feat(argv): join static tables at compile time

[jdx]

#[usage(flatten)] needs a flattened struct's flags and arguments to appear in the parent's
own table, and the parent's macro expansion cannot see them — it has a type and nothing else.
CommandArgs::COMMAND is a const for exactly this reason, so a const fn can read through
it and produce one static array before the program runs.

table_len computes the length, which concat_flags and concat_args need as a const
generic and so cannot compute themselves. A wrong N fails to compile rather than leaving a
slot pointing at a placeholder that answers to nothing.

Groups keep the order they are given in, which is what lets a flattened group sit between
two of the parent's own declarations. That matters most for positionals, where the position
is the meaning: [FILE], SHARED, [REST] has to stay in that order or the wrong words bind.
Empty groups contribute nothing, so the derive can emit one group per field without checking
whether it is empty.

Two functions rather than one generic: each needs a value to fill an array with before
overwriting it, and a const fn has no way to ask a type parameter for one. MaybeUninit
would mean unsafe, and a Flag nobody can reach is cheaper than that.

What the parser walks is a single flat slice, indistinguishable from a command that declared
everything itself — so flatten will cost nothing at run time. A test parses through a
concatenated table to hold that.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

---

Note

Low Risk
Additive const APIs and tests only; the runtime parser is unchanged and flatten is not wired in yet.

Overview
Adds compile-time helpers so a parent command can merge its own flag/arg tables with flattened child types into one static slice before the program runs—supporting #[usage(flatten)] without changing the parser’s hot path.

table_len sums entry counts across grouped slices (needed as a const generic N for the concat functions). concat_flags and concat_args flatten &[&[&Flag]] / &[&[&Arg]] in declaration order, with a const assert! when N doesn’t match table_len (wrong size fails at compile time, not with silent placeholders). Under the spec feature, concat_flag_metas and concat_arg_metas do the same for help/metadata tables, kept in sync with parse order.

New tests lock in group order (including a flattened group between parent positionals), empty groups, and that a concatenated Command parses identically to a hand-declared one.

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

Why this exists

#[usage(flatten)] (#852, on top of this) needs a flattened struct's flags to appear in the
parent's own table — but the parent's macro expansion has only a type name. CommandArgs::COMMAND
is a const for this reason, and its doc already said so:

A const rather than a method, because a parent splices it into its own static tables and a
method call is not allowed there.

So a const fn can read through it and produce one static array before the program runs.
Verified against real derive output before any of this was written: ["force", "no-header"],
the parent's own flag plus the flattened struct's, resolved at compile time.

What the tests pin

• Order, including a group in the middle. [FILE], SHARED, [REST] stays in that order.
  This is the property positional arguments depend on — position is their identity, so a
  flattened group appended at the end would bind the wrong words.
• Empty groups contribute nothing, so the derive can emit one group per field without
  first checking whether it is empty.
• A concatenated table parses like a declared one — the whole point of doing it at compile
  time is that the parser cannot tell the difference.

Notes

• table_len is separate because N is a const generic and the concatenation cannot compute
  its own length. A wrong N fails to compile rather than leaving a slot pointing at a
  placeholder that answers to nothing.
• Two functions rather than one generic: each needs a value to fill the array with before
  overwriting it, and a const fn has no way to ask a type parameter for one. MaybeUninit
  would mean unsafe; an unreachable Flag is cheaper than that.
• The metadata versions live in spec alongside the types they copy. Metadata is held by
  value, so those copy rather than point — free at compile time.

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

[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: 90e1e398-e9d8-4459-8a94-e7f9da3f2c7d

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	▁▁▁▁▁▁▁▁▂███	152,797,288 → 152,849,292	+0.03%	14.15 → 14.28ms	+0.88%
startup	▅▅▅█▅▅▅▅▅▅▁▁	1,201,844 → 1,201,836	-0.00%	0.96 → 0.96ms	+0.12%

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	40221	5960254	148x

usage: argv -> struct                            1778 ns      1.78 µs
clap: build tree + parse -> struct             502223 ns    502.22 µs
clap: parse -> struct, tree reused              23384 ns     23.38 µs
clap: build tree only                          310189 ns    310.19 µs

_{e41a3fdf6062 vs 076fe59bdc97 · measured on the runner, not pushed to the history.}

[greptile-apps]

Greptile Summary

Adds compile-time helpers for joining static argv parse tables and their corresponding metadata while preserving declaration order.

• Adds generic table-length calculation and ordered flag/argument concatenation.
• Adds equivalent metadata concatenation under the optional spec surface.
• Adds parser tests covering ordering, empty groups, and concatenated-table behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
argv/src/lib.rs	Adds const table-length and parse-table concatenation helpers with tests for ordering, empty groups, and parser behavior.
argv/src/spec.rs	Adds matching const concatenation helpers for flag and argument metadata.

_{Reviews (2): Last reviewed commit: "feat(argv): join static tables at compil..." | Re-trigger Greptile}