feat(derive): a command that takes nothing can be written that way

[jdx]

The last of the communique follow-ups. clap lets a command with no options be a bare variant; the derive wanted three things to say the same:

// before
#[derive(Args)] struct Sponsors {}
enum Command { Sponsors(Box<Sponsors>) }
// ...and at the call site, because `_` leaves the payload unread and dead_code is an error in CI:
Command::Sponsors(args) => { let cli::Sponsors {} = *args; sponsors() }

// after
enum Command { #[usage(effect = "read")] Sponsors }
Command::Sponsors => sponsors(),

Everything generated speaks to a struct — its tables, its metadata, its build — so rather than teach all of that about a variant with no struct, the derive writes the empty struct such a variant implies and points the variant at it. Only the construction differs.

The struct is named after the enum as well as the variant: two enums in one module may each declare a Sponsors, and two structs of one name is a worse error than the one being avoided — it would land in the adopter's crate, pointing at something they never wrote. A test has two such enums.

effect moves with it

This is the part I did not see coming. effect is an Args attribute, because that is where a command declares itself — and a bare variant has none. Porting communique's sponsors over dropped effect=read from its spec, silently. Its in-sync test caught it, which is the second time that test has paid for itself.

So a variant carries effect when it holds nothing, and the written struct receives it as the same attribute, read by the same code. Refused on a variant that does wrap a struct: two places to say one thing is two answers waiting to disagree.

What communique deletes

 src/cli.rs  | 7 +------
 src/main.rs | 8 +-------

Verification

mutation	result
a bare variant still builds with a payload	generated code fails to compile
the implied struct is not written	generated code fails to compile
the struct name omits the enum	generated code fails to compile (two enums, one name)
effect on a struct-wrapping variant is accepted	FAILED

The third survived at first — my fixture had only one enum, so nothing collided. Seven conformance tests, workspace suite green, clippy clean, gate green over mise's 211 commands.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

---

Note

Medium Risk
Touches core Subcommands codegen and parsing/build paths for all unit variants; mistakes could break spec/help/effect metadata or cause name collisions, though coverage is broad in new conformance tests.

Overview
Subcommands can be written as bare unit variants (e.g. Sponsors,) instead of Sponsors(Box<Sponsors>) plus a hand-written empty Args struct. The derive emits a hidden #[derive(Args)] empty struct per unit variant so parsing, spec, help, and build still go through the same CommandArgs path; only enum construction changes (Command::Sponsors vs wrapping a payload).

#[usage(effect = "...")] on the variant is allowed when the variant holds nothing (forwarded onto the generated struct). Putting effect on a variant that wraps a struct is a compile error.

Naming hardening: implied structs use length-prefixed __Usage{n}{Enum}{Variant} ids so two enums in one module can both have Sponsors; variant ids use unraw() so r#type becomes command name type and macro id generation does not panic.

Adds conformance tests in unit_variants.rs and crate docs for the pattern.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 15483c5c-45b2-4d7c-8f9b-071991e94dbb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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 adds support for bare unit variants in Subcommands, generating empty Args helpers so existing table, metadata, validation, and build paths remain shared.

• Supports command-level effect metadata on unit variants while rejecting it on payload-bearing variants.
• Uses raw-identifier normalization and length-prefixed helper names to avoid the previously reported generated-name ambiguity and panic.
• Adds conformance coverage for parsing, metadata, help, aliases, hidden commands, effects, and generated-name edge cases.

Confidence Score: 4/5

The PR is not yet safe to merge because a bare subcommand can still make an adopter's crate fail to compile when its generated helper name matches an existing module-level type.

The raw-identifier and generated-pair ambiguity issue is fixed, but unit helpers are still emitted under predictable names directly into the adopter's type namespace, leaving the previously reported user-type collision unresolved.

Files Needing Attention: derive/src/codegen.rs, derive/src/model.rs

Important Files Changed

Filename	Overview
derive/src/model.rs	Adds unit-variant modeling, effect validation, raw-identifier normalization, and unambiguous generated helper naming.
derive/src/codegen.rs	Generates empty backing structs and unit-variant construction, but the deterministic helper remains exposed to collisions in the adopter's module namespace.
conformance/tests/unit_variants.rs	Adds end-to-end coverage for unit commands, metadata, aliases, hiding, effects, and generated-name edge cases.
derive/src/lib.rs	Documents bare subcommand variants and where their effect metadata is declared.

_{Reviews (5): Last reviewed commit: "fix(derive): a command may be named afte..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ef3bb01. Configure here.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▃▄▄▃▃███	180,287,329 → 180,384,453	+0.05%	16.15 → 16.50ms	+2.17%
startup	▁▁▁▁▁▁▁▁▆▃█	1,222,732 → 1,226,001	+0.27%	0.95 → 0.96ms	+0.69%

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	72156	5895162	81x

usage: argv -> struct                            1193 ns      1.19 µs
clap: build tree + parse -> struct             497404 ns    497.40 µs
clap: parse -> struct, tree reused              23316 ns     23.32 µs
clap: build tree only                          307400 ns    307.40 µs

_{99f2622ead38 vs 81b1ee788d23 · measured on the runner, not pushed to the history.}

[jdx]

Triaged all three; none needs a change here, but the second one surfaced a real limitation worth writing down.

Synthesized identifiers collide and panic — neither half holds. Raw identifiers are unraw'd before the name is built (enum_ident.unraw() / variant.unraw()), so r#type never reaches syn::Ident::new with its prefix. And the concatenation is not separator-free: it carries the enum name's length, so the pair you name goes to __Usage3FooBarBaz and __Usage6FooBarBaz. Verified by compiling a CLI with a r#type bare variant alongside a normal one.

Public generated unit structs — the premise is not right: pub items are legal in function scope. pub struct, pub mod, and pub fn in an impl all compile inside a fn body; rustc emits no error and only an unused warning.

Underneath it, though, there is a real failure — a Subcommands enum declared in a function body does not compile, because the generated mod refers to its types through super, and super from a module nested in a function body is the enclosing module, not the body:

error[E0425]: cannot find type `__Usage5LocalInner` in module `super`
error[E0425]: cannot find type `Local` in module `super`

Not a regression from this PR, and not about unit variants: the identical enum written with a wrapping variant and no bare variant anywhere fails the same way, with the same two errors. It is a pre-existing limitation of the mod/super emission. Filing it separately rather than expanding this PR's scope.

Generated helper collides with user types — accepted. __Usage{len}{Enum}{Variant} is __-prefixed, length-disambiguated against sibling enums, and would require an adopter to declare that exact name at module scope. Worth a note in the derive docs rather than a hygiene mechanism.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.