ng-upgrade-doctor 0.2.0

package/src/report/html.js

@@ -0,0 +1,539 @@
+'use strict';
+
+function esc(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function num(n) {
+  return typeof n === 'number' ? n.toLocaleString('en-US') : esc(n);
+}
+
+const CAT = {
+  ok: { label: 'Compatible', cls: 'ok' },
+  agnostic: { label: 'Agnostic', cls: 'ok' },
+  upgrade: { label: 'Needs upgrade', cls: 'warn' },
+  partial: { label: 'Partial', cls: 'warn' },
+  blocker: { label: 'Blocker', cls: 'bad' },
+  removed: { label: 'Removed', cls: 'info' },
+  abandoned: { label: 'Abandoned', cls: 'muted' },
+  unknown: { label: 'Unknown', cls: 'muted' },
+};
+
+const SEV = {
+  removed: { label: 'Removed', cls: 'bad' },
+  deprecated: { label: 'Deprecated', cls: 'warn' },
+  opportunity: { label: 'Opportunity', cls: 'info' },
+};
+
+function renderHtml(report) {
+  const { snapshot, versionGap, deps, verdict, census, breakingChanges, meta } = report;
+  const s = deps.summary;
+  const scoreClass = verdict.score >= 80 ? 'good' : verdict.score >= 60 ? 'ok' : verdict.score >= 40 ? 'warn' : 'bad';
+
+  // --- Radial gauge geometry ---
+  const R = 54;
+  const CIRC = 2 * Math.PI * R;
+  const gaugeOffset = (CIRC * (1 - verdict.score / 100)).toFixed(2);
+
+  // --- Stat card: animate integers, render strings verbatim ---
+  const stat = (label, value, sub, accent) => {
+    const v = typeof value === 'number'
+      ? `<div class="stat-v" data-count="${value}">0</div>`
+      : `<div class="stat-v">${esc(value)}</div>`;
+    return `<div class="stat${accent ? ' a-' + accent : ''}">${v}<div class="stat-l">${esc(label)}</div>${sub ? `<div class="stat-s">${esc(sub)}</div>` : ''}</div>`;
+  };
+
+  // --- Plain-English verdict sentence ---
+  const hardBlockers = s.blocker + s.removed;
+  const verdictSentence = buildVerdictSentence(snapshot, versionGap, deps, verdict, breakingChanges, hardBlockers);
+
+  const inventoryStats = [
+    stat('Total dependencies', snapshot.totalDependencyCount, `${snapshot.prodDependencyCount} prod · ${snapshot.devDependencyCount} dev`, 'indigo'),
+    snapshot.transitiveDependencyCount != null ? stat('Transitive deps', snapshot.transitiveDependencyCount, 'from lockfile', 'indigo') : '',
+    stat('Angular packages', snapshot.angularPackageCount, snapshot.angularVersion || '', 'indigo'),
+    stat('3rd-party Angular libs', snapshot.thirdPartyAngularCount, '', 'indigo'),
+    census ? stat('Components', census.counts.components, `${census.counts.standaloneComponents} standalone`, 'teal') : '',
+    census ? stat('NgModules', census.counts.modules, `${census.counts.services} services`, 'teal') : '',
+    census ? stat('Source files', census.fileCounts.tsFiles, `${census.fileCounts.htmlTemplates} templates · ${census.fileCounts.specFiles} specs`, 'teal') : '',
+    census ? stat('Lines of code', census.counts.totalLoc, 'approx (src/**)', 'teal') : '',
+  ].join('');
+
+  // --- Dependency distribution bar ---
+  const distSegments = [
+    { key: 'ok', label: 'Compatible', count: s.ok + s.agnostic, cls: 'ok' },
+    { key: 'warn', label: 'Upgrade / partial', count: s.upgrade + s.partial, cls: 'warn' },
+    { key: 'blocker', label: 'Blockers', count: s.blocker, cls: 'bad' },
+    { key: 'removed', label: 'Removed', count: s.removed, cls: 'info' },
+    { key: 'abandoned', label: 'Abandoned', count: s.abandoned, cls: 'muted' },
+    { key: 'unknown', label: 'Unknown', count: s.unknown, cls: 'faint' },
+  ].filter((seg) => seg.count > 0);
+  const distTotal = distSegments.reduce((a, b) => a + b.count, 0) || 1;
+  const distBar = distSegments
+    .map((seg) => `<span class="seg ${seg.cls}" style="flex:${seg.count}" title="${esc(seg.label)}: ${seg.count}"></span>`)
+    .join('');
+  const distLegend = distSegments
+    .map((seg) => `<span class="lg"><i class="dot ${seg.cls}"></i>${esc(seg.label)} <b>${seg.count}</b> <span class="pct">${Math.round((seg.count / distTotal) * 100)}%</span></span>`)
+    .join('');
+
+  const compatStats = [
+    stat('Compatible', s.ok + s.agnostic, 'has a supporting release', 'green'),
+    stat('Needs work', s.upgrade + s.partial, 'behind or partial', 'amber'),
+    stat('Hard blockers', hardBlockers, 'no path to target', 'red'),
+    stat('Abandoned', s.abandoned, 'unmaintained', 'gray'),
+  ].join('');
+
+  const rows = deps.packages.map((p) => {
+    const cat = CAT[p.category] || CAT.unknown;
+    return `<tr data-cat="${p.category}">
+      <td class="mono">${esc(p.name)}${p.dev ? '<span class="tag">dev</span>' : ''}</td>
+      <td><span class="pill ${cat.cls}">${esc(cat.label)}</span></td>
+      <td class="mono">${esc(p.declaredRange || '')}</td>
+      <td class="mono">${esc(p.latestVersion || '—')}</td>
+      <td class="center">${p.maxAngularSupported != null ? 'v' + p.maxAngularSupported : (p.angularCoupled ? '—' : 'n/a')}</td>
+      <td class="reason">${esc(p.reason || '')}${p.replacement ? `<div class="repl">→ ${esc(p.replacement)}</div>` : ''}</td>
+    </tr>`;
+  }).join('');
+
+  // --- Code breaking-changes section ---
+  let breakingSection = '';
+  if (breakingChanges && breakingChanges.summary.totalHits > 0) {
+    const b = breakingChanges.summary;
+    const bcStats = [
+      stat('Removed APIs in use', b.removed, 'hard breaks', 'red'),
+      stat('Deprecated APIs', b.deprecated, 'will break later', 'amber'),
+      stat('Modernization ops', b.opportunity, 'optional upgrades', 'blue'),
+      stat('Files affected', b.filesAffected, `of ${breakingChanges.filesScanned.ts + breakingChanges.filesScanned.html} scanned`, 'indigo'),
+    ].join('');
+    const ruleRows = breakingChanges.rules.map((r) => {
+      const sev = SEV[r.severity] || SEV.opportunity;
+      const samples = r.samples.map((sp) => `<code>${esc(sp)}</code>`).join('');
+      const more = r.count > r.samples.length ? `<span class="muted"> +${r.count - r.samples.length} more</span>` : '';
+      return `<tr>
+        <td><span class="pill ${sev.cls}">${esc(sev.label)}</span></td>
+        <td><b>${esc(r.title)}</b><div class="reason">${esc(r.message)}</div><div class="repl">→ ${esc(r.fix)}</div></td>
+        <td class="center mono">${num(r.count)}</td>
+        <td class="center mono">${num(r.fileCount)}</td>
+        <td class="samples">${samples}${more}</td>
+      </tr>`;
+    }).join('');
+    breakingSection = `
+      <section id="code">
+      <h2><span class="h-ic">🧬</span>Code breaking changes</h2>
+      <div class="stats s4">${bcStats}</div>
+      <p class="legend">Scanned ${num(breakingChanges.filesScanned.ts)} TypeScript &amp; ${num(breakingChanges.filesScanned.html)} template files using ${breakingChanges.astAvailable ? 'the project’s TypeScript compiler (AST)' : 'a regex fallback'}. Locations are <code>file:line:col</code>.</p>
+      <div class="tablewrap">
+        <table>
+          <thead><tr><th>Severity</th><th>Issue &amp; recommended fix</th><th class="center">Hits</th><th class="center">Files</th><th>Sample locations</th></tr></thead>
+          <tbody>${ruleRows}</tbody>
+        </table>
+      </div>
+      </section>`;
+  }
+
+  const blockerCards = verdict.blockers.length
+    ? verdict.blockers.map((b) => `<div class="card bad">
+        <div class="card-h"><span class="pill ${b.category === 'removed' ? 'info' : 'bad'}">${esc((CAT[b.category] || {}).label || b.category)}</span> <span class="mono">${esc(b.name)}</span></div>
+        <div class="card-b">${esc(b.reason)}</div>
+        ${b.replacement ? `<div class="card-r">Recommended: <b>${esc(b.replacement)}</b></div>` : ''}
+      </div>`).join('')
+    : '<div class="empty">✓ No hard blockers detected — nice.</div>';
+
+  const pathHtml = versionGap.known && versionGap.hops.length
+    ? `<div class="path">${[`<span class="hop cur">v${versionGap.currentMajor}<em>current</em></span>`]
+        .concat(versionGap.hops.map((h, i) => `<span class="arrow">→</span><span class="hop${i === versionGap.hops.length - 1 ? ' target' : ''}" title="${esc((h.notes || []).join(' · '))}">v${h.major}${i === versionGap.hops.length - 1 ? '<em>target</em>' : ''}</span>`))
+        .join('')}</div>
+       <div class="hop-notes">${versionGap.hops.map((h) => `<div class="hop-note"><div class="hop-badge">v${h.major}</div><div class="hop-req">Node ${esc(h.node)} · TS ${esc(h.ts)}</div><ul>${(h.notes || []).map((n) => `<li>${esc(n)}</li>`).join('')}</ul></div>`).join('')}</div>`
+    : '<p class="muted">Upgrade path unavailable (version not recognized).</p>';
+
+  const deductionsHtml = verdict.deductions.length
+    ? `<ul class="deductions">${verdict.deductions.map((d) => `<li><span class="minus">−${d.points}</span><span class="dbar"><span style="width:${Math.min(100, d.points * 2.2)}%"></span></span><span class="dlabel">${esc(d.label)}</span></li>`).join('')}</ul>`
+    : '<p class="muted">No deductions — full marks.</p>';
+
+  const quickWins = verdict.quickWins.length
+    ? `<ul class="wins">${verdict.quickWins.map((w) => `<li>${esc(w)}</li>`).join('')}</ul>`
+    : '';
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ng-upgrade-doctor · ${esc(snapshot.name)}</title>
+<style>
+${CSS}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <header class="masthead">
+    <div class="brand"><span class="logo">🩺</span><div><div class="btitle">ng-upgrade-doctor</div><div class="bsub">Angular upgrade readiness &amp; blast-radius report</div></div></div>
+    <div class="meta-right">
+      <div class="proj">${esc(snapshot.name)}</div>
+      <div class="muted small"><span title="The Angular version compatibility is assessed against. Defaults to the latest version known to the tool; override with --target <major>." style="cursor:help;border-bottom:1px dotted var(--faint)">Target Angular ${esc(deps.targetMajor)}</span>${deps.offline ? ' · offline mode' : ''}${meta.generatedAt ? ' · ' + esc(meta.generatedAt) : ''}</div>
+    </div>
+  </header>
+
+  <section class="hero ${scoreClass}">
+    <div class="gauge" role="img" aria-label="Upgrade readiness score ${verdict.score} out of 100">
+      <svg viewBox="0 0 130 130">
+        <circle class="g-track" cx="65" cy="65" r="${R}"></circle>
+        <circle class="g-fill" cx="65" cy="65" r="${R}"
+          stroke-dasharray="${CIRC.toFixed(2)}" stroke-dashoffset="${CIRC.toFixed(2)}"
+          data-offset="${gaugeOffset}" transform="rotate(-90 65 65)"></circle>
+      </svg>
+      <div class="g-center"><div class="g-score" data-count="${verdict.score}">0</div><div class="g-out">/ 100</div></div>
+    </div>
+    <div class="hero-body">
+      <div class="band-tag ${scoreClass}">${esc(verdict.bandLabel)}</div>
+      <p class="verdict">${verdictSentence}</p>
+      <div class="kpis">
+        <div class="kpi"><div class="kpi-v">${esc(snapshot.angularVersion || '?')}</div><div class="kpi-l">Current Angular</div></div>
+        <div class="kpi"><div class="kpi-v">${versionGap.known ? versionGap.majorsBehind : '?'}</div><div class="kpi-l">Majors behind</div></div>
+        <div class="kpi"><div class="kpi-v">${hardBlockers}</div><div class="kpi-l">Hard blockers</div></div>
+        <div class="kpi" title="Estimated developer-days: roughly how many working days ONE developer would need for the whole upgrade — clearing blockers, the version hops and code fixes. Across a team, divide by the number of developers for calendar time. Heuristic range, not a commitment.">
+          <div class="kpi-v">${verdict.effort.lowDays}–${verdict.effort.highDays}</div><div class="kpi-l">Est. effort <span class="info">ⓘ</span></div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <nav class="toc">
+    <a href="#inventory">Inventory</a>
+    <a href="#path">Upgrade path</a>
+    <a href="#deps">Dependencies</a>
+    ${breakingSection ? '<a href="#code">Code changes</a>' : ''}
+    <a href="#plan">Plan</a>
+  </nav>
+
+  <section id="inventory">
+    <h2><span class="h-ic">📦</span>Project inventory</h2>
+    <div class="stats">${inventoryStats}</div>
+  </section>
+
+  <section id="path">
+    <h2><span class="h-ic">🧭</span>Upgrade path</h2>
+    <div class="panel">${pathHtml}</div>
+  </section>
+
+  <section id="deps">
+    <h2><span class="h-ic">🔗</span>Dependency compatibility</h2>
+    <div class="stats s4">${compatStats}</div>
+    <div class="panel distpanel">
+      <div class="distbar">${distBar}</div>
+      <div class="dist-legend">${distLegend}</div>
+    </div>
+    <div class="controls" id="filters">
+      <button data-f="all" class="active">All (${s.total})</button>
+      <button data-f="blocker">Blockers (${s.blocker})</button>
+      <button data-f="removed">Removed (${s.removed})</button>
+      <button data-f="abandoned">Abandoned (${s.abandoned})</button>
+      <button data-f="partial">Partial (${s.partial})</button>
+      <button data-f="ok">Compatible (${s.ok + s.agnostic})</button>
+    </div>
+    <div class="tablewrap">
+    <table id="deptable">
+      <thead><tr>
+        <th data-k="name">Package</th><th data-k="cat">Status</th><th data-k="range">Declared</th>
+        <th data-k="latest">Latest</th><th class="center" data-k="max">Supports</th><th>Notes</th>
+      </tr></thead>
+      <tbody>${rows}</tbody>
+    </table>
+    </div>
+    <div class="legend">“Supports” = highest Angular major the package’s published peer dependencies accept. “n/a” = framework-agnostic library. Click a header to sort.</div>
+  </section>
+
+  ${breakingSection}
+
+  <section id="plan">
+    <h2><span class="h-ic">🚑</span>Must-fix before upgrading</h2>
+    <div class="cards">${blockerCards}</div>
+
+    <h3>Readiness score breakdown</h3>
+    <div class="panel">${deductionsHtml}</div>
+
+    ${quickWins ? `<h3>Quick wins</h3><div class="panel">${quickWins}</div>` : ''}
+  </section>
+
+  <footer>
+    Generated by <b>ng-upgrade-doctor</b> v${esc(meta.toolVersion)} · zero-dependency · read-only.<br>
+    Compatibility is inferred from published npm peer dependencies and a curated knowledge base; always verify against the official Angular Update Guide before upgrading.
+  </footer>
+</div>
+<button id="toTop" class="to-top" aria-label="Back to top" title="Back to top">↑</button>
+${SCRIPT}
+</body>
+</html>`;
+}
+
+function buildVerdictSentence(snapshot, versionGap, deps, verdict, breakingChanges, hardBlockers) {
+  const from = snapshot.angularMajor;
+  const to = deps.targetMajor;
+  const bits = [];
+  if (from && versionGap.known) {
+    bits.push(`Upgrading <b>Angular ${from} → ${to}</b> is rated <b>${esc(verdict.band)}</b>.`);
+  } else {
+    bits.push(`This project is rated <b>${esc(verdict.band)}</b> for upgrade readiness.`);
+  }
+  const clauses = [];
+  if (hardBlockers > 0) clauses.push(`<b>${hardBlockers}</b> hard blocker${hardBlockers === 1 ? '' : 's'} to clear`);
+  if (versionGap.known && versionGap.hopCount > 0) clauses.push(`<b>${versionGap.hopCount}</b> version hop${versionGap.hopCount === 1 ? '' : 's'}`);
+  if (breakingChanges && breakingChanges.summary.removed > 0) clauses.push(`<b>${breakingChanges.summary.removed}</b> removed-API usage${breakingChanges.summary.removed === 1 ? '' : 's'} in code`);
+  if (clauses.length) {
+    bits.push(`There ${clauses.length === 1 ? 'is' : 'are'} ${joinList(clauses)}, for an estimated <b>${verdict.effort.lowDays}–${verdict.effort.highDays} developer-days</b> of work.`);
+  } else {
+    bits.push(`Estimated effort is <b>${verdict.effort.lowDays}–${verdict.effort.highDays} developer-days</b>.`);
+  }
+  return bits.join(' ');
+}
+
+function joinList(arr) {
+  if (arr.length === 1) return arr[0];
+  return arr.slice(0, -1).join(', ') + ' and ' + arr[arr.length - 1];
+}
+
+const CSS = `
+:root{
+  --bg:#f4f6fa; --panel:#ffffff; --ink:#151b28; --muted:#5f6b82; --faint:#9aa4ba; --line:#e6e9f0;
+  --brand:#5b3df5; --brand2:#7b5cff;
+  --good:#12855a; --ok:#1f8f6a; --warn:#b0730d; --bad:#cf3a2b; --info:#2f6fed;
+  --good-bg:#e4f6ec; --warn-bg:#fdf1de; --bad-bg:#fbe7e4; --info-bg:#e8f0fe; --muted-bg:#eef1f6; --faint-bg:#f2f4f8;
+  --shadow:0 1px 2px rgba(20,27,40,.04),0 4px 12px rgba(20,27,40,.05);
+}
+@media (prefers-color-scheme: dark){
+  :root{ --bg:#0d1118; --panel:#161c29; --ink:#e8edf6; --muted:#98a3ba; --faint:#5b6577; --line:#25304a;
+    --brand:#8b73ff; --brand2:#a48dff;
+    --good:#3fce8f; --ok:#3fce8f; --warn:#e5a94a; --bad:#f2705f; --info:#6ea0ff;
+    --good-bg:#10321f; --warn-bg:#33280f; --bad-bg:#3a1b16; --info-bg:#132244; --muted-bg:#1d2536; --faint-bg:#161d2b;
+    --shadow:0 1px 2px rgba(0,0,0,.28),0 5px 16px rgba(0,0,0,.26);}
+}
+:root[data-theme=dark]{ color-scheme:dark; }
+*{box-sizing:border-box}
+html{scroll-behavior:smooth}
+body{margin:0;font:15px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;background:var(--bg);color:var(--ink);-webkit-font-smoothing:antialiased}
+.wrap{max-width:1080px;margin:0 auto;padding:28px 20px 80px}
+.small{font-size:12px}
+.muted{color:var(--muted)}
+
+.masthead{display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:14px;margin-bottom:22px}
+.brand{display:flex;align-items:center;gap:12px}
+.logo{font-size:30px;filter:drop-shadow(0 2px 6px rgba(91,61,245,.35))}
+.btitle{font-size:19px;font-weight:800;letter-spacing:-.3px}
+.bsub{color:var(--muted);font-size:12.5px}
+.meta-right{text-align:right}
+.proj{font-weight:700}
+
+/* Hero */
+.hero{position:relative;display:grid;grid-template-columns:170px 1fr;gap:28px;align-items:center;background:
+  radial-gradient(120% 140% at 0% 0%, color-mix(in srgb,var(--brand) 10%, var(--panel)) 0%, var(--panel) 55%);
+  border:1px solid var(--line);border-radius:20px;padding:26px 28px;box-shadow:var(--shadow);overflow:hidden}
+.hero:before{content:"";position:absolute;inset:0 0 auto 0;height:4px;background:linear-gradient(90deg,var(--brand),var(--brand2))}
+.hero.good:before{background:linear-gradient(90deg,var(--good),#4fd6a0)}
+.hero.warn:before{background:linear-gradient(90deg,var(--warn),#e6b24d)}
+.hero.bad:before{background:linear-gradient(90deg,var(--bad),#f0866f)}
+@media(max-width:620px){.hero{grid-template-columns:1fr;justify-items:center;text-align:center}}
+
+.gauge{position:relative;width:150px;height:150px}
+.gauge svg{width:150px;height:150px;display:block}
+.g-track{fill:none;stroke:var(--muted-bg);stroke-width:12}
+.g-fill{fill:none;stroke-width:12;stroke-linecap:round;transition:stroke-dashoffset 1.15s cubic-bezier(.34,.9,.3,1)}
+.hero.good .g-fill{stroke:var(--good)} .hero.ok .g-fill{stroke:var(--ok)}
+.hero.warn .g-fill{stroke:var(--warn)} .hero.bad .g-fill{stroke:var(--bad)}
+.g-center{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center}
+.g-score{font-size:44px;font-weight:850;line-height:1;letter-spacing:-1px}
+.hero.good .g-score{color:var(--good)} .hero.ok .g-score{color:var(--ok)}
+.hero.warn .g-score{color:var(--warn)} .hero.bad .g-score{color:var(--bad)}
+.g-out{font-size:12px;color:var(--muted);font-weight:600;margin-top:2px}
+
+.band-tag{display:inline-block;font-weight:700;font-size:13px;padding:4px 12px;border-radius:20px;margin-bottom:8px}
+.band-tag.good{background:var(--good-bg);color:var(--good)} .band-tag.ok{background:var(--good-bg);color:var(--ok)}
+.band-tag.warn{background:var(--warn-bg);color:var(--warn)} .band-tag.bad{background:var(--bad-bg);color:var(--bad)}
+.verdict{margin:6px 0 16px;font-size:16px;line-height:1.5}
+.kpis{display:grid;grid-template-columns:repeat(4,1fr);gap:12px}
+@media(max-width:620px){.kpis{grid-template-columns:repeat(2,1fr);width:100%}}
+.kpi{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:10px 12px}
+.kpi-v{font-size:19px;font-weight:800;letter-spacing:-.3px}
+.kpi-l{color:var(--muted);font-size:11.5px;margin-top:1px}
+
+/* TOC */
+.toc{position:sticky;top:0;z-index:20;display:flex;gap:6px;flex-wrap:wrap;margin:22px 0 8px;padding:9px 10px;background:var(--panel);border:1px solid var(--line);border-radius:12px;box-shadow:var(--shadow)}
+.toc a{color:var(--muted);text-decoration:none;font-size:13px;font-weight:600;padding:5px 11px;border-radius:16px}
+.toc a:hover{color:var(--ink);background:var(--muted-bg)}
+section{scroll-margin-top:66px}
+.info{font-size:10px;opacity:.65;cursor:help;vertical-align:super}
+
+h2{font-size:15px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:34px 0 14px;font-weight:800;display:flex;align-items:center;gap:8px}
+.h-ic{font-size:16px}
+h3{font-size:14px;margin:26px 0 10px;font-weight:700}
+.panel{background:var(--panel);border:1px solid var(--line);border-radius:16px;padding:20px;box-shadow:var(--shadow)}
+
+.stats{display:grid;grid-template-columns:repeat(auto-fill,minmax(158px,1fr));gap:12px}
+.stats.s4{grid-template-columns:repeat(auto-fill,minmax(180px,1fr))}
+.stat{position:relative;background:var(--panel);border:1px solid var(--line);border-radius:14px;padding:15px 16px;box-shadow:var(--shadow);overflow:hidden;transition:transform .15s ease,box-shadow .15s ease}
+.stat:hover{transform:translateY(-2px)}
+.stat:before{content:"";position:absolute;left:0;top:0;bottom:0;width:4px;background:var(--faint)}
+.stat.a-indigo:before{background:var(--brand)} .stat.a-teal:before{background:#17a2a2}
+.stat.a-green:before{background:var(--good)} .stat.a-amber:before{background:var(--warn)}
+.stat.a-red:before{background:var(--bad)} .stat.a-blue:before{background:var(--info)} .stat.a-gray:before{background:var(--faint)}
+.stat-v{font-size:27px;font-weight:850;letter-spacing:-.6px;line-height:1.1}
+.stat-l{color:var(--muted);font-size:12.5px;margin-top:3px;font-weight:600}
+.stat-s{color:var(--faint);font-size:11.5px;margin-top:4px}
+
+/* Distribution bar */
+.stats + .panel{margin-top:18px}
+.distpanel{margin-top:18px;margin-bottom:14px}
+.distbar{display:flex;height:16px;border-radius:8px;overflow:hidden;gap:2px;background:var(--muted-bg)}
+.distbar .seg{display:block;min-width:3px;transition:flex .6s ease}
+.seg.ok{background:var(--good)} .seg.warn{background:var(--warn)} .seg.bad{background:var(--bad)}
+.seg.info{background:var(--info)} .seg.muted{background:var(--faint)} .seg.faint{background:var(--line)}
+.dist-legend{display:flex;flex-wrap:wrap;gap:14px;margin-top:12px;font-size:12.5px}
+.lg{display:flex;align-items:center;gap:6px;color:var(--muted)}
+.lg b{color:var(--ink)} .pct{color:var(--faint)}
+.dot{width:10px;height:10px;border-radius:3px;display:inline-block}
+.dot.ok{background:var(--good)} .dot.warn{background:var(--warn)} .dot.bad{background:var(--bad)}
+.dot.info{background:var(--info)} .dot.muted{background:var(--faint)} .dot.faint{background:var(--line)}
+
+/* Path */
+.path{display:flex;align-items:center;flex-wrap:wrap;gap:8px;font-weight:800;margin-bottom:18px}
+.hop{position:relative;background:var(--info-bg);color:var(--info);border-radius:10px;padding:8px 14px 18px;text-align:center}
+.hop em{position:absolute;left:0;right:0;bottom:3px;font-style:normal;font-size:9px;font-weight:700;letter-spacing:.05em;text-transform:uppercase;opacity:.7}
+.hop.cur{background:var(--muted-bg);color:var(--muted)}
+.hop.target{background:var(--brand);color:#fff}
+.arrow{color:var(--faint)}
+.hop-notes{display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:12px}
+.hop-note{border:1px solid var(--line);border-radius:12px;padding:14px;font-size:13px;background:var(--panel)}
+.hop-badge{display:inline-block;font-weight:800;color:var(--brand);background:var(--info-bg);border-radius:8px;padding:2px 9px;font-size:13px}
+.hop-req{color:var(--faint);font-size:11.5px;margin:8px 0 6px}
+.hop-note ul{margin:0;padding-left:18px;color:var(--muted)}
+.hop-note li{margin:3px 0}
+
+/* Controls + table */
+.controls{display:flex;gap:8px;flex-wrap:wrap;margin:14px 0 12px}
+.controls button{background:var(--panel);border:1px solid var(--line);color:var(--muted);border-radius:20px;padding:6px 13px;font-size:12.5px;cursor:pointer;font-weight:600;transition:all .12s}
+.controls button:hover{color:var(--ink);border-color:var(--faint)}
+.controls button.active{background:var(--brand);color:#fff;border-color:var(--brand)}
+.tablewrap{overflow-x:auto;border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow)}
+table{width:100%;border-collapse:collapse;font-size:13.5px;background:var(--panel)}
+th,td{text-align:left;padding:10px 12px;border-bottom:1px solid var(--line);vertical-align:top}
+tbody tr{transition:background .1s}
+tbody tr:hover{background:var(--faint-bg)}
+tbody tr:last-child td{border-bottom:none}
+th{background:var(--panel);cursor:pointer;user-select:none;font-size:11.5px;text-transform:uppercase;letter-spacing:.04em;color:var(--muted)}
+th:hover{color:var(--ink)}
+td.center,th.center{text-align:center}
+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12.5px}
+.tag{background:var(--muted-bg);color:var(--muted);border-radius:5px;padding:1px 5px;margin-left:6px;font-size:10.5px;font-family:inherit}
+.reason{color:var(--muted);max-width:420px;font-size:12.5px}
+.repl{color:var(--info);margin-top:4px;font-size:12.5px}
+.samples{max-width:320px}
+.samples code{display:inline-block;background:var(--muted-bg);color:var(--muted);border-radius:5px;padding:1px 6px;margin:2px 4px 2px 0;font-size:11px;font-family:ui-monospace,Menlo,Consolas,monospace}
+
+.pill{display:inline-block;border-radius:20px;padding:2px 11px;font-size:12px;font-weight:700;white-space:nowrap}
+.pill.ok{background:var(--good-bg);color:var(--good)}
+.pill.warn{background:var(--warn-bg);color:var(--warn)}
+.pill.bad{background:var(--bad-bg);color:var(--bad)}
+.pill.info{background:var(--info-bg);color:var(--info)}
+.pill.muted{background:var(--muted-bg);color:var(--muted)}
+
+.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(270px,1fr));gap:12px}
+.card{border:1px solid var(--line);border-radius:14px;padding:15px;background:var(--panel);box-shadow:var(--shadow)}
+.card.bad{border-left:4px solid var(--bad)}
+.card-h{display:flex;align-items:center;gap:8px;font-weight:700;margin-bottom:7px}
+.card-b{color:var(--muted);font-size:13px}
+.card-r{margin-top:9px;font-size:13px}
+.empty{background:var(--good-bg);color:var(--good);border-radius:14px;padding:16px;font-weight:600}
+
+.deductions{list-style:none;padding:0;margin:0}
+.deductions li{display:flex;align-items:center;gap:12px;padding:9px 0;border-bottom:1px solid var(--line)}
+.deductions li:last-child{border-bottom:none}
+.minus{min-width:40px;color:var(--bad);font-weight:800;font-variant-numeric:tabular-nums}
+.dbar{flex:0 0 110px;height:7px;background:var(--muted-bg);border-radius:4px;overflow:hidden}
+.dbar span{display:block;height:100%;background:linear-gradient(90deg,var(--bad),#f0866f);border-radius:4px}
+.dlabel{color:var(--muted);font-size:13px}
+.wins{list-style:none;padding:0;margin:0}
+.wins li{padding:8px 0 8px 26px;position:relative;border-bottom:1px solid var(--line)}
+.wins li:last-child{border-bottom:none}
+.wins li:before{content:"✓";position:absolute;left:2px;top:8px;color:var(--good);font-weight:800}
+
+.legend{color:var(--faint);font-size:12px;margin-top:10px}
+.legend code{background:var(--muted-bg);padding:1px 5px;border-radius:4px}
+footer{margin-top:44px;color:var(--faint);font-size:12px;text-align:center;line-height:1.7}
+footer b{color:var(--muted)}
+
+.to-top{position:fixed;right:22px;bottom:22px;width:46px;height:46px;border-radius:50%;border:none;background:var(--brand);color:#fff;font-size:22px;line-height:1;cursor:pointer;box-shadow:0 6px 20px rgba(20,27,40,.25);opacity:0;visibility:hidden;transform:translateY(10px);transition:opacity .2s,transform .2s,visibility .2s,background .15s;z-index:40}
+.to-top.show{opacity:1;visibility:visible;transform:none}
+.to-top:hover{background:var(--brand2)}
+.to-top:focus-visible{outline:2px solid var(--brand2);outline-offset:2px}
+
+@media (prefers-reduced-motion: reduce){
+  .g-fill{transition:none} .stat{transition:none} html{scroll-behavior:auto}
+}
+@media print{
+  .toc{display:none} .to-top{display:none} body{background:#fff} .stat,.panel,.card,.tablewrap,.hero{box-shadow:none}
+}
+`;
+
+const SCRIPT = `<script>
+(function(){
+  function ready(fn){ if(document.readyState!=='loading') fn(); else document.addEventListener('DOMContentLoaded',fn); }
+  ready(function(){
+    var reduce = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+    // Gauge fill
+    var fill=document.querySelector('.g-fill');
+    if(fill){ var off=fill.getAttribute('data-offset');
+      if(reduce){ fill.style.strokeDashoffset=off; }
+      else { requestAnimationFrame(function(){ requestAnimationFrame(function(){ fill.style.strokeDashoffset=off; }); }); }
+    }
+
+    // Count-up numbers
+    document.querySelectorAll('[data-count]').forEach(function(el){
+      var target=parseInt(el.getAttribute('data-count'),10)||0;
+      if(reduce||target<=0){ el.textContent=target.toLocaleString('en-US'); return; }
+      var dur= target>1000?900:650, start=null;
+      function step(ts){ if(start===null)start=ts; var p=Math.min((ts-start)/dur,1);
+        var e=1-Math.pow(1-p,3); el.textContent=Math.floor(e*target).toLocaleString('en-US');
+        if(p<1)requestAnimationFrame(step); else el.textContent=target.toLocaleString('en-US'); }
+      requestAnimationFrame(step);
+    });
+
+    // Back-to-top button
+    var toTop=document.getElementById('toTop');
+    if(toTop){
+      var onScroll=function(){ if(window.pageYOffset>400) toTop.classList.add('show'); else toTop.classList.remove('show'); };
+      window.addEventListener('scroll',onScroll,{passive:true}); onScroll();
+      toTop.addEventListener('click',function(){ window.scrollTo({top:0,behavior:reduce?'auto':'smooth'}); });
+    }
+
+    // Table filtering
+    var filters=document.getElementById('filters');
+    var table=document.getElementById('deptable');
+    if(filters&&table){
+      var tbody=table.querySelector('tbody');
+      var rows=Array.prototype.slice.call(tbody.querySelectorAll('tr'));
+      filters.addEventListener('click',function(e){
+        var b=e.target.closest('button'); if(!b)return;
+        filters.querySelectorAll('button').forEach(function(x){x.classList.remove('active')});
+        b.classList.add('active');
+        var f=b.getAttribute('data-f');
+        rows.forEach(function(r){ var c=r.getAttribute('data-cat');
+          r.style.display=(f==='all'||c===f||(f==='ok'&&(c==='ok'||c==='agnostic')))?'':'none'; });
+      });
+      // Sorting
+      var dir={};
+      table.querySelectorAll('th').forEach(function(th,i){
+        th.addEventListener('click',function(){ dir[i]=!dir[i];
+          rows.slice().sort(function(a,b){
+            var x=a.children[i].innerText.trim().toLowerCase(), y=b.children[i].innerText.trim().toLowerCase();
+            if(x<y)return dir[i]?-1:1; if(x>y)return dir[i]?1:-1; return 0;
+          }).forEach(function(r){tbody.appendChild(r)});
+        });
+      });
+    }
+  });
+})();
+</script>`;
+
+module.exports = { renderHtml };

package/src/report/json.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/** Machine-readable report for CI gates and dashboards. */
+function renderJson(report) {
+  const { snapshot, versionGap, deps, verdict, census, breakingChanges, meta } = report;
+  return JSON.stringify(
+    {
+      tool: 'ng-upgrade-doctor',
+      version: meta.toolVersion,
+      generatedAtNote: 'timestamp added by caller if available',
+      project: {
+        name: snapshot.name,
+        angularVersion: snapshot.angularVersion,
+        angularMajor: snapshot.angularMajor,
+        typescript: snapshot.tsVersion,
+        packageManager: snapshot.packageManager,
+        workspaceType: snapshot.workspaceType,
+        builder: snapshot.builder,
+        testRunner: snapshot.testRunner,
+        e2e: snapshot.e2e,
+      },
+      inventory: {
+        prodDependencies: snapshot.prodDependencyCount,
+        devDependencies: snapshot.devDependencyCount,
+        totalDependencies: snapshot.totalDependencyCount,
+        transitiveDependencies: snapshot.transitiveDependencyCount,
+        angularPackages: snapshot.angularPackageCount,
+        thirdPartyAngularLibs: snapshot.thirdPartyAngularCount,
+        census: census || null,
+      },
+      versionGap,
+      readiness: {
+        score: verdict.score,
+        band: verdict.band,
+        bandLabel: verdict.bandLabel,
+        effort: verdict.effort,
+        deductions: verdict.deductions,
+      },
+      dependencies: {
+        target: deps.targetMajor,
+        summary: deps.summary,
+        packages: deps.packages,
+      },
+      breakingChanges: breakingChanges
+        ? {
+            astAvailable: breakingChanges.astAvailable,
+            filesScanned: breakingChanges.filesScanned,
+            summary: breakingChanges.summary,
+            rules: breakingChanges.rules,
+          }
+        : null,
+      blockers: verdict.blockers,
+      quickWins: verdict.quickWins,
+    },
+    null,
+    2
+  );
+}
+
+module.exports = { renderJson };