fix: Redact internal spec identifiers (DM1, R4.4) from min --help output - #1017
Conversation
clap's derive macro publishes `///` doc comments verbatim as help text, so two internal spec references shipped in `min --help`: - the global `--provider` arg carried `(DM1)` and, being `global`, rendered on all 18 help surfaces; - the `login` subcommand carried `(R4.4, R4.5)`. Drop the parenthetical spec tags, leaving the descriptive prose intact. Both edits are copy-only and carry no behavioural change. Add a convention-discovered guard (crates/minimal/tests/help_text.rs) that renders long help for the root command and every subcommand recursively and fails on `DM<n>`, `UC<n>`, `FR<n>`, `NFR<n>`, `R<n>.<n>`, and the retired `PTask` vocabulary — so the convention "internal spec IDs go in `//` comments, never `///`" is enforced rather than merely remembered. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 40 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
Comment |
The 149-line byte-level scanner is disproportionate to what it protects. Keeping the copy fixes; the convention can be enforced more cheaply later if it proves it needs enforcing.
Redact the internal deployment-model IDs DM1/DM2/DM3 from the user-facing linux-host-setup reference, describing the deployments functionally instead. This follows #1017, which cleaned the same class from `min --help` but stopped before the docs. Refresh two stale counts in AGENTS.md: 40 justfile recipes on Linux (was 33; `just --summary`) and 12 CI workflows (was 11 — the docs-hotfix workflow was missing from the table). Drop the two docs.minimal.dev/concepts links (stacks, sessions) that 404, keeping the surrounding prose as plain text; sibling concept pages resolve but no slug is published for these two. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Redact the internal deployment-model IDs DM1/DM2/DM3 from the user-facing linux-host-setup reference, describing the deployments functionally instead. This follows #1017, which cleaned the same class from `min --help` but stopped before the docs. Refresh two stale counts in AGENTS.md: 40 justfile recipes on Linux (was 33; `just --summary`) and 12 CI workflows (was 11 — the docs-hotfix workflow was missing from the table). Drop the two docs.minimal.dev/concepts links (stacks, sessions) that 404, keeping the surrounding prose as plain text; sibling concept pages resolve but no slug is published for these two. Co-authored-by: gominimal-aw-bot[bot] <281738952+gominimal-aw-bot[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Norrie Taylor <91171431+norrietaylor@users.noreply.github.com>
Fixes #1013
Routing-Key: inbox-route/I_kwDOSUhdos8AAAABKk1ZkQ
Problem
clap's derive macro publishes
///doc comments verbatim as user-facing help text, so two internal spec identifiers were shipping inmin --help:crates/minimal/src/lib.rs: the--providerglobal arg carried(DM1). Beingglobal = true, that line renders on all 18 help surfaces — the single most-printed string in the CLI.crates/minimal/src/lib.rs: theloginsubcommand description carried(R4.4, R4.5), rendered bymin login --help.Change
Drop the parenthetical spec tags from both doc comments, leaving the descriptive prose intact. Copy-only, no behavioural change.
That is the whole diff: +2/-2 in one file.
On the CI guard
The issue asked for a CI guard enforcing the convention (internal spec IDs in
//comments, never///). This PR originally carried one — a dependency-freecrates/minimal/tests/help_text.rsthat rendered help recursively and scanned it forDM<n>,UC<n>,FR<n>,NFR<n>,R<n>.<n>, andPTask.It has been removed. 149 lines of hand-rolled byte-level scanning, plus a second test to test the scanner, is disproportionate to catching two string literals. If this class of leak recurs, a
grep -Estep in CI covers it at a fraction of the cost and none of the maintenance surface.The convention itself still stands and is worth applying in review.
Scope notes
The
Providerenum-level doc (DM2/DM1) and thecmd_loginfn doc (R4.4) are Rust docs on non-clap items, so they never reach help output and were left untouched.The
PTask/R4.8references onmeshandssh-forwardsit behind the default-offremote-accessfeature and do not ship today. They will leak if those commands are ever enabled — worth catching then.Verification
The full Rust gate (
cargo fmt --check,cargo clippy -- -D warnings,cargo build,cargo test --workspace) was run green against the tree as originally authored, i.e. with the guard present. Those results no longer describe this diff.The current head is d581366. CI on that commit is the authority for this PR. The remaining change is two doc-comment strings, so the risk surface is limited to whether the help text still reads correctly:
Note
Redact internal spec identifiers from
min --helpoutputRemoves parenthetical internal spec references (e.g.
DM1,R4.4) from the CLI help text in lib.rs. Affected descriptions are the mTLS client certificate subcommand and the microVM backend provider option.Macroscope summarized d581366.