oxidecomputer / oxidecomputer/prettier-plugin-asciidoc
internal-citations does not check prose mentions of symbols, so deleted functions survive in docs and ledger notes
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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