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

package/README.md

@@ -34,6 +34,10 @@
 - Generated services accept a `RequestExecutor` in the constructor (`request` / `requestRaw`, interceptors, `customExecutorPath` / `createExecutorAdapter`)
 - Optional output formatting via `prettierConfigPath` (explicit Prettier config file)
 - Optional batch ESLint `--fix` after generation when both `tsconfigPath` and `eslintConfigPath` are set
+- Supports unified `analyze-diff` report (`schemaVersion: 2.0.0`) with separate `semantic` (CI/governance) and `structural` (generation) sections
+- Restores `generate --useHistory` compatibility with semantic diff reports (ghost operations/properties, coercion, rename miracles)
+- Uses selective OpenAPI `$ref` expansion in analyze-diff for faster and safer comparison
+- Automatic RENAME / TYPE_COERCION miracle detection from semantic property changes
 
 ## Install
 

package/README.rus.md

@@ -34,6 +34,10 @@
 - Сгенерированные сервисы принимают `RequestExecutor` в конструкторе (`request` / `requestRaw`, interceptors, `customExecutorPath` / `createExecutorAdapter`)
 - Опциональное форматирование вывода через `prettierConfigPath` (явный путь к конфигу Prettier)
 - Опциональный пакетный ESLint `--fix` после генерации при указании `tsconfigPath` и `eslintConfigPath`
+- Поддерживает унифицированный отчёт `analyze-diff` (`schemaVersion: 2.0.0`) с отдельными секциями `semantic` (CI/governance) и `structural` (генерация)
+- Восстанавливает совместимость `generate --useHistory` с semantic diff-отчётами (ghost operations/properties, coercion, rename miracles)
+- Использует селективное раскрытие OpenAPI `$ref` в analyze-diff для более быстрого и безопасного сравнения
+- Автоматическое обнаружение RENAME / TYPE_COERCION miracles из semantic-изменений свойств
 
 ## Установка
 

package/dist/cli/analyzeDiff/__tests__/analyzeDiff.cli.test.js

@@ -111,12 +111,13 @@ async function runAnalyzeDiffCli(options) {
         const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
         const schemaValidation = (0, semanticDiffReportSchema_1.validateSemanticDiffReportSchema)(report);
         node_assert_1.default.strictEqual(schemaValidation.valid, true, schemaValidation.errors.join('\n'));
-        node_assert_1.default.strictEqual(report.schemaVersion, '1.1.0');
-        node_assert_1.default.strictEqual(report.summary.breaking, 0);
-        node_assert_1.default.ok(report.summary.nonBreaking > 0);
-        node_assert_1.default.strictEqual(report.recommendation.semver, 'minor');
-        node_assert_1.default.ok(report.recommendation.reasons.includes('HAS_BACKWARD_COMPATIBLE_CHANGES'));
-        node_assert_1.default.strictEqual(report.governance.summary.errors, 0);
+        node_assert_1.default.strictEqual(report.schemaVersion, '2.0.0');
+        node_assert_1.default.strictEqual(report.semantic.summary.breaking, 0);
+        node_assert_1.default.ok(report.semantic.summary.nonBreaking > 0);
+        node_assert_1.default.strictEqual(report.semantic.recommendation.semver, 'minor');
+        node_assert_1.default.ok(report.semantic.recommendation.reasons.includes('HAS_BACKWARD_COMPATIBLE_CHANGES'));
+        node_assert_1.default.strictEqual(report.semantic.governance.summary.errors, 0);
+        node_assert_1.default.strictEqual(report.structural.diff.all.length, report.semantic.changes.length);
         const ciSummary = (0, ciSummary_1.formatCiMarkdownSummary)(report, reportPath);
         node_assert_1.default.ok(ciSummary.includes('### OpenAPI Semantic Diff'));
         node_assert_1.default.ok(ciSummary.includes('HAS_BACKWARD_COMPATIBLE_CHANGES'));
@@ -154,12 +155,12 @@ async function runAnalyzeDiffCli(options) {
         const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
         const schemaValidation = (0, semanticDiffReportSchema_1.validateSemanticDiffReportSchema)(report);
         node_assert_1.default.strictEqual(schemaValidation.valid, true, schemaValidation.errors.join('\n'));
-        node_assert_1.default.strictEqual(report.schemaVersion, '1.1.0');
-        node_assert_1.default.ok(report.summary.breaking > 0);
-        node_assert_1.default.ok(report.changes.some(change => change.severity === 'breaking'));
-        node_assert_1.default.strictEqual(report.recommendation.semver, 'major');
-        node_assert_1.default.ok(report.recommendation.reasons.includes('HAS_BREAKING_CHANGES'));
-        node_assert_1.default.ok(report.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
+        node_assert_1.default.strictEqual(report.schemaVersion, '2.0.0');
+        node_assert_1.default.ok(report.semantic.summary.breaking > 0);
+        node_assert_1.default.ok(report.semantic.changes.some(change => change.severity === 'breaking'));
+        node_assert_1.default.strictEqual(report.semantic.recommendation.semver, 'major');
+        node_assert_1.default.ok(report.semantic.recommendation.reasons.includes('HAS_BREAKING_CHANGES'));
+        node_assert_1.default.ok(report.semantic.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
         const ciSummary = (0, ciSummary_1.formatCiMarkdownSummary)(report, reportPath);
         node_assert_1.default.ok(ciSummary.includes('### OpenAPI Semantic Diff'));
         node_assert_1.default.ok(ciSummary.includes('HAS_BREAKING_CHANGES'));
@@ -199,9 +200,9 @@ async function runAnalyzeDiffCli(options) {
         const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
         const schemaValidation = (0, semanticDiffReportSchema_1.validateSemanticDiffReportSchema)(report);
         node_assert_1.default.strictEqual(schemaValidation.valid, true, schemaValidation.errors.join('\n'));
-        node_assert_1.default.strictEqual(report.schemaVersion, '1.1.0');
-        node_assert_1.default.ok(report.summary.breaking > 0);
-        node_assert_1.default.ok(!report.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
+        node_assert_1.default.strictEqual(report.schemaVersion, '2.0.0');
+        node_assert_1.default.ok(report.semantic.summary.breaking > 0);
+        node_assert_1.default.ok(!report.semantic.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
         node_assert_1.default.ok((0, ciSummary_1.formatCiMarkdownSummary)(report, reportPath).includes('### OpenAPI Semantic Diff'));
     });
     (0, node_test_1.test)('returns exit code 0 for breaking diff in ci mode when governance config disables no-breaking rule', async (t) => {
@@ -247,9 +248,9 @@ async function runAnalyzeDiffCli(options) {
         const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
         const schemaValidation = (0, semanticDiffReportSchema_1.validateSemanticDiffReportSchema)(report);
         node_assert_1.default.strictEqual(schemaValidation.valid, true, schemaValidation.errors.join('\n'));
-        node_assert_1.default.strictEqual(report.schemaVersion, '1.1.0');
-        node_assert_1.default.ok(report.summary.breaking > 0);
-        node_assert_1.default.ok(!report.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
+        node_assert_1.default.strictEqual(report.schemaVersion, '2.0.0');
+        node_assert_1.default.ok(report.semantic.summary.breaking > 0);
+        node_assert_1.default.ok(!report.semantic.governance.violations.some(violation => violation.ruleId === 'NO_BREAKING_WITHOUT_FLAG'));
         node_assert_1.default.ok((0, ciSummary_1.formatCiMarkdownSummary)(report, reportPath).includes('### OpenAPI Semantic Diff'));
     });
     (0, node_test_1.test)('uses --compare-with over --git when both flags are provided', async (t) => {
@@ -293,8 +294,8 @@ async function runAnalyzeDiffCli(options) {
         node_assert_1.default.strictEqual(exitCode, 0);
         node_assert_1.default.strictEqual(result.success, true);
         const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
-        node_assert_1.default.strictEqual(report.summary.breaking, 0);
-        node_assert_1.default.strictEqual(report.recommendation.semver, 'patch');
+        node_assert_1.default.strictEqual(report.semantic.summary.breaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.recommendation.semver, 'patch');
         node_assert_1.default.ok(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.COMPARE_WITH_OVERRIDES_GIT('HEAD~9999').includes('Ignoring git ref'));
     });
     (0, node_test_1.test)('filters semantic changes with analyze.ignore and recalculates summary', async (t) => {
@@ -355,10 +356,10 @@ async function runAnalyzeDiffCli(options) {
         node_assert_1.default.strictEqual(exitCode, 0);
         node_assert_1.default.strictEqual(result.ignored, 1);
         const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
-        node_assert_1.default.strictEqual(report.summary.breaking, 0);
-        node_assert_1.default.strictEqual(report.summary.nonBreaking, 0);
-        node_assert_1.default.strictEqual(report.summary.informational, 0);
-        node_assert_1.default.strictEqual(report.recommendation.semver, 'patch');
+        node_assert_1.default.strictEqual(report.semantic.summary.breaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.summary.nonBreaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.summary.informational, 0);
+        node_assert_1.default.strictEqual(report.semantic.recommendation.semver, 'patch');
         node_assert_1.default.ok(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.IGNORED_CHANGES(1).includes('IGNORED: 1 semantic change'));
     });
     (0, node_test_1.test)('fails when --input is missing', async () => {
@@ -371,4 +372,10 @@ async function runAnalyzeDiffCli(options) {
         node_assert_1.default.strictEqual((0, analyzeDiff_1.toAnalyzeDiffExitCode)(result), 1);
         node_assert_1.default.ok(result.error?.includes('"--input" is required for analyze-diff command'));
     });
+    (0, node_test_1.test)('uses semantic ref expansion instead of full dereference in the analyze hot path', () => {
+        const source = (0, node_fs_1.readFileSync)(node_path_1.default.join(__dirname, '..', 'analyzeDiff.ts'), 'utf8');
+        node_assert_1.default.ok(source.includes('loadSemanticOpenApiSpec'));
+        node_assert_1.default.ok(!source.includes('dereferenceOpenApiSpec'));
+        node_assert_1.default.ok(!source.includes('dereferenceOpenApiObject'));
+    });
 });

package/dist/cli/analyzeDiff/__tests__/analyzeDiffLomMiracles.test.d.ts

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

package/dist/cli/analyzeDiff/__tests__/analyzeDiffLomMiracles.test.d.ts.map

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

package/dist/cli/analyzeDiff/__tests__/analyzeDiffLomMiracles.test.js

@@ -0,0 +1,47 @@
+"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_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_test_1 = require("node:test");
+const silenceLoggers_1 = require("../../../test/helpers/silenceLoggers");
+const analyzeDiff_1 = require("../analyzeDiff");
+const generatedRoot = node_path_1.default.join(__dirname, 'generated');
+const createTempDir = (t, prefix) => {
+    node_fs_1.default.mkdirSync(generatedRoot, { recursive: true });
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(generatedRoot, prefix));
+    t.after(() => {
+        node_fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+    });
+    return tempDir;
+};
+(0, node_test_1.describe)('@unit: analyzeDiff lom miracles', () => {
+    let restoreAppLogger;
+    (0, node_test_1.beforeEach)(() => {
+        restoreAppLogger = (0, silenceLoggers_1.installSilenceAppLogger)();
+    });
+    (0, node_test_1.afterEach)(() => {
+        restoreAppLogger?.();
+        restoreAppLogger = undefined;
+    });
+    (0, node_test_1.test)('builds changes and miracles for lom v1 vs v2 specs', async (t) => {
+        const tmpDir = createTempDir(t, 'lom-diff-');
+        const reportPath = node_path_1.default.join(tmpDir, 'report.json');
+        const specRoot = node_path_1.default.join(__dirname, '../../../../test/spec/lom');
+        const result = await (0, analyzeDiff_1.analyzeDiff)({
+            input: node_path_1.default.join(specRoot, 'lom_api.v2.yaml'),
+            compareWith: node_path_1.default.join(specRoot, 'lom_api.v1.yaml'),
+            outputReport: reportPath,
+        });
+        node_assert_1.default.ok(result.success, result.error);
+        const report = JSON.parse(node_fs_1.default.readFileSync(reportPath, 'utf-8'));
+        node_assert_1.default.ok(report.semantic.changes.length > 0, 'expected semantic changes');
+        node_assert_1.default.ok(report.structural.miracles.length > 0, 'expected miracles in report');
+        node_assert_1.default.ok(report.structural.miracles.some(miracle => miracle.type === 'RENAME'));
+        node_assert_1.default.ok(report.structural.miracles.some(miracle => miracle.type === 'TYPE_COERCION'));
+        node_assert_1.default.ok(report.semantic.changes.some(change => change.type === 'model.property.type.changed'));
+    });
+});

package/dist/cli/analyzeDiff/__tests__/analyzeDiffRenameAndInvalidRegex.test.js

@@ -75,12 +75,13 @@ const createTempDir = (t, prefix) => {
         node_assert_1.default.ok(result.success, `analyzeDiff failed: ${result.error ?? 'unknown'}`);
         const reportRaw = node_fs_1.default.readFileSync(reportPath, 'utf-8');
         const report = JSON.parse(reportRaw);
-        const removed = report.changes.find(change => change.type === 'model.property.removed' && change.path === '#/components/schemas/User/properties/first_name');
-        const added = report.changes.find(change => change.type === 'model.property.added' && change.path === '#/components/schemas/User/properties/firstName');
+        const removed = report.semantic.changes.find(change => change.type === 'model.property.removed' && change.path === '#/components/schemas/User/properties/first_name');
+        const added = report.semantic.changes.find(change => change.type === 'model.property.added' && change.path === '#/components/schemas/User/properties/firstName');
         node_assert_1.default.ok(removed, 'Expected semantic removal entry for previous property');
         node_assert_1.default.ok(added, 'Expected semantic addition entry for renamed property');
         node_assert_1.default.strictEqual(removed?.severity, 'breaking');
         node_assert_1.default.strictEqual(added?.severity, 'non-breaking');
+        node_assert_1.default.ok(report.structural.miracles.some(miracle => miracle.type === 'RENAME'));
     });
     (0, node_test_1.test)('invalid regex in config does not crash and valid rules still apply', async (t) => {
         const tmpDir = createTempDir(t, 'openapi-diff-invalidregex-');
@@ -141,11 +142,11 @@ const createTempDir = (t, prefix) => {
         node_assert_1.default.ok(result.success, `analyzeDiff failed: ${result.error ?? 'unknown'}`);
         const reportRaw = node_fs_1.default.readFileSync(reportPath, 'utf-8');
         const report = JSON.parse(reportRaw);
-        const filteredTypeChange = report.changes.find(change => change.type === 'model.property.type.changed' && change.path === '#/components/schemas/User/properties/age');
+        const filteredTypeChange = report.semantic.changes.find(change => change.type === 'model.property.type.changed' && change.path === '#/components/schemas/User/properties/age');
         node_assert_1.default.ok(!filteredTypeChange, 'Expected matching semantic change to be filtered by valid rule while invalid regex is ignored');
-        node_assert_1.default.strictEqual(report.summary.breaking, 0);
-        node_assert_1.default.strictEqual(report.summary.nonBreaking, 0);
-        node_assert_1.default.strictEqual(report.summary.informational, 0);
-        node_assert_1.default.strictEqual(report.recommendation.semver, 'patch');
+        node_assert_1.default.strictEqual(report.semantic.summary.breaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.summary.nonBreaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.summary.informational, 0);
+        node_assert_1.default.strictEqual(report.semantic.recommendation.semver, 'patch');
     });
 });

package/dist/cli/analyzeDiff/__tests__/analyzeDiffTypeCoercion.test.js

@@ -75,11 +75,12 @@ const createTempDir = (t, prefix) => {
         node_assert_1.default.ok(result.success, `analyzeDiff failed: ${result.error ?? 'unknown error'}`);
         const reportRaw = node_fs_1.default.readFileSync(reportPath, 'utf-8');
         const report = JSON.parse(reportRaw);
-        const typeChange = report.changes.find(change => change.type === 'model.property.type.changed');
+        const typeChange = report.semantic.changes.find(change => change.type === 'model.property.type.changed');
         node_assert_1.default.ok(typeChange, 'Expected semantic type-change entry');
         node_assert_1.default.strictEqual(typeChange?.path, '#/components/schemas/User/properties/age');
         node_assert_1.default.strictEqual(typeChange?.severity, 'breaking');
-        node_assert_1.default.ok(report.summary.breaking > 0);
+        node_assert_1.default.ok(report.semantic.summary.breaking > 0);
+        node_assert_1.default.ok(report.structural.miracles.some(miracle => miracle.type === 'TYPE_COERCION'));
     });
     (0, node_test_1.test)('filters semantic type-change entry when rule matches path', async (t) => {
         const tmpDir = createTempDir(t, 'openapi-diff-test-');
@@ -136,11 +137,11 @@ const createTempDir = (t, prefix) => {
         node_assert_1.default.ok(result.success, `analyzeDiff failed: ${result.error ?? 'unknown error'}`);
         const reportRaw = node_fs_1.default.readFileSync(reportPath, 'utf-8');
         const report = JSON.parse(reportRaw);
-        const filteredTypeChange = report.changes.find(change => change.type === 'model.property.type.changed' && change.path === '#/components/schemas/User/properties/age');
+        const filteredTypeChange = report.semantic.changes.find(change => change.type === 'model.property.type.changed' && change.path === '#/components/schemas/User/properties/age');
         node_assert_1.default.ok(!filteredTypeChange, 'Expected semantic type-change to be filtered by analyze.ignore');
-        node_assert_1.default.strictEqual(report.summary.breaking, 0);
-        node_assert_1.default.strictEqual(report.summary.nonBreaking, 0);
-        node_assert_1.default.strictEqual(report.summary.informational, 0);
-        node_assert_1.default.strictEqual(report.recommendation.semver, 'patch');
+        node_assert_1.default.strictEqual(report.semantic.summary.breaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.summary.nonBreaking, 0);
+        node_assert_1.default.strictEqual(report.semantic.summary.informational, 0);
+        node_assert_1.default.strictEqual(report.semantic.recommendation.semver, 'patch');
     });
 });

package/dist/cli/analyzeDiff/analyzeDiff.d.ts

@@ -1,4 +1,12 @@
 import { OptionValues } from 'commander';
+/**
+ * Результат выполнения команды analyze-diff.
+ * @property success признак успешного завершения
+ * @property [skipped] анализ пропущен из-за отсутствия базовой спецификации
+ * @property [reportPath] абсолютный путь к сохранённому отчёту
+ * @property [ignored] количество проигнорированных изменений
+ * @property [error] текст ошибки при неуспешном завершении
+ */
 export type AnalyzeDiffResult = {
     success: boolean;
     skipped?: boolean;
@@ -7,11 +15,15 @@ export type AnalyzeDiffResult = {
     error?: string;
 };
 /**
- * Maps analyze-diff result to a process exit code. Does not call `process.exit`.
+ * Преобразует результат analyze-diff в код выхода процесса. Не вызывает `process.exit`.
+ * @param result результат выполнения analyze-diff
+ * @returns код выхода: 0 при успехе, 1 при ошибке
  */
 export declare function toAnalyzeDiffExitCode(result: AnalyzeDiffResult): number;
 /**
- * Runs semantic diff analysis between two OpenAPI specs and writes JSON report.
+ * Выполняет семантическое сравнение двух OpenAPI-спецификаций и записывает JSON-отчёт.
+ * @param options опции CLI команды analyze-diff
+ * @returns результат выполнения с путём к отчёту или описанием ошибки
  */
 export declare function analyzeDiff(options: OptionValues): Promise<AnalyzeDiffResult>;
 //# sourceMappingURL=analyzeDiff.d.ts.map

package/dist/cli/analyzeDiff/analyzeDiff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzeDiff.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/analyzeDiff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAoBzC,MAAM,MAAM,iBAAiB,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuFnF"}
+{"version":3,"file":"analyzeDiff.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/analyzeDiff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAuBzC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAEvE;AAqBD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuGnF"}

package/dist/cli/analyzeDiff/analyzeDiff.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toAnalyzeDiffExitCode = toAnalyzeDiffExitCode;
 exports.analyzeDiff = analyzeDiff;
+const crypto_1 = __importDefault(require("crypto"));
 const Consts_1 = require("../../common/Consts");
 const LoggerMessages_1 = require("../../common/LoggerMessages");
 const validateZodOptions_1 = require("../../common/Validation/validateZodOptions");
@@ -10,7 +14,10 @@ const loadGovernanceConfig_1 = require("../../core/governance/loadGovernanceConf
 const applySemanticDiffPluginHooks_1 = require("../../core/plugins/applySemanticDiffPluginHooks");
 const loadGeneratorPlugins_1 = require("../../core/plugins/loadGeneratorPlugins");
 const analyzeOpenApiDiff_1 = require("../../core/semanticDiff/analyzeOpenApiDiff");
-const getOpenApiSpec_1 = require("../../core/utils/getOpenApiSpec");
+const DiffReport_model_1 = require("../../core/types/DiffReport.model");
+const adapters_1 = require("../../core/utils/adapters");
+const buildMiraclesFromSemanticChanges_1 = require("../../core/utils/buildMiraclesFromSemanticChanges");
+const loadSemanticOpenApiSpec_1 = require("../../core/utils/loadSemanticOpenApiSpec");
 const schemas_1 = require("../schemas");
 const ciSummary_1 = require("./ciSummary");
 const ignoreRules_1 = require("./ignoreRules");
@@ -19,13 +26,33 @@ const pluginPaths_1 = require("./pluginPaths");
 const semanticDiffContext_1 = require("./semanticDiffContext");
 const specParser_1 = require("./specParser");
 /**
- * Maps analyze-diff result to a process exit code. Does not call `process.exit`.
+ * Преобразует результат analyze-diff в код выхода процесса. Не вызывает `process.exit`.
+ * @param result результат выполнения analyze-diff
+ * @returns код выхода: 0 при успехе, 1 при ошибке
  */
 function toAnalyzeDiffExitCode(result) {
     return result.success ? 0 : 1;
 }
+function createSpecHash(spec) {
+    const seen = new WeakSet();
+    const serializedSpec = JSON.stringify(spec, (_key, value) => {
+        if (value && typeof value === 'object') {
+            if (seen.has(value)) {
+                return '[Circular]';
+            }
+            seen.add(value);
+        }
+        return value;
+    });
+    return crypto_1.default
+        .createHash('sha256')
+        .update(serializedSpec ?? '')
+        .digest('hex');
+}
 /**
- * Runs semantic diff analysis between two OpenAPI specs and writes JSON report.
+ * Выполняет семантическое сравнение двух OpenAPI-спецификаций и записывает JSON-отчёт.
+ * @param options опции CLI команды analyze-diff
+ * @returns результат выполнения с путём к отчёту или описанием ошибки
  */
 async function analyzeDiff(options) {
     const validationResult = (0, validateZodOptions_1.validateZodOptions)(schemas_1.analyzeDiffOptionsSchema, options);
@@ -46,11 +73,9 @@ async function analyzeDiff(options) {
         }
         const baseSourceLabel = oldSpecInput ? `compare-with:${oldSpecInput}` : `git:${gitRef}`;
         Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.STARTED(newSpecInput, baseSourceLabel));
-        const newContext = (0, semanticDiffContext_1.createSemanticDiffContext)(newSpecInput);
-        const newSpec = await (0, getOpenApiSpec_1.getOpenApiSpec)(newContext, newSpecInput);
-        const oldSpec = oldSpecInput
-            ? await (0, getOpenApiSpec_1.getOpenApiSpec)((0, semanticDiffContext_1.createSemanticDiffContext)(oldSpecInput), oldSpecInput)
-            : (await (0, specParser_1.readSpecFromGit)(gitRef, newSpecInput));
+        (0, semanticDiffContext_1.createSemanticDiffContext)(newSpecInput);
+        const newSpec = await (0, loadSemanticOpenApiSpec_1.loadSemanticOpenApiSpec)(newSpecInput);
+        const oldSpec = oldSpecInput ? await (0, loadSemanticOpenApiSpec_1.loadSemanticOpenApiSpec)(oldSpecInput) : await (0, loadSemanticOpenApiSpec_1.loadSemanticOpenApiObject)(await (0, specParser_1.readSpecFromGit)(gitRef, newSpecInput), newSpecInput);
         if (oldSpecInput && validatedOptions.git) {
             Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.COMPARE_WITH_OVERRIDES_GIT(validatedOptions.git));
         }
@@ -72,7 +97,7 @@ async function analyzeDiff(options) {
             },
         });
         const { report: reportAfterIgnore, ignored } = (0, ignoreSemanticChanges_1.filterSemanticChangesByIgnoreRules)(pluginHooksResult.report, ignoreRules);
-        const report = {
+        const semanticReport = {
             ...reportAfterIgnore,
             governance: (0, evaluateGovernanceRules_1.evaluateGovernanceRules)({
                 openApi: newSpec,
@@ -80,19 +105,37 @@ async function analyzeDiff(options) {
                 allowBreaking: validatedOptions.allowBreaking ?? false,
                 governanceConfig: governancePolicy,
             }),
+            miracles: (0, buildMiraclesFromSemanticChanges_1.buildMiraclesFromSemanticChanges)(reportAfterIgnore.changes),
+        };
+        const report = {
+            schemaVersion: DiffReport_model_1.UNIFIED_DIFF_REPORT_SCHEMA_VERSION,
+            timestamp: new Date().toISOString(),
+            metadata: {
+                base: baseSourceLabel,
+                target: newSpecInput,
+                baseHash: createSpecHash(oldSpec),
+                targetHash: createSpecHash(newSpec),
+            },
+            semantic: {
+                changes: semanticReport.changes,
+                governance: semanticReport.governance,
+                recommendation: semanticReport.recommendation,
+                summary: semanticReport.summary,
+            },
+            structural: (0, adapters_1.adaptSemanticToStructural)(semanticReport, ignored),
         };
         const reportPath = await (0, analyzeOpenApiDiff_1.writeSemanticDiffReport)(report, pluginHooksResult.reportPath);
         Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.REPORT_CREATED(reportPath));
-        Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.SUMMARY(report, reportPath));
-        Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.RECOMMENDATION(report));
-        Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.GOVERNANCE(report));
+        Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.SUMMARY(semanticReport, reportPath));
+        Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.RECOMMENDATION(semanticReport));
+        Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.GOVERNANCE(semanticReport));
         if (ignored > 0) {
             Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.IGNORED_CHANGES(ignored));
         }
         if (validatedOptions.ci) {
             Consts_1.APP_LOGGER.info(LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.CI_MARKDOWN_SUMMARY((0, ciSummary_1.formatCiMarkdownSummary)(report, reportPath)));
         }
-        if (validatedOptions.ci && report.governance.summary.errors > 0) {
+        if (validatedOptions.ci && semanticReport.governance.summary.errors > 0) {
             return { success: false, reportPath, error: LoggerMessages_1.LOGGER_MESSAGES.ANALYZE_DIFF.CI_FAILURE };
         }
         return { success: true, reportPath, ignored };

package/dist/cli/analyzeDiff/ciSummary.d.ts

@@ -1,6 +1,9 @@
-import { SemanticDiffReport } from '../../core/semanticDiff/analyzeOpenApiDiff';
+import type { UnifiedDiffReport } from '../../core/types/DiffReport.model';
 /**
- * Builds markdown summary for CI logs.
+ * Формирует markdown-сводку семантического diff для CI-логов.
+ * @param report унифицированный diff-отчёт
+ * @param reportPath путь к сохранённому отчёту
+ * @returns markdown-текст для вывода в CI
  */
-export declare function formatCiMarkdownSummary(report: SemanticDiffReport, reportPath: string): string;
+export declare function formatCiMarkdownSummary(report: UnifiedDiffReport, reportPath: string): string;
 //# sourceMappingURL=ciSummary.d.ts.map

package/dist/cli/analyzeDiff/ciSummary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ciSummary.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/ciSummary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAEhF;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAc9F"}
+{"version":3,"file":"ciSummary.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/ciSummary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAe7F"}

package/dist/cli/analyzeDiff/ciSummary.js

@@ -2,19 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatCiMarkdownSummary = formatCiMarkdownSummary;
 /**
- * Builds markdown summary for CI logs.
+ * Формирует markdown-сводку семантического diff для CI-логов.
+ * @param report унифицированный diff-отчёт
+ * @param reportPath путь к сохранённому отчёту
+ * @returns markdown-текст для вывода в CI
  */
 function formatCiMarkdownSummary(report, reportPath) {
-    const reasons = report.recommendation.reasons.map(reason => `- \`${reason}\``).join('\n');
+    const semantic = report.semantic;
+    const reasons = semantic.recommendation.reasons.map(reason => `- \`${reason}\``).join('\n');
     return [
         '### OpenAPI Semantic Diff',
         `- Report: \`${reportPath}\``,
         `- Schema Version: \`${report.schemaVersion}\``,
-        `- Recommendation: \`${report.recommendation.semver}\` (confidence: \`${report.recommendation.confidence}\`)`,
-        `- Reason: ${report.recommendation.reason}`,
+        `- Recommendation: \`${semantic.recommendation.semver}\` (confidence: \`${semantic.recommendation.confidence}\`)`,
+        `- Reason: ${semantic.recommendation.reason}`,
         '- Reason Codes:',
         reasons,
-        `- Summary: breaking=\`${report.summary.breaking}\`, nonBreaking=\`${report.summary.nonBreaking}\`, informational=\`${report.summary.informational}\``,
-        `- Governance: errors=\`${report.governance.summary.errors}\`, warnings=\`${report.governance.summary.warnings}\`, info=\`${report.governance.summary.info}\``,
+        `- Summary: breaking=\`${semantic.summary.breaking}\`, nonBreaking=\`${semantic.summary.nonBreaking}\`, informational=\`${semantic.summary.informational}\``,
+        `- Governance: errors=\`${semantic.governance.summary.errors}\`, warnings=\`${semantic.governance.summary.warnings}\`, info=\`${semantic.governance.summary.info}\``,
     ].join('\n');
 }

package/dist/cli/analyzeDiff/report.d.ts

@@ -1,3 +1,2 @@
-export { buildLegacyReport as buildReport } from './buildLegacyReport';
 export { writeLegacyReport as writeReportToFile } from './writeLegacyReport';
 //# sourceMappingURL=report.d.ts.map

package/dist/cli/analyzeDiff/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAE,iBAAiB,IAAI,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,IAAI,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/cli/analyzeDiff/report.js

@@ -1,7 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeReportToFile = exports.buildReport = void 0;
-var buildLegacyReport_1 = require("./buildLegacyReport");
-Object.defineProperty(exports, "buildReport", { enumerable: true, get: function () { return buildLegacyReport_1.buildLegacyReport; } });
+exports.writeReportToFile = void 0;
 var writeLegacyReport_1 = require("./writeLegacyReport");
 Object.defineProperty(exports, "writeReportToFile", { enumerable: true, get: function () { return writeLegacyReport_1.writeLegacyReport; } });

package/dist/cli/analyzeDiff/writeLegacyReport.d.ts

@@ -1,6 +1,8 @@
 import { DiffReport } from './types';
 /**
  * Сохраняет legacy report на диск и логирует summary.
+ * @param report legacy diff-отчёт
+ * @param [reportPath] путь к файлу отчёта
  */
 export declare function writeLegacyReport(report: DiffReport, reportPath?: string): void;
 //# sourceMappingURL=writeLegacyReport.d.ts.map

package/dist/cli/analyzeDiff/writeLegacyReport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeLegacyReport.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/writeLegacyReport.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,GAAE,MAAyC,GAAG,IAAI,CASjH"}
+{"version":3,"file":"writeLegacyReport.d.ts","sourceRoot":"","sources":["../../../src/cli/analyzeDiff/writeLegacyReport.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,GAAE,MAAyC,GAAG,IAAI,CASjH"}

package/dist/cli/analyzeDiff/writeLegacyReport.js

@@ -10,6 +10,8 @@ const Consts_1 = require("../../common/Consts");
 const logLegacyReport_1 = require("./logLegacyReport");
 /**
  * Сохраняет legacy report на диск и логирует summary.
+ * @param report legacy diff-отчёт
+ * @param [reportPath] путь к файлу отчёта
  */
 function writeLegacyReport(report, reportPath = Consts_1.DEFAULT_ANALYZE_DIFF_REPORT_PATH) {
     const reportDir = path_1.default.dirname(reportPath);

package/dist/cli/analyzeUsage/core/Scanner.d.ts

@@ -1,8 +1,16 @@
 import { SourceFile } from 'ts-morph';
 import type { Contract } from '../types';
+/** Сканер экспортов сгенерированного API-файла для построения контракта. */
 export declare class Scanner {
     private generatedFile;
+    /**
+     * @param generatedFile сгенерированный исходный файл API
+     */
     constructor(generatedFile: SourceFile);
+    /**
+     * Сканирует экспорты файла и собирает контракт сервисов, моделей и схем.
+     * @returns контракт сгенерированного API
+     */
     scan(): Contract;
     private extractMethodsFromDeclaration;
     /**

package/dist/cli/analyzeUsage/core/Scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scanner.d.ts","sourceRoot":"","sources":["../../../../src/cli/analyzeUsage/core/Scanner.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,UAAU,EAAc,MAAM,UAAU,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,UAAU,CAAC;AAEzD,qBAAa,OAAO;IACJ,OAAO,CAAC,aAAa;gBAAb,aAAa,EAAE,UAAU;IAEtC,IAAI,IAAI,QAAQ;IA4CvB,OAAO,CAAC,6BAA6B;IA0CrC;;;OAGG;IACH,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,cAAc;CAGzB"}
+{"version":3,"file":"Scanner.d.ts","sourceRoot":"","sources":["../../../../src/cli/analyzeUsage/core/Scanner.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,UAAU,EAAc,MAAM,UAAU,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,UAAU,CAAC;AAEzD,4EAA4E;AAC5E,qBAAa,OAAO;IAIJ,OAAO,CAAC,aAAa;IAHjC;;OAEG;gBACiB,aAAa,EAAE,UAAU;IAE7C;;;OAGG;IACI,IAAI,IAAI,QAAQ;IA4CvB,OAAO,CAAC,6BAA6B;IA0CrC;;;OAGG;IACH,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,cAAc;CAGzB"}

package/dist/cli/analyzeUsage/core/Scanner.js

@@ -2,11 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Scanner = void 0;
 const ts_morph_1 = require("ts-morph");
+/** Сканер экспортов сгенерированного API-файла для построения контракта. */
 class Scanner {
     generatedFile;
+    /**
+     * @param generatedFile сгенерированный исходный файл API
+     */
     constructor(generatedFile) {
         this.generatedFile = generatedFile;
     }
+    /**
+     * Сканирует экспорты файла и собирает контракт сервисов, моделей и схем.
+     * @returns контракт сгенерированного API
+     */
     scan() {
         const exports = this.generatedFile.getExportedDeclarations();
         console.log(`DEBUG SCANNER: File exports:`, Array.from(exports.keys()));
@@ -102,6 +110,8 @@ class Scanner {
             name,
             params: sig?.getParameters().map(p => ({
                 name: p.getName(),
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
                 isOptional: p.isOptional(),
                 type: p.getTypeAtLocation(node).getText(),
             })) || [],

package/dist/cli/analyzeUsage/rules/ClientRule.d.ts

@@ -1,6 +1,14 @@
 import type { ProjectContext } from '../core/ProjectContext';
 import type { Contract, Finding, Rule, Stats } from '../types';
+/** Правило проверки использования createClient и ClientOptions в потребителях API. */
 export declare class ClientRule implements Rule {
+    /**
+     * Проверяет вызовы createClient и соответствие ClientOptions.
+     * @param context контекст проекта
+     * @param contract контракт сгенерированного API
+     * @param stats накопительная статистика использования
+     * @returns список найденных проблем
+     */
     check(context: ProjectContext, contract: Contract, stats: Stats): Promise<Finding[]>;
 }
 //# sourceMappingURL=ClientRule.d.ts.map

package/dist/cli/analyzeUsage/rules/ClientRule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientRule.d.ts","sourceRoot":"","sources":["../../../../src/cli/analyzeUsage/rules/ClientRule.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAE/D,qBAAa,UAAW,YAAW,IAAI;IAC7B,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CA0E7F"}
+{"version":3,"file":"ClientRule.d.ts","sourceRoot":"","sources":["../../../../src/cli/analyzeUsage/rules/ClientRule.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAE/D,sFAAsF;AACtF,qBAAa,UAAW,YAAW,IAAI;IACnC;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CA4E7F"}

package/dist/cli/analyzeUsage/rules/ClientRule.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientRule = void 0;
 const ts_morph_1 = require("ts-morph");
+/** Правило проверки использования createClient и ClientOptions в потребителях API. */
 class ClientRule {
+    /**
+     * Проверяет вызовы createClient и соответствие ClientOptions.
+     * @param context контекст проекта
+     * @param contract контракт сгенерированного API
+     * @param stats накопительная статистика использования
+     * @returns список найденных проблем
+     */
     async check(context, contract, stats) {
         const findings = [];
         const checker = context.getTypeChecker();
@@ -47,6 +55,8 @@ class ClientRule {
                     continue;
                 if (expectedType) {
                     const providedType = checker.getTypeAtLocation(args[0]);
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-ignore
                     if (!providedType.isAssignableTo(expectedType)) {
                         findings.push({
                             id: 'CLIENT_OPTIONS_MISMATCH',