learningcircuit--local-deep-research/.pre-commit-hooks/check-fixture-duplication.py

#!/usr/bin/env python3
"""
Pre-commit hook to warn when test files redefine root-conftest fixtures.

The root tests/conftest.py provides `app`, `client`, and `authenticated_client`
fixtures with security-relevant setup (CSRF, auth DB init, temp data dir).
Full-app redefinitions (those calling `create_app()`) often skip that setup,
which is the real harm. Fixtures that build a minimal `Flask(__name__)` app
for blueprint isolation are intentionally different and are NOT flagged.

Class-level fixtures are allowed because they cannot easily inherit from
conftest. Module-level redefinitions produce a WARNING for allowlisted
files (exit 0) and an ERROR for new occurrences (exit 1).
"""

import ast
import os
import sys

# Fixture names defined in tests/conftest.py that should not be redefined
# at module level in individual test files when they use create_app().
PROTECTED_FIXTURES = {"app", "client", "authenticated_client"}

# Existing violations — these files already redefine the fixtures using
# create_app(). They emit a soft warning (exit 0) instead of blocking.
# Remove entries as files are migrated to use the shared conftest fixtures.
ALLOWLIST: dict[str, set[str]] = {
    "tests/auth_tests/test_auth_integration.py": {"app", "client"},
    "tests/auth_tests/test_auth_routes.py": {"app", "client"},
    "tests/security/test_cookie_security.py": {"app", "client"},
    "tests/web/test_error_handler_behavior.py": {"app", "client"},
    "tests/web/test_teardown_cleanup.py": {"app"},
    "tests/web/test_websocket_middleware.py": {"app", "client"},
}


def _normalize(filepath: str) -> str:
    """Normalize path to use forward slashes and strip a leading './'."""
    path = filepath.replace(os.sep, "/")
    if path.startswith("./"):
        path = path[2:]
    return path


def _is_fixture_decorator(decorator: ast.expr) -> bool:
    """Check if an AST decorator node is @pytest.fixture (with or without args)."""
    # @pytest.fixture
    if isinstance(decorator, ast.Attribute):
        return (
            isinstance(decorator.value, ast.Name)
            and decorator.value.id == "pytest"
            and decorator.attr == "fixture"
        )
    # @pytest.fixture() or @pytest.fixture(scope=...)
    if isinstance(decorator, ast.Call):
        return _is_fixture_decorator(decorator.func)
    return False


def _calls_create_app(func_node: ast.AST) -> bool:
    """Return True if the fixture body contains a call to `create_app`.

    Matches `create_app(...)` (bare) and `module.create_app(...)` (attribute).
    A fixture that only uses `Flask(__name__)` for blueprint isolation does
    not trigger this and is treated as intentional, not a violation.
    """
    for node in ast.walk(func_node):
        if not isinstance(node, ast.Call):
            continue
        func = node.func
        if isinstance(func, ast.Name) and func.id == "create_app":
            return True
        if isinstance(func, ast.Attribute) and func.attr == "create_app":
            return True
    return False


def find_module_level_fixture_redefinitions(
    filepath: str,
) -> list[tuple[int, str]]:
    """Find module-level pytest fixtures that shadow root conftest definitions.

    Only full-app redefinitions (fixtures that call create_app) are reported.
    Returns list of (line_number, fixture_name) tuples.
    """
    try:
        with open(filepath, "r", encoding="utf-8") as f:
            source = f.read()
    except (OSError, UnicodeDecodeError) as exc:
        print(f"WARNING: could not read {filepath}: {exc}", file=sys.stderr)
        return []

    try:
        tree = ast.parse(source, filename=filepath)
    except SyntaxError as exc:
        print(f"WARNING: could not parse {filepath}: {exc}", file=sys.stderr)
        return []

    # A `client`/`authenticated_client` fixture is flagged only when the file
    # also has a local `app` fixture that uses create_app — because the client
    # then inherits the problematic full-app without conftest security setup.
    # If no such `app` exists (file uses a minimal Flask inside the client
    # fixture itself), the client is flagged only if it calls create_app directly.
    local_app_uses_create_app = False
    for node in ast.iter_child_nodes(tree):
        if (
            isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
            and node.name == "app"
            and any(_is_fixture_decorator(d) for d in node.decorator_list)
            and _calls_create_app(node)
        ):
            local_app_uses_create_app = True
            break

    violations = []
    for node in ast.iter_child_nodes(tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
        if node.name not in PROTECTED_FIXTURES:
            continue
        if not any(_is_fixture_decorator(d) for d in node.decorator_list):
            continue

        if node.name == "app":
            if _calls_create_app(node):
                violations.append((node.lineno, node.name))
        else:
            # client / authenticated_client
            if _calls_create_app(node) or local_app_uses_create_app:
                violations.append((node.lineno, node.name))

    return violations


def main() -> int:
    if len(sys.argv) < 2:
        return 0

    new_violations: list[str] = []
    allowlisted_warnings: list[str] = []

    for filepath in sys.argv[1:]:
        norm = _normalize(filepath)

        # Only check files under tests/
        if not norm.startswith("tests/"):
            continue

        # Skip the root conftest itself — it's the canonical source
        if norm == "tests/conftest.py":
            continue

        violations = find_module_level_fixture_redefinitions(filepath)
        if not violations:
            continue

        allowed = ALLOWLIST.get(norm, set())

        for lineno, fixture_name in violations:
            msg = f"{norm}:{lineno}: module-level redefinition of `{fixture_name}` fixture (uses create_app)"
            if fixture_name in allowed:
                allowlisted_warnings.append(msg)
            else:
                new_violations.append(msg)

    if allowlisted_warnings:
        print(
            "WARNING: The following files redefine root-conftest fixtures "
            "(allowlisted, but please migrate):"
        )
        for w in allowlisted_warnings:
            print(f"  {w}")
        print()

    if new_violations:
        print(
            "ERROR: New module-level redefinitions of root-conftest fixtures detected!\n"
        )
        print(
            "The root tests/conftest.py provides `app`, `client`, and "
            "`authenticated_client` fixtures with security-relevant setup "
            "(CSRF disable, auth DB init, temp data dir)."
        )
        print(
            "Redefining these at module level with `create_app()` skips that "
            "setup and may create subtle test-environment differences.\n"
        )
        print("New violations:")
        for v in new_violations:
            print(f"  {v}")
        print(
            "\nTo fix: remove the local fixture and use the shared one from "
            "tests/conftest.py."
        )
        print(
            "If this is intentional (e.g., testing a different app factory "
            "configuration), add the file to the ALLOWLIST in "
            ".pre-commit-hooks/check-fixture-duplication.py\n"
        )
        print(
            "Note: minimal `Flask(__name__)` fixtures for blueprint isolation "
            "are NOT flagged — only fixtures calling create_app() are.\n"
        )
        return 1

    return 0


if __name__ == "__main__":
    sys.exit(main())