refactor(cli): cross-subcommand parity (only-filter naming, --output/--strip-prefix on diff family)

[dekobon]

Decided (2026-06-05): standardize on --<section>-only (rename exemptions' --only-*, hidden alias 1 cycle) — breaking, 2.0. Add --output/-o + --strip-prefix to the diff family additively, pre-2.0 (batch-fixable). See the resolved-decisions comment.

Summary

Cross-subcommand inconsistencies in the bca CLI grammar. Each is a breaking
flag change → 2.0.

Findings

1. --*-only vs --only-* section-filter naming. The two sibling read-only
   reporters disagree on word order:

   • diff-baseline: --added-only / --removed-only / --worsened-only /
     --improved-only (big-code-analysis-cli/src/lib.rs:796)
   • exemptions: --only-markers / --only-excludes / --only-baseline
     (big-code-analysis-cli/src/lib.rs:896)
     A user who learns --added-only will guess --markers-only. Pick one
     convention for both; add the old spelling as a hidden alias for one cycle.

2. Output destination not uniform. --output/-o exists on
   metrics/ops/report/check/preproc/exemptions but not on diff
   or diff-baseline, which unconditionally write stdout
   (commands.rs write_stdout_or_die). Adding -o is additive (could ship in
   1.x), but the contract "every emitting subcommand accepts -o, stdout if
   omitted" is worth establishing deliberately at 2.0.

3. --strip-prefix missing from the diff family. Present on report
   (lib.rs:391) and exemptions (lib.rs:894); absent from diff /
   diff-baseline, whose markdown output is meant for PR comments where long
   paths are exactly the noise --strip-prefix removes.

Why 2.0-worthy

Item 1 is a rename (breaking). Items 2–3 are additive in isolation but should be
locked into a uniform "every reporter subcommand shares the same output/path
flags" contract at the major bump. (Distinct from #513 output-format selection
and #518 --ls/--le.)

Acceptance

• Section-filter flags use one consistent word order across diff-baseline and
  exemptions.
• diff / diff-baseline accept --output/-o and --strip-prefix.

Part of the pre-2.0 review (#505).

Resolution

Resolved in commit 66e52cbb on branch fix/issue-538 (integration
fix/batch-2026-06-06).

The exemptions section filters were renamed to the
--<section>-only suffix idiom (--markers-only / --excludes-only /
--baseline-only), matching the existing diff-baseline filters. The
prior --only-* spellings remain as hidden clap aliases for one
release cycle (clap alias = "...", which is excluded from --help).
The Rust fields were renamed to match (internal, non-breaking). Man
pages regenerated; book docs updated with a deprecated-alias note.

This is a breaking CLI flag rename deferred to 2.0; recorded in
CHANGELOG.md [Unreleased] marked (breaking) by the orchestrator.

The additive --output / --strip-prefix parity that was originally
bundled with this issue is split out to #544 and is not part of this
change.

[dekobon]

Resolved decisions (2026-06-05)

1. Section-filter naming → --<section>-only everywhere. Standardize on the
suffix idiom. diff-baseline already uses it (--added-only/--removed-only/
--worsened-only/--improved-only), so only exemptions is renamed:
--only-markers→--markers-only, --only-excludes→--excludes-only,
--only-baseline→--baseline-only. Keep the old --only-* spellings as
hidden aliases for one cycle. The rename is the only breaking part → 2.0.

2. --output/-o + --strip-prefix on the diff family → land additively,
pre-2.0. Add both to diff and diff-baseline in a normal minor release
(purely additive, no break), establishing the "every emitting reporter accepts
-o (stdout if omitted) and --strip-prefix" contract. Document the universal
stdout-if-omitted behavior.

Split for scheduling: the additive flag work (item 2) can go now and is
batch-fixable (self-contained, non-breaking, no decision left). The alias
rename (item 1) stays 2.0-gated. Consider splitting this issue into a pre-2.0
"add diff-family output/strip-prefix flags" task and a 2.0 "rename section
filters" task.

[dekobon]

Split: the additive / parity slice is now tracked separately as #544 (pre-2.0, batch-fixable). This issue (#538) retains only the breaking --only-*→--*-only section-filter rename for 2.0.

[dekobon]

Split: the additive --output/--strip-prefix parity slice is now tracked
separately as #544 (pre-2.0, batch-fixable). This issue (#538) retains only the
breaking --only-* → --*-only section-filter rename, on the 2.0 milestone.

[dekobon]

Done — section-filter rename (breaking, deferred to 2.0)

Per the 2026-06-05 decision, standardized the exemptions subcommand
on the --<section>-only suffix idiom already used by diff-baseline:

• --only-markers → --markers-only
• --only-excludes → --excludes-only
• --only-baseline → --baseline-only

Hidden one-cycle aliases. The old --only-* spellings stay as clap
alias = "..." aliases. clap's alias (vs visible_alias) is omitted
from --help, which is exactly the desired behavior — verified by a
test that parses exemptions --help and asserts the old spellings never
appear as their own option entry.

Internal field rename. The Rust fields only_markers /
only_excludes / only_baseline were renamed to markers_only /
excludes_only / baseline_only (non-breaking, internal) so the
struct matches the new canonical flags; conflicts_with_all string refs
and the dispatch in commands.rs were updated to match.

Changes

• big-code-analysis-cli/src/lib.rs — three flag renames + hidden aliases, doc comment
• big-code-analysis-cli/src/commands.rs — field references in run_command_exemptions
• big-code-analysis-cli/tests/exemptions.rs — tests for new flags, alias parity, hidden-from-help, mutual exclusion (canonical+alias)
• man/bca-exemptions.1 — regenerated via cargo xtask (drift gate clean)
• big-code-analysis-book/src/commands/suppression.md, .../recipes/baselines.md — docs + deprecated-alias note

Tests

cargo test -p big-code-analysis-cli --test exemptions: 16 passed.
Full cargo test --workspace --all-features green. clippy
(--workspace --all-targets --all-features -D warnings) clean. fmt
clean. Man-page drift gate (cargo xtask && git diff --exit-code -- man/) clean.

Scope note

The additive --output / --strip-prefix parity work is tracked
separately in #544 and is not touched here.

CHANGELOG (orchestrator consolidates)

(breaking) bca exemptions: section filters renamed to the
--<section>-only idiom (--markers-only / --excludes-only /
--baseline-only), matching diff-baseline. The old --only-*
spellings remain as hidden aliases for one release cycle. Deferred to
2.0.

Commit: 66e52cbb