Documentation
¶
Overview ¶
Package docsref parses and resolves the documentation references the live path's refusals carry.
Every refusal in the three registries - internal/live/lint's Rule table, internal/live/identity's refusals.go and internal/live/passthrough's - names the shipped document that explains it, in one string:
live/LIMITATIONS.md, "unadmitted-type" live/LIMITATIONS.md, "local-exec" / "remote-exec" live/RECEIPTS.md, "Guard 4. The leaf rule" live/MARKERS.md
That string is rendered into the diagnostic a user reads, so it has always been prose. GitHub issue #110 makes it data as well: a generator has to turn the registries into live/LIMITATIONS.md's own entries, and a test has to fail when a refusal cites a heading nobody wrote. Both need the string parsed rather than matched, which is what this package is for.
Nothing here changes the strings themselves. Ref.String round-trips what was parsed, and the registries stay the authority on what each refusal cites.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Headings ¶
Headings returns every markdown heading in a document, as a set of the text following the "#" run.
Four things that look like headings are not, and an audit found this counting all four - so a refusal could cite a "heading" no reader would ever see, and the test that resolves references would pass:
- lines inside a fenced code block, ``` or ~~~. A shell transcript full of comment lines is not a table of contents.
- lines inside an HTML comment. This document has generated regions delimited by them, and a commented-out section is deliberately not part of the page.
- indented code blocks, four spaces or a tab.
- a "#" run with no space after it, or longer than six, neither of which markdown renders as a heading at all.
Types ¶
type Ref ¶
type Ref struct {
// Doc is the repository-relative path of the document, as written:
// "live/LIMITATIONS.md".
Doc string
// Headings are the section titles cited within it, in the order
// written, without their quotes. Empty when the reference names a
// document and no section.
Headings []string
}
Ref is one parsed documentation reference.
func Parse ¶
Parse reads one reference string.
It is deliberately strict about the two shapes that appear in the registries and refuses anything else, because a malformed reference that parsed to "a document with no headings" would resolve successfully against any document and silently document nothing.
func (Ref) Resolve ¶
Resolve checks that the document exists under root and that every heading cited appears in it as a markdown heading of some level.
A heading match is exact on the text after the "#" run, trimmed. The documents this reads are ours and the convention is already enforced elsewhere (internal/live/lint's TestLimitationsDocCoversDirs matches "### <name>" as a literal), so a fuzzy match would only let a typo through.
Source Files