ts-openapi-codegen 2.0.0 → 2.1.0-beta.2

package/dist/core/plugins/loadGeneratorPlugins.d.ts

@@ -0,0 +1,6 @@
+import { OpenApiGeneratorPlugin } from './GeneratorPlugin.model';
+/**
+ * Loads user plugins and appends built-in plugins as fallback handlers.
+ */
+export declare function loadGeneratorPlugins(pluginPaths: string[]): Promise<OpenApiGeneratorPlugin[]>;
+//# sourceMappingURL=loadGeneratorPlugins.d.ts.map

package/dist/core/plugins/loadGeneratorPlugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadGeneratorPlugins.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/loadGeneratorPlugins.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAiDjE;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAcnG"}

package/dist/core/plugins/loadGeneratorPlugins.js

@@ -0,0 +1,94 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGeneratorPlugins = loadGeneratorPlugins;
+const pathHelpers_1 = require("../../common/utils/pathHelpers");
+const getBuiltinPlugins_1 = require("./getBuiltinPlugins");
+const node_url_1 = require("node:url");
+/**
+ * Type guard for runtime plugin objects.
+ */
+function isOpenApiGeneratorPlugin(value) {
+    return !!value && typeof value === 'object' && typeof value.name === 'string';
+}
+/**
+ * Resolves plugin export from a required module.
+ */
+function getPluginFromModule(moduleExports) {
+    const exported = moduleExports;
+    return exported?.default ?? exported?.plugin ?? moduleExports;
+}
+/**
+ * Checks whether loader can fallback from require() to dynamic import().
+ */
+function canFallbackToDynamicImport(error) {
+    const errorCode = typeof error === 'object' && error && 'code' in error ? String(error.code) : '';
+    const errorMessage = error instanceof Error ? error.message : '';
+    return (errorCode === 'ERR_REQUIRE_ESM' ||
+        errorCode === 'ERR_UNKNOWN_FILE_EXTENSION' ||
+        errorMessage.includes('Cannot use import statement outside a module') ||
+        errorMessage.includes('Unexpected token export'));
+}
+/**
+ * Loads a plugin module from a file path using require() with import() fallback.
+ */
+async function loadPluginModule(pluginPath) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require(pluginPath);
+    }
+    catch (error) {
+        if (!canFallbackToDynamicImport(error)) {
+            throw error;
+        }
+        return Promise.resolve(`${(0, node_url_1.pathToFileURL)(pluginPath).href}`).then(s => __importStar(require(s)));
+    }
+}
+/**
+ * Loads user plugins and appends built-in plugins as fallback handlers.
+ */
+async function loadGeneratorPlugins(pluginPaths) {
+    const loadedPlugins = [];
+    for (const pluginPath of pluginPaths) {
+        const resolvedPath = (0, pathHelpers_1.resolveHelper)(process.cwd(), pluginPath);
+        const moduleExports = await loadPluginModule(resolvedPath);
+        const plugin = getPluginFromModule(moduleExports);
+        if (!isOpenApiGeneratorPlugin(plugin)) {
+            throw new Error(`Invalid plugin at "${pluginPath}": expected export with shape { name: string }`);
+        }
+        loadedPlugins.push(plugin);
+    }
+    return [...loadedPlugins, ...(0, getBuiltinPlugins_1.getBuiltinPlugins)()];
+}

package/dist/core/semanticDiff/__tests__/analyzeOpenApiDiff.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analyzeOpenApiDiff.test.d.ts.map

package/dist/core/semanticDiff/__tests__/analyzeOpenApiDiff.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeOpenApiDiff.test.d.ts","sourceRoot":"","sources":["../../../../src/core/semanticDiff/__tests__/analyzeOpenApiDiff.test.ts"],"names":[],"mappings":""}

package/dist/core/semanticDiff/__tests__/analyzeOpenApiDiff.test.js

@@ -0,0 +1,537 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_test_1 = require("node:test");
+const analyzeOpenApiDiff_1 = require("../analyzeOpenApiDiff");
+(0, node_test_1.describe)('@unit: analyzeOpenApiDiff', () => {
+    (0, node_test_1.test)('detects breaking model and operation removals', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/pets': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {
+                    Pet: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                        },
+                        required: ['id'],
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {},
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.strictEqual(report.schemaVersion, '1.1.0');
+        node_assert_1.default.ok(report.summary.breaking >= 2);
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.removed'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'operation.removed'));
+    });
+    (0, node_test_1.test)('detects property required/type changes and enum changes', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            age: { type: 'number' },
+                            role: { enum: ['user', 'admin'] },
+                        },
+                        required: ['age'],
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            age: { type: 'integer' },
+                            role: { enum: ['admin'] },
+                        },
+                        required: [],
+                    },
+                },
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.property.type.changed' && change.severity === 'breaking'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.property.required.changed' && change.severity === 'non-breaking'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.property.type.changed' && change.path.includes('/role')));
+    });
+    (0, node_test_1.test)('detects non-breaking additions', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/ping': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {
+                    Ping: {
+                        type: 'object',
+                        properties: {
+                            value: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/ping': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                            '201': { description: 'created' },
+                        },
+                    },
+                },
+                '/pong': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {
+                    Ping: {
+                        type: 'object',
+                        properties: {
+                            value: { type: 'string' },
+                            meta: { type: 'string' },
+                        },
+                    },
+                    Pong: {
+                        type: 'object',
+                        properties: {
+                            value: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.ok(report.summary.nonBreaking >= 3);
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.added'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'operation.added'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'operation.response.success.added'));
+    });
+    (0, node_test_1.test)('classifies widening and narrowing transitions for enum/number and union', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    Account: {
+                        type: 'object',
+                        properties: {
+                            tier: { enum: ['basic', 'pro'] },
+                            score: { type: 'integer' },
+                            state: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+                        },
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    Account: {
+                        type: 'object',
+                        properties: {
+                            tier: { enum: ['basic', 'pro', 'enterprise'] },
+                            score: { type: 'number' },
+                            state: { oneOf: [{ type: 'string' }] },
+                        },
+                    },
+                },
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/tier') &&
+            change.severity === 'non-breaking'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/score') &&
+            change.severity === 'non-breaking'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/state') &&
+            change.severity === 'breaking'));
+    });
+    (0, node_test_1.test)('treats different refs and narrowing formats as breaking, widening formats as non-breaking', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            profile: { $ref: '#/components/schemas/ProfileV1' },
+                            count: { type: 'integer', format: 'int32' },
+                            ratio: { type: 'number', format: 'float' },
+                        },
+                    },
+                    ProfileV1: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                        },
+                    },
+                    ProfileV2: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            profile: { $ref: '#/components/schemas/ProfileV2' },
+                            count: { type: 'integer', format: 'int64' },
+                            ratio: { type: 'number', format: 'double' },
+                        },
+                    },
+                    ProfileV1: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                        },
+                    },
+                    ProfileV2: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        };
+        const wideningReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.ok(wideningReport.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/profile') &&
+            change.severity === 'breaking'));
+        node_assert_1.default.ok(wideningReport.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/count') &&
+            change.severity === 'non-breaking'));
+        node_assert_1.default.ok(wideningReport.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/ratio') &&
+            change.severity === 'non-breaking'));
+        const narrowingReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            count: { type: 'integer', format: 'int64' },
+                        },
+                    },
+                },
+            },
+        }, {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            count: { type: 'integer', format: 'int32' },
+                        },
+                    },
+                },
+            },
+        });
+        node_assert_1.default.ok(narrowingReport.changes.some(change => change.type === 'model.property.type.changed' &&
+            change.path.includes('/count') &&
+            change.severity === 'breaking'));
+    });
+    (0, node_test_1.test)('detects success response payload schema changes', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/users/{id}': {
+                    get: {
+                        responses: {
+                            '200': {
+                                description: 'ok',
+                                content: {
+                                    'application/json': {
+                                        schema: { type: 'integer' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {},
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/users/{id}': {
+                    get: {
+                        responses: {
+                            '200': {
+                                description: 'ok',
+                                content: {
+                                    'application/json': {
+                                        schema: { type: 'number' },
+                                    },
+                                },
+                            },
+                            '201': {
+                                description: 'created',
+                                content: {
+                                    'application/json': {
+                                        schema: { type: 'string' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {},
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'operation.response.success.type.changed' && change.severity === 'non-breaking'));
+        node_assert_1.default.ok(report.changes.some(change => change.type === 'operation.response.success.added'));
+    });
+    (0, node_test_1.test)('returns stable and deduplicated changes ordering', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/z': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: {
+                schemas: {
+                    Zeta: {
+                        type: 'object',
+                        properties: {
+                            value: { type: 'string' },
+                        },
+                    },
+                    Alpha: {
+                        type: 'object',
+                        properties: {
+                            value: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {},
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        const keys = report.changes.map(change => `${change.path}|${change.type}|${change.severity}|${change.message}`);
+        const sortedKeys = [...keys].sort((left, right) => left.localeCompare(right));
+        const uniqueSize = new Set(keys).size;
+        node_assert_1.default.deepStrictEqual(keys, sortedKeys);
+        node_assert_1.default.equal(keys.length, uniqueSize);
+    });
+    (0, node_test_1.test)('builds semver recommendation matrix (major/minor/patch)', () => {
+        const majorReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        }, {
+            openapi: '3.0.0',
+            paths: {},
+            components: { schemas: {} },
+        });
+        node_assert_1.default.strictEqual(majorReport.recommendation.semver, 'major');
+        node_assert_1.default.ok(majorReport.recommendation.reasons.includes('HAS_BREAKING_CHANGES'));
+        const minorReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
+            openapi: '3.0.0',
+            paths: {},
+            components: { schemas: {} },
+        }, {
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        });
+        node_assert_1.default.strictEqual(minorReport.recommendation.semver, 'minor');
+        node_assert_1.default.ok(minorReport.recommendation.reasons.includes('HAS_BACKWARD_COMPATIBLE_CHANGES'));
+        const patchReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        }, {
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        });
+        node_assert_1.default.strictEqual(patchReport.recommendation.semver, 'patch');
+        node_assert_1.default.ok(patchReport.recommendation.reasons.includes('NO_API_SURFACE_CHANGES'));
+    });
+    (0, node_test_1.test)('builds governance violations and supports allowBreaking override', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        operationId: 'getUsers',
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        responses: {
+                            default: { description: 'fallback' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        };
+        const strictGovernanceReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        node_assert_1.default.ok(strictGovernanceReport.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
+        node_assert_1.default.ok(strictGovernanceReport.governance.violations.some(violation => violation.ruleId === 'REQUIRE_OPERATION_ID'));
+        node_assert_1.default.ok(strictGovernanceReport.governance.violations.some(violation => violation.ruleId === 'NO_DEFAULT_WITHOUT_2XX'));
+        node_assert_1.default.ok(strictGovernanceReport.governance.summary.errors > 0);
+        const allowedBreakingReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec, { allowBreaking: true });
+        node_assert_1.default.ok(!allowedBreakingReport.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
+    });
+    (0, node_test_1.test)('applies governance config overrides in semantic diff report', () => {
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        operationId: 'getUsers',
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        }, {
+            openapi: '3.0.0',
+            paths: {
+                '/users': {
+                    get: {
+                        responses: {
+                            default: { description: 'fallback' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        }, {
+            governanceConfig: {
+                rules: {
+                    REQUIRE_OPERATION_ID: {
+                        enabled: false,
+                    },
+                    NO_DEFAULT_WITHOUT_2XX: {
+                        severity: 'error',
+                    },
+                },
+            },
+        });
+        node_assert_1.default.ok(!report.governance.violations.some(violation => violation.ruleId === 'REQUIRE_OPERATION_ID'));
+        node_assert_1.default.ok(report.governance.violations.some(violation => violation.ruleId === 'NO_DEFAULT_WITHOUT_2XX' && violation.severity === 'error'));
+    });
+});

package/dist/core/semanticDiff/__tests__/semanticDiffReportSchema.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=semanticDiffReportSchema.test.d.ts.map

package/dist/core/semanticDiff/__tests__/semanticDiffReportSchema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticDiffReportSchema.test.d.ts","sourceRoot":"","sources":["../../../../src/core/semanticDiff/__tests__/semanticDiffReportSchema.test.ts"],"names":[],"mappings":""}