breakscope 0.0.1__tar.gz

breakscope-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: pytest -q

breakscope-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

breakscope-0.0.1/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: breakscope
+Version: 0.0.1
+Summary: See what your API changes will break in your code.
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: syrupy>=4; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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
+```
+
+**Status:** pre-alpha. See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/ARCHITECTURE-v0.1.md](docs/ARCHITECTURE-v0.1.md).
+
+## License
+
+MIT

breakscope-0.0.1/README.md

@@ -0,0 +1,17 @@
+# 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
+```
+
+**Status:** pre-alpha. 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/__init__.py

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

breakscope-0.0.1/breakscope/__main__.py

@@ -0,0 +1,3 @@
+from breakscope.cli.main import app
+
+app()

breakscope-0.0.1/breakscope/cli/main.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from breakscope import __version__
+
+app = typer.Typer(
+    name="breakscope",
+    help="See what your API changes will break in your code.",
+    no_args_is_help=True,
+)
+
+
+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(exists=True, dir_okay=False, help="Old OpenAPI spec.")],
+    new: Annotated[Path, typer.Argument(exists=True, dir_okay=False, help="New OpenAPI spec.")],
+) -> None:
+    """Show contract changes between two OpenAPI specs."""
+    typer.echo("diff: coming in v0.1", err=True)
+    raise typer.Exit(2)
+
+
+@app.command()
+def analyze() -> None:
+    """Trace API changes into your codebase."""
+    typer.echo("analyze: coming in v0.4", err=True)
+    raise typer.Exit(2)

breakscope-0.0.1/docs/ARCHITECTURE-v0.1.md

@@ -0,0 +1,187 @@
+# v0.1 Architecture — Contract Diff
+
+v0.1 ships `breakscope diff` only. Its job is to fix the **internal change model** that code analysis (v0.2 onward) will consume. If this model is right, the analyzers never need to touch OpenAPI.
+
+## Pipeline
+
+```text
+old.yaml ─┐
+          ├─► loader ─► resolver ($ref) ─► normalizer ─► Contract ─┐
+new.yaml ─┘                                                        ├─► differ ─► list[APIChange] ─► reporter
+                                                           Contract┘
+```
+
+Each stage is a pure function with no I/O except in the loader, so every stage can be tested on its own.
+
+## Package layout (v0.1 only)
+
+```text
+breakscope/
+├── __init__.py            # __version__
+├── __main__.py            # python -m breakscope
+├── cli/
+│   └── main.py            # Typer app: diff (analyze/check are stubs that exit 2 with "coming in v0.4")
+├── contracts/
+│   ├── loader.py          # read file / git ref → dict; detect openapi version
+│   ├── resolver.py        # $ref resolution, cycle-safe, records origin component name
+│   ├── normalize.py       # dict → Contract (3.0 + 3.1 → one model)
+│   ├── model.py           # Contract, Operation, Parameter, Schema
+│   ├── diff.py            # Contract × Contract → list[APIChange]
+│   └── rules.py           # rule catalog: id, default severity, description
+├── changes.py             # APIChange, Severity, ChangeKind — the shared contract for everything downstream
+├── reports/
+│   ├── terminal.py        # rich
+│   └── json.py
+└── errors.py              # SpecLoadError, RefError, UnsupportedVersionError (human messages + hints)
+```
+
+`changes.py` sits at the top level on purpose. Analyzers and the impact engine depend on it, not on `contracts/`.
+
+## Core models
+
+```python
+# changes.py
+class Severity(StrEnum):
+    BREAKING = "breaking"
+    WARNING = "warning"        # e.g. enum value added to response (may break exhaustive switches)
+    INFO = "info"              # non-breaking additions
+
+class Direction(StrEnum):
+    REQUEST = "request"        # client sends it; tightening breaks clients
+    RESPONSE = "response"      # client reads it; loosening/removal breaks clients
+
+class APIChange(BaseModel, frozen=True):
+    rule: str                  # "response.property.removed"
+    severity: Severity
+    method: str | None         # "GET"; None for global/schema-only changes
+    path: str | None           # "/users/{id}"
+    direction: Direction | None
+    status_code: str | None    # "200", "default"
+    field_path: tuple[str, ...]  # ("items", "[]", "name"); "[]" = array element
+    schema_name: str | None    # "User" if the field came from components/schemas/User
+    old: Any | None
+    new: Any | None
+    message: str               # human-readable one-liner
+
+    @property
+    def key(self) -> str: ...  # stable id for snapshots/dedupe/ignore-lists
+
+    @property
+    def group_key(self) -> tuple[str, str | None, tuple[str, ...]]: ...  # (rule, schema_name, field_path)
+```
+
+`field_path` and `schema_name` are the two fields the impact engine will match code against (`user.name` ↔ `("name",)`, `User`). The resolver must keep `schema_name` when it inlines a `$ref`.
+
+```python
+# contracts/model.py
+class Schema(BaseModel):
+    types: frozenset[str]          # {"string"}, {"string","null"}; nullable folded in
+    properties: dict[str, "Schema"]
+    required: frozenset[str]
+    items: "Schema | None"
+    enum: tuple[Any, ...] | None
+    format: str | None
+    union: tuple["Schema", ...] | None   # oneOf/anyOf, compared opaquely in v0.1
+    ref_name: str | None
+    additional_properties: "bool | Schema"
+
+class Parameter(BaseModel):
+    name: str; location: Literal["path","query","header","cookie"]
+    required: bool; schema: Schema
+
+class Operation(BaseModel):
+    method: str; path: str; operation_id: str | None
+    parameters: dict[tuple[str, str], Parameter]   # (location, name)
+    request_body: dict[str, Schema]                # media type → schema
+    request_body_required: bool
+    responses: dict[str, dict[str, Schema]]        # status → media type → schema
+
+class Contract(BaseModel):
+    version: str
+    operations: dict[tuple[str, str], Operation]   # (METHOD, normalized_path)
+```
+
+**Path normalization:** `/users/{id}` and `/users/{userId}` are the same endpoint. The key replaces parameter names with `{}`, and the original path is kept for display.
+
+## Direction-aware rule catalog (v0.1)
+
+Breaking-ness depends on direction. Making a *response* field optional breaks readers. Making a *request* field required breaks writers.
+
+| Rule | Severity |
+|---|---|
+| `endpoint.removed` | breaking |
+| `endpoint.added` | info |
+| `parameter.removed` (path/query/header) | breaking |
+| `parameter.added.required` | breaking |
+| `parameter.added.optional` | info |
+| `parameter.became_required` | breaking |
+| `parameter.type.changed` | breaking |
+| `parameter.enum.value_removed` | breaking |
+| `request.body.added.required` | breaking |
+| `request.property.added.required` | breaking |
+| `request.property.became_required` | breaking |
+| `request.property.type.changed` | breaking |
+| `request.property.enum.value_removed` | breaking |
+| `request.property.removed` | warning (server may now reject or ignore it) |
+| `response.status.removed` (2xx) | breaking |
+| `response.media_type.removed` | breaking |
+| `response.property.removed` | breaking |
+| `response.property.became_optional` | warning |
+| `response.property.became_nullable` | breaking |
+| `response.property.type.changed` | breaking |
+| `response.property.format.changed` | warning |
+| `response.enum.value_added` | warning |
+| `response.enum.value_removed` | info |
+| `response.property.added` | info |
+| `schema.union.changed` | warning (opaque in v0.1) |
+
+The differ recurses through `properties` and `items` and builds up `field_path`. Each rule is a small function `(old, new, ctx) -> Iterable[APIChange]` registered in `rules.py`, so adding a rule never touches the walker.
+
+## Key decisions
+
+| Decision | Choice | Why |
+|---|---|---|
+| Spec parsing | PyYAML (`CSafeLoader`) + own resolver | We need `ref_name` provenance, which most resolvers throw away. `openapi-spec-validator` is only an optional `--validate` step. |
+| Models | Pydantic v2, frozen | Free JSON serialization for the JSON reporter, and hashable keys |
+| Recursive schemas | Resolver keeps a visited set and emits a `RecursiveRef(name)` sentinel. The differ compares sentinels by name. | Avoids infinite recursion on `Node.children: [Node]` |
+| Determinism | Changes are sorted by `(path, method, direction, field_path, rule)` | Stable snapshots and stable PR comments |
+| Errors | Each error has a message, a file and JSON pointer, and a hint | Developer tools live or die by their error messages |
+| Partial failure | One broken operation logs a warning and is skipped; the diff of the rest continues | Real specs are messy |
+| 3.2 | `UnsupportedVersionError`, with a hint that it is planned | Explicit beats silently wrong |
+
+## Shared schemas: one change, many endpoints
+
+Removing `User.name` when `User` is used by 8 operations must not print 8 unrelated changes. The differ still emits one `APIChange` per operation, because the impact engine needs the `(method, path)` of each one. Reporters then group changes by `(rule, schema_name, field_path)`:
+
+```text
+🔴 response.property.removed  User.name
+   affects 8 operations: GET /users/{id}, GET /users, GET /teams/{id}/members, …
+```
+
+`APIChange.group_key` makes this grouping explicit. JSON output contains both the flat list and the groups.
+
+## CLI surface (v0.1)
+
+```text
+breakscope diff OLD NEW [--format terminal|json] [--min-severity breaking|warning|info] [--output FILE]
+```
+
+- `OLD`/`NEW` accept paths now. `git:<ref>:<path>` comes in v0.5.
+- Exit codes: `0` no breaking changes, `1` breaking changes present, `2` error.
+
+## Testing strategy
+
+- `tests/contracts/rules/<rule_id>/{old,new}.yaml` holds one fixture per rule, auto-discovered by a parametrized test and snapshot-asserted
+- `tests/contracts/test_normalize.py` checks that equivalent 3.0 and 3.1 forms normalize to equal `Schema`s
+- `tests/contracts/corpus/` holds real-world specs, used only to assert "no crash, deterministic output"
+- Target ≥90% coverage on `contracts/` and `changes.py`
+
+## Dependencies
+
+Runtime: `typer`, `rich`, `pydantic>=2`, `pyyaml`.
+Dev: `pytest`, `syrupy`, `ruff`, `mypy`.
+`tree-sitter` is **not** a v0.1 dependency.
+
+## What v0.1 explicitly does not do
+
+Code scanning, git refs, config files, remote `$ref`, deep `oneOf`/`anyOf` comparison, OpenAPI 3.2, Swagger 2.0.

breakscope-0.0.1/docs/ROADMAP.md

@@ -0,0 +1,107 @@
+# BreakScope — Implementation Roadmap
+
+> Find the code that breaks before your API change reaches production.
+
+The diff engine is a prerequisite. What sets this tool apart is tracing each change to `file:line` with an honest confidence level. Every milestone below either builds toward that or ships it.
+
+Each milestone ends with a **demo gate**: one command, one fixture repo, and one expected output that is checked in as a snapshot test. A milestone is not done until its gate passes in CI.
+
+---
+
+## M0 — Skeleton (2–3 days)
+
+**Goal:** a package that installs and runs, with CI in place.
+
+- `pyproject.toml` (hatchling), Python 3.11+, package `breakscope`, entry point `breakscope`
+- Typer CLI with `--version` and stub `diff` / `analyze` commands
+- Tooling: ruff, mypy (strict, whole package), pytest, syrupy snapshots
+- GitHub Actions: lint, type-check and tests on 3.11 and 3.12, Linux and Windows
+- Name: **BreakScope** — PyPI `breakscope`, CLI `breakscope`, GitHub `breakscope` (PyPI name looked free in a search on 2026-10-06; the GitHub name is still unchecked. Register both before the first publish.)
+
+**Gate:** `pipx install .` then `breakscope --version` works on Windows and Linux.
+
+---
+
+## M1 — Contract diff, v0.1 (2–3 weeks)
+
+**Goal:** `breakscope diff old.yaml new.yaml` gives correct, stable output for OpenAPI 3.0 and 3.1.
+
+1. **Loader:** YAML/JSON, local `$ref` resolution (in-file and relative files), with cycle detection. Remote `$ref` is off by default.
+2. **Normalizer:** turn the spec into a flat, version-agnostic `Contract` model. Merge `nullable` (3.0) and `type: [x, "null"]` (3.1). Flatten `allOf`. Keep `oneOf`/`anyOf` as opaque unions for now.
+3. **Differ:** walk the operations and schemas and produce `APIChange` records (see the rule catalog in [ARCHITECTURE-v0.1.md](ARCHITECTURE-v0.1.md)).
+4. **Field paths:** every change carries a `field_path` such as `["name"]` or `["items", "[]", "status"]`. This path is the bridge to code analysis later, so get it right now.
+5. **Reporters:** terminal (rich) and JSON. The JSON schema is versioned (`"schema_version": 1`).
+6. **Exit codes:** `0` no breaking changes, `1` breaking changes found, `2` usage or parse error.
+7. **Tests:** at least 25 rule fixtures, each a minimal `old.yaml`/`new.yaml` pair with a snapshot. Also test against 3 real-world specs (for example the Petstore, GitHub and Stripe subsets) to catch crashes.
+
+**Gate:** `breakscope diff examples/demo/api/openapi-v1.yaml examples/demo/api/openapi-v2.yaml` reports `response.property.removed GET /users/{id} name`.
+
+**Ship v0.1.0 to PyPI.**
+
+---
+
+## M2 — Usage extraction, v0.2 (Python) + v0.3 (TS/JS) (3–4 weeks)
+
+**Goal:** find every API call site in a repo and say which endpoint it targets.
+
+- tree-sitter via `tree-sitter-language-pack` (prebuilt wheels, so no compiler is needed on Windows)
+- `Analyzer` protocol: `scan(file) -> list[CallSite]`
+- **TypeScript/JavaScript:** `fetch`, `axios.<verb>`, `axios({method, url})`, `<ident>.get|post|put|patch|delete(...)`. Handle template literals (`` `/users/${id}` ``) and string concatenation with a constant prefix.
+- **Python:** `requests.*`, `httpx.*` (sync and async client), `session.*`, `client.*`
+- **URL matcher:** turn literals and templates into path patterns and match them against the contract's path templates (`/users/${id}` → `/users/{id}`). Strip a configurable `base_url`.
+- Command: `breakscope usages` lists endpoint → call sites. This is useful on its own and is how M2 gets dogfooded.
+
+**Gate:** in `examples/demo`, `usages` finds both the TSX and the Python call sites of `GET /users/{id}`.
+
+---
+
+## M3 — Impact resolver, v0.4 (3–4 weeks) ← the product
+
+**Goal:** `breakscope analyze` connects changes to `file:line` with a confidence level.
+
+- **Intra-function data flow:** follow the response through `await`, `.data`, `.json()`, destructuring, and reassignment, then collect property accesses (`x.name`, `x["name"]`, `{ name } = x`, `x.get("name")`).
+- **Confidence tiers:**
+  - **HIGH:** the call site's URL matches the endpoint *and* the access is reached through data flow from that call
+  - **MEDIUM:** the access is on a variable typed or named after the schema (`User`, `user`), or comes through a single hop across a function return
+  - **LOW:** the property name and the schema name both appear in the file with no traced flow
+- Rule-based scoring (`severity × confidence`) that maps to a `risk` value of high, medium or low
+- Tests are labelled separately (`tests/`, `*.test.ts`, `test_*.py`), downranked, but still shown
+- Measure precision on the fixture corpus. Record a precision and recall table in `docs/accuracy.md` and **track it as a CI metric.**
+
+**Gate:** the demo from the pitch, `frontend/UserProfile.tsx:6 {user.name}` reported HIGH, comes out exactly as a snapshot.
+
+---
+
+## M4 — CI and GitHub Action, v0.5 → v1.0 (1–2 weeks)
+
+- `breakscope check --base origin/main`: reads the old spec through `git show <ref>:<path>`
+- `.breakscope.yml` config and `breakscope init`
+- Markdown reporter plus a composite GitHub Action that posts or updates a single PR comment
+- `--fail-on high|medium|low|never`
+- SARIF output, so results show up in GitHub code scanning (this costs little and adds a lot)
+
+**Ship v1.0:** README with a GIF, `examples/` (fastapi, express, react, mixed), and the Action on the Marketplace.
+
+---
+
+## M5 — Generated clients and migrations (after 1.0)
+
+- Generated-client mapping: parse `openapi-generator` and `openapi-typescript-codegen` output to map `UsersApi.getUserById` → `GET /users/{id}`
+- Rename detection: a removed property plus an added property of the same type and a similar name gives a `likely_renamed_to` hint
+- `breakscope fix --dry-run` writes a unified diff only. It never edits files.
+- `breakscope explain <METHOD path>`
+
+## Deliberately out of scope until after 1.0
+
+Dashboard, SaaS, accounts, GraphQL/gRPC/AsyncAPI, languages beyond Python/TS/JS, IDE extension, cross-file inter-procedural analysis beyond one hop.
+
+---
+
+## Risks to watch
+
+| Risk | Mitigation |
+|---|---|
+| False positives destroy trust | Confidence tiers. LOW is hidden by default. Track precision in CI. |
+| Custom HTTP wrappers hide URLs | Config `clients: [{ name: "api", base_url: "/v1" }]`, then generated-client support |
+| `$ref`/`allOf` edge cases crash the diff | Real-world spec corpus in tests. Fail per-operation, not globally. |
+| Scope creep into a better diff tool | Diff rule catalog is frozen at about 25 rules for 1.0. Effort goes into the resolver. |

breakscope-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "breakscope"
+dynamic = ["version"]
+description = "See what your API changes will break in your code."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["typer>=0.12", "rich>=13", "pydantic>=2", "pyyaml>=6"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "syrupy>=4", "ruff>=0.6", "mypy>=1.11", "types-PyYAML"]
+
+[project.scripts]
+breakscope = "breakscope.cli.main:app"
+
+[tool.hatch.version]
+path = "breakscope/__init__.py"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["breakscope"]

breakscope-0.0.1/recoverycode.md

@@ -0,0 +1,9 @@
+PyPI recovery codes
+e1df80f727ecd59c
+9fe858e62d69b605
+9fb2c174950c9285
+95a927d08905c0af
+875444e0a46ceae5
+85524ca88f5a0c4d
+7b41ad842f0d1268
+5b42057cbe24c039

breakscope-0.0.1/tests/test_cli.py

@@ -0,0 +1,16 @@
+from typer.testing import CliRunner
+
+from breakscope import __version__
+from breakscope.cli.main import app
+
+runner = CliRunner()
+
+
+def test_version() -> None:
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+    assert __version__ in result.output
+
+
+def test_analyze_stub_exits_2() -> None:
+    assert runner.invoke(app, ["analyze"]).exit_code == 2