@kosdev-code/kos-ui-cli 2.0.44 → 2.0.45

package/src/lib/generators/api/lib/compare-api.mjs

@@ -0,0 +1,748 @@
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { getProjectDetails } from '../../../utils/nx-context.mjs';
+
+/**
+ * Compares two OpenAPI versions and generates a detailed compatibility report.
+ *
+ * Analyzes generated TypeScript type definitions (openapi.d.ts files) to detect
+ * breaking changes, new endpoints, and API modifications. Supports multiple output
+ * formats and can compare multiple app namespaces simultaneously.
+ *
+ * @param {Object} options - Comparison options
+ * @param {string} options.project - Project name containing generated API types
+ * @param {string} [options.app] - Single app namespace to compare (e.g., 'kos', 'dispense')
+ * @param {string[]} [options.apps] - Array of app namespaces for multi-app comparison
+ * @param {string} options.baseVersion - Base version identifier (e.g., 'v1.8.0')
+ * @param {string} options.targetVersion - Target version identifier (e.g., 'v1.9.0')
+ * @param {('console'|'json'|'markdown')} [options.format='console'] - Output format
+ * @param {string} [options.outputFile] - Optional file path to write output
+ * @returns {Promise<{compatible: boolean, results: Array}>} Comparison results with compatibility status
+ * @throws {Error} When project not found or required type files don't exist
+ *
+ * @example
+ * ```javascript
+ * // Basic comparison
+ * const result = await compareApiVersions({
+ *   project: 'device-models',
+ *   app: 'kos',
+ *   baseVersion: 'v1.8.0',
+ *   targetVersion: 'v1.9.0',
+ *   format: 'console'
+ * });
+ *
+ * if (!result.compatible) {
+ *   console.error('Breaking changes detected!');
+ *   process.exit(1);
+ * }
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Multi-app comparison with markdown output
+ * await compareApiVersions({
+ *   project: 'device-models',
+ *   apps: ['kos', 'dispense', 'freestyle'],
+ *   baseVersion: 'v1.8.0',
+ *   targetVersion: 'v1.9.0',
+ *   format: 'markdown',
+ *   outputFile: 'CHANGELOG-API.md'
+ * });
+ * ```
+ */
+export async function compareApiVersions(options) {
+  const {
+    project,
+    app,
+    apps, // Array for multi-app comparison
+    baseVersion,
+    targetVersion,
+    format = 'console',
+    outputFile,
+  } = options;
+
+  // Get project configuration (following generate-api.mjs pattern exactly)
+  let projectConfig, src, outputPath;
+
+  try {
+    projectConfig = await getProjectDetails(project);
+    src = projectConfig.sourceRoot || projectConfig.root;
+    outputPath = projectConfig.targets?.api?.options?.outputPath;
+  } catch (error) {
+    throw new Error(`Project "${project}" not found in workspace: ${error.message}`);
+  }
+
+  // Use custom output path if specified, otherwise default to src/utils
+  const utilsDir = outputPath ? join(src, outputPath) : join(src, "utils");
+  const servicesDir = join(utilsDir, "services");
+
+  // Determine which apps to compare
+  const appsToCompare = apps || [app];
+  const results = [];
+
+  // Compare each app
+  for (const appName of appsToCompare) {
+    const baseSpecPath = join(servicesDir, appName, baseVersion, 'openapi.d.ts');
+    const targetSpecPath = join(servicesDir, appName, targetVersion, 'openapi.d.ts');
+
+    // Validate files exist
+    if (!existsSync(baseSpecPath)) {
+      throw new Error(
+        `Base version not found: ${baseSpecPath}\n` +
+        `Generate it by running: kosui api:generate --project ${project}\n` +
+        `(Point to ${baseVersion} device first)`
+      );
+    }
+
+    if (!existsSync(targetSpecPath)) {
+      throw new Error(
+        `Target version not found: ${targetSpecPath}\n` +
+        `Generate it by running: kosui api:generate --project ${project}\n` +
+        `(Point to ${targetVersion} device first)`
+      );
+    }
+
+    // Load and parse specs
+    const baseContent = readFileSync(baseSpecPath, 'utf-8');
+    const targetContent = readFileSync(targetSpecPath, 'utf-8');
+
+    const basePaths = extractPaths(baseContent);
+    const targetPaths = extractPaths(targetContent);
+
+    // Perform comparison
+    const comparison = compareSpecs(basePaths, targetPaths, {
+      app: appName,
+      baseVersion,
+      targetVersion,
+    });
+
+    results.push(comparison);
+  }
+
+  // Format and output results
+  const formatted = formatResults(results, format);
+
+  if (outputFile) {
+    writeFileSync(outputFile, formatted, 'utf-8');
+  } else {
+    console.log(formatted);
+  }
+
+  // Return exit code based on compatibility
+  const hasBreakingChanges = results.some(r => !r.summary.compatible);
+  process.exitCode = hasBreakingChanges ? 1 : 0;
+
+  return {
+    compatible: !hasBreakingChanges,
+    results,
+  };
+}
+
+/**
+ * Extracts API paths and their HTTP methods from OpenAPI TypeScript type definitions.
+ *
+ * Parses the `export interface paths` section of a generated openapi.d.ts file
+ * to build a map of endpoint paths to their available HTTP methods and parameters.
+ *
+ * @param {string} content - Content of openapi.d.ts file
+ * @returns {Map<string, Map<string, Object>>} Map of paths to methods with parameter info
+ *
+ * @example
+ * ```javascript
+ * const content = readFileSync('openapi.d.ts', 'utf-8');
+ * const paths = extractPaths(content);
+ * // paths.get('/api/kos/device/status') → Map { 'get' => { params: {...} } }
+ * ```
+ */
+function extractPaths(content) {
+  const paths = new Map();
+  const pathsMatch = content.match(/export interface paths \{([\s\S]*?)\n\}/);
+
+  if (!pathsMatch) {
+    return paths;
+  }
+
+  const pathsContent = pathsMatch[1];
+  const lines = pathsContent.split('\n');
+  let currentPath = null;
+  let braceCount = 0;
+  let pathContent = '';
+
+  for (const line of lines) {
+    // Match path property (quoted string at start of line)
+    const pathMatch = line.match(/^\s*"([^"]+)":\s*\{/);
+
+    if (pathMatch && braceCount === 0) {
+      currentPath = pathMatch[1];
+      braceCount = 1;
+      pathContent = line;
+    } else if (currentPath) {
+      pathContent += '\n' + line;
+      braceCount += (line.match(/\{/g) || []).length;
+      braceCount -= (line.match(/\}/g) || []).length;
+
+      if (braceCount === 0) {
+        const methods = extractMethods(pathContent);
+        paths.set(currentPath, methods);
+        currentPath = null;
+        pathContent = '';
+      }
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Extracts HTTP methods and their parameters from a path definition string.
+ *
+ * Parses the TypeScript definition for a single path to identify available
+ * HTTP methods (GET, POST, PUT, DELETE, PATCH) and their query, path, and
+ * body parameters.
+ *
+ * @param {string} pathDef - TypeScript definition string for a single path
+ * @returns {Map<string, Object>} Map of method names to parameter definitions
+ *
+ * @example
+ * ```javascript
+ * const pathDef = `"/api/kos/device/status": {
+ *   get: { parameters: { query: { detailed?: boolean } } }
+ * }`;
+ * const methods = extractMethods(pathDef);
+ * // methods.get('get') → { params: { query: [...], path: [...], body: '...' } }
+ * ```
+ */
+function extractMethods(pathDef) {
+  const methods = new Map();
+  const methodNames = ['get', 'post', 'put', 'delete', 'patch'];
+
+  for (const methodName of methodNames) {
+    // Match method property (unquoted identifier with any indentation)
+    const methodRegex = new RegExp(`^\\s*${methodName}:\\s*\\{`, 'gm');
+    const match = methodRegex.exec(pathDef);
+
+    if (match) {
+      const startIdx = match.index;
+      let braceCount = 1;
+      let endIdx = startIdx + match[0].length;
+
+      for (let i = endIdx; i < pathDef.length; i++) {
+        if (pathDef[i] === '{') braceCount++;
+        if (pathDef[i] === '}') braceCount--;
+        if (braceCount === 0) {
+          endIdx = i + 1;
+          break;
+        }
+      }
+
+      const methodDef = pathDef.substring(startIdx, endIdx);
+
+      const params = {
+        query: extractParameters(methodDef, 'query'),
+        path: extractParameters(methodDef, 'path'),
+        body: extractRequestBody(methodDef)
+      };
+
+      methods.set(methodName, { params });
+    }
+  }
+
+  return methods;
+}
+
+/**
+ * Extracts parameters of a specific type from an HTTP method definition.
+ *
+ * Parses query or path parameters from the TypeScript definition, identifying
+ * parameter names and whether they are required or optional.
+ *
+ * @param {string} methodDef - TypeScript definition for an HTTP method
+ * @param {('query'|'path')} paramType - Type of parameters to extract
+ * @returns {Array<{name: string, required: boolean}>} Array of parameter definitions
+ *
+ * @example
+ * ```javascript
+ * const methodDef = `get: { parameters: { query: { id: string, optional?: string } } }`;
+ * const params = extractParameters(methodDef, 'query');
+ * // Returns: [{ name: 'id', required: true }, { name: 'optional', required: false }]
+ * ```
+ */
+function extractParameters(methodDef, paramType) {
+  const params = [];
+  const paramMatch = methodDef.match(new RegExp(`${paramType}[?]?:\\s*\\{([\\s\\S]*?)\\n\\s*\\}`, 'm'));
+
+  if (paramMatch) {
+    const paramContent = paramMatch[1];
+    const paramRegex = /(\w+)(\?)?:/g;
+    let match;
+
+    while ((match = paramRegex.exec(paramContent)) !== null) {
+      if (match[1] !== 'never' && match[1] !== 'header' && match[1] !== 'cookie') {
+        params.push({
+          name: match[1],
+          required: !match[2]
+        });
+      }
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Checks if an HTTP method definition includes a request body.
+ *
+ * Determines whether the endpoint expects a request body by checking for
+ * the presence of requestBody schema in the TypeScript definition.
+ *
+ * @param {string} methodDef - TypeScript definition for an HTTP method
+ * @returns {('present'|'none')} Whether a request body is expected
+ *
+ * @example
+ * ```javascript
+ * const methodDef = `post: { requestBody: { schema: {...} } }`;
+ * extractRequestBody(methodDef); // Returns: 'present'
+ * ```
+ */
+function extractRequestBody(methodDef) {
+  const bodyMatch = methodDef.match(/requestBody[:\?]\s*\{[\s\S]*?schema:/);
+  return bodyMatch ? 'present' : 'none';
+}
+
+/**
+ * Compares parameters between two API versions to detect changes.
+ *
+ * Identifies added, removed, and modified parameters, classifying changes
+ * as either breaking (removed params, new required params) or safe
+ * (new optional params, optional becoming required).
+ *
+ * @param {Array<{name: string, required: boolean}>} baseParams - Parameters from base version
+ * @param {Array<{name: string, required: boolean}>} targetParams - Parameters from target version
+ * @returns {Array<{type: string, param: string, severity: string}>} Array of parameter changes
+ *
+ * @example
+ * ```javascript
+ * const base = [{ name: 'id', required: true }];
+ * const target = [{ name: 'id', required: false }, { name: 'filter', required: true }];
+ * const changes = compareParameters(base, target);
+ * // Returns changes including:
+ * // - { type: 'changed', param: 'id', change: 'now optional', severity: 'safe' }
+ * // - { type: 'added', param: 'filter', required: true, severity: 'breaking' }
+ * ```
+ */
+function compareParameters(baseParams, targetParams) {
+  const changes = [];
+  const baseNames = new Set(baseParams.map(p => p.name));
+  const targetNames = new Set(targetParams.map(p => p.name));
+
+  // Removed parameters (breaking)
+  for (const param of baseParams) {
+    if (!targetNames.has(param.name)) {
+      changes.push({ type: 'removed', param: param.name, severity: 'breaking' });
+    }
+  }
+
+  // Added parameters
+  for (const param of targetParams) {
+    if (!baseNames.has(param.name)) {
+      const severity = param.required ? 'breaking' : 'safe';
+      changes.push({ type: 'added', param: param.name, required: param.required, severity });
+    }
+  }
+
+  // Changed required status
+  for (const baseParam of baseParams) {
+    const targetParam = targetParams.find(p => p.name === baseParam.name);
+    if (targetParam && baseParam.required !== targetParam.required) {
+      const severity = targetParam.required ? 'breaking' : 'safe';
+      changes.push({
+        type: 'changed',
+        param: baseParam.name,
+        change: targetParam.required ? 'now required' : 'now optional',
+        severity
+      });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Performs comprehensive comparison of two OpenAPI specifications.
+ *
+ * Analyzes paths, methods, and parameters to generate a detailed compatibility
+ * report including breaking changes, new endpoints, and modifications. The
+ * comparison identifies API evolution and determines backward compatibility.
+ *
+ * @param {Map<string, Map<string, Object>>} basePaths - Parsed paths from base version
+ * @param {Map<string, Map<string, Object>>} targetPaths - Parsed paths from target version
+ * @param {Object} metadata - Version metadata (app, baseVersion, targetVersion)
+ * @returns {Object} Comprehensive comparison results with summary and detailed changes
+ *
+ * @example
+ * ```javascript
+ * const basePaths = extractPaths(baseContent);
+ * const targetPaths = extractPaths(targetContent);
+ * const results = compareSpecs(basePaths, targetPaths, {
+ *   app: 'kos',
+ *   baseVersion: 'v1.8.0',
+ *   targetVersion: 'v1.9.0'
+ * });
+ *
+ * console.log(`Compatible: ${results.summary.compatible}`);
+ * console.log(`Breaking changes: ${results.summary.breakingChanges.length}`);
+ * ```
+ */
+function compareSpecs(basePaths, targetPaths, metadata) {
+  const results = {
+    metadata,
+    summary: {
+      totalPathsBase: basePaths.size,
+      totalPathsTarget: targetPaths.size,
+      addedPaths: [],
+      removedPaths: [],
+      modifiedPaths: [],
+      compatible: true,
+      breakingChanges: []
+    }
+  };
+
+  // Find added paths
+  for (const [path, methods] of targetPaths) {
+    if (!basePaths.has(path)) {
+      results.summary.addedPaths.push({
+        path,
+        methods: Array.from(methods.keys()).map(m => m.toUpperCase())
+      });
+    }
+  }
+
+  // Find removed paths (breaking)
+  for (const [path, methods] of basePaths) {
+    if (!targetPaths.has(path)) {
+      results.summary.removedPaths.push({
+        path,
+        methods: Array.from(methods.keys()).map(m => m.toUpperCase())
+      });
+      results.summary.compatible = false;
+      results.summary.breakingChanges.push({
+        path,
+        change: `${Array.from(methods.keys()).map(m => m.toUpperCase()).join(', ')} removed`
+      });
+    }
+  }
+
+  // Find modified paths
+  for (const [path, baseMethods] of basePaths) {
+    if (!targetPaths.has(path)) continue;
+
+    const targetMethods = targetPaths.get(path);
+    const changes = [];
+
+    // Check for removed methods (breaking)
+    for (const [method, baseMethodDef] of baseMethods) {
+      if (!targetMethods.has(method)) {
+        changes.push(`${method.toUpperCase()} method removed`);
+        results.summary.compatible = false;
+        results.summary.breakingChanges.push({
+          path,
+          change: `${method.toUpperCase()} method removed`
+        });
+      }
+    }
+
+    // Check for added methods (safe)
+    for (const [method] of targetMethods) {
+      if (!baseMethods.has(method)) {
+        changes.push(`Added ${method.toUpperCase()} method`);
+      }
+    }
+
+    // Check for parameter changes
+    for (const [method, baseMethodDef] of baseMethods) {
+      const targetMethodDef = targetMethods.get(method);
+      if (!targetMethodDef) continue;
+
+      // Query parameters
+      const queryChanges = compareParameters(baseMethodDef.params.query, targetMethodDef.params.query);
+      for (const change of queryChanges) {
+        const changeDesc = `${method.toUpperCase()} query parameter "${change.param}" ${change.type}${change.change ? ` (${change.change})` : ''}`;
+
+        if (change.severity === 'breaking') {
+          results.summary.compatible = false;
+          results.summary.breakingChanges.push({ path, change: changeDesc });
+        } else {
+          changes.push(changeDesc);
+        }
+      }
+
+      // Path parameters
+      const pathChanges = compareParameters(baseMethodDef.params.path, targetMethodDef.params.path);
+      for (const change of pathChanges) {
+        const changeDesc = `${method.toUpperCase()} path parameter "${change.param}" ${change.type}${change.change ? ` (${change.change})` : ''}`;
+
+        if (change.severity === 'breaking') {
+          results.summary.compatible = false;
+          results.summary.breakingChanges.push({ path, change: changeDesc });
+        } else {
+          changes.push(changeDesc);
+        }
+      }
+
+      // Request body changes
+      if (baseMethodDef.params.body !== targetMethodDef.params.body) {
+        const changeDesc = targetMethodDef.params.body === 'present' && baseMethodDef.params.body === 'none'
+          ? `${method.toUpperCase()} request body now required`
+          : `${method.toUpperCase()} request body changed`;
+
+        const severity = targetMethodDef.params.body === 'present' && baseMethodDef.params.body === 'none' ? 'breaking' : 'safe';
+
+        if (severity === 'breaking') {
+          results.summary.compatible = false;
+          results.summary.breakingChanges.push({ path, change: changeDesc });
+        } else {
+          changes.push(changeDesc);
+        }
+      }
+    }
+
+    if (changes.length > 0) {
+      results.summary.modifiedPaths.push({ path, changes });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Formats comparison results according to the specified output format.
+ *
+ * Delegates to format-specific functions to generate console, JSON, or
+ * markdown output suitable for different use cases (terminal display,
+ * automation, documentation).
+ *
+ * @param {Array<Object>} results - Array of comparison results (one per app)
+ * @param {('console'|'json'|'markdown')} format - Desired output format
+ * @returns {string} Formatted comparison output
+ *
+ * @example
+ * ```javascript
+ * const results = [{ metadata: {...}, summary: {...} }];
+ * const output = formatResults(results, 'markdown');
+ * writeFileSync('CHANGELOG.md', output);
+ * ```
+ */
+function formatResults(results, format) {
+  switch (format) {
+    case 'json':
+      return formatJson(results);
+    case 'markdown':
+      return formatMarkdown(results);
+    case 'console':
+    default:
+      return formatConsole(results);
+  }
+}
+
+/**
+ * Formats comparison results as JSON for machine-readable output.
+ *
+ * Generates a structured JSON representation suitable for automation,
+ * CI/CD pipelines, and programmatic analysis.
+ *
+ * @param {Array<Object>} results - Array of comparison results
+ * @returns {string} JSON-formatted comparison data
+ *
+ * @example
+ * ```javascript
+ * const json = formatJson(results);
+ * const parsed = JSON.parse(json);
+ * console.log(`Breaking changes: ${parsed[0].summary.breakingChanges.length}`);
+ * ```
+ */
+function formatJson(results) {
+  return JSON.stringify(results, null, 2);
+}
+
+/**
+ * Formats comparison results as Markdown for documentation and release notes.
+ *
+ * Generates well-structured markdown with sections for summary, breaking changes,
+ * new endpoints, removed endpoints, and modifications. Suitable for changelogs,
+ * release notes, and technical documentation.
+ *
+ * @param {Array<Object>} results - Array of comparison results
+ * @returns {string} Markdown-formatted comparison report
+ *
+ * @example
+ * ```javascript
+ * const markdown = formatMarkdown(results);
+ * writeFileSync('CHANGELOG-API.md', markdown);
+ * ```
+ */
+function formatMarkdown(results) {
+  let output = [];
+
+  for (const result of results) {
+    const { metadata, summary } = result;
+
+    output.push(`# API Changes: ${metadata.app} (${metadata.baseVersion} → ${metadata.targetVersion})\n`);
+
+    // Summary
+    output.push(`## Summary\n`);
+    output.push(`- Total endpoints: ${summary.totalPathsBase} → ${summary.totalPathsTarget}`);
+    output.push(`- Added: ${summary.addedPaths.length}`);
+    output.push(`- Removed: ${summary.removedPaths.length}`);
+    output.push(`- Modified: ${summary.modifiedPaths.length}`);
+    output.push(`- Breaking changes: ${summary.breakingChanges.length}`);
+    output.push(`- **Status**: ${summary.compatible ? '✅ Backward compatible' : '❌ Not backward compatible'}\n`);
+
+    // Breaking changes
+    if (summary.breakingChanges.length > 0) {
+      output.push(`## Breaking Changes\n`);
+      for (const change of summary.breakingChanges) {
+        output.push(`- \`${change.path}\` - ${change.change}`);
+      }
+      output.push('');
+    }
+
+    // New endpoints
+    if (summary.addedPaths.length > 0) {
+      output.push(`## New Endpoints\n`);
+      for (const { path, methods } of summary.addedPaths) {
+        output.push(`- \`${path}\` - ${methods.join(', ')}`);
+      }
+      output.push('');
+    }
+
+    // Removed endpoints
+    if (summary.removedPaths.length > 0) {
+      output.push(`## Removed Endpoints\n`);
+      for (const { path, methods } of summary.removedPaths) {
+        output.push(`- \`${path}\` - ${methods.join(', ')}`);
+      }
+      output.push('');
+    }
+
+    // Modified endpoints
+    if (summary.modifiedPaths.length > 0) {
+      output.push(`## Modified Endpoints (Non-Breaking)\n`);
+      for (const { path, changes } of summary.modifiedPaths) {
+        output.push(`- \`${path}\` - ${changes.join(', ')}`);
+      }
+      output.push('');
+    }
+  }
+
+  return output.join('\n');
+}
+
+/**
+ * Formats comparison results with colored terminal output for human readability.
+ *
+ * Generates visually appealing console output with color-coded sections,
+ * compatibility status, and actionable recommendations. Uses chalk for
+ * terminal color support.
+ *
+ * @param {Array<Object>} results - Array of comparison results
+ * @returns {string} Colored terminal output with ASCII decorations
+ *
+ * @example
+ * ```javascript
+ * const output = formatConsole(results);
+ * console.log(output); // Displays colored comparison in terminal
+ * ```
+ */
+function formatConsole(results) {
+  let output = [];
+
+  for (const result of results) {
+    const { metadata, summary } = result;
+
+    // Header
+    output.push(chalk.gray('═'.repeat(63)));
+    output.push(chalk.bold.cyan('API Compatibility Analysis\n'));
+    output.push(chalk.white(`App:            ${metadata.app}`));
+    output.push(chalk.white(`Base Version:   ${metadata.baseVersion}`));
+    output.push(chalk.white(`Target Version: ${metadata.targetVersion}`));
+    output.push(chalk.gray('═'.repeat(63)) + '\n');
+
+    // Compatibility status
+    if (summary.compatible) {
+      output.push(chalk.green.bold('BACKWARD COMPATIBLE\n'));
+    } else {
+      output.push(chalk.red.bold('BREAKING CHANGES DETECTED\n'));
+    }
+
+    output.push(chalk.gray('═'.repeat(63)) + '\n');
+
+    // Summary
+    output.push(chalk.bold('Summary\n'));
+    output.push(chalk.white(`Total Paths in Base:   ${summary.totalPathsBase}`));
+    output.push(chalk.white(`Total Paths in Target: ${summary.totalPathsTarget}`));
+    output.push(chalk.white(`Added Paths:           ${summary.addedPaths.length}`));
+    output.push(chalk.white(`Removed Paths:         ${summary.removedPaths.length}`));
+    output.push(chalk.white(`Modified Paths:        ${summary.modifiedPaths.length}`));
+    output.push(chalk.white(`Breaking Changes:      ${summary.breakingChanges.length}`));
+    output.push('');
+
+    // Breaking changes
+    if (summary.breakingChanges.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.red.bold('BREAKING CHANGES\n'));
+      for (const change of summary.breakingChanges) {
+        output.push(chalk.yellow(`${change.path}`) + chalk.white(` - ${change.change}`));
+      }
+      output.push('');
+    }
+
+    // New endpoints
+    if (summary.addedPaths.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.green.bold('NEW ENDPOINTS\n'));
+      for (const { path, methods } of summary.addedPaths) {
+        output.push(chalk.cyan(path) + chalk.white(` - ${methods.join(', ')}`));
+      }
+      output.push('');
+    }
+
+    // Removed endpoints
+    if (summary.removedPaths.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.red.bold('REMOVED ENDPOINTS\n'));
+      for (const { path, methods } of summary.removedPaths) {
+        output.push(chalk.red(path) + chalk.white(` - ${methods.join(', ')}`));
+      }
+      output.push('');
+    }
+
+    // Modified endpoints
+    if (summary.modifiedPaths.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.blue.bold('MODIFIED ENDPOINTS (Non-Breaking)\n'));
+      for (const { path, changes } of summary.modifiedPaths) {
+        output.push(chalk.cyan(path) + chalk.white(` - ${changes.join(', ')}`));
+      }
+      output.push('');
+    }
+
+    output.push(chalk.gray('═'.repeat(63)) + '\n');
+
+    // Recommendations
+    output.push(chalk.bold('Recommendations\n'));
+    if (!summary.compatible) {
+      output.push(chalk.yellow('Migration Required - Breaking changes detected'));
+      output.push(chalk.white('Review all breaking changes before upgrading'));
+    } else if (summary.addedPaths.length > 0) {
+      output.push(chalk.green('Safe to upgrade - No breaking changes'));
+      output.push(chalk.white('New endpoints available to use'));
+    } else {
+      output.push(chalk.green('Versions are identical or fully compatible'));
+    }
+
+    output.push('\n' + chalk.gray('═'.repeat(63)));
+  }
+
+  return output.join('\n');
+}