fix(cli): add regression tests for argparse -f conflict (closes #174)

[Wolfvin]

What

Adds regression tests + defensive comment for the argparse -f conflict bug reported in issue #174.

Why

Issue #174 reported a P0 crash: every codelens CLI invocation failed with:

argparse.ArgumentError: argument --format/-f: conflicting option string(s): -f

Root cause: The global parser registers --format/-f (line ~934). Subparsers also register --format/-f via a loop that adds the format flag to every subparser. A guard checks existing_option_strings before adding -f to a subparser, so commands like affected (issue #62, uses -f for --filter) don't conflict. PR #153 (graphml, issue #59 Phase 3) accidentally dropped this guard, breaking every CLI invocation.

Timeline:

• Bug introduced: PR feat(formatters): GraphML XML export for graph-producing commands (closes #59 phase-3) #153 (graphml export) dropped the existing_option_strings guard
• Bug fixed: commit 23487af (fix [FIX] PR #141: missing @WHO header on baseline_diff.py + wrong command count #171) restored the guard — merged at 2026-07-03T03:30:25Z
• Issue [BUG] argparse -f conflict: --diff-base PR introduced global --format/-f that clashes with subparser --format/-f #174 created: 2026-07-03T03:30:10Z (14 seconds before the fix merged — a race between BOS creating the issue and the worker merging the fix)

The bug is already fixed on main. This PR prevents it from regressing by:

1. Adding a defensive comment explaining why the guard is critical
2. Adding 7 regression tests that lock the behavior

Files touched

• scripts/codelens.py — defensive comment (9 lines added at lines 896-904) explaining why the existing_option_strings guard is critical, referencing the regression test. No code logic changed.
• tests/test_cli.py — new TestArgparseFormatConflictRegression class with 7 tests (129 lines added)
• README.md, SKILL-QUICK.md, SKILL.md, pyproject.toml, scripts/graph_model.py, skill.json — command count sync 76→77 (pre-existing drift caught during testing, fixed via sync_command_count.py --apply)

Verification

New regression tests — 7 passed

tests/test_cli.py::TestArgparseFormatConflictRegression::test_help_does_not_crash PASSED
tests/test_cli.py::TestArgparseFormatConflictRegression::test_command_count_does_not_crash PASSED
tests/test_cli.py::TestArgparseFormatConflictRegression::test_scan_with_format_long_does_not_crash PASSED
tests/test_cli.py::TestArgparseFormatConflictRegression::test_scan_with_format_short_does_not_crash PASSED
tests/test_cli.py::TestArgparseFormatConflictRegression::test_affected_with_filter_short_does_not_crash PASSED
tests/test_cli.py::TestArgparseFormatConflictRegression::test_parser_construction_no_argparse_error PASSED
tests/test_cli.py::TestArgparseFormatConflictRegression::test_no_duplicate_f_in_subparsers PASSED

Regression check — 142 passed, 0 failed

tests/test_cli.py + tests/test_doctor.py + tests/test_command_count.py +
tests/test_command_registry.py + tests/test_formatters.py
142 passed in 19.25s

Definition of Done (issue #174)

• codelens --help runs without error
• codelens scan . --format json runs without argparse error
• codelens scan . -f json works
• test_cli.py and test_doctor.py pass (82 passed: 75 existing + 7 new)
• No regression on --diff-base functionality (verified: codelens scan . --diff-base HEAD~1 reports 11 files in scope)

Findings

• Bug was already fixed on main. Commit 23487af (fix [FIX] PR #141: missing @WHO header on baseline_diff.py + wrong command count #171, merged 2026-07-03T03:30:25Z) restored the existing_option_strings guard that PR feat(formatters): GraphML XML export for graph-producing commands (closes #59 phase-3) #153 had accidentally dropped. Issue [BUG] argparse -f conflict: --diff-base PR introduced global --format/-f that clashes with subparser --format/-f #174 was created 14 seconds before the fix merged — a race condition between BOS creating the issue and the worker merging the fix. The bug is not reproducible on current main.
• Pre-existing command count drift. Docs had 76 commands but runtime had 77 (the orient command from PR feat(orient): 10-second codebase orientation brief (closes #160) #165 was merged but docs weren't synced). Fixed via sync_command_count.py --apply. This is unrelated to issue [BUG] argparse -f conflict: --diff-base PR introduced global --format/-f that clashes with subparser --format/-f #174 but was caught during testing.
• The guard is fragile. The fix relies on a single if "-f" not in existing_option_strings check. If a future PR refactors the subparser registration loop and drops this check, the bug will return. The regression test test_no_duplicate_f_in_subparsers iterates 5 commands' --help output and asserts no conflicting option string appears — this should catch any future regression at test time.

Issue link

Closes #174 — #174

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud