dependencyiq 2.0.0

package/src/dashboardGenerator.js

@@ -0,0 +1,642 @@
+/**
+ * Static HTML dashboard generator.
+ *
+ * GitLab's direct equivalent of GitHub Pages is GitLab Pages — a static
+ * site published from a `public/` directory by a CI job named `pages`,
+ * no extra hosting service needed. Since there's no backend here (by
+ * design — see README's honesty boundaries), this renders one
+ * self-contained HTML file from the same data the CLI already produces,
+ * with inline CSS and zero external JS/fonts/images — nothing to fetch,
+ * nothing that can go stale or 404. No live interactivity, no server —
+ * exactly what GitLab Pages is for.
+ */
+
+const { buildExecutiveSummary } = require('./executiveSummary');
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function priorityColor(priority) {
+  return {
+    UNUSED: '#8b5cf6',
+    URGENT: '#dc2626',
+    HIGH: '#ea580c',
+    MEDIUM: '#ca8a04',
+    LOW: '#65a30d',
+  }[priority] || '#6b7280';
+}
+
+/**
+ * Build a GitLab "new issue" URL with the title/description prefilled —
+ * a real, no-backend way to make a static page actionable: GitLab itself
+ * renders the New Issue form from these query params, no API call or
+ * server needed on our side.
+ */
+function buildIssueUrl(v, meta, totalRiskScore) {
+  if (!meta.serverUrl || !meta.projectPath) return null;
+  const isRemoval = v.recommendation === 'remove';
+  const contributionPercent = totalRiskScore > 0 ? Math.round(((v.riskScore?.score || 0) / totalRiskScore) * 100) : null;
+  const contributionLine = contributionPercent !== null ? `\n- Share of total flagged risk: ${contributionPercent}% of ${totalRiskScore} points across all findings` : '';
+  const title = isRemoval
+    ? `Remove unused dependency: ${v.package}`
+    : `Security: upgrade ${v.package} ${v.currentVersion} → ${v.fixedVersion} (${v.id || v.vulnerability || 'CVE'})`;
+  const description = isRemoval
+    ? `GitLab Orbit found zero files importing **${v.package}** anywhere in this project. Recommend removing it instead of patching ${v.id || 'this advisory'}.\n\nRun: \`node src/agent.js analyze . --fix --create-pr\` (when this is the top-ranked finding) to remove it automatically, or delete the dependency manually.`
+    : `**${v.package}** (${v.ecosystem}) ${v.currentVersion} → ${v.fixedVersion}\n- Severity: ${v.severity || '?'} (CVSS ${v.cvss ?? '?'})\n- Risk score: ${v.riskScore?.score ?? '?'}/100 (${v.riskScore?.priority || 'unscored'})\n- Exposure data: ${v.riskScore?.exposureDataSource === 'orbit' ? 'GitLab Orbit blast-radius query' : 'unavailable — Orbit not reachable for this run'}${contributionLine}\n\nRun: \`node src/agent.js analyze . --fix --create-pr\` (when this is the top-ranked finding) to upgrade and open a merge request automatically, or bump the dependency manually to ${v.fixedVersion}.`;
+  const params = new URLSearchParams({ 'issue[title]': title, 'issue[description]': description });
+  return `${meta.serverUrl}/${meta.projectPath}/-/issues/new?${params.toString()}`;
+}
+
+/**
+ * Direct-vs-transitive badge, with the real resolved chain when known
+ * (src/scanners/dependencyTreeBuilder.js) — never a guessed chain.
+ */
+function renderDependencyBadge(v) {
+  const info = v.dependencyChain;
+  if (!info || !info.available) {
+    return `<span class="dep-badge dep-unknown">unknown${info?.reason ? ` (${escapeHtml(info.reason)})` : ''}</span>`;
+  }
+  if (info.isDirect) {
+    return '<span class="dep-badge dep-direct">direct</span>';
+  }
+  if (info.chain) {
+    return `<span class="dep-badge dep-transitive">transitive</span> <code class="dep-chain">${escapeHtml(info.chain.join(' → '))}</code>`;
+  }
+  return '<span class="dep-badge dep-unknown">transitive (chain unknown)</span>';
+}
+
+const CATEGORY_LABEL = { 'public-api': '🌐 Public API', internal: '🔒 Internal', test: '🧪 Test-only' };
+const CATEGORY_ORDER = ['public-api', 'internal', 'test'];
+
+/**
+ * Group the real evidence files by exposure category (src/blastRadius.js
+ * classifies each one individually) instead of one flat list — public-
+ * API exposure is the whole reason this finding might outrank a
+ * higher-CVSS one with only test-only usage, so the grouping should be
+ * visible, not just folded into a single aggregate number.
+ */
+function renderEvidenceGroups(files, packageName) {
+  if (files.length === 0) return '';
+  const groups = { 'public-api': [], internal: [], test: [] };
+  for (const f of files) {
+    (groups[f.category] || groups.internal).push(f);
+  }
+
+  const sections = CATEGORY_ORDER
+    .filter(cat => groups[cat].length > 0)
+    .map(cat => {
+      const items = groups[cat].slice(0, 6).map(f => `<li>${escapeHtml(f.path || f)}</li>`).join('');
+      const more = groups[cat].length > 6 ? `<div class="trail-more">+${groups[cat].length - 6} more</div>` : '';
+      return `<div class="evidence-group"><strong>${CATEGORY_LABEL[cat]} (${groups[cat].length})</strong><ul>${items}</ul>${more}</div>`;
+    })
+    .join('');
+
+  return `<div class="trail-evidence"><strong>Evidence — files importing ${escapeHtml(packageName)}, grouped by exposure:</strong>${sections}</div>`;
+}
+
+/**
+ * "Show your work" panel — the same risk-score formula this project
+ * documents everywhere (README/AGENTS.md), broken into its actual
+ * weighted contributions for this one finding, plus the real evidence
+ * (the file list Orbit returned, grouped by exposure) instead of just a
+ * final number. Also states this finding's share of the project's total
+ * flagged risk, so "fix this one" has a concrete, quantified payoff
+ * instead of an abstract score.
+ */
+function fmt1(n) {
+  // One decimal, but drop a trailing ".0" so whole numbers read cleanly.
+  return Number.isInteger(n) ? String(n) : n.toFixed(1);
+}
+
+function renderDecisionTrail(v, totalRiskScore) {
+  const b = v.riskScore?.breakdown;
+  if (!b) return '';
+  const files = v.affectedFiles || [];
+  // Prefer the exact point contributions the calculator computed; these
+  // sum to the final score by construction, so the trail can never claim
+  // a breakdown that doesn't add up. (Older breakdowns without
+  // `contributions` fall back to deriving from the normalized values.)
+  const c = b.contributions || {
+    cvss: (b.cvss || 0) * 45,
+    exposure: (b.exposure || 0) * 35,
+    usage: (b.usage || 0) * 10,
+    testCoverageDiscount: (b.testCoverage || 0) * 10,
+  };
+  const exposureNote = v.riskScore.exposureDataSource === 'orbit'
+    ? 'real GitLab Orbit blast-radius query'
+    : 'unavailable — Orbit unreachable, contributes 0 rather than a guess';
+  const contributionPercent = totalRiskScore > 0 ? Math.round((v.riskScore.score / totalRiskScore) * 100) : null;
+
+  return `
+    <details class="decision-trail">
+      <summary>🔍 Decision trail</summary>
+      <div class="trail-content">
+        <div class="trail-row"><span>CVSS contribution</span><span>+${fmt1(c.cvss)} <em>(45% weight)</em></span></div>
+        <div class="trail-row"><span>Exposure contribution</span><span>+${fmt1(c.exposure)} <em>(35% weight · ${escapeHtml(exposureNote)})</em></span></div>
+        <div class="trail-row"><span>Usage contribution</span><span>+${fmt1(c.usage)} <em>(10% weight)</em></span></div>
+        <div class="trail-row"><span>Test-coverage discount</span><span>−${fmt1(c.testCoverageDiscount)} <em>(10% weight)</em></span></div>
+        <div class="trail-row trail-final"><span>Final score</span><span>${v.riskScore.score}/100 (${escapeHtml(v.riskScore.priority)})</span></div>
+        ${contributionPercent !== null ? `<div class="trail-row trail-contribution"><span>Share of total flagged risk</span><span>${contributionPercent}% of ${totalRiskScore} points</span></div>` : ''}
+        ${renderEvidenceGroups(files, v.package)}
+      </div>
+    </details>`;
+}
+
+/**
+ * One finding, rendered as a self-contained card instead of a row in a
+ * wide table — reads cleanly top-to-bottom on any screen size, no
+ * horizontal scrolling needed regardless of how many data points a
+ * finding carries.
+ */
+function renderFindingCard(v, index, meta, totalRiskScore) {
+  const priority = v.riskScore?.priority || 'UNSCORED';
+  const score = v.riskScore?.score ?? '—';
+  const exposureSource = v.riskScore?.exposureDataSource === 'orbit' ? 'Orbit (real)' : 'unavailable';
+  const fixCommand = 'node src/agent.js analyze . --fix --create-pr';
+  const issueUrl = buildIssueUrl(v, meta, totalRiskScore);
+  const color = priorityColor(priority);
+
+  return `
+    <article class="finding-card" data-priority="${escapeHtml(priority)}" data-score="${typeof score === 'number' ? score : -1}">
+      <div class="finding-top">
+        <div class="finding-identity">
+          <span class="finding-rank">#${index + 1}</span>
+          <code class="finding-pkg">${escapeHtml(v.package)}</code>
+          <span class="finding-version">${escapeHtml(v.currentVersion)} → ${escapeHtml(v.fixedVersion || '?')}</span>
+        </div>
+        <div class="finding-score" style="--score-color:${color}">
+          <span class="score-num">${escapeHtml(score)}</span><span class="score-max">/100</span>
+          <span class="badge" style="background:${color}">${escapeHtml(priority)}</span>
+        </div>
+      </div>
+
+      <div class="finding-meta">
+        <span class="meta-chip">${escapeHtml(v.ecosystem)}</span>
+        ${renderDependencyBadge(v)}
+        <span class="meta-chip">CVSS ${escapeHtml(v.cvss ?? '?')} · ${escapeHtml(v.severity || '?')}</span>
+        <span class="meta-chip">Exposure: ${escapeHtml(exposureSource)}</span>
+        <span class="meta-chip meta-recommendation">${escapeHtml(v.recommendation || 'upgrade')}</span>
+      </div>
+
+      <div class="finding-actions">
+        ${issueUrl ? `<a href="${issueUrl}" target="_blank" class="action-btn action-btn-primary">📋 Create issue</a>` : ''}
+        <button class="action-btn copy-btn" data-copy="${escapeHtml(fixCommand)}" onclick="copyFixCommand(this)">📎 Copy fix command</button>
+      </div>
+
+      ${renderDecisionTrail(v, totalRiskScore)}
+    </article>`;
+}
+
+/**
+ * Executive framing banner — the numbers a non-technical decision-maker
+ * weighs: remediation work on the table, how much is urgent, and the
+ * manual triage the tool did for you. Sourced from executiveSummary.js
+ * (all derived from data already computed; the triage-saved figure is a
+ * labelled heuristic).
+ */
+function renderExecutiveSummary(vulnerabilities) {
+  if (vulnerabilities.length === 0) return '';
+  const s = buildExecutiveSummary(vulnerabilities);
+  return `
+  <section class="exec">
+    <h2>📊 Executive summary</h2>
+    <div class="exec-grid">
+      <div class="exec-item"><span class="exec-num">${s.remediationEffortHours}h</span><span class="exec-label">Remediation effort represented</span></div>
+      <div class="exec-item"><span class="exec-num">${s.urgentHigh}</span><span class="exec-label">Urgent / high priority</span></div>
+      <div class="exec-item"><span class="exec-num">${s.breakingCount}</span><span class="exec-label">Likely-breaking (major) fixes</span></div>
+      <div class="exec-item"><span class="exec-num">${s.unusedCount}</span><span class="exec-label">Removable unused deps</span></div>
+      <div class="exec-item exec-highlight"><span class="exec-num">~${s.manualTriageHoursSaved}h</span><span class="exec-label">Manual triage avoided</span></div>
+    </div>
+    <div class="exec-note">"Manual triage avoided" is a heuristic — ~${s.manualTriageMinutesPerFinding}min/finding of grep-and-decide that DependencyIQ did automatically (blast-radius classification + remove/upgrade/override decision). Effort figures are estimates, not measurements.</div>
+  </section>`;
+}
+
+/**
+ * Visualize the agentic decision pipeline for the top finding — the same
+ * five stages the Custom Flow runs (discover → assess → score → decide →
+ * remediate/verify), each filled in with this finding's REAL data, so a
+ * viewer can see how DependencyIQ reasoned, stage by stage, not just the
+ * final score. Stages 1-4 are computed here from real analysis data;
+ * stage 5 (remediate + verify) is what the Flow executes as a CI job —
+ * shown so the full agentic loop is visible end to end.
+ */
+function renderDecisionPipeline(top) {
+  if (!top || !top.riskScore) return '';
+  const rs = top.riskScore;
+  const files = top.affectedFiles || [];
+
+  const dep = top.dependencyChain;
+  const depText = dep?.isDirect ? 'direct dependency'
+    : dep?.chain ? `transitive via ${escapeHtml(dep.chain.join(' → '))}`
+      : 'dependency';
+
+  const orbitReal = rs.exposureDataSource === 'orbit';
+  const assessText = orbitReal
+    ? `Orbit: <strong>${files.length}</strong> file(s) import it`
+    : 'Orbit unavailable — score is CVSS-only';
+
+  // Show the final score and the formula label only — NOT rounded
+  // intermediate contributions, which can visually fail to sum (the
+  // exact, provably-summing breakdown lives in the per-finding decision
+  // trail below; the compact pipeline view must not appear to not add up).
+  const scoreText = `<strong>${rs.score}</strong>/100`;
+
+  const decideText = top.recommendation === 'remove'
+    ? 'Remove (zero importers)'
+    : `Upgrade → <strong>${escapeHtml(top.fixedVersion || '?')}</strong>`;
+
+  const stages = [
+    { n: 1, label: 'Discover', icon: '🔎', body: `OSV-Scanner found <code>${escapeHtml(top.package)}</code> ${escapeHtml(top.currentVersion)}<br><span class="stage-sub">${escapeHtml(top.id || top.cveLink || 'advisory')} · ${depText}</span>` },
+    { n: 2, label: 'Assess', icon: '🛰️', body: `${assessText}<br><span class="stage-sub">${orbitReal ? 'real blast-radius exposure' : 'no import-graph weighting'}</span>` },
+    { n: 3, label: 'Score', icon: '⚖️', body: `${scoreText}<br><span class="stage-sub">CVSS+Exposure+Usage−Coverage</span>` },
+    { n: 4, label: 'Decide', icon: '🎯', body: `${decideText}<br><span class="stage-sub badge-inline" style="color:${priorityColor(rs.priority)}">${escapeHtml(rs.priority)}</span></span>` },
+    { n: 5, label: 'Remediate + Verify', icon: '🔧', body: 'Flow commits the fix, opens an MR,<br><span class="stage-sub">runs the test suite, never auto-merges</span>' },
+  ];
+
+  return `
+  <section class="pipeline">
+    <h2>🤖 Agentic decision flow <span class="pipeline-subject">— top finding: <code>${escapeHtml(top.package)}</code></span></h2>
+    <div class="pipeline-stages">
+      ${stages.map((s, i) => `
+        <div class="stage">
+          <div class="stage-head"><span class="stage-icon">${s.icon}</span><span class="stage-n">${s.n}. ${s.label}</span></div>
+          <div class="stage-body">${s.body}</div>
+        </div>${i < stages.length - 1 ? '<div class="stage-arrow">→</div>' : ''}`).join('')}
+    </div>
+    <div class="pipeline-note">Stages 1–4 are the analysis you see below; stage 5 is what the <strong>Custom Flow</strong> runs as a CI job when triggered. Same engine throughout.</div>
+  </section>`;
+}
+
+/**
+ * "Why this ranks above that" — compares the top two findings' actual
+ * score components instead of leaving the ranking as an unexplained
+ * black box.
+ */
+function renderRankingExplanation(vulnerabilities) {
+  if (vulnerabilities.length < 2) return '';
+  const [top, second] = vulnerabilities;
+  if (!top.riskScore || !second.riskScore) return '';
+
+  const exposureDiff = (top.riskScore.exposure ?? 0) - (second.riskScore.exposure ?? 0);
+  const severityDiff = (top.riskScore.severity ?? 0) - (second.riskScore.severity ?? 0);
+
+  let reason;
+  if (exposureDiff !== 0 && Math.abs(exposureDiff) >= Math.abs(severityDiff)) {
+    reason = `exposure — ${(top.affectedFiles || []).length} file(s) import <strong>${escapeHtml(top.package)}</strong> vs ${(second.affectedFiles || []).length} for <strong>${escapeHtml(second.package)}</strong>`;
+  } else if (severityDiff !== 0) {
+    reason = `severity — a CVSS-derived score of ${top.riskScore.severity}/100 vs ${second.riskScore.severity}/100`;
+  } else {
+    reason = 'a near-tie across severity and exposure';
+  }
+
+  return `<div class="ranking-note"><span class="ranking-icon">📌</span> <strong>${escapeHtml(top.package)}</strong> ranks above <strong>${escapeHtml(second.package)}</strong> primarily because of ${reason}.</div>`;
+}
+
+function relativeTime(isoDate, now = Date.now()) {
+  const diffMs = now - new Date(isoDate).getTime();
+  const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+  if (diffHours < 1) return 'just now';
+  if (diffHours < 24) return `${diffHours}h ago`;
+  return `${Math.floor(diffHours / 24)}d ago`;
+}
+
+const ACTIVITY_ICON = { issue: '📋', merge_request: '🔧' };
+const STATE_LABEL = { opened: 'open', merged: 'merged', closed: 'closed' };
+
+function renderActivityItem(item) {
+  const icon = ACTIVITY_ICON[item.type] || '•';
+  const stateLabel = STATE_LABEL[item.state] || item.state;
+  const stateClass = item.state === 'merged' ? 'state-merged' : item.state === 'opened' ? 'state-open' : 'state-closed';
+  return `
+    <li class="activity-item">
+      <span class="activity-icon">${icon}</span>
+      <a href="${escapeHtml(item.url)}" target="_blank">${escapeHtml(item.title)}</a>
+      <span class="activity-state ${stateClass}">${escapeHtml(stateLabel)}</span>
+      <span class="activity-time">${escapeHtml(relativeTime(item.createdAt))}</span>
+    </li>`;
+}
+
+/**
+ * Render the "what has the agent actually done" feed — real issues/MRs
+ * fetched live from GitLab's API (src/activityFetcher.js), not a
+ * separate log this project would have to keep in sync.
+ * @param {Object} activity - result of activityFetcher.getRecentActivity
+ */
+function renderActivityFeed(activity) {
+  if (!activity) return '';
+  if (!activity.available) {
+    return `<section class="activity"><h2>🤖 Agent Activity</h2><div class="empty">Activity feed unavailable: ${escapeHtml(activity.reason || 'unknown reason')}</div></section>`;
+  }
+  if (activity.items.length === 0) {
+    return '<section class="activity"><h2>🤖 Agent Activity</h2><div class="empty">No issues or merge requests created by the agent yet.</div></section>';
+  }
+  return `
+  <section class="activity">
+    <h2>🤖 Agent Activity</h2>
+    <ul class="activity-list">
+      ${activity.items.map(renderActivityItem).join('')}
+    </ul>
+  </section>`;
+}
+
+const SHARED_STYLES = `
+  :root {
+    color-scheme: dark;
+    --bg: #0a0d12;
+    --surface: #11161d;
+    --surface-raised: #161c25;
+    --border: #232b36;
+    --border-soft: #1b212b;
+    --text: #e6edf3;
+    --text-muted: #8b949e;
+    --accent: #2f81f7;
+    --accent-soft: rgba(47, 129, 247, 0.14);
+    --radius: 10px;
+    --radius-sm: 6px;
+    --font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  }
+  * { box-sizing: border-box; }
+  body {
+    font-family: var(--font);
+    margin: 0;
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.5;
+  }
+  a { color: var(--accent); }
+  code { background: var(--surface-raised); padding: 0.15rem 0.4rem; border-radius: 4px; font-size: 0.85em; }
+`;
+
+/**
+ * @param {Object} result - return value of agent.js's analyzeRepository()
+ * @param {Object} meta - { projectName, projectId, generatedAt, projectPath, serverUrl }
+ * @param {Object} activity - result of activityFetcher.getRecentActivity, or null to omit the feed
+ * @returns {string} a complete, self-contained HTML document
+ */
+function generateDashboardHtml(result, meta = {}, activity = null) {
+  // Highest risk first — the CLI's sortByRisk already does this, but a
+  // dashboard shouldn't trust call-order; sort explicitly for display.
+  const vulnerabilities = [...(result.vulnerabilities || [])]
+    .sort((a, b) => (b.riskScore?.score ?? -1) - (a.riskScore?.score ?? -1));
+  const counts = vulnerabilities.reduce((acc, v) => {
+    const p = v.riskScore?.priority || 'UNSCORED';
+    acc[p] = (acc[p] || 0) + 1;
+    return acc;
+  }, {});
+  const orbitCount = vulnerabilities.filter(v => v.riskScore?.exposureDataSource === 'orbit').length;
+  const totalRiskScore = vulnerabilities.reduce((sum, v) => sum + (v.riskScore?.score || 0), 0);
+  const generatedAt = meta.generatedAt || new Date().toISOString();
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DependencyIQ Dashboard${meta.projectName ? ` — ${escapeHtml(meta.projectName)}` : ''}</title>
+<style>
+${SHARED_STYLES}
+  .page { max-width: 1080px; margin: 0 auto; padding: 0 1.5rem 3rem; }
+  header.page-header {
+    display: flex; align-items: center; gap: 0.9rem;
+    padding: 1.75rem 0 1.25rem; border-bottom: 1px solid var(--border);
+    margin-bottom: 1.75rem;
+  }
+  .brand-icon { font-size: 1.9rem; line-height: 1; }
+  .brand-title { font-size: 1.25rem; font-weight: 700; letter-spacing: -0.01em; }
+  .brand-subtitle { color: var(--text-muted); font-size: 0.85rem; margin-top: 0.15rem; }
+
+  .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 0.85rem; margin-bottom: 1.75rem; }
+  .stat { background: var(--surface); border: 1px solid var(--border); border-left: 3px solid var(--accent); border-radius: var(--radius); padding: 1rem 1.1rem; }
+  .stat .num { font-size: 1.7rem; font-weight: 700; line-height: 1.1; }
+  .stat .label { color: var(--text-muted); font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.04em; margin-top: 0.3rem; }
+
+  .exec { margin-bottom: 1.75rem; background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 1.1rem 1.25rem; }
+  .exec h2 { font-size: 1rem; margin: 0 0 0.85rem; font-weight: 600; }
+  .exec-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 0.75rem; }
+  .exec-item { display: flex; flex-direction: column; gap: 0.2rem; padding: 0.6rem 0.75rem; background: var(--surface-raised); border-radius: var(--radius-sm); border: 1px solid var(--border-soft); }
+  .exec-num { font-size: 1.5rem; font-weight: 800; line-height: 1; }
+  .exec-label { font-size: 0.72rem; color: var(--text-muted); }
+  .exec-highlight { border-color: rgba(47, 129, 247, 0.4); }
+  .exec-highlight .exec-num { color: var(--accent); }
+  .exec-note { color: var(--text-muted); font-size: 0.72rem; margin-top: 0.7rem; }
+  .ranking-note {
+    background: var(--accent-soft); border: 1px solid rgba(47, 129, 247, 0.35);
+    border-radius: var(--radius); padding: 0.85rem 1.1rem; margin-bottom: 1.1rem; font-size: 0.88rem;
+  }
+  .ranking-icon { display: inline-block; }
+
+  .pipeline { margin-bottom: 1.75rem; }
+  .pipeline h2 { font-size: 1rem; margin: 0 0 0.85rem; font-weight: 600; }
+  .pipeline-subject { color: var(--text-muted); font-weight: 400; }
+  .pipeline-stages { display: flex; align-items: stretch; gap: 0; flex-wrap: wrap; }
+  .stage {
+    flex: 1 1 0; min-width: 150px;
+    background: var(--surface); border: 1px solid var(--border); border-top: 2px solid var(--accent);
+    border-radius: var(--radius); padding: 0.75rem 0.85rem;
+  }
+  .stage-head { display: flex; align-items: center; gap: 0.4rem; margin-bottom: 0.4rem; }
+  .stage-icon { font-size: 1rem; }
+  .stage-n { font-size: 0.78rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.02em; }
+  .stage-body { font-size: 0.8rem; line-height: 1.45; }
+  .stage-sub { color: var(--text-muted); font-size: 0.72rem; }
+  .badge-inline { font-weight: 700; text-transform: uppercase; font-size: 0.7rem; }
+  .stage-arrow { display: flex; align-items: center; color: var(--text-muted); padding: 0 0.35rem; font-size: 1.1rem; }
+  .pipeline-note { color: var(--text-muted); font-size: 0.76rem; margin-top: 0.6rem; }
+  @media (max-width: 760px) {
+    .stage-arrow { display: none; }
+    .stage { flex-basis: 100%; }
+  }
+
+  .filters { display: flex; gap: 0.5rem; margin-bottom: 1.25rem; flex-wrap: wrap; }
+  .filter-btn {
+    background: var(--surface); border: 1px solid var(--border); color: var(--text);
+    padding: 0.4rem 0.9rem; border-radius: 999px; cursor: pointer; font-size: 0.82rem;
+    transition: background 0.15s, border-color 0.15s;
+  }
+  .filter-btn:hover { border-color: var(--accent); }
+  .filter-btn.active { background: var(--accent); border-color: var(--accent); color: #fff; font-weight: 600; }
+
+  .findings-list { display: flex; flex-direction: column; gap: 0.85rem; }
+  .finding-card {
+    background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius);
+    padding: 1.1rem 1.25rem;
+  }
+  .finding-top { display: flex; align-items: center; justify-content: space-between; gap: 1rem; flex-wrap: wrap; }
+  .finding-identity { display: flex; align-items: baseline; gap: 0.6rem; flex-wrap: wrap; }
+  .finding-rank { color: var(--text-muted); font-size: 0.8rem; }
+  .finding-pkg { font-size: 1.05rem; font-weight: 600; }
+  .finding-version { color: var(--text-muted); font-size: 0.85rem; }
+  .finding-score { display: flex; align-items: center; gap: 0.6rem; }
+  .score-num { font-size: 1.4rem; font-weight: 800; color: var(--score-color); }
+  .score-max { color: var(--text-muted); font-size: 0.85rem; }
+
+  .finding-meta { display: flex; gap: 0.5rem; flex-wrap: wrap; margin: 0.75rem 0 0.85rem; }
+  .meta-chip {
+    background: var(--surface-raised); border: 1px solid var(--border-soft); color: var(--text-muted);
+    padding: 0.2rem 0.55rem; border-radius: var(--radius-sm); font-size: 0.75rem;
+  }
+  .meta-recommendation { color: var(--text); }
+
+  .badge { color: white; padding: 0.2rem 0.55rem; border-radius: var(--radius-sm); font-size: 0.72rem; font-weight: 700; text-transform: uppercase; }
+
+  .finding-actions { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.5rem; }
+  .action-btn {
+    background: var(--surface-raised); border: 1px solid var(--border); color: var(--text);
+    padding: 0.35rem 0.7rem; border-radius: var(--radius-sm); cursor: pointer; font-size: 0.78rem;
+    text-decoration: none; display: inline-block; transition: background 0.15s, border-color 0.15s;
+  }
+  .action-btn:hover { background: var(--border); border-color: var(--accent); }
+  .action-btn-primary { border-color: rgba(47, 129, 247, 0.4); color: var(--accent); }
+
+  .dep-badge { padding: 0.18rem 0.5rem; border-radius: var(--radius-sm); font-size: 0.72rem; text-transform: uppercase; font-weight: 700; }
+  .dep-direct { background: rgba(47, 129, 247, 0.16); color: #58a6ff; }
+  .dep-transitive { background: rgba(202, 138, 4, 0.18); color: #e3b341; }
+  .dep-unknown { background: rgba(107, 114, 128, 0.18); color: var(--text-muted); }
+  .dep-chain { font-size: 0.72rem; color: var(--text-muted); }
+
+  .decision-trail { font-size: 0.82rem; border-top: 1px solid var(--border-soft); padding-top: 0.6rem; margin-top: 0.4rem; }
+  .decision-trail summary { cursor: pointer; color: var(--accent); font-weight: 500; }
+  .trail-content { margin-top: 0.6rem; }
+  .trail-row { display: flex; justify-content: space-between; gap: 1rem; padding: 0.3rem 0; border-bottom: 1px solid var(--border-soft); }
+  .trail-row em { color: var(--text-muted); font-style: normal; font-size: 0.72rem; }
+  .trail-final { font-weight: 700; border-bottom: none; }
+  .trail-contribution { color: #e3b341; }
+  .trail-evidence { margin-top: 0.6rem; padding-top: 0.6rem; border-top: 1px solid var(--border-soft); }
+  .trail-evidence ul { margin: 0.3rem 0; padding-left: 1.2rem; }
+  .trail-more { color: var(--text-muted); font-size: 0.75rem; }
+  .evidence-group { margin-top: 0.5rem; }
+  .evidence-group strong { font-size: 0.76rem; }
+
+  .empty { padding: 2.25rem 1rem; text-align: center; color: var(--text-muted); background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); }
+
+  .activity { margin-top: 2.25rem; }
+  .activity h2 { font-size: 1.05rem; margin-bottom: 0.85rem; }
+  .activity-list { list-style: none; padding: 0; margin: 0; background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
+  .activity-item { padding: 0.7rem 1.1rem; border-bottom: 1px solid var(--border-soft); display: flex; align-items: center; gap: 0.7rem; font-size: 0.85rem; }
+  .activity-item:last-child { border-bottom: none; }
+  .activity-item a { text-decoration: none; flex: 1; }
+  .activity-item a:hover { text-decoration: underline; }
+  .activity-state { padding: 0.12rem 0.55rem; border-radius: var(--radius-sm); font-size: 0.7rem; text-transform: uppercase; }
+  .state-open { background: rgba(47, 129, 247, 0.16); color: #58a6ff; }
+  .state-merged { background: rgba(137, 87, 229, 0.18); color: #a371f7; }
+  .state-closed { background: rgba(107, 114, 128, 0.18); color: var(--text-muted); }
+  .activity-time { color: var(--text-muted); font-size: 0.75rem; white-space: nowrap; }
+
+  footer { margin-top: 2.5rem; padding-top: 1.25rem; border-top: 1px solid var(--border); color: var(--text-muted); font-size: 0.78rem; }
+
+  @media (max-width: 560px) {
+    .finding-top { flex-direction: column; align-items: flex-start; }
+    .page { padding: 0 1rem 2.5rem; }
+  }
+</style>
+</head>
+<body>
+<div class="page">
+  <header class="page-header">
+    <span class="brand-icon">🛡️</span>
+    <div>
+      <div class="brand-title">DependencyIQ Dashboard</div>
+      <div class="brand-subtitle">${meta.projectName ? escapeHtml(meta.projectName) + ' · ' : ''}generated ${escapeHtml(generatedAt)}</div>
+    </div>
+  </header>
+
+  <div class="stats">
+    <div class="stat"><div class="num">${vulnerabilities.length}</div><div class="label">Total findings</div></div>
+    <div class="stat" style="border-left-color:${priorityColor('URGENT')}"><div class="num" style="color:${priorityColor('URGENT')}">${counts.URGENT || 0}</div><div class="label">Urgent</div></div>
+    <div class="stat" style="border-left-color:${priorityColor('HIGH')}"><div class="num" style="color:${priorityColor('HIGH')}">${counts.HIGH || 0}</div><div class="label">High</div></div>
+    <div class="stat" style="border-left-color:${priorityColor('UNUSED')}"><div class="num" style="color:${priorityColor('UNUSED')}">${counts.UNUSED || 0}</div><div class="label">Unused (remove)</div></div>
+    <div class="stat"><div class="num">${orbitCount}/${vulnerabilities.length}</div><div class="label">Scored with real Orbit data</div></div>
+  </div>
+
+  ${vulnerabilities.length === 0 ? '<div class="empty">No vulnerabilities found.</div>' : `
+  ${renderExecutiveSummary(vulnerabilities)}
+  ${renderDecisionPipeline(vulnerabilities[0])}
+  ${renderRankingExplanation(vulnerabilities)}
+  <div class="filters">
+    <button class="filter-btn active" data-filter="ALL" onclick="filterRows(this)">All</button>
+    <button class="filter-btn" data-filter="UNUSED" onclick="filterRows(this)">Unused</button>
+    <button class="filter-btn" data-filter="URGENT" onclick="filterRows(this)">Urgent</button>
+    <button class="filter-btn" data-filter="HIGH" onclick="filterRows(this)">High</button>
+    <button class="filter-btn" data-filter="MEDIUM" onclick="filterRows(this)">Medium</button>
+    <button class="filter-btn" data-filter="LOW" onclick="filterRows(this)">Low</button>
+  </div>
+  <div class="findings-list" id="findings-list">
+    ${vulnerabilities.map((v, i) => renderFindingCard(v, i, meta, totalRiskScore)).join('')}
+  </div>`}
+
+  ${renderActivityFeed(activity)}
+
+  <footer>
+    Generated by <a href="https://github.com/google/osv-scanner">OSV-Scanner</a> +
+    GitLab Orbit blast-radius scoring. "Exposure: unavailable" means Orbit was unreachable for this
+    run — the score is still real CVSS, just without the import-graph weighting.
+    Static page published via GitLab Pages — no backend, no live data after generation. Client-side
+    filtering is plain JS on data already in this page — still no server round-trip.
+  </footer>
+</div>
+
+  <script>
+    function filterRows(btn) {
+      document.querySelectorAll('.filter-btn').forEach(b => b.classList.remove('active'));
+      btn.classList.add('active');
+      const filter = btn.dataset.filter;
+      document.querySelectorAll('#findings-list .finding-card').forEach(card => {
+        card.style.display = (filter === 'ALL' || card.dataset.priority === filter) ? '' : 'none';
+      });
+    }
+    function copyFixCommand(btn) {
+      const text = btn.dataset.copy;
+      if (navigator.clipboard) {
+        navigator.clipboard.writeText(text).then(() => {
+          const original = btn.textContent;
+          btn.textContent = '✅ Copied';
+          setTimeout(() => { btn.textContent = original; }, 1500);
+        });
+      }
+    }
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * Render an honest "scan failed" page instead of either crashing the
+ * pipeline with no artifact at all, or — the mistake this project
+ * actually made once — silently treating a failed scan as a clean one.
+ * @param {string} errorMessage
+ * @param {Object} meta - { projectName, generatedAt }
+ */
+function generateScanFailedHtml(errorMessage, meta = {}) {
+  const generatedAt = meta.generatedAt || new Date().toISOString();
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DependencyIQ Dashboard — Scan Failed</title>
+<style>
+${SHARED_STYLES}
+  .page { max-width: 720px; margin: 0 auto; padding: 2.5rem 1.5rem; }
+  h1 { color: #f85149; font-size: 1.4rem; display: flex; align-items: center; gap: 0.5rem; }
+  pre { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); padding: 1rem; white-space: pre-wrap; word-break: break-word; }
+  .subtitle { color: var(--text-muted); margin-bottom: 1.75rem; font-size: 0.88rem; }
+</style>
+</head>
+<body>
+<div class="page">
+  <h1>⚠️ Scan failed — this is NOT a clean result</h1>
+  <div class="subtitle">${meta.projectName ? escapeHtml(meta.projectName) + ' — ' : ''}attempted ${escapeHtml(generatedAt)}</div>
+  <p>The vulnerability scan did not complete successfully, so no risk data is shown here. This page intentionally does not claim "no vulnerabilities found" — that would be indistinguishable from a real clean scan, which would be misleading.</p>
+  <pre>${escapeHtml(errorMessage)}</pre>
+  <p>Check the pipeline job log for the full error, and re-run once resolved.</p>
+</div>
+</body>
+</html>`;
+}
+
+module.exports = { generateDashboardHtml, generateScanFailedHtml, SHARED_STYLES, escapeHtml, priorityColor };