Skip to content

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.

9.3 KB
Raw Blame
"""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