breakscope 0.0.1__tar.gz → 0.1.0__tar.gz

breakscope-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag matches package version
+        run: |
+          version=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('breakscope/__init__.py').read()).group(1))")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match breakscope/__init__.py version $version"
+            exit 1
+          fi
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

{breakscope-0.0.1 → breakscope-0.1.0}/.gitignore

@@ -6,3 +6,4 @@ build/
 .mypy_cache/
 .ruff_cache/
 .pytest_cache/
+recoverycode.md

{breakscope-0.0.1 → breakscope-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: breakscope
-Version: 0.0.1
+Version: 0.1.0
 Summary: See what your API changes will break in your code.
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -28,7 +28,25 @@ pip install breakscope
 breakscope diff openapi-old.yaml openapi-new.yaml
 ```
 
-**Status:** pre-alpha. See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/ARCHITECTURE-v0.1.md](docs/ARCHITECTURE-v0.1.md).
+```text
+BREAKING CHANGES: 4
+
+🔴 response.property.removed  User.name
+   A response property was removed.
+   affects 3 operations:
+     GET /users -> 200
+     POST /users -> 201
+     GET /users/{userId} -> 200
+
+🔴 request.property.became_required  POST /users
+   [request] `email` is now required
+...
+```
+
+Try it on the demo: `breakscope diff examples/demo/api/openapi-v1.yaml examples/demo/api/openapi-v2.yaml`.
+Use `--format json` for machine-readable output. Exit codes: `0` no breaking changes, `1` breaking changes, `2` error.
+
+**Status:** v0.1: contract diff. Tracing changes into your code comes in v0.4. See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/ARCHITECTURE-v0.1.md](docs/ARCHITECTURE-v0.1.md).
 
 ## License
 

breakscope-0.1.0/README.md

@@ -0,0 +1,35 @@
+# BreakScope
+
+> **See what your API changes will break — before they reach production.**
+
+API contract changes are easy to detect. Knowing what they break isn't.
+BreakScope diffs your OpenAPI specs and traces each breaking change to the exact `file:line` in your Python and TypeScript code that's likely affected.
+
+```bash
+pip install breakscope
+breakscope diff openapi-old.yaml openapi-new.yaml
+```
+
+```text
+BREAKING CHANGES: 4
+
+🔴 response.property.removed  User.name
+   A response property was removed.
+   affects 3 operations:
+     GET /users -> 200
+     POST /users -> 201
+     GET /users/{userId} -> 200
+
+🔴 request.property.became_required  POST /users
+   [request] `email` is now required
+...
+```
+
+Try it on the demo: `breakscope diff examples/demo/api/openapi-v1.yaml examples/demo/api/openapi-v2.yaml`.
+Use `--format json` for machine-readable output. Exit codes: `0` no breaking changes, `1` breaking changes, `2` error.
+
+**Status:** v0.1: contract diff. Tracing changes into your code comes in v0.4. See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/ARCHITECTURE-v0.1.md](docs/ARCHITECTURE-v0.1.md).
+
+## License
+
+MIT

{breakscope-0.0.1 → breakscope-0.1.0}/breakscope/__init__.py

@@ -1,3 +1,3 @@
 """BreakScope: see what your API changes will break in your code."""
 
-__version__ = "0.0.1"
+__version__ = "0.1.0"

breakscope-0.1.0/breakscope/changes.py

@@ -0,0 +1,93 @@
+"""The change model shared by the diff engine, reporters and (later) the impact engine.
+
+Nothing in here knows about OpenAPI. Downstream code depends on this module only.
+"""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Severity(StrEnum):
+    BREAKING = "breaking"
+    WARNING = "warning"
+    INFO = "info"
+
+    @property
+    def rank(self) -> int:
+        return {"breaking": 0, "warning": 1, "info": 2}[self.value]
+
+
+class Direction(StrEnum):
+    REQUEST = "request"
+    RESPONSE = "response"
+
+
+class APIChange(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    rule: str
+    severity: Severity
+    method: str | None = None
+    path: str | None = None
+    direction: Direction | None = None
+    status_code: str | None = None
+    # Location of the field from the root of the request/response body (or parameter).
+    # "[]" marks an array element: ("items", "[]", "name").
+    field_path: tuple[str, ...] = ()
+    # Nearest named schema (components/schemas/<name>) that owns the field, and the
+    # field's path relative to it. User.name is ("name",) whether it was reached
+    # through GET /users/{id} or through GET /users -> "[]".
+    schema_name: str | None = None
+    schema_path: tuple[str, ...] = ()
+    old: Any = None
+    new: Any = None
+    message: str
+
+    @property
+    def key(self) -> str:
+        """Stable identifier for snapshots, dedupe and ignore lists."""
+        parts = [
+            self.rule,
+            self.method or "",
+            self.path or "",
+            self.status_code or "",
+            ".".join(self.field_path),
+        ]
+        return " ".join(p for p in parts if p)
+
+    @property
+    def group_key(self) -> tuple[str, ...]:
+        """Changes to one shared schema field group together across operations."""
+        if self.schema_name and self.schema_path:
+            return (self.rule, self.schema_name, *self.schema_path)
+        return (self.key,)
+
+    @property
+    def subject(self) -> str:
+        """Short human label for the changed thing: `User.name`, `email`, `items[].id`."""
+        if self.schema_name and self.schema_path:
+            return format_field_path((self.schema_name, *self.schema_path))
+        return format_field_path(self.field_path)
+
+    def sort_key(self) -> tuple[Any, ...]:
+        return (
+            self.severity.rank,
+            self.path or "",
+            self.method or "",
+            self.direction or "",
+            self.status_code or "",
+            self.field_path,
+            self.rule,
+        )
+
+
+def format_field_path(path: tuple[str, ...]) -> str:
+    out = ""
+    for part in path:
+        if part == "[]":
+            out += "[]"
+        else:
+            out += f".{part}" if out else part
+    return out

breakscope-0.1.0/breakscope/cli/main.py

@@ -0,0 +1,94 @@
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from breakscope import __version__
+from breakscope.changes import Severity
+from breakscope.contracts import diff_files
+from breakscope.errors import BreakScopeError
+from breakscope.reports import json as json_report
+from breakscope.reports import terminal
+
+app = typer.Typer(
+    name="breakscope",
+    help="See what your API changes will break in your code.",
+    no_args_is_help=True,
+)
+
+EXIT_OK, EXIT_BREAKING, EXIT_ERROR = 0, 1, 2
+
+
+class Format(StrEnum):
+    terminal = "terminal"
+    json = "json"
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"breakscope {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show version.")
+    ] = False,
+) -> None:
+    pass
+
+
+@app.command()
+def diff(
+    old: Annotated[Path, typer.Argument(help="Old OpenAPI spec (YAML or JSON).")],
+    new: Annotated[Path, typer.Argument(help="New OpenAPI spec (YAML or JSON).")],
+    fmt: Annotated[Format, typer.Option("--format", "-f", help="Output format.")] = Format.terminal,
+    min_severity: Annotated[
+        Severity, typer.Option("--min-severity", help="Hide changes below this severity.")
+    ] = Severity.WARNING,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Write the report to a file.")
+    ] = None,
+) -> None:
+    """Show contract changes between two OpenAPI specs.
+
+    Exit code 0: no breaking changes. 1: breaking changes found. 2: error.
+    """
+    err = Console(stderr=True)
+    try:
+        changes, a, b = diff_files(old, new)
+    except BreakScopeError as e:
+        err.print(e.render(), markup=False, highlight=False)
+        raise typer.Exit(EXIT_ERROR) from None
+
+    skipped = {
+        f"{m} {p} ({src})": reason
+        for contract, src in ((a, "old"), (b, "new"))
+        for (m, p), reason in contract.skipped.items()
+    }
+    shown = [c for c in changes if c.severity.rank <= min_severity.rank]
+
+    if fmt is Format.json:
+        text = json_report.render(shown, skipped=skipped)
+        if output:
+            output.write_text(text, encoding="utf-8")
+        else:
+            typer.echo(text, nl=False)
+    elif output:
+        with output.open("w", encoding="utf-8") as fh:
+            terminal.render(shown, Console(file=fh, width=100, no_color=True), skipped=skipped)
+    else:
+        terminal.render(shown, Console(highlight=False), skipped=skipped)
+
+    breaking = any(c.severity is Severity.BREAKING for c in changes)
+    raise typer.Exit(EXIT_BREAKING if breaking else EXIT_OK)
+
+
+@app.command()
+def analyze() -> None:
+    """Trace API changes into your codebase."""
+    typer.echo("analyze: coming in v0.4", err=True)
+    raise typer.Exit(EXIT_ERROR)

breakscope-0.1.0/breakscope/contracts/__init__.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from breakscope.changes import APIChange
+from breakscope.contracts.diff import diff_contracts
+from breakscope.contracts.loader import load_spec
+from breakscope.contracts.model import Contract
+from breakscope.contracts.normalize import normalize
+
+
+def load_contract(path: Path) -> Contract:
+    return normalize(load_spec(path))
+
+
+def diff_files(old: Path, new: Path) -> tuple[list[APIChange], Contract, Contract]:
+    a, b = load_contract(old), load_contract(new)
+    return diff_contracts(a, b), a, b
+
+
+__all__ = ["Contract", "diff_contracts", "diff_files", "load_contract"]