claude-dev-env 1.50.0 → 1.50.2

package/hooks/blocking/code_rules_test_isolation.py

@@ -0,0 +1,341 @@
+"""Test-isolation check ensuring tests do not probe real home or shared-temp directories."""
+
+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
+    _attribute_chain_resolves_to_os_environ,
+    _canonical_probe_prefix_for_value,
+    _descend_within_test_scope,
+    _node_is_lexically_inside_function_or_class,
+    _record_probe_import_aliases,
+)
+from code_rules_probe_detection import (  # noqa: E402
+    _pathlib_path_construction_uses_home_tilde,
+)
+from code_rules_probe_recording import (  # noqa: E402
+    _collect_pytest_collectable_test_functions,
+    _detect_home_or_temp_probes_in_body,
+    _function_uses_pytest_isolation_fixture,
+)
+from code_rules_shared import (  # noqa: E402
+    _build_parent_map,
+    _function_definition_line_span,
+    _scope_violations_to_changed_lines,
+    is_test_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_CANONICAL_DOTTED_NAMES_BY_BARE_IMPORT,
+    OS_ENVIRON_DOTTED_NAME,
+    TEST_ISOLATION_MESSAGE_SUFFIX,
+)
+
+
+def _build_alias_canonicalization_map(syntax_tree: ast.Module) -> dict[str, str]:
+    """Map each module-level probe import local name to its canonical prefix.
+
+    Resolves both module aliases and bare-imported names so a dotted-call
+    chain rooted at any module-level binding rewrites to the canonical form the
+    probe set already matches:
+
+    - ``import os as o`` -> ``o`` resolves to ``os`` (so ``o.getenv`` ->
+      ``os.getenv`` and ``o.path.expanduser`` -> ``os.path.expanduser``).
+    - ``import os.path as op`` -> ``op`` resolves to ``os.path`` (so
+      ``op.expanduser`` -> ``os.path.expanduser``).
+    - ``import pathlib as pl`` -> ``pl`` resolves to ``pathlib``.
+    - ``from pathlib import Path as P`` -> ``P`` resolves to ``Path``.
+    - ``from os import path`` -> ``path`` resolves to ``os.path`` (so
+      ``path.expanduser`` -> ``os.path.expanduser``).
+    - ``from os.path import expanduser as e`` -> ``e`` resolves to
+      ``os.path.expanduser``; ``from os import getenv`` -> ``getenv``
+      resolves to ``os.getenv``; ``from os import environ`` -> ``environ``
+      resolves to ``os.environ``.
+
+    An import is module-scoped — and enters this shared map — when it is not
+    lexically inside any ``FunctionDef``/``AsyncFunctionDef``/``ClassDef`` body.
+    That admits top-level imports nested in module-level ``try``/``except``,
+    ``if``, or ``with`` blocks (the ``try: import os as o except ImportError:``
+    optional-import idiom binds ``o`` module-wide) while excluding both
+    function-local and class-body imports. A function-local import binds its
+    name only inside the function it appears in, and a class-body import binds
+    its alias only within the class namespace; neither may enter this shared,
+    module-wide map — otherwise a probe import inside one test would
+    canonicalize a same-named reference in a sibling test that never imported
+    it. Function-local imports are scoped to their own function by
+    ``_collect_local_probe_alias_bindings``.
+
+    Args:
+        syntax_tree: The parsed module to scan for module-scoped import
+            statements.
+
+    Returns:
+        Mapping from module-level local binding name to its canonical dotted
+        prefix.
+    """
+    parent_by_child_id = _build_parent_map(syntax_tree)
+    all_canonical_names_by_alias: dict[str, str] = {}
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, (ast.Import, ast.ImportFrom)):
+            continue
+        if _node_is_lexically_inside_function_or_class(each_node, parent_by_child_id):
+            continue
+        _record_probe_import_aliases(each_node, all_canonical_names_by_alias)
+    return all_canonical_names_by_alias
+
+
+def _collect_os_environ_local_binding_names(
+    scope_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    all_canonical_names_by_alias: dict[str, str],
+) -> set[str]:
+    """Return local names bound to ``os.environ`` within *scope_node*.
+
+    Scoped to the single test function passed as *scope_node* so a binding in
+    one test never attributes a same-named access in a sibling test. Tracks
+    ``e = os.environ`` style assignments (resolving the right-hand side through
+    *all_canonical_names_by_alias* so ``e = o.environ`` with ``import os as o``
+    is recognized) and ``from os import environ`` bindings (rare inside a
+    function but supported for completeness). Subscript and ``.get(...)`` reads
+    on these local names are treated as ``os.environ`` accesses.
+
+    Args:
+        scope_node: The single test function node to scan for bindings.
+        all_canonical_names_by_alias: Import-alias map from
+            ``_build_alias_canonicalization_map``.
+
+    Returns:
+        Set of local variable names that reference ``os.environ``.
+    """
+    environ_bindings: set[str] = set()
+    for each_node in _descend_within_test_scope(scope_node):
+        if isinstance(each_node, ast.ImportFrom):
+            for each_alias in each_node.names:
+                canonical_dotted = ALL_CANONICAL_DOTTED_NAMES_BY_BARE_IMPORT.get(
+                    (each_node.module or "", each_alias.name)
+                )
+                if canonical_dotted == OS_ENVIRON_DOTTED_NAME:
+                    environ_bindings.add(each_alias.asname or each_alias.name)
+            continue
+        if not isinstance(each_node, ast.Assign):
+            continue
+        if not _attribute_chain_resolves_to_os_environ(each_node.value, all_canonical_names_by_alias):
+            continue
+        for each_target in each_node.targets:
+            if isinstance(each_target, ast.Name):
+                environ_bindings.add(each_target.id)
+    return environ_bindings
+
+
+def _collect_pathlib_path_local_binding_names(
+    scope_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    all_canonical_names_by_alias: dict[str, str],
+) -> set[str]:
+    """Return local names bound to a home-tilde ``pathlib.Path(...)`` construction.
+
+    Scoped to the single test function passed as *scope_node* so a binding in
+    one test never attributes a same-named ``.expanduser()`` call in a sibling
+    test. Tracks ``candidate = Path('~/x')`` style assignments whose first
+    constructor argument is a literal string beginning with ``~`` (resolving
+    the constructor through *all_canonical_names_by_alias* so an aliased
+    ``candidate = P('~/x')`` with ``from pathlib import Path as P`` and a
+    fully qualified ``candidate = pathlib.Path('~/x')`` are both recognized).
+    A later ``candidate.expanduser()`` call on such a name is attributed to a
+    home-directory probe. A tilde-free or dynamic constructor argument
+    (``Path('/tmp/x')`` / ``Path(some_path)``) expands no home directory and
+    is not collected, keeping the instance ``.expanduser()`` form symmetric
+    with ``os.path.expanduser`` argument inspection.
+
+    Args:
+        scope_node: The single test function node to scan for bindings.
+        all_canonical_names_by_alias: Import-alias map from
+            ``_build_alias_canonicalization_map``.
+
+    Returns:
+        Set of local variable names bound to a home-tilde ``pathlib.Path``
+        construction.
+    """
+    path_bindings: set[str] = set()
+    for each_node in _descend_within_test_scope(scope_node):
+        if not isinstance(each_node, ast.Assign):
+            continue
+        if not _pathlib_path_construction_uses_home_tilde(
+            each_node.value, all_canonical_names_by_alias
+        ):
+            continue
+        for each_target in each_node.targets:
+            if isinstance(each_target, ast.Name):
+                path_bindings.add(each_target.id)
+    return path_bindings
+
+
+def _collect_local_probe_alias_bindings(
+    scope_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    all_canonical_names_by_alias: dict[str, str],
+) -> dict[str, str]:
+    """Return a per-test overlay mapping local names to canonical probe prefixes.
+
+    Scoped to the single test function passed as *scope_node* so an alias bound
+    in one test never resolves a same-named access in a sibling test. Two
+    binding forms are tracked, both scoped to this function only:
+
+    - Function-local imports — ``import os as o``, ``from os import environ``,
+      ``from pathlib import Path`` — resolved through the same probe-relevant
+      filtering ``_build_alias_canonicalization_map`` applies to module-level
+      imports. Because the shared module map omits function-local imports, this
+      overlay is the only place a probe import inside one test takes effect, and
+      it stays confined to that test's body.
+    - Rebindings of a probe module, class, or callable to a local name —
+      ``path_class = Path``, ``read_env = os.getenv``, ``temp_module = tempfile``,
+      ``path_module = os.path``, ``e = os.environ`` — by resolving each
+      right-hand side through *all_canonical_names_by_alias* and keeping only
+      those whose canonical prefix is probe-aliasable
+      (``ALL_PROBE_ALIASABLE_CANONICAL_PREFIXES``).
+
+    Merged over the module-level alias map, the overlay lets a later
+    ``path_class.home()`` / ``read_env('HOME')`` / ``temp_module.mkdtemp()``
+    resolve to its canonical probe chain.
+
+    Args:
+        scope_node: The single test function node to scan for alias bindings.
+        all_canonical_names_by_alias: Module-level import-alias map from
+            ``_build_alias_canonicalization_map``.
+
+    Returns:
+        Mapping from local binding name to its canonical probe prefix.
+    """
+    local_alias_canonical_names: dict[str, str] = {}
+    for each_node in _descend_within_test_scope(scope_node):
+        if isinstance(each_node, (ast.Import, ast.ImportFrom)):
+            _record_probe_import_aliases(each_node, local_alias_canonical_names)
+            continue
+        if not isinstance(each_node, ast.Assign):
+            continue
+        canonical_prefix = _canonical_probe_prefix_for_value(
+            each_node.value, all_canonical_names_by_alias
+        )
+        if canonical_prefix is None:
+            continue
+        for each_target in each_node.targets:
+            if isinstance(each_target, ast.Name):
+                local_alias_canonical_names[each_target.id] = canonical_prefix
+    return local_alias_canonical_names
+
+
+def check_tests_use_isolated_filesystem_paths(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag test functions that probe HOME or TMP without pytest isolation.
+
+    Pattern class: tests that call ``Path.home()``, ``os.path.expanduser('~')``,
+    ``os.getenv('HOME'|'USERPROFILE'|'TMPDIR'|…)``, ``os.environ['HOME'|…]``, or
+    ``tempfile.gettempdir()`` against the real environment leak state across
+    the suite and surface as environment-coupled bugs (audit Theme M).
+
+    Test functions whose signatures take ``monkeypatch`` are treated as
+    intentionally isolated and pass — ``monkeypatch.setenv('HOME', ...)``
+    can intercept every env-derived probe, and this suppression applies
+    uniformly to every probe type below. ``tmp_path`` / ``tmp_path_factory``
+    / ``tmpdir`` / ``tmpdir_factory`` allocate alternative sandbox paths but
+    do not intercept env reads, so their presence alone does not suppress
+    the check. Module-level helpers and fixtures (any function whose name
+    does not start with ``test_`` or ``should_``) are out of scope — only
+    pytest-collectable ``def test_*`` / ``async def test_*`` / ``def
+    should_*`` module-level or class-method functions are scanned.
+
+    Covered forms (API surface × access form):
+        Probe API surfaces — ``pathlib.Path.home()``,
+        ``pathlib.Path('~...').expanduser()``, ``os.path.expanduser(arg)``,
+        ``os.path.expandvars(arg)``, ``os.getenv(name)``,
+        ``os.environ[name]``, ``os.environ.get(name)``, and the ``tempfile``
+        allocators (``gettempdir``, ``gettempdirb``, ``gettempprefix``,
+        ``mkstemp``, ``mkdtemp``, ``mktemp``, ``NamedTemporaryFile``,
+        ``TemporaryFile``, ``TemporaryDirectory``, ``SpooledTemporaryFile``).
+        Each surface is recognized through four access forms: (1) canonical
+        dotted (``os.path.expanduser``), (2) module-level ``from X import
+        name`` bare use (``from os import environ; environ['HOME']``),
+        (3) module-level aliased import (``import tempfile as tf;
+        tf.mkdtemp()``), and (4) a function-local binding tracked per test —
+        either a function-local import (``def t(): from os import environ;
+        environ['HOME']``) or a local rebinding (``path_class = Path;
+        path_class.home()``; ``read_env = os.getenv; read_env('HOME')``). A
+        function-local binding never leaks into a sibling test, so a same-named
+        bare reference in another test that lacks its own binding does not fire.
+        Gating is symmetric across the two ``expanduser`` forms (flag only on a
+        leading-``~`` literal) and across the env getters / subscript (flag only
+        on a home/temp env-var name). Probes are reported in source-line order
+        for every probe type.
+
+    Out of scope by design (dynamically constructed call targets that no
+    AST-level pattern can resolve statically): attribute access through
+    ``getattr(os, 'environ')``, callable names assembled at runtime by
+    string concatenation, and calls built through ``exec``/``eval``. These
+    bound the detector to a fixed, documented surface rather than an
+    open-ended chase.
+
+    Args:
+        content: The Python source to analyze.
+        file_path: The path of the file being checked. The check only fires
+            on test files.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a probe
+            blocks when any line of its enclosing test function's declared span
+            (signature line through last body line) is among the changed lines,
+            so editing the signature to remove an isolation fixture brings an
+            unchanged-body probe into scope.
+        defer_scope_to_caller: When True, return every probe so the commit/push
+            gate's ``split_violations_by_scope`` can scope by added line and
+            report the in-scope set.
+
+    Returns:
+        A list of issue strings naming each offending probe call. When
+        *defer_scope_to_caller* is True every probe is returned for the gate to
+        scope; otherwise every probe in scope is returned.
+    """
+    if not is_test_file(file_path):
+        return []
+
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    all_module_canonical_names_by_alias = _build_alias_canonicalization_map(syntax_tree)
+    all_violations_in_source_line_order: list[tuple[range, str]] = []
+    for each_node in _collect_pytest_collectable_test_functions(syntax_tree):
+        if _function_uses_pytest_isolation_fixture(each_node):
+            continue
+        all_canonical_names_by_alias = {
+            **all_module_canonical_names_by_alias,
+            **_collect_local_probe_alias_bindings(each_node, all_module_canonical_names_by_alias),
+        }
+        all_environ_local_bindings = _collect_os_environ_local_binding_names(each_node, all_canonical_names_by_alias)
+        all_path_local_bindings = _collect_pathlib_path_local_binding_names(each_node, all_canonical_names_by_alias)
+        line_span = _function_definition_line_span(each_node)
+        enclosing_function_span = range(each_node.lineno, each_node.lineno + line_span)
+        for each_line, each_probe_label in _detect_home_or_temp_probes_in_body(
+            each_node, all_canonical_names_by_alias, all_environ_local_bindings, all_path_local_bindings
+        ):
+            message = (
+                f"Line {each_line}: Test {each_node.name!r} "
+                f"(defined at line {each_node.lineno}, spanning {line_span} lines) "
+                f"probes {each_probe_label} - {TEST_ISOLATION_MESSAGE_SUFFIX}"
+            )
+            all_violations_in_source_line_order.append(
+                (enclosing_function_span, message)
+            )
+    return _scope_violations_to_changed_lines(
+        all_violations_in_source_line_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )

package/hooks/blocking/code_rules_type_escape.py

@@ -0,0 +1,341 @@
+"""Type escape-hatch and boundary-type checks: Any imports, cast(), unjustified type: ignore, and Any in signatures."""
+
+import ast
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+_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_comments import (  # noqa: E402
+    _comment_tokens,
+)
+from code_rules_shared import (  # noqa: E402
+    _collect_annotated_arguments,
+    _walk_skipping_type_checking_blocks,
+    is_hook_infrastructure,
+    is_test_file,
+)
+
+from hooks_constants.any_type_config import (  # noqa: E402
+    ALL_ANY_ALLOWED_PATTERNS,
+)
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_BOUNDARY_TYPE_EXEMPT_FILENAMES,
+    MAX_BOUNDARY_TYPE_ISSUES,
+    MAX_TYPE_ESCAPE_HATCH_ISSUES,
+)
+
+
+def _render_annotation_source(annotation_node: ast.expr) -> str:
+    """Return a textual representation of an annotation AST node."""
+    unparse_function = getattr(ast, "unparse", None)
+    if unparse_function is not None:
+        return unparse_function(annotation_node)
+    sys.stderr.write(
+        "code_rules_enforcer: ast.unparse unavailable on this interpreter; "
+        "falling back to ast.dump for Any detection.\n"
+    )
+    return ast.dump(annotation_node)
+
+
+def _annotation_uses_any(annotation_node: Optional[ast.expr]) -> bool:
+    """Return True when an annotation AST node textually references Any."""
+    if annotation_node is None:
+        return False
+    annotation_source = _render_annotation_source(annotation_node)
+    return bool(re.search(r"\bAny\b", annotation_source))
+
+
+def _find_any_annotation_lines(source: str) -> list[int]:
+    """Return line numbers of annotations that textually reference Any."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    offending_line_numbers: list[int] = []
+    already_reported_lines: set[int] = set()
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if isinstance(each_node, ast.AnnAssign) and _annotation_uses_any(each_node.annotation):
+            if each_node.lineno not in already_reported_lines:
+                offending_line_numbers.append(each_node.lineno)
+                already_reported_lines.add(each_node.lineno)
+            continue
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _annotation_uses_any(each_node.returns) and each_node.lineno not in already_reported_lines:
+                offending_line_numbers.append(each_node.lineno)
+                already_reported_lines.add(each_node.lineno)
+            for each_argument in _collect_annotated_arguments(each_node):
+                if _annotation_uses_any(each_argument.annotation) and each_argument.lineno not in already_reported_lines:
+                    offending_line_numbers.append(each_argument.lineno)
+                    already_reported_lines.add(each_argument.lineno)
+    return offending_line_numbers
+
+
+def _find_unjustified_type_ignore_lines(source: str) -> list[int]:
+    """Return line numbers of # type: ignore comments lacking a trailing reason."""
+    ignore_pattern = re.compile(r"#\s*type:\s*ignore(?:\[[^\]]*\])?(.*)$")
+    minimum_justification_characters = len("xxxxx")
+    offending_line_numbers: list[int] = []
+    for each_comment_token in _comment_tokens(source):
+        matched = ignore_pattern.search(each_comment_token.string)
+        if not matched:
+            continue
+        line_number = each_comment_token.start[0]
+        trailing_text = matched.group(1).strip()
+        if not trailing_text.startswith("#"):
+            offending_line_numbers.append(line_number)
+            continue
+        justification_text = trailing_text.lstrip("#").strip()
+        if len(justification_text) < minimum_justification_characters:
+            offending_line_numbers.append(line_number)
+    return offending_line_numbers
+
+
+def _find_typing_any_imports(source: str) -> list[int]:
+    """Return line numbers of `from typing import ... Any ...` statements."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    offending_line_numbers: list[int] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if each_node.module != "typing":
+            continue
+        for each_alias in each_node.names:
+            if each_alias.name == "Any":
+                offending_line_numbers.append(each_node.lineno)
+                break
+    return offending_line_numbers
+
+
+def _find_typing_wildcard_imports(source: str) -> list[int]:
+    """Return line numbers of `from typing import *` statements."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    offending_line_numbers: list[int] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if each_node.module != "typing":
+            continue
+        for each_alias in each_node.names:
+            if each_alias.name == "*":
+                offending_line_numbers.append(each_node.lineno)
+                break
+    return offending_line_numbers
+
+
+def _collect_typing_cast_import_names(source: str) -> frozenset[str]:
+    """Return the set of names bound to typing.cast via `from typing import cast`."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return frozenset()
+
+    cast_names: set[str] = set()
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if each_node.module != "typing":
+            continue
+        for each_alias in each_node.names:
+            if each_alias.name == "cast":
+                cast_names.add(each_alias.asname or each_alias.name)
+    return frozenset(cast_names)
+
+
+def _is_typing_cast_call(call_node: ast.Call, all_cast_import_names: frozenset[str]) -> bool:
+    """Return True when a Call node represents a typing.cast() or known bare cast()."""
+    function_node = call_node.func
+    if isinstance(function_node, ast.Attribute) and function_node.attr == "cast":
+        if isinstance(function_node.value, ast.Name) and function_node.value.id == "typing":
+            return True
+    if isinstance(function_node, ast.Name) and function_node.id in all_cast_import_names:
+        return True
+    return False
+
+
+def _find_cast_call_lines(source: str) -> list[int]:
+    """Return line numbers of cast(...) calls (typing.cast or bare cast)."""
+    try:
+        parsed_tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    all_cast_import_names = _collect_typing_cast_import_names(source)
+
+    offending_line_numbers: list[int] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if isinstance(each_node, ast.Call) and _is_typing_cast_call(each_node, all_cast_import_names):
+            offending_line_numbers.append(each_node.lineno)
+    return offending_line_numbers
+
+
+def _file_path_matches_any_exemption(file_path: str) -> bool:
+    filename = file_path.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    return filename in {each_pattern.lower() for each_pattern in ALL_ANY_ALLOWED_PATTERNS}
+
+
+def check_type_escape_hatches(content: str, file_path: str) -> list[str]:
+    """Flag Any annotations, Any imports, cast() calls, and unjustified # type: ignore."""
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+
+    issues: list[str] = []
+    is_any_exempt = _file_path_matches_any_exemption(file_path)
+
+    if not is_any_exempt:
+        any_annotation_issues: list[str] = []
+        for each_any_line in _find_any_annotation_lines(content):
+            any_annotation_issues.append(f"Line {each_any_line}: Any annotation - replace with explicit type")
+        issues.extend(any_annotation_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+        any_import_issues: list[str] = []
+        for each_import_line in _find_typing_any_imports(content):
+            any_import_issues.append(
+                f"Line {each_import_line}: 'from typing import Any' - remove the Any import and use explicit types"
+            )
+        issues.extend(any_import_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+        wildcard_issues: list[str] = []
+        for each_wildcard_line in _find_typing_wildcard_imports(content):
+            wildcard_issues.append(
+                f"Line {each_wildcard_line}: 'from typing import *' wildcard import - import explicit names instead"
+            )
+        issues.extend(wildcard_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+        cast_issues: list[str] = []
+        for each_cast_line in _find_cast_call_lines(content):
+            cast_issues.append(
+                f"Line {each_cast_line}: cast() call - escape hatch around the type system; use explicit types or runtime validation"
+            )
+        issues.extend(cast_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+    type_ignore_issues: list[str] = []
+    for each_ignore_line in _find_unjustified_type_ignore_lines(content):
+        type_ignore_issues.append(
+            f"Line {each_ignore_line}: Unjustified # type: ignore - add trailing '# reason' explaining why"
+        )
+    issues.extend(type_ignore_issues[:MAX_TYPE_ESCAPE_HATCH_ISSUES])
+
+    return issues
+
+
+def _annotation_node_references_any(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    for each_descendant in ast.walk(annotation_node):
+        if isinstance(each_descendant, ast.Name) and each_descendant.id == "Any":
+            return True
+        if isinstance(each_descendant, ast.Attribute) and each_descendant.attr == "Any":
+            return True
+    return False
+
+
+def _file_has_exempt_boundary_filename(file_path: str) -> bool:
+    filename = file_path.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    return filename in {each_name.lower() for each_name in ALL_BOUNDARY_TYPE_EXEMPT_FILENAMES}
+
+
+def _signature_annotations(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[
+    tuple[ast.expr, str, int]
+]:
+    collected_annotations: list[tuple[ast.expr, str, int]] = []
+    function_name = function_node.name
+    for each_argument in function_node.args.args:
+        if each_argument.annotation is not None:
+            collected_annotations.append(
+                (each_argument.annotation, f"{function_name}({each_argument.arg})", each_argument.lineno)
+            )
+    for each_argument in function_node.args.posonlyargs:
+        if each_argument.annotation is not None:
+            collected_annotations.append(
+                (each_argument.annotation, f"{function_name}({each_argument.arg})", each_argument.lineno)
+            )
+    for each_argument in function_node.args.kwonlyargs:
+        if each_argument.annotation is not None:
+            collected_annotations.append(
+                (each_argument.annotation, f"{function_name}({each_argument.arg})", each_argument.lineno)
+            )
+    if function_node.args.vararg is not None and function_node.args.vararg.annotation is not None:
+        collected_annotations.append(
+            (function_node.args.vararg.annotation, f"{function_name}(*{function_node.args.vararg.arg})", function_node.args.vararg.lineno)
+        )
+    if function_node.args.kwarg is not None and function_node.args.kwarg.annotation is not None:
+        collected_annotations.append(
+            (function_node.args.kwarg.annotation, f"{function_name}(**{function_node.args.kwarg.arg})", function_node.args.kwarg.lineno)
+        )
+    if function_node.returns is not None:
+        collected_annotations.append(
+            (function_node.returns, f"{function_name} -> return", function_node.returns.lineno)
+        )
+    return collected_annotations
+
+
+def _class_attribute_annotations(class_node: ast.ClassDef) -> list[tuple[ast.expr, str, int]]:
+    collected_annotations: list[tuple[ast.expr, str, int]] = []
+    for each_statement in class_node.body:
+        if isinstance(each_statement, ast.AnnAssign) and isinstance(each_statement.target, ast.Name):
+            collected_annotations.append(
+                (
+                    each_statement.annotation,
+                    f"{class_node.name}.{each_statement.target.id}",
+                    each_statement.lineno,
+                )
+            )
+    return collected_annotations
+
+
+def check_boundary_types(content: str, file_path: str) -> list[str]:
+    """Flag `Any` appearing in function signatures or class attribute annotations.
+
+    Module boundaries (function parameters, return types, class attributes)
+    must name the concrete shape they accept and produce. Local variable
+    annotations are private and exempt; `protocols.py` and `types.py` are
+    interface-declaration files and exempt.
+    """
+    if (
+        is_test_file(file_path)
+        or is_hook_infrastructure(file_path)
+        or _file_has_exempt_boundary_filename(file_path)
+    ):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for each_annotation, each_label, each_line_number in _signature_annotations(each_node):
+                if _annotation_node_references_any(each_annotation):
+                    issues.append(
+                        f"Line {each_line_number}: {each_label} uses Any at module boundary — "
+                        "name the concrete shape callers receive/produce"
+                    )
+        elif isinstance(each_node, ast.ClassDef):
+            for each_annotation, each_label, each_line_number in _class_attribute_annotations(each_node):
+                if _annotation_node_references_any(each_annotation):
+                    issues.append(
+                        f"Line {each_line_number}: {each_label} uses Any at class boundary — "
+                        "name the concrete shape this attribute holds"
+                    )
+        if len(issues) >= MAX_BOUNDARY_TYPE_ISSUES:
+            break
+    return issues[:MAX_BOUNDARY_TYPE_ISSUES]