feat(go): answer what could go where the cursor is

[jdx]

argv.Walk reads the words before the cursor and reports what it is standing in; argv.Candidates says what could go there — subcommands and their aliases, the flags in scope, and the values a choices list allows.

Stacked on #978.

Asking the parser rather than re-deriving it

That is the whole design. A completion advertising a flag the parser would refuse is worse than no completion, so the scope a candidate comes from is the scope a token would be resolved in:

• a global is offered inside a subcommand
• a subcommand redeclaring an inherited name offers its own
• a hidden flag binds without being advertised
• past a --, nothing is offered — there is no flag of this CLI to type there

Errors are not failures here

A line being completed is unfinished by definition, so a parse error means "the grammar runs out here" — which is the position being asked about. missing_flag_value says the cursor is standing in a flag's value, and that flag's choices take the position entirely. help says the cursor is naming a command to read about, where nothing else belongs.

Not included

Turning candidates into the text each shell expects, and running the complete scripts a spec can declare. The first is per-shell formatting, the second runs subprocesses, and neither belongs in a package whose claim is that a parse does not allocate. Both are noted in the README.

One note from writing the tests

The first fixture numbered its keys 10–14 in an eight-entry table. Both cold tables are indexed by key, so every lookup missed and the assertions about hiding and choices passed for the wrong reason — they only started failing once the keys were dense. The invariant is documented on Metadata; worth knowing that breaking it fails quietly rather than loudly.

🤖 Generated with Claude Code

---

Note

Medium Risk
New completion surface area mirrors subtle parser/help scope rules; behavior is heavily tested but mistakes would mislead users without breaking parses.

Overview
Adds parser-driven tab completion in argv: Walk parses words before the cursor into a Position (command chain, whether flags/subcommands still apply, awaiting flag value, variadic collection, pending arg, help topic mode), and Candidates returns subcommands/aliases, in-scope flag spellings, and choices values filtered by a partial prefix.

Completion reuses the same scope rules as help via flagsInScope (per-spelling shadowing of inherited globals, negation vs long-form precedence) and refactors everyFormInScope / negationSurvives in scope.go so help and completions stay aligned. Parser.SubcommandsPossible exposes when descent into subcommands has stopped.

README documents the completion API and notes that per-shell formatting and complete scripts are still out of scope.

^{Reviewed by Cursor Bugbot for commit 84b303e. 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: 80f46d25-b431-4065-9087-d1c92377fb51

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

[greptile-apps]

Greptile Summary

The PR adds Go APIs that derive completion positions and candidates from parser state, with focused fixes ensuring completion visibility and flag ownership match parser behavior.

• Adds Walk and Candidates for commands, aliases, scoped flags, and declared choices.
• Shares negation and flag-scope rules between help rendering and completion.
• Covers hidden commands, required separators, positional state, variadic values, and shadowed flag spellings with tests.
• Documents the completion API and its deliberately excluded shell-formatting responsibilities.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
go/argv/complete.go	Adds parser-driven completion state and candidate generation; the previously reported visibility, separator, shadowing, and negation defects are addressed.
go/argv/complete_test.go	Adds focused regression coverage for completion scope, hidden entries, required separators, variadic collection, and negation collisions.
go/argv/parser.go	Exposes whether parser state still permits subcommand descent for completion parity.
go/argv/scope.go	Extracts shared form and negation-survival logic without changing the established help-rendering contract.
go/README.md	Documents the new parser-driven completion APIs and clarifies that shell-specific output remains out of scope.

_{Reviews (8): Last reviewed commit: "fix(go): a variadic still collecting is ..." | Re-trigger Greptile}

[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	4161	—
argh	6292	1.5x
clap	5895248	1416x
bpaf	21917778	5267x

                                              min       p01       p10    median
usage-rs: argv -> struct                      210       214       219       227  ns
argh: argv -> struct                          273       278       283       295  ns
clap: build tree + parse -> struct         482935    483649    487867    501766  ns
bpaf: build parser + parse -> struct      1563765   1563765   1569977   1594023  ns

usage: argv -> struct                             206 ns      0.21 µs
clap: build tree + parse -> struct             505175 ns    505.17 µs
clap: parse -> struct, tree reused              24485 ns     24.48 µs
clap: build tree only                          319377 ns    319.38 µs

_{84b303e0bbd4 vs c5d9ad605c95 · measured on the runner, not pushed to the history.}

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