@girardmedia/bootspring 1.2.0 → 2.0.3

package/cli/audit.js

@@ -0,0 +1,557 @@
+/**
+ * Bootspring Audit CLI
+ *
+ * Quality, security, and best practices audit for codebases.
+ * Generates prioritized recommendations and remediation tasks.
+ *
+ * @package bootspring
+ * @module cli/audit
+ */
+
+const path = require('path');
+const utils = require('../core/utils');
+const { AuditWorkflowEngine, AUDIT_PHASES, SEVERITY_LEVELS } = require('../core/audit-workflow');
+
+// Get project root
+const projectRoot = process.cwd();
+
+/**
+ * Show audit help
+ */
+function showHelp() {
+  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) {
+  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) {
+  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, args) {
+  while (true) {
+    const nextPhaseId = workflow.getNextPhase();
+
+    if (!nextPhaseId) {
+      // Workflow complete
+      break;
+    }
+
+    const phase = AUDIT_PHASES[nextPhaseId];
+
+    // 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;
+
+      switch (nextPhaseId) {
+        case 'quality':
+          result = await workflow.runQualityMetrics();
+          spinner.succeed(`Quality metrics: Score ${result.score}/100`);
+          displayQualityResults(result);
+          break;
+
+        case 'security':
+          result = await workflow.runSecurityScan();
+          if (result.critical > 0) {
+            spinner.fail(`Security scan: ${result.critical} CRITICAL issues found`);
+          } else if (result.high > 0) {
+            spinner.warn(`Security scan: ${result.high} high severity issues found`);
+          } else if (result.passed) {
+            spinner.succeed('Security scan: PASSED');
+          } else {
+            spinner.succeed(`Security scan: ${result.total} findings`);
+          }
+          displaySecurityResults(result);
+          break;
+
+        case 'performance':
+          result = await workflow.runPerformanceAnalysis();
+          spinner.succeed('Performance analysis complete');
+          break;
+
+        case 'practices':
+          result = await workflow.runBestPractices();
+          spinner.succeed(`Best practices: ${result.passed}/${result.total} checks passed`);
+          displayPracticesResults(result);
+          break;
+
+        case 'techDebt':
+          result = await workflow.runTechDebtInventory();
+          if (result.depAnalysisSkipped) {
+            spinner.succeed(`Tech debt: ${result.todos} TODOs (dep analysis skipped - large codebase)`);
+          } else {
+            spinner.succeed(`Tech debt: ${result.todos} TODOs, ${result.unusedDeps} unused deps`);
+          }
+          displayTechDebtResults(result);
+          break;
+
+        case 'recommendations':
+          result = await workflow.runRecommendations();
+          spinner.succeed('Recommendations generated');
+          displayRecommendationsResults(result);
+          break;
+
+        default:
+          spinner.warn(`Unknown phase: ${nextPhaseId}`);
+          continue;
+      }
+
+      workflow.completePhase(nextPhaseId, result);
+
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      workflow.failPhase(nextPhaseId, 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) {
+  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) {
+  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) {
+  if (result.passed < result.total) {
+    console.log('');
+    for (const [checkId, 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) {
+  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) {
+  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, args) {
+  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() {
+  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) {
+  const phaseId = args.phase;
+
+  if (!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];
+  const spinner = utils.createSpinner(`Running: ${phase.name}`).start();
+
+  try {
+    let result;
+
+    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.message}`);
+  }
+}
+
+/**
+ * Reset audit workflow
+ */
+async function auditReset() {
+  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) {
+  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
+ */
+async function run(args) {
+  const parsedArgs = utils.parseArgs(args);
+  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);
+  }
+}
+
+module.exports = { run };