feat(spec): select a subcommand from argv0 when multicall

[jdx]

Stacked on #1027. Adds clap's Command::multicall as spec-level multicall #true.

Semantics

argv[0]'s basename is a word unless it is the dispatcher (name or bin). A symlink ls -> busybox is parsed as if the first token were ls. busybox ls still selects ls: the dispatcher name is skipped. Path components and a trailing .exe are stripped so /usr/bin/ls and ls.exe agree.

An unknown applet is an unmatched word: it errors, is forwarded when the root declares external_subcommand, or is caught by default_subcommand. Invoking the dispatcher with no further words stays at the root.

Where argv0 is rewritten

• usage-lib parse includes the program name. After pop_front, a non-dispatcher basename is pushed back.
• usage-argv / derive parse_from / Go Parse take argv without the program name. parse() and the corpus adapters rewrite at process entry; parse_from stays unchanged because the caller already decided the words.
• Helpers: multicall_basename / multicall_applet in usage-lib and usage-argv; Go RewriteMulticall.

Surfaces

• Spec parse/emit/merge, clap is_multicall_set
• Derive #[usage(multicall)] on the root (refused below it, and without subcommands)
• Go JSON multicall, argv.RewriteMulticall
• Corpus 12-multicall.json (argv0 on Vector; absent means the spec's bin)
• usage lint reports multicall-no-subcommands
• Shadows emit multicall for both usage and clap dialects

no_binary_name stays out of scope.

This comment was generated by Claude Code.

  

[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: a0634528-429a-4f0f-8a75-8d3eb204b81a

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

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.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	instructions, cold parse	vs usage
usage	4220	—
argh	6292	1.5x
clap	5893652	1396x
bpaf	21917954	5193x

                                              min       p01       p10    median
usage-rs: argv -> struct                      187       190       193       196  ns
argh: argv -> struct                          285       289       293       299  ns
clap: build tree + parse -> struct         483347    485321    489077    495486  ns
bpaf: build parser + parse -> struct      1585062   1585062   1592298   1609874  ns

usage: argv -> struct                             199 ns      0.20 µs
clap: build tree + parse -> struct             498028 ns    498.03 µs
clap: parse -> struct, tree reused              23612 ns     23.61 µs
clap: build tree only                          307915 ns    307.91 µs

_{188cef88a288 vs 698b529649c7 · measured on the runner, not pushed to the history.}