feat(derive): check what a parse cannot decide on its own

[jdx]

Second of the stack (#816 merged while this was in flight, so it targets main). The parser binds tokens and stops there, which left required-ness, choices, variadic bounds, and env fallback unimplemented — the 18 corpus vectors the harness reports as post-binding, and the reason a subcommand field had to be Option<T>.

Order matters, so it is stated

1. The environment fills what argv left out.
2. Required-ness — which the type declares: a String has nowhere to put "absent". After the environment, so a flag with env set is not reported missing.
3. choices and bounds, which judge a value however it arrived, including from the environment or a default.

Only the command that actually ran is judged. A flag that install requires says nothing about an invocation of run — which is why the check hangs off the CommandArgs trait and the enum forwards it to the selected variant only. A bare subcommand field now means one is required and says so when absent, removing #816's stated limit.

Two decisions worth arguing with

A field remembers whether a token supplied it, rather than inferring that from an empty value. --out= is a value somebody typed, and treating "" as unset would make it unsayable — the same distinction #810 fixed in the parser, carried through to the checks.

Bounds constrain the values a field was given. An unused optional flag is absent, not a violation. Otherwise var_min = 1 becomes a second spelling of required-ness, and there is no way left to say "at least two, if you use it at all". My own test caught this: I put var_min = 1 on an optional flag and every unrelated test in the file started failing with VarTooFew.

Contradictions are compile errors

error: a `bool` or counting field has no value to check against `choices`
error: `var_min = 3` is more than `var_max = 2`, so nothing could satisfy both
error: `var_min` and `var_max` count values, so the field has to be a `Vec`
error: the default `z` is not one of this field's choices, so it could never be valid

Consistent with the rest of this crate: the derive's job is refusing what cannot round-trip or cannot mean anything.

The declarations reach the spec

A test pins that, because a choice list the parser enforces but the spec omits would be invisible to docs and completions — exactly the kind of half-implemented feature this project keeps turning up.

10 tests: each check, the empty-value case, per-command judging, and a required subcommand.

Still missing, and now stated in the crate docs

overrides and required_unless (both need the order flags arrived in, which nothing records yet), nesting past one level, and typed values.

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

---

Note

Medium Risk
Touches public Error and trait APIs and adds substantial generated validation/env logic that changes how CLIs accept or reject input. Well-tested, but incorrect checks would mis-parse real command lines.

Overview
Implements the post-binding layer the parser deliberately left out: after tokens are bound, generated code now checks required-ness, choices, var_min/var_max, and fills from env when argv left a field unset.

Validation order is fixed: env fallback → required checks → choices/bounds. Only the selected subcommand is judged. A bare subcommand: T field is now allowed and reports MissingSubcommand when absent (previously had to be Option<T>).

Extends Error with MissingRequired, InvalidChoice, VarTooFew, VarTooMany, and MissingSubcommand, and marks it non_exhaustive. Adds check to CommandArgs/Subcommands. Declarations also flow into the emitted spec so docs and completions see the same constraints.

Contradictions (choices on bool, var_min > var_max, default outside choices) are compile errors. New conformance tests cover each check, empty values counting as given, and env precedence.

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

Summary by CodeRabbit

• New Features

  • Added post-parse validation for required values, allowed choices, variable-length arguments, and required subcommands.
  • Added environment-value fallback and clear precedence when command-line values are provided.
  • Added support for validating only the selected subcommand.
  • Expanded generated command specifications with choices and argument bounds.

• Bug Fixes

  • Improved handling of boolean environment values and invalid defaults.

• Documentation

  • Documented validation order, scope, supported constraints, and current limitations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The parser now performs post-binding validation for required values, choices, variadic bounds, environment fallback, and required subcommands. Public traits expose validation hooks, derive metadata records constraints, generated code validates selected commands, and conformance tests cover the behavior.

Changes

Post-Binding Validation

Layer / File(s)	Summary
Public validation contracts argv/src/lib.rs, argv/src/spec.rs	Error includes deferred validation variants. CommandArgs::check and Subcommands::check expose post-binding validation.
Validation metadata and subcommand model derive/src/model.rs, derive/src/lib.rs	Field metadata stores choices and variadic bounds. The derive model validates declarations and supports required or optional subcommands. Documentation describes validation order and limitations.
Generated post-binding flow derive/src/codegen.rs	Generated parsers track supplied fields, apply environment fallback, validate constraints, dispatch checks to the selected subcommand, and build parsed values.
Conformance validation coverage conformance/src/argv.rs, conformance/tests/post_binding.rs	Tests cover required values, choices, variadic bounds, environment precedence, boolean parsing, subcommand validation scope, and generated specifications.

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

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant GeneratedParser
  participant Environment
  participant SelectedCommand
  participant ParsedValue
  CLI->>GeneratedParser: supply arguments
  GeneratedParser->>Environment: resolve unset fields
  GeneratedParser->>SelectedCommand: validate selected command
  SelectedCommand-->>GeneratedParser: return success or Error
  GeneratedParser-->>ParsedValue: build validated value

Loading

Possibly related PRs

• jdx/usage#797: Adds the conformance harness and validation behavior extended by this change.
• jdx/usage#798: Provides the parser infrastructure extended with post-binding validation.
• jdx/usage#816: Adds subcommand parsing integrated with the new validation flow.

Poem

A rabbit checks each flag in line,
With choices neat and bounds that shine.
Env values hop where fields are bare,
The chosen command gets its share.
“No missing carrots!” says the hare.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 summarizes the main change: adding derive-time post-parse checks for conditions the parser cannot decide during binding.

---

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 derive-generated post-binding validation after argv parsing.

• Applies environment fallback before required-value checks.
• Validates choices and variadic bounds for supplied values.
• Supports required subcommands and checks only the selected command.
• Exposes post-binding failures through new argv error variants and generated spec metadata.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/codegen.rs	Generates environment fallback, required-value, choice, variadic-bound, and selected-subcommand checks; the previously reported count-environment defect is corrected.
derive/src/model.rs	Parses and validates choices and variadic bounds while adding required-subcommand modeling.
argv/src/spec.rs	Adds post-binding check hooks to the command and subcommand traits.
argv/src/lib.rs	Adds non-exhaustive post-binding error variants.
conformance/tests/post_binding.rs	Covers required values, choices, bounds, selected-command validation, required subcommands, and emitted metadata.
conformance/tests/post_binding_env.rs	Covers environment fallback, argv precedence, boolean values, and count parsing.

_{Reviews (2): Last reviewed commit: "fix(derive): stop claiming a count came ..." | Re-trigger Greptile}

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (4)

conformance/tests/post_binding.rs (2)

74-98: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

No test exercises VarTooFew.

include declares var_min = 1, but the minimum can never be violated on this fixture. bound_checks runs only when __given_include is true, and every --include occurrence pushes exactly one value. The count is therefore at least 1 whenever the check runs.

The min branch of bound_checks in derive/src/codegen.rs is currently untested. Add a field with var_min = 2 and give it one value.

💚 Proposed test addition

/// Files to pair
#[usage(long, var = true, var_min = 2)]
pair: Vec<String>,

#[test]
fn too_few_values_is_refused() {
    let a = argv(["--pair", "a", "x"]);
    assert!(matches!(
        Ex::parse_from(&a),
        Err(Error::VarTooFew {
            name: "pair",
            min: 2,
            got: 1
        })
    ));
}

🤖 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/post_binding.rs` around lines 74 - 98, Extend the test
fixture with a repeatable pair field configured with var_min = 2, then add a
too_few_values_is_refused test passing one value and asserting Error::VarTooFew
with name "pair", min 2, and got 1. Keep the existing include tests unchanged.

---

162-205: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a case for an optional subcommand field.

These tests cover the required subcommand path only. derive/src/codegen.rs at lines 126-139 branches on optional, and the Option<T> branch has no test here. That branch must produce None when no command is given, and it must still run check on a command that was given.

💚 Proposed test addition

/// A CLI whose subcommand may be left out
#[derive(Cli)]
#[usage(bin = "opt")]
struct Opt {
    /// What to do, if anything
    #[usage(subcommand)]
    command: Option<Commands>,
}

#[test]
fn an_optional_subcommand_may_be_left_out() {
    let a = argv([]);
    assert!(Opt::parse_from(&a).expect("should parse").command.is_none());

    // A command that was given is still judged.
    let a = argv(["install"]);
    assert!(matches!(
        Opt::parse_from(&a),
        Err(Error::MissingRequired { name: "tool" })
    ));
}

Commands wraps Install and Noop, and the model rejects two variants sharing one struct. Reuse Commands rather than declaring a second enum over the same structs.

🤖 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/post_binding.rs` around lines 162 - 205, Add a test near
the existing subcommand tests defining an optional-subcommand CLI type, such as
Opt with command: Option<Commands>. Verify parsing no arguments succeeds with
command set to None, and parsing ["install"] still returns
Error::MissingRequired for tool, confirming validation runs for provided
commands while omission is allowed. Reuse the existing Commands enum.

derive/src/codegen.rs (2)

1000-1009: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

A count field with env set is marked as given without receiving a value.

For Shape::Count the assignment is let _ = value;, but the surrounding block still runs partial.#given = true;. The field keeps its zero value while __given_* claims a value arrived.

Nothing reads that marker for a count field today: required_checks only covers Shape::Required, and the model rejects choices and bounds on counting fields. The state is still contradictory, and a later check that consults __given_* would read it wrong.

Consider skipping the field entirely instead of emitting a no-op assignment.

♻️ Proposed change

             // A count from the environment would be a number, not an occurrence
             // count; nothing needs it yet.
-            Shape::Count => quote!(let _ = value;),
+            Shape::Count => return None,
         };

🤖 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/codegen.rs` around lines 1000 - 1009, Update the
environment-variable assignment logic in the Shape::Count branch so count fields
are skipped entirely when env is configured, rather than executing the shared
partial.#given update. Preserve the existing behavior for other shapes, and
ensure count fields do not emit a no-op assignment or mark their given-state
flag.

---

769-780: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding unused_lifetimes to the generated module's allow list.

check declares 't and 'v, but the body uses neither, and only 't appears in the return type. The generated module inherits the deriving crate's lint configuration. A crate with #![deny(unused_lifetimes)] would then fail to compile on a derive it did not write.

The other generated-module allow lists in this file already cover non_snake_case and unused_imports for the same reason.

♻️ Proposed change

         #[allow(
             non_upper_case_globals,
             non_snake_case,
             unused_imports,
+            unused_lifetimes,
             // Fires when a metadata struct happens to be fully specified. `..EMPTY`
             // is kept on purpose: it is what lets usage-argv gain a metadata field
             // without breaking every crate that derives.
             clippy::needless_update
         )]

🤖 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/codegen.rs` around lines 769 - 780, Add unused_lifetimes to the
generated module’s lint allow list so the generated check method’s unused
generic lifetimes do not fail downstream crates configured with
deny(unused_lifetimes). Update the existing generated-module allow attributes
near the check method generation, preserving the current non_snake_case and
unused_imports allowances.

🤖 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 `@argv/src/lib.rs`:
- Around line 288-319: Preserve 5.x compatibility across
argv/src/lib.rs:288-319, argv/src/spec.rs:775-781, and argv/src/spec.rs:804-808,
or explicitly release these changes as 6.0.0. For compatibility, avoid adding
breaking Error variants such as MissingRequired, InvalidChoice, VarTooFew,
VarTooMany, and MissingSubcommand, and give CommandArgs::check and
Subcommands::check default Ok(()) implementations so existing manual
implementations remain valid; generated implementations should continue
providing both checks.

In `@conformance/tests/post_binding.rs`:
- Around line 100-125: Move the_environment_fills_what_argv_left_out into a
separate integration test file containing no other tests that parse a struct
with env bindings, so its set_var/remove_var calls cannot race with sibling
tests. Keep the existing environment assertions and cleanup intact, and add the
required // SAFETY: comments for each unsafe environment mutation.

---

Nitpick comments:
In `@conformance/tests/post_binding.rs`:
- Around line 74-98: Extend the test fixture with a repeatable pair field
configured with var_min = 2, then add a too_few_values_is_refused test passing
one value and asserting Error::VarTooFew with name "pair", min 2, and got 1.
Keep the existing include tests unchanged.
- Around line 162-205: Add a test near the existing subcommand tests defining an
optional-subcommand CLI type, such as Opt with command: Option<Commands>. Verify
parsing no arguments succeeds with command set to None, and parsing ["install"]
still returns Error::MissingRequired for tool, confirming validation runs for
provided commands while omission is allowed. Reuse the existing Commands enum.

In `@derive/src/codegen.rs`:
- Around line 1000-1009: Update the environment-variable assignment logic in the
Shape::Count branch so count fields are skipped entirely when env is configured,
rather than executing the shared partial.#given update. Preserve the existing
behavior for other shapes, and ensure count fields do not emit a no-op
assignment or mark their given-state flag.
- Around line 769-780: Add unused_lifetimes to the generated module’s lint allow
list so the generated check method’s unused generic lifetimes do not fail
downstream crates configured with deny(unused_lifetimes). Update the existing
generated-module allow attributes near the check method generation, preserving
the current non_snake_case and unused_imports allowances.

🪄 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: 75aabba8-962e-4526-a20d-b5b70ad4f1e6

📥 Commits

Reviewing files that changed from the base of the PR and between ac75068 and d642010.

📒 Files selected for processing (7)

• argv/src/lib.rs
• argv/src/spec.rs
• conformance/src/argv.rs
• conformance/tests/post_binding.rs
• derive/src/codegen.rs
• derive/src/lib.rs
• derive/src/model.rs

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect declared package versions and local manual trait implementations.
fd -a 'Cargo.toml' -x sh -c '
  printf "\n== %s ==\n" "$1"
  rg -n "^(name|version)\\s*=" "$1"
' sh {}

ast-grep outline . --items all --type impl --match 'CommandArgs|Subcommands'

rg -n -C 3 --glob '*.rs' \
  '\bimpl(?:<[^>]*>)?\s+(?:[^ \t]+::)?(?:CommandArgs|Subcommands)\b' .

Repository: jdx/usage

Length of output: 803

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== workspace and package metadata =='
sed -n '1,120p' Cargo.toml
sed -n '1,100p' argv/Cargo.toml

printf '%s\n' '== relevant trait definitions and implementations =='
rg -n -C 12 \
  'trait (CommandArgs|Subcommands)|impl[^\\n]*(CommandArgs|Subcommands)|fn check<' \
  argv/src '*.rs' 2>/dev/null || true

printf '%s\n' '== public Error definition =='
rg -n -C 8 'pub enum Error|MissingRequired|InvalidChoice|VarTooFew|VarTooMany|MissingSubcommand' argv/src

printf '%s\n' '== repository-wide manual implementations =='
rg -n -C 8 --glob '*.rs' \
  'impl(?:<[^>]*>)?\\s+(?:[^\\s]+::)?(?:CommandArgs|Subcommands)\\b' . || true

printf '%s\n' '== API and compatibility documentation =='
rg -n -C 3 --glob '*.md' --glob '*.toml' \
  'breaking|major release|semver|compatib|CommandArgs|Subcommands' . || true

Repository: jdx/usage

Length of output: 25343

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== spec module boundaries and check call sites =='
sed -n '1,80p' argv/src/spec.rs
rg -n -C 10 '::check\\(|\\.check\\(|CommandArgs::check|Subcommands::check|check\\(' \
  argv/src derive/src lib/src cli/src 2>/dev/null || true

printf '%s\n' '== derive implementation generation =='
fd -a -e rs . derive -x sh -c '
  if rg -q "CommandArgs|Subcommands|fn check|MissingRequired|InvalidChoice|VarTooFew|VarTooMany|MissingSubcommand" "$1"; then
    printf "\n== %s ==\n" "$1"
    rg -n -C 10 "CommandArgs|Subcommands|fn check|MissingRequired|InvalidChoice|VarTooFew|VarTooMany|MissingSubcommand" "$1"
  fi
' sh {}

printf '%s\n' '== read-only source invariant verifier =='
python3 - <<'PY'
from pathlib import Path
import re

lib = Path("argv/src/lib.rs").read_text()
spec = Path("argv/src/spec.rs").read_text()
derive = "\n".join(p.read_text() for p in Path("derive/src").rglob("*.rs"))

error = re.search(r"pub enum Error<'t, 'v>\s*\{(.*?)\n\}", lib, re.S)
assert error, "public Error enum not found"
body = error.group(1)
print("Error enum is public:", True)
print("Error enum is non_exhaustive:", bool(re.search(r"#\[non_exhaustive\]", lib[:error.start()])))
for variant in ("MissingRequired", "InvalidChoice", "VarTooFew", "VarTooMany", "MissingSubcommand"):
    print(f"Error::{variant} present:", bool(re.search(rf"\b{variant}\b", body)))

for trait_name, method in (("CommandArgs", "check"), ("Subcommands", "check")):
    m = re.search(rf"pub trait {trait_name}\s*:\s*Sized\s*\{{(.*?)\n\}}", spec, re.S)
    assert m, f"{trait_name} trait not found"
    trait_body = m.group(1)
    method_match = re.search(rf"\bfn {method}\b[^;{{]*(;|\{{)", trait_body)
    assert method_match, f"{trait_name}::{method} not found"
    print(f"{trait_name}::{method} has default body:",
          method_match.group(1) == "{")

print("derive source contains CommandArgs implementation:", "CommandArgs" in derive)
print("derive source contains Subcommands implementation:", "Subcommands" in derive)
PY

Repository: jdx/usage

Length of output: 28079

---

Preserve 5.x compatibility or release these APIs as 6.0.0.

• New Error variants break exhaustive downstream matches.
• Required CommandArgs::check and Subcommands::check methods break manual implementations. Add default Ok(()) bodies if 5.x compatibility is required.
• Generated implementations already provide both checks.

📍 Affects 2 files

• argv/src/lib.rs#L288-L319 (this comment)
• argv/src/spec.rs#L775-L781
• argv/src/spec.rs#L804-L808

🤖 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 `@argv/src/lib.rs` around lines 288 - 319, Preserve 5.x compatibility across
argv/src/lib.rs:288-319, argv/src/spec.rs:775-781, and argv/src/spec.rs:804-808,
or explicitly release these changes as 6.0.0. For compatibility, avoid adding
breaking Error variants such as MissingRequired, InvalidChoice, VarTooFew,
VarTooMany, and MissingSubcommand, and give CommandArgs::check and
Subcommands::check default Ok(()) implementations so existing manual
implementations remain valid; generated implementations should continue
providing both checks.

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▁▁▁▁▁████████	148,143,213 → 148,149,874	+0.00%	14.03 → 13.45ms	-4.14%
startup	▄▄▄▄▄▄▄▄█████▁▁▁	1,199,527 → 1,199,593	+0.01%	0.96 → 0.95ms	-1.03%

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

_{5bc52c746c9f vs ac75068b9a59 · measured on the runner, not pushed to the history.}

[jdx]

Four findings fixed, and two of them are about not breaking people.

A counting field with env discarded the value and marked the field filled anyway. It now reads a number — EX_VERBOSE=3 is how you say -vvv, since the environment cannot repeat a flag — and something unparseable leaves the field alone rather than counting as given. Both cases are pinned.

A required flag said so at run time but not in the spec, so docs and completions described a different CLI from the one that runs. Same rule an argument already followed. That is the second time this PR has caught a declaration enforced in one place and missing from the other, which is why the test asserting "the declarations reach the spec" earns its keep.

On semver, you were right to raise it. Error is now non_exhaustive — an error enum grows, and recognizing a new failure should never be a breaking change. This is the last time adding a variant breaks anyone, and it immediately proved itself by breaking the conformance harness's exhaustive match, which now has a wildcard. Both check methods default to Ok(()), so a hand-written implementation with nothing to check is not forced to say so.

The environment test race is the most interesting one. My comment claimed consolidating the cases into one #[test] handled it, and that was wrong in a way worth spelling out: it removed the race between those cases and not the race with their neighbours — including tests that read the environment only implicitly, by parsing a CLI that has an env field. Those tests would have been flaky depending on scheduling.

The fix is a separate test binary, since each integration test file is its own process. The file says so at the top, because the next person will be tempted to merge it back.

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