docscheck

docscheck

Check that the command examples in a tool's documentation name commands the tool can actually run.

import "gitlab.com/phpboyscout/go/docscheck"

Documentation drifts from a CLI silently. Split a command into a group and every page using the old form starts telling readers to run something that errors — and nothing notices, because no test compares the two.

What it flags

One shape, and only one: inside a fenced code block, a command group followed by a concrete token that is not one of its subcommands.

Example	Verdict
krites reset IMG_2043.CR2	finding — reset is a group; IMG_2043.CR2 is not a subcommand
krites reset frame IMG_2043.CR2	fine — resolves to a leaf
krites reset	fine — a bare group is a synopsis, not an instruction
krites xmp <subcommand>	fine — a placeholder is a synopsis
krites config --help	fine — a flag is not a subcommand
Undo with `krites reset IMG.CR2`.	fine — prose is a reference, not an invocation

That narrowness is what makes it usable. The obvious rule — flag anything that resolves to a node with children — found 15 problems on a corpus whose real defect count was 3, because a group's own reference page names the group in its title, its heading and its prose. Restricting to fenced blocks removed twelve; ignoring bare groups and placeholders removed the rest.

It also dissolves what looks like the hard problem. Some groups run standalone and some error without a subcommand, so it seems the checker has to tell them apart. It does not: a group handed a token that is not one of its subcommands fails either way. There is no allowlist of runnable parents to maintain — and nothing needs executing to find out, which matters, because a command's exit status depends on how its binary was built while its shape does not.

Usage

The tree comes from the running program, so it cannot drift from what the binary accepts. This module imports no CLI framework — see TestDependencyFootprint — so a Cobra tool converts its own root command:

func tree(c *cobra.Command) docscheck.Command {
	n := docscheck.Command{Name: c.Name()}
	for _, sub := range c.Commands() {
		n.Sub = append(n.Sub, tree(sub))
	}

	return n
}

func TestDocumentedCommandsExist(t *testing.T) {
	root, _ := root.NewCmdRoot(version.Info{})

	c, err := docscheck.New(tree(root.Command))
	if err != nil {
		t.Fatal(err)
	}

	rep, err := c.Walk(os.DirFS(".."), "docs", "README.md")
	if err != nil {
		t.Fatal(err)
	}

	if !rep.OK() {
		t.Fatalf("documentation names commands that cannot run:\n%s", rep)
	}
}

Scan is the pure form — content in, findings out, no filesystem — if you want to drive it yourself.

It will not quietly pass

A guard that stops working while still looking green is worse than no guard. New rejects a tree with no name or no subcommands, and Walk returns ErrNoFiles when nothing matched, rather than reporting a clean run.

Scope

Command paths only. It does not validate flags, argument counts, or whether the prose around a command describes it correctly, and it does not execute anything.

Dependencies

One, at runtime: gitlab.com/phpboyscout/go/errors, which is itself dependency-free — so adding a documentation check to a project costs it one module and no transitive graph.

TestDependencyFootprint enforces that against an explicit allowlist, and separately forbids any CLI framework reaching the runtime graph. The allowlist is the decision, not a record of one: adding a line to it is a choice to be made deliberately.

Why it exists

Three pages of one tool's documentation told readers to run `krites reset

` — a form that had exited 1 since `reset` gained subcommands. The getting-started tutorial among them was *written a fortnight after* the change, so that step never worked for anyone who followed it.

Measured against that tool's real corpus: 57 files, 97 documented invocations, 0 false positives, and 3 of 3 defects caught when the fix is reverted.

Licence

MIT — see LICENSE.