Validate conflicting short flags in command signatures (#400)

[warp-factories]

Summary

Implements #400: detect duplicate short flags claimed by two or more distinct option entries directly authored on the same handwritten command or subcommand.

• Adds warp_completion_metadata::validation::find_short_flag_conflicts, a recursive validator over fig_types::Command (before conversion into Signature, since conversion loses source option boundaries and copies persistent options into descendants). Each command/subcommand node is an independent namespace, so sibling subcommands and a parent/child may reuse a short flag.
• Option names are normalized with the same html_unescape used by From<CommandOption> for Opt before being classified by the existing (now pub(crate)) is_short_hand_flag, so an authored -h and a literal -h are recognized as the same flag. Diagnostics show the normalized flag alongside the raw authored name arrays and one-based positions, e.g.:
  command-signatures/json/flutter.json: command "flutter assemble": duplicate short flag "-d" is used by options #1 ["-d", "--device-id"] and #3 ["-d", "--define"]
• Adds a repository invariant test in warp-command-signatures (command-signatures/src/lib.rs) that scans only the top-level handwritten command-signatures/json/*.json files (excluding autogenerated/ and overrides/) and compares the collected conflicts against a temporary, exact baseline allowlist of the 45 pre-existing conflicts across 13 files.
• The baseline comparison is against complete records — (file, canonical command path, normalized short flag) plus the ordered claimant list of source indices and raw name arrays — not just the key. Adding a claimant, removing one, reordering options, or swapping a claimant fails even when (file, command path, flag) is unchanged. Two dedicated regression tests exercise the comparison function directly with a synthetic third-claimant case and a synthetic swapped-claimant case.
• Focused fixture coverage lives under completion-metadata/tests/fixtures/duplicate_short_flags/ and is exercised by completion-metadata/tests/duplicate_short_flags.rs, covering all the valid/invalid cases from the spec (distinct flags, identical name arrays, three claimants, nested subcommands, internal repetition, HTML-escaped vs. literal spellings, parent/child and sibling reuse, unrelated top-level fixtures, short+long alias on one option, single-dash long names, and multi-alias command namespaces).
• Opened a dedicated follow-up issue, Reduce the duplicate short-flag baseline allowlist to zero #402, to track shrinking the baseline to zero, and linked it from the baseline's doc comment.

Does not touch any of the 45 existing offending command specs; cleanup is tracked separately in #402 per the approved spec's rollout plan.

Fixes #400.

Validation

Ran with a locally installed Rust toolchain (this sandbox does not ship one by default) and Node/npm for the prettier check:

• script/presubmit — passed (npm format:check, cargo fmt --check, cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings, cargo test --verbose, all green; 182 tests in warp-command-signatures including the new invariant/regression tests, 12 + 13 tests in warp-completion-metadata)
• cargo build --workspace
• cargo test --workspace
• cargo fmt --check
• cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings

The re-derived conflict inventory matches the spec's expected baseline exactly: 45 conflicts across 13 files (brew 2, copilot 27, flutter 2, kubecolor 1, kubectl 1, oc 1, pscale 2, pulumi 1, rsync 1, sfdx 1, stripe 4, yarn 1, zapier 1).

[warp-factories]

This PR was generated with Warp.

Comment @warp-factory on this PR to send it follow-up work.

  

[warp-factories]

Spec approved. This specification covers issue #400, and the spec stage is now complete.

Implementation remains gated: a maintainer can apply ready-to-implement on #400 and assign @warp-factory to start it. Merging this PR stays a human decision.

Responding as Warp for OSS: Open session · View run

[warp-factories]

Overview

Adds a short-flag conflict validator for handwritten command signatures, wired into the existing invariant tests that script/presubmit and CI already run, with a frozen 45-record baseline so the current offenders do not break main while new conflicts fail immediately. Net position: accepted.

Verdict

Verdict: accepted

Checks: build pass (author-run; cargo unavailable in the review sandbox), tests pass (author-run: 183 tests in warp-command-signatures, 12 unit + 13 integration in warp-completion-metadata), CI green with Rust CodeQL still in progress and nothing failing, visual proof n/a

Found: 0 critical, 0 important, 0 suggestions, 0 nits

Two earlier passes found and closed three issues: the baseline originally compared bare keys and so missed a claimant added under an existing conflict; validation originally ran on raw names, missing that From<CommandOption> for Opt unescapes before is_short_hand_flag classifies, so -h and -h would not have collided; and the invariant's own failure output rendered zero-based debug tuples instead of the actionable diagnostic. All three are fixed. All 45 baseline records were independently cross-checked against the handwritten JSON — no missing keys, no stale keys, no claimant mismatches — and namespace isolation for siblings, parent/child, and separate roots was verified.

Responding as Warp for OSS: Open session · View run