claude-dev-env 8.5.0 → 8.6.1

package/scripts/followup_cli.py

@@ -26,6 +26,12 @@ from typing import TextIO
 from dev_env_scripts_constants.followup_constants import (
     ABSENT_LOCATION_PATH,
     ALL_COMMAND_NAMES,
+    BACKLOG_EXCEEDED_EXIT_CODE,
+    BACKLOG_EXCEEDED_TEMPLATE,
+    BACKLOG_WITHIN_TEMPLATE,
+    COUNT_COMMAND_NAME,
+    DIAGNOSTIC_CHECK_ID_KEY,
+    FOLLOWUP_BACKLOG_THRESHOLD,
     BRIEF_COMMAND_NAME,
     BRIEF_FINDING_TEMPLATE,
     BRIEF_FOOTER_TEMPLATE,
@@ -54,8 +60,10 @@ from followup_ledger import (
     FollowupFinding,
     all_recorded_findings,
     followup_ledger_path,
+    head_commit,
     record_followup_finding,
 )
+from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
 
 
 def _parse_arguments(all_arguments: list[str]) -> argparse.Namespace | None:
@@ -99,7 +107,8 @@ def _formatted_finding(finding_template: str, finding: FollowupFinding) -> str:
     """Fill one template with a finding's fields.
 
     Args:
-        finding_template: A template naming rule_id, file_path, and message.
+        finding_template: A template naming any of rule_id, check_id,
+            severity, origin_commit, file_path, and message.
         finding: The finding whose fields fill the template.
 
     Returns:
@@ -107,6 +116,9 @@ def _formatted_finding(finding_template: str, finding: FollowupFinding) -> str:
     """
     return finding_template.format(
         rule_id=finding.rule_id,
+        check_id=finding.check_id or finding.rule_id,
+        severity=finding.severity,
+        origin_commit=finding.origin_commit,
         file_path=finding.file_path,
         message=finding.message,
     )
@@ -156,18 +168,25 @@ def _run_ingest(repository_root: Path, report_path: Path | None, stdout: TextIO)
     all_diagnostics = parsed_report.get(DIAGNOSTICS_KEY, [])
     if not isinstance(all_diagnostics, list):
         return SUCCESS_EXIT_CODE
+    origin_commit = head_commit(repository_root)
     for each_diagnostic in all_diagnostics:
-        each_finding = _finding_from_diagnostic(each_diagnostic)
+        each_finding = _finding_from_diagnostic(each_diagnostic, origin_commit)
         if each_finding is not None:
             record_followup_finding(repository_root, each_finding)
     return SUCCESS_EXIT_CODE
 
 
-def _finding_from_diagnostic(diagnostic_by_key: object) -> FollowupFinding | None:
+def _finding_from_diagnostic(
+    diagnostic_by_key: object, origin_commit: str
+) -> FollowupFinding | None:
     """Convert one lint diagnostic into a ledger finding.
 
+    A report reaches this command once its blocking findings are settled, so
+    every diagnostic it carries records as a smell.
+
     Args:
         diagnostic_by_key: One entry of the report's diagnostics list.
+        origin_commit: The revision the repository has checked out.
 
     Returns:
         The finding, or None when the entry carries no rule identifier and
@@ -179,7 +198,31 @@ def _finding_from_diagnostic(diagnostic_by_key: object) -> FollowupFinding | Non
     message = diagnostic_by_key.get(DIAGNOSTIC_MESSAGE_KEY)
     if not isinstance(rule_id, str) or not isinstance(message, str):
         return None
-    return FollowupFinding(rule_id, _diagnostic_file_path(diagnostic_by_key), message)
+    return FollowupFinding(
+        rule_id,
+        _diagnostic_file_path(diagnostic_by_key),
+        message,
+        _diagnostic_check_id(diagnostic_by_key, rule_id),
+        SEVERITY_SMELL,
+        origin_commit,
+    )
+
+
+def _diagnostic_check_id(diagnostic_by_key: dict[str, object], rule_id: str) -> str:
+    """Return the check identifier a diagnostic names.
+
+    Args:
+        diagnostic_by_key: One entry of the report's diagnostics list.
+        rule_id: The rule the diagnostic carries.
+
+    Returns:
+        The diagnostic's check identifier, or the rule identifier when a
+        report written before that field carries none.
+    """
+    check_id = diagnostic_by_key.get(DIAGNOSTIC_CHECK_ID_KEY)
+    if isinstance(check_id, str) and check_id:
+        return check_id
+    return rule_id
 
 
 def _diagnostic_file_path(diagnostic_by_key: dict[str, object]) -> str:
@@ -226,6 +269,35 @@ def _run_brief(repository_root: Path, stdout: TextIO) -> int:
     return SUCCESS_EXIT_CODE
 
 
+def _run_count(repository_root: Path, stdout: TextIO) -> int:
+    """Report the backlog size against the threshold.
+
+    Args:
+        repository_root: The repository whose ledger to measure.
+        stdout: The stream the line goes to.
+
+    Returns:
+        SUCCESS_EXIT_CODE while the backlog sits at or under the threshold,
+        and BACKLOG_EXCEEDED_EXIT_CODE once it passes it.
+    """
+    finding_count = len(all_recorded_findings(repository_root))
+    if finding_count <= FOLLOWUP_BACKLOG_THRESHOLD:
+        stdout.write(
+            BACKLOG_WITHIN_TEMPLATE.format(
+                finding_count=finding_count, threshold=FOLLOWUP_BACKLOG_THRESHOLD
+            )
+            + LINE_SEPARATOR
+        )
+        return SUCCESS_EXIT_CODE
+    stdout.write(
+        BACKLOG_EXCEEDED_TEMPLATE.format(
+            finding_count=finding_count, threshold=FOLLOWUP_BACKLOG_THRESHOLD
+        )
+        + LINE_SEPARATOR
+    )
+    return BACKLOG_EXCEEDED_EXIT_CODE
+
+
 def _run_clear(repository_root: Path) -> int:
     """Empty the repository's ledger.
 
@@ -266,6 +338,8 @@ def main(all_arguments: list[str], stdout: TextIO = sys.stdout) -> int:
         return _run_ingest(repository_root, report_path, stdout)
     if parsed_arguments.command == BRIEF_COMMAND_NAME:
         return _run_brief(repository_root, stdout)
+    if parsed_arguments.command == COUNT_COMMAND_NAME:
+        return _run_count(repository_root, stdout)
     return _run_clear(repository_root)
 
 

package/scripts/policy_lint/adapter_detectors.py

@@ -318,7 +318,7 @@ def state_description_diagnostics(
     """
     absolute_path = adapter_support._document_path(repository_root, document)
     detector_module = load_module("blocking.state_description_blocker")
-    all_messages = detector_module.find_violations(
+    all_messages = detector_module.find_violations_with_lines(
         document.text, absolute_path.as_posix()
     )
     return adapter_support._diagnostics_for_state_messages(document, all_messages)

package/scripts/policy_lint/adapter_support.py

@@ -4,6 +4,7 @@ from collections.abc import Callable, Iterable
 from pathlib import Path
 from types import ModuleType
 
+from .check_catalog import check_id_for_message
 from .model import Diagnostic, Document, Location, Severity
 
 HookModuleLoader = Callable[[str], ModuleType]
@@ -69,28 +70,23 @@ def _diagnostics_for_messages(
             None if maybe_line is None else Location(document.path, maybe_line, 1)
         )
         all_diagnostics.append(
-            Diagnostic(rule_id, Severity.ERROR, each_message, location)
+            Diagnostic(
+                rule_id,
+                Severity.ERROR,
+                each_message,
+                location,
+                check_id_for_message(rule_id, each_message),
+            )
         )
     return tuple(all_diagnostics)
 
 
-def _source_line_for_phrase(source_text: str, phrase: str) -> int | None:
-    normalized_phrase = phrase.casefold()
-    for each_line_number, each_line in enumerate(source_text.splitlines(), 1):
-        if normalized_phrase in each_line.casefold():
-            return each_line_number
-    return None
-
-
 def _diagnostics_for_state_messages(
-    document: Document, all_messages: Iterable[str]
+    document: Document, all_messages: Iterable[tuple[str, int]]
 ) -> tuple[Diagnostic, ...]:
     all_diagnostics: list[Diagnostic] = []
-    for each_message in all_messages:
-        maybe_line = _source_line_for_phrase(document.text, each_message)
-        location = (
-            None if maybe_line is None else Location(document.path, maybe_line, 1)
-        )
+    for each_message, each_line_number in all_messages:
+        location = Location(document.path, each_line_number, 1)
         all_diagnostics.append(
             Diagnostic("state-description", Severity.ERROR, each_message, location)
         )

package/scripts/policy_lint/adapters.py

@@ -21,7 +21,6 @@ from .model import Diagnostic, Document, DocumentSet
 _document_path = adapter_support._document_path
 _line_number = adapter_support._line_number
 _diagnostics_for_messages = adapter_support._diagnostics_for_messages
-_source_line_for_phrase = adapter_support._source_line_for_phrase
 _diagnostics_for_state_messages = adapter_support._diagnostics_for_state_messages
 
 

package/scripts/policy_lint/check_catalog.py

@@ -0,0 +1,44 @@
+"""Name the check behind one finding of a bundling rule.
+
+::
+
+    rule "code-rules", "Line 3: Constant TIMEOUT - move to config/"
+      -> code-rules/constant-outside-config
+    rule "code-rules", "Line 4: something no entry names"
+      -> code-rules/unclassified
+    rule "rmtree-safety", any message
+      -> rmtree-safety
+
+A consumer partitions findings into blocking and advisory ones by this
+identifier. A message no catalog entry names resolves to the unclassified
+identifier, which a partition treats as blocking, so a reworded message
+reports louder rather than quieter.
+"""
+
+from __future__ import annotations
+
+from .config.check_catalog_constants import (
+    ALL_BUNDLING_RULE_IDS,
+    ALL_CHECK_CATALOG_ENTRIES,
+    CHECK_ID_SEPARATOR,
+    UNCLASSIFIED_CHECK_NAME,
+)
+
+
+def check_id_for_message(rule_id: str, message: str) -> str:
+    """Return the check identifier one rule and message resolve to.
+
+    Args:
+        rule_id: The rule that raised the finding.
+        message: The finding's message text.
+
+    Returns:
+        The rule identifier for a rule that runs one check, or the rule
+        identifier joined to the name of the check the message names.
+    """
+    if rule_id not in ALL_BUNDLING_RULE_IDS:
+        return rule_id
+    for each_entry in ALL_CHECK_CATALOG_ENTRIES:
+        if each_entry.message_marker in message:
+            return rule_id + CHECK_ID_SEPARATOR + each_entry.check_name
+    return rule_id + CHECK_ID_SEPARATOR + UNCLASSIFIED_CHECK_NAME

package/scripts/policy_lint/config/check_catalog_constants.py

@@ -0,0 +1,59 @@
+"""The message markers that name which check inside a bundling rule spoke.
+
+Most lint rules run one check, so their rule identifier already names the
+check. Two rules bundle many checks behind one identifier, and a consumer that
+classifies a finding by severity needs to know which of them raised it. Each
+entry below pairs a stable fragment of a check's message with the name that
+identifies the check.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class CheckCatalogEntry(NamedTuple):
+    """One check inside a bundling rule, and the text that identifies it.
+
+    Attributes:
+        message_marker: A fragment the check's message always carries.
+        check_name: The name that identifies the check inside its rule.
+    """
+
+    message_marker: str
+    check_name: str
+
+
+CHECK_ID_SEPARATOR: str = "/"
+UNCLASSIFIED_CHECK_NAME: str = "unclassified"
+ALL_BUNDLING_RULE_IDS: frozenset[str] = frozenset({"code-rules", "validators"})
+
+ALL_CHECK_CATALOG_ENTRIES: tuple[CheckCatalogEntry, ...] = (
+    CheckCatalogEntry(
+        "exceeds blocking threshold - split into helpers", "function-length"
+    ),
+    CheckCatalogEntry(" - consider moving to config/", "function-local-constant"),
+    CheckCatalogEntry(" - move to config/", "constant-outside-config"),
+    CheckCatalogEntry(" - prefix with all_ (CODE_RULES §5)", "collection-name-prefix"),
+    CheckCatalogEntry(" - prefix with each_ (CODE_RULES §5)", "loop-variable-prefix"),
+    CheckCatalogEntry("Stuttering collection prefix", "stuttering-collection-prefix"),
+    CheckCatalogEntry("string separator", "unnamed-string-separator"),
+    CheckCatalogEntry("string magic value", "string-magic-value"),
+    CheckCatalogEntry(
+        "Block comment found - refactor to self-documenting code",
+        "block-comment-added",
+    ),
+    CheckCatalogEntry(
+        "Comment found - refactor to self-documenting code", "comment-added"
+    ),
+    CheckCatalogEntry("comment added:", "comment-diff"),
+    CheckCatalogEntry("docstring carries a", "docstring-runon-sentence"),
+    CheckCatalogEntry("summary runs", "docstring-prose-wall"),
+    CheckCatalogEntry(
+        "return type annotation (CODE_RULES §6)", "missing-return-annotation"
+    ),
+    CheckCatalogEntry(
+        "missing type annotation (CODE_RULES §6)", "missing-type-annotation"
+    ),
+    CheckCatalogEntry("Single-letter variable", "single-letter-variable"),
+)

package/scripts/policy_lint/model.py

@@ -254,15 +254,18 @@ class Diagnostic:
     severity: Severity
     message: str
     location: Location | None = None
+    check_id: str | None = None
 
     def as_dict(self) -> dict[str, object]:
         """Return a JSON-compatible diagnostic.
 
         Returns:
-            The diagnostic mapping.
+            The diagnostic mapping, whose check_id names the single check
+            behind the finding and falls back to the rule identifier.
         """
         return {
             "rule_id": self.rule_id,
+            "check_id": self.check_id or self.rule_id,
             "severity": self.severity.value,
             "message": self.message,
             "location": None if self.location is None else self.location.as_dict(),

package/scripts/test_followup_cli.py

@@ -7,6 +7,10 @@ import json
 import sys
 from pathlib import Path
 
+from dev_env_scripts_constants.followup_constants import (
+    BACKLOG_EXCEEDED_EXIT_CODE,
+    FOLLOWUP_BACKLOG_THRESHOLD,
+)
 from followup_cli import main
 
 _hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
@@ -76,7 +80,9 @@ def test_ingest_records_every_located_diagnostic(tmp_path: Path) -> None:
 
     assert exit_code == 0
     assert all_recorded_findings(tmp_path) == (
-        FollowupFinding("line-length", "src/app.py", "line runs past the limit"),
+        FollowupFinding(
+            "line-length", "src/app.py", "line runs past the limit", "line-length"
+        ),
     )
 
 
@@ -97,7 +103,9 @@ def test_ingest_records_a_diagnostic_without_a_location(tmp_path: Path) -> None:
     run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
 
     assert all_recorded_findings(tmp_path) == (
-        FollowupFinding("inventory-drift", "", "inventory row missing"),
+        FollowupFinding(
+            "inventory-drift", "", "inventory row missing", "inventory-drift"
+        ),
     )
 
 
@@ -154,3 +162,109 @@ def test_an_unknown_command_reports_usage(tmp_path: Path) -> None:
 
     assert exit_code == 2
     assert "Usage" in output_text
+
+
+def test_ingest_carries_the_check_identifier_a_diagnostic_names(
+    tmp_path: Path,
+) -> None:
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "code-rules",
+                "check_id": "code-rules/constant-outside-config",
+                "severity": "error",
+                "message": "Line 3: Constant TIMEOUT - move to config/",
+                "location": {"path": "scripts/run.py", "start_line": 3},
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+    assert recorded_finding.check_id == "code-rules/constant-outside-config"
+    assert recorded_finding.severity == "smell"
+
+
+def test_ingest_records_the_revision_the_repository_has_checked_out(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / ".git").mkdir()
+    (tmp_path / ".git" / "HEAD").write_text("f00dcafe\n", encoding="utf-8")
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "code-rules",
+                "check_id": "code-rules/function-length",
+                "message": "Line 9: Function 'run' is 74 lines",
+                "location": {"path": "scripts/run.py", "start_line": 9},
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    assert all_recorded_findings(tmp_path)[0].origin_commit == "f00dcafe"
+
+
+def test_count_reports_an_empty_backlog(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "0" in output_text
+
+
+def test_count_passes_while_the_backlog_sits_under_the_threshold(
+    tmp_path: Path,
+) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("code-rules", "run.py", "one smell", "code-rules/x")
+    )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "1" in output_text
+
+
+def test_count_escalates_once_the_backlog_passes_the_threshold(
+    tmp_path: Path,
+) -> None:
+    for each_index in range(FOLLOWUP_BACKLOG_THRESHOLD + 1):
+        record_followup_finding(
+            tmp_path,
+            FollowupFinding(
+                "code-rules",
+                f"run{each_index}.py",
+                "one smell",
+                f"code-rules/x{each_index}",
+            ),
+        )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == BACKLOG_EXCEEDED_EXIT_CODE
+    assert str(FOLLOWUP_BACKLOG_THRESHOLD) in output_text
+
+
+def test_list_names_the_check_behind_each_finding(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path,
+        FollowupFinding(
+            "code-rules",
+            "run.py",
+            "one smell",
+            "code-rules/constant-outside-config",
+            "smell",
+            "f00dcafe",
+        ),
+    )
+
+    _, output_text = run_command(["list", "--repository-root", str(tmp_path)])
+
+    assert "code-rules/constant-outside-config" in output_text
+    assert "f00dcafe" in output_text

package/scripts/test_validate_instruction_pairs.py

@@ -15,7 +15,8 @@ _hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
-from followup_ledger import all_recorded_findings
+from followup_ledger import all_recorded_findings, head_commit
+from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
 
 
 def read_workflow(workflow_filename: str) -> str:
@@ -234,6 +235,27 @@ def test_run_gate_passes_a_smell_and_records_it(tmp_path: Path) -> None:
     ] == ["instruction-git-mode"]
 
 
+def test_a_recorded_smell_carries_its_severity_and_the_checked_out_revision(
+    tmp_path: Path,
+) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_git_mode_executable(tmp_path)
+    subprocess.run(
+        ["git", "commit", "--quiet", "-m", "instruction pair"],
+        cwd=tmp_path,
+        check=True,
+    )
+
+    run_gate(tmp_path)
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+    assert recorded_finding.severity == SEVERITY_SMELL
+    assert recorded_finding.check_id == "instruction-git-mode"
+    assert recorded_finding.origin_commit == head_commit(tmp_path)
+    assert recorded_finding.origin_commit
+
+
 def test_run_gate_records_a_smell_it_finds_beside_a_breaking_finding(
     tmp_path: Path,
 ) -> None:

package/scripts/tests/test_policy_lint_rules_check_catalog.py

@@ -0,0 +1,151 @@
+"""Synchronization tests for the per-check identifier catalog.
+
+Each sample below is a message copied from the check that raises it. A check
+whose wording moves fails its sample here, so the catalog and the checks stay
+in step.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from policy_lint.check_catalog import check_id_for_message
+from policy_lint.config.check_catalog_constants import (
+    ALL_CHECK_CATALOG_ENTRIES,
+    UNCLASSIFIED_CHECK_NAME,
+)
+from policy_lint.model import Diagnostic, Severity
+
+_BUNDLING_RULE_ID = "code-rules"
+_HOOKS_DIRECTORY = Path(__file__).resolve().parents[2] / "hooks"
+_TEST_FILE_PREFIX = "test_"
+_PYTHON_GLOB = "*.py"
+_SOURCE_ENCODING = "utf-8"
+
+ALL_MESSAGE_SAMPLES: tuple[tuple[str, str], ...] = (
+    (
+        "Line 20: Function 'run' is 74 lines - exceeds blocking threshold - "
+        "split into helpers",
+        "function-length",
+    ),
+    (
+        "Line 8: Function-local constant TIMEOUT - consider moving to config/",
+        "function-local-constant",
+    ),
+    ("Line 3: Constant TIMEOUT - move to config/", "constant-outside-config"),
+    (
+        "Line 5: Collection parameter paths - prefix with all_ (CODE_RULES §5)",
+        "collection-name-prefix",
+    ),
+    (
+        "Line 6: loop variable 'path' - prefix with each_ (CODE_RULES §5)",
+        "loop-variable-prefix",
+    ),
+    (
+        "Line 7: Stuttering collection prefix 'all_all_paths'",
+        "stuttering-collection-prefix",
+    ),
+    ("Line 9: string separator '\\n' - name it", "unnamed-string-separator"),
+    ("Line 10: string magic value 'utf-8'", "string-magic-value"),
+    (
+        "Line 11: Block comment found - refactor to self-documenting code",
+        "block-comment-added",
+    ),
+    (
+        "Line 12: Comment found - refactor to self-documenting code",
+        "comment-added",
+    ),
+    ("Line 13: TODO comment added: fix later", "comment-diff"),
+    (
+        "Line 14: module docstring carries a 44-word run-on sentence",
+        "docstring-runon-sentence",
+    ),
+    ("Line 15: module summary runs 9 prose lines", "docstring-prose-wall"),
+    (
+        "Line 16: parameter 'count' on 'run' missing type annotation (CODE_RULES §6)",
+        "missing-type-annotation",
+    ),
+    (
+        "Line 17: function 'run' missing return type annotation (CODE_RULES §6)",
+        "missing-return-annotation",
+    ),
+    ("src/app.py:3: Single-letter variable 'p'", "single-letter-variable"),
+)
+
+
+def _all_hook_source_texts() -> tuple[str, ...]:
+    return tuple(
+        each_path.read_text(encoding=_SOURCE_ENCODING)
+        for each_path in _HOOKS_DIRECTORY.rglob(_PYTHON_GLOB)
+        if not each_path.name.startswith(_TEST_FILE_PREFIX)
+    )
+
+
+@pytest.mark.parametrize(("sample_message", "expected_name"), ALL_MESSAGE_SAMPLES)
+def test_a_message_sample_resolves_to_its_check_name(
+    sample_message: str, expected_name: str
+) -> None:
+    resolved_check_id = check_id_for_message(_BUNDLING_RULE_ID, sample_message)
+
+    assert resolved_check_id == f"{_BUNDLING_RULE_ID}/{expected_name}"
+
+
+def test_every_catalog_entry_carries_a_message_sample() -> None:
+    all_sampled_names = {each_sample[1] for each_sample in ALL_MESSAGE_SAMPLES}
+    all_catalog_names = {
+        each_entry.check_name for each_entry in ALL_CHECK_CATALOG_ENTRIES
+    }
+
+    assert all_catalog_names == all_sampled_names
+
+
+@pytest.mark.parametrize("catalog_entry", ALL_CHECK_CATALOG_ENTRIES)
+def test_each_catalog_marker_is_still_written_by_a_check(catalog_entry) -> None:
+    all_source_texts = _all_hook_source_texts()
+
+    assert any(
+        catalog_entry.message_marker in each_text for each_text in all_source_texts
+    )
+
+
+def test_every_catalog_check_name_is_distinct_from_its_neighbours() -> None:
+    all_names = [each_entry.check_name for each_entry in ALL_CHECK_CATALOG_ENTRIES]
+
+    assert len(set(all_names)) == len(all_names)
+
+
+def test_an_unmatched_message_stays_unclassified() -> None:
+    resolved_check_id = check_id_for_message(
+        _BUNDLING_RULE_ID, "Line 4: a finding no catalog entry names"
+    )
+
+    assert resolved_check_id == f"{_BUNDLING_RULE_ID}/{UNCLASSIFIED_CHECK_NAME}"
+
+
+def test_a_rule_outside_the_bundling_set_keeps_its_own_identifier() -> None:
+    resolved_check_id = check_id_for_message(
+        "rmtree-safety", "Line 9: shutil.rmtree with ignore_errors=True"
+    )
+
+    assert resolved_check_id == "rmtree-safety"
+
+
+def test_a_diagnostic_reports_its_rule_identifier_when_it_carries_no_check_name() -> (
+    None
+):
+    diagnostic = Diagnostic("test-pairing", Severity.ERROR, "no matching test")
+
+    assert diagnostic.as_dict()["check_id"] == "test-pairing"
+
+
+def test_a_diagnostic_reports_the_check_identifier_it_carries() -> None:
+    diagnostic = Diagnostic(
+        "code-rules",
+        Severity.ERROR,
+        "Line 3: Constant TIMEOUT - move to config/",
+        None,
+        "code-rules/constant-outside-config",
+    )
+
+    assert diagnostic.as_dict()["check_id"] == "code-rules/constant-outside-config"

package/scripts/tests/test_policy_lint_rules_engine.py

@@ -296,7 +296,10 @@ def test_state_description_diagnostics_maps_and_scopes_phrases(
         adapters,
         "_hooks_module",
         lambda _module_name: types.SimpleNamespace(
-            find_violations=lambda _text, _path: ["used to", "replaced by"]
+            find_violations_with_lines=lambda _text, _path: [
+                ("used to", 2),
+                ("replaced by", 1),
+            ]
         ),
     )
     source_document = Document(