Skip to content

feat(cli): derive flag documentation from flag definitions - #7700

Open
mdonnalley wants to merge 5 commits into
developfrom
feat/cli-2685-flag-docs
Open

mdonnalley wants to merge 5 commits into
developfrom
feat/cli-2685-flag-docs

Conversation

@mdonnalley

Copy link
Copy Markdown
Contributor

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 --output flag because commands such as db query choose the format at runtime. The only change to the published reference is logs --limit: its documented default is now 100, matching the existing CLI behavior.

@mdonnalley
mdonnalley requested a review from a team as a code owner November 18, 2026 21:01
@github-actions

Copy link
Copy Markdown
Contributor

CLI benchmark (Lightweight Commands): no changes found

Commit 7a19e96 against develop at 6a2e55a · 10 runs each · report only, never blocks merging

Command Workload Before After Change
supabase --version version 429 ms 475 ms no real change (+11%, within normal variation)
supabase --help help 390 ms 390 ms no real change
supabase init init 382 ms 368 ms no real change
supabase migration new bench migration-new 314 ms 301 ms no real change
supabase config convert config-convert 376 ms 437 ms no real change (+16%, within normal variation)
supabase config validate config-validate 445 ms 435 ms no real change
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 668 ms 623 ms no real change (-7%, within normal variation)
supabase projects list projects-list 534 ms 541 ms no real change
supabase functions list --project-ref replayfixtureprojref functions-list 452 ms 471 ms no real change

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 phases

Timing ranges

Command Workload Before range After range Change Verdict
supabase --version version 344-563 ms 390-691 ms +46 ms (+11%) within noise
supabase --help help 322-526 ms 334-485 ms +0 ms (+0%) within noise
supabase init init 322-490 ms 315-434 ms -14 ms (-4%) within noise
supabase migration new bench migration-new 265-353 ms 269-341 ms -13 ms (-4%) within noise
supabase config convert config-convert 285-482 ms 278-510 ms +60 ms (+16%) within noise
supabase config validate config-validate 317-535 ms 310-768 ms -10 ms (-2%) within noise
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 478-774 ms 564-717 ms -45 ms (-7%) within noise
supabase projects list projects-list 399-715 ms 386-700 ms +6 ms (+1%) within noise
supabase functions list --project-ref replayfixtureprojref functions-list 391-566 ms 410-552 ms +19 ms (+4%) within noise

API calls per command

Command Workload Before After Endpoint changes
supabase --version version 0 0
supabase --help help 0 0
supabase init init 0 0
supabase migration new bench migration-new 0 0
supabase config convert config-convert 0 0
supabase config validate config-validate 0 0
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 2 2
supabase projects list projects-list 1 1
supabase functions list --project-ref replayfixtureprojref functions-list 2 2

Slowest phases

No command moved beyond noise, so there are no phase deltas.

Workflow run

Comment /bench to run the lightweight benchmark (this comment) again on the latest commit, or /bench full to also run the integration-heavy benchmark, which posts in its own comment.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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 Prashansa-K left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

This branch has not been deployed

No deployments
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.

2 participants