perf(derive): outline invalid-value error construction from generated builds

[jdx]

Every generated build() inlined the full error-construction path per value field: the lossy rendering of the bad bytes, the diagnostic string allocations, and the boxing of InvalidValue. On a mise-sized CLI that code is duplicated across hundreds of fields — it accounted for roughly half of the generated build() code, and build() was the single largest category of code in the binary.

This keeps the conversion checks (String::from_utf8, FromStr, from_choice, os_string_from_bytes) inline at each field and moves only the cold error construction into four #[cold] #[inline(never)] builders in usage-argv:

• invalid_utf8_value — a word that was not UTF-8
• invalid_parsed_value — a value the field's type would not build from; takes the reason as &dyn Display so one copy serves every FromStr error type
• invalid_choice_value — a word not among a value enum's choices
• invalid_os_value — bytes the platform cannot hold in a path

Error messages are byte-identical by construction.

Measurements

Mise shadow gate binary (parse-n, 211 commands, stripped, full workspace release build, rustc 1.97.1, x86-64 Linux):

	main	this PR	delta
stripped binary	1,579,248 B	1,369,072 B	−210 KB (−13.3%)
generated build() code	427 KB	~215 KB	−50%
cold parse, instructions	7,501	7,433	−0.9%
parse wall time (time-sweep)	365 ns	364 ns	indistinguishable

Wall time is the min of 8 interleaved runs of each build on one machine; the run-to-run spread is about 15%, so a 1 ns difference is noise. The instruction count is the deterministic figure, and it moves the right way: the builders are only ever reached on a parse that has already failed, so pulling them out of the hot functions improves their codegen rather than costing a call.

For scale: parser cost over a no-parser baseline binary (346 KB) was 1,233 KB before this change — clap is 2,524 KB and bpaf 2,148 KB on the same fixture.

Verified: full conformance suite (535 tests), argv/derive/usage-rs suites (480 tests), clippy, fmt.

This PR description was generated by Claude Code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: ef1a2bdf-8eb7-4be6-8b40-9df80bd3cfca

📥 Commits

Reviewing files that changed from the base of the PR and between 4a4580d and 191ca5e.

📒 Files selected for processing (1)

• derive/src/codegen.rs

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The argv crate adds centralized constructors for invalid conversion errors. The derive code generator uses these constructors and expands generated CLI rendering, dispatch, metadata, inline subcommands, and requiredness behavior.

Changes

Invalid-value error handling

Layer / File(s)	Summary
Add invalid-value constructors argv/src/lib.rs	Adds cold, non-inlined constructors for UTF-8, parsed, choice, and platform-byte InvalidValue errors.
Route generated failures through constructors derive/src/codegen.rs	Generated conversions call the dedicated constructors for path, UTF-8, choice, and parsed-value failures.

Generated CLI behavior

Layer / File(s)	Summary
Render and dispatch generated commands derive/src/codegen.rs	Generated CLI types expose runtime-aware help and failure rendering. Dispatch supports external, inline, synchronous, asynchronous, context-free, context-aware, and lazy-context variants.
Preserve command metadata and fields derive/src/codegen.rs	Flattened groups retain help_heading metadata. Visible inline subcommand structs expose fields and descriptive documentation.
Adjust implicit-group requiredness derive/src/codegen.rs	Single-member implicit groups no longer add requiredness to field metadata or runtime checks.

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

Merge Risk: ⚪ Minimal · up to 191ca

The change moves invalid-value error construction out of generated hot paths while preserving conversion checks and error messages; no actionable merge-blocking risk remains beyond normal checks and review.

Poem

A rabbit reviewed the generated command flow,
With errors and dispatch in one tidy row.
Help renders cleanly; contexts load light,
Inline fields stay visible and right.
Old group checks now rest for the night.

🚥 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%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files.
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 and concisely describes moving invalid-value error construction out of generated build code, which is the primary 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.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▇▇▇▇▇▇▇▇▇▇▇▇█████	290,092,895 → 290,108,385	+0.01%	25.58 → 26.06ms	+1.91%
startup	▁▁▁▂▂▂▂▂████▅▅▅████▇	874,835 → 874,116	-0.08%	0.86 → 0.93ms	+7.70%

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.

framework	instructions, cold parse	vs usage
usage	8351	—
argh	6307	0.8x
clap	6315224	756x
bpaf	21909147	2623x

                                              min       p01       p10    median
usage-rs: argv -> struct                      433       440       444       460  ns
argh: argv -> struct                          316       322       329       338  ns
clap: build tree + parse -> struct         523829    525567    528714    542315  ns
bpaf: build parser + parse -> struct      1481732   1481732   1607368   1688929  ns

usage: argv -> struct                             450 ns      0.45 µs
clap: build tree + parse -> struct             543905 ns    543.91 µs
clap: parse -> struct, tree reused              24159 ns     24.16 µs
clap: build tree only                          334181 ns    334.18 µs

_{191ca5e46ed6 vs baad8d20bbf3 · measured on the runner, not pushed to the history.}