feat(derive): say that a command cannot be run alone, which it knew and did not write

[jdx]

Stacked on #923 — review that first; this PR's diff is the last commit. One of the two gaps #936 found by converting usage-cli itself to the derive; the other one gets its own PR.

A bare T subcommand field requires a subcommand and an Option<T> does not. The parser has always refused the invocation accordingly — that half was never missing — but Spec::to_kdl wrote nothing, so the emitted KDL described usage generate as a command a user could type on its own.

That reaches past help text: docs, manpages, completions and the SDK generators all read the emitted spec rather than the Rust type, so every one of them was offering a command that cannot run.

cmd "settings" help="Manage settings" subcommand_required=#true {

Shape

Cold metadata rather than a parse table — subcommand_required is not how a word binds, and the hot path never reads it. CommandMeta gains a bool, the derive fills it from the field's type, and the writer emits it only where there is something to require: the property on a command with no subcommands is a spec the linter reports and nothing could satisfy, so both conditions are held.

gen-shadow already read subcommand_required from a KDL and chose T against Option<T> accordingly, so mise's shadow round-trips it now instead of losing it on the way back out.

Verification

• conformance/tests/subcommand_required.rs — four tests: a strict command says it, a loose one stays quiet and reads back as false, a leaf never claims it, and the parser and the spec agree about which invocations exist.
• nesting's snapshot picks the change up on a fixture that was already shaped this way, which is the check that this is emission rather than a new rule.
• Workspace suite green, clippy clean.

Not fixed here

The spec accepts subcommand_required only inside a cmd block, so a root that cannot run alone still has no way to say so — the same restriction as the root mount, recorded next to it in PLAN.md. The clap bridge could not say it either, so nothing regressed.

This PR was generated by Claude Code.

---

Note

Low Risk
Cold-path metadata and KDL emission only; parsing behavior was already correct, with added compile-time validation for an invalid flatten shape.

Overview
Emits subcommand_required in specs so docs, completions, and generators match parser behavior: a non-optional #[usage(subcommand)] field sets cold metadata and writes subcommand_required=#true only when the command actually has subcommands; optional fields stay omitted and read back as false.

Compile-time guard via flatten_checks: a #[usage(flatten)] type that still declares subcommands fails const evaluation, because flatten would leave the parent unable to express required subcommands while the nested build still demands one.

Tests and docs: new conformance/tests/subcommand_required.rs, updated nesting snapshot (settings gains the flag), and PLAN.md marks the derive/spec gap done while noting root-level subcommand_required remains unsupported in KDL.

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

Summary by CodeRabbit

• New Features

  • Command specifications now identify when a subcommand is required.
  • Help, documentation, completions, and generated specifications consistently reflect required versus optional subcommands.
  • Nested required-subcommand behavior is supported.

• Bug Fixes

  • Improved parsing and specification output for commands with required or optional subcommands.

• Documentation

  • Documented the remaining limitation that root-level required subcommands cannot currently be represented.

[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: 16dd7ed0-8776-4459-97a8-01749cb48ab2

📥 Commits

Reviewing files that changed from the base of the PR and between eb35780 and a2b02d4.

⛔ Files ignored due to path filters (1)

• conformance/tests/snapshots/nesting__the_emitted_spec_reads_like_a_handwritten_one.snap is excluded by !**/*.snap

📒 Files selected for processing (4)

• PLAN.md
• argv/src/spec.rs
• conformance/tests/subcommand_required.rs
• derive/src/codegen.rs

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

---

📝 Walkthrough

Walkthrough

The derive code now computes required-subcommand metadata for root and nested commands. CommandMeta stores the value, and KDL serialization emits it for applicable commands. Conformance tests cover required, optional, and leaf command hierarchies.

Changes

Subcommand requirement metadata

Layer / File(s)	Summary
Command metadata and KDL serialization argv/src/spec.rs	CommandMeta includes subcommand_required. KDL output emits the property only for commands with required subcommands.
Derived requirement generation derive/src/codegen.rs	Root and nested command generation detect non-optional subcommand fields and pass the result into CommandMeta.
Conformance coverage and milestone tracking conformance/tests/subcommand_required.rs, PLAN.md	Tests verify required, optional, and leaf command behavior. The plan records nested support and the root-level specification limitation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to a2b02

The change adds a public CommandMeta field, which can break downstream code using complete struct literals; merge is appropriate with explicit release-version or migration guidance.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as CLI declaration
  participant DeriveCodegen
  participant CommandMeta
  participant KDLSerializer
  CLI->>DeriveCodegen: define subcommand fields
  DeriveCodegen->>CommandMeta: emit subcommand_required
  CommandMeta->>KDLSerializer: provide command metadata
  KDLSerializer-->>CLI: serialize required-subcommand flag

Loading

Possibly related PRs

• jdx/usage#905: Both changes update derive code generation and CommandMeta emission for command-level metadata.

Poem

A rabbit hops through nested commands,
Marking which paths must run below.
Metadata blooms in KDL,
Tests check every route they know.
Root-level limits remain in tow.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 accurately describes the derive change that emits metadata for commands that require a subcommand, although its wording is somewhat verbose.

---

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 aligns derived command metadata with parser behavior by emitting subcommand_required for commands containing a required subcommand field and rejecting flattened groups whose subcommands cannot be routed.

• Adds subcommand_required to cold command metadata and conditionally serializes it to KDL.
• Derives requiredness from bare versus optional subcommand fields.
• Adds a compile-time guard against flattened groups that declare subcommands.
• Adds conformance coverage and updates the nesting snapshot and implementation plan.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported flattened-subcommand mismatch is prevented by a compile-time assertion on each flattened group, and no blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/codegen.rs	Derive output now records required subcommands and the compile-time flatten guard resolves the previously reported metadata/parser mismatch.
argv/src/spec.rs	Cold command metadata gains a default-false requiredness field that is emitted only for commands with satisfiable subcommands.
conformance/tests/subcommand_required.rs	End-to-end tests cover strict, optional, leaf, parsing, and emitted-spec behavior.
conformance/tests/snapshots/nesting__the_emitted_spec_reads_like_a_handwritten_one.snap	Snapshot correctly records requiredness for the existing nested strict command.
PLAN.md	Documents the completed nested-command fix and the intentionally deferred root-command limitation.

_{Reviews (5): Last reviewed commit: "feat(derive): say that a command cannot ..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁████████	180,301,068 → 180,465,907	+0.09%	17.50 → 16.49ms	-5.79%
startup	▁▆▂▂▅█▆██	1,226,319 → 1,226,289	-0.00%	1.00 → 1.01ms	+0.83%

No instruction-count regression above 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	60439	5893640	97x

usage: argv -> struct                            1053 ns      1.05 µs
clap: build tree + parse -> struct             500627 ns    500.63 µs
clap: parse -> struct, tree reused              22862 ns     22.86 µs
clap: build tree only                          310992 ns    310.99 µs

_{8ca7f41e0745 vs 02e459bc675b · measured on the runner, not pushed to the history.}

[jdx]

Addressed the P1, and it was real — worse than reported, in fact.

A #[usage(flatten)] group that declares subcommands of its own does not merely report subcommand_required=false: the group's subcommands never reach the parent's table at all, so the command is unreachable in both directions. Reduced to a probe on the branch before this fix:

cmd "parent" {
}

bare parent parses: false

The spec says parent is a runnable leaf; the parser rejects it; and no word could satisfy it, because leaf is in no table. That is flatten's own hole rather than something this PR introduced — this PR would just have printed a confident false over it.

Refused at compile time, the way Option<T> flatten already is: joining two commands' subcommand sets needs a rule for which enum a word selects from, and nothing in the fleet asks for one. flatten_checks asserts the group's COMMAND has no subcommands, during const evaluation in the parent's expansion — the same trick find_subcommand uses for default_subcommand, and what lets one expansion check a fact about another it cannot see:

error[E0080]: evaluation panicked: a flattened group cannot declare subcommands: flatten
joins flags and arguments into the parent's tables and leaves subcommands behind, so the
command would require one that no word could select. Declare the `subcommand` field on the
command's own struct instead.
  --> src/main.rs:10:10
   |
10 | #[derive(Args)]
   |          ^^^^

It points at the parent's derive, which is where the flatten is written.

The legitimate shape is untouched — conformance/tests/flatten.rs has a command with both a subcommand field and a flattened group, and mise's ten flattens are all flags and arguments. Workspace suite green, clippy clean under --all-targets, gate green.

There is no compile-fail harness in this repo, so the refusal is verified by hand and documented at the top of conformance/tests/subcommand_required.rs and in PLAN.md, next to the entry it protects.

This comment was generated by Claude Code.