feat(derive): declare the words a value may be

[jdx]

Reopens #834, which GitHub closed when I deleted its base branch on merging #833 — a closed PR cannot be reopened once its base is gone, so this is the same work on a fresh branch against main. My mistake in the merge order: retarget the child first, then merge the parent.

jdx: "yes let's do the ValueEnum derive, mise has a lot of those" — nine, to be exact.

#[derive(usage::ValueEnum)]
enum Interpreter {
    Bash,
    Zsh,
    Fish,
    #[usage(name = "pwsh")]
    PowerShell,
}

#[usage(short = 's', long, value_enum)] shell: Option<Interpreter>,
#[usage(long, var, value_enum)]         also: Vec<Interpreter>,

The point is that the list exists once

A value enum is normally a list of words written twice — once as the type, once for the framework. Here the type is the only copy, and everything reads from it:

• the emitted spec carries the words, so usage g markdown and the completions offer exactly what the parse accepts;
• the check that rejects a wrong value reads the same CHOICES;
• the generated FromStr is what typed values already call, so a value enum is not a special path — it is a type whose values happen to be listed.

A wrong word gives InvalidChoice { name: "shell", choices: ["bash", "zsh", "fish", "pwsh"] } rather than a conversion error mentioning a type the user never named.

What it refuses

declaration	why not
value_enum with choices(…)	the same list twice, and they can drift
value_enum on a bool	a switch has no value for a word to be
a variant holding fields	a value is one word; nothing would build the fields
two variants with the same name	one could never be reached
an enum with no variants	accepts no value at all
a variant behind #[cfg]	the words are a const array, which cannot hold a matching hole — so the arm would name a variant that is not there, or the list would offer a word nothing answers to

That last one was review's catch. I checked mise before choosing to refuse rather than support it: nine value enums, no cfg on any variant. If something ever needs it, the fix is to make the word list a function rather than a const, which is contained.

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

---

Note

Low Risk
Additive derive and trait surface with validation tests; no changes to the hot argv binding path beyond reusing existing choice checks.

Overview
Introduces #[derive(usage::ValueEnum)] for unit enums whose variants map to CLI words (kebab-case by default, overridable with #[usage(name = "...")]). Fields use value_enum instead of duplicating choices(...) on the attribute.

usage_argv::spec::ValueEnum exposes a single CHOICES slice. The derive wires that into cold-path metadata (emitted KDL choices), post-binding validation (InvalidChoice with the expected list), and generated FromStr so parsing still goes through the normal typed conversion path.

Compile-time guards reject value_enum combined with choices, on bool/count fields, non-unit variants, duplicate names, empty enums, generics, and #[cfg] on variants (const word lists cannot have holes). Conformance tests cover parse, spec round-trip, wrong values, and standalone FromStr.

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

Summary by CodeRabbit

• New Features
  • Added support for defining CLI values with enums using ValueEnum.
  • Enum values now power help text, completions, specifications, and input validation.
  • Added kebab-case names and optional custom names for enum choices.
  • Invalid values now report the accepted choices.
  • Added support for optional and repeated enum-valued fields.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds ValueEnum support for fixed CLI words. Derive code generates ordered choices and FromStr conversion. Fields can use value_enum to share choices across specification output, help, completions, parsing, and validation.

Changes

Typed value enum support

Layer / File(s)	Summary
Enum contracts and field validation argv/src/spec.rs, derive/src/model.rs, derive/src/lib.rs	Adds the ValueEnum trait and derive. Parses unit enums with kebab-case or overridden names. Validates duplicate names, conditional variants, unsupported variants, and conflicting field options.
Generated conversion and choice wiring derive/src/codegen.rs	Generates ValueEnum::CHOICES and FromStr. Uses type-provided choices for specification data and invalid-value errors.
CLI behavior and specification coverage conformance/tests/typed.rs, PLAN.md	Tests optional and repeated enum fields, pwsh naming, specification choices, parsing errors, and standalone conversion. Documents the completed milestone.

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

Mergeability Score: 🔵 Low · up to 7dafa

The derive currently rejects otherwise valid enums whose variants use Rust configuration attributes, which can prevent supported declarations from compiling. The PR is otherwise mergeable, but the owner should address this bounded compatibility issue or explicitly accept it.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant GeneratedEnum
  participant Specification
  User->>CLI: provide an enum word
  CLI->>GeneratedEnum: call FromStr
  GeneratedEnum-->>CLI: return variant or valid-choice error
  CLI->>Specification: expose ValueEnum::CHOICES

Loading

Possibly related PRs

• jdx/usage#803: Introduces the derive model and code-generation mechanisms extended by this change.
• jdx/usage#817: Relates to choice validation and generated specification handling.
• jdx/usage#833: Provides typed field and FromStr infrastructure used by ValueEnum.

Poem

I hop through words from dawn till night,
Each enum choice is ordered right.
pwsh joins the naming cheer,
Bad words list the choices clear.
Typed CLI fields now bloom—
A carrot dance inside the loom!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes declaring valid CLI words through the new value-enum derive.
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.

---

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 a ValueEnum derive and field-level value_enum attribute so enum words drive generated parsing, validation, and spec choices from one declaration.

• Adds the runtime ValueEnum::CHOICES contract.
• Generates FromStr and choice metadata from validated unit variants.
• Rejects conflicting choices, switches, conditional variants, duplicate names, and unsupported enum forms.
• Adds end-to-end typed parsing, spec, and error tests.

Confidence Score: 4/5

The implementation is otherwise coherent, but the broken public derive path should be corrected before merging because the documented integration does not compile.

The enum model and generated parser/spec behavior remain aligned, but downstream users following the new public example cannot resolve the derive macro from the usage crate.

Files Needing Attention: derive/src/lib.rs

Important Files Changed

Filename	Overview
derive/src/model.rs	Parses and validates value_enum fields and enum variants, with consistent rejection of unsupported declarations.
derive/src/codegen.rs	Emits aligned choice metadata, validation, and FromStr implementations from the same variant list.
derive/src/lib.rs	Exposes the new proc macro, but its example uses the unavailable usage::ValueEnum path.
argv/src/spec.rs	Adds the associated-constant trait consumed by generated metadata and validation.
conformance/tests/typed.rs	Covers enum conversion, repeated and optional fields, emitted choices, and invalid-choice diagnostics.

_{Reviews (1): Last reviewed commit: "feat(derive): declare the words a value ..." | Re-trigger Greptile}

[greptile-apps]

Documented derive path is unavailable

When a downstream user copies #[derive(usage::ValueEnum)], the usage crate has no such export, causing compilation to fail; the proc macro is currently exported from usage_derive.

Suggested change

	/// #[derive(usage::ValueEnum)]
	/// #[derive(usage_derive::ValueEnum)]

Knowledge Base Used: Compiled argv parsing and derives

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

[cursor]

Defaults skip value_enum choice check

Medium Severity

A default that is not among a field's choices is rejected at compile time, but the same mismatch on a value_enum field is not. The words live on the type, so choices is empty here and the check never runs. A mistyped default then fails every parse that relies on it.

 

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@derive/src/model.rs`:
- Around line 1470-1480: The rejection of variant-level cfg and cfg_attr in the
ValueEnum model must be removed. In derive/src/model.rs:1470-1480 delete the
unreachable cfg/cfg_attr error, and in derive/src/model.rs:1688-1707 update the
related handling/documentation to reflect that configured variants are
supported; also update derive/src/lib.rs:267-269 documentation accordingly. Add
an integration test covering variant-level cfg and cfg_attr, ensuring generated
CHOICES and FromStr use only enabled variants.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 5524b528-f849-4784-931c-307ec03f594e

📥 Commits

Reviewing files that changed from the base of the PR and between 7f18282 and 7dafa4b.

📒 Files selected for processing (6)

• PLAN.md
• argv/src/spec.rs
• conformance/tests/typed.rs
• derive/src/codegen.rs
• derive/src/lib.rs
• derive/src/model.rs

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

In the Rust version declared by this repository, do custom derive macros receive variant-level #[cfg]and#[cfg_attr] after active attribute processing? Cite Rust Reference or rustc documentation.

💡 Result:

Yes, custom derive macros receive a fully "configured" version of the item they are applied to, which means variant-level #[cfg] and #[cfg_attr] attributes are processed and evaluated before the derive macro receives the token stream [1][2][3]. According to the implementation details of the Rust compiler (rustc), #[derive] macro invocations require eager expansion of conditional compilation attributes across their entire input [2][3]. Specifically, the compiler performs a configuration pass (cfg-expansion) on the input item—including its variants, fields, and their associated attributes—to resolve #[cfg] and #[cfg_attr] attributes based on the current compilation target and active features [2][3]. Consequently, the derive macro does not see the original unconfigured source code; instead, it receives a stream where unconfigured parts (where the predicate was false) have been removed, and #[cfg_attr] attributes have been expanded into their constituent attributes [1][2][3]. While The Rust Reference describes the general attribute processing order—noting that macros are expanded after other attributes and that attributes are processed in a specific sequence—it is the specific "eager expansion" behavior of the #[derive] compiler machinery that ensures #[cfg] and #[cfg_attr] are resolved before the derive macro logic executes [1][2][4]. This behavior is designed to ensure that derive macros operate on the final, valid structure of the type they are processing [1].

Citations:

• 1: Make #[derive(A, B, ...)] cfg-eval its input only for A, B, ... and stabilize feature(macro_attributes_in_derive_output) rust-lang/rust#87220
• 2: https://doc.rust-lang.org/stable/nightly-rustc/src/rustc_expand/config.rs.html
• 3: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/config/struct.StripUnconfigured.html
• 4: https://doc.rust-lang.org/stable/reference/attributes.html

---

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- repository files ---'
git ls-files | rg '(^|/)(Cargo.toml|model\.rs|lib\.rs)$|derive'

printf '%s\n' '--- relevant source and tests ---'
for f in $(git ls-files | rg '(^|/)derive/src/(model|lib)\.rs$'); do
  printf '\n--- %s ---\n' "$f"
  wc -l "$f"
  sed -n '1440,1495p;1660,1725p' "$f" 2>/dev/null || sed -n '240,285p' "$f"
done

printf '%s\n' '--- manifest and cfg-related usage ---'
rg -n --glob 'Cargo.toml' 'rust-version|version|name'
rg -n --glob '*.rs' '#\[cfg(_attr)?\([^]]*\)\]|cannot have holes|value_enum|ValueEnum' derive tests 2>/dev/null | head -250

Repository: jdx/usage

Length of output: 5592

---

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- manifests ---'
for f in Cargo.toml derive/Cargo.toml conformance/Cargo.toml; do
  printf '\n--- %s ---\n' "$f"
  cat -n "$f"
done

printf '%s\n' '--- derive structure ---'
ast-grep outline derive/src/lib.rs
ast-grep outline derive/src/model.rs
ast-grep outline derive/src/codegen.rs

printf '%s\n' '--- ValueEnum implementation and generated choices ---'
rg -n -C 8 'impl ValueEnum|CHOICES|value_enum|to_kebab|from_input|variants' derive/src/model.rs derive/src/codegen.rs derive/src/lib.rs

printf '%s\n' '--- tests and conditional ValueEnum declarations ---'
rg -n -C 5 '#\[derive\(.*ValueEnum|ValueEnum.*derive|cfg_attr|#\[cfg' --glob '*.rs' .

Repository: jdx/usage

Length of output: 50368

---

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- ValueEnum codegen ---'
sed -n '1430,1515p' derive/src/model.rs
sed -n '1680,1735p' derive/src/codegen.rs

printf '%s\n' '--- derive documentation ---'
sed -n '252,281p' derive/src/lib.rs

printf '%s\n' '--- integration test harness ---'
sed -n '1,240p' conformance/tests/derive.rs

printf '%s\n' '--- all relevant conditional declarations ---'
rg -n -C 4 '#\[cfg(_attr)?\(' --glob '*.rs' conformance derive lib argv clap_usage cli

Repository: jdx/usage

Length of output: 50367

---

Align ValueEnum with Rust’s configured variant behavior.

cfg and cfg_attr are processed before the derive macro. The generated CHOICES list and FromStr arms use the same remaining variants, so no hole or miscompilation occurs.

Remove the unreachable rejection, add an integration test for variant-level cfg and cfg_attr, and update the documentation.

📍 Affects 2 files

• derive/src/model.rs#L1470-L1480 (this comment)
• derive/src/model.rs#L1688-L1707
• derive/src/lib.rs#L267-L269

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@derive/src/model.rs` around lines 1470 - 1480, The rejection of variant-level
cfg and cfg_attr in the ValueEnum model must be removed. In
derive/src/model.rs:1470-1480 delete the unreachable cfg/cfg_attr error, and in
derive/src/model.rs:1688-1707 update the related handling/documentation to
reflect that configured variants are supported; also update
derive/src/lib.rs:267-269 documentation accordingly. Add an integration test
covering variant-level cfg and cfg_attr, ensuring generated CHOICES and FromStr
use only enabled variants.

[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	39828	5960254	149x

usage: argv -> struct                            1621 ns      1.62 µs
clap: build tree + parse -> struct             498818 ns    498.82 µs
clap: parse -> struct, tree reused              23329 ns     23.33 µs
clap: build tree only                          308579 ns    308.58 µs

_{7dafa4b05f00 vs 7f1828254f27 · measured on the runner, not pushed to the history.}