feat(help): line the flag column up, and give the short page a column at all

[jdx]

PR 1 of the help plan. Two findings from putting communique's help next to clap's.

The long forms did not line up

Everything started at column 2:

Flags:
  --github-release           Push editorialized notes to the GitHub release
  -n --dry-run               Generate notes without updating GitHub
  --repo <REPO>              GitHub repo in owner/repo format

clap spends a four-character column on -n, — or the blank standing in for it:

Flags:
      --github-release           Push editorialized notes to the GitHub release
  -n, --dry-run                  Generate notes without updating GitHub
      --repo <REPO>              GitHub repo in owner/repo format

Measured from clap 4, including the two rules that are easy to get wrong:

• The column is only spent where there is a long form to line up with. -j <JOBS> writes at the indent and does not pad — that is clap's behaviour, not an oversight in it.
• A flag whose declared name the forms do not imply — verbose: -v, which clap has no equivalent for — takes that same path.

The short page had no column at all

This is the one I did not plan for and think matters more. -h was:

Flags:
  --github-release  Push editorialized notes to the GitHub release
  --changelog  Update CHANGELOG.md with the generated changelog entry
  -n --dry-run  Generate notes without updating GitHub or verifying links

Every description began directly after the name it belonged to, so nothing in -h lined up with anything — and -h is the form most people type. It now computes one column per section over its visible entries, the rule the long page already followed.

Result

communique generate -h is now byte-for-byte clap's output except the word Flags:, which is the difference we chose to keep:

Arguments:
  <TAG>       Git tag to generate release notes for
  [PREV_TAG]  Previous tag (auto-detected if omitted)

Flags:
      --github-release           Push editorialized notes to the GitHub release
  -n, --dry-run                  Generate notes without updating GitHub or verifying links
      --max-tokens <MAX_TOKENS>  Max response tokens

Notes

Built as column_usage, separate from flag_usage which feeds the usage line — Usage: ex [ --describe] would be absurd, and a test says so. In usage-lib the same split lives beside display_usage, which only the two CLI help templates read; SpecFlag::usage() is untouched, so markdown and manpage are unaffected.

Landed in both renderers, so the gate still holds them byte-identical over mise's 211 commands.

Verification

mutation	result
no short column	FAILED
a short-only flag pays for the column	FAILED
no comma	FAILED
the short page stops padding	FAILED

Snapshots accepted where the change is the intended one (descriptions moving into a column); two lib/tests/parse.rs expectations updated for the same reason. Workspace suite green, clippy clean.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

---

Note

Low Risk
Presentation-only help formatting in two renderers; parsing and spec usage() for markdown/man are unchanged aside from aligned CLI help text.

Overview
Help output is updated so flag sections match clap 4 layout: a fixed four-character short column (-n, or blank), long -- options starting in one column, and short-only flags like -j <JOBS> left unpadded. That logic lives in new column_usage, separate from usage-line flag_usage so Usage: stays compact.

Short help (-h) now pads Arguments and Flags into per-section columns (max visible entry width + two spaces before help), matching what long help already did. Empty help text skips padding.

usage-lib applies the same column_usage for SpecFlag::display_usage, uses it for column-width math, and updates short/long Tera templates (ljust on args/flags). Snapshots and parse help expectations reflect the new spacing.

Conformance adds flag_column.rs tests (alignment, comma, short-only, short-page columns, unpadded usage line).

^{Reviewed by Cursor Bugbot for commit 5a8febf. 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: 1020f0f1-d744-430c-9345-f4e6ad45ef67

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

[greptile-apps]

Greptile Summary

This PR aligns flag forms into a clap-style short/long column and adds per-section description columns to short help.

• Adds parallel column_usage formatting to the compiled and usage-lib renderers.
• Updates short and long CLI-help templates, snapshots, parse expectations, and conformance coverage.

Confidence Score: 4/5

The PR is not yet safe to merge because whitespace-only help still produces divergent output between the two CLI-help renderers.

The short Tera template checks raw help-string truthiness, while the argv renderer trims before checking emptiness, so equivalent whitespace-only metadata continues to break the renderer-parity contract.

Files Needing Attention: lib/src/docs/cli/templates/spec_template_short.tera

Important Files Changed

Filename	Overview
argv/src/help.rs	Adds short-help column sizing and clap-style flag-column formatting while preserving trimmed empty-help handling.
lib/src/docs/models.rs	Computes display-only flag usage with a fixed short-form column for CLI-help templates.
lib/src/docs/cli/templates/spec_template_short.tera	Adds short-help padding, but the previously reported whitespace-only help parity defect remains.
lib/src/docs/cli/templates/spec_template_long.tera	Preserves leading flag-column padding by removing the final trim operation.
conformance/tests/flag_column.rs	Covers long-form alignment, commas, short-only flags, short-page columns, and compact usage lines.

_{Reviews (2): Last reviewed commit: "feat(help): line the flag column up, and..." | Re-trigger Greptile}

[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 5d0d943. Configure here.}