@unispechq/unispec-core 0.3.2 → 0.3.3

package/dist/diff/core.js

@@ -1,155 +0,0 @@
-import { annotateGraphQLChange, annotateRestChange, annotateWebSocketChange, } from "./annotators.js";
-import { DEFAULT_NAMED_COLLECTION_PATHS, } from "./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 || DEFAULT_NAMED_COLLECTION_PATHS;
-        const isNamedCollection = (options.namedCollectionPaths || [...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
- */
-export function diffUniSpec(oldDoc, newDoc, options = {}) {
-    const changes = [];
-    diffValues(oldDoc, newDoc, "", changes, options);
-    const annotated = changes.map((change) => annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(change))));
-    return { changes: annotated };
-}

package/dist/diff/enhanced-diff.d.ts

@@ -1,51 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-import { type RiskLevel } from "./risk-calculator.js";
-import type { UniSpecChange } from "./types.js";
-export interface ChangeImpact {
-    backwardCompatibility: "compatible" | "incompatible" | "unknown";
-    clientImpact: "none" | "low" | "medium" | "high";
-    serverImpact: "none" | "low" | "medium" | "high";
-    migrationComplexity: "none" | "simple" | "moderate" | "complex";
-}
-export interface EnhancedUniSpecChange extends UniSpecChange {
-    impact: ChangeImpact;
-    suggestions: string[];
-    examples?: {
-        before: UniSpecDocument;
-        after: UniSpecDocument;
-    };
-    riskLevel: RiskLevel;
-}
-export interface CompatibilityMetrics {
-    overallCompatibility: number;
-    breakingChangesCount: number;
-    nonBreakingChangesCount: number;
-    clientCompatibilityScore: number;
-    serverCompatibilityScore: number;
-    migrationEffort: "minimal" | "moderate" | "significant" | "major";
-}
-export interface EnhancedDiffResult {
-    changes: EnhancedUniSpecChange[];
-    metrics: CompatibilityMetrics;
-    summary: {
-        totalChanges: number;
-        criticalChanges: number;
-        highRiskChanges: number;
-        mediumRiskChanges: number;
-        lowRiskChanges: number;
-    };
-}
-/**
- * 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
- */
-export declare function diffUniSpecEnhanced(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): EnhancedDiffResult;

package/dist/diff/enhanced-diff.js

@@ -1,76 +0,0 @@
-import { diffUniSpec } from "./core.js";
-import { ImpactAnalysisStrategyFactory } from "./impact-strategies-refactored.js";
-import { MetricsCalculatorService } from "./metrics-calculator.js";
-import { RiskLevelCalculator } from "./risk-calculator.js";
-import { SuggestionGeneratorService } from "./suggestion-generator.js";
-/**
- * Service instances for better separation of concerns.
- */
-const suggestionGenerator = new SuggestionGeneratorService();
-const metricsCalculator = new MetricsCalculatorService();
-/**
- * Generate migration suggestions based on change impact.
- * @deprecated Use SuggestionGeneratorService.generateSuggestions instead
- */
-function generateSuggestions(change, impact) {
-    return suggestionGenerator.generateSuggestions(change, impact);
-}
-/**
- * Calculate compatibility metrics from enhanced changes.
- * @deprecated Use MetricsCalculatorService.calculateMetrics instead
- */
-function calculateMetrics(changes) {
-    return metricsCalculator.calculateMetrics(changes);
-}
-/**
- * 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
- */
-export function diffUniSpecEnhanced(oldDoc, newDoc) {
-    // Get basic diff
-    const basicDiff = 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 = ImpactAnalysisStrategyFactory.getStrategy(change.protocol);
-        // Analyze impact using strategy
-        const impact = strategy.analyze(change);
-        // Generate suggestions
-        const suggestions = generateSuggestions(change, impact);
-        // Calculate risk level using calculator
-        const riskLevel = RiskLevelCalculator.calculate(impact);
-        return {
-            ...change,
-            impact,
-            suggestions,
-            riskLevel,
-        };
-    });
-    // Calculate metrics
-    const metrics = 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/diff/impact-strategies-refactored.d.ts

@@ -1,69 +0,0 @@
-import type { ChangeImpact } from "./enhanced-diff.js";
-import type { UniSpecChange } from "./types.js";
-/**
- * Strategy interface for analyzing change impact.
- */
-export interface ImpactAnalysisStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-}
-/**
- * Base class for impact analysis strategies with common functionality.
- */
-declare abstract class BaseImpactStrategy implements ImpactAnalysisStrategy {
-    protected createDefaultImpact(): ChangeImpact;
-    protected setBreakingChange(impact: ChangeImpact, clientImpact?: "low" | "medium" | "high", serverImpact?: "low" | "medium" | "high", migrationComplexity?: "simple" | "moderate" | "complex"): ChangeImpact;
-    protected setNonBreakingChange(impact: ChangeImpact, clientImpact?: "none" | "low" | "medium" | "high", serverImpact?: "none" | "low" | "medium" | "high", migrationComplexity?: "none" | "simple" | "moderate" | "complex"): ChangeImpact;
-    abstract analyze(change: UniSpecChange): ChangeImpact;
-}
-/**
- * REST route impact analysis strategy.
- */
-export declare class RestRouteImpactStrategy extends BaseImpactStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-    private isRouteRemoval;
-    private isRouteAddition;
-    private isMethodChange;
-    private isPathChange;
-    private isRequiredParameterChange;
-    private isResponseRemoval;
-    private isOptionalParameterAddition;
-}
-/**
- * GraphQL operation impact analysis strategy.
- */
-export declare class GraphQLOperationImpactStrategy extends BaseImpactStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-    private isOperationRemoval;
-    private isOperationAddition;
-    private isReturnTypeChange;
-    private isOptionalArgumentAddition;
-    private isRequiredArgumentChange;
-}
-/**
- * WebSocket impact analysis strategy.
- */
-export declare class WebSocketImpactStrategy extends BaseImpactStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-    private isChannelRemoval;
-    private isChannelAddition;
-    private isMessageRemoval;
-    private isMessageAddition;
-    private isMessageSchemaChange;
-}
-/**
- * Default impact analysis strategy for unknown changes.
- */
-export declare class DefaultImpactStrategy extends BaseImpactStrategy {
-    analyze(_change: UniSpecChange): ChangeImpact;
-}
-/**
- * Factory for creating impact analysis strategies.
- */
-declare const ImpactAnalysisStrategyFactory: {
-    strategies: Map<string, ImpactAnalysisStrategy>;
-    getStrategy(protocol?: string): ImpactAnalysisStrategy;
-    registerStrategy(protocol: string, strategy: ImpactAnalysisStrategy): void;
-    getAvailableStrategies(): string[];
-    clearStrategies(): void;
-};
-export { ImpactAnalysisStrategyFactory };

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

@@ -1,223 +0,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.
- */
-export 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");
-    }
-}
-/**
- * GraphQL operation impact analysis strategy.
- */
-export 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");
-    }
-}
-/**
- * WebSocket impact analysis strategy.
- */
-export 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");
-    }
-}
-/**
- * Default impact analysis strategy for unknown changes.
- */
-export class DefaultImpactStrategy extends BaseImpactStrategy {
-    analyze(_change) {
-        return this.createDefaultImpact();
-    }
-}
-/**
- * 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();
-    },
-};
-export { ImpactAnalysisStrategyFactory };

package/dist/diff/impact-strategies.d.ts

@@ -1,41 +0,0 @@
-import type { ChangeImpact } from "./enhanced-diff.js";
-import type { UniSpecChange } from "./types.js";
-/**
- * Strategy interface for analyzing change impact.
- */
-export interface ImpactAnalysisStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-}
-/**
- * REST route impact analysis strategy.
- */
-export declare class RestRouteImpactStrategy implements ImpactAnalysisStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-}
-/**
- * GraphQL operation impact analysis strategy.
- */
-export declare class GraphQLOperationImpactStrategy implements ImpactAnalysisStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-}
-/**
- * WebSocket impact analysis strategy.
- */
-export declare class WebSocketImpactStrategy implements ImpactAnalysisStrategy {
-    analyze(change: UniSpecChange): ChangeImpact;
-}
-/**
- * Default impact analysis strategy for unknown changes.
- */
-export declare class DefaultImpactStrategy implements ImpactAnalysisStrategy {
-    analyze(_change: UniSpecChange): ChangeImpact;
-}
-/**
- * Factory for creating impact analysis strategies.
- */
-declare const ImpactAnalysisStrategyFactory: {
-    strategies: Map<string, ImpactAnalysisStrategy>;
-    getStrategy(protocol?: string): ImpactAnalysisStrategy;
-    registerStrategy(protocol: string, strategy: ImpactAnalysisStrategy): void;
-};
-export { ImpactAnalysisStrategyFactory };