vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/runAudit.js

@@ -0,0 +1,692 @@
+/**
+ * runAudit.js - "Convincing Wrongness" Detector
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AUDIT: Find what makes the app LOOK done but NOT work.
+ * The most dangerous bugs are the invisible ones.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Features:
+ * - Ranked "Attack List" with confidence and blast radius
+ * - Every finding: file/line evidence + "how to prove" + "how to fix"
+ * - --fast mode: cheap signals, single-file analysis
+ * - --deep mode: runtime + cross-file analysis
+ * - Zero false-positive obsession: show confidence + evidence
+ * 
+ * @version 2.0.0
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+const { EXIT } = require("./lib/exit-codes");
+const { withErrorHandling } = require("./lib/error-handler");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TERMINAL STYLING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const SUPPORTS_UNICODE = process.platform !== "win32" || process.env.WT_SESSION || process.env.TERM_PROGRAM;
+
+const c = SUPPORTS_COLOR ? {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  italic: "\x1b[3m",
+  underline: "\x1b[4m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  brightRed: "\x1b[91m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  bgRed: "\x1b[41m",
+  bgYellow: "\x1b[43m",
+  bgGreen: "\x1b[42m",
+  bgMagenta: "\x1b[45m",
+} : Object.fromEntries([
+  "reset", "bold", "dim", "italic", "underline",
+  "red", "green", "yellow", "blue", "magenta", "cyan", "white", "gray",
+  "brightRed", "brightGreen", "brightYellow",
+  "bgRed", "bgYellow", "bgGreen", "bgMagenta"
+].map(k => [k, ""]));
+
+const sym = SUPPORTS_UNICODE ? {
+  skull: "💀",
+  fire: "🔥",
+  warning: "⚠️",
+  bomb: "💣",
+  ghost: "👻",
+  mask: "🎭",
+  lock: "🔒",
+  unlock: "🔓",
+  money: "💰",
+  check: "✓",
+  cross: "✗",
+  bullet: "•",
+  arrow: "→",
+  arrowRight: "▸",
+  box: "■",
+  boxEmpty: "□",
+  line: "─",
+  corner: "└",
+  tee: "├",
+  vertical: "│",
+  topLeft: "╭",
+  topRight: "╮",
+  bottomLeft: "╰",
+  bottomRight: "╯",
+  star: "★",
+  target: "◎",
+} : {
+  skull: "[X]",
+  fire: "(!)",
+  warning: "[!]",
+  bomb: "[*]",
+  ghost: "[G]",
+  mask: "[M]",
+  lock: "[L]",
+  unlock: "[U]",
+  money: "[$]",
+  check: "[v]",
+  cross: "[x]",
+  bullet: "*",
+  arrow: "->",
+  arrowRight: ">",
+  box: "#",
+  boxEmpty: "o",
+  line: "-",
+  corner: "+",
+  tee: "+",
+  vertical: "|",
+  topLeft: "+",
+  topRight: "+",
+  bottomLeft: "+",
+  bottomRight: "+",
+  star: "*",
+  target: "@",
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UNIFIED CLI OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+let _cliOutput = null;
+function getCliOutput() {
+  if (!_cliOutput) _cliOutput = require("./lib/unified-cli-output");
+  return _cliOutput;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// BANNER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const BANNER_FALLBACK = `
+${c.bgRed}${c.bold}                                                                   ${c.reset}
+${c.bgRed}${c.bold}   ${sym.skull} AUDIT - Convincing Wrongness Detector                       ${c.reset}
+${c.bgRed}${c.bold}                                                                   ${c.reset}
+
+${c.dim}Find code that LOOKS done but DOESN'T work.${c.reset}
+${c.dim}The most dangerous bugs are the invisible ones.${c.reset}
+`;
+
+function printBanner(projectRoot = process.cwd()) {
+  try {
+    const cli = getCliOutput();
+    console.log(cli.renderFullHeader("audit", {
+      version: "2.0.0",
+      tier: "FREE",
+      integrity: "ANALYZING",
+      target: projectRoot,
+      sessionId: cli.generateSessionId(),
+    }));
+  } catch {
+    console.log(BANNER_FALLBACK);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARGUMENT PARSING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function parseArgs(args) {
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(args);
+  
+  const opts = {
+    help: globalFlags.help || false,
+    json: globalFlags.json || false,
+    ci: globalFlags.ci || false,
+    quiet: globalFlags.quiet || false,
+    verbose: globalFlags.verbose || false,
+    noBanner: globalFlags.noBanner || false,
+    path: globalFlags.path || process.cwd(),
+    output: globalFlags.output || null,
+    
+    // Audit-specific options
+    mode: "fast", // "fast" | "deep"
+    threshold: "all", // "critical" | "high" | "medium" | "all"
+    format: "terminal", // "terminal" | "json" | "sarif" | "markdown"
+    maxFindings: 50,
+    failOn: null, // "critical" | "high" | "medium" - exit code 1 if found
+  };
+
+  for (let i = 0; i < cleanArgs.length; i++) {
+    const arg = cleanArgs[i];
+    
+    switch (arg) {
+      case "--fast":
+        opts.mode = "fast";
+        break;
+      case "--deep":
+        opts.mode = "deep";
+        break;
+      case "--threshold":
+        opts.threshold = cleanArgs[++i] || "all";
+        break;
+      case "--format":
+        opts.format = cleanArgs[++i] || "terminal";
+        break;
+      case "--max":
+      case "--max-findings":
+        opts.maxFindings = parseInt(cleanArgs[++i], 10) || 50;
+        break;
+      case "--fail-on":
+        opts.failOn = cleanArgs[++i] || null;
+        break;
+      case "--sarif":
+        opts.format = "sarif";
+        break;
+      case "--markdown":
+      case "--md":
+        opts.format = "markdown";
+        break;
+    }
+  }
+
+  return opts;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printHelp(showBanner = true, projectRoot = process.cwd()) {
+  if (showBanner) printBanner(projectRoot);
+  
+  console.log(`
+${c.bold}USAGE${c.reset}
+  vibecheck audit [options]
+
+${c.bold}DESCRIPTION${c.reset}
+  Find code that LOOKS done but DOESN'T work. Detects:
+  
+  ${c.red}${sym.skull} DEAD_ROUTE${c.reset}      Routes that exist but don't work
+  ${c.yellow}${sym.ghost} GHOST_ENV${c.reset}       Env vars used but never declared
+  ${c.magenta}${sym.mask} FAKE_SUCCESS${c.reset}    UI shows success without operation
+  ${c.red}${sym.lock} AUTH_DRIFT${c.reset}      Auth patterns that look secure but aren't
+  ${c.yellow}${sym.bomb} MOCK_LANDMINE${c.reset}   Mock/TODO code in production paths
+  ${c.yellow}${sym.warning} SILENT_FAIL${c.reset}     Errors swallowed without feedback
+  ${c.yellow}${sym.fire} OPTIMISTIC_BOMB${c.reset} Optimistic UI without rollback
+  ${c.green}${sym.money} PAID_THEATER${c.reset}    Paid features that aren't enforced
+
+${c.bold}OPTIONS${c.reset}
+  ${c.cyan}--fast${c.reset}             Quick scan - cheap signals only (default)
+  ${c.cyan}--deep${c.reset}             Deep scan - runtime + cross-file analysis
+  ${c.cyan}--threshold${c.reset} <lvl>  Show: "critical", "high", "medium", or "all"
+  ${c.cyan}--fail-on${c.reset} <lvl>    Exit 1 if findings at level: "critical", "high"
+  ${c.cyan}--format${c.reset} <fmt>     Output: "terminal", "json", "sarif", "markdown"
+  ${c.cyan}--sarif${c.reset}            Output as SARIF (for GitHub)
+  ${c.cyan}--max${c.reset} <n>          Max findings to display (default: 50)
+  ${c.cyan}--output${c.reset} <file>    Write output to file
+  ${c.cyan}--json${c.reset}             JSON output
+  ${c.cyan}--quiet${c.reset}            Minimal output
+  ${c.cyan}--ci${c.reset}               CI mode (quiet + no-banner + json)
+
+${c.bold}EXAMPLES${c.reset}
+  ${c.dim}# Quick scan${c.reset}
+  vibecheck audit
+
+  ${c.dim}# Deep scan with CI integration${c.reset}
+  vibecheck audit --deep --fail-on critical --sarif > audit.sarif
+
+  ${c.dim}# Only show critical and high findings${c.reset}
+  vibecheck audit --threshold high
+
+  ${c.dim}# Generate markdown report${c.reset}
+  vibecheck audit --markdown --output AUDIT.md
+
+${c.bold}EXIT CODES${c.reset}
+  0    No findings (or below --fail-on threshold)
+  1    Findings at or above --fail-on threshold
+  2    Error during scan
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TERMINAL OUTPUT FORMATTERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getSeverityStyle(severity) {
+  switch (severity) {
+    case "critical": return { color: c.bgRed + c.white, icon: sym.skull, label: "CRIT" };
+    case "high": return { color: c.red, icon: sym.fire, label: "HIGH" };
+    case "medium": return { color: c.yellow, icon: sym.warning, label: "MED " };
+    case "low": return { color: c.dim, icon: sym.bullet, label: "LOW " };
+    default: return { color: c.dim, icon: sym.bullet, label: "INFO" };
+  }
+}
+
+function getTypeIcon(type) {
+  switch (type) {
+    case "DEAD_ROUTE": return sym.skull;
+    case "GHOST_ENV": return sym.ghost;
+    case "FAKE_SUCCESS": return sym.mask;
+    case "AUTH_DRIFT": return sym.lock;
+    case "MOCK_LANDMINE": return sym.bomb;
+    case "SILENT_FAIL": return sym.warning;
+    case "OPTIMISTIC_BOMB": return sym.fire;
+    case "PAID_THEATER": return sym.money;
+    default: return sym.bullet;
+  }
+}
+
+function formatFinding(finding, index, verbose = false) {
+  const sev = getSeverityStyle(finding.severity);
+  const typeIcon = getTypeIcon(finding.type);
+  
+  let output = `
+${c.dim}${sym.line.repeat(70)}${c.reset}
+${sev.color}${c.bold} ${sev.label} ${c.reset} ${c.bold}#${index + 1}${c.reset} ${typeIcon} ${c.bold}${finding.title}${c.reset}
+${c.dim}${sym.line.repeat(70)}${c.reset}
+
+${c.cyan}${sym.arrowRight} File:${c.reset}       ${finding.file}:${finding.line}
+${c.cyan}${sym.arrowRight} Type:${c.reset}       ${finding.type}
+${c.cyan}${sym.arrowRight} Confidence:${c.reset} ${finding.confidence}%  ${c.dim}Blast Radius: ${finding.blastRadius}/10${c.reset}
+
+${c.dim}${sym.vertical}${c.reset} ${c.gray}${finding.snippet}${c.reset}
+
+${c.green}${sym.check} Why it looks right:${c.reset}
+  ${finding.whyConvincing}
+
+${c.red}${sym.cross} Why it's wrong:${c.reset}
+  ${finding.whyWrong}
+
+${c.yellow}${sym.target} How to prove:${c.reset}
+  ${finding.howToProve}
+
+${c.cyan}${sym.star} How to fix:${c.reset}
+  ${finding.howToFix}
+`;
+
+  if (verbose && finding.attackVector) {
+    output += `
+${c.magenta}${sym.bomb} Attack vector:${c.reset}
+  ${finding.attackVector}
+`;
+  }
+
+  return output;
+}
+
+function formatSummary(report) {
+  const { summary, attackScore, manifest, elapsedMs } = report;
+  
+  // Attack score visualization
+  const scoreBar = (score) => {
+    const filled = Math.round(score / 5);
+    const empty = 20 - filled;
+    const color = score >= 70 ? c.red : score >= 40 ? c.yellow : c.green;
+    return color + sym.box.repeat(filled) + c.dim + sym.boxEmpty.repeat(empty) + c.reset;
+  };
+
+  let output = `
+${c.bold}${c.bgMagenta}                                                                   ${c.reset}
+${c.bold}${c.bgMagenta}   ${sym.target} ATTACK SURFACE ANALYSIS                                    ${c.reset}
+${c.bold}${c.bgMagenta}                                                                   ${c.reset}
+
+${c.bold}Attack Score:${c.reset} ${attackScore}/100 ${scoreBar(attackScore)}
+${attackScore >= 70 ? c.red + sym.skull + " HIGH RISK - Critical issues found" + c.reset : 
+  attackScore >= 40 ? c.yellow + sym.warning + " MEDIUM RISK - Issues need attention" + c.reset :
+  c.green + sym.check + " LOW RISK - Looking good!" + c.reset}
+
+${c.bold}Findings by Severity:${c.reset}
+  ${c.bgRed}${c.white} CRITICAL ${c.reset} ${summary.critical}
+  ${c.red}    HIGH ${c.reset} ${summary.high}
+  ${c.yellow}  MEDIUM ${c.reset} ${summary.medium}
+  ${c.dim}     LOW ${c.reset} ${summary.low}
+
+${c.bold}Findings by Type:${c.reset}
+`;
+
+  const typeOrder = [
+    "AUTH_DRIFT", "DEAD_ROUTE", "MOCK_LANDMINE", "GHOST_ENV",
+    "FAKE_SUCCESS", "SILENT_FAIL", "OPTIMISTIC_BOMB", "PAID_THEATER"
+  ];
+  
+  for (const type of typeOrder) {
+    const count = summary.byType[type] || 0;
+    if (count > 0) {
+      output += `  ${getTypeIcon(type)} ${type.padEnd(16)} ${count}\n`;
+    }
+  }
+
+  output += `
+${c.dim}${sym.line.repeat(50)}${c.reset}
+${c.dim}Total: ${summary.total} findings | Critical paths: ${summary.inCriticalPaths}${c.reset}
+${c.dim}Scan time: ${elapsedMs}ms | Manifest: ${manifest.hash.slice(0, 12)}...${c.reset}
+`;
+
+  return output;
+}
+
+function formatTerminal(report, opts) {
+  let output = "";
+  
+  // Filter by threshold
+  const thresholdOrder = { critical: 0, high: 1, medium: 2, low: 3, all: 4 };
+  const thresholdLevel = thresholdOrder[opts.threshold] || 4;
+  
+  const filteredFindings = report.findings.filter(f => {
+    const sevLevel = thresholdOrder[f.severity];
+    return sevLevel <= thresholdLevel;
+  });
+
+  // Show summary first
+  output += formatSummary(report);
+
+  if (filteredFindings.length === 0) {
+    output += `\n${c.green}${sym.check} No findings at threshold '${opts.threshold}' or above.${c.reset}\n`;
+    return output;
+  }
+
+  output += `\n${c.bold}${c.bgRed}                                                                   ${c.reset}`;
+  output += `\n${c.bold}${c.bgRed}   ${sym.skull} ATTACK LIST - Ranked by Severity                            ${c.reset}`;
+  output += `\n${c.bold}${c.bgRed}                                                                   ${c.reset}\n`;
+
+  // Show findings (up to max)
+  const displayFindings = filteredFindings.slice(0, opts.maxFindings);
+  
+  for (let i = 0; i < displayFindings.length; i++) {
+    output += formatFinding(displayFindings[i], i, opts.verbose);
+  }
+
+  if (filteredFindings.length > opts.maxFindings) {
+    output += `\n${c.dim}... and ${filteredFindings.length - opts.maxFindings} more findings. Use --max to see more.${c.reset}\n`;
+  }
+
+  // Action items
+  output += `
+${c.bold}${c.cyan}${sym.star} NEXT STEPS${c.reset}
+
+  1. ${c.bold}Fix critical issues first${c.reset} - these can break your app
+  2. ${c.bold}Add to safelist${c.reset} if false positive: ${c.dim}vibecheck safelist add --id <ID>${c.reset}
+  3. ${c.bold}Run with --deep${c.reset} for cross-file analysis
+  4. ${c.bold}CI integration:${c.reset} vibecheck audit --fail-on critical --sarif
+
+${c.dim}Need help? Run: vibecheck fix --id <FINDING_ID>${c.reset}
+`;
+
+  return output;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SARIF OUTPUT (GitHub compatible)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function formatSarif(report) {
+  const sarifSeverity = {
+    critical: "error",
+    high: "error",
+    medium: "warning",
+    low: "note",
+  };
+
+  const sarifLevel = {
+    critical: "error",
+    high: "error",
+    medium: "warning",
+    low: "note",
+  };
+
+  return {
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [{
+      tool: {
+        driver: {
+          name: "vibecheck-audit",
+          version: report.version,
+          informationUri: "https://docs.vibecheckai.dev/audit",
+          rules: [
+            { id: "DEAD_ROUTE", shortDescription: { text: "Dead route - endpoint doesn't exist" } },
+            { id: "GHOST_ENV", shortDescription: { text: "Missing environment variable" } },
+            { id: "FAKE_SUCCESS", shortDescription: { text: "Fake success - no actual operation" } },
+            { id: "AUTH_DRIFT", shortDescription: { text: "Authentication vulnerability" } },
+            { id: "MOCK_LANDMINE", shortDescription: { text: "Mock/TODO code in production" } },
+            { id: "SILENT_FAIL", shortDescription: { text: "Silent error handling" } },
+            { id: "OPTIMISTIC_BOMB", shortDescription: { text: "Optimistic update without rollback" } },
+            { id: "PAID_THEATER", shortDescription: { text: "Paid feature not enforced" } },
+          ],
+        },
+      },
+      results: report.findings.map(f => ({
+        ruleId: f.type,
+        level: sarifLevel[f.severity],
+        message: {
+          text: `${f.title}\n\nWhy it looks right: ${f.whyConvincing}\nWhy it's wrong: ${f.whyWrong}\nHow to prove: ${f.howToProve}\nHow to fix: ${f.howToFix}`,
+        },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: {
+              uri: f.file,
+            },
+            region: {
+              startLine: f.line,
+            },
+          },
+        }],
+        properties: {
+          confidence: f.confidence,
+          blastRadius: f.blastRadius,
+          attackVector: f.attackVector,
+        },
+      })),
+    }],
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MARKDOWN OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function formatMarkdown(report) {
+  const { summary, attackScore, findings, manifest } = report;
+  
+  let md = `# 🔍 AUDIT Report - Convincing Wrongness Detector
+
+> Generated: ${report.timestamp}  
+> Mode: ${report.mode}  
+> Attack Score: **${attackScore}/100**
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | ${summary.critical} |
+| 🟠 High | ${summary.high} |
+| 🟡 Medium | ${summary.medium} |
+| ⚪ Low | ${summary.low} |
+| **Total** | **${summary.total}** |
+
+## Findings by Type
+
+| Type | Count | Description |
+|------|-------|-------------|
+| DEAD_ROUTE | ${summary.byType.DEAD_ROUTE || 0} | Routes that exist but don't work |
+| GHOST_ENV | ${summary.byType.GHOST_ENV || 0} | Env vars used but never declared |
+| FAKE_SUCCESS | ${summary.byType.FAKE_SUCCESS || 0} | UI shows success without operation |
+| AUTH_DRIFT | ${summary.byType.AUTH_DRIFT || 0} | Auth patterns that aren't secure |
+| MOCK_LANDMINE | ${summary.byType.MOCK_LANDMINE || 0} | Mock/TODO in production |
+| SILENT_FAIL | ${summary.byType.SILENT_FAIL || 0} | Errors swallowed silently |
+| OPTIMISTIC_BOMB | ${summary.byType.OPTIMISTIC_BOMB || 0} | Optimistic UI without rollback |
+| PAID_THEATER | ${summary.byType.PAID_THEATER || 0} | Paid features not enforced |
+
+---
+
+## Attack List
+
+`;
+
+  for (let i = 0; i < findings.length; i++) {
+    const f = findings[i];
+    const sevEmoji = f.severity === "critical" ? "🔴" : 
+                     f.severity === "high" ? "🟠" : 
+                     f.severity === "medium" ? "🟡" : "⚪";
+    
+    md += `### ${sevEmoji} #${i + 1}: ${f.title}
+
+- **ID:** \`${f.id}\`
+- **File:** \`${f.file}:${f.line}\`
+- **Type:** ${f.type}
+- **Severity:** ${f.severity}
+- **Confidence:** ${f.confidence}%
+- **Blast Radius:** ${f.blastRadius}/10
+
+\`\`\`
+${f.snippet}
+\`\`\`
+
+| | |
+|---|---|
+| ✅ **Why it looks right** | ${f.whyConvincing} |
+| ❌ **Why it's wrong** | ${f.whyWrong} |
+| 🎯 **How to prove** | ${f.howToProve} |
+| ⭐ **How to fix** | ${f.howToFix} |
+
+---
+
+`;
+  }
+
+  md += `
+## Manifest
+
+\`\`\`json
+${JSON.stringify(manifest, null, 2)}
+\`\`\`
+
+---
+
+*Report generated by [vibecheck audit](https://docs.vibecheckai.dev/audit)*
+`;
+
+  return md;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN RUNNER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function runAudit(args, context = {}) {
+  const opts = parseArgs(args);
+  
+  if (opts.help) {
+    printHelp(shouldShowBanner(opts));
+    return EXIT.SUCCESS;
+  }
+
+  // Determine project path
+  const projectPath = path.resolve(opts.path);
+  
+  if (!fs.existsSync(projectPath)) {
+    console.error(`${c.red}${sym.cross}${c.reset} Path not found: ${projectPath}`);
+    return EXIT.NOT_FOUND;
+  }
+
+  // Show banner unless suppressed
+  if (!opts.quiet && !opts.json && !opts.ci && !opts.noBanner && opts.format === "terminal") {
+    printBanner(projectPath);
+    console.log(`${c.dim}Mode: ${opts.mode}${c.reset}\n`);
+  }
+
+  // Run the detector
+  const { AttackDetector } = require("./lib/engines/attack-detector");
+  const detector = new AttackDetector(projectPath, {
+    mode: opts.mode,
+  });
+
+  let report;
+  try {
+    report = await detector.scan();
+  } catch (err) {
+    console.error(`${c.red}${sym.cross}${c.reset} Scan failed: ${err.message}`);
+    if (opts.verbose) console.error(err.stack);
+    return EXIT.INTERNAL_ERROR;
+  }
+
+  // Format output
+  let output;
+  switch (opts.format) {
+    case "json":
+      output = JSON.stringify(report, null, 2);
+      break;
+    case "sarif":
+      output = JSON.stringify(formatSarif(report), null, 2);
+      break;
+    case "markdown":
+      output = formatMarkdown(report);
+      break;
+    default:
+      output = formatTerminal(report, opts);
+  }
+
+  // Write output
+  if (opts.output) {
+    fs.writeFileSync(opts.output, output);
+    if (!opts.quiet) {
+      console.log(`${c.green}${sym.check}${c.reset} Report written to: ${opts.output}`);
+    }
+  } else if (opts.format === "terminal") {
+    console.log(output);
+  } else {
+    // JSON/SARIF/Markdown to stdout
+    console.log(output);
+  }
+
+  // Determine exit code based on --fail-on
+  if (opts.failOn) {
+    const thresholdOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    const failLevel = thresholdOrder[opts.failOn];
+    
+    if (failLevel !== undefined) {
+      const hasFailure = report.findings.some(f => 
+        thresholdOrder[f.severity] <= failLevel
+      );
+      
+      if (hasFailure) {
+        if (!opts.quiet && opts.format === "terminal") {
+          console.log(`\n${c.red}${sym.cross}${c.reset} Failing due to findings at '${opts.failOn}' level or above.`);
+        }
+        return EXIT.BLOCKING;
+      }
+    }
+  }
+
+  return EXIT.SUCCESS;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  runAudit: withErrorHandling(runAudit, "Audit failed"),
+};