getdoorman 1.0.0

package/src/reporter.js

@@ -0,0 +1,975 @@
+import chalk from 'chalk';
+import { writeFileSync } from 'fs';
+
+const SEVERITY_COLORS = {
+  critical: chalk.bgRed.white.bold,
+  high: chalk.red.bold,
+  medium: chalk.yellow,
+  low: chalk.blue,
+  info: chalk.gray,
+};
+
+const SEVERITY_LABELS = {
+  critical: 'CRITICAL',
+  high: 'HIGH    ',
+  medium: 'MEDIUM  ',
+  low: 'LOW     ',
+  info: 'INFO    ',
+};
+
+const SEVERITY_ICONS = {
+  critical: '\u{1F534}',
+  high: '\u{1F7E0}',
+  medium: '\u{1F7E1}',
+  low: '\u{1F535}',
+  info: '\u{26AA}',
+};
+
+const CONFIDENCE_LEVELS = ['definite', 'likely', 'suggestion'];
+const CONFIDENCE_WEIGHT = { definite: 1, likely: 0.6, suggestion: 0 };
+
+const CONFIDENCE_BADGES = {
+  definite: chalk.bgRed.white(' DEFINITE '),
+  likely: chalk.bgYellow.black(' LIKELY '),
+  suggestion: chalk.bgGray.white(' SUGGESTION '),
+};
+
+const CATEGORY_NAMES = {
+  security: 'SECURITY',
+  performance: 'PERFORMANCE',
+  reliability: 'RELIABILITY',
+  cost: 'COST',
+  compliance: 'COMPLIANCE',
+  data: 'DATA PROTECTION',
+  infrastructure: 'INFRASTRUCTURE',
+  quality: 'CODE QUALITY',
+  dependencies: 'DEPENDENCIES',
+  deployment: 'DEPLOYMENT',
+  bugs: 'BUGS',
+};
+
+// --- Scoring ---
+
+const SEVERITY_DEDUCTIONS = {
+  critical: 10,
+  high: 4,
+  medium: 1.5,
+  low: 0.5,
+  info: 0,
+};
+
+const SUGGESTION_DEDUCTION = 0.5;
+
+/**
+ * Categories that count toward the safety score.
+ * Other categories (compliance, infrastructure, deployment, dependencies) are
+ * shown as "Recommendations" and do NOT tank the score.
+ */
+const SCORE_CATEGORIES = new Set([
+  'security', 'bugs', 'reliability', 'performance', 'cost', 'data', 'quality',
+]);
+
+/**
+ * Calculate the safety score based on findings and project signals.
+ * Only findings in SCORE_CATEGORIES affect the score. Compliance, infrastructure,
+ * deployment, and dependency findings are shown as recommendations.
+ * @param {Array} findings - array of finding objects
+ * @param {object} [projectSignals] - optional { hasSecurityMiddleware, hasTests, hasCI }
+ * @returns {number} score 0-100
+ */
+export function calculateScore(findings, projectSignals = {}) {
+  let score = 100;
+
+  // Calculate raw deductions per finding, then apply diminishing returns per severity group.
+  // This preserves per-finding confidence weights while preventing hundreds of findings
+  // from obliterating the score.
+  const groups = {};
+
+  for (const finding of findings) {
+    // Skip recommendation categories — they don't affect score
+    const cat = (finding.category || '').toLowerCase();
+    if (cat && !SCORE_CATEGORIES.has(cat)) continue;
+
+    const confidence = finding.confidence || 'likely';
+    const weight = CONFIDENCE_WEIGHT[confidence] ?? 0.6;
+    const severity = finding.severity || 'info';
+
+    if (confidence === 'suggestion') {
+      score -= SUGGESTION_DEDUCTION * weight;
+      continue;
+    }
+
+    if (!groups[severity]) groups[severity] = [];
+    groups[severity].push((SEVERITY_DEDUCTIONS[severity] || 0) * weight);
+  }
+
+  // Apply diminishing returns: full deduction for first N findings per severity,
+  // then logarithmic scaling. This keeps small counts accurate (matching old behavior)
+  // while preventing 500+ medium findings from pushing the score to 0.
+  const FULL_IMPACT_THRESHOLD = { critical: 2, high: 4, medium: 8, low: 20, info: 50 };
+
+  for (const [severity, deductions] of Object.entries(groups)) {
+    const threshold = FULL_IMPACT_THRESHOLD[severity] || 10;
+    // Sort descending so highest-confidence findings get full impact
+    deductions.sort((a, b) => b - a);
+
+    if (deductions.length <= threshold) {
+      // Small count: full impact (preserves original behavior for few findings)
+      for (const d of deductions) score -= d;
+    } else {
+      // Full impact up to threshold
+      for (let i = 0; i < threshold; i++) score -= deductions[i];
+      // Logarithmic scaling for the rest
+      const extraCount = deductions.length - threshold;
+      if (extraCount > 0) {
+        const avgDeduction = deductions.slice(threshold).reduce((a, b) => a + b, 0) / extraCount;
+        score -= Math.log2(extraCount + 1) * avgDeduction;
+      }
+    }
+  }
+
+  // Bonus points for good practices
+  if (projectSignals.hasSecurityMiddleware) score += 5;
+  if (projectSignals.hasTests) score += 5;
+  if (projectSignals.hasCI) score += 5;
+
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+
+// --- Severity summary helpers ---
+
+function countBySeverity(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings) {
+    const sev = f.severity || 'info';
+    if (counts[sev] !== undefined) counts[sev]++;
+  }
+  return counts;
+}
+
+function countByCategory(findings) {
+  const counts = {};
+  for (const f of findings) {
+    const cat = f.category || 'other';
+    counts[cat] = (counts[cat] || 0) + 1;
+  }
+  return counts;
+}
+
+function groupByFile(findings) {
+  const groups = {};
+  for (const f of findings) {
+    const file = f.file || '(no file)';
+    if (!groups[file]) groups[file] = [];
+    groups[file].push(f);
+  }
+  return groups;
+}
+
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+
+/**
+ * Check if a finding has a real auto-fix (replace/insert/create), not just a suggestion string.
+ */
+function isAutoFixable(finding) {
+  const fix = finding.fix;
+  if (!fix) return false;
+  if (fix === true) return true;
+  if (typeof fix === 'object') return true;  // Any fix object means we can try
+  return false;
+}
+
+function sortBySeverity(findings) {
+  return [...findings].sort(
+    (a, b) => (SEVERITY_ORDER[a.severity] || 4) - (SEVERITY_ORDER[b.severity] || 4),
+  );
+}
+
+// --- Terminal output ---
+
+function printSeverityBar(counts) {
+  const parts = [];
+  if (counts.critical > 0) parts.push(`${SEVERITY_ICONS.critical} ${counts.critical} critical`);
+  if (counts.high > 0) parts.push(`${SEVERITY_ICONS.high} ${counts.high} high`);
+  if (counts.medium > 0) parts.push(`${SEVERITY_ICONS.medium} ${counts.medium} medium`);
+  if (counts.low > 0) parts.push(`${SEVERITY_ICONS.low} ${counts.low} low`);
+  if (counts.info > 0) parts.push(`${SEVERITY_ICONS.info} ${counts.info} info`);
+
+  if (parts.length === 0) {
+    console.log(chalk.green.bold('  No issues found!'));
+  } else {
+    console.log(`  ${parts.join(' | ')}`);
+  }
+  console.log('');
+}
+
+function printScoreBadge(score) {
+  let color, label;
+  if (score >= 80) {
+    color = chalk.green.bold;
+    label = 'SAFE TO LAUNCH';
+  } else if (score >= 60) {
+    color = chalk.yellow.bold;
+    label = 'NEEDS ATTENTION';
+  } else if (score >= 40) {
+    color = chalk.red.bold;
+    label = 'AT RISK';
+  } else {
+    color = chalk.bgRed.white.bold;
+    label = 'NOT SAFE TO LAUNCH';
+  }
+
+  console.log(`  Score: ${color(`${score}/100`)} — ${color(label)}`);
+}
+
+/**
+ * Print detailed findings grouped by file (used when --detail flag is set or few findings).
+ */
+function printDetailedFindings(visible) {
+  const byFile = groupByFile(visible);
+  for (const [file, fileFindings] of Object.entries(byFile)) {
+    console.log(chalk.bold.white(`  ${file}`));
+    const sorted = sortBySeverity(fileFindings);
+
+    for (const item of sorted) {
+      const sevColor = SEVERITY_COLORS[item.severity] || chalk.white;
+      const sevLabel = SEVERITY_LABELS[item.severity] || item.severity;
+      const confidence = item.confidence || 'likely';
+      const badge = CONFIDENCE_BADGES[confidence] || '';
+      const fixTag = isAutoFixable(item) ? chalk.green(' [auto-fixable]') : '';
+      const lineInfo = item.line ? chalk.gray(`:${item.line}`) : '';
+
+      console.log(`    ${sevColor(sevLabel)}  ${item.title}${fixTag}${lineInfo}`);
+
+      if (item.codeContext) {
+        console.log(chalk.gray(`             > ${item.codeContext.trim()}`));
+      }
+
+      if (item.fix?.suggestion) {
+        console.log(chalk.gray(`             Tip: ${item.fix.suggestion}`));
+      } else if (item.fix && typeof item.fix === 'string') {
+        console.log(chalk.green(`             Fix: ${item.fix}`));
+      } else if (item.description && (item.severity === 'critical' || item.severity === 'high')) {
+        console.log(chalk.gray(`             ${item.description}`));
+      }
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Estimate the score impact of fixing a set of findings.
+ */
+function estimateScoreGain(findingsToFix) {
+  let gain = 0;
+  for (const f of findingsToFix) {
+    const confidence = f.confidence || 'likely';
+    const weight = CONFIDENCE_WEIGHT[confidence] ?? 0.6;
+    const severity = f.severity || 'info';
+    if (confidence === 'suggestion') {
+      gain += SUGGESTION_DEDUCTION * weight;
+    } else {
+      gain += (SEVERITY_DEDUCTIONS[severity] || 0) * weight;
+    }
+  }
+  return Math.round(gain);
+}
+
+/**
+ * Print the smart summary — category breakdown, top priorities, score roadmap.
+ */
+function printSmartSummary(visible, score) {
+  // --- Category breakdown ---
+  const catCounts = countByCategory(visible);
+  const catEntries = Object.entries(catCounts).sort((a, b) => b[1] - a[1]);
+
+  console.log(chalk.bold.white('  Issues by category:'));
+  console.log('');
+  for (const [cat, count] of catEntries) {
+    const label = CATEGORY_NAMES[cat] || cat.toUpperCase();
+    const barLen = Math.max(1, Math.round((count / visible.length) * 30));
+    const bar = chalk.cyan('\u2588'.repeat(barLen));
+    console.log(`    ${chalk.gray(label.padEnd(18))} ${bar} ${chalk.bold(count)}`);
+  }
+  console.log('');
+
+  // --- Top 5 priorities ---
+  const prioritized = sortBySeverity(visible);
+  // Deduplicate by title (show unique issues, not the same issue in 50 files)
+  const seen = new Set();
+  const unique = [];
+  for (const f of prioritized) {
+    const key = f.ruleId || f.title;
+    if (!seen.has(key)) {
+      seen.add(key);
+      // Count how many files this issue appears in
+      const count = prioritized.filter(p => (p.ruleId || p.title) === key).length;
+      unique.push({ ...f, occurrences: count });
+    }
+  }
+
+  const top5 = unique.slice(0, 5);
+  console.log(chalk.bold.white('  Top priorities (fix these first):'));
+  console.log('');
+  for (let i = 0; i < top5.length; i++) {
+    const item = top5[i];
+    const sevColor = SEVERITY_COLORS[item.severity] || chalk.white;
+    const sevLabel = (item.severity || 'info').toUpperCase().padEnd(8);
+    const fixTag = isAutoFixable(item) ? chalk.green(' \u2713 auto-fixable') : '';
+    const fileCount = item.occurrences > 1 ? chalk.gray(` \u00d7 ${item.occurrences} files`) : '';
+    console.log(`    ${chalk.bold(`${i + 1}.`)} ${sevColor(sevLabel)} ${item.title}${fixTag}${fileCount}`);
+    if (item.description) {
+      const desc = item.description.length > 120 ? item.description.slice(0, 120) + '...' : item.description;
+      console.log(chalk.gray(`       ${desc}`));
+    }
+  }
+  if (unique.length > 5) {
+    console.log(chalk.gray(`       ... and ${unique.length - 5} more unique issues`));
+  }
+  console.log('');
+
+  // --- Score roadmap ---
+  printScoreRoadmap(visible, score);
+}
+
+/**
+ * Print an action-oriented roadmap showing what to do next.
+ */
+function printScoreRoadmap(visible, score) {
+  const autoFixable = visible.filter(f => isAutoFixable(f));
+  const criticalCount = visible.filter(f => f.severity === 'critical').length;
+  const highCount = visible.filter(f => f.severity === 'high').length;
+  const mediumCount = visible.filter(f => f.severity === 'medium').length;
+
+  console.log(chalk.bold.white('  What to do next:'));
+  console.log('');
+
+  let stepNum = 1;
+
+  // Step 1: Auto-fix (always show if available — it's the easy win)
+  if (autoFixable.length > 0) {
+    console.log(`    ${chalk.green(`${stepNum}.`)} Run ${chalk.bold.green('npx getdoorman fix')} — instantly resolves ${chalk.bold(autoFixable.length)} issues`);
+    stepNum++;
+  }
+
+  // Step 2: Critical findings
+  if (criticalCount > 0) {
+    // Deduplicate by ruleId to show unique issue types
+    const uniqueCritical = new Set(visible.filter(f => f.severity === 'critical').map(f => f.ruleId || f.title));
+    console.log(`    ${chalk.red(`${stepNum}.`)} Fix ${chalk.bold(criticalCount)} critical issues (${uniqueCritical.size} unique types)`);
+    // Show top 3 critical issue types
+    const critTypes = {};
+    for (const f of visible.filter(f => f.severity === 'critical')) {
+      const key = f.title || f.ruleId;
+      critTypes[key] = (critTypes[key] || 0) + 1;
+    }
+    const topCrit = Object.entries(critTypes).sort((a, b) => b[1] - a[1]).slice(0, 3);
+    for (const [title, count] of topCrit) {
+      const suffix = count > 1 ? chalk.gray(` (${count}×)`) : '';
+      console.log(chalk.gray(`       \u2022 ${title}${suffix}`));
+    }
+    stepNum++;
+  }
+
+  // Step 3: High findings
+  if (highCount > 0) {
+    const uniqueHigh = new Set(visible.filter(f => f.severity === 'high').map(f => f.ruleId || f.title));
+    console.log(`    ${chalk.yellow(`${stepNum}.`)} Fix ${chalk.bold(highCount)} high issues (${uniqueHigh.size} unique types)`);
+    stepNum++;
+  }
+
+  // Step 4: Medium (just mention count)
+  if (mediumCount > 0) {
+    console.log(`    ${chalk.blue(`${stepNum}.`)} Clean up ${chalk.bold(mediumCount)} medium issues for a polished codebase`);
+  }
+
+  // Show projected score after fixing critical + high
+  const remaining = visible.filter(f => f.severity !== 'critical' && f.severity !== 'high' && !isAutoFixable(f));
+  const projectedScore = calculateScore(remaining);
+  if (projectedScore > score) {
+    console.log('');
+    console.log(chalk.gray(`    After steps 1${criticalCount > 0 ? '-' + (autoFixable.length > 0 ? 3 : 2) : ''}: ~${chalk.bold.white(projectedScore + '/100')}`));
+  }
+
+  console.log('');
+}
+
+/**
+ * Print the scan report to the terminal (default output).
+ */
+export function printReport(findings, stack, score, options = {}) {
+  // Legacy JSON handling (kept for backward compat; index.js now handles JSON separately)
+  if (options.json) {
+    console.log(JSON.stringify({ score, findings, stack }, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold.cyan('\u2501'.repeat(60)));
+  console.log(chalk.bold.cyan('  Doorman v1.0.0 \u2014 Scan Results'));
+  console.log(chalk.bold.cyan('\u2501'.repeat(60)));
+  console.log('');
+
+  // Detected stack
+  const stackParts = [
+    stack.framework || stack.language || 'Unknown',
+    stack.orm,
+    stack.database,
+    stack.hasTypescript ? 'TypeScript' : null,
+    stack.hasDocker ? 'Docker' : null,
+  ].filter(Boolean);
+
+  console.log(chalk.gray(`  Detected: ${stackParts.join(' + ')}`));
+  console.log('');
+
+  // Normalize confidence and filter by verbosity
+  const normalized = findings.map((f) => ({ ...f, confidence: f.confidence || 'likely' }));
+  const visible = options.verbose
+    ? normalized
+    : normalized.filter((f) => f.confidence !== 'suggestion');
+
+  if (visible.length === 0) {
+    console.log(chalk.green.bold('  No issues found!'));
+    console.log('');
+    printScoreBadge(score);
+    console.log(chalk.bold.cyan('\u2501'.repeat(60)));
+    console.log('');
+    return;
+  }
+
+  // --- Determine output mode by plan ---
+  // Free: security + bugs only
+  // Pro ($20): security, bugs, performance, reliability, cost, data, quality
+  // Enterprise ($100): all categories (adds compliance, infrastructure, deployment, dependencies)
+  const FREE_CATEGORIES = new Set(['security', 'bugs']);
+  const PRO_CATEGORIES = new Set(['security', 'bugs', 'performance', 'reliability', 'cost', 'data', 'quality']);
+  const ENTERPRISE_ONLY = new Set(['compliance', 'infrastructure', 'deployment', 'dependencies']);
+
+  let userCategories;
+  if (options.allCategories) userCategories = null;  // show all
+  else if (options.planCategories) userCategories = new Set(options.planCategories);
+  else userCategories = FREE_CATEGORIES;
+
+  const vibeVisible = userCategories ? visible.filter(f => userCategories.has(f.category)) : visible;
+  const hiddenCount = visible.length - vibeVisible.length;
+
+  // Count what Pro would unlock vs what Enterprise would unlock
+  const proUnlockCount = userCategories === FREE_CATEGORIES
+    ? visible.filter(f => PRO_CATEGORIES.has(f.category) && !FREE_CATEGORIES.has(f.category)).length
+    : 0;
+  const enterpriseUnlockCount = userCategories && userCategories !== null
+    ? visible.filter(f => ENTERPRISE_ONLY.has(f.category)).length
+    : 0;
+
+  if (options.detail) {
+    // Full detail: every finding, per file
+    printDetailedFindings(visible);
+  } else if (options.strict) {
+    // Strict: show smart summary with ALL findings
+    printSeverityBar(countBySeverity(visible));
+    printSmartSummary(visible, score);
+  } else {
+    // DEFAULT: Vibe coder mode — gated by plan
+    printVibeCoderReport(vibeVisible, score, hiddenCount, proUnlockCount, enterpriseUnlockCount);
+  }
+
+  // Footer
+  console.log(chalk.bold.cyan('\u2501'.repeat(60)));
+  printScoreBadge(score);
+
+  // Show auto-fix banner in footer only for strict/detail modes (vibe coder mode has its own)
+  if (options.strict || options.detail) {
+    const totalAutoFix = findings.filter((f) => isAutoFixable(f)).length;
+    if (totalAutoFix > 0) {
+      console.log('');
+      console.log(
+        chalk.yellow(`  ${totalAutoFix} auto-fixable issue${totalAutoFix === 1 ? '' : 's'} found.`),
+      );
+      console.log(chalk.yellow(`  Run ${chalk.bold('npx getdoorman fix')} to fix them automatically.`));
+    }
+  }
+
+  if (!options.detail) {
+    console.log('');
+    console.log(chalk.gray(`  ${chalk.bold('--detail')} to see every finding  |  ${chalk.bold('--strict')} to see all severities`));
+  }
+
+  console.log(chalk.bold.cyan('\u2501'.repeat(60)));
+  console.log('');
+
+  // One-line summary at the end — use filtered findings to match the report above
+  const summaryFindings = (options.strict || options.detail) ? findings : vibeVisible;
+  printSummaryLine(summaryFindings, score, { minScore: options.minScore });
+  console.log('');
+}
+
+/**
+ * Vibe coder report — default mode.
+ * Shows top issues with file + line so users can paste into Claude/Codex to fix.
+ */
+function printVibeCoderReport(visible, score, hiddenCategoryCount = 0, proUnlockCount = 0, enterpriseUnlockCount = 0) {
+  const critical = visible.filter(f => f.severity === 'critical');
+  const high = visible.filter(f => f.severity === 'high');
+  const medium = visible.filter(f => f.severity === 'medium');
+
+  // --- Show top issues with details ---
+  const sevColors = { critical: chalk.red, high: chalk.hex('#ff6b35'), medium: chalk.yellow };
+  const allSorted = [...critical, ...high, ...medium];
+  const showCount = Math.min(allSorted.length, 15);
+
+  if (critical.length > 0) {
+    console.log(chalk.red.bold(`  ${critical.length} critical issue${critical.length === 1 ? '' : 's'}`));
+  }
+  if (high.length > 0) {
+    console.log(chalk.hex('#ff6b35').bold(`  ${high.length} high-priority issue${high.length === 1 ? '' : 's'}`));
+  }
+  if (medium.length > 0) {
+    console.log(chalk.yellow(`  ${medium.length} medium issue${medium.length === 1 ? '' : 's'}`));
+  }
+  console.log('');
+
+  for (let i = 0; i < showCount; i++) {
+    const f = allSorted[i];
+    const sev = (sevColors[f.severity] || chalk.white)(f.severity.toUpperCase().padEnd(8));
+    const loc = f.file ? chalk.gray(` ${f.file}${f.line ? ':' + f.line : ''}`) : '';
+    console.log(`    ${sev} ${f.title}`);
+    if (loc) console.log(`             ${loc}`);
+  }
+  if (allSorted.length > showCount) {
+    console.log(chalk.gray(`    ... +${allSorted.length - showCount} more (use --detail to see all)`));
+  }
+  console.log('');
+
+  // --- Tell them how to fix ---
+  console.log(chalk.green('  To fix: paste the issues above into Claude, Codex, or Cursor.'));
+  console.log(chalk.gray('  Example: "Fix the SQL injection in src/api/search.ts:42"'));
+  console.log('');
+
+  // Projected score after fixing
+  const afterFixing = visible.filter(f => f.severity !== 'critical' && f.severity !== 'high' && !isAutoFixable(f));
+  const projected = calculateScore(afterFixing);
+  if (projected > score) {
+    console.log(chalk.gray(`  After fixing: score goes from ${chalk.white.bold(score)} → ${chalk.green.bold(projected + '/100')}`));
+    console.log('');
+  }
+
+  // --- Upsell ---
+  if (proUnlockCount > 0) {
+    console.log(chalk.cyan(`  🔒 ${proUnlockCount} more issues in performance, cost, reliability, data...`));
+    console.log(chalk.gray('     Upgrade to Pro ($20/mo) to see all categories + unlimited fixes.'));
+    console.log('');
+  }
+  if (enterpriseUnlockCount > 0 && proUnlockCount === 0) {
+    console.log(chalk.gray(`  + ${enterpriseUnlockCount} compliance/infrastructure findings (Enterprise plan)`));
+    console.log('');
+  }
+}
+
+// --- JSON output ---
+
+/**
+ * Generate structured JSON output for CI integration.
+ */
+export function generateJSON(findings, stack, score, metadata = {}) {
+  const counts = countBySeverity(findings);
+  const categoryCounts = countByCategory(findings);
+
+  return {
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    score,
+    summary: {
+      total: findings.length,
+      bySeverity: counts,
+      byCategory: categoryCounts,
+    },
+    findings: findings.map((f) => ({
+      ruleId: f.ruleId || null,
+      title: f.title || '',
+      description: f.description || '',
+      severity: f.severity || 'info',
+      confidence: f.confidence || 'likely',
+      category: f.category || 'other',
+      file: f.file || null,
+      line: f.line || null,
+      codeContext: f.codeContext || null,
+      fix: f.fix || null,
+      attackPath: f.attackPath || null,
+    })),
+    stack,
+    metadata: {
+      filesScanned: metadata.filesScanned || 0,
+      scanDurationSeconds: metadata.scanDurationSeconds || 0,
+      rulesMatched: new Set(findings.map((f) => f.ruleId).filter(Boolean)).size,
+      mode: metadata.mode || 'full',
+      ...(metadata.partial && { partial: true }),
+    },
+  };
+}
+
+// --- SARIF output ---
+
+const SARIF_SEVERITY_MAP = {
+  critical: 'error',
+  high: 'error',
+  medium: 'warning',
+  low: 'note',
+  info: 'note',
+};
+
+/**
+ * Generate SARIF 2.1.0 output for GitHub Code Scanning, VS Code, etc.
+ */
+export function generateSARIF(findings, stack, score, metadata = {}) {
+  // Collect unique rules
+  const ruleMap = new Map();
+  for (const f of findings) {
+    const ruleId = f.ruleId || `doorman-${f.category || 'general'}-${f.title ? f.title.replace(/\s+/g, '-').toLowerCase().slice(0, 40) : 'unknown'}`;
+    if (!ruleMap.has(ruleId)) {
+      ruleMap.set(ruleId, {
+        id: ruleId,
+        name: f.title || ruleId,
+        shortDescription: { text: f.title || ruleId },
+        fullDescription: { text: f.description || f.title || ruleId },
+        defaultConfiguration: {
+          level: SARIF_SEVERITY_MAP[f.severity] || 'note',
+        },
+        properties: {
+          tags: [f.category || 'security'],
+        },
+      });
+    }
+  }
+
+  const rules = Array.from(ruleMap.values());
+  const ruleIndex = {};
+  rules.forEach((r, i) => {
+    ruleIndex[r.id] = i;
+  });
+
+  const results = findings.map((f) => {
+    const ruleId = f.ruleId || `doorman-${f.category || 'general'}-${f.title ? f.title.replace(/\s+/g, '-').toLowerCase().slice(0, 40) : 'unknown'}`;
+    const result = {
+      ruleId,
+      ruleIndex: ruleIndex[ruleId] ?? 0,
+      level: SARIF_SEVERITY_MAP[f.severity] || 'note',
+      message: {
+        text: f.description || f.title || 'Finding detected',
+      },
+    };
+
+    if (f.file) {
+      result.locations = [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: f.file,
+              uriBaseId: '%SRCROOT%',
+            },
+            region: {
+              startLine: f.line || 1,
+            },
+          },
+        },
+      ];
+    }
+
+    if (f.fix) {
+      result.fixes = [
+        {
+          description: {
+            text: typeof f.fix === 'string' ? f.fix : 'Auto-fix available',
+          },
+        },
+      ];
+    }
+
+    return 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: 'Doorman',
+            version: '1.0.0',
+            informationUri: 'https://github.com/tiago520/VoiceAI',
+            rules,
+          },
+        },
+        results,
+        invocations: [
+          {
+            executionSuccessful: true,
+            endTimeUtc: new Date().toISOString(),
+          },
+        ],
+        properties: {
+          score,
+          filesScanned: metadata.filesScanned || 0,
+          scanDurationSeconds: metadata.scanDurationSeconds || 0,
+        },
+      },
+    ],
+  };
+}
+
+// --- HTML report ---
+
+/**
+ * Generate a standalone HTML report with dark theme dashboard.
+ */
+export function generateHTML(findings, stack, score, metadata = {}) {
+  const counts = countBySeverity(findings);
+  const categoryCounts = countByCategory(findings);
+  const sorted = sortBySeverity(findings);
+
+  const stackParts = [
+    stack.framework || stack.language || 'Unknown',
+    stack.orm,
+    stack.database,
+    stack.hasTypescript ? 'TypeScript' : null,
+    stack.hasDocker ? 'Docker' : null,
+  ].filter(Boolean);
+
+  let scoreColor;
+  let scoreLabel;
+  if (score >= 80) {
+    scoreColor = '#22c55e';
+    scoreLabel = 'SAFE TO LAUNCH';
+  } else if (score >= 60) {
+    scoreColor = '#eab308';
+    scoreLabel = 'NEEDS ATTENTION';
+  } else if (score >= 40) {
+    scoreColor = '#ef4444';
+    scoreLabel = 'AT RISK';
+  } else {
+    scoreColor = '#dc2626';
+    scoreLabel = 'NOT SAFE TO LAUNCH';
+  }
+
+  const sevColors = {
+    critical: '#dc2626',
+    high: '#ef4444',
+    medium: '#eab308',
+    low: '#3b82f6',
+    info: '#6b7280',
+  };
+
+  const findingsRows = sorted
+    .map((f, i) => {
+      const sev = f.severity || 'info';
+      const color = sevColors[sev] || '#6b7280';
+      const file = f.file ? `${escapeHtml(f.file)}${f.line ? ':' + f.line : ''}` : '-';
+      const confidence = f.confidence || 'likely';
+      return `<tr>
+        <td>${i + 1}</td>
+        <td><span class="sev-badge" style="background:${color}">${sev.toUpperCase()}</span></td>
+        <td>${escapeHtml(f.title || '')}</td>
+        <td>${escapeHtml(f.category || '')}</td>
+        <td>${file}</td>
+        <td><span class="conf-badge conf-${confidence}">${confidence}</span></td>
+        <td>${f.fix ? '<span class="fix-yes">Yes</span>' : '-'}</td>
+      </tr>`;
+    })
+    .join('\n');
+
+  const categoryChartData = Object.entries(categoryCounts)
+    .sort((a, b) => b[1] - a[1])
+    .map(
+      ([cat, count]) =>
+        `<div class="cat-bar-row"><span class="cat-label">${escapeHtml(CATEGORY_NAMES[cat] || cat.toUpperCase())}</span><div class="cat-bar" style="width:${Math.max(5, (count / Math.max(findings.length, 1)) * 100)}%">${count}</div></div>`,
+    )
+    .join('\n');
+
+  // Score gauge SVG
+  const gaugeAngle = (score / 100) * 180;
+  const gaugeRad = (gaugeAngle * Math.PI) / 180;
+  const gaugeX = 50 + 40 * Math.cos(Math.PI - gaugeRad);
+  const gaugeY = 50 - 40 * Math.sin(Math.PI - gaugeRad);
+  const largeArc = gaugeAngle > 90 ? 1 : 0;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Doorman Report</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, monospace; background: #0f172a; color: #e2e8f0; min-height: 100vh; padding: 2rem; }
+  .container { max-width: 1200px; margin: 0 auto; }
+  h1 { font-size: 1.8rem; margin-bottom: 0.5rem; color: #38bdf8; }
+  .subtitle { color: #64748b; margin-bottom: 2rem; }
+  .dashboard { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1.5rem; margin-bottom: 2rem; }
+  .card { background: #1e293b; border-radius: 12px; padding: 1.5rem; border: 1px solid #334155; }
+  .card h2 { font-size: 1rem; color: #94a3b8; margin-bottom: 1rem; text-transform: uppercase; letter-spacing: 0.05em; }
+  .score-card { display: flex; flex-direction: column; align-items: center; justify-content: center; }
+  .score-value { font-size: 3rem; font-weight: bold; color: ${scoreColor}; }
+  .score-label { font-size: 0.9rem; color: ${scoreColor}; font-weight: bold; margin-top: 0.5rem; }
+  .sev-summary { display: flex; gap: 1rem; flex-wrap: wrap; justify-content: center; }
+  .sev-item { text-align: center; padding: 0.5rem 1rem; border-radius: 8px; background: #0f172a; min-width: 80px; }
+  .sev-item .count { font-size: 1.5rem; font-weight: bold; }
+  .sev-item .label { font-size: 0.75rem; text-transform: uppercase; color: #94a3b8; }
+  .gauge-svg { width: 120px; height: 70px; }
+  .cat-bar-row { display: flex; align-items: center; margin-bottom: 0.5rem; }
+  .cat-label { width: 140px; font-size: 0.8rem; color: #94a3b8; text-align: right; padding-right: 0.75rem; flex-shrink: 0; }
+  .cat-bar { background: #38bdf8; color: #0f172a; font-size: 0.75rem; font-weight: bold; padding: 4px 8px; border-radius: 4px; min-width: 30px; text-align: center; }
+  table { width: 100%; border-collapse: collapse; }
+  th { text-align: left; padding: 0.75rem; border-bottom: 2px solid #334155; color: #94a3b8; font-size: 0.8rem; text-transform: uppercase; cursor: pointer; user-select: none; }
+  th:hover { color: #38bdf8; }
+  td { padding: 0.6rem 0.75rem; border-bottom: 1px solid #1e293b; font-size: 0.85rem; }
+  tr:hover { background: #1e293b; }
+  .sev-badge { padding: 2px 8px; border-radius: 4px; font-size: 0.7rem; font-weight: bold; color: white; }
+  .conf-badge { padding: 2px 6px; border-radius: 4px; font-size: 0.7rem; }
+  .conf-definite { background: #dc2626; color: white; }
+  .conf-likely { background: #eab308; color: black; }
+  .conf-suggestion { background: #475569; color: white; }
+  .fix-yes { color: #22c55e; font-weight: bold; }
+  .meta { color: #64748b; font-size: 0.8rem; margin-top: 2rem; text-align: center; }
+  @media (max-width: 768px) { .dashboard { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<div class="container">
+  <h1>Doorman Security Report</h1>
+  <p class="subtitle">Stack: ${escapeHtml(stackParts.join(' + '))} | ${metadata.filesScanned || 0} files scanned in ${metadata.scanDurationSeconds || 0}s | ${new Date().toISOString().slice(0, 10)}</p>
+
+  <div class="dashboard">
+    <div class="card score-card">
+      <h2>Security Score</h2>
+      <svg class="gauge-svg" viewBox="0 0 100 55">
+        <path d="M 10 50 A 40 40 0 0 1 90 50" fill="none" stroke="#334155" stroke-width="6" stroke-linecap="round"/>
+        <path d="M 10 50 A 40 40 0 ${largeArc} 1 ${gaugeX.toFixed(1)} ${gaugeY.toFixed(1)}" fill="none" stroke="${scoreColor}" stroke-width="6" stroke-linecap="round"/>
+      </svg>
+      <div class="score-value">${score}</div>
+      <div class="score-label">${scoreLabel}</div>
+    </div>
+
+    <div class="card">
+      <h2>Severity Breakdown</h2>
+      <div class="sev-summary">
+        <div class="sev-item"><div class="count" style="color:${sevColors.critical}">${counts.critical}</div><div class="label">Critical</div></div>
+        <div class="sev-item"><div class="count" style="color:${sevColors.high}">${counts.high}</div><div class="label">High</div></div>
+        <div class="sev-item"><div class="count" style="color:${sevColors.medium}">${counts.medium}</div><div class="label">Medium</div></div>
+        <div class="sev-item"><div class="count" style="color:${sevColors.low}">${counts.low}</div><div class="label">Low</div></div>
+        <div class="sev-item"><div class="count" style="color:${sevColors.info}">${counts.info}</div><div class="label">Info</div></div>
+      </div>
+    </div>
+
+    <div class="card">
+      <h2>Category Breakdown</h2>
+      ${categoryChartData || '<p style="color:#64748b">No findings</p>'}
+    </div>
+  </div>
+
+  <div class="card">
+    <h2>Findings (${findings.length})</h2>
+    <table id="findings-table">
+      <thead>
+        <tr>
+          <th data-col="0">#</th>
+          <th data-col="1">Severity</th>
+          <th data-col="2">Title</th>
+          <th data-col="3">Category</th>
+          <th data-col="4">File</th>
+          <th data-col="5">Confidence</th>
+          <th data-col="6">Fix</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${findingsRows || '<tr><td colspan="7" style="text-align:center;color:#64748b">No findings</td></tr>'}
+      </tbody>
+    </table>
+  </div>
+
+  <p class="meta">Generated by Doorman v1.0.0</p>
+</div>
+
+<script>
+// Simple table sorting
+document.querySelectorAll('#findings-table th').forEach(th => {
+  th.addEventListener('click', () => {
+    const table = document.getElementById('findings-table');
+    const tbody = table.querySelector('tbody');
+    const rows = Array.from(tbody.querySelectorAll('tr'));
+    const col = parseInt(th.dataset.col);
+    const asc = th.dataset.asc !== 'true';
+    th.dataset.asc = asc;
+    rows.sort((a, b) => {
+      const at = (a.children[col] || {}).textContent || '';
+      const bt = (b.children[col] || {}).textContent || '';
+      return asc ? at.localeCompare(bt, undefined, {numeric: true}) : bt.localeCompare(at, undefined, {numeric: true});
+    });
+    rows.forEach(r => tbody.appendChild(r));
+  });
+});
+</script>
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// --- One-line summary ---
+
+/**
+ * Build a one-line summary string (without ANSI codes).
+ * @param {Array} findings
+ * @param {number} score
+ * @param {object} [opts] - { minScore }
+ * @returns {string}
+ */
+export function formatSummaryLine(findings, score, opts = {}) {
+  const counts = countBySeverity(findings);
+  const minScore = opts.minScore != null ? parseInt(opts.minScore, 10) : null;
+
+  let line = `Doorman: ${score}/100 — ${counts.critical} critical, ${counts.high} high, ${counts.medium} medium, ${counts.low} low`;
+
+  if (minScore != null) {
+    if (score < minScore || counts.critical > 0 || counts.high > 0) {
+      line += ` \u2717 BLOCKED (min-score: ${minScore})`;
+    } else {
+      line += ` \u2713 PASSED (min-score: ${minScore})`;
+    }
+  }
+
+  return line;
+}
+
+/**
+ * Print the bold one-line summary to stdout.
+ */
+export function printSummaryLine(findings, score, opts = {}) {
+  const line = formatSummaryLine(findings, score, opts);
+  console.log(chalk.bold(line));
+}
+
+// --- File writers ---
+
+/**
+ * Write SARIF output to a file.
+ */
+export function writeSARIF(filePath, findings, stack, score, metadata = {}) {
+  const sarif = generateSARIF(findings, stack, score, metadata);
+  writeFileSync(filePath, JSON.stringify(sarif, null, 2));
+  return sarif;
+}
+
+/**
+ * Write HTML report to a file.
+ */
+export function writeHTML(filePath, findings, stack, score, metadata = {}) {
+  const html = generateHTML(findings, stack, score, metadata);
+  writeFileSync(filePath, html);
+  return html;
+}