patchahead 0.3.0__py3-none-any.whl

patchahead/handlers/base.py

@@ -0,0 +1,211 @@
+"""The migration handler interface and registry.
+
+A *migration family* is one class. It answers four questions, in order:
+
+``supports(change)``
+    Is this change mine?
+``analyze(change, index, config)``
+    Where in this repository is the old contract used, and how sure am I?
+``plan(change, report, config)``
+    Which of those sites will I change, into what, and why not the others?
+``generate(plan, workspace)``
+    Apply the plan and produce a diff.
+
+Nothing outside this package needs an ``if change.kind == ...`` branch. The
+engine selects a handler through :func:`find_handler` and calls the interface,
+so adding a fifth family never touches the engine: it needs the new
+``ChangeKind``, the classifier's signals for it, the handler module, and the
+registry import in ``handlers/__init__.py`` (see ``docs/contributing.md``).
+
+Handlers must **fail closed**. A handler that cannot recognize the code shape it
+is looking at returns a plan with ``blocked_reason`` set, never a guess. The
+prototype's pagination transform guessed, and overwrote user code with the
+demo's function body (``docs/assessment.md`` §2.1).
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+
+from patchahead.analysis.index import RepoIndex
+from patchahead.config import Config
+from patchahead.domain.change import BreakingChange, ChangeKind
+from patchahead.domain.impact import ImpactReport
+from patchahead.domain.patch import FileEdit, PatchProposal
+from patchahead.domain.plan import MigrationPlan
+from patchahead.workspace import Workspace
+
+log = logging.getLogger(__name__)
+
+
+def analyzed_paths(index: RepoIndex, config: Config) -> list[str]:
+    """The modules a handler reads: the code, and its tests when ``migrate_tests``.
+
+    Tests that call the old API break with it, so migrating them is part of
+    the job. What keeps that honest is in the validation engine: a test this
+    patch edited is never counted as evidence that the patch worked.
+    """
+    return index.paths() if config.migrate_tests else index.non_test_paths()
+
+
+class MigrationHandler(ABC):
+    """Base class for a migration family."""
+
+    #: Stable identifier, recorded on plans and shown by ``patchahead handlers``.
+    name: str = ""
+    #: The change kinds this handler claims.
+    kinds: tuple[ChangeKind, ...] = ()
+    #: One-line description for ``patchahead handlers``.
+    summary: str = ""
+    #: What this handler explicitly does *not* do, shown in docs and the CLI.
+    limitations: tuple[str, ...] = ()
+
+    def supports(self, change: BreakingChange) -> bool:
+        """Whether this handler can act on ``change``.
+
+        The default is kind matching. Override to add preconditions -- for
+        example, the rename handlers also require both symbol names.
+        """
+        return change.kind in self.kinds
+
+    @abstractmethod
+    def analyze(self, change: BreakingChange, index: RepoIndex, config: Config) -> ImpactReport:
+        """Find every use of the old contract, with graded confidence."""
+
+    @abstractmethod
+    def plan(
+        self,
+        change: BreakingChange,
+        report: ImpactReport,
+        index: RepoIndex,
+        config: Config,
+    ) -> MigrationPlan:
+        """Decide which findings to rewrite and into what.
+
+        Takes the index as well as the report because some families need the
+        code again -- the pagination handler rebuilds its loop structures to
+        emit edits. Re-parsing inside the handler would cost a second pass and
+        could disagree with what analysis saw.
+        """
+
+    def generate(self, plan: MigrationPlan, workspace: Workspace) -> PatchProposal:
+        """Apply a plan inside a workspace and produce a diff.
+
+        The default implementation applies the plan's text edits file by file
+        and is correct for every deterministic handler; the edits themselves are
+        where a handler's intelligence lives. Override only for a family that
+        cannot express its change as range edits.
+        """
+        from patchahead.analysis import edits as edit_utils
+
+        if plan.blocked_reason:
+            return PatchProposal(plan=plan, engine="deterministic", error=plan.blocked_reason)
+        if plan.is_empty:
+            return PatchProposal(
+                plan=plan,
+                engine="deterministic",
+                error="the plan contains no transformations",
+            )
+
+        files: list[FileEdit] = []
+        entries: list[tuple[str, str, str]] = []
+        for path in plan.target_files:
+            try:
+                original = workspace.read(path)
+            except OSError as exc:
+                return PatchProposal(
+                    plan=plan, engine="deterministic", error=f"cannot read {path}: {exc}"
+                )
+            path_edits = plan.edits_for(path)
+            try:
+                patched = edit_utils.apply_edits(original, path_edits)
+            except edit_utils.EditError as exc:
+                return PatchProposal(
+                    plan=plan,
+                    engine="deterministic",
+                    error=f"cannot apply edits to {path}: {exc}",
+                )
+            workspace.write(path, patched)
+            files.append(
+                FileEdit(
+                    path=path,
+                    old_source=original,
+                    new_source=patched,
+                    edit_count=len(path_edits),
+                )
+            )
+            entries.append((path, original, patched))
+
+        return PatchProposal(
+            plan=plan,
+            files=files,
+            diff=edit_utils.combined_diff(entries),
+            engine="deterministic",
+            explanation=plan.rationale,
+        )
+
+
+_HANDLERS: list[MigrationHandler] = []
+
+
+def register(handler: MigrationHandler) -> MigrationHandler:
+    """Add a handler to the registry."""
+    _HANDLERS.append(handler)
+    return handler
+
+
+def registered() -> list[MigrationHandler]:
+    return list(_HANDLERS)
+
+
+def find_handler(change: BreakingChange) -> MigrationHandler | None:
+    """The first registered handler that supports ``change``, or ``None``."""
+    for handler in _HANDLERS:
+        if handler.supports(change):
+            return handler
+    return None
+
+
+def supported_kinds() -> list[ChangeKind]:
+    """Every change kind some registered handler claims."""
+    kinds: list[ChangeKind] = []
+    for handler in _HANDLERS:
+        for kind in handler.kinds:
+            if kind not in kinds:
+                kinds.append(kind)
+    return kinds
+
+
+def selftest_registry() -> list[str]:
+    """Check the registry's invariants. Returns a list of problems.
+
+    Enforces the project rule from ``docs/migrations.md``: every actionable
+    :class:`~patchahead.domain.change.ChangeKind` has a handler, every handler
+    is identifiable, and no two handlers claim the same kind. This is asserted
+    by the test suite so a half-added migration family fails CI rather than
+    shipping as a kind nothing can migrate.
+    """
+    problems: list[str] = []
+    claimed: dict[ChangeKind, str] = {}
+
+    for handler in _HANDLERS:
+        if not handler.name:
+            problems.append(f"{type(handler).__name__} has no `name`")
+        if not handler.kinds:
+            problems.append(f"handler `{handler.name}` claims no change kinds")
+        if not handler.summary:
+            problems.append(f"handler `{handler.name}` has no `summary`")
+        for kind in handler.kinds:
+            if kind in claimed:
+                problems.append(
+                    f"change kind `{kind.value}` is claimed by both "
+                    f"`{claimed[kind]}` and `{handler.name}`"
+                )
+            claimed[kind] = handler.name
+
+    for kind in ChangeKind:
+        if kind.is_actionable and kind not in claimed:
+            problems.append(f"change kind `{kind.value}` has no handler")
+
+    return problems

patchahead/handlers/field_rename.py

@@ -0,0 +1,425 @@
+"""Field rename: ``order["total"]`` -> ``order["amount"]``.
+
+The hardest part of this family is not rewriting -- it is deciding *what not to
+rewrite*. A field named ``total``, ``name``, ``id``, or ``status`` is a word that
+appears all over a codebase for unrelated reasons. The prototype matched the
+word as text and corrupted three out of four sites in a four-line test
+(``docs/assessment.md`` §2.2).
+
+Two mechanisms keep this one honest.
+
+**Syntactic filtering.** Only three constructs can be a field access:
+``obj["total"]``, ``obj.get("total")``, and ``obj.total``. A bare string literal
+(``LABEL = "total"``) is not one of them and is invisible to the AST walk, so it
+cannot be a false positive at all -- not "filtered out later", but never a
+candidate.
+
+**Confidence grading by receiver.** Among real accesses, the receiver decides:
+
+========================================  ==========  ====================
+Site (change document names ``order``)    Confidence  Patched by default?
+========================================  ==========  ====================
+``order["total"]``                        HIGH        yes
+``self.order["total"]``                   HIGH        yes
+``customer["total"]``                     LOW         no -- reported
+``o["total"]``                            LOW         no -- reported
+``df.total``                              LOW         no -- reported
+========================================  ==========  ====================
+
+When the change document names an owner, **a receiver that is not that owner is
+never patched**, however plausible the key looks. ``order["total"]`` and
+``customer["total"]`` on the same line are different fields that happen to share
+a name, and rewriting both is precisely the class of corruption this handler
+exists to prevent. Such sites are still *reported*, with the mismatch stated, so
+a human can decide.
+
+The cost is real and accepted: ``for o in orders: o["total"]`` is not patched
+automatically, because ``o`` cannot be shown to be an ``order`` without type
+inference PatchAhead does not do. A false negative is recoverable by hand; a
+silent wrong edit in unrelated code is not.
+
+When the document names **no** owner there is nothing to check the receiver
+against, so subscript and ``.get()`` accesses on a named receiver are graded
+MEDIUM (a constant string key matching a renamed field is strong evidence on its
+own) and attribute access stays LOW. A key on a nested or computed expression --
+``charge["customer"]["amount"]`` -- is LOW too: it reads a field of whatever the
+inner expression returns, which may be a different object entirely.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from patchahead.analysis import receiver_matches_owner
+from patchahead.analysis.index import RepoIndex, is_test_path
+from patchahead.config import Config
+from patchahead.domain.change import BreakingChange, ChangeKind, Confidence
+from patchahead.domain.impact import AccessKind, CodeReference, ImpactFinding, ImpactReport
+from patchahead.domain.plan import MigrationPlan, Risk, TextEdit, Transformation
+from patchahead.handlers.base import MigrationHandler, analyzed_paths, register
+
+log = logging.getLogger(__name__)
+
+
+def quoted_replacement(original_quote: str, new_value: str) -> str:
+    """Re-quote a string literal, preserving the author's quote style.
+
+    ``'total'`` becomes ``'amount'`` and ``"total"`` becomes ``"amount"``. A
+    rename should not also restyle the file.
+    """
+    quote = "'" if original_quote.lstrip("rbuRBU").startswith("'") else '"'
+    prefix = original_quote[: len(original_quote) - len(original_quote.lstrip("rbuRBU"))]
+    return f"{prefix}{quote}{new_value}{quote}"
+
+
+class FieldRenameHandler(MigrationHandler):
+    """Renames a data field accessed by subscript, ``.get()``, or attribute."""
+
+    name = "field_rename"
+    kinds = (ChangeKind.FIELD_RENAME,)
+    summary = 'Rename a response/data field: obj["old"], obj.get("old"), obj.old'
+    limitations = (
+        "Only constant string keys. `order[key]` with a variable key is reported, never rewritten.",
+        "Attribute access on a receiver that does not match the declared owner is "
+        "graded LOW and left for a human.",
+        'Does not follow the field through assignment: `t = order["total"]` is '
+        "renamed, but a later use of `t` is not traced.",
+    )
+
+    def supports(self, change: BreakingChange) -> bool:
+        return change.kind in self.kinds and change.target.is_rename
+
+    # -- analysis ----------------------------------------------------------
+
+    def analyze(self, change: BreakingChange, index: RepoIndex, config: Config) -> ImpactReport:
+        old = change.target.symbol
+        # Only an *asserted* owner constrains which receiver may be patched.
+        owner = change.target.owner if change.target.owner_is_explicit else ""
+        hint = "" if change.target.owner_is_explicit else change.target.owner
+        findings: list[ImpactFinding] = []
+
+        for path in analyzed_paths(index, config):
+            module = index.modules[path]
+            in_test = is_test_path(path)
+
+            for access in module.subscripts:
+                if access.key != old:
+                    continue
+                confidence, reason, patchable, blocked = _in_tests_only_on_the_owner(
+                    self._grade_subscript(access.receiver, owner, hint),
+                    in_test,
+                    access.receiver,
+                    owner or hint,
+                )
+                findings.append(
+                    ImpactFinding(
+                        reference=CodeReference(
+                            path=path,
+                            line=access.key_range.line,
+                            col=access.key_range.col,
+                            end_line=access.key_range.end_line,
+                            end_col=access.key_range.end_col,
+                            snippet=module.line_text(access.range.line),
+                        ),
+                        symbol=access.symbol,
+                        matched_contract=f'{access.receiver or "<expr>"}["{old}"]',
+                        access=AccessKind.SUBSCRIPT,
+                        reason=reason,
+                        confidence=confidence,
+                        source_text=_span(module.source, access.key_range),
+                        patchable=patchable,
+                        unpatchable_reason=blocked,
+                        other_object=_other_object(access.receiver, owner),
+                    )
+                )
+
+            for access in module.get_calls:
+                if access.key != old:
+                    continue
+                confidence, reason, patchable, blocked = _in_tests_only_on_the_owner(
+                    self._grade_subscript(access.receiver, owner, hint),
+                    in_test,
+                    access.receiver,
+                    owner or hint,
+                )
+                findings.append(
+                    ImpactFinding(
+                        reference=CodeReference(
+                            path=path,
+                            line=access.key_range.line,
+                            col=access.key_range.col,
+                            end_line=access.key_range.end_line,
+                            end_col=access.key_range.end_col,
+                            snippet=module.line_text(access.range.line),
+                        ),
+                        symbol=access.symbol,
+                        matched_contract=f'{access.receiver or "<expr>"}.get("{old}")',
+                        access=AccessKind.DICT_GET,
+                        reason=reason,
+                        confidence=confidence,
+                        source_text=_span(module.source, access.key_range),
+                        patchable=patchable,
+                        unpatchable_reason=blocked,
+                        other_object=_other_object(access.receiver, owner),
+                    )
+                )
+
+            for access in module.attributes:
+                if access.attr != old:
+                    continue
+                confidence, reason, patchable, blocked = _in_tests_only_on_the_owner(
+                    self._grade_attribute(access.receiver, owner, hint),
+                    in_test,
+                    access.receiver,
+                    owner or hint,
+                )
+                findings.append(
+                    ImpactFinding(
+                        reference=CodeReference(
+                            path=path,
+                            line=access.attr_range.line,
+                            col=access.attr_range.col,
+                            end_line=access.attr_range.end_line,
+                            end_col=access.attr_range.end_col,
+                            snippet=module.line_text(access.range.line),
+                        ),
+                        symbol=access.symbol,
+                        matched_contract=f"{access.receiver or '<expr>'}.{old}",
+                        access=AccessKind.ATTRIBUTE,
+                        reason=reason,
+                        confidence=confidence,
+                        source_text=_span(module.source, access.attr_range),
+                        patchable=patchable,
+                        unpatchable_reason=blocked,
+                        other_object=_other_object(access.receiver, owner),
+                    )
+                )
+
+        findings.sort(key=lambda f: (f.reference.path, f.reference.line, f.reference.col))
+        return ImpactReport(
+            change=change,
+            findings=findings,
+            related_tests=_related_tests(index, findings),
+            files_scanned=index.file_count,
+            skipped_files=dict(index.skipped),
+        )
+
+    def _grade_subscript(
+        self, receiver: str, owner: str, hint: str = ""
+    ) -> tuple[Confidence, str, bool, str]:
+        """Grade a dict-style access.
+
+        Returns ``(confidence, reason, patchable, blocked_reason)``.
+
+        A constant string key exactly matching a renamed field is strong
+        evidence on its own -- dicts are how API responses arrive in Python --
+        but only when there is nothing to contradict it. A named owner that the
+        receiver does not match *is* such a contradiction, and it wins.
+        """
+        if owner and receiver_matches_owner(receiver, owner):
+            return (
+                Confidence.HIGH,
+                f"dict access with the renamed key on `{owner}`, the object the "
+                f"change document names",
+                True,
+                "",
+            )
+        if owner:
+            return (
+                Confidence.LOW,
+                f"dict access with the renamed key, but on "
+                f"`{receiver or '<expression>'}` rather than `{owner}`, which the "
+                f"change document names as the owner of this field",
+                False,
+                f"receiver is `{receiver or '<expression>'}`, not the declared owner `{owner}`",
+            )
+        if hint and receiver_matches_owner(receiver, hint):
+            return (
+                Confidence.HIGH,
+                f"dict access with the renamed key on `{receiver}`, matching the "
+                f"receiver used in the change document's example",
+                True,
+                "",
+            )
+        if not receiver:
+            # `charge["customer"]["amount"]`: the key belongs to whatever the
+            # inner expression returns, which is a different object from the one
+            # the access chain starts at. With no owner to check, there is no
+            # evidence it is the renamed field rather than a nested one.
+            return (
+                Confidence.LOW,
+                "dict access with the renamed key on a nested or computed "
+                "expression; the change document asserts no owning object, so "
+                "there is nothing to tell this field from one on a nested object",
+                False,
+                "receiver is a nested or computed expression and no owner is asserted",
+            )
+        return (
+            Confidence.MEDIUM,
+            "dict access with the renamed key; the change document asserts no "
+            "owning object, so the receiver could not be checked",
+            True,
+            "",
+        )
+
+    def _grade_attribute(
+        self, receiver: str, owner: str, hint: str = ""
+    ) -> tuple[Confidence, str, bool, str]:
+        """Grade an attribute access.
+
+        Weaker than a subscript in the unowned case: ``.total`` on an arbitrary
+        object is poor evidence, because attribute names collide across
+        unrelated libraries. Only a receiver match makes it actionable.
+        """
+        if owner and receiver_matches_owner(receiver, owner):
+            return (
+                Confidence.HIGH,
+                f"attribute access on `{owner}`, the object the change document names",
+                True,
+                "",
+            )
+        if owner:
+            return (
+                Confidence.LOW,
+                f"attribute with the renamed name on "
+                f"`{receiver or '<expression>'}` rather than `{owner}`, which the "
+                f"change document names as the owner of this field",
+                False,
+                f"receiver is `{receiver or '<expression>'}`, not the declared owner `{owner}`",
+            )
+        if hint and receiver_matches_owner(receiver, hint):
+            return (
+                Confidence.HIGH,
+                f"attribute access on `{receiver}`, matching the receiver used in "
+                f"the change document's example",
+                True,
+                "",
+            )
+        return (
+            Confidence.LOW,
+            "attribute access with a matching name, but the change document "
+            "asserts no owning object, so this cannot be distinguished from an "
+            "unrelated attribute",
+            False,
+            "attribute access with no asserted owner to check the receiver against",
+        )
+
+    # -- planning ----------------------------------------------------------
+
+    def plan(
+        self,
+        change: BreakingChange,
+        report: ImpactReport,
+        index: RepoIndex,
+        config: Config,
+    ) -> MigrationPlan:
+        old, new = change.target.symbol, change.target.replacement
+        plan = MigrationPlan(
+            change=change,
+            handler=self.name,
+            expected_tests=list(report.related_tests),
+            risk=Risk.LOW,
+            rationale=(
+                f"Rename the `{old}` field to `{new}` at every data access that "
+                f"reads it. Only subscript, `.get()`, and attribute accesses are "
+                f"rewritten; string literals that merely contain the word `{old}` "
+                f"are not field accesses and are left alone."
+            ),
+        )
+
+        for finding in report.findings:
+            if not finding.patchable:
+                plan.skipped.append(
+                    f"{finding.reference} ({finding.matched_contract}): "
+                    f"{finding.unpatchable_reason}"
+                )
+                continue
+            if finding.confidence < config.min_confidence:
+                plan.skipped.append(
+                    f"{finding.reference} ({finding.matched_contract}): confidence "
+                    f"{finding.confidence.value} is below the `{config.min_confidence.value}` "
+                    f"threshold"
+                )
+                continue
+
+            reference = finding.reference
+            if finding.access is AccessKind.ATTRIBUTE:
+                old_text, new_text = old, new
+            else:
+                # The recorded span is the quoted literal; preserve quote style.
+                old_text = finding.source_text or f'"{old}"'
+                new_text = quoted_replacement(old_text, new)
+
+            plan.transformations.append(
+                Transformation(
+                    reference=reference,
+                    old=old_text,
+                    new=new_text,
+                    symbol=finding.symbol,
+                    confidence=finding.confidence,
+                    edit=TextEdit(
+                        line=reference.line,
+                        col=reference.col,
+                        end_line=reference.end_line or reference.line,
+                        end_col=reference.end_col or reference.col,
+                        new_text=new_text,
+                        description=f"rename `{old}` to `{new}` ({finding.access.value})",
+                    ),
+                )
+            )
+
+        if not plan.transformations:
+            plan.blocked_reason = (
+                f"found {len(report.findings)} reference(s) to `{old}` but none met "
+                f"the `{config.min_confidence.value}` confidence threshold for "
+                f"automatic rewriting"
+                if report.findings
+                else f"no field accesses to `{old}` were found"
+            )
+        return plan
+
+
+def _span(source: str, source_range) -> str:
+    """The exact source text a single-line range covers."""
+    lines = source.splitlines()
+    if not (1 <= source_range.line <= len(lines)):
+        return ""
+    if source_range.end_line != source_range.line:
+        return ""
+    return lines[source_range.line - 1][source_range.col : source_range.end_col]
+
+
+def _related_tests(index: RepoIndex, findings: list[ImpactFinding]) -> list[str]:
+    from patchahead.testing import discovery
+
+    return discovery.tests_for_paths(index, [f.path for f in findings])
+
+
+register(FieldRenameHandler())
+
+
+def _other_object(receiver: str, owner: str) -> bool:
+    """Whether an *asserted* owner rules this receiver out."""
+    return bool(owner) and not receiver_matches_owner(receiver, owner)
+
+
+def _in_tests_only_on_the_owner(
+    graded: tuple[Confidence, str, bool, str], in_test: bool, receiver: str, owner: str
+) -> tuple[Confidence, str, bool, str]:
+    """In a test, a field is renamed only on the object the change names.
+
+    A test builds fake upstream responses -- which do change -- but it also
+    asserts on the application's own output, which does not: `report["total"]`
+    in a test is the report's field, whatever the API renamed. Without an owner
+    to tell the two apart, a test site is reported rather than rewritten.
+    """
+    confidence, reason, patchable, blocked = graded
+    if in_test and patchable and not receiver_matches_owner(receiver, owner):
+        return (
+            Confidence.LOW,
+            f"{reason}; in a test, a field is renamed only on the object the change "
+            f"document names, since tests also check the code's own output",
+            False,
+            "a test site whose receiver is not the named owner",
+        )
+    return graded