Add architecture guard for polling loop centralization

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

Author: cursoragent

CONTRIBUTING.md

@@ -88,7 +88,8 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_architecture_marker_usage.py` (architecture marker coverage across guard modules),
   - `tests/test_readme_examples_listing.py` (README example-listing consistency enforcement),
   - `tests/test_plain_type_guard_usage.py` (`str`/`int` guardrail enforcement via plain-type checks),
-  - `tests/test_type_utils_usage.py` (type `__mro__` boundary centralization in `hyperbrowser/type_utils.py`).
+  - `tests/test_type_utils_usage.py` (type `__mro__` boundary centralization in `hyperbrowser/type_utils.py`),
+  - `tests/test_polling_loop_usage.py` (`while True` polling-loop centralization in `hyperbrowser/client/polling.py`).
 
 ## Code quality conventions
 

tests/guardrail_ast_utils.py

@@ -53,3 +53,13 @@ def collect_list_keys_call_lines(module: ast.AST) -> list[int]:
             continue
         lines.append(node.lineno)
     return lines
+
+
+def collect_while_true_lines(module: ast.AST) -> list[int]:
+    lines: list[int] = []
+    for node in ast.walk(module):
+        if not isinstance(node, ast.While):
+            continue
+        if isinstance(node.test, ast.Constant) and node.test.value is True:
+            lines.append(node.lineno)
+    return lines

tests/test_architecture_marker_usage.py

@@ -18,6 +18,7 @@
     "tests/test_architecture_marker_usage.py",
     "tests/test_plain_type_guard_usage.py",
     "tests/test_type_utils_usage.py",
+    "tests/test_polling_loop_usage.py",
 )
 
 

tests/test_guardrail_ast_utils.py

@@ -6,6 +6,7 @@
     collect_attribute_call_lines,
     collect_list_keys_call_lines,
     collect_name_call_lines,
+    collect_while_true_lines,
 )
 
 pytestmark = pytest.mark.architecture
@@ -16,6 +17,8 @@
 values = list(mapping.keys())
 result = helper()
 other = obj.method()
+while True:
+    break
 """
 )
 
@@ -30,3 +33,7 @@ def test_collect_attribute_call_lines_returns_attribute_calls():
 
 def test_collect_list_keys_call_lines_returns_list_key_calls():
     assert collect_list_keys_call_lines(SAMPLE_MODULE) == [2]
+
+
+def test_collect_while_true_lines_returns_while_true_statements():
+    assert collect_while_true_lines(SAMPLE_MODULE) == [5]

tests/test_polling_loop_usage.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import pytest
+
+from tests.guardrail_ast_utils import collect_while_true_lines, read_module_ast
+
+pytestmark = pytest.mark.architecture
+
+
+ALLOWED_WHILE_TRUE_MODULES = {
+    "hyperbrowser/client/polling.py",
+}
+
+
+def test_while_true_loops_are_centralized_to_polling_module():
+    violations: list[str] = []
+    polling_while_true_lines: list[int] = []
+
+    for module_path in sorted(Path("hyperbrowser").rglob("*.py")):
+        module_ast = read_module_ast(module_path)
+        while_true_lines = collect_while_true_lines(module_ast)
+        if not while_true_lines:
+            continue
+        path_text = module_path.as_posix()
+        if path_text in ALLOWED_WHILE_TRUE_MODULES:
+            polling_while_true_lines.extend(while_true_lines)
+            continue
+        for line in while_true_lines:
+            violations.append(f"{path_text}:{line}")
+
+    assert violations == []
+    assert polling_while_true_lines != []