feat(spec): add rich choice metadata

[jdx]

Summary

• add backward-compatible rich choices blocks with per-value help, hidden values, and visible or hidden aliases
• apply ignore_case and aliases in usage-lib while keeping hidden entries out of visible choice lists
• preserve clap PossibleValue metadata through the clap-to-spec bridge

Follow-up

Generated Rust and Go tables still flatten choice metadata. A follow-up PR will stack on this one to carry the model through those runtimes.

Test plan

• cargo test -p usage-lib --all-features
• cargo clippy -p usage-lib --all-features -- -D warnings

Ready for review.

---

Note

Medium Risk
Touches argv choice validation for all enumerated args and flags; behavior is backward compatible for simple lists but new alias/case rules change acceptance for rich specs.

Overview
Extends CLI choices beyond flat string lists so KDL and usage-lib can carry clap-style PossibleValue metadata: ignore_case, per-value help, hidden values, and visible or hidden aliases. Simple choices "a" "b" specs stay valid; rich blocks use nested choice / alias nodes as documented in arg.md.

Parsing and validation now resolve choices through SpecChoices::matches / matches_with_env, so argv accepts aliases and case-insensitive canonical names while visible choice lists omit hidden values and include non-hidden aliases. KDL round-trips the rich form when details is present.

The clap → spec path is centralized in choices_from_clap (args and flags), preserving help, hide, aliases, and ignore_case instead of flattening to strings. SpecChoice and SpecChoiceAlias are exported from the crate.

PLAN.md notes that generated Rust/Go tables still flatten choices; that codegen is explicitly out of scope here.

^{Reviewed by Cursor Bugbot for commit cfc5038. 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: 7095aa13-0fbf-4881-9219-4188c804c244

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 afacea4. 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	4220	—
argh	6292	1.5x
clap	5895248	1396x
bpaf	21917796	5193x

                                              min       p01       p10    median
usage-rs: argv -> struct                      192       196       199       203  ns
argh: argv -> struct                          282       286       291       299  ns
clap: build tree + parse -> struct         486967    488485    493088    502162  ns
bpaf: build parser + parse -> struct      1603172   1603172   1639458   1671574  ns

usage: argv -> struct                             219 ns      0.22 µs
clap: build tree + parse -> struct             507124 ns    507.12 µs
clap: parse -> struct, tree reused              23823 ns     23.82 µs
clap: build tree only                          316526 ns    316.53 µs

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