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

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

@@ -0,0 +1,40 @@
+export const isDeprecated = (doc) => doc?.deprecated === true;
+/**
+ * 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 const withDeprecation = (schema, source) => isDeprecated(source) && !isDeprecated(schema)
+    ? { ...schema, deprecated: true }
+    : schema;
+const jsDocStart = "/**";
+const jsDocEnd = "*/";
+const deprecatedTag = "@deprecated";
+/**
+ * `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 const ensureDeprecatedTypeAliasComment = (compiled, tsTypeName) => {
+    const declaration = `export type ${tsTypeName} `;
+    const declarationIndex = compiled.indexOf(declaration);
+    if (declarationIndex < 0) {
+        return compiled;
+    }
+    const before = compiled.slice(0, declarationIndex);
+    const trimmedBefore = before.trimEnd();
+    if (!trimmedBefore.endsWith(jsDocEnd)) {
+        return `${before}/**\n * ${deprecatedTag}\n */\n${compiled.slice(declarationIndex)}`;
+    }
+    const commentStart = trimmedBefore.lastIndexOf(jsDocStart);
+    if (commentStart < 0 ||
+        trimmedBefore.slice(commentStart).includes(deprecatedTag)) {
+        return compiled;
+    }
+    const insertAt = commentStart + jsDocStart.length;
+    return `${compiled.slice(0, insertAt)}\n * ${deprecatedTag}${compiled.slice(insertAt)}`;
+};

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

@@ -0,0 +1,43 @@
+import { ensureDeprecatedTypeAliasComment, isDeprecated, withDeprecation, } from "./deprecation.js";
+test("isDeprecated only reports an explicit true", () => {
+    expect(isDeprecated({ deprecated: true })).toBe(true);
+    expect(isDeprecated({ deprecated: false })).toBe(false);
+    expect(isDeprecated({})).toBe(false);
+    expect(isDeprecated(undefined)).toBe(false);
+});
+test("withDeprecation copies the annotation onto the schema", () => {
+    const schema = { type: "string" };
+    expect(withDeprecation(schema, { deprecated: true })).toEqual({
+        type: "string",
+        deprecated: true,
+    });
+});
+test("withDeprecation leaves the schema untouched when not deprecated", () => {
+    const schema = { type: "string" };
+    expect(withDeprecation(schema, { deprecated: false })).toBe(schema);
+    expect(withDeprecation(schema, undefined)).toBe(schema);
+});
+test("withDeprecation keeps an annotation that is already on the schema", () => {
+    const schema = { type: "string", deprecated: true };
+    expect(withDeprecation(schema, { deprecated: true })).toBe(schema);
+});
+test("ensureDeprecatedTypeAliasComment adds the tag to an empty comment block", () => {
+    const compiled = "/**\n */\nexport type LegacySort = string;\n";
+    expect(ensureDeprecatedTypeAliasComment(compiled, "LegacySort")).toBe("/**\n * @deprecated\n */\nexport type LegacySort = string;\n");
+});
+test("ensureDeprecatedTypeAliasComment keeps an existing description", () => {
+    const compiled = "/**\n * Old thing\n */\nexport type LegacySort = string;\n";
+    expect(ensureDeprecatedTypeAliasComment(compiled, "LegacySort")).toBe("/**\n * @deprecated\n * Old thing\n */\nexport type LegacySort = string;\n");
+});
+test("ensureDeprecatedTypeAliasComment adds a comment block when there is none", () => {
+    const compiled = "export type LegacySort = string;\n";
+    expect(ensureDeprecatedTypeAliasComment(compiled, "LegacySort")).toBe("/**\n * @deprecated\n */\nexport type LegacySort = string;\n");
+});
+test("ensureDeprecatedTypeAliasComment is idempotent", () => {
+    const compiled = "/**\n * @deprecated\n */\nexport type LegacySort = string;\n";
+    expect(ensureDeprecatedTypeAliasComment(compiled, "LegacySort")).toBe(compiled);
+});
+test("ensureDeprecatedTypeAliasComment ignores output without a matching alias", () => {
+    const compiled = "export interface LegacySort {\n  a?: string;\n}\n";
+    expect(ensureDeprecatedTypeAliasComment(compiled, "LegacySort")).toBe(compiled);
+});

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,246 @@ test("const keywords survive from the spec into the generated types", async () =
         | Api.Components.Schemas.DoneEvent;
     `));
 });
+const doc = {
+    openapi: "3.0.3",
+    info: { title: "Test API", version: "1.0.0" },
+    paths: {
+        "/conversations": {
+            get: {
+                operationId: "conversation-list",
+                tags: ["conversation"],
+                parameters: [
+                    {
+                        name: "legacyFilter",
+                        in: "query",
+                        deprecated: true,
+                        schema: { type: "string" },
+                    },
+                    { $ref: "#/components/parameters/LegacySort" },
+                ],
+                responses: {
+                    "200": {
+                        description: "OK",
+                        content: {
+                            "application/json": {
+                                schema: { $ref: "#/components/schemas/Conversation" },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    components: {
+        parameters: {
+            LegacySort: {
+                name: "legacySort",
+                in: "query",
+                deprecated: true,
+                schema: { type: "string" },
+            },
+        },
+        schemas: {
+            Conversation: {
+                type: "object",
+                properties: {
+                    lastMessageAt: {
+                        type: "string",
+                        format: "date-time",
+                        deprecated: true,
+                    },
+                },
+            },
+            LegacyState: {
+                type: "string",
+                enum: ["enabled", "disabled"],
+                deprecated: true,
+            },
+        },
+    },
+};
+const compileTypes = () => CodeGenerationModel.fromDoc("Api", doc).compileTypes({
+    rootNamespace: "Api",
+});
+/** Matches an `@deprecated` JSDoc tag directly in front of `declaration`. */
+const deprecatedBefore = (declaration) => new RegExp(`@deprecated[^;{}]*?\\*/\\s*${declaration.replace(/[$?]/g, "\\$&")}`);
+test("a deprecated schema property is emitted with an @deprecated tag", async () => {
+    const types = await compileTypes();
+    expect(types).toMatch(deprecatedBefore("lastMessageAt?"));
+});
+test("a deprecated standalone type gets an @deprecated tag", async () => {
+    const types = await compileTypes();
+    expect(types).toMatch(deprecatedBefore("export type LegacyState"));
+});
+test("a deprecated request parameter is emitted with an @deprecated tag", async () => {
+    const types = await compileTypes();
+    expect(types).toMatch(deprecatedBefore("legacyFilter?"));
+});
+test("a deprecated referenced request parameter is emitted with an @deprecated tag", async () => {
+    const types = await compileTypes();
+    expect(types).toMatch(deprecatedBefore("legacySort?"));
+});
+/**
+ * Component parameters are request-only, so they are compiled through
+ * `compileAsRequestInput` rather than `compile`. Both paths have to apply the
+ * type alias workaround, otherwise the standalone alias ends up with an empty
+ * JSDoc block.
+ */
+test("a deprecated component parameter alias gets an @deprecated tag", async () => {
+    const types = await compileTypes();
+    expect(types).toMatch(deprecatedBefore("export type LegacySort"));
+});
+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/components/Parameters.js

@@ -2,6 +2,7 @@ import { JSONSchema } from "../global/JSONSchema.js";
 import { Name } from "../global/Name.js";
 import { asyncStringJoin } from "../../asyncStringJoin.js";
 import { assertNoRefs } from "../../refs/assertNoRefs.js";
+import { withDeprecation } from "../../deprecation.js";
 export class Parameters {
     static ns = "Parameters";
     components;
@@ -15,7 +16,12 @@ export class Parameters {
     async compileTypes(opts) {
         const schemas = Object.entries(this.parameters).map(([name, param]) => {
             assertNoRefs(param);
-            return new JSONSchema(new Name(name, this.name), param.schema);
+            return new JSONSchema(new Name(name, this.name), 
+            // `deprecated` lives on the Parameter Object, not on its schema, so it
+            // has to be carried over explicitly to end up in the generated JSDoc.
+            param.schema === undefined
+                ? undefined
+                : withDeprecation(param.schema, param));
         });
         const t = {
             ns: Parameters.ns,

package/dist/esm/generation/model/global/JSONSchema.js

@@ -2,6 +2,7 @@ import { compileJsonSchema } from "../../compileJsonSchema.js";
 import { Name } from "./Name.js";
 import cloneDeep from "clone-deep";
 import { componentRefsToCustomTypes } from "../../refs/componentRefsToCustomTypes.js";
+import { ensureDeprecatedTypeAliasComment, isDeprecated, } from "../../deprecation.js";
 import { widenDateTimeInputs } from "../../dateTime/dateTimeInput.js";
 import { dateTimeInputRefTSNameResolver } from "../../dateTime/dateTimeInputRefs.js";
 export class JSONSchema {
@@ -13,7 +14,10 @@ export class JSONSchema {
     }
     async compile(opts) {
         const withCustomRefTypes = componentRefsToCustomTypes(opts.rootNamespace, this.schemaObject);
-        return compileJsonSchema(withCustomRefTypes, this.name.tsType);
+        const compiled = await compileJsonSchema(withCustomRefTypes, this.name.tsType);
+        return isDeprecated(this.schemaObject)
+            ? ensureDeprecatedTypeAliasComment(compiled, this.name.tsType)
+            : compiled;
     }
     /**
      * Compiles the schema for usage in _request_ position.
@@ -29,7 +33,10 @@ export class JSONSchema {
     async compileAsRequestInput(opts, dateTimeInputSchemaNames) {
         const widened = widenDateTimeInputs(this.schemaObject);
         const withCustomRefTypes = componentRefsToCustomTypes(opts.rootNamespace, widened, false, dateTimeInputRefTSNameResolver(dateTimeInputSchemaNames));
-        return compileJsonSchema(withCustomRefTypes, this.name.tsType);
+        const compiled = await compileJsonSchema(withCustomRefTypes, this.name.tsType);
+        return isDeprecated(this.schemaObject)
+            ? ensureDeprecatedTypeAliasComment(compiled, this.name.tsType)
+            : compiled;
     }
     clone() {
         return new JSONSchema(new Name(this.name.raw), cloneDeep(this.schemaObject));

package/dist/esm/generation/model/paths/operation/RequestParameters.js

@@ -1,6 +1,7 @@
 import { JSONSchema } from "../../global/JSONSchema.js";
 import { Name } from "../../global/Name.js";
 import { isRef } from "../../../refs/isRef.js";
+import { withDeprecation } from "../../../deprecation.js";
 import invariant from "invariant";
 export class RequestParameters {
     static ns = "Parameters";
@@ -26,7 +27,9 @@ export class RequestParameters {
                     ? parameter
                     : parameter.schema;
                 invariant(!!jsonSchemaObject, `Could not find schema for request parameter ${name.raw}`);
-                properties[resolvedParameter.name] = jsonSchemaObject;
+                // `deprecated` lives on the Parameter Object, not on its schema, so it
+                // has to be carried over explicitly to end up in the generated JSDoc.
+                properties[resolvedParameter.name] = withDeprecation(jsonSchemaObject, resolvedParameter);
                 if (resolvedParameter.required) {
                     required.push(resolvedParameter.name);
                 }

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();
+});