Baseline matching should not require the user to pick a strategy (line numbers vs. not)

[fain182]

Context

Today the user has to choose how baseline violations are matched against the current run, via the --ignore-baseline-linenumbers / -i flag (and the corresponding ignoreBaselineLinenumbers() in the config file). This drives two separate matching code paths in Violations::remove() and Violations::countUnmatchedIn():

• with line numbers (default): a violation matches a baseline entry only if FQCN, line number, file path and the (stable part of the) error message match. Any change above the offending line shifts the line number and the check starts failing on an already-known violation.
• without line numbers (-i): line numbers are dropped from the match, so unrelated edits don't reopen a baselined violation — but two violations of the same kind in the same class become indistinguishable.

Problem

The matching mechanism is an implementation detail, and it doesn't make sense that the user has to understand and choose it. It's not a decision about what to enforce (which is the user's job), it's a decision about how the baseline is compared (which is ours). The current situation:

• forces users to learn the trade-off between the two modes;
• makes baselines behave differently across projects/CI depending on a flag;
• the default (line-number-sensitive) produces false failures on unrelated edits, which is a common source of confusion.

Proposal

There should be a single matching strategy that works well for everyone, with no user-facing knob. The line-number sensitivity in particular should not be something the user opts into.

Approaches to evaluate:

• Hash of the line content instead of the line number. Anchoring a baseline entry to a hash of the offending line's source (optionally normalized for whitespace) makes matching stable against edits elsewhere in the file, while still distinguishing multiple violations of the same kind in the same class — which is exactly what the two current modes each fail at.
• Fuzzy line matching (nearest line with the same content) as a lighter-weight alternative.
• Keep FQCN + stable error key as the primary identity and use the line only as a tie-breaker.

Backwards compatibility

• --ignore-baseline-linenumbers / ignoreBaselineLinenumbers() would be deprecated (kept as a no-op with a notice, then removed in a future major).
• Existing baseline files may need a one-time regeneration; generate-baseline should produce the new format.

Related

• --ignore-baseline-linenumbers can report the wrong violation as new #636 — bug report on --ignore-baseline-linenumbers reporting the wrong violation as new. It explores the matching-identity solution space in depth (hash of source line, enclosing member, count-based grouping à la PHPStan/ESLint, git-diff à la golangci-lint). This issue is the DX counterpart: rather than fixing the flag's behaviour, it argues the flag (the user-facing choice) should not exist at all, and a single robust strategy should be the default for everyone. Whatever identity scheme --ignore-baseline-linenumbers can report the wrong violation as new #636 lands on is a strong candidate for that single strategy.
• Add a prune-baseline command to remove fixed violations from the baseline #649 — prune-baseline command; touches the same area since pruning would refresh stale line numbers.

Notes

Relevant code: src/Rules/Violations.php (remove(), countUnmatchedIn(), compareViolations(), extractViolationKey()), src/CLI/Baseline.php, and the option wiring in src/CLI/Command/CommonOptions.php.

[fain182]

Proposal: single two-pass matching, no baseline format change

Identity is (fqcn, stable error key). The line number is not part of the identity — it is only a pairing hint:

1. Exact pass — pair current and baseline violations with identical (fqcn, key, filePath, line). This covers every violation that hasn't moved.
2. Group pass — pair whatever is left within the same (fqcn, key), choosing the nearest line. This covers violations shifted by edits elsewhere in the file.
3. Current violations left unpaired are new; baseline entries left unpaired are stale.

This gives both properties the two current modes each miss: an edit above the offending line does not reopen a baselined violation (group pass), and two violations of the same kind in the same class stay distinct (exact pass + counting).

It also fixes #636 without any new data: in the 10/20/30 + new violation at 15 case, the three pre-existing ones pair exactly and 15 is the one reported as new. The positional pairing that causes the misattribution goes away.

Residual ambiguity: when a group is both shifted and grown in the same run, the count is still correct and the reported line is the nearest candidate. That ambiguity is inherent — ESLint says as much in their bulk-suppressions docs — but no new violation is ever silently absorbed.

Impact

• --ignore-baseline-linenumbers / ignoreBaselineLinenumbers() become no-ops with a deprecation notice, removed in the next major.
• generate-baseline always writes line numbers (useful for display and for the exact pass). Existing baselines without line numbers keep working — they simply skip the exact pass. No regeneration required.
• Internally, remove(), countUnmatchedIn() and intersection() in Violations collapse onto one matching routine returning pairs / new / stale, replacing three near-duplicate loops.

Alternatives considered

• Hash of the source line: needs a format change and regeneration, breaks en masse on a csfix pass unless normalized, and still collides on textually identical lines. Little gain over the exact pass, which already covers the common case.
• Count-only grouping (PHPStan / ESLint): never misattributes, but reports the whole group when the count grows — a real DX regression for a class with many baselined violations.
• Enclosing member as identity (--ignore-baseline-linenumbers can report the wrong violation as new #636 B): worth having, but it changes the baseline format and needs the member name plumbed from FileVisitor to Violation. Better as a follow-up, where it would also enrich the violation message.