feat(derive): add typed command finalization

[jdx]

Summary

• add #[usage(validate_with = path)] for command-wide invariants after typed field conversion and env/default resolution
• add #[usage(try_into = DomainType)] with parse_into* entry points that finalize directly through TryFrom
• expose an ergonomic ValidationError builder and route validation/finalization failures through the existing Error::InvalidValue diagnostic
• validate nested Args as well as root commands and preserve the normal process behavior for help, warnings, and failures

This removes adapter glue for applications that parse into a declaration type but operate on a stricter domain command, while keeping every existing parse_* entry point source-compatible.

Example

#[derive(usage::Cli)]
#[usage(
    bin = "copy",
    validate_with = validate_copy,
    try_into = CopyCommand
)]
struct CopyArgs {
    #[usage(long)]
    source: PathBuf,
    #[usage(long)]
    destination: PathBuf,
}

fn validate_copy(args: &CopyArgs) -> Result<(), usage::ValidationError> {
    if args.source == args.destination {
        return Err(usage::ValidationError::field("--destination")
            .value(args.destination.display().to_string())
            .reason("must differ from --source"));
    }
    Ok(())
}

let command: CopyCommand = CopyArgs::parse_into();

Validation

• mise run ci
• focused conformance tests cover cross-field validation, nested Args, returning-error finalization, full argv handling, and finalization failures

AI-assisted — Tool: Codex; model: unavailable; version: unavailable.

---

Note

Medium Risk
Touches derive-generated parse and update entry points, including transactional clone-then-commit updates. Existing parse APIs stay compatible, but generated signatures and Clone bounds change when validation is enabled.

Overview
Adds command-wide validation and typed finalization on the root #[derive(Cli)] type so apps can check fully typed fields and convert into a domain type without a second error path.

#[usage(validate_with = ...)] runs after field conversion on parse (including settings and views). Failures become Error::InvalidValue via a new ValidationError builder. Updates clone, validate the candidate, and commit only on success, so a failed try_update_from leaves the standing value; those methods gain a Clone bound when validation is present. Nested Args cannot declare these attributes.

#[usage(try_into = DomainType)] generates parse_into* / parse_into() APIs that TryFrom the parser type and map ValidationError the same way. Existing parse_* methods remain. Docs and conformance tests cover both hooks.

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

[coderabbitai]

Warning

Review limit reached

@jdx, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 2 minutes

Limit details: You’ve used all 4 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 0aea1603-d20a-40d1-b8fb-9e793d1b1d97

📥 Commits

Reviewing files that changed from the base of the PR and between aa6aeaf and c5b784d.

📒 Files selected for processing (5)

• argv/src/lib.rs
• conformance/tests/finalize.rs
• derive/src/codegen.rs
• derive/src/model.rs
• docs/rust/validation.md

---

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 09a3cf0. Configure here.}