@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/analyze-workflow.js

@@ -0,0 +1,1134 @@
+/**
+ * Bootspring Analyze Workflow Engine
+ *
+ * Deep codebase analysis for understanding architecture,
+ * dependencies, patterns, and code flows.
+ *
+ * @package bootspring
+ * @module core/analyze-workflow
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { StructureAnalyzer } = require('../analyzers/structure-analyzer');
+const { ArchitectureAnalyzer } = require('../analyzers/architecture-analyzer');
+const { DependencyAnalyzer } = require('../analyzers/dependency-analyzer');
+
+/**
+ * Workflow phase status
+ */
+const PHASE_STATUS = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped',
+  FAILED: 'failed'
+};
+
+/**
+ * Analysis phases
+ */
+const ANALYZE_PHASES = {
+  structure: {
+    name: 'Structure Mapping',
+    description: 'Parse files, build tree, detect monorepo',
+    order: 1,
+    required: true
+  },
+  architecture: {
+    name: 'Architecture Analysis',
+    description: 'Identify layers, modules, patterns (MVC, etc.)',
+    order: 2,
+    required: true,
+    dependencies: ['structure']
+  },
+  dependencies: {
+    name: 'Dependency Analysis',
+    description: 'Import graph, circular deps, unused deps',
+    order: 3,
+    required: true,
+    dependencies: ['structure']
+  },
+  patterns: {
+    name: 'Pattern Detection',
+    description: 'Design patterns, anti-patterns, code smells',
+    order: 4,
+    required: true,
+    dependencies: ['structure', 'architecture']
+  },
+  flows: {
+    name: 'Flow Tracing',
+    description: 'Entry points, request flows, data flows',
+    order: 5,
+    required: false,
+    dependencies: ['structure', 'dependencies']
+  },
+  components: {
+    name: 'Component Analysis',
+    description: 'Component signatures, prop drilling, coupling',
+    order: 6,
+    required: false,
+    dependencies: ['structure', 'architecture']
+  },
+  report: {
+    name: 'Report Generation',
+    description: 'Executive summary, Mermaid diagrams',
+    order: 7,
+    required: true,
+    dependencies: ['structure', 'architecture', 'dependencies', 'patterns']
+  }
+};
+
+/**
+ * Analysis depth levels
+ */
+const ANALYSIS_DEPTH = {
+  shallow: {
+    phases: ['structure', 'architecture', 'report'],
+    description: 'Quick scan for basic understanding'
+  },
+  standard: {
+    phases: ['structure', 'architecture', 'dependencies', 'patterns', 'report'],
+    description: 'Standard analysis with patterns'
+  },
+  deep: {
+    phases: ['structure', 'architecture', 'dependencies', 'patterns', 'flows', 'components', 'report'],
+    description: 'Comprehensive analysis with flows'
+  }
+};
+
+/**
+ * Default workflow state
+ */
+const DEFAULT_STATE = {
+  version: '1.0.0',
+  startedAt: null,
+  lastUpdated: null,
+  currentPhase: null,
+  depth: 'standard',
+  phases: {},
+  results: {},
+  summary: null
+};
+
+/**
+ * AnalyzeWorkflowEngine - Manages analysis workflow
+ */
+class AnalyzeWorkflowEngine {
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.workflowDir = path.join(projectRoot, '.bootspring', 'analyze');
+    this.stateFile = path.join(this.workflowDir, 'workflow-state.json');
+    this.reportsDir = path.join(this.workflowDir, 'reports');
+    this.artifactsDir = path.join(this.workflowDir, 'artifacts');
+    this.options = {
+      depth: options.depth || 'standard',
+      include: options.include || null,
+      exclude: options.exclude || null,
+      ...options
+    };
+    this.state = null;
+  }
+
+  /**
+   * Setup directories
+   */
+  setupDirectories() {
+    const dirs = [this.workflowDir, this.reportsDir, this.artifactsDir];
+
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * Load workflow state
+   */
+  loadState() {
+    if (fs.existsSync(this.stateFile)) {
+      try {
+        this.state = JSON.parse(fs.readFileSync(this.stateFile, 'utf-8'));
+        return true;
+      } catch (_e) {
+        this.state = { ...DEFAULT_STATE };
+        return false;
+      }
+    }
+    this.state = { ...DEFAULT_STATE };
+    return false;
+  }
+
+  /**
+   * Save workflow state
+   */
+  saveState() {
+    this.setupDirectories();
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  /**
+   * Initialize workflow
+   */
+  initializeWorkflow(depth = 'standard') {
+    this.setupDirectories();
+    this.state = {
+      ...DEFAULT_STATE,
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+      depth
+    };
+
+    // Get phases for this depth
+    const activePhases = ANALYSIS_DEPTH[depth]?.phases || ANALYSIS_DEPTH.standard.phases;
+
+    // Initialize phase states
+    for (const phaseId of Object.keys(ANALYZE_PHASES)) {
+      this.state.phases[phaseId] = {
+        status: activePhases.includes(phaseId) ? PHASE_STATUS.PENDING : PHASE_STATUS.SKIPPED,
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+    }
+
+    this.state.currentPhase = 'structure';
+    this.saveState();
+    return this.state;
+  }
+
+  /**
+   * Check if workflow exists
+   */
+  hasWorkflow() {
+    return fs.existsSync(this.stateFile);
+  }
+
+  /**
+   * Reset workflow
+   */
+  resetWorkflow() {
+    if (fs.existsSync(this.stateFile)) {
+      fs.unlinkSync(this.stateFile);
+    }
+    this.state = null;
+    return true;
+  }
+
+  /**
+   * Check if phase dependencies are met
+   */
+  arePhaseDependenciesMet(phaseId) {
+    const phase = ANALYZE_PHASES[phaseId];
+    if (!phase || !phase.dependencies || phase.dependencies.length === 0) {
+      return true;
+    }
+
+    for (const depPhaseId of phase.dependencies) {
+      const depPhase = this.state.phases[depPhaseId];
+      if (!depPhase || (depPhase.status !== PHASE_STATUS.COMPLETED && depPhase.status !== PHASE_STATUS.SKIPPED)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get next phase
+   */
+  getNextPhase() {
+    const phaseOrder = Object.keys(ANALYZE_PHASES).sort(
+      (a, b) => ANALYZE_PHASES[a].order - ANALYZE_PHASES[b].order
+    );
+
+    for (const phaseId of phaseOrder) {
+      const phase = this.state.phases[phaseId];
+      if (phase.status === PHASE_STATUS.PENDING && this.arePhaseDependenciesMet(phaseId)) {
+        return phaseId;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Start a phase
+   */
+  startPhase(phaseId) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.IN_PROGRESS;
+    this.state.phases[phaseId].startedAt = new Date().toISOString();
+    this.state.currentPhase = phaseId;
+    this.saveState();
+  }
+
+  /**
+   * Complete a phase
+   */
+  completePhase(phaseId, result = null) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.COMPLETED;
+    this.state.phases[phaseId].completedAt = new Date().toISOString();
+    this.state.phases[phaseId].result = result;
+    this.state.results[phaseId] = result;
+    this.saveState();
+  }
+
+  /**
+   * Fail a phase
+   */
+  failPhase(phaseId, error) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.FAILED;
+    this.state.phases[phaseId].completedAt = new Date().toISOString();
+    this.state.phases[phaseId].error = error;
+    this.saveState();
+  }
+
+  /**
+   * Run structure mapping phase
+   */
+  async runStructureMapping() {
+    const analyzer = new StructureAnalyzer(this.projectRoot, {
+      includeHidden: false
+    });
+
+    const result = analyzer.analyze();
+
+    // Save artifact
+    fs.writeFileSync(
+      path.join(this.artifactsDir, 'structure.json'),
+      JSON.stringify(result, null, 2)
+    );
+
+    return {
+      totalFiles: result.stats.totalFiles,
+      totalDirs: result.stats.totalDirs,
+      structureType: result.structureType,
+      entryPoints: result.entryPoints.length,
+      keyDirectories: Object.keys(result.keyDirectories).filter(k => result.keyDirectories[k])
+    };
+  }
+
+  /**
+   * Run architecture analysis phase
+   */
+  async runArchitectureAnalysis() {
+    const analyzer = new ArchitectureAnalyzer(this.projectRoot);
+    const result = analyzer.analyze();
+
+    // Save artifact
+    fs.writeFileSync(
+      path.join(this.artifactsDir, 'architecture.json'),
+      JSON.stringify(result, null, 2)
+    );
+
+    // Save architecture report
+    const report = this.generateArchitectureReport(result);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'architecture.md'),
+      report
+    );
+
+    return {
+      patterns: result.patterns.slice(0, 3),
+      layers: Object.keys(result.layers),
+      modules: result.modules.length,
+      hasComponentSystem: result.componentStructure.hasComponentDir
+    };
+  }
+
+  /**
+   * Generate architecture report
+   */
+  generateArchitectureReport(analysis) {
+    const lines = [
+      '# Architecture Analysis',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Detected Patterns',
+      ''
+    ];
+
+    for (const pattern of analysis.patterns) {
+      lines.push(`### ${pattern.name} (${pattern.confidence}% confidence)`);
+      lines.push(`${pattern.description}`);
+      lines.push(`Indicators: ${pattern.matchedIndicators.join(', ')}`);
+      lines.push('');
+    }
+
+    lines.push('## Layer Structure');
+    lines.push('');
+
+    for (const [layer, dirs] of Object.entries(analysis.layers)) {
+      if (dirs.length > 0) {
+        lines.push(`### ${layer.charAt(0).toUpperCase() + layer.slice(1)}`);
+        for (const dir of dirs) {
+          lines.push(`- \`${dir.path}\`: ${dir.purpose}`);
+        }
+        lines.push('');
+      }
+    }
+
+    if (analysis.modules.length > 0) {
+      lines.push('## Modules/Features');
+      lines.push('');
+      for (const mod of analysis.modules) {
+        lines.push(`- **${mod.name}** (\`${mod.path}\`): ${mod.type}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('## Architecture Diagram');
+    lines.push('');
+    lines.push(analysis.diagram);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run dependency analysis phase
+   */
+  async runDependencyAnalysis() {
+    // Auto-detect large codebase and skip heavy analysis
+    const LARGE_CODEBASE_THRESHOLD = 500;
+    const structurePath = path.join(this.artifactsDir, 'structure.json');
+    let fileCount = 0;
+
+    if (fs.existsSync(structurePath)) {
+      try {
+        const structure = JSON.parse(fs.readFileSync(structurePath, 'utf-8'));
+        fileCount = structure.stats?.totalFiles || 0;
+      } catch (_e) {
+        // Ignore
+      }
+    }
+
+    // For large codebases, return lightweight results
+    if (fileCount >= LARGE_CODEBASE_THRESHOLD) {
+      const lightResult = {
+        fileCount: fileCount,
+        circularDependencies: [],
+        unusedDependencies: [],
+        packageUsage: [],
+        mostImported: [],
+        skipped: true,
+        reason: `Large codebase (${fileCount} files) - dependency analysis skipped for performance`
+      };
+
+      // Save artifact with note
+      fs.writeFileSync(
+        path.join(this.artifactsDir, 'dependencies.json'),
+        JSON.stringify(lightResult, null, 2)
+      );
+
+      // Save lightweight report
+      const report = [
+        '# Dependency Analysis',
+        '',
+        `> Skipped: Large codebase (${fileCount} files)`,
+        '',
+        'Dependency analysis was skipped for performance.',
+        'Run `bootspring analyze --depth=deep` to force full analysis.',
+        ''
+      ].join('\n');
+
+      fs.writeFileSync(
+        path.join(this.reportsDir, 'dependencies.md'),
+        report
+      );
+
+      return {
+        fileCount: fileCount,
+        circularCount: 0,
+        unusedCount: 0,
+        externalPackages: 0,
+        mostImported: [],
+        skipped: true
+      };
+    }
+
+    const analyzer = new DependencyAnalyzer(this.projectRoot);
+    const result = analyzer.analyze();
+
+    // Save artifact
+    fs.writeFileSync(
+      path.join(this.artifactsDir, 'dependencies.json'),
+      JSON.stringify(result, null, 2)
+    );
+
+    // Save dependency report
+    const report = this.generateDependencyReport(result);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'dependencies.md'),
+      report
+    );
+
+    return {
+      fileCount: result.fileCount,
+      circularCount: result.circularDependencies.length,
+      unusedCount: result.unusedDependencies.length,
+      externalPackages: result.packageUsage.length,
+      mostImported: result.mostImported.slice(0, 5)
+    };
+  }
+
+  /**
+   * Generate dependency report
+   */
+  generateDependencyReport(analysis) {
+    const lines = [
+      '# Dependency Analysis',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Summary',
+      '',
+      `- **Total Files Analyzed**: ${analysis.fileCount}`,
+      `- **Circular Dependencies**: ${analysis.circularDependencies.length}`,
+      `- **Unused Dependencies**: ${analysis.unusedDependencies.length}`,
+      `- **External Packages**: ${analysis.packageUsage.length}`,
+      ''
+    ];
+
+    if (analysis.circularDependencies.length > 0) {
+      lines.push('## Circular Dependencies');
+      lines.push('');
+      lines.push('> These should be resolved to improve maintainability.');
+      lines.push('');
+      for (let i = 0; i < Math.min(analysis.circularDependencies.length, 5); i++) {
+        const cycle = analysis.circularDependencies[i];
+        lines.push(`${i + 1}. ${cycle.join(' → ')}`);
+      }
+      lines.push('');
+    }
+
+    if (analysis.unusedDependencies.length > 0) {
+      lines.push('## Potentially Unused Dependencies');
+      lines.push('');
+      lines.push('> Consider removing these to reduce bundle size.');
+      lines.push('');
+      for (const dep of analysis.unusedDependencies) {
+        lines.push(`- \`${dep.name}\` (${dep.type})`);
+      }
+      lines.push('');
+    }
+
+    lines.push('## Most Imported Files');
+    lines.push('');
+    lines.push('| File | Import Count |');
+    lines.push('|------|--------------|');
+    for (const file of analysis.mostImported.slice(0, 10)) {
+      lines.push(`| \`${file.file}\` | ${file.importCount} |`);
+    }
+    lines.push('');
+
+    lines.push('## Package Usage');
+    lines.push('');
+    lines.push('| Package | Usage Count |');
+    lines.push('|---------|-------------|');
+    for (const pkg of analysis.packageUsage.slice(0, 15)) {
+      lines.push(`| \`${pkg.package}\` | ${pkg.count} |`);
+    }
+    lines.push('');
+
+    lines.push('## Dependency Graph');
+    lines.push('');
+    lines.push(analysis.diagram);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run pattern detection phase
+   */
+  async runPatternDetection() {
+    // Load previous results
+    const architectureArtifact = path.join(this.artifactsDir, 'architecture.json');
+    const dependencyArtifact = path.join(this.artifactsDir, 'dependencies.json');
+
+    const patterns = {
+      designPatterns: [],
+      antiPatterns: [],
+      codeSmells: []
+    };
+
+    if (fs.existsSync(architectureArtifact)) {
+      const architecture = JSON.parse(fs.readFileSync(architectureArtifact, 'utf-8'));
+      patterns.designPatterns = architecture.patterns || [];
+    }
+
+    if (fs.existsSync(dependencyArtifact)) {
+      const dependencies = JSON.parse(fs.readFileSync(dependencyArtifact, 'utf-8'));
+
+      // Detect anti-patterns from dependencies
+      if (dependencies.circularDependencies?.length > 0) {
+        patterns.antiPatterns.push({
+          id: 'circular-deps',
+          name: 'Circular Dependencies',
+          severity: 'medium',
+          count: dependencies.circularDependencies.length,
+          description: 'Files that depend on each other in a cycle'
+        });
+      }
+
+      // High coupling detection
+      const highCoupling = dependencies.mostImported?.filter(f => f.importCount > 20);
+      if (highCoupling?.length > 0) {
+        patterns.antiPatterns.push({
+          id: 'high-coupling',
+          name: 'High Coupling',
+          severity: 'low',
+          count: highCoupling.length,
+          description: 'Files with many dependents (potential god objects)'
+        });
+      }
+    }
+
+    // Save artifact
+    fs.writeFileSync(
+      path.join(this.artifactsDir, 'patterns.json'),
+      JSON.stringify(patterns, null, 2)
+    );
+
+    // Save patterns report
+    const report = this.generatePatternsReport(patterns);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'patterns.md'),
+      report
+    );
+
+    return {
+      designPatterns: patterns.designPatterns.length,
+      antiPatterns: patterns.antiPatterns.length,
+      codeSmells: patterns.codeSmells.length
+    };
+  }
+
+  /**
+   * Generate patterns report
+   */
+  generatePatternsReport(patterns) {
+    const lines = [
+      '# Pattern Analysis',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      ''
+    ];
+
+    if (patterns.designPatterns.length > 0) {
+      lines.push('## Design Patterns');
+      lines.push('');
+      for (const pattern of patterns.designPatterns) {
+        lines.push(`### ${pattern.name}`);
+        lines.push(`**Confidence**: ${pattern.confidence}%`);
+        lines.push(`${pattern.description || ''}`);
+        lines.push('');
+      }
+    }
+
+    if (patterns.antiPatterns.length > 0) {
+      lines.push('## Anti-Patterns Detected');
+      lines.push('');
+      for (const pattern of patterns.antiPatterns) {
+        lines.push(`### ${pattern.name}`);
+        lines.push(`**Severity**: ${pattern.severity}`);
+        lines.push(`**Count**: ${pattern.count}`);
+        lines.push(`${pattern.description || ''}`);
+        lines.push('');
+      }
+    }
+
+    if (patterns.designPatterns.length === 0 && patterns.antiPatterns.length === 0) {
+      lines.push('No significant patterns detected.');
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run flow tracing phase
+   */
+  async runFlowTracing() {
+    // Load structure artifact
+    const structureArtifact = path.join(this.artifactsDir, 'structure.json');
+
+    const flows = {
+      entryPoints: [],
+      apiEndpoints: [],
+      pageRoutes: []
+    };
+
+    if (fs.existsSync(structureArtifact)) {
+      const structure = JSON.parse(fs.readFileSync(structureArtifact, 'utf-8'));
+      flows.entryPoints = structure.entryPoints || [];
+    }
+
+    // Detect API routes
+    const apiDirs = ['api', 'app/api', 'pages/api', 'src/api'];
+    for (const apiDir of apiDirs) {
+      const apiPath = path.join(this.projectRoot, apiDir);
+      if (fs.existsSync(apiPath)) {
+        flows.apiEndpoints = this.findApiEndpoints(apiPath);
+        break;
+      }
+    }
+
+    // Save artifact
+    fs.writeFileSync(
+      path.join(this.artifactsDir, 'flows.json'),
+      JSON.stringify(flows, null, 2)
+    );
+
+    return {
+      entryPoints: flows.entryPoints.length,
+      apiEndpoints: flows.apiEndpoints.length,
+      pageRoutes: flows.pageRoutes.length
+    };
+  }
+
+  /**
+   * Find API endpoints in a directory
+   */
+  findApiEndpoints(apiDir, basePath = '/api') {
+    const endpoints = [];
+
+    const walk = (dir, currentPath) => {
+      try {
+        const items = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const item of items) {
+          const fullPath = path.join(dir, item.name);
+
+          if (item.isDirectory()) {
+            const routePath = item.name.startsWith('[')
+              ? `${currentPath}/:${item.name.replace(/[[\]]/g, '')}`
+              : `${currentPath}/${item.name}`;
+            walk(fullPath, routePath);
+          } else if (item.isFile() && /\.(js|ts)x?$/.test(item.name)) {
+            // Skip non-route files
+            if (item.name.startsWith('_')) continue;
+
+            // Determine route path
+            let routePath = currentPath;
+            if (item.name !== 'route.js' && item.name !== 'route.ts') {
+              const baseName = item.name.replace(/\.(js|ts)x?$/, '');
+              if (baseName !== 'index') {
+                routePath = `${currentPath}/${baseName}`;
+              }
+            }
+
+            // Read file to detect methods
+            try {
+              const content = fs.readFileSync(fullPath, 'utf-8');
+              const methods = [];
+              if (/export\s+(async\s+)?function\s+GET/i.test(content)) methods.push('GET');
+              if (/export\s+(async\s+)?function\s+POST/i.test(content)) methods.push('POST');
+              if (/export\s+(async\s+)?function\s+PUT/i.test(content)) methods.push('PUT');
+              if (/export\s+(async\s+)?function\s+PATCH/i.test(content)) methods.push('PATCH');
+              if (/export\s+(async\s+)?function\s+DELETE/i.test(content)) methods.push('DELETE');
+
+              endpoints.push({
+                path: routePath,
+                file: path.relative(this.projectRoot, fullPath),
+                methods: methods.length > 0 ? methods : ['ALL']
+              });
+            } catch (_e) {
+              // Skip unreadable files
+            }
+          }
+        }
+      } catch (_e) {
+        // Skip inaccessible directories
+      }
+    };
+
+    walk(apiDir, basePath);
+    return endpoints;
+  }
+
+  /**
+   * Run component analysis phase
+   */
+  async runComponentAnalysis() {
+    // Load architecture artifact
+    const architectureArtifact = path.join(this.artifactsDir, 'architecture.json');
+
+    const components = {
+      total: 0,
+      categories: [],
+      propDrilling: [],
+      coupling: []
+    };
+
+    if (fs.existsSync(architectureArtifact)) {
+      const architecture = JSON.parse(fs.readFileSync(architectureArtifact, 'utf-8'));
+      components.total = architecture.componentStructure?.totalComponents || 0;
+      components.categories = architecture.componentStructure?.categories || [];
+    }
+
+    // Save artifact
+    fs.writeFileSync(
+      path.join(this.artifactsDir, 'components.json'),
+      JSON.stringify(components, null, 2)
+    );
+
+    return {
+      total: components.total,
+      categories: components.categories.length
+    };
+  }
+
+  /**
+   * Run report generation phase
+   */
+  async runReportGeneration() {
+    const report = this.generateFullReport();
+
+    // Save main report
+    const reportPath = path.join(this.projectRoot, 'planning', 'CODEBASE_ANALYSIS.md');
+    const planningDir = path.join(this.projectRoot, 'planning');
+
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    fs.writeFileSync(reportPath, report);
+
+    // Also save in workflow directory
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'CODEBASE_ANALYSIS.md'),
+      report
+    );
+
+    this.state.summary = {
+      reportPath,
+      generatedAt: new Date().toISOString()
+    };
+
+    return {
+      reportPath,
+      reportLength: report.length
+    };
+  }
+
+  /**
+   * Generate full analysis report
+   */
+  generateFullReport() {
+    const lines = [
+      '# Codebase Analysis Report',
+      '',
+      '**Generated by**: Bootspring Analyze',
+      `**Date**: ${new Date().toISOString().split('T')[0]}`,
+      `**Analysis Depth**: ${this.state.depth}`,
+      ''
+    ];
+
+    // Executive Summary
+    lines.push('## Executive Summary');
+    lines.push('');
+
+    const structure = this.loadArtifact('structure.json');
+    const architecture = this.loadArtifact('architecture.json');
+    const dependencies = this.loadArtifact('dependencies.json');
+
+    if (structure) {
+      lines.push(`- **Total Files**: ${structure.stats?.totalFiles || 0}`);
+      lines.push(`- **Source Files**: ${structure.stats?.byCategory?.source || 0}`);
+      lines.push(`- **Test Files**: ${structure.stats?.byCategory?.test || 0}`);
+      lines.push(`- **Structure Type**: ${structure.structureType?.pattern || 'unknown'}`);
+    }
+
+    if (architecture) {
+      const primaryPattern = architecture.patterns?.[0];
+      lines.push(`- **Primary Architecture**: ${primaryPattern?.name || 'Not determined'}`);
+      lines.push(`- **Modules**: ${architecture.modules?.length || 0}`);
+    }
+
+    if (dependencies) {
+      lines.push(`- **Circular Dependencies**: ${dependencies.circularDependencies?.length || 0}`);
+      lines.push(`- **External Packages**: ${dependencies.packageUsage?.length || 0}`);
+    }
+
+    lines.push('');
+
+    // Health Score
+    lines.push('## Health Score');
+    lines.push('');
+    const score = this.calculateHealthScore(structure, architecture, dependencies);
+    lines.push(`**Overall**: ${score.overall}/100`);
+    lines.push('');
+    lines.push('| Category | Score |');
+    lines.push('|----------|-------|');
+    lines.push(`| Structure | ${score.structure}/100 |`);
+    lines.push(`| Architecture | ${score.architecture}/100 |`);
+    lines.push(`| Dependencies | ${score.dependencies}/100 |`);
+    lines.push('');
+
+    // Architecture Overview
+    if (architecture) {
+      lines.push('## Architecture Overview');
+      lines.push('');
+      lines.push(architecture.diagram || '');
+      lines.push('');
+
+      if (architecture.patterns?.length > 0) {
+        lines.push('### Detected Patterns');
+        lines.push('');
+        for (const pattern of architecture.patterns.slice(0, 3)) {
+          lines.push(`- **${pattern.name}** (${pattern.confidence}%): ${pattern.description}`);
+        }
+        lines.push('');
+      }
+    }
+
+    // Entry Points
+    if (structure?.entryPoints?.length > 0) {
+      lines.push('## Entry Points');
+      lines.push('');
+      lines.push('| Path | Type |');
+      lines.push('|------|------|');
+      for (const entry of structure.entryPoints.slice(0, 10)) {
+        lines.push(`| \`${entry.path}\` | ${entry.type} |`);
+      }
+      lines.push('');
+    }
+
+    // Dependencies
+    if (dependencies) {
+      lines.push('## Dependency Overview');
+      lines.push('');
+
+      if (dependencies.circularDependencies?.length > 0) {
+        lines.push('### Circular Dependencies');
+        lines.push('');
+        lines.push('> These create tight coupling and should be resolved.');
+        lines.push('');
+        for (const cycle of dependencies.circularDependencies.slice(0, 5)) {
+          lines.push(`- ${cycle.join(' → ')}`);
+        }
+        lines.push('');
+      }
+
+      if (dependencies.mostImported?.length > 0) {
+        lines.push('### Most Imported Files');
+        lines.push('');
+        lines.push('| File | Imported By |');
+        lines.push('|------|-------------|');
+        for (const file of dependencies.mostImported.slice(0, 10)) {
+          lines.push(`| \`${file.file}\` | ${file.importCount} files |`);
+        }
+        lines.push('');
+      }
+    }
+
+    // Recommendations
+    lines.push('## Recommendations');
+    lines.push('');
+    const recommendations = this.generateRecommendations(structure, architecture, dependencies);
+    for (let i = 0; i < recommendations.length; i++) {
+      lines.push(`${i + 1}. **${recommendations[i].title}**: ${recommendations[i].description}`);
+    }
+    lines.push('');
+
+    lines.push('---');
+    lines.push('');
+    lines.push('*Generated by [Bootspring](https://bootspring.com)*');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Load artifact file
+   */
+  loadArtifact(filename) {
+    const filePath = path.join(this.artifactsDir, filename);
+    if (fs.existsSync(filePath)) {
+      try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      } catch (_e) {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Calculate health score
+   */
+  calculateHealthScore(structure, architecture, dependencies) {
+    const scores = {
+      structure: 100,
+      architecture: 100,
+      dependencies: 100
+    };
+
+    // Structure scoring
+    if (structure) {
+      const sourceFiles = structure.stats?.byCategory?.source || 0;
+      const testFiles = structure.stats?.byCategory?.test || 0;
+      const testRatio = sourceFiles > 0 ? testFiles / sourceFiles : 0;
+
+      if (testRatio < 0.1) scores.structure -= 20;
+      else if (testRatio < 0.3) scores.structure -= 10;
+
+      if (!structure.structureType?.hasTypescript) scores.structure -= 10;
+    }
+
+    // Architecture scoring
+    if (architecture) {
+      if (architecture.patterns?.length === 0) scores.architecture -= 20;
+      if (architecture.modules?.length === 0) scores.architecture -= 10;
+    }
+
+    // Dependencies scoring
+    if (dependencies) {
+      const circularCount = dependencies.circularDependencies?.length || 0;
+      if (circularCount > 10) scores.dependencies -= 30;
+      else if (circularCount > 5) scores.dependencies -= 20;
+      else if (circularCount > 0) scores.dependencies -= 10;
+
+      const unusedCount = dependencies.unusedDependencies?.length || 0;
+      if (unusedCount > 10) scores.dependencies -= 10;
+    }
+
+    // Ensure scores are within bounds
+    for (const key of Object.keys(scores)) {
+      scores[key] = Math.max(0, Math.min(100, scores[key]));
+    }
+
+    scores.overall = Math.round(
+      scores.structure * 0.3 +
+      scores.architecture * 0.3 +
+      scores.dependencies * 0.4
+    );
+
+    return scores;
+  }
+
+  /**
+   * Generate recommendations
+   */
+  generateRecommendations(structure, architecture, dependencies) {
+    const recommendations = [];
+
+    if (dependencies?.circularDependencies?.length > 0) {
+      recommendations.push({
+        title: 'Resolve Circular Dependencies',
+        description: `Found ${dependencies.circularDependencies.length} circular dependency chains that increase coupling.`
+      });
+    }
+
+    if (dependencies?.unusedDependencies?.length > 5) {
+      recommendations.push({
+        title: 'Clean Up Unused Dependencies',
+        description: `Found ${dependencies.unusedDependencies.length} potentially unused packages. Consider removing them.`
+      });
+    }
+
+    if (structure && !structure.structureType?.hasTypescript) {
+      recommendations.push({
+        title: 'Consider TypeScript',
+        description: 'TypeScript provides better type safety and developer experience.'
+      });
+    }
+
+    const testRatio = structure ? (structure.stats?.byCategory?.test || 0) / (structure.stats?.byCategory?.source || 1) : 0;
+    if (testRatio < 0.2) {
+      recommendations.push({
+        title: 'Increase Test Coverage',
+        description: 'Current test file ratio is low. Add more tests to improve reliability.'
+      });
+    }
+
+    if (recommendations.length === 0) {
+      recommendations.push({
+        title: 'Codebase Looks Good',
+        description: 'No major issues detected. Continue following best practices.'
+      });
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Get workflow progress
+   */
+  getProgress() {
+    if (!this.state) return null;
+
+    const phases = Object.entries(ANALYZE_PHASES).map(([phaseId, phase]) => {
+      const phaseState = this.state.phases[phaseId] || { status: PHASE_STATUS.PENDING };
+
+      return {
+        id: phaseId,
+        name: phase.name,
+        description: phase.description,
+        order: phase.order,
+        required: phase.required,
+        status: phaseState.status,
+        dependenciesMet: this.arePhaseDependenciesMet(phaseId)
+      };
+    });
+
+    const completedCount = phases.filter(p => p.status === PHASE_STATUS.COMPLETED).length;
+    const activeCount = phases.filter(p => p.status !== PHASE_STATUS.SKIPPED).length;
+
+    return {
+      currentPhase: this.state.currentPhase,
+      depth: this.state.depth,
+      startedAt: this.state.startedAt,
+      lastUpdated: this.state.lastUpdated,
+      phases,
+      overall: {
+        completed: completedCount,
+        total: activeCount,
+        percentage: Math.round((completedCount / activeCount) * 100)
+      },
+      isComplete: completedCount === activeCount,
+      summary: this.state.summary
+    };
+  }
+
+  /**
+   * Get resume point
+   */
+  getResumePoint() {
+    if (!this.state || !this.state.currentPhase) {
+      return null;
+    }
+
+    const phase = ANALYZE_PHASES[this.state.currentPhase];
+    const phaseState = this.state.phases[this.state.currentPhase];
+
+    return {
+      phase: this.state.currentPhase,
+      phaseName: phase?.name,
+      phaseStatus: phaseState?.status,
+      lastUpdated: this.state.lastUpdated
+    };
+  }
+}
+
+module.exports = {
+  AnalyzeWorkflowEngine,
+  ANALYZE_PHASES,
+  PHASE_STATUS,
+  ANALYSIS_DEPTH
+};