feat(parse): support inferred prefixes

[jdx]

Summary

• accept unique prefixes for command names and aliases
• accept unique prefixes for long flags, aliases, and negations
• inherit both policies through Rust and Go command trees
• preserve the settings in typed derive metadata, KDL, runtime specs, and generated Go
• document the clap bridge limitation and close the PLAN gap

Validation

• cargo test -p usage-argv --all-features
• cargo test -p usage-lib --all-features
• cargo test -p usage-conformance --all-features
• cargo clippy --all --all-features --all-targets -- -D warnings
• USAGE_BIN=../target/debug/usage go test ./... from go/

This pull request was generated by an AI coding agent.

---

Note

Medium Risk
Changes core argv parsing and help routing in Rust, Go, and usage-lib when inference is enabled; behavior is opt-in but must stay consistent across emitters and runtimes.

Overview
Adds infer_subcommands and infer_long_args so CLIs can accept only unambiguous prefixes of subcommand names/aliases and long flags (including negations), with exact spellings always winning and ambiguous prefixes rejected.

The policy is inherited as the parser descends, wired through #[usage(infer_subcommands, infer_long_args)], KDL/spec fields, usage-lib parsing, usage-argv (Rust + Go), generated tables, and help routing (help insta-style paths). Built-in help / --help participate in prefix rules without colliding with declared helper / --help-all when that would be ambiguous.

Docs note clap’s no public getters for these globals, so the clap bridge cannot infer them. PLAN.md marks this gap closed. Long-flag lookup is refactored so negated value flags (e.g. --no-mode) no longer consume the following positional.

^{Reviewed by Cursor Bugbot for commit 53c5807. 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: ff6067fe-9277-419a-8039-f227a50e25d5

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	4242	—
argh	6292	1.5x
clap	5895248	1389x
bpaf	21917778	5166x

                                              min       p01       p10    median
usage-rs: argv -> struct                      202       204       207       214  ns
argh: argv -> struct                          281       286       291       303  ns
clap: build tree + parse -> struct         483366    485157    491674    506367  ns
bpaf: build parser + parse -> struct      1586867   1586867   1596290   1626316  ns

usage: argv -> struct                             220 ns      0.22 µs
clap: build tree + parse -> struct             487818 ns    487.82 µs
clap: parse -> struct, tree reused              23449 ns     23.45 µs
clap: build tree only                          298962 ns    298.96 µs

_{87f9da9c9899 vs 0b137759b66b · measured on the runner, not pushed to the history.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 87f9da9. Configure here.}