docs: regen cli.md for gc prompt + add freshness guardrail#2071
Open
hexsprite wants to merge 2 commits into
Open
docs: regen cli.md for gc prompt + add freshness guardrail#2071hexsprite wants to merge 2 commits into
hexsprite wants to merge 2 commits into
Conversation
`gc prompt` and `gc prompt synth` were added to the CLI without regenerating docs/reference/cli.md from cmd/genschema. The pre-commit hook auto-regenerates this file when staged Go changes touch CLI definitions, so the drift surfaced on an unrelated PR's commit. Run: `go run ./cmd/genschema`
Adds TestCLIDocsFreshness, which walks the live cobra tree and asserts every non-hidden command has a heading in docs/reference/cli.md. The prior pre-commit hook silently regenerated cli.md and stapled it to whichever commit happened to touch Go files, so CLI drift leaked onto unrelated PRs. This catches the drift in CI/pre-commit and points at the right fix: go run ./cmd/genschema. Structural rather than byte-equal — cobra registers `completion`/`help` only on Execute, which the in-test render path skips.
github-actions
Bot
added
the
status/needs-triage
randy-release-manager
Bot
added
kind/chore
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
1 participant
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
Two things:
docs/reference/cli.mdregen —gc promptandgc prompt synthwere added to the CLI without runninggo run ./cmd/genschema. The pre-commit hook silently regenerates that file when staged Go changes touch CLI definitions, so the drift was leaking onto unrelated PRs as a stowaway diff (caught while opening test(cmd/gc): cut managed-dolt + stale-key delay overhead in city runtime tests #2069).Guardrail:
TestCLIDocsFreshnessincmd/gc— walks the live cobra tree and asserts every non-hidden command has a## <path>heading indocs/reference/cli.md. Runs undergo test ./...(somake testin pre-commit + CI both catch it). Structural rather than byte-equal: cobra lazily registerscompletion/helponly onExecute, which the in-test render path skips, so a strict byte-equal check produces false positives.How drift used to slip through
Pre-commit hook flow when Go files are staged:
If
cli.mdwas already drifted (someone added a CLI command and didn't regen), the next contributor's unrelated commit picks up the regen + the auto-stage, polluting their PR.TestCLIDocsFreshnessfails at the source before the commit lands.Test plan
go test -run TestCLIDocsFreshness ./cmd/gc/...— passes with current tree## gc promptfrom cli.md, test failed withmissing sections for 2 commands: [gc prompt gc prompt synth]make check-docs,make vet,make test, dashboard rebuild)Why it's a separate PR
Pure docs + test guardrail change. Allows #2069 (test cleanup for managed-dolt-spawning tests) to land with only its actual diff once this merges and that branch rebases off main.