Add AST module-import helper usage guard

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

Author: cursoragent

CONTRIBUTING.md

@@ -99,6 +99,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_ast_import_utils.py` (shared AST import-helper contract validation),
   - `tests/test_ast_import_utils_module_import_boundary.py` (shared AST import-helper module import boundary enforcement across test modules),
   - `tests/test_ast_module_import_helper_import_boundary.py` (shared AST module-import helper import boundary enforcement across test modules),
+  - `tests/test_ast_module_import_helper_usage.py` (shared AST module-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_binary_file_open_helper_usage.py` (shared binary file open helper usage enforcement),

tests/test_architecture_marker_usage.py

@@ -28,6 +28,7 @@
     "tests/test_ast_import_utils.py",
     "tests/test_ast_import_utils_module_import_boundary.py",
     "tests/test_ast_module_import_helper_import_boundary.py",
+    "tests/test_ast_module_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_import_boundary.py",
     "tests/test_ast_symbol_import_helper_usage.py",
     "tests/test_guardrail_ast_utils.py",

tests/test_ast_call_symbol_helper_import_boundary.py

@@ -12,6 +12,7 @@
     "tests/test_ast_function_source_helper_usage.py",
     "tests/test_ast_import_helper_usage.py",
     "tests/test_ast_import_utils.py",
+    "tests/test_ast_module_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_usage.py",
 )
 

tests/test_ast_call_symbol_helper_usage.py

@@ -10,6 +10,7 @@
 AST_CALL_SYMBOL_GUARD_MODULES = (
     "tests/test_ast_function_source_helper_usage.py",
     "tests/test_ast_import_helper_usage.py",
+    "tests/test_ast_module_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_usage.py",
 )
 

tests/test_ast_import_utils_module_import_boundary.py

@@ -20,6 +20,7 @@
     "tests/test_ast_import_helper_import_boundary.py",
     "tests/test_ast_import_helper_secondary_import_boundary.py",
     "tests/test_ast_module_import_helper_import_boundary.py",
+    "tests/test_ast_module_import_helper_usage.py",
     "tests/test_ast_symbol_import_helper_import_boundary.py",
     "tests/test_ast_symbol_import_helper_usage.py",
     "tests/test_ast_import_utils.py",

tests/test_ast_module_import_helper_import_boundary.py

@@ -3,13 +3,14 @@
 import pytest
 
 from tests.ast_import_utils import imports_symbol_from_module
+from tests.test_ast_module_import_helper_usage import AST_MODULE_IMPORT_GUARD_MODULES
 
 pytestmark = pytest.mark.architecture
 
 
-EXPECTED_IMPORTS_FROM_MODULE_IMPORTERS = (
+EXPECTED_EXTRA_IMPORTERS = (
     "tests/test_ast_import_utils.py",
-    "tests/test_ast_import_utils_module_import_boundary.py",
+    "tests/test_ast_module_import_helper_usage.py",
 )
 
 
@@ -25,4 +26,5 @@ def test_imports_from_module_imports_are_centralized():
             continue
         discovered_modules.append(module_path.as_posix())
 
-    assert discovered_modules == list(EXPECTED_IMPORTS_FROM_MODULE_IMPORTERS)
+    expected_modules = sorted([*AST_MODULE_IMPORT_GUARD_MODULES, *EXPECTED_EXTRA_IMPORTERS])
+    assert discovered_modules == expected_modules

tests/test_ast_module_import_helper_usage.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+import pytest
+
+from tests.ast_import_utils import calls_symbol, imports_from_module
+
+pytestmark = pytest.mark.architecture
+
+
+AST_MODULE_IMPORT_GUARD_MODULES = (
+    "tests/test_ast_import_utils_module_import_boundary.py",
+)
+
+
+def test_ast_module_import_guard_modules_reuse_shared_helper():
+    violating_modules: list[str] = []
+    for module_path in AST_MODULE_IMPORT_GUARD_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        if not imports_from_module(module_text, module="tests.ast_import_utils"):
+            violating_modules.append(module_path)
+            continue
+        if not calls_symbol(module_text, "imports_from_module"):
+            violating_modules.append(module_path)
+            continue
+        if "def _imports_from_module" in module_text:
+            violating_modules.append(module_path)
+
+    assert violating_modules == []
+
+
+def test_ast_module_import_guard_inventory_stays_in_sync():
+    excluded_modules = {
+        "tests/test_ast_import_utils.py",
+        "tests/test_ast_module_import_helper_import_boundary.py",
+        "tests/test_ast_module_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_from_module(module_text, module="tests.ast_import_utils"):
+            continue
+        if not calls_symbol(module_text, "imports_from_module"):
+            continue
+        discovered_modules.append(normalized_path)
+
+    assert sorted(AST_MODULE_IMPORT_GUARD_MODULES) == discovered_modules