Skip to content

chore(cli): assert every flag is documented in the readme - #654

Merged
haribo merged 1 commit into
developfrom
chore/646-flag-doc-gate
Sep 10, 2026
Merged

chore(cli): assert every flag is documented in the readme#654
haribo merged 1 commit into
developfrom
chore/646-flag-doc-gate

Conversation

@haribo

@haribo haribo commented Sep 10, 2026

Copy link
Copy Markdown
Owner

Summary

#642 found four flags — --json, -v, --parallel, --limit — accepted by run and named
in no document. They were not new: they had been shipping undocumented, and nothing would ever
have said so. The check that found them was a throwaway; this is it, kept.

TestEveryFlagIsDocumented walks the commands' own flag sets rather than parsing
main.go: runFlags, statusFlags and cleanFlags are what runCmd, statusCmd and
cleanCmd call, so a flag cannot be added to one and missed by the other. That extraction is
the option #646 preferred, and it is now cheap because #640 already named the shared surface.

--check is the one exemption, by name and with its reason in the test: it is registered with
an empty usage string so it stays out of -h, and exists only to tell an operator the flag is
now --dry-run (ADR-0035). A documented --check would be the defect.

TestOnlyOneFlagIsHidden keeps the exemption from becoming a habit: a second hidden flag fails
the build, so the decision gets made rather than a line added to a skip list.

Test plan

Mutation-tested three ways — the gate is worth nothing unless it is seen red:

drop the --parallel row from the README
  → FAIL shellf run accepts -parallel and README.md does not mention it
  → FAIL shellf status accepts -parallel and README.md does not mention it

add an undocumented flag to run
  → FAIL shellf run accepts -brand-new and README.md does not mention it

give --check a usage string
  → FAIL --check carries a usage string now, so it shows in -h
  → FAIL hidden flags: got [], want [check]

restored → ok

go test ./..., test/lint.sh, test/dead-code.sh, test/coverage-ratchet.sh (82.3%),
test/changelog-rule.sh green.

Out of scope, as stated in the issue

Flag descriptions are not compared — the names are what silently drift, and a wording diff
would be noise on every rephrase. docs/language.md is untouched: it is the language spec,
not the CLI reference.

Closes #646

@haribo
haribo force-pushed the chore/646-flag-doc-gate branch from eb132ad to 3542e57 Compare September 10, 2026 15:32
@haribo
haribo merged commit db36c76 into develop Sep 10, 2026
8 checks passed
@haribo
haribo deleted the chore/646-flag-doc-gate branch September 10, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant