LEDMatrix/test/test_common_is_hardware_free.py

"""src/common must stay importable without display hardware.

Plugins import src.common.sports_* in place of their bundled copies. If any of
those modules reaches src.display_manager (and through it rgbmatrix) or the
src.base_classes package (whose core.py imports DisplayManager), a scoreboard
adopting it acquires a hardware dependency it never had, and the headless
tooling -- the web preview, check_plugin.py, these tests on a laptop -- stops
being able to load it.

Two checks, because each misses what the other catches:

1. A real import in a fresh interpreter with rgbmatrix made unimportable.
   Catches indirect imports (common -> X -> display_manager) that no text scan
   of src/common would see.
2. An AST scan of src/common/*.py for module-level imports of the hardware and
   plugin-system packages. Catches a direct import even where the target
   happens to import cleanly on this machine.
"""

import ast
import subprocess
import sys
import textwrap
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
COMMON = REPO_ROOT / "src" / "common"

FORBIDDEN = ("src.base_classes", "src.display_manager", "src.plugin_system")

#: Existing module-level violations, by file name, each with the reason it is
#: tolerated. Empty when this test was added (core 3.4.0 + sports_helpers):
#: no src/common module imported any of FORBIDDEN at module level. Add to this
#: only with a comment saying why, never to get a new import past the test.
ALLOWLIST = {}


def test_sports_modules_import_without_hardware():
    modules = sorted(p.stem for p in COMMON.glob("sports_*.py"))
    assert "sports_helpers" in modules
    script = textwrap.dedent(f"""
        import importlib, json, sys
        sys.modules["rgbmatrix"] = None   # any import of it now raises
        importlib.import_module("src.common")
        for name in {modules!r}:
            importlib.import_module("src.common." + name)
        loaded = sorted(m for m in sys.modules
                        if m.startswith(("src.display_manager", "src.base_classes")))
        print(json.dumps(loaded))
    """)
    result = subprocess.run(
        [sys.executable, "-c", script], cwd=str(REPO_ROOT),
        capture_output=True, text=True, timeout=120)
    assert result.returncode == 0, (
        f"importing src.common without rgbmatrix failed:\n{result.stderr}")
    loaded = result.stdout.strip().splitlines()[-1]
    assert loaded == "[]", f"src.common pulled in hardware modules: {loaded}"


def _module_level_imports(tree):
    """Imports executed at import time: top level, including inside if/try
    blocks, but not inside functions or classes (those are deferred)."""
    stack = list(tree.body)
    while stack:
        node = stack.pop()
        if isinstance(node, (ast.Import, ast.ImportFrom)):
            yield node
        elif isinstance(node, (ast.If, ast.Try, ast.With)):
            stack.extend(node.body)
            stack.extend(getattr(node, "orelse", []))
            stack.extend(getattr(node, "finalbody", []))
            for handler in getattr(node, "handlers", []):
                stack.extend(handler.body)


def _targets(node):
    if isinstance(node, ast.Import):
        return [alias.name for alias in node.names]
    if node.module is None:
        return []
    if node.module == "src":
        return [f"src.{alias.name}" for alias in node.names]
    return [node.module]


def _violations():
    found = {}
    for path in sorted(COMMON.glob("*.py")):
        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        for node in _module_level_imports(tree):
            for target in _targets(node):
                if target == FORBIDDEN or any(
                        target == f or target.startswith(f + ".") for f in FORBIDDEN):
                    found.setdefault(path.name, []).append(f"line {node.lineno}: {target}")
    return found


def test_no_module_level_hardware_or_plugin_system_imports():
    found = {name: hits for name, hits in _violations().items() if name not in ALLOWLIST}
    assert found == {}, (
        "src/common must not import these at module level (defer the import "
        f"into the function that needs it): {found}")


def test_allowlist_has_no_stale_entries():
    stale = sorted(set(ALLOWLIST) - set(_violations()))
    assert stale == [], f"allowlisted but no longer violating, remove: {stale}"


def test_the_scan_sees_a_direct_import(tmp_path):
    # Guard the guard: the walker must find imports nested in try/if.
    tree = ast.parse(textwrap.dedent("""
        try:
            from src.display_manager import DisplayManager
        except ImportError:
            pass
        if True:
            import src.base_classes.sports
        from src import plugin_system
        def later():
            from src.display_manager import DisplayManager
    """))
    targets = sorted(t for n in _module_level_imports(tree) for t in _targets(n))
    assert targets == ["src.base_classes.sports", "src.display_manager", "src.plugin_system"]