@unispechq/unispec-core 0.3.0 → 0.3.2

package/dist/cjs/src/diff/core.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffUniSpec = diffUniSpec;
+const annotators_1 = require("./annotators.js");
+const types_1 = require("./types.js");
+/**
+ * Check if a value is a plain object (not array, null, or other object types).
+ *
+ * @param value - The value to check
+ * @returns true if the value is a plain object, false otherwise
+ */
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+function diffValues(oldVal, newVal, basePath, out, options = {}) {
+    if (oldVal === newVal) {
+        return;
+    }
+    // Both plain objects → recurse by keys
+    if (isPlainObject(oldVal) && isPlainObject(newVal)) {
+        const oldKeys = new Set(Object.keys(oldVal));
+        const newKeys = new Set(Object.keys(newVal));
+        // Removed keys
+        for (const key of oldKeys) {
+            if (!newKeys.has(key)) {
+                out.push({
+                    path: `${basePath}/${key}`,
+                    description: "Field removed",
+                    severity: "unknown",
+                });
+            }
+        }
+        // Added / changed keys
+        for (const key of newKeys) {
+            const childPath = `${basePath}/${key}`;
+            if (!oldKeys.has(key)) {
+                out.push({
+                    path: childPath,
+                    description: "Field added",
+                    severity: "unknown",
+                });
+                continue;
+            }
+            const shouldRecurse = options.deepComparison !== false;
+            if (shouldRecurse) {
+                diffValues(oldVal[key], newVal[key], childPath, out, options);
+            }
+        }
+        return;
+    }
+    // Arrays
+    if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+        // Special handling for UniSpec collections identified by "name"
+        const _namedCollectionPaths = options.namedCollectionPaths || types_1.DEFAULT_NAMED_COLLECTION_PATHS;
+        const isNamedCollection = (options.namedCollectionPaths || [...types_1.DEFAULT_NAMED_COLLECTION_PATHS]).includes(basePath) || basePath.endsWith("/messages"); // Handle messages in channels
+        if (isNamedCollection) {
+            const oldByName = new Map();
+            const newByName = new Map();
+            for (const item of oldVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    oldByName.set(item.name, item);
+                }
+            }
+            for (const item of newVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    newByName.set(item.name, item);
+                }
+            }
+            // Removed
+            for (const [name, oldItem] of oldByName.entries()) {
+                if (!newByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item removed",
+                        severity: "unknown",
+                    });
+                }
+                else {
+                    const newItem = newByName.get(name);
+                    const shouldRecurse = options.deepComparison !== false;
+                    if (shouldRecurse) {
+                        diffValues(oldItem, newItem, `${basePath}/${name}`, out, options);
+                    }
+                }
+            }
+            // Added
+            for (const [name, _newItem] of newByName.entries()) {
+                if (!oldByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item added",
+                        severity: "unknown",
+                    });
+                }
+            }
+            return;
+        }
+        // Regular array comparison
+        const maxLength = Math.max(oldVal.length, newVal.length);
+        for (let i = 0; i < maxLength; i++) {
+            if (i >= oldVal.length) {
+                out.push({
+                    path: `${basePath}/${i}`,
+                    description: "Item added",
+                    severity: "unknown",
+                });
+            }
+            else if (i >= newVal.length) {
+                out.push({
+                    path: `${basePath}/${i}`,
+                    description: "Item removed",
+                    severity: "unknown",
+                });
+            }
+            else {
+                const shouldRecurse = options.deepComparison !== false;
+                if (shouldRecurse) {
+                    diffValues(oldVal[i], newVal[i], `${basePath}/${i}`, out, options);
+                }
+            }
+        }
+    }
+    // Primitive values or different types
+    out.push({
+        path: basePath,
+        description: "Value changed",
+        severity: "unknown",
+    });
+}
+/**
+ * Compare two UniSpec documents and return detected changes.
+ *
+ * This function performs a deep comparison between two UniSpec documents
+ * and categorizes changes by severity and protocol. Useful for:
+ * - API change detection in CI/CD pipelines
+ * - Breaking change analysis
+ * - Version compatibility checks
+ * - Audit trails for API evolution
+ *
+ * Features:
+ * - Detects added/removed fields at any depth
+ * - Special handling for named collections (routes, operations, channels)
+ * - Severity classification: "breaking" | "non-breaking" | "unknown"
+ * - Protocol categorization: "rest" | "graphql" | "websocket"
+ * - Detailed change descriptions with JSON paths
+ * - Configurable named collection paths and comparison depth
+ *
+ * @param oldDoc - The previous version of the UniSpec document
+ * @param newDoc - The current version of the UniSpec document
+ * @param options - Configuration options for diff behavior
+ * @returns Object containing all detected changes
+ */
+function diffUniSpec(oldDoc, newDoc, options = {}) {
+    const changes = [];
+    diffValues(oldDoc, newDoc, "", changes, options);
+    const annotated = changes.map((change) => (0, annotators_1.annotateWebSocketChange)((0, annotators_1.annotateGraphQLChange)((0, annotators_1.annotateRestChange)(change))));
+    return { changes: annotated };
+}

package/dist/cjs/src/diff/enhanced-diff.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffUniSpecEnhanced = diffUniSpecEnhanced;
+const core_1 = require("./core.js");
+const impact_strategies_refactored_1 = require("./impact-strategies-refactored.js");
+const metrics_calculator_1 = require("./metrics-calculator.js");
+const risk_calculator_1 = require("./risk-calculator.js");
+const suggestion_generator_1 = require("./suggestion-generator.js");
+/**
+ * Service instances for better separation of concerns.
+ */
+const suggestionGenerator = new suggestion_generator_1.SuggestionGeneratorService();
+const metricsCalculator = new metrics_calculator_1.MetricsCalculatorService();
+/**
+ * Perform enhanced diff analysis with impact assessment and compatibility metrics.
+ *
+ * This function extends the basic diff functionality with:
+ * - Detailed impact analysis for each change
+ * - Compatibility metrics
+ * - Migration suggestions
+ * - Risk assessment
+ *
+ * @param oldDoc - The previous version of the UniSpec document
+ * @param newDoc - The current version of the UniSpec document
+ * @returns Enhanced diff result with comprehensive analysis
+ */
+function diffUniSpecEnhanced(oldDoc, newDoc) {
+    // Get basic diff
+    const basicDiff = (0, core_1.diffUniSpec)(oldDoc, newDoc);
+    // Enhance each change with impact analysis using strategy pattern
+    const enhancedChanges = basicDiff.changes.map((change) => {
+        // Get appropriate strategy for the protocol
+        const strategy = impact_strategies_refactored_1.ImpactAnalysisStrategyFactory.getStrategy(change.protocol);
+        // Analyze impact using strategy
+        const impact = strategy.analyze(change);
+        // Generate suggestions
+        const suggestions = suggestionGenerator.generateSuggestions(change, impact);
+        // Calculate risk level using calculator
+        const riskLevel = risk_calculator_1.RiskLevelCalculator.calculate(impact);
+        return {
+            ...change,
+            impact,
+            suggestions,
+            riskLevel,
+        };
+    });
+    // Calculate metrics
+    const metrics = metricsCalculator.calculateMetrics(enhancedChanges);
+    // Generate summary
+    const summary = {
+        totalChanges: enhancedChanges.length,
+        criticalChanges: enhancedChanges.filter((c) => c.riskLevel === "critical")
+            .length,
+        highRiskChanges: enhancedChanges.filter((c) => c.riskLevel === "high")
+            .length,
+        mediumRiskChanges: enhancedChanges.filter((c) => c.riskLevel === "medium")
+            .length,
+        lowRiskChanges: enhancedChanges.filter((c) => c.riskLevel === "low").length,
+    };
+    return {
+        changes: enhancedChanges,
+        metrics,
+        summary,
+    };
+}

package/dist/cjs/src/diff/impact-strategies-refactored.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImpactAnalysisStrategyFactory = exports.DefaultImpactStrategy = exports.WebSocketImpactStrategy = exports.GraphQLOperationImpactStrategy = exports.RestRouteImpactStrategy = void 0;
+/**
+ * Base class for impact analysis strategies with common functionality.
+ */
+class BaseImpactStrategy {
+    createDefaultImpact() {
+        return {
+            backwardCompatibility: "unknown",
+            clientImpact: "none",
+            serverImpact: "none",
+            migrationComplexity: "none",
+        };
+    }
+    setBreakingChange(impact, clientImpact = "high", serverImpact = "medium", migrationComplexity = "moderate") {
+        impact.backwardCompatibility = "incompatible";
+        impact.clientImpact = clientImpact;
+        impact.serverImpact = serverImpact;
+        impact.migrationComplexity = migrationComplexity;
+        return impact;
+    }
+    setNonBreakingChange(impact, clientImpact = "none", serverImpact = "low", migrationComplexity = "none") {
+        impact.backwardCompatibility = "compatible";
+        impact.clientImpact = clientImpact;
+        impact.serverImpact = serverImpact;
+        impact.migrationComplexity = migrationComplexity;
+        return impact;
+    }
+}
+/**
+ * REST route impact analysis strategy.
+ */
+class RestRouteImpactStrategy extends BaseImpactStrategy {
+    analyze(change) {
+        const impact = this.createDefaultImpact();
+        // Route removal is always breaking
+        if (this.isRouteRemoval(change)) {
+            return this.setBreakingChange(impact, "high", "medium", "complex");
+        }
+        // Route addition is non-breaking
+        if (this.isRouteAddition(change)) {
+            return this.setNonBreakingChange(impact, "none", "low", "none");
+        }
+        // Method change is breaking
+        if (this.isMethodChange(change)) {
+            return this.setBreakingChange(impact, "high", "medium", "moderate");
+        }
+        // Path change is breaking
+        if (this.isPathChange(change)) {
+            return this.setBreakingChange(impact, "high", "medium", "moderate");
+        }
+        // Required parameter change is breaking
+        if (this.isRequiredParameterChange(change)) {
+            return this.setBreakingChange(impact, "medium", "low", "simple");
+        }
+        // Response status code removal is breaking
+        if (this.isResponseRemoval(change)) {
+            return this.setBreakingChange(impact, "medium", "low", "simple");
+        }
+        // Adding optional parameter is non-breaking
+        if (this.isOptionalParameterAddition(change)) {
+            return this.setNonBreakingChange(impact, "none", "low", "none");
+        }
+        return impact;
+    }
+    isRouteRemoval(change) {
+        return (change.description === "Item removed" &&
+            !!change.kind?.includes("route.removed"));
+    }
+    isRouteAddition(change) {
+        return (change.description === "Item added" &&
+            !!change.kind?.includes("route.added"));
+    }
+    isMethodChange(change) {
+        return (change.path.includes("/method") && change.description === "Value changed");
+    }
+    isPathChange(change) {
+        return (change.path.includes("/path") && change.description === "Value changed");
+    }
+    isRequiredParameterChange(change) {
+        return (change.path.includes("/required") &&
+            change.description === "Value changed");
+    }
+    isResponseRemoval(change) {
+        return (change.path.includes("/responses/") &&
+            change.description === "Item removed");
+    }
+    isOptionalParameterAddition(change) {
+        return (change.path.includes("/queryParams/") &&
+            change.description === "Item added");
+    }
+}
+exports.RestRouteImpactStrategy = RestRouteImpactStrategy;
+/**
+ * GraphQL operation impact analysis strategy.
+ */
+class GraphQLOperationImpactStrategy extends BaseImpactStrategy {
+    analyze(change) {
+        const impact = this.createDefaultImpact();
+        // Operation removal is breaking
+        if (this.isOperationRemoval(change)) {
+            return this.setBreakingChange(impact, "high", "medium", "complex");
+        }
+        // Operation addition is non-breaking
+        if (this.isOperationAddition(change)) {
+            return this.setNonBreakingChange(impact, "none", "low", "none");
+        }
+        // Return type change is breaking
+        if (this.isReturnTypeChange(change)) {
+            return this.setBreakingChange(impact, "high", "medium", "moderate");
+        }
+        // Adding optional argument is non-breaking
+        if (this.isOptionalArgumentAddition(change)) {
+            return this.setNonBreakingChange(impact, "none", "low", "none");
+        }
+        // Making argument required is breaking
+        if (this.isRequiredArgumentChange(change)) {
+            return this.setBreakingChange(impact, "medium", "low", "simple");
+        }
+        return impact;
+    }
+    isOperationRemoval(change) {
+        return (change.description === "Item removed" &&
+            !!change.kind?.includes("operation.removed"));
+    }
+    isOperationAddition(change) {
+        return (change.description === "Item added" &&
+            !!change.kind?.includes("operation.added"));
+    }
+    isReturnTypeChange(change) {
+        return (change.path.includes("/returnType") &&
+            change.description === "Value changed");
+    }
+    isOptionalArgumentAddition(change) {
+        return (change.path.includes("/args/") && change.description === "Item added");
+    }
+    isRequiredArgumentChange(change) {
+        return (change.path.includes("/args/") &&
+            change.path.includes("/required") &&
+            change.description === "Value changed");
+    }
+}
+exports.GraphQLOperationImpactStrategy = GraphQLOperationImpactStrategy;
+/**
+ * WebSocket impact analysis strategy.
+ */
+class WebSocketImpactStrategy extends BaseImpactStrategy {
+    analyze(change) {
+        const impact = this.createDefaultImpact();
+        // Channel removal is breaking
+        if (this.isChannelRemoval(change)) {
+            return this.setBreakingChange(impact, "high", "medium", "complex");
+        }
+        // Channel addition is non-breaking
+        if (this.isChannelAddition(change)) {
+            return this.setNonBreakingChange(impact, "none", "low", "none");
+        }
+        // Message removal is breaking
+        if (this.isMessageRemoval(change)) {
+            return this.setBreakingChange(impact, "medium", "low", "moderate");
+        }
+        // Message addition is non-breaking
+        if (this.isMessageAddition(change)) {
+            return this.setNonBreakingChange(impact, "none", "low", "none");
+        }
+        // Message schema change is breaking
+        if (this.isMessageSchemaChange(change)) {
+            return this.setBreakingChange(impact, "medium", "low", "moderate");
+        }
+        return impact;
+    }
+    isChannelRemoval(change) {
+        return (change.description === "Item removed" &&
+            !!change.kind?.includes("channel.removed"));
+    }
+    isChannelAddition(change) {
+        return (change.description === "Item added" &&
+            !!change.kind?.includes("channel.added"));
+    }
+    isMessageRemoval(change) {
+        return (change.description === "Item removed" &&
+            !!change.kind?.includes("message.removed"));
+    }
+    isMessageAddition(change) {
+        return (change.description === "Item added" &&
+            !!change.kind?.includes("message.added"));
+    }
+    isMessageSchemaChange(change) {
+        return (change.path.includes("/schemaRef") &&
+            change.description === "Value changed");
+    }
+}
+exports.WebSocketImpactStrategy = WebSocketImpactStrategy;
+/**
+ * Default impact analysis strategy for unknown changes.
+ */
+class DefaultImpactStrategy extends BaseImpactStrategy {
+    analyze(_change) {
+        return this.createDefaultImpact();
+    }
+}
+exports.DefaultImpactStrategy = DefaultImpactStrategy;
+/**
+ * Factory for creating impact analysis strategies.
+ */
+const ImpactAnalysisStrategyFactory = {
+    strategies: new Map([
+        ["rest", new RestRouteImpactStrategy()],
+        ["graphql", new GraphQLOperationImpactStrategy()],
+        ["websocket", new WebSocketImpactStrategy()],
+    ]),
+    getStrategy(protocol) {
+        if (!protocol) {
+            return new DefaultImpactStrategy();
+        }
+        const strategy = this.strategies.get(protocol);
+        return strategy || new DefaultImpactStrategy();
+    },
+    registerStrategy(protocol, strategy) {
+        this.strategies.set(protocol, strategy);
+    },
+    getAvailableStrategies() {
+        return Array.from(this.strategies.keys());
+    },
+    clearStrategies() {
+        this.strategies.clear();
+    },
+};
+exports.ImpactAnalysisStrategyFactory = ImpactAnalysisStrategyFactory;

package/dist/cjs/src/diff/impact-strategies.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImpactAnalysisStrategyFactory = exports.DefaultImpactStrategy = exports.WebSocketImpactStrategy = exports.GraphQLOperationImpactStrategy = exports.RestRouteImpactStrategy = void 0;
+/**
+ * REST route impact analysis strategy.
+ */
+class RestRouteImpactStrategy {
+    analyze(change) {
+        const impact = {
+            backwardCompatibility: "unknown",
+            clientImpact: "none",
+            serverImpact: "none",
+            migrationComplexity: "none",
+        };
+        // Route removal is always breaking
+        if (change.description === "Item removed" &&
+            change.kind?.includes("route.removed")) {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "high";
+            impact.serverImpact = "medium";
+            impact.migrationComplexity = "complex";
+        }
+        // Route addition is non-breaking
+        if (change.description === "Item added" &&
+            change.kind?.includes("route.added")) {
+            impact.backwardCompatibility = "compatible";
+            impact.clientImpact = "none";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "none";
+        }
+        // Method change is breaking
+        if (change.path.includes("/method") &&
+            change.description === "Value changed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "high";
+            impact.serverImpact = "medium";
+            impact.migrationComplexity = "moderate";
+        }
+        // Path change is breaking
+        if (change.path.includes("/path") &&
+            change.description === "Value changed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "high";
+            impact.serverImpact = "medium";
+            impact.migrationComplexity = "moderate";
+        }
+        // Required parameter change is breaking
+        if (change.path.includes("/required") &&
+            change.description === "Value changed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "medium";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "simple";
+        }
+        // Response status code removal is breaking
+        if (change.path.includes("/responses/") &&
+            change.description === "Item removed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "medium";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "simple";
+        }
+        // Adding optional parameter is non-breaking
+        if (change.path.includes("/queryParams/") &&
+            change.description === "Item added") {
+            impact.backwardCompatibility = "compatible";
+            impact.clientImpact = "none";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "none";
+        }
+        return impact;
+    }
+}
+exports.RestRouteImpactStrategy = RestRouteImpactStrategy;
+/**
+ * GraphQL operation impact analysis strategy.
+ */
+class GraphQLOperationImpactStrategy {
+    analyze(change) {
+        const impact = {
+            backwardCompatibility: "unknown",
+            clientImpact: "none",
+            serverImpact: "none",
+            migrationComplexity: "none",
+        };
+        // Operation removal is breaking
+        if (change.description === "Item removed" &&
+            change.kind?.includes("operation.removed")) {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "high";
+            impact.serverImpact = "medium";
+            impact.migrationComplexity = "complex";
+        }
+        // Operation addition is non-breaking
+        if (change.description === "Item added" &&
+            change.kind?.includes("operation.added")) {
+            impact.backwardCompatibility = "compatible";
+            impact.clientImpact = "none";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "none";
+        }
+        // Return type change is breaking
+        if (change.path.includes("/returnType") &&
+            change.description === "Value changed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "high";
+            impact.serverImpact = "medium";
+            impact.migrationComplexity = "moderate";
+        }
+        // Adding optional argument is non-breaking
+        if (change.path.includes("/args/") && change.description === "Item added") {
+            impact.backwardCompatibility = "compatible";
+            impact.clientImpact = "none";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "none";
+        }
+        // Making argument required is breaking
+        if (change.path.includes("/args/") &&
+            change.path.includes("/required") &&
+            change.description === "Value changed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "medium";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "simple";
+        }
+        return impact;
+    }
+}
+exports.GraphQLOperationImpactStrategy = GraphQLOperationImpactStrategy;
+/**
+ * WebSocket impact analysis strategy.
+ */
+class WebSocketImpactStrategy {
+    analyze(change) {
+        const impact = {
+            backwardCompatibility: "unknown",
+            clientImpact: "none",
+            serverImpact: "none",
+            migrationComplexity: "none",
+        };
+        // Channel removal is breaking
+        if (change.description === "Item removed" &&
+            change.kind?.includes("channel.removed")) {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "high";
+            impact.serverImpact = "medium";
+            impact.migrationComplexity = "complex";
+        }
+        // Channel addition is non-breaking
+        if (change.description === "Item added" &&
+            change.kind?.includes("channel.added")) {
+            impact.backwardCompatibility = "compatible";
+            impact.clientImpact = "none";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "none";
+        }
+        // Message removal is breaking
+        if (change.description === "Item removed" &&
+            change.kind?.includes("message.removed")) {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "medium";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "moderate";
+        }
+        // Message addition is non-breaking
+        if (change.description === "Item added" &&
+            change.kind?.includes("message.added")) {
+            impact.backwardCompatibility = "compatible";
+            impact.clientImpact = "none";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "none";
+        }
+        // Message schema change is breaking
+        if (change.path.includes("/schemaRef") &&
+            change.description === "Value changed") {
+            impact.backwardCompatibility = "incompatible";
+            impact.clientImpact = "medium";
+            impact.serverImpact = "low";
+            impact.migrationComplexity = "moderate";
+        }
+        return impact;
+    }
+}
+exports.WebSocketImpactStrategy = WebSocketImpactStrategy;
+/**
+ * Default impact analysis strategy for unknown changes.
+ */
+class DefaultImpactStrategy {
+    analyze(_change) {
+        return {
+            backwardCompatibility: "unknown",
+            clientImpact: "none",
+            serverImpact: "none",
+            migrationComplexity: "none",
+        };
+    }
+}
+exports.DefaultImpactStrategy = DefaultImpactStrategy;
+/**
+ * Factory for creating impact analysis strategies.
+ */
+const ImpactAnalysisStrategyFactory = {
+    strategies: new Map([
+        ["rest", new RestRouteImpactStrategy()],
+        ["graphql", new GraphQLOperationImpactStrategy()],
+        ["websocket", new WebSocketImpactStrategy()],
+    ]),
+    getStrategy(protocol) {
+        if (!protocol) {
+            return new DefaultImpactStrategy();
+        }
+        const strategy = this.strategies.get(protocol);
+        return strategy || new DefaultImpactStrategy();
+    },
+    registerStrategy(protocol, strategy) {
+        this.strategies.set(protocol, strategy);
+    },
+};
+exports.ImpactAnalysisStrategyFactory = ImpactAnalysisStrategyFactory;