fix(help): a declared name is not a short form, and blank help is no help

[jdx]

Two findings against the flag column from #912, both from review.

A declared name is not a short form

A flag may carry a name the forms do not imply — jobs: -j --parallel — and the split treated that whole prefix as the thing to put a comma after. The joined string is already wider than the column being padded to, so the padding did nothing and the space vanished:

  jobs: -j,--parallel  how many

Only a bare -x goes in the short column now; anything else keeps the shape it had:

  jobs: -j --parallel  how many

A description of only spaces is no description

usage-argv filters a blank description wherever it reads one. The template asked only whether the string was there, and Tera counts " " as present — so help=" " bought a column of padding and a line of trailing spaces on one side and nothing on the other.

Two renderings of one spec, which is exactly what the gate exists to prevent and could not see: mise's spec has no such flag. Normalised where the docs model is built, so every renderer downstream gets one answer.

Verification

mutation	result
the name prefix is split again	FAILED
blank help counts as help	FAILED

The second survived at first: my test found --blank on the usage line, which contains the flag and has no padding to get wrong. Scoped to the flags section, it fails properly. Same trap caught me on #913's tests — worth remembering that a page names its flags twice.

Found by Cursor Bugbot and greptile.

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

[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: Pro Plus

Run ID: e3ab6a20-d3c6-490c-b754-3c0692ac6598

📥 Commits

Reviewing files that changed from the base of the PR and between 1cf68f3 and e8a0465.

📒 Files selected for processing (4)

• argv/src/help.rs
• conformance/tests/flag_column.rs
• lib/src/docs/cli/mod.rs
• lib/src/docs/models.rs

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

---

📝 Walkthrough

Walkthrough

Help formatting now preserves nonstandard option prefixes and removes whitespace-only descriptions. New tests cover rendered output in short and long modes, declared option names, and parsed values.

Changes

Help rendering corrections

Layer / File(s)	Summary
Normalize help models and option columns lib/src/docs/models.rs, argv/src/help.rs	Whitespace-only help text becomes absent. Column formatting aligns only bare short options and preserves other usage strings.
Verify rendered help and parsing conformance/tests/flag_column.rs, lib/src/docs/cli/mod.rs	Tests cover declared-name rendering, comma-free option output, trimmed blank descriptions, short and long help modes, and parsed values.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to e8a04

This localized documentation, help-output, and conformance-test change has no actionable merge-blocking risk remaining and is merge-ready after normal checks and review.

Poem

A rabbit checks the flags in line,
No stray blank tails remain to shine.
Odd names keep their proper space,
Short and long modes show good grace.
Values bind, and help looks neat.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes both main fixes: declared names are not short forms, and whitespace-only help is treated as absent.

---

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 fixes help-column formatting for flags whose declared names differ from their forms and normalizes whitespace-only flag and argument descriptions.

• Restricts short-column alignment to bare short forms in both help-rendering implementations.
• Treats whitespace-only flag and argument help as absent in the shared docs model.
• Adds conformance and renderer tests for declared names, blank descriptions, and argument binding.

Confidence Score: 5/5

The PR appears safe to merge with no actionable correctness or security issues identified.

The two help renderers apply equivalent column rules, and blank-help normalization preserves meaningful long and markdown help fallbacks while removing only whitespace-only descriptions.

Important Files Changed

Filename	Overview
argv/src/help.rs	Tightens short-column detection while preserving valid long-only, short-plus-long, and short-only display forms.
conformance/tests/flag_column.rs	Adds focused regression coverage for declared flag names, whitespace-only descriptions, and parser bindings.
lib/src/docs/cli/mod.rs	Adds short- and long-help regression coverage ensuring blank descriptions do not introduce trailing whitespace.
lib/src/docs/models.rs	Keeps docs-model column formatting aligned with usage-argv and normalizes whitespace-only flag and argument help.

_{Reviews (1): Last reviewed commit: "fix(help): two the flag column got wrong" | Re-trigger Greptile}

[github-actions]

Instruction counts

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.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.

	usage	clap	ratio
instructions, cold parse	72156	5893576	81x

usage: argv -> struct                            1259 ns      1.26 µs
clap: build tree + parse -> struct             519843 ns    519.84 µs
clap: parse -> struct, tree reused              24248 ns     24.25 µs
clap: build tree only                          311258 ns    311.26 µs

_{e8a04657fb3e vs d80622f7018d · measured on the runner, not pushed to the history.}