fastapi-breakgate 1.0.1__py3-none-any.whl

fastapi_contract/diff/classifier.py

@@ -0,0 +1,779 @@
+"""Pure-Python OpenAPI breaking-change classifier (production ruleset)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from fastapi_contract.diff.policy import ChangeKind, severity_for
+from fastapi_contract.models import PolicyName
+
+HTTP_METHODS = ("get", "post", "put", "patch", "delete", "options", "head", "trace")
+
+
+class ChangeSeverity(str, Enum):
+    BREAKING = "breaking"
+    RISKY = "risky"
+    SAFE = "safe"
+
+
+@dataclass(frozen=True)
+class Change:
+    kind: ChangeKind
+    severity: ChangeSeverity
+    path: str
+    message: str
+    method: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind.value,
+            "severity": self.severity.value,
+            "path": self.path,
+            "method": self.method,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+@dataclass
+class DiffResult:
+    changes: list[Change]
+    base_paths: int
+    candidate_paths: int
+    engine: str = "python"
+
+    @property
+    def breaking(self) -> list[Change]:
+        return [c for c in self.changes if c.severity == ChangeSeverity.BREAKING]
+
+    @property
+    def risky(self) -> list[Change]:
+        return [c for c in self.changes if c.severity == ChangeSeverity.RISKY]
+
+    @property
+    def safe(self) -> list[Change]:
+        return [c for c in self.changes if c.severity == ChangeSeverity.SAFE]
+
+    def has_failing(self, fail_on: str) -> bool:
+        if fail_on == "any":
+            return bool(self.breaking or self.risky or self.safe)
+        if fail_on == "risky":
+            return bool(self.breaking or self.risky)
+        return bool(self.breaking)
+
+
+def _sev(kind: ChangeKind, policy: PolicyName) -> ChangeSeverity:
+    return ChangeSeverity(severity_for(kind, policy))
+
+
+def _change(
+    kind: ChangeKind,
+    policy: PolicyName,
+    path: str,
+    message: str,
+    *,
+    method: str | None = None,
+    **details: Any,
+) -> Change:
+    return Change(
+        kind=kind,
+        severity=_sev(kind, policy),
+        path=path,
+        method=method,
+        message=message,
+        details=details,
+    )
+
+
+def _paths(schema: dict[str, Any]) -> dict[str, Any]:
+    paths = schema.get("paths") or {}
+    return paths if isinstance(paths, dict) else {}
+
+
+def _components_schemas(schema: dict[str, Any]) -> dict[str, Any]:
+    components = schema.get("components") or {}
+    if not isinstance(components, dict):
+        return {}
+    schemas = components.get("schemas") or {}
+    return schemas if isinstance(schemas, dict) else {}
+
+
+def _resolve_ref(schema: dict[str, Any], node: Any, *, _seen: set[str] | None = None) -> Any:
+    if not isinstance(node, dict):
+        return node
+    ref = node.get("$ref")
+    if not isinstance(ref, str) or not ref.startswith("#/"):
+        return node
+    seen = _seen or set()
+    if ref in seen:
+        return node
+    seen.add(ref)
+    cur: Any = schema
+    for part in ref[2:].split("/"):
+        if not isinstance(cur, dict) or part not in cur:
+            return node
+        cur = cur[part]
+    if isinstance(cur, dict) and "$ref" in cur:
+        return _resolve_ref(schema, cur, _seen=seen)
+    return cur
+
+
+def _schema_type(node: dict[str, Any]) -> str | None:
+    t = node.get("type")
+    if isinstance(t, list):
+        return ",".join(str(x) for x in t)
+    return str(t) if t is not None else None
+
+
+def _enum_values(node: dict[str, Any]) -> set[Any] | None:
+    if "enum" not in node:
+        return None
+    values = node.get("enum")
+    if not isinstance(values, list):
+        return set()
+    return set(values)
+
+
+def _properties(node: dict[str, Any]) -> dict[str, Any]:
+    props = node.get("properties") or {}
+    return props if isinstance(props, dict) else {}
+
+
+def _required(node: dict[str, Any]) -> set[str]:
+    req = node.get("required") or []
+    if not isinstance(req, list):
+        return set()
+    return {str(x) for x in req}
+
+
+def _get_request_body_schema(
+    root: dict[str, Any], operation: dict[str, Any]
+) -> dict[str, Any] | None:
+    body = operation.get("requestBody")
+    if not isinstance(body, dict):
+        return None
+    content = body.get("content") or {}
+    if not isinstance(content, dict):
+        return None
+    for media in ("application/json", "application/x-www-form-urlencoded", "multipart/form-data"):
+        if media in content and isinstance(content[media], dict):
+            schema = content[media].get("schema")
+            if isinstance(schema, dict):
+                resolved = _resolve_ref(root, schema)
+                return resolved if isinstance(resolved, dict) else None
+    # first available
+    for item in content.values():
+        if isinstance(item, dict) and isinstance(item.get("schema"), dict):
+            resolved = _resolve_ref(root, item["schema"])
+            return resolved if isinstance(resolved, dict) else None
+    return None
+
+
+def _response_schemas(
+    root: dict[str, Any], operation: dict[str, Any]
+) -> dict[str, dict[str, Any]]:
+    result: dict[str, dict[str, Any]] = {}
+    responses = operation.get("responses") or {}
+    if not isinstance(responses, dict):
+        return result
+    for status, resp in responses.items():
+        if not isinstance(resp, dict):
+            continue
+        content = resp.get("content") or {}
+        if not isinstance(content, dict):
+            result[str(status)] = {}
+            continue
+        media = content.get("application/json") or next(iter(content.values()), None)
+        if isinstance(media, dict) and isinstance(media.get("schema"), dict):
+            resolved = _resolve_ref(root, media["schema"])
+            result[str(status)] = resolved if isinstance(resolved, dict) else {}
+        else:
+            result[str(status)] = {}
+    return result
+
+
+def _compare_object_schema(
+    *,
+    base_root: dict[str, Any],
+    cand_root: dict[str, Any],
+    base: dict[str, Any],
+    cand: dict[str, Any],
+    policy: PolicyName,
+    path: str,
+    method: str,
+    location: str,
+    changes: list[Change],
+) -> None:
+    base_props = _properties(base)
+    cand_props = _properties(cand)
+    base_req = _required(base)
+    cand_req = _required(cand)
+
+    for name in sorted(base_props.keys() - cand_props.keys()):
+        kind = (
+            ChangeKind.RESPONSE_FIELD_REMOVED
+            if location == "response"
+            else ChangeKind.REQUEST_FIELD_REMOVED
+        )
+        changes.append(
+            _change(
+                kind,
+                policy,
+                path,
+                f"Removed {location} field '{name}'",
+                method=method,
+                field=name,
+                location=location,
+            )
+        )
+
+    for name in sorted(cand_props.keys() - base_props.keys()):
+        if location == "request":
+            if name in cand_req:
+                changes.append(
+                    _change(
+                        ChangeKind.REQUIRED_REQUEST_FIELD_ADDED,
+                        policy,
+                        path,
+                        f"Added required request field '{name}'",
+                        method=method,
+                        field=name,
+                    )
+                )
+            else:
+                changes.append(
+                    Change(
+                        kind=ChangeKind.OTHER,
+                        severity=ChangeSeverity.SAFE,
+                        path=path,
+                        method=method,
+                        message=f"Added optional request field '{name}'",
+                        details={"field": name, "location": "request"},
+                    )
+                )
+        else:
+            if name in cand_req and name not in base_req:
+                changes.append(
+                    _change(
+                        ChangeKind.RESPONSE_REQUIRED_FIELD_ADDED,
+                        policy,
+                        path,
+                        f"Added required response field '{name}'",
+                        method=method,
+                        field=name,
+                    )
+                )
+            else:
+                changes.append(
+                    _change(
+                        ChangeKind.RESPONSE_FIELD_ADDED,
+                        policy,
+                        path,
+                        f"Added response field '{name}'",
+                        method=method,
+                        field=name,
+                    )
+                )
+
+    for name in sorted(cand_req - base_req):
+        if name in base_props and location == "request":
+            changes.append(
+                _change(
+                    ChangeKind.REQUEST_FIELD_OPTIONAL_TO_REQUIRED,
+                    policy,
+                    path,
+                    f"Request field '{name}' became required",
+                    method=method,
+                    field=name,
+                )
+            )
+
+    for name in sorted(base_req - cand_req):
+        if name in cand_props and location == "request":
+            changes.append(
+                _change(
+                    ChangeKind.REQUEST_FIELD_REQUIRED_TO_OPTIONAL,
+                    policy,
+                    path,
+                    f"Request field '{name}' became optional",
+                    method=method,
+                    field=name,
+                )
+            )
+
+    for name in sorted(base_props.keys() & cand_props.keys()):
+        b = base_props[name]
+        c = cand_props[name]
+        if not isinstance(b, dict) or not isinstance(c, dict):
+            continue
+        _compare_schema_nodes(
+            base_root=base_root,
+            cand_root=cand_root,
+            base=b,
+            cand=c,
+            policy=policy,
+            path=path,
+            method=method,
+            location=f"{location}.{name}",
+            changes=changes,
+            field_name=name,
+        )
+
+
+def _compare_schema_nodes(
+    *,
+    base_root: dict[str, Any],
+    cand_root: dict[str, Any],
+    base: dict[str, Any],
+    cand: dict[str, Any],
+    policy: PolicyName,
+    path: str,
+    method: str,
+    location: str,
+    changes: list[Change],
+    field_name: str | None = None,
+) -> None:
+    b = _resolve_ref(base_root, base) if base_root else base
+    c = _resolve_ref(cand_root, cand) if cand_root else cand
+    if not isinstance(b, dict) or not isinstance(c, dict):
+        return
+
+    bt = _schema_type(b)
+    ct = _schema_type(c)
+    if bt and ct and bt != ct:
+        # narrowing / widening heuristics
+        widen_pairs = {("integer", "number"), ("number", "string")}
+        if (bt, ct) in widen_pairs:
+            kind = ChangeKind.TYPE_WIDENED
+        elif (ct, bt) in widen_pairs:
+            kind = ChangeKind.TYPE_NARROWED
+        else:
+            kind = ChangeKind.TYPE_CHANGED
+        label = field_name or location
+        changes.append(
+            _change(
+                kind,
+                policy,
+                path,
+                f"Type of '{label}' changed from {bt} to {ct}",
+                method=method,
+                field=field_name,
+                from_type=bt,
+                to_type=ct,
+            )
+        )
+
+    be = _enum_values(b)
+    ce = _enum_values(c)
+    if be is not None and ce is not None:
+        removed = be - ce
+        added = ce - be
+        label = field_name or location
+        for value in sorted(removed, key=lambda x: str(x)):
+            changes.append(
+                _change(
+                    ChangeKind.ENUM_VALUE_REMOVED,
+                    policy,
+                    path,
+                    f"Enum value {value!r} removed from '{label}'",
+                    method=method,
+                    field=field_name,
+                    value=value,
+                )
+            )
+        for value in sorted(added, key=lambda x: str(x)):
+            changes.append(
+                _change(
+                    ChangeKind.ENUM_VALUE_ADDED,
+                    policy,
+                    path,
+                    f"Enum value {value!r} added to '{label}'",
+                    method=method,
+                    field=field_name,
+                    value=value,
+                )
+            )
+
+    if _properties(b) or _properties(c):
+        loc = "request"
+        if "response" in location:
+            loc = "response"
+        elif "request" in location:
+            loc = "request"
+        _compare_object_schema(
+            base_root=base_root,
+            cand_root=cand_root,
+            base=b,
+            cand=c,
+            policy=policy,
+            path=path,
+            method=method,
+            location=loc,
+            changes=changes,
+        )
+
+
+def _compare_parameters(
+    *,
+    base_root: dict[str, Any],
+    cand_root: dict[str, Any],
+    base_op: dict[str, Any],
+    cand_op: dict[str, Any],
+    policy: PolicyName,
+    path: str,
+    method: str,
+    changes: list[Change],
+) -> None:
+    def index(op: dict[str, Any], root: dict[str, Any]) -> dict[tuple[str, str], dict[str, Any]]:
+        out: dict[tuple[str, str], dict[str, Any]] = {}
+        params = op.get("parameters") or []
+        if not isinstance(params, list):
+            return out
+        for raw in params:
+            if not isinstance(raw, dict):
+                continue
+            node = _resolve_ref(root, raw)
+            if not isinstance(node, dict):
+                continue
+            name = str(node.get("name", ""))
+            location = str(node.get("in", "query"))
+            if name:
+                out[(name, location)] = node
+        return out
+
+    b_params = index(base_op, base_root)
+    c_params = index(cand_op, cand_root)
+
+    for key in sorted(b_params.keys() - c_params.keys()):
+        name, location = key
+        changes.append(
+            _change(
+                ChangeKind.PARAMETER_REMOVED,
+                policy,
+                path,
+                f"Removed {location} parameter '{name}'",
+                method=method,
+                parameter=name,
+                location=location,
+            )
+        )
+
+    for key in sorted(c_params.keys() - b_params.keys()):
+        name, location = key
+        node = c_params[key]
+        required = bool(node.get("required"))
+        kind = (
+            ChangeKind.PARAMETER_ADDED_REQUIRED
+            if required
+            else ChangeKind.PARAMETER_ADDED_OPTIONAL
+        )
+        changes.append(
+            _change(
+                kind,
+                policy,
+                path,
+                f"Added {'required ' if required else ''}{location} parameter '{name}'",
+                method=method,
+                parameter=name,
+                location=location,
+            )
+        )
+
+    for key in sorted(b_params.keys() & c_params.keys()):
+        b = b_params[key]
+        c = c_params[key]
+        if not bool(b.get("required")) and bool(c.get("required")):
+            name, location = key
+            changes.append(
+                _change(
+                    ChangeKind.PARAMETER_BECAME_REQUIRED,
+                    policy,
+                    path,
+                    f"{location} parameter '{name}' became required",
+                    method=method,
+                    parameter=name,
+                )
+            )
+        b_schema = b.get("schema") if isinstance(b.get("schema"), dict) else {}
+        c_schema = c.get("schema") if isinstance(c.get("schema"), dict) else {}
+        if b_schema and c_schema:
+            _compare_schema_nodes(
+                base_root=base_root,
+                cand_root=cand_root,
+                base=b_schema,
+                cand=c_schema,
+                policy=policy,
+                path=path,
+                method=method,
+                location=f"parameter.{key[0]}",
+                changes=changes,
+                field_name=key[0],
+            )
+
+
+def _compare_security(
+    base_op: dict[str, Any],
+    cand_op: dict[str, Any],
+    policy: PolicyName,
+    path: str,
+    method: str,
+    changes: list[Change],
+) -> None:
+    base_sec = base_op.get("security")
+    cand_sec = cand_op.get("security")
+    if not base_sec and cand_sec:
+        changes.append(
+            _change(
+                ChangeKind.SECURITY_ADDED,
+                policy,
+                path,
+                "Operation now requires security",
+                method=method,
+            )
+        )
+
+
+def _compare_operation(
+    *,
+    base_root: dict[str, Any],
+    cand_root: dict[str, Any],
+    base_op: dict[str, Any],
+    cand_op: dict[str, Any],
+    policy: PolicyName,
+    path: str,
+    method: str,
+    changes: list[Change],
+) -> None:
+    if not base_op.get("deprecated") and cand_op.get("deprecated"):
+        changes.append(
+            _change(
+                ChangeKind.OPERATION_DEPRECATED,
+                policy,
+                path,
+                "Operation marked deprecated",
+                method=method,
+            )
+        )
+
+    _compare_parameters(
+        base_root=base_root,
+        cand_root=cand_root,
+        base_op=base_op,
+        cand_op=cand_op,
+        policy=policy,
+        path=path,
+        method=method,
+        changes=changes,
+    )
+    _compare_security(base_op, cand_op, policy, path, method, changes)
+
+    base_body = _get_request_body_schema(base_root, base_op)
+    cand_body = _get_request_body_schema(cand_root, cand_op)
+    if base_body is not None and cand_body is not None:
+        _compare_schema_nodes(
+            base_root=base_root,
+            cand_root=cand_root,
+            base=base_body,
+            cand=cand_body,
+            policy=policy,
+            path=path,
+            method=method,
+            location="request",
+            changes=changes,
+        )
+    elif base_body is not None and cand_body is None:
+        changes.append(
+            _change(
+                ChangeKind.MEDIA_TYPE_REMOVED,
+                policy,
+                path,
+                "Request body removed",
+                method=method,
+            )
+        )
+
+    base_resps = _response_schemas(base_root, base_op)
+    cand_resps = _response_schemas(cand_root, cand_op)
+    for status in sorted(set(base_resps) - set(cand_resps)):
+        # ignore default-only noise somewhat
+        changes.append(
+            _change(
+                ChangeKind.RESPONSE_STATUS_REMOVED,
+                policy,
+                path,
+                f"Response status {status} removed",
+                method=method,
+                status=status,
+            )
+        )
+    for status in sorted(set(cand_resps) - set(base_resps)):
+        changes.append(
+            _change(
+                ChangeKind.RESPONSE_STATUS_ADDED,
+                policy,
+                path,
+                f"Response status {status} added",
+                method=method,
+                status=status,
+            )
+        )
+    for status in sorted(set(base_resps) & set(cand_resps)):
+        b_schema = base_resps[status]
+        c_schema = cand_resps[status]
+        if b_schema or c_schema:
+            _compare_schema_nodes(
+                base_root=base_root,
+                cand_root=cand_root,
+                base=b_schema or {},
+                cand=c_schema or {},
+                policy=policy,
+                path=path,
+                method=method,
+                location=f"response.{status}",
+                changes=changes,
+            )
+
+
+def diff_openapi(
+    base: dict[str, Any],
+    candidate: dict[str, Any],
+    *,
+    policy: PolicyName = PolicyName.ADDITIVE_FRIENDLY,
+) -> DiffResult:
+    """Compare two OpenAPI documents and classify changes."""
+    changes: list[Change] = []
+    base_paths = _paths(base)
+    cand_paths = _paths(candidate)
+
+    for path in sorted(set(base_paths) - set(cand_paths)):
+        changes.append(
+            _change(
+                ChangeKind.PATH_REMOVED,
+                policy,
+                path,
+                f"Path removed: {path}",
+            )
+        )
+    for path in sorted(set(cand_paths) - set(base_paths)):
+        changes.append(
+            _change(
+                ChangeKind.PATH_ADDED,
+                policy,
+                path,
+                f"Path added: {path}",
+            )
+        )
+
+    for path in sorted(set(base_paths) & set(cand_paths)):
+        b_item = base_paths[path] if isinstance(base_paths[path], dict) else {}
+        c_item = cand_paths[path] if isinstance(cand_paths[path], dict) else {}
+        for method in HTTP_METHODS:
+            b_op = b_item.get(method)
+            c_op = c_item.get(method)
+            b_ok = isinstance(b_op, dict)
+            c_ok = isinstance(c_op, dict)
+            if b_ok and not c_ok:
+                changes.append(
+                    _change(
+                        ChangeKind.OPERATION_REMOVED,
+                        policy,
+                        path,
+                        f"Operation removed: {method.upper()} {path}",
+                        method=method,
+                    )
+                )
+            elif c_ok and not b_ok:
+                changes.append(
+                    _change(
+                        ChangeKind.OPERATION_ADDED,
+                        policy,
+                        path,
+                        f"Operation added: {method.upper()} {path}",
+                        method=method,
+                    )
+                )
+            elif b_ok and c_ok:
+                _compare_operation(
+                    base_root=base,
+                    cand_root=candidate,
+                    base_op=b_op,
+                    cand_op=c_op,
+                    policy=policy,
+                    path=path,
+                    method=method,
+                    changes=changes,
+                )
+
+    # Component schema removals / enum-level diffs (FastAPI often uses $ref enums)
+    base_schemas = _components_schemas(base)
+    cand_schemas = _components_schemas(candidate)
+    for name in sorted(set(base_schemas) - set(cand_schemas)):
+        changes.append(
+            _change(
+                ChangeKind.SCHEMA_REMOVED,
+                policy,
+                f"#/components/schemas/{name}",
+                f"Component schema removed: {name}",
+            )
+        )
+    for name in sorted(set(base_schemas) & set(cand_schemas)):
+        b_node = base_schemas[name]
+        c_node = cand_schemas[name]
+        if not isinstance(b_node, dict) or not isinstance(c_node, dict):
+            continue
+        be = _enum_values(b_node)
+        ce = _enum_values(c_node)
+        if be is not None and ce is not None:
+            for value in sorted(be - ce, key=lambda x: str(x)):
+                changes.append(
+                    _change(
+                        ChangeKind.ENUM_VALUE_REMOVED,
+                        policy,
+                        f"#/components/schemas/{name}",
+                        f"Enum value {value!r} removed from '{name}'",
+                        value=value,
+                    )
+                )
+            for value in sorted(ce - be, key=lambda x: str(x)):
+                changes.append(
+                    _change(
+                        ChangeKind.ENUM_VALUE_ADDED,
+                        policy,
+                        f"#/components/schemas/{name}",
+                        f"Enum value {value!r} added to '{name}'",
+                        value=value,
+                    )
+                )
+        bt = _schema_type(b_node)
+        ct = _schema_type(c_node)
+        if bt and ct and bt != ct:
+            changes.append(
+                _change(
+                    ChangeKind.TYPE_CHANGED,
+                    policy,
+                    f"#/components/schemas/{name}",
+                    f"Type of '{name}' changed from {bt} to {ct}",
+                    from_type=bt,
+                    to_type=ct,
+                )
+            )
+
+    # Deduplicate identical messages
+    unique: list[Change] = []
+    seen: set[tuple[Any, ...]] = set()
+    for change in changes:
+        key = (change.kind, change.severity, change.path, change.method, change.message)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(change)
+
+    return DiffResult(
+        changes=unique,
+        base_paths=len(base_paths),
+        candidate_paths=len(cand_paths),
+        engine="python",
+    )