Repository navigation
chore(cli): carry sidebar category and title as a command annotation (CLI-2686) - #7723
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 24.0 KB from 135.3 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@10488ed supplied to reviewers (advisory, not a style pass).
The release still publishes only the YAML spec, which now has empty section tags. The sidebar generator can silently omit commands assigned to an unknown category or emit links with blank labels. Several new labels misstate command behavior. The two terminology findings concern sidebar titles, which fall outside the trusted CLI reference prose procedure. The review was static. The website consumer and the pinned pnpm version were unavailable for verification.
Findings
| Severity | Location | Category | Sources | Claim |
|---|---|---|---|---|
| 🟡 MINOR | apps/cli/src/docs/docs-spec.ts:435 |
compatibility |
codex | The published clispec 001 loses the section definitions and per-command section memberships that it previously supplied. |
| 🟡 MINOR | apps/cli/src/docs/docs-spec.ts:416 |
build-validation |
codex | The spec generator and publisher can accept a new top-level command with no sidebar category. |
| 🟡 MINOR | apps/cli/src/command-internal/command-sidebar.ts:43 |
input-validation |
codex | An invalid category can pass type checking and silently omit a top-level command and its descendants from the generated sidebar. |
| 🟡 MINOR | apps/cli/src/docs/docs-sidebar.ts:66 |
accessibility |
codex | The generator can emit a command link with an empty or whitespace-only label. |
| 🟡 MINOR | apps/cli/docs/README.md:67 |
developer-workflow |
codex | Copying or redirecting the complete output of the documented pnpm docs:sidebar invocation may produce invalid sidebar JSON if pnpm includes a lifecycle banner on stdout. |
| 🟡 MINOR | apps/cli/src/commands/db/db.command.ts:18 |
docs-accuracy |
codex | The sidebar labels for db, db diff, and db pull imply target restrictions absent from the commands. |
| 🟡 MINOR | apps/cli/src/commands/db/dump/dump.command.ts:101 |
docs-accuracy |
codex | The new db dump sidebar label describes only a remote schema dump even though the command also supports local targets, data dumps, and role dumps. |
| 🟡 MINOR | apps/cli/src/commands/start/start.command.ts:94 |
docs-accuracy |
codex | The start sidebar label suggests a single container, and the stop label suggests all containers on the machine. |
| 🟡 MINOR | apps/cli/src/commands/storage/ls/ls.command.ts:33 |
docs-accuracy |
codex | The storage ls sidebar label promises a complete listing, but the command can scope the results by path and recurses only when requested. |
| 🟡 MINOR | apps/cli/src/commands/postgres-config/delete/delete.command.ts:46 |
docs-accuracy |
codex | The postgres-config delete sidebar label can be read as deleting entire Postgres configurations. |
| ⚪ NIT | apps/cli/scripts/publish-docs-spec.ts:134 |
docs-tooling |
claude | The release still depends on a manual sidebar update. Commands such as logs or config validate can remain missing from the website reference if their IDs are absent from the website sidebar and nobody copies the generated file. |
| ⚪ NIT | apps/cli/src/docs/docs-spec.unit.test.ts:273 |
test-clarity |
codex | The whoami test still names the Management API reference after losing its section placement assertion. |
| ⚪ NIT | apps/cli/scripts/generate-docs-sidebar.ts:9 |
repo-conventions |
codex | The new script writes to stdout outside Effect. |
Refuted findings (kept for transparency, not posted as review comments)
apps/cli/src/commands/login/login.command.ts:37(docs-style): The new login sidebar title uses “Log in” where the upstream word list prescribes “Sign in” for prose.
Refuted: The quotation and upstream rule match. The trusted procedure limits this style check to overlays and command, flag, and example descriptions. The changed string is consumed as a navigation title at apps/cli/src/docs/docs-sidebar.ts:66–77. The command descriptions at apps/cli/src/commands/login/login.command.ts:38–39 are unchanged.apps/cli/src/commands/domains/delete/delete.command.ts:36(docs-style): The new custom hostname sidebar titles use “config” where the upstream word list prefers “configuration” in general prose.
Refuted: The pinned heading and all three quotations match. Each change is awithSidebartitle consumed by the sidebar generator. The neighboring command descriptions and examples are unchanged, so the changed strings fall outside the trusted prose procedure.
Stats
Claude findings: 1 · Codex findings: 14 · Confirmed: 12 · Refuted: 2 · 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.
Generate the docs-site CLI sidebar from command annotations. A top-level command declares its sidebar category with
withSidebar({ category }), and its subcommands inherit that category. A sidebar title defaults to the command's short description, andwithSidebar({ title })overrides it. Overrides are added only where the current sidebar already uses a different title or where the short description is longer than 50 characters, so no short descriptions change.pnpm docs:sidebar(fromapps/cli) writes the content forcommon-cli-sections.json. Categories are a compile-time union ofDOCS_SIDEBAR_CATEGORIES, which also sets their order. The build fails when a top-level command has no category, a subcommand declares one, a title is longer than 50 characters, or a category has no commands.The spec no longer carries section tags:
DOCS_TAGSis removed and everytagsarray is empty.Differences from the current sidebar:
inspect db collation-drift,inspect db toast-sizes,inspect db xid-age,logs,logs sources,config convertandconfig validate.inspect db.inspect db role-statsslug becomessupabase-inspect-db-role-stats.ssl-enforcement gettitle drops a trailing "s" to fit the 50-character limit.Linear: CLI-2686