@mittwald/api-code-generator 0.0.0-development-860f5d6-20261009 → 0.0.0-development-fd38fc6-20261012

package/dist/esm/generation/compileJsonSchema.test.js

@@ -64,3 +64,35 @@ test("const-tagged members compile to a discriminated union", async () => {
           };
     `));
 });
+test("compiles an object schema into an interface", async () => {
+    const output = await compileJsonSchema({
+        type: "object",
+        required: ["id"],
+        properties: { id: { type: "string" }, name: { type: "string" } },
+    }, "Pet");
+    expect(output).toContain("export interface Pet {");
+    expect(output).toContain("id: string;");
+    expect(output).toContain("name?: string;");
+});
+test("emits no banner comment", async () => {
+    const output = await compileJsonSchema({ type: "string" }, "Name");
+    expect(output).not.toContain("/* eslint-disable */");
+    expect(output.trimStart().startsWith("export")).toBe(true);
+});
+test("disallows additional properties by default", async () => {
+    const output = await compileJsonSchema({ type: "object", properties: { id: { type: "string" } } }, "Pet");
+    expect(output).not.toContain("[k: string]: unknown");
+});
+test("lets callers override the defaults", async () => {
+    const output = await compileJsonSchema({ type: "object", properties: { id: { type: "string" } } }, "Pet", { additionalProperties: true });
+    expect(output).toContain("[k: string]: unknown");
+});
+test("compiles a scalar schema into a type alias", async () => {
+    const output = await compileJsonSchema({ type: "string" }, "Name");
+    expect(output).toContain("export type Name = string;");
+});
+test("compiles an enum into a union", async () => {
+    const output = await compileJsonSchema({ type: "string", enum: ["asc", "desc"] }, "Order");
+    expect(output).toContain('"asc"');
+    expect(output).toContain('"desc"');
+});

package/dist/esm/generation/format.test.js

@@ -0,0 +1,46 @@
+import { format } from "./format.js";
+import { prepareTypeScriptOutput } from "./prepareTypeScriptOutput.js";
+describe("format", () => {
+    test("formats TypeScript source", async () => {
+        await expect(format("const   a={b:1}")).resolves.toBe("const a = { b: 1 };\n");
+    });
+    test("keeps already formatted source stable", async () => {
+        const formatted = await format("const a = 1;\n");
+        expect(await format(formatted)).toBe(formatted);
+    });
+    test("formats type declarations", async () => {
+        await expect(format("type A={b:string}")).resolves.toBe("type A = { b: string };\n");
+    });
+    test("reports a syntax error as a CodeFormattingError", async () => {
+        await expect(format("const a = {")).rejects.toMatchObject({
+            name: "CodeFormattingError",
+        });
+    });
+    test("points at the likely cause in the error message", async () => {
+        await expect(format("const a = {")).rejects.toThrow("Failed to format the generated code");
+    });
+    test("keeps the underlying prettier error as cause", async () => {
+        const error = await format("const a = {").catch((e) => e);
+        expect(error.cause()).toBeInstanceOf(Error);
+    });
+});
+describe("prepareTypeScriptOutput", () => {
+    test("prepends the generated-file header", async () => {
+        const output = await prepareTypeScriptOutput("const a=1");
+        expect(output).toBe([
+            "/* eslint-disable */",
+            "/* prettier-ignore */",
+            "/* This file is auto-generated with acg (@mittwald/api-code-generator) */",
+            "const a = 1;",
+            "",
+        ].join("\n"));
+    });
+    test("marks the output so lint and prettier skip it", async () => {
+        const output = await prepareTypeScriptOutput("const a=1");
+        expect(output).toContain("/* eslint-disable */");
+        expect(output).toContain("/* prettier-ignore */");
+    });
+    test("propagates formatting failures", async () => {
+        await expect(prepareTypeScriptOutput("const a = {")).rejects.toThrow("Failed to format the generated code");
+    });
+});

package/dist/esm/generation/model/CodeGenerationModel.test.js

@@ -1,5 +1,6 @@
 import { OpenApiSpec } from "../../openapi/OpenApiSpec.js";
 import { CodeGenerationModel } from "./CodeGenerationModel.js";
+import { makePetstoreDoc } from "./__fixtures__/petstore.js";
 const normalize = (typeScript) => typeScript.replace(/\s+/g, " ").trim();
 /**
  * End-to-end check for the `const` keyword: an OpenAPI document describing a
@@ -64,3 +65,157 @@ test("const keywords survive from the spec into the generated types", async () =
         | Api.Components.Schemas.DoneEvent;
     `));
 });
+const buildModel = (doc = makePetstoreDoc()) => CodeGenerationModel.fromDoc("PetstoreAPI", doc);
+const compile = (doc = makePetstoreDoc()) => buildModel(doc).compileTypes({ rootNamespace: "PetstoreAPI" });
+/** Collapses whitespace so assertions do not depend on generated indentation. */
+const flat = (s) => s.replace(/\s+/g, " ");
+describe("model structure", () => {
+    test("names the root namespace", () => {
+        expect(buildModel().rootNamespace.tsType).toBe("PetstoreAPI");
+    });
+    test("keeps the source document", () => {
+        const doc = makePetstoreDoc();
+        expect(buildModel(doc).doc).toBe(doc);
+    });
+    test("builds a Tag per documented tag", () => {
+        const { tags } = buildModel();
+        expect(tags.map((t) => t.name.raw)).toEqual(["pet", "store"]);
+        expect(tags[0].description).toBe("Everything about pets");
+        expect(tags[1].description).toBeUndefined();
+    });
+    test("tolerates a document without tags", () => {
+        const model = buildModel({ ...makePetstoreDoc(), tags: undefined });
+        expect(model.tags).toEqual([]);
+    });
+});
+describe("compiled types", () => {
+    let types;
+    beforeAll(async () => {
+        types = await compile();
+    });
+    test("wraps everything in the root namespace", () => {
+        expect(types).toContain("export declare module PetstoreAPI {");
+    });
+    test("imports the descriptors and the commons helper types", () => {
+        expect(types).toContain('import * as descriptors from "./descriptors.js"');
+        expect(flat(types)).toContain('InferredRequestData, InferredResponseData, HttpStatus } from "@mittwald/api-client-commons"');
+    });
+    test("declares an Operations namespace entry per operation", () => {
+        for (const operation of ["ListPets", "CreatePet", "GetPet", "DeletePet"]) {
+            expect(types).toContain(`namespace ${operation} {`);
+        }
+    });
+    test("wires operation request and response data to the descriptors", () => {
+        expect(flat(types)).toContain("type RequestData = InferredRequestData<typeof descriptors.listPets>;");
+        expect(flat(types)).toContain("type ResponseData<TStatus extends HttpStatus = 200> = InferredResponseData<typeof descriptors.listPets, TStatus>;");
+    });
+    test("compiles component schemas into interfaces", () => {
+        expect(flat(types)).toContain("export interface Pet { id: string; name: string; nickname?: string | null; tags?: PetstoreAPI.Components.Schemas.Tag[]; }");
+    });
+    test("turns schema refs into fully namespaced type references", () => {
+        expect(types).toContain("PetstoreAPI.Components.Schemas.Tag[]");
+    });
+    test("marks a nullable property as nullable", () => {
+        expect(flat(types)).toContain("nickname?: string | null;");
+    });
+    test("keeps required properties required", () => {
+        expect(flat(types)).toContain("export interface Tag { label: string; }");
+    });
+    test("compiles component parameters", () => {
+        expect(flat(types)).toContain("export type PetId = string;");
+    });
+    test("compiles component responses through to the referenced schema", () => {
+        expect(flat(types)).toContain("export type ApplicationJson = PetstoreAPI.Components.Schemas.Error;");
+    });
+    test("compiles the security scheme into a required header", () => {
+        expect(flat(types)).toContain('export interface AccessToken { "x-access-token": string; }');
+    });
+    test("derives a path namespace name from the path template", () => {
+        expect(types).toContain("namespace Pets {");
+        expect(types).toContain("namespace PetsPetId {");
+    });
+    test("declares a namespace per HTTP method of a path", () => {
+        expect(types).toContain("namespace Get {");
+        expect(types).toContain("namespace Post {");
+        expect(types).toContain("namespace Delete {");
+    });
+    test("splits operation parameters by location", () => {
+        expect(flat(types)).toContain("export type Query = { limit?: number; };");
+        expect(flat(types)).toContain('export type Header = { "x-access-token": string; };');
+        expect(flat(types)).toContain("export type Path = { petId: PetstoreAPI.Components.Parameters.PetId; };");
+    });
+    test("emits an empty parameter type where a location has no parameters", () => {
+        expect(flat(types)).toContain("export type Path = {};");
+    });
+    test("declares a namespace per response status", () => {
+        expect(types).toContain("namespace $200 {");
+        expect(types).toContain("namespace $201 {");
+        expect(types).toContain("namespace $204 {");
+        expect(types).toContain("namespace Default {");
+    });
+    test("types an inline array response through to the item schema", () => {
+        expect(flat(types)).toContain("export type ApplicationJson = PetstoreAPI.Components.Schemas.Pet[];");
+    });
+    test("resolves a referenced request body to its component type", () => {
+        expect(flat(types)).toContain("export type RequestBody = PetstoreAPI.Components.RequestBodies.PetBody;");
+    });
+    /**
+     * `ResponseContentTypes.buildContentTypesFromReferenceObject` passes
+     * `c.schema` — a `JSONSchema` _model instance_ — into `ResponseContent`,
+     * whose parameter is a raw JSON schema object. The instance is then wrapped
+     * in another `JSONSchema`, so nothing usable reaches
+     * `json-schema-to-typescript` and it falls back to an index signature.
+     * `c.schema.schemaObject` is what it should pass.
+     *
+     * Every error response in the real mittwald spec is a `$ref` to a component
+     * response, so every error payload in the published client is untyped even
+     * though `Components.Responses.*.ApplicationJson` is generated correctly.
+     */
+    test("loses the type of a response that references a component response", () => {
+        expect(flat(types)).toContain("export interface ApplicationJson { [k: string]: unknown; }");
+        expect(flat(types)).not.toContain("export type ApplicationJson = PetstoreAPI.Components.Responses.NotFound.ApplicationJson;");
+    });
+    /** Same root cause, reached through the request body component. */
+    test("loses the type of a request body component that references a schema", () => {
+        expect(flat(types)).toContain("export interface PetBody { [k: string]: unknown; }");
+    });
+});
+describe("compiled descriptors", () => {
+    let descriptors;
+    beforeAll(() => {
+        descriptors = buildModel().paths.compileDescriptors();
+    });
+    test("exports a descriptor per operation", () => {
+        for (const operationId of [
+            "listPets",
+            "createPet",
+            "getPet",
+            "deletePet",
+        ]) {
+            expect(descriptors).toContain(operationId);
+        }
+    });
+    test("records the path and method of each operation", () => {
+        expect(flat(descriptors)).toContain('path: "/pets/{petId}"');
+        expect(flat(descriptors)).toContain('method: "DELETE"');
+        expect(flat(descriptors)).toContain('method: "GET"');
+        expect(flat(descriptors)).toContain('method: "POST"');
+    });
+    test("records the response statuses and media types", () => {
+        expect(flat(descriptors)).toContain('"application/json"');
+        expect(flat(descriptors)).toContain('"default"');
+    });
+});
+describe("optional headers", () => {
+    test("makes a named header optional in the generated parameter type", async () => {
+        const types = await buildModel().compileTypes({
+            rootNamespace: "PetstoreAPI",
+            optionalHeaders: ["x-access-token"],
+        });
+        expect(flat(types)).toContain('export type Header = { "x-access-token"?: string; };');
+    });
+    test("leaves the header required when it is not listed", async () => {
+        const types = await compile();
+        expect(flat(types)).toContain('export type Header = { "x-access-token": string; };');
+    });
+});

package/dist/esm/generation/model/__fixtures__/petstore.js

@@ -0,0 +1,152 @@
+/**
+ * A deliberately small but structurally complete OpenAPI v3 document: refs
+ * between components, both safe and unsafe operations, path/query/header
+ * parameters, several response statuses, and a security scheme. It exercises
+ * the code generation model without the bulk of a real spec.
+ *
+ * Returned fresh on every call: building a `CodeGenerationModel` runs
+ * `populateNullableTypes` over the document and mutates it in place, so a
+ * shared instance would accumulate changes between tests.
+ */
+export const makePetstoreDoc = () => ({
+    openapi: "3.0.3",
+    info: { title: "Petstore", version: "1.0.0" },
+    tags: [
+        { name: "pet", description: "Everything about pets" },
+        { name: "store" },
+    ],
+    components: {
+        securitySchemes: {
+            accessToken: {
+                type: "apiKey",
+                in: "header",
+                name: "x-access-token",
+            },
+        },
+        schemas: {
+            Pet: {
+                type: "object",
+                required: ["id", "name"],
+                properties: {
+                    id: { type: "string" },
+                    name: { type: "string" },
+                    nickname: { type: "string", nullable: true },
+                    tags: { type: "array", items: { $ref: "#/components/schemas/Tag" } },
+                },
+            },
+            Tag: {
+                type: "object",
+                required: ["label"],
+                properties: { label: { type: "string" } },
+            },
+            Error: {
+                type: "object",
+                required: ["message"],
+                properties: { message: { type: "string" } },
+            },
+        },
+        parameters: {
+            PetId: {
+                name: "petId",
+                in: "path",
+                required: true,
+                schema: { type: "string" },
+            },
+        },
+        requestBodies: {
+            PetBody: {
+                required: true,
+                content: {
+                    "application/json": { schema: { $ref: "#/components/schemas/Pet" } },
+                },
+            },
+        },
+        responses: {
+            NotFound: {
+                description: "Not found",
+                content: {
+                    "application/json": {
+                        schema: { $ref: "#/components/schemas/Error" },
+                    },
+                },
+            },
+        },
+    },
+    paths: {
+        "/pets": {
+            get: {
+                operationId: "listPets",
+                tags: ["pet"],
+                parameters: [
+                    {
+                        name: "limit",
+                        in: "query",
+                        required: false,
+                        schema: { type: "integer" },
+                    },
+                    {
+                        name: "x-access-token",
+                        in: "header",
+                        required: true,
+                        schema: { type: "string" },
+                    },
+                ],
+                responses: {
+                    "200": {
+                        description: "A list of pets",
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "array",
+                                    items: { $ref: "#/components/schemas/Pet" },
+                                },
+                            },
+                        },
+                    },
+                    default: { $ref: "#/components/responses/NotFound" },
+                },
+            },
+            post: {
+                operationId: "createPet",
+                tags: ["pet"],
+                requestBody: { $ref: "#/components/requestBodies/PetBody" },
+                responses: {
+                    "201": {
+                        description: "The created pet",
+                        content: {
+                            "application/json": {
+                                schema: { $ref: "#/components/schemas/Pet" },
+                            },
+                        },
+                    },
+                    "400": { $ref: "#/components/responses/NotFound" },
+                },
+            },
+        },
+        "/pets/{petId}": {
+            get: {
+                operationId: "getPet",
+                tags: ["pet"],
+                parameters: [{ $ref: "#/components/parameters/PetId" }],
+                responses: {
+                    "200": {
+                        description: "The pet",
+                        content: {
+                            "application/json": {
+                                schema: { $ref: "#/components/schemas/Pet" },
+                            },
+                        },
+                    },
+                    "404": { $ref: "#/components/responses/NotFound" },
+                },
+            },
+            delete: {
+                operationId: "deletePet",
+                parameters: [{ $ref: "#/components/parameters/PetId" }],
+                responses: {
+                    "204": { description: "Deleted" },
+                },
+            },
+        },
+    },
+});

package/dist/esm/generation/model/tags/Tag.test.js

@@ -0,0 +1,13 @@
+import { Tag } from "./Tag.js";
+test("keeps the raw tag name", () => {
+    expect(Tag.fromDoc({ name: "pet" }).name.raw).toBe("pet");
+});
+test("derives a TypeScript type name from the tag name", () => {
+    expect(Tag.fromDoc({ name: "pet-store" }).name.tsType).toBe("PetStore");
+});
+test("keeps the description when present", () => {
+    expect(Tag.fromDoc({ name: "pet", description: "About pets" }).description).toBe("About pets");
+});
+test("leaves the description undefined when absent", () => {
+    expect(Tag.fromDoc({ name: "pet" }).description).toBeUndefined();
+});

package/dist/esm/generation/populateNullableTypes.test.js

@@ -0,0 +1,153 @@
+import { populateNullableTypes } from "./populateNullableTypes.js";
+const populate = (schema) => populateNullableTypes(schema);
+describe("non-nullable schemas", () => {
+    test("are returned unchanged", () => {
+        expect(populate({ type: "string" })).toEqual({ type: "string" });
+    });
+    test("are returned unchanged when nullable is false", () => {
+        expect(populate({ type: "string", nullable: false })).toEqual({
+            type: "string",
+            nullable: false,
+        });
+    });
+});
+describe("nullable schemas", () => {
+    test("are wrapped in an anyOf with a null branch", () => {
+        expect(populate({ type: "string", nullable: true })).toEqual({
+            anyOf: [{ type: "string", nullable: true }, { type: "null" }],
+        });
+    });
+    test("keep sibling keywords inside the anyOf branch", () => {
+        expect(populate({ type: "string", nullable: true, maxLength: 5 })).toEqual({
+            anyOf: [
+                { type: "string", nullable: true, maxLength: 5 },
+                { type: "null" },
+            ],
+        });
+    });
+});
+describe("references", () => {
+    test("are returned unchanged", () => {
+        const ref = { $ref: "#/components/schemas/Project" };
+        expect(populateNullableTypes(ref)).toBe(ref);
+    });
+});
+describe("nested structures", () => {
+    test("nullable object properties are wrapped", () => {
+        const result = populate({
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                description: { type: "string", nullable: true },
+            },
+        });
+        expect(result.properties?.name).toEqual({ type: "string" });
+        expect(result.properties?.description).toEqual({
+            anyOf: [{ type: "string", nullable: true }, { type: "null" }],
+        });
+    });
+    test("nullable array items are wrapped", () => {
+        const result = populate({
+            type: "array",
+            items: { type: "string", nullable: true },
+        });
+        expect(result).toEqual({
+            type: "array",
+            items: { anyOf: [{ type: "string", nullable: true }, { type: "null" }] },
+        });
+    });
+    test("recurses into deeply nested properties", () => {
+        const result = populate({
+            type: "object",
+            properties: {
+                outer: {
+                    type: "object",
+                    properties: { inner: { type: "number", nullable: true } },
+                },
+            },
+        });
+        const outer = result.properties?.outer;
+        expect(outer.properties?.inner).toEqual({
+            anyOf: [{ type: "number", nullable: true }, { type: "null" }],
+        });
+    });
+    test.each(["allOf", "anyOf", "oneOf"])("recurses into %s branches", (key) => {
+        const result = populate({
+            [key]: [{ type: "string", nullable: true }, { type: "number" }],
+        });
+        expect(result[key]).toEqual([
+            { anyOf: [{ type: "string", nullable: true }, { type: "null" }] },
+            { type: "number" },
+        ]);
+    });
+    test("leaves references inside properties untouched", () => {
+        const result = populate({
+            type: "object",
+            properties: { project: { $ref: "#/components/schemas/Project" } },
+        });
+        expect(result.properties?.project).toEqual({
+            $ref: "#/components/schemas/Project",
+        });
+    });
+    test("wraps a nullable schema that also has nullable properties", () => {
+        const result = populate({
+            type: "object",
+            nullable: true,
+            properties: { name: { type: "string", nullable: true } },
+        });
+        const branch = result.anyOf?.[0];
+        expect(result.anyOf?.[1]).toEqual({ type: "null" });
+        expect(branch.properties?.name).toEqual({
+            anyOf: [{ type: "string", nullable: true }, { type: "null" }],
+        });
+    });
+});
+describe("mutation of the input", () => {
+    /**
+     * The function rewrites `properties`, `items` and the composition keys on the
+     * schema it was given rather than on a copy. Callers that keep the original
+     * document around — or that build a second model from it — see the rewritten
+     * version.
+     */
+    test("rewrites nested properties on the given schema, not a copy", () => {
+        const schema = {
+            type: "object",
+            properties: { name: { type: "string", nullable: true } },
+        };
+        populate(schema);
+        expect(schema.properties?.name).toEqual({
+            anyOf: [{ type: "string", nullable: true }, { type: "null" }],
+        });
+    });
+    /**
+     * Because the wrapped branch keeps its `nullable: true`, applying the
+     * function twice to the same object nests another `anyOf`. A schema visited n
+     * times therefore compiles to n nested `| null` unions — which is why a
+     * shared OpenAPI document must not be fed to two models.
+     */
+    test("compounds when applied twice to the same schema", () => {
+        const schema = {
+            type: "object",
+            properties: { name: { type: "string", nullable: true } },
+        };
+        populate(schema);
+        populate(schema);
+        expect(schema.properties?.name).toEqual({
+            anyOf: [
+                {
+                    anyOf: [{ type: "string", nullable: true }, { type: "null" }],
+                },
+                { type: "null" },
+            ],
+        });
+    });
+    test("is idempotent for a schema with no nullable members", () => {
+        const schema = {
+            type: "object",
+            properties: { name: { type: "string" } },
+        };
+        populate(schema);
+        populate(schema);
+        expect(schema.properties?.name).toEqual({ type: "string" });
+    });
+});

package/dist/esm/generation/refs/assertNoRefs.test.js

@@ -0,0 +1,10 @@
+import { assertNoRefs } from "./assertNoRefs.js";
+test("passes for a plain schema object", () => {
+    expect(() => assertNoRefs({ type: "string" })).not.toThrow();
+});
+test("passes for an empty object", () => {
+    expect(() => assertNoRefs({})).not.toThrow();
+});
+test("throws for a reference object", () => {
+    expect(() => assertNoRefs({ $ref: "#/components/schemas/Project" })).toThrow("$ref's are not supported here (ref: #/components/schemas/Project)");
+});

package/dist/esm/generation/refs/extractComponentRefName.test.js

@@ -0,0 +1,19 @@
+import { extractComponentRefName } from "./extractComponentRefName.js";
+test("extracts the name of a schema ref", () => {
+    expect(extractComponentRefName("#/components/schemas/Project", "schemas")).toBe("Project");
+});
+test("extracts the name of a response ref", () => {
+    expect(extractComponentRefName("#/components/responses/NotFound", "responses")).toBe("NotFound");
+});
+test("only looks at the last two segments", () => {
+    expect(extractComponentRefName("#/foo/bar/components/schemas/Project", "schemas")).toBe("Project");
+});
+test("rejects a ref that belongs to a different component type", () => {
+    expect(() => extractComponentRefName("#/components/schemas/Project", "responses")).toThrow("Could not extract ref name (component: responses, ref: #/components/schemas/Project)");
+});
+test("rejects a ref without a component segment", () => {
+    expect(() => extractComponentRefName("#/Project", "schemas")).toThrow("Could not extract ref name");
+});
+test("rejects an empty ref", () => {
+    expect(() => extractComponentRefName("#/", "schemas")).toThrow("Could not extract ref name");
+});

package/dist/esm/generation/refs/isRef.test.js

@@ -0,0 +1,19 @@
+import { isRef } from "./isRef.js";
+test("recognizes a reference object", () => {
+    expect(isRef({ $ref: "#/components/schemas/Project" })).toBe(true);
+});
+test("rejects an object without $ref", () => {
+    expect(isRef({ type: "string" })).toBe(false);
+});
+test("rejects an empty object", () => {
+    expect(isRef({})).toBe(false);
+});
+test("rejects a $ref that is not a string", () => {
+    expect(isRef({ $ref: 42 })).toBe(false);
+});
+test("accepts an empty $ref string", () => {
+    expect(isRef({ $ref: "" })).toBe(true);
+});
+test("recognizes a schema that carries both $ref and other keys", () => {
+    expect(isRef({ $ref: "#/components/schemas/Project", description: "a project" })).toBe(true);
+});

package/dist/esm/generation/tsNamespaceName.test.js

@@ -0,0 +1,13 @@
+import { tsNamespaceName } from "./tsNamespaceName.js";
+test("joins a single part", () => {
+    expect(tsNamespaceName("components")).toBe("Components");
+});
+test("joins multiple parts with dots", () => {
+    expect(tsNamespaceName("components", "schemas")).toBe("Components.Schemas");
+});
+test("converts each part to a TypeScript type name", () => {
+    expect(tsNamespaceName("my-api", "some_schemas")).toBe("MyApi.SomeSchemas");
+});
+test("returns an empty string for no parts", () => {
+    expect(tsNamespaceName()).toBe("");
+});

package/dist/esm/lib/makeError.test.js

@@ -0,0 +1,36 @@
+import { makeError } from "./makeError.js";
+test("passes an Error through unchanged", () => {
+    const error = new TypeError("boom");
+    expect(makeError(error)).toBe(error);
+});
+test("passes a subclass of Error through unchanged", () => {
+    class CustomError extends Error {
+    }
+    const error = new CustomError("boom");
+    expect(makeError(error)).toBe(error);
+});
+test("wraps an error-shaped object, keeping name and message", () => {
+    const error = makeError({ name: "HttpError", message: "not found" });
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe("HttpError");
+    expect(error.message).toBe("not found");
+});
+test("falls back to the Error name when none is given", () => {
+    expect(makeError({ message: "boom" }).name).toBe("Error");
+});
+test("falls back to an empty message when none is given", () => {
+    expect(makeError({ name: "HttpError" }).message).toBe("");
+});
+/**
+ * `dot-prop` returns the value itself when the subject is not an object, so a
+ * thrown string ends up as both the name and the message of the wrapper.
+ */
+test("wraps a thrown string, using it as name and message", () => {
+    const error = makeError("boom");
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe("boom");
+    expect(error.message).toBe("boom");
+});
+test("wraps undefined into an Error", () => {
+    expect(makeError(undefined)).toBeInstanceOf(Error);
+});

package/dist/esm/lib/relativePath.test.js

@@ -0,0 +1,16 @@
+import * as path from "path";
+import * as url from "url";
+import { relativePath } from "./relativePath.js";
+const meta = { url: url.pathToFileURL("/tmp/project/src/lib/thing.ts").href };
+test("resolves a path relative to the importing module's directory", () => {
+    expect(relativePath(meta, "template.txt")).toBe(path.join("/tmp/project/src/lib", "template.txt"));
+});
+test("joins multiple segments", () => {
+    expect(relativePath(meta, "templates", "type.ts")).toBe(path.join("/tmp/project/src/lib", "templates", "type.ts"));
+});
+test("returns the module directory, trailing separator included, when no segments are given", () => {
+    expect(relativePath(meta)).toBe(`${path.sep}tmp${path.sep}project${path.sep}src${path.sep}lib${path.sep}`);
+});
+test("normalizes parent-directory segments", () => {
+    expect(relativePath(meta, "..", "other.ts")).toBe(path.join("/tmp/project/src", "other.ts"));
+});

package/dist/esm/lib/writeIfChangedAsync.test.js

@@ -0,0 +1,37 @@
+import { jest } from "@jest/globals";
+import jetpack from "fs-jetpack";
+import { writeIfChangedAsync } from "./writeIfChangedAsync.js";
+const readAsync = jest.spyOn(jetpack, "readAsync");
+const writeAsync = jest.spyOn(jetpack, "writeAsync");
+beforeEach(() => {
+    readAsync.mockReset();
+    writeAsync.mockReset().mockResolvedValue(undefined);
+});
+afterAll(() => {
+    jest.restoreAllMocks();
+});
+test("writes when the file does not exist yet", async () => {
+    readAsync.mockResolvedValue(undefined);
+    await writeIfChangedAsync("out.ts", "content");
+    expect(writeAsync).toHaveBeenCalledWith("out.ts", "content");
+});
+test("writes when the content changed", async () => {
+    readAsync.mockResolvedValue("old content");
+    await writeIfChangedAsync("out.ts", "new content");
+    expect(writeAsync).toHaveBeenCalledWith("out.ts", "new content");
+});
+test("does not write when the content is unchanged", async () => {
+    readAsync.mockResolvedValue("content");
+    await writeIfChangedAsync("out.ts", "content");
+    expect(writeAsync).not.toHaveBeenCalled();
+});
+test("treats a trailing-whitespace difference as a change", async () => {
+    readAsync.mockResolvedValue("content");
+    await writeIfChangedAsync("out.ts", "content\n");
+    expect(writeAsync).toHaveBeenCalledWith("out.ts", "content\n");
+});
+test("reads the file it is about to write", async () => {
+    readAsync.mockResolvedValue("content");
+    await writeIfChangedAsync("some/nested/out.ts", "content");
+    expect(readAsync).toHaveBeenCalledWith("some/nested/out.ts");
+});

package/dist/esm/loading/UniversalFileLoader.test.js

@@ -0,0 +1,50 @@
+import { jest } from "@jest/globals";
+import jetpack from "fs-jetpack";
+import nock from "nock";
+import { UniversalFileLoader } from "./UniversalFileLoader.js";
+const readAsync = jest.spyOn(jetpack, "readAsync");
+beforeEach(() => {
+    readAsync.mockReset();
+});
+afterEach(() => {
+    nock.cleanAll();
+});
+afterAll(() => {
+    jest.restoreAllMocks();
+});
+describe("source", () => {
+    test("is kept as given", () => {
+        expect(new UniversalFileLoader("spec.json").source).toBe("spec.json");
+    });
+});
+describe("loading from a file", () => {
+    test("returns the file content", async () => {
+        readAsync.mockResolvedValue("{}");
+        await expect(new UniversalFileLoader("spec.json").load()).resolves.toBe("{}");
+        expect(readAsync).toHaveBeenCalledWith("spec.json");
+    });
+    test("rejects when the file does not exist", async () => {
+        readAsync.mockResolvedValue(undefined);
+        await expect(new UniversalFileLoader("missing.json").load()).rejects.toThrow("File not found: missing.json");
+    });
+    test("treats a relative path as a file, not a URL", async () => {
+        readAsync.mockResolvedValue("{}");
+        await new UniversalFileLoader("./spec/openapi.json").load();
+        expect(readAsync).toHaveBeenCalledWith("./spec/openapi.json");
+    });
+});
+describe("loading from a URL", () => {
+    test("fetches http sources", async () => {
+        nock("http://example.com").get("/openapi.json").reply(200, "{}");
+        await expect(new UniversalFileLoader("http://example.com/openapi.json").load()).resolves.toBe("{}");
+        expect(readAsync).not.toHaveBeenCalled();
+    });
+    test("fetches https sources", async () => {
+        nock("https://example.com").get("/openapi.json").reply(200, "{}");
+        await expect(new UniversalFileLoader("https://example.com/openapi.json").load()).resolves.toBe("{}");
+    });
+    test("rejects a non-200 response", async () => {
+        nock("https://example.com").get("/openapi.json").reply(404, "nope");
+        await expect(new UniversalFileLoader("https://example.com/openapi.json").load()).rejects.toThrow();
+    });
+});

package/dist/esm/openapi/OpenAPISchemaValidationError.test.js

@@ -0,0 +1,27 @@
+import { OpenAPISchemaValidationError } from "./OpenAPISchemaValidationError.js";
+const errors = (...items) => items;
+test("prefixes the message so the source of the failure is clear", () => {
+    const error = new OpenAPISchemaValidationError(errors({ instancePath: "/paths", message: "is required" }));
+    expect(error.message).toContain("OpenAPI is invalid:");
+});
+test("numbers each validation error", () => {
+    const error = new OpenAPISchemaValidationError(errors({ instancePath: "/paths", message: "is required" }, { instancePath: "/info", message: "is required" }));
+    expect(error.message).toContain("#1");
+    expect(error.message).toContain("#2");
+});
+test("dumps each error as YAML so nested details stay readable", () => {
+    const error = new OpenAPISchemaValidationError(errors({ instancePath: "/paths", message: "is required" }));
+    expect(error.message).toContain("instancePath: /paths");
+    expect(error.message).toContain("message: is required");
+});
+test("uses its own name instead of the inherited one", () => {
+    expect(new OpenAPISchemaValidationError(errors()).name).toBe("OpenAPISchemaValidationError");
+});
+test("is recognizable via instanceof after the prototype fix-up", () => {
+    const error = new OpenAPISchemaValidationError(errors());
+    expect(error).toBeInstanceOf(OpenAPISchemaValidationError);
+    expect(error).toBeInstanceOf(Error);
+});
+test("handles an empty error list", () => {
+    expect(new OpenAPISchemaValidationError(errors()).message).toBe("OpenAPI is invalid: ");
+});

package/dist/esm/openapi/OpenApiSpec.test.js

@@ -1,4 +1,6 @@
 import { OpenApiSpec } from "./OpenApiSpec.js";
+import { OpenAPISchemaValidationError } from "./OpenAPISchemaValidationError.js";
+import { makePetstoreDoc } from "../generation/model/__fixtures__/petstore.js";
 const documentWithSchemas = (schemas) => ({
     openapi: "3.0.3",
     info: { title: "Test", version: "1.0.0" },
@@ -47,3 +49,67 @@ test("unknown schema keywords are still rejected", async () => {
         Broken: { type: "string", definitelyNotAKeyword: true },
     }))).rejects.toThrow(/Failed parsing OpenAPISpec/);
 });
+describe("parsing a valid v3 document", () => {
+    test("keeps the document as-is", async () => {
+        const doc = makePetstoreDoc();
+        const spec = await OpenApiSpec.parse(doc);
+        expect(spec.document).toBe(doc);
+    });
+    test("exposes the document through the instance", async () => {
+        const spec = await OpenApiSpec.parse(makePetstoreDoc());
+        expect(spec.document.info.title).toBe("Petstore");
+        expect(Object.keys(spec.document.paths)).toEqual([
+            "/pets",
+            "/pets/{petId}",
+        ]);
+    });
+    test("accepts a document constructed directly", () => {
+        const doc = makePetstoreDoc();
+        expect(new OpenApiSpec(doc).document).toBe(doc);
+    });
+});
+describe("validation", () => {
+    const invalidDoc = { openapi: "3.0.3", info: { title: "Broken" } };
+    test("rejects a document that does not satisfy the OpenAPI schema", async () => {
+        await expect(OpenApiSpec.parse(invalidDoc)).rejects.toThrow("Failed parsing OpenAPISpec");
+    });
+    test("names the failure OpenAPIParserError", async () => {
+        await expect(OpenApiSpec.parse(invalidDoc)).rejects.toMatchObject({
+            name: "OpenAPIParserError",
+        });
+    });
+    test("keeps the validation error as the cause", async () => {
+        const error = await OpenApiSpec.parse(invalidDoc).catch((e) => e);
+        expect(error.cause()).toBeInstanceOf(OpenAPISchemaValidationError);
+    });
+    test("accepts the same document when validation is skipped", async () => {
+        const spec = await OpenApiSpec.parse(invalidDoc, { skipValidation: true });
+        expect(spec.document.info.title).toBe("Broken");
+    });
+});
+describe("swagger 2 conversion", () => {
+    const swaggerDoc = {
+        swagger: "2.0",
+        info: { title: "Legacy", version: "1.0.0" },
+        paths: {
+            "/pets": {
+                get: {
+                    operationId: "listPets",
+                    responses: {
+                        "200": { description: "ok", schema: { type: "array", items: {} } },
+                    },
+                },
+            },
+        },
+    };
+    test("converts a swagger 2 document to OpenAPI 3", async () => {
+        const spec = await OpenApiSpec.parse(swaggerDoc);
+        expect(spec.document.openapi).toMatch(/^3\./);
+        expect(spec.document.paths["/pets"]?.get?.operationId).toBe("listPets");
+    });
+});
+describe("malformed input", () => {
+    test("rejects a document without a version field", async () => {
+        await expect(OpenApiSpec.parse({ info: {} })).rejects.toThrow("Failed parsing OpenAPISpec");
+    });
+});

package/dist/types/generation/format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/generation/model/__fixtures__/petstore.d.ts

@@ -0,0 +1,12 @@
+import { OpenAPIV3 } from "openapi-types";
+/**
+ * A deliberately small but structurally complete OpenAPI v3 document: refs
+ * between components, both safe and unsafe operations, path/query/header
+ * parameters, several response statuses, and a security scheme. It exercises
+ * the code generation model without the bulk of a real spec.
+ *
+ * Returned fresh on every call: building a `CodeGenerationModel` runs
+ * `populateNullableTypes` over the document and mutates it in place, so a
+ * shared instance would accumulate changes between tests.
+ */
+export declare const makePetstoreDoc: () => OpenAPIV3.Document;

package/dist/types/generation/model/tags/Tag.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/generation/populateNullableTypes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/generation/refs/assertNoRefs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/generation/refs/extractComponentRefName.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/generation/refs/isRef.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/generation/tsNamespaceName.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/makeError.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/relativePath.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/writeIfChangedAsync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/loading/UniversalFileLoader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/openapi/OpenAPISchemaValidationError.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/api-code-generator",
-  "version": "0.0.0-development-860f5d6-20261009",
+  "version": "0.0.0-development-fd38fc6-20261012",
   "type": "module",
   "repository": "https://github.com/mittwald/api-client-js.git",
   "license": "MIT",
@@ -24,7 +24,8 @@
     "lint": "run eslint .",
     "test": "",
     "test:compile": "run tsc --noEmit",
-    "test:unit": "node --experimental-vm-modules $(yarn bin jest)"
+    "test:unit": "node --experimental-vm-modules $(yarn bin jest)",
+    "test:unit:coverage": "run test:unit --coverage"
   },
   "dependencies": {
     "@oclif/core": "^3.27.0",
@@ -84,5 +85,5 @@
       "@oclif/plugin-plugins"
     ]
   },
-  "gitHead": "f97d7936d6b673d95cc2574c929c71a29b7db732"
+  "gitHead": "b4a8cf280ff804dee2c67e6c5919020cd0067c59"
 }