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

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,EAA2B,sBAAsB,EAAE,gBAAgB,EAAE,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,GAAG,sBAAsB,GAAG,iCAAiC,GAAG,gCAAgC,GAAG,wBAAwB,CAAC;AAEjK,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;AAuxBF;;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,9 +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":"AAKA,MAAM,MAAM,wCAAwC,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AA4GF;;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"}

package/dist/core/semanticDiff/semanticDiffReportSchema.js

@@ -1,115 +1,205 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticDiffReportJsonSchema = void 0;
 exports.validateSemanticDiffReportSchema = validateSemanticDiffReportSchema;
 const json_schema_1 = require("json-schema");
-const analyzeOpenApiDiff_1 = require("./analyzeOpenApiDiff");
-const semanticDiffReportJsonSchema = {
+const DiffReport_model_1 = require("../types/DiffReport.model");
+/** JSON Schema контракт унифицированного diff-отчёта. */
+exports.semanticDiffReportJsonSchema = {
     type: 'object',
     additionalProperties: false,
     properties: {
         schemaVersion: {
             type: 'string',
-            enum: [analyzeOpenApiDiff_1.SEMANTIC_DIFF_REPORT_SCHEMA_VERSION],
+            enum: [DiffReport_model_1.UNIFIED_DIFF_REPORT_SCHEMA_VERSION],
             required: true,
         },
-        summary: {
+        timestamp: {
+            type: 'string',
+            minLength: 1,
+            required: true,
+        },
+        metadata: {
             type: 'object',
             additionalProperties: false,
             required: true,
             properties: {
-                breaking: { type: 'integer', minimum: 0, required: true },
-                nonBreaking: { type: 'integer', minimum: 0, required: true },
-                informational: { type: 'integer', minimum: 0, required: true },
+                base: { type: 'string', minLength: 1, required: true },
+                target: { type: 'string', minLength: 1, required: true },
+                baseHash: { type: 'string', minLength: 1, required: true },
+                targetHash: { type: 'string', minLength: 1, required: true },
             },
         },
-        recommendation: {
+        semantic: {
             type: 'object',
             additionalProperties: false,
             required: true,
             properties: {
-                semver: {
-                    type: 'string',
-                    enum: ['major', 'minor', 'patch'],
+                summary: {
+                    type: 'object',
+                    additionalProperties: false,
                     required: true,
+                    properties: {
+                        breaking: { type: 'integer', minimum: 0, required: true },
+                        nonBreaking: { type: 'integer', minimum: 0, required: true },
+                        informational: { type: 'integer', minimum: 0, required: true },
+                    },
                 },
-                confidence: {
-                    type: 'string',
-                    enum: ['high', 'medium', 'low'],
+                recommendation: {
+                    type: 'object',
+                    additionalProperties: false,
                     required: true,
+                    properties: {
+                        semver: {
+                            type: 'string',
+                            enum: ['major', 'minor', 'patch'],
+                            required: true,
+                        },
+                        confidence: {
+                            type: 'string',
+                            enum: ['high', 'medium', 'low'],
+                            required: true,
+                        },
+                        reason: {
+                            type: 'string',
+                            minLength: 1,
+                            required: true,
+                        },
+                        reasons: {
+                            type: 'array',
+                            minItems: 1,
+                            required: true,
+                            items: {
+                                type: 'string',
+                                enum: ['HAS_BREAKING_CHANGES', 'HAS_BACKWARD_COMPATIBLE_CHANGES', 'HAS_INFORMATIONAL_ONLY_CHANGES', 'NO_API_SURFACE_CHANGES'],
+                            },
+                        },
+                    },
                 },
-                reason: {
-                    type: 'string',
-                    minLength: 1,
+                governance: {
+                    type: 'object',
+                    additionalProperties: false,
                     required: true,
+                    properties: {
+                        summary: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: true,
+                            properties: {
+                                errors: { type: 'integer', minimum: 0, required: true },
+                                warnings: { type: 'integer', minimum: 0, required: true },
+                                info: { type: 'integer', minimum: 0, required: true },
+                            },
+                        },
+                        violations: {
+                            type: 'array',
+                            required: true,
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    ruleId: { type: 'string', minLength: 1, required: true },
+                                    severity: {
+                                        type: 'string',
+                                        enum: ['error', 'warning', 'info'],
+                                        required: true,
+                                    },
+                                    message: { type: 'string', minLength: 1, required: true },
+                                    path: { type: 'string', minLength: 1, required: true },
+                                },
+                            },
+                        },
+                    },
                 },
-                reasons: {
+                changes: {
                     type: 'array',
-                    minItems: 1,
                     required: true,
                     items: {
-                        type: 'string',
-                        enum: ['HAS_BREAKING_CHANGES', 'HAS_BACKWARD_COMPATIBLE_CHANGES', 'HAS_INFORMATIONAL_ONLY_CHANGES', 'NO_API_SURFACE_CHANGES'],
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            type: { type: 'string', minLength: 1, required: true },
+                            severity: {
+                                type: 'string',
+                                enum: ['breaking', 'non-breaking', 'informational'],
+                                required: true,
+                            },
+                            message: { type: 'string', minLength: 1, required: true },
+                            path: { type: 'string', minLength: 1, required: true },
+                            from: {},
+                            to: {},
+                            fromRequired: { type: 'boolean' },
+                            toRequired: { type: 'boolean' },
+                            fromNullable: { type: 'boolean' },
+                            toNullable: { type: 'boolean' },
+                        },
                     },
                 },
             },
         },
-        governance: {
+        structural: {
             type: 'object',
             additionalProperties: false,
             required: true,
             properties: {
-                summary: {
+                diff: {
                     type: 'object',
                     additionalProperties: false,
                     required: true,
                     properties: {
-                        errors: { type: 'integer', minimum: 0, required: true },
-                        warnings: { type: 'integer', minimum: 0, required: true },
-                        info: { type: 'integer', minimum: 0, required: true },
+                        breaking: { type: 'array', required: true, items: { type: 'object' } },
+                        warnings: { type: 'array', required: true, items: { type: 'object' } },
+                        info: { type: 'array', required: true, items: { type: 'object' } },
+                        all: { type: 'array', required: true, items: { type: 'object' } },
                     },
                 },
-                violations: {
+                miracles: {
                     type: 'array',
                     required: true,
                     items: {
                         type: 'object',
                         additionalProperties: false,
                         properties: {
-                            ruleId: { type: 'string', minLength: 1, required: true },
-                            severity: {
+                            oldPath: { type: 'string', minLength: 1, required: true },
+                            newPath: { type: 'string', minLength: 1, required: true },
+                            type: {
                                 type: 'string',
-                                enum: ['error', 'warning', 'info'],
+                                enum: ['RENAME', 'TYPE_COERCION'],
                                 required: true,
                             },
-                            message: { type: 'string', minLength: 1, required: true },
-                            path: { type: 'string', minLength: 1, required: true },
+                            confidence: { type: 'number', minimum: 0, maximum: 1, required: true },
+                            status: {
+                                type: 'string',
+                                enum: ['auto-generated', 'confirmed'],
+                                required: true,
+                            },
+                            modelName: { type: 'string' },
+                            oldProperty: { type: 'string' },
+                            newProperty: { type: 'string' },
                         },
                     },
                 },
-            },
-        },
-        changes: {
-            type: 'array',
-            required: true,
-            items: {
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                    type: { type: 'string', minLength: 1, required: true },
-                    severity: {
-                        type: 'string',
-                        enum: ['breaking', 'non-breaking', 'informational'],
-                        required: true,
+                stats: {
+                    type: 'object',
+                    additionalProperties: false,
+                    required: true,
+                    properties: {
+                        totalChanges: { type: 'integer', minimum: 0, required: true },
+                        added: { type: 'integer', minimum: 0, required: true },
+                        removed: { type: 'integer', minimum: 0, required: true },
+                        changed: { type: 'integer', minimum: 0, required: true },
+                        ignored: { type: 'integer', minimum: 0 },
+                        stabilityScore: { type: 'integer', minimum: 0, maximum: 100, required: true },
                     },
-                    message: { type: 'string', minLength: 1, required: true },
-                    path: { type: 'string', minLength: 1, required: true },
                 },
             },
         },
     },
 };
 /**
- * Validates semantic diff report payload by JSON Schema contract.
+ * Валидирует payload diff-отчёта по JSON Schema контракту.
+ * @param report проверяемый отчёт
+ * @returns результат валидации с перечнем ошибок
  */
 function validateSemanticDiffReportSchema(report) {
     if (report === null || typeof report !== 'object') {
@@ -118,7 +208,7 @@ function validateSemanticDiffReportSchema(report) {
             errors: ['root: report must be an object'],
         };
     }
-    const result = (0, json_schema_1.validate)(report, semanticDiffReportJsonSchema);
+    const result = (0, json_schema_1.validate)(report, exports.semanticDiffReportJsonSchema);
     return {
         valid: result.valid,
         errors: result.errors.map(error => `${error.property}: ${error.message}`),