@girardmedia/bootspring 2.0.21 → 2.0.22

package/src/cli/analyze.ts

@@ -0,0 +1,640 @@
+/**
+ * Bootspring Analyze CLI
+ *
+ * Deep codebase analysis for understanding architecture,
+ * dependencies, patterns, and code flows.
+ *
+ * @package bootspring
+ * @module cli/analyze
+ */
+
+// Import JS modules with type interfaces
+interface ParsedArgs {
+  _: string[];
+  depth?: string | undefined;
+  phase?: string | undefined;
+  include?: string | undefined;
+  exclude?: string | undefined;
+}
+
+interface AnalysisDepthConfig {
+  description: string;
+}
+
+interface PhaseConfig {
+  name: string;
+  description: string;
+  required: boolean;
+}
+
+interface StructureResult {
+  totalFiles: number;
+  totalDirs: number;
+  structureType?: { pattern: string } | undefined;
+  keyDirectories: string[];
+  entryPoints: number;
+}
+
+interface ArchitectureResult {
+  patterns: Array<{ name: string; confidence: number }>;
+  layers: string[];
+  modules: number;
+}
+
+interface DependencyResult {
+  skipped?: boolean | undefined;
+  fileCount: number;
+  circularCount: number;
+  unusedCount: number;
+  externalPackages: number;
+  mostImported: Array<{ file: string; importCount: number }>;
+}
+
+interface PatternResult {
+  designPatterns: number;
+  antiPatterns: number;
+}
+
+interface FlowResult {
+  entryPoints: number;
+  apiEndpoints: number;
+}
+
+interface ComponentResult {
+  total: number;
+}
+
+interface ReportResult {
+  reportPath: string;
+}
+
+interface OverallProgress {
+  completed: number;
+  total: number;
+  percentage: number;
+}
+
+interface PhaseProgress {
+  name: string;
+  status: string;
+  required: boolean;
+}
+
+interface WorkflowProgress {
+  overall: OverallProgress;
+  isComplete: boolean;
+  currentPhase?: string | undefined;
+  depth: string;
+  phases: PhaseProgress[];
+  startedAt?: string | undefined;
+  lastUpdated?: string | undefined;
+  summary?: {
+    reportPath?: string | undefined;
+  } | undefined;
+}
+
+interface ResumePoint {
+  phaseName: string;
+}
+
+interface AnalyzeWorkflowEngineClass {
+  new (projectRoot: string, options?: { depth?: string | undefined }): AnalyzeWorkflowEngine;
+}
+
+interface AnalyzeWorkflowEngine {
+  hasWorkflow(): boolean;
+  loadState(): void;
+  initializeWorkflow(depth: string): void;
+  getProgress(): WorkflowProgress;
+  getResumePoint(): ResumePoint | null;
+  getNextPhase(): string | null;
+  startPhase(phaseId: string): void;
+  completePhase(phaseId: string, result: unknown): void;
+  failPhase(phaseId: string, error: string): void;
+  skipPhase(phaseId: string): void;
+  resetWorkflow(): void;
+  runStructureMapping(): Promise<StructureResult>;
+  runArchitectureAnalysis(): Promise<ArchitectureResult>;
+  runDependencyAnalysis(): Promise<DependencyResult>;
+  runPatternDetection(): Promise<PatternResult>;
+  runFlowTracing(): Promise<FlowResult>;
+  runComponentAnalysis(): Promise<ComponentResult>;
+  runReportGeneration(): Promise<ReportResult>;
+}
+
+interface AnalyzeWorkflowModule {
+  AnalyzeWorkflowEngine: AnalyzeWorkflowEngineClass;
+  ANALYZE_PHASES: Record<string, PhaseConfig>;
+  ANALYSIS_DEPTH: Record<string, AnalysisDepthConfig>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const utils = require('../../core/utils') as typeof import('../core/utils');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const analyzeWorkflowModule = require('../../core/analyze-workflow') as AnalyzeWorkflowModule;
+
+const { AnalyzeWorkflowEngine, ANALYZE_PHASES, ANALYSIS_DEPTH } = analyzeWorkflowModule;
+
+// Get project root
+const projectRoot = process.cwd();
+
+/**
+ * Show analyze help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.bold}Bootspring Analyze${utils.COLORS.reset}
+Deep codebase analysis for understanding
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring analyze              Full analysis
+  bootspring analyze status       Show progress
+  bootspring analyze resume       Continue from checkpoint
+  bootspring analyze reset        Reset workflow
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --depth=<level>                 Analysis depth: shallow, standard, deep
+  --phase=<phase>                 Run specific phase only
+  --include=<glob>                Include pattern (e.g., "src/**")
+  --exclude=<glob>                Exclude pattern
+
+${utils.COLORS.bold}Depth Levels:${utils.COLORS.reset}
+  shallow     Quick scan - structure and architecture only
+  standard    Standard analysis with patterns and dependencies
+  deep        Comprehensive with flow tracing and components
+
+${utils.COLORS.bold}Notes:${utils.COLORS.reset}
+  Large codebases (500+ files) automatically skip heavy dependency
+  analysis for performance. Use --depth=deep to force full analysis.
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring analyze              Auto-adjusts for codebase size
+  bootspring analyze --depth=shallow
+  bootspring analyze --depth=deep
+  bootspring analyze status
+`);
+}
+
+/**
+ * Start analysis workflow
+ */
+async function analyzeStart(args: ParsedArgs): Promise<void> {
+  const depth = args.depth || 'standard';
+
+  if (!ANALYSIS_DEPTH[depth]) {
+    utils.print.error(`Unknown depth level: ${depth}`);
+    utils.print.info('Valid options: shallow, standard, deep');
+    return;
+  }
+
+  const workflow = new AnalyzeWorkflowEngine(projectRoot, { depth });
+
+  // Check for existing workflow
+  if (workflow.hasWorkflow()) {
+    workflow.loadState();
+    const progress = workflow.getProgress();
+
+    if (!progress.isComplete) {
+      utils.print.info('Existing analysis workflow found.');
+      console.log(`  Progress: ${progress.overall.percentage}% complete`);
+      console.log(`  Current phase: ${progress.currentPhase || 'none'}`);
+      console.log('');
+      utils.print.info('Use "bootspring analyze resume" to continue');
+      utils.print.info('Use "bootspring analyze reset" to start fresh');
+      return;
+    }
+  }
+
+  // Initialize new workflow
+  utils.print.header('Codebase Analysis');
+  const depthConfig = ANALYSIS_DEPTH[depth];
+  console.log(`Analysis depth: ${depth} (${depthConfig?.description || 'unknown'})`);
+  console.log('');
+
+  workflow.initializeWorkflow(depth);
+
+  // Run workflow
+  await runWorkflowLoop(workflow);
+}
+
+/**
+ * Resume analysis workflow
+ */
+async function analyzeResume(): Promise<void> {
+  const workflow = new AnalyzeWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.error('No existing workflow found.');
+    utils.print.info('Run "bootspring analyze" to start.');
+    return;
+  }
+
+  workflow.loadState();
+  const resumePoint = workflow.getResumePoint();
+
+  if (!resumePoint) {
+    utils.print.success('Analysis workflow already complete!');
+    displayCompletionSummary(workflow);
+    return;
+  }
+
+  utils.print.header('Resuming Analysis');
+  console.log(`Continuing from: ${resumePoint.phaseName}`);
+  console.log('');
+
+  await runWorkflowLoop(workflow);
+}
+
+/**
+ * Run the workflow loop
+ */
+async function runWorkflowLoop(workflow: AnalyzeWorkflowEngine): Promise<void> {
+  while (true) {
+    const nextPhaseId = workflow.getNextPhase();
+
+    if (!nextPhaseId) {
+      // Workflow complete
+      break;
+    }
+
+    const phase = ANALYZE_PHASES[nextPhaseId];
+    if (!phase) {
+      continue;
+    }
+
+    // Run the phase
+    workflow.startPhase(nextPhaseId);
+    const spinner = utils.createSpinner(`Running: ${phase.name}`).start();
+
+    try {
+      let result: unknown;
+
+      switch (nextPhaseId) {
+        case 'structure': {
+          const structureResult = await workflow.runStructureMapping();
+          spinner.succeed(`Structure mapped: ${structureResult.totalFiles} files, ${structureResult.totalDirs} directories`);
+          displayStructureResults(structureResult);
+          result = structureResult;
+          break;
+        }
+
+        case 'architecture': {
+          const archResult = await workflow.runArchitectureAnalysis();
+          spinner.succeed(`Architecture analyzed: ${archResult.patterns.length} patterns found`);
+          displayArchitectureResults(archResult);
+          result = archResult;
+          break;
+        }
+
+        case 'dependencies': {
+          const depResult = await workflow.runDependencyAnalysis();
+          if (depResult.skipped) {
+            spinner.succeed(`Dependencies skipped: Large codebase (${depResult.fileCount} files)`);
+            console.log('');
+            console.log(`  ${utils.COLORS.dim}Use --depth=deep to force full analysis${utils.COLORS.reset}`);
+          } else {
+            spinner.succeed(`Dependencies analyzed: ${depResult.fileCount} files`);
+            displayDependencyResults(depResult);
+          }
+          result = depResult;
+          break;
+        }
+
+        case 'patterns': {
+          const patternResult = await workflow.runPatternDetection();
+          spinner.succeed('Pattern detection complete');
+          displayPatternResults(patternResult);
+          result = patternResult;
+          break;
+        }
+
+        case 'flows': {
+          const flowResult = await workflow.runFlowTracing();
+          spinner.succeed(`Flow tracing complete: ${flowResult.entryPoints} entry points, ${flowResult.apiEndpoints} API endpoints`);
+          result = flowResult;
+          break;
+        }
+
+        case 'components': {
+          const componentResult = await workflow.runComponentAnalysis();
+          spinner.succeed(`Component analysis complete: ${componentResult.total} components`);
+          result = componentResult;
+          break;
+        }
+
+        case 'report': {
+          const reportResult = await workflow.runReportGeneration();
+          spinner.succeed('Report generated');
+          displayReportResults(reportResult);
+          result = reportResult;
+          break;
+        }
+
+        default:
+          spinner.warn(`Unknown phase: ${nextPhaseId}`);
+          continue;
+      }
+
+      workflow.completePhase(nextPhaseId, result);
+
+    } catch (error) {
+      spinner.fail(`Failed: ${(error as Error).message}`);
+      workflow.failPhase(nextPhaseId, (error as Error).message);
+
+      if (phase.required) {
+        utils.print.error('Required phase failed. Cannot continue.');
+        return;
+      }
+    }
+
+    console.log('');
+  }
+
+  // Workflow complete
+  displayCompletionSummary(workflow);
+}
+
+/**
+ * Display structure results
+ */
+function displayStructureResults(result: StructureResult): void {
+  console.log('');
+  console.log(`  ${utils.COLORS.cyan}Structure:${utils.COLORS.reset} ${result.structureType?.pattern || 'flat'}`);
+
+  if (result.keyDirectories.length > 0) {
+    console.log(`  ${utils.COLORS.cyan}Key dirs:${utils.COLORS.reset} ${result.keyDirectories.slice(0, 5).join(', ')}`);
+  }
+
+  if (result.entryPoints > 0) {
+    console.log(`  ${utils.COLORS.cyan}Entry points:${utils.COLORS.reset} ${result.entryPoints}`);
+  }
+}
+
+/**
+ * Display architecture results
+ */
+function displayArchitectureResults(result: ArchitectureResult): void {
+  if (result.patterns.length > 0) {
+    console.log('');
+    console.log('  Detected patterns:');
+    for (const pattern of result.patterns.slice(0, 3)) {
+      console.log(`    - ${pattern.name} (${pattern.confidence}%)`);
+    }
+  }
+
+  if (result.layers.length > 0) {
+    console.log('');
+    console.log(`  ${utils.COLORS.cyan}Layers:${utils.COLORS.reset} ${result.layers.join(', ')}`);
+  }
+
+  if (result.modules > 0) {
+    console.log(`  ${utils.COLORS.cyan}Modules:${utils.COLORS.reset} ${result.modules}`);
+  }
+}
+
+/**
+ * Display dependency results
+ */
+function displayDependencyResults(result: DependencyResult): void {
+  console.log('');
+
+  if (result.circularCount > 0) {
+    console.log(`  ${utils.COLORS.yellow}⚠${utils.COLORS.reset} Circular dependencies: ${result.circularCount}`);
+  } else {
+    console.log(`  ${utils.COLORS.green}✓${utils.COLORS.reset} No circular dependencies`);
+  }
+
+  if (result.unusedCount > 0) {
+    console.log(`  ${utils.COLORS.yellow}○${utils.COLORS.reset} Potentially unused packages: ${result.unusedCount}`);
+  }
+
+  console.log(`  ${utils.COLORS.cyan}External packages:${utils.COLORS.reset} ${result.externalPackages}`);
+
+  if (result.mostImported.length > 0) {
+    console.log('');
+    console.log('  Most imported files:');
+    for (const file of result.mostImported.slice(0, 3)) {
+      console.log(`    - ${file.file} (${file.importCount} imports)`);
+    }
+  }
+}
+
+/**
+ * Display pattern results
+ */
+function displayPatternResults(result: PatternResult): void {
+  console.log('');
+  console.log(`  ${utils.COLORS.cyan}Design patterns:${utils.COLORS.reset} ${result.designPatterns}`);
+  console.log(`  ${utils.COLORS.cyan}Anti-patterns:${utils.COLORS.reset} ${result.antiPatterns}`);
+}
+
+/**
+ * Display report results
+ */
+function displayReportResults(result: ReportResult): void {
+  console.log('');
+  utils.print.success(`Report saved to: ${result.reportPath}`);
+}
+
+/**
+ * Display completion summary
+ */
+function displayCompletionSummary(workflow: AnalyzeWorkflowEngine): void {
+  const progress = workflow.getProgress();
+
+  console.log('');
+  utils.print.success('Analysis complete!');
+  console.log('');
+
+  // Show summary
+  utils.print.header('Summary');
+  console.log(`  Phases completed: ${progress.overall.completed}/${progress.overall.total}`);
+  console.log(`  Depth: ${progress.depth}`);
+
+  if (progress.summary?.reportPath) {
+    console.log('');
+    console.log('  Reports generated:');
+    console.log(`    ${utils.COLORS.green}✓${utils.COLORS.reset} ${progress.summary.reportPath}`);
+    console.log(`    ${utils.COLORS.green}✓${utils.COLORS.reset} .bootspring/analyze/reports/architecture.md`);
+    console.log(`    ${utils.COLORS.green}✓${utils.COLORS.reset} .bootspring/analyze/reports/dependencies.md`);
+  }
+
+  console.log('');
+  utils.print.info('Next steps:');
+  console.log('  1. Review the analysis report');
+  console.log('  2. Run "bootspring audit" for quality & security checks');
+}
+
+/**
+ * Show analysis status
+ */
+async function analyzeStatus(): Promise<void> {
+  const workflow = new AnalyzeWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.info('No analysis workflow started.');
+    utils.print.info('Run "bootspring analyze" to begin.');
+    return;
+  }
+
+  workflow.loadState();
+  const progress = workflow.getProgress();
+
+  utils.print.header('Analysis Status');
+
+  // Overall progress
+  console.log(`Progress: ${progress.overall.percentage}% complete`);
+  console.log(`Depth: ${progress.depth}`);
+  console.log(`Started: ${progress.startedAt ? new Date(progress.startedAt).toLocaleString() : 'N/A'}`);
+  console.log(`Last updated: ${progress.lastUpdated ? utils.formatRelativeTime(new Date(progress.lastUpdated)) : 'N/A'}`);
+  console.log('');
+
+  // Phase status
+  console.log('Phases:');
+  for (const phase of progress.phases) {
+    const statusIcon = getStatusIcon(phase.status);
+    const required = phase.required ? '' : ' (optional)';
+    console.log(`  ${statusIcon} ${phase.name}${required}`);
+  }
+
+  if (progress.summary?.reportPath) {
+    console.log('');
+    console.log(`Report: ${progress.summary.reportPath}`);
+  }
+
+  if (!progress.isComplete) {
+    console.log('');
+    utils.print.info('Run "bootspring analyze resume" to continue');
+  }
+}
+
+/**
+ * Run specific phase
+ */
+async function analyzePhase(args: ParsedArgs): Promise<void> {
+  const phaseId = args.phase;
+
+  if (!phaseId || !ANALYZE_PHASES[phaseId]) {
+    utils.print.error(`Unknown phase: ${phaseId}`);
+    console.log('');
+    console.log('Available phases:');
+    for (const [id, phase] of Object.entries(ANALYZE_PHASES)) {
+      console.log(`  ${id}: ${phase.description}`);
+    }
+    return;
+  }
+
+  const workflow = new AnalyzeWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    workflow.initializeWorkflow('standard');
+  } else {
+    workflow.loadState();
+  }
+
+  const phase = ANALYZE_PHASES[phaseId];
+  if (!phase) return;
+
+  const spinner = utils.createSpinner(`Running: ${phase.name}`).start();
+
+  try {
+    let result: unknown;
+
+    switch (phaseId) {
+      case 'structure':
+        result = await workflow.runStructureMapping();
+        break;
+      case 'architecture':
+        result = await workflow.runArchitectureAnalysis();
+        break;
+      case 'dependencies':
+        result = await workflow.runDependencyAnalysis();
+        break;
+      case 'patterns':
+        result = await workflow.runPatternDetection();
+        break;
+      case 'flows':
+        result = await workflow.runFlowTracing();
+        break;
+      case 'components':
+        result = await workflow.runComponentAnalysis();
+        break;
+      case 'report':
+        result = await workflow.runReportGeneration();
+        break;
+    }
+
+    spinner.succeed(`${phase.name} complete`);
+    console.log('');
+    console.log('Result:', JSON.stringify(result, null, 2));
+
+  } catch (error) {
+    spinner.fail(`Failed: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Reset analysis workflow
+ */
+async function analyzeReset(): Promise<void> {
+  const workflow = new AnalyzeWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.info('No workflow to reset.');
+    return;
+  }
+
+  workflow.resetWorkflow();
+  utils.print.success('Analysis workflow reset.');
+}
+
+/**
+ * Get status icon
+ */
+function getStatusIcon(status: string): string {
+  switch (status) {
+    case 'completed':
+      return `${utils.COLORS.green}✓${utils.COLORS.reset}`;
+    case 'in_progress':
+      return `${utils.COLORS.cyan}●${utils.COLORS.reset}`;
+    case 'failed':
+      return `${utils.COLORS.red}✗${utils.COLORS.reset}`;
+    case 'skipped':
+      return `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+    default:
+      return `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+  }
+}
+
+/**
+ * Main entry point
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsedArgs = utils.parseArgs(args) as ParsedArgs;
+  const subcommand = parsedArgs._[0];
+
+  // Handle --phase flag
+  if (parsedArgs.phase) {
+    return analyzePhase(parsedArgs);
+  }
+
+  switch (subcommand) {
+    case 'status':
+      return analyzeStatus();
+
+    case 'resume':
+      return analyzeResume();
+
+    case 'reset':
+      return analyzeReset();
+
+    case 'help':
+    case '--help':
+    case '-h':
+      return showHelp();
+
+    default:
+      // Start analysis
+      return analyzeStart(parsedArgs);
+  }
+}