@unispechq/unispec-core 0.3.0 → 0.3.2

package/dist/cjs/src/cache/lru-cache.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LRUCache = void 0;
+const constants_1 = require("./constants.js");
+/**
+ * Simple LRU (Least Recently Used) cache implementation.
+ */
+class LRUCache {
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.maxSize = options.maxSize || constants_1.CACHE_CONSTANTS.DEFAULT_MAX_SIZE;
+        this.ttl = options.ttl || constants_1.CACHE_CONSTANTS.DEFAULT_TTL;
+        this.enableStats = options.enableStats || false;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            size: 0,
+            hitRate: 0,
+            evictions: 0,
+        };
+    }
+    /**
+     * Get a value from the cache asynchronously.
+     */
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            if (this.enableStats) {
+                this.stats.misses++;
+                this.updateHitRate();
+            }
+            return undefined;
+        }
+        // Check TTL
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            if (this.enableStats) {
+                this.stats.misses++;
+                this.stats.size--;
+                this.updateHitRate();
+            }
+            return undefined;
+        }
+        // Update access info
+        entry.accessCount++;
+        entry.lastAccessed = Date.now();
+        // Move to end (most recently used)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        if (this.enableStats) {
+            this.stats.hits++;
+            this.updateHitRate();
+        }
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache asynchronously.
+     */
+    async set(key, value) {
+        // Remove existing entry if present
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        // Evict oldest entries if cache is full
+        while (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+                if (this.enableStats) {
+                    this.stats.evictions++;
+                    this.stats.size--;
+                }
+            }
+            else {
+                break;
+            }
+        }
+        const entry = {
+            value,
+            timestamp: Date.now(),
+            accessCount: 1,
+            lastAccessed: Date.now(),
+        };
+        this.cache.set(key, entry);
+        if (this.enableStats) {
+            this.stats.size++;
+        }
+    }
+    /**
+     * Delete a value from the cache.
+     */
+    delete(key) {
+        const deleted = this.cache.delete(key);
+        if (deleted && this.enableStats) {
+            this.stats.size--;
+        }
+        return deleted;
+    }
+    /**
+     * Clear all entries from the cache.
+     */
+    clear() {
+        this.cache.clear();
+        if (this.enableStats) {
+            this.stats.size = 0;
+        }
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Check if an entry is expired.
+     */
+    isExpired(entry) {
+        return Date.now() - entry.timestamp > this.ttl;
+    }
+    /**
+     * Update hit rate statistics.
+     */
+    updateHitRate() {
+        const total = this.stats.hits + this.stats.misses;
+        this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
+    }
+    /**
+     * Clean up expired entries.
+     */
+    cleanup() {
+        let cleaned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (this.isExpired(entry)) {
+                this.cache.delete(key);
+                cleaned++;
+                if (this.enableStats) {
+                    this.stats.size--;
+                }
+            }
+        }
+        return cleaned;
+    }
+}
+exports.LRUCache = LRUCache;

package/dist/cjs/src/cache/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Cache interfaces and types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.annotateRestChange = annotateRestChange;
+exports.annotateWebSocketChange = annotateWebSocketChange;
+exports.annotateGraphQLChange = annotateGraphQLChange;
+function annotateRestChange(change) {
+    // Add defensive check for null/undefined path
+    if (!change.path || typeof change.path !== "string") {
+        return change;
+    }
+    if (!change.path.startsWith("/service/protocols/rest/routes/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected shape: ["service", "protocols", "rest", "routes", routeName, ...]
+    if (segments[0] !== "service" ||
+        segments[1] !== "protocols" ||
+        segments[2] !== "rest" ||
+        segments[3] !== "routes") {
+        return change;
+    }
+    const routeName = segments[4];
+    if (typeof routeName === "undefined") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "rest",
+    };
+    if (change.description === "Item removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added") {
+        annotated.kind = "rest.route.added";
+        annotated.severity = "non-breaking";
+    }
+    else if (change.path.includes("/required") &&
+        change.description === "Value changed") {
+        // Changing required field from false to true is breaking
+        annotated.kind = "rest.parameter.required_changed";
+        annotated.severity = "breaking";
+    }
+    return annotated;
+}
+function annotateWebSocketChange(change) {
+    // Add defensive check for null/undefined path
+    if (!change.path || typeof change.path !== "string") {
+        return change;
+    }
+    if (!change.path.startsWith("/service/protocols/websocket/channels/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected base: ["service","protocols","websocket","channels", channelName, ...]
+    if (segments[0] !== "service" ||
+        segments[1] !== "protocols" ||
+        segments[2] !== "websocket" ||
+        segments[3] !== "channels") {
+        return change;
+    }
+    const channelName = segments[4];
+    const next = segments[5];
+    const annotated = {
+        ...change,
+        protocol: "websocket",
+    };
+    if (typeof channelName === "undefined") {
+        return annotated;
+    }
+    // Channel-level changes: /service/protocols/websocket/channels/{channelName}
+    if (!next) {
+        if (change.description === "Item removed") {
+            annotated.kind = "websocket.channel.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added") {
+            annotated.kind = "websocket.channel.added";
+            annotated.severity = "non-breaking";
+        }
+        return annotated;
+    }
+    // Message-level changes: /service/protocols/websocket/channels/{channelName}/messages/{messageName}
+    if (next === "messages") {
+        const messageName = segments[6];
+        if (typeof messageName === "undefined") {
+            return annotated;
+        }
+        if (change.description === "Item removed") {
+            annotated.kind = "websocket.message.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added") {
+            annotated.kind = "websocket.message.added";
+            annotated.severity = "non-breaking";
+        }
+    }
+    return annotated;
+}
+function annotateGraphQLChange(change) {
+    // Add defensive check for null/undefined path
+    if (!change.path || typeof change.path !== "string") {
+        return change;
+    }
+    if (!change.path.startsWith("/service/protocols/graphql/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected: ["service","protocols","graphql", operationType, operationName, ...]
+    if (segments[0] !== "service" ||
+        segments[1] !== "protocols" ||
+        segments[2] !== "graphql") {
+        return change;
+    }
+    const operationType = segments[3];
+    const operationName = segments[4];
+    if (!operationType || typeof operationName === "undefined") {
+        return change;
+    }
+    if (operationType !== "queries" &&
+        operationType !== "mutations" &&
+        operationType !== "subscriptions") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "graphql",
+    };
+    // Create operation-specific annotations
+    const singularMap = {
+        queries: "query",
+        mutations: "mutation",
+        subscriptions: "subscription",
+    };
+    const operationKind = `graphql.${singularMap[operationType]}`;
+    // Check for specific changes first, then general ones
+    if (change.path.includes("/returnType") &&
+        change.description === "Value changed") {
+        // Changing return type is breaking
+        annotated.kind = `${operationKind}.return_type_changed`;
+        annotated.severity = "breaking";
+    }
+    else if (change.path.includes("/args") &&
+        (change.description === "Item added" ||
+            change.description === "Item removed")) {
+        // Argument changes
+        const action = change.description === "Item added" ? "added" : "removed";
+        annotated.kind = `${operationKind}.argument_${action}`;
+        annotated.severity = action === "added" ? "non-breaking" : "breaking";
+    }
+    else if (change.description === "Item removed") {
+        annotated.kind = `${operationKind}.removed`;
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added") {
+        annotated.kind = `${operationKind}.added`;
+        annotated.severity = "non-breaking";
+    }
+    return annotated;
+}

package/dist/cjs/src/diff/change-reports.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateChangeReport = generateChangeReport;
+/**
+ * Generate a markdown report from enhanced diff result.
+ */
+function generateMarkdownReport(diff, options) {
+    const lines = [];
+    // Title and metadata
+    lines.push(`# ${options.title || "UniSpec Changes Report"}`);
+    lines.push("");
+    if (options.versionInfo) {
+        lines.push("## Version Information");
+        if (options.versionInfo.oldVersion) {
+            lines.push(`- **From:** ${options.versionInfo.oldVersion}`);
+        }
+        if (options.versionInfo.newVersion) {
+            lines.push(`- **To:** ${options.versionInfo.newVersion}`);
+        }
+        if (options.versionInfo.comparisonDate) {
+            lines.push(`- **Date:** ${options.versionInfo.comparisonDate}`);
+        }
+        lines.push("");
+    }
+    // Executive summary
+    lines.push("## Executive Summary");
+    lines.push("");
+    lines.push(`- **Total Changes:** ${diff.summary.totalChanges}`);
+    lines.push(`- **Critical Changes:** ${diff.summary.criticalChanges}`);
+    lines.push(`- **High Risk Changes:** ${diff.summary.highRiskChanges}`);
+    lines.push(`- **Compatibility Score:** ${diff.metrics.overallCompatibility}%`);
+    lines.push(`- **Migration Effort:** ${diff.metrics.migrationEffort}`);
+    lines.push("");
+    // Compatibility metrics
+    lines.push("## Compatibility Metrics");
+    lines.push("");
+    lines.push("| Metric | Score | Status |");
+    lines.push("|--------|-------|--------|");
+    const overallStatus = diff.metrics.overallCompatibility >= 80
+        ? "✅ Good"
+        : diff.metrics.overallCompatibility >= 60
+            ? "⚠️ Moderate"
+            : "❌ Poor";
+    lines.push(`| Overall Compatibility | ${diff.metrics.overallCompatibility}% | ${overallStatus} |`);
+    const clientStatus = diff.metrics.clientCompatibilityScore >= 80
+        ? "✅ Good"
+        : diff.metrics.clientCompatibilityScore >= 60
+            ? "⚠️ Moderate"
+            : "❌ Poor";
+    lines.push(`| Client Compatibility | ${diff.metrics.clientCompatibilityScore}% | ${clientStatus} |`);
+    const serverStatus = diff.metrics.serverCompatibilityScore >= 80
+        ? "✅ Good"
+        : diff.metrics.serverCompatibilityScore >= 60
+            ? "⚠️ Moderate"
+            : "❌ Poor";
+    lines.push(`| Server Compatibility | ${diff.metrics.serverCompatibilityScore}% | ${serverStatus} |`);
+    lines.push("");
+    // Group changes
+    const groupedChanges = groupChanges(diff.changes, options);
+    for (const section of groupedChanges) {
+        lines.push(`## ${section.title}`);
+        lines.push("");
+        lines.push(section.summary);
+        lines.push("");
+        if (section.changes.length === 0) {
+            lines.push("No changes in this category.");
+            lines.push("");
+            continue;
+        }
+        for (const change of section.changes) {
+            lines.push(`### ${getChangeIcon(change.riskLevel)} ${getChangeTitle(change)}`);
+            lines.push("");
+            lines.push(`- **Path:** \`${change.path}\``);
+            lines.push(`- **Protocol:** ${change.protocol || "Unknown"}`);
+            lines.push(`- **Risk Level:** ${change.riskLevel.toUpperCase()}`);
+            lines.push(`- **Impact:** ${formatImpact(change.impact)}`);
+            lines.push("");
+            if (change.description) {
+                lines.push(`**Description:** ${change.description}`);
+                lines.push("");
+            }
+            if (options.includeSuggestions && change.suggestions.length > 0) {
+                lines.push("**Migration Suggestions:**");
+                for (const suggestion of change.suggestions) {
+                    lines.push(`- ${suggestion}`);
+                }
+                lines.push("");
+            }
+        }
+    }
+    // Migration recommendations
+    if (diff.summary.criticalChanges > 0 || diff.summary.highRiskChanges > 0) {
+        lines.push("## Migration Recommendations");
+        lines.push("");
+        if (diff.summary.criticalChanges > 0) {
+            lines.push("⚠️ **Critical Changes Detected**");
+            lines.push("");
+            lines.push("Immediate action required:");
+            lines.push("- Review all critical changes");
+            lines.push("- Plan migration strategy");
+            lines.push("- Communicate changes to all stakeholders");
+            lines.push("- Consider feature flags for gradual rollout");
+            lines.push("");
+        }
+        if (diff.metrics.migrationEffort === "major") {
+            lines.push("🔧 **Major Migration Effort**");
+            lines.push("");
+            lines.push("Recommended approach:");
+            lines.push("- Break migration into phases");
+            lines.push("- Use parallel development");
+            lines.push("- Implement comprehensive testing");
+            lines.push("- Provide detailed migration guides");
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate an HTML report from enhanced diff result.
+ */
+function generateHtmlReport(diff, options) {
+    const styles = `
+    <style>
+      body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 40px; }
+      .header { border-bottom: 2px solid #e1e5e9; padding-bottom: 20px; margin-bottom: 30px; }
+      .metric { display: inline-block; margin: 10px 20px 10px 0; text-align: center; }
+      .metric-value { font-size: 2em; font-weight: bold; display: block; }
+      .metric-label { color: #666; font-size: 0.9em; }
+      .critical { color: #dc3545; }
+      .high { color: #fd7e14; }
+      .medium { color: #ffc107; }
+      .low { color: #28a745; }
+      .change { border: 1px solid #e1e5e9; border-radius: 8px; padding: 20px; margin: 20px 0; }
+      .change-header { font-weight: bold; margin-bottom: 10px; }
+      .suggestions { background: #f8f9fa; padding: 15px; border-radius: 5px; margin-top: 10px; }
+      .compatibility-bar { height: 20px; background: #e9ecef; border-radius: 10px; overflow: hidden; margin: 10px 0; }
+      .compatibility-fill { height: 100%; transition: width 0.3s ease; }
+    </style>
+  `;
+    const groupedChanges = groupChanges(diff.changes, options);
+    let html = `
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>${options.title || "UniSpec Changes Report"}</title>
+      ${styles}
+    </head>
+    <body>
+      <div class="header">
+        <h1>${options.title || "UniSpec Changes Report"}</h1>
+        <p>Generated on ${new Date().toLocaleDateString()}</p>
+      </div>
+      
+      <div class="summary">
+        <h2>Executive Summary</h2>
+        <div class="metric">
+          <span class="metric-value">${diff.summary.totalChanges}</span>
+          <span class="metric-label">Total Changes</span>
+        </div>
+        <div class="metric">
+          <span class="metric-value critical">${diff.summary.criticalChanges}</span>
+          <span class="metric-label">Critical</span>
+        </div>
+        <div class="metric">
+          <span class="metric-value high">${diff.summary.highRiskChanges}</span>
+          <span class="metric-label">High Risk</span>
+        </div>
+        <div class="metric">
+          <span class="metric-value">${diff.metrics.overallCompatibility}%</span>
+          <span class="metric-label">Compatibility</span>
+        </div>
+      </div>
+      
+      <div class="compatibility">
+        <h2>Compatibility Metrics</h2>
+        <div>
+          <strong>Overall Compatibility: ${diff.metrics.overallCompatibility}%</strong>
+          <div class="compatibility-bar">
+            <div class="compatibility-fill ${getCompatibilityClass(diff.metrics.overallCompatibility)}" 
+                 style="width: ${diff.metrics.overallCompatibility}%"></div>
+          </div>
+        </div>
+        <div>
+          <strong>Client Compatibility: ${diff.metrics.clientCompatibilityScore}%</strong>
+          <div class="compatibility-bar">
+            <div class="compatibility-fill ${getCompatibilityClass(diff.metrics.clientCompatibilityScore)}" 
+                 style="width: ${diff.metrics.clientCompatibilityScore}%"></div>
+          </div>
+        </div>
+        <div>
+          <strong>Server Compatibility: ${diff.metrics.serverCompatibilityScore}%</strong>
+          <div class="compatibility-bar">
+            <div class="compatibility-fill ${getCompatibilityClass(diff.metrics.serverCompatibilityScore)}" 
+                 style="width: ${diff.metrics.serverCompatibilityScore}%"></div>
+          </div>
+        </div>
+      </div>
+  `;
+    for (const section of groupedChanges) {
+        html += `
+      <div class="section">
+        <h2>${section.title}</h2>
+        <p>${section.summary}</p>
+    `;
+        for (const change of section.changes) {
+            html += `
+        <div class="change ${change.riskLevel}">
+          <div class="change-header">
+            ${getChangeIcon(change.riskLevel)} ${getChangeTitle(change)}
+          </div>
+          <p><strong>Path:</strong> <code>${change.path}</code></p>
+          <p><strong>Protocol:</strong> ${change.protocol || "Unknown"}</p>
+          <p><strong>Risk Level:</strong> <span class="${change.riskLevel}">${change.riskLevel.toUpperCase()}</span></p>
+          <p><strong>Description:</strong> ${change.description}</p>
+          <p><strong>Impact:</strong> ${formatImpact(change.impact)}</p>
+      `;
+            if (options.includeSuggestions && change.suggestions.length > 0) {
+                html += `
+          <div class="suggestions">
+            <strong>Migration Suggestions:</strong>
+            <ul>
+        `;
+                for (const suggestion of change.suggestions) {
+                    html += `<li>${suggestion}</li>`;
+                }
+                html += `
+            </ul>
+          </div>
+        `;
+            }
+            html += `
+        </div>
+      `;
+        }
+        html += `
+      </div>
+    `;
+    }
+    html += `
+    </body>
+    </html>
+  `;
+    return html;
+}
+/**
+ * Group changes by risk level or protocol.
+ */
+function groupChanges(changes, options) {
+    const sections = [];
+    if (options.groupByRisk) {
+        const riskGroups = {
+            critical: changes.filter((c) => c.riskLevel === "critical"),
+            high: changes.filter((c) => c.riskLevel === "high"),
+            medium: changes.filter((c) => c.riskLevel === "medium"),
+            low: changes.filter((c) => c.riskLevel === "low"),
+        };
+        for (const [risk, riskChanges] of Object.entries(riskGroups)) {
+            sections.push({
+                title: `${risk.charAt(0).toUpperCase() + risk.slice(1)} Risk Changes`,
+                changes: riskChanges,
+                summary: `${riskChanges.length} ${risk} risk changes that ${getRiskDescription(risk)}.`,
+            });
+        }
+    }
+    if (options.groupByProtocol) {
+        const protocolGroups = {
+            rest: changes.filter((c) => c.protocol === "rest"),
+            graphql: changes.filter((c) => c.protocol === "graphql"),
+            websocket: changes.filter((c) => c.protocol === "websocket"),
+            other: changes.filter((c) => !c.protocol || !["rest", "graphql", "websocket"].includes(c.protocol)),
+        };
+        for (const [protocol, protocolChanges] of Object.entries(protocolGroups)) {
+            if (protocolChanges.length > 0) {
+                sections.push({
+                    title: `${protocol.charAt(0).toUpperCase() + protocol.slice(1)} Protocol Changes`,
+                    changes: protocolChanges,
+                    summary: `${protocolChanges.length} changes affecting ${protocol} protocol.`,
+                });
+            }
+        }
+    }
+    // If no grouping, create a single section
+    if (sections.length === 0) {
+        sections.push({
+            title: "All Changes",
+            changes,
+            summary: `${changes.length} total changes detected.`,
+        });
+    }
+    return sections;
+}
+/**
+ * Helper functions for formatting.
+ */
+function getChangeIcon(riskLevel) {
+    switch (riskLevel) {
+        case "critical":
+            return "🚨";
+        case "high":
+            return "⚠️";
+        case "medium":
+            return "⚡";
+        case "low":
+            return "✅";
+        default:
+            return "📝";
+    }
+}
+function getChangeTitle(change) {
+    const parts = change.path.split("/").filter(Boolean);
+    const lastPart = parts[parts.length - 1];
+    if (change.kind) {
+        return `${change.kind.replace(/\./g, " ").toUpperCase()} - ${lastPart}`;
+    }
+    return `${change.description} - ${lastPart}`;
+}
+function formatImpact(impact) {
+    const parts = [];
+    if (impact.backwardCompatibility !== "unknown") {
+        parts.push(`Compatibility: ${impact.backwardCompatibility}`);
+    }
+    if (impact.clientImpact !== "none") {
+        parts.push(`Client: ${impact.clientImpact}`);
+    }
+    if (impact.serverImpact !== "none") {
+        parts.push(`Server: ${impact.serverImpact}`);
+    }
+    return parts.join(", ");
+}
+function getRiskDescription(risk) {
+    switch (risk) {
+        case "critical":
+            return "require immediate attention and breaking changes";
+        case "high":
+            return "involve breaking changes or significant impact";
+        case "medium":
+            return "require attention but are manageable";
+        case "low":
+            return "are minor and easily handled";
+        default:
+            return "have unknown impact";
+    }
+}
+function getCompatibilityClass(score) {
+    if (score >= 80)
+        return "low";
+    if (score >= 60)
+        return "medium";
+    return "high";
+}
+/**
+ * Generate a comprehensive change report.
+ *
+ * @param diff - Enhanced diff result
+ * @param options - Report generation options
+ * @returns Formatted report in the specified format
+ */
+function generateChangeReport(diff, options) {
+    switch (options.format) {
+        case "markdown":
+            return generateMarkdownReport(diff, options);
+        case "html":
+            return generateHtmlReport(diff, options);
+        case "json":
+            return JSON.stringify(diff, null, 2);
+        default:
+            throw new Error(`Unsupported format: ${options.format}`);
+    }
+}