Add a qual crate that diffs rustqual findings by identity

• Status: Todo
• Kind: Feature
• Authors: jp
• Date: 2026-10-06
• Label: domain=tooling
• Label: type=task

A new internal crate, crates/internal/qual, that turns rustqual reports into individual findings, compares two reports, and renders the result. CI, cargo_check and the burn-down loop harness all call it, so the gate and its messages behave the same in every place it runs.

Why

The gate today compares per-category counts in .config/rustqual/baseline.json and baseline-dry.json. Those files record a location only for IOSP violations (violation_details). Every other finding (about 2,000 of the ~3,200 distinct ones) is stored as a count. That is why CI can say srp_module_warnings: 207 -> 208 but not which file. A committed baseline also goes stale as soon as main moves (see T-0yb2pgw).

Scope

• Parse both passes (config.toml and dry.toml) into findings keyed by (rule, file, symbol). Line numbers are not part of the key, so editing code above a function causes no churn. Duplicate keys count as a multiset. IOSP appears in both passes, so de-duplicate it. This ticket picks the input format (json, sarif or ai-json): whichever gives a stable rule ID and symbol most cleanly.
• Diff a base report against a head report and return the new findings. Before comparing, map renamed files using git diff -M between the two revisions.
• Base analysis: run rustqual on git worktree add --detach <base>. Cache the report, keyed by base sha, rustqual version and config hash. A run takes a few seconds, so the cache is a convenience, not a requirement.
• Policy, read from .config/rustqual/ (exact file decided here):
  • exempt: rules that never gate. IOSP goes here, because rustqual has no way to turn it off.
  • enforced: rules that have reached zero on main. Any finding of an enforced rule fails, whether or not it appears in the diff. Rules are only ever added to this list; it never shrinks.
• Render the same findings as plain text, GitHub annotations (::error file=…,line=…::), a Markdown table for $GITHUB_STEP_SUMMARY, and a compact AI-oriented format. Each finding carries rustqual's message plus the guidance from .config/rustqual/guidance/<RULE>.md when that file exists.
• CLI:
  • qual diff --base <rev> [--format …] exits non-zero on new or enforced findings.
  • qual report lists every current finding (the burn-down picker needs this).
• Library API: jp-tools depends on the crate the same way it depends on ticket.

Fail closed

A report that can't be parsed, or a rustqual run that fails, is an error, never a pass. This replaces the canary in qual-ci: unit tests prove that a new finding fails the gate and that a malformed report is an error.

Tests

Keep the core pure: parsing, rename mapping, diff, policy and rendering are tested against fixed fixture reports. Only the thin shell around them spawns rustqual and git.

Out of scope

Wiring into CI, cargo_check or the harness. Those are separate tickets that depend on this one.