feat(spec): expose package metadata

[jdx]

Summary

• add typed root attributes for author, license, and repository metadata
• preserve those fields in direct usage-rs KDL emission and spec views
• render package metadata in Markdown references and manpages
• close the license metadata PLAN gap

Validation

• cargo test -p usage-rs --all-features package_metadata_survives_spec_emission
• cargo test -p usage-lib --all-features
• cargo clippy -p usage-argv -p usage-derive -p usage-rs -p usage-lib --all-features -- -D warnings

---

Note

Low Risk
Additive optional metadata and documentation output only; no parsing or auth behavior changes.

Overview
Adds root-level package metadata (author, license, repository) to the CLI spec so it can flow from derive attributes through KDL into generated docs.

Spec & derive: Spec gains the three optional fields (including EMPTY and overlay wiring), KDL emission writes them when set, and #[usage(author|license|repository = …)] on the root accepts expressions (e.g. env!("CARGO_PKG_…")) while rejecting the same attributes on nested commands.

Output: Markdown templates and the manpage renderer emit Author, License, and Source sections when present; the usage CLI manpage gains a SOURCE section via generated docs.

Docs & tracking: PLAN marks license metadata done; clap compatibility and migration docs describe the new surface. Conformance roundtrip and facade tests lock in KDL/spec preservation.

^{Reviewed by Cursor Bugbot for commit 49e751e. 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: 32fade67-83d0-4714-897c-cdeb5b94e4b3

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

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▇█	207,853,342 → 209,634,588	+0.86%	19.31 → 19.36ms	+0.29%
startup	▅▁█	1,216,618 → 1,219,660	+0.25%	1.48 → 1.45ms	-1.88%

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	instructions, cold parse	vs usage
usage	4347	—
argh	6292	1.4x
clap	5893640	1355x
bpaf	21917948	5042x

                                              min       p01       p10    median
usage-rs: argv -> struct                      188       192       196       203  ns
argh: argv -> struct                          275       279       284       291  ns
clap: build tree + parse -> struct         487328    488691    495864    506109  ns
bpaf: build parser + parse -> struct      1575248   1575248   1580854   1629284  ns

usage: argv -> struct                             208 ns      0.21 µs
clap: build tree + parse -> struct             495510 ns    495.51 µs
clap: parse -> struct, tree reused              22735 ns     22.74 µs
clap: build tree only                          303124 ns    303.12 µs

_{49e751ed6d2b vs d9ec8b579ada · 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 3b8e1b5. Configure here.}