@mittwald/api-code-generator 0.0.0-development-fd38fc6-20261012 → 0.0.0-development-34bc8ae-20261013

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/model/CodeGenerationModel.test.js

@@ -65,6 +65,95 @@ 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. */

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/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/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/openapi/OpenApiSpec.test.js

@@ -49,6 +49,88 @@ 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();

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/api-code-generator",
-  "version": "0.0.0-development-fd38fc6-20261012",
+  "version": "0.0.0-development-34bc8ae-20261013",
   "type": "module",
   "repository": "https://github.com/mittwald/api-client-js.git",
   "license": "MIT",
@@ -58,15 +58,15 @@
     "zod-validation-error": "^3.5.3"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.14",
     "@types/swagger2openapi": "^7.0.4",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.1",
-    "eslint-config-prettier": "^9.1.2",
-    "eslint-plugin-json": "^3.1.0",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint": "^10.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-json": "^5.0.0",
+    "eslint-plugin-prettier": "^5.5.6",
+    "globals": "^17.11.0",
     "jest": "^29.7.0",
     "prettier": "^3.6.2",
     "prettier-plugin-jsdoc": "^1.3.3",
@@ -74,7 +74,8 @@
     "prettier-plugin-sort-json": "^3.1.0",
     "rimraf": "^5.0.10",
     "ts-jest": "^29.2.5",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.68.0"
   },
   "oclif": {
     "bin": "acg",
@@ -85,5 +86,5 @@
       "@oclif/plugin-plugins"
     ]
   },
-  "gitHead": "b4a8cf280ff804dee2c67e6c5919020cd0067c59"
+  "gitHead": "b4795a8b89bf28874a654c71cbb70d9f61f81516"
 }