fix(completion): handle attached values and emit built-ins

[jdx]

Summary

• complete the value fragment in attached long options such as --format=j, then return whole-word candidates such as --format=json
• route static choices, named completers, and runtime completion overlays through the attached-value context
• materialize parser-supplied help and version flags in generated specs, including collision-aware surviving spellings
• mark materialized entries as built-ins so listings and completion consumers see them without changing ordinary usage synopses

Tests

• cargo test --all --all-features
• cargo clippy --all --all-features --all-targets -- -D warnings
• cargo test -p usage-argv --all-features
• cargo test -p usage-conformance --all-features
• cargo test -p gate --test fleet --all-features
• cargo fmt --check

AI-assisted — Tool: Codex; model: unavailable; version: unavailable.

---

Note

Medium Risk
Touches completion routing and the generated spec surface (KDL/JSON/docs). Builtin flags change what consumers see without altering parse behavior, but a mismatch in builtin handling could duplicate help/version in generated parsers or synopses.

Overview
Shell completion now treats --flag=prefix as a value position. Candidates are matched against the fragment after = and rewritten as whole words (--flag=json) so static choices, named completers, and runtime overlays work for attached longs.

Generated specs materialize the parser-supplied help/version spellings (collision-aware) as action flags with builtin=#true. They show up in listings, completions, and docs, but stay out of command synopses. Shadow codegen skips those entries so generated parsers do not redeclare the framework built-ins.

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

[coderabbitai]

Warning

Review limit reached

Next included review available in 24 minutes.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 27044a9a-82ad-4938-9eba-3d3c5ec0c80a

📥 Commits

Reviewing files that changed from the base of the PR and between 2a30ed9 and f752a7a.

⛔ Files ignored due to path filters (3)

• conformance/tests/snapshots/nesting__the_emitted_spec_reads_like_a_handwritten_one.snap is excluded by !**/*.snap
• conformance/tests/snapshots/spec_roundtrip__the_emitted_spec_is_stable.snap is excluded by !**/*.snap
• conformance/tests/snapshots/subcommands__the_emitted_spec_reads_the_way_a_handwritten_one_would.snap is excluded by !**/*.snap

📒 Files selected for processing (43)

• argv/src/complete.rs
• argv/src/help.rs
• argv/src/spec.rs
• benches/fleet/communique.usage.kdl
• cli/assets/fig.ts
• cli/assets/usage.1
• cli/usage.usage.kdl
• conformance/src/tables.rs
• conformance/tests/combinations.rs
• conformance/tests/completion.rs
• conformance/tests/derive.rs
• conformance/tests/flatten.rs
• conformance/tests/help_request.rs
• conformance/tests/spec_roundtrip.rs
• conformance/tests/subcommands.rs
• conformance/tests/unit_variants.rs
• conformance/tests/version.rs
• derive/src/lib.rs
• docs/cli/reference/commands.json
• docs/cli/reference/complete-word.md
• docs/cli/reference/diff.md
• docs/cli/reference/explain.md
• docs/cli/reference/generate.md
• docs/cli/reference/generate/completion-init.md
• docs/cli/reference/generate/completion.md
• docs/cli/reference/generate/fig.md
• docs/cli/reference/generate/go.md
• docs/cli/reference/generate/json-schema.md
• docs/cli/reference/generate/json.md
• docs/cli/reference/generate/manpage.md
• docs/cli/reference/generate/markdown.md
• docs/cli/reference/generate/sdk.md
• docs/cli/reference/index.md
• docs/cli/reference/lint.md
• docs/cli/reference/mcp.md
• docs/cli/reference/sponsors.md
• docs/rust/completions.md
• docs/spec/reference/cmd.md
• docs/spec/reference/flag.md
• lib/src/spec/cmd.rs
• lib/src/spec/flag.rs
• usage-rs/tests/facade.rs
• xtask/src/shadow.rs

---

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

[jdx]

Fixed the Linux and Windows fleet failures in commit 6c73479. Exported specs still materialize parser-supplied help and version entries for docs and completions, while generated parser shadows now leave those entries to the target framework instead of emitting ordinary fields. The failing fleet test, full workspace tests, clippy, formatting, and shadow regeneration all pass locally.

AI-assisted — Tool: Codex; model: unavailable; version: unavailable.

[jdx]

Adjusted the regression test in commit f752a7a for current usage-rs main, which removed the Argh benchmark dialect after this branch was created. The production shadow fix is unchanged; the focused xtask test and xtask clippy pass.

AI-assisted — Tool: Codex; model: unavailable; version: unavailable.