patchahead 0.3.0__py3-none-any.whl

patchahead/__init__.py

@@ -0,0 +1,8 @@
+"""PatchAhead — find and migrate downstream code broken by upstream API changes.
+
+Static evidence identifies risk. AI can propose. Tests verify. Humans approve.
+"""
+
+__version__ = "0.3.0"
+
+__all__ = ["__version__"]

patchahead/analysis/__init__.py

@@ -0,0 +1,52 @@
+"""Static analysis: parsing Python source and applying range-based edits."""
+
+from patchahead.analysis.edits import (
+    EditError,
+    apply_edits,
+    combined_diff,
+    is_parseable,
+    unified_diff,
+)
+from patchahead.analysis.index import RepoIndex, build, discover_python_files, is_test_path
+from patchahead.analysis.python_ast import (
+    MODULE_SCOPE,
+    AttributeAccess,
+    CallSite,
+    ColumnMap,
+    GetCallAccess,
+    ModuleAnalysis,
+    ParseError,
+    SourceRange,
+    SubscriptAccess,
+    analyze_source,
+    base_name,
+    iter_own_scope,
+    receiver_matches_owner,
+    receiver_name,
+)
+
+__all__ = [
+    "MODULE_SCOPE",
+    "AttributeAccess",
+    "CallSite",
+    "ColumnMap",
+    "EditError",
+    "GetCallAccess",
+    "ModuleAnalysis",
+    "ParseError",
+    "RepoIndex",
+    "SourceRange",
+    "SubscriptAccess",
+    "analyze_source",
+    "apply_edits",
+    "base_name",
+    "build",
+    "combined_diff",
+    "discover_python_files",
+    "is_parseable",
+    "is_test_path",
+    "iter_own_scope",
+    "receiver_matches_owner",
+    "receiver_name",
+    "unified_diff",
+]

patchahead/analysis/edits.py

@@ -0,0 +1,143 @@
+"""Applying source ranges edits, and rendering diffs.
+
+Edits are applied to the original text by range, not by regenerating the module
+from its AST. ``ast.unparse`` would discard every comment, blank line, and
+formatting choice in the file, turning a two-token rename into a whole-file
+rewrite that no reviewer would approve. Range edits keep the diff to exactly the
+tokens that changed.
+"""
+
+from __future__ import annotations
+
+import ast
+import difflib
+from pathlib import Path
+
+from patchahead.domain.plan import TextEdit
+
+
+class EditError(Exception):
+    """Raised when a set of edits cannot be applied safely."""
+
+
+def read_source(path: Path) -> str:
+    """Read a file as UTF-8 text with its line endings exactly as they are.
+
+    ``Path.read_text`` translates ``\r\n`` to ``\n``, and writing that back
+    converts a whole Windows-style file to Unix endings: a two-token rename
+    becomes a diff of every line, and the patch no longer applies to the file
+    it was made from.
+    """
+    return path.read_bytes().decode("utf-8")
+
+
+def write_source(path: Path, text: str) -> None:
+    """Write UTF-8 text without translating line endings. See :func:`read_source`."""
+    path.write_bytes(text.encode("utf-8"))
+
+
+def newline_of(text: str) -> str:
+    """The line ending a file uses: ``\r\n`` if its first line ends that way."""
+    first = text.find("\n")
+    return "\r\n" if first > 0 and text[first - 1] == "\r" else "\n"
+
+
+def _offset(line_starts: list[int], line: int, col: int, length: int) -> int:
+    """Absolute character offset for a 1-indexed line and 0-indexed column."""
+    if line < 1 or line > len(line_starts):
+        raise EditError(f"line {line} is out of range (file has {len(line_starts)} lines)")
+    offset = line_starts[line - 1] + col
+    if offset > length:
+        raise EditError(f"position {line}:{col} is past the end of the file")
+    return offset
+
+
+def apply_edits(source: str, edits: list[TextEdit]) -> str:
+    """Apply ``edits`` to ``source`` and return the new text.
+
+    Edits are applied from the end of the file backwards so earlier offsets stay
+    valid. Overlapping edits are rejected rather than silently resolved: two
+    handlers disagreeing about the same range is a bug, and producing a
+    plausible-looking merge would hide it.
+    """
+    if not edits:
+        return source
+
+    line_starts = [0]
+    for index, char in enumerate(source):
+        if char == "\n":
+            line_starts.append(index + 1)
+    length = len(source)
+
+    spans: list[tuple[int, int, str]] = []
+    for edit in edits:
+        start = _offset(line_starts, edit.line, edit.col, length)
+        end = _offset(line_starts, edit.end_line, edit.end_col, length)
+        if end < start:
+            raise EditError(
+                f"edit at {edit.line}:{edit.col} ends before it starts "
+                f"({edit.end_line}:{edit.end_col})"
+            )
+        spans.append((start, end, edit.new_text))
+
+    spans.sort(key=lambda span: (span[0], span[1]))
+    for (_, end, _), (next_start, _, _) in zip(spans, spans[1:], strict=False):
+        if next_start < end:
+            raise EditError(
+                f"overlapping edits: span ending at offset {end} overlaps the span "
+                f"starting at offset {next_start}"
+            )
+
+    result = source
+    for start, end, new_text in reversed(spans):
+        result = result[:start] + new_text + result[end:]
+    return result
+
+
+def is_parseable(source: str, path: str = "<patched>") -> tuple[bool, str]:
+    """Whether ``source`` parses as Python, and the error if it does not.
+
+    Used by the syntax gate. ``ast.parse`` rather than ``compile`` because it
+    catches the same syntax errors without executing any compile-time side
+    effects, and gives a cleaner message.
+    """
+    try:
+        ast.parse(source, filename=path)
+    except SyntaxError as exc:
+        return False, f"{path}:{exc.lineno or '?'}:{exc.offset or '?'}: {exc.msg}"
+    except ValueError as exc:
+        return False, f"{path}: {exc}"
+    return True, ""
+
+
+def unified_diff(old: str, new: str, path: str, context: int = 3) -> str:
+    """A git-style unified diff for one file.
+
+    ``a/``-``b/`` prefixes and a trailing newline make the output directly
+    consumable by ``git apply`` and ``patch -p1``.
+    """
+    if old == new:
+        return ""
+    diff = difflib.unified_diff(
+        old.splitlines(keepends=True),
+        new.splitlines(keepends=True),
+        fromfile=f"a/{path}",
+        tofile=f"b/{path}",
+        n=context,
+    )
+    text = "".join(diff)
+    if text and not text.endswith("\n"):
+        text += "\n"
+    return text
+
+
+def combined_diff(files: list[tuple[str, str, str]], context: int = 3) -> str:
+    """A single diff across several files, ordered by path.
+
+    ``files`` is a list of ``(path, old_source, new_source)``.
+    """
+    parts = [
+        unified_diff(old, new, path, context=context)
+        for path, old, new in sorted(files, key=lambda item: item[0])
+    ]
+    return "".join(part for part in parts if part)

patchahead/analysis/index.py

@@ -0,0 +1,203 @@
+"""A parsed, cached view of one repository's Python source.
+
+Each file is read and parsed at most once per run, no matter how many handlers
+analyze it. The prototype re-read and re-scanned every file for every pattern of
+every change; this does one pass and shares it.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+
+from patchahead.analysis.edits import read_source
+from patchahead.analysis.python_ast import ModuleAnalysis, ParseError, analyze_source
+from patchahead.config import Config
+
+log = logging.getLogger(__name__)
+
+#: Files larger than this are skipped. A multi-megabyte generated module is
+#: never the hand-written integration code a migration targets, and parsing it
+#: costs more than it can possibly return.
+MAX_FILE_BYTES = 2_000_000
+
+
+@dataclass
+class RepoIndex:
+    """Discovered and parsed Python modules under a repository root."""
+
+    root: Path
+    config: Config
+    #: relative POSIX path -> parsed module
+    modules: dict[str, ModuleAnalysis] = field(default_factory=dict)
+    #: relative POSIX path -> why it was skipped
+    skipped: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def file_count(self) -> int:
+        return len(self.modules)
+
+    def paths(self) -> list[str]:
+        return sorted(self.modules)
+
+    def get(self, path: str) -> ModuleAnalysis | None:
+        return self.modules.get(path)
+
+    def source_of(self, path: str) -> str:
+        module = self.modules.get(path)
+        return module.source if module else ""
+
+    def test_paths(self) -> list[str]:
+        """Paths that look like pytest test modules."""
+        return [p for p in self.paths() if is_test_path(p)]
+
+    def non_test_paths(self) -> list[str]:
+        return [p for p in self.paths() if not is_test_path(p)]
+
+
+def is_test_path(path: str) -> bool:
+    """Whether a relative path looks like a pytest test module.
+
+    Follows pytest's own default discovery rules (``test_*.py`` / ``*_test.py``),
+    plus the near-universal convention of a ``tests/`` directory.
+    """
+    pure = PurePosixPath(path)
+    name = pure.name
+    if name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    return any(part in ("test", "tests") for part in pure.parts[:-1])
+
+
+def is_excluded(relative: str, patterns: list[str]) -> bool:
+    """Whether a relative POSIX path is excluded by name or glob.
+
+    A bare name like ``node_modules`` excludes any directory with that name at
+    any depth; a pattern containing ``/`` or ``*`` is matched as a glob against
+    the whole relative path.
+    """
+    parts = PurePosixPath(relative).parts
+    for pattern in patterns:
+        if "/" in pattern or "*" in pattern or "?" in pattern:
+            if fnmatch.fnmatch(relative, pattern):
+                return True
+            if fnmatch.fnmatch(relative, pattern.rstrip("/") + "/*"):
+                return True
+        elif pattern in parts:
+            return True
+    return False
+
+
+def discover_python_files(root: Path, config: Config) -> list[Path]:
+    """Every analyzable ``.py`` file under ``root``, honouring the config.
+
+    Directories are pruned during the walk rather than filtered afterwards, so
+    a ``node_modules`` or ``.venv`` inside the repository costs nothing.
+    """
+    root = Path(root).resolve()
+    roots: list[Path] = []
+    if config.source_dirs:
+        for entry in config.source_dirs:
+            candidate = (root / entry).resolve()
+            if not candidate.is_dir():
+                log.warning("configured source_dir does not exist: %s", entry)
+                continue
+            if root not in candidate.parents and candidate != root:
+                log.warning("ignoring source_dir outside the repository: %s", entry)
+                continue
+            roots.append(candidate)
+        if not roots:
+            log.warning("no configured source_dirs exist; scanning the whole repository")
+            roots = [root]
+    else:
+        roots = [root]
+
+    # When `source_dirs` narrows analysis, test files are still discovered from
+    # the whole repository. `source_dirs` exists to stop PatchAhead proposing
+    # edits outside a project's own source; it is not a statement about where
+    # the tests live, and narrowing test discovery with it would silently
+    # disable the targeted-test validation gate.
+    scan_roots = list(roots)
+    if config.source_dirs and root not in scan_roots:
+        scan_roots.append(root)
+
+    found: list[Path] = []
+    seen: set[Path] = set()
+    for base in scan_roots:
+        restrict_to_tests = base == root and config.source_dirs
+        stack = [base]
+        while stack:
+            directory = stack.pop()
+            try:
+                entries = sorted(directory.iterdir())
+            except OSError as exc:
+                log.debug("cannot list %s: %s", directory, exc)
+                continue
+            for entry in entries:
+                try:
+                    relative = entry.resolve().relative_to(root).as_posix()
+                except ValueError:
+                    # A symlink pointing outside the repository. Following it
+                    # could make PatchAhead read or propose edits to files the
+                    # user did not point it at.
+                    log.debug("skipping path outside the repository: %s", entry)
+                    continue
+                if is_excluded(relative, config.exclude):
+                    continue
+                if entry.is_symlink():
+                    log.debug("skipping symlink: %s", relative)
+                    continue
+                if entry.is_dir():
+                    stack.append(entry)
+                elif entry.suffix == ".py" and entry not in seen:
+                    if restrict_to_tests and not is_test_path(relative):
+                        continue
+                    seen.add(entry)
+                    found.append(entry)
+    return sorted(found)
+
+
+def build(root: Path, config: Config) -> RepoIndex:
+    """Discover, read, and parse every Python file under ``root``.
+
+    Unreadable and unparseable files are recorded in
+    :attr:`RepoIndex.skipped` with a reason and reported to the user, rather
+    than dropped. A repository with a syntax error in one module is still
+    analyzable, but the user should know which module was not looked at.
+    """
+    root = Path(root).resolve()
+    index = RepoIndex(root=root, config=config)
+
+    for path in discover_python_files(root, config):
+        relative = path.relative_to(root).as_posix()
+        try:
+            size = path.stat().st_size
+        except OSError as exc:
+            index.skipped[relative] = f"cannot stat: {exc}"
+            continue
+        if size > MAX_FILE_BYTES:
+            index.skipped[relative] = f"file is {size} bytes (limit {MAX_FILE_BYTES})"
+            continue
+        try:
+            source = read_source(path)
+        except UnicodeDecodeError as exc:
+            index.skipped[relative] = f"not valid UTF-8: {exc.reason}"
+            continue
+        except OSError as exc:
+            index.skipped[relative] = f"cannot read: {exc}"
+            continue
+        try:
+            index.modules[relative] = analyze_source(source, relative)
+        except ParseError as exc:
+            index.skipped[relative] = f"syntax error: {exc}"
+
+    log.debug(
+        "indexed %d module(s), skipped %d, under %s",
+        len(index.modules),
+        len(index.skipped),
+        root,
+    )
+    for relative, reason in index.skipped.items():
+        log.debug("skipped %s: %s", relative, reason)
+    return index