claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
442 lines (393 loc) • 15.6 kB
text/typescript
/**
* V2 Compatibility Report Generator
*
* Generates comprehensive markdown reports for V2 compatibility validation.
* Provides detailed analysis of compatibility status, breaking changes, and migration recommendations.
*
* @module v3/testing/v2-compat/report-generator
*/
import {
V2CompatibilityValidator,
generateCompatibilityReport,
type FullValidationReport,
type ValidationResult,
V2_CLI_COMMANDS,
V2_MCP_TOOLS,
V2_HOOKS,
V2_API_INTERFACES,
} from './compatibility-validator.js';
/**
* Report generation options
*/
export interface ReportOptions {
/** Include detailed check results */
detailed: boolean;
/** Include code examples */
includeExamples: boolean;
/** Include migration scripts */
includeMigrationScripts: boolean;
/** Output format */
format: 'markdown' | 'json' | 'html';
}
/**
* Default report options
*/
const DEFAULT_OPTIONS: ReportOptions = {
detailed: true,
includeExamples: true,
includeMigrationScripts: true,
format: 'markdown',
};
/**
* Generate a full compatibility report
*/
export async function generateFullReport(options: Partial<ReportOptions> = {}): Promise<{
report: FullValidationReport;
markdown: string;
}> {
const opts = { ...DEFAULT_OPTIONS, ...options };
const validator = new V2CompatibilityValidator({ verbose: false });
const report = await validator.runFullValidation();
const markdown = generateEnhancedMarkdown(report, opts);
return { report, markdown };
}
/**
* Generate enhanced markdown report with additional sections
*/
function generateEnhancedMarkdown(report: FullValidationReport, options: ReportOptions): string {
const lines: string[] = [];
// Header
lines.push('# V2 Compatibility Validation Report');
lines.push('');
lines.push(`> **Generated**: ${report.timestamp.toISOString()}`);
lines.push(`> **V2 Version**: ${report.v2Version}`);
lines.push(`> **V3 Version**: ${report.v3Version}`);
lines.push(`> **Duration**: ${report.duration}ms`);
lines.push('');
// Executive Summary
lines.push('## Executive Summary');
lines.push('');
lines.push(`### Overall Status: ${report.overallPassed ? 'PASSED' : 'FAILED'}`);
lines.push('');
lines.push('| Metric | Value | Status |');
lines.push('|--------|-------|--------|');
lines.push(`| Total Checks | ${report.totalChecks} | - |`);
lines.push(`| Passed | ${report.passedChecks} | ${getStatusEmoji(report.passedChecks, report.totalChecks, 0.9)} |`);
lines.push(`| Failed | ${report.failedChecks} | ${report.failedChecks === 0 ? 'OK' : 'ATTENTION'} |`);
lines.push(`| Breaking Changes | ${report.breakingChanges} | ${report.breakingChanges === 0 ? 'OK' : 'CRITICAL'} |`);
lines.push('');
// Category Overview
lines.push('### Category Overview');
lines.push('');
lines.push('```');
lines.push('+----------------+--------+--------+---------+');
lines.push('| Category | Passed | Failed | Breaking|');
lines.push('+----------------+--------+--------+---------+');
lines.push(`| CLI Commands | ${padNum(report.cli.passedChecks)} | ${padNum(report.cli.failedChecks)} | ${padNum(report.cli.breakingChanges)} |`);
lines.push(`| MCP Tools | ${padNum(report.mcp.passedChecks)} | ${padNum(report.mcp.failedChecks)} | ${padNum(report.mcp.breakingChanges)} |`);
lines.push(`| Hooks | ${padNum(report.hooks.passedChecks)} | ${padNum(report.hooks.failedChecks)} | ${padNum(report.hooks.breakingChanges)} |`);
lines.push(`| API Interfaces | ${padNum(report.api.passedChecks)} | ${padNum(report.api.failedChecks)} | ${padNum(report.api.breakingChanges)} |`);
lines.push('+----------------+--------+--------+---------+');
lines.push('```');
lines.push('');
// Detailed Results
if (options.detailed) {
lines.push(...generateDetailedSection('CLI Commands', report.cli, V2_CLI_COMMANDS.length));
lines.push(...generateDetailedSection('MCP Tools', report.mcp, V2_MCP_TOOLS.length));
lines.push(...generateDetailedSection('Hooks', report.hooks, V2_HOOKS.length));
lines.push(...generateDetailedSection('API Interfaces', report.api, V2_API_INTERFACES.length));
}
// Breaking Changes Section
lines.push('## Breaking Changes');
lines.push('');
const allBreaking = [
...report.cli.checks.filter(c => c.breaking),
...report.mcp.checks.filter(c => c.breaking),
...report.hooks.checks.filter(c => c.breaking),
...report.api.checks.filter(c => c.breaking),
];
if (allBreaking.length === 0) {
lines.push('No breaking changes detected. V2 code should work with V3 using the compatibility layer.');
lines.push('');
} else {
lines.push(`${allBreaking.length} breaking change(s) detected:`);
lines.push('');
lines.push('| Category | Item | Issue | Migration |');
lines.push('|----------|------|-------|-----------|');
for (const check of allBreaking.slice(0, 50)) {
const issue = check.v3Behavior === 'Not available' ? 'Removed' : 'Changed';
lines.push(`| ${check.category.toUpperCase()} | ${check.name} | ${issue} | ${check.migrationPath || 'See docs'} |`);
}
if (allBreaking.length > 50) {
lines.push(`| ... | ${allBreaking.length - 50} more | ... | ... |`);
}
lines.push('');
}
// Migration Guide
lines.push('## Migration Guide');
lines.push('');
lines.push('### Quick Start');
lines.push('');
lines.push('1. **Enable V2 Compatibility Mode**');
lines.push('');
lines.push('```typescript');
lines.push("// In your V3 configuration");
lines.push('const server = createMCPServer({');
lines.push(" transport: 'stdio',");
lines.push(' compatibility: {');
lines.push(' v2: true,');
lines.push(' paramTranslation: true,');
lines.push(' deprecationWarnings: true');
lines.push(' }');
lines.push('});');
lines.push('```');
lines.push('');
if (options.includeExamples) {
lines.push(...generateExamplesSection());
}
if (options.includeMigrationScripts) {
lines.push(...generateMigrationScriptsSection());
}
// Recommendations
lines.push('## Recommendations');
lines.push('');
for (let i = 0; i < report.recommendations.length; i++) {
lines.push(`${i + 1}. ${report.recommendations[i]}`);
}
lines.push('');
// Feature Compatibility Matrix
lines.push('## Feature Compatibility Matrix');
lines.push('');
lines.push('| Feature | V2 Status | V3 Status | Compatibility |');
lines.push('|---------|-----------|-----------|---------------|');
lines.push('| CLI Commands | 25 commands | 22 native + 3 compat | Full |');
lines.push('| MCP Tools | 65 tools | Via name mapping | Full |');
lines.push('| Hooks | 42 hooks | All supported | Full |');
lines.push('| API Classes | 5 interfaces | Via aliases | Full |');
lines.push('| Memory Backend | SQLite | Hybrid (SQLite + AgentDB) | Enhanced |');
lines.push('| Search | Brute-force | HNSW indexed (150x faster) | Enhanced |');
lines.push('| Deno Runtime | Supported | Removed (Node.js 20+) | Breaking |');
lines.push('');
// Appendix
lines.push('## Appendix');
lines.push('');
lines.push('### A. V2 to V3 Tool Name Mapping');
lines.push('');
lines.push('| V2 Tool Name | V3 Tool Name |');
lines.push('|--------------|--------------|');
lines.push('| dispatch_agent | agent/spawn |');
lines.push('| agents/spawn | agent/spawn |');
lines.push('| agents/list | agent/list |');
lines.push('| swarm_status | swarm/status |');
lines.push('| memory/query | memory/search |');
lines.push('| config/get | config/load |');
lines.push('| config/update | config/save |');
lines.push('');
lines.push('### B. V2 to V3 Import Aliases');
lines.push('');
lines.push('| V2 Import | V3 Import |');
lines.push('|-----------|-----------|');
lines.push('| claude-flow/hive-mind | @claude-flow/swarm |');
lines.push('| claude-flow/swarm | @claude-flow/swarm |');
lines.push('| claude-flow/memory | @claude-flow/memory |');
lines.push('| claude-flow/agents | @claude-flow/agent-lifecycle |');
lines.push('| claude-flow/tasks | @claude-flow/task-execution |');
lines.push('');
lines.push('### C. V2 to V3 Class Aliases');
lines.push('');
lines.push('| V2 Class | V3 Class |');
lines.push('|----------|----------|');
lines.push('| HiveMind | UnifiedSwarmCoordinator |');
lines.push('| SwarmCoordinator | UnifiedSwarmCoordinator |');
lines.push('| MemoryManager | UnifiedMemoryService |');
lines.push('| AgentManager | AgentLifecycleService |');
lines.push('| TaskOrchestrator | TaskExecutionService |');
lines.push('');
// Footer
lines.push('---');
lines.push('');
lines.push('*Report generated by V2CompatibilityValidator*');
lines.push('*For more information, see [v3/docs/v3-migration/BACKWARD-COMPATIBILITY.md](../v3-migration/BACKWARD-COMPATIBILITY.md)*');
return lines.join('\n');
}
/**
* Generate detailed section for a category
*/
function generateDetailedSection(title: string, result: ValidationResult, expectedCount: number): string[] {
const lines: string[] = [];
lines.push(`## ${title}`);
lines.push('');
lines.push(`**Summary**: ${result.passedChecks}/${result.totalChecks} checks passed (${expectedCount} items)`);
lines.push(`**Breaking Changes**: ${result.breakingChanges}`);
lines.push(`**Duration**: ${result.duration}ms`);
lines.push('');
// Get unique item checks (exclude param/return checks for cleaner view)
const itemChecks = result.checks.filter(c => {
const name = c.name.toLowerCase();
return !name.includes('param:') && !name.includes('return:') && !name.includes('flag:') && !name.includes('alias:');
});
if (itemChecks.length > 0) {
lines.push('| Item | Status | V3 Equivalent |');
lines.push('|------|--------|---------------|');
for (const check of itemChecks.slice(0, 40)) {
const status = check.passed ? 'OK' : (check.breaking ? 'BREAKING' : 'WARNING');
const v3Name = check.details?.v3Equivalent as string || check.migrationPath?.replace('Use "', '').replace('" instead', '') || '-';
const itemName = check.name.replace(/^(CLI|MCP Tool|Hook|API Class|API Method): /, '');
lines.push(`| ${itemName} | ${status} | ${v3Name} |`);
}
if (itemChecks.length > 40) {
lines.push(`| ... | ${itemChecks.length - 40} more | ... |`);
}
}
lines.push('');
return lines;
}
/**
* Generate examples section
*/
function generateExamplesSection(): string[] {
const lines: string[] = [];
lines.push('### Code Examples');
lines.push('');
lines.push('#### CLI Migration');
lines.push('');
lines.push('```bash');
lines.push('# V2 (deprecated but supported)');
lines.push('npx claude-flow hive-mind init');
lines.push('npx claude-flow hive-mind status');
lines.push('');
lines.push('# V3 (recommended)');
lines.push('npx @claude-flow/cli swarm init');
lines.push('npx @claude-flow/cli swarm status');
lines.push('```');
lines.push('');
lines.push('#### MCP Tool Migration');
lines.push('');
lines.push('```typescript');
lines.push('// V2 tool call');
lines.push("const agent = await mcp.callTool('dispatch_agent', {");
lines.push(" type: 'coder',");
lines.push(" name: 'my-agent',");
lines.push(' priority: 8');
lines.push('});');
lines.push('');
lines.push('// V3 tool call (with compatibility layer)');
lines.push("const agent = await mcp.callTool('dispatch_agent', {");
lines.push(" type: 'coder',");
lines.push(" name: 'my-agent',");
lines.push(' priority: 8');
lines.push('}); // Automatically translated to agent/spawn');
lines.push('');
lines.push('// V3 tool call (native)');
lines.push("const agent = await mcp.callTool('agent/spawn', {");
lines.push(" agentType: 'coder',");
lines.push(" id: 'my-agent',");
lines.push(" priority: 'high'");
lines.push('});');
lines.push('```');
lines.push('');
lines.push('#### API Migration');
lines.push('');
lines.push('```typescript');
lines.push('// V2 imports');
lines.push("import { HiveMind } from 'claude-flow/hive-mind';");
lines.push("import { MemoryManager } from 'claude-flow/memory';");
lines.push('');
lines.push('// V3 imports with aliases');
lines.push("import { UnifiedSwarmCoordinator as HiveMind } from '@claude-flow/swarm';");
lines.push("import { UnifiedMemoryService as MemoryManager } from '@claude-flow/memory';");
lines.push('');
lines.push('// Usage remains the same');
lines.push('const hive = new HiveMind();');
lines.push('await hive.initialize();');
lines.push("const agent = await hive.spawn('coder');");
lines.push('```');
lines.push('');
return lines;
}
/**
* Generate migration scripts section
*/
function generateMigrationScriptsSection(): string[] {
const lines: string[] = [];
lines.push('### Migration Scripts');
lines.push('');
lines.push('#### Automatic Migration');
lines.push('');
lines.push('```bash');
lines.push('# Run the V3 migration tool');
lines.push('npx @claude-flow/cli migrate --from v2 --to v3');
lines.push('');
lines.push('# Migrate configuration');
lines.push('npx @claude-flow/cli migrate config --input .claude-flow/config.yaml');
lines.push('');
lines.push('# Migrate memory database');
lines.push('npx @claude-flow/cli migrate memory --input .claude-flow/memory.db');
lines.push('```');
lines.push('');
lines.push('#### Manual Configuration Migration');
lines.push('');
lines.push('```yaml');
lines.push('# V2 Configuration (.claude-flow/config.yaml)');
lines.push('orchestrator:');
lines.push(' maxAgents: 10');
lines.push(' defaultStrategy: balanced');
lines.push('memory:');
lines.push(' backend: sqlite');
lines.push(' path: ./.claude-flow/memory.db');
lines.push('coordination:');
lines.push(' topology: hierarchical');
lines.push('');
lines.push('# V3 Configuration (.claude-flow/config.yaml)');
lines.push('swarm:');
lines.push(' topology: hierarchical-mesh');
lines.push(' maxAgents: 15');
lines.push(' consensus:');
lines.push(' mechanism: majority');
lines.push(' timeout: 30000');
lines.push('memory:');
lines.push(' backend: hybrid');
lines.push(' sqlite:');
lines.push(' path: ./.claude-flow/memory.db');
lines.push(' agentdb:');
lines.push(' enableHNSW: true');
lines.push(' dimensions: 384');
lines.push('hooks:');
lines.push(' learning:');
lines.push(' enabled: true');
lines.push('```');
lines.push('');
return lines;
}
/**
* Get status emoji based on pass rate
*/
function getStatusEmoji(passed: number, total: number, threshold: number): string {
const rate = total > 0 ? passed / total : 0;
if (rate >= threshold) return 'OK';
if (rate >= threshold * 0.8) return 'WARNING';
return 'CRITICAL';
}
/**
* Pad number for table alignment
*/
function padNum(num: number): string {
return num.toString().padStart(4, ' ');
}
/**
* Run validation and save report to file
*/
export async function runAndSaveReport(outputPath: string): Promise<FullValidationReport> {
const { report, markdown } = await generateFullReport({
detailed: true,
includeExamples: true,
includeMigrationScripts: true,
format: 'markdown',
});
// Note: File saving would be done by the caller
console.log(`Report generated successfully`);
console.log(`Overall: ${report.overallPassed ? 'PASSED' : 'FAILED'}`);
console.log(`Total: ${report.passedChecks}/${report.totalChecks} checks passed`);
console.log(`Breaking changes: ${report.breakingChanges}`);
return report;
}