Add tertiary AST import-helper boundary guards

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

CONTRIBUTING.md

@@ -103,6 +103,8 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_ast_secondary_import_helper_usage.py` (shared AST secondary import-helper usage enforcement across AST boundary guard suites),
   - `tests/test_ast_symbol_import_helper_import_boundary.py` (shared AST symbol-import helper import boundary enforcement across test modules),
   - `tests/test_ast_symbol_import_helper_usage.py` (shared AST symbol-import helper usage enforcement across AST boundary guard suites),
+  - `tests/test_ast_tertiary_import_helper_import_boundary.py` (shared AST tertiary import-helper import boundary enforcement across test modules),
+  - `tests/test_ast_tertiary_import_helper_usage.py` (shared AST tertiary import-helper usage enforcement across AST boundary guard suites),
   - `tests/test_binary_file_open_helper_usage.py` (shared binary file open helper usage enforcement),
   - `tests/test_browser_use_payload_helper_usage.py` (browser-use payload helper usage enforcement),
   - `tests/test_ci_workflow_quality_gates.py` (CI guard-stage + make-target enforcement),

tests/ast_import_utils.py

@@ -60,3 +60,11 @@ def imports_imports_imports_collect_function_sources(module_text: str) -> bool:
         module="tests.ast_import_utils",
         symbol="imports_imports_collect_function_sources",
     )
+
+
+def imports_imports_imports_imports_collect_function_sources(module_text: str) -> bool:
+    return imports_symbol_from_module(
+        module_text,
+        module="tests.ast_import_utils",
+        symbol="imports_imports_imports_collect_function_sources",
+    )

tests/test_architecture_marker_usage.py

@@ -32,6 +32,8 @@
     "tests/test_ast_secondary_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_import_boundary.py",
     "tests/test_ast_symbol_import_helper_usage.py",
+    "tests/test_ast_tertiary_import_helper_import_boundary.py",
+    "tests/test_ast_tertiary_import_helper_usage.py",
     "tests/test_guardrail_ast_utils.py",
     "tests/test_helper_transport_usage_boundary.py",
     "tests/test_manager_model_dump_usage.py",

tests/test_ast_call_symbol_helper_usage.py

@@ -13,6 +13,7 @@
     "tests/test_ast_module_import_helper_usage.py",
     "tests/test_ast_secondary_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_usage.py",
+    "tests/test_ast_tertiary_import_helper_usage.py",
 )
 
 

tests/test_ast_import_utils.py

@@ -5,6 +5,7 @@
     imports_collect_function_sources,
     imports_from_module,
     imports_imports_imports_collect_function_sources,
+    imports_imports_imports_imports_collect_function_sources,
     imports_imports_collect_function_sources,
     imports_symbol_from_module,
 )
@@ -211,6 +212,42 @@ def test_imports_imports_imports_collect_function_sources_ignores_non_from_impor
     assert imports_imports_imports_collect_function_sources(module_text) is False
 
 
+def test_imports_imports_imports_imports_collect_function_sources_detects_expected_import():
+    module_text = (
+        "from tests.ast_import_utils import imports_imports_imports_collect_function_sources\n"
+        "imports_imports_imports_collect_function_sources('dummy')\n"
+    )
+
+    assert imports_imports_imports_imports_collect_function_sources(module_text) is True
+
+
+def test_imports_imports_imports_imports_collect_function_sources_ignores_non_matching_imports():
+    module_text = (
+        "from tests.ast_import_utils import imports_imports_collect_function_sources\n"
+        "imports_imports_collect_function_sources('dummy')\n"
+    )
+
+    assert imports_imports_imports_imports_collect_function_sources(module_text) is False
+
+
+def test_imports_imports_imports_imports_collect_function_sources_supports_aliased_import():
+    module_text = (
+        "from tests.ast_import_utils import imports_imports_imports_collect_function_sources as helper\n"
+        "helper('dummy')\n"
+    )
+
+    assert imports_imports_imports_imports_collect_function_sources(module_text) is True
+
+
+def test_imports_imports_imports_imports_collect_function_sources_ignores_non_from_imports():
+    module_text = (
+        "import tests.ast_import_utils as import_utils\n"
+        "import_utils.imports_imports_imports_collect_function_sources('dummy')\n"
+    )
+
+    assert imports_imports_imports_imports_collect_function_sources(module_text) is False
+
+
 def test_calls_symbol_detects_direct_function_call():
     module_text = (
         "from tests.ast_function_source_utils import collect_function_sources\n"

tests/test_ast_import_utils_module_import_boundary.py

@@ -22,6 +22,8 @@
     "tests/test_ast_secondary_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_import_boundary.py",
     "tests/test_ast_symbol_import_helper_usage.py",
+    "tests/test_ast_tertiary_import_helper_import_boundary.py",
+    "tests/test_ast_tertiary_import_helper_usage.py",
     "tests/test_ast_import_utils.py",
     "tests/test_ast_import_utils_module_import_boundary.py",
 )

tests/test_ast_tertiary_import_helper_import_boundary.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+import pytest
+
+from tests.ast_import_utils import (
+    imports_imports_imports_imports_collect_function_sources,
+)
+from tests.test_ast_tertiary_import_helper_usage import (
+    AST_TERTIARY_IMPORT_GUARD_MODULES,
+)
+
+pytestmark = pytest.mark.architecture
+
+
+EXPECTED_EXTRA_IMPORTERS = ("tests/test_ast_import_utils.py",)
+
+
+def test_tertiary_ast_import_helper_imports_are_centralized():
+    discovered_modules: list[str] = []
+    for module_path in sorted(Path("tests").glob("test_*.py")):
+        module_text = module_path.read_text(encoding="utf-8")
+        if not imports_imports_imports_imports_collect_function_sources(module_text):
+            continue
+        discovered_modules.append(module_path.as_posix())
+
+    expected_modules = sorted([*AST_TERTIARY_IMPORT_GUARD_MODULES, *EXPECTED_EXTRA_IMPORTERS])
+    assert discovered_modules == expected_modules

tests/test_ast_tertiary_import_helper_usage.py

@@ -0,0 +1,51 @@
+from pathlib import Path
+
+import pytest
+
+from tests.ast_import_utils import (
+    calls_symbol,
+    imports_imports_imports_imports_collect_function_sources,
+)
+
+pytestmark = pytest.mark.architecture
+
+
+AST_TERTIARY_IMPORT_GUARD_MODULES = (
+    "tests/test_ast_import_helper_secondary_import_boundary.py",
+    "tests/test_ast_secondary_import_helper_usage.py",
+)
+
+
+def test_ast_tertiary_import_guard_modules_reuse_shared_helper():
+    violating_modules: list[str] = []
+    for module_path in AST_TERTIARY_IMPORT_GUARD_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        if not imports_imports_imports_imports_collect_function_sources(module_text):
+            violating_modules.append(module_path)
+            continue
+        if not calls_symbol(module_text, "imports_imports_imports_collect_function_sources"):
+            violating_modules.append(module_path)
+            continue
+        if "def _imports_imports_imports_collect_function_sources" in module_text:
+            violating_modules.append(module_path)
+
+    assert violating_modules == []
+
+
+def test_ast_tertiary_import_guard_inventory_stays_in_sync():
+    excluded_modules = {
+        "tests/test_ast_import_utils.py",
+        "tests/test_ast_tertiary_import_helper_import_boundary.py",
+        "tests/test_ast_tertiary_import_helper_usage.py",
+    }
+    discovered_modules: list[str] = []
+    for module_path in sorted(Path("tests").glob("test_*.py")):
+        normalized_path = module_path.as_posix()
+        if normalized_path in excluded_modules:
+            continue
+        module_text = module_path.read_text(encoding="utf-8")
+        if not imports_imports_imports_imports_collect_function_sources(module_text):
+            continue
+        discovered_modules.append(normalized_path)
+
+    assert sorted(AST_TERTIARY_IMPORT_GUARD_MODULES) == discovered_modules