fix(argv): inherit unknown_flags, which reached one command out of a tree

[jdx]

Stacked on #937 (and so on #923) — review those first; this PR's diff is the last commit. The second of the two gaps #936 found by converting usage-cli itself to the derive.

usage-lib resolves this by walking outward from the command that ran and falling back to the spec's own setting — effective_unknown_flags in lib/src/parse.rs. usage-argv held the effective value per command instead, on the theory that whoever built the tables would resolve it.

A derive cannot. It expands one struct at a time and cannot see the command above, so #[usage(unknown_flags = "error")] reached the root alone — and on an Args it was parsed and then ignored, a declaration that compiled and did nothing. A CLI could not make a subcommand strict, or a single command lenient, whatever it wrote.

#[usage(bin = "usage", unknown_flags = "error")]  // now reaches the whole tree
struct Cli { … }

#[usage(unknown_flags = "value")]                 // now means something on an Args
struct Bash { … }                                 // `usage bash x.sh --script-flag`

Without it, usage lint --nope f.kdl offers --nope to the positional, so the file becomes --nope and the real file is the unexpected word — where clap named the flag.

Shape

Command::unknown_flags is an Option now: None means inherit. The parser carries the effective value down as it descends rather than reading it off the command in scope — one branch on descent, and a field read instead of a pointer chase on the two sites that ask.

The KDL writer follows: a command that states nothing writes nothing, one that restates what it inherited writes nothing, and one that differs says so. Same output as before for every spec that already round-tripped.

The corpus's table builder stops resolving inheritance on the way in, which is the part worth noticing: conformance/src/argv.rs had its own correct implementation of the rule, and that is exactly why no vector ever caught the parser not having one. One implementation now, in the parser, where the reference has it.

Cost

160 instructions per parse — 72,272 against 72,112 at mise's scale, measured twice against the parent branch on one machine. cachegrind is deterministic; both figures repeated.

Verification

• conformance/tests/unknown_flags_inherit.rs — five tests: a subcommand inherits the root's answer, it reaches two levels down, a command that declares its own keeps it, the emitted spec says what the parser does, and usage-lib reads the emitted spec the same way, which is the claim that matters.
• a_subcommand_writes_unknown_flags_only_where_it_differs gains a command that declares nothing at all, which is the case the Option adds.
• Workspace suite green, clippy clean, corpus green.

This PR was generated by Claude Code.

---

Note

Medium Risk
Changes core argv binding for unrecognized flags across the whole CLI tree; behavior fixes are intentional but affect every parse path that relied on the old pre-resolved tables.

Overview
unknown_flags now inherits down the command tree instead of being baked into each command table. Command::unknown_flags is Option<UnknownFlags> (None = inherit); the parser keeps an effective mode on descent and only updates it when a subcommand sets one.

The derive emits None for commands that do not declare the attribute (fixing root-only error and ignored #[usage(unknown_flags)] on Args). KDL emission and the conformance table builder stop flattening inheritance on build—only the parser applies the rule, matching usage-lib’s outward walk.

New conformance/tests/unknown_flags_inherit.rs covers inheritance depth, per-command value, spec round-trip, and usage-lib parity on emitted KDL.

^{Reviewed by Cursor Bugbot for commit 2ff6307. 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: 9babe7c7-c348-4993-bf21-3f9ce6eb4aba

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

[greptile-apps]

Greptile Summary

The PR moves unknown_flags inheritance into the compiled argv parser so root policies flow through command trees while explicit child policies override them.

• Represents an unstated command policy as None and carries the effective policy during parser descent.
• Updates derive output and the conformance adapter to preserve unresolved inheritance.
• Updates KDL emission to serialize policies only where their effective value changes.
• Adds nested inheritance, override, and usage-lib parity coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
argv/src/lib.rs	Changes command policy storage to an optional declaration and consistently updates the effective parser policy during monotonic subcommand descent.
argv/src/spec.rs	Preserves effective unknown-flag semantics in generated KDL while omitting redundant inherited declarations.
derive/src/codegen.rs	Emits explicit optional policies for both root and Args-derived command tables, allowing silent child commands to inherit.
conformance/src/argv.rs	Stops pre-resolving descendant policies so the conformance adapter exercises parser-owned inheritance.
conformance/tests/unknown_flags_inherit.rs	Covers root inheritance, deep descent, child overrides, emitted-spec shape, and usage-lib parity.

_{Reviews (5): Last reviewed commit: "fix(argv): inherit `unknown_flags`, whic..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁████████	180,301,068 → 180,365,943	+0.04%	17.50 → 16.53ms	-5.57%
startup	▁▆▂▂▅█▆██	1,226,319 → 1,226,125	-0.02%	1.00 → 0.96ms	-3.79%

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	60604	5893640	97x

usage: argv -> struct                            1030 ns      1.03 µs
clap: build tree + parse -> struct             496703 ns    496.70 µs
clap: parse -> struct, tree reused              23070 ns     23.07 µs
clap: build tree only                          312822 ns    312.82 µs

_{2ff6307581d6 vs 02e459bc675b · measured on the runner, not pushed to the history.}