perf(cli): avoid color analysis for plain help

[jdx]

Plain help currently builds the headings and spellings used to recognize colored spans, then discards them. Skip that work when color is disabled, and share the duplicated invalid-flag diagnostic formatting. Extend the timing tool to cover the process renderer in both plain and colored modes.

Paired local mise measurements: plain process help 42.15 → 34.68 µs (-18%), recursive help 4.88 → 3.36 ms (-31%). Colored help remains roughly unchanged. These are wall-clock measurements, not instruction counts.

Machine code shrinks by 2,896 B across the oxc binaries, but Mach-O alignment leaves only 32 B of combined on-disk savings. With the preceding size changes:

Stripped binary	bpaf	usage-rs (no bpaf)
oxlint	12,421,856 B	12,587,296 B (+1.33%)
oxfmt	5,044,368 B	5,143,328 B (+1.96%)

Same arm64 macOS / Rust 1.98.1 release configuration and strip/sign procedure as #1400, including the optional-feature/embedded-spec configuration from #1399.

Validation: the 733,411-byte help dump and 56 oxc process comparisons (plain and forced color) match exactly. Full Clippy, Rust 1.91, reduced-feature tests, formatting and spelling of added text pass. Full workspace tests: 2,725 passed; only the previously reproduced local zsh completion timeout failed.

Implemented with AI assistance.

---

Note

Low Risk
Output-preserving performance refactor in help and error formatting; behavior is validated by byte-identical help dumps and diagnostic tests.

Overview
Plain --help no longer builds the heading/flag/argument spellings used only to paint colored spans. Styled rendering still runs help_structure when style.coloured is true; otherwise it passes an empty HelpStructure so recursive and process help avoid that work without changing bytes on the wire.

Invalid long-flag diagnostics are deduplicated into a shared unexpected_flag helper used for both UnknownFlag and dash-prefixed UnexpectedArg, keeping the same clap-style message and Jaro-based tips.

The help timing bench now measures process render_styled in plain and colored modes alongside the existing paths.

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

Summary by CodeRabbit

• Bug Fixes

  • Improved consistency of unknown-flag and unexpected-argument messages, including normalized flag names and relevant suggestions.

• Performance

  • Reduced unnecessary help-formatting work when displaying plain, uncolored help output.

• Tests

  • Added coverage for rendering root help in both plain and colored styles, including process-based rendering.

[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: b82f38c4-99e5-4ed7-8a54-d81955e1bc59

📥 Commits

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

📒 Files selected for processing (3)

• argv/src/diagnostic.rs
• argv/src/help.rs
• benches/gate/src/bin/time-help.rs

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

---

📝 Walkthrough

Walkthrough

The changes centralize unexpected-flag diagnostics, avoid building help styling metadata for plain output, and add process-rendered help benchmarks for plain and colored styles.

Changes

Diagnostics and Help Rendering

Layer / File(s)	Summary
Shared unexpected-flag diagnostics argv/src/diagnostic.rs	The private unexpected_flag helper now formats unexpected arguments and generates scoped suggestions. UnknownFlag and dash-prefixed UnexpectedArg use the helper.
Conditional help rendering and benchmarks argv/src/help.rs, benches/gate/src/bin/time-help.rs	HelpStructure derives Default. Plain help uses the default structure without computing styling spans. Benchmarks cover plain and colored process-rendered root help.

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

Merge Risk: ⚪ Minimal · up to 19980

Plain help rendering avoids unnecessary styling analysis while colored rendering and unexpected-flag diagnostics retain their existing behavior. Reported validation and coverage indicate no current merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 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 main change: skipping color analysis during plain help rendering. It matches the primary objective of the pull request.
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.}