feat(parse): support ordered environment fallbacks

[jdx]

Summary

• add ordered env_fallback and deprecated_env flag metadata to KDL and the typed derive
• apply precedence as argv, canonical environment, ordinary fallbacks, deprecated aliases, then defaults
• carry the declarations through Rust and Go parsing, help, docs, and generated tables
• close the corresponding PLAN gap with conformance coverage

Validation

• cargo clippy --workspace --all-features -- -D warnings
• cargo test --workspace --all-features
• (cd go && go test ./...)

This PR was generated by Codex.

---

Note

Medium Risk
Changes environment-variable fill order in Rust and Go parsers, which can change which value a CLI binds when multiple vars are set. Help and spec round-trip are updated in lockstep.

Overview
Adds ordered environment fallbacks and deprecated env aliases on flags and positionals. After argv, parsers try the canonical env, then env_fallback in declaration order, then deprecated_env, then defaults.

The lists are first-class in KDL (env_fallback / deprecated_env nodes), the typed derive (env_fallback(...), deprecated_env(...)), usage-lib, generated Go tables, and help/docs (including man pages). hide_env still suppresses all of those names.

Closes the PLAN item for clap#5447 / clap#5925, with conformance covering flags, positionals, flatten/next-line help, and KDL round-trip.

^{Reviewed by Cursor Bugbot for commit ae16f8c. 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: 944d0783-494d-435d-b873-c656c22024d7

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	▄▁▁█	199,315,003 → 218,166,819	+9.46% ⚠️	19.00 → 21.82ms	+14.85%
startup	▁███	1,221,718 → 1,221,948	+0.02%	1.35 → 1.47ms	+9.13%

1 benchmark(s) above the 1% gate: markdown +9.46%

_{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	4353	—
argh	6292	1.4x
clap	5893640	1353x
bpaf	21917948	5035x

                                              min       p01       p10    median
usage-rs: argv -> struct                      189       193       196       203  ns
argh: argv -> struct                          289       293       300       311  ns
clap: build tree + parse -> struct         483458    483884    487048    491316  ns
bpaf: build parser + parse -> struct      1565108   1565108   1575438   1599749  ns

usage: argv -> struct                             196 ns      0.20 µs
clap: build tree + parse -> struct             490815 ns    490.82 µs
clap: parse -> struct, tree reused              23564 ns     23.56 µs
clap: build tree only                          302941 ns    302.94 µs

_{0c6975743363 vs c10d85cbe1b9 · 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 fd31165. Configure here.}