feat(derive): keep command aliases on their args

[jdx]

Summary

• accept alias and alias_hidden(...) on derived Args command structs
• merge struct aliases with any enum-variant aliases for backwards compatibility
• reject duplicate command names and aliases at compile time
• document the migration-friendly placement and cover it with conformance tests

This lets Clap-shaped command structs keep their command metadata when moving to usage_derive, so callers no longer need to relocate aliases into the parent enum.

Stack

Targets #939 (claude/derive-unknown-flags-inherit). #936 should be retargeted onto the final PR in this stack.

Checks

• cargo test -p usage-conformance --test subcommands
• cargo test -p usage-derive
• cargo test -p usage-argv
• full stacked cargo test --all --all-features
• full stacked Clippy with warnings denied

This PR was generated by Codex.

---

Note

Medium Risk
Changes derive codegen and static command tables used by every CLI; mistakes could break routing, help, or specs, though conformance tests cover the new alias paths.

Overview
Command aliases can live on derived Args structs (clap-style migration), not only on Subcommands variants. Visible and hidden aliases on the struct and on the mounting variant are joined at compile time via new concat_aliases, and emitted into both parse tables and metadata.

Root Cli still cannot declare aliases — those attributes are rejected there as misplaced. Duplicate aliases on one command fail at derive time; assert_unique_subcommand_names panics at compile time if any two subcommands share a name or alias after merging struct + variant tables.

Conformance tests move install/remove aliases onto the Args types and assert spec + parsing behavior (including hidden vs visible aliases).

^{Reviewed by Cursor Bugbot for commit 6a4511b. 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: dcb35ec6-0b49-406a-bda2-ab77be7767a1

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 preserves aliases declared directly on derived Args structs when they are mounted as subcommands, while retaining aliases declared on enum variants.

• Concatenates struct-level and variant-level visible and hidden alias metadata into generated static command tables.
• Adds compile-time validation that rejects collisions among command names and aliases after composition.
• Extends attribute parsing, documentation, and conformance coverage for migration-friendly alias placement.

Confidence Score: 5/5

The PR appears safe to merge, with alias composition, visibility metadata, and duplicate-name rejection remaining consistent across generated parser and specification tables.

The changed derive paths preserve aliases from both declaration levels, maintain matching hot and cold metadata, and reject ambiguous composed names at compile time; no actionable failure remains.

Important Files Changed

Filename	Overview
derive/src/codegen.rs	Emits struct-level aliases, composes them with variant aliases, keeps hidden-alias metadata aligned, and validates the completed subcommand table.
derive/src/model.rs	Parses and validates alias attributes on derived Args while retaining placement checks that reject them on root Cli declarations.
argv/src/lib.rs	Adds const-compatible validation for duplicate command names and aliases across fully composed subcommand tables.
argv/src/spec.rs	Adds compile-time alias-slice concatenation using lengths calculated from the same source groups.
conformance/tests/subcommands.rs	Exercises aliases split between Args structs and Subcommands variants and verifies emitted visibility metadata.
derive/src/lib.rs	Documents supported alias placement and the composition behavior when both declaration levels provide aliases.

_{Reviews (1): Last reviewed commit: "feat(derive): keep command aliases on th..." | 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	60566	5893652	97x

usage: argv -> struct                            1030 ns      1.03 µs
clap: build tree + parse -> struct             499514 ns    499.51 µs
clap: parse -> struct, tree reused              23413 ns     23.41 µs
clap: build tree only                          308597 ns    308.60 µs

_{6a4511b2bd81 vs 2ff6307581d6 · measured on the runner, not pushed to the history.}