feat(derive): support path value hints

[jdx]

Summary

• add a usage-owned usage_argv::ValueHint for value_hint expressions
• map FilePath and AnyPath to the spec's type="path", and DirPath to type="dir"
• carry hints through native usage-argv completion and emitted KDL
• reject hints on valueless fields or alongside a custom completer
• document and test file/directory completion behavior end to end

Declarations use usage’s own hint type:

#[usage(long, value_hint = usage_argv::ValueHint::FilePath)]

The hint type lives in usage-argv, the derive runtime a compiled CLI already uses.

Stack

Targets #949 and becomes the direct base for #936.

Checks

• cargo test -p usage-conformance --test completion
• cargo test -p usage-argv --features spec,complete
• cargo test -p usage-derive
• cargo test --all --all-features
• cargo clippy --all --all-features --all-targets -- -D warnings
• mise run render

This PR was generated by Codex.

---

Note

Low Risk
Changes are limited to completion/spec metadata and derive codegen; parsing is unaffected and behavior is covered by conformance tests.

Overview
Adds usage_argv::ValueHint (FilePath, AnyPath, DirPath) so #[usage(value_hint = …)] can declare filesystem completion without pulling in clap.

The derive maps hints to spec vocabulary (path / dir), stores them on FlagMeta / ArgMeta as complete_type, and emits complete "…" type="…" blocks in KDL. Native completion now prefers that metadata (then still falls back to value-name heuristics like <FILE>).

Compile-time guards reject value_hint on valueless fields and value_hint together with a custom complete function. Conformance tests cover bash markers, emitted KDL, and parsing unchanged.

^{Reviewed by Cursor Bugbot for commit 26fa455. 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: 0621d2c1-f727-4023-875b-c37df251a790

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

Adds a usage-owned path hint type and carries path or directory completion metadata through derive-generated runtime tables and emitted KDL.

• Maps file and arbitrary-path hints to type="path" and directory hints to type="dir".
• Rejects hints on valueless fields and alongside custom completers.
• Adds end-to-end coverage for native completion, KDL emission, and unchanged parsing.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
argv/src/complete.rs	Prefers explicit completion metadata over value-name-based filesystem inference.
argv/src/spec.rs	Stores completion types in argument and flag metadata and serializes them into KDL.
argv/src/lib.rs	Introduces the public usage-owned ValueHint variants for file and directory completion.
derive/src/model.rs	Parses supported value hints, lowers them to spec completion types, and validates incompatible field shapes.
derive/src/codegen.rs	Propagates derived completion types into generated runtime metadata.
conformance/tests/completion.rs	Verifies path hints through native completion, emitted KDL, and normal argument parsing.

_{Reviews (6): Last reviewed commit: "refactor(derive): use usage value hints" | 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.

	usage	clap	ratio
instructions, cold parse	64525	5895248	91x

usage: argv -> struct                            1125 ns      1.12 µs
clap: build tree + parse -> struct             508782 ns    508.78 µs
clap: parse -> struct, tree reused              24458 ns     24.46 µs
clap: build tree only                          315543 ns    315.54 µs

_{26fa45574d48 vs 60b4357913a5 · measured on the runner, not pushed to the history.}