@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/audit-workflow.js

@@ -0,0 +1,1350 @@
+/**
+ * Bootspring Audit Workflow Engine
+ *
+ * Quality, security, and best practices audit for codebases.
+ * Generates prioritized recommendations and remediation tasks.
+ *
+ * @package bootspring
+ * @module core/audit-workflow
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SecurityScanner, SEVERITY } = require('../analyzers/security-scanner');
+const { QualityAnalyzer } = require('../analyzers/quality-analyzer');
+const { DependencyAnalyzer } = require('../analyzers/dependency-analyzer');
+
+/**
+ * Workflow phase status
+ */
+const PHASE_STATUS = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped',
+  FAILED: 'failed'
+};
+
+/**
+ * Audit phases
+ */
+const AUDIT_PHASES = {
+  quality: {
+    name: 'Quality Metrics',
+    description: 'Complexity, duplication, comments, naming',
+    order: 1,
+    required: true
+  },
+  security: {
+    name: 'Security Scan',
+    description: 'Secrets, vulnerabilities, OWASP, injection',
+    order: 2,
+    required: true
+  },
+  performance: {
+    name: 'Performance Analysis',
+    description: 'Bundle size, lazy loading, N+1 queries',
+    order: 3,
+    required: false,
+    dependencies: ['quality']
+  },
+  practices: {
+    name: 'Best Practices',
+    description: 'TypeScript strict, error handling, env vars',
+    order: 4,
+    required: true
+  },
+  techDebt: {
+    name: 'Tech Debt Inventory',
+    description: 'TODOs, deprecated APIs, dead code, missing tests',
+    order: 5,
+    required: true,
+    dependencies: ['quality']
+  },
+  recommendations: {
+    name: 'Recommendations',
+    description: 'Prioritize (P0-P3), estimate effort, generate tasks',
+    order: 6,
+    required: true,
+    dependencies: ['quality', 'security', 'practices', 'techDebt']
+  }
+};
+
+/**
+ * Finding severity levels with actions
+ */
+const SEVERITY_LEVELS = {
+  critical: {
+    label: 'CRITICAL',
+    color: 'red',
+    action: 'Immediate fix required',
+    priority: 0
+  },
+  high: {
+    label: 'HIGH',
+    color: 'orange',
+    action: 'Fix within 1-2 days',
+    priority: 1
+  },
+  medium: {
+    label: 'MEDIUM',
+    color: 'yellow',
+    action: 'Plan fix within 1-2 weeks',
+    priority: 2
+  },
+  low: {
+    label: 'LOW',
+    color: 'blue',
+    action: 'Add to backlog',
+    priority: 3
+  },
+  info: {
+    label: 'INFO',
+    color: 'gray',
+    action: 'Consider when convenient',
+    priority: 4
+  }
+};
+
+/**
+ * Default workflow state
+ */
+const DEFAULT_STATE = {
+  version: '1.0.0',
+  startedAt: null,
+  lastUpdated: null,
+  currentPhase: null,
+  phases: {},
+  findings: [],
+  summary: null
+};
+
+/**
+ * AuditWorkflowEngine - Manages audit workflow
+ */
+class AuditWorkflowEngine {
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.workflowDir = path.join(projectRoot, '.bootspring', 'audit');
+    this.stateFile = path.join(this.workflowDir, 'workflow-state.json');
+    this.reportsDir = path.join(this.workflowDir, 'reports');
+    this.findingsDir = path.join(this.workflowDir, 'findings');
+    this.options = {
+      severityFilter: options.severityFilter || null,
+      autoFix: options.autoFix || false,
+      ciMode: options.ciMode || false,
+      ...options
+    };
+    this.state = null;
+  }
+
+  /**
+   * Setup directories
+   */
+  setupDirectories() {
+    const dirs = [this.workflowDir, this.reportsDir, this.findingsDir];
+
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * Load workflow state
+   */
+  loadState() {
+    if (fs.existsSync(this.stateFile)) {
+      try {
+        this.state = JSON.parse(fs.readFileSync(this.stateFile, 'utf-8'));
+        return true;
+      } catch (_e) {
+        this.state = { ...DEFAULT_STATE };
+        return false;
+      }
+    }
+    this.state = { ...DEFAULT_STATE };
+    return false;
+  }
+
+  /**
+   * Save workflow state
+   */
+  saveState() {
+    this.setupDirectories();
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  /**
+   * Initialize workflow
+   */
+  initializeWorkflow() {
+    this.setupDirectories();
+    this.state = {
+      ...DEFAULT_STATE,
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+      findings: []
+    };
+
+    // Initialize phase states
+    for (const phaseId of Object.keys(AUDIT_PHASES)) {
+      this.state.phases[phaseId] = {
+        status: PHASE_STATUS.PENDING,
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+    }
+
+    this.state.currentPhase = 'quality';
+    this.saveState();
+    return this.state;
+  }
+
+  /**
+   * Check if workflow exists
+   */
+  hasWorkflow() {
+    return fs.existsSync(this.stateFile);
+  }
+
+  /**
+   * Reset workflow
+   */
+  resetWorkflow() {
+    if (fs.existsSync(this.stateFile)) {
+      fs.unlinkSync(this.stateFile);
+    }
+    this.state = null;
+    return true;
+  }
+
+  /**
+   * Check if phase dependencies are met
+   */
+  arePhaseDependenciesMet(phaseId) {
+    const phase = AUDIT_PHASES[phaseId];
+    if (!phase || !phase.dependencies || phase.dependencies.length === 0) {
+      return true;
+    }
+
+    for (const depPhaseId of phase.dependencies) {
+      const depPhase = this.state.phases[depPhaseId];
+      if (!depPhase || (depPhase.status !== PHASE_STATUS.COMPLETED && depPhase.status !== PHASE_STATUS.SKIPPED)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get next phase
+   */
+  getNextPhase() {
+    const phaseOrder = Object.keys(AUDIT_PHASES).sort(
+      (a, b) => AUDIT_PHASES[a].order - AUDIT_PHASES[b].order
+    );
+
+    for (const phaseId of phaseOrder) {
+      const phase = this.state.phases[phaseId];
+      if (phase.status === PHASE_STATUS.PENDING && this.arePhaseDependenciesMet(phaseId)) {
+        return phaseId;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Start a phase
+   */
+  startPhase(phaseId) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.IN_PROGRESS;
+    this.state.phases[phaseId].startedAt = new Date().toISOString();
+    this.state.currentPhase = phaseId;
+    this.saveState();
+  }
+
+  /**
+   * Complete a phase
+   */
+  completePhase(phaseId, result = null) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.COMPLETED;
+    this.state.phases[phaseId].completedAt = new Date().toISOString();
+    this.state.phases[phaseId].result = result;
+    this.saveState();
+  }
+
+  /**
+   * Fail a phase
+   */
+  failPhase(phaseId, error) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.FAILED;
+    this.state.phases[phaseId].completedAt = new Date().toISOString();
+    this.state.phases[phaseId].error = error;
+    this.saveState();
+  }
+
+  /**
+   * Skip a phase
+   */
+  skipPhase(phaseId) {
+    if (!this.state.phases[phaseId]) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    this.state.phases[phaseId].status = PHASE_STATUS.SKIPPED;
+    this.state.phases[phaseId].completedAt = new Date().toISOString();
+    this.saveState();
+  }
+
+  /**
+   * Add finding
+   */
+  addFinding(finding) {
+    this.state.findings.push({
+      ...finding,
+      id: `F${this.state.findings.length + 1}`,
+      timestamp: new Date().toISOString()
+    });
+    this.saveState();
+  }
+
+  /**
+   * Run quality metrics phase
+   */
+  async runQualityMetrics() {
+    const analyzer = new QualityAnalyzer(this.projectRoot);
+    const result = analyzer.analyze();
+
+    // Add findings for quality issues
+    for (const file of result.worstFiles) {
+      for (const issue of file.issues) {
+        this.addFinding({
+          phase: 'quality',
+          category: 'quality',
+          severity: issue.type === 'high-complexity' ? 'medium' : 'low',
+          title: issue.type,
+          description: issue.message,
+          file: file.path,
+          function: issue.function || null,
+          remediation: this.getQualityRemediation(issue.type)
+        });
+      }
+    }
+
+    // Add findings for code smells
+    for (const smell of result.smells) {
+      this.addFinding({
+        phase: 'quality',
+        category: 'code-smell',
+        severity: smell.severity,
+        title: smell.name,
+        description: `Found ${smell.count} instance(s)`,
+        file: smell.file,
+        remediation: this.getSmellRemediation(smell.id)
+      });
+    }
+
+    // Save report
+    const report = this.generateQualityReport(result);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'quality.md'),
+      report
+    );
+
+    return {
+      score: result.scores.overall,
+      breakdown: result.scores.breakdown,
+      totalFiles: result.summary.totalFiles,
+      totalIssues: result.summary.totalIssues,
+      totalSmells: result.summary.totalSmells
+    };
+  }
+
+  /**
+   * Get remediation for quality issue
+   */
+  getQualityRemediation(issueType) {
+    const remediations = {
+      'long-function': 'Break function into smaller, focused functions',
+      'high-complexity': 'Simplify logic by extracting helper functions or using early returns',
+      'too-many-params': 'Use an options object or break into multiple functions',
+      'long-file': 'Split into multiple modules with clear responsibilities',
+      'low-comments': 'Add JSDoc comments for public functions and complex logic'
+    };
+    return remediations[issueType] || 'Review and refactor as needed';
+  }
+
+  /**
+   * Get remediation for code smell
+   */
+  getSmellRemediation(smellId) {
+    const remediations = {
+      'todo-comment': 'Convert to a tracked issue or complete the TODO',
+      'fixme-comment': 'Address the issue and remove the comment',
+      'console-log': 'Remove console.log or replace with proper logging',
+      'debugger': 'Remove debugger statement before committing',
+      'empty-catch': 'Handle the error appropriately or add a comment explaining why it is safe to ignore',
+      'any-type': 'Add proper TypeScript types',
+      'ts-ignore': 'Fix the underlying TypeScript error',
+      'eslint-disable': 'Fix the underlying ESLint error or add specific disable reason'
+    };
+    return remediations[smellId] || 'Review and address as appropriate';
+  }
+
+  /**
+   * Generate quality report
+   */
+  generateQualityReport(analysis) {
+    const lines = [
+      '# Quality Analysis Report',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Quality Score',
+      '',
+      `**Overall**: ${analysis.scores.overall}/100`,
+      '',
+      '| Category | Score |',
+      '|----------|-------|',
+      `| Complexity | ${analysis.scores.breakdown.complexity}/100 |`,
+      `| Maintainability | ${analysis.scores.breakdown.maintainability}/100 |`,
+      `| Documentation | ${analysis.scores.breakdown.documentation}/100 |`,
+      `| Code Smells | ${analysis.scores.breakdown.codeSmells}/100 |`,
+      '',
+      '## Summary',
+      '',
+      `- **Total Files**: ${analysis.summary.totalFiles}`,
+      `- **Total Lines**: ${analysis.summary.totalLines}`,
+      `- **Average Complexity**: ${analysis.summary.averageComplexity}`,
+      `- **Total Issues**: ${analysis.summary.totalIssues}`,
+      `- **Code Smells**: ${analysis.summary.totalSmells}`,
+      ''
+    ];
+
+    if (analysis.worstFiles.length > 0) {
+      lines.push('## Files Needing Attention');
+      lines.push('');
+      lines.push('| File | Issues | Complexity |');
+      lines.push('|------|--------|------------|');
+      for (const file of analysis.worstFiles.slice(0, 10)) {
+        lines.push(`| \`${file.path}\` | ${file.issues.length} | ${file.complexity} |`);
+      }
+      lines.push('');
+    }
+
+    if (analysis.smellsByCategory && Object.keys(analysis.smellsByCategory).length > 0) {
+      lines.push('## Code Smells by Category');
+      lines.push('');
+      for (const [category, smells] of Object.entries(analysis.smellsByCategory)) {
+        lines.push(`### ${category}`);
+        for (const smell of smells.slice(0, 5)) {
+          lines.push(`- **${smell.name}** in \`${smell.file}\`: ${smell.count} instances`);
+        }
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run security scan phase
+   */
+  async runSecurityScan() {
+    const scanner = new SecurityScanner(this.projectRoot);
+    const result = scanner.scan();
+
+    // Add findings
+    for (const finding of result.findings) {
+      this.addFinding({
+        phase: 'security',
+        category: finding.type,
+        severity: finding.severity,
+        title: finding.name,
+        description: finding.message,
+        file: finding.file,
+        line: finding.line,
+        remediation: finding.remediation || this.getSecurityRemediation(finding.id)
+      });
+    }
+
+    // Save findings by severity
+    fs.writeFileSync(
+      path.join(this.findingsDir, 'critical.json'),
+      JSON.stringify(result.bySeverity[SEVERITY.CRITICAL], null, 2)
+    );
+    fs.writeFileSync(
+      path.join(this.findingsDir, 'high.json'),
+      JSON.stringify(result.bySeverity[SEVERITY.HIGH], null, 2)
+    );
+
+    // Save report
+    const report = this.generateSecurityReport(result);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'security.md'),
+      report
+    );
+
+    return {
+      passed: result.summary.passed,
+      total: result.summary.total,
+      critical: result.summary.critical,
+      high: result.summary.high,
+      medium: result.summary.medium,
+      low: result.summary.low
+    };
+  }
+
+  /**
+   * Get security remediation
+   */
+  getSecurityRemediation(findingId) {
+    const remediations = {
+      'aws-key': 'Remove AWS key and rotate credentials immediately',
+      'api-key': 'Move API key to environment variables',
+      'private-key': 'Remove private key from repository and rotate',
+      'sql-injection': 'Use parameterized queries',
+      'command-injection': 'Sanitize input and use spawn with array arguments',
+      'xss': 'Sanitize output and use content security policy'
+    };
+    return remediations[findingId] || 'Review and remediate security issue';
+  }
+
+  /**
+   * Generate security report
+   */
+  generateSecurityReport(analysis) {
+    const lines = [
+      '# Security Audit Report',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Summary',
+      '',
+      `**Status**: ${analysis.summary.passed ? 'PASSED' : 'FAILED'}`,
+      '',
+      '| Severity | Count |',
+      '|----------|-------|',
+      `| Critical | ${analysis.summary.critical} |`,
+      `| High | ${analysis.summary.high} |`,
+      `| Medium | ${analysis.summary.medium} |`,
+      `| Low | ${analysis.summary.low} |`,
+      `| Info | ${analysis.summary.info} |`,
+      ''
+    ];
+
+    if (analysis.summary.critical > 0) {
+      lines.push('## Critical Findings');
+      lines.push('');
+      lines.push('> These require immediate attention.');
+      lines.push('');
+      for (const finding of analysis.bySeverity[SEVERITY.CRITICAL]) {
+        lines.push(`### ${finding.name}`);
+        lines.push(`- **File**: \`${finding.file}:${finding.line || 0}\``);
+        lines.push(`- **Message**: ${finding.message}`);
+        lines.push(`- **Remediation**: ${finding.remediation || 'Review and fix'}`);
+        lines.push('');
+      }
+    }
+
+    if (analysis.summary.high > 0) {
+      lines.push('## High Severity Findings');
+      lines.push('');
+      for (const finding of analysis.bySeverity[SEVERITY.HIGH]) {
+        lines.push(`- **${finding.name}** in \`${finding.file}\`: ${finding.message}`);
+      }
+      lines.push('');
+    }
+
+    if (analysis.byType.secret.length > 0) {
+      lines.push('## Potential Secrets');
+      lines.push('');
+      lines.push('> Remove these from version control and rotate credentials.');
+      lines.push('');
+      for (const finding of analysis.byType.secret) {
+        lines.push(`- **${finding.name}** in \`${finding.file}\``);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run performance analysis phase
+   */
+  async runPerformanceAnalysis() {
+    const findings = {
+      bundleSize: null,
+      lazyLoading: [],
+      n1Queries: [],
+      recommendations: []
+    };
+
+    // Check for bundle analysis config
+    const nextConfigPath = path.join(this.projectRoot, 'next.config.js');
+    if (fs.existsSync(nextConfigPath)) {
+      const content = fs.readFileSync(nextConfigPath, 'utf-8');
+      if (!content.includes('bundle-analyzer')) {
+        findings.recommendations.push({
+          id: 'add-bundle-analyzer',
+          title: 'Add Bundle Analyzer',
+          description: 'Consider adding @next/bundle-analyzer to monitor bundle size'
+        });
+      }
+    }
+
+    // Check for dynamic imports
+    const hasDynamicImports = await this.checkForDynamicImports();
+    if (!hasDynamicImports) {
+      findings.recommendations.push({
+        id: 'use-dynamic-imports',
+        title: 'Use Dynamic Imports',
+        description: 'Consider using dynamic imports for large components'
+      });
+    }
+
+    // Add findings
+    for (const rec of findings.recommendations) {
+      this.addFinding({
+        phase: 'performance',
+        category: 'performance',
+        severity: 'low',
+        title: rec.title,
+        description: rec.description,
+        remediation: 'Implement the suggested optimization'
+      });
+    }
+
+    return {
+      recommendations: findings.recommendations.length
+    };
+  }
+
+  /**
+   * Check for dynamic imports
+   */
+  async checkForDynamicImports() {
+    const patterns = [
+      /import\s*\(\s*['"][^'"]+['"]\s*\)/g,
+      /dynamic\s*\(\s*\(\)\s*=>\s*import/g,
+      /lazy\s*\(\s*\(\)\s*=>\s*import/g
+    ];
+
+    const sourceDirs = ['src', 'app', 'pages', 'components'];
+
+    for (const dir of sourceDirs) {
+      const dirPath = path.join(this.projectRoot, dir);
+      if (fs.existsSync(dirPath)) {
+        const found = await this.searchForPatterns(dirPath, patterns);
+        if (found) return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Search for patterns in directory
+   */
+  async searchForPatterns(dir, patterns) {
+    try {
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const item of items) {
+        const fullPath = path.join(dir, item.name);
+
+        if (item.isDirectory() && !item.name.startsWith('.') && item.name !== 'node_modules') {
+          if (await this.searchForPatterns(fullPath, patterns)) {
+            return true;
+          }
+        } else if (item.isFile() && /\.(js|jsx|ts|tsx)$/.test(item.name)) {
+          const content = fs.readFileSync(fullPath, 'utf-8');
+          for (const pattern of patterns) {
+            if (pattern.test(content)) {
+              return true;
+            }
+          }
+        }
+      }
+    } catch (_e) {
+      // Skip
+    }
+
+    return false;
+  }
+
+  /**
+   * Run best practices phase
+   */
+  async runBestPractices() {
+    const checks = {
+      typescript: await this.checkTypeScriptConfig(),
+      errorHandling: await this.checkErrorHandling(),
+      envVars: await this.checkEnvVars(),
+      gitignore: await this.checkGitignore()
+    };
+
+    // Add findings for failed checks
+    for (const [check, result] of Object.entries(checks)) {
+      if (!result.passed) {
+        for (const issue of result.issues) {
+          this.addFinding({
+            phase: 'practices',
+            category: 'best-practice',
+            severity: issue.severity || 'medium',
+            title: issue.title,
+            description: issue.description,
+            file: issue.file,
+            remediation: issue.remediation
+          });
+        }
+      }
+    }
+
+    const passedCount = Object.values(checks).filter(c => c.passed).length;
+
+    return {
+      passed: passedCount,
+      total: Object.keys(checks).length,
+      checks
+    };
+  }
+
+  /**
+   * Check TypeScript configuration
+   */
+  async checkTypeScriptConfig() {
+    const result = { passed: true, issues: [] };
+    const tsconfigPath = path.join(this.projectRoot, 'tsconfig.json');
+
+    if (!fs.existsSync(tsconfigPath)) {
+      result.passed = false;
+      result.issues.push({
+        title: 'TypeScript Not Configured',
+        description: 'No tsconfig.json found',
+        severity: 'low',
+        remediation: 'Consider using TypeScript for better type safety'
+      });
+      return result;
+    }
+
+    try {
+      const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, 'utf-8'));
+      const compilerOptions = tsconfig.compilerOptions || {};
+
+      if (!compilerOptions.strict) {
+        result.passed = false;
+        result.issues.push({
+          title: 'TypeScript Strict Mode Disabled',
+          description: 'strict mode is not enabled in tsconfig.json',
+          file: 'tsconfig.json',
+          severity: 'low',
+          remediation: 'Enable "strict": true for better type safety'
+        });
+      }
+
+      if (compilerOptions.noImplicitAny === false) {
+        result.passed = false;
+        result.issues.push({
+          title: 'Implicit Any Allowed',
+          description: 'noImplicitAny is disabled',
+          file: 'tsconfig.json',
+          severity: 'low',
+          remediation: 'Enable noImplicitAny for stricter typing'
+        });
+      }
+    } catch (_e) {
+      // Invalid tsconfig
+    }
+
+    return result;
+  }
+
+  /**
+   * Check error handling patterns
+   */
+  async checkErrorHandling() {
+    const result = { passed: true, issues: [] };
+
+    // Check for global error handler in Next.js
+    const errorPagePaths = [
+      'app/error.tsx', 'app/error.js',
+      'pages/_error.tsx', 'pages/_error.js',
+      'src/app/error.tsx', 'src/pages/_error.tsx'
+    ];
+
+    let hasErrorPage = false;
+    for (const errorPath of errorPagePaths) {
+      if (fs.existsSync(path.join(this.projectRoot, errorPath))) {
+        hasErrorPage = true;
+        break;
+      }
+    }
+
+    if (!hasErrorPage) {
+      result.passed = false;
+      result.issues.push({
+        title: 'No Global Error Handler',
+        description: 'No error page found for handling runtime errors',
+        severity: 'medium',
+        remediation: 'Create an error.tsx (App Router) or _error.tsx (Pages Router)'
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Check environment variable handling
+   */
+  async checkEnvVars() {
+    const result = { passed: true, issues: [] };
+
+    const envPath = path.join(this.projectRoot, '.env');
+    const envExamplePath = path.join(this.projectRoot, '.env.example');
+    const envLocalPath = path.join(this.projectRoot, '.env.local');
+
+    // Check for .env.example
+    if (!fs.existsSync(envExamplePath)) {
+      if (fs.existsSync(envPath) || fs.existsSync(envLocalPath)) {
+        result.passed = false;
+        result.issues.push({
+          title: 'Missing .env.example',
+          description: 'No .env.example file to document required environment variables',
+          severity: 'low',
+          remediation: 'Create .env.example with all required variables (without values)'
+        });
+      }
+    }
+
+    // Check .gitignore includes .env
+    const gitignorePath = path.join(this.projectRoot, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+      if (!gitignore.includes('.env')) {
+        result.passed = false;
+        result.issues.push({
+          title: '.env Not in .gitignore',
+          description: '.env files should be excluded from version control',
+          file: '.gitignore',
+          severity: 'high',
+          remediation: 'Add .env* to .gitignore'
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check .gitignore configuration
+   */
+  async checkGitignore() {
+    const result = { passed: true, issues: [] };
+    const gitignorePath = path.join(this.projectRoot, '.gitignore');
+
+    if (!fs.existsSync(gitignorePath)) {
+      result.passed = false;
+      result.issues.push({
+        title: 'Missing .gitignore',
+        description: 'No .gitignore file found',
+        severity: 'medium',
+        remediation: 'Create a .gitignore file with appropriate exclusions'
+      });
+      return result;
+    }
+
+    const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    const requiredEntries = ['node_modules', '.env'];
+
+    for (const entry of requiredEntries) {
+      if (!gitignore.includes(entry)) {
+        result.passed = false;
+        result.issues.push({
+          title: `Missing ${entry} in .gitignore`,
+          description: `${entry} should be in .gitignore`,
+          file: '.gitignore',
+          severity: entry === '.env' ? 'high' : 'low',
+          remediation: `Add ${entry} to .gitignore`
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Run tech debt inventory phase
+   */
+  async runTechDebtInventory() {
+    const techDebt = {
+      todos: [],
+      deprecated: [],
+      deadCode: [],
+      missingTests: []
+    };
+
+    // Scan for TODOs (already captured in quality phase)
+    const qualityFindings = this.state.findings.filter(
+      f => f.phase === 'quality' && f.category === 'code-smell'
+    );
+
+    techDebt.todos = qualityFindings.filter(
+      f => f.title.toLowerCase().includes('todo') || f.title.toLowerCase().includes('fixme')
+    );
+
+    // Check for missing tests
+    const srcDirs = ['src', 'lib', 'app', 'components'];
+    let sourceFiles = 0;
+    let testFiles = 0;
+
+    for (const dir of srcDirs) {
+      const dirPath = path.join(this.projectRoot, dir);
+      if (fs.existsSync(dirPath)) {
+        const counts = await this.countSourceAndTestFiles(dirPath);
+        sourceFiles += counts.source;
+        testFiles += counts.test;
+      }
+    }
+
+    const testRatio = sourceFiles > 0 ? testFiles / sourceFiles : 0;
+    if (testRatio < 0.2) {
+      this.addFinding({
+        phase: 'techDebt',
+        category: 'tech-debt',
+        severity: 'medium',
+        title: 'Low Test Coverage',
+        description: `Only ${Math.round(testRatio * 100)}% test file ratio`,
+        remediation: 'Add unit and integration tests for critical paths'
+      });
+    }
+
+    // Check for unused dependencies (skip for large codebases)
+    const LARGE_CODEBASE_THRESHOLD = 500;
+    let unusedDeps = [];
+    let depAnalysisSkipped = false;
+
+    // Estimate file count from source files scanned
+    const estimatedFileCount = sourceFiles + testFiles;
+
+    if (estimatedFileCount < LARGE_CODEBASE_THRESHOLD) {
+      const depAnalyzer = new DependencyAnalyzer(this.projectRoot);
+      depAnalyzer.buildGraph();
+      unusedDeps = depAnalyzer.findUnusedDependencies();
+
+      for (const dep of unusedDeps.slice(0, 10)) {
+        this.addFinding({
+          phase: 'techDebt',
+          category: 'tech-debt',
+          severity: 'low',
+          title: 'Potentially Unused Dependency',
+          description: `${dep.name} may be unused`,
+          remediation: `Remove ${dep.name} if not needed, or verify it is used`
+        });
+      }
+    } else {
+      depAnalysisSkipped = true;
+    }
+
+    // Save tech debt report
+    const report = this.generateTechDebtReport(techDebt, testRatio, unusedDeps, depAnalysisSkipped);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'tech-debt.md'),
+      report
+    );
+
+    return {
+      todos: techDebt.todos.length,
+      unusedDeps: unusedDeps.length,
+      testCoverage: Math.round(testRatio * 100),
+      depAnalysisSkipped
+    };
+  }
+
+  /**
+   * Count source and test files
+   */
+  async countSourceAndTestFiles(dir) {
+    let source = 0;
+    let test = 0;
+
+    try {
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const item of items) {
+        const fullPath = path.join(dir, item.name);
+
+        if (item.isDirectory() && !item.name.startsWith('.') && item.name !== 'node_modules') {
+          const counts = await this.countSourceAndTestFiles(fullPath);
+          source += counts.source;
+          test += counts.test;
+        } else if (item.isFile() && /\.(js|jsx|ts|tsx)$/.test(item.name)) {
+          if (/\.(test|spec)\.(js|jsx|ts|tsx)$/.test(item.name)) {
+            test++;
+          } else {
+            source++;
+          }
+        }
+      }
+    } catch (_e) {
+      // Skip
+    }
+
+    return { source, test };
+  }
+
+  /**
+   * Generate tech debt report
+   */
+  generateTechDebtReport(techDebt, testRatio, unusedDeps, depAnalysisSkipped = false) {
+    const lines = [
+      '# Technical Debt Report',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Summary',
+      '',
+      `- **TODO/FIXME Comments**: ${techDebt.todos.length}`,
+      `- **Test Coverage**: ${Math.round(testRatio * 100)}%`,
+      `- **Unused Dependencies**: ${depAnalysisSkipped ? 'Skipped (large codebase)' : unusedDeps.length}`,
+      ''
+    ];
+
+    if (techDebt.todos.length > 0) {
+      lines.push('## TODO/FIXME Items');
+      lines.push('');
+      for (const todo of techDebt.todos.slice(0, 20)) {
+        lines.push(`- \`${todo.file}\`: ${todo.title}`);
+      }
+      lines.push('');
+    }
+
+    if (unusedDeps.length > 0) {
+      lines.push('## Potentially Unused Dependencies');
+      lines.push('');
+      for (const dep of unusedDeps) {
+        lines.push(`- \`${dep.name}\` (${dep.type})`);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run recommendations phase
+   */
+  async runRecommendations() {
+    // Group findings by severity
+    const bySeverity = {
+      critical: [],
+      high: [],
+      medium: [],
+      low: [],
+      info: []
+    };
+
+    for (const finding of this.state.findings) {
+      const severity = finding.severity || 'info';
+      if (bySeverity[severity]) {
+        bySeverity[severity].push(finding);
+      }
+    }
+
+    // Generate prioritized recommendations
+    const recommendations = [];
+    let priority = 0;
+
+    // P0: Critical findings
+    for (const finding of bySeverity.critical) {
+      recommendations.push({
+        priority: 'P0',
+        severity: 'critical',
+        title: finding.title,
+        description: finding.description,
+        file: finding.file,
+        remediation: finding.remediation
+      });
+      priority++;
+    }
+
+    // P1: High findings
+    for (const finding of bySeverity.high.slice(0, 10)) {
+      recommendations.push({
+        priority: 'P1',
+        severity: 'high',
+        title: finding.title,
+        description: finding.description,
+        file: finding.file,
+        remediation: finding.remediation
+      });
+    }
+
+    // P2: Medium findings
+    for (const finding of bySeverity.medium.slice(0, 10)) {
+      recommendations.push({
+        priority: 'P2',
+        severity: 'medium',
+        title: finding.title,
+        description: finding.description,
+        file: finding.file,
+        remediation: finding.remediation
+      });
+    }
+
+    // P3: Low findings (just summary)
+    recommendations.push({
+      priority: 'P3',
+      severity: 'low',
+      title: `${bySeverity.low.length} Low Priority Items`,
+      description: 'Address when convenient',
+      remediation: 'Review low priority findings in the audit report'
+    });
+
+    // Generate final report
+    const report = this.generateFinalReport(bySeverity, recommendations);
+    const reportPath = path.join(this.projectRoot, 'planning', 'AUDIT_REPORT.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, 'AUDIT_REPORT.md'),
+      report
+    );
+
+    this.state.summary = {
+      reportPath,
+      totalFindings: this.state.findings.length,
+      critical: bySeverity.critical.length,
+      high: bySeverity.high.length,
+      medium: bySeverity.medium.length,
+      low: bySeverity.low.length,
+      recommendations: recommendations.length,
+      generatedAt: new Date().toISOString()
+    };
+
+    return {
+      reportPath,
+      recommendations: recommendations.length,
+      passed: bySeverity.critical.length === 0
+    };
+  }
+
+  /**
+   * Generate final audit report
+   */
+  generateFinalReport(bySeverity, recommendations) {
+    const totalFindings = Object.values(bySeverity).reduce((sum, arr) => sum + arr.length, 0);
+
+    const lines = [
+      '# Audit Report',
+      '',
+      '**Generated by**: Bootspring Audit',
+      `**Date**: ${new Date().toISOString().split('T')[0]}`,
+      `**Status**: ${bySeverity.critical.length === 0 ? 'PASSED' : 'NEEDS ATTENTION'}`,
+      '',
+      '## Executive Summary',
+      '',
+      `This audit found **${totalFindings}** findings across quality, security, and best practices checks.`,
+      '',
+      '### Findings by Severity',
+      '',
+      '| Severity | Count | Action Required |',
+      '|----------|-------|-----------------|',
+      `| Critical | ${bySeverity.critical.length} | Immediate |`,
+      `| High | ${bySeverity.high.length} | 1-2 days |`,
+      `| Medium | ${bySeverity.medium.length} | 1-2 weeks |`,
+      `| Low | ${bySeverity.low.length} | Backlog |`,
+      ''
+    ];
+
+    // Critical findings
+    if (bySeverity.critical.length > 0) {
+      lines.push('## Critical Findings');
+      lines.push('');
+      lines.push('> These require immediate attention.');
+      lines.push('');
+      for (const finding of bySeverity.critical) {
+        lines.push(`### ${finding.title}`);
+        lines.push(`- **Category**: ${finding.category}`);
+        lines.push(`- **File**: ${finding.file ? `\`${finding.file}\`` : 'N/A'}`);
+        lines.push(`- **Description**: ${finding.description}`);
+        lines.push(`- **Remediation**: ${finding.remediation}`);
+        lines.push('');
+      }
+    }
+
+    // High findings
+    if (bySeverity.high.length > 0) {
+      lines.push('## High Priority Findings');
+      lines.push('');
+      for (const finding of bySeverity.high) {
+        lines.push(`- **${finding.title}** ${finding.file ? `(\`${finding.file}\`)` : ''}: ${finding.description}`);
+      }
+      lines.push('');
+    }
+
+    // Recommendations
+    lines.push('## Prioritized Recommendations');
+    lines.push('');
+    lines.push('| Priority | Title | Severity |');
+    lines.push('|----------|-------|----------|');
+    for (const rec of recommendations.slice(0, 15)) {
+      lines.push(`| ${rec.priority} | ${rec.title} | ${rec.severity} |`);
+    }
+    lines.push('');
+
+    // Quality metrics
+    const qualityPhase = this.state.phases.quality;
+    if (qualityPhase?.result) {
+      lines.push('## Quality Metrics');
+      lines.push('');
+      lines.push(`- **Quality Score**: ${qualityPhase.result.score}/100`);
+      lines.push(`- **Total Files**: ${qualityPhase.result.totalFiles}`);
+      lines.push(`- **Total Issues**: ${qualityPhase.result.totalIssues}`);
+      lines.push('');
+    }
+
+    // Security summary
+    const securityPhase = this.state.phases.security;
+    if (securityPhase?.result) {
+      lines.push('## Security Summary');
+      lines.push('');
+      lines.push(`- **Status**: ${securityPhase.result.passed ? 'PASSED' : 'NEEDS ATTENTION'}`);
+      lines.push(`- **Critical Issues**: ${securityPhase.result.critical}`);
+      lines.push(`- **High Issues**: ${securityPhase.result.high}`);
+      lines.push('');
+    }
+
+    lines.push('---');
+    lines.push('');
+    lines.push('*Generated by [Bootspring](https://bootspring.com)*');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get workflow progress
+   */
+  getProgress() {
+    if (!this.state) return null;
+
+    const phases = Object.entries(AUDIT_PHASES).map(([phaseId, phase]) => {
+      const phaseState = this.state.phases[phaseId] || { status: PHASE_STATUS.PENDING };
+
+      return {
+        id: phaseId,
+        name: phase.name,
+        description: phase.description,
+        order: phase.order,
+        required: phase.required,
+        status: phaseState.status,
+        dependenciesMet: this.arePhaseDependenciesMet(phaseId)
+      };
+    });
+
+    const completedCount = phases.filter(p => p.status === PHASE_STATUS.COMPLETED).length;
+    const activeCount = phases.filter(p => p.status !== PHASE_STATUS.SKIPPED).length;
+
+    // Count findings by severity
+    const findingsBySeverity = {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      low: 0,
+      info: 0
+    };
+
+    for (const finding of this.state.findings) {
+      const severity = finding.severity || 'info';
+      if (findingsBySeverity[severity] !== undefined) {
+        findingsBySeverity[severity]++;
+      }
+    }
+
+    return {
+      currentPhase: this.state.currentPhase,
+      startedAt: this.state.startedAt,
+      lastUpdated: this.state.lastUpdated,
+      phases,
+      overall: {
+        completed: completedCount,
+        total: activeCount,
+        percentage: Math.round((completedCount / activeCount) * 100)
+      },
+      findings: {
+        total: this.state.findings.length,
+        ...findingsBySeverity
+      },
+      isComplete: completedCount === activeCount,
+      summary: this.state.summary
+    };
+  }
+
+  /**
+   * Get resume point
+   */
+  getResumePoint() {
+    if (!this.state || !this.state.currentPhase) {
+      return null;
+    }
+
+    const phase = AUDIT_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,
+      findingsCount: this.state.findings.length
+    };
+  }
+
+  /**
+   * Get exit code for CI mode
+   */
+  getExitCode() {
+    if (!this.state) return 1;
+
+    const criticalCount = this.state.findings.filter(f => f.severity === 'critical').length;
+    const highCount = this.state.findings.filter(f => f.severity === 'high').length;
+
+    if (criticalCount > 0) return 2;
+    if (highCount > 0) return 1;
+    return 0;
+  }
+}
+
+module.exports = {
+  AuditWorkflowEngine,
+  AUDIT_PHASES,
+  PHASE_STATUS,
+  SEVERITY_LEVELS
+};