patchahead 0.3.0__py3-none-any.whl

patchahead/domain/change.py

@@ -0,0 +1,269 @@
+"""The upstream side of the domain model: what broke, and how sure we are.
+
+A :class:`BreakingChange` is the output of change ingestion and the input to
+everything else. It carries two things that the prototype conflated:
+
+* what the change *is* (:class:`ChangeKind` plus a :class:`SymbolTarget`), and
+* how confident we are that we read the document correctly
+  (:class:`Confidence` plus the :class:`Evidence` we based it on).
+
+Uncertain extraction is represented as uncertain. A document PatchAhead cannot
+classify yields ``ChangeKind.UNKNOWN``, not a plausible-looking guess.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class ChangeKind(str, enum.Enum):
+    """The migration families PatchAhead knows about.
+
+    Every member except :attr:`UNKNOWN` and :attr:`UNSUPPORTED` has a handler in
+    :mod:`patchahead.handlers` with analysis, planning, patching, validation,
+    tests, and documentation. Adding a member without a handler is a bug --
+    :func:`patchahead.handlers.selftest_registry` asserts this.
+    """
+
+    FIELD_RENAME = "field_rename"
+    METHOD_RENAME = "method_rename"
+    KWARG_RENAME = "kwarg_rename"
+    PAGINATION_PAGE_TO_CURSOR = "pagination_page_to_cursor"
+
+    #: Recognized as a breaking change, but no v1 handler can migrate it.
+    UNSUPPORTED = "unsupported"
+    #: The document could not be classified at all.
+    UNKNOWN = "unknown"
+
+    @property
+    def is_actionable(self) -> bool:
+        return self not in (ChangeKind.UNSUPPORTED, ChangeKind.UNKNOWN)
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+class Confidence(str, enum.Enum):
+    """Graded confidence, ordered.
+
+    Deliberately coarse. A float implies a calibration we do not have; three
+    buckets can be explained to a reviewer and tested against fixtures.
+    """
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+    @property
+    def rank(self) -> int:
+        return {"low": 0, "medium": 1, "high": 2}[self.value]
+
+    def __ge__(self, other: object) -> bool:
+        if not isinstance(other, Confidence):
+            return NotImplemented
+        return self.rank >= other.rank
+
+    def __gt__(self, other: object) -> bool:
+        if not isinstance(other, Confidence):
+            return NotImplemented
+        return self.rank > other.rank
+
+    def __le__(self, other: object) -> bool:
+        if not isinstance(other, Confidence):
+            return NotImplemented
+        return self.rank <= other.rank
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Confidence):
+            return NotImplemented
+        return self.rank < other.rank
+
+    @classmethod
+    def parse(cls, value: object, default: Confidence = None) -> Confidence:
+        """Coerce user/LLM-supplied text to a member, falling back to ``default``."""
+        if isinstance(value, Confidence):
+            return value
+        if isinstance(value, str):
+            try:
+                return cls(value.strip().lower())
+            except ValueError:
+                pass
+        if default is None:
+            raise ValueError(f"not a confidence level: {value!r}")
+        return default
+
+
+class Severity(str, enum.Enum):
+    """How bad the break is if left unmigrated. Reported, never acted upon."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+    @classmethod
+    def parse(cls, value: object, default: Severity = None) -> Severity:
+        if isinstance(value, Severity):
+            return value
+        if isinstance(value, str):
+            try:
+                return cls(value.strip().lower())
+            except ValueError:
+                pass
+        if default is None:
+            raise ValueError(f"not a severity: {value!r}")
+        return default
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """A quotation from the change document that justifies a conclusion.
+
+    Evidence always points back at the source text. If PatchAhead asserts
+    something about a change, a reviewer can find the line it came from.
+    """
+
+    quote: str
+    #: 1-indexed line in the source document, when known.
+    line: int | None = None
+    #: Free-text note on why this quote mattered, e.g. "matched 'renamed to'".
+    note: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"quote": self.quote, "line": self.line, "note": self.note}
+
+
+@dataclass
+class SymbolTarget:
+    """The concrete syntactic thing a migration renames or rewrites.
+
+    ``symbol`` and ``replacement`` are the old and new names. ``owner`` scopes
+    them: for a field rename it is the object the field hangs off
+    (``order["total"]`` -> owner ``order``), and for a kwarg rename it is the
+    function being called (``fetch_orders(timeout_seconds=...)`` -> owner
+    ``fetch_orders``). ``owner`` is the main tool for suppressing false
+    positives, and it is optional because release notes often omit it.
+
+    ``owner_is_explicit`` records *how strongly* the document asserted the
+    owner, and it decides whether a receiver mismatch refuses or merely lowers
+    confidence. The distinction is real:
+
+    * "the field on each ``order`` object was renamed" and
+      "``client.fetch_orders`` -> ``client.list_orders``" **assert** ownership.
+      A mismatched receiver is then evidence of a *different* object, and the
+      site is reported rather than patched.
+    * "**Before:** ``client.fetch_orders(limit=10)``" is the vendor's
+      illustrative variable name. It says nothing about what a downstream
+      repository calls its variable, and treating it as a constraint would
+      refuse to migrate ``api_client.fetch_orders()`` -- the same SDK call,
+      spelled with a different local name.
+
+    Structured change documents always set this to ``True``: someone typed the
+    owner into a field named ``owner``, which is an assertion by construction.
+    """
+
+    symbol: str = ""
+    replacement: str = ""
+    owner: str = ""
+    #: Whether the document *asserted* the owner rather than it being inferred
+    #: from an illustrative snippet. See the class docstring.
+    owner_is_explicit: bool = False
+
+    @property
+    def is_rename(self) -> bool:
+        return bool(self.symbol and self.replacement and self.symbol != self.replacement)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "replacement": self.replacement,
+            "owner": self.owner,
+            "owner_is_explicit": self.owner_is_explicit,
+        }
+
+
+@dataclass
+class PaginationContract:
+    """Field and parameter names for a page-based -> cursor-based migration.
+
+    Defaults are the overwhelmingly common names. They are overridable so the
+    handler is not tied to one vendor's vocabulary.
+    """
+
+    page_param: str = "page"
+    total_pages_key: str = "total_pages"
+    cursor_param: str = "cursor"
+    next_cursor_key: str = "next_cursor"
+    has_more_key: str = "has_more"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "page_param": self.page_param,
+            "total_pages_key": self.total_pages_key,
+            "cursor_param": self.cursor_param,
+            "next_cursor_key": self.next_cursor_key,
+            "has_more_key": self.has_more_key,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> PaginationContract:
+        data = data or {}
+        base = cls()
+        return cls(
+            page_param=str(data.get("page_param") or base.page_param),
+            total_pages_key=str(data.get("total_pages_key") or base.total_pages_key),
+            cursor_param=str(data.get("cursor_param") or base.cursor_param),
+            next_cursor_key=str(data.get("next_cursor_key") or base.next_cursor_key),
+            has_more_key=str(data.get("has_more_key") or base.has_more_key),
+        )
+
+
+@dataclass
+class BreakingChange:
+    """One breaking change, extracted from one change document.
+
+    A document may describe several; ingestion returns a list of these.
+    """
+
+    title: str
+    kind: ChangeKind
+    target: SymbolTarget = field(default_factory=SymbolTarget)
+    old_behavior: str = ""
+    new_behavior: str = ""
+    migration_hint: str = ""
+    severity: Severity = Severity.MEDIUM
+    #: How confident ingestion is that this reading of the document is correct.
+    confidence: Confidence = Confidence.MEDIUM
+    evidence: list[Evidence] = field(default_factory=list)
+    pagination: PaginationContract = field(default_factory=PaginationContract)
+    #: Which parser produced this: "markdown", "structured", or "llm".
+    source: str = "markdown"
+    #: Why classification landed where it did -- shown to the user verbatim.
+    classification_reason: str = ""
+
+    @property
+    def is_actionable(self) -> bool:
+        return self.kind.is_actionable
+
+    def describe(self) -> str:
+        """A one-line human summary, used in logs and reports."""
+        if self.target.is_rename:
+            return f"{self.kind.value}: `{self.target.symbol}` -> `{self.target.replacement}`"
+        return f"{self.kind.value}: {self.title}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "kind": self.kind.value,
+            "target": self.target.to_dict(),
+            "old_behavior": self.old_behavior,
+            "new_behavior": self.new_behavior,
+            "migration_hint": self.migration_hint,
+            "severity": self.severity.value,
+            "confidence": self.confidence.value,
+            "evidence": [e.to_dict() for e in self.evidence],
+            "pagination": self.pagination.to_dict(),
+            "source": self.source,
+            "classification_reason": self.classification_reason,
+        }

patchahead/domain/completeness.py

@@ -0,0 +1,91 @@
+"""What is left of the old API after a migration.
+
+Tests that pass after a patch show that the code they exercise works. They do
+not show that the migration is *finished*: a wrapper no test calls, a
+``getattr(order, "total")``, an import of the old name, or a test that still
+mocks the old method can all survive a green run. A completeness report lists
+every place the old name still appears in the patched copy, sorted by how much
+it needs a person's attention.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class ResidualKind(str, enum.Enum):
+    """Where an old name survived, from most to least in need of attention."""
+
+    #: Code that still uses the old name and was not rewritten.
+    CODE = "code"
+    #: The old name as a string handed to ``getattr``/``hasattr``/``setattr``:
+    #: an access no static rewrite can see, which fails only at runtime.
+    DYNAMIC = "dynamic"
+    #: A test that still uses the old name.
+    TEST = "test"
+    #: The same name on an object the change document says is not affected.
+    OTHER_OBJECT = "other_object"
+    #: A string, comment, configuration file, or document mentioning the name.
+    STRING = "string"
+    COMMENT = "comment"
+    CONFIG = "config"
+    DOCS = "docs"
+
+    @property
+    def unfinished(self) -> bool:
+        """Whether a residual of this kind means the migration is not done."""
+        return self in (ResidualKind.CODE, ResidualKind.DYNAMIC, ResidualKind.TEST)
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass(frozen=True)
+class Residual:
+    """One place the old name still appears after patching."""
+
+    path: str
+    line: int
+    kind: ResidualKind
+    snippet: str
+    reason: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "line": self.line,
+            "kind": self.kind.value,
+            "snippet": self.snippet,
+            "reason": self.reason,
+        }
+
+
+@dataclass
+class CompletenessReport:
+    """Every surviving use of one change's old name, in the patched copy."""
+
+    old: str
+    new: str
+    residuals: list[Residual] = field(default_factory=list)
+
+    @property
+    def unfinished(self) -> list[Residual]:
+        return [r for r in self.residuals if r.kind.unfinished]
+
+    @property
+    def complete(self) -> bool:
+        """No code, dynamic access, or test still uses the old name."""
+        return not self.unfinished
+
+    def count(self, kind: ResidualKind) -> int:
+        return sum(1 for residual in self.residuals if residual.kind is kind)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "old": self.old,
+            "new": self.new,
+            "complete": self.complete,
+            "residuals": [r.to_dict() for r in self.residuals],
+        }

patchahead/domain/impact.py

@@ -0,0 +1,248 @@
+"""The downstream side of the domain model: what the change touches.
+
+The chain the prototype could not express, and which every report now walks:
+
+.. code-block:: text
+
+    BreakingChange
+       -> affected API symbol          (BreakingChange.target)
+       -> call sites / data accesses   (CodeReference)
+       -> affected functions           (ImpactFinding.symbol)
+       -> affected files               (ImpactFinding.reference.path)
+       -> relevant tests               (ImpactReport.related_tests)
+
+:class:`ImpactGraph` materializes that chain so migration planning can be
+explained rather than asserted.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+from patchahead.domain.change import BreakingChange, Confidence
+
+
+class AccessKind(str, enum.Enum):
+    """The syntactic shape of an old-contract usage, as seen by the AST."""
+
+    #: ``obj["name"]``
+    SUBSCRIPT = "subscript"
+    #: ``obj.get("name")``
+    DICT_GET = "dict_get"
+    #: ``obj.name``
+    ATTRIBUTE = "attribute"
+    #: ``name(...)`` or ``obj.name(...)``
+    CALL = "call"
+    #: ``f(name=...)``
+    KEYWORD_ARG = "keyword_arg"
+    #: A ``while``-loop paginating over an integer page counter.
+    PAGE_LOOP = "page_loop"
+    #: ``from sdk import name``
+    IMPORT = "import"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass(frozen=True)
+class CodeReference:
+    """A precise location in a source file.
+
+    Columns are 0-indexed **character** offsets into the line -- not the byte
+    offsets ``ast`` reports. The two agree only while a line is pure ASCII, and
+    :mod:`patchahead.analysis.python_ast` converts at the single point where
+    ``ast`` data enters the system, so everything downstream of it (this class
+    included) is character-based and can index a Python ``str`` directly.
+
+    ``line`` is 1-indexed, matching every editor and traceback. Ranges are
+    half-open on the end column, matching ``ast``.
+    """
+
+    #: Path relative to the repository root, always POSIX-style.
+    path: str
+    line: int
+    col: int = 0
+    end_line: int | None = None
+    end_col: int | None = None
+    #: The source line, stripped -- so a report is readable without the file.
+    snippet: str = ""
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "line": self.line,
+            "col": self.col,
+            "end_line": self.end_line,
+            "end_col": self.end_col,
+            "snippet": self.snippet,
+        }
+
+
+@dataclass
+class ImpactFinding:
+    """One place in the downstream repository affected by the change.
+
+    Every field here exists because a reviewer needs it: *where* (reference),
+    *in what* (symbol), *what matched* (matched_contract, access), *why we think
+    so* (reason), and *how sure* (confidence).
+    """
+
+    reference: CodeReference
+    #: Dotted name of the enclosing function/method/class, or "<module>".
+    symbol: str
+    #: The old contract this matched, e.g. ``order["total"]``.
+    matched_contract: str
+    access: AccessKind
+    reason: str
+    confidence: Confidence
+    #: The exact source text the reference covers, e.g. ``"total"`` including
+    #: its quotes. Recorded at analysis time so planning can build a
+    #: replacement that preserves quote style without re-reading the file.
+    source_text: str = ""
+    #: True when a handler can mechanically rewrite this exact site.
+    patchable: bool = True
+    #: Set when ``patchable`` is False: why not.
+    unpatchable_reason: str = ""
+    #: True when the change document *asserted* what owns the renamed name and
+    #: this site belongs to something else -- `customer["total"]` for a rename
+    #: on `order`. Left alone on purpose, so not unfinished work.
+    other_object: bool = False
+
+    @property
+    def path(self) -> str:
+        return self.reference.path
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "reference": self.reference.to_dict(),
+            "symbol": self.symbol,
+            "matched_contract": self.matched_contract,
+            "access": self.access.value,
+            "reason": self.reason,
+            "confidence": self.confidence.value,
+            "source_text": self.source_text,
+            "patchable": self.patchable,
+            "unpatchable_reason": self.unpatchable_reason,
+            "other_object": self.other_object,
+        }
+
+
+@dataclass
+class ImpactGraph:
+    """The change -> symbol -> site -> function -> file -> test chain.
+
+    Not a graph database; a set of adjacency views over the findings, computed
+    once so reports and plans do not each re-derive them.
+    """
+
+    change_title: str
+    api_symbol: str
+    #: file path -> enclosing symbols affected in it
+    functions_by_file: dict[str, list[str]] = field(default_factory=dict)
+    #: file path -> test files believed relevant to it
+    tests_by_file: dict[str, list[str]] = field(default_factory=dict)
+
+    @classmethod
+    def build(
+        cls,
+        change: BreakingChange,
+        findings: list[ImpactFinding],
+        tests_by_file: dict[str, list[str]] | None = None,
+    ) -> ImpactGraph:
+        functions_by_file: dict[str, list[str]] = {}
+        for finding in findings:
+            bucket = functions_by_file.setdefault(finding.path, [])
+            if finding.symbol not in bucket:
+                bucket.append(finding.symbol)
+        return cls(
+            change_title=change.title,
+            api_symbol=change.target.symbol or change.title,
+            functions_by_file=functions_by_file,
+            tests_by_file=dict(tests_by_file or {}),
+        )
+
+    def render(self) -> str:
+        """An indented text rendering, used by ``patchahead analyze``."""
+        lines = [f"BreakingChange: {self.change_title}", f"  symbol: {self.api_symbol}"]
+        for path in sorted(self.functions_by_file):
+            lines.append(f"  file: {path}")
+            for symbol in self.functions_by_file[path]:
+                lines.append(f"    function: {symbol}")
+            for test in self.tests_by_file.get(path, []):
+                lines.append(f"    test: {test}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "change_title": self.change_title,
+            "api_symbol": self.api_symbol,
+            "functions_by_file": self.functions_by_file,
+            "tests_by_file": self.tests_by_file,
+        }
+
+
+@dataclass
+class ImpactReport:
+    """Everything analysis learned about one change against one repository."""
+
+    change: BreakingChange
+    findings: list[ImpactFinding] = field(default_factory=list)
+    graph: ImpactGraph | None = None
+    #: Test files judged relevant to the affected modules.
+    related_tests: list[str] = field(default_factory=list)
+    #: Number of Python files actually parsed (for timing/debug reporting).
+    files_scanned: int = 0
+    #: Files that could not be parsed, as ``path: reason``.
+    skipped_files: dict[str, str] = field(default_factory=dict)
+    analysis_ms: int = 0
+    #: Set when the handler declined to analyze at all.
+    unsupported_reason: str = ""
+
+    @property
+    def has_impact(self) -> bool:
+        return bool(self.findings)
+
+    @property
+    def affected_files(self) -> list[str]:
+        seen: list[str] = []
+        for finding in self.findings:
+            if finding.path not in seen:
+                seen.append(finding.path)
+        return seen
+
+    @property
+    def affected_symbols(self) -> list[str]:
+        seen: list[str] = []
+        for finding in self.findings:
+            if finding.symbol not in seen:
+                seen.append(finding.symbol)
+        return seen
+
+    def at_least(self, minimum: Confidence) -> list[ImpactFinding]:
+        """Findings meeting a confidence floor -- the patching threshold."""
+        return [f for f in self.findings if f.confidence >= minimum]
+
+    @property
+    def highest_confidence(self) -> Confidence | None:
+        if not self.findings:
+            return None
+        return max((f.confidence for f in self.findings), key=lambda c: c.rank)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "change": self.change.to_dict(),
+            "findings": [f.to_dict() for f in self.findings],
+            "graph": self.graph.to_dict() if self.graph else None,
+            "related_tests": self.related_tests,
+            "affected_files": self.affected_files,
+            "affected_symbols": self.affected_symbols,
+            "files_scanned": self.files_scanned,
+            "skipped_files": self.skipped_files,
+            "analysis_ms": self.analysis_ms,
+            "unsupported_reason": self.unsupported_reason,
+        }

patchahead/domain/patch.py

@@ -0,0 +1,81 @@
+"""Patch proposals: the new file contents a plan produces, plus a diff."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from patchahead.domain.plan import MigrationPlan
+
+
+@dataclass
+class FileEdit:
+    """The before and after contents of one file."""
+
+    path: str
+    old_source: str
+    new_source: str
+    #: Number of :class:`~patchahead.domain.plan.TextEdit` s applied.
+    edit_count: int = 0
+
+    @property
+    def changed(self) -> bool:
+        return self.old_source != self.new_source
+
+    def to_dict(self) -> dict[str, Any]:
+        # Source is deliberately excluded: run logs are for reading, and the
+        # diff already carries the content a reviewer needs.
+        return {"path": self.path, "edit_count": self.edit_count, "changed": self.changed}
+
+
+@dataclass
+class PatchProposal:
+    """A proposed, not-yet-validated set of file edits.
+
+    "Proposal" is the operative word: a :class:`PatchProposal` has passed no
+    gates. Only a :class:`~patchahead.domain.validation.ValidationResult` can
+    say whether it is any good.
+    """
+
+    plan: MigrationPlan
+    files: list[FileEdit] = field(default_factory=list)
+    #: Unified diff across every changed file.
+    diff: str = ""
+    #: "deterministic" or "llm".
+    engine: str = "deterministic"
+    explanation: str = ""
+    #: Set when generation failed; ``files`` is then empty.
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return not self.error and any(f.changed for f in self.files)
+
+    @property
+    def changed_files(self) -> list[str]:
+        return [f.path for f in self.files if f.changed]
+
+    @property
+    def edit_count(self) -> int:
+        return sum(f.edit_count for f in self.files)
+
+    @property
+    def diff_line_count(self) -> int:
+        """Added + removed lines, used by the diff-size validation gate."""
+        return sum(
+            1
+            for line in self.diff.splitlines()
+            if (line.startswith(("+", "-")) and not line.startswith(("+++", "---")))
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "engine": self.engine,
+            "explanation": self.explanation,
+            "error": self.error,
+            "files": [f.to_dict() for f in self.files],
+            "changed_files": self.changed_files,
+            "edit_count": self.edit_count,
+            "diff_line_count": self.diff_line_count,
+            "diff": self.diff,
+        }