test(cli): guard boolean-flag help across every command

[nh13]

Stacked on #703 — base is nh/cli-boolish-value-parser, not main. Review #703 first; the diff shown here is only the test and documentation work.

Closes out the review comments on #690 that #703 did not, now that switching to BoolishValueParser makes the precise version possible.

The problem with the guard as it stands

#690 added test_bool_args_name_their_accepted_values to sort.rs. It has two limits:

• It guards Sort alone, while the convention it enforces is repo-wide.
• It identifies boolean flags by the structural proxy num_args = 0..=1. An optional path or an optional count has that same shape, so the first non-boolean optional-value flag added to Sort would fail the test with a message instructing the author to declare value_name = "true|false" on it — wrong advice, produced confidently.

Against parse_bool there was no better option: clap keeps default_missing_vals private with no getter (clap_builder-4.6.2/src/builder/arg.rs:85), and ArgAction does not implement PartialEq (builder/action.rs:31), so neither discriminator was reachable.

What #703 unlocked

BoolishValueParser implements possible_values(), and Arg::get_possible_values() (builder/arg.rs:4320) surfaces it — all twelve literals, including the ten clap marks hidden. So is_boolish can now decide exactly whether a flag is a boolean instead of inferring it from shape.

That precision is what makes a repo-wide walk safe. The guard moves to src/main.rs and recurses from Args::command() through every subcommand, nested ones included: 44 flags across 19 commands instead of 3 on one. It walks the CLI itself rather than a parallel list, so it cannot drift from it.

Four tests, four halves of the contract

test	asserts
..._name_their_accepted_values	every boolean flag declares value_name = "true|false"
..._hide_their_partial_possible_values	every boolean flag sets hide_possible_values, so help never advertises true, false alone
..._render_an_optional_boolean_placeholder	the rendered help of every command owning a boolean flag actually contains [<true|false>]
..._top_level_help_names_every_accepted_spelling	the top-level note stays in sync with BOOLISH_LITERALS

The render test is not redundant with the declaration test. The placeholder also depends on num_args: changing 0..=1 to a required 1 would break bare --verify while still declaring the correct value_name, and only the render test sees that.

Vacuity guards, verified by mutation

Both guards in bool_flags() — a >= 40 floor and a check that the walk reached six named commands — exist because a test that walks an empty set passes. They were verified rather than assumed:

• stripping value_name from QueueMemoryOptions::memory_per_thread fails the declaration and render tests, naming fgumi extract --memory_per_thread;
• stripping hide_possible_values from the same flag fails the third.

Documenting the other ten spellings

The remaining #690 comment was that true|false names two of the twelve values the parser accepts, and that after #703 nothing in the CLI names the rest — clap's error is value was not a boolean, which does not enumerate.

I did not put this in each flag's doc comment, which is what that comment literally asked for. Forty-four copies of the same sentence is forty-four places to drift, and the sentence is a property of the shared parser rather than of any one flag. It is stated once in fgumi --help via after_help, once in the getting-started guide, and pinned to BOOLISH_LITERALS by the fourth test. Say the word if you want it per-flag instead.

Tests

cargo ci-fmt / ci-lint clean.

Risk: CLI help output changes only, pinned by repository-wide boolean-flag tests; unsafe changes: none; memory bounds, queue capacity, and thread/backpressure policy changes: none.

• Added recursive tests for 44 boolean flags across 19 commands.
• Documented accepted boolean spellings in top-level help and the getting-started guide.
• Moved validation from sort.rs to src/main.rs.
• cargo ci-fmt and ci-lint pass.

[coderabbitai]

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: d1a6d9b3-db9f-4a1f-a22b-59988c1ce8d5

📥 Commits

Reviewing files that changed from the base of the PR and between 38c12d8 and 249532d.

📒 Files selected for processing (2)

• src/lib/commands/sort.rs
• src/main.rs

---

Walkthrough

The CLI now documents accepted boolean flag spellings and optional values. Repository-wide tests validate boolean metadata, help placeholders, recursive command coverage, and bare flags. The getting-started guide documents the same behavior.

Changes

Boolean flag help and validation

Layer / File(s)	Summary
Boolean help contract src/main.rs, docs/src/guide/getting-started.md	Top-level help and the getting-started guide document accepted boolean spellings, case-insensitive parsing, optional values, and the true|false placeholder.
Repository-wide validation src/main.rs, src/lib/commands/sort.rs	Tests recursively inspect boolean flags across nested commands and verify metadata, rendered help, and bare-option parsing. Sort-specific validation is removed.

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

Possibly related PRs

• fulcrumgenomics/fgumi#690: Generalizes boolean-flag help and value-name validation from Sort to repository-wide coverage.

Suggested labels: fgumi sort, documentation

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses valid Conventional Commit syntax, a lowercase imperative description, and accurately describes the repository-wide boolean-flag help tests.
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.

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.03%. Comparing base (37be9b6) to head (249532d).

Files with missing lines	Patch %	Lines
src/main.rs	95.45%	4 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #704   +/-   ##
=======================================
  Coverage   94.03%   94.03%           
=======================================
  Files         178      178           
  Lines      108829   108899   +70     
=======================================
+ Hits       102340   102408   +68     
- Misses       6489     6491    +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nh13]

@coderabbitai pause

[coderabbitai]

✅ Action performed

Reviews paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main.rs`:
- Around line 72-76: Wrap the Rust documentation identifier BoolishValueParser
in backticks at all four affected sites: src/main.rs lines 72-76, 237-241,
265-270, and 340-345. No other documentation content needs to change.
- Around line 376-405: Expand
test_bool_args_render_an_optional_boolean_placeholder to iterate over each
boolean flag rather than only deduplicated command paths. For every flag,
resolve its command, assert help contains the optional [<BOOL_VALUE_NAME>]
placeholder, and parse the flag’s bare long option to verify it yields true.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4a87531c-f95c-4863-9ca8-d8cec9283c7e

📥 Commits

Reviewing files that changed from the base of the PR and between 2dbfbb7 and 38c12d8.

⛔ Files ignored due to path filters (1)

• CHANGELOG.md is excluded by !**/CHANGELOG.md

📒 Files selected for processing (20)

• docs/src/guide/getting-started.md
• src/lib/commands/clip.rs
• src/lib/commands/common.rs
• src/lib/commands/compare/bams.rs
• src/lib/commands/compare/metrics.rs
• src/lib/commands/correct.rs
• src/lib/commands/dedup.rs
• src/lib/commands/downsample.rs
• src/lib/commands/duplex_metrics.rs
• src/lib/commands/fastq.rs
• src/lib/commands/filter.rs
• src/lib/commands/group.rs
• src/lib/commands/review.rs
• src/lib/commands/simulate/common.rs
• src/lib/commands/simulate/consensus_reads.rs
• src/lib/commands/simulate/fastq_reads.rs
• src/lib/commands/simulate/grouped_reads.rs
• src/lib/commands/sort.rs
• src/lib/commands/zipper.rs
• src/main.rs

[nh13]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.