Ryth Azhur
0a95f3c860
Substrate-level gate: same @client fixture registered in both backends
emits equivalent schemas, therefore the codegen produces equivalent
TypeScript regardless of which backend the frontend is generated against.
Catches adapter symmetry problems (Pydantic→OpenAPI converter divergence,
metadata leakage, ordering non-determinism) without docker, browser, or
Playwright.
What ships:
backends/mizan-fastapi/src/mizan_fastapi/schema.py — build_schema():
- Builds OpenAPI 3.0 from registered Mizan functions, mirroring the
shape mizan-django's export emits.
- Drives FastAPI's native OpenAPI generation by registering a stub POST
endpoint per function with its Input/Output Pydantic models, then
appends x-mizan-functions and x-mizan-contexts extensions.
- Param-elevation logic mirrors mizan-django/src/mizan/export/__init__.py
exactly (sharedBy tracking, required iff every function in context has
the param).
- snake_to_camel and metadata field shapes match Django for byte-equality
on the AFI surface.
tests/afi/ — the conformance harness:
- fixture.py: 5 @client functions covering the protocol axes (plain,
context, mutation+affects). No channels/forms — those aren't AFI-common.
- django_app/: minimal Django project (settings, urls, AppConfig.ready
registers the fixture). manage.py adds tests/afi/ to sys.path so both
backends import the same fixture module.
- fastapi_app.py: thin make_app() that registers fixture and mounts router.
- schema_normalizer.py: drops backend-specific framing — Ninja-vs-FastAPI
envelope differences (info/servers/tags), Django-only function fields
(form metadata), x-mizan-channels. Plus afi_subset() and
function_io_schemas() helpers for narrower comparisons.
- test_codegen_parity.py: three gates
1. x-mizan-functions match across backends
2. x-mizan-contexts match across backends
3. Per-function Input/Output OpenAPI schemas match (what codegen feeds
to openapi-typescript for type generation)
The full normalized OpenAPI envelopes do diverge — FastAPI adds
HTTPValidationError, the two converters wrap things slightly differently
in non-AFI-essential ways. That's not in the test scope. The codegen
only consumes x-mizan-functions, x-mizan-contexts, and the per-function
type schemas; those are what the test gates.
Makefile: test-afi target added; rolls into the test aggregate.
Verified: 3/3 conformance tests pass. Other surfaces unaffected —
mizan-core 15/15, mizan-django 348 pass, mizan-fastapi 11/11.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
80 lines
2.6 KiB
Python
80 lines
2.6 KiB
Python
"""
|
|
Normalize an OpenAPI schema dict so backend-specific framing doesn't make
|
|
two semantically-equivalent schemas compare unequal.
|
|
|
|
Drops:
|
|
- Top-level OpenAPI envelope fields that vary trivially (info, servers, tags)
|
|
- Django-only x-mizan-functions sub-fields (form metadata)
|
|
- Django-only top-level extensions (x-mizan-channels)
|
|
|
|
Sorts:
|
|
- x-mizan-functions by name
|
|
- components.schemas keys
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from copy import deepcopy
|
|
from typing import Any
|
|
|
|
|
|
_DJANGO_ONLY_FUNCTION_FIELDS = {"isForm", "formName", "formRole", "formFields", "formFieldsError"}
|
|
|
|
_OPENAPI_ENVELOPE_FIELDS_TO_DROP = {"info", "servers", "tags", "openapi"}
|
|
|
|
|
|
def normalize(schema: dict[str, Any]) -> dict[str, Any]:
|
|
"""Return a canonicalized copy suitable for deep-equal comparison."""
|
|
out = deepcopy(schema)
|
|
|
|
for k in _OPENAPI_ENVELOPE_FIELDS_TO_DROP:
|
|
out.pop(k, None)
|
|
|
|
out.pop("x-mizan-channels", None)
|
|
|
|
fns = out.get("x-mizan-functions") or []
|
|
for fn in fns:
|
|
for field in _DJANGO_ONLY_FUNCTION_FIELDS:
|
|
fn.pop(field, None)
|
|
out["x-mizan-functions"] = sorted(fns, key=lambda f: f["name"])
|
|
|
|
components = out.get("components", {})
|
|
schemas = components.get("schemas")
|
|
if isinstance(schemas, dict):
|
|
components["schemas"] = {k: schemas[k] for k in sorted(schemas)}
|
|
|
|
return out
|
|
|
|
|
|
def afi_subset(schema: dict[str, Any]) -> dict[str, Any]:
|
|
"""Just the AFI-essential surface — what every adapter must agree on."""
|
|
fns = schema.get("x-mizan-functions") or []
|
|
fns_clean = [
|
|
{k: v for k, v in fn.items() if k not in _DJANGO_ONLY_FUNCTION_FIELDS}
|
|
for fn in fns
|
|
]
|
|
return {
|
|
"x-mizan-functions": sorted(fns_clean, key=lambda f: f["name"]),
|
|
"x-mizan-contexts": schema.get("x-mizan-contexts", {}),
|
|
}
|
|
|
|
|
|
def function_io_schemas(schema: dict[str, Any]) -> dict[str, Any]:
|
|
"""
|
|
Subset of components.schemas containing only the per-function Input/Output
|
|
models (what the codegen actually consumes for TypeScript type generation).
|
|
Drops backend-specific noise like HTTPValidationError, ValidationError,
|
|
that one backend emits and the other doesn't.
|
|
"""
|
|
fns = schema.get("x-mizan-functions") or []
|
|
expected_names: set[str] = set()
|
|
for fn in fns:
|
|
if fn.get("inputType"):
|
|
expected_names.add(fn["inputType"])
|
|
if fn.get("outputType"):
|
|
expected_names.add(fn["outputType"])
|
|
|
|
components = schema.get("components", {})
|
|
schemas = components.get("schemas", {})
|
|
return {name: schemas[name] for name in sorted(expected_names) if name in schemas}
|