ts-openapi-codegen 2.1.0-beta.7 → 2.1.0-beta.9

package/dist/core/api/v3/parser/getOperationResponses.js

@@ -17,9 +17,7 @@ function getOperationResponses(openApi, responses, parentRef) {
             const response = (responseOrReference.$ref ? this.context.get(responseOrReference.$ref, parentRef) : responseOrReference);
             const responseCode = (0, getOperationResponseCode_1.getOperationResponseCode)(code);
             const normalizedParentRef = (0, path_1.isAbsolute)(parentRef) ? parentRef : (0, pathHelpers_1.resolveHelper)(this.context.root?.dirName || process.cwd(), parentRef);
-            const responseParentRef = responseOrReference.$ref
-                ? (0, parseRef_1.parseRef)((0, normalizeRef_1.normalizeRef)(responseOrReference.$ref, normalizedParentRef)).filePath || normalizedParentRef
-                : parentRef;
+            const responseParentRef = responseOrReference.$ref ? (0, parseRef_1.parseRef)((0, normalizeRef_1.normalizeRef)(responseOrReference.$ref, normalizedParentRef)).filePath || normalizedParentRef : parentRef;
             if (responseCode) {
                 const operationResponse = this.getOperationResponse(openApi, response, responseCode, responseParentRef);
                 operationResponses.push(operationResponse);

package/dist/core/api/v3/parser/getServiceName.d.ts

@@ -1,3 +1,3 @@
-import { OpenApiOperation } from "../types/OpenApiOperation.model";
+import { OpenApiOperation } from '../types/OpenApiOperation.model';
 export declare function getServiceName(op: OpenApiOperation, fileName: string): string;
 //# sourceMappingURL=getServiceName.d.ts.map

package/dist/core/governance/evaluateGovernanceRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluateGovernanceRules.d.ts","sourceRoot":"","sources":["../../../src/core/governance/evaluateGovernanceRules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,KAAK,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GAAG,0BAA0B,GAAG,sBAAsB,GAAG,wBAAwB,CAAC;AAE9G,KAAK,iBAAiB,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,SAAS,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,eAAe,GAAG;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAwFF;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAqEjF"}
+{"version":3,"file":"evaluateGovernanceRules.d.ts","sourceRoot":"","sources":["../../../src/core/governance/evaluateGovernanceRules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,KAAK,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GAAG,0BAA0B,GAAG,sBAAsB,GAAG,wBAAwB,CAAC;AAE9G,KAAK,iBAAiB,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,SAAS,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,eAAe,GAAG;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAiFF;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAqEjF"}

package/dist/core/governance/evaluateGovernanceRules.js

@@ -61,9 +61,7 @@ function getEffectiveRuleConfig(ruleId, governanceConfig) {
 function isViolationAllowed(allowList, operation, violationPath) {
     return allowList.some(item => {
         const operationAllowed = typeof item.operation === 'string' && operation ? item.operation === operation : false;
-        const pathAllowed = typeof item.path === 'string' && item.path.trim().length > 0
-            ? violationPath === item.path || violationPath.startsWith(item.path)
-            : false;
+        const pathAllowed = typeof item.path === 'string' && item.path.trim().length > 0 ? violationPath === item.path || violationPath.startsWith(item.path) : false;
         return operationAllowed || pathAllowed;
     });
 }

package/dist/core/governance/loadGovernanceConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadGovernanceConfig.d.ts","sourceRoot":"","sources":["../../../src/core/governance/loadGovernanceConfig.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAkCnE;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CA6BrH"}
+{"version":3,"file":"loadGovernanceConfig.d.ts","sourceRoot":"","sources":["../../../src/core/governance/loadGovernanceConfig.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAgCnE;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAyBrH"}

package/dist/core/governance/loadGovernanceConfig.js

@@ -27,9 +27,7 @@ function formatGovernanceConfigValidationError(error) {
     if (!error.issues.length) {
         return 'Unknown governance config validation error';
     }
-    return error.issues
-        .map(issue => `${formatGovernanceConfigPath(issue.path)}: ${issue.message}`)
-        .join('\n');
+    return error.issues.map(issue => `${formatGovernanceConfigPath(issue.path)}: ${issue.message}`).join('\n');
 }
 /**
  * Loads governance policy config JSON from file path.
@@ -44,7 +42,7 @@ async function loadGovernanceConfig(governanceConfigPath) {
     if (!exists) {
         throw new Error(`Governance config file does not exist: ${resolvedPath}`);
     }
-    const rawContent = await fileSystemHelpers_1.fileSystemHelpers.readFile(resolvedPath, "utf8");
+    const rawContent = await fileSystemHelpers_1.fileSystemHelpers.readFile(resolvedPath, 'utf8');
     let parsed;
     try {
         parsed = JSON.parse(rawContent);

package/dist/core/plugins/GeneratorPlugin.model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GeneratorPlugin.model.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/GeneratorPlugin.model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;AAC1C,MAAM,MAAM,8BAA8B,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACtC,cAAc,EAAE,eAAe,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,EAAE,yBAAyB,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE;QACL,aAAa,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAED,MAAM,WAAW,2BAA2B;IACxC,cAAc,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IACrD,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACvC,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,8BAA8B;IAC3C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,8BAA8B,CAAC;IAC5C,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,MAAM,GAAG,SAAS,CAAC;IACnF,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,yBAAyB,KAAK,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACvH,iBAAiB,CAAC,EAAE,CAChB,GAAG,EAAE,2BAA2B,KAC/B,kBAAkB,CAAC,gBAAgB,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAC;IACxG,iBAAiB,CAAC,EAAE,CAChB,GAAG,EAAE,8BAA8B,KAClC;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC3I"}
+{"version":3,"file":"GeneratorPlugin.model.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/GeneratorPlugin.model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;AAC1C,MAAM,MAAM,8BAA8B,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACtC,cAAc,EAAE,eAAe,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,EAAE,yBAAyB,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE;QACL,aAAa,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAED,MAAM,WAAW,2BAA2B;IACxC,cAAc,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IACrD,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACvC,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,8BAA8B;IAC3C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,8BAA8B,CAAC;IAC5C,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,MAAM,GAAG,SAAS,CAAC;IACnF,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,yBAAyB,KAAK,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACvH,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,2BAA2B,KAAK,kBAAkB,CAAC,gBAAgB,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7J,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,8BAA8B,KAAK;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACnM"}

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

@@ -1 +1 @@
-{"version":3,"file":"applySemanticDiffPluginHooks.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/applySemanticDiffPluginHooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAE7F,MAAM,MAAM,oBAAoB,GAAG;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC7C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,wBAAsB,4BAA4B,CAC9C,KAAK,EAAE,iCAAiC,GACzC,OAAO,CAAC,kCAAkC,CAAC,CAmK7C"}
+{"version":3,"file":"applySemanticDiffPluginHooks.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/applySemanticDiffPluginHooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAE7F,MAAM,MAAM,oBAAoB,GAAG;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC7C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,iCAAiC,GAAG,OAAO,CAAC,kCAAkC,CAAC,CAmKxI"}

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

@@ -44,6 +44,78 @@ const analyzeOpenApiDiff_1 = require("../analyzeOpenApiDiff");
         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)('includes from/to on property type and enum value changes', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            age: { type: 'number' },
+                            role: { enum: ['user', 'admin'] },
+                        },
+                    },
+                },
+            },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            age: { type: 'integer' },
+                            role: { enum: ['admin'] },
+                        },
+                    },
+                },
+            },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        const typeChange = report.changes.find(change => change.type === 'model.property.type.changed' && change.path.includes('/age'));
+        const roleTypeChange = report.changes.find(change => change.type === 'model.property.type.changed' && change.path.includes('/role'));
+        node_assert_1.default.strictEqual(typeChange?.from, 'number');
+        node_assert_1.default.strictEqual(typeChange?.to, 'integer');
+        node_assert_1.default.strictEqual(roleTypeChange?.from, 'enum(admin|user)');
+        node_assert_1.default.strictEqual(roleTypeChange?.to, 'enum(admin)');
+    });
+    (0, node_test_1.test)('includes operation metadata on operation.removed', () => {
+        const oldSpec = {
+            openapi: '3.0.0',
+            paths: {
+                '/pets': {
+                    get: {
+                        operationId: 'listPets',
+                        summary: 'List pets',
+                        description: 'Returns pets',
+                        tags: ['pets'],
+                        responses: {
+                            '200': { description: 'ok' },
+                        },
+                    },
+                },
+            },
+            components: { schemas: {} },
+        };
+        const newSpec = {
+            openapi: '3.0.0',
+            paths: {},
+            components: { schemas: {} },
+        };
+        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)(oldSpec, newSpec);
+        const removed = report.changes.find(change => change.type === 'operation.removed');
+        node_assert_1.default.ok(removed);
+        node_assert_1.default.deepStrictEqual(removed?.from, {
+            operationId: 'listPets',
+            summary: 'List pets',
+            description: 'Returns pets',
+            tags: ['pets'],
+        });
+    });
     (0, node_test_1.test)('detects property required/type changes and enum changes', () => {
         const oldSpec = {
             openapi: '3.0.0',
@@ -182,15 +254,9 @@ const analyzeOpenApiDiff_1 = require("../analyzeOpenApiDiff");
             },
         };
         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'));
+        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 = {
@@ -250,15 +316,9 @@ const analyzeOpenApiDiff_1 = require("../analyzeOpenApiDiff");
             },
         };
         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'));
+        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: {},
@@ -286,9 +346,7 @@ const analyzeOpenApiDiff_1 = require("../analyzeOpenApiDiff");
                 },
             },
         });
-        node_assert_1.default.ok(narrowingReport.changes.some(change => change.type === 'model.property.type.changed' &&
-            change.path.includes('/count') &&
-            change.severity === 'breaking'));
+        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 = {

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

@@ -5,11 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_assert_1 = __importDefault(require("node:assert"));
 const node_test_1 = require("node:test");
+const DiffReport_model_1 = require("../../types/DiffReport.model");
+const adapters_1 = require("../../utils/adapters");
 const analyzeOpenApiDiff_1 = require("../analyzeOpenApiDiff");
 const semanticDiffReportSchema_1 = require("../semanticDiffReportSchema");
 (0, node_test_1.describe)('@unit: semanticDiffReportSchema', () => {
     (0, node_test_1.test)('validates report produced by analyzeOpenApiDiff', () => {
-        const report = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
+        const semanticReport = (0, analyzeOpenApiDiff_1.analyzeOpenApiDiff)({
             openapi: '3.0.0',
             paths: {
                 '/ping': {
@@ -35,6 +37,23 @@ const semanticDiffReportSchema_1 = require("../semanticDiffReportSchema");
             },
             components: { schemas: {} },
         });
+        const report = {
+            schemaVersion: DiffReport_model_1.UNIFIED_DIFF_REPORT_SCHEMA_VERSION,
+            timestamp: '2026-01-01T00:00:00.000Z',
+            metadata: {
+                base: 'old',
+                target: 'new',
+                baseHash: 'old-hash',
+                targetHash: 'new-hash',
+            },
+            semantic: {
+                changes: semanticReport.changes,
+                governance: semanticReport.governance,
+                recommendation: semanticReport.recommendation,
+                summary: semanticReport.summary,
+            },
+            structural: (0, adapters_1.adaptSemanticToStructural)(semanticReport),
+        };
         const validation = (0, semanticDiffReportSchema_1.validateSemanticDiffReportSchema)(report);
         node_assert_1.default.strictEqual(validation.valid, true, validation.errors.join('\n'));
     });

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

@@ -1,7 +1,15 @@
 import { GovernancePolicyConfig, GovernanceReport } from '../governance/evaluateGovernanceRules';
+import type { UnifiedDiffReport } from '../types/DiffReport.model';
 import { CommonOpenApi } from '../types/shared/CommonOpenApi.model';
+import type { MiracleEntry } from '../types/shared/Miracle.model';
 type ChangeSeverity = 'breaking' | 'non-breaking' | 'informational';
-type SemanticDiffSummary = {
+/**
+ * Сводка семантических изменений по уровню серьёзности.
+ * @property breaking количество breaking-изменений
+ * @property nonBreaking количество обратно совместимых изменений
+ * @property informational количество информационных изменений
+ */
+export type SemanticDiffSummary = {
     breaking: number;
     nonBreaking: number;
     informational: number;
@@ -9,37 +17,81 @@ type SemanticDiffSummary = {
 type SemanticDiffSemverRecommendation = 'major' | 'minor' | 'patch';
 type SemanticDiffConfidence = 'high' | 'medium' | 'low';
 type SemanticDiffRecommendationReason = 'HAS_BREAKING_CHANGES' | 'HAS_BACKWARD_COMPATIBLE_CHANGES' | 'HAS_INFORMATIONAL_ONLY_CHANGES' | 'NO_API_SURFACE_CHANGES';
-type SemanticDiffRecommendation = {
+/**
+ * Рекомендация по semver-версии на основе семантического diff.
+ * @property semver рекомендуемый уровень версии
+ * @property confidence уверенность в рекомендации
+ * @property reason человекочитаемое объяснение
+ * @property reasons машиночитаемые коды причин
+ */
+export type SemanticDiffRecommendation = {
     semver: SemanticDiffSemverRecommendation;
     confidence: SemanticDiffConfidence;
     reason: string;
     reasons: SemanticDiffRecommendationReason[];
 };
-type SemanticDiffChange = {
+/**
+ * Одно семантическое изменение OpenAPI.
+ * @property type тип изменения
+ * @property severity уровень серьёзности
+ * @property message описание изменения
+ * @property path JSON Pointer путь к изменённому элементу
+ * @property [from] значение до изменения
+ * @property [to] значение после изменения
+ * @property [fromRequired] обязательность до изменения
+ * @property [toRequired] обязательность после изменения
+ * @property [fromNullable] nullable до изменения
+ * @property [toNullable] nullable после изменения
+ */
+export type SemanticDiffChange = {
     type: string;
     severity: ChangeSeverity;
     message: string;
     path: string;
+    from?: unknown;
+    to?: unknown;
+    fromRequired?: boolean;
+    toRequired?: boolean;
+    fromNullable?: boolean;
+    toNullable?: boolean;
 };
+/** Версия схемы семантического diff-отчёта. */
 export declare const SEMANTIC_DIFF_REPORT_SCHEMA_VERSION = "1.1.0";
+/**
+ * Семантический diff-отчёт OpenAPI.
+ * @property schemaVersion версия схемы отчёта
+ * @property summary сводка изменений по серьёзности
+ * @property recommendation рекомендация по semver
+ * @property governance результат проверки governance-правил
+ * @property changes список семантических изменений
+ * @property [miracles] кандидаты на переименование и приведение типов
+ */
 export type SemanticDiffReport = {
     schemaVersion: string;
     summary: SemanticDiffSummary;
     recommendation: SemanticDiffRecommendation;
     governance: GovernanceReport;
     changes: SemanticDiffChange[];
+    miracles?: MiracleEntry[];
 };
 type AnalyzeOpenApiDiffOptions = {
     allowBreaking?: boolean;
     governanceConfig?: GovernancePolicyConfig;
 };
 /**
- * Creates semantic diff report between two OpenAPI specs.
+ * Формирует семантический diff-отчёт между двумя OpenAPI-спецификациями.
+ * @param oldSpec базовая спецификация
+ * @param newSpec целевая спецификация
+ * @param [options] опции анализа, включая governance и разрешение breaking-изменений
+ * @returns семантический diff-отчёт
  */
 export declare function analyzeOpenApiDiff(oldSpec: CommonOpenApi, newSpec: CommonOpenApi, options?: AnalyzeOpenApiDiffOptions): SemanticDiffReport;
 /**
- * Writes semantic diff report to JSON file and returns absolute path.
+ * Записывает семантический или унифицированный diff-отчёт в JSON-файл.
+ * @param report отчёт для сохранения
+ * @param reportFilePath путь к файлу отчёта
+ * @returns абсолютный путь к сохранённому файлу
  */
-export declare function writeSemanticDiffReport(report: SemanticDiffReport, reportFilePath: string): Promise<string>;
+export declare function writeSemanticDiffReport(report: SemanticDiffReport | UnifiedDiffReport, reportFilePath: string): Promise<string>;
 export {};
 //# sourceMappingURL=analyzeOpenApiDiff.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"analyzeOpenApiDiff.d.ts","sourceRoot":"","sources":["../../../src/core/semanticDiff/analyzeOpenApiDiff.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAA2B,MAAM,uCAAuC,CAAC;AAC1H,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,KAAK,cAAc,GAAG,UAAU,GAAG,cAAc,GAAG,eAAe,CAAC;AAEpE,KAAK,mBAAmB,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,KAAK,gCAAgC,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AACpE,KAAK,sBAAsB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACxD,KAAK,gCAAgC,GAC/B,sBAAsB,GACtB,iCAAiC,GACjC,gCAAgC,GAChC,wBAAwB,CAAC;AAE/B,KAAK,0BAA0B,GAAG;IAC9B,MAAM,EAAE,gCAAgC,CAAC;IACzC,UAAU,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gCAAgC,EAAE,CAAC;CAC/C,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,mCAAmC,UAAU,CAAC;AAE3D,MAAM,MAAM,kBAAkB,GAAG;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,cAAc,EAAE,0BAA0B,CAAC;IAC3C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,EAAE,kBAAkB,EAAE,CAAC;CACjC,CAAC;AAEF,KAAK,yBAAyB,GAAG;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AA6yBF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,GAAE,yBAA8B,GAAG,kBAAkB,CA2B9I;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAajH"}
+{"version":3,"file":"analyzeOpenApiDiff.d.ts","sourceRoot":"","sources":["../../../src/core/semanticDiff/analyzeOpenApiDiff.ts"],"names":[],"mappings":"AAKA,OAAO,EAA2B,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC1H,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,KAAK,cAAc,GAAG,UAAU,GAAG,cAAc,GAAG,eAAe,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,KAAK,gCAAgC,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AACpE,KAAK,sBAAsB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACxD,KAAK,gCAAgC,GAAG,sBAAsB,GAAG,iCAAiC,GAAG,gCAAgC,GAAG,wBAAwB,CAAC;AAEjK;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACrC,MAAM,EAAE,gCAAgC,CAAC;IACzC,UAAU,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gCAAgC,EAAE,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAIF,+CAA+C;AAC/C,eAAO,MAAM,mCAAmC,UAAU,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,cAAc,EAAE,0BAA0B,CAAC;IAC3C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC7B,CAAC;AAEF,KAAK,yBAAyB,GAAG;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AA0zBF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,GAAE,yBAA8B,GAAG,kBAAkB,CA2B9I;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAarI"}

package/dist/core/semanticDiff/analyzeOpenApiDiff.js

@@ -11,6 +11,7 @@ const fileSystemHelpers_1 = require("../../common/utils/fileSystemHelpers");
 const format_1 = require("../../common/utils/format");
 const pathHelpers_1 = require("../../common/utils/pathHelpers");
 const evaluateGovernanceRules_1 = require("../governance/evaluateGovernanceRules");
+/** Версия схемы семантического diff-отчёта. */
 exports.SEMANTIC_DIFF_REPORT_SCHEMA_VERSION = '1.1.0';
 const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 /**
@@ -373,10 +374,19 @@ function buildCanonicalOperations(spec) {
                     }
                 }
             }
+            const operationId = typeof operation.operationId === 'string' ? operation.operationId : undefined;
+            const summary = typeof operation.summary === 'string' ? operation.summary : undefined;
+            const description = typeof operation.description === 'string' ? operation.description : undefined;
+            const tagsRaw = operation.tags;
+            const tags = Array.isArray(tagsRaw) ? tagsRaw.map(tag => String(tag)) : undefined;
             operations.set(operationKey, {
                 parameters,
                 requestBodyRequired,
                 successResponses,
+                operationId,
+                summary,
+                description,
+                tags,
             });
         }
     }
@@ -385,8 +395,8 @@ function buildCanonicalOperations(spec) {
 /**
  * Pushes change entry to report collection.
  */
-function pushChange(changes, severity, type, path, message) {
-    changes.push({ severity, type, path, message });
+function pushChange(changes, severity, type, path, message, extras) {
+    changes.push({ severity, type, path, message, ...extras });
 }
 /**
  * Normalizes, deduplicates and sorts changes for stable CI output.
@@ -440,13 +450,13 @@ function diffModels(oldModels, newModels, changes) {
         }
         for (const oldPropertyName of oldModel.properties.keys()) {
             if (!newModel.properties.has(oldPropertyName)) {
-                pushChange(changes, 'breaking', 'model.property.removed', `#/components/schemas/${modelName}/properties/${oldPropertyName}`, `Property "${oldPropertyName}" was removed from model "${modelName}".`);
+                pushChange(changes, 'breaking', 'model.property.removed', `#/components/schemas/${modelName}/properties/${oldPropertyName}`, `Property "${oldPropertyName}" was removed from model "${modelName}".`, { from: { type: oldModel.properties.get(oldPropertyName) } });
             }
         }
-        for (const [newPropertyName] of newModel.properties.entries()) {
+        for (const [newPropertyName, newPropertyType] of newModel.properties.entries()) {
             if (!oldModel.properties.has(newPropertyName)) {
                 const isRequired = newModel.required.has(newPropertyName);
-                pushChange(changes, isRequired ? 'breaking' : 'non-breaking', 'model.property.added', `#/components/schemas/${modelName}/properties/${newPropertyName}`, `Property "${newPropertyName}" was added to model "${modelName}".`);
+                pushChange(changes, isRequired ? 'breaking' : 'non-breaking', 'model.property.added', `#/components/schemas/${modelName}/properties/${newPropertyName}`, `Property "${newPropertyName}" was added to model "${modelName}".`, { to: { type: newPropertyType } });
             }
         }
         for (const [propertyName, oldPropertyType] of oldModel.properties.entries()) {
@@ -456,22 +466,26 @@ function diffModels(oldModels, newModels, changes) {
             }
             if (oldPropertyType !== newPropertyType) {
                 const severity = classifyTypeTransition(oldPropertyType, newPropertyType);
-                pushChange(changes, severity, 'model.property.type.changed', `#/components/schemas/${modelName}/properties/${propertyName}`, `Property "${propertyName}" type changed in model "${modelName}" from "${oldPropertyType}" to "${newPropertyType}".`);
+                pushChange(changes, severity, 'model.property.type.changed', `#/components/schemas/${modelName}/properties/${propertyName}`, `Property "${propertyName}" type changed in model "${modelName}" from "${oldPropertyType}" to "${newPropertyType}".`, { from: oldPropertyType, to: newPropertyType });
             }
             const wasRequired = oldModel.required.has(propertyName);
             const isRequired = newModel.required.has(propertyName);
             if (wasRequired !== isRequired) {
-                pushChange(changes, isRequired ? 'breaking' : 'non-breaking', 'model.property.required.changed', `#/components/schemas/${modelName}/required/${propertyName}`, `Property "${propertyName}" required flag changed in model "${modelName}" from "${wasRequired}" to "${isRequired}".`);
+                pushChange(changes, isRequired ? 'breaking' : 'non-breaking', 'model.property.required.changed', `#/components/schemas/${modelName}/required/${propertyName}`, `Property "${propertyName}" required flag changed in model "${modelName}" from "${wasRequired}" to "${isRequired}".`, { fromRequired: wasRequired, toRequired: isRequired });
             }
         }
         for (const oldEnumValue of oldModel.enumValues) {
             if (!newModel.enumValues.has(oldEnumValue)) {
-                pushChange(changes, 'breaking', 'model.enum.value.removed', `#/components/schemas/${modelName}/enum`, `Enum value "${oldEnumValue}" was removed from model "${modelName}".`);
+                pushChange(changes, 'breaking', 'model.enum.value.removed', `#/components/schemas/${modelName}/enum`, `Enum value "${oldEnumValue}" was removed from model "${modelName}".`, {
+                    from: oldEnumValue,
+                });
             }
         }
         for (const newEnumValue of newModel.enumValues) {
             if (!oldModel.enumValues.has(newEnumValue)) {
-                pushChange(changes, 'non-breaking', 'model.enum.value.added', `#/components/schemas/${modelName}/enum`, `Enum value "${newEnumValue}" was added to model "${modelName}".`);
+                pushChange(changes, 'non-breaking', 'model.enum.value.added', `#/components/schemas/${modelName}/enum`, `Enum value "${newEnumValue}" was added to model "${modelName}".`, {
+                    to: newEnumValue,
+                });
             }
         }
     }
@@ -480,9 +494,16 @@ function diffModels(oldModels, newModels, changes) {
  * Diffs canonical operations and appends semantic changes.
  */
 function diffOperations(oldOperations, newOperations, changes) {
-    for (const oldOperationKey of oldOperations.keys()) {
+    for (const [oldOperationKey, oldOperation] of oldOperations.entries()) {
         if (!newOperations.has(oldOperationKey)) {
-            pushChange(changes, 'breaking', 'operation.removed', `#/paths/${oldOperationKey}`, `Operation "${oldOperationKey}" was removed.`);
+            pushChange(changes, 'breaking', 'operation.removed', `#/paths/${oldOperationKey}`, `Operation "${oldOperationKey}" was removed.`, {
+                from: {
+                    operationId: oldOperation.operationId,
+                    summary: oldOperation.summary,
+                    description: oldOperation.description,
+                    tags: oldOperation.tags,
+                },
+            });
         }
     }
     for (const newOperationKey of newOperations.keys()) {
@@ -497,12 +518,12 @@ function diffOperations(oldOperations, newOperations, changes) {
         }
         for (const oldParameterName of oldOperation.parameters.keys()) {
             if (!newOperation.parameters.has(oldParameterName)) {
-                pushChange(changes, 'breaking', 'operation.parameter.removed', `#/paths/${operationKey}/parameters/${oldParameterName}`, `Parameter "${oldParameterName}" was removed from operation "${operationKey}".`);
+                pushChange(changes, 'breaking', 'operation.parameter.removed', `#/paths/${operationKey}/parameters/${oldParameterName}`, `Parameter "${oldParameterName}" was removed from operation "${operationKey}".`, { from: { type: oldOperation.parameters.get(oldParameterName)?.type } });
             }
         }
         for (const [newParameterName, newParameter] of newOperation.parameters.entries()) {
             if (!oldOperation.parameters.has(newParameterName)) {
-                pushChange(changes, newParameter.required ? 'breaking' : 'non-breaking', 'operation.parameter.added', `#/paths/${operationKey}/parameters/${newParameterName}`, `Parameter "${newParameterName}" was added to operation "${operationKey}".`);
+                pushChange(changes, newParameter.required ? 'breaking' : 'non-breaking', 'operation.parameter.added', `#/paths/${operationKey}/parameters/${newParameterName}`, `Parameter "${newParameterName}" was added to operation "${operationKey}".`, { to: { type: newParameter.type, required: newParameter.required } });
             }
         }
         for (const [parameterName, oldParameter] of oldOperation.parameters.entries()) {
@@ -511,15 +532,15 @@ function diffOperations(oldOperations, newOperations, changes) {
                 continue;
             }
             if (oldParameter.required !== newParameter.required) {
-                pushChange(changes, newParameter.required ? 'breaking' : 'non-breaking', 'operation.parameter.required.changed', `#/paths/${operationKey}/parameters/${parameterName}/required`, `Required flag for parameter "${parameterName}" changed in operation "${operationKey}".`);
+                pushChange(changes, newParameter.required ? 'breaking' : 'non-breaking', 'operation.parameter.required.changed', `#/paths/${operationKey}/parameters/${parameterName}/required`, `Required flag for parameter "${parameterName}" changed in operation "${operationKey}".`, { fromRequired: oldParameter.required, toRequired: newParameter.required });
             }
             if (oldParameter.type !== newParameter.type) {
                 const severity = classifyTypeTransition(oldParameter.type, newParameter.type);
-                pushChange(changes, severity, 'operation.parameter.type.changed', `#/paths/${operationKey}/parameters/${parameterName}/schema`, `Type for parameter "${parameterName}" changed in operation "${operationKey}" from "${oldParameter.type}" to "${newParameter.type}".`);
+                pushChange(changes, severity, 'operation.parameter.type.changed', `#/paths/${operationKey}/parameters/${parameterName}/schema`, `Type for parameter "${parameterName}" changed in operation "${operationKey}" from "${oldParameter.type}" to "${newParameter.type}".`, { from: oldParameter.type, to: newParameter.type });
             }
         }
         if (oldOperation.requestBodyRequired !== newOperation.requestBodyRequired) {
-            pushChange(changes, newOperation.requestBodyRequired ? 'breaking' : 'non-breaking', 'operation.requestBody.required.changed', `#/paths/${operationKey}/requestBody/required`, `requestBody.required changed in operation "${operationKey}" from "${oldOperation.requestBodyRequired}" to "${newOperation.requestBodyRequired}".`);
+            pushChange(changes, newOperation.requestBodyRequired ? 'breaking' : 'non-breaking', 'operation.requestBody.required.changed', `#/paths/${operationKey}/requestBody/required`, `requestBody.required changed in operation "${operationKey}" from "${oldOperation.requestBodyRequired}" to "${newOperation.requestBodyRequired}".`, { from: oldOperation.requestBodyRequired, to: newOperation.requestBodyRequired });
         }
         for (const oldResponseCode of oldOperation.successResponses.keys()) {
             if (!newOperation.successResponses.has(oldResponseCode)) {
@@ -537,7 +558,7 @@ function diffOperations(oldOperations, newOperations, changes) {
                 continue;
             }
             const severity = classifyTypeTransition(oldResponseType, newResponseType);
-            pushChange(changes, severity, 'operation.response.success.type.changed', `#/paths/${operationKey}/responses/${responseCode}/content`, `Successful response "${responseCode}" payload type changed in operation "${operationKey}" from "${oldResponseType}" to "${newResponseType}".`);
+            pushChange(changes, severity, 'operation.response.success.type.changed', `#/paths/${operationKey}/responses/${responseCode}/content`, `Successful response "${responseCode}" payload type changed in operation "${operationKey}" from "${oldResponseType}" to "${newResponseType}".`, { from: oldResponseType, to: newResponseType });
         }
     }
 }
@@ -598,7 +619,11 @@ function buildSemverRecommendation(summary) {
     };
 }
 /**
- * Creates semantic diff report between two OpenAPI specs.
+ * Формирует семантический diff-отчёт между двумя OpenAPI-спецификациями.
+ * @param oldSpec базовая спецификация
+ * @param newSpec целевая спецификация
+ * @param [options] опции анализа, включая governance и разрешение breaking-изменений
+ * @returns семантический diff-отчёт
  */
 function analyzeOpenApiDiff(oldSpec, newSpec, options = {}) {
     const oldModels = buildCanonicalModels(oldSpec);
@@ -625,7 +650,10 @@ function analyzeOpenApiDiff(oldSpec, newSpec, options = {}) {
     };
 }
 /**
- * Writes semantic diff report to JSON file and returns absolute path.
+ * Записывает семантический или унифицированный diff-отчёт в JSON-файл.
+ * @param report отчёт для сохранения
+ * @param reportFilePath путь к файлу отчёта
+ * @returns абсолютный путь к сохранённому файлу
  */
 async function writeSemanticDiffReport(report, reportFilePath) {
     const resolvedPath = (0, pathHelpers_1.resolveHelper)(process.cwd(), reportFilePath);

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

@@ -1,11 +1,19 @@
 import { JSONSchema7 } from 'json-schema';
+/**
+ * Результат валидации diff-отчёта по JSON Schema.
+ * @property valid признак успешной валидации
+ * @property errors список ошибок валидации
+ */
 export type SemanticDiffReportSchemaValidationResult = {
     valid: boolean;
     errors: string[];
 };
+/** JSON Schema контракт унифицированного diff-отчёта. */
 export declare const semanticDiffReportJsonSchema: JSONSchema7;
 /**
- * Validates semantic diff report payload by JSON Schema contract.
+ * Валидирует payload diff-отчёта по JSON Schema контракту.
+ * @param report проверяемый отчёт
+ * @returns результат валидации с перечнем ошибок
  */
 export declare function validateSemanticDiffReportSchema(report: unknown): SemanticDiffReportSchemaValidationResult;
 //# sourceMappingURL=semanticDiffReportSchema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"semanticDiffReportSchema.d.ts","sourceRoot":"","sources":["../../../src/core/semanticDiff/semanticDiffReportSchema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C,MAAM,MAAM,wCAAwC,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,WA6G1C,CAAC;AAEF;;GAEG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,OAAO,GAAG,wCAAwC,CAc1G"}
+{"version":3,"file":"semanticDiffReportSchema.d.ts","sourceRoot":"","sources":["../../../src/core/semanticDiff/semanticDiffReportSchema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C;;;;GAIG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,4BAA4B,EAAE,WA8L1C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,OAAO,GAAG,wCAAwC,CAc1G"}