chore(cli): assert every flag is documented in the readme - #654
Merged
Conversation
haribo
force-pushed
the
chore/646-flag-doc-gate
branch
from
September 10, 2026 15:32
eb132ad to
3542e57
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
#642 found four flags —
--json,-v,--parallel,--limit— accepted byrunand namedin 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.
TestEveryFlagIsDocumentedwalks the commands' own flag sets rather than parsingmain.go:runFlags,statusFlagsandcleanFlagsare whatrunCmd,statusCmdandcleanCmdcall, so a flag cannot be added to one and missed by the other. That extraction isthe option #646 preferred, and it is now cheap because #640 already named the shared surface.
--checkis the one exemption, by name and with its reason in the test: it is registered withan empty usage string so it stays out of
-h, and exists only to tell an operator the flag isnow
--dry-run(ADR-0035). A documented--checkwould be the defect.TestOnlyOneFlagIsHiddenkeeps the exemption from becoming a habit: a second hidden flag failsthe 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:
go test ./...,test/lint.sh,test/dead-code.sh,test/coverage-ratchet.sh(82.3%),test/changelog-rule.shgreen.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.mdis untouched: it is the language spec,not the CLI reference.
Closes #646