claude-dev-env 1.50.0 → 1.50.2

package/hooks/blocking/code_rules_probe_recording.py

@@ -0,0 +1,225 @@
+"""Pytest test-function collection, isolation-fixture detection, and probe recording for the test-isolation check."""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_probe_chains import (  # noqa: E402
+    _descend_within_test_scope,
+    _dotted_attribute_chain,
+    _dotted_call_attribute_chain,
+    _environ_key_string_from_call,
+    _environ_key_string_from_subscript,
+    _resolve_chain_through_aliases,
+)
+from code_rules_probe_detection import (  # noqa: E402
+    _expanduser_argument_references_home,
+    _expanduser_method_call_targets_pathlib_path,
+    _expandvars_argument_references_home_or_temp,
+    _tempfile_factory_call_is_isolated_by_dir,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_DIR_ACCEPTING_TEMPFILE_FACTORY_DOTTED_NAMES,
+    ALL_FILESYSTEM_HOME_PROBE_DOTTED_NAMES,
+    ALL_HOME_DIRECTORY_ENV_VAR_NAMES,
+    ALL_PATHLIB_STATIC_EXPANDUSER_DOTTED_NAMES,
+    ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES,
+    EXPANDUSER_DOTTED_NAME,
+    EXPANDVARS_DOTTED_NAME,
+    PATHLIB_EXPANDUSER_METHOD_NAME,
+    PYTEST_TEST_CLASS_NAME_PREFIX,
+    PYTEST_USEFIXTURES_MARKER_NAME,
+)
+
+
+def _collect_pytest_collectable_test_functions(
+    syntax_tree: ast.Module,
+) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
+    """Enumerate the function nodes pytest would actually collect as tests.
+
+    Walks module-level statements and the top-level methods of module-level
+    classes only. Functions nested inside other functions or lambdas are
+    excluded because pytest does not collect nested callables. Module-level
+    classes whose name does not start with the
+    ``PYTEST_TEST_CLASS_NAME_PREFIX`` (``Test``) are skipped because the
+    repo's ``pytest.ini`` declares ``python_classes = Test*``; methods on
+    non-``Test*`` helper classes are never collected by pytest.
+    """
+    collectable: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
+    for each_module_statement in syntax_tree.body:
+        if isinstance(each_module_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if (
+                each_module_statement.name.startswith("test_")
+                or each_module_statement.name.startswith("should_")
+            ):
+                collectable.append(each_module_statement)
+        elif isinstance(each_module_statement, ast.ClassDef):
+            if not each_module_statement.name.startswith(PYTEST_TEST_CLASS_NAME_PREFIX):
+                continue
+            for each_class_member in each_module_statement.body:
+                if isinstance(each_class_member, (ast.FunctionDef, ast.AsyncFunctionDef)) and (
+                    each_class_member.name.startswith("test_")
+                    or each_class_member.name.startswith("should_")
+                ):
+                    collectable.append(each_class_member)
+    return collectable
+
+
+def _detect_home_or_temp_probes_in_body(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    all_canonical_names_by_alias: dict[str, str],
+    all_environ_local_bindings: set[str],
+    all_path_local_bindings: set[str],
+) -> list[tuple[int, str]]:
+    """Yield ``(line, probe_label)`` pairs for HOME/TMP probes in *function_node*.
+
+    The walk descends into ``ClassDef`` nodes nested inside the test body and
+    into their class-level statements. Class-level statements (class attribute
+    initializers) run at class-creation time as the ``class`` statement
+    executes during the test, so a probe in an initializer such as ``root =
+    Path.home()`` is on the test's runtime path and is reported. A method of a
+    nested class is a callable-scope boundary: Python does not run a method
+    just because its class is defined, so the walk does not descend into method
+    bodies. Standalone nested helper functions and lambdas defined anywhere are
+    likewise scope boundaries — each runs in its own callable scope and carries
+    its own isolation contract. Probes that genuinely execute on the test path
+    (top-level statements and class-level initializers) are still detected.
+
+    Args:
+        function_node: The test function whose body is being scanned.
+        all_canonical_names_by_alias: Local-binding-to-canonical-prefix mapping used to resolve
+            aliased imports before probe membership checks.
+        all_environ_local_bindings: Local names bound to ``os.environ`` (scoped
+            to *function_node*) used to attribute subscript and ``.get(...)``
+            reads to a HOME/TMP env probe.
+        all_path_local_bindings: Local names bound to a ``pathlib.Path``
+            construction (scoped to *function_node*) used to attribute a
+            ``.expanduser()`` method call to a home-directory probe.
+
+    Returns:
+        A list of ``(line_number, probe_label)`` tuples for each HOME/TMP
+        probe attributed to the test, in stack-pop order.
+    """
+    probes: list[tuple[int, str]] = []
+    for each_descendant in _descend_within_test_scope(function_node):
+        _record_home_or_temp_probe(
+            each_descendant,
+            probes,
+            all_canonical_names_by_alias,
+            all_environ_local_bindings,
+            all_path_local_bindings,
+        )
+    probes.sort(key=lambda each_probe: each_probe[0])
+    return probes
+
+
+def _record_home_or_temp_probe(
+    node: ast.AST,
+    all_probes: list[tuple[int, str]],
+    all_canonical_names_by_alias: dict[str, str],
+    all_environ_local_bindings: set[str],
+    all_path_local_bindings: set[str],
+) -> None:
+    if isinstance(node, ast.Call):
+        if _expanduser_method_call_targets_pathlib_path(
+            node, all_canonical_names_by_alias, all_path_local_bindings
+        ):
+            all_probes.append((node.lineno, f"Path.{PATHLIB_EXPANDUSER_METHOD_NAME}()"))
+            return
+        raw_chain = _dotted_call_attribute_chain(node)
+        if raw_chain is None:
+            return
+        canonical_chain = _resolve_chain_through_aliases(raw_chain, all_canonical_names_by_alias)
+        if canonical_chain == EXPANDVARS_DOTTED_NAME:
+            if _expandvars_argument_references_home_or_temp(node):
+                all_probes.append((node.lineno, f"{canonical_chain}()"))
+            return
+        if canonical_chain == EXPANDUSER_DOTTED_NAME:
+            if _expanduser_argument_references_home(node):
+                all_probes.append((node.lineno, f"{canonical_chain}()"))
+            return
+        if canonical_chain in ALL_PATHLIB_STATIC_EXPANDUSER_DOTTED_NAMES:
+            if _expanduser_argument_references_home(node):
+                all_probes.append((node.lineno, f"{canonical_chain}()"))
+            return
+        if canonical_chain in ALL_FILESYSTEM_HOME_PROBE_DOTTED_NAMES:
+            if (
+                canonical_chain in ALL_DIR_ACCEPTING_TEMPFILE_FACTORY_DOTTED_NAMES
+                and _tempfile_factory_call_is_isolated_by_dir(
+                    node, all_canonical_names_by_alias, all_environ_local_bindings
+                )
+            ):
+                return
+            all_probes.append((node.lineno, f"{canonical_chain}()"))
+            return
+        environ_key = _environ_key_string_from_call(
+            node, all_canonical_names_by_alias, all_environ_local_bindings
+        )
+        if environ_key in ALL_HOME_DIRECTORY_ENV_VAR_NAMES:
+            all_probes.append((node.lineno, f"os env probe '{environ_key}'"))
+        return
+    if isinstance(node, ast.Subscript):
+        environ_key = _environ_key_string_from_subscript(
+            node, all_canonical_names_by_alias, all_environ_local_bindings
+        )
+        if environ_key in ALL_HOME_DIRECTORY_ENV_VAR_NAMES:
+            all_probes.append((node.lineno, f"os.environ['{environ_key}']"))
+
+
+def _usefixtures_decorator_requests_isolation_fixture(decorator_node: ast.expr) -> bool:
+    """Report whether a decorator is ``usefixtures`` requesting an isolation fixture.
+
+    Recognizes ``@pytest.mark.usefixtures("monkeypatch")`` and the
+    ``@mark.usefixtures("monkeypatch")`` short form: an ``ast.Call`` whose callee
+    attribute chain ends in ``usefixtures`` and whose string-constant arguments
+    include any name in ``ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES``.
+
+    Args:
+        decorator_node: A single decorator expression from a test's decorator list.
+
+    Returns:
+        True when the decorator injects an isolation fixture by name.
+    """
+    if not isinstance(decorator_node, ast.Call):
+        return False
+    if not isinstance(decorator_node.func, ast.Attribute):
+        return False
+    callee_chain = _dotted_attribute_chain(decorator_node.func)
+    if callee_chain is None:
+        return False
+    if not callee_chain.endswith(PYTEST_USEFIXTURES_MARKER_NAME):
+        return False
+    for each_argument in decorator_node.args:
+        if (
+            isinstance(each_argument, ast.Constant)
+            and isinstance(each_argument.value, str)
+            and each_argument.value in ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES
+        ):
+            return True
+    return False
+
+
+def _function_uses_pytest_isolation_fixture(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    for each_argument in function_node.args.posonlyargs:
+        if each_argument.arg in ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES:
+            return True
+    for each_argument in function_node.args.args:
+        if each_argument.arg in ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES:
+            return True
+    for each_argument in function_node.args.kwonlyargs:
+        if each_argument.arg in ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES:
+            return True
+    for each_decorator in function_node.decorator_list:
+        if _usefixtures_decorator_requests_isolation_fixture(each_decorator):
+            return True
+    return False

package/hooks/blocking/code_rules_scope_binding.py

@@ -0,0 +1,151 @@
+"""Lexical scope-binding collectors used by the unused-import check."""
+
+import ast
+
+from hooks_constants.stuttering_import_binding_constants import (
+    WILDCARD_IMPORT_SENTINEL,
+)
+
+
+def _attribute_root_name_if_loaded(attribute_node: ast.Attribute) -> ast.Name | None:
+    current: ast.expr = attribute_node
+    while isinstance(current, ast.Attribute):
+        current = current.value
+    if isinstance(current, ast.Name) and isinstance(current.ctx, ast.Load):
+        return current
+    return None
+
+
+class _ScopeBindingCollector(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.binding_names: set[str] = set()
+        self.global_names: set[str] = set()
+
+    def collect_arguments(self, arguments: ast.arguments) -> None:
+        for each_argument in (
+            arguments.posonlyargs
+            + arguments.args
+            + arguments.kwonlyargs
+        ):
+            self.binding_names.add(each_argument.arg)
+        if arguments.vararg is not None:
+            self.binding_names.add(arguments.vararg.arg)
+        if arguments.kwarg is not None:
+            self.binding_names.add(arguments.kwarg.arg)
+
+    def visit_Global(self, node: ast.Global) -> None:
+        self.global_names.update(node.names)
+
+    def visit_Nonlocal(self, node: ast.Nonlocal) -> None:
+        self.binding_names.update(node.names)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self.binding_names.add(node.name)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self.binding_names.add(node.name)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.binding_names.add(node.name)
+
+    def visit_Lambda(self, node: ast.Lambda) -> None:
+        return None
+
+    def visit_Name(self, node: ast.Name) -> None:
+        if isinstance(node.ctx, ast.Store):
+            self.binding_names.add(node.id)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for each_alias in node.names:
+            self.binding_names.add(each_alias.asname or each_alias.name.split(".")[0])
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        for each_alias in node.names:
+            if each_alias.name != WILDCARD_IMPORT_SENTINEL:
+                self.binding_names.add(each_alias.asname or each_alias.name)
+
+    def visit_ListComp(self, node: ast.ListComp) -> None:
+        return None
+
+    def visit_SetComp(self, node: ast.SetComp) -> None:
+        return None
+
+    def visit_DictComp(self, node: ast.DictComp) -> None:
+        return None
+
+    def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
+        return None
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
+        if node.name is not None:
+            self.binding_names.add(node.name)
+        self.generic_visit(node)
+
+
+def _scope_binding_names(scope_node: ast.AST) -> tuple[set[str], set[str]]:
+    collector = _ScopeBindingCollector()
+    if isinstance(scope_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        collector.collect_arguments(scope_node.args)
+        for each_statement in scope_node.body:
+            collector.visit(each_statement)
+    elif isinstance(scope_node, ast.Lambda):
+        collector.collect_arguments(scope_node.args)
+        collector.visit(scope_node.body)
+    elif isinstance(scope_node, ast.ClassDef):
+        for each_statement in scope_node.body:
+            collector.visit(each_statement)
+    return collector.binding_names, collector.global_names
+
+
+def _load_name_is_shadowed(
+    load_node: ast.AST,
+    name: str,
+    parent_by_node_id: dict[int, ast.AST],
+) -> bool:
+    current = parent_by_node_id.get(id(load_node))
+    has_passed_function_scope = False
+    while current is not None:
+        if isinstance(current, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            has_passed_function_scope = True
+            binding_names, global_names = _scope_binding_names(current)
+            if name in global_names:
+                return False
+            if name in binding_names:
+                return True
+        elif isinstance(current, ast.ClassDef) and not has_passed_function_scope:
+            # Class body bindings are order-dependent (name resolution is
+            # dynamic, unlike function locals). A load before an assignment
+            # still resolves to the module-level name, so conservatively
+            # skip class-body shadow detection to avoid false positives.
+            pass
+        current = parent_by_node_id.get(id(current))
+    return False
+
+
+def _names_from_annotation_text(annotation_text: str) -> set[str]:
+    try:
+        annotation_tree = ast.parse(annotation_text, mode="eval")
+    except SyntaxError:
+        return set()
+    referenced_names: set[str] = set()
+    for each_node in ast.walk(annotation_tree):
+        if isinstance(each_node, ast.Name):
+            referenced_names.add(each_node.id)
+        elif isinstance(each_node, ast.Attribute):
+            root_name = _attribute_root_name_if_loaded(each_node)
+            if root_name is not None:
+                referenced_names.add(root_name.id)
+    return referenced_names
+
+
+def _collect_string_annotation_names(tree: ast.Module) -> set[str]:
+    referenced_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        annotation = None
+        if isinstance(each_node, ast.arg):
+            annotation = each_node.annotation
+        elif isinstance(each_node, (ast.AnnAssign, ast.FunctionDef, ast.AsyncFunctionDef)):
+            annotation = each_node.annotation if isinstance(each_node, ast.AnnAssign) else each_node.returns
+        if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+            referenced_names.update(_names_from_annotation_text(annotation.value))
+    return referenced_names

package/hooks/blocking/code_rules_shared.py

@@ -0,0 +1,301 @@
+"""Shared file classifiers, AST-walk helpers, and diff-scoping utilities for the code-rules checks."""
+
+import ast
+import difflib
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_DIFF_CHANGED_OPCODE_TAGS,
+    ALL_HOOK_INFRASTRUCTURE_PATTERNS,
+    ALL_MIGRATION_PATH_PATTERNS,
+    ALL_TEST_PATH_PATTERNS,
+    ALL_WORKFLOW_REGISTRY_PATTERNS,
+)
+from hooks_constants.unused_module_import_constants import (  # noqa: E402
+    TYPE_CHECKING_IDENTIFIER,
+)
+
+
+def get_file_extension(file_path: str) -> str:
+    """Extract lowercase file extension."""
+    dot_index = file_path.rfind(".")
+    if dot_index == -1:
+        return ""
+    return file_path[dot_index:].lower()
+
+
+def is_hook_infrastructure(file_path: str) -> bool:
+    """Check if file is a Claude Code hook (standalone infrastructure, not project code)."""
+    path_lower = "/" + file_path.lower().replace("\\", "/").lstrip("/")
+    return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_HOOK_INFRASTRUCTURE_PATTERNS)
+
+
+def is_test_file(file_path: str) -> bool:
+    """Check if file is a test file."""
+    path_lower = file_path.lower()
+    basename_lower = path_lower.replace("\\", "/").rsplit("/", 1)[-1]
+    if basename_lower == "conftest.py":
+        return True
+    return any(pattern in path_lower for pattern in ALL_TEST_PATH_PATTERNS)
+
+
+def is_workflow_registry_file(file_path: str) -> bool:
+    """Check if file is a workflow state/module registry file.
+
+    Workflow tab files and state/module registry files use UPPER_SNAKE naming
+    for StateDefinition and WorkflowModule instances by architectural convention.
+    These are module-level singletons, not misplaced literal constants.
+    """
+    path_lower = file_path.lower().replace("\\", "/")
+    return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_WORKFLOW_REGISTRY_PATTERNS)
+
+
+def is_spec_file(file_path: str) -> bool:
+    """Check if file is an E2E spec file."""
+    return ".spec." in file_path.lower()
+
+
+def _is_type_checking_guard(if_node: ast.If) -> bool:
+    test_node = if_node.test
+    if isinstance(test_node, ast.Name) and test_node.id == TYPE_CHECKING_IDENTIFIER:
+        return True
+    return isinstance(test_node, ast.Attribute) and test_node.attr == TYPE_CHECKING_IDENTIFIER
+
+
+def _walk_skipping_type_checking_blocks(node: ast.AST) -> "Iterator[ast.AST]":
+    for each_child in ast.iter_child_nodes(node):
+        if isinstance(each_child, ast.If) and _is_type_checking_guard(each_child):
+            continue
+        yield each_child
+        yield from _walk_skipping_type_checking_blocks(each_child)
+
+
+def _walk_skipping_nested_functions(node: ast.AST) -> "Iterator[ast.AST]":
+    for each_child in ast.iter_child_nodes(node):
+        if isinstance(each_child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        yield each_child
+        yield from _walk_skipping_nested_functions(each_child)
+
+
+def _walk_skipping_nested_function_defs(start_node: ast.AST) -> Iterator[ast.AST]:
+    if isinstance(start_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return
+    nodes_to_visit: list[ast.AST] = [start_node]
+    while nodes_to_visit:
+        current_node = nodes_to_visit.pop()
+        yield current_node
+        all_child_nodes = list(ast.iter_child_nodes(current_node))
+        for each_child_node in reversed(all_child_nodes):
+            if isinstance(each_child_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            nodes_to_visit.append(each_child_node)
+
+
+def _collect_annotated_arguments(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[ast.arg]:
+    """Return every argument node on a function that may carry an annotation."""
+    arguments = function_node.args
+    all_annotated_arguments: list[ast.arg] = []
+    all_annotated_arguments.extend(arguments.posonlyargs)
+    all_annotated_arguments.extend(arguments.args)
+    all_annotated_arguments.extend(arguments.kwonlyargs)
+    if arguments.vararg is not None:
+        all_annotated_arguments.append(arguments.vararg)
+    if arguments.kwarg is not None:
+        all_annotated_arguments.append(arguments.kwarg)
+    return all_annotated_arguments
+
+
+def _collect_target_names(target: ast.expr) -> list[ast.Name]:
+    """Return every ast.Name reachable through tuple/list/starred unpacking targets."""
+    if isinstance(target, ast.Name):
+        return [target]
+    if isinstance(target, (ast.Tuple, ast.List)):
+        names: list[ast.Name] = []
+        for each_element in target.elts:
+            names.extend(_collect_target_names(each_element))
+        return names
+    if isinstance(target, ast.Starred):
+        return _collect_target_names(target.value)
+    return []
+
+
+def _extract_fstring_literal_parts(
+    joined_string_node: ast.JoinedStr,
+    interpolation_placeholder: str = "INTERP",
+) -> tuple[str, str]:
+    """Return (display_body, shape_body) for an f-string node.
+
+    ``display_body`` concatenates only the literal segments for use in the
+    human-readable flag message. ``shape_body`` substitutes each interpolation
+    slot with ``interpolation_placeholder`` so callers can choose a token that
+    both preserves structural shape and does not collide with literal text in
+    the source. The default ``"INTERP"`` keeps regex patterns for path shape
+    (``\\w+/\\w+/\\w+``) matching across interpolation boundaries
+    (e.g. ``/api/v1/{id}/home`` keeps its three path segments instead of
+    collapsing to ``/api/v1//home``). Callers that will compare shape bodies
+    verbatim — such as the skeleton builder — should pass their final token
+    here directly rather than post-processing with ``.replace``, since that
+    would corrupt literal text containing the default placeholder. Escaped
+    braces (``{{`` / ``}}``) are already decoded by :mod:`ast` into their
+    literal forms.
+    """
+    display_segments: list[str] = []
+    shape_segments: list[str] = []
+    for each_part in joined_string_node.values:
+        if isinstance(each_part, ast.Constant) and isinstance(each_part.value, str):
+            display_segments.append(each_part.value)
+            shape_segments.append(each_part.value)
+        else:
+            shape_segments.append(interpolation_placeholder)
+    return "".join(display_segments), "".join(shape_segments)
+
+
+def is_migration_file(file_path: str) -> bool:
+    """Check if file is a Django migration (must be self-contained)."""
+    path_lower = file_path.lower().replace("\\", "/")
+    return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_MIGRATION_PATH_PATTERNS)
+
+
+def _build_parent_map(module_tree: ast.Module) -> dict[int, ast.AST]:
+    """Map child node id() to its parent node for ancestor walking."""
+    parent_by_child_id: dict[int, ast.AST] = {}
+    for each_parent in ast.walk(module_tree):
+        for each_child in ast.iter_child_nodes(each_parent):
+            parent_by_child_id[id(each_child)] = each_parent
+    return parent_by_child_id
+
+
+def _statement_is_docstring(statement_node: ast.stmt) -> bool:
+    return (
+        isinstance(statement_node, ast.Expr)
+        and isinstance(statement_node.value, ast.Constant)
+        and isinstance(statement_node.value.value, str)
+    )
+
+
+def _function_definition_line_span(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> int:
+    end_lineno = getattr(function_node, "end_lineno", None) or function_node.lineno
+    return end_lineno - function_node.lineno + 1
+
+
+def _definition_docstring_line_span(
+    definition_node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
+) -> int:
+    """Return the source-line count of the definition's leading docstring.
+
+    The Google Python Style Guide pairs a small-function preference that
+    targets executable complexity with a requirement for complete docstrings
+    on public functions and classes. Counting those docstring lines toward the
+    function-length gate would penalize the very documentation the Guide
+    mandates, so the gate measures executable span and excludes leading
+    docstring statements.
+
+    Args:
+        definition_node: The function, method, or class definition node to
+            inspect.
+
+    Returns:
+        The number of source lines the leading docstring statement occupies,
+        or zero when the definition body is empty or does not open with a
+        string literal.
+    """
+    definition_body = definition_node.body
+    if not definition_body:
+        return 0
+    first_statement = definition_body[0]
+    if _statement_is_docstring(first_statement):
+        docstring_end = getattr(first_statement, "end_lineno", None) or first_statement.lineno
+        return docstring_end - first_statement.lineno + 1
+    return 0
+
+
+def changed_line_numbers(prior_content: str, post_edit_content: str) -> set[int]:
+    """Return the post-edit line numbers an edit added or replaced.
+
+    Runs a line-level diff of *prior_content* against *post_edit_content* and
+    collects the 1-indexed line numbers in *post_edit_content* that fall inside
+    a ``replace`` or ``insert`` opcode. This mirrors the "added lines" notion
+    that ``code_rules_gate.parse_added_line_numbers`` derives from
+    ``git diff --unified=0``, so the PreToolUse layer and the gate agree on
+    which lines the change touched.
+
+    Args:
+        prior_content: The file content before the edit.
+        post_edit_content: The reconstructed file content after the edit.
+
+    Returns:
+        The set of 1-indexed line numbers in *post_edit_content* that the edit
+        added or replaced.
+    """
+    matcher = difflib.SequenceMatcher(
+        a=prior_content.splitlines(),
+        b=post_edit_content.splitlines(),
+        autojunk=False,
+    )
+    all_changed_lines: set[int] = set()
+    for each_tag, _, _, each_post_start, each_post_end in matcher.get_opcodes():
+        if each_tag in ALL_DIFF_CHANGED_OPCODE_TAGS:
+            for each_post_index in range(each_post_start, each_post_end):
+                all_changed_lines.add(each_post_index + 1)
+    return all_changed_lines
+
+
+def _scope_violations_to_changed_lines(
+    all_violations_in_walk_order: list[tuple[range, str]],
+    all_changed_lines: set[int] | None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Scope span-tagged violations by diff intersection.
+
+    In-scope violations are always reported; the untouched out-of-scope set is
+    surfaced or dropped according to which caller path is active:
+
+    - ``defer_scope_to_caller`` True (the commit/push gate): every violation is
+      returned in walk order so the gate's ``split_violations_by_scope`` can
+      classify blocking vs advisory by added line. The gate does this scoping,
+      so no scoping happens here.
+    - ``all_changed_lines`` None (a terminal new-file or full-file write): every
+      line was just authored, so every violation is in scope and returned.
+    - ``all_changed_lines`` provided (a terminal diff-scoped Edit): only the
+      in-scope violations whose span intersects the changed lines are returned;
+      the untouched out-of-scope set is dropped, because untouched code must not
+      block a single-file edit.
+
+    Args:
+        all_violations_in_walk_order: ``(span_range, issue_message)`` pairs in
+            ``ast.walk`` traversal order, where ``span_range`` covers the
+            violation's source lines.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat every violation as in-scope.
+        defer_scope_to_caller: When True, return every violation message in walk
+            order so the gate scopes by added line. When False, this enforcer is
+            terminal and scopes directly.
+
+    Returns:
+        Every violation message when *defer_scope_to_caller* is True or
+        *all_changed_lines* is None; otherwise only the in-scope messages whose
+        span intersects the changed lines — so an edit that grows a function
+        past the threshold always blocks even when many earlier untouched
+        functions already exceed it.
+    """
+    if defer_scope_to_caller:
+        return [each_message for _, each_message in all_violations_in_walk_order]
+    if all_changed_lines is None:
+        return [each_message for _, each_message in all_violations_in_walk_order]
+    return [
+        each_message
+        for each_span, each_message in all_violations_in_walk_order
+        if any(each_line in all_changed_lines for each_line in each_span)
+    ]