feat(derive): support clap implicit groups

[jdx]

Summary

• accept clap's struct-level #[group(...)] helper attribute
• place direct Args fields into the derived implicit group
• preserve clap's default multiple(true) and explicit required/multiple/skip settings

Verification

• cargo test -p usage-rs --test facade clap_implicit_groups_apply_to_the_args_struct_fields
• cargo clippy -p usage-derive --all-targets --all-features -- -D warnings

This pull request was generated by Codex.

---

Note

Medium Risk
Touches derive parsing and how required flags/groups are encoded in generated parsers and specs. Wrong mapping would change CLI validation and portable KDL, but behavior is covered by facade tests.

Overview
Adds clap-compatible struct-level #[group(...)] on Cli/Args derives so an Args struct’s direct flags and positionals form an implicit group (clap defaults: multiple(true), optional required/id/skip).

Membership is joined from both field group = "..." and implicit group member lists. One-member required implicit groups do not emit a spec group; they lower onto the field as ordinary requiredness (metadata, help, and runtime MissingRequired). Multi-member implicit groups that only restated clap’s default multiple without required are omitted from emitted group metadata.

^{Reviewed by Cursor Bugbot for commit bc00e65. 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: 0db5db98-51d1-459c-a05b-649b8cc8a984

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	▄▁█	199,368,396 → 219,462,294	+10.08% ⚠️	18.76 → 22.52ms	+20.03%
startup	▁██	1,221,718 → 1,221,447	-0.02%	1.30 → 1.58ms	+21.90%

1 benchmark(s) above the 1% gate: markdown +10.08%

_{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	instructions, cold parse	vs usage
usage	4355	—
argh	6292	1.4x
clap	5893640	1353x
bpaf	21917948	5032x

                                              min       p01       p10    median
usage-rs: argv -> struct                      194       198       201       207  ns
argh: argv -> struct                          283       288       294       306  ns
clap: build tree + parse -> struct         486625    487560    491640    504963  ns
bpaf: build parser + parse -> struct      1649776   1649776   1662952   1681108  ns

usage: argv -> struct                             199 ns      0.20 µs
clap: build tree + parse -> struct             504869 ns    504.87 µs
clap: parse -> struct, tree reused              22969 ns     22.97 µs
clap: build tree only                          309420 ns    309.42 µs

_{203b9d56bbc3 vs e5c8eb0982a6 · measured on the runner, not pushed to the history.}

[jdx]

Addressed both new implicit-group findings in this PR:

• a direct field now remains a member of clap’s implicit Args group even when it also names an explicit group;
• repeated #[group(...)] attributes apply cumulatively, so splitting id/required and multiple/skip does not reset earlier settings.

The facade regression covers split attributes, dual membership, requiredness, and exclusivity.

This comment was generated by Codex.