sixfold-space/madtea

SHA256

Fork 0

test: hold hand-written CLI help to a baseline that may only shrink #863

Merged

hexajon merged 3 commits from issue-515-opspec-help-ratchet into main

2026-10-21 16:37:52 +00:00

hexajon commented

2026-10-21 16:37:47 +00:00

Owner

Summary

What was wrong

ADR 0008 moves CLI help into the internal/opspec registry. Almost no command uses it. Nothing stops a new command from adding more hand-written Long: help.

What changed

internal/cmdutil/clispec.go: ApplyCLISpec now keeps a copy of the Short and Long text it renders in two command annotations. It clones the Annotations map first. Commands that share one map (for example the adr commands) no longer replace each other's record.
internal/cmdutil/clispec.go: new HelpFromSpec reports whether a command's Short and Long are still the rendered text. It returns false for hand-written help, for text written over the rendered text, and for an empty Long.
internal/cmd/handwritten_help_test.go: new TestHandwrittenHelpBaseline walks the command tree from RootCmd. It lists every runnable command whose help does not render from opspec. Command groups with no Run are not counted, and neither is the help command that Cobra adds.
internal/cmd/testdata/handwritten_help.golden: the checked-in baseline, with 542 commands.
docs/contributing/adding-commands.md: the add-a-command checklist now says to render help with cmdutil.ApplyCLISpec and names the baseline test.

The test fails in three cases:

A command is not in the baseline. The message tells the author to use cmdutil.ApplyCLISpec.
A baseline line has no matching hand-written command. The message names -update.
The file is not sorted, or it has duplicate lines.

Running the test with -update rewrites the file. It refuses to add a line, so the baseline can only shrink.

Tests

TestHelpFromSpec and TestHelpFromSpecShortOverwritten in internal/cmdutil/clispec_test.go cover rendered, hand-written, overwritten Long, overwritten Short, and empty help.
TestApplyCLISpecSharedAnnotations covers two commands that share one Annotations map. It checks that each keeps its own record, that the shared map is unchanged, and that existing annotations stay.
TestHandwrittenHelpNewCommandFails checks that a new hand-written command fails and that -update refuses to add it.
TestHandwrittenHelpMigrationShrinksBaseline checks that a migrated command leaves a stale line, and that -update removes it.
TestHandwrittenHelpOverwrittenLongFails checks that a Long written over rendered help counts as hand-written.

Not in this change

The issue also asks for an epic with one child per noun. This change does not add it. Refs #515

./scripts/gate.sh passes on this commit.

Refs #515

## Summary ## What was wrong ADR 0008 moves CLI help into the `internal/opspec` registry. Almost no command uses it. Nothing stops a new command from adding more hand-written `Long:` help. ## What changed - `internal/cmdutil/clispec.go`: `ApplyCLISpec` now keeps a copy of the `Short` and `Long` text it renders in two command annotations. It clones the `Annotations` map first. Commands that share one map (for example the `adr` commands) no longer replace each other's record. - `internal/cmdutil/clispec.go`: new `HelpFromSpec` reports whether a command's `Short` and `Long` are still the rendered text. It returns false for hand-written help, for text written over the rendered text, and for an empty `Long`. - `internal/cmd/handwritten_help_test.go`: new `TestHandwrittenHelpBaseline` walks the command tree from `RootCmd`. It lists every runnable command whose help does not render from opspec. Command groups with no `Run` are not counted, and neither is the `help` command that Cobra adds. - `internal/cmd/testdata/handwritten_help.golden`: the checked-in baseline, with 542 commands. - `docs/contributing/adding-commands.md`: the add-a-command checklist now says to render help with `cmdutil.ApplyCLISpec` and names the baseline test. The test fails in three cases: - A command is not in the baseline. The message tells the author to use `cmdutil.ApplyCLISpec`. - A baseline line has no matching hand-written command. The message names `-update`. - The file is not sorted, or it has duplicate lines. Running the test with `-update` rewrites the file. It refuses to add a line, so the baseline can only shrink. ## Tests - `TestHelpFromSpec` and `TestHelpFromSpecShortOverwritten` in `internal/cmdutil/clispec_test.go` cover rendered, hand-written, overwritten `Long`, overwritten `Short`, and empty help. - `TestApplyCLISpecSharedAnnotations` covers two commands that share one `Annotations` map. It checks that each keeps its own record, that the shared map is unchanged, and that existing annotations stay. - `TestHandwrittenHelpNewCommandFails` checks that a new hand-written command fails and that `-update` refuses to add it. - `TestHandwrittenHelpMigrationShrinksBaseline` checks that a migrated command leaves a stale line, and that `-update` removes it. - `TestHandwrittenHelpOverwrittenLongFails` checks that a `Long` written over rendered help counts as hand-written. ## Not in this change The issue also asks for an epic with one child per noun. This change does not add it. Refs #515 `./scripts/gate.sh` passes on this commit. Refs #515

hexajon added 3 commits

2026-10-21 16:37:48 +00:00

test: hold hand-written CLI help to a baseline that may only shrink fa4fedb331

ApplyCLISpec now keeps a copy of the Long it renders in a command
annotation, and HelpFromSpec reports whether a command's Long is still
that rendered text.

A new test walks the command tree from the root and lists every runnable
command whose help does not render from opspec. The list is checked in
at internal/cmd/testdata/handwritten_help.golden (542 commands). A
command that is not in the baseline fails the test. A baseline line with
no matching command fails until -update removes it. With -update the test
rewrites the file but refuses to add a line.

Refs #515

fix: keep rendered-help records per command and check Short too b190c6b4fb

ApplyCLISpec copied nothing before it wrote its record of the rendered
Long, so commands that share one Annotations map (adr's skipConfig)
replaced each other's record. It now clones the map. HelpFromSpec also
compares Short, so a Short written by hand after rendering counts as
hand-written help. The add-a-command checklist now says to render help
with cmdutil.ApplyCLISpec and names the baseline test.

Refs #515

test: use strings.SplitSeq in the baseline reader, as go fix asks

drift / govulncheck (pull_request) Has been skipped

Details

drift / forgejo-smoke (pull_request) Has been skipped

Details

drift / surface-diff (pull_request) Successful in 1m22s

Details

drift / govulncheck (push) Has been skipped

Details

drift / surface-diff (push) Successful in 3m40s

Details

drift / forgejo-smoke (push) Has been skipped

Details

ci / gate (push) Successful in 22m23s

Details

ci / gate (pull_request) Successful in 43m36s

Details

099879dc0c

hexajon merged commit 099879dc0c into main

2026-10-21 16:37:52 +00:00

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea!863

No description provided.

Rows
Columns