docenttest

func Check ¶

func Check(fsys fs.FS, root docent.Command) []error

Check loads guides from fsys, verifies that every command path listed in guide frontmatter exists in root, and returns one error per violation. Each returned error wraps the sentinel that classifies its class:

• docent.ErrMissingFrontmatter – guide file has no YAML frontmatter block
• docent.ErrInvalidFrontmatter – frontmatter block is not valid YAML
• docent.ErrMissingField – a required frontmatter field is absent
• docent.ErrSlugMismatch – frontmatter slug does not match the filename
• docent.ErrInvalidSlug – slug violates the Agent Skills name rules
• docent.ErrDescriptionTooLong – description and when_to_use exceed the skill description budget
• docent.ErrCompatibilityTooLong – compatibility exceeds the skill budget
• docent.ErrInvalidSections – wrong number or order of body sections
• docent.ErrDuplicateOrder – two guides share the same order value
• docent.ErrAliasCollision – an alias is empty, declared twice, or shadows a slug
• docent.ErrMultilineField – an index-emitted frontmatter field contains a newline
• docent.ErrFormFeed – a guide file contains a form-feed character
• docent.ErrCommandNotFound – a guide lists a command not present in root

When root is the zero Command (root.Name == ""), command-reference checking is skipped, and a guide with an explicitly empty commands list (a whole-tool guide) has nothing to check by construction. A nil return value means no violations were found.

func MaskFlagDefaults ¶

func MaskFlagDefaults(cmd docent.Command, names ...string) docent.Command

MaskFlagDefaults returns a deep copy of cmd in which every flag named in names — wherever it appears in the tree — has its Default replaced with "MASKED". Use it before SchemaGolden when a default is computed at startup (an ephemeral port, a home-directory path) and would flake the golden; the masked copy shares no storage with cmd.

func SchemaGolden ¶

func SchemaGolden(tb testing.TB, cmd docent.Command, goldenPath string, update bool)

SchemaGolden asserts that cmd's canonical schema JSON is byte-identical to the golden file at goldenPath, writing the file instead when update is true. The emission goes through docent.MarshalSchema — the same function the adapter's "agent schema" command writes through — so the golden pins the artifact agents actually read, not a lookalike. Adapter effects sit on top of the canonical shape and are not covered here: the contract-version stamp (Config.ContractVersion), the full-tree structure-only emission (docent.Command.StripShapes replaces embedded schema bodies with has_* markers unless --shapes or --path is used), shape pooling in embedding emissions (docent.Command.PoolShapes hoists repeated bodies into $defs), and host schema transforms. Hosts relying on any of these effects should golden the schema command's output itself — or golden the policy-shaped tree by passing cmd.StripShapes() / cmd.PoolShapes() here.

Hosts whose trees carry volatile flag defaults (ephemeral ports, home-dir paths, timestamps) golden a masked copy via MaskFlagDefaults first; pinning volatile bytes makes the golden flake.

func Validate ¶

func Validate(tb testing.TB, fsys fs.FS, root docent.Command)

Validate loads guides from fsys and reports each violation as a distinct t.Errorf call. Each call is prefixed with the violation class so test output identifies the problem without inspecting message strings:

• "missing frontmatter: …" wraps docent.ErrMissingFrontmatter
• "invalid frontmatter: …" wraps docent.ErrInvalidFrontmatter
• "missing required field: …" wraps docent.ErrMissingField
• "slug mismatch: …" wraps docent.ErrSlugMismatch
• "invalid slug: …" wraps docent.ErrInvalidSlug
• "description budget: …" wraps docent.ErrDescriptionTooLong
• "compatibility budget: …" wraps docent.ErrCompatibilityTooLong
• "invalid sections: …" wraps docent.ErrInvalidSections
• "duplicate order: …" wraps docent.ErrDuplicateOrder
• "alias collision: …" wraps docent.ErrAliasCollision
• "multiline field: …" wraps docent.ErrMultilineField
• "form feed: …" wraps docent.ErrFormFeed
• "unknown command reference: …" wraps docent.ErrCommandNotFound

When root is the zero Command, command-reference checking is skipped.