Documentation
¶
Overview ¶
Package docsdrift holds parsing helpers for the documentation drift tests.
The docs under docs/*.md are hand-written prose and stay that way: nothing here generates markdown. These helpers only extract the *keys* a table documents (tool names, flag names, config keys, …) so a test can compare them against the keys the code actually exposes. Descriptions are never compared — only membership.
Several of the code-side key sets live in unexported identifiers (the CLI flag set is built inline in main(), modelAliases and allCommands are package private). Rather than exporting them just to be testable, the helpers below read the source with go/ast. That keeps production code untouched and the coupling confined to this package.
Index ¶
- func AllBacktickTokens(cell string) []string
- func BacktickToken(cell string) string
- func Diff(want, got map[string]bool) (missing, extra []string)
- func GoDispatchedCommandNames(path, funcName, cmdVar string) ([]string, error)
- func GoFlagNames(path, receiver string) ([]string, error)
- func GoStringMap(path, name string) (map[string]string, error)
- func GoStructSliceField(path, name, field string) ([]string, error)
- func ReadDoc(root, rel string) (string, error)
- func RepoRoot() (string, error)
- func SetOf(items []string) map[string]bool
- func SplitTableRow(line string) []string
- func TableAfter(content, anchor string) ([][]string, error)
- func TablesInSection(content, heading string) ([][]string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AllBacktickTokens ¶
AllBacktickTokens returns the text inside every pair of backticks in cell. Used where a token may appear anywhere in the row (an alias mentioned in a description, e.g. "Quit (alias `/quit`)"), not only as the row's key.
func BacktickToken ¶
BacktickToken returns the text inside the first pair of backticks in cell, or "" when the cell has no code span.
func GoDispatchedCommandNames ¶
GoDispatchedCommandNames extracts the command names a dispatcher function accepts: the string literals it compares the command variable against. It recognises the three shapes used by pkg/tui's handleCommand —
switch cmd { case "branch", "back": … }
cmd == "prompt" / strings.HasPrefix(cmd, "prompt ")
cutCommand(cmd, "compact")
— which is where aliases actually live: allCommands lists one canonical name per action, so an alias added to the dispatcher alone would never show up in a palette-only comparison.
Known limitation: only comparisons against a literal, inside the named function, and against the named variable are seen. A command routed through a helper, a table or a computed name is invisible here; the test would then under-report rather than mis-report.
func GoFlagNames ¶
GoFlagNames extracts flag names declared in a Go file through calls like flag.String("p", …), fs.Bool("check", …) or flag.StringVar(&x, "p", …). receiver is the identifier the calls hang off ("flag" for the default flag set, "fs" for a sub-command's FlagSet).
Any call on that receiver whose method is neither a known registrar nor a known non-registrar is an error: an extractor that no longer understands the code must say so rather than report a green test over a partial view of it.
func GoStringMap ¶
GoStringMap extracts a package-level `var name = map[string]string{…}` literal with constant keys and values. An entry that is not a literal-to-literal pair is an error rather than a skip: silently dropping it would hide exactly the entry the docs may be missing.
func GoStructSliceField ¶
GoStructSliceField extracts one string field from every element of a package-level `var name = []T{{Field: "…"}, …}` slice literal. Every element must carry the field as a string literal: an element the extractor cannot read is an element whose documentation cannot be checked, so it fails loudly instead of shrinking the set under comparison.
func RepoRoot ¶
RepoRoot walks up from the working directory until it finds go.mod, so the tests work from any package directory without absolute paths.
func SplitTableRow ¶
SplitTableRow splits a markdown table row into trimmed cells. Pipes escaped as `\|` (used by cells like `/path [list\|add\|rm]`) are part of the cell text, not separators.
func TableAfter ¶
TableAfter returns the data rows of the first markdown table that starts after the line equal to anchor (a heading, or a lead-in line such as "Always registered:"). Header and separator rows are dropped.
func TablesInSection ¶
TablesInSection returns the data rows of every markdown table between the given heading and the next heading of the same or higher level. Used for sections whose keys are spread over several sub-tables (config fields).
Types ¶
This section is empty.
Source Files