fix(argv): show choices when a subcommand is required

[jdx]

Summary

• render the command's short help page when a required subcommand is missing
• keep the parse failure and exit status unchanged
• add diagnostic coverage for the command list

This restores the discoverability users expect from Clap: running a command that requires a subcommand shows the available choices instead of only saying that a subcommand is missing.

Stack

Targets the duplicate-flag PR and is the new direct base for #936.

Checks

• cargo test -p usage-argv --features diagnostics
• cargo test -p usage-conformance --test help_request --test subcommand_required
• full stacked cargo test --all --all-features
• full stacked Clippy with warnings denied

This PR was generated by Codex.

---

Note

Low Risk
User-facing stderr text only on a parse-error path; parse failure and exit status stay the same, with a safe fallback if help rendering fails.

Overview
When parsing stops with Error::MissingSubcommand, diagnostics now try help::render_at for the current command path and return that short help (including the Commands: list) instead of the old “requires a subcommand” line plus a usage block.

If help cannot be rendered, behavior falls back to the previous error message. A unit test asserts the new output lists subcommands like use and user and omits the old wording.

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

Summary by CodeRabbit

• User Experience
  • When a required subcommand is omitted, the command now displays its help page with available subcommands.
  • The previous “requires a subcommand” error and usage block are no longer shown in this case.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 6a73664c-c059-4717-b666-94b4452a6555

📥 Commits

Reviewing files that changed from the base of the PR and between 10b5f1f and 16e0387.

📒 Files selected for processing (1)

• argv/src/diagnostic.rs

Included review availability: Your plan includes up to 4 reviews per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Error::MissingSubcommand now renders the parsed command’s help page. The regression test verifies that the help lists use and user and excludes the previous missing-subcommand error.

Changes

Missing subcommand help

Layer / File(s)	Summary
Help rendering and regression coverage argv/src/diagnostic.rs	Error::MissingSubcommand returns help::render_at output. The regression test verifies the use and user commands and excludes the old error text.

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

Merge Risk: ⚪ Minimal · up to 16e03

Missing required subcommands will now show available choices while preserving the parse failure and exit status; no actionable merge-blocking risk remains.

Poem

I’m a rabbit with a help page bright,
Missing commands now show what’s right.
use and user hop into view,
The old error text is gone from the queue.
Carrots for tests—one, two, three!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the change to show available choices when a required subcommand is missing.

---

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

The PR changes missing-subcommand diagnostics to render the relevant command’s short help while preserving parse failure behavior and the existing fallback.

• Shows available subcommands when a required subcommand is omitted.
• Adds diagnostic coverage for the command list and removal of the generic error text.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
argv/src/diagnostic.rs	MissingSubcommand now returns short help when route resolution succeeds, retains the prior error-and-usage fallback, and adds focused output assertions.

_{Reviews (3): Last reviewed commit: "fix(argv): show choices when a subcomman..." | Re-trigger Greptile}

[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.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

	usage	clap	ratio
instructions, cold parse	64525	5893640	91x

usage: argv -> struct                            1071 ns      1.07 µs
clap: build tree + parse -> struct             500106 ns    500.11 µs
clap: parse -> struct, tree reused              23591 ns     23.59 µs
clap: build tree only                          310190 ns    310.19 µs

_{ae19f7bbca20 vs 60b4357913a5 · measured on the runner, not pushed to the history.}