fix(cli): recognize about as root command help

[jdx]

Summary

• treat top-level about as the root command's help text during linting
• continue reporting undocumented subcommands independently
• add regression coverage for root and subcommand help handling

Root cause

KDL stores the root CLI description in Spec.about, while the generic command linter only inspected SpecCommand.help. As a result, the synthetic root command always reported missing-cmd-help even when the spec provided about.

Closes #790.

Validation

• cargo fmt --all -- --check
• cargo test -p usage-cli cli::lint
• cargo clippy -p usage-cli --all-features -- -D warnings

AI-assisted — Tool: Codex; model: OpenAI/GPT-5; version: unavailable.

---

Note

Low Risk
Lint-only behavior change with regression tests; no runtime CLI or security impact.

Overview
Fixes false missing-cmd-help info on the root command when a spec defines top-level about instead of root help (KDL stores the CLI description in Spec.about).

lint_command now takes has_root_about: the root lint passes spec.about.is_some(), and the missing-help rule is skipped only for that synthetic root. Subcommands still require their own help.

Tests expect a clean spec with about to lint with no issues, and assert only undocumented subcommands still get missing-cmd-help.

^{Reviewed by Cursor Bugbot for commit 2d2b01c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes

  • Updated linting to recognize root-level descriptive text as valid command help.
  • Prevented false missing-help warnings for documented root commands.
  • Continued reporting missing help for undocumented subcommands.

• Tests

  • Added coverage for root-level descriptions and undocumented subcommands.

[coderabbitai]

📝 Walkthrough

Walkthrough

The lint logic now accepts root-level about text as command help. It suppresses the root missing-cmd-help issue when about exists. Subcommands still require help. Tests verify this behavior.

Changes

Root command help linting

Layer / File(s)	Summary
Help validation and tests cli/src/cli/lint.rs	Root linting checks spec.about. Recursive subcommand linting does not inherit the root condition. Tests verify that only an undocumented subcommand produces missing-cmd-help.

Estimated code review effort: 2 (Simple) | ~10 minutes

Poem

A rabbit hops through linting bright,
Root about makes the warning take flight.
Subcommands still must helpfully speak,
Tests guard the rule the code now keeps.
Thump, thump—clean checks this week!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: treating root command about text as help during CLI linting.
Linked Issues check	✅ Passed	The changes address issue #790 by suppressing false root missing-cmd-help reports while preserving subcommand documentation checks.
Out of Scope Changes check	✅ Passed	The changes are limited to root help linting behavior and regression tests, which directly support issue #790.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR updates CLI linting so a top-level about satisfies the root command’s help requirement while undocumented subcommands remain independently reported.

• Passes root-description state explicitly into recursive command linting.
• Adds regression coverage for documented roots and undocumented subcommands.

Confidence Score: 5/5

The PR appears safe to merge with no actionable defects identified.

The root-only help exemption matches the separation between Spec.about and per-command SpecCommand.help, while recursion continues checking every subcommand independently.

Important Files Changed

Filename	Overview
cli/src/cli/lint.rs	Correctly limits Spec.about handling to the synthetic root command and adds focused regression tests without changing subcommand lint behavior.

_{Reviews (1): Last reviewed commit: "fix(cli): recognize about as root comman..." | Re-trigger Greptile}

[coderabbitai]

🧹 Nitpick comments (1)

cli/src/cli/lint.rs (1)

473-495: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a regression case for a root without about.

This test verifies root about suppression and subcommand validation. It does not verify that a root without about or cmd.help still reports missing-cmd-help. Add a fixture that asserts the root location is cmd test.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cli/src/cli/lint.rs` around lines 473 - 495, Extend
test_lint_uses_about_as_root_command_help with a fixture whose root omits about
and cmd.help, then assert lint_spec reports missing-cmd-help for the root
location cmd test. Preserve the existing subcommand validation assertion.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@cli/src/cli/lint.rs`:
- Around line 473-495: Extend test_lint_uses_about_as_root_command_help with a
fixture whose root omits about and cmd.help, then assert lint_spec reports
missing-cmd-help for the root location cmd test. Preserve the existing
subcommand validation assertion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 4b4fe441-b4eb-4c38-b36b-0525e4a68e62

📥 Commits

Reviewing files that changed from the base of the PR and between f274af8 and 2d2b01c.

📒 Files selected for processing (1)

• cli/src/cli/lint.rs

[github-actions]

Instruction counts

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{2d2b01cf156e vs f274af850209 · measured on the runner, not pushed to the history.}