ramp-tool-openapi 0.1.1__tar.gz

ramp_tool_openapi-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.uv-cache/
+build/
+dist/
+*.egg-info/

ramp_tool_openapi-0.1.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright © 2026 Ramp Business Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ramp_tool_openapi-0.1.1/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: ramp-tool-openapi
+Version: 0.1.1
+Summary: Shared OpenAPI normalization for Ramp tool surfaces
+Author-email: Ramp <developer@ramp.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: openapi,tooling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ramp-tool-openapi
+
+Shared, dependency-free OpenAPI normalization for Ramp tool surfaces.
+
+## Installation
+
+```bash
+pip install ramp-tool-openapi
+```
+
+The current package requires Python 3.11 or newer.
+
+## What is this?
+
+`ramp-tool-openapi` is the shared normalization boundary between Ramp OpenAPI
+specifications and downstream tool adapters. It accepts an already-loaded OpenAPI
+document and returns neutral `ParsedOperation` objects that consumers translate
+into their own representations.
+
+This gives Ramp tool consumers:
+
+- one implementation of shared OpenAPI parsing rules
+- consistent local `$ref`, parameter, request, response, operation-level OAuth
+  scope, and extension handling
+- stable operation identity for paths that support multiple HTTP methods
+- a dependency-free intermediate representation
+- freedom to keep product-specific behavior in each downstream adapter
+
+## Core concepts
+
+### Neutral parsed operations
+
+The main entry point returns the package's typed intermediate representation:
+
+```python
+from ramp_tool_openapi import (
+    ParsedOperation,
+    ParsedParameter,
+    ParsedRequestBody,
+    ParsedResponse,
+    parse_openapi_operations,
+)
+
+operations: tuple[ParsedOperation, ...] = parse_openapi_operations(
+    spec,
+    path_prefix="/developer/v1/agent-tools/",
+)
+
+operation: ParsedOperation = operations[0]
+parameters: tuple[ParsedParameter, ...] = operation.parameters
+request_body: ParsedRequestBody | None = operation.request_body
+response: ParsedResponse | None = operation.response
+```
+
+The intended data flow is:
+
+```text
+OpenAPI specification
+    -> parse_openapi_operations
+    -> tuple[ParsedOperation, ...]
+    -> downstream CLI or MCP adapter
+    -> consumer-specific tool model
+```
+
+### Stable operation identity
+
+`ParsedOperation.operation_key` combines the normalized HTTP method and path:
+
+```text
+get /developer/v1/agent-tools/procurement-draft
+post /developer/v1/agent-tools/procurement-draft
+delete /developer/v1/agent-tools/procurement-draft
+```
+
+This prevents operations on the same path from overwriting one another.
+
+### Shared normalization, adapter-owned policy
+
+This package owns OpenAPI facts that must remain consistent across consumers:
+
+- operation enumeration and optional path-prefix filtering
+- local reference resolution
+- path-level and operation-level parameter merging
+- request and response media schema extraction
+- operation-level OAuth scope and `x-*` extension preservation
+- raw tag and `x-platforms` metadata preservation
+- stable `(method, path)` operation identity
+
+Downstream consumers continue to own product and execution policy.
+
+`ramp-cli` owns:
+
+- Click parameter classification
+- synthetic commands and registry behavior
+- CLI-visible names and aliases
+- final category and tag selection
+- CLI platform visibility defaults
+
+`ramp-mcp-remote` owns:
+
+- Pydantic model generation
+- FastAPI route registration
+- MCP-visible names
+- path rendering and request execution
+- MCP platform visibility defaults
+
+If both consumers need to derive the same fact from `raw_operation`, that fact
+should generally become a typed field on `ParsedOperation` instead. This keeps
+shared parsing logic from drifting back into the adapters.
+
+## Supported OpenAPI behavior
+
+The parser currently supports:
+
+- `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` operations
+- path, query, header, and cookie parameters
+- path-level parameter inheritance
+- operation-level parameter overrides matched by `(location, name)`
+- local component references for parameters, request bodies, and responses
+- JSON and multipart request schemas, preferring `application/json`
+- the first successful response, in sorted status-code order, with an
+  `application/json` schema
+- operation-level OAuth scopes declared under each operation's
+  `security[*].oauth2`
+- raw OpenAPI tags
+- string and list forms of `x-platforms`
+- `x-alias` and arbitrary operation-level `x-*` extensions
+
+Schemas are preserved as dictionaries. The package does not recursively
+dereference schemas or generate Python models from them.
+
+Operation-level `security` overrides document-level security. When an operation
+omits `security`, document-level requirements are inherited; an explicit empty
+array opts the operation out of those requirements.
+
+## API reference
+
+The intentionally narrow public API is:
+
+```python
+from ramp_tool_openapi import (
+    ParameterLocation,
+    ParsedOperation,
+    ParsedParameter,
+    ParsedRequestBody,
+    ParsedResponse,
+    parse_openapi_operations,
+    resolve_local_ref,
+)
+```
+
+### `parse_openapi_operations`
+
+```python
+def parse_openapi_operations(
+    spec: Mapping[str, Any],
+    *,
+    path_prefix: str | None = None,
+) -> tuple[ParsedOperation, ...]
+```
+
+Normalizes the supported operations in an already-loaded OpenAPI document.
+
+**Arguments**
+
+- `spec`: OpenAPI document represented as a Python mapping.
+- `path_prefix`: Optional prefix used to include only matching paths.
+
+**Returns**
+
+A tuple of `ParsedOperation` objects in document order. An empty tuple is
+returned when the document does not contain a valid `paths` mapping or no paths
+match `path_prefix`.
+
+**Raises**
+
+- `ValueError` when a parameter, request-body, or response reference is remote or cyclic.
+- `KeyError` when a local reference cannot be resolved.
+- `TypeError` when a reference does not resolve to an OpenAPI object.
+
+### `resolve_local_ref`
+
+```python
+def resolve_local_ref(
+    ref: str,
+    spec: Mapping[str, Any],
+) -> Mapping[str, Any]
+```
+
+Resolves a mapping-only local OpenAPI reference path against an already-decoded
+document. Paths must begin with `#/`; reference tokens support JSON Pointer's
+`~0` and `~1` escapes. URI-fragment percent-decoding and array traversal are not
+supported.
+
+```python
+from ramp_tool_openapi import resolve_local_ref
+
+schema = resolve_local_ref(
+    "#/components/schemas/CreateCardRequest",
+    spec,
+)
+```
+
+**Arguments**
+
+- `ref`: Mapping-only local reference path beginning with `#/`.
+- `spec`: OpenAPI document containing the referenced object.
+
+**Returns**
+
+The referenced OpenAPI object as a mapping.
+
+**Raises**
+
+- `ValueError` when `ref` is not local.
+- `KeyError` when `ref` cannot be resolved.
+- `TypeError` when `ref` does not resolve to an OpenAPI object.
+
+Remote references are not supported.
+
+### Returned models
+
+The parser returns frozen dataclass models. Their schema and extension values
+remain dictionaries so downstream adapters can consume the original OpenAPI
+data without taking a dependency on another schema library.
+
+| Model | Purpose | Fields |
+| --- | --- | --- |
+| `ParsedOperation` | One normalized HTTP operation | `operation_key`, `path`, `method`, `operation_id`, `summary`, `description`, `tags`, `platforms`, `alias`, `scopes`, `extensions`, `parameters`, `request_body`, `response`, `raw_operation` |
+| `ParsedParameter` | One path, query, header, or cookie parameter | `name`, `location`, `required`, `schema`, `description` |
+| `ParsedRequestBody` | The selected request media type and schema | `content_type`, `schema`, `schema_name`, `required` |
+| `ParsedResponse` | The selected successful response and schema | `status_code`, `content_type`, `schema`, `schema_name` |
+| `ParameterLocation` | Supported parameter location type | `"path"`, `"query"`, `"header"`, or `"cookie"` |
+
+Internal parser helpers, including underscore-prefixed functions, are
+implementation details and should not be imported by downstream consumers.
+
+## Security model
+
+This library accepts an already-decoded OpenAPI mapping. It does not parse YAML,
+read files, fetch remote references, execute requests, or enforce authorization.
+Only local references beginning with `#/` are supported.
+
+`ParsedOperation.security_requirements` preserves OpenAPI's boolean structure: the
+outer tuple contains alternatives, while every scheme inside one alternative must
+be satisfied. `ParsedOperation.scopes` is a convenience union of scopes from OAuth2
+schemes and must not be used as an authorization decision.
+
+Operation paths must be absolute and canonical. Percent-encoded paths, backslashes,
+control characters, and `.` or `..` path segments are rejected. `path_prefix`
+selects operations but is not a replacement for authorization in a caller.
+
+Reference-object traversal is bounded by `max_reference_depth`, which defaults to
+100. Applications accepting untrusted documents should also enforce an input-size
+limit before decoding JSON.
+
+## Non-goals
+
+This package is not a general-purpose OpenAPI framework. It does not own:
+
+- OpenAPI document loading or full-spec validation
+- remote `$ref` resolution or recursive schema dereferencing
+- CLI command or Pydantic model generation
+- CLI- or MCP-visible naming
+- platform visibility defaults
+- category or tag selection
+- route or command registration
+- request serialization or execution
+
+## Development
+
+Run the package tests with:
+
+```bash
+uv run --group test python -m pytest -q
+```
+
+## Status
+
+The initial `0.x` API is provisional until both `ramp-cli` and
+`ramp-mcp-remote` have migrated to the shared normalization layer. Add links to
+both consumer migration PRs here before treating the API as stable.

ramp_tool_openapi-0.1.1/README.md

@@ -0,0 +1,282 @@
+# ramp-tool-openapi
+
+Shared, dependency-free OpenAPI normalization for Ramp tool surfaces.
+
+## Installation
+
+```bash
+pip install ramp-tool-openapi
+```
+
+The current package requires Python 3.11 or newer.
+
+## What is this?
+
+`ramp-tool-openapi` is the shared normalization boundary between Ramp OpenAPI
+specifications and downstream tool adapters. It accepts an already-loaded OpenAPI
+document and returns neutral `ParsedOperation` objects that consumers translate
+into their own representations.
+
+This gives Ramp tool consumers:
+
+- one implementation of shared OpenAPI parsing rules
+- consistent local `$ref`, parameter, request, response, operation-level OAuth
+  scope, and extension handling
+- stable operation identity for paths that support multiple HTTP methods
+- a dependency-free intermediate representation
+- freedom to keep product-specific behavior in each downstream adapter
+
+## Core concepts
+
+### Neutral parsed operations
+
+The main entry point returns the package's typed intermediate representation:
+
+```python
+from ramp_tool_openapi import (
+    ParsedOperation,
+    ParsedParameter,
+    ParsedRequestBody,
+    ParsedResponse,
+    parse_openapi_operations,
+)
+
+operations: tuple[ParsedOperation, ...] = parse_openapi_operations(
+    spec,
+    path_prefix="/developer/v1/agent-tools/",
+)
+
+operation: ParsedOperation = operations[0]
+parameters: tuple[ParsedParameter, ...] = operation.parameters
+request_body: ParsedRequestBody | None = operation.request_body
+response: ParsedResponse | None = operation.response
+```
+
+The intended data flow is:
+
+```text
+OpenAPI specification
+    -> parse_openapi_operations
+    -> tuple[ParsedOperation, ...]
+    -> downstream CLI or MCP adapter
+    -> consumer-specific tool model
+```
+
+### Stable operation identity
+
+`ParsedOperation.operation_key` combines the normalized HTTP method and path:
+
+```text
+get /developer/v1/agent-tools/procurement-draft
+post /developer/v1/agent-tools/procurement-draft
+delete /developer/v1/agent-tools/procurement-draft
+```
+
+This prevents operations on the same path from overwriting one another.
+
+### Shared normalization, adapter-owned policy
+
+This package owns OpenAPI facts that must remain consistent across consumers:
+
+- operation enumeration and optional path-prefix filtering
+- local reference resolution
+- path-level and operation-level parameter merging
+- request and response media schema extraction
+- operation-level OAuth scope and `x-*` extension preservation
+- raw tag and `x-platforms` metadata preservation
+- stable `(method, path)` operation identity
+
+Downstream consumers continue to own product and execution policy.
+
+`ramp-cli` owns:
+
+- Click parameter classification
+- synthetic commands and registry behavior
+- CLI-visible names and aliases
+- final category and tag selection
+- CLI platform visibility defaults
+
+`ramp-mcp-remote` owns:
+
+- Pydantic model generation
+- FastAPI route registration
+- MCP-visible names
+- path rendering and request execution
+- MCP platform visibility defaults
+
+If both consumers need to derive the same fact from `raw_operation`, that fact
+should generally become a typed field on `ParsedOperation` instead. This keeps
+shared parsing logic from drifting back into the adapters.
+
+## Supported OpenAPI behavior
+
+The parser currently supports:
+
+- `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` operations
+- path, query, header, and cookie parameters
+- path-level parameter inheritance
+- operation-level parameter overrides matched by `(location, name)`
+- local component references for parameters, request bodies, and responses
+- JSON and multipart request schemas, preferring `application/json`
+- the first successful response, in sorted status-code order, with an
+  `application/json` schema
+- operation-level OAuth scopes declared under each operation's
+  `security[*].oauth2`
+- raw OpenAPI tags
+- string and list forms of `x-platforms`
+- `x-alias` and arbitrary operation-level `x-*` extensions
+
+Schemas are preserved as dictionaries. The package does not recursively
+dereference schemas or generate Python models from them.
+
+Operation-level `security` overrides document-level security. When an operation
+omits `security`, document-level requirements are inherited; an explicit empty
+array opts the operation out of those requirements.
+
+## API reference
+
+The intentionally narrow public API is:
+
+```python
+from ramp_tool_openapi import (
+    ParameterLocation,
+    ParsedOperation,
+    ParsedParameter,
+    ParsedRequestBody,
+    ParsedResponse,
+    parse_openapi_operations,
+    resolve_local_ref,
+)
+```
+
+### `parse_openapi_operations`
+
+```python
+def parse_openapi_operations(
+    spec: Mapping[str, Any],
+    *,
+    path_prefix: str | None = None,
+) -> tuple[ParsedOperation, ...]
+```
+
+Normalizes the supported operations in an already-loaded OpenAPI document.
+
+**Arguments**
+
+- `spec`: OpenAPI document represented as a Python mapping.
+- `path_prefix`: Optional prefix used to include only matching paths.
+
+**Returns**
+
+A tuple of `ParsedOperation` objects in document order. An empty tuple is
+returned when the document does not contain a valid `paths` mapping or no paths
+match `path_prefix`.
+
+**Raises**
+
+- `ValueError` when a parameter, request-body, or response reference is remote or cyclic.
+- `KeyError` when a local reference cannot be resolved.
+- `TypeError` when a reference does not resolve to an OpenAPI object.
+
+### `resolve_local_ref`
+
+```python
+def resolve_local_ref(
+    ref: str,
+    spec: Mapping[str, Any],
+) -> Mapping[str, Any]
+```
+
+Resolves a mapping-only local OpenAPI reference path against an already-decoded
+document. Paths must begin with `#/`; reference tokens support JSON Pointer's
+`~0` and `~1` escapes. URI-fragment percent-decoding and array traversal are not
+supported.
+
+```python
+from ramp_tool_openapi import resolve_local_ref
+
+schema = resolve_local_ref(
+    "#/components/schemas/CreateCardRequest",
+    spec,
+)
+```
+
+**Arguments**
+
+- `ref`: Mapping-only local reference path beginning with `#/`.
+- `spec`: OpenAPI document containing the referenced object.
+
+**Returns**
+
+The referenced OpenAPI object as a mapping.
+
+**Raises**
+
+- `ValueError` when `ref` is not local.
+- `KeyError` when `ref` cannot be resolved.
+- `TypeError` when `ref` does not resolve to an OpenAPI object.
+
+Remote references are not supported.
+
+### Returned models
+
+The parser returns frozen dataclass models. Their schema and extension values
+remain dictionaries so downstream adapters can consume the original OpenAPI
+data without taking a dependency on another schema library.
+
+| Model | Purpose | Fields |
+| --- | --- | --- |
+| `ParsedOperation` | One normalized HTTP operation | `operation_key`, `path`, `method`, `operation_id`, `summary`, `description`, `tags`, `platforms`, `alias`, `scopes`, `extensions`, `parameters`, `request_body`, `response`, `raw_operation` |
+| `ParsedParameter` | One path, query, header, or cookie parameter | `name`, `location`, `required`, `schema`, `description` |
+| `ParsedRequestBody` | The selected request media type and schema | `content_type`, `schema`, `schema_name`, `required` |
+| `ParsedResponse` | The selected successful response and schema | `status_code`, `content_type`, `schema`, `schema_name` |
+| `ParameterLocation` | Supported parameter location type | `"path"`, `"query"`, `"header"`, or `"cookie"` |
+
+Internal parser helpers, including underscore-prefixed functions, are
+implementation details and should not be imported by downstream consumers.
+
+## Security model
+
+This library accepts an already-decoded OpenAPI mapping. It does not parse YAML,
+read files, fetch remote references, execute requests, or enforce authorization.
+Only local references beginning with `#/` are supported.
+
+`ParsedOperation.security_requirements` preserves OpenAPI's boolean structure: the
+outer tuple contains alternatives, while every scheme inside one alternative must
+be satisfied. `ParsedOperation.scopes` is a convenience union of scopes from OAuth2
+schemes and must not be used as an authorization decision.
+
+Operation paths must be absolute and canonical. Percent-encoded paths, backslashes,
+control characters, and `.` or `..` path segments are rejected. `path_prefix`
+selects operations but is not a replacement for authorization in a caller.
+
+Reference-object traversal is bounded by `max_reference_depth`, which defaults to
+100. Applications accepting untrusted documents should also enforce an input-size
+limit before decoding JSON.
+
+## Non-goals
+
+This package is not a general-purpose OpenAPI framework. It does not own:
+
+- OpenAPI document loading or full-spec validation
+- remote `$ref` resolution or recursive schema dereferencing
+- CLI command or Pydantic model generation
+- CLI- or MCP-visible naming
+- platform visibility defaults
+- category or tag selection
+- route or command registration
+- request serialization or execution
+
+## Development
+
+Run the package tests with:
+
+```bash
+uv run --group test python -m pytest -q
+```
+
+## Status
+
+The initial `0.x` API is provisional until both `ramp-cli` and
+`ramp-mcp-remote` have migrated to the shared normalization layer. Add links to
+both consumer migration PRs here before treating the API as stable.

ramp_tool_openapi-0.1.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling>=1.27,<2"]
+
+[dependency-groups]
+test = [
+  "pytest>=9.0.3,<10"
+]
+
+[project]
+authors = [
+  {name = "Ramp", email = "developer@ramp.com"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed"
+]
+dependencies = []
+description = "Shared OpenAPI normalization for Ramp tool surfaces"
+keywords = ["openapi", "tooling"]
+license = "MIT"
+license-files = ["LICENSE"]
+name = "ramp-tool-openapi"
+readme = "README.md"
+requires-python = ">=3.11"
+version = "0.1.1"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["ramp_tool_openapi"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ramp_tool_openapi"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

ramp_tool_openapi-0.1.1/ramp_tool_openapi/__init__.py

@@ -0,0 +1,15 @@
+from .models import ParameterLocation as ParameterLocation
+from .models import ParsedOperation as ParsedOperation
+from .models import ParsedParameter as ParsedParameter
+from .models import ParsedRequestBody as ParsedRequestBody
+from .models import ParsedResponse as ParsedResponse
+from .models import (
+    ParsedSecurityRequirement as ParsedSecurityRequirement,
+)
+from .models import (
+    ParsedSecuritySchemeRequirement as ParsedSecuritySchemeRequirement,
+)
+from .parser import (
+    parse_openapi_operations as parse_openapi_operations,
+)
+from .schema import resolve_local_ref as resolve_local_ref

ramp_tool_openapi-0.1.1/ramp_tool_openapi/models.py

@@ -0,0 +1,68 @@
+"""Neutral OpenAPI operation models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+ParameterLocation = Literal["path", "query", "header", "cookie"]
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedParameter:
+    name: str
+    location: ParameterLocation
+    required: bool
+    schema: dict[str, Any]
+    description: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedRequestBody:
+    content_type: str
+    schema: dict[str, Any]
+    schema_name: str
+    required: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedResponse:
+    status_code: str
+    content_type: str
+    schema: dict[str, Any]
+    schema_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedSecuritySchemeRequirement:
+    """One security scheme within an OpenAPI security requirement."""
+
+    scheme_name: str
+    scopes: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedSecurityRequirement:
+    """Schemes that must all be satisfied for one security alternative."""
+
+    schemes: tuple[ParsedSecuritySchemeRequirement, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedOperation:
+    operation_key: str
+    path: str
+    method: str
+    operation_id: str | None
+    summary: str | None
+    description: str | None
+    tags: tuple[str, ...]
+    platforms: tuple[str, ...]
+    alias: str | None
+    security_requirements: tuple[ParsedSecurityRequirement, ...]
+    scopes: tuple[str, ...]
+    extensions: dict[str, Any]
+    parameters: tuple[ParsedParameter, ...]
+    request_body: ParsedRequestBody | None
+    response: ParsedResponse | None
+    raw_operation: dict[str, Any]

ramp_tool_openapi-0.1.1/ramp_tool_openapi/parser.py

@@ -0,0 +1,443 @@
+"""Dependency-free OpenAPI operation parsing."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import unquote
+
+from .models import (
+    ParsedOperation,
+    ParsedParameter,
+    ParsedRequestBody,
+    ParsedResponse,
+    ParsedSecurityRequirement,
+    ParsedSecuritySchemeRequirement,
+)
+from .schema import resolve_local_ref, schema_ref_name
+
+_DEFAULT_REQUEST_CONTENT_TYPES = ("application/json", "multipart/form-data")
+_DEFAULT_RESPONSE_CONTENT_TYPES = ("application/json",)
+_DEFAULT_MAX_REFERENCE_DEPTH = 100
+_HTTP_METHODS = frozenset({"delete", "get", "patch", "post", "put"})
+_PARAMETER_LOCATIONS = frozenset({"cookie", "header", "path", "query"})
+
+
+def _is_http_method(method: str) -> bool:
+    return method in _HTTP_METHODS
+
+
+def _validate_path(path: str, *, field_name: str = "path") -> None:
+    if not path.startswith("/"):
+        raise ValueError(f"OpenAPI {field_name} must start with '/': {path!r}")
+    if any(ord(character) < 32 or ord(character) == 127 for character in path):
+        raise ValueError(f"OpenAPI {field_name} contains control characters: {path!r}")
+    if "\\" in path:
+        raise ValueError(f"OpenAPI {field_name} contains a backslash: {path!r}")
+    if unquote(path) != path:
+        raise ValueError(
+            f"OpenAPI {field_name} must not contain percent-encoding: {path!r}"
+        )
+    path_parts = path.split("/")
+    if "" in path_parts[1:-1]:
+        raise ValueError(f"OpenAPI {field_name} contains an empty segment: {path!r}")
+    if any(part in {".", ".."} for part in path_parts):
+        raise ValueError(f"OpenAPI {field_name} contains a dot segment: {path!r}")
+
+
+def _path_matches_prefix(path: str, path_prefix: str) -> bool:
+    if path_prefix == "/":
+        return True
+    normalized_prefix = path_prefix.rstrip("/")
+    return path == normalized_prefix or path.startswith(f"{normalized_prefix}/")
+
+
+def _operation_tags(operation: Mapping[str, Any]) -> tuple[str, ...]:
+    tags = operation.get("tags")
+    if not isinstance(tags, Sequence) or isinstance(tags, (str, bytes)):
+        return ()
+    return tuple(tag for tag in tags if isinstance(tag, str))
+
+
+def _operation_platforms(operation: Mapping[str, Any]) -> tuple[str, ...]:
+    platforms = operation.get("x-platforms")
+    if isinstance(platforms, str):
+        return (platforms,)
+    if isinstance(platforms, Sequence) and not isinstance(platforms, (str, bytes)):
+        return tuple(item for item in platforms if isinstance(item, str))
+    return ()
+
+
+def _extract_security_requirements(
+    operation: Mapping[str, Any],
+    spec: Mapping[str, Any],
+) -> tuple[ParsedSecurityRequirement, ...]:
+    security_source = operation if "security" in operation else spec
+    if "security" not in security_source:
+        return ()
+    security = security_source["security"]
+    if not isinstance(security, Sequence) or isinstance(security, (str, bytes)):
+        raise ValueError("OpenAPI security requirements must be an array")
+
+    parsed_requirements: list[ParsedSecurityRequirement] = []
+    for requirement in security:
+        if not isinstance(requirement, Mapping):
+            raise ValueError("Each OpenAPI security requirement must be an object")
+        schemes: list[ParsedSecuritySchemeRequirement] = []
+        for scheme_name, raw_scopes in requirement.items():
+            if not isinstance(scheme_name, str) or not scheme_name:
+                raise ValueError(
+                    "OpenAPI security scheme names must be non-empty strings"
+                )
+            if not isinstance(raw_scopes, Sequence) or isinstance(
+                raw_scopes, (str, bytes)
+            ):
+                raise ValueError(
+                    f"OpenAPI security scopes for {scheme_name!r} must be an array"
+                )
+            if not all(isinstance(scope, str) for scope in raw_scopes):
+                raise ValueError(
+                    f"OpenAPI security scopes for {scheme_name!r} must be strings"
+                )
+            schemes.append(
+                ParsedSecuritySchemeRequirement(
+                    scheme_name=scheme_name,
+                    scopes=tuple(raw_scopes),
+                )
+            )
+        parsed_requirements.append(ParsedSecurityRequirement(schemes=tuple(schemes)))
+    return tuple(parsed_requirements)
+
+
+def _oauth_scheme_names(
+    spec: Mapping[str, Any],
+    *,
+    max_reference_depth: int,
+) -> frozenset[str]:
+    components = spec.get("components")
+    if not isinstance(components, Mapping):
+        return frozenset({"oauth2"})
+    security_schemes = components.get("securitySchemes")
+    if not isinstance(security_schemes, Mapping):
+        return frozenset({"oauth2"})
+    oauth_scheme_names: set[str] = set()
+    for name, scheme in security_schemes.items():
+        if not isinstance(name, str) or not isinstance(scheme, Mapping):
+            continue
+        resolved_scheme = _resolve_reference_object(
+            scheme,
+            spec,
+            max_reference_depth=max_reference_depth,
+        )
+        if resolved_scheme.get("type") == "oauth2":
+            oauth_scheme_names.add(name)
+    return frozenset(oauth_scheme_names)
+
+
+def _extract_oauth_scopes(
+    security_requirements: tuple[ParsedSecurityRequirement, ...],
+    oauth_scheme_names: frozenset[str],
+) -> tuple[str, ...]:
+    scopes: dict[str, None] = {}
+    for requirement in security_requirements:
+        for scheme in requirement.schemes:
+            if scheme.scheme_name in oauth_scheme_names:
+                for scope in scheme.scopes:
+                    scopes[scope] = None
+    return tuple(scopes)
+
+
+def _operation_alias(operation: Mapping[str, Any]) -> str | None:
+    alias = operation.get("x-alias")
+    return alias if isinstance(alias, str) and alias else None
+
+
+def _operation_extensions(operation: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        key: value
+        for key, value in operation.items()
+        if isinstance(key, str) and key.startswith("x-")
+    }
+
+
+def _combine_parameters(
+    path_parameters: Any,
+    operation_parameters: Any,
+    *,
+    spec: Mapping[str, Any] | None = None,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> tuple[Mapping[str, Any], ...]:
+    by_key: dict[tuple[str, str], Mapping[str, Any]] = {}
+    for raw_parameter in _iter_parameter_mappings(
+        path_parameters,
+        spec=spec,
+        max_reference_depth=max_reference_depth,
+    ):
+        key = _parameter_key(raw_parameter)
+        if key is not None:
+            by_key[key] = raw_parameter
+    for raw_parameter in _iter_parameter_mappings(
+        operation_parameters,
+        spec=spec,
+        max_reference_depth=max_reference_depth,
+    ):
+        key = _parameter_key(raw_parameter)
+        if key is not None:
+            by_key[key] = raw_parameter
+    return tuple(by_key.values())
+
+
+def _extract_parameters(
+    raw_parameters: Any,
+    *,
+    spec: Mapping[str, Any] | None = None,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> tuple[ParsedParameter, ...]:
+    parameters: list[ParsedParameter] = []
+    for raw_parameter in _iter_parameter_mappings(
+        raw_parameters,
+        spec=spec,
+        max_reference_depth=max_reference_depth,
+    ):
+        name = raw_parameter.get("name")
+        location = raw_parameter.get("in")
+        if not isinstance(name, str) or location not in _PARAMETER_LOCATIONS:
+            continue
+        raw_schema = raw_parameter.get("schema")
+        schema = dict(raw_schema) if isinstance(raw_schema, Mapping) else {}
+        description = raw_parameter.get("description")
+        parameters.append(
+            ParsedParameter(
+                name=name,
+                location=location,
+                required=bool(raw_parameter.get("required")),
+                schema=schema,
+                description=description if isinstance(description, str) else None,
+            )
+        )
+    return tuple(parameters)
+
+
+def _extract_request_body(
+    operation: Mapping[str, Any],
+    *,
+    spec: Mapping[str, Any] | None = None,
+    content_types: tuple[str, ...] = _DEFAULT_REQUEST_CONTENT_TYPES,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> ParsedRequestBody | None:
+    request_body = operation.get("requestBody")
+    if not isinstance(request_body, Mapping):
+        return None
+    request_body = _resolve_reference_object(
+        request_body,
+        spec,
+        max_reference_depth=max_reference_depth,
+    )
+    content = request_body.get("content")
+    if not isinstance(content, Mapping):
+        return None
+    for content_type in content_types:
+        media_type = content.get(content_type)
+        if not isinstance(media_type, Mapping):
+            continue
+        schema = media_type.get("schema")
+        if isinstance(schema, Mapping):
+            return ParsedRequestBody(
+                content_type=content_type,
+                schema=dict(schema),
+                schema_name=schema_ref_name(schema),
+                required=bool(request_body.get("required")),
+            )
+    return None
+
+
+def _extract_response(
+    operation: Mapping[str, Any],
+    *,
+    spec: Mapping[str, Any] | None = None,
+    content_types: tuple[str, ...] = _DEFAULT_RESPONSE_CONTENT_TYPES,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> ParsedResponse | None:
+    responses = operation.get("responses")
+    if not isinstance(responses, Mapping):
+        return None
+    for status_code in sorted(responses, key=str):
+        if not str(status_code).startswith("2"):
+            continue
+        response = responses[status_code]
+        if not isinstance(response, Mapping):
+            continue
+        response = _resolve_reference_object(
+            response,
+            spec,
+            max_reference_depth=max_reference_depth,
+        )
+        content = response.get("content")
+        if not isinstance(content, Mapping):
+            continue
+        for content_type in content_types:
+            media_type = content.get(content_type)
+            if not isinstance(media_type, Mapping):
+                continue
+            schema = media_type.get("schema")
+            if isinstance(schema, Mapping):
+                return ParsedResponse(
+                    status_code=str(status_code),
+                    content_type=content_type,
+                    schema=dict(schema),
+                    schema_name=schema_ref_name(schema),
+                )
+    return None
+
+
+def parse_openapi_operations(
+    spec: Mapping[str, Any],
+    *,
+    path_prefix: str | None = None,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> tuple[ParsedOperation, ...]:
+    if max_reference_depth < 1:
+        raise ValueError("max_reference_depth must be at least 1")
+    if path_prefix is not None:
+        _validate_path(path_prefix, field_name="path prefix")
+
+    operations: list[ParsedOperation] = []
+    operation_keys: set[str] = set()
+    paths = spec.get("paths")
+    if not isinstance(paths, Mapping):
+        return ()
+    oauth_scheme_names = _oauth_scheme_names(
+        spec,
+        max_reference_depth=max_reference_depth,
+    )
+
+    for path, path_item in paths.items():
+        if not isinstance(path, str) or not isinstance(path_item, Mapping):
+            continue
+        _validate_path(path)
+        if path_prefix is not None and not _path_matches_prefix(path, path_prefix):
+            continue
+        path_parameters = path_item.get("parameters", ())
+        for method, operation in path_item.items():
+            if not isinstance(method, str):
+                continue
+            if method.lower() in _HTTP_METHODS and not _is_http_method(method):
+                raise ValueError(
+                    f"OpenAPI HTTP method keys must be lowercase: {method!r}"
+                )
+            if not _is_http_method(method):
+                continue
+            if not isinstance(operation, Mapping):
+                continue
+            normalized_method = method
+            operation_key = _operation_key(normalized_method, path)
+            if operation_key in operation_keys:
+                raise ValueError(f"Duplicate OpenAPI operation key: {operation_key!r}")
+            operation_keys.add(operation_key)
+            parameters = _combine_parameters(
+                path_parameters,
+                operation.get("parameters", ()),
+                spec=spec,
+                max_reference_depth=max_reference_depth,
+            )
+            security_requirements = _extract_security_requirements(operation, spec)
+            operations.append(
+                ParsedOperation(
+                    operation_key=operation_key,
+                    path=path,
+                    method=normalized_method,
+                    operation_id=_string_or_none(operation.get("operationId")),
+                    summary=_string_or_none(operation.get("summary")),
+                    description=_string_or_none(operation.get("description")),
+                    tags=_operation_tags(operation),
+                    platforms=_operation_platforms(operation),
+                    alias=_operation_alias(operation),
+                    security_requirements=security_requirements,
+                    scopes=_extract_oauth_scopes(
+                        security_requirements,
+                        oauth_scheme_names,
+                    ),
+                    extensions=_operation_extensions(operation),
+                    parameters=_extract_parameters(
+                        parameters,
+                        max_reference_depth=max_reference_depth,
+                    ),
+                    request_body=_extract_request_body(
+                        operation,
+                        spec=spec,
+                        max_reference_depth=max_reference_depth,
+                    ),
+                    response=_extract_response(
+                        operation,
+                        spec=spec,
+                        max_reference_depth=max_reference_depth,
+                    ),
+                    raw_operation=dict(operation),
+                )
+            )
+    return tuple(operations)
+
+
+def _operation_key(method: str, path: str) -> str:
+    return f"{method.lower()} {path}"
+
+
+def _iter_parameter_mappings(
+    raw_parameters: Any,
+    *,
+    spec: Mapping[str, Any] | None = None,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> tuple[Mapping[str, Any], ...]:
+    if not isinstance(raw_parameters, Sequence) or isinstance(
+        raw_parameters, (str, bytes)
+    ):
+        return ()
+    return tuple(
+        _resolve_reference_object(
+            item,
+            spec,
+            max_reference_depth=max_reference_depth,
+        )
+        for item in raw_parameters
+        if isinstance(item, Mapping)
+    )
+
+
+def _resolve_reference_object(
+    raw_object: Mapping[str, Any],
+    spec: Mapping[str, Any] | None,
+    *,
+    max_reference_depth: int = _DEFAULT_MAX_REFERENCE_DEPTH,
+) -> Mapping[str, Any]:
+    if max_reference_depth < 1:
+        raise ValueError("max_reference_depth must be at least 1")
+
+    current = raw_object
+    seen_refs: set[str] = set()
+    while True:
+        ref = current.get("$ref")
+        if not isinstance(ref, str):
+            return current
+        if spec is None:
+            raise ValueError(f"OpenAPI ref {ref!r} cannot be resolved without a spec")
+        if ref in seen_refs:
+            raise ValueError(f"OpenAPI ref cycle detected for {ref!r}")
+        if len(seen_refs) >= max_reference_depth:
+            raise ValueError(
+                "OpenAPI reference depth exceeds "
+                f"the configured maximum of {max_reference_depth}"
+            )
+        seen_refs.add(ref)
+        current = resolve_local_ref(ref, spec)
+
+
+def _parameter_key(parameter: Mapping[str, Any]) -> tuple[str, str] | None:
+    name = parameter.get("name")
+    location = parameter.get("in")
+    if isinstance(name, str) and isinstance(location, str):
+        return (location, name)
+    return None
+
+
+def _string_or_none(value: Any) -> str | None:
+    return value if isinstance(value, str) else None

ramp_tool_openapi-0.1.1/ramp_tool_openapi/schema.py

@@ -0,0 +1,35 @@
+"""Small schema helpers for OpenAPI parser adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def schema_ref_name(schema: Mapping[str, Any] | None) -> str:
+    if not schema:
+        return ""
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        return ref.rsplit("/", 1)[-1]
+    refs = [
+        item["$ref"].rsplit("/", 1)[-1]
+        for item in schema.get("allOf", [])
+        if isinstance(item, Mapping) and isinstance(item.get("$ref"), str)
+    ]
+    return "+".join(refs)
+
+
+def resolve_local_ref(ref: str, spec: Mapping[str, Any]) -> Mapping[str, Any]:
+    if not ref.startswith("#/"):
+        raise ValueError(f"Only local OpenAPI refs are supported, got {ref!r}")
+
+    value: Any = spec
+    for part in ref.removeprefix("#/").split("/"):
+        key = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(value, Mapping) or key not in value:
+            raise KeyError(f"OpenAPI ref {ref!r} could not be resolved")
+        value = value[key]
+    if not isinstance(value, Mapping):
+        raise TypeError(f"OpenAPI ref {ref!r} did not resolve to an object")
+    return value