Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
"""Envelope tests for `POST /v1/codegen` — the typed-artifact projection route.
Pins `conformance/specs/pipelex-codegen.md#route-envelopes`, in the `conformance` repo beside the tests
that verify it: the method's tree as the protocol's `files` map XOR a `method_ref`, read as `/v1/resolve`
reads it; the two explicit projection axes (`kind`, `target`); a produced verdict is a 200
discriminated on `is_valid` with the stamped artifacts + lock on the valid arm; an unknown
`kind`/`target` is a request-shape 422 problem+json; the artifacts a client writes verbatim pass the
offline `codegen check` byte-for-byte.
"""
from collections.abc import Callable
from pathlib import Path
import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pipelex.codegen.check import run_codegen_check
from pipelex.codegen.stamp import comment_prefix_for, parse_stamped
from pipelex.interpreter_hub import get_library_manager
from pytest_mock import MockerFixture
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, STUB_METHOD_ADDRESS, VALID_MTHDS
from tests.unit._problems import assert_problem
def _build_client() -> TestClient:
app = FastAPI()
app.include_router(api_router, prefix="/v1")
register_exception_handlers(app)
return TestClient(app)
class TestCodegenRoute:
@pytest.mark.parametrize(
("target", "expected_filename"),
[
("python-pydantic", "models.py"),
("python-structures", "structures.py"),
("ts-zod", "types.ts"),
],
)
def test_types_projection_returns_stamped_artifacts_and_lock(self, target: str, expected_filename: str):
client = _build_client()
response = client.post(
"/v1/codegen",
json={"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": target},
)
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is True
assert body["kind"] == "types"
assert body["target"] == target
assert body["crate_fingerprint"]
assert body["engine_version"]
artifact_paths = [artifact["path"] for artifact in body["artifacts"]]
assert expected_filename in artifact_paths
# Every artifact is stamped and the stamp agrees with the envelope's fingerprint.
first_artifact = body["artifacts"][0]
stamped = parse_stamped(first_artifact["content"], comment_prefix=comment_prefix_for(first_artifact["path"]))
assert stamped is not None
assert stamped.stamp.crate_fingerprint == body["crate_fingerprint"]
assert body["lock_filename"] == "codegen.lock"
assert body["crate_fingerprint"] in body["lock"]
def test_artifacts_written_verbatim_pass_the_offline_check(self, tmp_path: Path):
# The trust-chain guarantee over HTTP: a client that writes the artifacts and the lock
# verbatim reproduces a local projection — the offline drift check reports it current.
client = _build_client()
response = client.post(
"/v1/codegen",
json={"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "python-pydantic"},
)
assert response.status_code == 200, response.text
body = response.json()
for artifact in body["artifacts"]:
(tmp_path / artifact["path"]).write_text(artifact["content"], encoding="utf-8")
(tmp_path / body["lock_filename"]).write_text(body["lock"], encoding="utf-8")
drift_report = run_codegen_check(root=tmp_path)
assert not drift_report.drifts, f"client-written artifacts must be drift-free, got: {drift_report.drifts}"
def test_invalid_files_return_200_invalid_arm(self):
client = _build_client()
response = client.post(
"/v1/codegen",
json={"files": {"broken.mthds": INVALID_MAIN_PIPE_MTHDS}, "kind": "types", "target": "ts-zod"},
)
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
assert body["errors"], "an invalid verdict must carry a non-empty errors[]"
assert all(item["code"] for item in body["errors"])
assert "artifacts" not in body
@pytest.mark.parametrize(
"payload_patch",
[
{"kind": "does_not_exist"},
{"target": "not-a-target"},
{"kind": "inputs"}, # an editable scaffold, projected client-side from /pipe-io's input form
{"pipe_ref": "smoke.echo"}, # types is concept-set-wide; a pipe selector is a shape error
],
ids=["unknown-kind", "unknown-target", "unserved-kind", "pipe-ref-on-types"],
)
def test_request_shape_errors_are_422_problem_json(self, payload_patch: dict[str, str]):
client = _build_client()
payload: dict[str, object] = {"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "ts-zod"}
payload.update(payload_patch)
response = client.post("/v1/codegen", json=payload)
assert_problem(response, status=422, code="request.invalid")
def test_a_pipe_ref_on_a_concept_set_wide_kind_names_the_pipe_ref(self):
client = _build_client()
payload = {"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "ts-zod", "pipe_ref": "smoke.echo"}
response = client.post("/v1/codegen", json=payload)
assert_problem(response, status=422, code="request.invalid", field="pipe_ref")
def test_an_address_method_ref_projects_the_fetched_package(self, install_method_package: Callable[..., Path]):
install_method_package(files={"documents.mthds": VALID_MTHDS})
client = _build_client()
by_ref = client.post("/v1/codegen", json={"method_ref": f"{STUB_METHOD_ADDRESS}@v0.1.0", "kind": "types", "target": "ts-zod"})
by_tree = client.post("/v1/codegen", json={"files": {"documents.mthds": VALID_MTHDS}, "kind": "types", "target": "ts-zod"})
assert by_ref.status_code == 200, by_ref.text
assert by_ref.json()["is_valid"] is True
# The package's bundle and the same bundle sent in `files` resolve to one crate, so to one projection.
assert by_ref.json()["crate_fingerprint"] == by_tree.json()["crate_fingerprint"]
assert by_ref.json()["artifacts"] == by_tree.json()["artifacts"]
def test_the_retired_list_shape_is_refused_as_no_method_tree(self):
client = _build_client()
response = client.post("/v1/codegen", json={"files": [{"content": VALID_MTHDS}], "kind": "types", "target": "ts-zod"})
assert_problem(response, status=422, code="request.invalid", field="files")
def test_a_registry_form_method_ref_is_an_unsupported_request_until_registry_exists(self):
client = _build_client()
response = client.post("/v1/codegen", json={"method_ref": "acme/methods/x", "kind": "types", "target": "ts-zod"})
problem = assert_problem(response, status=422, code="request.unsupported")
assert problem["params"] == {"field": "method_ref", "reason": "registry_form_method_ref"}
def test_codegen_tears_down_its_library(self, mocker: MockerFixture):
# The engine core leaves the library loaded + current on success; the route owns teardown.
# Conservation property: opens == teardowns (mirrors /resolve's analog).
library_manager = get_library_manager()
open_spy = mocker.spy(library_manager, "open_library")
teardown_spy = mocker.spy(library_manager, "teardown")
client = _build_client()
response = client.post("/v1/codegen", json={"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "python-pydantic"})
assert response.status_code == 200, response.text
assert open_spy.call_count >= 1
assert open_spy.call_count == teardown_spy.call_count
def test_codegen_tears_down_library_when_emission_raises(self, mocker: MockerFixture):
# Leak canary: a failure in the success window — after project_resolved_method's worker left
# the library loaded + current, before its teardown in the finally — must NOT leak that library. The synthetic
# RuntimeError propagates to the global Exception handler (500), and the conservation
# property still holds: opens == teardowns.
library_manager = get_library_manager()
open_spy = mocker.spy(library_manager, "open_library")
teardown_spy = mocker.spy(library_manager, "teardown")
mocker.patch(
"pipelex_api.routes.pipelex.codegen.emit_types",
side_effect=RuntimeError("synthetic emission failure"),
)
# raise_server_exceptions=False: Starlette's ServerErrorMiddleware would otherwise re-raise
# the synthetic RuntimeError through the TestClient (convention of test_exception_handlers.py).
app = FastAPI()
app.include_router(api_router, prefix="/v1")
register_exception_handlers(app)
client = TestClient(app, raise_server_exceptions=False)
response = client.post("/v1/codegen", json={"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "python-pydantic"})
assert response.status_code == 500
assert open_spy.call_count >= 1
assert open_spy.call_count == teardown_spy.call_count