Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(workspace): extract bounded OpenAPI schemas (#2227)

Raghav Chamadiya9ad4733da8e9
diff --git a/packages/core/src/repowise/core/workspace/breaking_change.py b/packages/core/src/repowise/core/workspace/breaking_change.py
index 52b4b7c61..153ca0314 100644
--- a/packages/core/src/repowise/core/workspace/breaking_change.py
+++ b/packages/core/src/repowise/core/workspace/breaking_change.py
@@ -551,7 +551,10 @@ def detect_breaking_changes(
if (
prev_schema is not None
and curr_schema is not None
+ and prev_schema.comparison_ready
+ and curr_schema.comparison_ready
and prev_schema.source == curr_schema.source
+ and prev_schema.comparison_key == curr_schema.comparison_key
):
raws.extend(_diff_schemas(prev_schema, curr_schema))
diff --git a/packages/core/src/repowise/core/workspace/contract_schema.py b/packages/core/src/repowise/core/workspace/contract_schema.py
index 670e5d989..163b274e2 100644
--- a/packages/core/src/repowise/core/workspace/contract_schema.py
+++ b/packages/core/src/repowise/core/workspace/contract_schema.py
@@ -1,17 +1,8 @@
-"""Schema-level shape for a contract — the request/response field structure.
-
-A :class:`Contract` carries the *identity* of an API surface (its method + path,
-its ``service/method``, its topic). This module adds the optional *shape*: the
-fields a request or response carries, when a parser can recover them. Only the
-gRPC ``.proto`` dialect populates this today (message fields, reusing the
-existing proto parser); HTTP gains a schema when an OpenAPI spec is present — a
-new :class:`ContractSchema` ``source`` slots in without touching the consumers
-here or the breaking-change rules that read it.
-
-Kept deliberately transport-neutral so one diff engine
-(:mod:`repowise.core.workspace.breaking_change`) can reason over every schema the
-same way: a field has a ``name``, a ``type``, whether it is ``required``, and an
-optional wire ``number`` (proto) for field-number-reuse detection.
+"""Transport-neutral request and response shapes for workspace contracts.
+
+The legacy protobuf and signature sources use flat fields. OpenAPI adds optional
+wire metadata and recursive children without changing those existing serialized
+rows. Every optional attribute is omitted when absent.
"""
from __future__ import annotations
@@ -22,27 +13,41 @@ from typing import Any
@dataclass(frozen=True)
class SchemaField:
- """One field in a request or response shape.
-
- ``number`` is the proto field tag (``None`` for transports without one).
- ``repeated`` carries proto list-ness; it is informational for diffing.
- """
+ """One field or root node in a request or response shape."""
name: str
type: str
required: bool = False
number: int | None = None
repeated: bool = False
+ nullable: bool | None = None
+ enum_values: list[Any] | None = None
+ location: str | None = None
+ source_pointer: str | None = None
+ children: list[SchemaField] = field(default_factory=list)
+ items: SchemaField | None = None
def to_dict(self) -> dict[str, Any]:
- d: dict[str, Any] = {"name": self.name, "type": self.type}
+ result: dict[str, Any] = {"name": self.name, "type": self.type}
if self.required:
- d["required"] = True
+ result["required"] = True
if self.number is not None:
- d["number"] = self.number
+ result["number"] = self.number
if self.repeated:
- d["repeated"] = True
- return d
+ result["repeated"] = True
+ if self.nullable is not None:
+ result["nullable"] = self.nullable
+ if self.enum_values is not None:
+ result["enum_values"] = list(self.enum_values)
+ if self.location is not None:
+ result["location"] = self.location
+ if self.source_pointer is not None:
+ result["source_pointer"] = self.source_pointer
+ if self.children:
+ result["children"] = [child.to_dict() for child in self.children]
+ if self.items is not None:
+ result["items"] = self.items.to_dict()
+ return result
@classmethod
def from_dict(cls, data: dict[str, Any]) -> SchemaField:
@@ -52,6 +57,41 @@ class SchemaField:
required=bool(data.get("required", False)),
number=data.get("number"),
repeated=bool(data.get("repeated", False)),
+ nullable=data.get("nullable"),
+ enum_values=(list(data["enum_values"]) if "enum_values" in data else None),
+ location=data.get("location"),
+ source_pointer=data.get("source_pointer"),
+ children=[cls.from_dict(child) for child in data.get("children", [])],
+ items=cls.from_dict(data["items"]) if data.get("items") else None,
+ )
+
+
+@dataclass(frozen=True)
+class SchemaIssue:
+ """Why one request or response side was not recovered completely."""
+
+ code: str
+ side: str
+ source_pointer: str
+ detail: str = ""
+
+ def to_dict(self) -> dict[str, str]:
+ result = {
+ "code": self.code,
+ "side": self.side,
+ "source_pointer": self.source_pointer,
+ }
+ if self.detail:
+ result["detail"] = self.detail
+ return result
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> SchemaIssue:
+ return cls(
+ code=str(data.get("code", "openapi_unknown")),
+ side=str(data.get("side", "unknown")),
+ source_pointer=str(data.get("source_pointer", "")),
+ detail=str(data.get("detail", "")),
)
@@ -59,30 +99,77 @@ class SchemaField:
class ContractSchema:
"""The structured request/response shape of a contract, when recoverable.
- ``source`` records which parser produced it (``"proto"`` / ``"openapi"``) so
- a diff never compares shapes captured by two different extraction strategies
- as if they were the same fidelity.
+ The source names the producing parser. comparison_ready is false for newly
+ extracted OpenAPI schemas until the direction-aware Phase 3 rules are
+ enabled, preventing the legacy flat-field rules from overstating changes.
"""
source: str
request_fields: list[SchemaField] = field(default_factory=list)
response_fields: list[SchemaField] = field(default_factory=list)
+ source_version: str | None = None
+ comparison_key: str | None = None
+ comparison_ready: bool = True
+ request_state: str | None = None
+ response_state: str | None = None
+ request_media_type: str | None = None
+ response_media_type: str | None = None
+ response_status_code: str | None = None
+ issues: list[SchemaIssue] = field(default_factory=list)
@property
def is_empty(self) -> bool:
- return not self.request_fields and not self.response_fields
+ return (
+ not self.request_fields
+ and not self.response_fields
+ and self.source_version is None
+ and self.comparison_key is None
+ and self.comparison_ready
+ and self.request_state is None
+ and self.response_state is None
+ and self.request_media_type is None
+ and self.response_media_type is None
+ and self.response_status_code is None
+ and not self.issues
+ )
def to_dict(self) -> dict[str, Any]:
- return {
+ result: dict[str, Any] = {
"source": self.source,
- "request_fields": [f.to_dict() for f in self.request_fields],
- "response_fields": [f.to_dict() for f in self.response_fields],
+ "request_fields": [item.to_dict() for item in self.request_fields],
+ "response_fields": [item.to_dict() for item in self.response_fields],
+ }
+ optional = {
+ "source_version": self.source_version,
+ "comparison_key": self.comparison_key,
+ "request_state": self.request_state,
+ "response_state": self.response_state,
+ "request_media_type": self.request_media_type,
+ "response_media_type": self.response_media_type,
+ "response_status_code": self.response_status_code,
}
+ result.update({key: value for key, value in optional.items() if value is not None})
+ if not self.comparison_ready:
+ result["comparison_ready"] = False
+ if self.issues:
+ result["issues"] = [issue.to_dict() for issue in self.issues]
+ return result
@classmethod
def from_dict(cls, data: dict[str, Any]) -> ContractSchema:
return cls(
source=data.get("source", ""),
- request_fields=[SchemaField.from_dict(f) for f in data.get("request_fields", [])],
- response_fields=[SchemaField.from_dict(f) for f in data.get("response_fields", [])],
+ request_fields=[SchemaField.from_dict(item) for item in data.get("request_fields", [])],
+ response_fields=[
+ SchemaField.from_dict(item) for item in data.get("response_fields", [])
+ ],
+ source_version=data.get("source_version"),
+ comparison_key=data.get("comparison_key"),
+ comparison_ready=bool(data.get("comparison_ready", True)),
+ request_state=data.get("request_state"),
+ response_state=data.get("response_state"),
+ request_media_type=data.get("request_media_type"),
+ response_media_type=data.get("response_media_type"),
+ response_status_code=data.get("response_status_code"),
+ issues=[SchemaIssue.from_dict(issue) for issue in data.get("issues", [])],
)
diff --git a/packages/core/src/repowise/core/workspace/contracts.py b/packages/core/src/repowise/core/workspace/contracts.py
index 02624e01a..467f53cf9 100644
--- a/packages/core/src/repowise/core/workspace/contracts.py
+++ b/packages/core/src/repowise/core/workspace/contracts.py
@@ -50,7 +50,8 @@ CONTRACTS_FILENAME = "contracts.json"
#: Java, Kotlin and PHP client calls resolved from URL expressions.
#: A store written under an older version is readable but not reusable: its
#: rows carry no identity, and nothing short of re-extraction can give them one.
-CONTRACTS_VERSION = 7
+# Version 8 adds bounded OpenAPI 3.x schemas and their extraction diagnostics.
+CONTRACTS_VERSION = 8
# ---------------------------------------------------------------------------
@@ -891,10 +892,12 @@ async def run_contract_extraction(
DataExtractor,
GrpcExtractor,
HttpExtractor,
+ OpenApiExtractor,
SocketExtractor,
TopicExtractor,
assign_service,
detect_service_boundaries,
+ merge_openapi_providers,
)
from .extractors.base import iter_source_files, make_exclude_predicate
from .extractors.from_index import EXTRACTION_LAYER_KEY, LAYER_REGEX
@@ -1004,6 +1007,7 @@ async def run_contract_extraction(
extractors = []
if contract_config.detect_http:
extractors.append(HttpExtractor())
+ extractors.append(OpenApiExtractor())
if contract_config.detect_grpc:
extractors.append(GrpcExtractor())
if contract_config.detect_socket:
@@ -1043,11 +1047,12 @@ async def run_contract_extraction(
stats["walks"] = 1
for extractor in extractors:
- kwargs = (
- {"repo_index": repo_index, "stats": stats}
- if isinstance(extractor, HttpExtractor)
- else {}
- )
+ if isinstance(extractor, HttpExtractor):
+ kwargs = {"repo_index": repo_index, "stats": stats}
+ elif isinstance(extractor, OpenApiExtractor):
+ kwargs = {"stats": stats}
+ else:
+ kwargs = {}
found = await asyncio.to_thread(
lambda e=extractor, kw=kwargs: e.extract(
repo_path, alias, exclude, files, **kw
@@ -1065,6 +1070,11 @@ async def run_contract_extraction(
contracts.extend(code_rows)
stats.update(code_surface.stats.get(alias, {}))
+ # The OpenAPI document and a framework route describe one provider.
+ # Keep the code-backed identity and enrich it with the spec's wire shape;
+ # unmatched spec operations remain first-class providers.
+ contracts = merge_openapi_providers(contracts, stats)
+
stats.update(bind_symbol_ids(contracts, repo_index))
stats.update(attach_signature_schemas(contracts, repo_index))
diff --git a/packages/core/src/repowise/core/workspace/diagnostics.py b/packages/core/src/repowise/core/workspace/diagnostics.py
index de2ddb487..a9420fe42 100644
--- a/packages/core/src/repowise/core/workspace/diagnostics.py
+++ b/packages/core/src/repowise/core/workspace/diagnostics.py
@@ -222,6 +222,84 @@ class CodeApiCoverage:
}
+@dataclass
+class OpenApiCoverage:
+ """Bounded OpenAPI extraction coverage and explicit refusal reasons."""
+
+ documents: int = 0
+ parsed_documents: int = 0
+ unresolved_documents: int = 0
+ operations: int = 0
+ providers: int = 0
+ schemas_merged: int = 0
+ spec_only_providers: int = 0
+ request_states: dict[str, int] = field(default_factory=dict)
+ response_states: dict[str, int] = field(default_factory=dict)
+ refusal_reasons: dict[str, int] = field(default_factory=dict)
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "documents": self.documents,
+ "parsed_documents": self.parsed_documents,
+ "unresolved_documents": self.unresolved_documents,
+ "operations": self.operations,
+ "providers": self.providers,
+ "schemas_merged": self.schemas_merged,
+ "spec_only_providers": self.spec_only_providers,
+ "request_states": self.request_states,
+ "response_states": self.response_states,
+ "refusal_reasons": self.refusal_reasons,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> OpenApiCoverage:
+ return cls(
+ documents=data.get("documents", 0),
+ parsed_documents=data.get("parsed_documents", 0),
+ unresolved_documents=data.get("unresolved_documents", 0),
+ operations=data.get("operations", 0),
+ providers=data.get("providers", 0),
+ schemas_merged=data.get("schemas_merged", 0),
+ spec_only_providers=data.get("spec_only_providers", 0),
+ request_states=data.get("request_states", {}),
+ response_states=data.get("response_states", {}),
+ refusal_reasons=data.get("refusal_reasons", {}),
+ )
+
+ @classmethod
+ def from_stats(cls, stats_by_repo: dict[str, dict[str, int]]) -> OpenApiCoverage:
+ totals: dict[str, int] = {}
+ for repo_stats in stats_by_repo.values():
+ for key, value in repo_stats.items():
+ if key.startswith("openapi_"):
+ totals[key] = totals.get(key, 0) + value
+
+ def states(side: str) -> dict[str, int]:
+ prefix = f"openapi_{side}_"
+ return {
+ state: totals.get(f"{prefix}{state}", 0)
+ for state in ("complete", "partial", "unsupported", "unresolved")
+ }
+
+ reason_prefix = "openapi_reason_"
+ return cls(
+ documents=totals.get("openapi_documents", 0),
+ parsed_documents=totals.get("openapi_documents_parsed", 0),
+ unresolved_documents=totals.get("openapi_documents_unresolved", 0),
+ operations=totals.get("openapi_operations", 0),
+ providers=totals.get("openapi_providers", 0),
+ schemas_merged=totals.get("openapi_schemas_merged", 0),
+ spec_only_providers=totals.get("openapi_spec_only_providers", 0),
+ request_states=states("request"),
+ response_states=states("response"),
+ refusal_reasons={
+ key.removeprefix(reason_prefix): value
+ for key, value in sorted(totals.items())
+ if key.startswith(reason_prefix)
+ },
+ )
+
+
@dataclass
class ExtractionDiagnostics:
"""Aggregate explanation of contract extraction + matching coverage."""
@@ -248,6 +326,8 @@ class ExtractionDiagnostics:
schema_coverage: SchemaCoverage = field(default_factory=SchemaCoverage)
#: Published-package surface coverage. Reported, never asserted.
code_api: CodeApiCoverage = field(default_factory=CodeApiCoverage)
+ #: OpenAPI document, operation, per-side fidelity, and refusal coverage.
+ openapi: OpenApiCoverage = field(default_factory=OpenApiCoverage)
@property
def http_consumer_coverage(self) -> float | None:
@@ -282,12 +362,14 @@ class ExtractionDiagnostics:
"symbol_identity": {r: v.to_dict() for r, v in sorted(self.symbol_identity.items())},
"schema_coverage": self.schema_coverage.to_dict(),
"code_api": self.code_api.to_dict(),
+ "openapi": self.openapi.to_dict(),
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> ExtractionDiagnostics:
schema = data.get("schema_coverage") or {}
code = data.get("code_api") or {}
+ openapi = data.get("openapi") or {}
return cls(
total_providers=data.get("total_providers", 0),
total_consumers=data.get("total_consumers", 0),
@@ -353,6 +435,7 @@ class ExtractionDiagnostics:
consumers=code.get("consumers", 0),
linked_providers=code.get("linked_providers", 0),
),
+ openapi=OpenApiCoverage.from_dict(openapi),
)
@@ -554,4 +637,5 @@ def build_diagnostics(
symbol_identity=identity,
schema_coverage=schema,
code_api=code_api,
+ openapi=OpenApiCoverage.from_stats(stats_by_repo),
)
diff --git a/packages/core/src/repowise/core/workspace/extractors/__init__.py b/packages/core/src/repowise/core/workspace/extractors/__init__.py
index 9cdb9a3b1..e5bea2f60 100644
--- a/packages/core/src/repowise/core/workspace/extractors/__init__.py
+++ b/packages/core/src/repowise/core/workspace/extractors/__init__.py
@@ -6,6 +6,7 @@ from __future__ import annotations
from .data import DataExtractor, normalize_table_name
from .grpc_extractor import GrpcExtractor
from .http_extractor import HttpExtractor, normalize_http_path
+from .openapi import OpenApiExtractor, merge_openapi_providers
from .service_boundary import (
ServiceBoundary,
assign_service,
@@ -18,11 +19,13 @@ __all__ = [
"DataExtractor",
"GrpcExtractor",
"HttpExtractor",
+ "OpenApiExtractor",
"ServiceBoundary",
"SocketExtractor",
"TopicExtractor",
"assign_service",
"detect_service_boundaries",
+ "merge_openapi_providers",
"normalize_http_path",
"normalize_table_name",
]
diff --git a/packages/core/src/repowise/core/workspace/extractors/openapi.py b/packages/core/src/repowise/core/workspace/extractors/openapi.py
new file mode 100644
index 000000000..34b1d4057
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/extractors/openapi.py
@@ -0,0 +1,715 @@
+"""Bounded OpenAPI 3.x provider-schema extraction.
+
+This module deliberately implements only the approved common subset. It reuses
+the workspace's shared file walk, never dereferences the network, and refuses a
+whole request or response side when a construct cannot be represented faithfully.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import defaultdict
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+
+import yaml
+
+from repowise.core.workspace.contract_schema import (
+ ContractSchema,
+ SchemaField,
+ SchemaIssue,
+)
+
+from .base import SourceFile, select_files
+from .from_index import EXTRACTION_LAYER_KEY
+from .http.paths import normalize_http_path
+
+OPENAPI_SCHEMA_SOURCE = "openapi"
+OPENAPI_COMPARISON_KEY = "openapi-wire-v1"
+OPENAPI_EXTRACTION_LAYER = "openapi"
+
+_EXTENSIONS = frozenset({".json", ".yaml", ".yml"})
+_HTTP_METHODS = frozenset({"get", "put", "post", "delete", "options", "head", "patch", "trace"})
+_PARAMETER_LOCATIONS = frozenset({"path", "query", "header", "cookie"})
+_SUPPORTED_TYPES = frozenset({"object", "array", "string", "integer", "number", "boolean"})
+_VERSION_RE = re.compile(r"^3\.(0|1|2)\.\d+(?:[-+].*)?$")
+_SUCCESS_STATUS_RE = re.compile(r"^2\d\d$")
+_MAX_SCHEMA_DEPTH = 32
+
+_COMPOSITION_KEYS = frozenset({"allOf", "oneOf", "anyOf", "not"})
+_UNSUPPORTED_SCHEMA_KEYS = frozenset(
+ {
+ "additionalProperties",
+ "patternProperties",
+ "prefixItems",
+ "contains",
+ "unevaluatedProperties",
+ "unevaluatedItems",
+ "if",
+ "then",
+ "else",
+ "dependentSchemas",
+ "propertyNames",
+ "discriminator",
+ "readOnly",
+ "writeOnly",
+ "format",
+ "pattern",
+ "minimum",
+ "maximum",
+ "exclusiveMinimum",
+ "exclusiveMaximum",
+ "multipleOf",
+ "minLength",
+ "maxLength",
+ "minItems",
+ "maxItems",
+ "uniqueItems",
+ "minProperties",
+ "maxProperties",
+ }
+)
+
+
+class _Refusal(Exception): # noqa: N818 - domain outcome, not a surfaced error
+ def __init__(self, code: str, status: str, pointer: str, detail: str = "") -> None:
+ super().__init__(detail or code)
+ self.code = code
+ self.status = status
+ self.pointer = pointer
+ self.detail = detail
+
+
+def _increment(stats: dict[str, int] | None, key: str, amount: int = 1) -> None:
+ if stats is not None:
+ stats[key] = stats.get(key, 0) + amount
+
+
+def _record_reason(stats: dict[str, int] | None, code: str) -> None:
+ """Record refusal reasons separately from stable coverage counters."""
+ _increment(stats, f"openapi_reason_{code.removeprefix('openapi_')}")
+
+
+def _pointer_token(value: str) -> str:
+ return value.replace("~", "~0").replace("/", "~1")
+
+
+def _child_pointer(pointer: str, value: str) -> str:
+ return f"{pointer}/{_pointer_token(value)}"
+
+
+def _is_candidate(rel_path: str) -> bool:
+ name = rel_path.rsplit("/", 1)[-1].lower()
+ return name in {
+ "openapi.json",
+ "openapi.yaml",
+ "openapi.yml",
+ "swagger.json",
+ "swagger.yaml",
+ "swagger.yml",
+ } or any(
+ name.endswith(suffix)
+ for suffix in (".openapi.json", ".openapi.yaml", ".openapi.yml")
+ )
+
+
+def _load_document(content: str, suffix: str, rel_path: str) -> Mapping[str, Any]:
+ try:
+ value = json.loads(content) if suffix == ".json" else yaml.safe_load(content)
+ except (json.JSONDecodeError, yaml.YAMLError, RecursionError) as exc:
+ raise _Refusal("openapi_parse_error", "unresolved", rel_path, str(exc)) from exc
+ if not isinstance(value, Mapping):
+ raise _Refusal(
+ "openapi_document_not_mapping",
+ "unresolved",
+ rel_path,
+ "document root must be a mapping",
+ )
+ return value
+
+
+def _lookup_pointer(document: Mapping[str, Any], ref: str, source_pointer: str) -> Any:
+ if not ref.startswith("#/"):
+ raise _Refusal(
+ "openapi_remote_ref",
+ "unsupported",
+ source_pointer,
+ ref,
+ )
+ current: Any = document
+ for encoded in unquote(ref[2:]).split("/"):
+ token = encoded.replace("~1", "/").replace("~0", "~")
+ if isinstance(current, Mapping) and token in current:
+ current = current[token]
+ elif isinstance(current, list) and token.isdigit() and int(token) < len(current):
+ current = current[int(token)]
+ else:
+ raise _Refusal(
+ "openapi_ref_unresolved",
+ "unresolved",
+ source_pointer,
+ ref,
+ )
+ return current
+
+
+def _resolve_object(
+ document: Mapping[str, Any],
+ value: Any,
+ pointer: str,
+ seen_refs: frozenset[str] = frozenset(),
+ depth: int = 0,
+) -> tuple[Mapping[str, Any], str, frozenset[str], int]:
+ if depth > _MAX_SCHEMA_DEPTH:
+ raise _Refusal("openapi_depth_exceeded", "unresolved", pointer)
+ if not isinstance(value, Mapping):
+ raise _Refusal("openapi_object_expected", "unresolved", pointer)
+ if "$ref" not in value:
+ return value, pointer, seen_refs, depth
+ if len(value) != 1:
+ raise _Refusal("openapi_ref_siblings_unsupported", "unsupported", pointer)
+ ref = value.get("$ref")
+ if not isinstance(ref, str):
+ raise _Refusal("openapi_ref_invalid", "unresolved", pointer)
+ if ref in seen_refs:
+ raise _Refusal("openapi_ref_cycle", "unresolved", pointer, ref)
+ resolved = _lookup_pointer(document, ref, pointer)
+ return _resolve_object(document, resolved, ref, seen_refs | {ref}, depth + 1)
+
+
+def _normalized_type(
+ schema: Mapping[str, Any], version_family: str, pointer: str
+) -> tuple[str, bool]:
+ raw_type = schema.get("type")
+ nullable = False
+ if isinstance(raw_type, list):
+ if version_family == "0":
+ raise _Refusal("openapi_type_union_unsupported", "unsupported", pointer)
+ if not all(isinstance(item, str) for item in raw_type):
+ raise _Refusal("openapi_type_union_invalid", "unresolved", pointer)
+ members = list(dict.fromkeys(raw_type))
+ concrete = [item for item in members if item != "null"]
+ if len(concrete) != 1 or len(concrete) == len(members):
+ raise _Refusal("openapi_type_union_unsupported", "unsupported", pointer)
+ raw_type = concrete[0]
+ nullable = True
+ if not isinstance(raw_type, str):
+ raise _Refusal("openapi_type_missing", "unresolved", pointer)
+ if raw_type not in _SUPPORTED_TYPES:
+ raise _Refusal("openapi_type_unsupported", "unsupported", pointer, raw_type)
+ if version_family == "0":
+ raw_nullable = schema.get("nullable", False)
+ if not isinstance(raw_nullable, bool):
+ raise _Refusal("openapi_nullable_invalid", "unresolved", pointer)
+ nullable = raw_nullable
+ elif "nullable" in schema:
+ raise _Refusal("openapi_nullable_keyword_unsupported", "unsupported", pointer)
+ return raw_type, nullable
+
+
+def _value_matches_type(value: Any, type_name: str) -> bool:
+ if value is None:
+ return False
+ if type_name == "string":
+ return isinstance(value, str)
+ if type_name == "boolean":
+ return isinstance(value, bool)
+ if type_name == "integer":
+ return isinstance(value, int) and not isinstance(value, bool)
+ if type_name == "number":
+ return isinstance(value, (int, float)) and not isinstance(value, bool)
+ return False
+
+
+def _enum_values(
+ schema: Mapping[str, Any], type_name: str, nullable: bool, pointer: str
+) -> list[Any] | None:
+ if "enum" not in schema:
+ return None
+ raw = schema["enum"]
+ if not isinstance(raw, list):
+ raise _Refusal("openapi_enum_invalid", "unresolved", pointer)
+ if type_name not in {"string", "integer", "number", "boolean"}:
+ raise _Refusal("openapi_enum_unsupported", "unsupported", pointer)
+ for value in raw:
+ if value is None and nullable:
+ continue
+ if not _value_matches_type(value, type_name):
+ raise _Refusal("openapi_enum_mixed_types", "unsupported", pointer)
+ return list(raw)
+
+
+def _parse_schema_node(
+ document: Mapping[str, Any],
+ value: Any,
+ *,
+ name: str,
+ required: bool,
+ location: str | None,
+ pointer: str,
+ version_family: str,
+ seen_refs: frozenset[str] = frozenset(),
+ depth: int = 0,
+) -> SchemaField:
+ schema, resolved_pointer, seen_refs, depth = _resolve_object(
+ document, value, pointer, seen_refs, depth
+ )
+ composition = sorted(_COMPOSITION_KEYS.intersection(schema))
+ if composition:
+ raise _Refusal(
+ "openapi_composition_unsupported",
+ "unsupported",
+ _child_pointer(resolved_pointer, composition[0]),
+ composition[0],
+ )
+ unsupported = sorted(_UNSUPPORTED_SCHEMA_KEYS.intersection(schema))
+ if unsupported:
+ raise _Refusal(
+ "openapi_schema_keyword_unsupported",
+ "unsupported",
+ _child_pointer(resolved_pointer, unsupported[0]),
+ unsupported[0],
+ )
+
+ type_name, nullable = _normalized_type(schema, version_family, resolved_pointer)
+ enum_values = _enum_values(schema, type_name, nullable, resolved_pointer)
+ children: list[SchemaField] = []
+ items: SchemaField | None = None
+
+ if type_name == "object":
+ properties = schema.get("properties", {})
+ required_names = schema.get("required", [])
+ if not isinstance(properties, Mapping):
+ raise _Refusal("openapi_properties_invalid", "unresolved", resolved_pointer)
+ if not isinstance(required_names, list) or not all(
+ isinstance(item, str) for item in required_names
+ ):
+ raise _Refusal("openapi_required_invalid", "unresolved", resolved_pointer)
+ unknown_required = set(required_names).difference(properties)
+ if unknown_required:
+ raise _Refusal(
+ "openapi_required_property_unresolved",
+ "unresolved",
+ resolved_pointer,
+ sorted(unknown_required)[0],
+ )
+ for child_name, child_schema in properties.items():
+ if not isinstance(child_name, str):
+ raise _Refusal("openapi_property_name_invalid", "unresolved", resolved_pointer)
+ children.append(
+ _parse_schema_node(
+ document,
+ child_schema,
+ name=child_name,
+ required=child_name in required_names,
+ location=None,
+ pointer=_child_pointer(
+ _child_pointer(resolved_pointer, "properties"), child_name
+ ),
+ version_family=version_family,
+ seen_refs=seen_refs,
+ depth=depth + 1,
+ )
+ )
+ elif type_name == "array":
+ if "items" not in schema:
+ raise _Refusal("openapi_array_items_missing", "unresolved", resolved_pointer)
+ items = _parse_schema_node(
+ document,
+ schema["items"],
+ name="$items",
+ required=True,
+ location=None,
+ pointer=_child_pointer(resolved_pointer, "items"),
+ version_family=version_family,
+ seen_refs=seen_refs,
+ depth=depth + 1,
+ )
+
+ return SchemaField(
+ name=name,
+ type=type_name,
+ required=required,
+ nullable=nullable,
+ enum_values=enum_values,
+ location=location,
+ source_pointer=resolved_pointer,
+ children=children,
+ items=items,
+ )
+
+
+def _parameter_entries(
+ document: Mapping[str, Any],
+ path_item: Mapping[str, Any],
+ operation: Mapping[str, Any],
+ pointer: str,
+) -> list[tuple[Mapping[str, Any], str]]:
+ merged: dict[tuple[str, str], tuple[Mapping[str, Any], str]] = {}
+ for owner, owner_pointer in ((path_item, pointer.rsplit("/", 1)[0]), (operation, pointer)):
+ raw_parameters = owner.get("parameters", [])
+ if not isinstance(raw_parameters, list):
+ raise _Refusal("openapi_parameters_invalid", "unresolved", owner_pointer)
+ for index, raw in enumerate(raw_parameters):
+ item_pointer = _child_pointer(_child_pointer(owner_pointer, "parameters"), str(index))
+ parameter, resolved_pointer, _, _ = _resolve_object(document, raw, item_pointer)
+ name = parameter.get("name")
+ location = parameter.get("in")
+ if not isinstance(name, str) or not isinstance(location, str):
+ raise _Refusal("openapi_parameter_identity_invalid", "unresolved", resolved_pointer)
+ merged[(location, name)] = (parameter, resolved_pointer)
+ return list(merged.values())
+
+
+def _build_request(
+ document: Mapping[str, Any],
+ path_item: Mapping[str, Any],
+ operation: Mapping[str, Any],
+ pointer: str,
+ version_family: str,
+) -> tuple[list[SchemaField], str | None]:
+ fields: list[SchemaField] = []
+ for parameter, parameter_pointer in _parameter_entries(document, path_item, operation, pointer):
+ location = str(parameter["in"])
+ if location not in _PARAMETER_LOCATIONS:
+ raise _Refusal(
+ "openapi_parameter_location_unsupported",
+ "unsupported",
+ parameter_pointer,
+ location,
+ )
+ if "content" in parameter:
+ raise _Refusal(
+ "openapi_parameter_content_unsupported", "unsupported", parameter_pointer
+ )
+ if "schema" not in parameter:
+ raise _Refusal("openapi_parameter_schema_missing", "unresolved", parameter_pointer)
+ required = bool(parameter.get("required", False))
+ if location == "path" and not required:
+ raise _Refusal("openapi_path_parameter_optional", "unresolved", parameter_pointer)
+ fields.append(
+ _parse_schema_node(
+ document,
+ parameter["schema"],
+ name=str(parameter["name"]),
+ required=required,
+ location=location,
+ pointer=_child_pointer(parameter_pointer, "schema"),
+ version_family=version_family,
+ )
+ )
+
+ if "requestBody" not in operation:
+ return fields, None
+ body_pointer = _child_pointer(pointer, "requestBody")
+ body, body_pointer, _, _ = _resolve_object(document, operation["requestBody"], body_pointer)
+ content = body.get("content")
+ if not isinstance(content, Mapping) or not content:
+ raise _Refusal("openapi_request_content_missing", "unresolved", body_pointer)
+ if "application/json" not in content:
+ raise _Refusal("openapi_media_type_unsupported", "unsupported", body_pointer)
+ if len(content) != 1:
+ raise _Refusal("openapi_media_type_ambiguous", "unsupported", body_pointer)
+ media = content["application/json"]
+ if not isinstance(media, Mapping) or "schema" not in media:
+ raise _Refusal("openapi_request_schema_missing", "unresolved", body_pointer)
+ fields.append(
+ _parse_schema_node(
+ document,
+ media["schema"],
+ name="$body",
+ required=bool(body.get("required", False)),
+ location="body",
+ pointer=_child_pointer(
+ _child_pointer(_child_pointer(body_pointer, "content"), "application/json"),
+ "schema",
+ ),
+ version_family=version_family,
+ )
+ )
+ return fields, "application/json"
+
+
+def _build_response(
+ document: Mapping[str, Any], operation: Mapping[str, Any], pointer: str, version_family: str
+) -> tuple[list[SchemaField], str | None, str]:
+ responses = operation.get("responses")
+ if not isinstance(responses, Mapping):
+ raise _Refusal("openapi_responses_missing", "unresolved", pointer)
+ successes = [
+ (str(code), value)
+ for code, value in responses.items()
+ if _SUCCESS_STATUS_RE.fullmatch(str(code))
+ ]
+ if len(successes) != 1:
+ code = (
+ "openapi_success_response_missing"
+ if not successes
+ else "openapi_success_response_ambiguous"
+ )
+ raise _Refusal(code, "unresolved", _child_pointer(pointer, "responses"))
+ status_code, raw_response = successes[0]
+ response_pointer = _child_pointer(_child_pointer(pointer, "responses"), status_code)
+ response, response_pointer, _, _ = _resolve_object(document, raw_response, response_pointer)
+ content = response.get("content")
+ if not isinstance(content, Mapping) or not content:
+ raise _Refusal("openapi_response_content_missing", "unresolved", response_pointer)
+ if "application/json" not in content:
+ raise _Refusal("openapi_media_type_unsupported", "unsupported", response_pointer)
+ if len(content) != 1:
+ raise _Refusal("openapi_media_type_ambiguous", "unsupported", response_pointer)
+ media = content["application/json"]
+ if not isinstance(media, Mapping) or "schema" not in media:
+ raise _Refusal("openapi_response_schema_missing", "unresolved", response_pointer)
+ root = _parse_schema_node(
+ document,
+ media["schema"],
+ name="$response",
+ required=True,
+ location="body",
+ pointer=_child_pointer(
+ _child_pointer(_child_pointer(response_pointer, "content"), "application/json"),
+ "schema",
+ ),
+ version_family=version_family,
+ )
+ return [root], "application/json", status_code
+
+
+def _capture_side(
+ side: str,
+ builder: Callable[[], tuple[list[SchemaField], ...]],
+ stats: dict[str, int] | None,
+) -> tuple[tuple[Any, ...], str, list[SchemaIssue]]:
+ try:
+ result = builder()
+ except _Refusal as exc:
+ _increment(stats, f"openapi_{side}_{exc.status}")
+ _record_reason(stats, exc.code)
+ issue = SchemaIssue(exc.code, side, exc.pointer, exc.detail)
+ return ([],), exc.status, [issue]
+ _increment(stats, f"openapi_{side}_complete")
+ return result, "complete", []
+
+
+def _operation_contract(
+ document: Mapping[str, Any],
+ version: str,
+ version_family: str,
+ rel_path: str,
+ repo_alias: str,
+ path: str,
+ method: str,
+ path_item: Mapping[str, Any],
+ operation: Mapping[str, Any],
+ stats: dict[str, int] | None,
+) -> Any:
+ from repowise.core.workspace.contracts import Contract
+
+ operation_pointer = f"#/paths/{_pointer_token(path)}/{method}"
+ request_result, request_state, request_issues = _capture_side(
+ "request",
+ lambda: _build_request(document, path_item, operation, operation_pointer, version_family),
+ stats,
+ )
+ response_result, response_state, response_issues = _capture_side(
+ "response",
+ lambda: _build_response(document, operation, operation_pointer, version_family),
+ stats,
+ )
+ request_fields = request_result[0]
+ request_media_type = request_result[1] if len(request_result) > 1 else None
+ response_fields = response_result[0]
+ response_media_type = response_result[1] if len(response_result) > 1 else None
+ response_status_code = response_result[2] if len(response_result) > 2 else None
+ normalized_path = normalize_http_path(path)
+ return Contract(
+ repo=repo_alias,
+ contract_id=f"http::{method.upper()}::{normalized_path}",
+ contract_type="http",
+ role="provider",
+ file_path=rel_path,
+ symbol_name=f"openapi:{method.upper()} {path}",
+ confidence=0.98,
+ meta={
+ EXTRACTION_LAYER_KEY: OPENAPI_EXTRACTION_LAYER,
+ "openapi_version": version,
+ "schema_source_file": rel_path,
+ "schema_operation_pointer": operation_pointer,
+ },
+ schema=ContractSchema(
+ source=OPENAPI_SCHEMA_SOURCE,
+ request_fields=request_fields,
+ response_fields=response_fields,
+ source_version=version,
+ comparison_key=OPENAPI_COMPARISON_KEY,
+ comparison_ready=False,
+ request_state=request_state,
+ response_state=response_state,
+ request_media_type=request_media_type,
+ response_media_type=response_media_type,
+ response_status_code=response_status_code,
+ issues=request_issues + response_issues,
+ ),
+ )
+
+
+class OpenApiExtractor:
+ """Extract HTTP provider contracts and wire shapes from OpenAPI 3.x files."""
+
+ @classmethod
+ def source_extensions(cls) -> frozenset[str]:
+ return _EXTENSIONS
+
+ def extract(
+ self,
+ repo_path: Path,
+ repo_alias: str = "",
+ exclude: Callable[[str], bool] | None = None,
+ files: Sequence[SourceFile] | None = None,
+ stats: dict[str, int] | None = None,
+ ) -> list[Any]:
+ contracts: list[Any] = []
+ for rel_path, suffix, content in select_files(repo_path, _EXTENSIONS, exclude, files):
+ if not _is_candidate(rel_path):
+ continue
+ _increment(stats, "openapi_documents")
+ try:
+ document = _load_document(content, suffix, rel_path)
+ version = document.get("openapi")
+ match = _VERSION_RE.fullmatch(version) if isinstance(version, str) else None
+ if match is None:
+ raise _Refusal(
+ "openapi_version_unsupported",
+ "unsupported",
+ f"{rel_path}#/openapi",
+ str(version or "missing"),
+ )
+ paths = document.get("paths")
+ if not isinstance(paths, Mapping):
+ raise _Refusal("openapi_paths_missing", "unresolved", f"{rel_path}#/paths")
+ except _Refusal as exc:
+ _increment(stats, "openapi_documents_unresolved")
+ _record_reason(stats, exc.code)
+ continue
+
+ _increment(stats, "openapi_documents_parsed")
+ for path, raw_path_item in paths.items():
+ if not isinstance(path, str) or not path.startswith("/"):
+ _record_reason(stats, "openapi_path_unsupported")
+ continue
+ path_pointer = f"#/paths/{_pointer_token(path)}"
+ try:
+ path_item, _, _, _ = _resolve_object(document, raw_path_item, path_pointer)
+ except _Refusal as exc:
+ _record_reason(stats, exc.code)
+ continue
+ for method, raw_operation in path_item.items():
+ method_text = str(method).lower()
+ if method_text not in _HTTP_METHODS:
+ continue
+ if not isinstance(raw_operation, Mapping):
+ _record_reason(stats, "openapi_operation_invalid")
+ continue
+ contracts.append(
+ _operation_contract(
+ document,
+ version,
+ match.group(1),
+ rel_path,
+ repo_alias,
+ path,
+ method_text,
+ path_item,
+ raw_operation,
+ stats,
+ )
+ )
+ _increment(stats, "openapi_operations")
+ _increment(stats, "openapi_providers", len(contracts))
+ return contracts
+
+
+def merge_openapi_providers(contracts: list[Any], stats: dict[str, int]) -> list[Any]:
+ """Attach each unambiguous spec schema to one matching code provider."""
+ from repowise.core.workspace.contracts import normalize_contract_id
+
+ def spec_key(contract: Any) -> tuple[str, str | None, str]:
+ return (contract.repo, contract.service, normalize_contract_id(contract.contract_id))
+
+ def route_key(contract: Any) -> tuple[str, str]:
+ return (contract.repo, normalize_contract_id(contract.contract_id))
+
+ source_rows: list[Any] = []
+ spec_groups: dict[tuple[str, str | None, str], list[Any]] = defaultdict(list)
+ for contract in contracts:
+ if contract.schema is not None and contract.schema.source == OPENAPI_SCHEMA_SOURCE:
+ spec_groups[spec_key(contract)].append(contract)
+ else:
+ source_rows.append(contract)
+
+ providers: dict[tuple[str, str], list[Any]] = defaultdict(list)
+ for contract in source_rows:
+ if contract.role == "provider" and contract.contract_type == "http":
+ providers[route_key(contract)].append(contract)
+
+ retained_specs: list[Any] = []
+ for group_key, rows in spec_groups.items():
+ selected = rows[0]
+ if len(rows) > 1:
+ _increment(stats, "openapi_duplicate_operation", len(rows) - 1)
+ shapes = {json.dumps(row.schema.to_dict(), sort_keys=True) for row in rows}
+ if len(shapes) > 1:
+ selected.schema = ContractSchema(
+ source=OPENAPI_SCHEMA_SOURCE,
+ source_version=selected.schema.source_version,
+ comparison_key=OPENAPI_COMPARISON_KEY,
+ comparison_ready=False,
+ request_state="unresolved",
+ response_state="unresolved",
+ issues=[
+ SchemaIssue(
+ "openapi_duplicate_operation_conflict",
+ "both",
+ str(selected.meta.get("schema_operation_pointer", "")),
+ )
+ ],
+ )
+ _record_reason(stats, "openapi_duplicate_operation_conflict")
+
+ repo, service, normalized_id = group_key
+ targets = providers.get((repo, normalized_id), [])
+ if service is not None:
+ targets = [target for target in targets if target.service == service]
+ if not targets:
+ retained_specs.append(selected)
+ _increment(stats, "openapi_spec_only_providers")
+ continue
+ if len(targets) > 1:
+ retained_specs.append(selected)
+ _record_reason(stats, "openapi_provider_ambiguous")
+ continue
+ target = targets[0]
+ if target.schema is not None:
+ retained_specs.append(selected)
+ _record_reason(stats, "openapi_existing_schema_conflict")
+ continue
+ target.schema = selected.schema
+ target.meta["schema_source_file"] = selected.file_path
+ target.meta["schema_operation_pointer"] = selected.meta.get(
+ "schema_operation_pointer", ""
+ )
+ target.meta["openapi_version"] = selected.meta.get("openapi_version", "")
+ _increment(stats, "openapi_schemas_merged")
+ return source_rows + retained_specs
+
+
+__all__ = [
+ "OPENAPI_COMPARISON_KEY",
+ "OPENAPI_SCHEMA_SOURCE",
+ "OpenApiExtractor",
+ "merge_openapi_providers",
+]
diff --git a/tests/fixtures/openapi_contracts/compatible-3.0-before.yaml b/tests/fixtures/openapi_contracts/compatible-3.0-before.yaml
new file mode 100644
index 000000000..3f9c3ce7d
--- /dev/null
+++ b/tests/fixtures/openapi_contracts/compatible-3.0-before.yaml
@@ -0,0 +1,32 @@
+openapi: 3.0.4
+info: {title: Orders, version: '1'}
+paths:
+ /orders:
+ post:
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: {$ref: '#/components/schemas/OrderCreate'}
+ responses:
+ '201':
+ description: created
+ content:
+ application/json:
+ schema: {$ref: '#/components/schemas/Order'}
+components:
+ schemas:
+ OrderCreate:
+ type: object
+ required: [sku]
+ properties:
+ sku: {type: string}
+ priority: {type: string, enum: [standard, express]}
+ note: {type: string}
+ Order:
+ type: object
+ required: [id, status]
+ properties:
+ id: {type: string}
+ status: {type: string, enum: [pending, complete]}
+ note: {type: string, nullable: true}
diff --git a/tests/fixtures/openapi_contracts/compatible-3.1-after.yaml b/tests/fixtures/openapi_contracts/compatible-3.1-after.yaml
new file mode 100644
index 000000000..9c04cbffe
--- /dev/null
+++ b/tests/fixtures/openapi_contracts/compatible-3.1-after.yaml
@@ -0,0 +1,21 @@
+openapi: 3.1.2
+info: {title: Notes, version: '2'}
+paths:
+ /notes:
+ post:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ note: {type: [string, 'null']}
+ responses:
+ '200':
+ description: ok
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ note: {type: string}
diff --git a/tests/fixtures/openapi_contracts/parameters-3.0.yaml b/tests/fixtures/openapi_contracts/parameters-3.0.yaml
new file mode 100644
index 000000000..de1d180a7
--- /dev/null
+++ b/tests/fixtures/openapi_contracts/parameters-3.0.yaml
@@ -0,0 +1,30 @@
+openapi: 3.0.3
+info: {title: Parameter merge, version: '1'}
+paths:
+ /users/{userId}:
+ parameters:
+ - {$ref: '#/components/parameters/UserId'}
+ - {name: trace, in: header, schema: {type: string}}
+ get:
+ parameters:
+ - {name: trace, in: header, required: true, schema: {type: string}}
+ - {name: verbose, in: query, schema: {type: boolean}}
+ responses:
+ '200':
+ description: ok
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ required: [id]
+ properties:
+ id: {type: integer}
+components:
+ parameters:
+ UserId:
+ name: userId
+ in: path
+ required: true
+ schema: {type: string}
diff --git a/tests/fixtures/openapi_contracts/unresolved-3.2.yaml b/tests/fixtures/openapi_contracts/unresolved-3.2.yaml
new file mode 100644
index 000000000..3a0d9fac3
--- /dev/null
+++ b/tests/fixtures/openapi_contracts/unresolved-3.2.yaml
@@ -0,0 +1,44 @@
+openapi: 3.2.0
+info: {title: Unsupported cases, version: '1'}
+paths:
+ /remote:
+ get:
+ responses:
+ '200':
+ description: remote reference
+ content:
+ application/json:
+ schema: {$ref: 'https://example.invalid/schemas.json#/User'}
+ /choice:
+ post:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - {type: string}
+ - {type: integer}
+ responses:
+ '204': {description: no content}
+ /tree:
+ get:
+ responses:
+ '200':
+ description: cyclic local reference
+ content:
+ application/json:
+ schema: {$ref: '#/components/schemas/Node'}
+ /xml:
+ get:
+ responses:
+ '200':
+ description: unsupported media type
+ content:
+ application/xml:
+ schema: {type: string}
+components:
+ schemas:
+ Node:
+ type: object
+ properties:
+ child: {$ref: '#/components/schemas/Node'}
diff --git a/tests/unit/workspace/test_breaking_change.py b/tests/unit/workspace/test_breaking_change.py
index c287cf3ac..65cf1cd98 100644
--- a/tests/unit/workspace/test_breaking_change.py
+++ b/tests/unit/workspace/test_breaking_change.py
@@ -64,6 +64,38 @@ def _schema(request=None, response=None):
)
+def test_schema_diff_waits_until_source_declares_comparison_ready():
+ before = ContractSchema(
+ source="openapi",
+ request_fields=[SchemaField("id", "string", required=True)],
+ comparison_ready=False,
+ )
+ after = ContractSchema(source="openapi", comparison_ready=False)
+
+ report = detect_breaking_changes(
+ _store([_provider("http::POST::/orders", schema=before)]),
+ _store([_provider("http::POST::/orders", schema=after)]),
+ )
+
+ assert report.changes == []
+
+
+def test_schema_diff_requires_matching_comparison_fidelity():
+ before = ContractSchema(
+ source="openapi",
+ comparison_key="openapi-wire-v1",
+ request_fields=[SchemaField("id", "string", required=True)],
+ )
+ after = ContractSchema(source="openapi", comparison_key="openapi-wire-v2")
+
+ report = detect_breaking_changes(
+ _store([_provider("http::POST::/orders", schema=before)]),
+ _store([_provider("http::POST::/orders", schema=after)]),
+ )
+
+ assert report.changes == []
+
+
def _kinds(report):
return sorted(c.kind for c in report.changes)
diff --git a/tests/unit/workspace/test_openapi_extractor.py b/tests/unit/workspace/test_openapi_extractor.py
new file mode 100644
index 000000000..9466cd7bf
--- /dev/null
+++ b/tests/unit/workspace/test_openapi_extractor.py
@@ -0,0 +1,267 @@
+"""Focused coverage for bounded OpenAPI 3.x schema extraction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.core.workspace import contracts as contracts_module
+from repowise.core.workspace.config import ContractConfig, RepoEntry, WorkspaceConfig
+from repowise.core.workspace.contract_schema import ContractSchema, SchemaField
+from repowise.core.workspace.contracts import Contract, run_contract_extraction
+from repowise.core.workspace.diagnostics import ExtractionDiagnostics, OpenApiCoverage
+from repowise.core.workspace.extractors.openapi import (
+ OpenApiExtractor,
+ merge_openapi_providers,
+)
+
+FIXTURES = Path(__file__).parents[2] / "fixtures" / "openapi_contracts"
+
+
+def _extract(name: str) -> tuple[list[Contract], dict[str, int]]:
+ content = (FIXTURES / name).read_text(encoding="utf-8")
+ stats: dict[str, int] = {}
+ rows = OpenApiExtractor().extract(
+ Path("."), "api", files=[("openapi.yaml", ".yaml", content)], stats=stats
+ )
+ return rows, stats
+
+
+def _field(fields: list[SchemaField], name: str) -> SchemaField:
+ return next(item for item in fields if item.name == name)
+
+
+def test_openapi_30_recovers_recursive_shapes_enums_and_provenance() -> None:
+ rows, stats = _extract("compatible-3.0-before.yaml")
+
+ assert len(rows) == 1
+ row = rows[0]
+ assert row.contract_id == "http::POST::/orders"
+ assert row.meta["schema_operation_pointer"] == "#/paths/~1orders/post"
+ assert row.schema is not None
+ assert row.schema.source_version == "3.0.4"
+ assert row.schema.comparison_ready is False
+ assert row.schema.request_state == row.schema.response_state == "complete"
+
+ body = row.schema.request_fields[0]
+ assert body.type == "object"
+ assert _field(body.children, "sku").required is True
+ assert _field(body.children, "priority").enum_values == ["standard", "express"]
+ assert _field(row.schema.response_fields[0].children, "note").nullable is True
+ assert stats == {
+ "openapi_documents": 1,
+ "openapi_documents_parsed": 1,
+ "openapi_request_complete": 1,
+ "openapi_response_complete": 1,
+ "openapi_operations": 1,
+ "openapi_providers": 1,
+ }
+
+
+def test_openapi_31_normalizes_union_nullability() -> None:
+ rows, _ = _extract("compatible-3.1-after.yaml")
+
+ schema = rows[0].schema
+ assert schema is not None
+ note = _field(schema.request_fields[0].children, "note")
+ assert (note.type, note.nullable) == ("string", True)
+
+
+def test_parameters_merge_by_location_and_operation_overrides_path_item() -> None:
+ rows, _ = _extract("parameters-3.0.yaml")
+
+ schema = rows[0].schema
+ assert schema is not None
+ assert [(field.location, field.name) for field in schema.request_fields] == [
+ ("path", "userId"),
+ ("header", "trace"),
+ ("query", "verbose"),
+ ]
+ assert _field(schema.request_fields, "trace").required is True
+ response = schema.response_fields[0]
+ assert response.type == "array"
+ assert response.items is not None
+ assert _field(response.items.children, "id").type == "integer"
+
+
+def test_unsupported_constructs_refuse_only_the_affected_side() -> None:
+ rows, stats = _extract("unresolved-3.2.yaml")
+
+ assert len(rows) == 4
+ by_path = {row.contract_id: row.schema for row in rows}
+ assert by_path["http::GET::/remote"].response_state == "unsupported"
+ assert by_path["http::POST::/choice"].request_state == "unsupported"
+ assert by_path["http::POST::/choice"].response_state == "unresolved"
+ assert by_path["http::GET::/tree"].response_state == "unresolved"
+ assert by_path["http::GET::/xml"].response_state == "unsupported"
+ assert {
+ issue.code
+ for schema in by_path.values()
+ if schema
+ for issue in schema.issues
+ } == {
+ "openapi_remote_ref",
+ "openapi_composition_unsupported",
+ "openapi_response_content_missing",
+ "openapi_ref_cycle",
+ "openapi_media_type_unsupported",
+ }
+ coverage = OpenApiCoverage.from_stats({"api": stats})
+ assert coverage.operations == 4
+ assert coverage.response_states == {
+ "complete": 0,
+ "partial": 0,
+ "unsupported": 2,
+ "unresolved": 2,
+ }
+ assert coverage.refusal_reasons["remote_ref"] == 1
+ payload = ExtractionDiagnostics(openapi=coverage).to_dict()
+ assert ExtractionDiagnostics.from_dict(payload).openapi == coverage
+
+
+def test_legacy_schema_serialization_is_unchanged_and_new_shape_round_trips() -> None:
+ legacy = ContractSchema(
+ source="proto", request_fields=[SchemaField("id", "string", required=True)]
+ )
+ assert legacy.to_dict() == {
+ "source": "proto",
+ "request_fields": [{"name": "id", "type": "string", "required": True}],
+ "response_fields": [],
+ }
+
+ rows, _ = _extract("compatible-3.0-before.yaml")
+ schema_payload = rows[0].schema.to_dict()
+ assert ContractSchema.from_dict(schema_payload).to_dict() == schema_payload
+ contract_payload = rows[0].to_dict()
+ assert Contract.from_dict(contract_payload).to_dict() == contract_payload
+
+
+def test_merge_enriches_code_provider_and_keeps_spec_only_operations() -> None:
+ spec_rows, _ = _extract("compatible-3.0-before.yaml")
+ spec = spec_rows[0]
+ code = Contract(
+ repo="api",
+ contract_id=spec.contract_id,
+ contract_type="http",
+ role="provider",
+ file_path="src/orders.py",
+ symbol_name="create_order",
+ confidence=0.9,
+ )
+ extra = Contract.from_dict(spec.to_dict())
+ extra.contract_id = "http::GET::/health"
+ stats: dict[str, int] = {}
+
+ merged = merge_openapi_providers([code, spec, extra], stats)
+
+ assert merged == [code, extra]
+ assert code.schema == spec.schema
+ assert code.meta["schema_source_file"] == "openapi.yaml"
+ assert stats == {"openapi_schemas_merged": 1, "openapi_spec_only_providers": 1}
+
+
+def test_merge_retains_spec_when_multiple_code_providers_are_ambiguous() -> None:
+ spec = _extract("compatible-3.0-before.yaml")[0][0]
+ providers = [
+ Contract(
+ repo="api",
+ contract_id=spec.contract_id,
+ contract_type="http",
+ role="provider",
+ file_path=f"services/{name}/orders.py",
+ symbol_name="create_order",
+ confidence=0.9,
+ service=name,
+ )
+ for name in ("one", "two")
+ ]
+ stats: dict[str, int] = {}
+
+ merged = merge_openapi_providers([*providers, spec], stats)
+
+ assert merged == [*providers, spec]
+ assert all(provider.schema is None for provider in providers)
+ assert stats == {"openapi_reason_provider_ambiguous": 1}
+
+
+def test_non_candidates_and_openapi_2_are_not_extracted() -> None:
+ stats: dict[str, int] = {}
+ rows = OpenApiExtractor().extract(
+ Path("."),
+ "api",
+ files=[
+ ("schema.yaml", ".yaml", "openapi: 3.0.0\npaths: {}\n"),
+ ("swagger.json", ".json", '{"swagger": "2.0", "paths": {}}'),
+ ],
+ stats=stats,
+ )
+
+ assert rows == []
+ assert stats["openapi_documents"] == 1
+ assert stats["openapi_documents_unresolved"] == 1
+ assert stats["openapi_reason_version_unsupported"] == 1
+
+
+def test_malformed_union_and_excessive_parse_depth_become_diagnostics() -> None:
+ malformed_union = """
+openapi: 3.1.0
+paths:
+ /bad:
+ get:
+ responses:
+ '200':
+ description: bad union
+ content:
+ application/json:
+ schema: {type: [string, {bad: value}]}
+"""
+ stats: dict[str, int] = {}
+ rows = OpenApiExtractor().extract(
+ Path("."),
+ "api",
+ files=[("openapi.yaml", ".yaml", malformed_union)],
+ stats=stats,
+ )
+ assert rows[0].schema.response_state == "unresolved"
+ assert rows[0].schema.issues[0].code == "openapi_type_union_invalid"
+
+ deep_stats: dict[str, int] = {}
+ deep_yaml = "openapi: 3.1.0\npaths: " + "[" * 3000 + "]" * 3000
+ assert (
+ OpenApiExtractor().extract(
+ Path("."),
+ "api",
+ files=[("openapi.yaml", ".yaml", deep_yaml)],
+ stats=deep_stats,
+ )
+ == []
+ )
+ assert deep_stats["openapi_reason_parse_error"] == 1
+
+
+async def test_workspace_orchestrator_extracts_openapi_in_its_single_repo_walk(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ api = tmp_path / "api"
+ web = tmp_path / "web"
+ for repo in (api, web):
+ (repo / ".repowise").mkdir(parents=True)
+ (api / "openapi.yaml").write_text(
+ (FIXTURES / "compatible-3.0-before.yaml").read_text(encoding="utf-8"),
+ encoding="utf-8",
+ )
+ config = WorkspaceConfig(
+ repos=[RepoEntry(path="api", alias="api"), RepoEntry(path="web", alias="web")],
+ contracts=ContractConfig(),
+ )
+ monkeypatch.setattr(contracts_module, "save_contract_store", lambda store, root: root)
+
+ store = await run_contract_extraction(config, tmp_path, [])
+
+ provider = next(row for row in store.contracts if row.contract_id == "http::POST::/orders")
+ assert provider.schema is not None
+ assert provider.schema.source == "openapi"
+ assert store.extraction_stats["api"]["walks"] == 1
+ assert store.extraction_stats["api"]["openapi_documents_parsed"] == 1
diff --git a/tests/unit/workspace/test_system_graph.py b/tests/unit/workspace/test_system_graph.py
index 5a7c88587..abfb679e1 100644
--- a/tests/unit/workspace/test_system_graph.py
+++ b/tests/unit/workspace/test_system_graph.py
@@ -322,6 +322,7 @@ def test_system_graph_json_shape_is_locked():
"http_consumer_coverage",
"symbol_identity",
"schema_coverage",
+ "openapi",
"code_api",
}