fastapi-breakgate 1.0.1__py3-none-any.whl

fastapi_contract/export.py

@@ -0,0 +1,283 @@
+"""Reliable FastAPI OpenAPI export with live / factory / snapshot ladder."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from fastapi_contract.config import ContractConfig
+from fastapi_contract.models import ExportMode, ExportStrategy
+
+
+@dataclass
+class ExportResult:
+    schema: dict[str, Any]
+    strategy: ExportStrategy
+    app_path: str
+    warnings: list[str] = field(default_factory=list)
+    drift_detected: bool = False
+
+    def to_json(self, *, indent: int = 2) -> str:
+        return json.dumps(self.schema, indent=indent, sort_keys=True) + "\n"
+
+
+class ExportError(RuntimeError):
+    """Raised when OpenAPI cannot be exported."""
+
+
+def _parse_target(target: str) -> tuple[str, str]:
+    if ":" not in target:
+        raise ExportError(
+            f"Invalid app target {target!r}. Expected 'module.path:attribute' "
+            "(e.g. 'myapp.main:app' or 'myapp.main:create_app')."
+        )
+    module_name, attr = target.rsplit(":", 1)
+    module_name = module_name.strip()
+    attr = attr.strip()
+    if not module_name or not attr:
+        raise ExportError(f"Invalid app target {target!r}.")
+    return module_name, attr
+
+
+def _load_stub_env(path: Path | None) -> dict[str, str]:
+    if path is None or not path.is_file():
+        return {}
+    env: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        key = key.strip()
+        value = value.strip().strip("'").strip('"')
+        if key:
+            env[key] = value
+    return env
+
+
+@contextmanager
+def _temporary_env(updates: dict[str, str]) -> Iterator[None]:
+    previous: dict[str, str | None] = {}
+    try:
+        for key, value in updates.items():
+            previous[key] = os.environ.get(key)
+            os.environ[key] = value
+        yield
+    finally:
+        for key, old in previous.items():
+            if old is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = old
+
+
+def _ensure_cwd_on_path(cwd: Path) -> None:
+    cwd_str = str(cwd.resolve())
+    if cwd_str not in sys.path:
+        sys.path.insert(0, cwd_str)
+
+
+def _is_fastapi_app(obj: Any) -> bool:
+    return callable(getattr(obj, "openapi", None)) and hasattr(obj, "routes")
+
+
+def _resolve_app(obj: Any, *, app_factory: bool, target: str) -> Any:
+    if app_factory or callable(obj) and not _is_fastapi_app(obj):
+        if not callable(obj):
+            raise ExportError(f"{target!r} is not callable; cannot use as app factory.")
+        app = obj()
+    else:
+        app = obj
+    if not _is_fastapi_app(app):
+        raise ExportError(
+            f"{target!r} did not resolve to a FastAPI-like app with .openapi()."
+        )
+    return app
+
+
+def _call_openapi(app: Any, *, skip_lifespan: bool) -> dict[str, Any]:
+    # FastAPI generates OpenAPI without requiring lifespan/startup in normal cases.
+    # skip_lifespan is retained for compatibility and future ASGI lifespan guards.
+    _ = skip_lifespan
+    schema = app.openapi()
+    if not isinstance(schema, dict):
+        raise ExportError("app.openapi() did not return a dict.")
+    return schema
+
+
+def _live_export(
+    config: ContractConfig, cwd: Path
+) -> tuple[dict[str, Any], ExportStrategy, list[str]]:
+    warnings: list[str] = []
+    module_name, attr = _parse_target(config.app)
+    _ensure_cwd_on_path(cwd)
+
+    stub_path = Path(config.stub_env_file) if config.stub_env_file else None
+    if stub_path and not stub_path.is_absolute():
+        stub_path = cwd / stub_path
+    env_updates = {**_load_stub_env(stub_path), **config.extra_env}
+    # Common CI-safe defaults when not already set / stubbed
+    defaults = {
+        "DATABASE_URL": "sqlite+aiosqlite:///:memory:",
+        "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:",
+        "REDIS_URL": "redis://localhost:6379/15",
+        "ENVIRONMENT": "contract",
+        "ENV": "contract",
+        "TESTING": "1",
+    }
+    for key, value in defaults.items():
+        env_updates.setdefault(key, value)
+
+    with _temporary_env(env_updates):
+        try:
+            # Always re-import so repeated checks in the same process (pytest / REPL)
+            # see the latest source. Drop the module and its submodules first.
+            to_drop = [
+                name
+                for name in list(sys.modules)
+                if name == module_name or name.startswith(module_name + ".")
+            ]
+            for name in to_drop:
+                del sys.modules[name]
+            module = importlib.import_module(module_name)
+        except Exception as exc:  # noqa: BLE001 - surface full import failure
+            raise ExportError(f"Failed to import module {module_name!r}: {exc}") from exc
+
+        if not hasattr(module, attr):
+            raise ExportError(f"Module {module_name!r} has no attribute {attr!r}.")
+        obj = getattr(module, attr)
+
+        factory_hint = config.app_factory or attr.startswith("create_") or attr in {
+            "create_app",
+            "get_app",
+            "make_app",
+            "build_app",
+        }
+        strategy = ExportStrategy.FACTORY if factory_hint else ExportStrategy.LIVE
+        try:
+            app = _resolve_app(obj, app_factory=factory_hint, target=config.app)
+            schema = _call_openapi(app, skip_lifespan=config.skip_lifespan)
+        except Exception as exc:  # noqa: BLE001
+            raise ExportError(f"Failed to export OpenAPI from {config.app!r}: {exc}") from exc
+
+        if env_updates:
+            warnings.append(
+                "Used stub/default environment variables during export "
+                f"({', '.join(sorted(env_updates)[:8])}{'…' if len(env_updates) > 8 else ''})."
+            )
+        return schema, strategy, warnings
+
+
+def _load_snapshot(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise ExportError(f"Snapshot not found: {path}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ExportError(f"Invalid snapshot JSON at {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ExportError(f"Snapshot at {path} must be a JSON object.")
+    return data
+
+
+def export_openapi(
+    config: ContractConfig | None = None,
+    *,
+    cwd: Path | None = None,
+    snapshot_path: Path | None = None,
+) -> ExportResult:
+    """Export OpenAPI using the configured strategy ladder."""
+    cfg = config or ContractConfig()
+    root = (cwd or Path.cwd()).resolve()
+    snap = snapshot_path or (root / cfg.snapshot_path)
+    warnings: list[str] = []
+
+    mode = cfg.export_mode
+    live_error: Exception | None = None
+    live_schema: dict[str, Any] | None = None
+    live_strategy = ExportStrategy.LIVE
+
+    if mode in (ExportMode.AUTO, ExportMode.LIVE):
+        try:
+            live_schema, live_strategy, live_warnings = _live_export(cfg, root)
+            warnings.extend(live_warnings)
+            if mode == ExportMode.LIVE:
+                return ExportResult(
+                    schema=live_schema,
+                    strategy=live_strategy,
+                    app_path=cfg.app,
+                    warnings=warnings,
+                )
+            # AUTO: optionally compare drift against snapshot
+            if snap.is_file():
+                try:
+                    snap_schema = _load_snapshot(snap)
+                    if snap_schema != live_schema:
+                        warnings.append(
+                            f"Snapshot drift detected: live OpenAPI differs from {snap}."
+                        )
+                        return ExportResult(
+                            schema=live_schema,
+                            strategy=live_strategy,
+                            app_path=cfg.app,
+                            warnings=warnings,
+                            drift_detected=True,
+                        )
+                except ExportError as exc:
+                    warnings.append(str(exc))
+            return ExportResult(
+                schema=live_schema,
+                strategy=live_strategy,
+                app_path=cfg.app,
+                warnings=warnings,
+            )
+        except ExportError as exc:
+            live_error = exc
+            if mode == ExportMode.LIVE:
+                raise
+            warnings.append(f"Live export failed: {exc}")
+
+    # SNAPSHOT or AUTO fallback
+    if mode in (ExportMode.AUTO, ExportMode.SNAPSHOT):
+        try:
+            schema = _load_snapshot(snap)
+            if mode == ExportMode.AUTO:
+                warnings.append(
+                    "Live export unavailable — using committed snapshot; "
+                    "drift vs live could not be verified."
+                )
+            return ExportResult(
+                schema=schema,
+                strategy=ExportStrategy.SNAPSHOT,
+                app_path=cfg.app,
+                warnings=warnings,
+            )
+        except ExportError as snap_exc:
+            if live_error is not None:
+                raise ExportError(
+                    f"Could not export OpenAPI.\n"
+                    f"Live error: {live_error}\n"
+                    f"Snapshot error: {snap_exc}\n"
+                    "Run `fastapi-contract doctor` for diagnosis."
+                ) from snap_exc
+            raise
+
+    raise ExportError(f"Unsupported export mode: {mode}")
+
+
+def write_snapshot(
+    schema: dict[str, Any],
+    path: Path,
+    *,
+    indent: int = 2,
+) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(schema, indent=indent, sort_keys=True) + "\n", encoding="utf-8")
+    return path

fastapi_contract/intentional.py

@@ -0,0 +1,109 @@
+"""Intentional breaking-change protocol enforcement."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastapi_contract.config import ContractConfig
+
+
+@dataclass(frozen=True)
+class IntentionalStatus:
+    marker_present: bool
+    changelog_ok: bool
+    allowed: bool
+    reasons: tuple[str, ...]
+
+    @property
+    def complete(self) -> bool:
+        return self.allowed
+
+
+def _read_text(path: Path) -> str:
+    if not path.is_file():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def _section_has_bullet(changelog_text: str, heading: str) -> bool:
+    if heading not in changelog_text:
+        return False
+    after = changelog_text.split(heading, 1)[1]
+    for line in after.splitlines()[1:]:
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            # reached next markdown heading
+            break
+        if stripped.startswith(("-", "*", "+")) and len(stripped) > 2:
+            return True
+    return False
+
+
+def evaluate_intentional(
+    config: ContractConfig,
+    *,
+    pr_title: str | None = None,
+    pr_labels: list[str] | None = None,
+    cwd: Path | None = None,
+    changelog_text: str | None = None,
+) -> IntentionalStatus:
+    """Return whether an intentional break protocol is complete.
+
+    Protocol requires:
+    1. Label match OR title marker
+    2. Changelog contains required heading with at least one bullet
+    """
+    root = (cwd or Path.cwd()).resolve()
+    labels = {label.strip().lower() for label in (pr_labels or []) if label}
+    title = pr_title or ""
+    marker = config.intentional_title_marker
+    label_ok = config.intentional_label.lower() in labels
+    title_ok = bool(marker) and marker.lower() in title.lower()
+    marker_present = label_ok or title_ok
+
+    reasons: list[str] = []
+    if not marker_present:
+        reasons.append(
+            f"Missing intentional marker: add label "
+            f"'{config.intentional_label}' or put '{marker}' in the PR title."
+        )
+
+    if changelog_text is None:
+        changelog_text = _read_text(root / config.changelog_path)
+
+    heading = config.changelog_required_heading
+    changelog_ok = False
+    if not changelog_text.strip():
+        reasons.append(f"Changelog missing or empty at {config.changelog_path}.")
+    elif heading not in changelog_text:
+        reasons.append(
+            f"Changelog must include heading '{heading}' describing the break."
+        )
+    elif not _section_has_bullet(changelog_text, heading):
+        reasons.append(
+            f"Heading '{heading}' found but no bullet points describing the break."
+        )
+    else:
+        changelog_ok = True
+
+    allowed = marker_present and changelog_ok
+    if allowed:
+        reasons = (
+            "Intentional breaking-change protocol satisfied "
+            "(marker + changelog).",
+        )
+    return IntentionalStatus(
+        marker_present=marker_present,
+        changelog_ok=changelog_ok,
+        allowed=allowed,
+        reasons=tuple(reasons),
+    )
+
+
+def suggest_semver_bump(has_breaking: bool, has_additive: bool) -> str:
+    if has_breaking:
+        return "major"
+    if has_additive:
+        return "minor"
+    return "patch"

fastapi_contract/models.py

@@ -0,0 +1,33 @@
+"""Shared enums and typed structures."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class PolicyName(str, Enum):
+    """Severity policy for classifying OpenAPI changes."""
+
+    ADDITIVE_FRIENDLY = "additive-friendly"
+    STRICT = "strict"
+
+
+class FailOn(str, Enum):
+    """Which severities cause a non-zero exit."""
+
+    BREAKING = "breaking"
+    RISKY = "risky"
+    ANY = "any"
+
+
+class ExportMode(str, Enum):
+    AUTO = "auto"
+    LIVE = "live"
+    SNAPSHOT = "snapshot"
+
+
+class ExportStrategy(str, Enum):
+    LIVE = "live"
+    FACTORY = "factory"
+    SNAPSHOT = "snapshot"
+    FAILED = "failed"

fastapi_contract/pytest_plugin.py

@@ -0,0 +1,98 @@
+"""Pytest plugin: assert OpenAPI compatibility against a snapshot/base schema."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from fastapi_contract.check import compare_schemas, run_check
+from fastapi_contract.config import ContractConfig, load_config
+from fastapi_contract.diff.classifier import DiffResult
+from fastapi_contract.export import export_openapi
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("fastapi-contract")
+    group.addoption(
+        "--fastapi-contract-app",
+        action="store",
+        default=None,
+        help="Override FastAPI app target (module:attr)",
+    )
+    group.addoption(
+        "--fastapi-contract-base",
+        action="store",
+        default=None,
+        help="Path to base OpenAPI JSON snapshot",
+    )
+    group.addoption(
+        "--fastapi-contract-policy",
+        action="store",
+        default=None,
+        help="additive-friendly | strict",
+    )
+
+
+@pytest.fixture
+def fastapi_contract_config(pytestconfig: pytest.Config, tmp_path_factory: Any) -> ContractConfig:
+    overrides: dict[str, Any] = {}
+    app = pytestconfig.getoption("--fastapi-contract-app")
+    policy = pytestconfig.getoption("--fastapi-contract-policy")
+    if app:
+        overrides["app"] = app
+    if policy:
+        overrides["policy"] = policy
+    return load_config(overrides=overrides)
+
+
+class FastAPIContractFixture:
+    def __init__(self, config: ContractConfig, base_path: Path | None) -> None:
+        self.config = config
+        self.base_path = base_path
+
+    def export(self) -> dict[str, Any]:
+        return export_openapi(self.config).schema
+
+    def diff(self, base: dict[str, Any] | None = None) -> DiffResult:
+        candidate = self.export()
+        if base is None:
+            path = self.base_path or Path(self.config.snapshot_path)
+            base = __import__("json").loads(path.read_text(encoding="utf-8"))
+        return compare_schemas(
+            base,
+            candidate,
+            policy=self.config.policy,
+            prefer_oasdiff=self.config.prefer_oasdiff,
+            oasdiff_bin=self.config.oasdiff_bin,
+        )
+
+    def assert_compatible(self, base: dict[str, Any] | None = None) -> DiffResult:
+        result = run_check(
+            self.config,
+            base_schema=base,
+            base_schema_path=None if base is not None else self.base_path,
+        )
+        if not result.passed:
+            pytest.fail(
+                "OpenAPI contract check failed:\n"
+                + "\n".join(
+                    f"- [{c.severity.value}] {c.message}" for c in result.diff.breaking
+                )
+            )
+        return result.diff
+
+
+@pytest.fixture
+def fastapi_contract(
+    fastapi_contract_config: ContractConfig, pytestconfig: pytest.Config
+) -> FastAPIContractFixture:
+    base = pytestconfig.getoption("--fastapi-contract-base")
+    base_path = Path(base) if base else None
+    return FastAPIContractFixture(fastapi_contract_config, base_path)
+
+
+@pytest.fixture
+def assert_openapi_compatible(fastapi_contract: FastAPIContractFixture):
+    return fastapi_contract.assert_compatible