feat(derive): let a field be the type it means

[jdx]

The largest thing standing between the derive and mise. Independent of #827–#829, so it can go in either order.

mise names PathBuf 227 times and its tool-version type 83 times in src/cli/. A derive that only holds String cannot hold mise's commands, however faithfully it expresses mise's spec.

#[usage(short = 'j', long)] jobs: Option<usize>,
#[usage(long)]              out: Option<PathBuf>,
#[usage(long)]              port: u16,          // bare: the type says it is required
#[usage(long, var)]         tool: Vec<Tool>,    // any FromStr of your own
#[usage(long, var)]         search: Option<Vec<PathBuf>>,

Option<Vec<T>> earns its place: "never given" and "given nothing" are different answers, and mise's root asks for that distinction three times.

What keeps it cheap

The layering does not move. Binding still collects text — a word's meaning is not a question about where it lands — and conversion happens once, where the struct is built. So defaults, env, choices and the variadic bounds all keep working on text, untouched.

Measured on the same fixture as main: 40,129 instructions against 39,963. +166, or 0.4%, nearly all of it bookkeeping the identity conversion cannot avoid.

That comparison is worth a note. On #827/#828 this parse measures ~50.9k, and I nearly reported this branch's 40k as a 20% win — it is not, it is a smaller shadow, because main has neither those branches' 91 aliases nor their boxed variants. Same trap the informative-benchmark change was made for; the honest number needs the same fixture on both sides.

Errors say what the type says

Err(Error::InvalidValue(bad)) => {
    bad.name;    // "jobs"
    bad.value;   // "lots"
    bad.reason;  // "invalid digit found in string"
}

Better than anything this crate could invent about someone else's type: u16 explains "number too large than can fit", and a tool argument explains itself. Error gained one variant and lost Copy, since that variant owns two strings — but the payload is boxed, so Error is still 40 bytes and the Result it rides in on the hot path did not grow. I checked that rather than assuming it.

A type no word could become is a compile error naming that type:

error[E0277]: the trait bound `HashMap<String, String>: FromStr` is not satisfied

One gap, deliberate and documented

A word reaches a field through from_utf8_lossy, so a PathBuf holding a path that is not UTF-8 gets replacement characters rather than bytes. Rare, and wrong when it happens. The fix is for the partial to hold OsString and let build decide — exact for PathBuf and OsString, an error for String rather than a silent mangling — which is the next PR rather than a bigger one now.

Also in here, from jdx's note that mise carries hacks purely to work around clap: PLAN.md now lists what adoption should let mise delete, checked against mise rather than assumed. Two of the five do not survive contact — command_effects.rs argues its own case for staying one central list, and mise-extra.usage.kdl turns out to be a docs link template rather than a workaround.

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

---

Note

Medium Risk
Public usage_argv::Error API changes (Copy removed, new variant) and derive codegen affects all parsers, but behavior is covered by new conformance tests and conversion stays off the successful parse hot path.

Overview
Typed CLI fields move beyond string-only binding: a field can be any T: FromStr, plus Option<T>, Vec<T>, and Option<Vec<T>> (so “flag never given” vs “given but empty” stays distinct). The argv layer still binds text; usage-derive converts when building the struct, with a fast path that moves std::string::String without re-parsing.

Failed conversions surface as Error::InvalidValue (boxed InvalidValue with field name, raw text, and the type’s Display message). Error no longer implements Copy; the new variant is boxed so the enum stays 40 bytes.

Subcommand Args builds use the same field_final logic as the root CLI (fixing typed fields on nested commands).

PLAN.md marks typed values done, notes the next step (non–UTF-8 via OsString in partials), and adds a mise adoption section on what clap workarounds can be removed vs what should stay.

conformance/tests/typed.rs covers numeric/path/custom types, Option<Vec<_>>, spec/KDL unchanged by Rust types, and subcommand conversion errors.

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

Summary by CodeRabbit

• New Features

  • Added type-driven conversion for CLI values, supporting numeric, path, custom FromStr, optional, and repeated fields.
  • Added support for optional collections, distinguishing absent values from empty collections.
  • Conversion failures now report the field, rejected value, and reason.

• Documentation

  • Updated documentation for supported typed-value patterns and current non-UTF-8 handling limitations.

• Tests

  • Added comprehensive coverage for typed fields, collections, conversion errors, and numeric validation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The derive pipeline now supports typed FromStr values for scalar, optional, repeated, and optional-repeated fields. Conversion failures use a boxed InvalidValue error. Tests and documentation cover the new behavior.

Changes

Typed value derivation

Layer / File(s)	Summary
Field type metadata derive/src/model.rs	Field analysis records declared value types, optional collection state, and generic wrapper structure for code generation.
Conversion error contract argv/src/lib.rs	Error no longer implements Copy. Error::InvalidValue stores the field name, rejected value, and conversion reason.
Typed field construction derive/src/codegen.rs	Root and subcommand construction converts required, optional, repeated, boolean, and count fields.
Typed value validation and documentation conformance/tests/typed.rs, derive/src/lib.rs, PLAN.md	Tests cover successful conversions, errors, ranges, collection presence, nested commands, and generated specifications. Documentation records supported types and non-UTF-8 handling.

Mise adoption plan

Layer / File(s)	Summary
Adoption and deletion inventory PLAN.md	The plan describes router-first migration, parser replay, and candidate obsolete structures.

Estimated code review effort: 4 (Complex) | ~45 minutes

Mergeability Score: ⚪ Minimal · up to f240d

The PR’s typed CLI conversion change has no demonstrated merge-blocking risk; one localized test should be strengthened to verify the rejected value explicitly.

Sequence Diagram(s)

sequenceDiagram
  participant CLIInput
  participant GeneratedCLI
  participant field_final
  participant FromStr
  participant InvalidValue
  CLIInput->>GeneratedCLI: parsed argument text
  GeneratedCLI->>field_final: finalize declared field
  field_final->>FromStr: convert value text
  FromStr-->>field_final: typed value or conversion error
  field_final-->>InvalidValue: create conversion error
  field_final-->>GeneratedCLI: finalized value or error

Loading

Possibly related PRs

• jdx/usage#798: Introduced the parser error model extended by this change.
• jdx/usage#803: Introduced derive model and codegen paths extended for typed values.
• jdx/usage#816: Modified the same derive field-handling pipeline.

Poem

A rabbit sorts strings by type,
Paths and numbers join the trip.
Missing piles stay clearly bare,
Bad values tell what went wrong there.
Boxed errors guard the lair.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the derive feature that lets fields use their declared types, matching the main change.

---

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 5e9cbaa. Configure here.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▃▁▂▁▆▇▅█▄▂▄▆	148,194,785 → 148,247,815	+0.04%	14.02 → 14.32ms	+2.15%
startup	██▁▁▁▅▅▅▅▅▅▅	1,201,903 → 1,201,983	+0.01%	0.97 → 0.97ms	+0.12%

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	39976	5960254	149x

usage: argv -> struct                            1644 ns      1.64 µs
clap: build tree + parse -> struct             505546 ns    505.55 µs
clap: parse -> struct, tree reused              23134 ns     23.13 µs
clap: build tree only                          313398 ns    313.40 µs

_{0501bb551c09 vs 128d19f0e471 · measured on the runner, not pushed to the history.}

[greptile-apps]

Greptile Summary

The PR adds FromStr-based typed CLI fields while preserving text-based binding, and reports conversion failures through a structured InvalidValue error.

• Supports required, optional, repeated, and optionally repeated typed values.
• Applies conversion consistently to root and subcommand payloads.
• Adds conformance coverage for standard, path, numeric, custom, and failing conversions.
• Documents the remaining non-UTF-8 limitation and updates the adoption plan.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/codegen.rs	Generates final FromStr conversion for root and subcommand fields; the previously reported qualified-type and subcommand omissions are fixed.
derive/src/model.rs	Classifies typed scalar and collection shapes and preserves full written paths for standard String identity detection.
argv/src/lib.rs	Adds the boxed InvalidValue payload and removes Copy from the public error enum.
conformance/tests/typed.rs	Covers typed root and subcommand values, optional collections, custom conversions, qualified custom String, and conversion errors.
derive/src/lib.rs	Updates the derive documentation to describe supported typed field shapes and conversion behavior.
PLAN.md	Marks typed values complete, records the non-UTF-8 follow-up, and documents expected mise adoption cleanup.

_{Reviews (3): Last reviewed commit: "fix(derive): move a `Vec<String>` rather..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 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/codegen.rs`:
- Around line 744-752: The generated parsing path in
derive/src/codegen.rs:744-752 stringifies FromStr errors, so either constrain
and document FromStr::Err: Display for required, optional, and repeated
non-String fields, or update InvalidValue to preserve conversion errors without
requiring Display; apply the corresponding API/documentation change in
derive/src/lib.rs:136-140 and ensure all affected generated conversion paths use
the same behavior.
- Around line 740-742: Remove the type_name(ty) == "String" fast path in the
final-segment generation logic so every value is converted through FromStr. Add
a regression test covering a custom::String field, document the required
FromStr::Err: Display bound needed by ToString::to_string(&reason), and preserve
the existing conversion behavior for other types.

🪄 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: ae08e8cd-977c-423e-a23c-8bae84128ffb

📥 Commits

Reviewing files that changed from the base of the PR and between 128d19f and 5e9cbaa.

📒 Files selected for processing (6)

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

[coderabbitai]

🧹 Nitpick comments (1)

conformance/tests/typed.rs (1)

19-42: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Test the rejected item in Vec<Tool>.

The test uses an empty invalid value. An empty fallback value would also pass an assertion for bad.value.

Make Tool reject one non-empty fixture value. Put that value after a valid --tool value. Assert that bad.value equals the rejected item.

Proposed test change

 impl FromStr for Tool {
     type Err = String;

     fn from_str(s: &str) -> Result<Self, Self::Err> {
+        if s == "invalid" {
+            return Err("unknown tool".into());
+        }
         if s.is_empty() {
             return Err("a tool needs a name".into());
         }

-    let a = argv(["--port", "1", "--tool", "", "thing"]);
+    let a = argv([
+        "--port", "1", "--tool", "node@20", "--tool", "invalid", "thing",
+    ]);
     match Typed::parse_from(&a) {
         Err(Error::InvalidValue(bad)) => {
             assert_eq!(bad.name, "tool");
-            assert_eq!(bad.reason, "a tool needs a name");
+            assert_eq!(bad.value, "invalid");
+            assert_eq!(bad.reason, "unknown tool");

Also applies to: 132-142

🤖 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 `@conformance/tests/typed.rs` around lines 19 - 42, Update the Tool::from_str
test fixture so one specific non-empty value is rejected, while preserving
acceptance of the valid --tool value before it. In the relevant Vec<Tool> test,
assert that bad.value equals that rejected fixture instead of relying on an
empty fallback value.

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

Nitpick comments:
In `@conformance/tests/typed.rs`:
- Around line 19-42: Update the Tool::from_str test fixture so one specific
non-empty value is rejected, while preserving acceptance of the valid --tool
value before it. In the relevant Vec<Tool> test, assert that bad.value equals
that rejected fixture instead of relying on an empty fallback value.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 19015755-3e50-45e8-b917-8ecabf13e5da

📥 Commits

Reviewing files that changed from the base of the PR and between 5e9cbaa and f240de9.

📒 Files selected for processing (4)

• conformance/tests/typed.rs
• derive/src/codegen.rs
• derive/src/lib.rs
• derive/src/model.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• derive/src/lib.rs
• derive/src/codegen.rs
• derive/src/model.rs

[jdx]

Real, and I priced the alternative rather than arguing about likelihood.

If an adopter writes use my_crate::String over a FromStr type of their own, that field is moved rather than converted and their crate fails to compile. A macro cannot resolve a name, so recognising String by how it is written is the only option available — the question is what the fix costs.

Converting unconditionally instead: 3 allocations become 5, and the parse goes 40,129 → 41,039 instructions (+2.3%) on mise use -g node@20. That is the price of protecting against someone shadowing String, which is a thing nobody should do and nobody in mise does.

So the fast path stays, the hazard is documented alongside the other known gaps, and it stops being a choice at all in the next PR: once the partial holds bytes rather than text, a String field converts like every other type and there is no identity case left to recognise. That change is already planned for the non-UTF-8 fix, and this is a second reason for it.

Measuring it turned up something worth having anyway. The collecting path was rebuilding a Vec<String> element by element — allocating a second Vec to hold what the first already held, one allocation per collecting field, and mise's commands collect a lot. It is moved whole now, which is what took the count back to 3.

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