server-decorator-gen-openapi 2.0.19__tar.gz

server_decorator_gen_openapi-2.0.19/.gitignore

@@ -0,0 +1,57 @@
+.npmrc
+dist
+node_modules
+.astro
+
+
+# GitHub Actions
+.env
+*.log
+
+# Package managers
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+package-lock.json  # Use pnpm-lock.yaml instead
+yarn.lock         # Use pnpm-lock.yaml instead
+# uv is dev-only; do not commit the lockfile
+python/uv.lock
+
+# iCloud-style duplicate files (D-D)
+* 2
+* 2.*
+* 3
+* 3.*
+
+# Python (added during polyglot migration)
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+# ps-release-workflow (gitignored state)
+.claude/state/
+.claude/worktrees/
+
+# Rendered design HTML — local view artifacts only (global rule)
+docs/superpowers/**/*.html
+research/**/*.html
+
+# Nim (F-006): `nim c` drops binaries beside sources; `nim r`/`nimble test` do not, but be safe.
+nimcache/
+nim/tests/t_*
+!nim/tests/t_*.nim
+nim/examples/emit_*
+!nim/examples/emit_*.nim
+nim/examples/user
+nim/nimble.lock
+# ^ the package has zero dependencies (plan constraint) — this lockfile must never be committed.
+
+# graft's local graph cache — regenerable, not committed (run `graft build`).
+graft/
+# Rust build artifacts
+target/
+rust/target/
+

server_decorator_gen_openapi-2.0.19/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: server-decorator-gen-openapi
+Version: 2.0.19
+Summary: IR-derived OpenAPI 3.1 document (contracts/rules/rest-conventions.md). Polyglot sibling of @montionugera/entity-spec-gen-openapi.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: server-decorator-entity==2.0.19
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# server-decorator-gen-openapi
+
+Compiles the EntitySpec IR into an OpenAPI 3.1 document, following
+`contracts/rules/rest-conventions.md`. Pure functions — no HTTP framework, no
+dependency on `server-decorator` or on `server-decorator-gen-pydantic`.
+
+Polyglot sibling of `@montionugera/entity-spec-gen-openapi`; both emit a
+byte-identical document, enforced by `scripts/check-openapi-parity.sh`.

server_decorator_gen_openapi-2.0.19/README.md

@@ -0,0 +1,8 @@
+# server-decorator-gen-openapi
+
+Compiles the EntitySpec IR into an OpenAPI 3.1 document, following
+`contracts/rules/rest-conventions.md`. Pure functions — no HTTP framework, no
+dependency on `server-decorator` or on `server-decorator-gen-pydantic`.
+
+Polyglot sibling of `@montionugera/entity-spec-gen-openapi`; both emit a
+byte-identical document, enforced by `scripts/check-openapi-parity.sh`.

server_decorator_gen_openapi-2.0.19/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "server-decorator-gen-openapi"
+version = "2.0.19"
+description = "IR-derived OpenAPI 3.1 document (contracts/rules/rest-conventions.md). Polyglot sibling of @montionugera/entity-spec-gen-openapi."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = ["server-decorator-entity==2.0.19"]
+
+[tool.uv.sources]
+server-decorator-entity = { workspace = true }
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.5", "mypy>=1.10"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/server_decorator_gen_openapi"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "ASYNC", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/server_decorator_gen_openapi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

server_decorator_gen_openapi-2.0.19/scripts/check.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# python/packages/gen_openapi/scripts/check.sh — lint + type-check + unit tests.
+# Assumes `uv` is installed; `pip install uv` if not.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if command -v uv >/dev/null 2>&1; then
+  uv sync --extra dev >/dev/null
+  RUN="uv run"
+else
+  echo "warning: uv not found; falling back to plain python+pytest. Install uv for the full dev experience." >&2
+  RUN=""
+fi
+
+$RUN ruff check src tests
+$RUN ruff format --check src tests
+$RUN mypy src
+
+# Coverage gate (unit tests only; integration-marked tests are excluded).
+# COV_MIN is a ratchet: achieved line+branch coverage (--cov-branch) rounded down,
+# measured on Python 3.10, 3.12 and 3.14. Raise it, never lower it.
+COV_MIN=${COV_MIN:-94}
+export COVERAGE_FILE="${COVERAGE_FILE:-${TMPDIR:-/tmp}/server-decorator-gen_openapi.coverage}"
+$RUN pytest -q tests/unit -m "not integration" \
+  --cov=src --cov-branch --cov-report=term-missing:skip-covered --cov-fail-under="$COV_MIN"

server_decorator_gen_openapi-2.0.19/scripts/emit_openapi.py

@@ -0,0 +1,12 @@
+import sys
+from pathlib import Path
+
+from server_decorator_entity import entity_spec
+from server_decorator_entity.canonical import canonical_json
+from server_decorator_entity.testing.user_fixture import User
+
+from server_decorator_gen_openapi import openapi_document
+
+# emit_openapi.py -> scripts -> gen_openapi -> packages -> python -> repo root
+version = (Path(__file__).resolve().parents[4] / "contracts/VERSION").read_text().strip()
+sys.stdout.write(canonical_json(openapi_document([entity_spec(User)], version)))

server_decorator_gen_openapi-2.0.19/src/server_decorator_gen_openapi/__init__.py

@@ -0,0 +1,371 @@
+"""IR-derived OpenAPI 3.1 document — see contracts/rules/rest-conventions.md."""
+
+from collections.abc import Callable
+from typing import Any
+
+# Copied from contracts/rules/entity-spec-validation.md, not imported: this package must
+# not depend on gen_pydantic (layering rule). Keep byte-identical to gen-openapi's patterns.ts.
+EMAIL_PATTERN = (
+    r"^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?"
+    r"(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"
+)
+UUID_PATTERN = r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+URI_PATTERN = r"^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s]+$"
+
+_BASE_TYPE = {
+    "str": "string",
+    "ref": "string",
+    "int": "integer",
+    "float": "number",
+    "bool": "boolean",
+    "datetime": "string",
+    "enum": "string",
+    "list": "array",
+    "obj": "object",
+}
+_FORMAT_PATTERN = {"email": EMAIL_PATTERN, "uuid": UUID_PATTERN, "uri": URI_PATTERN}
+
+Include = Callable[[dict[str, Any]], bool]
+
+
+def json_schema_for_field(f: dict[str, Any], include: Include | None = None) -> dict[str, Any]:
+    """Map one IR field to JSON Schema.
+
+    ``include`` threads through EVERY level of nesting — obj members and list items alike —
+    because contracts/rules/rest-conventions.md filters nested obj and list members by the same
+    rule as their parent, and gen_pydantic's model builder already does exactly this. Without it
+    a create DTO would keep a readonly member that lives inside a list of objects.
+    """
+    keep: Include = (lambda _f: True) if include is None else include
+    t = f["type"]
+    base = _BASE_TYPE[t]
+    s: dict[str, Any] = {"type": [base, "null"] if f.get("nullable") else base}
+    if t == "datetime":
+        s["format"] = "date-time"
+    if t in ("str", "ref"):
+        fmt = f.get("format")
+        if fmt:
+            s["format"] = fmt
+            s["pattern"] = _FORMAT_PATTERN[fmt]
+        if "pattern" in f:
+            s["pattern"] = f["pattern"]
+        if "min" in f:
+            s["minLength"] = f["min"]
+        if "max" in f:
+            s["maxLength"] = f["max"]
+    if t in ("int", "float"):
+        if "min" in f:
+            s["minimum"] = f["min"]
+        if "max" in f:
+            s["maximum"] = f["max"]
+    if t == "enum":
+        s["enum"] = list(f["enum"])
+    if t == "list":
+        s["items"] = json_schema_for_field(f["item"], keep) if f.get("item") else {}
+        if "min" in f:
+            s["minItems"] = f["min"]
+        if "max" in f:
+            s["maxItems"] = f["max"]
+    if t == "obj":
+        kept = [n for n in f.get("fields", []) if keep(n)]
+        s["properties"] = object_properties(kept, keep)
+        # Filter `required` by `include` too: an excluded member left in `required` would make
+        # the schema impossible to satisfy, since its property is not emitted at all.
+        required = [n["name"] for n in kept if not n.get("optional")]
+        if required:
+            s["required"] = required
+        s["additionalProperties"] = False
+    if "description" in f:
+        s["description"] = f["description"]
+    return s
+
+
+def object_properties(fields: list[dict[str, Any]], include: Include) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for f in [x for x in fields if include(x)]:
+        out[f["name"]] = json_schema_for_field(f, include)
+    return out
+
+
+def _strict_object(fields: list[dict[str, Any]], include: Include) -> dict[str, Any]:
+    kept = [f for f in fields if include(f)]
+    s: dict[str, Any] = {"type": "object", "properties": object_properties(kept, include)}
+    required = [f["name"] for f in kept if not f.get("optional")]
+    if required:
+        s["required"] = required
+    s["additionalProperties"] = False
+    return s
+
+
+def _list_envelope(entity: str, pagination: str) -> dict[str, Any]:
+    items = {"type": "array", "items": {"$ref": f"#/components/schemas/{entity}Read"}}
+    limit = {"type": "integer", "minimum": 1, "maximum": 100}
+    if pagination == "cursor":
+        return {
+            "type": "object",
+            "properties": {"items": items, "nextCursor": {"type": ["string", "null"]}},
+            "required": ["items", "nextCursor"],
+            "additionalProperties": False,
+        }
+    return {
+        "type": "object",
+        "properties": {
+            "items": items,
+            "total": {"type": "integer", "minimum": 0},
+            "limit": limit,
+            "offset": {"type": "integer", "minimum": 0},
+        },
+        "required": ["items", "total", "limit", "offset"],
+        "additionalProperties": False,
+    }
+
+
+_PROBLEM_PROPS: dict[str, Any] = {
+    "type": {"type": "string", "format": "uri"},
+    "title": {"type": "string"},
+    "status": {"type": "integer"},
+    "detail": {"type": "string"},
+    "instance": {"type": "string", "format": "uri"},
+}
+
+PROBLEM_SCHEMAS: dict[str, Any] = {
+    "Problem": {
+        "type": "object",
+        "properties": dict(_PROBLEM_PROPS),
+        "required": ["type", "title", "status"],
+        "additionalProperties": False,
+    },
+    "ValidationProblem": {
+        "type": "object",
+        "properties": {**_PROBLEM_PROPS, "fields": {"type": "array", "items": {"type": "string"}}},
+        "required": ["type", "title", "status", "fields"],
+        "additionalProperties": False,
+    },
+}
+
+
+def _scheme_object(s: dict[str, Any]) -> dict[str, Any]:
+    if s["type"] == "apiKey":
+        return {"type": "apiKey", "in": s["in"], "name": s["paramName"]}
+    out: dict[str, Any] = {"type": "http", "scheme": s["scheme"]}
+    if "bearerFormat" in s:
+        out["bearerFormat"] = s["bearerFormat"]
+    return out
+
+
+def openapi_components(spec: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    e = spec["entity"]
+    create = _strict_object(spec["fields"], lambda f: not f.get("readonly"))
+    update = {k: v for k, v in create.items() if k != "required"}
+    schemas: dict[str, Any] = {
+        f"{e}Create": create,
+        f"{e}Update": update,
+        f"{e}Read": _strict_object(spec["fields"], lambda f: not f.get("writeonly")),
+        f"{e}ListResponse": _list_envelope(e, spec["pagination"]),
+    }
+    for a in spec.get("actions", []):
+        name = a["name"][0].upper() + a["name"][1:]
+        schemas[f"{e}{name}Input"] = _strict_object(a.get("input", []), lambda _f: True)
+    security_schemes = {
+        s["name"]: _scheme_object(s) for s in spec.get("security", {}).get("schemes", [])
+    }
+    return schemas, security_schemes
+
+
+def _problem(status: str, description: str, component: str = "Problem") -> dict[str, Any]:
+    return {
+        status: {
+            "description": description,
+            "content": {
+                "application/problem+json": {
+                    "schema": {"$ref": f"#/components/schemas/{component}"}
+                }
+            },
+        }
+    }
+
+
+def _json(ref: str) -> dict[str, Any]:
+    return {"content": {"application/json": {"schema": {"$ref": f"#/components/schemas/{ref}"}}}}
+
+
+def _security_for(spec: dict[str, Any], key: str, kind: str) -> dict[str, Any]:
+    security = spec.get("security")
+    if security is None or key not in security.get(kind, {}):
+        return {}
+    schemes = security.get("schemes", [])
+    if not schemes:
+        return {}
+    return {"security": [{schemes[0]["name"]: security[kind][key]}]}
+
+
+def _filter_params(spec: dict[str, Any]) -> list[dict[str, Any]]:
+    out = []
+    for f in spec["fields"]:
+        if not f.get("filterable"):
+            continue
+        bare = {k: v for k, v in f.items() if k not in ("optional", "nullable")}
+        out.append(
+            {
+                "name": f["name"],
+                "in": "query",
+                "required": False,
+                "schema": json_schema_for_field(bare),
+            }
+        )
+    return out
+
+
+def _pagination_params(spec: dict[str, Any]) -> list[dict[str, Any]]:
+    limit = {
+        "name": "limit",
+        "in": "query",
+        "required": False,
+        "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20},
+    }
+    if spec["pagination"] == "cursor":
+        return [
+            limit,
+            {"name": "cursor", "in": "query", "required": False, "schema": {"type": "string"}},
+        ]
+    return [
+        limit,
+        {
+            "name": "offset",
+            "in": "query",
+            "required": False,
+            "schema": {"type": "integer", "minimum": 0, "default": 0},
+        },
+    ]
+
+
+def openapi_paths(spec: dict[str, Any]) -> dict[str, Any]:
+    e = spec["entity"]
+    base = "/" + spec["path"]
+    id_field = next((f for f in spec["fields"] if f.get("role") == "id"), None)
+    if id_field is None:
+        raise ValueError(f'{e}: no field with role "id"')
+    id_bare = {k: v for k, v in id_field.items() if k != "role"}
+    id_param = {
+        "name": id_field["name"],
+        "in": "path",
+        "required": True,
+        "schema": json_schema_for_field(id_bare),
+    }
+    tags = {"tags": spec["tags"]} if "tags" in spec else {}
+    ops = spec["ops"]
+    out: dict[str, Any] = {}
+    collection: dict[str, Any] = {}
+    item: dict[str, Any] = {}
+    filters = _filter_params(spec)
+
+    if "list" in ops:
+        params = sorted(_pagination_params(spec) + filters, key=lambda p: str(p["name"]))
+        responses = {"200": {"description": "OK", **_json(f"{e}ListResponse")}}
+        if filters:
+            responses.update(_problem("400", "Bad Request", "ValidationProblem"))
+        collection["get"] = {
+            **tags,
+            "operationId": f"list{e}",
+            "parameters": params,
+            "responses": responses,
+            **_security_for(spec, "list", "ops"),
+        }
+    if "create" in ops:
+        collection["post"] = {
+            **tags,
+            "operationId": f"create{e}",
+            "requestBody": {"required": True, **_json(f"{e}Create")},
+            "responses": {
+                "201": {"description": "Created", **_json(f"{e}Read")},
+                **_problem("400", "Bad Request", "ValidationProblem"),
+            },
+            **_security_for(spec, "create", "ops"),
+        }
+    if "get" in ops:
+        item["get"] = {
+            **tags,
+            "operationId": f"get{e}",
+            "parameters": [id_param],
+            "responses": {
+                "200": {"description": "OK", **_json(f"{e}Read")},
+                **_problem("404", "Not Found"),
+            },
+            **_security_for(spec, "get", "ops"),
+        }
+    if "update" in ops:
+        item["patch"] = {
+            **tags,
+            "operationId": f"update{e}",
+            "parameters": [id_param],
+            "requestBody": {"required": True, **_json(f"{e}Update")},
+            "responses": {
+                "200": {"description": "OK", **_json(f"{e}Read")},
+                **_problem("400", "Bad Request", "ValidationProblem"),
+                **_problem("404", "Not Found"),
+            },
+            **_security_for(spec, "update", "ops"),
+        }
+    if "delete" in ops:
+        item["delete"] = {
+            **tags,
+            "operationId": f"delete{e}",
+            "parameters": [id_param],
+            "responses": {
+                "204": {"description": "No Content"},
+                **_problem("404", "Not Found"),
+            },
+            **_security_for(spec, "delete", "ops"),
+        }
+    if collection:
+        out[base] = collection
+    if item:
+        out[f"{base}/{{{id_field['name']}}}"] = item
+
+    for a in spec.get("actions", []):
+        name = a["name"][0].upper() + a["name"][1:]
+        responses = {
+            "200": {"description": "OK", **_json(f"{e}Read")},
+            **_problem("400", "Bad Request", "ValidationProblem"),
+            **_problem("404", "Not Found"),
+        }
+        if "from" in a:
+            responses.update(_problem("409", "Conflict"))
+        post: dict[str, Any] = {
+            **tags,
+            "operationId": f"{a['name']}{e}",
+            "parameters": [id_param],
+        }
+        if "description" in a:
+            post["description"] = a["description"]
+        post["requestBody"] = {"required": True, **_json(f"{e}{name}Input")}
+        post["responses"] = responses
+        post.update(_security_for(spec, a["name"], "actions"))
+        out[f"{base}/{{{id_field['name']}}}/actions/{a['name']}"] = {"post": post}
+    return out
+
+
+def openapi_document(specs: list[dict[str, Any]], version: str) -> dict[str, Any]:
+    schemas: dict[str, Any] = dict(PROBLEM_SCHEMAS)
+    security_schemes: dict[str, Any] = {}
+    paths: dict[str, Any] = {}
+    tag_names: set[str] = set()
+
+    for spec in specs:
+        s, sec = openapi_components(spec)
+        schemas.update(s)
+        security_schemes.update(sec)
+        paths.update(openapi_paths(spec))
+        tag_names.update(spec.get("tags", []))
+
+    doc: dict[str, Any] = {
+        "openapi": "3.1.0",
+        "info": {"title": "server-decorator API", "version": version},
+        "paths": paths,
+        "components": {"schemas": schemas},
+    }
+    if tag_names:
+        doc["tags"] = [{"name": n} for n in sorted(tag_names)]
+    if security_schemes:
+        doc["components"]["securitySchemes"] = security_schemes
+    return doc

server_decorator_gen_openapi-2.0.19/tests/unit/test_cases.py

@@ -0,0 +1,38 @@
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from server_decorator_gen_openapi import openapi_document
+
+# test_cases.py -> unit -> tests -> gen_openapi -> packages -> python -> repo root
+_CASES_FILE = Path(__file__).resolve().parents[5] / "contracts/fixtures/entity-spec.cases.json"
+CASES: list[dict[str, Any]] = json.loads(_CASES_FILE.read_text()).get("openapi", [])
+
+
+def _resolve(doc: Any, pointer: str) -> Any:
+    """RFC 6901 JSON Pointer.
+
+    Path keys in an OpenAPI document contain "/" ("/users/{id}"), so a naive split on "/"
+    cannot address them — segments escape "/" as "~1" and "~" as "~0". gen-openapi's Node
+    runner resolves pointers identically; keep the two in step.
+    """
+    node: Any = doc
+    for raw in pointer.split("/")[1:]:
+        if node is None:
+            return None
+        key = raw.replace("~1", "/").replace("~0", "~")
+        node = node[int(key)] if isinstance(node, list) else node.get(key)
+    return node
+
+
+def test_at_least_one_case() -> None:
+    assert len(CASES) > 0
+
+
+@pytest.mark.parametrize("case", CASES, ids=lambda c: str(c["name"]))
+def test_case(case: dict[str, Any]) -> None:
+    doc = openapi_document([case["spec"]], "1.2.0")
+    for pointer, expected in case["expect"].items():
+        assert _resolve(doc, pointer) == expected, pointer

server_decorator_gen_openapi-2.0.19/tests/unit/test_document.py

@@ -0,0 +1,48 @@
+import json
+from pathlib import Path
+
+from server_decorator_entity import entity_spec
+from server_decorator_entity.testing.user_fixture import User
+
+from server_decorator_gen_openapi import openapi_document
+
+# test_document.py -> unit -> tests -> gen_openapi -> packages -> python -> repo root
+_CONTRACTS = Path(__file__).resolve().parents[5] / "contracts"
+# The golden document is emitted with contracts/VERSION (scripts/emit_openapi.py), so the
+# test must read the same file: a hardcoded literal goes stale on every contract bump.
+_VERSION_FILE = _CONTRACTS / "VERSION"
+VERSION = _VERSION_FILE.read_text().strip() if _VERSION_FILE.exists() else "0.0.0"
+
+DOC = openapi_document([entity_spec(User)], VERSION)
+
+
+def test_declares_openapi_31() -> None:
+    assert DOC["openapi"] == "3.1.0"
+    assert DOC["info"] == {"title": "server-decorator API", "version": VERSION}
+
+
+def test_version_argument_is_passed_through_verbatim() -> None:
+    doc = openapi_document([entity_spec(User)], "9.8.7-rc.1")
+    assert doc["info"] == {"title": "server-decorator API", "version": "9.8.7-rc.1"}
+
+
+def test_routes_match_conventions() -> None:
+    assert sorted(DOC["paths"]) == [
+        "/users",
+        "/users/{id}",
+        "/users/{id}/actions/activate",
+        "/users/{id}/actions/ping",
+    ]
+    assert "put" not in DOC["paths"]["/users/{id}"]
+    assert "patch" in DOC["paths"]["/users/{id}"]
+
+
+def test_security_only_on_declared_ops() -> None:
+    assert DOC["paths"]["/users"]["post"]["security"] == [{"bearerAuth": ["user:write"]}]
+    assert "security" not in DOC["paths"]["/users"]["get"]
+
+
+def test_matches_golden_document() -> None:
+    golden = _CONTRACTS / "fixtures/openapi.valid-user.json"
+    if golden.exists():
+        assert DOC == json.loads(golden.read_text())