feat(help): add semantic command styling

[jdx]

Summary

• add a command semantic help style with bold green defaults
• color visible subcommand names and the synthetic help row in both Rust renderers
• keep the derive, KDL, Go, and shared conformance vocabularies aligned
• document the semantic palette

Closes #1374

Tests

• cargo test --workspace --all-features --exclude gate
• cargo clippy --all --all-features --all-targets -- -D warnings
• focused usage-lib, usage-argv, and help-template conformance tests
• cargo fmt --all -- --check
• npx --yes prettier@latest -w docs/rust/help.md docs/spec/reference/index.md

The full local gate could not run because this machine has mise 2026.6.13 while the repository requires 2026.8.16; Go and a few shell integration dependencies are also supplied by that managed toolchain.

This pull request was generated by Codex.

---

Note

Low Risk
Help presentation-only changes with no parsing or spec behavior impact; plain and generated artifacts stay compatible.

Overview
Coloured terminal help now highlights subcommand names (and the built-in help row when shown) with a new command semantic style—bold green, same palette family as options. Plain output is unchanged; stripping ANSI still yields byte-identical pages.

Both render paths pick this up: usage-argv collects command_usages in a refactored HelpStructure and applies them in styled_help with row-aware matching (two-space table separator), so command-group prose like build these projects… is not mistaken for a command row. usage-lib mirrors the same logic in Styling, including skipping command names under flatten_help.

{$command}…{/$} is added to the closed help-template style vocabulary everywhere it is validated—derive, corpus, Go HelpStyles, and shared template parsers—and docs note that heading, option, metavar, and command are the semantic tags.

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

Summary by CodeRabbit

• New Features

  • Added command-specific styling to help output, rendering subcommands and the built-in help command in bold green when color is enabled.
  • Added command as a supported help-template style.

• Bug Fixes

  • Prevented ordinary group prose and flattened help text from being incorrectly styled as commands.

• Documentation

  • Updated help-template references to document command styling and its default appearance.

• Tests

  • Expanded coverage for styled command rows, prose handling, and the new template style.

[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: 2ad7afba-0d52-4d89-ba64-d1174d8af0a8

📥 Commits

Reviewing files that changed from the base of the PR and between 1c6df06 and 07d0dbd.

📒 Files selected for processing (3)

• argv/src/help.rs
• lib/src/docs/cli/mod.rs
• lib/src/docs/cli/style.rs

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

---

📝 Walkthrough

Walkthrough

The help system adds a command semantic style. It collects visible subcommands, including the optional help command, and renders command rows in bold green coloured output. Template vocabularies, validation, tests, and documentation now include the style.

Changes

Command help styling

Layer / File(s)	Summary
Command style contract argv/src/help/template.rs, lib/src/help_template.rs, derive/src/model.rs, go/argv/sections.go, corpus/help-template-styles.txt, conformance/tests/help_template.rs, docs/...	The command style is added to template vocabularies and validators. ANSI rendering uses bold green. Documentation and fixtures cover the new style.
Generated help command rendering argv/src/help.rs	Help generation records visible command usages and passes them to rendering. Matching command rows receive the command style. Tests cover coloured output and unchanged plain output.
CLI styling integration lib/src/docs/cli/style.rs, lib/src/docs/cli/mod.rs	CLI styling collects direct subcommands and the optional help command. Matching rows receive command styling. Integration tests verify command rows, group prose exclusion, and flattened-help behavior.

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

Merge Risk: ⚪ Minimal · up to 07d0d

Visible command rows, including the optional help row, now use the configurable bold-green command style while prose and flattened help remain unchanged. No concrete current-head merge risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant render_help_styled
  participant Styling
  participant styled_help
  participant HelpOutput
  render_help_styled->>Styling: pass show_help_subcommand
  Styling->>Styling: collect and sort command_usages
  render_help_styled->>styled_help: pass command_usages
  styled_help->>HelpOutput: render matching rows with command style

Loading

Poem

A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 8 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: adding semantic styling for commands in help output.
Linked Issues check	✅ Passed	The pull request satisfies issue #1374 by making subcommands themable, adding the command semantic style with a bold green default, and applying it to visible subcommand rows and the synthetic help ro…
Out of Scope Changes check	✅ Passed	The changes remain within scope. Renderer updates, style vocabulary updates, tests, conformance data, documentation, and Go support all directly support command styling.

• 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.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1c6df06. Configure here.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁█	380,410,350 → 386,448,609	+1.59% ⚠️	62.78 → 64.74ms	+3.12%
startup	▁█	947,710 → 957,270	+1.01% ⚠️	1.16 → 1.19ms	+2.43%

2 benchmark(s) above the 1% gate: markdown +1.59%, startup +1.01%

_{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	1344744
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                     1182      1212      1224      1230  ns
clap: build tree + parse -> struct        1796714   1798446   1805940   1816028  ns
bpaf: build parser + parse -> struct      5578322   5578322   5591018   5630840  ns

usage: argv -> struct                            1233 ns      1.23 µs
clap: build tree + parse -> struct            1832778 ns   1832.78 µs
clap: parse -> struct, tree reused              72371 ns     72.37 µs
clap: build tree only                         1057886 ns   1057.89 µs

_{07d0dbd4ea37 vs 4d51490c3626 · measured on the runner, not pushed to the history.}