feat(argv,derive): add compiled clause support

[jdx]

Summary

• add clause tables and boundary events to the zero-allocation argv parser
• support typed Vec clause fields through usage derive
• add equivalent Go parser, spec-lowering, and generated-table support
• extend the shared corpus so interpreted Rust, compiled Rust, and Go agree
• report clause addition, removal, and separator changes as breaking in usage diff

Stack

• Depends on feat(spec,parse): add repeatable clause groups #1321

Test plan

• mise run test
• mise run lint
• mise run render
• mise run gen-shadow
• cd go && go test ./...

AI-assisted — Tool: Codex; model: OpenAI/GPT-5; version: unavailable.

---

Note

Medium Risk
Touches core positional parsing, derive codegen, and Go-generated binders; mistakes could mis-split repeated positionals or break compatibility detection, though coverage is broad.

Overview
Adds repeatable clause parsing: a command can own one separator-delimited positional group (e.g. :::) whose inner arguments reset on each boundary instead of overwriting the previous instance.

The Rust argv parser gains Command::clause, Event::ClauseSeparator, and positional routing through clause args; separators stay syntax after double_dash="automatic" unless protected by --. Help, completions, and KDL emission treat clause positionals like ordinary args for listings and usage (including the repeatable [separator …]… pattern).

usage derive supports #[usage(clause, separator = "…")] on Vec<T> (T: Args) with partial state, separator handling in apply, and per-instance build. Go mirrors the same behavior in argv, help, spec lowering, and generated Parse (per-instance validation and []Clause fields). Conformance and a new corpus section assert matching clauses maps across interpreted Rust, compiled Rust, and Go.

usage diff flags adding, removing, or changing a clause separator as breaking.

^{Reviewed by Cursor Bugbot for commit 8b8f0ff. 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: 091cb5ec-7fdb-4abc-8ead-d8db685d2e5d

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	▁█	341,631,291 → 341,678,724	+0.01%	31.73 → 28.91ms	-8.89%
startup	█▁	910,819 → 908,110	-0.30%	0.98 → 0.89ms	-9.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.

framework	stripped binary, bytes
usage	1340672
bpaf	2493280
clap	3101832

framework	instructions, cold parse	vs usage
usage	8523	—
clap	6315248	740x
bpaf	21909169	2570x

                                              min       p01       p10    median
usage-rs: argv -> struct                      428       431       434       446  ns
clap: build tree + parse -> struct         514148    515132    518519    525164  ns
bpaf: build parser + parse -> struct      1590042   1590042   1596910   1608187  ns

usage: argv -> struct                             435 ns      0.44 µs
clap: build tree + parse -> struct             532922 ns    532.92 µs
clap: parse -> struct, tree reused              24004 ns     24.00 µs
clap: build tree only                          325144 ns    325.14 µs

_{8b8f0ff4ffeb vs 7db6c6c30649 · measured on the runner, not pushed to the history.}

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