@unispechq/unispec-core 0.3.2 → 0.3.3

package/dist/diff/annotators.js

@@ -1,154 +0,0 @@
-export 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;
-}
-export 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;
-}
-export 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/diff/change-reports.d.ts

@@ -1,37 +0,0 @@
-import type { EnhancedDiffResult, EnhancedUniSpecChange } from "./enhanced-diff.js";
-export interface ReportOptions {
-    format: "markdown" | "html" | "json";
-    includeSuggestions?: boolean;
-    includeExamples?: boolean;
-    groupByRisk?: boolean;
-    groupByProtocol?: boolean;
-    title?: string;
-    versionInfo?: {
-        oldVersion?: string;
-        newVersion?: string;
-        comparisonDate?: string;
-    };
-}
-export interface ChangeReport {
-    title: string;
-    summary: {
-        totalChanges: number;
-        breakingChanges: number;
-        compatibilityScore: number;
-        migrationEffort: string;
-    };
-    sections: ReportSection[];
-}
-export interface ReportSection {
-    title: string;
-    changes: EnhancedUniSpecChange[];
-    summary: string;
-}
-/**
- * Generate a comprehensive change report.
- *
- * @param diff - Enhanced diff result
- * @param options - Report generation options
- * @returns Formatted report in the specified format
- */
-export declare function generateChangeReport(diff: EnhancedDiffResult, options: ReportOptions): string;

package/dist/diff/change-reports.js

@@ -1,366 +0,0 @@
-/**
- * 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
- */
-export 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}`);
-    }
-}

package/dist/diff/core.d.ts

@@ -1,26 +0,0 @@
-import type { UniSpecDocument } from "../types/index.js";
-import { type DiffOptions, type DiffResult } from "./types.js";
-/**
- * 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 declare function diffUniSpec(oldDoc: UniSpecDocument, newDoc: UniSpecDocument, options?: DiffOptions): DiffResult;