feat(lib): add usage-rs facade

[jdx]

Summary

• add usage-rs, the single dependency for compiled usage CLIs
• re-export the four derives, the argv runtime, and ValueHint from the facade
• forward cold-path spec, help, completions, and diagnostics features
• make generated derive paths resolve either usage-rs or a direct/renamed usage-argv dependency
• retain direct usage-argv compatibility for low-level adopters

Applications can choose the short public crate name in Cargo:

[dependencies]
usage = { package = "usage-rs", version = "5.1" }

and then keep the declaration on one API:

use usage::Cli;

#[derive(Cli)]
struct Cli {
    #[usage(long, value_hint = usage::ValueHint::FilePath)]
    file: Option<std::path::PathBuf>,
}

Why

Depending on usage-derive and usage-argv separately exposes an implementation split and allows their versions or features to drift. The facade gives adopters one versioned package while leaving the zero-allocation runtime independently usable.

The facade crate target remains usage_rs to avoid colliding with the existing usage-lib target inside this workspace. The documented Cargo alias provides the intended usage::… source spelling.

Stack

Targets #951, which introduces the usage-owned ValueHint re-exported here.

Checks

• cargo test --all --all-features
• cargo clippy --all --all-features --all-targets -- -D warnings
• cargo +1.91.0 check -p usage-argv -p usage-derive -p usage-rs --all-features
• cargo check -p usage-rs --no-default-features
• external path-dependency check using the documented usage = { package = "usage-rs", … } alias

This PR was generated by Codex.

---

Note

Low Risk
Mostly additive packaging and path resolution in proc-macro codegen; direct usage-argv usage remains supported, with limited blast radius beyond new adopters choosing the facade.

Overview
Introduces usage-rs, a facade so compiled CLI apps can depend on one Cargo package (e.g. usage = { package = "usage-rs", … }) instead of splitting usage-derive and usage-argv.

The crate re-exports the argv runtime (including ValueHint), optionally re-exports Cli, Args, Subcommands, and ValueEnum behind the spec feature, and forwards help, completions, and diagnostics to the underlying crates. usage-derive codegen now prefers resolving runtime and derive paths through usage-rs (including renamed package aliases), with the previous direct usage-argv / usage-derive paths kept for low-level adopters.

Workspace wiring adds the new member, lockfile entry, and MSRV CI coverage for usage-rs.

^{Reviewed by Cursor Bugbot for commit 5c280bf. 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: e77265cd-1132-4545-be9a-5db7e342cca9

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​proc-macro-crate@​3.5.0

View full report

[greptile-apps]

Greptile Summary

The PR adds the usage-rs facade so compiled CLI consumers can access derives and the argv runtime through one dependency.

• Re-exports the argv runtime, derive macros, and ValueHint.
• Resolves generated derive paths through either the facade or a direct/renamed usage-argv dependency.
• Forwards spec, help, completion, and diagnostics features.
• Adds facade integration coverage and Rust 1.91 CI coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/codegen.rs	Adds dependency-aware runtime path resolution and consistently aliases generated runtime references through the selected facade or direct crate.
usage-rs/src/lib.rs	Defines the facade's unconditional argv exports and feature-gated derive re-exports.
usage-rs/Cargo.toml	Declares the facade package and forwards cold-path runtime features while enabling spec and help by default.
usage-rs/tests/facade.rs	Exercises derives, parsing, generated metadata, and value hints through the facade.
derive/Cargo.toml	Adds proc-macro-crate so generated code can resolve renamed facade and runtime dependencies.
.github/workflows/test.yml	Adds usage-rs to the Rust 1.91 all-features compatibility check.

_{Reviews (5): Last reviewed commit: "chore: include usage-rs in msrv checks" | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁████▇	197,252,892 → 195,546,689	-0.86%	18.19 → 18.86ms	+3.72%
startup	███████▁	1,242,733 → 828,952	-33.30%	1.05 → 0.87ms	-17.39%

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.

	usage	clap	ratio
instructions, cold parse	64541	5895248	91x

usage: argv -> struct                            1081 ns      1.08 µs
clap: build tree + parse -> struct             500149 ns    500.15 µs
clap: parse -> struct, tree reused              23667 ns     23.67 µs
clap: build tree only                          308034 ns    308.03 µs

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

[greptile-apps]

No reviewable files after applying ignore patterns.