feat(derive): say three things about a CLI the spec could and the derive could not

[jdx]

Found by rendering mise's help from the shadow's metadata and diffing every line against
usage-lib's. 23 of 211 differed, and every difference traced back to something mise's KDL
declared, the derive had no vocabulary for, and gen-shadow dropped without counting.
That last part is what made them invisible: the dropped-property report exists to prevent
exactly this, and it was reporting nothing.

value_name — the placeholder for a flag's value. FlagMeta had the field and the KDL
writer already read it; nothing could set it. So a spec saying --tool <TOOL> came back
saying --tool <tool>, because the flag's own name was all that was left. 211 of mise's
flags carry one.

required on a collecting argument — <TARGET>…, meaning one or more. Required-ness is
normally the type's to say, and a Vec cannot: it has no bare-versus-Option shape. This is
the one place it is declared rather than inferred, and it is refused anywhere the type
already answers the question, in either direction.

var on a counted flag — inferred rather than declared, because a count is repetition:
-vvv is three occurrences and counting them is the point. Left out, the emitted spec said
count without var where mise's says both.

These matter past help text. The emitted spec is what docs, manpages, completions and the SDK
generators read, so a property that cannot survive the round trip is one every downstream
consumer is wrong about.

gen-shadow emits all three now, and the report for the usage dialect drops from six kinds
of loss to three — the remaining ones being genuine gaps with nothing yet to express them.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

---

Note

Medium Risk
Touches derive parsing, post-bind validation, and shadow codegen across the full mise CLI surface; behavior changes for empty required collections and help/spec placeholders, but bounded by new tests and spec diffing.

Overview
Closes three spec→derive gaps that were silently dropped by gen-shadow (and invisible in the drop report): flag value placeholders, one-or-more collections, and repeatability on counted flags.

value_name on value-taking flags so help/spec show --tool <TOOL> instead of defaulting to the flag name. required on Vec positionals and collecting flags so <TARGET>… is enforced at parse time and in emitted KDL, aligned with metadata via a single required expression. var is inferred for count flags (and plain repeatable valueless flags get var in shadow gen) so -vvv matches the reference spec.

gen-shadow now emits these attributes; the mise shadow gains widespread value_name / required annotations. Compile-time validation rejects contradictory uses (required on Option/bare types, value_name on positionals or valueless flags, required vs required_if/Option<Vec>). Conformance tests cover metadata and required-collection parsing; PLAN.md marks the milestone done.

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

How these were found

By starting the next item — help rendering — and immediately checking it against the
reference: render mise's usage line from the shadow's metadata, compare all 211 against
usage-lib's. 23 differed, and every one traced back to something mise's KDL declared, the
derive had no vocabulary for, and gen-shadow dropped without counting it.

That last part is the real finding. The dropped-property report exists so the shadow can never
look like a faithful translation of a spec it cannot represent — and for these three it was
reporting nothing at all.

mise config get   [-f --file <file>] [KEY]   ← ours
                  [-f --file <FILE>] [KEY]   ← usage-lib

mise deps remove  [PACKAGES]…               ← ours
                  <PACKAGES>…               ← usage-lib

mise cache prune  [-v --verbose]            ← ours
                  [-v --verbose…]           ← usage-lib

The three

	what it is	why the derive could not say it
value_name	the placeholder for a flag's value	FlagMeta had the field and the KDL writer already read it — nothing could set it, so the flag's own name stood in
required on a collection	<TARGET>…, one or more	required-ness is the type's to say, and a Vec has no bare-versus-Option shape to say it with
var on a counted flag	that it may be given again	now inferred, not declared: a count is repetition — -vvv is three occurrences

required is refused anywhere the type already answers the question, in either direction — on
an Option it contradicts, on a bare type it is redundant, and a declaration that changes
nothing is one someone will eventually trust.

Why it matters past help text

The emitted spec is what docs, manpages, completions and the SDK generators read. A property
that cannot survive the round trip is one every downstream consumer is wrong about — which is
also why the fix belongs here rather than in the renderer.

The usage dialect's dropped-property report goes from six kinds of loss to three, and the three
that remain are genuine gaps with nothing yet to express them.

Verification

• Four tests on a CLI declaring all three, asserting each reaches the parsed-back spec.
• All three mutation-checked: reverting each fix fails exactly its own test.
• Two refusal tests for required in the places the type already answers.
• mise run gen-shadow regenerated; 211 value names and 16 required markers now survive.

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

Summary by CodeRabbit

• New Features

  • Generated CLI help and completion metadata now preserve explicit value names.
  • Required variadic arguments and collections are represented accurately.
  • Counted and repeatable flags now expose correct repeatability metadata.
  • Generated specifications better reflect command usage with required markers and value placeholders.

• Bug Fixes

  • Fixed discrepancies between generated specifications and rendered help output.
  • Improved metadata handling for flags, collections, flattened fields, and subcommands.
  • Added validation for unsupported or conflicting argument metadata.

[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: fd3316ed-e093-465b-8f31-d83ea13a806a

📥 Commits

Reviewing files that changed from the base of the PR and between 93ab605 and 93b378f.

📒 Files selected for processing (1)

• derive/src/model.rs

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

• derive/src/model.rs

---

📝 Walkthrough

Walkthrough

The derive model now preserves value names, required collection metadata, and counted-flag repeatability. Code generation and shadow generation emit these semantics. The mise shadow and conformance tests update and validate the resulting metadata.

Changes

Metadata parity

Layer / File(s)	Summary
Derive metadata model and code generation derive/src/model.rs, derive/src/codegen.rs	The derive model parses and validates value_name and collection required attributes. Code generation emits value names and required metadata. Count flags now infer repeatability.
Usage shadow metadata generation xtask/src/shadow.rs	Shadow generation preserves repeatability for valueless flags, omits redundant value names, and emits required for required collecting arguments.
Generated shadow updates and conformance coverage benches/shadows/mise/src/lib.rs, conformance/tests/metadata.rs, conformance/tests/derive.rs, PLAN.md	The mise shadow adds value labels and required positionals. Conformance tests verify value-name preservation, counted-flag repetition, required collections, KDL output, parsing, and argument binding. The plan records the completed parity milestone.

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

Mergeability Score: ⚪ Minimal · up to 93b37

This PR updates CLI metadata propagation, collection validation, and the generated shadow; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CliDeclaration
  participant DeriveModel
  participant Codegen
  participant ShadowGenerator
  participant ConformanceTests
  CliDeclaration->>DeriveModel: Provide value_name and required attributes
  DeriveModel->>Codegen: Provide validated field metadata
  Codegen->>ShadowGenerator: Provide generated argument metadata
  ShadowGenerator->>ConformanceTests: Produce shadow usage metadata
  ConformanceTests->>ConformanceTests: Verify value names, repeatability, required collections, and binding

Loading

Possibly related PRs

• jdx/usage#799: Related flag repeatability and variadic parsing semantics.
• jdx/usage#801: Related CLI usage-spec metadata and KDL generation.
• jdx/usage#803: Related derive model, code generation, and conformance paths.

Poem

A rabbit names each flag with care,
And counts the values gathered there.
Required bundles stand in line,
While shadow specs preserve each sign.
The tests confirm the meanings match—
Hop, hop, metadata is intact!

🚥 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 and summarizes the three metadata capabilities added by the changes.

---

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 closes metadata round-trip gaps for flag value placeholders, required collections, and repeatable counted flags.

• Adds and validates value_name and required-collection derive attributes.
• Aligns required-collection runtime checks with emitted metadata.
• Updates shadow generation and adds conformance coverage.
• Regenerates the mise shadow with preserved metadata.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/model.rs	Adds attribute parsing and validation for required collections and value placeholders; the two previously reported cases are now rejected or preserved correctly.
derive/src/codegen.rs	Emits value names and required-collection metadata and enforces required collections during post-binding validation.
xtask/src/shadow.rs	Preserves value names, required variadic collections, and repeatability when generating derive shadows.
conformance/tests/derive.rs	Verifies that absent required collections fail at runtime while populated collections still bind normally.
conformance/tests/metadata.rs	Covers round-trip metadata for value names, counted flags, and required collecting arguments.
benches/shadows/mise/src/lib.rs	Regenerates the mise shadow with the newly supported metadata attributes.

_{Reviews (5): Last reviewed commit: "fix(derive): enforce what the metadata p..." | 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/model.rs`:
- Around line 775-776: Update the metadata parsing logic surrounding the
"value_name" match arm in the derive implementation to reject value_name unless
the argument is a value-taking flag, excluding positional arguments and
valueless bool/count flags. Return an appropriate validation error instead of
accepting and dropping unsupported metadata, while preserving the existing
assignment for valid flags.

In `@xtask/src/shadow.rs`:
- Around line 579-592: Update the flag-option generation path around the
existing var and value_name handling to emit required for value-taking
collecting flags when flag.required is true, so generated repeatable or variadic
values remain mandatory and render as <VALUE>… rather than [VALUE]…. Preserve
the existing valueless-flag required handling, and add a generator regression
test covering a required repeatable/variadic value flag.

🪄 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: 14b0088d-027c-458a-98cf-724d4de13012

📥 Commits

Reviewing files that changed from the base of the PR and between ebea895 and b286dc6.

📒 Files selected for processing (6)

• PLAN.md
• benches/shadows/mise/src/lib.rs
• conformance/tests/metadata.rs
• derive/src/codegen.rs
• derive/src/model.rs
• xtask/src/shadow.rs

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▁▁▂▂▂██	175,245,063 → 175,128,082	-0.07%	16.93 → 17.91ms	+5.74%
startup	▁▁▁▁▁▁▁▁██	1,222,129 → 1,222,033	-0.01%	1.00 → 1.05ms	+5.26%

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	29823	5962046	199x

usage: argv -> struct                             872 ns      0.87 µs
clap: build tree + parse -> struct             511231 ns    511.23 µs
clap: parse -> struct, tree reused              23681 ns     23.68 µs
clap: build tree only                          314532 ns    314.53 µs

_{93b378f7fae8 vs fe13b0b9c7d8 · measured on the runner, not pushed to the history.}

[jdx]

Three findings, all real and all the same shape — a declaration written down, emitted into the spec, and then not honoured.

required on a collection was documentation only (Bugbot, Greptile). The required check looked at the field's shape, and a Vec has the same shape whether or not it declared required — so the spec, the help, the manpage and the completions all said one-or-more while the CLI that ran accepted none. It now uses the same expression the metadata is built from:

if !(f.shape == Shape::Required || f.required_collection) || f.default.is_some() {

That is deliberately the identical expression to the one at the two *_meta sites: one expression cannot disagree with itself.

value_name was accepted where nothing could show it (Greptile, CodeRabbit — same finding). It names the placeholder a flag's value gets in help; arg_meta never emits it and a bool/count flag has no placeholder, so on a positional or a valueless flag the declaration compiled and was dropped. Refused now, with a message that says what to use instead — name for a positional.

The shadow generator dropped required from a collecting flag (CodeRabbit). A scalar flag says required by type — String rather than Option<String> — and a Vec has no such spelling, so required is the only way to say it. Without emitting it, a spec demanding one-or-more values became a shadow accepting none, whose regenerated spec read [VALUE]… where the source said …. Note this one depends on the first fix: emitting required there is only honest now that the derive enforces it, which is why they belong in the same commit.

Each has a test in the layer that owns the behaviour — parse-time in the conformance suite, attribute validation in the model's own tests, generator output in the shadow's — and each test is checked against a reverted fix.

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

[jdx]

Both real, and both the same thing as the first round: a declaration that compiles and cannot mean what it says. Refused now, beside the value_name check.

required beside required_if/required_unless. required on a collection means one or more values always, and the check for it runs unconditionally — so a sibling condition was accepted, emitted into the spec, and never consulted. For a scalar the two cannot meet: required_unless needs somewhere to put "absent" and so only goes on an Option. A collection has no type to keep them apart, so validation does.

required on an Option<Vec<_>>. Shaped like any other collection, so it was accepted — after which the field can never be None and the Option means nothing at all.

`required` on a collection means one or more values, always, but
`required_if` says it is required only sometimes

Three cases tested, three mutations, and a fourth assertion that a plain #[usage(long, required)] Vec<String> still compiles — which is the thing the refusals are protecting.

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

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

[jdx]

Fixed. A line continuation had lost its backslash, so the one message that tells an author what a field accepts had a long run of spaces through the middle of it. The test asserts the absence of a double space rather than the exact list, so it stays true as options are added.

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

[jdx]

All addressed, though two of them twice over — another session was fixing the same findings in parallel, and reconciling the two is most of what this took.

Required collection not enforced (High) — real, and fixed: required_checks now keys off the same expression the metadata is built from (shape == Required || required_collection), so the spec and the parser cannot disagree about it. One expression cannot contradict itself.

Required ignores conditional exceptions / Required allowed on Option<Vec> (Medium ×2) — both real. required on a collection means one or more values always, so it contradicts required_if, required_unless, and Option<Vec<_>> — each of which says absence is representable. All three refused at the declaration now.

value_name silently discarded and required not preserved for collecting flags in the generator — both fixed, with a generator regression test for the second.

Malformed unknown-option error text (Low) — the run of spaces was a stray line continuation, already gone.

One thing worth recording: the parallel fixes collided. Both sessions added a guard refusing the self-contradicting required; mine ran first and its wording did not match the test the other had written, and the reconciliation then dropped the other rule — refusing required where the type already answers — while keeping its variables. clippy caught the orphans (assigned but never used), and the test caught the missing rule. Both are back, and the duplicate guard is gone.

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