@vibecheckai/cli 3.1.2 → 3.1.4

package/bin/runners/lib/report-engine.js

@@ -1,59 +1,99 @@
 /**
- * Report Engine - World-Class Report Generation
+ * Report Engine - Enterprise Data Processing
  * 
- * Enterprise-grade reporting with:
- * - Multiple output formats (HTML, PDF, MD, JSON, SARIF, CSV)
- * - Beautiful interactive HTML with Chart.js
- * - Executive, Technical, Compliance, and Trend reports
- * - Historical analysis and fix time estimates
- * - Print-optimized layouts
+ * Handles:
+ * - Data normalization from multiple scan sources
+ * - Trend analysis from historical reports
+ * - Export to multiple formats (JSON, SARIF, CSV, Markdown)
+ * - Fix time estimation based on severity and type
+ * - Category scoring and aggregation
  */
 
 const fs = require("fs");
 const path = require("path");
 
-// ============================================================================
-// REPORT DATA MODEL
-// ============================================================================
+// Severity weights for scoring
+const SEVERITY_WEIGHTS = {
+  critical: 25,
+  high: 15,
+  medium: 5,
+  low: 1,
+  info: 0,
+};
+
+// Fix time estimates in minutes by severity
+const FIX_TIME_ESTIMATES = {
+  critical: { min: 45, max: 120, avg: 60 },
+  high: { min: 30, max: 60, avg: 45 },
+  medium: { min: 15, max: 30, avg: 20 },
+  low: { min: 5, max: 15, avg: 10 },
+  info: { min: 2, max: 10, avg: 5 },
+};
+
+// Fix time by finding type
+const TYPE_MULTIPLIERS = {
+  secret: 1.5, // Requires key rotation
+  auth: 2.0, // Complex logic
+  billing: 2.5, // Critical + testing
+  injection: 1.5,
+  xss: 1.2,
+  config: 0.8,
+  quality: 0.5,
+  mock: 0.6,
+  error: 0.7,
+};
 
 /**
- * Build comprehensive report data from ship results
+ * Build comprehensive report data from scan results
  */
-function buildReportData(shipResults, options = {}) {
-  const findings = shipResults?.findings || [];
-  const truthpack = shipResults?.truthpack || {};
+function buildReportData(shipResults, opts = {}) {
+  const { projectName = "Unknown", repoRoot = ".", includeTrends = false } = opts;
+  
+  // Normalize findings
+  const rawFindings = shipResults?.findings || [];
+  const findings = rawFindings.map((f, i) => normalizeFinding(f, i));
   
-  // Severity counts
+  // Calculate severity counts
   const severityCounts = {
-    critical: findings.filter(f => f.severity === "BLOCK" || f.severity === "critical").length,
+    critical: findings.filter(f => f.severity === "critical").length,
     high: findings.filter(f => f.severity === "high").length,
-    medium: findings.filter(f => f.severity === "WARN" || f.severity === "medium").length,
-    low: findings.filter(f => f.severity === "low" || f.severity === "INFO").length,
+    medium: findings.filter(f => f.severity === "medium").length,
+    low: findings.filter(f => f.severity === "low").length,
+    info: findings.filter(f => f.severity === "info").length,
   };
   
-  // Category scores (invert finding counts to scores)
-  const categoryFindings = groupFindingsByCategory(findings);
-  const categoryScores = calculateCategoryScores(categoryFindings);
+  // Calculate score
+  const score = calculateScore(severityCounts, findings.length);
   
-  // Overall score
-  const score = calculateOverallScore(severityCounts, categoryScores);
+  // Determine verdict
+  const verdict = determineVerdict(severityCounts, score);
   
-  // Verdict
-  const verdict = severityCounts.critical > 0 ? "BLOCK" :
-                  severityCounts.high > 0 || severityCounts.medium > 5 ? "WARN" : "SHIP";
+  // Group by category
+  const byCategory = groupByCategory(findings);
+  const categoryScores = calculateCategoryScores(byCategory);
   
-  // Fix time estimates
-  const fixEstimates = estimateFixTimes(findings);
+  // Calculate fix estimates
+  const fixEstimates = calculateFixEstimates(findings);
   
-  // Coverage stats
-  const coverage = extractCoverageStats(truthpack);
+  // Process truthpack
+  const truthpack = processTruthpack(shipResults?.truthpack);
+  
+  // Process reality data
+  const reality = processReality(shipResults?.reality);
+  
+  // Load trends if requested
+  let trends = null;
+  if (includeTrends) {
+    trends = loadTrends(repoRoot);
+  }
   
   return {
     meta: {
-      projectName: options.projectName || truthpack?.project?.name || path.basename(process.cwd()),
+      projectName,
       generatedAt: new Date().toISOString(),
       version: "2.0.0",
       reportId: generateReportId(),
+      repoRoot,
     },
     summary: {
       score,
@@ -61,294 +101,416 @@ function buildReportData(shipResults, options = {}) {
       totalFindings: findings.length,
       severityCounts,
       categoryScores,
+      topBlockers: findings.filter(f => f.severity === "critical").slice(0, 5),
     },
-    findings: enrichFindings(findings),
-    coverage,
+    findings,
     fixEstimates,
-    truthpack: {
-      routes: truthpack?.routes?.server?.length || 0,
-      envVars: truthpack?.env?.vars?.length || 0,
-      hasAuth: !!(truthpack?.auth?.nextMiddleware?.length || truthpack?.auth?.fastify?.hooks?.length),
-      hasBilling: !!truthpack?.billing?.webhooks?.length,
-    },
-    trends: options.includeTrends ? loadHistoricalTrends(options.repoRoot) : null,
+    truthpack,
+    reality,
+    trends,
   };
 }
 
-function groupFindingsByCategory(findings) {
-  const groups = {
-    security: [],
-    auth: [],
-    billing: [],
-    routes: [],
-    env: [],
-    quality: [],
-    other: [],
-  };
-  
-  for (const f of findings) {
-    const cat = categorizeFindings(f);
-    if (groups[cat]) {
-      groups[cat].push(f);
-    } else {
-      groups.other.push(f);
-    }
-  }
+/**
+ * Normalize a finding to consistent format
+ */
+function normalizeFinding(f, index) {
+  const severity = normalizeSeverity(f.severity);
+  const type = normalizeType(f.type || f.category);
   
-  return groups;
+  return {
+    id: f.id || `F${String(index + 1).padStart(3, "0")}`,
+    severity,
+    type,
+    title: f.title || f.message || "Unknown issue",
+    message: f.message || f.title || "",
+    description: f.description || "",
+    file: f.file || f.path || null,
+    line: f.line || f.lineNumber || null,
+    column: f.column || null,
+    fix: f.fix || f.recommendation || f.suggestion || null,
+    cwe: f.cwe || null,
+    references: f.references || [],
+    confidence: f.confidence || "high",
+    falsePositive: f.falsePositive || false,
+  };
 }
 
-function categorizeFindings(finding) {
-  const type = (finding.type || finding.id || "").toLowerCase();
-  const msg = (finding.message || finding.title || "").toLowerCase();
-  
-  if (type.includes("auth") || msg.includes("auth") || msg.includes("session")) return "auth";
-  if (type.includes("billing") || type.includes("stripe") || msg.includes("payment")) return "billing";
-  if (type.includes("route") || type.includes("endpoint") || msg.includes("route")) return "routes";
-  if (type.includes("env") || msg.includes("environment")) return "env";
-  if (type.includes("secret") || type.includes("security") || msg.includes("secret")) return "security";
-  if (type.includes("mock") || type.includes("fake") || msg.includes("console")) return "quality";
-  return "other";
+/**
+ * Normalize severity to standard values
+ */
+function normalizeSeverity(sev) {
+  const s = String(sev || "").toLowerCase();
+  if (s === "block" || s === "critical" || s === "blocker") return "critical";
+  if (s === "high" || s === "error") return "high";
+  if (s === "warn" || s === "warning" || s === "medium") return "medium";
+  if (s === "info" || s === "low" || s === "note") return "low";
+  return "info";
 }
 
-function calculateCategoryScores(categoryFindings) {
-  const scores = {};
-  const weights = {
-    security: { max: 100, perFinding: 20 },
-    auth: { max: 100, perFinding: 15 },
-    billing: { max: 100, perFinding: 15 },
-    routes: { max: 100, perFinding: 10 },
-    env: { max: 100, perFinding: 5 },
-    quality: { max: 100, perFinding: 5 },
+/**
+ * Normalize finding type
+ */
+function normalizeType(type) {
+  const t = String(type || "").toLowerCase();
+  const typeMap = {
+    secret: ["secret", "credential", "key", "token", "password", "api_key"],
+    auth: ["auth", "authentication", "authorization", "session", "jwt"],
+    billing: ["billing", "payment", "stripe", "subscription", "checkout"],
+    injection: ["injection", "sql", "nosql", "command", "ldap"],
+    xss: ["xss", "cross-site", "script"],
+    config: ["config", "configuration", "env", "environment"],
+    quality: ["quality", "lint", "style", "format"],
+    mock: ["mock", "stub", "fake", "dummy", "placeholder"],
+    error: ["error", "exception", "catch", "handling"],
+    route: ["route", "endpoint", "path", "url"],
   };
   
-  for (const [cat, findings] of Object.entries(categoryFindings)) {
-    if (cat === "other") continue;
-    const w = weights[cat] || { max: 100, perFinding: 10 };
-    scores[cat] = Math.max(0, w.max - (findings.length * w.perFinding));
+  for (const [category, keywords] of Object.entries(typeMap)) {
+    if (keywords.some(k => t.includes(k))) return category;
   }
-  
-  return scores;
+  return "other";
 }
 
-function calculateOverallScore(severityCounts, categoryScores) {
-  // Weighted average of category scores with severity penalties
-  const categoryAvg = Object.values(categoryScores).reduce((a, b) => a + b, 0) / 
-                      Math.max(1, Object.keys(categoryScores).length);
+/**
+ * Calculate overall score
+ */
+function calculateScore(severityCounts, totalFindings) {
+  if (totalFindings === 0) return 100;
   
-  // Severity penalties
-  const penalties = 
-    (severityCounts.critical * 25) +
-    (severityCounts.high * 10) +
-    (severityCounts.medium * 3) +
-    (severityCounts.low * 1);
+  const deductions =
+    severityCounts.critical * SEVERITY_WEIGHTS.critical +
+    severityCounts.high * SEVERITY_WEIGHTS.high +
+    severityCounts.medium * SEVERITY_WEIGHTS.medium +
+    severityCounts.low * SEVERITY_WEIGHTS.low;
   
-  return Math.max(0, Math.min(100, Math.round(categoryAvg - penalties)));
+  // Cap deductions at 100
+  const score = Math.max(0, 100 - deductions);
+  return Math.round(score);
 }
 
-function enrichFindings(findings) {
-  return findings.map((f, idx) => ({
-    id: f.id || `F${String(idx + 1).padStart(3, "0")}`,
-    severity: normalizeSeverity(f.severity),
-    category: categorizeFindings(f),
-    title: f.title || f.message || "Finding",
-    description: f.description || f.message || "",
-    file: f.file || f.evidence?.file || null,
-    line: f.line || f.evidence?.line || null,
-    fix: f.fix || f.recommendation || null,
-    fixTime: estimateSingleFixTime(f),
-    evidence: f.evidence || null,
-  }));
+/**
+ * Determine verdict from score and findings
+ */
+function determineVerdict(severityCounts, score) {
+  if (severityCounts.critical > 0) return "BLOCK";
+  if (severityCounts.high > 2 || score < 60) return "BLOCK";
+  if (severityCounts.high > 0 || severityCounts.medium > 5 || score < 80) return "WARN";
+  return "SHIP";
 }
 
-function normalizeSeverity(sev) {
-  const s = String(sev || "medium").toLowerCase();
-  if (s === "block" || s === "critical") return "critical";
-  if (s === "high") return "high";
-  if (s === "warn" || s === "warning" || s === "medium") return "medium";
-  return "low";
+/**
+ * Group findings by category
+ */
+function groupByCategory(findings) {
+  const groups = {};
+  for (const f of findings) {
+    const cat = f.type || "other";
+    if (!groups[cat]) groups[cat] = [];
+    groups[cat].push(f);
+  }
+  return groups;
 }
 
-function estimateFixTimes(findings) {
-  const times = {
-    critical: { count: 0, totalMinutes: 0 },
-    high: { count: 0, totalMinutes: 0 },
-    medium: { count: 0, totalMinutes: 0 },
-    low: { count: 0, totalMinutes: 0 },
-  };
+/**
+ * Calculate category scores
+ */
+function calculateCategoryScores(byCategory) {
+  const scores = {};
   
-  for (const f of findings) {
-    const sev = normalizeSeverity(f.severity);
-    const mins = estimateSingleFixTime(f);
-    if (times[sev]) {
-      times[sev].count++;
-      times[sev].totalMinutes += mins;
-    }
+  for (const [cat, findings] of Object.entries(byCategory)) {
+    const deductions = findings.reduce((sum, f) => {
+      return sum + (SEVERITY_WEIGHTS[f.severity] || 0);
+    }, 0);
+    
+    scores[cat] = Math.max(0, Math.min(100, 100 - deductions));
   }
   
-  const totalMinutes = Object.values(times).reduce((a, t) => a + t.totalMinutes, 0);
-  
-  return {
-    bySeverity: times,
-    totalMinutes,
-    totalHours: Math.round(totalMinutes / 60 * 10) / 10,
-    humanReadable: formatDuration(totalMinutes),
-  };
+  return scores;
 }
 
-function estimateSingleFixTime(finding) {
-  const sev = normalizeSeverity(finding.severity);
-  const type = (finding.type || finding.id || "").toLowerCase();
+/**
+ * Calculate fix time estimates
+ */
+function calculateFixEstimates(findings) {
+  let totalMin = 0;
+  let totalMax = 0;
+  let totalAvg = 0;
   
-  // Base times by severity
-  const baseTimes = { critical: 60, high: 30, medium: 15, low: 5 };
-  let mins = baseTimes[sev] || 15;
+  const bySeverity = {};
   
-  // Adjustments by type
-  if (type.includes("auth") || type.includes("security")) mins *= 1.5;
-  if (type.includes("mock") || type.includes("console")) mins *= 0.5;
+  for (const f of findings) {
+    const sev = f.severity;
+    const type = f.type;
+    const base = FIX_TIME_ESTIMATES[sev] || FIX_TIME_ESTIMATES.medium;
+    const multiplier = TYPE_MULTIPLIERS[type] || 1.0;
+    
+    totalMin += Math.round(base.min * multiplier);
+    totalMax += Math.round(base.max * multiplier);
+    totalAvg += Math.round(base.avg * multiplier);
+    
+    if (!bySeverity[sev]) bySeverity[sev] = { count: 0, minutes: 0 };
+    bySeverity[sev].count++;
+    bySeverity[sev].minutes += Math.round(base.avg * multiplier);
+  }
   
-  return Math.round(mins);
+  return {
+    totalMinutes: totalAvg,
+    range: { min: totalMin, max: totalMax },
+    humanReadable: formatDuration(totalAvg),
+    rangeReadable: `${formatDuration(totalMin)} - ${formatDuration(totalMax)}`,
+    bySeverity,
+  };
 }
 
+/**
+ * Format duration in minutes to human readable
+ */
 function formatDuration(minutes) {
-  if (minutes < 60) return `${minutes} min`;
-  const hours = Math.floor(minutes / 60);
-  const mins = minutes % 60;
-  if (mins === 0) return `${hours}h`;
-  return `${hours}h ${mins}m`;
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60 * 10) / 10;
+  if (hours < 8) return `${hours}h`;
+  const days = Math.round(hours / 8 * 10) / 10;
+  return `${days}d`;
 }
 
-function extractCoverageStats(truthpack) {
+/**
+ * Process truthpack data
+ */
+function processTruthpack(truthpack) {
+  if (!truthpack) return null;
+  
   return {
-    routes: {
-      total: truthpack?.routes?.server?.length || 0,
-      protected: truthpack?.routes?.server?.filter(r => r.protected)?.length || 0,
-      tested: truthpack?.routes?.coverage?.hit || 0,
-    },
-    env: {
-      total: truthpack?.env?.vars?.length || 0,
-      declared: truthpack?.env?.declared?.length || 0,
-    },
-    auth: {
-      middlewareCount: truthpack?.auth?.nextMiddleware?.length || 0,
-      patterns: truthpack?.auth?.nextMatcherPatterns?.length || 0,
+    routes: Array.isArray(truthpack.routes?.server) ? truthpack.routes.server.length : 0,
+    envVars: Array.isArray(truthpack.env?.vars) ? truthpack.env.vars.length : 0,
+    hasAuth: !!(truthpack.auth?.nextMiddleware?.length || truthpack.auth?.middleware?.length),
+    hasBilling: !!(truthpack.billing?.webhooks?.length || truthpack.billing?.stripeConfig),
+    rawCounts: {
+      serverRoutes: truthpack.routes?.server?.length || 0,
+      clientRoutes: truthpack.routes?.client?.length || 0,
+      envVars: truthpack.env?.vars?.length || 0,
+      authMiddleware: truthpack.auth?.nextMiddleware?.length || truthpack.auth?.middleware?.length || 0,
+      webhooks: truthpack.billing?.webhooks?.length || 0,
     },
   };
 }
 
-function generateReportId() {
-  const date = new Date().toISOString().split("T")[0].replace(/-/g, "");
-  const rand = Math.random().toString(36).substring(2, 8).toUpperCase();
-  return `VC-${date}-${rand}`;
+/**
+ * Process reality mode data
+ */
+function processReality(reality) {
+  if (!reality) return null;
+  
+  return {
+    coverage: reality.coverage || {},
+    brokenFlows: reality.brokenFlows || [],
+    unmappedRequests: reality.unmappedRequests || [],
+    latencyP95: reality.latencyP95 || null,
+    latencySparkline: reality.latencySparkline || [],
+    requestsOverTime: reality.requestsOverTime || [],
+    totalRequests: reality.totalRequests || 0,
+  };
 }
 
-function loadHistoricalTrends(repoRoot) {
-  // Try to load previous reports for trend analysis
-  const historyPath = path.join(repoRoot || process.cwd(), ".vibecheck", "history");
-  if (!fs.existsSync(historyPath)) return null;
+/**
+ * Load historical trends
+ */
+function loadTrends(repoRoot) {
+  const historyDir = path.join(repoRoot, ".vibecheck", "history");
+  if (!fs.existsSync(historyDir)) return null;
   
   try {
-    const files = fs.readdirSync(historyPath)
+    const files = fs.readdirSync(historyDir)
       .filter(f => f.endsWith(".json"))
       .sort()
-      .slice(-10);
+      .slice(-30); // Last 30 entries
+    
+    const dataPoints = files.map(f => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(historyDir, f), "utf8"));
+        return {
+          date: f.replace(".json", ""),
+          score: data.summary?.score || 0,
+          findings: data.summary?.totalFindings || 0,
+          critical: data.summary?.severityCounts?.critical || 0,
+        };
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+    
+    if (dataPoints.length === 0) return null;
+    
+    // Calculate trend
+    const scores = dataPoints.map(d => d.score);
+    const trend = scores.length >= 2 ? scores[scores.length - 1] - scores[0] : 0;
     
-    return files.map(f => {
-      const data = JSON.parse(fs.readFileSync(path.join(historyPath, f), "utf8"));
-      return {
-        date: data.meta?.generatedAt || f.replace(".json", ""),
-        score: data.summary?.score || 0,
-        findings: data.summary?.totalFindings || 0,
-      };
-    });
+    return {
+      dataPoints,
+      trend,
+      trendDirection: trend > 0 ? "improving" : trend < 0 ? "declining" : "stable",
+      averageScore: Math.round(scores.reduce((a, b) => a + b, 0) / scores.length),
+    };
   } catch {
     return null;
   }
 }
 
+/**
+ * Generate unique report ID
+ */
+function generateReportId() {
+  const timestamp = Date.now().toString(36).toUpperCase();
+  const random = Math.random().toString(36).substring(2, 6).toUpperCase();
+  return `VC-${timestamp}-${random}`;
+}
+
 // ============================================================================
 // EXPORT FORMATS
 // ============================================================================
 
 /**
- * Export to SARIF format (Static Analysis Results Interchange Format)
+ * Export to JSON
+ */
+function exportToJSON(reportData) {
+  return JSON.stringify(reportData, null, 2);
+}
+
+/**
+ * Export to SARIF format
  */
 function exportToSARIF(reportData) {
+  const rules = new Map();
+  const results = [];
+  
+  for (const f of reportData.findings) {
+    // Build rule if not exists
+    if (!rules.has(f.id)) {
+      rules.set(f.id, {
+        id: f.id,
+        name: f.type ? `${f.type}/${f.id}` : f.id,
+        shortDescription: { text: f.title },
+        fullDescription: { text: f.description || f.message },
+        defaultConfiguration: {
+          level: sarifLevel(f.severity),
+        },
+        helpUri: f.references?.[0] || "https://vibecheck.dev/docs",
+        properties: {
+          category: f.type,
+          cwe: f.cwe,
+        },
+      });
+    }
+    
+    // Build result
+    const result = {
+      ruleId: f.id,
+      level: sarifLevel(f.severity),
+      message: { text: f.message || f.title },
+      locations: [],
+    };
+    
+    if (f.file) {
+      result.locations.push({
+        physicalLocation: {
+          artifactLocation: { uri: f.file },
+          region: f.line ? { startLine: f.line, startColumn: f.column || 1 } : undefined,
+        },
+      });
+    }
+    
+    if (f.fix) {
+      result.fixes = [{
+        description: { text: f.fix },
+      }];
+    }
+    
+    results.push(result);
+  }
+  
   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",
+          name: "VibeCheck",
           version: reportData.meta.version,
           informationUri: "https://vibecheck.dev",
-          rules: generateSARIFRules(reportData.findings),
+          rules: Array.from(rules.values()),
         },
       },
-      results: reportData.findings.map(f => ({
-        ruleId: f.id,
-        level: sarifLevel(f.severity),
-        message: { text: f.title },
-        locations: f.file ? [{
-          physicalLocation: {
-            artifactLocation: { uri: f.file },
-            region: f.line ? { startLine: f.line } : undefined,
-          },
-        }] : [],
-      })),
+      results,
+      invocations: [{
+        executionSuccessful: true,
+        endTimeUtc: reportData.meta.generatedAt,
+      }],
     }],
   };
 }
 
-function generateSARIFRules(findings) {
-  const seen = new Set();
-  return findings
-    .filter(f => {
-      if (seen.has(f.id)) return false;
-      seen.add(f.id);
-      return true;
-    })
-    .map(f => ({
-      id: f.id,
-      shortDescription: { text: f.title },
-      fullDescription: { text: f.description || f.title },
-      defaultConfiguration: { level: sarifLevel(f.severity) },
-    }));
-}
-
+/**
+ * Convert severity to SARIF level
+ */
 function sarifLevel(severity) {
-  const levels = { critical: "error", high: "error", medium: "warning", low: "note" };
+  const levels = { critical: "error", high: "error", medium: "warning", low: "note", info: "none" };
   return levels[severity] || "warning";
 }
 
 /**
- * Export to CSV format
+ * Export to CSV
  */
 function exportToCSV(reportData) {
-  const headers = ["ID", "Severity", "Category", "Title", "File", "Line", "Fix Time (min)"];
+  const headers = [
+    "ID",
+    "Severity",
+    "Type",
+    "Title",
+    "File",
+    "Line",
+    "Fix",
+    "CWE",
+    "Confidence",
+  ];
+  
   const rows = reportData.findings.map(f => [
     f.id,
     f.severity,
-    f.category,
-    `"${(f.title || "").replace(/"/g, '""')}"`,
+    f.type,
+    csvEscape(f.title),
     f.file || "",
     f.line || "",
-    f.fixTime || "",
+    csvEscape(f.fix || ""),
+    f.cwe || "",
+    f.confidence,
   ]);
   
-  return [headers.join(","), ...rows.map(r => r.join(","))].join("\n");
+  return [
+    headers.join(","),
+    ...rows.map(r => r.join(",")),
+  ].join("\n");
 }
 
 /**
- * Export to Markdown format
+ * Escape CSV value
  */
-function exportToMarkdown(reportData, options = {}) {
-  const { meta, summary, findings, fixEstimates, coverage } = reportData;
-  const verdictEmoji = summary.verdict === "SHIP" ? "✅" : summary.verdict === "WARN" ? "⚠️" : "🚫";
+function csvEscape(val) {
+  if (!val) return "";
+  const str = String(val);
+  if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+/**
+ * Export to Markdown
+ */
+function exportToMarkdown(reportData, opts = {}) {
+  const { meta, summary, findings, fixEstimates, reality } = reportData;
+  const redactPaths = opts.redactPaths || false;
   
-  let md = `# ${options.title || "Vibecheck Report"}
+  let md = `# VibeCheck Report
 
 **Project:** ${meta.projectName}  
 **Generated:** ${new Date(meta.generatedAt).toLocaleString()}  
@@ -360,25 +522,14 @@ function exportToMarkdown(reportData, options = {}) {
 
 | Metric | Value |
 |--------|-------|
-| **Score** | ${summary.score}/100 |
-| **Verdict** | ${verdictEmoji} ${summary.verdict} |
-| **Total Findings** | ${summary.totalFindings} |
-| **Est. Fix Time** | ${fixEstimates.humanReadable} |
-
-### Severity Breakdown
-
-| Severity | Count |
-|----------|-------|
-| 🔴 Critical | ${summary.severityCounts.critical} |
-| 🟠 High | ${summary.severityCounts.high} |
-| 🟡 Medium | ${summary.severityCounts.medium} |
-| ⚪ Low | ${summary.severityCounts.low} |
-
-### Category Scores
-
-| Category | Score |
-|----------|-------|
-${Object.entries(summary.categoryScores).map(([k, v]) => `| ${formatCategoryName(k)} | ${v}% |`).join("\n")}
+| Score | **${summary.score}/100** |
+| Verdict | **${summary.verdict}** |
+| Total Findings | ${summary.totalFindings} |
+| Critical | ${summary.severityCounts.critical} |
+| High | ${summary.severityCounts.high} |
+| Medium | ${summary.severityCounts.medium} |
+| Low | ${summary.severityCounts.low} |
+| Est. Fix Time | ${fixEstimates?.humanReadable || 'N/A'} |
 
 ---
 
@@ -387,61 +538,89 @@ ${Object.entries(summary.categoryScores).map(([k, v]) => `| ${formatCategoryName
 `;
 
   // Group by severity
-  const bySeverity = { critical: [], high: [], medium: [], low: [] };
-  for (const f of findings) {
-    if (bySeverity[f.severity]) bySeverity[f.severity].push(f);
-  }
+  const bySeverity = {
+    critical: findings.filter(f => f.severity === "critical"),
+    high: findings.filter(f => f.severity === "high"),
+    medium: findings.filter(f => f.severity === "medium"),
+    low: findings.filter(f => f.severity === "low"),
+  };
   
   for (const [sev, items] of Object.entries(bySeverity)) {
     if (items.length === 0) continue;
-    md += `### ${sev.charAt(0).toUpperCase() + sev.slice(1)} (${items.length})\n\n`;
-    for (const f of items.slice(0, options.maxFindings || 20)) {
-      md += `#### ${f.id}: ${f.title}\n`;
-      if (f.file) md += `- **File:** \`${f.file}${f.line ? `:${f.line}` : ""}\`\n`;
-      if (f.fix) md += `- **Fix:** ${f.fix}\n`;
-      md += `\n`;
+    
+    md += `### ${sev.toUpperCase()} (${items.length})\n\n`;
+    
+    for (const f of items.slice(0, 20)) {
+      const file = redactPaths && f.file ? redactPath(f.file) : f.file;
+      md += `- **${f.title}**\n`;
+      if (file) md += `  - File: \`${file}${f.line ? `:${f.line}` : ''}\`\n`;
+      if (f.fix) md += `  - Fix: ${f.fix}\n`;
+      md += "\n";
+    }
+    
+    if (items.length > 20) {
+      md += `_...and ${items.length - 20} more ${sev} findings_\n\n`;
     }
   }
   
-  md += `---
-
-*Generated by [Vibecheck](https://vibecheck.dev) · ${meta.reportId}*
-`;
+  // Reality section if available
+  if (reality && (reality.brokenFlows?.length > 0 || Object.keys(reality.coverage).length > 0)) {
+    md += `---\n\n## Reality Mode\n\n`;
+    
+    if (Object.keys(reality.coverage).length > 0) {
+      md += `### Coverage\n\n`;
+      for (const [key, val] of Object.entries(reality.coverage)) {
+        md += `- ${formatCoverageKey(key)}: **${val}%**\n`;
+      }
+      md += "\n";
+    }
+    
+    if (reality.brokenFlows?.length > 0) {
+      md += `### Broken Flows (${reality.brokenFlows.length})\n\n`;
+      for (const flow of reality.brokenFlows.slice(0, 5)) {
+        md += `- **${flow.title}** (${flow.severity})\n`;
+        if (flow.steps) {
+          md += `  - Steps: ${flow.steps.map(s => s.label).join(' → ')}\n`;
+        }
+      }
+      md += "\n";
+    }
+  }
+  
+  md += `---\n\n*Generated by [VibeCheck](https://vibecheck.dev)*\n`;
   
   return md;
 }
 
 /**
- * Export to JSON format
+ * Helper: redact file path
  */
-function exportToJSON(reportData) {
-  return JSON.stringify(reportData, null, 2);
+function redactPath(p) {
+  if (!p) return p;
+  const parts = p.split("/");
+  if (parts.length <= 2) return p;
+  return ".../" + parts.slice(-2).join("/");
 }
 
-function formatCategoryName(name) {
-  const names = {
-    security: "Security",
-    auth: "Authentication",
-    billing: "Billing/Payments",
-    routes: "Route Integrity",
-    env: "Environment",
-    quality: "Code Quality",
-  };
-  return names[name] || name.charAt(0).toUpperCase() + name.slice(1);
+/**
+ * Helper: format coverage key
+ */
+function formatCoverageKey(key) {
+  return key
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, s => s.toUpperCase())
+    .trim();
 }
 
-// ============================================================================
-// EXPORTS
-// ============================================================================
-
 module.exports = {
   buildReportData,
+  exportToJSON,
   exportToSARIF,
   exportToCSV,
   exportToMarkdown,
-  exportToJSON,
-  formatCategoryName,
+  // Expose helpers for testing
+  normalizeFinding,
   normalizeSeverity,
-  estimateFixTimes,
-  generateReportId,
+  calculateScore,
+  calculateFixEstimates,
 };