vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/lib/why-tree.js

@@ -0,0 +1,650 @@
+/**
+ * Why Tree - Evidence Chain Builder
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * CLEAR "WHY" FOR EVERY VERDICT
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Builds a human-readable evidence chain for verdicts:
+ * - Top 3 blockers with file:line evidence
+ * - Fix missions (actionable next steps)
+ * - Proof chain (how we know this is true)
+ * 
+ * @module why-tree
+ * @version 1.1.0 - Hardened
+ */
+
+"use strict";
+
+const path = require("path");
+const crypto = require("crypto");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const MAX_STRING_LENGTH = 500;
+const MAX_BLOCKERS = 10;
+const MAX_WARNINGS = 20;
+const MAX_FIX_MISSIONS = 10;
+const MAX_EVIDENCE_ITEMS = 5;
+
+// Characters to strip from output (prevent terminal injection)
+const UNSAFE_CHARS = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\u001B]/g;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// INPUT SANITIZATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Sanitize a string for safe output (prevent injection)
+ * @param {*} str - Input to sanitize
+ * @param {number} maxLen - Maximum length
+ * @returns {string|null} Sanitized string or null
+ */
+function sanitize(str, maxLen = MAX_STRING_LENGTH) {
+  if (str === null || str === undefined) {
+    return null;
+  }
+
+  const s = String(str)
+    .replace(UNSAFE_CHARS, "") // Remove unsafe characters
+    .trim();
+
+  if (!s) {
+    return null;
+  }
+
+  return s.length > maxLen ? s.slice(0, maxLen - 3) + "..." : s;
+}
+
+/**
+ * Validate and sanitize a finding object
+ * @param {*} finding - Finding to validate
+ * @returns {Object|null} Validated finding or null
+ */
+function validateFinding(finding) {
+  if (!finding || typeof finding !== "object") {
+    return null;
+  }
+
+  // Must have at least a title or message
+  const title = sanitize(finding.title || finding.message);
+  if (!title) {
+    return null;
+  }
+
+  return {
+    id: sanitize(finding.id || finding.fingerprint, 64),
+    category: sanitize(finding.category, 50) || "Unknown",
+    severity: validateSeverity(finding.severity),
+    title,
+    why: sanitize(finding.why || finding.explanation),
+    confidence: validateConfidence(finding.confidence),
+    evidence: validateEvidence(finding.evidence),
+    fixHints: validateFixHints(finding.fixHints),
+    fingerprint: sanitize(finding.fingerprint, 64),
+    detectorId: sanitize(finding.detectorId, 50),
+  };
+}
+
+/**
+ * Validate severity
+ */
+function validateSeverity(sev) {
+  const valid = ["BLOCK", "WARN", "INFO"];
+  const s = String(sev || "").toUpperCase();
+  return valid.includes(s) ? s : "INFO";
+}
+
+/**
+ * Validate confidence
+ */
+function validateConfidence(conf) {
+  const valid = ["high", "medium", "low"];
+  const c = String(conf || "").toLowerCase();
+  return valid.includes(c) ? c : "medium";
+}
+
+/**
+ * Validate evidence array
+ */
+function validateEvidence(evidence) {
+  if (!Array.isArray(evidence)) {
+    return [];
+  }
+
+  return evidence
+    .slice(0, MAX_EVIDENCE_ITEMS)
+    .map(e => {
+      if (!e || typeof e !== "object") return null;
+      return {
+        file: sanitize(e.file || e.path, 300),
+        lines: sanitize(e.lines, 20),
+        line: typeof e.line === "number" ? Math.max(0, Math.floor(e.line)) : null,
+        snippet: sanitize(e.snippet, 200),
+        kind: sanitize(e.kind, 20) || "file",
+      };
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Validate fix hints
+ */
+function validateFixHints(hints) {
+  if (!Array.isArray(hints)) {
+    return [];
+  }
+  return hints
+    .slice(0, 5)
+    .map(h => sanitize(h, MAX_STRING_LENGTH))
+    .filter(Boolean);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// WHY TREE BUILDER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build a comprehensive why tree from findings.
+ * 
+ * The why tree answers: "Why did we get this verdict?"
+ * 
+ * @param {Array} findings - All findings
+ * @param {Object} options - Options
+ * @returns {Object} Why tree structure (always returns valid object)
+ */
+function buildWhyTree(findings = [], options = {}) {
+  // Validate options
+  const opts = options || {};
+  const maxBlockers = Math.min(Math.max(1, Number(opts.maxBlockers) || 3), MAX_BLOCKERS);
+  const maxWarnings = Math.min(Math.max(1, Number(opts.maxWarnings) || 5), MAX_WARNINGS);
+  const maxFixMissions = Math.min(Math.max(1, Number(opts.maxFixMissions) || 5), MAX_FIX_MISSIONS);
+  const includeEvidence = opts.includeEvidence !== false;
+  const includeProofChain = opts.includeProofChain !== false;
+
+  // Validate and filter findings
+  const validFindings = (Array.isArray(findings) ? findings : [])
+    .map(validateFinding)
+    .filter(Boolean);
+
+  // Separate by severity
+  const blockers = validFindings
+    .filter(f => f.severity === "BLOCK")
+    .sort((a, b) => getConfidenceScore(b) - getConfidenceScore(a));
+
+  const warnings = validFindings
+    .filter(f => f.severity === "WARN")
+    .sort((a, b) => getConfidenceScore(b) - getConfidenceScore(a));
+
+  const info = validFindings.filter(f => f.severity === "INFO");
+
+  // Build tree structure with safe defaults
+  const tree = {
+    verdict: blockers.length > 0 ? "BLOCK" : warnings.length > 0 ? "WARN" : "SHIP",
+    summary: buildSummary(blockers, warnings),
+    
+    // Top blockers with full evidence
+    topBlockers: blockers.slice(0, maxBlockers).map((b, i) => ({
+      rank: i + 1,
+      ...buildIssueNode(b, includeEvidence, includeProofChain),
+    })),
+    
+    // Top warnings (if no blockers)
+    topWarnings: blockers.length === 0 
+      ? warnings.slice(0, maxWarnings).map((w, i) => ({
+          rank: i + 1,
+          ...buildIssueNode(w, includeEvidence, false),
+        }))
+      : [],
+    
+    // Fix missions (actionable next steps)
+    fixMissions: buildFixMissions(blockers, warnings, maxFixMissions),
+    
+    // Stats
+    stats: {
+      totalFindings: validFindings.length,
+      blockers: blockers.length,
+      warnings: warnings.length,
+      info: info.length,
+      byCategory: groupByCategory(validFindings),
+    },
+  };
+
+  return tree;
+}
+
+/**
+ * Build summary text based on findings
+ */
+function buildSummary(blockers, warnings) {
+  if (blockers.length === 0 && warnings.length === 0) {
+    return "All checks passed. Ready to ship.";
+  }
+
+  const parts = [];
+
+  if (blockers.length > 0) {
+    parts.push(`${blockers.length} blocker${blockers.length !== 1 ? "s" : ""} must be fixed`);
+  }
+
+  if (warnings.length > 0) {
+    parts.push(`${warnings.length} warning${warnings.length !== 1 ? "s" : ""} to review`);
+  }
+
+  return parts.join(", ") + ".";
+}
+
+/**
+ * Build an issue node with evidence
+ */
+function buildIssueNode(finding, includeEvidence, includeProofChain) {
+  const node = {
+    id: finding.fingerprint || finding.id || sha256Short(finding.title || ""),
+    category: finding.category,
+    severity: finding.severity,
+    title: finding.title || finding.message,
+    why: finding.why || finding.explanation || null,
+    confidence: finding.confidence || "medium",
+  };
+
+  // Add evidence
+  if (includeEvidence && finding.evidence?.length > 0) {
+    node.evidence = finding.evidence.slice(0, 3).map(formatEvidence);
+    node.primaryLocation = formatPrimaryLocation(finding);
+  }
+
+  // Add fix hints
+  if (finding.fixHints?.length > 0) {
+    node.fixHint = finding.fixHints[0];
+    node.allFixHints = finding.fixHints;
+  }
+
+  // Add proof chain (how we know this)
+  if (includeProofChain) {
+    node.proofChain = buildProofChain(finding);
+  }
+
+  return node;
+}
+
+/**
+ * Format evidence for display
+ */
+function formatEvidence(ev) {
+  return {
+    file: ev.file || ev.path || null,
+    lines: ev.lines || (ev.line ? String(ev.line) : null),
+    snippet: ev.snippet ? truncate(ev.snippet, 100) : null,
+    kind: ev.kind || "file",
+    snippetHash: ev.snippetHash || null,
+  };
+}
+
+/**
+ * Format primary location as a clickable reference
+ */
+function formatPrimaryLocation(finding) {
+  const ev = finding.evidence?.[0];
+  if (!ev) return null;
+
+  const file = ev.file || ev.path;
+  if (!file) return null;
+
+  const line = ev.lines?.split("-")[0] || ev.line;
+
+  return {
+    file,
+    line: line ? parseInt(line) : null,
+    display: line ? `${file}:${line}` : file,
+    vscodeUri: line ? `vscode://file/${file}:${line}` : `vscode://file/${file}`,
+  };
+}
+
+/**
+ * Build proof chain (how we know this finding is true)
+ */
+function buildProofChain(finding) {
+  const chain = [];
+
+  // Add detector info
+  if (finding.detectorId || finding.detector) {
+    chain.push({
+      step: "detected",
+      by: finding.detectorId || finding.detector,
+      type: finding.detectorType || "static",
+    });
+  }
+
+  // Add evidence verification
+  if (finding.evidence?.length > 0) {
+    const ev = finding.evidence[0];
+    chain.push({
+      step: "verified",
+      method: ev.kind === "runtime" ? "runtime" : "file-citation",
+      confidence: finding.confidence || "medium",
+      at: ev.file ? `${ev.file}:${ev.lines || ev.line || ""}` : "unknown",
+    });
+  }
+
+  // Add cross-reference if available
+  if (finding.crossRef) {
+    chain.push({
+      step: "cross-referenced",
+      with: finding.crossRef.type,
+      matches: finding.crossRef.matches,
+    });
+  }
+
+  return chain.length > 0 ? chain : null;
+}
+
+/**
+ * Build fix missions (prioritized action items)
+ */
+function buildFixMissions(blockers, warnings, max) {
+  const missions = [];
+
+  // Priority 1: Blockers
+  for (const b of blockers.slice(0, max)) {
+    missions.push({
+      priority: "critical",
+      category: b.category,
+      target: b.evidence?.[0]?.file || "unknown",
+      action: b.fixHints?.[0] || `Fix ${b.category} issue: ${truncate(b.title, 50)}`,
+      findingId: b.fingerprint || b.id,
+    });
+  }
+
+  // Priority 2: Warnings (if room)
+  const remaining = max - missions.length;
+  if (remaining > 0) {
+    for (const w of warnings.slice(0, remaining)) {
+      missions.push({
+        priority: "recommended",
+        category: w.category,
+        target: w.evidence?.[0]?.file || "unknown",
+        action: w.fixHints?.[0] || `Address ${w.category} warning: ${truncate(w.title, 50)}`,
+        findingId: w.fingerprint || w.id,
+      });
+    }
+  }
+
+  return missions;
+}
+
+/**
+ * Group findings by category
+ */
+function groupByCategory(findings) {
+  const groups = {};
+
+  for (const f of findings) {
+    const cat = f.category || "Other";
+    if (!groups[cat]) {
+      groups[cat] = { total: 0, blockers: 0, warnings: 0 };
+    }
+    groups[cat].total++;
+    if (f.severity === "BLOCK") groups[cat].blockers++;
+    if (f.severity === "WARN") groups[cat].warnings++;
+  }
+
+  return groups;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RENDERING (Human-readable output)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Render why tree as terminal output (plain text with ANSI colors)
+ */
+function renderWhyTreeTerminal(tree, options = {}) {
+  const { colorize = true, width = 72 } = options;
+  const lines = [];
+
+  // ANSI helpers
+  const c = colorize ? {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[38;2;255;100;100m",
+    yellow: "\x1b[38;2;255;200;100m",
+    green: "\x1b[38;2;100;255;150m",
+    cyan: "\x1b[38;2;100;200;255m",
+    gray: "\x1b[38;2;150;150;150m",
+  } : { reset: "", bold: "", dim: "", red: "", yellow: "", green: "", cyan: "", gray: "" };
+
+  // Header
+  const verdictColor = tree.verdict === "SHIP" ? c.green : tree.verdict === "WARN" ? c.yellow : c.red;
+  lines.push("");
+  lines.push(`  ${c.bold}WHY: ${verdictColor}${tree.verdict}${c.reset}`);
+  lines.push(`  ${c.dim}${tree.summary}${c.reset}`);
+  lines.push("");
+
+  // Top blockers
+  if (tree.topBlockers.length > 0) {
+    lines.push(`  ${c.bold}Top Blockers:${c.reset}`);
+    lines.push("");
+
+    for (const blocker of tree.topBlockers) {
+      lines.push(`  ${c.red}${blocker.rank}.${c.reset} ${c.bold}${blocker.title}${c.reset}`);
+      
+      if (blocker.why) {
+        lines.push(`     ${c.dim}Why: ${blocker.why}${c.reset}`);
+      }
+      
+      if (blocker.primaryLocation) {
+        lines.push(`     ${c.cyan}→ ${blocker.primaryLocation.display}${c.reset}`);
+      }
+      
+      if (blocker.fixHint) {
+        lines.push(`     ${c.green}Fix: ${blocker.fixHint}${c.reset}`);
+      }
+      
+      lines.push("");
+    }
+  }
+
+  // Top warnings (if no blockers)
+  if (tree.topWarnings.length > 0) {
+    lines.push(`  ${c.bold}Warnings:${c.reset}`);
+    lines.push("");
+
+    for (const warning of tree.topWarnings.slice(0, 3)) {
+      lines.push(`  ${c.yellow}${warning.rank}.${c.reset} ${warning.title}`);
+      
+      if (warning.primaryLocation) {
+        lines.push(`     ${c.cyan}→ ${warning.primaryLocation.display}${c.reset}`);
+      }
+      
+      lines.push("");
+    }
+  }
+
+  // Fix missions
+  if (tree.fixMissions.length > 0) {
+    lines.push(`  ${c.bold}Fix Missions:${c.reset}`);
+    lines.push("");
+
+    for (const mission of tree.fixMissions.slice(0, 3)) {
+      const priorityColor = mission.priority === "critical" ? c.red : c.yellow;
+      lines.push(`  ${priorityColor}[${mission.priority.toUpperCase()}]${c.reset} ${mission.action}`);
+      lines.push(`     ${c.dim}Target: ${mission.target}${c.reset}`);
+      lines.push("");
+    }
+  }
+
+  // Stats summary
+  lines.push(`  ${c.dim}${"─".repeat(width - 4)}${c.reset}`);
+  lines.push(`  ${c.dim}Stats: ${tree.stats.blockers} blockers, ${tree.stats.warnings} warnings, ${tree.stats.info} info${c.reset}`);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Render why tree as Markdown (for PR comments, reports)
+ */
+function renderWhyTreeMarkdown(tree) {
+  const lines = [];
+
+  // Verdict header
+  const emoji = tree.verdict === "SHIP" ? "✅" : tree.verdict === "WARN" ? "⚠️" : "🚫";
+  lines.push(`## ${emoji} Verdict: ${tree.verdict}`);
+  lines.push("");
+  lines.push(tree.summary);
+  lines.push("");
+
+  // Top blockers
+  if (tree.topBlockers.length > 0) {
+    lines.push("### Top Blockers");
+    lines.push("");
+
+    for (const blocker of tree.topBlockers) {
+      lines.push(`**${blocker.rank}. ${blocker.title}**`);
+      
+      if (blocker.why) {
+        lines.push(`> ${blocker.why}`);
+      }
+      
+      if (blocker.primaryLocation) {
+        lines.push(`- 📁 \`${blocker.primaryLocation.display}\``);
+      }
+      
+      if (blocker.fixHint) {
+        lines.push(`- 🔧 **Fix:** ${blocker.fixHint}`);
+      }
+
+      // Proof chain
+      if (blocker.proofChain?.length > 0) {
+        const chainStr = blocker.proofChain.map(c => c.by || c.method || c.with).join(" → ");
+        lines.push(`- 📋 Proof: ${chainStr}`);
+      }
+      
+      lines.push("");
+    }
+  }
+
+  // Top warnings
+  if (tree.topWarnings.length > 0) {
+    lines.push("### Warnings");
+    lines.push("");
+
+    for (const warning of tree.topWarnings.slice(0, 5)) {
+      lines.push(`- ⚠️ **${warning.title}**`);
+      if (warning.primaryLocation) {
+        lines.push(`  - \`${warning.primaryLocation.display}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  // Fix missions
+  if (tree.fixMissions.length > 0) {
+    lines.push("### Fix Missions");
+    lines.push("");
+
+    for (const mission of tree.fixMissions.slice(0, 5)) {
+      const emoji = mission.priority === "critical" ? "🔴" : "🟡";
+      lines.push(`${emoji} **${mission.action}**`);
+      lines.push(`   - Target: \`${mission.target}\``);
+    }
+    lines.push("");
+  }
+
+  // Stats
+  lines.push("---");
+  lines.push(`📊 **Stats:** ${tree.stats.blockers} blockers, ${tree.stats.warnings} warnings, ${tree.stats.totalFindings} total findings`);
+
+  return lines.join("\n");
+}
+
+/**
+ * Render why tree as JSON (for API/programmatic use)
+ */
+function renderWhyTreeJSON(tree) {
+  return JSON.stringify(tree, null, 2);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getConfidenceScore(finding) {
+  if (!finding) return 0;
+  const scores = { high: 3, medium: 2, low: 1 };
+  return scores[finding.confidence] || 2;
+}
+
+function truncate(str, len) {
+  if (!str) return "";
+  const s = String(str);
+  if (s.length <= len) return s;
+  return s.slice(0, Math.max(0, len - 3)) + "...";
+}
+
+function sha256Short(input) {
+  try {
+    return crypto.createHash("sha256").update(String(input || "")).digest("hex").slice(0, 8);
+  } catch {
+    return "00000000";
+  }
+}
+
+/**
+ * Escape special characters for safe terminal output
+ */
+function escapeTerminal(str) {
+  if (!str) return "";
+  return String(str).replace(UNSAFE_CHARS, "");
+}
+
+/**
+ * Escape special characters for safe markdown output
+ */
+function escapeMarkdown(str) {
+  if (!str) return "";
+  return String(str)
+    .replace(UNSAFE_CHARS, "")
+    .replace(/[<>&]/g, c => ({
+      "<": "&lt;",
+      ">": "&gt;",
+      "&": "&amp;",
+    }[c]));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Main builder
+  buildWhyTree,
+  
+  // Renderers
+  renderWhyTreeTerminal,
+  renderWhyTreeMarkdown,
+  renderWhyTreeJSON,
+  
+  // Individual builders (for custom use)
+  buildIssueNode,
+  buildFixMissions,
+  buildProofChain,
+  formatPrimaryLocation,
+  
+  // Validation (for external use)
+  validateFinding,
+  sanitize,
+  
+  // Utilities
+  escapeTerminal,
+  escapeMarkdown,
+  
+  // Constants
+  MAX_STRING_LENGTH,
+  MAX_BLOCKERS,
+  MAX_WARNINGS,
+  MAX_FIX_MISSIONS,
+};