feat(docs): color process-facing help

[jdx]

Summary

• add automatic ANSI styling for process-facing help headings, usage literals, and flag names
• honor NO_COLOR and CLICOLOR_FORCE while retaining explicit plain/colored rendering APIs
• document the intentional boundary around clap custom style palettes and close the PLAN colour gap

Verification

• cargo test -p usage-argv --features diagnostics style_tests -- --nocapture
• cargo test -p usage-rs --test facade
• cargo clippy -p usage-argv --all-features -- -D warnings
• cargo clippy -p usage-rs --all-features -- -D warnings

This pull request was generated by Codex.

---

Note

Low Risk
Help-only presentation changes with explicit plain APIs preserved; behaviour is covered by new style tests and an extended missing-subcommand diagnostic test.

Overview
Process-facing help is now ANSI-coloured when stdout is a TTY, matching the existing diagnostic styling story: section headings, Usage: lines, synopsis literals, and flag spellings in option lists get selective colour while plain text stays byte-identical for pipes, tests, and generated docs via help::Style::PLAIN / COLOURED and Style::auto() (NO_COLOR, CLICOLOR_FORCE).

New render_styled / render_at_styled build the same page as before, then post-process with structure derived from the spec (help_structure, styled_flag_usage). usage-derive switches generated --help handling to Style::auto() instead of plain render / render_at. MissingSubcommand diagnostics use coloured short help when error rendering is coloured.

PLAN and clap-compatibility mark the colour gap closed and note that clap’s custom Command::styles palette is intentionally not reproduced.

^{Reviewed by Cursor Bugbot for commit f3ccb40. 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: c83d56c2-b05a-4a54-a67c-9c3de6133eac

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 → 207,877,991	+0.01%	19.31 → 20.02ms	+3.69%
startup	▃▁█	1,216,618 → 1,221,817	+0.43%	1.48 → 1.70ms	+15.28%

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	5895248	1356x
bpaf	21917778	5042x

                                              min       p01       p10    median
usage-rs: argv -> struct                      188       192       196       207  ns
argh: argv -> struct                          272       278       284       289  ns
clap: build tree + parse -> struct         475320    476708    479061    482982  ns
bpaf: build parser + parse -> struct      1579526   1579526   1586524   1597914  ns

usage: argv -> struct                             206 ns      0.21 µs
clap: build tree + parse -> struct             494103 ns    494.10 µs
clap: parse -> struct, tree reused              23536 ns     23.54 µs
clap: build tree only                          299066 ns    299.07 µs

_{f3ccb403720b 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 5e6e4b4. Configure here.}