@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/audit.ts

@@ -0,0 +1,707 @@
+/**
+ * Bootspring Audit CLI
+ *
+ * Quality, security, and best practices audit for codebases.
+ * Generates prioritized recommendations and remediation tasks.
+ *
+ * @package bootspring
+ * @module cli/audit
+ */
+
+// Import JS modules with type interfaces
+interface ParsedArgs {
+  _: string[];
+  phase?: string | undefined;
+  severity?: string | undefined;
+  fix?: boolean | undefined;
+  ci?: boolean | undefined;
+}
+
+interface PhaseConfig {
+  name: string;
+  description: string;
+  required: boolean;
+}
+
+interface QualityResult {
+  score: number;
+  breakdown: {
+    complexity: number;
+    maintainability: number;
+    documentation: number;
+    codeSmells: number;
+  };
+  totalIssues: number;
+  totalFiles: number;
+}
+
+interface SecurityResult {
+  passed: boolean;
+  total: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+}
+
+interface PerformanceResult {
+  score: number;
+}
+
+interface PracticesResult {
+  passed: number;
+  total: number;
+  checks: Record<string, {
+    passed: boolean;
+    issues: Array<{ title: string }>;
+  }>;
+}
+
+interface TechDebtResult {
+  todos: number;
+  unusedDeps: number;
+  testCoverage: number;
+  depAnalysisSkipped?: boolean | undefined;
+}
+
+interface RecommendationsResult {
+  reportPath: string;
+  passed: boolean;
+}
+
+interface FindingsSummary {
+  total: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+}
+
+interface OverallProgress {
+  completed: number;
+  total: number;
+  percentage: number;
+}
+
+interface PhaseProgress {
+  name: string;
+  status: string;
+  required: boolean;
+}
+
+interface WorkflowProgress {
+  overall: OverallProgress;
+  isComplete: boolean;
+  findings: FindingsSummary;
+  phases: PhaseProgress[];
+  startedAt?: string | undefined;
+  lastUpdated?: string | undefined;
+  summary?: {
+    reportPath?: string | undefined;
+  } | undefined;
+}
+
+interface ResumePoint {
+  phaseName: string;
+  findingsCount: number;
+}
+
+interface AuditWorkflowEngineClass {
+  new (projectRoot: string, options?: AuditOptions): AuditWorkflowEngine;
+}
+
+interface AuditOptions {
+  severityFilter?: string | null | undefined;
+  ciMode?: boolean | undefined;
+}
+
+interface AuditWorkflowEngine {
+  hasWorkflow(): boolean;
+  loadState(): void;
+  initializeWorkflow(): 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;
+  getExitCode(): number;
+  runQualityMetrics(): Promise<QualityResult>;
+  runSecurityScan(): Promise<SecurityResult>;
+  runPerformanceAnalysis(): Promise<PerformanceResult>;
+  runBestPractices(): Promise<PracticesResult>;
+  runTechDebtInventory(): Promise<TechDebtResult>;
+  runRecommendations(): Promise<RecommendationsResult>;
+}
+
+interface AuditWorkflowModule {
+  AuditWorkflowEngine: AuditWorkflowEngineClass;
+  AUDIT_PHASES: Record<string, PhaseConfig>;
+  SEVERITY_LEVELS: Record<string, unknown>;
+}
+
+// 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 auditWorkflowModule = require('../../core/audit-workflow') as AuditWorkflowModule;
+
+const { AuditWorkflowEngine, AUDIT_PHASES } = auditWorkflowModule;
+
+// Get project root
+const projectRoot = process.cwd();
+
+/**
+ * Show audit help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.bold}Bootspring Audit${utils.COLORS.reset}
+Quality, security, and best practices audit
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring audit                Full audit
+  bootspring audit status         Show progress
+  bootspring audit resume         Continue from checkpoint
+  bootspring audit reset          Reset workflow
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --phase=<phase>                 Run specific phase only
+  --severity=<level>              Filter by severity (critical, high, medium, low)
+  --fix                           Auto-fix safe issues (where possible)
+  --ci                            CI mode with exit codes
+
+${utils.COLORS.bold}Phases:${utils.COLORS.reset}
+  quality       Code quality metrics (complexity, duplication)
+  security      Security scan (secrets, vulnerabilities)
+  performance   Performance analysis
+  practices     Best practices checks
+  techDebt      Tech debt inventory
+  recommendations Generate prioritized recommendations
+
+${utils.COLORS.bold}Exit Codes (CI Mode):${utils.COLORS.reset}
+  0   All checks passed
+  1   High severity issues found
+  2   Critical issues found
+
+${utils.COLORS.bold}Notes:${utils.COLORS.reset}
+  Large codebases (500+ files) automatically skip heavy dependency
+  analysis in the tech debt phase for performance.
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring audit              Auto-adjusts for codebase size
+  bootspring audit --phase=security
+  bootspring audit --severity=high
+  bootspring audit --ci
+`);
+}
+
+/**
+ * Start audit workflow
+ */
+async function auditStart(args: ParsedArgs): Promise<void> {
+  const workflow = new AuditWorkflowEngine(projectRoot, {
+    severityFilter: args.severity || null,
+    ciMode: args.ci || false
+  });
+
+  // Check for existing workflow
+  if (workflow.hasWorkflow()) {
+    workflow.loadState();
+    const progress = workflow.getProgress();
+
+    if (!progress.isComplete) {
+      utils.print.info('Existing audit workflow found.');
+      console.log(`  Progress: ${progress.overall.percentage}% complete`);
+      console.log(`  Findings: ${progress.findings.total}`);
+      console.log('');
+      utils.print.info('Use "bootspring audit resume" to continue');
+      utils.print.info('Use "bootspring audit reset" to start fresh');
+      return;
+    }
+  }
+
+  // Initialize new workflow
+  utils.print.header('Codebase Audit');
+  console.log('Running quality, security, and best practices checks...');
+  console.log('');
+
+  workflow.initializeWorkflow();
+
+  // Run workflow
+  await runWorkflowLoop(workflow, args);
+}
+
+/**
+ * Resume audit workflow
+ */
+async function auditResume(args: ParsedArgs): Promise<void> {
+  const workflow = new AuditWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.error('No existing workflow found.');
+    utils.print.info('Run "bootspring audit" to start.');
+    return;
+  }
+
+  workflow.loadState();
+  const resumePoint = workflow.getResumePoint();
+
+  if (!resumePoint) {
+    utils.print.success('Audit workflow already complete!');
+    displayCompletionSummary(workflow, args);
+    return;
+  }
+
+  utils.print.header('Resuming Audit');
+  console.log(`Continuing from: ${resumePoint.phaseName}`);
+  console.log(`Current findings: ${resumePoint.findingsCount}`);
+  console.log('');
+
+  await runWorkflowLoop(workflow, args);
+}
+
+/**
+ * Run the workflow loop
+ */
+async function runWorkflowLoop(workflow: AuditWorkflowEngine, args: ParsedArgs): Promise<void> {
+  while (true) {
+    const nextPhaseId = workflow.getNextPhase();
+
+    if (!nextPhaseId) {
+      // Workflow complete
+      break;
+    }
+
+    const phase = AUDIT_PHASES[nextPhaseId];
+    if (!phase) continue;
+
+    // Skip optional phases
+    if (!phase.required) {
+      // For now, skip optional phases in basic flow
+      workflow.skipPhase(nextPhaseId);
+      continue;
+    }
+
+    // Run the phase
+    workflow.startPhase(nextPhaseId);
+    const spinner = utils.createSpinner(`Running: ${phase.name}`).start();
+
+    try {
+      let result: unknown;
+
+      switch (nextPhaseId) {
+        case 'quality': {
+          const qualityResult = await workflow.runQualityMetrics();
+          spinner.succeed(`Quality metrics: Score ${qualityResult.score}/100`);
+          displayQualityResults(qualityResult);
+          result = qualityResult;
+          break;
+        }
+
+        case 'security': {
+          const securityResult = await workflow.runSecurityScan();
+          if (securityResult.critical > 0) {
+            spinner.fail(`Security scan: ${securityResult.critical} CRITICAL issues found`);
+          } else if (securityResult.high > 0) {
+            spinner.warn(`Security scan: ${securityResult.high} high severity issues found`);
+          } else if (securityResult.passed) {
+            spinner.succeed('Security scan: PASSED');
+          } else {
+            spinner.succeed(`Security scan: ${securityResult.total} findings`);
+          }
+          displaySecurityResults(securityResult);
+          result = securityResult;
+          break;
+        }
+
+        case 'performance': {
+          const perfResult = await workflow.runPerformanceAnalysis();
+          spinner.succeed('Performance analysis complete');
+          result = perfResult;
+          break;
+        }
+
+        case 'practices': {
+          const practicesResult = await workflow.runBestPractices();
+          spinner.succeed(`Best practices: ${practicesResult.passed}/${practicesResult.total} checks passed`);
+          displayPracticesResults(practicesResult);
+          result = practicesResult;
+          break;
+        }
+
+        case 'techDebt': {
+          const techDebtResult = await workflow.runTechDebtInventory();
+          if (techDebtResult.depAnalysisSkipped) {
+            spinner.succeed(`Tech debt: ${techDebtResult.todos} TODOs (dep analysis skipped - large codebase)`);
+          } else {
+            spinner.succeed(`Tech debt: ${techDebtResult.todos} TODOs, ${techDebtResult.unusedDeps} unused deps`);
+          }
+          displayTechDebtResults(techDebtResult);
+          result = techDebtResult;
+          break;
+        }
+
+        case 'recommendations': {
+          const recsResult = await workflow.runRecommendations();
+          spinner.succeed('Recommendations generated');
+          displayRecommendationsResults(recsResult);
+          result = recsResult;
+          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, args);
+}
+
+/**
+ * Display quality results
+ */
+function displayQualityResults(result: QualityResult): void {
+  console.log('');
+  console.log(`  ${utils.COLORS.cyan}Complexity:${utils.COLORS.reset} ${result.breakdown.complexity}/100`);
+  console.log(`  ${utils.COLORS.cyan}Maintainability:${utils.COLORS.reset} ${result.breakdown.maintainability}/100`);
+  console.log(`  ${utils.COLORS.cyan}Documentation:${utils.COLORS.reset} ${result.breakdown.documentation}/100`);
+  console.log(`  ${utils.COLORS.cyan}Code Smells:${utils.COLORS.reset} ${result.breakdown.codeSmells}/100`);
+
+  if (result.totalIssues > 0) {
+    console.log('');
+    console.log(`  ${utils.COLORS.yellow}○${utils.COLORS.reset} ${result.totalIssues} issues found across ${result.totalFiles} files`);
+  }
+}
+
+/**
+ * Display security results
+ */
+function displaySecurityResults(result: SecurityResult): void {
+  if (result.total > 0) {
+    console.log('');
+    console.log('  Findings:');
+
+    if (result.critical > 0) {
+      console.log(`    ${utils.COLORS.red}●${utils.COLORS.reset} Critical: ${result.critical}`);
+    }
+    if (result.high > 0) {
+      console.log(`    ${utils.COLORS.yellow}●${utils.COLORS.reset} High: ${result.high}`);
+    }
+    if (result.medium > 0) {
+      console.log(`    ${utils.COLORS.yellow}○${utils.COLORS.reset} Medium: ${result.medium}`);
+    }
+    if (result.low > 0) {
+      console.log(`    ${utils.COLORS.dim}○${utils.COLORS.reset} Low: ${result.low}`);
+    }
+  }
+}
+
+/**
+ * Display best practices results
+ */
+function displayPracticesResults(result: PracticesResult): void {
+  if (result.passed < result.total) {
+    console.log('');
+    for (const [, check] of Object.entries(result.checks)) {
+      if (!check.passed) {
+        for (const issue of check.issues.slice(0, 2)) {
+          console.log(`  ${utils.COLORS.yellow}○${utils.COLORS.reset} ${issue.title}`);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Display tech debt results
+ */
+function displayTechDebtResults(result: TechDebtResult): void {
+  console.log('');
+  console.log(`  ${utils.COLORS.cyan}Test coverage:${utils.COLORS.reset} ${result.testCoverage}%`);
+
+  if (result.todos > 0) {
+    console.log(`  ${utils.COLORS.yellow}○${utils.COLORS.reset} ${result.todos} TODO/FIXME comments`);
+  }
+
+  if (result.unusedDeps > 0) {
+    console.log(`  ${utils.COLORS.yellow}○${utils.COLORS.reset} ${result.unusedDeps} potentially unused dependencies`);
+  }
+}
+
+/**
+ * Display recommendations results
+ */
+function displayRecommendationsResults(result: RecommendationsResult): void {
+  console.log('');
+  utils.print.success(`Report saved to: ${result.reportPath}`);
+
+  if (!result.passed) {
+    console.log('');
+    utils.print.warning('Audit found issues that need attention.');
+  }
+}
+
+/**
+ * Display completion summary
+ */
+function displayCompletionSummary(workflow: AuditWorkflowEngine, args: ParsedArgs): void {
+  const progress = workflow.getProgress();
+
+  console.log('');
+
+  // Show audit result
+  if (progress.findings.critical > 0) {
+    utils.print.error('Audit FAILED: Critical issues found');
+  } else if (progress.findings.high > 0) {
+    utils.print.warning('Audit completed with high severity issues');
+  } else {
+    utils.print.success('Audit completed successfully!');
+  }
+
+  console.log('');
+
+  // Show findings summary
+  utils.print.header('Findings Summary');
+
+  console.log('');
+  console.log(`  Total findings: ${progress.findings.total}`);
+  console.log('');
+
+  if (progress.findings.critical > 0) {
+    console.log(`  ${utils.COLORS.red}● Critical:${utils.COLORS.reset} ${progress.findings.critical} ${utils.COLORS.dim}(immediate action required)${utils.COLORS.reset}`);
+  }
+  if (progress.findings.high > 0) {
+    console.log(`  ${utils.COLORS.yellow}● High:${utils.COLORS.reset} ${progress.findings.high} ${utils.COLORS.dim}(fix within 1-2 days)${utils.COLORS.reset}`);
+  }
+  if (progress.findings.medium > 0) {
+    console.log(`  ${utils.COLORS.yellow}○ Medium:${utils.COLORS.reset} ${progress.findings.medium} ${utils.COLORS.dim}(plan within 1-2 weeks)${utils.COLORS.reset}`);
+  }
+  if (progress.findings.low > 0) {
+    console.log(`  ${utils.COLORS.dim}○ Low:${utils.COLORS.reset} ${progress.findings.low} ${utils.COLORS.dim}(add to backlog)${utils.COLORS.reset}`);
+  }
+
+  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/audit/reports/quality.md`);
+    console.log(`    ${utils.COLORS.green}✓${utils.COLORS.reset} .bootspring/audit/reports/security.md`);
+    console.log(`    ${utils.COLORS.green}✓${utils.COLORS.reset} .bootspring/audit/reports/tech-debt.md`);
+  }
+
+  console.log('');
+  utils.print.info('Review the detailed report for remediation steps.');
+
+  // CI mode exit code
+  if (args?.ci) {
+    const exitCode = workflow.getExitCode();
+    process.exitCode = exitCode;
+    console.log('');
+    console.log(`CI exit code: ${exitCode}`);
+  }
+}
+
+/**
+ * Show audit status
+ */
+async function auditStatus(): Promise<void> {
+  const workflow = new AuditWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.info('No audit workflow started.');
+    utils.print.info('Run "bootspring audit" to begin.');
+    return;
+  }
+
+  workflow.loadState();
+  const progress = workflow.getProgress();
+
+  utils.print.header('Audit Status');
+
+  // Overall progress
+  console.log(`Progress: ${progress.overall.percentage}% complete`);
+  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}`);
+  }
+
+  // Findings summary
+  if (progress.findings.total > 0) {
+    console.log('');
+    console.log('Findings so far:');
+    console.log(`  Critical: ${progress.findings.critical}`);
+    console.log(`  High: ${progress.findings.high}`);
+    console.log(`  Medium: ${progress.findings.medium}`);
+    console.log(`  Low: ${progress.findings.low}`);
+  }
+
+  if (progress.summary?.reportPath) {
+    console.log('');
+    console.log(`Report: ${progress.summary.reportPath}`);
+  }
+
+  if (!progress.isComplete) {
+    console.log('');
+    utils.print.info('Run "bootspring audit resume" to continue');
+  }
+}
+
+/**
+ * Run specific phase
+ */
+async function auditPhase(args: ParsedArgs): Promise<void> {
+  const phaseId = args.phase;
+
+  if (!phaseId || !AUDIT_PHASES[phaseId]) {
+    utils.print.error(`Unknown phase: ${phaseId}`);
+    console.log('');
+    console.log('Available phases:');
+    for (const [id, phase] of Object.entries(AUDIT_PHASES)) {
+      console.log(`  ${id}: ${phase.description}`);
+    }
+    return;
+  }
+
+  const workflow = new AuditWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    workflow.initializeWorkflow();
+  } else {
+    workflow.loadState();
+  }
+
+  const phase = AUDIT_PHASES[phaseId];
+  if (!phase) return;
+
+  const spinner = utils.createSpinner(`Running: ${phase.name}`).start();
+
+  try {
+    let result: unknown;
+
+    switch (phaseId) {
+      case 'quality':
+        result = await workflow.runQualityMetrics();
+        break;
+      case 'security':
+        result = await workflow.runSecurityScan();
+        break;
+      case 'performance':
+        result = await workflow.runPerformanceAnalysis();
+        break;
+      case 'practices':
+        result = await workflow.runBestPractices();
+        break;
+      case 'techDebt':
+        result = await workflow.runTechDebtInventory();
+        break;
+      case 'recommendations':
+        result = await workflow.runRecommendations();
+        break;
+    }
+
+    spinner.succeed(`${phase.name} complete`);
+    console.log('');
+    console.log('Result:', JSON.stringify(result, null, 2));
+
+    // Show findings for this phase
+    const progress = workflow.getProgress();
+    if (progress.findings.total > 0) {
+      console.log('');
+      console.log(`Findings: ${progress.findings.total}`);
+    }
+
+  } catch (error) {
+    spinner.fail(`Failed: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Reset audit workflow
+ */
+async function auditReset(): Promise<void> {
+  const workflow = new AuditWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.info('No workflow to reset.');
+    return;
+  }
+
+  workflow.resetWorkflow();
+  utils.print.success('Audit 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 auditPhase(parsedArgs);
+  }
+
+  switch (subcommand) {
+    case 'status':
+      return auditStatus();
+
+    case 'resume':
+      return auditResume(parsedArgs);
+
+    case 'reset':
+      return auditReset();
+
+    case 'help':
+    case '--help':
+    case '-h':
+      return showHelp();
+
+    default:
+      // Start audit
+      return auditStart(parsedArgs);
+  }
+}