[primer] Pair symbol-renamed messages at the same location

Adds a second pairing pass keyed on exact source location, gated on
``SequenceMatcher.ratio() >= 0.5`` between the old and new symbols.  This
catches renames like ``used-before-assignment`` →
``possibly-used-before-assignment`` and reports them as one *changed*
message instead of a separate removal + addition.

The similarity gate avoids pairing unrelated messages that happen to
coincide on the same line (e.g. ``useless-suppression`` removed and
``locally-disabled`` added at the same position).

Author: Pierre-Sassoulas

doc/whatsnew/fragments/10914.internal

@@ -1,7 +1,9 @@
-The primer now pairs residual messages by ``(symbol, path, obj)`` and reports altered
-messages as a single *changed* entry with a compact diff, rather than as a separate
-removal + addition. New messages are classified into genuine new messages, fixed false
-positives (``useless-suppression``), new false positives (``locally-disabled``), and
-``astroid-error`` fatal errors.
+The primer now pairs residual messages — first by ``(symbol, path, obj)`` and then by
+exact source location — and reports altered messages as a single *changed* entry with
+a compact diff, rather than as a separate removal + addition. The location-based pass
+also catches symbol renames at the same code position (e.g. ``used-before-assignment``
+→ ``possibly-used-before-assignment``). New messages are classified into genuine new
+messages, fixed false positives (``useless-suppression``), new false positives
+(``locally-disabled``), and ``astroid-error`` fatal errors.
 
 Refs #10914

pylint/testutils/_primer/comparator.py

@@ -6,7 +6,7 @@
 
 import json
 from collections import defaultdict
-from collections.abc import Iterator
+from collections.abc import Callable, Hashable, Iterator
 from difflib import SequenceMatcher
 from pathlib import Path
 from typing import NamedTuple
@@ -34,26 +34,35 @@ class PackageDiff(NamedTuple):
     changed: list[ChangedMessage]  # same message, altered line / text
 
 
-def _pair_by_position(
-    old_residuals: list[JSONMessage], new_residuals: list[JSONMessage]
+SYMBOL_RENAME_SIMILARITY_THRESHOLD = 0.5
+
+
+def _pair_by_key(
+    old_residuals: list[JSONMessage],
+    new_residuals: list[JSONMessage],
+    key: Callable[[JSONMessage], tuple[Hashable, ...]],
+    accept: Callable[[JSONMessage, JSONMessage], bool] = lambda _o, _n: True,
 ) -> tuple[list[ChangedMessage], list[JSONMessage], list[JSONMessage]]:
-    """Pair residual messages by ``(symbol, path, obj)`` in input order.
+    """Pair messages whose ``key`` matches, in input order.
 
-    Two messages sharing that key are the "same warning" — if they differ only
+    Two messages sharing the key are the "same warning" — if they differ only
     in line numbers or message text, they should be reported as *changed*
     rather than as a separate removal + addition.  Leftovers on each side are
-    genuinely missing or genuinely new.
+    passed through to the next pass (or reported as missing/new).
+
+    ``accept`` is an optional predicate that can veto a candidate pair (used to
+    avoid pairing two unrelated messages that happen to share the key).
     """
-    new_by_key: dict[tuple[str, str, str], list[JSONMessage]] = defaultdict(list)
+    new_by_key: dict[tuple[Hashable, ...], list[JSONMessage]] = defaultdict(list)
     for m in new_residuals:
-        new_by_key[m["symbol"], m["path"], m["obj"]].append(m)
+        new_by_key[key(m)].append(m)
 
     paired: list[ChangedMessage] = []
     final_missing: list[JSONMessage] = []
     matched_new: set[int] = set()
     for old in old_residuals:
-        bucket = new_by_key.get((old["symbol"], old["path"], old["obj"]))
-        if bucket:
+        bucket = new_by_key.get(key(old))
+        if bucket and accept(old, bucket[0]):
             new = bucket.pop(0)
             paired.append(ChangedMessage(old=old, new=new))
             matched_new.add(id(new))
@@ -63,6 +72,48 @@ def _pair_by_position(
     return paired, final_missing, final_new
 
 
+def _is_symbol_rename(old: JSONMessage, new: JSONMessage) -> bool:
+    """True when the two symbols are textually similar enough to be a rename.
+
+    Used to avoid pairing unrelated messages that happen to share a source
+    position (e.g. ``useless-suppression`` removed and ``locally-disabled``
+    added on the same line — those are conceptually opposite, not a rename).
+    """
+    ratio = SequenceMatcher(None, old["symbol"], new["symbol"]).ratio()
+    return ratio >= SYMBOL_RENAME_SIMILARITY_THRESHOLD
+
+
+def _pair_residuals(
+    old_residuals: list[JSONMessage], new_residuals: list[JSONMessage]
+) -> tuple[list[ChangedMessage], list[JSONMessage], list[JSONMessage]]:
+    """Pair residual messages with two passes of decreasing strictness.
+
+    First by ``(symbol, path, obj)`` — catches line-only or message-only changes
+    for the same warning. Then by exact source location, gated on symbol
+    similarity — catches symbol renames such as ``used-before-assignment`` →
+    ``possibly-used-before-assignment``, where the same code position now
+    emits a renamed message.
+    """
+    paired_by_symbol, missing, new = _pair_by_key(
+        old_residuals,
+        new_residuals,
+        key=lambda m: (m["symbol"], m["path"], m["obj"]),
+    )
+    paired_by_location, missing, new = _pair_by_key(
+        missing,
+        new,
+        key=lambda m: (
+            m["path"],
+            m["line"],
+            m["column"],
+            m.get("endLine"),
+            m.get("endColumn"),
+        ),
+        accept=_is_symbol_rename,
+    )
+    return paired_by_symbol + paired_by_location, missing, new
+
+
 def format_span(msg: JSONMessage) -> str:
     """Format a message's location as ``line:col to endLine:endCol``."""
     start = f"{msg['line']}:{msg['column']}"
@@ -176,9 +227,10 @@ def __iter__(self) -> Iterator[PackageDiff]:
                 except ValueError:
                     residual_old.append(message)
 
-            # Second pass: pair residuals by position to detect *changed*
-            # messages (same warning, different line or text).
-            paired, final_missing, final_new = _pair_by_position(
+            # Second pass: pair residuals by symbol then by location to
+            # detect *changed* messages (same warning, different line/text,
+            # or a symbol rename at the same source position).
+            paired, final_missing, final_new = _pair_residuals(
                 residual_old, pr_messages
             )
 

tests/testutils/_primer/cases/symbol_renamed/expected.txt

@@ -0,0 +1,26 @@
+🤖 **Effect of this PR on checked open source code:** 🤖
+
+
+**Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
+Changed messages:
+
+<details>
+
+1) [possibly-used-before-assignment](https://github.com/pylint-dev/astroid/blob/123456789abcdef/astroid/wcs.py#L3072):
+confidence: `HIGH` → `INFERENCE`
+
+```diff
+- Using variable 'orig_key' before assignment
++ Possibly using variable 'orig_key' before assignment
+  ^^^^^^^^^^
+```
+
+messageId: `E0601` → `E0606`
+
+symbol: `used-before-assignment` → `possibly-used-before-assignment`
+
+type: `error` → `warning`
+</details>
+
+*This comment was generated for commit v2.14.2*

tests/testutils/_primer/cases/symbol_renamed/expected_comparator.json

@@ -0,0 +1 @@
+[{ "package": "astroid", "missing": 0, "new": 0, "changed": 1 }]

tests/testutils/_primer/cases/symbol_renamed/main.json

@@ -0,0 +1,22 @@
+{
+  "astroid": {
+    "commit": "1234567890abcdef",
+    "messages": [
+      {
+        "type": "error",
+        "module": "astroid.wcs",
+        "obj": "WCS.fix",
+        "line": 3072,
+        "column": 12,
+        "endLine": 3072,
+        "endColumn": 20,
+        "path": "tests/.pylint_primer_tests/pylint-dev/astroid/astroid/wcs.py",
+        "symbol": "used-before-assignment",
+        "message": "Using variable 'orig_key' before assignment",
+        "messageId": "E0601",
+        "confidence": "HIGH",
+        "absolutePath": "tests/.pylint_primer_tests/pylint-dev/astroid/astroid/wcs.py"
+      }
+    ]
+  }
+}

tests/testutils/_primer/cases/symbol_renamed/pr.json

@@ -0,0 +1,22 @@
+{
+  "astroid": {
+    "commit": "123456789abcdef",
+    "messages": [
+      {
+        "type": "warning",
+        "module": "astroid.wcs",
+        "obj": "WCS.fix",
+        "line": 3072,
+        "column": 12,
+        "endLine": 3072,
+        "endColumn": 20,
+        "path": "tests/.pylint_primer_tests/pylint-dev/astroid/astroid/wcs.py",
+        "symbol": "possibly-used-before-assignment",
+        "message": "Possibly using variable 'orig_key' before assignment",
+        "messageId": "E0606",
+        "confidence": "INFERENCE",
+        "absolutePath": "tests/.pylint_primer_tests/pylint-dev/astroid/astroid/wcs.py"
+      }
+    ]
+  }
+}

tests/testutils/_primer/test_comparator.py

@@ -12,6 +12,7 @@
 from pylint.testutils._primer.comparator import (
     Comparator,
     _caret_hint,
+    _is_symbol_rename,
     format_span,
 )
 
@@ -67,6 +68,21 @@ def test_caret_hint_returns_empty_when_mostly_changed() -> None:
     assert _caret_hint("hello world", "goodbye universe") == ""
 
 
+@pytest.mark.parametrize(
+    ("old_symbol", "new_symbol", "expected"),
+    [
+        ("used-before-assignment", "possibly-used-before-assignment", True),
+        ("abstract-method", "no-abstract-method", True),
+        ("useless-suppression", "locally-disabled", False),
+        ("too-complex", "too-many-locals", False),
+    ],
+)
+def test_is_symbol_rename(old_symbol: str, new_symbol: str, expected: bool) -> None:
+    old = _msg(symbol=old_symbol)
+    new = _msg(symbol=new_symbol)
+    assert _is_symbol_rename(old, new) is expected
+
+
 def test_comparator_batched() -> None:
     fixture = Path(__file__).parent / "batched_cases"
     comparator = Comparator.from_json(