patchahead 0.3.0__py3-none-any.whl

patchahead/testing/discovery.py

@@ -0,0 +1,113 @@
+"""Finding the tests that exercise a given module.
+
+Used for two things: telling a reviewer which tests cover the code being
+changed, and giving the targeted-tests validation gate a narrow, fast subset to
+run before the full suite.
+
+The strategy is name-based and deliberately simple: a module ``app/client.py``
+is matched to ``tests/test_client.py``, ``tests/app/test_client.py``,
+``tests/test_app_client.py``, and so on. It does not trace imports, so it is
+*best effort*. That is why the regression gate always runs the full suite as
+well -- the targeted gate exists to fail fast and to tell a reviewer where to
+look, not to replace running everything.
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+from pathlib import PurePosixPath
+
+from patchahead.analysis.index import RepoIndex, is_test_path
+
+log = logging.getLogger(__name__)
+
+
+def module_stem(path: str) -> str:
+    """The importable stem of a module path: ``app/order_sync.py`` -> ``order_sync``."""
+    return PurePosixPath(path).stem
+
+
+def _candidate_names(source_path: str) -> set[str]:
+    """Test-module basenames that would conventionally cover ``source_path``."""
+    pure = PurePosixPath(source_path)
+    stem = pure.stem
+    if stem == "__init__":
+        stem = pure.parent.name or stem
+
+    names = {f"test_{stem}.py", f"{stem}_test.py"}
+    # tests/test_app_client.py for app/client.py
+    parts = [part for part in pure.parts[:-1] if part not in (".", "src")]
+    if parts:
+        names.add(f"test_{'_'.join(parts[-1:] + [stem])}.py")
+        names.add(f"test_{'_'.join(parts + [stem])}.py")
+    return names
+
+
+def tests_for_path(index: RepoIndex, source_path: str) -> list[str]:
+    """Test modules that look like they cover ``source_path``.
+
+    Ordered by how specific the match is, so the most likely test comes first.
+    """
+    if is_test_path(source_path):
+        return []
+
+    candidates = _candidate_names(source_path)
+    stem = module_stem(source_path)
+    exact: list[str] = []
+    fuzzy: list[str] = []
+
+    for test_path in index.test_paths():
+        name = PurePosixPath(test_path).name
+        if name in candidates:
+            exact.append(test_path)
+        elif stem and stem in name:
+            fuzzy.append(test_path)
+
+    return exact + fuzzy
+
+
+def tests_for_paths(index: RepoIndex, source_paths: list[str]) -> list[str]:
+    """The union of tests covering several modules, order-preserving.
+
+    Callers pass one path per finding, so the same module can arrive thousands
+    of times; each distinct module is matched once.
+    """
+    found: dict[str, None] = {}
+    for source_path in dict.fromkeys(source_paths):
+        found.update(dict.fromkeys(tests_for_path(index, source_path)))
+    return list(found)
+
+
+def tests_by_file(index: RepoIndex, source_paths: list[str]) -> dict[str, list[str]]:
+    """A ``source path -> test paths`` mapping, for the impact graph."""
+    mapping: dict[str, list[str]] = {}
+    for source_path in dict.fromkeys(source_paths):
+        tests = tests_for_path(index, source_path)
+        if tests:
+            mapping[source_path] = tests
+    return mapping
+
+
+def has_any_tests(index: RepoIndex) -> bool:
+    return bool(index.test_paths())
+
+
+def scoped_command(test_command: str, test_paths: list[str]) -> str:
+    """Build a command that runs only ``test_paths``.
+
+    Only attempted for pytest-shaped commands, where appending paths is a
+    well-defined way to narrow a run. For any other runner the full command is
+    returned unchanged and the caller reports the targeted gate as covering the
+    whole suite -- guessing at another runner's path syntax would produce a gate
+    that silently tests nothing.
+    """
+    if not test_paths:
+        return test_command
+    if "pytest" not in test_command:
+        return test_command
+    # Refuse to append to a command that already has shell plumbing; appending
+    # after a pipe or redirect would change what the arguments apply to.
+    if any(token in test_command for token in ("|", ">", "<", "&&", ";")):
+        return test_command
+    return " ".join([test_command] + [shlex.quote(path) for path in test_paths])

patchahead/testing/runner.py

@@ -0,0 +1,138 @@
+"""Running a test command inside a workspace and structuring the result.
+
+Parsing test output is inherently runner-specific. This module understands
+pytest's summary lines well and degrades to "the command's exit code" for
+anything else, which is the part that actually decides a gate.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+import time
+
+from patchahead.domain.validation import TestRun
+from patchahead.workspace import Workspace
+
+log = logging.getLogger(__name__)
+
+_FAILED_LINE = re.compile(r"^(?:FAILED|ERROR)\s+(\S+)", re.MULTILINE)
+_SHORT_TALLY = re.compile(r"(\d+ (?:passed|failed|error|skipped)[^\n=]*)")
+_ASSERTION = re.compile(r"^E\s+(\w*(?:Error|Exception|AssertionError).*)$", re.MULTILINE)
+_NO_TESTS = re.compile(r"no tests ran|collected 0 items", re.IGNORECASE)
+_MISSING_RUNNER = re.compile(
+    r"No module named (\S+)|(?:command )?not found|is not recognized as an internal"
+)
+#: POSIX exit codes for "the shell could not run this at all": 127 is
+#: command-not-found, 126 is found-but-not-executable. Neither is a test
+#: result, and neither depends on how a particular shell words its error --
+#: bash says "command not found", dash says "not found", and a Windows shell
+#: says something else again. Matching on the status rather than the prose is
+#: what makes this reliable: relying on the wording meant `sh` reporting
+#: "not found" was read as a test failure and reported as a regression.
+CANNOT_START_CODES = (126, 127)
+#: Appended wherever a gate has to explain that nothing ran. A message that
+#: says only "could not run" leaves the reader with no next step.
+RUNNER_ADVICE = (
+    "Check `test_command` in the repository's PatchAhead configuration, and "
+    "that the test runner is installed in the environment PatchAhead is "
+    "running in."
+)
+
+
+def could_not_start(output: str, returncode: int) -> bool:
+    """Whether the command never got as far as running a test.
+
+    Two independent signals, because either alone misses cases: the exit status
+    (127/126, which no test runner produces) and the shell's message (which
+    covers a runner that exits non-zero while reporting a missing module).
+    """
+    if returncode in CANNOT_START_CODES:
+        return True
+    return returncode != 0 and bool(_MISSING_RUNNER.search(output))
+
+
+def _summarize(output: str, returncode: int) -> str:
+    """One line describing what happened, for reports and logs."""
+    if could_not_start(output, returncode):
+        missing = _MISSING_RUNNER.search(output)
+        reason = missing.group(0).strip() if missing else f"exit status {returncode}"
+        return f"the test command could not start ({reason}). {RUNNER_ADVICE}"
+    if _NO_TESTS.search(output):
+        return "no tests ran"
+    tally = _SHORT_TALLY.search(output)
+    if returncode == 0:
+        return tally.group(1).strip() if tally else "tests passed"
+    assertion = _ASSERTION.search(output)
+    if assertion:
+        detail = assertion.group(1).strip()
+        return f"{tally.group(1).strip()} ({detail})" if tally else detail
+    if tally:
+        return tally.group(1).strip()
+    return f"test command exited {returncode}"
+
+
+def run_tests(
+    workspace: Workspace,
+    command: str,
+    timeout: int = 300,
+) -> TestRun:
+    """Run ``command`` in ``workspace`` and return a structured result.
+
+    A command that cannot be executed at all -- not found, or killed by the
+    timeout -- is returned with ``errored=True`` rather than raising, so a gate
+    can report "could not verify" distinctly from "verified and failed". These
+    are different facts and the prototype's boolean could not tell them apart.
+    """
+    start = time.perf_counter()
+    try:
+        completed = workspace.run(command, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        duration = int((time.perf_counter() - start) * 1000)
+        log.warning("test command timed out after %ds: %s", timeout, command)
+        return TestRun(
+            command=command,
+            returncode=-1,
+            summary=f"test command timed out after {timeout}s",
+            duration_ms=duration,
+            errored=True,
+        )
+    except OSError as exc:
+        duration = int((time.perf_counter() - start) * 1000)
+        log.warning("test command could not be run: %s", exc)
+        return TestRun(
+            command=command,
+            returncode=-1,
+            stderr=str(exc),
+            summary=f"could not run the test command: {exc}",
+            duration_ms=duration,
+            errored=True,
+        )
+
+    duration = int((time.perf_counter() - start) * 1000)
+    output = completed.stdout + completed.stderr
+    failing = sorted(set(_FAILED_LINE.findall(output)))
+
+    # pytest exit code 5 is "no tests collected", which is not a test failure.
+    # Reporting it as one would make an empty repository look broken. A runner
+    # that could not start at all is also "could not verify", not "verified and
+    # failed" -- the gates treat those differently on purpose, and every gate
+    # that executes tests has to read it the same way or the same fact gets two
+    # different verdicts depending on which gate saw it.
+    errored = (completed.returncode == 5 and bool(_NO_TESTS.search(output))) or could_not_start(
+        output, completed.returncode
+    )
+
+    run = TestRun(
+        command=command,
+        returncode=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+        failing_tests=failing,
+        summary=_summarize(output, completed.returncode),
+        duration_ms=duration,
+        errored=errored,
+    )
+    log.debug("test run finished in %dms: rc=%d, %s", duration, completed.returncode, run.summary)
+    return run

patchahead/validation/__init__.py

@@ -0,0 +1,5 @@
+"""The validation subsystem: the only thing allowed to call a migration good."""
+
+from patchahead.validation.engine import ValidationEngine, ValidationOptions
+
+__all__ = ["ValidationEngine", "ValidationOptions"]

patchahead/validation/completeness.py

@@ -0,0 +1,265 @@
+"""Scanning the patched copy for what is left of the old API.
+
+Runs after the gates, against the workspace as patched. It is a report, not a
+gate: a migration can be verified by its tests and still leave the old name
+behind somewhere no test reaches, and saying where is the point. ``--require-
+complete`` lets a CI run treat unfinished residuals as a failure.
+
+Three sources, cheapest to read first:
+
+1. **The handler's own analysis, re-run on the patched code.** Whatever it still
+   finds was not rewritten -- below the confidence threshold, an unfamiliar
+   shape, or another object that shares the name.
+2. **Python tokens.** Strings and comments that mention the name, a string
+   handed to ``getattr`` (an access no static rewrite can see), tests that
+   still use the old name, and -- for a method rename -- any other use of the
+   name, such as the ``from sdk import fetch_orders`` that the call-site rewrite
+   leaves behind.
+3. **Configuration and documentation files** that mention it.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import re
+import tokenize
+from pathlib import Path
+
+from patchahead.analysis import index as repo_index
+from patchahead.analysis.edits import read_source
+from patchahead.config import Config
+from patchahead.domain.change import BreakingChange, ChangeKind
+from patchahead.domain.completeness import CompletenessReport, Residual, ResidualKind
+from patchahead.domain.impact import ImpactReport
+
+log = logging.getLogger(__name__)
+
+#: Text files worth reading for mentions, by suffix.
+TEXT_FILES: dict[str, ResidualKind] = {
+    ".yaml": ResidualKind.CONFIG,
+    ".yml": ResidualKind.CONFIG,
+    ".json": ResidualKind.CONFIG,
+    ".toml": ResidualKind.CONFIG,
+    ".ini": ResidualKind.CONFIG,
+    ".cfg": ResidualKind.CONFIG,
+    ".env": ResidualKind.CONFIG,
+    ".md": ResidualKind.DOCS,
+    ".rst": ResidualKind.DOCS,
+    ".txt": ResidualKind.DOCS,
+}
+#: A text file larger than this is skipped rather than read.
+MAX_TEXT_BYTES = 1_000_000
+_DYNAMIC_ACCESS = re.compile(r"\b(?:getattr|hasattr|setattr|delattr)\s*\(")
+
+
+def scan(
+    change: BreakingChange,
+    remaining: ImpactReport,
+    index: repo_index.RepoIndex,
+    root: Path,
+    config: Config,
+) -> CompletenessReport:
+    """Every place ``change``'s old name survives in the patched tree at ``root``.
+
+    ``remaining`` is the handler's analysis re-run on the patched code and
+    ``index`` the patched tree's index.
+    """
+    old, new = _names(change)
+    report = CompletenessReport(old=old, new=new)
+    seen: set[tuple[str, int]] = set()
+
+    for finding in remaining.findings:
+        if finding.other_object:
+            kind, reason = ResidualKind.OTHER_OBJECT, finding.unpatchable_reason
+        elif finding.patchable:
+            kind = ResidualKind.CODE
+            reason = (
+                f"confidence {finding.confidence.value} is below the "
+                f"`{config.min_confidence.value}` threshold"
+            )
+        else:
+            kind, reason = ResidualKind.CODE, finding.unpatchable_reason or finding.reason
+        _add(
+            report,
+            seen,
+            finding.path,
+            finding.reference.line,
+            kind,
+            finding.reference.snippet,
+            reason,
+        )
+
+    symbol = change.target.symbol
+    if not symbol:
+        return report
+    word = re.compile(rf"\b{re.escape(symbol)}\b")
+
+    for path in index.paths():
+        module = index.modules[path]
+        _scan_python(report, seen, change, path, module.source, word)
+
+    for path in _text_files(root, config):
+        try:
+            text = read_source(root / path)
+        except (OSError, UnicodeDecodeError):
+            continue
+        for number, line in enumerate(text.splitlines(), start=1):
+            if word.search(line):
+                kind = TEXT_FILES[Path(path).suffix.lower()]
+                _add(report, seen, path, number, kind, line.strip(), f"mentions `{symbol}`")
+
+    report.residuals.sort(key=lambda r: (list(ResidualKind).index(r.kind), r.path, r.line))
+    log.debug(
+        "completeness for `%s`: %d residual(s), %d unfinished",
+        old,
+        len(report.residuals),
+        len(report.unfinished),
+    )
+    return report
+
+
+def _names(change: BreakingChange) -> tuple[str, str]:
+    if change.kind is ChangeKind.PAGINATION_PAGE_TO_CURSOR:
+        return change.pagination.page_param, change.pagination.cursor_param
+    return change.target.symbol, change.target.replacement
+
+
+def _scan_python(
+    report: CompletenessReport,
+    seen: set[tuple[str, int]],
+    change: BreakingChange,
+    path: str,
+    source: str,
+    word: re.Pattern[str],
+) -> None:
+    symbol = change.target.symbol
+    is_test = repo_index.is_test_path(path)
+    lines = source.splitlines()
+    try:
+        tokens = list(tokenize.generate_tokens(io.StringIO(source).readline))
+    except (tokenize.TokenError, SyntaxError):
+        return
+
+    for token in tokens:
+        line = token.start[0]
+        text = lines[line - 1].strip() if 0 < line <= len(lines) else ""
+        if token.type == tokenize.NAME and token.string == symbol:
+            if is_test:
+                _add(
+                    report,
+                    seen,
+                    path,
+                    line,
+                    ResidualKind.TEST,
+                    text,
+                    "a test still uses the old name",
+                )
+            elif change.kind is ChangeKind.METHOD_RENAME:
+                # Field and keyword names are ordinary variable names too; a
+                # method's name appearing as a name is an import, a reference,
+                # or a definition -- each worth a look.
+                _add(report, seen, path, line, ResidualKind.CODE, text, _name_reason(text, symbol))
+        elif token.type == tokenize.STRING and word.search(token.string):
+            kind, reason = _string_residual(change, token, lines, text, is_test)
+            _add(report, seen, path, line, kind, text, reason)
+        elif token.type == tokenize.COMMENT and word.search(token.string):
+            _add(
+                report,
+                seen,
+                path,
+                line,
+                ResidualKind.COMMENT,
+                text,
+                f"a comment mentions `{symbol}`",
+            )
+
+
+def _string_residual(
+    change: BreakingChange,
+    token: tokenize.TokenInfo,
+    lines: list[str],
+    text: str,
+    is_test: bool,
+) -> tuple[ResidualKind, str]:
+    """Classify a string literal that contains the old name."""
+    symbol = change.target.symbol
+    literal = token.string.strip("rbuRBUfF").strip("'\"")
+    if literal == symbol and _DYNAMIC_ACCESS.search(text):
+        return (
+            ResidualKind.DYNAMIC,
+            "the old name is passed as a string, which no static rewrite can follow",
+        )
+    single_line = token.start[0] == token.end[0]
+    if literal == symbol and change.kind is ChangeKind.FIELD_RENAME and single_line:
+        role = _key_role(lines[token.start[0] - 1], token.start[1], token.end[1])
+        if role:
+            return (
+                (ResidualKind.TEST, f"a test {role}")
+                if is_test
+                else (
+                    ResidualKind.CODE,
+                    f"code {role}",
+                )
+            )
+    return ResidualKind.STRING, f"a string mentions `{symbol}`"
+
+
+def _key_role(line: str, start: int, end: int) -> str:
+    """How a string literal equal to a field name is used, if as a key at all.
+
+    ``x["total"]`` and ``x.get("total")`` read the field; ``{"total": 5}``
+    builds a payload or fixture with it. Any other string -- a label, a
+    message -- only mentions the word.
+    """
+    before, after = line[:start].rstrip(), line[end:].lstrip()
+    if before.endswith("[") and after.startswith("]"):
+        return "reads the old field by key"
+    if before.endswith(".get("):
+        return "reads the old field with .get()"
+    if after.startswith(":") and before.endswith(("{", ",")):
+        return "builds a dictionary with the old field name"
+    return ""
+
+
+def _name_reason(line: str, symbol: str) -> str:
+    if re.match(r"(?:from\s+\S+\s+)?import\b", line):
+        return "an import of the old name; call sites were rewritten, imports are not"
+    if re.match(rf"(?:async\s+)?def\s+{re.escape(symbol)}\b", line):
+        return "a definition with the old name in this repository"
+    return "a use of the old name that is not a call PatchAhead could rewrite"
+
+
+def _add(
+    report: CompletenessReport,
+    seen: set[tuple[str, int]],
+    path: str,
+    line: int,
+    kind: ResidualKind,
+    snippet: str,
+    reason: str,
+) -> None:
+    """Record a residual once per line: the first, most specific reading wins."""
+    if (path, line) in seen:
+        return
+    seen.add((path, line))
+    report.residuals.append(
+        Residual(path=path, line=line, kind=kind, snippet=snippet[:200], reason=reason)
+    )
+
+
+def _text_files(root: Path, config: Config) -> list[str]:
+    found: list[str] = []
+    for path in sorted(root.rglob("*")):
+        if path.suffix.lower() not in TEXT_FILES or not path.is_file():
+            continue
+        relative = path.relative_to(root).as_posix()
+        if repo_index.is_excluded(relative, config.exclude):
+            continue
+        try:
+            if path.stat().st_size > MAX_TEXT_BYTES:
+                continue
+        except OSError:
+            continue
+        found.append(relative)
+    return found