perf(cli): compile out advanced help and share layout code

[jdx]

Follow-up to #1396, #1399, and #1400 for the oxc migration binary-size work.

CLIs that omit help-advanced (oxlint/oxfmt) no longer compile flatten or recursive help. Fat LTO was still cloning section layout and unexpected-flag diagnostics; those now share one #[inline(never)] implementation each, the same pattern as the shared sorts. Plain help skips help_structure, which only exists to recognize colored spans.

Help text is intended to stay identical. Flattened and HelpAll pages still panic without the feature.

Validation: argv lib tests with and without help-advanced; usage-rs facade tests with completions; reduced-feature static_endpoint tests including the existing panic coverage. Clippy -D warnings on usage-argv --all-features.

Implemented with AI assistance.

---

Note

Low Risk
Changes are compile-time gating and internal refactors aimed at binary size and LTO; behaviour is covered by existing tests with and without help-advanced.

Overview
This PR shrinks binaries for CLIs built without help-advanced (e.g. oxlint/oxfmt) and reduces fat-LTO duplication in help and diagnostics.

Advanced help — Flattened help, recursive HelpAll rendering, and related helpers (flat_help_*, flat_commands_*, recursive_help, multi-line usage for flatten) are now behind #[cfg(feature = "help-advanced")]. Public render_all_* entry points return None when the feature is off instead of linking that code.

Plain help path — When output is not coloured, rendering skips help_structure entirely (it only collects spellings for styled span matching), using HelpStructure::default() instead.

Shared cold paths — Unknown-flag diagnostics for UnknownFlag and dash-prefixed UnexpectedArg share one #[inline(never)] unexpected_flag. split_groups_section takes slice + trait-object callbacks so LTO does not monomorphize a copy per args/flags section; several layout helpers (entry, wrap, etc.) are also #[inline(never)].

Behaviour — Intended help/error text stays the same; advanced pages still require help-advanced (and panic when invoked without it where documented).

^{Reviewed by Cursor Bugbot for commit 00a9b93. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes

  • Standardized handling of unexpected flags and dash-prefixed arguments, including near-match suggestions in error messages.

• Refactor

  • Improved the consistency and efficiency of help and diagnostic message rendering without changing the available public interfaces.

• Tests

  • Updated coverage for advanced help rendering and feature-specific behavior.

[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: Team

Run ID: d3ae3d1f-a636-47af-b96e-bfce010cce5b

📥 Commits

Reviewing files that changed from the base of the PR and between 19aa045 and 00a9b93.

📒 Files selected for processing (2)

• argv/src/diagnostic.rs
• argv/src/help.rs

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

---

📝 Walkthrough

Walkthrough

The change centralizes unexpected-flag diagnostics and updates help rendering with advanced-feature gates, generalized grouping callbacks, reduced monomorphization, and feature-specific tests.

Changes

Diagnostic rendering

Layer / File(s)	Summary
Unexpected flag rendering argv/src/diagnostic.rs	A shared unexpected_flag helper now renders the message and near-miss suggestions for both relevant diagnostic paths.

Help rendering

Layer / File(s)	Summary
Advanced help feature gates argv/src/help.rs	Flattened and recursive help paths now require help-advanced; unsupported builds return None after the feature check.
Help grouping interface argv/src/help.rs	split_groups_section now accepts slices and borrowed dynamic callbacks. Short and long help call sites use the updated interface.
Help rendering optimization and validation argv/src/help.rs	Selected helpers are marked #[inline(never)]. Plain output avoids help metadata construction. Advanced-only tests and imports are feature-gated.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 00a9b

The help and diagnostic changes preserve expected behavior across supported feature configurations, with no actionable merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 36 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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 primary changes: compiling out advanced help and sharing layout code for performance.
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.

• Fix all pre-merge checks with AI

---

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	▁▁▁▁███	388,207,469 → 388,246,775	+0.01%	65.74 → 65.56ms	-0.28%
startup	▁▁▁▁█▇▄	1,012,327 → 983,597	-2.84%	1.45 → 1.37ms	-4.98%

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	stripped binary, bytes
usage	1344904
bpaf	2493216
clap	3101656

framework	instructions, cold parse	vs usage
usage	8374	—
clap	6314655	754x
bpaf	21909025	2616x

                                              min       p01       p10    median
usage-rs: argv -> struct                      749       752       755       765  ns
clap: build tree + parse -> struct        1241213   1244682   1252814   1270548  ns
bpaf: build parser + parse -> struct      3374892   3374892   3422088   3472014  ns

usage: argv -> struct                             743 ns      0.74 µs
clap: build tree + parse -> struct            1264654 ns   1264.65 µs
clap: parse -> struct, tree reused              50608 ns     50.61 µs
clap: build tree only                          750435 ns    750.43 µs

_{00a9b93f0da6 vs 19aa045f0b1d · measured on the runner, not pushed to the history.}