Skip to content

CLI for SidePulse

Python
16.3 KB
Raw Blame
"""Packaging and import-contract tests.

These guard the class of bug where the code imports a module that nothing
declares as a dependency, so the package installs cleanly and then explodes
at runtime on a user's machine.

The concrete instance that motivated this file: ``status_bar.py`` grew a
``from ScriptingBridge import SBApplication`` for the Ghostty integration.
``ScriptingBridge`` ships in ``pyobjc-framework-ScriptingBridge``, which was
never added to ``pyproject.toml``. Because the import shared a ``try`` block
with AppKit, the failure surfaced as a misleading "requires PyObjC/AppKit"
message and killed the whole status bar.

``test_hard_third_party_imports_are_declared`` fails on exactly that mistake.
"""

from __future__ import annotations

import ast
import importlib
import re
import subprocess
import sys
import unittest
from importlib.metadata import PackageNotFoundError, distribution, packages_distributions
from pathlib import Path

try:  # Python 3.11+
    import tomllib
except ModuleNotFoundError:  # pragma: no cover - Python 3.10
    try:
        import tomli as tomllib  # type: ignore[no-redef]
    except ModuleNotFoundError:  # pragma: no cover
        tomllib = None  # type: ignore[assignment]


REPO_ROOT = Path(__file__).resolve().parents[1]
SRC_ROOT = REPO_ROOT / "src"
PYPROJECT = REPO_ROOT / "pyproject.toml"

# Top-level packages that live in this repo.
FIRST_PARTY = {"sidepulse", "sidepulse_cli", "agent_monitor"}

# Modules that are stdlib on some supported interpreters and not others, so
# they are legitimately imported without being declared.
CONDITIONAL_STDLIB = {"tomllib"}


def normalize_dist_name(name: str) -> str:
    """PEP 503 normalization, so Foo_Bar and foo-bar compare equal."""
    return re.sub(r"[-_.]+", "-", name).lower()


def load_pyproject() -> dict:
    if tomllib is None:  # pragma: no cover
        raise unittest.SkipTest("need tomllib (3.11+) or tomli to parse pyproject.toml")
    return tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))


def requirement_name(spec: str) -> str:
    """Pull the distribution name out of a requirement string.

    ``"pyobjc-framework-Cocoa>=10; sys_platform == 'darwin'"`` -> ``pyobjc-framework-cocoa``
    """
    head = spec.split(";", 1)[0].strip()
    head = re.split(r"[<>=!~\[\s]", head, 1)[0]
    return normalize_dist_name(head)


def declared_dependencies() -> set[str]:
    """Distribution names declared in ``[project] dependencies``."""
    data = load_pyproject()
    return {requirement_name(dep) for dep in data["project"].get("dependencies", [])}


def dependency_closure(roots: set[str]) -> set[str]:
    """Every distribution reachable from ``roots`` through installed metadata.

    A direct import satisfied only transitively (``objc`` via ``pyobjc-core``,
    which ``pyobjc-framework-Cocoa`` pulls in) is accepted. An import satisfied
    by nothing in the closure is the bug this module exists to catch.
    """
    seen: set[str] = set()
    queue = list(roots)
    while queue:
        name = queue.pop()
        if name in seen:
            continue
        seen.add(name)
        try:
            reqs = distribution(name).requires or []
        except PackageNotFoundError:
            continue
        for req in reqs:
            # Skip requirements gated behind an extra we do not install.
            if "extra ==" in req:
                continue
            child = requirement_name(req)
            if child and child not in seen:
                queue.append(child)
    return seen


class ImportRecord:
    def __init__(self, module: str, path: Path, lineno: int, optional: bool):
        self.module = module
        self.top = module.split(".")[0]
        self.path = path
        self.lineno = lineno
        self.optional = optional

    @property
    def where(self) -> str:
        rel = self.path.relative_to(REPO_ROOT)
        return f"{rel}:{self.lineno}"


def handlers_swallow_failure(node: ast.Try) -> bool:
    """True when a failed import in this ``try`` leaves the module usable.

    A handler that re-raises anything -- including ``raise SystemExit(...)``,
    which is how the ScriptingBridge bug manifested -- does not make the
    import optional. It makes it mandatory with a nicer error message, so the
    dependency still has to be declared.
    """
    if not node.handlers:
        return False
    for handler in node.handlers:
        for child in ast.walk(handler):
            if isinstance(child, ast.Raise):
                return False
    return True


def scan_imports(root: Path) -> list[ImportRecord]:
    """Every import in the tree, tagged with whether the code can live without it.

    An import is optional when either:

    * it sits inside a function or method body, so it only runs when that
      feature is actually used and the caller can handle the failure; or
    * it sits inside a module-level ``try`` whose handlers swallow the error
      (assigning ``None``, setting a flag) rather than re-raising.

    Everything else runs unconditionally at import time and must be
    satisfiable from the declared dependencies.
    """
    records: list[ImportRecord] = []

    def visit(node: ast.AST, path: Path, in_function: bool, in_safe_try: bool) -> None:
        if isinstance(node, ast.Import):
            modules = [alias.name for alias in node.names]
        elif isinstance(node, ast.ImportFrom):
            # Relative imports are first-party by definition.
            modules = [node.module] if node.level == 0 and node.module else []
        else:
            modules = []
        for module in modules:
            records.append(
                ImportRecord(
                    module, path, node.lineno, optional=in_function or in_safe_try
                )
            )

        if isinstance(node, ast.Try):
            # Only the protected body benefits from the handler.
            safe = in_safe_try or handlers_swallow_failure(node)
            for child in node.body:
                visit(child, path, in_function, safe)
            for child in (*node.handlers, *node.orelse, *node.finalbody):
                visit(child, path, in_function, in_safe_try)
            return

        entering_function = isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
        for child in ast.iter_child_nodes(node):
            visit(child, path, in_function or entering_function, in_safe_try)

    for path in sorted(root.rglob("*.py")):
        visit(ast.parse(path.read_text(encoding="utf-8"), str(path)), path, False, False)
    return records


def third_party(records: list[ImportRecord]) -> list[ImportRecord]:
    return [
        record
        for record in records
        if record.top not in sys.stdlib_module_names
        and record.top not in FIRST_PARTY
        and record.top not in CONDITIONAL_STDLIB
    ]


class ImportContractTests(unittest.TestCase):
    """The dependency declaration must cover what the code actually imports."""

    def test_source_tree_is_parseable(self):
        # Cheap canary: a syntax error anywhere makes every other scan lie.
        for path in sorted(SRC_ROOT.rglob("*.py")):
            with self.subTest(path=path.relative_to(REPO_ROOT)):
                ast.parse(path.read_text(encoding="utf-8"), str(path))

    @unittest.skipUnless(
        sys.platform == "darwin",
        "every declared dependency is darwin-gated, so the contract can only "
        "be checked where they are installed",
    )
    def test_hard_third_party_imports_are_declared(self):
        """A module-level import of an undeclared distribution is a release bug.

        This is the regression test for the missing ScriptingBridge dependency.
        """
        closure = dependency_closure(declared_dependencies())
        module_to_dists = packages_distributions()

        missing: list[str] = []
        for record in third_party(scan_imports(SRC_ROOT)):
            if record.optional:
                continue
            providers = module_to_dists.get(record.top)
            if providers is None:
                missing.append(
                    f"{record.where}: imports {record.top!r}, which is not "
                    f"installed and not declared in pyproject.toml"
                )
                continue
            if not any(normalize_dist_name(p) in closure for p in providers):
                missing.append(
                    f"{record.where}: imports {record.top!r} from "
                    f"{providers}, which no declared dependency pulls in. "
                    f"Add it to [project] dependencies, or make the import "
                    f"guarded if the feature is optional."
                )

        self.assertEqual(
            [],
            missing,
            "Undeclared hard dependencies:\n  " + "\n  ".join(missing),
        )

    @unittest.skipUnless(sys.platform == "darwin", "optional deps are darwin-gated")
    def test_guarded_optional_imports_are_reachable_or_optional(self):
        """Guarded imports may be absent, but must name a real distribution.

        Catches typo'd optional imports (``ScriptingBrige``) that would
        silently disable a feature forever instead of failing loudly.
        """
        module_to_dists = packages_distributions()
        unknown: list[str] = []
        for record in third_party(scan_imports(SRC_ROOT)):
            if not record.optional:
                continue
            if record.top in module_to_dists:
                continue
            # Not installed here; accept only if some extra declares it.
            data = load_pyproject()
            extras = data["project"].get("optional-dependencies", {})
            declared_anywhere = {
                requirement_name(dep)
                for deps in extras.values()
                for dep in deps
            } | declared_dependencies()
            if normalize_dist_name(record.top) not in declared_anywhere:
                unknown.append(f"{record.where}: optional import {record.top!r}")

        # mlx_lm is the reply-classifier extra; it maps to distribution "mlx-lm".
        unknown = [u for u in unknown if "mlx_lm" not in u]
        self.assertEqual([], unknown, "Unrecognized optional imports:\n  " + "\n  ".join(unknown))

    def test_declared_dependencies_are_installed(self):
        """The test environment matches what we ship, or the suite proves nothing."""
        if sys.platform != "darwin":
            self.skipTest("declared dependencies are darwin-gated")
        for name in sorted(declared_dependencies()):
            with self.subTest(dependency=name):
                try:
                    distribution(name)
                except PackageNotFoundError:
                    self.fail(
                        f"{name} is declared in pyproject.toml but not installed. "
                        f"Run: pip install -e ."
                    )


class ModuleImportSmokeTests(unittest.TestCase):
    """Every shipped module must import. Nothing here is clever; that is the point."""

    def module_names(self) -> list[str]:
        names = []
        for path in sorted(SRC_ROOT.rglob("*.py")):
            rel = path.relative_to(SRC_ROOT)
            if rel.name == "__main__.py":
                continue  # executes on import by design
            parts = list(rel.parts)
            parts[-1] = rel.stem
            if parts[-1] == "__init__":
                parts.pop()
            if parts:
                names.append(".".join(parts))
        return names

    def test_every_module_imports(self):
        darwin_only = {
            "sidepulse.status_bar",
            "sidepulse.virtual_device",
            "sidepulse.led_wasm",
        }
        for name in self.module_names():
            if name in darwin_only and sys.platform != "darwin":
                continue
            with self.subTest(module=name):
                try:
                    importlib.import_module(name)
                except SystemExit as exc:
                    # status_bar raises SystemExit with an install hint when
                    # PyObjC is missing. On a machine with deps installed that
                    # is always a bug -- most likely an undeclared dependency.
                    self.fail(f"{name} raised SystemExit on import: {exc}")

    def test_main_module_does_not_import_eagerly(self):
        # __main__.py runs the CLI; it must be importable via runpy without
        # side effects beyond argument parsing.
        result = subprocess.run(
            [sys.executable, "-m", "sidepulse", "--help"],
            capture_output=True,
            text=True,
            timeout=60,
            cwd=REPO_ROOT,
        )
        self.assertEqual(0, result.returncode, result.stderr)
        self.assertIn("usage", result.stdout.lower())


class EntryPointTests(unittest.TestCase):
    """Every console script in pyproject must resolve to a real callable."""

    def test_console_scripts_resolve(self):
        scripts = load_pyproject()["project"].get("scripts", {})
        self.assertTrue(scripts, "expected console scripts in pyproject.toml")
        for name, target in sorted(scripts.items()):
            with self.subTest(script=name):
                module_name, _, attr = target.partition(":")
                if module_name == "sidepulse.status_bar" and sys.platform != "darwin":
                    continue
                module = importlib.import_module(module_name)
                self.assertTrue(
                    callable(getattr(module, attr, None)),
                    f"{target} is not callable",
                )

    def test_console_scripts_respond_to_help(self):
        """An entry point that cannot even print --help is broken for users."""
        scripts = load_pyproject()["project"].get("scripts", {})
        for name, target in sorted(scripts.items()):
            module_name, _, _ = target.partition(":")
            if module_name == "sidepulse.status_bar":
                continue  # launching the GUI is not a --help operation
            with self.subTest(script=name):
                result = subprocess.run(
                    [sys.executable, "-c", f"import sys; sys.argv=['{name}','--help']; "
                     f"import {module_name} as m; "
                     f"sys.exit(m.{target.split(':')[1]}())"],
                    capture_output=True,
                    text=True,
                    timeout=60,
                    cwd=REPO_ROOT,
                )
                self.assertIn(
                    result.returncode,
                    (0, 2),
                    f"{name} --help failed: {result.stderr}",
                )


class VersionTests(unittest.TestCase):
    """Tag-derived package metadata and the runtime version must not drift.

    A published wheel whose metadata disagrees with ``sidepulse.__version__``
    makes bug reports impossible to place.
    """

    def test_version_is_dynamic(self):
        project = load_pyproject()["project"]
        self.assertIn("version", project["dynamic"])
        self.assertNotIn("version", project)

    def test_metadata_and_dunder_version_agree(self):
        try:
            import sidepulse
        except ModuleNotFoundError:
            self.skipTest("sidepulse is not installed in this environment")
        from importlib.metadata import version

        try:
            installed = version("sidepulse")
        except PackageNotFoundError:
            self.skipTest("sidepulse is not installed in this environment")
        self.assertEqual(
            installed,
            sidepulse.__version__,
            "installed metadata and sidepulse.__version__ disagree",
        )


class PackageDataTests(unittest.TestCase):
    def test_declared_package_data_exists(self):
        data = load_pyproject()
        package_data = (
            data.get("tool", {})
            .get("setuptools", {})
            .get("package-data", {})
        )
        for package, patterns in package_data.items():
            package_dir = SRC_ROOT / package.replace(".", "/")
            with self.subTest(package=package):
                self.assertTrue(
                    package_dir.is_dir(),
                    f"package-data references missing package {package}",
                )
            for pattern in patterns:
                with self.subTest(package=package, pattern=pattern):
                    self.assertTrue(
                        list(package_dir.glob(pattern)),
                        f"package-data pattern {pattern!r} matches nothing in {package}",
                    )


if __name__ == "__main__":
    unittest.main()