Function ValidateExamples

internal/cmdhelp/example_validation.go:28–42

ValidateExamples is the contractual mechanism by which cmdhelp v0.1 prevents documentation drift (spec §6, §11 Q5). For every example in every command of `doc`: 1. Tokenize the `cmd` string with a shell-aware splitter. 2. Resolve the non-flag tokens against `root`'s live cobra command tree. Failure

(doc *Document, root *cobra.Command)

// Callers must pass `root` so flag-tree walks can include persistent
// flags from the binary root.
func ValidateExamples(doc *Document, root *cobra.Command) []string {
	if doc == nil || root == nil {
		return nil
	}
	var findings []string

	for path, cmd := range doc.Commands {
		for i, ex := range cmd.Examples {
			if ferrs := validateExample(path, i, ex, doc, root); len(ferrs) > 0 {
				findings = append(findings, ferrs...)
			}
		}
	}
	return findings
}

func validateExample(path string, idx int, ex Example, doc *Document, root *cobra.Command) []string {
	tokens, err := shellSplit(ex.Cmd)