feat(argv): route a word that names nothing to the default subcommand

[jdx]

default_subcommand was emitted into the spec and ignored by the parser, which the
previous commit recorded as a gap rather than a decision. usage-lib routes on it, and
this is the rule behind mise build meaning mise run build.

A word naming no subcommand now descends into the named one, and the cursor steps back so
the word is examined again against the command it reached — which lets it be that
command's argument or one of its subcommands, without this deciding which and without
two events for one word. The declaring command's own positional does not win, which is
what makes the property more than a synonym for an argument, and is mise's shape exactly:
the root has [TASK] and so does run.

Taken at most once per parse, as usage-lib does, so a chain of defaults cannot walk a CLI
deeper than anything the user typed.

The name is resolved by find_subcommand during const evaluation, so a name no
subcommand answers to is a compile error. The previous commit said the name could not be
checked because the variants are another expansion; that is true of the macro and not of
const eval, which can search the list the parent already holds.

Seven corpus vectors, six agreeing with usage-lib and one recording where it does not:
usage-lib holds the single name spec-wide and applies it at whichever command it stands
on, so ex config zzz descends into config ls when an unrelated command happens to
have a subcommand of that name. Read here as a property of the root, which is the only
place a spec can declare it.

default_subcommand on a nested Args is now refused outright instead of being dropped
in silence. Both derives share one parse, so the rule moved to where the context is
known — before, a nested struct got whichever check ran first, which named the wrong
problem.

No measurable cost: 40,370 instructions against 40,472, the branch being reached only by
a word that matched no subcommand. Allocations unchanged — 0 bare, 4 bound.

One thing this does not buy: mise build still fails in the shadow, because mise's spec
gives run no positional — its arguments are cleared and a mount supplies task names,
which usage-argv does not execute. Routing plus mounts is what lets mise delete its
hand-rolled dispatch; the gate test now says so rather than asserting the old answer.

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

---

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

---

Note

Medium Risk
Changes core subcommand routing and argv binding semantics (default descent, once-per-parse latch, token rewind), which can alter how bare words and edge cases parse across CLIs that declare default_subcommand.

Overview
Implements default_subcommand in the hot-path parser so a bare word like build can mean “descend into run and bind there,” matching usage-lib and mise’s mise build → mise run build shape.

Command gains default_subcommand plus find_subcommand (const-time name/alias lookup, compile error if the name is missing). In word(), after a failed subcommand match, the parser may descend once per parse (default_taken), rewind the argv cursor, and re-read the same token under the default command. Routing is skipped for flag-like tokens, after --, and when a positional already filled; unknown flags still bind at the current command.

Derive and conformance wire the root-level spec property into static tables; nested default_subcommand on Args is rejected. Corpus adds 09-default-subcommand.json (including one recorded usage-lib divergence: root-only vs spec-wide default). Gate shadow now expects mise build to route into run then fail with UnexpectedArg until mounts exist.

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

The decision behind this

Investigating flatten turned up that five of mise's ten #[clap(flatten)] sites are a
subcommand field beside a flatten of the same type the Ls variant holds — config,
tasks, settings, deps, tool all hand-rolling "with no subcommand, behave as ls".
Which raised the question of what default_subcommand actually means, and the answer was that
#842 got it wrong: usage-lib routes on it while parsing.

["mise", "build"] -> cmds ["mise", "run"], args [("TASK", String("build"))]

Even though the root declares its own arg "[TASK]". So the property is a binding rule, and
#842's test asserting otherwise was corrected in its own commit before this one.

Cost

	before	after
instructions, cold parse	40,472	40,370
allocations, bare / bound	0 / 4	0 / 4

No measurable cost. The branch is reached only by a word that already failed a subcommand
lookup, and the ±100 is code layout rather than work done — cachegrind is deterministic and
gave the same figure on repeated runs.

The name is now checked at compile time

#842 said "which command it names cannot be checked here — the enum's variants are in another
expansion". True of the macro, not of const evaluation: find_subcommand searches the list the
parent already holds, so

error[E0080]: evaluation panicked: `default_subcommand` names a command that this one does not have

A wrong name is a compile error rather than a spec property nothing validates.

What this does not buy

mise build still does not work end to end in the shadow, and it is worth being plain about
why: mise's spec gives run no positional at all — src/cli/usage.rs clears them and adds
mount run="mise tasks --usage", so task names are meant to come from running that.
usage-argv does not execute mounts, so after descending there is nothing to bind to. Routing
plus mounts is what would let mise delete its hand-rolled dispatch; this is half of it. The
gate test now records that instead of asserting the old answer.

Verification

• Seven corpus vectors. Six agree with usage-lib — checked automatically, since an absent
  reference label is an assertion the reference test enforces in both directions.
• Six parser unit tests: routing, a named subcommand not routed, re-examination against the
  reached command, the once-per-parse latch, a flag before the word, and nothing routing past
  --.
• Mutation-checked: removing the latch fails the latch test; removing the cursor rewind fails
  four.
• End-to-end through the derive, plus a test that the resolved pointer is the table's own entry
  rather than a copy.

One divergence, and a question

default-is-declared-for-the-root records it: usage-lib holds the single name for the whole
spec and applies it at whichever command it is standing on, so with default_subcommand "ls" declared at the top, ex config zzz descends into config ls — an unrelated command
acquiring a default because a name happened to match one level down.

["config", "zzz"] -> cmds ["ex", "config", "ls"], args [("WHAT", String("zzz"))]

This parser reads it as a property of the root, which is the only place a spec can declare one.
That looks like the intended meaning and usage-lib's looks accidental — but it is your call,
and if you agree it is a small fix in lib/src/parse.rs. The corpus label makes the difference
fail loudly the moment it changes either way.

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: a83a484c-bdc6-475e-9cb2-66c31cefdefc

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

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

[greptile-apps]

Greptile Summary

The PR implements default-subcommand routing in the compiled argv parser and resolves configured defaults against canonical subcommand names and aliases at compile time.

• Adds once-per-parse routing and token re-examination in usage-argv.
• Emits resolved default-subcommand pointers from usage-derive.
• Extends conformance vectors and parser, derive, and gate tests for routing behavior and edge cases.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
argv/src/lib.rs	Adds default-subcommand table state, alias-aware const resolution, and once-per-parse routing; the prior alias rejection is fixed.
derive/src/codegen.rs	Emits the configured default as a compile-time-resolved pointer while preserving visible and hidden aliases in the command alias table.
derive/src/model.rs	Documents compile-time name validation and retains root-versus-nested declaration checks.
conformance/src/argv.rs	Attaches the spec-level default to the root command used by corpus execution.
corpus/09-default-subcommand.json	Adds coverage for routing, aliases, separators, unknown flags, and root-only semantics.

_{Reviews (7): Last reviewed commit: "fix(argv): route only a word, and let an..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▁▁▁▁▁▂███	152,797,288 → 152,857,178	+0.04%	14.15 → 14.56ms	+2.84%
startup	▅▅▅█▅▅▅▅▅▅▁▁	1,201,844 → 1,201,836	-0.00%	0.96 → 0.95ms	-1.44%

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	5962046	148x

usage: argv -> struct                            1741 ns      1.74 µs
clap: build tree + parse -> struct             503130 ns    503.13 µs
clap: parse -> struct, tree reused              23478 ns     23.48 µs
clap: build tree only                          316625 ns    316.62 µs

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

[jdx]

Addressed in the latest push.

Both findings were real, and both confirmed against usage-lib before fixing.

• Unknown flags routing (Bugbot): `ex --wat` in usage-lib comes back as commands `["ex"]` with the token bound to the root positional. Only a token that could have named a command routes now, which also excludes the `--` a `preserve` argument asks for as a value.
• Aliases (Greptile): usage-lib resolves the name against names, aliases and hidden aliases, so `find_subcommand` does too — before, pointing `default_subcommand` at an alias failed to compile.

Three corpus vectors, all agreeing with usage-lib, and both fixes mutation-checked.

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