Add list parsing helper usage centralization guard

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

Author: cursoragent

CONTRIBUTING.md

@@ -167,6 +167,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_job_start_payload_helper_usage.py` (shared scrape/crawl start-payload helper usage enforcement),
   - `tests/test_job_wait_helper_boundary.py` (centralization boundary enforcement for wait-for-job helper primitives),
   - `tests/test_job_wait_helper_usage.py` (shared wait-for-job defaults helper usage enforcement),
+  - `tests/test_list_parsing_helper_usage.py` (list parsing shared helper usage centralization),
   - `tests/test_list_parsing_key_display_helper_usage.py` (list parsing safe key-display helper usage enforcement),
   - `tests/test_makefile_quality_targets.py` (Makefile quality-gate target enforcement),
   - `tests/test_manager_helper_import_boundary.py` (manager helper-import boundary enforcement for low-level parse modules),

tests/test_architecture_marker_usage.py

@@ -128,6 +128,7 @@
     "tests/test_job_start_payload_helper_usage.py",
     "tests/test_job_query_params_helper_usage.py",
     "tests/test_list_parsing_key_display_helper_usage.py",
+    "tests/test_list_parsing_helper_usage.py",
     "tests/test_job_wait_helper_boundary.py",
     "tests/test_job_wait_helper_usage.py",
     "tests/test_example_sync_async_parity.py",

tests/test_list_parsing_helper_usage.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+import pytest
+
+from tests.guardrail_ast_utils import collect_name_call_lines, read_module_ast
+
+pytestmark = pytest.mark.architecture
+
+HYPERBROWSER_ROOT = Path(__file__).resolve().parents[1] / "hyperbrowser"
+ALLOWED_PARSE_MAPPING_LIST_CALL_FILES = {
+    Path("client/managers/extension_utils.py"),
+    Path("client/managers/list_parsing_utils.py"),
+    Path("client/managers/session_utils.py"),
+}
+ALLOWED_READ_PLAIN_LIST_CALL_FILES = {
+    Path("client/managers/extension_utils.py"),
+    Path("client/managers/list_parsing_utils.py"),
+    Path("client/managers/session_utils.py"),
+}
+
+
+def _python_files() -> list[Path]:
+    return sorted(HYPERBROWSER_ROOT.rglob("*.py"))
+
+
+def test_parse_mapping_list_items_usage_is_centralized():
+    violations: list[str] = []
+
+    for path in _python_files():
+        relative_path = path.relative_to(HYPERBROWSER_ROOT)
+        module = read_module_ast(path)
+        helper_calls = collect_name_call_lines(module, "parse_mapping_list_items")
+        if not helper_calls:
+            continue
+        if relative_path in ALLOWED_PARSE_MAPPING_LIST_CALL_FILES:
+            continue
+        for line in helper_calls:
+            violations.append(f"{relative_path}:{line}")
+
+    assert violations == []
+
+
+def test_read_plain_list_items_usage_is_centralized():
+    violations: list[str] = []
+
+    for path in _python_files():
+        relative_path = path.relative_to(HYPERBROWSER_ROOT)
+        module = read_module_ast(path)
+        helper_calls = collect_name_call_lines(module, "read_plain_list_items")
+        if not helper_calls:
+            continue
+        if relative_path in ALLOWED_READ_PLAIN_LIST_CALL_FILES:
+            continue
+        for line in helper_calls:
+            violations.append(f"{relative_path}:{line}")
+
+    assert violations == []