@mittwald/api-code-generator 0.0.0-development-860f5d6-20261009 → 0.0.0-development-172be3a-20261013

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/componentRefsToCustomTypes.js

@@ -8,6 +8,19 @@ const getComponentRef = (something) => {
         return something.$ref;
     }
 };
+/**
+ * A `deprecated` annotation next to a `$ref` is put there by our own code
+ * model, not by the input document: the OpenAPI 3.0 meta schema rejects any
+ * sibling of a `$ref`, so a document that carries one never reaches this point.
+ * `RequestParameters` and `Parameters` copy the flag from a Parameter Object
+ * onto the referencing schema, because only the schema is handed to the
+ * TypeScript compiler. It describes the referencing property rather than the
+ * referenced component, so it has to survive the conversion into a custom
+ * `tsType` reference.
+ */
+const getRefSiblingAnnotations = (something) => something["deprecated"] === undefined
+    ? {}
+    : { deprecated: something["deprecated"] };
 export const componentRefsToCustomTypes = (rootNamespace, something, clone = true, resolveTSName = refNameToTSName) => {
     if (clone) {
         something = cloneDeep(something);
@@ -22,6 +35,7 @@ export const componentRefsToCustomTypes = (rootNamespace, something, clone = tru
     if (componentRef !== undefined) {
         // see https://github.com/bcherny/json-schema-to-typescript#custom-schema-properties
         return {
+            ...getRefSiblingAnnotations(something),
             tsType: resolveTSName(rootNamespace, componentRef),
             type: "object",
         };

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

@@ -38,6 +38,17 @@ test.each([
             },
         },
     ],
+    [
+        {
+            $ref: "#/components/foo/bar",
+            deprecated: true,
+        },
+        {
+            type: "object",
+            tsType: "Test.Components.Foo.Bar",
+            deprecated: true,
+        },
+    ],
 ])("componentRefsToCustomTypes works for test %#", (input, expected) => {
     const result = componentRefsToCustomTypes("test", input);
     expect(result).toMatchObject(expected);

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/UniversalContentLoader.js

@@ -40,12 +40,14 @@ export class UniversalContentLoader {
         try {
             return await UniversalContentLoader.parseJson(content);
         }
-        catch (error) {
+        catch {
             try {
                 return await UniversalContentLoader.parseYaml(content);
             }
             catch (error) {
-                throw new Error("Content is not of supported format JSON/YAML.");
+                throw new Error("Content is not of supported format JSON/YAML.", {
+                    cause: error,
+                });
             }
         }
     }

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,149 @@ test("unknown schema keywords are still rejected", async () => {
         Broken: { type: "string", definitelyNotAKeyword: true },
     }))).rejects.toThrow(/Failed parsing OpenAPISpec/);
 });
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const buildDoc = (overrides = {}) => ({
+    openapi: "3.0.3",
+    info: { title: "Test API", version: "1.0.0" },
+    paths: {},
+    ...overrides,
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const docWithSchema = (schema) => buildDoc({
+    components: {
+        schemas: {
+            Conversation: schema,
+        },
+    },
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const docWithOperation = (operation) => buildDoc({
+    paths: {
+        "/conversations": {
+            get: {
+                operationId: "conversation-list",
+                responses: { "200": { description: "OK" } },
+                ...operation,
+            },
+        },
+    },
+});
+test("a deprecated schema property does not invalidate the spec", async () => {
+    const doc = docWithSchema({
+        type: "object",
+        properties: {
+            lastMessageAt: {
+                type: "string",
+                format: "date-time",
+                deprecated: true,
+            },
+        },
+    });
+    await expect(OpenApiSpec.parse(doc)).resolves.toBeInstanceOf(OpenApiSpec);
+});
+test("a deprecated schema object does not invalidate the spec", async () => {
+    const doc = docWithSchema({
+        type: "object",
+        deprecated: true,
+        properties: { id: { type: "string" } },
+    });
+    await expect(OpenApiSpec.parse(doc)).resolves.toBeInstanceOf(OpenApiSpec);
+});
+test("a deprecated operation does not invalidate the spec", async () => {
+    const doc = docWithOperation({ deprecated: true });
+    await expect(OpenApiSpec.parse(doc)).resolves.toBeInstanceOf(OpenApiSpec);
+});
+test("a deprecated parameter does not invalidate the spec", async () => {
+    const doc = docWithOperation({
+        parameters: [
+            {
+                name: "legacyFilter",
+                in: "query",
+                deprecated: true,
+                schema: { type: "string" },
+            },
+        ],
+    });
+    await expect(OpenApiSpec.parse(doc)).resolves.toBeInstanceOf(OpenApiSpec);
+});
+test("a deprecated response header does not invalidate the spec", async () => {
+    const doc = docWithOperation({
+        responses: {
+            "200": {
+                description: "OK",
+                headers: {
+                    "X-Legacy": { deprecated: true, schema: { type: "string" } },
+                },
+            },
+        },
+    });
+    await expect(OpenApiSpec.parse(doc)).resolves.toBeInstanceOf(OpenApiSpec);
+});
+test("unknown keywords are still rejected", async () => {
+    const doc = docWithOperation({ bogusUnknownKey: true });
+    await expect(OpenApiSpec.parse(doc)).rejects.toThrow(/OpenAPI is invalid/);
+});
+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/deprecation.d.ts

@@ -0,0 +1,27 @@
+import { JSONSchema as JSONSchemaObject } from "json-schema-to-typescript";
+/**
+ * Anything that may carry the OpenAPI/JSON Schema `deprecated` annotation:
+ * schema objects, parameter objects, header objects and operation objects.
+ */
+export interface MaybeDeprecated {
+    deprecated?: boolean;
+}
+export declare const isDeprecated: (doc: MaybeDeprecated | undefined) => boolean;
+/**
+ * Copies a `deprecated: true` annotation from an OpenAPI object onto the JSON
+ * schema that is generated for it. Used where the annotation lives on the
+ * OpenAPI object (e.g. a Parameter Object) rather than on its `schema`, because
+ * only the schema is handed to the TypeScript compiler.
+ */
+export declare const withDeprecation: <T extends JSONSchemaObject>(schema: T, source: MaybeDeprecated | undefined) => T | (T & {
+    deprecated: true;
+});
+/**
+ * `json-schema-to-typescript` emits an `@deprecated` JSDoc tag for interface
+ * members and for standalone interfaces, but drops it for standalone type
+ * aliases: its `generateStandaloneType` calls the comment generator without the
+ * deprecation flag, so `export type Foo = string` ends up with an empty `/**
+ * *\/` block. We add the tag back so every generated declaration carries the
+ * deprecation.
+ */
+export declare const ensureDeprecatedTypeAliasComment: (compiled: string, tsTypeName: string) => string;

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

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

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 {};