Repository navigation
feat(cli): derive flag documentation from flag definitions - #7700
mdonnalley wants to merge 5 commits into
Conversation
CLI benchmark (Lightweight Commands): no changes foundCommit
API calls: unchanged for all 9 commands. Binary size: 135.3 MB, up 8.0 KB from 135.2 MB. Details: timing ranges, API calls per command, slowest phasesTiming ranges
API calls per command
Slowest phasesNo command moved beyond noise, so there are no phase deltas. Comment |
There was a problem hiding this comment.
🤖 AI Review
CLI reference prose guidance: snapshot supabase/supabase@8feb4a0 supplied to reviewers (advisory, not a style pass).
Both independent reviews were available. Seven findings are confirmed. The main issues are misleading defaults in text help, incorrect reference metadata for repeated flags with per-value fallbacks, and a parser test that can pass with a stale result. One shared-flag finding remains uncertain because the Effect dependency was unavailable to verify which rows appear in a command’s own help. The diff changes no in-scope reference prose. The review found no overlay drift or fundamental conflict with the pending next-branch work.
Findings
| Severity | Location | Category | Sources | Claim |
|---|---|---|---|---|
| 🟡 MINOR | apps/cli/src/shared/output/flag-defaults-help.ts:19 |
ux |
claude | Text help adds (default: false) to flags with an implicit false default, including login --no-browser. The same condition would display (default: 0) and (default: []) for explicit zero and empty-list fallbacks. |
| 🟡 MINOR | apps/cli/src/command-internal/param-introspection.ts:60 |
correctness |
codex | A per-value fallback inside a required repeated flag can remove its Required badge and publish the scalar fallback as the default for the entire list. |
| 🟡 MINOR | apps/cli/src/shared/output/flag-defaults-help.ts:55 |
correctness |
codex | The default lookup skips shared flags declared by the command whose help is being rendered. A shared flag displayed in that command’s own help would miss its suffix. |
| 🟡 MINOR | apps/cli/src/shared/output/flag-defaults-help.ts:11 |
correctness |
codex | A local flag can display an inherited flag’s default when both flags share a name and the local declaration suppresses or lacks a help default. |
| 🟡 MINOR | apps/cli/src/shared/output/flag-defaults-help.ts:32 |
correctness |
codex | An incidental use of the word “default” in a flag description suppresses its generated default label. |
| 🟡 MINOR | apps/cli/src/shared/output/flag-defaults-help.ts:36 |
correctness |
codex | Text help can change the spelling of a literal default by interpreting it as Markdown. |
| 🟡 MINOR | apps/cli/src/shared/output/flag-defaults-help.integration.test.ts:73 |
test-coverage |
codex | The explicit-value assertion can pass using the handler result from the preceding invocation. |
| ⚪ NIT | apps/cli/src/command-internal/flag-documentation.ts:9 |
dead-code |
claude | The new FlagDocumentation.hidden field has no production caller and only hides flags from the website reference. Its name leaves that scope implicit. |
Stats
Claude findings: 2 · Codex findings: 6 · Confirmed: 7 · Refuted: 0 · Uncertain: 1
Models: claude-opus-5-5 + gpt-6.2-sol · Trigger: auto · Workflow run
This review runs once per PR. A maintainer can request another with a /ai-review comment.
Prashansa-K
left a comment
There was a problem hiding this comment.
Changes look good to me.
There's one concern that is non-blocking today -
Not an issue for existing flags, since the generated reference is unchanged. But a future bare Flag.Boolean("x") (no default, not optional) would get a Required badge. Adding [Flag.Boolean("value"), undefined] to the required-badge it.each fails today. Treating boolean primitives as non-required would fix it.
Text help and the website reference now read literal defaults from flag definitions without evaluating runtime defaults. Flags declare documentation exceptions locally instead of relying on separate lookup tables. Parsing and JSON help are unchanged.
Text help omits a fixed default for the shared
--outputflag because commands such asdb querychoose the format at runtime. The only change to the published reference islogs --limit: its documented default is now100, matching the existing CLI behavior.