patchahead 0.3.0__py3-none-any.whl

patchahead/demo/fixtures/orders-service/README.md

@@ -0,0 +1,51 @@
+# orders-service (PatchAhead example repository)
+
+A small, self-contained Python service that integrates with a third-party
+**Orders API**. It exists so you can run PatchAhead against a *separate*
+repository without writing one first.
+
+This repo is **intentionally broken**. The vendored upstream client in
+`upstream/` is the new (v2) version of the Orders API; the integration code in
+`app/` is still written against the old (v1) contract. So:
+
+```console
+$ cd "$(patchahead demo --print-paths | awk '/^repository/ {print $2}')"
+$ python -m pytest
+...
+FAILED tests/test_order_sync.py::test_sync_all_orders - KeyError: 'total_pages'
+FAILED tests/test_order_report.py::test_total_revenue - KeyError: 'total'
+FAILED tests/test_client.py::test_fetch_recent - TypeError: ... 'timeout_seconds'
+3 failed
+```
+
+That is the situation PatchAhead is for. Each failure corresponds to one
+breaking change described in `../changes/`:
+
+| Change document | Breaking change | Breaks |
+|---|---|---|
+| `../changes/pagination-cursor.md` | page-based -> cursor-based pagination | `app/order_sync.py` |
+| `../changes/field-rename.md` | order field `total` -> `amount` | `app/order_report.py` |
+| `../changes/kwarg-rename.md` | `timeout_seconds=` -> `timeout=` | `app/client.py` |
+| `../changes/method-rename.md` | `fetch_orders()` -> `list_orders()` | `app/client.py` |
+| `../changes/pagination-cursor.json` | the same pagination change, as structured JSON | `app/order_sync.py` |
+| `../changes/sdk-v2.md` | both SDK changes in one release note | `app/client.py` |
+| `../changes/invoice-field-rename.md` | a rename on `invoice` objects — **nothing here** | nothing: it is refused |
+
+The easiest way to see all of this is `patchahead demo`, which serves these
+files through the UI with a short explanation of each scenario. To drive them
+from the command line instead, `patchahead demo --print-paths` prints where this
+directory and `../changes` landed in your installation:
+
+```bash
+repo=$(patchahead demo --print-paths | awk '/^repository/ {print $2}')
+changes=$(patchahead demo --print-paths | awk '/^changes/ {print $2}')
+
+patchahead analyze --repo "$repo" --change "$changes/pagination-cursor.md"
+patchahead migrate --repo "$repo" --change "$changes/pagination-cursor.md"
+```
+
+`migrate` copies this repo into a temporary workspace, patches the copy, runs the
+tests there, and prints a diff. This directory is left untouched.
+
+`upstream/api_v1.py` is kept only as documentation of the contract the `app/`
+code was originally written against. Nothing imports it.

patchahead/demo/fixtures/orders-service/app/client.py

@@ -0,0 +1,15 @@
+"""Thin wrapper over the upstream Orders API client.
+
+Written against the v1 SDK surface: ``fetch_orders(..., timeout_seconds=...)``.
+"""
+
+DEFAULT_TIMEOUT_SECONDS = 15.0
+
+
+def fetch_recent(api_client, limit=3):
+    return api_client.fetch_orders(limit=limit, timeout_seconds=DEFAULT_TIMEOUT_SECONDS)
+
+
+def fetch_one(api_client):
+    orders = api_client.fetch_orders(limit=1, timeout_seconds=5.0)
+    return orders[0] if orders else None

patchahead/demo/fixtures/orders-service/app/models.py

@@ -0,0 +1,10 @@
+"""Lightweight domain models for the downstream app."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Order:
+    id: int
+    customer: str
+    total: float

patchahead/demo/fixtures/orders-service/app/order_report.py

@@ -0,0 +1,24 @@
+"""Revenue reporting over synced orders.
+
+Reads each order's `total` field. Written against the v1 Orders schema.
+"""
+
+# Unrelated identifiers that merely contain the word "total". A correct
+# migration must not touch any of these.
+TOTAL_LABEL = "total"
+
+
+def total_revenue(orders):
+    return round(sum(order["total"] for order in orders), 2)
+
+
+def revenue_by_customer(orders):
+    totals = {}
+    for order in orders:
+        name = order["customer"]
+        totals[name] = round(totals.get(name, 0) + order["total"], 2)
+    return totals
+
+
+def format_summary(orders):
+    return f"{TOTAL_LABEL}: {total_revenue(orders)}"

patchahead/demo/fixtures/orders-service/app/order_sync.py

@@ -0,0 +1,21 @@
+"""Downstream order-sync integration.
+
+Syncs ALL orders from the upstream Orders API. Written against the v1
+(page-based) pagination contract.
+"""
+
+
+def sync_all_orders(api_client):
+    page = 1
+    all_orders = []
+
+    while True:
+        response = api_client.get_orders(page=page)
+        all_orders.extend(response["orders"])
+
+        if page >= response["total_pages"]:
+            break
+
+        page += 1
+
+    return all_orders

patchahead/demo/fixtures/orders-service/conftest.py

@@ -0,0 +1,6 @@
+"""Put this repository's own packages on sys.path for the tests."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

patchahead/demo/fixtures/orders-service/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "orders-service"
+version = "0.1.0"
+description = "Example downstream service for PatchAhead."
+requires-python = ">=3.10"
+
+[tool.patchahead]
+# PatchAhead reads this section. Everything here is optional; these values
+# happen to match what PatchAhead would infer anyway, and are written out so
+# the example doubles as documentation of the config format.
+source_dirs = ["app"]
+test_command = "python -m pytest"
+max_changed_files = 3
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

patchahead/demo/fixtures/orders-service/tests/test_client.py

@@ -0,0 +1,14 @@
+"""Integration test for the thin upstream client wrapper."""
+
+from app import client
+from upstream.api_v2 import OrdersAPIClient
+
+
+def test_fetch_recent():
+    orders = client.fetch_recent(OrdersAPIClient(), limit=2)
+
+    assert [o["id"] for o in orders] == [1, 2]
+
+
+def test_fetch_one():
+    assert client.fetch_one(OrdersAPIClient())["id"] == 1

patchahead/demo/fixtures/orders-service/tests/test_order_report.py

@@ -0,0 +1,24 @@
+"""Integration test for revenue reporting against the live upstream."""
+
+from app import order_report
+from upstream.api_v2 import OrdersAPIClient
+
+
+def _orders():
+    return OrdersAPIClient().get_orders(cursor=None)["orders"]
+
+
+def test_total_revenue():
+    assert order_report.total_revenue(_orders()) == 55.5
+
+
+def test_revenue_by_customer():
+    by_customer = order_report.revenue_by_customer(_orders())
+
+    assert by_customer == {"Ada": 42.0, "Linus": 13.5}
+
+
+def test_summary_label_is_not_a_data_field():
+    # `TOTAL_LABEL` is display text, not an API field. A migration that renames
+    # the `total` field must leave it alone.
+    assert order_report.TOTAL_LABEL == "total"

patchahead/demo/fixtures/orders-service/tests/test_order_sync.py

@@ -0,0 +1,11 @@
+"""Integration test for the downstream order-sync against the live upstream."""
+
+from app import order_sync
+from upstream.api_v2 import OrdersAPIClient
+
+
+def test_sync_all_orders():
+    orders = order_sync.sync_all_orders(OrdersAPIClient())
+
+    assert len(orders) == 6, f"expected 6 orders, got {len(orders)}"
+    assert sorted(o["id"] for o in orders) == [1, 2, 3, 4, 5, 6]

patchahead/demo/fixtures/orders-service/upstream/api_v1.py

@@ -0,0 +1,34 @@
+"""Vendored Orders API client -- v1.
+
+Kept purely as documentation of the contract `app/` was originally written
+against. Nothing imports this module; the service depends on ``api_v2``.
+"""
+
+_ORDERS = [
+    {"id": 1, "customer": "Ada", "total": 42.00},
+    {"id": 2, "customer": "Linus", "total": 13.50},
+    {"id": 3, "customer": "Grace", "total": 88.10},
+    {"id": 4, "customer": "Alan", "total": 27.75},
+    {"id": 5, "customer": "Edsger", "total": 64.20},
+    {"id": 6, "customer": "Margaret", "total": 9.99},
+]
+
+_PAGE_SIZE = 2
+
+
+class OrdersAPIClient:
+    """Page-based Orders API client (v1)."""
+
+    version = "v1"
+
+    def get_orders(self, page: int = 1, **_ignored):
+        total_pages = (len(_ORDERS) + _PAGE_SIZE - 1) // _PAGE_SIZE
+        start = (page - 1) * _PAGE_SIZE
+        return {
+            "orders": _ORDERS[start : start + _PAGE_SIZE],
+            "page": page,
+            "total_pages": total_pages,
+        }
+
+    def fetch_orders(self, limit=3, timeout_seconds=30.0):
+        return _ORDERS[:limit]

patchahead/demo/fixtures/orders-service/upstream/api_v2.py

@@ -0,0 +1,56 @@
+"""Vendored Orders API client -- v2 (the version this repo now depends on).
+
+BREAKING CHANGES vs v1, all of which the `app/` code has not been migrated to:
+
+1. Pagination moved from integer ``page`` + ``total_pages`` to opaque
+   ``cursor`` + ``next_cursor`` + ``has_more``. The ``page`` and
+   ``total_pages`` response fields are GONE.
+
+   ``get_orders`` still ACCEPTS a ``page`` kwarg, so old callers do not get a
+   loud ``TypeError`` -- they get something quieter and worse: a response with
+   no ``total_pages``, which raises ``KeyError`` and (in sloppier code) can
+   silently sync incomplete data.
+
+2. The order money field ``total`` was renamed to ``amount``.
+
+3. ``fetch_orders()`` was renamed to ``list_orders()``.
+
+4. The ``timeout_seconds=`` keyword argument was renamed to ``timeout=``.
+
+Fully in-memory and deterministic -- no network.
+"""
+
+_ORDERS = [
+    {"id": 1, "customer": "Ada", "amount": 42.00},
+    {"id": 2, "customer": "Linus", "amount": 13.50},
+    {"id": 3, "customer": "Grace", "amount": 88.10},
+    {"id": 4, "customer": "Alan", "amount": 27.75},
+    {"id": 5, "customer": "Edsger", "amount": 64.20},
+    {"id": 6, "customer": "Margaret", "amount": 9.99},
+]
+
+_PAGE_SIZE = 2
+# Opaque cursor -> start index into the dataset.
+_CURSOR_START = {None: 0, "c1": 2, "c2": 4}
+
+
+class OrdersAPIClient:
+    """Cursor-based Orders API client (v2)."""
+
+    version = "v2"
+
+    def get_orders(self, cursor=None, page=None, **_ignored):
+        start = _CURSOR_START.get(cursor, 0)
+        end = start + _PAGE_SIZE
+        chunk = _ORDERS[start:end]
+        has_more = end < len(_ORDERS)
+        next_cursor = None
+        if has_more:
+            next_cursor = "c1" if end == 2 else "c2"
+        return {"orders": chunk, "next_cursor": next_cursor, "has_more": has_more}
+
+    def list_orders(self, limit=3, timeout=30.0):
+        """v2 name for what v1 called ``fetch_orders(..., timeout_seconds=...)``."""
+        if not isinstance(timeout, (int, float)):
+            raise TypeError(f"timeout must be a number, got {timeout!r}")
+        return _ORDERS[:limit]

patchahead/demo/serve.py

@@ -0,0 +1,189 @@
+"""Starting the bundled demo: pick a port, print the URL, serve the UI.
+
+Everything here is about removing steps between ``pip install`` and seeing the
+product work. It contains no migration logic and no second execution path -- it
+builds the same FastAPI app :mod:`patchahead.web.server` builds for any
+repository, hands it the bundled fixtures, and runs it on the loopback
+interface.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import os
+import socket
+import sys
+import threading
+import webbrowser
+from pathlib import Path
+
+from patchahead import __version__
+from patchahead.demo import DemoError, changes_root, repo_root, scenarios
+
+log = logging.getLogger("patchahead.demo")
+
+DEFAULT_PORT = 8000
+#: How far to look for a free port before giving up. Twenty is enough to get
+#: past a handful of other dev servers and small enough to fail quickly.
+PORT_SEARCH_RANGE = 20
+HOST = "127.0.0.1"
+
+
+def port_is_free(port: int, host: str = HOST) -> bool:
+    """Whether a server could bind this port right now.
+
+    Asks the only question that matters -- "can I bind?" -- rather than probing
+    for a listener, because a port can be unbindable for reasons other than
+    something serving on it.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        try:
+            probe.bind((host, port))
+        except OSError:
+            return False
+    return True
+
+
+def choose_port(preferred: int = DEFAULT_PORT, *, explicit: bool = False) -> int:
+    """Return a bindable port, or explain why there is not one.
+
+    When the user named a port, an occupied one is an error: silently serving
+    somewhere else would send them to a URL they did not ask for, and in the
+    worst case to a *different* server that is already there. When the port is
+    just our default, moving on is the friendlier behaviour and is announced.
+    """
+    if port_is_free(preferred):
+        return preferred
+    if explicit:
+        raise DemoError(
+            f"port {preferred} is already in use. Pass a different --port, or stop "
+            f"whatever is listening on {HOST}:{preferred}."
+        )
+    for candidate in range(preferred + 1, preferred + 1 + PORT_SEARCH_RANGE):
+        if port_is_free(candidate):
+            log.info("port %d was busy; using %d instead", preferred, candidate)
+            return candidate
+    raise DemoError(
+        f"ports {preferred}-{preferred + PORT_SEARCH_RANGE} are all in use. "
+        f"Free one, or pass --port."
+    )
+
+
+def browser_is_practical() -> bool:
+    """Whether opening a browser would do something useful.
+
+    On a headless machine -- a container, a CI runner, an SSH session --
+    ``webbrowser.open`` can launch a terminal browser over the top of the
+    output, which is worse than doing nothing. The URL is always printed, so
+    declining here costs the user one click.
+    """
+    if os.environ.get("PATCHAHEAD_NO_BROWSER"):
+        return False
+    if sys.platform in ("darwin", "win32"):
+        return True
+    if not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")):
+        return False
+    try:
+        webbrowser.get()
+    except webbrowser.Error:
+        return False
+    return True
+
+
+def _open_later(url: str, delay: float = 1.0) -> None:
+    """Open the browser once the server has had a moment to start listening."""
+
+    def _open() -> None:
+        try:
+            webbrowser.open(url)
+        except Exception as exc:  # pragma: no cover - platform dependent
+            log.debug("could not open a browser: %s", exc)
+
+    timer = threading.Timer(delay, _open)
+    timer.daemon = True
+    timer.start()
+
+
+def test_runner_available() -> bool:
+    """Whether the bundled repository's test command can actually run.
+
+    The demo's whole point is the difference between "patched" and "verified",
+    and verification needs a test runner. Without pytest every scenario reports,
+    honestly and uselessly, that the test command could not start -- so this is
+    checked up front and the fix is printed, rather than leaving the viewer to
+    conclude the tool is broken.
+    """
+    return importlib.util.find_spec("pytest") is not None
+
+
+def banner(url: str, repo: Path, test_command: str, *, can_run_tests: bool = True) -> str:
+    """The text printed before the server takes over the terminal."""
+    lines = [
+        "",
+        f"  PatchAhead {__version__} — demo",
+        "",
+        f"  Open   {url}",
+        "",
+        f"  Repository   {repo}",
+        f"  Scenarios    {len(scenarios())} bundled, including one PatchAhead refuses",
+        "",
+        "  This is the real engine. Migrating copies the bundled repository to a",
+        f"  temporary directory, patches the copy, and runs `{test_command}` there.",
+        "  The bundled repository is never modified. Serving on localhost only.",
+        "",
+        "  Ctrl-C to stop.",
+        "",
+    ]
+    if not can_run_tests:
+        lines[-1:] = [
+            "  WARNING: pytest is not installed, so no scenario can be verified.",
+            "  Every run will report that the test command could not start.",
+            "  Fix:  pip install 'patchahead[demo]'",
+            "",
+        ]
+    return "\n".join(lines)
+
+
+def serve(
+    port: int = DEFAULT_PORT,
+    *,
+    port_was_explicit: bool = False,
+    open_browser: bool = True,
+    scenario: str = "",
+) -> int:
+    """Run the demo server until interrupted. Returns a process exit code."""
+    from patchahead.config import load as load_config
+    from patchahead.web.server import create_app
+
+    repo = repo_root()
+    changes = changes_root()
+
+    try:
+        import uvicorn
+    except ImportError:
+        log.error(
+            "the demo needs its extra dependencies: pip install 'patchahead[demo]' "
+            "(FastAPI, uvicorn, and the pytest that verifies the migrations)"
+        )
+        return 2
+
+    chosen = choose_port(port, explicit=port_was_explicit)
+    app = create_app(repo, changes, scenarios())
+    url = f"http://{HOST}:{chosen}"
+    if scenario:
+        url = f"{url}/?scenario={scenario}"
+
+    print(
+        banner(
+            url,
+            repo,
+            load_config(repo).test_command,
+            can_run_tests=test_runner_available(),
+        )
+    )
+    if open_browser and browser_is_practical():
+        _open_later(url)
+
+    uvicorn.run(app, host=HOST, port=chosen, log_level="warning")
+    return 0

patchahead/domain/__init__.py

@@ -0,0 +1,67 @@
+"""The PatchAhead domain model.
+
+Everything that crosses a stage boundary is one of these objects. No stage
+passes a loosely-structured dict to another stage.
+"""
+
+from patchahead.domain.change import (
+    BreakingChange,
+    ChangeKind,
+    Confidence,
+    Evidence,
+    PaginationContract,
+    Severity,
+    SymbolTarget,
+)
+from patchahead.domain.impact import (
+    AccessKind,
+    CodeReference,
+    ImpactFinding,
+    ImpactGraph,
+    ImpactReport,
+)
+from patchahead.domain.patch import FileEdit, PatchProposal
+from patchahead.domain.plan import MigrationPlan, Risk, TextEdit, Transformation
+from patchahead.domain.result import (
+    AnalysisResult,
+    MigrationResult,
+    MigrationRun,
+    Outcome,
+)
+from patchahead.domain.validation import (
+    GateName,
+    GateResult,
+    GateStatus,
+    TestRun,
+    ValidationResult,
+)
+
+__all__ = [
+    "AccessKind",
+    "AnalysisResult",
+    "BreakingChange",
+    "ChangeKind",
+    "CodeReference",
+    "Confidence",
+    "Evidence",
+    "FileEdit",
+    "GateName",
+    "GateResult",
+    "GateStatus",
+    "ImpactFinding",
+    "ImpactGraph",
+    "ImpactReport",
+    "MigrationPlan",
+    "MigrationResult",
+    "MigrationRun",
+    "Outcome",
+    "PaginationContract",
+    "PatchProposal",
+    "Risk",
+    "Severity",
+    "SymbolTarget",
+    "TestRun",
+    "TextEdit",
+    "Transformation",
+    "ValidationResult",
+]