Follow-up to #104 (ADR 0016).
ADR 0016 lists ambiguous anchor as an authoring error: two headings in one file that slug identically (## Setup twice → #setup and #setup-1 on GitHub). It is not implemented.
Why
Sections resolve through the scope stack: a candidate belongs to a section iff the section's slug appears in its scopeStack. That was a deliberate deviation — it means "from this heading until the next of the same or higher level" is already computed, and no headings field had to be added to Doc, which kept every port's doc.json golden untouched.
The cost is exactly this: two same-slug headings are indistinguishable that way, so a reference to #setup silently pulls in the candidates of both sections, in document order.
Options
- Lint rule (
reference/lint.md): a file containing a referenced section must have unique heading slugs. Cheap, local, catches it at authoring time — but only for people who run lint.
- Add
headings to Doc and resolve sections against the real outline. Correct at the source and enables a precise reference-ambiguous-anchor diagnostic, at the cost of a new AST field and regenerating doc.json across seven ports.
(1) is probably enough: duplicate headings in a shared-section file are rare and obviously bad. Worth deciding explicitly rather than leaving the ADR's Errors list out of sync with what the code does.
Follow-up to #104 (ADR 0016).
ADR 0016 lists ambiguous anchor as an authoring error: two headings in one file that slug identically (
## Setuptwice →#setupand#setup-1on GitHub). It is not implemented.Why
Sections resolve through the scope stack: a candidate belongs to a section iff the section's slug appears in its
scopeStack. That was a deliberate deviation — it means "from this heading until the next of the same or higher level" is already computed, and noheadingsfield had to be added toDoc, which kept every port'sdoc.jsongolden untouched.The cost is exactly this: two same-slug headings are indistinguishable that way, so a reference to
#setupsilently pulls in the candidates of both sections, in document order.Options
reference/lint.md): a file containing a referenced section must have unique heading slugs. Cheap, local, catches it at authoring time — but only for people who run lint.headingstoDocand resolve sections against the real outline. Correct at the source and enables a precisereference-ambiguous-anchordiagnostic, at the cost of a new AST field and regeneratingdoc.jsonacross seven ports.(1) is probably enough: duplicate headings in a shared-section file are rare and obviously bad. Worth deciding explicitly rather than leaving the ADR's Errors list out of sync with what the code does.