pytest-selective 0.1.0__py3-none-any.whl

pytest_selective/__main__.py

@@ -0,0 +1,3 @@
+from pytest_selective.impact_cli import main
+
+raise SystemExit(main())

pytest_selective/ast_imports.py

@@ -0,0 +1,75 @@
+"""Parse Python for static analysis and extract imports without walking expressions."""
+
+import ast
+import warnings
+from collections import deque
+from collections.abc import Iterator
+from pathlib import Path
+
+
+def parse_ast(source: str | bytes, filename: str = "<unknown>") -> ast.Module:
+    """Parse source independently of the caller's warning policy.
+
+    Compilation warnings belong to test execution, not static analysis: promoting
+    an invalid escape warning to an error would otherwise erase valid imports.
+    Bytes retain Python's encoding-cookie detection, and actual syntax errors
+    propagate unchanged. The caller's warning filters are restored on either path.
+    """
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return ast.parse(source, filename=filename)
+
+
+def iter_imports(tree: ast.Module) -> Iterator[ast.Import | ast.ImportFrom]:
+    """Yield all imports in the same breadth-first order as ``ast.walk``."""
+    pending: deque[ast.AST] = deque([tree])
+    while pending:
+        node = pending.popleft()
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            yield node
+        else:
+            # Parsed Python expressions cannot contain import statements.
+            # Keep the extra level for exception handlers and match cases so
+            # pruning expressions preserves ast.walk's finding order.
+            pending.extend(
+                child
+                for child in ast.iter_child_nodes(node)
+                if isinstance(child, (ast.stmt, ast.ExceptHandler, ast.match_case))
+            )
+
+
+def import_candidates(node: ast.Import | ast.ImportFrom, importer_package: str) -> set[str]:
+    """
+    Dotted module paths an import statement might load.
+
+    ``from X import Y`` can bind either attribute ``Y`` of module ``X``
+    or submodule ``X.Y`` — both are candidates; only ones that resolve
+    to real files are judged.
+    """
+    if isinstance(node, ast.Import):
+        return {alias.name for alias in node.names}
+    if node.level:
+        package_parts = importer_package.split(".") if importer_package else []
+        if node.level - 1 > len(package_parts):
+            return set()
+        prefix_parts = package_parts[: len(package_parts) - (node.level - 1)]
+        base = ".".join([*prefix_parts, node.module] if node.module else prefix_parts)
+    else:
+        base = node.module or ""
+    candidates = {base} if base else set()
+    for alias in node.names:
+        if alias.name != "*":
+            candidates.add(f"{base}.{alias.name}" if base else alias.name)
+    return candidates
+
+
+def module_file(repo_root: Path, dotted: str) -> Path | None:
+    """
+    Resolve a dotted module path to a repo file, if it exists.
+    """
+    base = repo_root.joinpath(*dotted.split("."))
+    if base.with_suffix(".py").is_file():
+        return base.with_suffix(".py")
+    if (base / "__init__.py").is_file():
+        return base / "__init__.py"
+    return None

pytest_selective/ci.py

@@ -0,0 +1,242 @@
+"""Select complete CI lanes while preserving each lane's execution/evidence contract."""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import Field, field_validator, model_validator
+
+from pytest_selective.impact_graph import DependencyDeclarationError, GraphCache, git, matches, within
+from pytest_selective.impact_models import ImpactConfig, ImpactModel
+from pytest_selective.impact_selection import affected
+from pytest_selective.input_policy import DEFAULT_GLOBAL_INPUTS
+
+JOB_INPUT = re.compile(r"(?P<path>[^#*?\[\]]+)#(?P<job>[A-Za-z_][A-Za-z0-9_-]*)")
+
+
+def job_input(value: str) -> tuple[str, str] | None:
+    """`<workflow path>#<job id>` names one GitHub Actions job; any other input is a glob."""
+    if "#" not in value:
+        return None
+    match = JOB_INPUT.fullmatch(value)
+    if match is None:
+        raise ValueError(f"{value!r}: write a job input as `<workflow path>#<job id>`, without wildcards")
+    return match["path"], match["job"]
+
+
+class Lane(ImpactModel):
+    """Test roots and additional inputs of one indivisible CI execution."""
+
+    roots: list[str] = Field(default_factory=list)
+    inputs: list[str] = Field(default_factory=list)
+
+    @field_validator("roots", "inputs")
+    @classmethod
+    def relative_paths(cls, values: list[str]) -> list[str]:
+        return ImpactConfig.relative_paths(values)
+
+    @field_validator("inputs")
+    @classmethod
+    def valid_job_inputs(cls, values: list[str]) -> list[str]:
+        for value in values:
+            job_input(value)
+        return values
+
+
+class LaneConfig(ImpactModel):
+    graph: ImpactConfig
+    lanes: dict[str, Lane]
+    global_inputs: list[str] = Field(default_factory=lambda: [*DEFAULT_GLOBAL_INPUTS, ".github/**"])
+
+    @field_validator("lanes")
+    @classmethod
+    def safe_output_names(cls, lanes: dict[str, Lane]) -> dict[str, Lane]:
+        if not lanes or any(not re.fullmatch(r"[a-z][a-z0-9_]*", name) for name in lanes):
+            raise ValueError("provide lanes named with lowercase letters, digits and underscores")
+        if any(not lane.roots and not lane.inputs for lane in lanes.values()):
+            raise ValueError("each lane needs test roots or explicit inputs")
+        return lanes
+
+    @model_validator(mode="after")
+    def job_inputs_can_narrow(self) -> "LaneConfig":
+        # A global input runs every lane before job inputs are consulted, so the
+        # job input would silently never narrow anything.
+        for lane in self.lanes.values():
+            for value in lane.inputs:
+                scoped = job_input(value)
+                if scoped and matches(scoped[0], self.global_inputs):
+                    raise ValueError(
+                        f"{value!r} cannot narrow: {scoped[0]} matches a global input, which runs every lane; "
+                        "set global_inputs without it"
+                    )
+        return self
+
+
+class WorkflowJobs:
+    """Whether one job of a workflow file changed, including the settings every job inherits."""
+
+    def __init__(self, repo: Path, base: str, head: str) -> None:
+        self.repo = repo
+        self.base = base
+        self.head = head
+        self.documents: dict[str, tuple[dict[str, Any] | None, dict[str, Any] | None]] = {}
+        self.heads: dict[str, dict[str, Any] | None] = {}
+
+    def changed(self, path: str, job: str) -> bool:
+        if path not in self.documents:
+            self.documents[path] = (self.load(self.base, path), self.load(self.head, path))
+        before, after = (self.view(document, job) for document in self.documents[path])
+        if before[1] is None and after[1] is None:
+            raise DependencyDeclarationError(f"{path}#{job}: {path} has no job {job!r} at the base or the head")
+        return before != after
+
+    def require(self, path: str, job: str) -> None:
+        """Reject a misspelled job before the change it should have caught."""
+        if path not in self.heads:
+            self.heads[path] = self.load(self.head, path)
+        if self.view(self.heads[path], job)[1] is None:
+            raise DependencyDeclarationError(f"{path}#{job}: {path} has no job {job!r}")
+
+    def load(self, revision: str, path: str) -> dict[str, Any] | None:
+        """The parsed workflow, or None when the revision does not have the file."""
+        try:
+            text = git(self.repo, "show", f"{revision}:{path}")
+        except subprocess.CalledProcessError:
+            return None
+        # Malformed YAML raises, so the planner falls back to every lane.
+        document = yaml.safe_load(text)
+        if not isinstance(document, dict) or not isinstance(document.get("jobs"), dict):
+            raise ValueError(f"{path} at {revision} is not a workflow with a jobs mapping")
+        return document
+
+    @staticmethod
+    def view(document: dict[str, Any] | None, job: str) -> tuple[dict[str, Any], Any]:
+        # Triggers, env, defaults, permissions and concurrency apply to every job.
+        if document is None:
+            return {}, None
+        return {key: value for key, value in document.items() if key != "jobs"}, document["jobs"].get(job)
+
+
+class LanePlan(ImpactModel):
+    lanes: dict[str, bool]
+    selected: list[str] = Field(default_factory=list)
+    changed: list[str] = Field(default_factory=list)
+    reason: str
+    lane_reasons: dict[str, list[str]] = Field(default_factory=dict)
+
+
+def plan(repo: Path, config: LaneConfig, base: str, head: str, *, full: bool = False) -> LanePlan:
+    """A missing proof runs every lane; bad declarations remain actionable failures."""
+
+    def all_lanes(reason: str, *, selected: list[str] | None = None, changed: list[str] | None = None) -> LanePlan:
+        return LanePlan(
+            lanes=dict.fromkeys(config.lanes, True),
+            selected=selected or [],
+            changed=changed or [],
+            reason=reason,
+            lane_reasons={name: [reason] for name in config.lanes},
+        )
+
+    if full:
+        return all_lanes("explicit full-suite checkpoint")
+    cache = None
+    try:
+        cache = GraphCache(repo / ".test-impact/cache.sqlite3")
+        report = affected(repo, base, head, config.graph, cache)
+        # Removed tests are absent from report.selected, but their lane still needs
+        # completeness checks. Consult the cached base inventory, not filename guesses.
+        before = cache.snapshot(repo, base, config.graph)
+        affected_tests = set(report.selected) | (set(report.changed) & set(before.tests))
+        unmapped = sorted(
+            test
+            for test in affected_tests
+            if not any(within(test, root) for lane in config.lanes.values() for root in lane.roots)
+        )
+        if unmapped:
+            return all_lanes(
+                "full-suite fallback: unmapped affected tests: " + ", ".join(unmapped),
+                selected=report.selected,
+                changed=report.changed,
+            )
+        global_paths = [path for path in report.changed if matches(path, config.global_inputs)]
+        changed = set(report.changed)
+        workflows = WorkflowJobs(repo, base, head)
+        lanes = {}
+        evidence = {}
+        # Select whole lanes: validators may require complete conformance evidence.
+        for name, lane in config.lanes.items():
+            reasons = [f"global input: {path}" for path in global_paths]
+            if report.mode == "full":
+                reasons.append("all graph test files affected")
+            reasons.extend(
+                f"affected test: {test}" for test in report.selected if any(within(test, root) for root in lane.roots)
+            )
+            reasons.extend(
+                f"changed root input: {path}"
+                for path in report.changed
+                if path not in report.selected and any(within(path, root) for root in lane.roots)
+            )
+            globs = [value for value in lane.inputs if job_input(value) is None]
+            reasons.extend(f"explicit input: {path}" for path in report.changed if matches(path, globs))
+            unchanged_jobs = []
+            for value in lane.inputs:
+                scoped = job_input(value)
+                if scoped is None:
+                    continue
+                if scoped[0] not in changed:
+                    workflows.require(*scoped)
+                elif workflows.changed(*scoped):
+                    reasons.append(f"explicit input: {value}")
+                else:
+                    unchanged_jobs.append(f"unchanged job: {value}")
+            lanes[name] = bool(reasons)
+            evidence[name] = reasons or unchanged_jobs or ["no affected tests or changed inputs"]
+        return LanePlan(
+            lanes=lanes,
+            selected=report.selected,
+            changed=report.changed,
+            reason="global CI/dependency input" if global_paths else "; ".join(report.reasons),
+            lane_reasons=evidence,
+        )
+    except DependencyDeclarationError:
+        raise
+    except Exception as error:
+        # A broken cache, missing Git history, or unreviewed pytest policy must
+        # never turn a failed planner into a passing skipped test job.
+        return all_lanes(f"full-suite fallback: {error}")
+    finally:
+        if cache is not None:
+            cache.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", type=Path, required=True)
+    parser.add_argument("--repo", type=Path, default=Path("."))
+    parser.add_argument("--base", required=True)
+    parser.add_argument("--head", default="HEAD")
+    parser.add_argument("--full", action="store_true")
+    parser.add_argument("--github-output", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        config = LaneConfig.model_validate_json(args.config.read_text(encoding="utf-8"))
+        result = plan(args.repo, config, args.base, args.head, full=args.full)
+    except (ValueError, OSError, DependencyDeclarationError) as error:
+        print(f"Invalid lane configuration/dependency: {error}", file=sys.stderr)
+        return 2
+    print(result.model_dump_json(indent=2))
+    if args.github_output:
+        with args.github_output.open("a", encoding="utf-8") as output:
+            for name, enabled in result.lanes.items():
+                output.write(f"{name}={str(enabled).lower()}\n")
+            output.write(f"lanes={json.dumps(result.lanes)}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pytest_selective/hygiene.py

@@ -0,0 +1,118 @@
+"""
+Enforce the test-file isolation invariant: test modules never import test modules.
+
+A test module (``test_*.py`` / ``*_test.py``) that imports another test module
+couples the two files' behavior, so re-running only the changed file no longer
+proves the unchanged one still passes. Keeping test modules import-isolated is
+what makes file-level CI test selection sound: a diff touching only
+``tests/x/test_y.py`` can re-run exactly that file.
+
+Shared code belongs in non-test modules instead — ``conftest.py`` for pytest
+fixtures at the narrowest useful scope, and plainly named helper modules
+(``helpers*.py``, ``fakes*.py``, ``factories*.py``, ...) either inside the test
+directory that owns them or in the repo's shared test-resource packages
+(``tests/helpers/``, ``tests/fakes/``, ``tests/fixtures/``, ``tests/test_data/``).
+
+The check is import-graph based, not name based: ``from tests.test_ci.helpers
+import x`` is fine (the imported *module* is ``helpers``) even though a package
+on the path is named ``test_ci``; ``from tests.test_ci.test_foo import x`` is a
+violation because the imported module is the test file ``test_foo``.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from pytest_selective.ast_imports import import_candidates, iter_imports, module_file, parse_ast
+from pytest_selective.test_inventory import TEST_FILE_PATTERNS, is_test_module_name
+
+
+class TestImportViolation(BaseModel):
+    """One test module importing another test module."""
+
+    model_config = ConfigDict(frozen=True)
+
+    importer: Path
+    line: int
+    imported_module: str
+
+    def __str__(self) -> str:
+        return f"{self.importer}:{self.line}: imports test module {self.imported_module!r}"
+
+
+def is_test_module(path: Path) -> bool:
+    return is_test_module_name(path.name)
+
+
+def discover_test_modules(test_roots: list[Path]) -> list[Path]:
+    discovered: set[Path] = set()
+    for root in test_roots:
+        if root.is_file():
+            if is_test_module(root):
+                discovered.add(root)
+            continue
+        for pattern in TEST_FILE_PATTERNS:
+            discovered.update(root.rglob(pattern))
+    return sorted(discovered)
+
+
+def find_test_import_violations(
+    repo_root: Path,
+    test_roots: list[Path],
+) -> list[TestImportViolation]:
+    """
+    Scan every test module under the roots for imports of other test
+    modules.
+
+    ``repo_root`` is the directory absolute imports resolve against (the
+    pytest rootdir); ``test_roots`` are the directories holding test modules.
+    """
+    repo_root = repo_root.resolve()
+    test_modules = discover_test_modules([repo_root / root for root in test_roots])
+    # Only modules under the scanned roots count as test modules: production
+    # code is free to end in `_test.py`-shaped names (e.g. a `stress_test`
+    # command) without tripping the invariant.
+    test_module_files = {test_file.resolve() for test_file in test_modules}
+
+    # Module resolution depends only on this scan's root and dotted name.
+    # Keep the cache local so subsequent scans see added/removed files.
+    @cache
+    def resolved_module(dotted: str) -> Path | None:
+        imported = module_file(repo_root, dotted)
+        return imported.resolve() if imported is not None else None
+
+    violations: list[TestImportViolation] = []
+    for test_file in test_modules:
+        resolved_test_file = test_file.resolve()
+        importer_package = ".".join(resolved_test_file.relative_to(repo_root).parent.parts)
+        tree = parse_ast(test_file.read_bytes(), filename=str(test_file))
+        for node in iter_imports(tree):
+            for dotted in sorted(import_candidates(node, importer_package)):
+                imported = resolved_module(dotted)
+                if imported is None or imported == resolved_test_file:
+                    continue
+                if imported in test_module_files:
+                    violations.append(
+                        TestImportViolation(
+                            importer=test_file.relative_to(repo_root),
+                            line=node.lineno,
+                            imported_module=dotted,
+                        )
+                    )
+    return violations
+
+
+def assert_test_file_isolation(repo_root: Path, test_roots: list[Path]) -> None:
+    """
+    Raise with every violation listed; the natural single-call consumer
+    API."""
+    violations = find_test_import_violations(repo_root, test_roots)
+    if violations:
+        summary = "\n".join(str(violation) for violation in violations)
+        raise AssertionError(
+            "test modules must not import other test modules "
+            f"(move shared code to conftest.py or a non-test helper module):\n{summary}"
+        )

pytest_selective/impact_audit.py

@@ -0,0 +1,104 @@
+"""
+Compare the files tests actually read with what the dependency graph lets them reach.
+
+The graph sees imports and declarations only. A test that reads a repository file as data, runs a
+script or loads a module by path is invisible to selection unless the input is declared, and
+nothing else notices the omission: the test simply stops running when that input changes. The
+``impact_audit_plugin`` records each test file's reads during the selected run; this module fails
+on every read the HEAD graph cannot reach from that test. A new test is always selected in the
+change that adds it, so its reads are audited when it is introduced, including reads in helpers.
+"""
+
+from pathlib import Path
+
+from pytest_selective.impact_declarations import match_inputs
+from pytest_selective.impact_graph import matches, reachable
+from pytest_selective.impact_models import (
+    AuditExemption,
+    AuditRecord,
+    AuditReport,
+    ImpactConfig,
+    Snapshot,
+    UndeclaredRead,
+    file_of,
+)
+
+PLACEMENT_GUIDE = "docs/guides/test-dependency-placement.md"
+
+
+def load_records(directory: Path) -> list[AuditRecord]:
+    records = [AuditRecord.model_validate_json(path.read_bytes()) for path in sorted(directory.glob("*.json"))]
+    if not records:
+        raise ValueError(f"no audit records in {directory}; was pytest run with --impact-audit-dir?")
+    return records
+
+
+def _exempt_pairs(snapshot: Snapshot, exemptions: list[AuditExemption]) -> list[tuple[set[str], set[str]]]:
+    # The declaration glob language, so a stale exemption is a hard error exactly like a stale declaration.
+    files = set(snapshot.files)
+    pairs: list[tuple[set[str], set[str]]] = []
+    for index, exemption in enumerate(exemptions):
+        location = f"{snapshot.tree}:audit_exemptions[{index}]"
+        readers = set().union(*(match_inputs(pattern, files, location) for pattern in exemption.readers))
+        inputs = set().union(*(match_inputs(pattern, files, location) for pattern in exemption.inputs))
+        pairs.append((readers, inputs))
+    return pairs
+
+
+def audit(snapshot: Snapshot, records: list[AuditRecord], config: ImpactConfig) -> AuditReport:
+    """Every recorded (test, input) pair the test's dependency closure does not contain."""
+    exempt = _exempt_pairs(snapshot, config.audit_exemptions)
+    reads: dict[str, set[str]] = {}
+    for record in records:
+        for test, paths in record.inputs.items():
+            reads.setdefault(test, set()).update(paths)
+    # Only the committed tree can be declared against: a file absent from HEAD has no edge to add.
+    reads = {test: paths & snapshot.files.keys() for test, paths in reads.items() if test in snapshot.files}
+    # An always-run test is selected by every change, so no input can skip it.
+    always = {test for test in reads if matches(test, config.always_run)}
+    undeclared: list[UndeclaredRead] = []
+    exempted = 0
+    for test, paths in sorted(reads.items()):
+        # `@contents:` nodes are the non-transitive edges of content declarations.
+        closure = {file_of(node) for node in reachable(snapshot.edges, {test})}
+        for path in sorted(paths - closure):
+            if test in always or any(test in readers and path in inputs for readers, inputs in exempt):
+                exempted += 1
+            else:
+                undeclared.append(UndeclaredRead(test=test, input=path))
+    return AuditReport(
+        head=snapshot.tree,
+        records=len(records),
+        audited_tests=len(reads),
+        recorded_reads=sum(len(paths) for paths in reads.values()),
+        exempted_reads=exempted,
+        undeclared=undeclared,
+        recorder_errors=sorted({error for record in records for error in record.errors}),
+    )
+
+
+def summary(report: AuditReport) -> str:
+    """Markdown for the GitHub step summary."""
+    lines = [
+        "### Test-impact read audit",
+        "",
+        f"{report.audited_tests} test files read {report.recorded_reads} tracked files "
+        f"({report.exempted_reads} exempted or always-run) across {report.records} pytest processes; "
+        f"{len(report.undeclared)} reads are unreachable in the dependency graph.",
+    ]
+    if report.undeclared:
+        lines += [
+            "",
+            "A change to an undeclared input selects none of its readers. Declare each input on the file "
+            "that reads it: `# gv:test-dependency: <path>` for an import edge, or a "
+            "`<file>.gv-dependency.yaml` sidecar with `kind: content` for a file read as text. "
+            f"See `{PLACEMENT_GUIDE}`. Inputs another lane covers belong in `audit_exemptions`.",
+            "",
+            "| Test file | Undeclared input |",
+            "| --- | --- |",
+            *(f"| `{read.test}` | `{read.input}` |" for read in report.undeclared),
+        ]
+    if report.recorder_errors:
+        lines += ["", "Recorder errors (the reads these events carried were not audited):", ""]
+        lines += [f"- `{error}`" for error in report.recorder_errors]
+    return "\n".join(lines) + "\n"