feat(complete): complete sigil-prefixed positionals

[jdx]

Summary

• match completions against the value after the declared sigil
• restore the sigil on emitted completion candidates
• keep explicit double dash behavior intact
• add dedicated sigil documentation and completion examples

Stack

• Depends on feat(spec,parse): add sigil-classified positional arguments #1322

Test plan

• cargo test -p usage-cli complete_word_sigil
• cargo test -p usage-conformance --test sigil
• mise run lint

AI-assisted — Tool: Codex; model: OpenAI/GPT-5; version: unavailable.

---

Note

Medium Risk
Touches shared completion routing in argv and the CLI completer; mistakes could mis-classify cursor position or leak incorrect file fallbacks, but behavior is heavily covered by new tests.

Overview
Tab completion now treats sigil-prefixed positionals (e.g. +node@22) as their own cursor position: the declared prefix is stripped for matching against choices, completers, and runtime overlays, then re-applied on every candidate—the same behavior in usage-argv and the complete_word CLI path.

Boundary rules align with parsing: sigil matching is disabled after --, when a restart token (:::) was already seen, while a flag is awaiting a value, or after an automatic double_dash argument has started its trailing segment—so tokens like -- +n stay ordinary positionals. Sigil-shaped tokens also suppress cwd/file shell fallback when the field is a closed choice set.

Adds sigil reference docs, an example KDL spec, and tests covering choices, separators, restart, and async overlays.

^{Reviewed by Cursor Bugbot for commit 5c3c3a1. 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: 64f6f164-d416-4248-939b-40e4ef9da4f2

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

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▄▆▄▄▄▆▆██	339,081,364 → 339,047,522	-0.01%	30.12 → 28.96ms	-3.85%
startup	▁██████▇██	909,012 → 908,375	-0.07%	0.92 → 0.93ms	+1.77%

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.

framework	stripped binary, bytes
usage	1328960
bpaf	2493280
clap	3101832

framework	instructions, cold parse	vs usage
usage	8441	—
clap	6315228	748x
bpaf	21909141	2595x

                                              min       p01       p10    median
usage-rs: argv -> struct                      420       423       427       438  ns
clap: build tree + parse -> struct         519239    519816    522353    539448  ns
bpaf: build parser + parse -> struct      1605018   1605018   1632776   1658218  ns

usage: argv -> struct                             480 ns      0.48 µs
clap: build tree + parse -> struct             534279 ns    534.28 µs
clap: parse -> struct, tree reused              23438 ns     23.44 µs
clap: build tree only                          327389 ns    327.39 µs

_{5c3c3a1d8bb2 vs c10123adf0f9 · measured on the runner, not pushed to the history.}