feat(derive): declare which flags conflict and which require each other

[jdx]

Stacked on #819, which taught the spec conflicts. This teaches the derive to declare it, along with the other two relationships that need only whether a flag was given: required_if and required_unless.

#[derive(usage::Cli)]
struct Rel {
    /// Read from a file
    #[usage(long, required_unless("--url", "--stdin"))]
    file: Option<String>,
    /// Read from standard input
    #[usage(short = 's', long, conflicts("--file", "--url"))]
    stdin: bool,
    /// Where to write
    #[usage(long, required_if = "--stdin")]
    out: Option<String>,
}

Each takes a flag the way the spec names one — "--long" or "-s" — with one as a value and several as a list. They reach FlagMeta, so the emitted KDL says what the struct says and usage g markdown and the completions can mention them.

Worth a look

• A selector naming no flag is a compile error, and so is one naming its own field. This is the concrete advantage of declaring relationships in code rather than in KDL: a typo'd selector in a hand-written spec is a relationship that quietly does not hold, and nothing ever tells you. Unit-tested through Cli::from_input, including resolution by long, short, and negation spelling.
• Env counts on both sides. The checks read __given_* after the environment fallback, so a value from the environment is as good as a typed one — matching clap (verified directly, including env-on-both-sides) and feat(spec): add conflicts to flags #819's usage-lib behaviour. An asymmetric rule would make the same pair a conflict or not depending on which side happened to be typed.
• Conflicts are reported before required-ness, matching usage-lib: when a conflict has also left something unfilled, "you gave two flags that cannot go together" beats "give me one more flag". There's a test for that ordering.
• overrides is deliberately not here. It is the one relationship that asks which flag came last rather than whether both arrived, and nothing records arrival order yet — so it gets its own PR rather than a half-answer in this one.
• The derive docs had a duplicated "Typed values" bullet and still claimed env was unread and required-ness unreported, both of which stopped being true a few PRs ago. Corrected.

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

---

Note

Medium Risk
Adds new post-binding constraint enforcement that changes which command lines parse successfully, but the checks are well-tested and do not touch auth or data handling.

Overview
Teaches the derive to declare flag relationships that only need whether a flag was given: conflicts, required_if, and required_unless.

#[usage(long, conflicts("--file", "--url"))]
stdin: bool,
#[usage(long, required_if = "--stdin")]
out: Option<String>,

Selectors use the spec's spelling ("--long" / "-s"), resolve at compile time (unknown or self-referential names are errors), and flow into FlagMeta so emitted KDL, docs, and completions see them. Post-binding checks enforce them after env fallback — env counts on both sides — and report conflicts before missing-required errors. overrides is deliberately deferred; it needs arrival order.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 3125d2d4-6d74-4d21-8aa6-f808616c55c1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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	▁▁▁▁▁▁▁█████████	148,242,482 → 148,254,286	+0.01%	13.93 → 14.09ms	+1.15%
startup	▄▄▄▄▄▄▄█████▁▁▁▅	1,199,527 → 1,201,983	+0.20%	0.95 → 0.94ms	-0.78%

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

_{b3d833d4f296 vs 7047ae1232b2 · measured on the runner, not pushed to the history.}

[greptile-apps]

Greptile Summary

The PR adds derive support for declaring, validating, enforcing, and serializing conflicts, required_if, and required_unless relationships.

• Resolves relationship selectors against long, short, and negated flag spellings at compile time.
• Runs conflict and conditional-required checks after environment fallback.
• Emits the relationships through FlagMeta into canonical KDL.
• Rejects positional declarations, self-references, unknown selectors, and empty relationship lists.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/model.rs	Parses and validates relationship attributes, including complete fixes for the two previously reported declaration-validation issues.
derive/src/codegen.rs	Emits relationship metadata and adds post-binding conflict and conditional-required validation.
argv/src/spec.rs	Extends flag metadata and KDL serialization with conflicts and conditional-required relationships.
argv/src/lib.rs	Adds the structured conflicting-flags runtime error.
conformance/tests/post_binding.rs	Covers runtime enforcement, error ordering, defaults, and conditional requiredness.
conformance/tests/derive.rs	Verifies that derive-declared relationships survive into the emitted specification.

_{Reviews (3): Last reviewed commit: "fix(derive): keep a relationship from cl..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a1ab330. Configure here.}

[jdx]

Four findings, all valid, all fixed. Two of them were the same underlying mistake seen from different angles.

Relationships on positionals (greptile P1, bugbot) — a positional could declare conflicts/required_if/required_unless, the check was generated, and ArgMeta had nowhere to record it. So the binary enforced something its own spec, docs and completions could not describe. SpecArg has no such fields either, so per the canonicality rule the derive refuses it rather than the spec growing them speculatively — the same treatment count and negate already get.

required_unless on a bare String (bugbot) — accepted and unreachable: the shape-based required check runs first and knows nothing about the condition, so the declared exception could never take effect. It needs somewhere to put "absent", which means an Option. Refused with that message.

default plus a condition (bugbot) — a defaulted field was reported missing by required_if/required_unless, because applying a default does not set __given_*. Plain required-ness has always skipped defaulted fields and usage-lib does too; the relationship checks now match. Runtime test added, and I mutation-checked it.

Empty conflicts() (greptile P2) — compiled into no relationship at all. Rejected, as choices() already was.

Each has a unit test asserting the message, since a compile error nobody can read is not much better than a silent one.

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