Documentation
¶
Overview ¶
Package skilldoc derives a structured description of the flashduty CLI's command tree (the "dump") and uses it to generate and validate the command-cards that document the CLI for an LLM operator.
The dump is the single source of truth: it is built in-process from the live cobra tree (see Build), so it can never drift from the binary it describes. The generator turns a dump into per-domain factual fences; the validator checks every documented `fduty …` example against the same dump.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FenceStart ¶
FenceStart / FenceEnd return the literal markers for a group, used by the freshness check to locate fences in docs.
func GenerateFence ¶
GenerateFence renders the factual fenced block for one command group: a section per leaf verb with its short description and a flag table (name, type, required, usage + enum), plus a body-only (--data) note when the command has nested JSON-only fields, plus a one-line response-shape summary (top-level object vs. bare array vs. `{items: [...]}` page wrapper, and the field names at that level) when the command documents one. Required-ness and enums are sourced from the authoritative "Request fields:" text in each command's Long; the response shape is likewise sourced from that same Long's "Response fields (...):" block (cligen's own ground truth — see responseShapeLine), not re-derived or hand-curated. The flag list falls back to the dump's Flags when no Request-fields block exists (read-only verbs). Output is deterministic.
func HasPlaceholder ¶
HasPlaceholder reports whether tok is a documentation placeholder rather than a literal argument: angle-bracket tokens (<id>), shell vars ($VAR), the ellipsis (...), or `ou_xxx`-style stand-ins. The validator skips the value of any flag whose token is a placeholder.
Types ¶
type Command ¶
type Command struct {
Path string `json:"path"` // space-joined name chain below root, e.g. "status-page change-create"
Group string `json:"group"` // first path segment, e.g. "status-page"
Short string `json:"short"`
// Use is cobra's raw Use string, e.g. "change-create <page-id>". cligen folds
// a required *_id field into a positional argument and records it here as a
// <placeholder>; that field is then supplied positionally, NOT via its
// same-named --flag (passing the flag alone fails the Args check). Capturing
// Use is what lets the generator render the correct positional invocation —
// the bare Path alone (which strips the placeholder) cannot.
Use string `json:"use"`
Long string `json:"long"` // cligen's Request/Response field text (authoritative for enums + nested --data)
Example string `json:"example"`
Flags []Flag `json:"flags"`
}
Command is one runnable leaf of the CLI tree.
type Doc ¶
Doc is a documentation file fed to the validator: its display Path (for issue reporting) and raw markdown Body.
type Dump ¶
type Dump struct {
Commands []Command `json:"commands"`
}
Dump is the structured snapshot of the CLI's command tree. It is the JSON contract shared between the dump oracle, the validator, and the generator.
func Build ¶
Build walks the cobra tree rooted at root and returns a structured dump of every runnable, non-hidden leaf command. Group containers (parents with their own subcommands, like "status-page") are descended into but not emitted themselves — see the predicate comment in walk for why this is keyed off subcommands rather than Runnable().
Path is the space-joined chain of cobra command names below the root, using c.Name() so a positional placeholder in Use (e.g. "change-create <page-id>") is stripped to the bare verb. Required flags are detected via cobra's one-required-flag annotation. Enums and nested --data fields are NOT re-derived here; they live verbatim in Long, which cligen authored.
type Example ¶
Example is one harvested CLI invocation from a markdown document. Tokens are the whitespace-separated arguments AFTER the `fduty`/`flashduty` binary word (so Tokens[0] is the command group). Line is the 1-based line where the invocation began.
func HarvestExamples ¶
HarvestExamples pulls every `fduty`/`flashduty` invocation out of markdown: fenced code blocks (```…```) and inline backtick spans alike. A candidate is any line whose first shell word is the binary; trailing-backslash continuations are joined into one example. Prose lines (no binary word) are ignored.
type Flag ¶
type Flag struct {
Name string `json:"name"`
Type string `json:"type"`
Default string `json:"default"`
Usage string `json:"usage"`
Required bool `json:"required"`
}
Flag is one flag of a command, as exposed by pflag.
type Issue ¶
type Issue struct {
Doc string
Line int
Kind string // "unknown-command" | "unknown-flag" | "stale-fence"
Detail string
}
Issue is one validation finding against the command oracle.
func CheckFences ¶
CheckFences asserts every GENERATED:<group> fence embedded in docs matches a fresh render from the dump. A fence whose inner content has drifted, or a start marker with no matching end marker, yields a stale-fence issue. Docs with no generated fence for a group are silently fine.
func Validate ¶
Validate checks every harvested `fduty …` example in docs against the dump: an example whose leading words resolve to no command path yields an unknown-command issue; an example flag absent from its command's flag set (and not a global flag) yields an unknown-flag issue. Placeholder tokens are skipped so documentation stand-ins (<id>, $VAR) never trip the validator.
Source Files