@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/analyze-workflow.ts

@@ -0,0 +1,1453 @@
+/**
+ * Bootspring Analyze Workflow Engine
+ *
+ * Deep codebase analysis for understanding architecture,
+ * dependencies, patterns, and code flows.
+ *
+ * @package bootspring
+ * @module core/analyze-workflow
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Import analyzers from JS modules
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { StructureAnalyzer } = require('../../analyzers/structure-analyzer') as {
+  StructureAnalyzer: new (projectRoot: string, options?: Record<string, unknown>) => {
+    analyze: () => Record<string, unknown>;
+  };
+};
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { ArchitectureAnalyzer } = require('../../analyzers/architecture-analyzer') as {
+  ArchitectureAnalyzer: new (projectRoot: string) => {
+    analyze: () => Record<string, unknown>;
+  };
+};
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { DependencyAnalyzer } = require('../../analyzers/dependency-analyzer') as {
+  DependencyAnalyzer: new (projectRoot: string) => {
+    analyze: () => Record<string, unknown>;
+  };
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type PhaseStatus = 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+export type AnalysisDepthLevel = 'shallow' | 'standard' | 'deep';
+
+export interface PhaseDefinition {
+  name: string;
+  description: string;
+  order: number;
+  required: boolean;
+  dependencies?: string[] | undefined;
+}
+
+export interface PhaseState {
+  status: PhaseStatus;
+  startedAt: string | null;
+  completedAt: string | null;
+  result: unknown | null;
+  error: string | null;
+}
+
+export interface DepthConfig {
+  phases: string[];
+  description: string;
+}
+
+export interface AnalyzeWorkflowState {
+  version: string;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  currentPhase: string | null;
+  depth: AnalysisDepthLevel;
+  phases: Record<string, PhaseState>;
+  results: Record<string, unknown>;
+  summary: WorkflowSummary | null;
+}
+
+export interface WorkflowSummary {
+  reportPath: string;
+  generatedAt: string;
+}
+
+export interface StructureResult {
+  totalFiles: number;
+  totalDirs: number;
+  structureType: unknown;
+  entryPoints: number;
+  keyDirectories: string[];
+}
+
+export interface ArchitectureResult {
+  patterns: unknown[];
+  layers: string[];
+  modules: number;
+  hasComponentSystem: boolean;
+}
+
+export interface DependencyResult {
+  fileCount: number;
+  circularCount: number;
+  unusedCount: number;
+  externalPackages: number;
+  mostImported: unknown[];
+  skipped?: boolean | undefined;
+}
+
+export interface PatternResult {
+  designPatterns: number;
+  antiPatterns: number;
+  codeSmells: number;
+}
+
+export interface FlowResult {
+  entryPoints: number;
+  apiEndpoints: number;
+  pageRoutes: number;
+}
+
+export interface ComponentResult {
+  total: number;
+  categories: number;
+}
+
+export interface ReportResult {
+  reportPath: string;
+  reportLength: number;
+}
+
+export interface ApiEndpoint {
+  path: string;
+  file: string;
+  methods: string[];
+}
+
+export interface HealthScore {
+  overall: number;
+  structure: number;
+  architecture: number;
+  dependencies: number;
+}
+
+export interface Recommendation {
+  title: string;
+  description: string;
+}
+
+export interface PhaseProgress {
+  id: string;
+  name: string;
+  description: string;
+  order: number;
+  required: boolean;
+  status: PhaseStatus;
+  dependenciesMet: boolean;
+}
+
+export interface WorkflowProgress {
+  currentPhase: string | null;
+  depth: AnalysisDepthLevel;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  phases: PhaseProgress[];
+  overall: {
+    completed: number;
+    total: number;
+    percentage: number;
+  };
+  isComplete: boolean;
+  summary: WorkflowSummary | null;
+}
+
+export interface ResumePoint {
+  phase: string;
+  phaseName: string | undefined;
+  phaseStatus: PhaseStatus | undefined;
+  lastUpdated: string | null;
+}
+
+export interface AnalyzeWorkflowOptions {
+  depth?: AnalysisDepthLevel | undefined;
+  include?: string | null | undefined;
+  exclude?: string | null | undefined;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Workflow phase status
+ */
+export const PHASE_STATUS: Record<string, PhaseStatus> = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped',
+  FAILED: 'failed'
+};
+
+/**
+ * Analysis phases
+ */
+export const ANALYZE_PHASES: Record<string, PhaseDefinition> = {
+  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
+ */
+export const ANALYSIS_DEPTH: Record<AnalysisDepthLevel, DepthConfig> = {
+  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
+ */
+export const DEFAULT_STATE: AnalyzeWorkflowState = {
+  version: '1.0.0',
+  startedAt: null,
+  lastUpdated: null,
+  currentPhase: null,
+  depth: 'standard',
+  phases: {},
+  results: {},
+  summary: null
+};
+
+// ============================================================================
+// AnalyzeWorkflowEngine Class
+// ============================================================================
+
+/**
+ * AnalyzeWorkflowEngine - Manages analysis workflow
+ */
+export class AnalyzeWorkflowEngine {
+  readonly projectRoot: string;
+  readonly workflowDir: string;
+  readonly stateFile: string;
+  readonly reportsDir: string;
+  readonly artifactsDir: string;
+  readonly options: AnalyzeWorkflowOptions;
+  state: AnalyzeWorkflowState | null;
+
+  constructor(projectRoot: string, options: AnalyzeWorkflowOptions = {}) {
+    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(): void {
+    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(): boolean {
+    if (fs.existsSync(this.stateFile)) {
+      try {
+        this.state = JSON.parse(fs.readFileSync(this.stateFile, 'utf-8')) as AnalyzeWorkflowState;
+        return true;
+      } catch {
+        this.state = { ...DEFAULT_STATE };
+        return false;
+      }
+    }
+    this.state = { ...DEFAULT_STATE };
+    return false;
+  }
+
+  /**
+   * Save workflow state
+   */
+  saveState(): void {
+    if (!this.state) return;
+    this.setupDirectories();
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  /**
+   * Initialize workflow
+   */
+  initializeWorkflow(depth: AnalysisDepthLevel = 'standard'): AnalyzeWorkflowState {
+    this.setupDirectories();
+    this.state = {
+      ...DEFAULT_STATE,
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+      depth,
+      phases: {},
+      results: {}
+    };
+
+    // Get phases for this depth
+    const depthConfig = ANALYSIS_DEPTH[depth];
+    const activePhases = depthConfig?.phases ?? ANALYSIS_DEPTH.standard.phases;
+
+    // Initialize phase states
+    for (const phaseId of Object.keys(ANALYZE_PHASES)) {
+      const phaseStatus: PhaseStatus = activePhases.includes(phaseId) ? 'pending' : 'skipped';
+      this.state.phases[phaseId] = {
+        status: phaseStatus,
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+    }
+
+    this.state.currentPhase = 'structure';
+    this.saveState();
+    return this.state;
+  }
+
+  /**
+   * Check if workflow exists
+   */
+  hasWorkflow(): boolean {
+    return fs.existsSync(this.stateFile);
+  }
+
+  /**
+   * Reset workflow
+   */
+  resetWorkflow(): boolean {
+    if (fs.existsSync(this.stateFile)) {
+      fs.unlinkSync(this.stateFile);
+    }
+    this.state = null;
+    return true;
+  }
+
+  /**
+   * Check if phase dependencies are met
+   */
+  arePhaseDependenciesMet(phaseId: string): boolean {
+    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 !== 'completed' && depPhase.status !== 'skipped')) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get next phase
+   */
+  getNextPhase(): string | null {
+    if (!this.state) return null;
+
+    const phaseOrder = Object.keys(ANALYZE_PHASES).sort((a, b) => {
+      const phaseA = ANALYZE_PHASES[a];
+      const phaseB = ANALYZE_PHASES[b];
+      return (phaseA?.order ?? 0) - (phaseB?.order ?? 0);
+    });
+
+    for (const phaseId of phaseOrder) {
+      const phase = this.state.phases[phaseId];
+      if (phase?.status === 'pending' && this.arePhaseDependenciesMet(phaseId)) {
+        return phaseId;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Start a phase
+   */
+  startPhase(phaseId: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'in_progress';
+    phase.startedAt = new Date().toISOString();
+    this.state.currentPhase = phaseId;
+    this.saveState();
+  }
+
+  /**
+   * Complete a phase
+   */
+  completePhase(phaseId: string, result: unknown = null): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'completed';
+    phase.completedAt = new Date().toISOString();
+    phase.result = result;
+    this.state.results[phaseId] = result;
+    this.saveState();
+  }
+
+  /**
+   * Fail a phase
+   */
+  failPhase(phaseId: string, error: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'failed';
+    phase.completedAt = new Date().toISOString();
+    phase.error = error;
+    this.saveState();
+  }
+
+  /**
+   * Run structure mapping phase
+   */
+  async runStructureMapping(): Promise<StructureResult> {
+    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)
+    );
+
+    const keyDirs = result.keyDirectories as Record<string, unknown> | undefined;
+    const keyDirectories = keyDirs
+      ? Object.keys(keyDirs).filter(k => keyDirs[k])
+      : [];
+
+    const stats = result.stats as Record<string, number> | undefined;
+    const entryPoints = result.entryPoints as unknown[] | undefined;
+
+    return {
+      totalFiles: stats?.totalFiles ?? 0,
+      totalDirs: stats?.totalDirs ?? 0,
+      structureType: result.structureType,
+      entryPoints: entryPoints?.length ?? 0,
+      keyDirectories
+    };
+  }
+
+  /**
+   * Run architecture analysis phase
+   */
+  async runArchitectureAnalysis(): Promise<ArchitectureResult> {
+    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
+    );
+
+    const patterns = result.patterns as unknown[] | undefined;
+    const layers = result.layers as Record<string, unknown> | undefined;
+    const modules = result.modules as unknown[] | undefined;
+    const componentStructure = result.componentStructure as Record<string, boolean> | undefined;
+
+    return {
+      patterns: (patterns ?? []).slice(0, 3),
+      layers: Object.keys(layers ?? {}),
+      modules: modules?.length ?? 0,
+      hasComponentSystem: componentStructure?.hasComponentDir ?? false
+    };
+  }
+
+  /**
+   * Generate architecture report
+   */
+  generateArchitectureReport(analysis: Record<string, unknown>): string {
+    const lines: string[] = [
+      '# Architecture Analysis',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Detected Patterns',
+      ''
+    ];
+
+    const patterns = analysis.patterns as Array<{
+      name: string;
+      confidence: number;
+      description?: string;
+      matchedIndicators: string[];
+    }> | undefined;
+
+    if (patterns) {
+      for (const pattern of 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('');
+
+    const layers = analysis.layers as Record<string, Array<{ path: string; purpose: string }>> | undefined;
+    if (layers) {
+      for (const [layer, dirs] of Object.entries(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('');
+        }
+      }
+    }
+
+    const modules = analysis.modules as Array<{ name: string; path: string; type: string }> | undefined;
+    if (modules && modules.length > 0) {
+      lines.push('## Modules/Features');
+      lines.push('');
+      for (const mod of modules) {
+        lines.push(`- **${mod.name}** (\`${mod.path}\`): ${mod.type}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('## Architecture Diagram');
+    lines.push('');
+    lines.push(String(analysis.diagram ?? ''));
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run dependency analysis phase
+   */
+  async runDependencyAnalysis(): Promise<DependencyResult> {
+    // 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')) as Record<string, unknown>;
+        const stats = structure.stats as Record<string, number> | undefined;
+        fileCount = stats?.totalFiles ?? 0;
+      } catch {
+        // 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
+    );
+
+    const circularDependencies = result.circularDependencies as unknown[] | undefined;
+    const unusedDependencies = result.unusedDependencies as unknown[] | undefined;
+    const packageUsage = result.packageUsage as unknown[] | undefined;
+    const mostImported = result.mostImported as unknown[] | undefined;
+
+    return {
+      fileCount: (result.fileCount as number | undefined) ?? 0,
+      circularCount: circularDependencies?.length ?? 0,
+      unusedCount: unusedDependencies?.length ?? 0,
+      externalPackages: packageUsage?.length ?? 0,
+      mostImported: (mostImported ?? []).slice(0, 5)
+    };
+  }
+
+  /**
+   * Generate dependency report
+   */
+  generateDependencyReport(analysis: Record<string, unknown>): string {
+    const lines: string[] = [
+      '# Dependency Analysis',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Summary',
+      '',
+      `- **Total Files Analyzed**: ${analysis.fileCount ?? 0}`,
+      `- **Circular Dependencies**: ${(analysis.circularDependencies as unknown[])?.length ?? 0}`,
+      `- **Unused Dependencies**: ${(analysis.unusedDependencies as unknown[])?.length ?? 0}`,
+      `- **External Packages**: ${(analysis.packageUsage as unknown[])?.length ?? 0}`,
+      ''
+    ];
+
+    const circularDependencies = analysis.circularDependencies as string[][] | undefined;
+    if (circularDependencies && 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(circularDependencies.length, 5); i++) {
+        const cycle = circularDependencies[i];
+        if (cycle) {
+          lines.push(`${i + 1}. ${cycle.join(' → ')}`);
+        }
+      }
+      lines.push('');
+    }
+
+    const unusedDependencies = analysis.unusedDependencies as Array<{ name: string; type: string }> | undefined;
+    if (unusedDependencies && 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 unusedDependencies) {
+        lines.push(`- \`${dep.name}\` (${dep.type})`);
+      }
+      lines.push('');
+    }
+
+    lines.push('## Most Imported Files');
+    lines.push('');
+    lines.push('| File | Import Count |');
+    lines.push('|------|--------------|');
+    const mostImported = analysis.mostImported as Array<{ file: string; importCount: number }> | undefined;
+    if (mostImported) {
+      for (const file of 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('|---------|-------------|');
+    const packageUsage = analysis.packageUsage as Array<{ package: string; count: number }> | undefined;
+    if (packageUsage) {
+      for (const pkg of packageUsage.slice(0, 15)) {
+        lines.push(`| \`${pkg.package}\` | ${pkg.count} |`);
+      }
+    }
+    lines.push('');
+
+    lines.push('## Dependency Graph');
+    lines.push('');
+    lines.push(String(analysis.diagram ?? ''));
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run pattern detection phase
+   */
+  async runPatternDetection(): Promise<PatternResult> {
+    // Load previous results
+    const architectureArtifact = path.join(this.artifactsDir, 'architecture.json');
+    const dependencyArtifact = path.join(this.artifactsDir, 'dependencies.json');
+
+    const patterns: {
+      designPatterns: unknown[];
+      antiPatterns: Array<{
+        id: string;
+        name: string;
+        severity: string;
+        count: number;
+        description: string;
+      }>;
+      codeSmells: unknown[];
+    } = {
+      designPatterns: [],
+      antiPatterns: [],
+      codeSmells: []
+    };
+
+    if (fs.existsSync(architectureArtifact)) {
+      const architecture = JSON.parse(fs.readFileSync(architectureArtifact, 'utf-8')) as Record<string, unknown>;
+      patterns.designPatterns = (architecture.patterns as unknown[]) ?? [];
+    }
+
+    if (fs.existsSync(dependencyArtifact)) {
+      const dependencies = JSON.parse(fs.readFileSync(dependencyArtifact, 'utf-8')) as Record<string, unknown>;
+
+      // Detect anti-patterns from dependencies
+      const circularDeps = dependencies.circularDependencies as unknown[] | undefined;
+      if (circularDeps && circularDeps.length > 0) {
+        patterns.antiPatterns.push({
+          id: 'circular-deps',
+          name: 'Circular Dependencies',
+          severity: 'medium',
+          count: circularDeps.length,
+          description: 'Files that depend on each other in a cycle'
+        });
+      }
+
+      // High coupling detection
+      const mostImported = dependencies.mostImported as Array<{ importCount: number }> | undefined;
+      const highCoupling = mostImported?.filter(f => f.importCount > 20);
+      if (highCoupling && 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: {
+    designPatterns: unknown[];
+    antiPatterns: Array<{ name: string; severity: string; count: number; description?: string }>;
+    codeSmells: unknown[];
+  }): string {
+    const lines: string[] = [
+      '# Pattern Analysis',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      ''
+    ];
+
+    if (patterns.designPatterns.length > 0) {
+      lines.push('## Design Patterns');
+      lines.push('');
+      for (const patternRaw of patterns.designPatterns) {
+        const pattern = patternRaw as { name: string; confidence: number; description?: string };
+        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(): Promise<FlowResult> {
+    // Load structure artifact
+    const structureArtifact = path.join(this.artifactsDir, 'structure.json');
+
+    const flows: {
+      entryPoints: unknown[];
+      apiEndpoints: ApiEndpoint[];
+      pageRoutes: unknown[];
+    } = {
+      entryPoints: [],
+      apiEndpoints: [],
+      pageRoutes: []
+    };
+
+    if (fs.existsSync(structureArtifact)) {
+      const structure = JSON.parse(fs.readFileSync(structureArtifact, 'utf-8')) as Record<string, unknown>;
+      flows.entryPoints = (structure.entryPoints as unknown[]) ?? [];
+    }
+
+    // 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: string, basePath: string = '/api'): ApiEndpoint[] {
+    const endpoints: ApiEndpoint[] = [];
+
+    const walk = (dir: string, currentPath: string): void => {
+      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: string[] = [];
+              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 {
+              // Skip unreadable files
+            }
+          }
+        }
+      } catch {
+        // Skip inaccessible directories
+      }
+    };
+
+    walk(apiDir, basePath);
+    return endpoints;
+  }
+
+  /**
+   * Run component analysis phase
+   */
+  async runComponentAnalysis(): Promise<ComponentResult> {
+    // Load architecture artifact
+    const architectureArtifact = path.join(this.artifactsDir, 'architecture.json');
+
+    const components: {
+      total: number;
+      categories: unknown[];
+      propDrilling: unknown[];
+      coupling: unknown[];
+    } = {
+      total: 0,
+      categories: [],
+      propDrilling: [],
+      coupling: []
+    };
+
+    if (fs.existsSync(architectureArtifact)) {
+      const architecture = JSON.parse(fs.readFileSync(architectureArtifact, 'utf-8')) as Record<string, unknown>;
+      const componentStructure = architecture.componentStructure as Record<string, unknown> | undefined;
+      components.total = (componentStructure?.totalComponents as number) ?? 0;
+      components.categories = (componentStructure?.categories as unknown[]) ?? [];
+    }
+
+    // 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(): Promise<ReportResult> {
+    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
+    );
+
+    if (this.state) {
+      this.state.summary = {
+        reportPath,
+        generatedAt: new Date().toISOString()
+      };
+    }
+
+    return {
+      reportPath,
+      reportLength: report.length
+    };
+  }
+
+  /**
+   * Generate full analysis report
+   */
+  generateFullReport(): string {
+    const lines: string[] = [
+      '# Codebase Analysis Report',
+      '',
+      '**Generated by**: Bootspring Analyze',
+      `**Date**: ${new Date().toISOString().split('T')[0]}`,
+      `**Analysis Depth**: ${this.state?.depth ?? 'standard'}`,
+      ''
+    ];
+
+    // Executive Summary
+    lines.push('## Executive Summary');
+    lines.push('');
+
+    const structure = this.loadArtifact('structure.json') as Record<string, unknown> | null;
+    const architecture = this.loadArtifact('architecture.json') as Record<string, unknown> | null;
+    const dependencies = this.loadArtifact('dependencies.json') as Record<string, unknown> | null;
+
+    if (structure) {
+      const stats = structure.stats as Record<string, unknown> | undefined;
+      const byCategory = stats?.byCategory as Record<string, number> | undefined;
+      const structureType = structure.structureType as Record<string, unknown> | undefined;
+      lines.push(`- **Total Files**: ${stats?.totalFiles ?? 0}`);
+      lines.push(`- **Source Files**: ${byCategory?.source ?? 0}`);
+      lines.push(`- **Test Files**: ${byCategory?.test ?? 0}`);
+      lines.push(`- **Structure Type**: ${structureType?.pattern ?? 'unknown'}`);
+    }
+
+    if (architecture) {
+      const patterns = architecture.patterns as Array<{ name: string }> | undefined;
+      const primaryPattern = patterns?.[0];
+      const modules = architecture.modules as unknown[] | undefined;
+      lines.push(`- **Primary Architecture**: ${primaryPattern?.name ?? 'Not determined'}`);
+      lines.push(`- **Modules**: ${modules?.length ?? 0}`);
+    }
+
+    if (dependencies) {
+      const circularDeps = dependencies.circularDependencies as unknown[] | undefined;
+      const packageUsage = dependencies.packageUsage as unknown[] | undefined;
+      lines.push(`- **Circular Dependencies**: ${circularDeps?.length ?? 0}`);
+      lines.push(`- **External Packages**: ${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(String(architecture.diagram ?? ''));
+      lines.push('');
+
+      const patterns = architecture.patterns as Array<{ name: string; confidence: number; description: string }> | undefined;
+      if (patterns && patterns.length > 0) {
+        lines.push('### Detected Patterns');
+        lines.push('');
+        for (const pattern of patterns.slice(0, 3)) {
+          lines.push(`- **${pattern.name}** (${pattern.confidence}%): ${pattern.description}`);
+        }
+        lines.push('');
+      }
+    }
+
+    // Entry Points
+    const entryPoints = structure?.entryPoints as Array<{ path: string; type: string }> | undefined;
+    if (entryPoints && entryPoints.length > 0) {
+      lines.push('## Entry Points');
+      lines.push('');
+      lines.push('| Path | Type |');
+      lines.push('|------|------|');
+      for (const entry of entryPoints.slice(0, 10)) {
+        lines.push(`| \`${entry.path}\` | ${entry.type} |`);
+      }
+      lines.push('');
+    }
+
+    // Dependencies
+    if (dependencies) {
+      lines.push('## Dependency Overview');
+      lines.push('');
+
+      const circularDeps = dependencies.circularDependencies as string[][] | undefined;
+      if (circularDeps && circularDeps.length > 0) {
+        lines.push('### Circular Dependencies');
+        lines.push('');
+        lines.push('> These create tight coupling and should be resolved.');
+        lines.push('');
+        for (const cycle of circularDeps.slice(0, 5)) {
+          lines.push(`- ${cycle.join(' → ')}`);
+        }
+        lines.push('');
+      }
+
+      const mostImported = dependencies.mostImported as Array<{ file: string; importCount: number }> | undefined;
+      if (mostImported && mostImported.length > 0) {
+        lines.push('### Most Imported Files');
+        lines.push('');
+        lines.push('| File | Imported By |');
+        lines.push('|------|-------------|');
+        for (const file of 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++) {
+      const rec = recommendations[i];
+      if (rec) {
+        lines.push(`${i + 1}. **${rec.title}**: ${rec.description}`);
+      }
+    }
+    lines.push('');
+
+    lines.push('---');
+    lines.push('');
+    lines.push('*Generated by [Bootspring](https://bootspring.com)*');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Load artifact file
+   */
+  loadArtifact(filename: string): unknown | null {
+    const filePath = path.join(this.artifactsDir, filename);
+    if (fs.existsSync(filePath)) {
+      try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Calculate health score
+   */
+  calculateHealthScore(
+    structure: Record<string, unknown> | null,
+    architecture: Record<string, unknown> | null,
+    dependencies: Record<string, unknown> | null
+  ): HealthScore {
+    let structureScore = 100;
+    let architectureScore = 100;
+    let dependenciesScore = 100;
+
+    // Structure scoring
+    if (structure) {
+      const stats = structure.stats as Record<string, unknown> | undefined;
+      const byCategory = stats?.byCategory as Record<string, number> | undefined;
+      const sourceFiles = byCategory?.source ?? 0;
+      const testFiles = byCategory?.test ?? 0;
+      const testRatio = sourceFiles > 0 ? testFiles / sourceFiles : 0;
+
+      if (testRatio < 0.1) structureScore -= 20;
+      else if (testRatio < 0.3) structureScore -= 10;
+
+      const structureType = structure.structureType as Record<string, boolean> | undefined;
+      if (!structureType?.hasTypescript) structureScore -= 10;
+    }
+
+    // Architecture scoring
+    if (architecture) {
+      const patterns = architecture.patterns as unknown[] | undefined;
+      const modules = architecture.modules as unknown[] | undefined;
+      if (!patterns || patterns.length === 0) architectureScore -= 20;
+      if (!modules || modules.length === 0) architectureScore -= 10;
+    }
+
+    // Dependencies scoring
+    if (dependencies) {
+      const circularDeps = dependencies.circularDependencies as unknown[] | undefined;
+      const circularCount = circularDeps?.length ?? 0;
+      if (circularCount > 10) dependenciesScore -= 30;
+      else if (circularCount > 5) dependenciesScore -= 20;
+      else if (circularCount > 0) dependenciesScore -= 10;
+
+      const unusedDeps = dependencies.unusedDependencies as unknown[] | undefined;
+      const unusedCount = unusedDeps?.length ?? 0;
+      if (unusedCount > 10) dependenciesScore -= 10;
+    }
+
+    // Ensure scores are within bounds
+    structureScore = Math.max(0, Math.min(100, structureScore));
+    architectureScore = Math.max(0, Math.min(100, architectureScore));
+    dependenciesScore = Math.max(0, Math.min(100, dependenciesScore));
+
+    return {
+      overall: Math.round(
+        structureScore * 0.3 +
+        architectureScore * 0.3 +
+        dependenciesScore * 0.4
+      ),
+      structure: structureScore,
+      architecture: architectureScore,
+      dependencies: dependenciesScore
+    };
+  }
+
+  /**
+   * Generate recommendations
+   */
+  generateRecommendations(
+    structure: Record<string, unknown> | null,
+    _architecture: Record<string, unknown> | null,
+    dependencies: Record<string, unknown> | null
+  ): Recommendation[] {
+    const recommendations: Recommendation[] = [];
+
+    const circularDeps = dependencies?.circularDependencies as unknown[] | undefined;
+    if (circularDeps && circularDeps.length > 0) {
+      recommendations.push({
+        title: 'Resolve Circular Dependencies',
+        description: `Found ${circularDeps.length} circular dependency chains that increase coupling.`
+      });
+    }
+
+    const unusedDeps = dependencies?.unusedDependencies as unknown[] | undefined;
+    if (unusedDeps && unusedDeps.length > 5) {
+      recommendations.push({
+        title: 'Clean Up Unused Dependencies',
+        description: `Found ${unusedDeps.length} potentially unused packages. Consider removing them.`
+      });
+    }
+
+    const structureType = structure?.structureType as Record<string, boolean> | undefined;
+    if (structure && !structureType?.hasTypescript) {
+      recommendations.push({
+        title: 'Consider TypeScript',
+        description: 'TypeScript provides better type safety and developer experience.'
+      });
+    }
+
+    const stats = structure?.stats as Record<string, unknown> | undefined;
+    const byCategory = stats?.byCategory as Record<string, number> | undefined;
+    const testFiles = byCategory?.test ?? 0;
+    const sourceFiles = byCategory?.source ?? 1;
+    const testRatio = structure ? testFiles / sourceFiles : 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(): WorkflowProgress | null {
+    if (!this.state) return null;
+
+    const phases: PhaseProgress[] = Object.entries(ANALYZE_PHASES).map(([phaseId, phase]) => {
+      const phaseState = this.state?.phases[phaseId];
+      const status: PhaseStatus = phaseState?.status ?? 'pending';
+
+      return {
+        id: phaseId,
+        name: phase.name,
+        description: phase.description,
+        order: phase.order,
+        required: phase.required,
+        status,
+        dependenciesMet: this.arePhaseDependenciesMet(phaseId)
+      };
+    });
+
+    const completedCount = phases.filter(p => p.status === 'completed').length;
+    const activeCount = phases.filter(p => p.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: activeCount > 0 ? Math.round((completedCount / activeCount) * 100) : 0
+      },
+      isComplete: completedCount === activeCount,
+      summary: this.state.summary
+    };
+  }
+
+  /**
+   * Get resume point
+   */
+  getResumePoint(): ResumePoint | null {
+    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
+    };
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function createAnalyzeWorkflowEngine(
+  projectRoot: string,
+  options: AnalyzeWorkflowOptions = {}
+): AnalyzeWorkflowEngine {
+  return new AnalyzeWorkflowEngine(projectRoot, options);
+}