Replace fuzzy matching with position-based pairing in primer diff

Match residual messages by (symbol, path, obj) key and pair them 1:1
instead of using SequenceMatcher similarity scoring. This catches the
same "message was slightly changed" cases (line moved, text changed)
with simpler, more predictable logic and no difflib dependency.

Also clean up <details> block formatting (no extra blank lines).

Author: Pierre-Sassoulas

pylint/testutils/_primer/comparator.py

@@ -7,83 +7,50 @@
 import json
 from collections import defaultdict
 from collections.abc import Iterator
-from difflib import SequenceMatcher
 from pathlib import Path
 
 from pylint.reporters.json_reporter import OldJsonExport
 from pylint.testutils._primer.primer_command import PackageMessages
 
-# Minimum SequenceMatcher ratio to consider two residual messages "the same
-# diagnostic".  The identity fields (symbol, path, obj) already match, so a
-# generous threshold is fine here.
-_FUZZY_THRESHOLD = 0.5
-
 ChangedMessage = tuple[OldJsonExport, OldJsonExport]  # (old, new)
 
 _LOCATION_KEYS = {"line", "column", "endLine", "endColumn"}
 
 
-def _match_key(msg: OldJsonExport) -> tuple[str, str, str]:
-    return (msg["symbol"], msg["path"], msg["obj"])
-
-
-def _fuzzy_pair(
-    old_msgs: list[OldJsonExport], new_msgs: list[OldJsonExport]
-) -> tuple[list[ChangedMessage], list[OldJsonExport], list[OldJsonExport]]:
-    """Pair residual messages by similarity.
+def _position_key(msg: OldJsonExport) -> tuple[str, str, str]:
+    """Key that identifies a diagnostic independently of its text or location.
 
-    Returns (paired, unmatched_old, unmatched_new).
+    Two messages that share (symbol, path, obj) are the "same diagnostic" — if
+    they differ only in line numbers or message text, they should be reported as
+    *changed* rather than as a separate removal + addition.
     """
-    if not old_msgs or not new_msgs:
-        return [], old_msgs, new_msgs
-
-    paired: list[ChangedMessage] = []
-    used_old: set[int] = set()
-    used_new: set[int] = set()
-
-    for i, old in enumerate(old_msgs):
-        old_str = str(old)
-        best_ratio = _FUZZY_THRESHOLD
-        best_idx = -1
-        for j, new in enumerate(new_msgs):
-            if j in used_new:
-                continue
-            ratio = SequenceMatcher(None, old_str, str(new)).ratio()
-            if ratio > best_ratio:
-                best_ratio = ratio
-                best_idx = j
-        if best_idx >= 0:
-            paired.append((old, new_msgs[best_idx]))
-            used_old.add(i)
-            used_new.add(best_idx)
-
-    unmatched_old = [m for i, m in enumerate(old_msgs) if i not in used_old]
-    unmatched_new = [m for j, m in enumerate(new_msgs) if j not in used_new]
-    return paired, unmatched_old, unmatched_new
+    return (msg["symbol"], msg["path"], msg["obj"])
 
 
-def _fuzzy_match_residuals(
+def _match_residuals(
     old_residuals: list[OldJsonExport], new_residuals: list[OldJsonExport]
 ) -> tuple[list[ChangedMessage], list[OldJsonExport], list[OldJsonExport]]:
-    """Fuzzy-match residual messages by identity fields then similarity.
+    """Pair residual messages by position key ``(symbol, path, obj)``.
+
+    Messages that share the same key are paired 1:1 in order.  Any left-over
+    messages remain as genuinely missing or genuinely new.
 
-    Returns (paired, unmatched_old, unmatched_new) with original order preserved.
+    Returns ``(paired, unmatched_old, unmatched_new)``.
     """
     old_by_key: dict[tuple[str, str, str], list[OldJsonExport]] = defaultdict(list)
     new_by_key: dict[tuple[str, str, str], list[OldJsonExport]] = defaultdict(list)
     for m in old_residuals:
-        old_by_key[_match_key(m)].append(m)
+        old_by_key[_position_key(m)].append(m)
     for m in new_residuals:
-        new_by_key[_match_key(m)].append(m)
+        new_by_key[_position_key(m)].append(m)
 
     paired: list[ChangedMessage] = []
     paired_old_ids: set[int] = set()
     paired_new_ids: set[int] = set()
     for key in old_by_key:
         if key not in new_by_key:
             continue
-        p, _, _ = _fuzzy_pair(old_by_key[key], new_by_key[key])
-        for old, new in p:
+        for old, new in zip(old_by_key[key], new_by_key[key]):
             paired.append((old, new))
             paired_old_ids.add(id(old))
             paired_new_ids.add(id(new))
@@ -140,26 +107,25 @@ class Comparator:
     etc.).
     """
 
-    def __init__(
-        self, main_data: PackageMessages, pr_data: PackageMessages
-    ) -> None:
+    def __init__(self, main_data: PackageMessages, pr_data: PackageMessages) -> None:
         self.missing_messages: dict[str, list[OldJsonExport]] = {}
         self.new_messages: dict[str, list[OldJsonExport]] = {}
         self.changed_messages: dict[str, list[ChangedMessage]] = {}
         self.commits: dict[str, str] = {}
 
         for package, data in main_data.items():
             self.commits[package] = pr_data[package]["commit"]
-            # First pass: exact-match removal (same as before).
+            # First pass: exact-match removal.
             residual_old: list[OldJsonExport] = []
             for message in data["messages"]:
                 try:
                     pr_data[package]["messages"].remove(message)
                 except ValueError:
                     residual_old.append(message)
 
-            # Second pass: fuzzy-match residuals to detect *changed* messages.
-            paired, final_missing, final_new = _fuzzy_match_residuals(
+            # Second pass: pair residuals by position to detect *changed*
+            # messages (same diagnostic, different line or text).
+            paired, final_missing, final_new = _match_residuals(
                 residual_old, pr_data[package]["messages"]
             )
 
@@ -177,8 +143,7 @@ def __iter__(
             list[ChangedMessage],
         ]
     ]:
-        for package in self.missing_messages:
-            missing = self.missing_messages[package]
+        for package, missing in self.missing_messages.items():
             new = self.new_messages[package]
             changed = self.changed_messages[package]
             if not missing and not new and not changed:
@@ -190,12 +155,14 @@ def from_json(
         base_file: str, new_file: str, batches: int | None = None
     ) -> Comparator:
         """Build a Comparator from JSON file paths, handling batched runs."""
+        main_data: PackageMessages
+        pr_data: PackageMessages
         if batches is None:
             main_data = _load_json(base_file)
             pr_data = _load_json(new_file)
         else:
-            main_data: PackageMessages = {}
-            pr_data: PackageMessages = {}
+            main_data = {}
+            pr_data = {}
             for idx in range(batches):
                 main_data.update(
                     _load_json(base_file.replace("BATCHIDX", "batch" + str(idx)))

pylint/testutils/_primer/primer_compare_command.py

@@ -66,18 +66,18 @@ def _source_link(msg: OldJsonExport) -> str:
             filepath = str(PurePosixPath(msg["path"]).relative_to(clone_dir))
             return f"{url}/blob/{commit}/{filepath}#L{msg['line']}"
 
-        comment = f"\n**Effect on [{package}]({url}):**\n"
+        comment = f"\n**Effect on [{package}]({url}):**\n\n"
 
         # -- Changed messages (same diagnostic, different details) -----------
         if changed_messages:
-            comment += "The following messages have been changed:\n\n<details>\n\n"
+            comment += "The following messages have been changed:\n\n<details>\n"
             for count, (old, new) in enumerate(changed_messages, 1):
                 comment += (
                     f"{count}) {new['symbol']}:\n"
                     f"{message_diff(old, new)}\n"
                     f"{_source_link(new)}\n"
                 )
-            comment += "\n</details>\n\n"
+            comment += "</details>\n\n"
 
         # -- New messages ----------------------------------------------------
         astroid_errors = 0
@@ -102,20 +102,20 @@ def _source_link(msg: OldJsonExport) -> str:
             )
         if new_non_astroid_messages:
             comment += (
-                "The following messages are now emitted:\n\n<details>\n\n"
+                "The following messages are now emitted:\n\n<details>\n"
                 + new_non_astroid_messages
-                + "\n</details>\n\n"
+                + "</details>\n\n"
             )
 
         # -- Missing messages ------------------------------------------------
         if missing_messages:
-            comment += "The following messages are no longer emitted:\n\n<details>\n\n"
+            comment += "The following messages are no longer emitted:\n\n<details>\n"
             for count, message in enumerate(missing_messages, 1):
                 comment += (
                     f"{count}) {message['symbol']}:\n*{message['message']}*\n"
                     f"{_source_link(message)}\n"
                 )
-            comment += "\n</details>\n\n"
+            comment += "</details>\n\n"
 
         return comment
 

tests/testutils/_primer/fixtures/batched/expected.txt

@@ -2,17 +2,16 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages are no longer emitted:
 
 <details>
-
 1) locally-disabled:
 *Locally disabling redefined-builtin (W0622)*
 https://github.com/pylint-dev/astroid/blob/1234567890abcdef/astroid/__init__.py#L91
 2) unknown-option-value:
 *Unknown option value for 'disable', expected a valid pylint message and got 'Ellipsis'*
 https://github.com/pylint-dev/astroid/blob/1234567890abcdef/astroid/__init__.py#L91
-
 </details>
 
 *This comment was generated for commit v2.14.2*

tests/testutils/_primer/fixtures/line_moved/expected.txt

@@ -2,14 +2,13 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages have been changed:
 
 <details>
-
 1) too-complex:
 Was raised on 100:0 to 100:15, now on 103:0 to 103:15.
 https://github.com/pylint-dev/astroid/blob/123456789abcdef/astroid/node_classes.py#L103
-
 </details>
 
 *This comment was generated for commit v2.14.2*

tests/testutils/_primer/fixtures/message_changed/expected.txt

@@ -2,18 +2,17 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages have been changed:
 
 <details>
-
 1) locally-disabled:
 The message changed:
 ```diff
 - Locally disabling redefined-builtin (W0622)
 + Locally disabling redefined-builtin [we added some text in the message] (W0622)
 ```
 https://github.com/pylint-dev/astroid/blob/123456789abcdef/astroid/__init__.py#L91
-
 </details>
 
 *This comment was generated for commit v2.14.2*

tests/testutils/_primer/fixtures/message_changed/expected_truncated.txt

@@ -2,10 +2,10 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages have been changed:
 
 <details>
-
 1) locally-disabled:
 The message changed:
 ```diff

tests/testutils/_primer/fixtures/message_changed_line/expected.txt

@@ -2,10 +2,10 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages have been changed:
 
 <details>
-
 1) too-complex:
 Was raised on 100:0 to 100:15, now on 103:0 to 103:15.
 The message changed:
@@ -14,7 +14,6 @@ The message changed:
 + 'my_function' is too complex. The McCabe rating is 17
 ```
 https://github.com/pylint-dev/astroid/blob/123456789abcdef/astroid/node_classes.py#L103
-
 </details>
 
 *This comment was generated for commit v2.14.2*

tests/testutils/_primer/fixtures/new_message/expected.txt

@@ -2,14 +2,13 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages are now emitted:
 
 <details>
-
 1) locally-disabled:
 *Locally disabling redefined-builtin [we added some text in the message] (W0622)*
 https://github.com/pylint-dev/astroid/blob/123456789abcdef/astroid/__init__.py#L91
-
 </details>
 
 *This comment was generated for commit v2.14.2*

tests/testutils/_primer/fixtures/removed_message/expected.txt

@@ -2,14 +2,13 @@
 
 
 **Effect on [astroid](https://github.com/pylint-dev/astroid):**
+
 The following messages are no longer emitted:
 
 <details>
-
 1) unknown-option-value:
 *Unknown option value for 'disable', expected a valid pylint message and got 'Ellipsis'*
 https://github.com/pylint-dev/astroid/blob/123456789abcdef/astroid/__init__.py#L91
-
 </details>
 
 *This comment was generated for commit v2.14.2*