patchahead 0.3.0__py3-none-any.whl

patchahead/domain/plan.py

@@ -0,0 +1,170 @@
+"""Migration planning: deciding *how* to fix what analysis found.
+
+Finding the problem and deciding how to fix it are separate stages with separate
+outputs. A :class:`MigrationPlan` is produced, serialized, and inspectable
+*before* any source file is touched -- ``patchahead migrate --dry-run`` stops
+exactly here.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+from patchahead.domain.change import BreakingChange, Confidence
+from patchahead.domain.impact import CodeReference
+
+
+class Risk(str, enum.Enum):
+    """How risky applying this plan is, independent of the change's severity.
+
+    Severity says "how bad if we do nothing". Risk says "how bad if we do this".
+    A HIGH-severity change can have a LOW-risk migration (a scoped rename), and
+    that distinction is what a reviewer actually needs.
+    """
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass(frozen=True)
+class TextEdit:
+    """A replacement of one source range with new text.
+
+    The unit of patching. Editing ranges rather than regenerating files is what
+    keeps diffs minimal and leaves comments, blank lines, and formatting outside
+    the edited span exactly as the author wrote them.
+
+    Coordinates follow ``ast``: ``line`` is 1-indexed, columns are 0-indexed
+    into the line, and ``end_col`` is exclusive.
+    """
+
+    line: int
+    col: int
+    end_line: int
+    end_col: int
+    new_text: str
+    #: What this edit accomplishes, shown in the plan.
+    description: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "line": self.line,
+            "col": self.col,
+            "end_line": self.end_line,
+            "end_col": self.end_col,
+            "new_text": self.new_text,
+            "description": self.description,
+        }
+
+
+@dataclass
+class Transformation:
+    """One concrete edit the plan intends to make, with its provenance.
+
+    Carries both the human-readable ``old``/``new`` (for the plan a person
+    reads) and the machine-applicable ``edit`` (for the patcher).
+    """
+
+    reference: CodeReference
+    old: str
+    new: str
+    edit: TextEdit
+    #: The enclosing function/method this edit lands in.
+    symbol: str = ""
+    confidence: Confidence = Confidence.MEDIUM
+
+    @property
+    def path(self) -> str:
+        return self.reference.path
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "reference": self.reference.to_dict(),
+            "old": self.old,
+            "new": self.new,
+            "symbol": self.symbol,
+            "confidence": self.confidence.value,
+            "edit": self.edit.to_dict(),
+        }
+
+
+@dataclass
+class MigrationPlan:
+    """What will be changed, where, why, and what should verify it.
+
+    Serializable and inspectable by design: ``patchahead migrate --dry-run
+    --json`` emits exactly this, and a reviewer can read it without trusting
+    that the patcher did what the plan says.
+    """
+
+    change: BreakingChange
+    #: The handler that produced this plan, e.g. "field_rename".
+    handler: str
+    transformations: list[Transformation] = field(default_factory=list)
+    #: Tests that should exercise the migrated behavior.
+    expected_tests: list[str] = field(default_factory=list)
+    risk: Risk = Risk.MEDIUM
+    #: One-paragraph explanation of the strategy, shown in reports.
+    rationale: str = ""
+    #: Sites analysis found but the plan deliberately leaves alone.
+    skipped: list[str] = field(default_factory=list)
+    #: Set when the handler could not produce a plan at all.
+    blocked_reason: str = ""
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.transformations
+
+    @property
+    def target_files(self) -> list[str]:
+        seen: list[str] = []
+        for transformation in self.transformations:
+            if transformation.path not in seen:
+                seen.append(transformation.path)
+        return seen
+
+    def edits_for(self, path: str) -> list[TextEdit]:
+        return [t.edit for t in self.transformations if t.path == path]
+
+    def render(self) -> str:
+        """The compact text rendering used by the CLI."""
+        lines = [
+            "MigrationPlan",
+            f"- change_kind: {self.change.kind.value}",
+            f"- handler: {self.handler}",
+            f"- risk: {self.risk.value.upper()}",
+        ]
+        for path in self.target_files:
+            lines.append(f"- target_file: {path}")
+            for transformation in self.transformations:
+                if transformation.path != path:
+                    continue
+                where = f"{transformation.symbol}:{transformation.reference.line}"
+                lines.append(f"    - {where}")
+                lines.append(f"        old: {transformation.old}")
+                lines.append(f"        new: {transformation.new}")
+        if self.expected_tests:
+            lines.append("- expected_tests:")
+            lines.extend(f"    {test}" for test in self.expected_tests)
+        if self.skipped:
+            lines.append("- skipped (not patched):")
+            lines.extend(f"    {item}" for item in self.skipped)
+        if self.blocked_reason:
+            lines.append(f"- blocked: {self.blocked_reason}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "change": self.change.to_dict(),
+            "handler": self.handler,
+            "risk": self.risk.value,
+            "rationale": self.rationale,
+            "transformations": [t.to_dict() for t in self.transformations],
+            "target_files": self.target_files,
+            "expected_tests": self.expected_tests,
+            "skipped": self.skipped,
+            "blocked_reason": self.blocked_reason,
+        }

patchahead/domain/result.py

@@ -0,0 +1,210 @@
+"""Top-level results returned by the engine to the CLI, the web UI, and tests."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+from patchahead.domain.completeness import CompletenessReport
+from patchahead.domain.impact import ImpactReport
+from patchahead.domain.patch import PatchProposal
+from patchahead.domain.plan import MigrationPlan
+from patchahead.domain.validation import TestRun, ValidationResult
+
+
+class Outcome(str, enum.Enum):
+    """Why a migration run ended the way it did.
+
+    Distinguishing these is the whole point: "we could not find anything to
+    change", "we refused to try", and "we tried and the tests failed" are three
+    very different messages to a user, and the prototype reported all of them as
+    the same boolean.
+    """
+
+    #: Patch generated and every gate passed.
+    MIGRATED = "migrated"
+    #: Patch generated, at least one gate failed. Diff is still available.
+    VALIDATION_FAILED = "validation_failed"
+    #: Patch generated and no gate objected, but no test gate ran -- so nothing
+    #: verified it. Produced by `--no-tests`, or a repository with no tests.
+    PATCHED_UNVERIFIED = "patched_unverified"
+    #: Analysis found nothing to change. Not an error.
+    NO_IMPACT = "no_impact"
+    #: The change kind has no handler in this version.
+    UNSUPPORTED_CHANGE = "unsupported_change"
+    #: A handler matched but declined to patch (e.g. unrecognized code shape).
+    NOT_PLANNABLE = "not_plannable"
+    #: Planning succeeded but patch generation failed.
+    PATCH_FAILED = "patch_failed"
+    #: ``--dry-run``: stopped after planning by request.
+    DRY_RUN = "dry_run"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass
+class AnalysisResult:
+    """What ``patchahead analyze`` returns."""
+
+    repo: str
+    change_document: str
+    reports: list[ImpactReport] = field(default_factory=list)
+    #: Wall-clock timings per stage, in milliseconds.
+    timings: dict[str, int] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def has_impact(self) -> bool:
+        return any(r.has_impact for r in self.reports)
+
+    @property
+    def total_findings(self) -> int:
+        return sum(len(r.findings) for r in self.reports)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repo": self.repo,
+            "change_document": self.change_document,
+            "has_impact": self.has_impact,
+            "total_findings": self.total_findings,
+            "reports": [r.to_dict() for r in self.reports],
+            "timings": self.timings,
+            "warnings": self.warnings,
+        }
+
+
+@dataclass
+class MigrationResult:
+    """What ``patchahead migrate`` returns, for one breaking change."""
+
+    outcome: Outcome
+    impact: ImpactReport
+    plan: MigrationPlan | None = None
+    proposal: PatchProposal | None = None
+    validation: ValidationResult | None = None
+    #: Test state before patching, used by the migration-assertion gate.
+    baseline_tests: TestRun | None = None
+    #: Absolute path of the isolated workspace, when it was kept.
+    workspace_path: str = ""
+    #: Paths of artifacts written to the output directory.
+    artifacts: dict[str, str] = field(default_factory=dict)
+    #: Human-readable explanation of the outcome. Always populated.
+    message: str = ""
+    timings: dict[str, int] = field(default_factory=dict)
+    #: What is left of the old API in the patched copy. Set only when a patch
+    #: was produced and validated.
+    completeness: CompletenessReport | None = None
+
+    @property
+    def succeeded(self) -> bool:
+        """A migration succeeded only if the tests verified it. No other path."""
+        return self.outcome is Outcome.MIGRATED and bool(
+            self.validation and self.validation.verified
+        )
+
+    @property
+    def diff(self) -> str:
+        return self.proposal.diff if self.proposal else ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "outcome": self.outcome.value,
+            "succeeded": self.succeeded,
+            "message": self.message,
+            "impact": self.impact.to_dict(),
+            "plan": self.plan.to_dict() if self.plan else None,
+            "proposal": self.proposal.to_dict() if self.proposal else None,
+            "validation": self.validation.to_dict() if self.validation else None,
+            "baseline_tests": self.baseline_tests.to_dict() if self.baseline_tests else None,
+            "completeness": self.completeness.to_dict() if self.completeness else None,
+            "workspace_path": self.workspace_path,
+            "artifacts": self.artifacts,
+            "timings": self.timings,
+        }
+
+
+@dataclass
+class MigrationRun:
+    """All migration results for one change document against one repository."""
+
+    repo: str
+    change_document: str
+    results: list[MigrationResult] = field(default_factory=list)
+    #: The verdict on the combined result of every change in the document. All
+    #: changes are patched into one workspace and validated together, because
+    #: changes in one release note are frequently interdependent.
+    validation: ValidationResult | None = None
+    warnings: list[str] = field(default_factory=list)
+    #: One unified diff of every change the run patched, against the original
+    #: repository -- the patch a reviewer would apply. Empty when nothing was
+    #: patched.
+    diff: str = ""
+
+    @property
+    def actionable_results(self) -> list[MigrationResult]:
+        """Results for changes that had work to do.
+
+        A change with no downstream impact, or one this version cannot migrate,
+        is not a failure -- but it is also not a migration, so it does not count
+        toward (or against) the run's success.
+        """
+        return [
+            result
+            for result in self.results
+            if result.outcome not in (Outcome.NO_IMPACT, Outcome.UNSUPPORTED_CHANGE)
+        ]
+
+    @property
+    def succeeded(self) -> bool:
+        """True when there was work to do and all of it passed validation."""
+        actionable = self.actionable_results
+        return bool(actionable) and all(result.succeeded for result in actionable)
+
+    @property
+    def complete(self) -> bool:
+        """No patched change left code, a dynamic access, or a test on its old name."""
+        return all(r.completeness.complete for r in self.results if r.completeness)
+
+    @property
+    def outcome(self) -> Outcome | None:
+        """The run's verdict in one word, for a CI step or a badge.
+
+        `migrated` only when :attr:`succeeded`. Otherwise the result that most
+        needs a reader's attention: a failed check outranks a refusal, which
+        outranks an unverified patch, which outranks "nothing to do".
+        """
+        if self.succeeded:
+            return Outcome.MIGRATED
+        present = {result.outcome for result in self.results}
+        for outcome in _ATTENTION_ORDER:
+            if outcome in present:
+                return outcome
+        return None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repo": self.repo,
+            "change_document": self.change_document,
+            "succeeded": self.succeeded,
+            "complete": self.complete,
+            "outcome": self.outcome.value if self.outcome else None,
+            "validation": self.validation.to_dict() if self.validation else None,
+            "results": [r.to_dict() for r in self.results],
+            "warnings": self.warnings,
+            "diff": self.diff,
+        }
+
+
+#: Most to least in need of attention; see :attr:`MigrationRun.outcome`.
+_ATTENTION_ORDER = (
+    Outcome.VALIDATION_FAILED,
+    Outcome.PATCH_FAILED,
+    Outcome.NOT_PLANNABLE,
+    Outcome.PATCHED_UNVERIFIED,
+    Outcome.MIGRATED,
+    Outcome.DRY_RUN,
+    Outcome.UNSUPPORTED_CHANGE,
+    Outcome.NO_IMPACT,
+)

patchahead/domain/validation.py

@@ -0,0 +1,200 @@
+"""Validation results: the gates a proposal must pass to be called a migration.
+
+Two properties, and the difference between them is the point.
+:attr:`ValidationResult.passed` is true when no gate failed and at least one
+actually ran -- necessary, and not sufficient.
+:attr:`ValidationResult.verified` additionally requires the
+``migration_assertion`` gate to have *passed*, meaning a test that failed before
+the patch passes after it.
+
+:attr:`~patchahead.domain.result.MigrationResult.succeeded` is defined in terms
+of ``verified``, not ``passed``: a run where every gate was happy but nothing
+demonstrated the break was fixed reports ``patched_unverified``, which is not a
+success. Nothing else in the codebase is permitted to decide that a migration
+worked.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class GateName(str, enum.Enum):
+    """The five gates, in the order they run.
+
+    Cheap and decisive gates run first so an unsafe proposal never reaches the
+    stage that executes repository code.
+    """
+
+    SYNTAX = "syntax"
+    SCOPE = "scope"
+    TARGETED_TESTS = "targeted_tests"
+    REGRESSION_TESTS = "regression_tests"
+    MIGRATION_ASSERTION = "migration_assertion"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+class GateStatus(str, enum.Enum):
+    PASSED = "passed"
+    FAILED = "failed"
+    #: Not run, for a stated reason (e.g. no tests found, ``--no-tests``).
+    SKIPPED = "skipped"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass
+class TestRun:
+    """The structured result of executing a test command."""
+
+    #: Tells pytest not to try to collect this as a test class. It is a domain
+    #: object whose name happens to start with "Test".
+    __test__ = False
+
+    command: str
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+    failing_tests: list[str] = field(default_factory=list)
+    summary: str = ""
+    duration_ms: int = 0
+    #: True when the command could not be run at all (not found, timed out).
+    errored: bool = False
+
+    @property
+    def passed(self) -> bool:
+        return self.returncode == 0 and not self.errored
+
+    def to_dict(self, *, tail: int = 2000) -> dict[str, Any]:
+        return {
+            "command": self.command,
+            "returncode": self.returncode,
+            "passed": self.passed,
+            "errored": self.errored,
+            "failing_tests": self.failing_tests,
+            "summary": self.summary,
+            "duration_ms": self.duration_ms,
+            "stdout_tail": self.stdout[-tail:],
+            "stderr_tail": self.stderr[-tail:],
+        }
+
+
+@dataclass
+class GateResult:
+    """One gate's verdict, with the detail needed to debug a failure."""
+
+    name: GateName
+    status: GateStatus
+    #: One line explaining the verdict. Always populated.
+    detail: str
+    duration_ms: int = 0
+    test_run: TestRun | None = None
+
+    @property
+    def passed(self) -> bool:
+        return self.status is GateStatus.PASSED
+
+    @property
+    def failed(self) -> bool:
+        return self.status is GateStatus.FAILED
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name.value,
+            "status": self.status.value,
+            "detail": self.detail,
+            "duration_ms": self.duration_ms,
+            "test_run": self.test_run.to_dict() if self.test_run else None,
+        }
+
+
+@dataclass
+class ValidationResult:
+    """The verdict on a patch proposal: every gate, in order, with reasons."""
+
+    gates: list[GateResult] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        """True only if no gate failed and at least one gate actually ran.
+
+        An all-skipped result is not a pass. Refusing to check something is not
+        evidence that it is correct.
+        """
+        if not self.gates:
+            return False
+        if any(g.failed for g in self.gates):
+            return False
+        return any(g.passed for g in self.gates)
+
+    @property
+    def verified(self) -> bool:
+        """Passed *and* the tests proved the break was fixed.
+
+        Distinct from :attr:`passed` because "no gate objected" and "the tests
+        confirmed it" are different claims. Verification requires the
+        migration-assertion gate to have *passed*, which means a test that
+        failed before the patch passes after it.
+
+        Everything short of that is a patch without evidence:
+
+        =========================  ===========================================
+        Situation                  Assertion gate
+        =========================  ===========================================
+        red before, green after    PASSED  -> verified
+        green before, green after  SKIPPED -> the tests do not cover the change
+        red before, still red      SKIPPED -> nothing was repaired to point at
+        no runnable tests          SKIPPED -> nothing ran
+        a test this patch broke    the regression gate FAILS first
+        =========================  ===========================================
+
+        Verification requires affirmative evidence, never merely the absence of
+        a regression -- which is why every row but the first lands short of it.
+        """
+        assertion = self.get(GateName.MIGRATION_ASSERTION)
+        return self.passed and assertion is not None and assertion.passed
+
+    @property
+    def tests_ran(self) -> bool:
+        return any(
+            gate.name in (GateName.TARGETED_TESTS, GateName.REGRESSION_TESTS)
+            and gate.status is not GateStatus.SKIPPED
+            for gate in self.gates
+        )
+
+    @property
+    def failed_gates(self) -> list[GateResult]:
+        return [g for g in self.gates if g.failed]
+
+    @property
+    def skipped_gates(self) -> list[GateResult]:
+        return [g for g in self.gates if g.status is GateStatus.SKIPPED]
+
+    def get(self, name: GateName) -> GateResult | None:
+        for gate in self.gates:
+            if gate.name is name:
+                return gate
+        return None
+
+    def summary(self) -> str:
+        if not self.gates:
+            return "no gates ran"
+        if self.passed:
+            skipped = len(self.skipped_gates)
+            tail = f" ({skipped} skipped)" if skipped else ""
+            return f"{len(self.gates) - skipped}/{len(self.gates)} gates passed{tail}"
+        first = self.failed_gates[0]
+        return f"gate `{first.name.value}` failed: {first.detail}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "passed": self.passed,
+            "verified": self.verified,
+            "summary": self.summary(),
+            "gates": [g.to_dict() for g in self.gates],
+        }