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

package/dist/core/semanticDiff/analyzeOpenApiDiff.js

@@ -0,0 +1,668 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMANTIC_DIFF_REPORT_SCHEMA_VERSION = void 0;
+exports.analyzeOpenApiDiff = analyzeOpenApiDiff;
+exports.writeSemanticDiffReport = writeSemanticDiffReport;
+const path_1 = __importDefault(require("path"));
+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'];
+/**
+ * Extracts OpenAPI v2/v3 schema container from a loaded spec.
+ */
+function getSchemaContainer(spec) {
+    const specRecord = spec;
+    const components = specRecord.components;
+    const schemas = components?.schemas;
+    const definitions = specRecord.definitions;
+    if (schemas && typeof schemas === 'object') {
+        return schemas;
+    }
+    if (definitions && typeof definitions === 'object') {
+        return definitions;
+    }
+    return {};
+}
+/**
+ * Normalizes schema into a comparable type descriptor.
+ */
+function getSchemaType(schema) {
+    if (!schema || typeof schema !== 'object') {
+        return 'unknown';
+    }
+    const schemaRecord = schema;
+    const schemaRef = schemaRecord.$ref;
+    if (typeof schemaRef === 'string') {
+        return `ref:${schemaRef}`;
+    }
+    const enumValues = schemaRecord.enum;
+    if (Array.isArray(enumValues)) {
+        const values = enumValues.map(item => String(item)).sort();
+        return `enum(${values.join('|')})`;
+    }
+    const schemaType = schemaRecord.type;
+    if (schemaType === 'array') {
+        return `array<${getSchemaType(schemaRecord.items)}>`;
+    }
+    if (Array.isArray(schemaRecord.oneOf)) {
+        const unionTypes = schemaRecord.oneOf.map(item => getSchemaType(item)).sort();
+        return `oneOf(${unionTypes.join('|')})`;
+    }
+    if (Array.isArray(schemaRecord.anyOf)) {
+        const unionTypes = schemaRecord.anyOf.map(item => getSchemaType(item)).sort();
+        return `anyOf(${unionTypes.join('|')})`;
+    }
+    if (Array.isArray(schemaRecord.allOf)) {
+        const intersectionTypes = schemaRecord.allOf.map(item => getSchemaType(item)).sort();
+        return `allOf(${intersectionTypes.join('&')})`;
+    }
+    if (typeof schemaType === 'string') {
+        const schemaFormat = schemaRecord.format;
+        if (typeof schemaFormat === 'string' && schemaFormat.trim()) {
+            return `${schemaType}:${schemaFormat}`;
+        }
+        return schemaType;
+    }
+    const properties = schemaRecord.properties;
+    if (properties && typeof properties === 'object') {
+        return 'object';
+    }
+    return 'unknown';
+}
+/**
+ * Classifies a type transition by severity for semantic diff.
+ */
+function classifyTypeTransition(fromType, toType) {
+    if (fromType === toType) {
+        return 'informational';
+    }
+    if (isTypeAssignable(fromType, toType)) {
+        return 'non-breaking';
+    }
+    return 'breaking';
+}
+/**
+ * Splits descriptor content by top-level delimiter while preserving nested blocks.
+ */
+function splitTopLevel(input, delimiter) {
+    const result = [];
+    let buffer = '';
+    let depth = 0;
+    for (const char of input) {
+        if (char === '(' || char === '<') {
+            depth += 1;
+            buffer += char;
+            continue;
+        }
+        if (char === ')' || char === '>') {
+            depth = Math.max(0, depth - 1);
+            buffer += char;
+            continue;
+        }
+        if (char === delimiter && depth === 0) {
+            if (buffer.trim()) {
+                result.push(buffer.trim());
+            }
+            buffer = '';
+            continue;
+        }
+        buffer += char;
+    }
+    if (buffer.trim()) {
+        result.push(buffer.trim());
+    }
+    return result;
+}
+/**
+ * Extracts descriptor arguments for pattern prefix(...)
+ */
+function extractDescriptorArgs(descriptor, prefix) {
+    if (!descriptor.startsWith(`${prefix}(`) || !descriptor.endsWith(')')) {
+        return null;
+    }
+    const inner = descriptor.slice(prefix.length + 1, -1);
+    if (!inner.trim()) {
+        return [];
+    }
+    const separator = prefix === 'allOf' ? '&' : '|';
+    return splitTopLevel(inner, separator);
+}
+/**
+ * Parses array descriptor array<...>.
+ */
+function extractArrayItemType(descriptor) {
+    if (!descriptor.startsWith('array<') || !descriptor.endsWith('>')) {
+        return null;
+    }
+    return descriptor.slice('array<'.length, -1);
+}
+/**
+ * Parses scalar descriptor into base and format parts.
+ */
+function parseScalarDescriptor(descriptor) {
+    const [base, ...formatParts] = descriptor.split(':');
+    if (!base) {
+        return { base: descriptor, format: null };
+    }
+    if (formatParts.length === 0) {
+        return { base, format: null };
+    }
+    return {
+        base,
+        format: formatParts.join(':'),
+    };
+}
+/**
+ * Checks whether format transition is widening for a given base type.
+ */
+function isFormatAssignable(baseType, fromFormat, toFormat) {
+    if (fromFormat === toFormat) {
+        return true;
+    }
+    if (fromFormat && !toFormat) {
+        return true;
+    }
+    if (!fromFormat && toFormat) {
+        return false;
+    }
+    if (!fromFormat || !toFormat) {
+        return true;
+    }
+    if (baseType === 'integer') {
+        if (fromFormat === 'int32' && toFormat === 'int64') {
+            return true;
+        }
+        if (fromFormat === 'int64' && toFormat === 'int32') {
+            return false;
+        }
+    }
+    if (baseType === 'number') {
+        if (fromFormat === 'float' && toFormat === 'double') {
+            return true;
+        }
+        if (fromFormat === 'double' && toFormat === 'float') {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Compares two scalar type descriptors without composite wrappers.
+ */
+function isScalarTypeAssignable(fromType, toType) {
+    if (fromType === toType) {
+        return true;
+    }
+    if (toType === 'any' || toType === 'unknown') {
+        return true;
+    }
+    if (fromType === 'any' || fromType === 'unknown') {
+        return false;
+    }
+    const fromRef = fromType.startsWith('ref:');
+    const toRef = toType.startsWith('ref:');
+    if (fromRef || toRef) {
+        if (!fromRef || !toRef) {
+            return false;
+        }
+        return fromType === toType;
+    }
+    const { base: fromBase, format: fromFormat } = parseScalarDescriptor(fromType);
+    const { base: toBase, format: toFormat } = parseScalarDescriptor(toType);
+    if (fromBase === toBase) {
+        return isFormatAssignable(fromBase, fromFormat, toFormat);
+    }
+    if (fromBase === 'integer' && toBase === 'number') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Checks assignability: true means change from -> to is widening or neutral.
+ */
+function isTypeAssignable(fromType, toType) {
+    if (fromType === toType) {
+        return true;
+    }
+    const fromArrayItem = extractArrayItemType(fromType);
+    const toArrayItem = extractArrayItemType(toType);
+    if (fromArrayItem !== null || toArrayItem !== null) {
+        if (fromArrayItem === null || toArrayItem === null) {
+            return false;
+        }
+        return isTypeAssignable(fromArrayItem, toArrayItem);
+    }
+    const fromEnum = extractDescriptorArgs(fromType, 'enum');
+    const toEnum = extractDescriptorArgs(toType, 'enum');
+    if (fromEnum !== null || toEnum !== null) {
+        if (fromEnum === null || toEnum === null) {
+            return false;
+        }
+        return fromEnum.every(value => toEnum.includes(value));
+    }
+    const fromOneOf = extractDescriptorArgs(fromType, 'oneOf') ?? extractDescriptorArgs(fromType, 'anyOf');
+    if (fromOneOf !== null) {
+        return fromOneOf.every(option => isTypeAssignable(option, toType));
+    }
+    const toOneOf = extractDescriptorArgs(toType, 'oneOf') ?? extractDescriptorArgs(toType, 'anyOf');
+    if (toOneOf !== null) {
+        return toOneOf.some(option => isTypeAssignable(fromType, option));
+    }
+    const fromAllOf = extractDescriptorArgs(fromType, 'allOf');
+    if (fromAllOf !== null) {
+        return fromAllOf.some(option => isTypeAssignable(option, toType));
+    }
+    const toAllOf = extractDescriptorArgs(toType, 'allOf');
+    if (toAllOf !== null) {
+        return toAllOf.every(option => isTypeAssignable(fromType, option));
+    }
+    return isScalarTypeAssignable(fromType, toType);
+}
+/**
+ * Builds canonical model map from v2/v3 schema section.
+ */
+function buildCanonicalModels(spec) {
+    const models = new Map();
+    const schemas = getSchemaContainer(spec);
+    for (const [name, schema] of Object.entries(schemas)) {
+        const propertiesMap = new Map();
+        const schemaProperties = schema.properties;
+        if (schemaProperties && typeof schemaProperties === 'object') {
+            for (const [propertyName, propertySchema] of Object.entries(schemaProperties)) {
+                propertiesMap.set(propertyName, getSchemaType(propertySchema));
+            }
+        }
+        const requiredRaw = schema.required;
+        const required = Array.isArray(requiredRaw) ? new Set(requiredRaw.map(value => String(value))) : new Set();
+        const modelEnumRaw = schema.enum;
+        const modelEnum = Array.isArray(modelEnumRaw) ? new Set(modelEnumRaw.map(value => String(value))) : new Set();
+        models.set(name, {
+            properties: propertiesMap,
+            required,
+            enumValues: modelEnum,
+        });
+    }
+    return models;
+}
+/**
+ * Checks whether response key is an explicit successful HTTP status key.
+ */
+function isSuccessResponseKey(value) {
+    return /^\s*2\d\d\s*$/.test(value) || /^\s*2xx\s*$/i.test(value);
+}
+/**
+ * Resolves response payload schema type for OpenAPI v2/v3 response object.
+ */
+function getResponsePayloadType(response) {
+    if (!response || typeof response !== 'object') {
+        return 'unknown';
+    }
+    const responseRecord = response;
+    const content = responseRecord.content;
+    if (content && typeof content === 'object') {
+        const jsonContent = content['application/json'];
+        if (jsonContent && typeof jsonContent === 'object') {
+            const jsonSchema = jsonContent.schema;
+            if (jsonSchema) {
+                return getSchemaType(jsonSchema);
+            }
+        }
+        for (const mediaTypeObject of Object.values(content)) {
+            if (!mediaTypeObject || typeof mediaTypeObject !== 'object') {
+                continue;
+            }
+            const mediaSchema = mediaTypeObject.schema;
+            if (mediaSchema) {
+                return getSchemaType(mediaSchema);
+            }
+        }
+    }
+    return getSchemaType(responseRecord.schema);
+}
+/**
+ * Builds canonical operation map from OpenAPI paths.
+ */
+function buildCanonicalOperations(spec) {
+    const operations = new Map();
+    const specRecord = spec;
+    const paths = specRecord.paths ?? {};
+    for (const [routePath, pathItemRaw] of Object.entries(paths)) {
+        const pathItem = pathItemRaw ?? {};
+        const pathParametersRaw = pathItem.parameters;
+        const pathParameters = Array.isArray(pathParametersRaw) ? pathParametersRaw : [];
+        for (const method of HTTP_METHODS) {
+            const operationRaw = pathItem[method];
+            if (!operationRaw || typeof operationRaw !== 'object') {
+                continue;
+            }
+            const operation = operationRaw;
+            const operationKey = `${method.toUpperCase()} ${routePath}`;
+            const operationParametersRaw = operation.parameters;
+            const operationParameters = Array.isArray(operationParametersRaw) ? operationParametersRaw : [];
+            const mergedParameters = [...pathParameters, ...operationParameters];
+            const parameters = new Map();
+            for (const parameterRaw of mergedParameters) {
+                if (!parameterRaw || typeof parameterRaw !== 'object') {
+                    continue;
+                }
+                const parameter = parameterRaw;
+                const parameterName = typeof parameter.name === 'string' ? parameter.name : '';
+                const parameterIn = typeof parameter.in === 'string' ? parameter.in : 'unknown';
+                if (!parameterName) {
+                    continue;
+                }
+                const schema = parameter.schema ?? parameter;
+                const type = getSchemaType(schema);
+                const required = parameter.required === true;
+                parameters.set(`${parameterIn}:${parameterName}`, { required, type });
+            }
+            const requestBody = operation.requestBody;
+            const requestBodyRequired = requestBody?.required === true;
+            const successResponses = new Map();
+            const responses = operation.responses;
+            if (responses && typeof responses === 'object') {
+                for (const [responseCode, responseValue] of Object.entries(responses)) {
+                    if (isSuccessResponseKey(responseCode)) {
+                        successResponses.set(responseCode, getResponsePayloadType(responseValue));
+                    }
+                }
+            }
+            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,
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * Pushes change entry to report collection.
+ */
+function pushChange(changes, severity, type, path, message, extras) {
+    changes.push({ severity, type, path, message, ...extras });
+}
+/**
+ * Normalizes, deduplicates and sorts changes for stable CI output.
+ */
+function normalizeAndDedupeChanges(changes) {
+    const unique = new Map();
+    for (const change of changes) {
+        const normalizedPath = change.path.replace(/\s+/g, ' ').trim();
+        const normalizedMessage = change.message.replace(/\s+/g, ' ').trim();
+        const normalizedChange = {
+            ...change,
+            path: normalizedPath,
+            message: normalizedMessage,
+        };
+        const key = [normalizedChange.severity, normalizedChange.type, normalizedChange.path, normalizedChange.message].join('|');
+        if (!unique.has(key)) {
+            unique.set(key, normalizedChange);
+        }
+    }
+    return [...unique.values()].sort((left, right) => {
+        if (left.path !== right.path) {
+            return left.path.localeCompare(right.path);
+        }
+        if (left.type !== right.type) {
+            return left.type.localeCompare(right.type);
+        }
+        if (left.severity !== right.severity) {
+            return left.severity.localeCompare(right.severity);
+        }
+        return left.message.localeCompare(right.message);
+    });
+}
+/**
+ * Diffs canonical models and appends semantic changes.
+ */
+function diffModels(oldModels, newModels, changes) {
+    for (const oldModelName of oldModels.keys()) {
+        if (!newModels.has(oldModelName)) {
+            pushChange(changes, 'breaking', 'model.removed', `#/components/schemas/${oldModelName}`, `Model "${oldModelName}" was removed.`);
+        }
+    }
+    for (const newModelName of newModels.keys()) {
+        if (!oldModels.has(newModelName)) {
+            pushChange(changes, 'non-breaking', 'model.added', `#/components/schemas/${newModelName}`, `Model "${newModelName}" was added.`);
+        }
+    }
+    for (const [modelName, oldModel] of oldModels.entries()) {
+        const newModel = newModels.get(modelName);
+        if (!newModel) {
+            continue;
+        }
+        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}".`, { from: { type: oldModel.properties.get(oldPropertyName) } });
+            }
+        }
+        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}".`, { to: { type: newPropertyType } });
+            }
+        }
+        for (const [propertyName, oldPropertyType] of oldModel.properties.entries()) {
+            const newPropertyType = newModel.properties.get(propertyName);
+            if (!newPropertyType) {
+                continue;
+            }
+            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}".`, { 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}".`, { 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}".`, {
+                    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}".`, {
+                    to: newEnumValue,
+                });
+            }
+        }
+    }
+}
+/**
+ * Diffs canonical operations and appends semantic changes.
+ */
+function diffOperations(oldOperations, newOperations, changes) {
+    for (const [oldOperationKey, oldOperation] of oldOperations.entries()) {
+        if (!newOperations.has(oldOperationKey)) {
+            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()) {
+        if (!oldOperations.has(newOperationKey)) {
+            pushChange(changes, 'non-breaking', 'operation.added', `#/paths/${newOperationKey}`, `Operation "${newOperationKey}" was added.`);
+        }
+    }
+    for (const [operationKey, oldOperation] of oldOperations.entries()) {
+        const newOperation = newOperations.get(operationKey);
+        if (!newOperation) {
+            continue;
+        }
+        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}".`, { 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}".`, { to: { type: newParameter.type, required: newParameter.required } });
+            }
+        }
+        for (const [parameterName, oldParameter] of oldOperation.parameters.entries()) {
+            const newParameter = newOperation.parameters.get(parameterName);
+            if (!newParameter) {
+                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}".`, { 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}".`, { 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}".`, { from: oldOperation.requestBodyRequired, to: newOperation.requestBodyRequired });
+        }
+        for (const oldResponseCode of oldOperation.successResponses.keys()) {
+            if (!newOperation.successResponses.has(oldResponseCode)) {
+                pushChange(changes, 'breaking', 'operation.response.success.removed', `#/paths/${operationKey}/responses/${oldResponseCode}`, `Successful response "${oldResponseCode}" was removed from operation "${operationKey}".`);
+            }
+        }
+        for (const newResponseCode of newOperation.successResponses.keys()) {
+            if (!oldOperation.successResponses.has(newResponseCode)) {
+                pushChange(changes, 'non-breaking', 'operation.response.success.added', `#/paths/${operationKey}/responses/${newResponseCode}`, `Successful response "${newResponseCode}" was added to operation "${operationKey}".`);
+            }
+        }
+        for (const [responseCode, oldResponseType] of oldOperation.successResponses.entries()) {
+            const newResponseType = newOperation.successResponses.get(responseCode);
+            if (!newResponseType || oldResponseType === newResponseType) {
+                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}".`, { from: oldResponseType, to: newResponseType });
+        }
+    }
+}
+/**
+ * Calculates summary counters from semantic changes list.
+ */
+function buildSummary(changes) {
+    return changes.reduce((summary, change) => {
+        if (change.severity === 'breaking') {
+            summary.breaking += 1;
+        }
+        else if (change.severity === 'non-breaking') {
+            summary.nonBreaking += 1;
+        }
+        else {
+            summary.informational += 1;
+        }
+        return summary;
+    }, {
+        breaking: 0,
+        nonBreaking: 0,
+        informational: 0,
+    });
+}
+/**
+ * Builds semver recommendation from semantic diff summary.
+ */
+function buildSemverRecommendation(summary) {
+    if (summary.breaking > 0) {
+        return {
+            semver: 'major',
+            confidence: summary.breaking >= 3 ? 'high' : 'medium',
+            reason: 'Breaking changes detected.',
+            reasons: ['HAS_BREAKING_CHANGES'],
+        };
+    }
+    if (summary.nonBreaking > 0) {
+        return {
+            semver: 'minor',
+            confidence: summary.nonBreaking >= 3 ? 'high' : 'medium',
+            reason: 'Backward-compatible feature changes detected.',
+            reasons: ['HAS_BACKWARD_COMPATIBLE_CHANGES'],
+        };
+    }
+    if (summary.informational > 0) {
+        return {
+            semver: 'patch',
+            confidence: 'medium',
+            reason: 'Only informational changes detected.',
+            reasons: ['HAS_INFORMATIONAL_ONLY_CHANGES'],
+        };
+    }
+    return {
+        semver: 'patch',
+        confidence: 'high',
+        reason: 'No breaking or feature-level changes detected.',
+        reasons: ['NO_API_SURFACE_CHANGES'],
+    };
+}
+/**
+ * Формирует семантический diff-отчёт между двумя OpenAPI-спецификациями.
+ * @param oldSpec базовая спецификация
+ * @param newSpec целевая спецификация
+ * @param [options] опции анализа, включая governance и разрешение breaking-изменений
+ * @returns семантический diff-отчёт
+ */
+function analyzeOpenApiDiff(oldSpec, newSpec, options = {}) {
+    const oldModels = buildCanonicalModels(oldSpec);
+    const newModels = buildCanonicalModels(newSpec);
+    const oldOperations = buildCanonicalOperations(oldSpec);
+    const newOperations = buildCanonicalOperations(newSpec);
+    const changes = [];
+    diffModels(oldModels, newModels, changes);
+    diffOperations(oldOperations, newOperations, changes);
+    const normalizedChanges = normalizeAndDedupeChanges(changes);
+    const summary = buildSummary(normalizedChanges);
+    const governance = (0, evaluateGovernanceRules_1.evaluateGovernanceRules)({
+        openApi: newSpec,
+        breakingChangesCount: summary.breaking,
+        allowBreaking: options.allowBreaking ?? false,
+        governanceConfig: options.governanceConfig,
+    });
+    return {
+        schemaVersion: exports.SEMANTIC_DIFF_REPORT_SCHEMA_VERSION,
+        summary,
+        recommendation: buildSemverRecommendation(summary),
+        governance,
+        changes: normalizedChanges,
+    };
+}
+/**
+ * Записывает семантический или унифицированный diff-отчёт в JSON-файл.
+ * @param report отчёт для сохранения
+ * @param reportFilePath путь к файлу отчёта
+ * @returns абсолютный путь к сохранённому файлу
+ */
+async function writeSemanticDiffReport(report, reportFilePath) {
+    const resolvedPath = (0, pathHelpers_1.resolveHelper)(process.cwd(), reportFilePath);
+    const directory = path_1.default.dirname(resolvedPath);
+    const directoryExists = await fileSystemHelpers_1.fileSystemHelpers.exists(directory);
+    if (!directoryExists) {
+        await fileSystemHelpers_1.fileSystemHelpers.mkdir(directory);
+    }
+    const reportContent = await (0, format_1.format)(JSON.stringify(report), 'json');
+    await fileSystemHelpers_1.fileSystemHelpers.writeFile(resolvedPath, reportContent);
+    return resolvedPath;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Результат валидации diff-отчёта по JSON Schema.
+ * @property valid признак успешной валидации
+ * @property errors список ошибок валидации
+ */
+export type SemanticDiffReportSchemaValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Валидирует 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

@@ -0,0 +1 @@
+{"version":3,"file":"semanticDiffReportSchema.d.ts","sourceRoot":"","sources":["../../../src/core/semanticDiff/semanticDiffReportSchema.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAmMF;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,OAAO,GAAG,wCAAwC,CAc1G"}