claude-dev-env 8.6.0 → 8.6.1

package/_shared/pr-loop/scripts/pr_loop_shared_constants/terminology_sweep_constants.py

@@ -10,6 +10,10 @@ MARKDOWN_FILE_EXTENSION: str = ".md"
 
 INLINE_CODE_SPAN_PATTERN: re.Pattern[str] = re.compile(r"`[^`]*`")
 
+MARKDOWN_LINK_TARGET_PATTERN: re.Pattern[str] = re.compile(r"\]\([^)]*\)")
+
+SENTENCE_BOUNDARY_PATTERN: re.Pattern[str] = re.compile(r"(?<=[.!?])\s+")
+
 SNAKE_CASE_IDENTIFIER_PATTERN: re.Pattern[str] = re.compile(
     r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b"
 )

package/_shared/pr-loop/scripts/terminology_sweep.py

@@ -62,10 +62,12 @@ from pr_loop_shared_constants.terminology_sweep_constants import (
     JAVASCRIPT_LINE_COMMENT_MARKER,
     JSDOC_CONTINUATION_MARKER,
     MARKDOWN_FILE_EXTENSION,
+    MARKDOWN_LINK_TARGET_PATTERN,
     MINIMUM_IDENTIFIER_TOKEN_COUNT,
     PROSE_WINDOW_WORD_SEPARATOR,
     PROSE_WORD_PATTERN,
     PYTHON_COMMENT_MARKER,
+    SENTENCE_BOUNDARY_PATTERN,
     SNAKE_CASE_IDENTIFIER_PATTERN,
     STRING_LITERAL_CONTENT_PATTERN,
     TERMINOLOGY_FINDING_TEMPLATE,
@@ -74,7 +76,6 @@ from pr_loop_shared_constants.terminology_sweep_constants import (
     TEST_FILE_PREFIX,
     TEST_FILE_SUFFIX,
 )
-
 from subprocess_window_access import hidden_window_creation_flags
 
 IdentifierTuple = tuple[str, ...]
@@ -161,27 +162,78 @@ def _collect_introduced_identifiers(
 ) -> frozenset[IdentifierTuple]:
     """Return the identifier tuples introduced on added code lines.
 
+    A name bound only inside a test module is a fixture's own local variable,
+    not a term the rest of the repository is expected to agree with, so a
+    test file's identifiers are left out.
+
     Args:
         all_added_lines: Added-line triples from :func:`_parse_added_lines`.
 
     Returns:
-        Every multi-word identifier tuple appearing on an added code line.
+        Every multi-word identifier tuple appearing on an added,
+        non-test-module code line.
     """
     all_identifier_tuples: set[IdentifierTuple] = set()
     for each_file_path, _, each_text in all_added_lines:
-        if _file_extension(each_file_path) in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+        if _file_extension(
+            each_file_path
+        ) in ALL_SWEEP_CODE_FILE_EXTENSIONS and not _is_test_file(each_file_path):
             all_identifier_tuples.update(_identifier_tuples_in_text(each_text))
     return frozenset(all_identifier_tuples)
 
 
+def _fragments_split_at_breaks(all_fragments: list[str]) -> list[str]:
+    """Split each fragment at every sentence, link, and code-span break in turn."""
+    for each_break_pattern in (
+        INLINE_CODE_SPAN_PATTERN,
+        MARKDOWN_LINK_TARGET_PATTERN,
+        SENTENCE_BOUNDARY_PATTERN,
+    ):
+        all_fragments = [
+            each_piece
+            for each_fragment in all_fragments
+            for each_piece in each_break_pattern.split(each_fragment)
+        ]
+    return all_fragments
+
+
+def _split_into_prose_fragments(raw_fragment: str) -> list[str]:
+    """Split a raw prose fragment at every sentence, link, and code-span break.
+
+    ::
+
+        raw:  "…gates the pull request. [`link`](docs/README.md) explains it."
+        split -> ["…gates the pull request", "explains it."]
+        flag: a window built from the joined text -- "pull request docs"
+        ok:   "pull request" and "docs" now sit in different fragments
+
+    A sentence-ending period, a Markdown link's target, and a backticked code
+    span each end whatever the reader was reading and start something new.
+    Splitting there keeps a word window scoped to one sentence, clear of a
+    stripped span's unrelated text on its far side.
+
+    Args:
+        raw_fragment: One prose fragment collected from an added line.
+
+    Returns:
+        The fragment's pieces with every break removed, in order, dropping
+        any piece left blank.
+    """
+    all_fragments = _fragments_split_at_breaks([raw_fragment])
+    return [
+        each_fragment.strip() for each_fragment in all_fragments if each_fragment.strip()
+    ]
+
+
 def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     """Return the prose fragments of an added line worth scanning for terms.
 
-    A Markdown line is prose with its inline-code spans removed, since a
-    backticked span names code verbatim. A code line contributes its comment
-    tail, its JSDoc continuation text, and the contents of its string
-    literals. A test module contributes its comment tail and JSDoc text only.
-    Its string literals hold fixture data, not prose.
+    A Markdown line is prose split at its sentence, link, and code-span
+    breaks, since a backticked span names code verbatim and a link target is
+    a path, not a word. A code line contributes its comment tail, its JSDoc
+    continuation text, and the contents of its string literals, each split
+    the same way. A test module contributes its comment tail and JSDoc text
+    only. Its string literals hold fixture data, not prose.
 
     Args:
         file_path: The path the added line belongs to.
@@ -192,17 +244,21 @@ def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     """
     extension = _file_extension(file_path)
     if extension == MARKDOWN_FILE_EXTENSION:
-        return [INLINE_CODE_SPAN_PATTERN.sub(" ", line_text)]
+        return _split_into_prose_fragments(line_text)
     if extension not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
         return []
-    all_fragments: list[str] = []
+    all_raw_fragments: list[str] = []
     stripped_line = line_text.strip()
     if stripped_line.startswith(JSDOC_CONTINUATION_MARKER):
-        all_fragments.append(stripped_line)
-    all_fragments.extend(_comment_fragments(line_text))
+        all_raw_fragments.append(stripped_line)
+    all_raw_fragments.extend(_comment_fragments(line_text))
     if not _is_test_file(file_path):
-        all_fragments.extend(_string_literal_fragments(line_text))
-    return all_fragments
+        all_raw_fragments.extend(_string_literal_fragments(line_text))
+    return [
+        each_split_fragment
+        for each_raw_fragment in all_raw_fragments
+        for each_split_fragment in _split_into_prose_fragments(each_raw_fragment)
+    ]
 
 
 def _is_test_file(file_path: str) -> bool:
@@ -428,15 +484,30 @@ def _near_miss_identifier(
     all_identifier_tuples: frozenset[IdentifierTuple],
     identifiers_by_first_token: dict[str, list[IdentifierTuple]],
     all_identifier_tokens: frozenset[str],
+    all_known_identifier_tuples: frozenset[IdentifierTuple],
 ) -> IdentifierTuple | None:
     """Return an identifier the candidate near-misses, or None when it does not.
 
+    ::
+
+        known identifier:  cde_lint            (scripts/cde_lint.py, the tool's own name)
+        introduced:        cde_lint_path        3-token, adds "path" to that name
+        candidate:         "cde lint standard"  shares "cde lint", then "standard"
+        candidate[:-1]:    ("cde", "lint")       == the known identifier cde_lint
+        ok:   candidate[:-1] names cde_lint verbatim -- agreement, not a near-miss
+        flag: "premium request budget" against premium_request_interactions
+              -- "premium request" names no identifier of its own
+
     Args:
         candidate_tuple: The prose term's lowercase token tuple.
         all_identifier_tuples: Every introduced identifier tuple.
         identifiers_by_first_token: Identifier tuples grouped by leading token.
         all_identifier_tokens: Every token of every identifier on added code
             lines, used to spare prose built from real code vocabulary.
+        all_known_identifier_tuples: Every identifier tuple the sweep knows
+            about, introduced or pre-existing, plus each added file's stem,
+            used to spare a candidate whose leading tokens name one of them
+            verbatim.
 
     Returns:
         The first identifier the candidate renames in only its final token. Such a
@@ -449,9 +520,12 @@ def _near_miss_identifier(
         common English compound tail word (``read-only``, ``data-driven``); it
         contains an English stopword (``to a``, ``each image``); it differs
         from the identifier only by a singular/plural form of one or more
-        tokens (``test files`` against ``test_file``); or every diverging word
+        tokens (``test files`` against ``test_file``); every diverging word
         is itself a token of some introduced identifier (``target width box``
-        when ``box_height`` is also in the diff).
+        when ``box_height`` is also in the diff); or its leading tokens, with
+        the final diverging word set aside, spell out a known identifier of
+        their own (``cde_lint standard`` against ``cde_lint_path``, when
+        ``cde_lint`` already names something in the tree).
     """
     if not candidate_tuple or candidate_tuple in all_identifier_tuples:
         return None
@@ -468,6 +542,8 @@ def _near_miss_identifier(
             continue
         if not _diverges_only_in_final_token(candidate_tuple, each_identifier):
             continue
+        if candidate_tuple[:-1] in all_known_identifier_tuples:
+            continue
         diverging_words = [
             each_word
             for each_word, each_token in zip(candidate_tuple, each_identifier)
@@ -489,6 +565,7 @@ def _findings_for_line(
     all_identifier_tuples: frozenset[IdentifierTuple],
     identifiers_by_first_token: dict[str, list[IdentifierTuple]],
     all_identifier_tokens: frozenset[str],
+    all_known_identifier_tuples: frozenset[IdentifierTuple],
 ) -> list[str]:
     """Return the near-miss findings for one added line.
 
@@ -500,6 +577,8 @@ def _findings_for_line(
         identifiers_by_first_token: Identifier tuples grouped by leading token.
         all_identifier_tokens: Every token of every identifier on added code
             lines, used to spare prose built from real code vocabulary.
+        all_known_identifier_tuples: Every identifier tuple the sweep knows
+            about, passed through to :func:`_near_miss_identifier`.
 
     Returns:
         One finding string per distinct near-miss term on the line.
@@ -515,6 +594,7 @@ def _findings_for_line(
                 all_identifier_tuples,
                 identifiers_by_first_token,
                 all_identifier_tokens,
+                all_known_identifier_tuples,
             )
             if matched_identifier is None or each_tuple in reported_tuples:
                 continue
@@ -530,6 +610,50 @@ def _findings_for_line(
     return all_findings
 
 
+def _stem_identifier_tuple_for_code_file(each_file_path: str) -> IdentifierTuple | None:
+    """Return a non-test code file's stem as a multi-word identifier tuple.
+
+    ``None`` when the path is not a swept code file, is a test file, or its
+    stem carries fewer than the minimum identifier token count.
+    """
+    if _file_extension(each_file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS or _is_test_file(
+        each_file_path
+    ):
+        return None
+    stem_tuple = _identifier_token_tuple(Path(each_file_path).stem)
+    if len(stem_tuple) < MINIMUM_IDENTIFIER_TOKEN_COUNT:
+        return None
+    return stem_tuple
+
+
+def _file_stem_identifier_tuples(
+    all_added_lines: list[tuple[str, int, str]],
+) -> frozenset[IdentifierTuple]:
+    """Return the identifier tuple of each added, non-test code file's stem.
+
+    ::
+
+        touched file:  scripts/cde_lint_partition.py
+        stem tuple:     ("cde", "lint", "partition")
+
+    A file that exists in the tree names something whether or not that name
+    is ever spelled out as a code identifier, so a file's stem joins the
+    known-identifier vocabulary the same way a spelled-out name does.
+
+    Args:
+        all_added_lines: Added-line triples from :func:`_parse_added_lines`.
+
+    Returns:
+        One tuple per distinct, multi-word stem of an added, non-test code
+        file.
+    """
+    return frozenset(
+        stem_tuple
+        for each_file_path, _, _ in all_added_lines
+        if (stem_tuple := _stem_identifier_tuple_for_code_file(each_file_path)) is not None
+    )
+
+
 def _find_terminology_near_misses(
     diff_text: str, all_preexisting_identifier_tuples: frozenset[IdentifierTuple]) -> list[str]:
     all_added_lines = _parse_added_lines(diff_text)
@@ -537,6 +661,9 @@ def _find_terminology_near_misses(
     all_identifier_tokens = frozenset(
         each_token for each_tuple in all_identifier_tuples for each_token in each_tuple
     )
+    all_known_identifier_tuples = all_identifier_tuples | _file_stem_identifier_tuples(
+        all_added_lines
+    )
     introduced_tuples = frozenset(
         each_tuple
         for each_tuple in all_identifier_tuples
@@ -557,6 +684,7 @@ def _find_terminology_near_misses(
                 introduced_tuples,
                 introduced_by_first_token,
                 all_identifier_tokens,
+                all_known_identifier_tuples,
             )
         )
     return all_findings
@@ -605,15 +733,23 @@ def repository_environment() -> dict[str, str]:
 def _identifier_names_on_added_code_lines(diff_text: str) -> frozenset[str]:
     """Return every multi-word identifier name on the diff's added code lines.
 
+    A name bound only inside a test module is left out, matching
+    :func:`_collect_introduced_identifiers`, since it is never treated as
+    introduced terminology and its presence in the base tree is not worth a
+    lookup.
+
     Args:
         diff_text: The unified-diff text to scan.
 
     Returns:
-        The distinct snake_case and camelCase names of two or more tokens.
+        The distinct snake_case and camelCase names of two or more tokens
+        on a non-test-module code line.
     """
     all_names: set[str] = set()
     for each_file_path, _, each_text in _parse_added_lines(diff_text):
-        if _file_extension(each_file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+        if _file_extension(
+            each_file_path
+        ) not in ALL_SWEEP_CODE_FILE_EXTENSIONS or _is_test_file(each_file_path):
             continue
         all_found_names = SNAKE_CASE_IDENTIFIER_PATTERN.findall(each_text)
         all_found_names += CAMEL_CASE_IDENTIFIER_PATTERN.findall(each_text)

package/_shared/pr-loop/scripts/tests/test_terminology_sweep.py

@@ -626,6 +626,123 @@ def test_does_not_flag_two_token_identifier_first_word_coincidence() -> None:
     assert sweep_diff(diff) == []
 
 
+def test_does_not_flag_window_crossing_a_sentence_boundary() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ a/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+pull_request_owner = 5\n"
+        "diff --git a/README.md b/README.md\n"
+        "--- a/README.md\n"
+        "+++ b/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+Merge the pull request. Trigger warnings surface elsewhere.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_window_crossing_a_markdown_link_target() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ a/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+pull_request_owner = 5\n"
+        "diff --git a/README.md b/README.md\n"
+        "--- a/README.md\n"
+        "+++ b/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+See the pull request [`link`](docs/README.md) explains it.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_identifier_bound_only_in_a_test_module() -> None:
+    diff = (
+        "diff --git a/tests/test_config.py b/tests/test_config.py\n"
+        "--- a/tests/test_config.py\n"
+        "+++ b/tests/test_config.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+jon_pc_json = load_fixture()\n"
+        "diff --git a/README.md b/README.md\n"
+        "--- a/README.md\n"
+        "+++ b/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The jon pc export runs first.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_still_flags_identifier_bound_in_a_production_module() -> None:
+    diff = (
+        "diff --git a/api/config.py b/api/config.py\n"
+        "--- a/api/config.py\n"
+        "+++ b/api/config.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+jon_pc_json = load_config()\n"
+        "diff --git a/README.md b/README.md\n"
+        "--- a/README.md\n"
+        "+++ b/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The jon pc export runs first.\n"
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "jon pc export" in findings[0]
+
+
+def test_does_not_flag_window_whose_leading_tokens_are_a_known_identifier() -> None:
+    diff = (
+        "diff --git a/api/store.py b/api/store.py\n"
+        "--- a/api/store.py\n"
+        "+++ b/api/store.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+cde_lint_path = Path(value)\n"
+        '+HELP_TEXT = "cde_lint standard output"\n'
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_still_flags_window_whose_leading_tokens_name_nothing_known() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_request_interactions = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The premium request budget gates the run.\n"
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "premium request budget" in findings[0]
+
+
+def test_does_not_flag_window_whose_leading_tokens_are_an_added_files_stem() -> None:
+    diff = (
+        "diff --git a/scripts/cde_lint.py b/scripts/cde_lint.py\n"
+        "--- a/scripts/cde_lint.py\n"
+        "+++ b/scripts/cde_lint.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+VERSION = 1\n"
+        "diff --git a/scripts/cde_lint_partition.py b/scripts/cde_lint_partition.py\n"
+        "--- a/scripts/cde_lint_partition.py\n"
+        "+++ b/scripts/cde_lint_partition.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+cde_lint_owner = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+Run cde_lint standard checks first.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
 def test_flags_near_miss_when_second_leading_token_is_plural_variant() -> None:
     diff = (
         "diff --git a/api/store.py b/api/store.py\n"

package/hooks/blocking/state_description_blocker.py

@@ -13,6 +13,7 @@ import json
 import os
 import sys
 from pathlib import Path
+from re import Pattern
 from typing import TextIO
 
 try:
@@ -33,10 +34,13 @@ try:
         ALL_HASH_AND_SLASH_EXTENSIONS,
         ALL_HASH_ONLY_EXTENSIONS,
         ALL_MARKDOWN_EXTENSIONS,
-        CODE_FENCE_PATTERN,
+        BLOCK_COMMENT_CLOSE_MARKER,
+        BLOCK_COMMENT_OPEN_MARKER,
+        DOUBLE_QUOTE_BODY_GROUP,
         DOUBLE_QUOTED_SPAN_PATTERN,
         INLINE_CODE_PATTERN,
         PYTHON_EXTENSION,
+        SINGLE_QUOTE_BODY_GROUP,
         TRIPLE_QUOTED_BLOCK_PATTERN,
     )
 except ImportError as import_error:
@@ -77,15 +81,56 @@ def _get_inline_markers(extension: str) -> tuple[str, ...]:
     return ("//",)
 
 
-def _extract_comment_lines(text: str, extension: str = "") -> list[str]:
-    """Extract comment lines from source code — Python (#), JS/TS/C/Rust/Go (//), and block comments."""
-    all_comment_lines: list[str] = []
-    all_lines = text.splitlines()
+def _consume_block_comment_open(
+    each_line_number: int, stripped: str
+) -> tuple[list[tuple[int, str]], str | None, bool]:
+    """Extract the comment span a ``/*``-opening line carries.
+
+    Returns the extracted entries, the leftover code text to keep scanning
+    on this same line (``None`` when the whole line was consumed), and
+    whether the comment is still open past this line.
+    """
+    slash_star_index = stripped.find(BLOCK_COMMENT_OPEN_MARKER)
+    close_star_index = stripped.find(
+        BLOCK_COMMENT_CLOSE_MARKER, slash_star_index + len(BLOCK_COMMENT_OPEN_MARKER)
+    )
+    if close_star_index < 0:
+        return [(each_line_number, stripped[slash_star_index:])], None, True
+    close_end = close_star_index + len(BLOCK_COMMENT_CLOSE_MARKER)
+    entry = (each_line_number, stripped[slash_star_index:close_end])
+    after_close = stripped[close_end:].lstrip()
+    return [entry], (after_close or None), False
+
+
+def _consume_block_comment_continuation(
+    each_line_number: int, stripped: str
+) -> tuple[list[tuple[int, str]], bool, bool]:
+    """Extract the comment span a line inside an already-open block carries.
+
+    Returns the extracted entries, whether the comment is still open past
+    this line, and whether the caller should move to the next source line.
+    """
+    close_index = stripped.find(BLOCK_COMMENT_CLOSE_MARKER)
+    if close_index < 0:
+        return [(each_line_number, stripped)], True, True
+    close_end = close_index + len(BLOCK_COMMENT_CLOSE_MARKER)
+    return [(each_line_number, stripped[:close_end])], False, False
+
+
+def _extract_comment_lines(text: str, extension: str = "") -> list[tuple[int, str]]:
+    """Return each comment line as ``(source_line_number, comment_text)``.
+
+    Covers Python (``#``), JS/TS/C/Rust/Go (``//``), and block comments, and
+    tags every extracted line with the source line it came from so a
+    matching pattern can be pinned to that line rather than searched for
+    again.
+    """
+    all_comment_lines: list[tuple[int, str]] = []
 
     is_in_block_comment = False
     has_block_comments = extension in ALL_BLOCK_COMMENT_EXTENSIONS
     all_inline_markers = _get_inline_markers(extension)
-    for each_line in all_lines:
+    for each_line_number, each_line in enumerate(text.splitlines(), 1):
         stripped = each_line.strip()
 
         if has_block_comments:
@@ -93,42 +138,33 @@ def _extract_comment_lines(text: str, extension: str = "") -> list[str]:
                 stripped.startswith(each_marker)
                 for each_marker in all_inline_markers
             ):
-                all_comment_lines.append(stripped)
+                all_comment_lines.append((each_line_number, stripped))
                 continue
-            if "/*" in stripped and not is_in_block_comment:
-                is_in_block_comment = True
-                slash_star_index = stripped.find("/*")
-                close_star_index = stripped.find("*/", slash_star_index + len("/*"))
-                if close_star_index >= 0:
-                    all_comment_lines.append(
-                        stripped[slash_star_index : close_star_index + 2]
-                    )
-                    is_in_block_comment = False
-                    after_close = stripped[close_star_index + 2:].lstrip()
-                    if not after_close:
-                        continue
-                    stripped = after_close
-                else:
-                    all_comment_lines.append(stripped[slash_star_index:])
+            if BLOCK_COMMENT_OPEN_MARKER in stripped and not is_in_block_comment:
+                entries, leftover, is_in_block_comment = _consume_block_comment_open(
+                    each_line_number, stripped
+                )
+                all_comment_lines.extend(entries)
+                if leftover is None:
                     continue
+                stripped = leftover
             if is_in_block_comment:
-                close_index = stripped.find("*/")
-                if close_index >= 0:
-                    all_comment_lines.append(stripped[: close_index + 2])
-                    is_in_block_comment = False
-                else:
-                    all_comment_lines.append(stripped)
+                entries, is_in_block_comment, should_continue = (
+                    _consume_block_comment_continuation(each_line_number, stripped)
+                )
+                all_comment_lines.extend(entries)
+                if should_continue:
                     continue
 
         if any(
             stripped.startswith(each_marker) for each_marker in all_inline_markers
         ):
-            all_comment_lines.append(stripped)
+            all_comment_lines.append((each_line_number, stripped))
             continue
 
         inline_index = _find_inline_comment_start(stripped, all_inline_markers)
         if inline_index is not None and inline_index > 0:
-            all_comment_lines.append(stripped[inline_index:])
+            all_comment_lines.append((each_line_number, stripped[inline_index:]))
             continue
 
     return all_comment_lines
@@ -154,16 +190,18 @@ def _find_inline_comment_start(stripped: str, all_markers: tuple[str, ...]) -> i
     return best_position
 
 
-def _extract_parsed_docstrings(tree: ast.Module) -> list[str]:
-    """Collect the module, class, and function docstrings from a parsed tree.
+def _extract_parsed_docstrings(tree: ast.Module) -> list[tuple[int, str]]:
+    """Return each docstring as ``(start_line, docstring_text)``.
 
     Args:
         tree: The parsed module tree to walk.
 
     Returns:
-        Every docstring found on the module and its class/function definitions.
+        One entry per docstring found on the module and its class/function
+        definitions, tagged with the source line the docstring's opening
+        quotes start on.
     """
-    all_found_docstrings: list[str] = []
+    all_found_docstrings: list[tuple[int, str]] = []
     for each_node in ast.walk(tree):
         if not isinstance(
             each_node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
@@ -171,102 +209,204 @@ def _extract_parsed_docstrings(tree: ast.Module) -> list[str]:
             continue
         maybe_docstring = ast.get_docstring(each_node, clean=False)
         if maybe_docstring:
-            all_found_docstrings.append(maybe_docstring)
+            docstring_statement = each_node.body[0]
+            all_found_docstrings.append((docstring_statement.lineno, maybe_docstring))
     return all_found_docstrings
 
 
-def _extract_fragment_docstrings(text: str) -> list[str]:
-    """Collect docstring-positioned triple-quoted blocks from an unparseable fragment.
+def _is_docstring_position(leading_text: str) -> bool:
+    """Decide whether the text before a triple-quoted block marks a docstring slot.
 
     A triple-quoted block counts as a docstring when it opens the fragment
-    (only whitespace before it) or when the nearest preceding non-blank line is
-    a def/class header ending in a colon. A block assigned to a name or sitting
-    elsewhere in the fragment is data and is skipped.
+    (only whitespace before it) or when the nearest preceding non-blank line
+    is a def/class header ending in a colon. A block assigned to a name or
+    sitting elsewhere in the fragment is data.
+    """
+    if not leading_text.strip():
+        return True
+    if leading_text.rpartition("\n")[2].strip():
+        return False
+    all_preceding_lines = [
+        each_line for each_line in leading_text.splitlines() if each_line.strip()
+    ]
+    if not all_preceding_lines:
+        return False
+    last_preceding_line = all_preceding_lines[-1].strip()
+    return last_preceding_line.startswith(
+        ALL_DEFINITION_HEADER_PREFIXES
+    ) and last_preceding_line.endswith(":")
+
+
+def _extract_fragment_docstrings(text: str) -> list[tuple[int, str]]:
+    """Return docstring-positioned triple-quoted blocks from an unparseable fragment.
 
     Args:
         text: The Python source fragment that failed to parse.
 
     Returns:
-        The body text of each docstring-positioned triple-quoted block.
+        One ``(start_line, body_text)`` pair per docstring-positioned
+        triple-quoted block, tagged with the source line its opening quotes
+        start on.
     """
-    all_found_docstrings: list[str] = []
+    all_found_docstrings: list[tuple[int, str]] = []
     for each_match in TRIPLE_QUOTED_BLOCK_PATTERN.finditer(text):
-        body = each_match.group(1) if each_match.group(1) is not None else each_match.group(2)
+        body = (
+            each_match.group(DOUBLE_QUOTE_BODY_GROUP)
+            if each_match.group(DOUBLE_QUOTE_BODY_GROUP) is not None
+            else each_match.group(SINGLE_QUOTE_BODY_GROUP)
+        )
+        start_line = text.count("\n", 0, each_match.start()) + 1
         leading_text = text[: each_match.start()]
-        if not leading_text.strip():
-            all_found_docstrings.append(body)
-            continue
-        if leading_text.rpartition("\n")[2].strip():
-            continue
-        all_preceding_lines = [
-            each_line for each_line in leading_text.splitlines() if each_line.strip()
-        ]
-        last_preceding_line = all_preceding_lines[-1].strip()
-        if last_preceding_line.startswith(
-            ALL_DEFINITION_HEADER_PREFIXES
-        ) and last_preceding_line.endswith(":"):
-            all_found_docstrings.append(body)
+        if _is_docstring_position(leading_text):
+            all_found_docstrings.append((start_line, body))
     return all_found_docstrings
 
 
-def _extract_python_docstring_text(text: str) -> str:
-    """Return the scannable docstring prose from Python source.
+def _docstring_scan_lines(text: str) -> list[tuple[int, str]]:
+    """Return each docstring's prose as ``(source_line_number, line_text)`` pairs.
 
     Parses the source when valid, or falls back to the docstring-positioned
     triple-quoted blocks of a mid-edit fragment. Double-quoted and backticked
     spans inside each docstring are mentions rather than uses, so both are
-    stripped from the returned prose.
+    stripped before the docstring is split back into its own source lines.
 
     Args:
         text: The Python source or fragment under scan.
 
     Returns:
-        The docstring prose joined into one scannable string.
+        One entry per physical line of docstring prose, numbered against the
+        source file so a pattern match on that line carries the line the
+        rule matched rather than an unrelated occurrence elsewhere in the
+        file.
     """
     try:
         all_found_docstrings = _extract_parsed_docstrings(ast.parse(text))
     except (SyntaxError, ValueError):
         all_found_docstrings = _extract_fragment_docstrings(text)
-    all_docstring_prose = [
-        DOUBLE_QUOTED_SPAN_PATTERN.sub("", INLINE_CODE_PATTERN.sub("", each_docstring))
-        for each_docstring in all_found_docstrings
-    ]
-    return "\n".join(all_docstring_prose)
+    all_scan_lines: list[tuple[int, str]] = []
+    for each_start_line, each_docstring in all_found_docstrings:
+        prose = DOUBLE_QUOTED_SPAN_PATTERN.sub(
+            "", INLINE_CODE_PATTERN.sub("", each_docstring)
+        )
+        for each_offset, each_prose_line in enumerate(prose.split("\n")):
+            all_scan_lines.append((each_start_line + each_offset, each_prose_line))
+    return all_scan_lines
 
 
-def find_violations(text: str, file_path: str) -> list[str]:
-    """Return all violated patterns found in text for the given file.
+def _markdown_scan_lines(text: str) -> list[tuple[int, str]]:
+    """Return each Markdown source line as ``(line_number, scannable_text)``.
 
-    For .md files, scans the entire text. For code files, scans comment lines,
-    and for Python files also scans module/class/function docstrings.
-    Returns a list of matched pattern source strings.
+    A fenced code block's content is data rather than prose, so a line
+    between a pair of ``` fence markers is skipped. An inline code span is a
+    mention rather than a use, so it is blanked out of the line it appears
+    on, the same way it is blanked from Python docstring prose.
+
+    Args:
+        text: The Markdown source to scan.
+
+    Returns:
+        One entry per source line outside a fenced code block, with its
+        inline code spans removed.
+    """
+    all_scan_lines: list[tuple[int, str]] = []
+    is_inside_fence = False
+    for each_line_number, each_line in enumerate(text.splitlines(), 1):
+        if each_line.strip().startswith("```"):
+            is_inside_fence = not is_inside_fence
+            continue
+        if is_inside_fence:
+            continue
+        all_scan_lines.append(
+            (each_line_number, INLINE_CODE_PATTERN.sub("", each_line))
+        )
+    return all_scan_lines
+
+
+def _first_pattern_match(
+    pattern: Pattern[str], all_scan_lines: list[tuple[int, str]]
+) -> tuple[str, int] | None:
+    """Return the first line a pattern matches, or None when it matches none."""
+    for each_line_number, each_line_text in all_scan_lines:
+        each_match = pattern.search(each_line_text)
+        if each_match is not None:
+            return (each_match.group(0).strip().lower(), each_line_number)
+    return None
+
+
+def _scan_lines_for_file(
+    text: str, extension: str, file_path: str
+) -> list[tuple[int, str]] | None:
+    """Return the file's scannable lines, or ``None`` when its kind carries no prose.
+
+    A ``.md`` file scans every source line outside a fenced code block. A
+    code file scans its comment lines, and a Python file also scans its
+    module, class, and function docstrings.
     """
-    extension = _get_file_extension(file_path)
     if is_markdown_file(file_path):
-        scan_text = text
-    elif is_comment_bearing_file(file_path):
-        all_comment_lines = _extract_comment_lines(text, extension)
-        scan_text = "\n".join(all_comment_lines)
-        if extension == PYTHON_EXTENSION:
-            scan_text = "\n".join([scan_text, _extract_python_docstring_text(text)])
-    else:
-        return []
+        return _markdown_scan_lines(text)
+    if not is_comment_bearing_file(file_path):
+        return None
+    all_scan_lines = _extract_comment_lines(text, extension)
+    if extension == PYTHON_EXTENSION:
+        return all_scan_lines + _docstring_scan_lines(text)
+    return all_scan_lines
+
+
+def _matched_transition_patterns(
+    all_scan_lines: list[tuple[int, str]],
+) -> list[tuple[str, int]]:
+    """Return each transition pattern the scan lines match, with its line."""
+    all_detected: list[tuple[str, int]] = []
+    for each_pattern in ALL_COMMENT_TRANSITION_PATTERNS:
+        matched_entry = _first_pattern_match(each_pattern, all_scan_lines)
+        if matched_entry is not None:
+            all_detected.append(matched_entry)
+    return all_detected
 
-    if is_markdown_file(file_path):
-        scan_text = CODE_FENCE_PATTERN.sub("", scan_text)
-        scan_text = INLINE_CODE_PATTERN.sub("", scan_text)
 
-    if not scan_text.strip():
+def find_violations_with_lines(text: str, file_path: str) -> list[tuple[str, int]]:
+    """Return each violated pattern with the source line the rule matched.
+
+    ::
+
+        # config.py
+        1  fixture_text = "the field was `previously` required"
+        4  def read_field():
+        5      \"\"\"Read the field.
+        7      `The field was previously required.`
+        8      \"\"\"
+        flag: ("previously", 7) and ("was previously", 7)  -- one per pattern
+        ok:   line 1 never reported  -- a plain string literal is fixture data, not prose
+
+    Each match is paired with the line it matched on, not an earlier mention
+    of the same words.
+
+    Args:
+        text: The file content to scan.
+        file_path: The path that selects the scan strategy for the file.
+
+    Returns:
+        One ``(matched_phrase, source_line_number)`` pair per matched
+        pattern, in pattern-declaration order, at most one match each.
+    """
+    extension = _get_file_extension(file_path)
+    all_scan_lines = _scan_lines_for_file(text, extension, file_path)
+    if all_scan_lines is None:
         return []
+    return _matched_transition_patterns(all_scan_lines)
 
-    all_detected: list[str] = []
-    all_transition_patterns = ALL_COMMENT_TRANSITION_PATTERNS
-    for each_pattern in all_transition_patterns:
-        all_matches = each_pattern.findall(scan_text)
-        if all_matches:
-            all_detected.append(all_matches[0].strip().lower())
 
-    return all_detected
+def find_violations(text: str, file_path: str) -> list[str]:
+    """Return all violated patterns found in text for the given file.
+
+    For .md files, scans the entire text. For code files, scans comment lines,
+    and for Python files also scans module/class/function docstrings.
+    Returns a list of matched pattern source strings.
+    """
+    return [
+        each_phrase
+        for each_phrase, _each_line_number in find_violations_with_lines(text, file_path)
+    ]
 
 
 def _build_deny_reason(file_path: str, all_detected_patterns: list[str]) -> str:

package/hooks/blocking/test_code_rules_enforcer_duplicate_body_hook_routing.py

@@ -1,20 +1,21 @@
-"""Entry-point tests proving the duplicate-body check guards hook-infrastructure files.
+"""Entry-point tests proving the duplicate-body check's lane assignment for hook files.
 
 The cross-file duplicate-body check exists to catch a helper copied across sibling
 modules in the ``blocking/`` hook directory itself — the exact directory the rest of
-the code-rules suite exempts. These tests drive the real entry points (the ``main()``
-stdin path and the pre-check CLI) with a hook-infrastructure target so the deny fires
-on the same path a live Write would take, rather than calling the check function
-directly.
+the code-rules suite exempts. CODE_RULES.md §11.6 assigns it by scope: it reads a
+sibling file, so it runs on the full gate only, and a hook-infrastructure target's
+live PreToolUse Write stays on the edit lane. These tests drive the shipped entry
+points (the ``main()`` stdin path and the pre-check CLI) with a hook-infrastructure
+target, so each lane's behavior is proven on the same path a live Write or a
+pre-check run would take, rather than by calling the check function directly.
 
 Each test builds a temporary tree whose tail mirrors a production hook directory
 (``packages/claude-dev-env/hooks/blocking``) so ``is_hook_infrastructure`` matches the
-target path the same way it would for the real directory.
+target path the same way it would for the production directory.
 """
 
 from __future__ import annotations
 
-import json
 import pathlib
 import shutil
 import sys
@@ -75,27 +76,22 @@ def _run_main_with_write_payload(
     return captured_stdout
 
 
-def test_write_of_copied_helper_into_hook_directory_denies(
+def test_write_of_copied_helper_into_hook_directory_does_not_deny(
     hook_blocking_dir: pathlib.Path,
 ) -> None:
-    """A Write that copies a sibling helper into a second hook file is denied.
+    """A live Write that copies a sibling helper into a second hook file is not denied.
 
-    The target lives under a hook-infrastructure path the rest of the code-rules
-    suite exempts, so this proves the duplicate-body check still guards the exact
-    directory its module docstring names as the primary target."""
+    Enforces CODE_RULES.md §11.6: "A check that reads a file other than the
+    target runs on the full gate." The cross-file duplicate-body check reads a
+    sibling module, so it is full-gate only; the live PreToolUse Write that
+    ``main()`` handles runs the edit lane, so it must not deny here even though
+    the copied helper is present."""
     (hook_blocking_dir / "existing_blocker.py").write_text(SHARED_HELPER_SOURCE, encoding="utf-8")
     new_file = hook_blocking_dir / "new_blocker.py"
     stdout = _run_main_with_write_payload(str(new_file), SHARED_HELPER_SOURCE)
-    assert stdout != "", (
-        "A copied helper written into a second hook-infrastructure file must "
-        "produce a deny payload, got empty stdout"
-    )
-    deny_payload = json.loads(stdout)
-    decision = deny_payload["hookSpecificOutput"]["permissionDecision"]
-    reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
-    assert decision == "deny", f"expected deny, got: {decision!r}"
-    assert "strip_code_and_quotes" in reason, (
-        f"the deny reason must name the duplicated helper, got: {reason!r}"
+    assert stdout == "", (
+        "the edit lane must not run the cross-file duplicate-body check, "
+        f"got stdout: {stdout!r}"
     )
 
 
@@ -124,9 +120,11 @@ def test_precheck_of_copied_helper_at_hook_target_exits_nonzero(
 ) -> None:
     """The pre-check CLI flags a copied helper judged at a hook-infrastructure target.
 
-    Driving the real ``--check`` argv path proves the gate's pre-check mode also
-    routes a hook ``.py`` target through the duplicate-body check rather than
-    exiting clean on the blanket hook-infrastructure exemption."""
+    Enforces CODE_RULES.md §11.6: hook-infrastructure targets "run ... the
+    whole roster on the full gate." The pre-check CLI runs the full gate, so
+    driving the shipped ``--check`` argv path proves it still routes a hook
+    ``.py`` target through the duplicate-body check rather than exiting clean
+    on the blanket hook-infrastructure exemption."""
     (hook_blocking_dir / "existing_blocker.py").write_text(SHARED_HELPER_SOURCE, encoding="utf-8")
     staging_directory = tmp_path
     candidate_file = staging_directory / "candidate.py"

package/hooks/blocking/test_state_description_blocker.py

@@ -26,6 +26,7 @@ if _HOOKS_ROOT not in sys.path:
 from pre_tool_use_dispatcher import NativeHook, run_native_hook  # noqa: E402
 from state_description_blocker import (  # noqa: E402
     build_deny_payload,
+    find_violations_with_lines,
 )
 from state_description_blocker import evaluate as _evaluate_without_opt_in  # noqa: E402
 
@@ -952,3 +953,45 @@ def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
     logged_record = json.loads(all_records[0])
     assert logged_record["hook"] == "state_description_blocker.py"
     assert logged_record["event"] == "PreToolUse"
+
+
+def test_find_violations_with_lines_names_the_docstring_line_not_the_fixture_line() -> None:
+    module_source = (
+        'fixture_text = "the field was previously required"\n'
+        "\n"
+        "\n"
+        "def read_field():\n"
+        '    """Read the field.\n'
+        "\n"
+        "    The field was previously required.\n"
+        '    """\n'
+        "    return 1\n"
+    )
+
+    all_violations = find_violations_with_lines(module_source, "src/module.py")
+
+    assert all_violations == [("previously", 7), ("was previously", 7)]
+
+
+def test_find_violations_with_lines_reports_first_matching_comment_line() -> None:
+    module_source = "x = 1\n# no longer needed\ny = 2\n# no longer used\n"
+
+    all_violations = find_violations_with_lines(module_source, "src/module.py")
+
+    assert all_violations == [("no longer", 2)]
+
+
+def test_find_violations_with_lines_reports_markdown_line_past_a_code_fence() -> None:
+    markdown_source = (
+        "# Title\n"
+        "\n"
+        "```\n"
+        "used to fail\n"
+        "```\n"
+        "\n"
+        "The API was previously public.\n"
+    )
+
+    all_violations = find_violations_with_lines(markdown_source, "docs/api.md")
+
+    assert all_violations == [("previously", 7), ("was previously", 7)]

package/hooks/hooks_constants/state_description_blocker_constants.py

@@ -40,12 +40,16 @@ ALL_COMMENT_TRANSITION_PATTERNS: list[Pattern[str]] = [
     compile(r"\bas of\b", IGNORECASE),
 ]
 
-CODE_FENCE_PATTERN: Pattern[str] = compile(r"```[\s\S]*?```")
+BLOCK_COMMENT_OPEN_MARKER: str = "/*"
+BLOCK_COMMENT_CLOSE_MARKER: str = "*/"
+
 INLINE_CODE_PATTERN: Pattern[str] = compile(r"``[^`]+``|`[^`]+`")
 DOUBLE_QUOTED_SPAN_PATTERN: Pattern[str] = compile(r'"[^"\n]*"')
 TRIPLE_QUOTED_BLOCK_PATTERN: Pattern[str] = compile(
     r'"""([\s\S]*?)"""|\'\'\'([\s\S]*?)\'\'\''
 )
+DOUBLE_QUOTE_BODY_GROUP: int = 1
+SINGLE_QUOTE_BODY_GROUP: int = 2
 
 PYTHON_EXTENSION: str = ".py"
 

package/hooks/hooks_constants/test_state_description_blocker_constants.py

@@ -0,0 +1,85 @@
+"""Behavior tests for state_description_blocker configuration constants."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from blocking.state_description_blocker import _extract_comment_lines
+from hooks_constants.state_description_blocker_constants import (
+    ALL_BLOCK_COMMENT_EXTENSIONS,
+    ALL_COMMENT_TRANSITION_PATTERNS,
+    ALL_HASH_ONLY_EXTENSIONS,
+    ALL_MARKDOWN_EXTENSIONS,
+    BLOCK_COMMENT_CLOSE_MARKER,
+    BLOCK_COMMENT_OPEN_MARKER,
+    DOUBLE_QUOTE_BODY_GROUP,
+    SINGLE_QUOTE_BODY_GROUP,
+    TRIPLE_QUOTED_BLOCK_PATTERN,
+)
+
+
+def test_transition_patterns_match_their_own_phrase() -> None:
+    all_phrases = [
+        "instead of",
+        "previously",
+        "was previously",
+        "used to",
+        "no longer",
+        "switched to",
+    ]
+    for each_phrase in all_phrases:
+        sentence = f"The field is {each_phrase} required."
+        assert any(
+            each_pattern.search(sentence) for each_pattern in ALL_COMMENT_TRANSITION_PATTERNS
+        ), each_phrase
+
+
+def test_transition_patterns_do_not_match_unrelated_prose() -> None:
+    sentence = "The path selects the scan strategy for the file."
+    assert not any(
+        each_pattern.search(sentence) for each_pattern in ALL_COMMENT_TRANSITION_PATTERNS
+    )
+
+
+def test_block_comment_markers_close_a_single_line_block_comment() -> None:
+    text = f"{BLOCK_COMMENT_OPEN_MARKER} note {BLOCK_COMMENT_CLOSE_MARKER}\ncode();"
+    all_comment_lines = _extract_comment_lines(text, ".js")
+    assert all_comment_lines == [
+        (1, f"{BLOCK_COMMENT_OPEN_MARKER} note {BLOCK_COMMENT_CLOSE_MARKER}")
+    ]
+
+
+def test_block_comment_markers_carry_an_unclosed_comment_to_the_next_line() -> None:
+    text = f"{BLOCK_COMMENT_OPEN_MARKER} still open\nclosed here {BLOCK_COMMENT_CLOSE_MARKER}"
+    all_comment_lines = _extract_comment_lines(text, ".js")
+    assert all_comment_lines == [
+        (1, f"{BLOCK_COMMENT_OPEN_MARKER} still open"),
+        (2, f"closed here {BLOCK_COMMENT_CLOSE_MARKER}"),
+    ]
+
+
+def test_double_and_single_quote_body_groups_index_the_matching_quote_style() -> None:
+    double_quoted_match = TRIPLE_QUOTED_BLOCK_PATTERN.search('"""double body"""')
+    assert double_quoted_match is not None
+    assert double_quoted_match.group(DOUBLE_QUOTE_BODY_GROUP) == "double body"
+    assert double_quoted_match.group(SINGLE_QUOTE_BODY_GROUP) is None
+
+    single_quoted_match = TRIPLE_QUOTED_BLOCK_PATTERN.search("'''single body'''")
+    assert single_quoted_match is not None
+    assert single_quoted_match.group(SINGLE_QUOTE_BODY_GROUP) == "single body"
+    assert single_quoted_match.group(DOUBLE_QUOTE_BODY_GROUP) is None
+
+
+def test_extension_sets_are_disjoint_from_markdown_extensions() -> None:
+    assert not (ALL_HASH_ONLY_EXTENSIONS & ALL_MARKDOWN_EXTENSIONS)
+    assert not (ALL_BLOCK_COMMENT_EXTENSIONS & ALL_MARKDOWN_EXTENSIONS)
+
+
+def test_python_is_hash_only_and_never_block_comment() -> None:
+    assert ".py" in ALL_HASH_ONLY_EXTENSIONS
+    assert ".py" not in ALL_BLOCK_COMMENT_EXTENSIONS

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.6.0",
+    "version": "8.6.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

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

@@ -81,23 +81,12 @@ def _diagnostics_for_messages(
     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/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(