fastapi-breakgate 1.0.1__py3-none-any.whl

fastapi_contract/diff/oasdiff.py

@@ -0,0 +1,160 @@
+"""Optional oasdiff integration — used when binary is available and preferred."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from fastapi_contract.diff.classifier import (
+    Change,
+    ChangeSeverity,
+    DiffResult,
+    diff_openapi,
+)
+from fastapi_contract.diff.policy import ChangeKind
+from fastapi_contract.models import PolicyName
+
+
+class OasdiffNotFoundError(RuntimeError):
+    pass
+
+
+def find_oasdiff(explicit: str | None = None) -> str | None:
+    if explicit:
+        path = Path(explicit)
+        if path.is_file():
+            return str(path)
+        found = shutil.which(explicit)
+        return found
+    return shutil.which("oasdiff")
+
+
+def _map_oasdiff_id(change_id: str) -> ChangeKind:
+    lowered = change_id.lower()
+    mapping = {
+        "endpoint-removed": ChangeKind.OPERATION_REMOVED,
+        "api-path-removed-without-deprecation": ChangeKind.PATH_REMOVED,
+        "api-removed-without-deprecation": ChangeKind.OPERATION_REMOVED,
+        "request-property-became-required": ChangeKind.REQUEST_FIELD_OPTIONAL_TO_REQUIRED,
+        "new-required-request-property": ChangeKind.REQUIRED_REQUEST_FIELD_ADDED,
+        "response-property-removed": ChangeKind.RESPONSE_FIELD_REMOVED,
+        "response-required-property-removed": ChangeKind.RESPONSE_FIELD_REMOVED,
+        "response-media-type-removed": ChangeKind.MEDIA_TYPE_REMOVED,
+        "response-success-status-removed": ChangeKind.RESPONSE_STATUS_REMOVED,
+        "request-parameter-removed": ChangeKind.PARAMETER_REMOVED,
+        "new-required-request-parameter": ChangeKind.PARAMETER_ADDED_REQUIRED,
+        "request-parameter-became-required": ChangeKind.PARAMETER_BECAME_REQUIRED,
+        "request-body-became-required": ChangeKind.REQUIRED_REQUEST_FIELD_ADDED,
+        "api-security-added": ChangeKind.SECURITY_ADDED,
+        "response-property-enum-value-added": ChangeKind.ENUM_VALUE_ADDED,
+        "request-property-enum-value-removed": ChangeKind.ENUM_VALUE_REMOVED,
+        "response-property-type-changed": ChangeKind.TYPE_CHANGED,
+        "request-property-type-changed": ChangeKind.TYPE_CHANGED,
+    }
+    for key, kind in mapping.items():
+        if key in lowered:
+            return kind
+    return ChangeKind.OTHER
+
+
+def diff_with_oasdiff(
+    base: dict[str, Any],
+    candidate: dict[str, Any],
+    *,
+    policy: PolicyName,
+    oasdiff_bin: str | None = None,
+) -> DiffResult:
+    binary = find_oasdiff(oasdiff_bin)
+    if not binary:
+        raise OasdiffNotFoundError("oasdiff binary not found on PATH")
+
+    with tempfile.TemporaryDirectory(prefix="fastapi-contract-") as tmp:
+        tmp_path = Path(tmp)
+        base_path = tmp_path / "base.json"
+        cand_path = tmp_path / "candidate.json"
+        base_path.write_text(json.dumps(base), encoding="utf-8")
+        cand_path.write_text(json.dumps(candidate), encoding="utf-8")
+
+        # Prefer JSON changelog output when available
+        proc = subprocess.run(
+            [
+                binary,
+                "changelog",
+                str(base_path),
+                str(cand_path),
+                "--format",
+                "json",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if proc.returncode not in (0, 1) or not proc.stdout.strip():
+            # Fallback to python engine if oasdiff invocation fails
+            result = diff_openapi(base, candidate, policy=policy)
+            result.engine = "python-fallback"
+            return result
+
+        try:
+            payload = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            result = diff_openapi(base, candidate, policy=policy)
+            result.engine = "python-fallback"
+            return result
+
+        changes: list[Change] = []
+        entries = payload if isinstance(payload, list) else payload.get("changes", [])
+        if not isinstance(entries, list):
+            entries = []
+
+        from fastapi_contract.diff.policy import severity_for
+
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            change_id = str(entry.get("id") or entry.get("text") or "other")
+            kind = _map_oasdiff_id(change_id)
+            level = str(entry.get("level") or entry.get("severity") or "").lower()
+            if level in {"error", "breaking"}:
+                severity = ChangeSeverity.BREAKING
+            elif level in {"warn", "warning", "risky"}:
+                severity = ChangeSeverity.RISKY
+            elif level in {"info", "safe"}:
+                severity = ChangeSeverity.SAFE
+            else:
+                severity = ChangeSeverity(severity_for(kind, policy))
+
+            # Policy overlay for enum additions etc.
+            if kind == ChangeKind.ENUM_VALUE_ADDED and policy == PolicyName.ADDITIVE_FRIENDLY:
+                severity = ChangeSeverity.SAFE
+
+            path = str(
+                entry.get("path")
+                or entry.get("operation")
+                or entry.get("section")
+                or "/"
+            )
+            method_raw = entry.get("method") or entry.get("operation")
+            method = method_raw.lower() if isinstance(method_raw, str) else None
+            message = str(entry.get("text") or entry.get("description") or change_id)
+            changes.append(
+                Change(
+                    kind=kind,
+                    severity=severity,
+                    path=path,
+                    method=method,
+                    message=message,
+                    details={"oasdiff_id": change_id, "raw": entry},
+                )
+            )
+
+        return DiffResult(
+            changes=changes,
+            base_paths=len(base.get("paths") or {}),
+            candidate_paths=len(candidate.get("paths") or {}),
+            engine="oasdiff",
+        )

fastapi_contract/diff/policy.py

@@ -0,0 +1,85 @@
+"""Map raw change kinds to severities under additive-friendly vs strict policies."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from fastapi_contract.models import PolicyName
+
+
+class ChangeKind(str, Enum):
+    PATH_REMOVED = "path_removed"
+    PATH_ADDED = "path_added"
+    OPERATION_REMOVED = "operation_removed"
+    OPERATION_ADDED = "operation_added"
+    OPERATION_DEPRECATED = "operation_deprecated"
+    REQUIRED_REQUEST_FIELD_ADDED = "required_request_field_added"
+    REQUEST_FIELD_REMOVED = "request_field_removed"
+    REQUEST_FIELD_OPTIONAL_TO_REQUIRED = "request_field_optional_to_required"
+    REQUEST_FIELD_REQUIRED_TO_OPTIONAL = "request_field_required_to_optional"
+    RESPONSE_FIELD_REMOVED = "response_field_removed"
+    RESPONSE_FIELD_ADDED = "response_field_added"
+    RESPONSE_REQUIRED_FIELD_ADDED = "response_required_field_added"
+    TYPE_CHANGED = "type_changed"
+    TYPE_NARROWED = "type_narrowed"
+    TYPE_WIDENED = "type_widened"
+    ENUM_VALUE_REMOVED = "enum_value_removed"
+    ENUM_VALUE_ADDED = "enum_value_added"
+    RESPONSE_STATUS_REMOVED = "response_status_removed"
+    RESPONSE_STATUS_ADDED = "response_status_added"
+    PARAMETER_REMOVED = "parameter_removed"
+    PARAMETER_ADDED_REQUIRED = "parameter_added_required"
+    PARAMETER_ADDED_OPTIONAL = "parameter_added_optional"
+    PARAMETER_BECAME_REQUIRED = "parameter_became_required"
+    SECURITY_ADDED = "security_added"
+    MEDIA_TYPE_REMOVED = "media_type_removed"
+    SCHEMA_REMOVED = "schema_removed"
+    OTHER = "other"
+
+
+# Base severities before policy overlay: BREAKING / RISKY / SAFE encoded as strings
+_BASE: dict[ChangeKind, str] = {
+    ChangeKind.PATH_REMOVED: "breaking",
+    ChangeKind.PATH_ADDED: "safe",
+    ChangeKind.OPERATION_REMOVED: "breaking",
+    ChangeKind.OPERATION_ADDED: "safe",
+    ChangeKind.OPERATION_DEPRECATED: "safe",
+    ChangeKind.REQUIRED_REQUEST_FIELD_ADDED: "breaking",
+    ChangeKind.REQUEST_FIELD_REMOVED: "risky",
+    ChangeKind.REQUEST_FIELD_OPTIONAL_TO_REQUIRED: "breaking",
+    ChangeKind.REQUEST_FIELD_REQUIRED_TO_OPTIONAL: "safe",
+    ChangeKind.RESPONSE_FIELD_REMOVED: "breaking",
+    ChangeKind.RESPONSE_FIELD_ADDED: "safe",
+    ChangeKind.RESPONSE_REQUIRED_FIELD_ADDED: "risky",
+    ChangeKind.TYPE_CHANGED: "breaking",
+    ChangeKind.TYPE_NARROWED: "breaking",
+    ChangeKind.TYPE_WIDENED: "safe",
+    ChangeKind.ENUM_VALUE_REMOVED: "breaking",
+    ChangeKind.ENUM_VALUE_ADDED: "breaking",  # strict default; overlay may soften
+    ChangeKind.RESPONSE_STATUS_REMOVED: "breaking",
+    ChangeKind.RESPONSE_STATUS_ADDED: "safe",
+    ChangeKind.PARAMETER_REMOVED: "breaking",
+    ChangeKind.PARAMETER_ADDED_REQUIRED: "breaking",
+    ChangeKind.PARAMETER_ADDED_OPTIONAL: "safe",
+    ChangeKind.PARAMETER_BECAME_REQUIRED: "breaking",
+    ChangeKind.SECURITY_ADDED: "breaking",
+    ChangeKind.MEDIA_TYPE_REMOVED: "breaking",
+    ChangeKind.SCHEMA_REMOVED: "risky",
+    ChangeKind.OTHER: "risky",
+}
+
+
+def severity_for(kind: ChangeKind, policy: PolicyName) -> str:
+    base = _BASE.get(kind, "risky")
+    if policy == PolicyName.STRICT:
+        return base
+    # additive-friendly overlay
+    if kind == ChangeKind.ENUM_VALUE_ADDED:
+        return "safe"
+    if kind == ChangeKind.RESPONSE_REQUIRED_FIELD_ADDED:
+        return "safe"
+    if kind == ChangeKind.REQUEST_FIELD_REMOVED:
+        return "safe"  # clients can omit removed optional request fields
+    if kind == ChangeKind.SCHEMA_REMOVED:
+        return "safe"  # unused component removal often OK if unreferenced in paths
+    return base

fastapi_contract/doctor.py

@@ -0,0 +1,251 @@
+"""Diagnose FastAPI OpenAPI export readiness."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from fastapi_contract.config import ContractConfig
+from fastapi_contract.export import (
+    ExportError,
+    _ensure_cwd_on_path,
+    _load_stub_env,
+    _parse_target,
+    export_openapi,
+)
+
+
+@dataclass
+class DoctorCheck:
+    name: str
+    ok: bool
+    detail: str
+    hint: str | None = None
+
+
+@dataclass
+class DoctorReport:
+    ok: bool
+    checks: list[DoctorCheck] = field(default_factory=list)
+    suggested_env: dict[str, str] = field(default_factory=dict)
+
+    def to_markdown(self) -> str:
+        lines = ["# fastapi-contract doctor", ""]
+        lines.append(f"**Overall:** {'PASS' if self.ok else 'FAIL'}")
+        lines.append("")
+        for check in self.checks:
+            mark = "OK" if check.ok else "FAIL"
+            lines.append(f"- [{mark}] **{check.name}**: {check.detail}")
+            if check.hint:
+                lines.append(f"  - hint: {check.hint}")
+        if self.suggested_env:
+            lines.append("")
+            lines.append("## Suggested `.env.contract`")
+            lines.append("```")
+            for key, value in sorted(self.suggested_env.items()):
+                lines.append(f"{key}={value}")
+            lines.append("```")
+        lines.append("")
+        return "\n".join(lines)
+
+
+_SENSITIVE_HINTS = (
+    "DATABASE_URL",
+    "SQLALCHEMY_DATABASE_URI",
+    "REDIS_URL",
+    "SECRET_KEY",
+    "API_KEY",
+    "POSTGRES",
+    "MONGO",
+)
+
+
+def run_doctor(
+    config: ContractConfig | None = None,
+    *,
+    cwd: Path | None = None,
+) -> DoctorReport:
+    cfg = config or ContractConfig()
+    root = (cwd or Path.cwd()).resolve()
+    checks: list[DoctorCheck] = []
+    suggested_env: dict[str, str] = {
+        "DATABASE_URL": "sqlite+aiosqlite:///:memory:",
+        "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:",
+        "REDIS_URL": "redis://localhost:6379/15",
+        "ENVIRONMENT": "contract",
+        "TESTING": "1",
+    }
+
+    # Target format
+    try:
+        module_name, attr = _parse_target(cfg.app)
+        checks.append(
+            DoctorCheck("app target format", True, f"{module_name}:{attr}")
+        )
+    except ExportError as exc:
+        return DoctorReport(
+            ok=False,
+            checks=[DoctorCheck("app target format", False, str(exc))],
+        )
+
+    _ensure_cwd_on_path(root)
+
+    # Stub env file
+    stub_path = Path(cfg.stub_env_file) if cfg.stub_env_file else None
+    if stub_path and not stub_path.is_absolute():
+        stub_path = root / stub_path
+    if cfg.stub_env_file:
+        if stub_path and stub_path.is_file():
+            stub = _load_stub_env(stub_path)
+            checks.append(
+                DoctorCheck(
+                    "stub env file",
+                    True,
+                    f"Found {stub_path} with {len(stub)} keys",
+                )
+            )
+            suggested_env.update(stub)
+        else:
+            checks.append(
+                DoctorCheck(
+                    "stub env file",
+                    True,
+                    f"Optional {cfg.stub_env_file} not found (OK if app imports without it)",
+                    hint=(
+                        "Create .env.contract with CI-safe placeholders "
+                        "when import needs secrets/DB URLs."
+                    ),
+                )
+            )
+
+    # Import module
+    try:
+        module = importlib.import_module(module_name)
+        checks.append(DoctorCheck("import module", True, f"Imported {module_name}"))
+    except Exception as exc:  # noqa: BLE001
+        msg = str(exc)
+        hint = None
+        upper = msg.upper()
+        for token in _SENSITIVE_HINTS:
+            if token in upper or token in msg:
+                hint = (
+                    f"Import appears to require {token}. "
+                    "Add it to .env.contract and use a create_app() factory."
+                )
+                break
+        if hint is None:
+            hint = (
+                "Prefer `create_app()` that accepts settings/env injection, "
+                "or set export_mode=snapshot with a committed openapi.snapshot.json."
+            )
+        checks.append(DoctorCheck("import module", False, msg, hint=hint))
+        # Still check snapshot fallback
+        snap = root / cfg.snapshot_path
+        if snap.is_file():
+            checks.append(
+                DoctorCheck(
+                    "snapshot fallback",
+                    True,
+                    f"Found {snap} — AUTO mode can use snapshot when live fails",
+                )
+            )
+        else:
+            checks.append(
+                DoctorCheck(
+                    "snapshot fallback",
+                    False,
+                    f"No snapshot at {snap}",
+                    hint=(
+                        "Run a local `fastapi-contract snapshot` once live "
+                        "export works, and commit it."
+                    ),
+                )
+            )
+        ok = any(c.ok and c.name == "snapshot fallback" for c in checks)
+        return DoctorReport(ok=ok, checks=checks, suggested_env=suggested_env)
+
+    if not hasattr(module, attr):
+        checks.append(
+            DoctorCheck(
+                "app attribute",
+                False,
+                f"{module_name} has no attribute {attr!r}",
+                hint="Check [tool.fastapi_contract].app in pyproject.toml",
+            )
+        )
+    else:
+        obj: Any = getattr(module, attr)
+        factory_like = callable(obj) and not hasattr(obj, "openapi")
+        kind = "factory" if factory_like or cfg.app_factory else "app instance"
+        checks.append(
+            DoctorCheck(
+                "app attribute",
+                True,
+                f"Found {attr} ({kind})",
+                hint=(
+                    "Set app_factory = true if this is a create_app() callable."
+                    if factory_like and not cfg.app_factory
+                    else None
+                ),
+            )
+        )
+
+    # Snapshot presence
+    snap = root / cfg.snapshot_path
+    if snap.is_file():
+        checks.append(DoctorCheck("snapshot file", True, f"Present at {snap}"))
+    else:
+        checks.append(
+            DoctorCheck(
+                "snapshot file",
+                True,
+                f"Optional snapshot not present ({cfg.snapshot_path})",
+                hint="Recommended as CI fallback when live import needs infra.",
+            )
+        )
+
+    # Full export attempt
+    try:
+        result = export_openapi(cfg, cwd=root)
+        checks.append(
+            DoctorCheck(
+                "openapi export",
+                True,
+                f"Succeeded via {result.strategy.value} "
+                f"({len(result.schema.get('paths', {}))} paths)",
+            )
+        )
+        for warning in result.warnings:
+            checks.append(DoctorCheck("export warning", True, warning))
+    except ExportError as exc:
+        checks.append(
+            DoctorCheck(
+                "openapi export",
+                False,
+                str(exc),
+                hint="Fix import/settings or commit a snapshot for AUTO fallback.",
+            )
+        )
+
+    # Env visibility note
+    missing_common = [k for k in ("DATABASE_URL", "SECRET_KEY") if k not in os.environ]
+    if missing_common:
+        checks.append(
+            DoctorCheck(
+                "host environment",
+                True,
+                f"Common keys not in process env: {', '.join(missing_common)} "
+                "(stubs/defaults may still work)",
+            )
+        )
+
+    critical = {"app target format", "app attribute", "openapi export"}
+    ok = all(c.ok for c in checks if c.name in critical)
+    # Allow pass if export works even if stub file missing
+    export_ok = any(c.name == "openapi export" and c.ok for c in checks)
+    if export_ok:
+        ok = True
+    return DoctorReport(ok=ok, checks=checks, suggested_env=suggested_env)