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 ¶
- func FenceEnd(id string) string
- func FenceStart(id string) string
- func FindFence(body, id string) (start, end int, ok bool)
- func GenerateFence(d Dump, group string) string
- func HasPlaceholder(tok string) bool
- func RenderGroupFences(d Dump, group string, ids []string) (map[string]string, []string)
- type Command
- type Doc
- type Dump
- type Example
- type FenceLoc
- type FenceSpec
- type Flag
- type Issue
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FenceStart ¶
FenceStart / FenceEnd return the literal markers for a fence id (a bare group, or group[prefix,…] — see ParseFenceID), used to locate fences in docs.
func FindFence ¶ added in v1.3.44
FindFence locates the full fenced block for id in body: start is the byte offset of the start marker, end is the offset just past the end marker. ok is false when either marker is missing.
func GenerateFence ¶
GenerateFence renders the fenced block for a group whose only fence is the catch-all — i.e. all of the group's commands in one block. Groups split across several cards must go through RenderGroupFences instead, which knows the sibling subset fences.
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.
func RenderGroupFences ¶ added in v1.3.44
RenderGroupFences renders the fenced block for every fence of one command group. ids must be the complete set of fence ids that exist for the group across all cards — the catch-all fence renders whatever its sibling subset fences leave unclaimed, so a fence cannot be rendered in isolation. Topology problems (a verb claimed twice, a prefix claiming nothing, verbs left over with no catch-all, a duplicated id) come back as violations; rendered blocks are still returned for the fences that parsed.
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 FenceSpec ¶ added in v1.3.44
FenceSpec is one parsed fence id.
func ParseFenceID ¶ added in v1.3.44
ParseFenceID parses a fence id as found in a GENERATED marker.
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" | "fence-topology"
Detail string
}
Issue is one validation finding against the command oracle.
func CheckFences ¶
CheckFences asserts every GENERATED fence embedded in docs matches a fresh render from the dump, and that each group's fences form a valid partition of the group's commands (see RenderGroupFences). A drifted fence or a start marker with no matching end marker yields a stale-fence issue; a malformed or unknown-group marker, and any partition violation, yields a fence-topology issue anchored at the group's first fence.
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