docs(rust): combine clap migration guidance

[jdx]

Folds clap compatibility into the migration guide and moves leftover “Current limitations” off /rust/.

Changes

• Replace the exhaustive clap compatibility matrix with a short Compatibility gaps table on Migrating from clap.
• Keep /rust/clap-compatibility as a redirect stub to that section so old links still work.
• Remove clap Compatibility from the VitePress sidebar.
• Drop Current limitations from /rust/: clap-specific bullets already live in Compatibility gaps; add value_optional there; document PathBuf/OsString/String argv encoding on Args and flags.

Notes

• Go /go/ still has its own Current limitations section; this change is Rust-only.
• The clap compatibility page is no longer a standalone matrix. If a reviewer wants that table back, it can live as an appendix without restoring a second nav item.

  

Summary by CodeRabbit

• Documentation
  • Consolidated clap migration and compatibility guidance into the “Migrating from clap” guide.
  • Added a compatibility-gaps checklist covering parsing, validation, naming, help, completion, and optional-value differences.
  • Redirected the former compatibility page to the relevant migration guidance.
  • Documented non-UTF-8 argument handling across platforms.
  • Clarified optional-value flag behavior and post-parse validation guidance.
  • Updated documentation links, navigation, and testing descriptions.
  • Clarified that conformance checks verify migration behavior across supported clap versions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: ac58f0dc-e196-43b1-b5a0-d11dc402e5da

📥 Commits

Reviewing files that changed from the base of the PR and between bc329ea and a9da182.

📒 Files selected for processing (3)

• docs/rust/args-and-flags.md
• docs/rust/index.md
• docs/rust/migrating-from-clap.md

💤 Files with no reviewable changes (1)

• docs/rust/index.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/rust/args-and-flags.md

Included review availability: Your plan provides up to 4 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The PR moves clap compatibility guidance into migrating-from-clap.md. It replaces the former compatibility page with a redirect and updates parsing guidance, documentation links, navigation, attribution, and conformance test wording.

Changes

Clap migration documentation

Layer / File(s)	Summary
Centralize migration guidance docs/rust/migrating-from-clap.md, docs/rust/args-and-flags.md	Adds compatibility-gap, parsing, optional-value, positional validation, and conformance verification guidance.
Redirect legacy compatibility documentation docs/rust/clap-compatibility.md, docs/.vitepress/config.mts, docs/rust/index.md	Replaces the compatibility page with a redirect and removes obsolete navigation and limitation content.
Update references and conformance wording NOTICE.md, conformance/tests/clap_micro.rs, docs/rust/args-and-flags.md, docs/spec/integrations/clap.md	Updates links and describes conformance checks as validation for clap migration claims.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to a9da1

This PR reorganizes Rust migration documentation and preserves the old compatibility-page link through a redirect; no actionable merge-blocking risk remains beyond normal checks and review.

Poem

A rabbit checks each migration line,
Old clap maps now point to the sign.
Gaps and flags are clearly shown,
Conformance checks mark what’s known.
Hop, hop—the guide is now aligned!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: consolidating clap migration guidance in the Rust documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1 files. (3 skipped: 3 unsupported.)
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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	▁█████████████████	270,640,489 → 270,635,692	-0.00%	23.47 → 22.77ms	-2.97%
startup	▁▅▅▅▅█████████████	869,419 → 869,571	+0.02%	0.85 → 0.89ms	+4.23%

No instruction-count regression above 6%.

_{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	8425	—
argh	6307	0.7x
clap	6316290	749x
bpaf	21909019	2600x

                                              min       p01       p10    median
usage-rs: argv -> struct                      415       417       421       427  ns
argh: argv -> struct                          266       276       279       284  ns
clap: build tree + parse -> struct         509580    511382    521097    527560  ns
bpaf: build parser + parse -> struct      1576173   1576173   1587024   1632529  ns

usage: argv -> struct                             441 ns      0.44 µs
clap: build tree + parse -> struct             525434 ns    525.43 µs
clap: parse -> struct, tree reused              23223 ns     23.22 µs
clap: build tree only                          325541 ns    325.54 µs

_{a9da1828a103 vs 312df1ae9246 · measured on the runner, not pushed to the history.}