oxidecomputer / oxidecomputer/prettier-plugin-asciidoc

internal-citations does not check prose mentions of symbols, so deleted functions survive in docs and ledger notes

Open
#305 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

harness mechanism:instrument obligation:completeness
Dominant language
TypeScript
Stars
0
Forks
1
PR merge metrics
No merged PRs in 30d

Description

What this is

bun run internal-citations resolves {@link Symbol} tags and the symbol pins in score-minimums.json, but a plain-prose mention of a symbol (a backticked name in a comment or a docs sentence: "drainTakesWholeBody in join.ts") is not a citation it checks. Two record lanes on Sep 7 (#241, #274) each left prose in docs/architecture.md and a ledger note naming functions their own commit deleted; both were caught by review, not by the gate.

The change

Extend the checker so a backticked identifier in src comments, docs/*.md and the JSON ledgers' note fields that matches the symbol index's name shape and is NOT declared anywhere fails with the documented message, with an allowlist for names that are deliberately historical (a deletion ledger row, a "formerly" sentence). Measure the false-positive count on the tree first and report it; if it is large, narrow to docs/ and the ledger notes.

Gate

The two Sep 7 cases (a deleted drain predicate named in architecture.md; a deleted span-edge helper named in a test comment) fail under the extended checker on a scratch copy of the pre-fix commit; the tree passes; 0 false positives or an allowlist listing each.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running bun run internal-citations and measuring existing false positives across src comments, docs/architecture.md, and the JSON ledger note fields. Inspect the checker’s symbol index and the two Sep 7 cases (#241 and #274); done means both deleted-symbol prose mentions fail, the current tree passes, and false positives are zero or listed in an allowlist.

Written by the indexing model from the issue text.

Assessment

Tech stack
bun, typescript
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.