feat(spec): add ValueEnum aliases and case matching

[jdx]

Summary

• add aliases to #[derive(ValueEnum)] variants
• add enum-wide #[usage(ignore_case)] matching for canonical words and aliases
• keep diagnostics and emitted basic choices canonical while accepting the expanded vocabulary

Test plan

• cargo test -p usage-conformance --test typed
• cargo clippy --workspace --all-features -- -D warnings

Ready for review.

---

Note

Medium Risk
Changes which argv tokens parse for value_enum fields (aliases and optional case folding), though scope is limited to derived enums and conformance tests cover the behavior; diagnostics intentionally stay on canonical choices only.

Overview
Extends the PossibleValue / ValueEnum story on the Rust derive path: enums can declare #[usage(alias = "...")] on variants and #[usage(ignore_case)] on the type. Parsing and FromStr accept the expanded vocabulary (aliases and, when enabled, ASCII case-insensitive canonical names and aliases); InvalidChoice and emitted choices still list only canonical words, matching the Go side’s split between accepted vs visible lists.

Runtime: ValueEnum gains ACCEPTED_CHOICES and IGNORE_CASE, plus shared choice_matches. Generated check logic uses accepted choices for validation but canonical CHOICES in error messages.

Derive: ValueEnum modeling is refactored to ValueVariant (name + aliases); compile-time checks reject empty aliases and duplicate names/aliases (with case folding when ignore_case is set). Docs and PLAN.md note Rust alias/case support; per-value help and hidden-value metadata in Rust remain outstanding.

^{Reviewed by Cursor Bugbot for commit 7987267. 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: 2e7ccb7b-0959-4e62-a355-c5df88b650fe

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

[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 4c0be60. Configure here.}

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

framework	instructions, cold parse	vs usage
usage	4253	—
argh	6292	1.5x
clap	5895248	1386x
bpaf	21917796	5153x

                                              min       p01       p10    median
usage-rs: argv -> struct                      204       208       211       220  ns
argh: argv -> struct                          294       303       310       323  ns
clap: build tree + parse -> struct         492078    493913    497122    506176  ns
bpaf: build parser + parse -> struct      1639230   1639230   1657533   1682288  ns

usage: argv -> struct                             213 ns      0.21 µs
clap: build tree + parse -> struct             501791 ns    501.79 µs
clap: parse -> struct, tree reused              23673 ns     23.67 µs
clap: build tree only                          308278 ns    308.28 µs

_{7987267cbe32 vs a5e49b3695d1 · measured on the runner, not pushed to the history.}