fullstack-critic 1.0.0 → 1.0.3

package/src/ui.js

@@ -0,0 +1,443 @@
+'use strict';
+/**
+ * Built-in per-run critic dashboard. Zero-dependency (Node core only).
+ *
+ * Why this exists: the only previous UI was the opt-in `--dash` bridge into an
+ * external, *shared* Session Observatory server that accumulates every session,
+ * so it visually mixes reports from other projects. This module is instead
+ * single-tenant: each `critic review`/`critic watch` process owns its own state,
+ * scoped to exactly one project. Starting a new run therefore always shows fresh
+ * data (there is nothing to clear because nothing is shared or persisted).
+ *
+ *   - review  -> writeStaticAndOpen(): one self-contained HTML file in a per-run
+ *                 temp path (unique + titled with the project), opened in the OS
+ *                 browser. No server left running; never written into the repo.
+ *   - watch   -> startLive(): an in-memory HTTP server on a verified free port
+ *                 that re-renders on every pass. Live updates; no file in the repo.
+ *
+ * Port policy: probe from a base port and walk to the next bindable port.
+ * Never block or break the workflow: any UI error is swallowed to a warning.
+ */
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const net = require('net');
+const { DIMENSIONS } = require('./analyzer');
+const { execSummary } = require('./report');
+const { openBrowser } = require('./observatory');
+const sysinfo = require('./sysinfo');
+
+const SEV_ORDER = ['BLOCKER', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+const UI_BASE_PORT = 4781;   // distinct from the observatory's 4780
+const PORT_SPAN = 15;
+
+function relName(root) {
+  const parts = String(root).replace(/[\\/]+$/, '').split(/[\\/]/);
+  return parts[parts.length - 1] || String(root);
+}
+
+/* ------------------------------ snapshot model ---------------------------- */
+
+function buildSnapshot(result, extra = {}) {
+  const counts = result.counts || {};
+  const cat = result.categoryCounts || {};
+  const cov = result.coverage || {};
+  const findings = result.findings || [];
+
+  const byDim = {};
+  for (const f of findings) (byDim[f.dimension] || (byDim[f.dimension] = [])).push(f);
+  const dimensions = DIMENSIONS.map((d) => {
+    const ds = byDim[d] || [];
+    const worst = SEV_ORDER.find((s) => ds.some((f) => f.severity === s));
+    const status = !ds.length ? 'REVIEW'
+      : (worst === 'BLOCKER' || worst === 'CRITICAL' || worst === 'HIGH') ? 'FAIL'
+        : (worst === 'MEDIUM' || worst === 'LOW') ? 'WARN' : 'INFO';
+    return { dimension: d, status, count: ds.length, worst: worst || '-' };
+  });
+
+  return {
+    empty: false,
+    project: relName((result.meta && result.meta.root) || ''),
+    root: (result.meta && result.meta.root) || '',
+    generatedAt: new Date().toISOString(),
+    cliVersion: (result.meta && result.meta.cliVersion) || 'unknown',
+    durationMs: (result.meta && result.meta.durationMs) || 0,
+    passNo: extra.passNo || 1,
+    addedCount: (extra.added || []).length,
+    resolvedCount: (extra.resolved || []).length,
+    verdict: execSummary(result),
+    counts,
+    categoryCounts: cat,
+    coverage: {
+      filesScanned: cov.filesScanned || 0,
+      totalLines: cov.totalLines || 0,
+      filesSkipped: cov.filesSkipped || 0,
+    },
+    ecosystems: (result.dependencies || []).map((e) => ({
+      name: e.name, manifest: e.manifest, declaredCount: e.declaredCount, lock: e.lock || null,
+    })),
+    dimensions,
+    findings: findings.map((f) => ({
+      file: f.file, line: f.line, severity: f.severity, category: f.category,
+      dimension: f.dimension, title: f.title, problem: f.problem, fix: f.fix, evidence: f.evidence,
+    })),
+    // OS-level live telemetry + expected-completion estimate (see sysinfo.js).
+    sys: extra.sys || null,
+    estimate: extra.estimate || null,
+  };
+}
+
+function emptySnapshot(root) {
+  return {
+    empty: true, project: relName(root), root, generatedAt: new Date().toISOString(),
+    passNo: 0, counts: {}, categoryCounts: {}, findings: [], dimensions: [], ecosystems: [],
+  };
+}
+
+/* ------------------------------- HTML shell ------------------------------- */
+
+// NOTE: the embedded client script intentionally avoids backticks/${} so it can
+// live inside this file's template literals without clashing with Node's parser.
+function renderHtml(data, opts = {}) {
+  const live = opts.live ? 'true' : 'false';
+  const payload = JSON.stringify(data).replace(/</g, '\\u003c');
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Full-Stack Critic — ${escAttr(data.project)}</title>
+<link rel="icon" href="data:,">
+<style>
+  :root{--bg:#0b1020;--card:#151b2e;--ink:#e6ecff;--mut:#93a0c2;--line:#26304a;--critic:#ff5470;--high:#ff9f43;--med:#ffd166;--low:#8bd450;--info:#63b3ed;--ok:#3ddc97;}
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);font:14px/1.5 system-ui,Segoe UI,Roboto,Arial,sans-serif}
+  header{padding:22px 26px;border-bottom:1px solid var(--line);background:linear-gradient(180deg,#111834,#0b1020)}
+  h1{margin:0;font-size:20px;letter-spacing:.3px}
+  h1 .proj{color:var(--info)}
+  .sub{color:var(--mut);margin-top:6px;font-size:12.5px}
+  main{padding:22px 26px;max-width:1080px;margin:0 auto}
+  .verdict{font-size:16px;font-weight:600;padding:12px 16px;border-radius:10px;background:var(--card);border:1px solid var(--line);margin-bottom:18px}
+  .grid{display:flex;flex-wrap:wrap;gap:10px;margin-bottom:18px}
+  .chip{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:10px 14px;min-width:78px}
+  .chip b{display:block;font-size:22px}
+  .chip span{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.6px}
+  .sev-CRITICAL,.sev-BLOCKER{color:var(--critic)} .sev-HIGH{color:var(--high)} .sev-MEDIUM{color:var(--med)} .sev-LOW{color:var(--low)} .sev-INFO{color:var(--info)}
+  h2{font-size:14px;text-transform:uppercase;letter-spacing:.8px;color:var(--mut);margin:26px 0 10px}
+  table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+  th,td{text-align:left;padding:9px 12px;border-bottom:1px solid var(--line);vertical-align:top}
+  th{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.5px}
+  tr:last-child td{border-bottom:none}
+  code{background:#0c1226;border:1px solid var(--line);border-radius:5px;padding:1px 6px;color:#cdd8ff;font-size:12px}
+  .tag{display:inline-block;font-size:10.5px;font-weight:700;padding:2px 8px;border-radius:999px;border:1px solid var(--line);text-transform:uppercase;letter-spacing:.4px}
+  .cat-fix{color:var(--critic)} .cat-optimize{color:var(--high)} .cat-delete{color:var(--med)} .cat-add{color:var(--ok)}
+  .st-FAIL{background:rgba(255,84,112,.14);color:var(--critic)} .st-WARN{background:rgba(255,209,102,.14);color:var(--med)} .st-INFO{background:rgba(99,179,237,.14);color:var(--info)} .st-REVIEW{background:rgba(147,160,194,.14);color:var(--mut)}
+  details{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 14px;margin-bottom:10px}
+  summary{cursor:pointer;font-weight:600}
+  .loc{color:var(--mut);font-size:12px;margin-left:8px}
+  .field{margin:8px 0} .field .k{color:var(--mut);font-size:11px;text-transform:uppercase}
+  footer{color:var(--mut);font-size:11.5px;padding:20px 26px;border-top:1px solid var(--line);margin-top:24px}
+  .pulse{display:inline-block;width:8px;height:8px;border-radius:50%;background:var(--ok);margin-right:6px;animation:p 1.4s infinite}
+  @keyframes p{0%,100%{opacity:.3}50%{opacity:1}}
+  /* --- OS live-task + ETA panels --- */
+  .row2{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-bottom:18px}
+  @media(max-width:860px){.row2{grid-template-columns:1fr}}
+  .card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px 16px}
+  .card h2{margin-top:0}
+  .gauges{display:flex;gap:18px;flex-wrap:wrap;margin-bottom:8px}
+  .gauge{min-width:120px;flex:1}
+  .gauge .top{display:flex;justify-content:space-between;align-items:baseline;color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.5px}
+  .gauge .top b{font-size:22px;color:var(--ink)}
+  .track{height:8px;background:#0c1226;border:1px solid var(--line);border-radius:999px;margin-top:6px;overflow:hidden}
+  .track>i{display:block;height:100%;border-radius:999px;transition:width .5s ease}
+  #charts{display:grid;grid-template-columns:1fr;gap:10px;margin-top:10px}
+  .chart{background:#0c1226;border:1px solid var(--line);border-radius:8px;padding:8px 10px}
+  .chart .ct{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.5px;margin-bottom:4px}
+  .chart svg{display:block;width:100%;height:46px}
+  .eta-barbox{height:14px;background:#0c1226;border:1px solid var(--line);border-radius:999px;overflow:hidden;margin-bottom:8px}
+  .eta-bar{height:100%;width:0;background:linear-gradient(90deg,var(--ok),var(--info));transition:width .15s linear}
+  .eta-line{font-size:15px;font-weight:600}
+  .grid2{display:grid;grid-template-columns:1fr 1fr 1fr;gap:10px;margin-top:12px}
+  @media(max-width:860px){.grid2{grid-template-columns:1fr 1fr}}
+  .kv{background:#0c1226;border:1px solid var(--line);border-radius:8px;padding:8px 10px}
+  .kv .k{color:var(--mut);font-size:10.5px;text-transform:uppercase;letter-spacing:.5px}
+  .kv .v{font-size:14px;font-weight:600;margin-top:2px}
+  .bar{position:relative;height:20px;min-width:90px;background:#0c1226;border:1px solid var(--line);border-radius:6px;overflow:hidden}
+  .bar>i{display:block;height:100%;opacity:.5;transition:width .5s ease}
+  .bar>span{position:absolute;left:6px;top:0;line-height:20px;font-size:11.5px;color:#fff;text-shadow:0 0 3px rgba(0,0,0,.85)}
+  th.sortable{cursor:pointer} th.sortable:hover{color:var(--ink)} th.act{color:var(--ink)}
+  .c-project{color:var(--ok)} .c-runtime{color:var(--info)} .c-browser{color:var(--high)} .c-terminal{color:var(--med)}
+  .c-editor{color:#c792ea} .c-database{color:var(--critic)} .c-container{color:#7fdbca} .c-package{color:#ffd166}
+  .c-vcs{color:#93a0c2} .c-system{color:var(--mut)} .c-other{color:var(--mut)}
+</style></head>
+<body>
+<header>
+  <h1>Full-Stack Critic <span class="proj" id="h-proj"></span></h1>
+  <div class="sub" id="h-sub"></div>
+</header>
+<main>
+  <div class="verdict" id="verdict"></div>
+  <div class="grid" id="counts"></div>
+  <div class="row2">
+    <section class="card"><h2>Estimated Completion</h2><div id="eta"></div></section>
+    <section class="card"><h2>OS Activity <span class="sub" id="os-meta"></span></h2><div id="gauges"></div><div id="charts"></div></section>
+  </div>
+  <h2>Live Tasks — running processes, grouped app-wise</h2>
+  <div id="tasks" class="card"></div>
+  <h2>12-Dimension Executive Summary</h2>
+  <table id="dims"><thead><tr><th>Dimension</th><th>Status</th><th>Findings</th><th>Worst</th></tr></thead><tbody></tbody></table>
+  <h2>Prioritised Action Plan</h2>
+  <div id="plan"></div>
+  <h2>All Findings</h2>
+  <div id="findings"></div>
+  <h2>Resources & Dependencies</h2>
+  <div id="deps"></div>
+</main>
+<footer id="foot"></footer>
+<script>
+var INITIAL = ${payload};
+var LIVE = ${live};
+var SEV = ['BLOCKER','CRITICAL','HIGH','MEDIUM','LOW','INFO'];
+var CATS = [['fix','FIX — correctness & security'],['optimize','OPTIMIZE — performance & structure'],['delete','DELETE — dead code & debug'],['add','ADD — tests, config & docs']];
+function el(t,c,x){var e=document.createElement(t);if(c)e.className=c;if(x!=null)e.textContent=x;return e;}
+
+/* ---- OS live-task + expected-completion rendering (zero-dep SVG charts) ---- */
+var LASTSYS=null; var SORT='cpu'; var LASTEST=null; var PASS={no:-1,start:0};
+var SVGNS='http://www.w3.org/2000/svg';
+function fmtBytes(n){n=Number(n)||0;if(n>=1073741824)return (n/1073741824).toFixed(1)+' GB';if(n>=1048576)return (n/1048576).toFixed(0)+' MB';if(n>=1024)return (n/1024).toFixed(0)+' KB';return n+' B';}
+function fmtPct(n){return (Math.round((Number(n)||0)*10)/10)+'%';}
+function round1(n){return Math.round((Number(n)||0)*10)/10;}
+function dur(sec){sec=Math.max(0,Math.floor(Number(sec)||0));var h=Math.floor(sec/3600),m=Math.floor((sec%3600)/60),s=sec%60;if(h)return h+'h '+m+'m';if(m)return m+'m '+s+'s';return s+'s';}
+function maxOf(hist,key){var mx=0;for(var i=0;i<hist.length;i++){var v=Number(hist[i][key])||0;if(v>mx)mx=v;}return mx;}
+function bar(val,max,color,text){var b=el('div','bar');var f=el('i');f.style.width=(max>0?Math.min(100,(val/max)*100):0)+'%';if(color)f.style.background=color;b.appendChild(f);if(text!=null)b.appendChild(el('span',null,text));return b;}
+function kv(k,v){var d=el('div','kv');d.appendChild(el('div','k',k));d.appendChild(el('div','v',String(v)));return d;}
+function gaugeCard(label,pct,color){var g=el('div','gauge');var top=el('div','top');top.appendChild(el('span',null,label));top.appendChild(el('b',null,fmtPct(pct)));g.appendChild(top);var tr=el('div','track');var f=el('i');f.style.width=Math.min(100,Math.max(0,Number(pct)||0))+'%';f.style.background=color;tr.appendChild(f);g.appendChild(tr);return g;}
+function chart(hist,key,label,color,max){var box=el('div','chart');box.appendChild(el('div','ct',label));var W=300,H=46;var svg=document.createElementNS(SVGNS,'svg');svg.setAttribute('viewBox','0 0 '+W+' '+H);svg.setAttribute('preserveAspectRatio','none');box.appendChild(svg);var n=hist.length;if(!n||n<2){box.appendChild(el('div','sub','collecting samples…'));return box;}var mx=max||maxOf(hist,key)||1;var line='';var area='0,'+H+' ';for(var i=0;i<n;i++){var v=Number(hist[i][key])||0;var x=(i/(n-1))*W;var y=H-(Math.min(v,mx)/mx)*H;line+=(i?' ':'')+x.toFixed(1)+','+y.toFixed(1);area+=x.toFixed(1)+','+y.toFixed(1)+' ';}area+=W+','+H;var pg=document.createElementNS(SVGNS,'polygon');pg.setAttribute('points',area);pg.setAttribute('fill',color);pg.setAttribute('opacity','0.12');var pl=document.createElementNS(SVGNS,'polyline');pl.setAttribute('points',line);pl.setAttribute('fill','none');pl.setAttribute('stroke',color);pl.setAttribute('stroke-width','1.6');svg.appendChild(pg);svg.appendChild(pl);var cap=el('div','sub');cap.textContent='now '+fmtPct(hist[n-1][key])+' · peak '+fmtPct(maxOf(hist,key))+' · scale '+round1(mx)+'%';box.appendChild(cap);return box;}
+function renderOs(sys){var box=document.getElementById('gauges');var ch=document.getElementById('charts');if(!box)return;box.textContent='';if(ch)ch.textContent='';if(!sys||!sys.system){box.appendChild(el('span','sub','OS telemetry unavailable'));return;}
+  var meta=document.getElementById('os-meta');if(meta)meta.textContent=sys.system.platform+'/'+sys.system.arch+' · '+sys.system.cores+' cores · '+sys.system.hostname;
+  var g=el('div','gauges');g.appendChild(gaugeCard('System CPU',sys.system.cpuPct,'var(--high)'));g.appendChild(gaugeCard('Memory',sys.system.memPct,'var(--info)'));g.appendChild(gaugeCard('Critic CPU',sys.self?sys.self.cpuPct:0,'var(--critic)'));box.appendChild(g);
+  var st=el('div','sub');st.textContent='Processes: '+sys.totals.procCount+' · Apps: '+sys.totals.appCount+' · RAM '+fmtBytes(sys.system.memUsed)+' / '+fmtBytes(sys.system.memTotal)+' · Critic RSS '+(sys.self?fmtBytes(sys.self.rss):'?')+' · uptime '+dur(sys.system.uptimeSec);box.appendChild(st);
+  if(ch){if(sys.history)ch.appendChild(chart(sys.history,'cpu','CPU %','var(--high)',100));if(sys.history)ch.appendChild(chart(sys.history,'mem','Memory %','var(--info)',100));if(sys.history)ch.appendChild(chart(sys.history,'selfCpu','Critic CPU %','var(--critic)',Math.max(40,maxOf(sys.history,'selfCpu'))));}
+}
+function th(label,key){var t=el('th','sortable'+(SORT===key?' act':''),label);if(key)t.onclick=function(){SORT=key;renderTasks(LASTSYS);};return t;}
+function renderTasks(sys){var box=document.getElementById('tasks');if(!box)return;box.textContent='';LASTSYS=sys;if(!sys||!sys.apps||!sys.apps.length){box.appendChild(el('p','sub',(sys&&sys.totals&&sys.totals.refreshing)?'sampling running processes…':'Per-app live tasks stream in here a few seconds after the dashboard starts.'));return;}
+  var maxcpu=1,maxmem=1;sys.apps.forEach(function(a){if(a.cpuPct>maxcpu)maxcpu=a.cpuPct;if(a.memBytes>maxmem)maxmem=a.memBytes;});
+  var rows=sys.apps.slice();if(SORT==='mem')rows.sort(function(a,b){return b.memBytes-a.memBytes;});else if(SORT==='name')rows.sort(function(a,b){return String(a.app).localeCompare(String(b.app));});else rows.sort(function(a,b){return b.cpuPct-a.cpuPct;});
+  var t=el('table');var thead=el('thead');var hr=el('tr');hr.appendChild(th('App / Process','name'));hr.appendChild(th('Category',''));hr.appendChild(th('Instances',''));hr.appendChild(th('CPU %','cpu'));hr.appendChild(th('Memory','mem'));thead.appendChild(hr);t.appendChild(thead);
+  var body=el('tbody');rows.forEach(function(a){var tr=el('tr');var nm=el('td');nm.appendChild(el('code',null,a.app));tr.appendChild(nm);tr.appendChild(el('td')).appendChild(el('span','tag c-'+a.category,a.category));tr.appendChild(el('td',null,String(a.count)));var cc=el('td');cc.appendChild(bar(a.cpuPct,maxcpu,'var(--high)',fmtPct(a.cpuPct)));tr.appendChild(cc);var mc=el('td');mc.appendChild(bar(a.memBytes,maxmem,'var(--info)',fmtBytes(a.memBytes)));tr.appendChild(mc);body.appendChild(tr);});
+  t.appendChild(body);box.appendChild(t);
+  var cats=Object.keys(sys.totals.byCategory||{});if(cats.length){var leg=el('div','sub');leg.style.marginTop='10px';leg.textContent='By category: '+cats.sort().map(function(k){return k+' ('+(sys.totals.byCategory[k].count)+' proc, '+fmtBytes(sys.totals.byCategory[k].memBytes)+')';}).join('  ·  ');box.appendChild(leg);}
+}
+function renderEta(e,d){var box=document.getElementById('eta');if(!box)return;box.textContent='';if(!e){box.appendChild(el('p','sub','Estimating expected completion…'));return;}LASTEST=e;if(e.passNo!==PASS.no){PASS.no=e.passNo;PASS.start=Date.now();}
+  var bb=el('div','eta-barbox');var b=el('div','eta-bar');b.id='eta-bar';if(e.complete)b.style.width='100%';bb.appendChild(b);box.appendChild(bb);
+  box.appendChild(el('div','eta-line',e.etaLabel||''));
+  var cnt=el('div','sub');cnt.id='eta-count';box.appendChild(cnt);
+  var g=el('div','grid2');
+  g.appendChild(kv('Scan rate',(e.scanRateFps||0)+' files/s'));
+  g.appendChild(kv('Lines/s',(e.linesPerSec||0).toLocaleString?String((e.linesPerSec||0).toLocaleString()):String(e.linesPerSec||0)));
+  g.appendChild(kv('Files scanned',String(e.filesTotal||0)));
+  g.appendChild(kv('Last pass',(e.lastPassMs||0)+' ms'));
+  g.appendChild(kv('Avg pass',(e.avgPassMs||0)+' ms'));
+  g.appendChild(kv('Passes','×'+(e.passNo||0)));
+  g.appendChild(kv('Time on task',dur(e.timeOnTaskSec)));
+  g.appendChild(kv('System load','×'+(e.loadFactor||1)));
+  g.appendChild(kv('Cores',String(e.cores||0)));
+  box.appendChild(g);tickEta();
+}
+function tickEta(){if(!LASTEST)return;var e=LASTEST;var b=document.getElementById('eta-bar');var c=document.getElementById('eta-count');var total=(e.estPassMs||0)/1000;if(e.complete){if(b)b.style.width='100%';if(c)c.textContent=(e.mode==='watch')?'idle — watching for your next edit':('done in ~'+round1(total)+'s');return;}var secs=(Date.now()-PASS.start)/1000;var pct=total>0?Math.min(100,(secs/total)*100):0;if(b)b.style.width=pct+'%';if(c)c.textContent='this pass: '+round1(secs)+'s / ~'+round1(total)+'s expected';}
+function render(d){
+  document.getElementById('h-proj').textContent = '— ' + (d.project||'');
+  var sub = (d.root||'') + '  ·  ' + (d.generatedAt? new Date(d.generatedAt).toLocaleString():'');
+  if(d.empty){ sub = 'waiting for first analysis pass…'; }
+  else if(LIVE){ sub += '  ·  live pass #' + d.passNo + ' (+'+d.addedCount+' new / -'+d.resolvedCount+' fixed)'; }
+  document.getElementById('h-sub').textContent = sub;
+
+  renderEta(d.estimate,d); renderOs(d.sys); renderTasks(d.sys);
+
+  var v=document.getElementById('verdict'); v.textContent='';
+  if(d.empty){ v.appendChild(el('span',null,'Analysis starting…')); return; }
+  v.appendChild(el('span','pulse'));
+  v.appendChild(el('span',null,d.verdict||''));
+
+  var c=document.getElementById('counts'); c.textContent='';
+  SEV.forEach(function(s){ if(!d.counts[s]) return; var chip=el('div','chip'); chip.appendChild(el('b','sev-'+s,String(d.counts[s]))); chip.appendChild(el('span',null,s)); c.appendChild(chip); });
+  ['fix','optimize','delete','add'].forEach(function(k){ if(!d.categoryCounts[k]) return; var chip=el('div','chip'); chip.appendChild(el('b','cat-'+k,String(d.categoryCounts[k]))); chip.appendChild(el('span',null,'to '+k)); c.appendChild(chip); });
+
+  var tb=document.querySelector('#dims tbody'); tb.textContent='';
+  (d.dimensions||[]).forEach(function(x){ var tr=el('tr'); tr.appendChild(el('td',null,x.dimension)); var st=el('td'); st.appendChild(el('span','tag st-'+x.status,x.status)); tr.appendChild(st); tr.appendChild(el('td',null,String(x.count))); tr.appendChild(el('td','sev-'+(x.worst||''),''),x.worst==='-'?null:x.worst); if(x.worst==='-')tr.lastChild.textContent='—'; tb.appendChild(tr); });
+
+  var p=document.getElementById('plan'); p.textContent='';
+  CATS.forEach(function(pair){
+    var key=pair[0]; var items=(d.findings||[]).filter(function(f){return f.category===key;});
+    if(!items.length) return;
+    var h=el('h3','cat-'+key, pair[1]+' — '+items.length+' item(s)'); p.appendChild(h);
+    var t=el('table'); var thead=el('thead'); var hr=el('tr');
+    ['Sev','Where','Action','Fix'].forEach(function(x){hr.appendChild(el('th',null,x));}); thead.appendChild(hr); t.appendChild(thead);
+    var body=el('tbody');
+    items.slice(0,200).forEach(function(f){ var tr=el('tr'); tr.appendChild(el('td','sev-'+f.severity,f.severity)); tr.appendChild(el('td')).appendChild(el('code',null,f.file+':'+f.line)); tr.appendChild(el('td',null,f.title)); tr.appendChild(el('td',null,f.fix||f.problem||'')); body.appendChild(tr); });
+    t.appendChild(body); p.appendChild(t);
+  });
+
+  var fd=document.getElementById('findings'); fd.textContent='';
+  if(!(d.findings||[]).length){ fd.appendChild(el('p','sub','No automated findings.')); }
+  (d.findings||[]).slice(0,400).forEach(function(f){
+    var det=el('details'); var sum=el('summary'); sum.appendChild(el('span','sev-'+f.severity,'['+f.severity+'] ')); sum.appendChild(document.createTextNode(f.title)); sum.appendChild(el('span','loc',f.file+':'+f.line+'  ·  '+f.dimension+'  ·  '+f.category)); det.appendChild(sum);
+    [['Problem',f.problem],['Evidence',f.evidence],['Fix',f.fix]].forEach(function(pair){ if(!pair[1])return; var div=el('div','field'); div.appendChild(el('div','k',pair[0])); div.appendChild(el('code',null,pair[1])); det.appendChild(div); });
+    fd.appendChild(det);
+  });
+
+  var dp=document.getElementById('deps'); dp.textContent='';
+  var info=el('p','sub','Scanned '+d.coverage.filesScanned+' files · '+Number(d.coverage.totalLines).toLocaleString()+' lines · '+d.coverage.filesSkipped+' counted-but-skipped resources · '+(d.ecosystems||[]).length+' package ecosystem(s).');
+  dp.appendChild(info);
+  if((d.ecosystems||[]).length){ var t=el('table'); var body=el('tbody');
+    d.ecosystems.forEach(function(e){ var tr=el('tr'); tr.appendChild(el('td',null,e.name)); tr.appendChild(el('td')).appendChild(el('code',null,e.manifest)); tr.appendChild(el('td',null,String(e.declaredCount)+' declared')); var lk=el('td'); if(e.lock){lk.appendChild(el('code',null,e.lock));}else{lk.appendChild(el('span','tag st-FAIL','NO LOCKFILE'));} tr.appendChild(lk); body.appendChild(tr); });
+    t.appendChild(body); dp.appendChild(t); }
+
+  document.getElementById('foot').textContent = 'Full-Stack Critic v'+(d.cliVersion||'')+' · read-only REVIEW · this dashboard is scoped to this single run/project ('+(d.root||'')+') and holds no history from other projects.';
+}
+render(INITIAL);
+function offline(){ var v=document.getElementById('verdict'); if(v){ v.textContent=''; v.appendChild(el('span',null,'Dashboard disconnected - the critic watch process is no longer serving. Restart it to resume live updates.')); } }
+if(LIVE){ setInterval(function(){ fetch('/data',{cache:'no-store'}).then(function(r){return r.json();}).then(render).catch(offline); }, 1500); }
+setInterval(tickEta, 150);
+function esc(s){return String(s==null?'':s);}
+</script>
+</body></html>`;
+}
+
+function escAttr(s) {
+  return String(s == null ? '' : s).replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' }[c]));
+}
+
+/* ------------------------------ free port probe --------------------------- */
+
+function pickFreePort(base, span) {
+  const b = Number(base) || UI_BASE_PORT;
+  const s = Number(span) || PORT_SPAN;
+  return new Promise((resolve) => {
+    let p = b;
+    (function test() {
+      if (p > b + s) return resolve(null);
+      const probe = net.createServer();
+      probe.once('error', () => { p++; test(); });
+      probe.once('listening', () => { probe.close(() => resolve(p)); });
+      probe.listen(p, '127.0.0.1');
+    })();
+  });
+}
+
+/* ------------------------------- static (review) -------------------------- */
+
+function writeStaticAndOpen(result, opts = {}) {
+  try {
+    const cov = result.coverage || {};
+    let sys = null;
+    let estimate = null;
+    try {
+      sys = sysinfo.snapshotOnce((result.meta && result.meta.root) || process.cwd());
+      estimate = sysinfo.computeEstimate({
+        mode: 'review', passNo: 1,
+        lastPassMs: (result.meta && result.meta.durationMs) || 0,
+        filesTotal: cov.filesScanned || 0, totalLines: cov.totalLines || 0,
+        cores: sys.system.cores, cpuPct: sys.system.cpuPct,
+      });
+    } catch { /* OS probe is best-effort; the report still renders without it */ }
+    const data = buildSnapshot(result, Object.assign({ sys, estimate }, opts.extra || {}));
+    const dir = path.join(os.tmpdir(), 'fullstack-critic');
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = data.generatedAt.replace(/[:.]/g, '-');
+    const file = path.join(dir, `${data.project}-${stamp}.html`);
+    fs.writeFileSync(file, renderHtml(data, { live: false }));
+    const url = 'file:///' + file.replace(/\\/g, '/');
+    if (opts.open !== false) openBrowser(url);
+    return { file, url };
+  } catch (e) {
+    return { error: e.code || e.message };
+  }
+}
+
+/* --------------------------------- live (watch) --------------------------- */
+
+function startLive(root, opts = {}) {
+  let data = emptySnapshot(root);
+
+  // Live OS telemetry. The cheap system/self reading advances on a timer so the
+  // charts keep moving between HTTP polls; the expensive machine-wide process
+  // table refreshes async on its own slower cadence and never blocks requests.
+  const monitor = sysinfo.createMonitor(root);
+  const startedAt = Date.now();
+  const timing = { passNo: 0, lastPassMs: 0, durations: [] };
+  try { monitor.sample(); monitor.refresh(() => {}); } catch { /* best-effort */ }
+  const timers = [
+    setInterval(() => { try { monitor.sample(); } catch { /* ignore */ } }, 1200),
+    setInterval(() => { try { monitor.refresh(() => {}); } catch { /* ignore */ } }, 3500),
+  ];
+
+  function currentEstimate(sys) {
+    const cov = data.coverage || {};
+    try {
+      return sysinfo.computeEstimate({
+        mode: 'watch', passNo: timing.passNo, lastPassMs: timing.lastPassMs, durationsMs: timing.durations,
+        filesTotal: cov.filesScanned || 0, totalLines: cov.totalLines || 0,
+        cores: sys && sys.system ? sys.system.cores : undefined, cpuPct: sys && sys.system ? sys.system.cpuPct : null,
+        startedAt, now: Date.now(), debounceMs: opts.debounceMs,
+      });
+    } catch { return null; }
+  }
+
+  function withSys(d) {
+    let sys = null;
+    try { sys = monitor.sample(); } catch { /* ignore */ }
+    return Object.assign({}, d, { sys, estimate: currentEstimate(sys), startedAt, passNo: timing.passNo });
+  }
+
+  const server = http.createServer((req, res) => {
+    if (req.url === '/data') {
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      return res.end(JSON.stringify(withSys(data)));
+    }
+    if (req.url === '/sys') {
+      let sys = null; try { sys = monitor.sample(); } catch { /* ignore */ }
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      return res.end(JSON.stringify({ sys, estimate: currentEstimate(sys) }));
+    }
+    if (req.url === '/health') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify({ product: 'critic-ui', port: server.address() ? server.address().port : 0 }));
+    }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(renderHtml(withSys(data), { live: true }));
+  });
+
+  return pickFreePort(opts.port).then((port) => {
+    if (!port) { for (const t of timers) clearInterval(t); return null; } // no free port → skip UI, never break the workflow
+    return new Promise((resolve) => {
+      server.once('error', (e) => {
+        for (const t of timers) clearInterval(t);
+        process.stderr.write(`critic UI server unavailable (${e.code || e.message}); watch continues without the dashboard.\n`);
+        resolve(null);
+      });
+      server.once('listening', () => {
+        const bound = server.address().port;
+        resolve({
+          port: bound,
+          url: `http://127.0.0.1:${bound}/`,
+          set: (r, extra) => {
+            data = buildSnapshot(r, extra);
+            timing.passNo = (extra && extra.passNo) || timing.passNo + 1;
+            const d = (r.meta && r.meta.durationMs) || 0;
+            timing.lastPassMs = d;
+            if (d > 0) { timing.durations.push(d); if (timing.durations.length > 12) timing.durations.shift(); }
+          },
+          close: () => {
+            for (const t of timers) clearInterval(t);
+            try { server.close(); } catch { /* already closed */ }
+          },
+        });
+      });
+      server.listen(port, '127.0.0.1');
+    });
+  });
+}
+
+module.exports = {
+  buildSnapshot, renderHtml, writeStaticAndOpen, startLive, pickFreePort,
+  UI_BASE_PORT, SEV_ORDER,
+};

package/src/util.js

@@ -15,6 +15,12 @@ const SKIP_DIRS = new Set([
   '.critic', '.critic-memory',
 ]);
 
+// Files the critic itself generates. Never re-scanned: otherwise a previous
+// report's example findings would echo back as stale "findings" forever.
+const OUTPUT_FILES = new Set([
+  '.critic-report.md', '.critic-review.json', '.critic-report.html', '.critic-report.json',
+]);
+
 // Extensions that are definitely not scannable text.
 const BINARY_EXT = new Set([
   '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.bmp', '.tiff', '.pdf',
@@ -62,6 +68,10 @@ function walk(root) {
         skipped.push({ rel, reason: 'symbolic link (not followed)' });
         continue;
       }
+      if (OUTPUT_FILES.has(ent.name)) {
+        skipped.push({ rel, reason: 'critic output artifact (self-report, not re-scanned)' });
+        continue;
+      }
       let st;
       try { st = fs.statSync(abs); } catch (e) { skipped.push({ rel, reason: `stat failed (${e.code})` }); continue; }
       const ext = path.extname(ent.name).toLowerCase();
@@ -96,4 +106,4 @@ function exists(p) {
   try { fs.accessSync(p); return true; } catch { return false; }
 }
 
-module.exports = { walk, readText, exists, SKIP_DIRS, MAX_FILE_BYTES };
+module.exports = { walk, readText, exists, SKIP_DIRS, OUTPUT_FILES, MAX_FILE_BYTES };

package/src/watcher.js

@@ -49,12 +49,15 @@ function watch(root, opts = {}) {
     const result = analyze(root);
     const current = new Map(result.findings.map((f) => [keyOf(f), f]));
 
+    let added = [];
+    let resolved = [];
     if (first) {
       process.stdout.write(renderConsole(result) + '\n');
+      added = [...current.values()]; // initial surfacing of everything open
       first = false;
     } else {
-      const added = [...current.values()].filter((f) => !last.has(keyOf(f)));
-      const resolved = [...last.values()].filter((f) => !current.has(keyOf(f)));
+      added = [...current.values()].filter((f) => !last.has(keyOf(f)));
+      resolved = [...last.values()].filter((f) => !current.has(keyOf(f)));
       const time = new Date().toLocaleTimeString();
       if (!added.length && !resolved.length) {
         process.stdout.write(`\x1b[90m[${time}] no change in findings (${result.findings.length} total).\x1b[0m\n`);
@@ -71,6 +74,13 @@ function watch(root, opts = {}) {
     }
     last = current;
 
+    // Optional observatory hook (only present with `--dash`); never let it
+    // break the watch loop.
+    if (opts.onPass) {
+      try { opts.onPass({ result, added, resolved }); }
+      catch (e) { process.stderr.write(`observatory onPass error: ${e.message}\n`); }
+    }
+
     if (opts.report) {
       try { fs.writeFileSync(opts.report, renderMarkdown(result)); }
       catch (e) { process.stderr.write(`could not write report ${opts.report}: ${e.message}\n`); }

package/tests/observatory.test.js

@@ -0,0 +1,111 @@
+'use strict';
+/**
+ * Session Observatory adapter self-tests (zero-dependency, `node --test`).
+ * A throwaway HTTP collector stands in for the observatory server so we can
+ * assert the exact protocol events a `critic watch --dash` run emits — the
+ * mapping contract between the two packages — without importing the server.
+ */
+const test = require('node:test');
+const assert = require('node:assert');
+const http = require('node:http');
+
+const { createAdapter, healthProbe, DEFAULT_PORT } = require('../src/observatory');
+
+function startCollector() {
+  const events = [];
+  const server = http.createServer((req, res) => {
+    if (req.method === 'POST' && req.url === '/ingest') {
+      let body = '';
+      req.on('data', (c) => { body += c; });
+      req.on('end', () => {
+        try { events.push(JSON.parse(body)); } catch { /* ignore malformed */ }
+        res.writeHead(202, { 'content-type': 'application/json' });
+        res.end('{"accepted":1}');
+      });
+      return;
+    }
+    res.writeHead(404); res.end();
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: server.address().port,
+        events,
+        close: () => new Promise((r) => server.close(r)),
+      });
+    });
+  });
+}
+
+const fakeResult = (n) => ({
+  meta: { durationMs: 42 },
+  coverage: { filesScanned: n },
+  counts: { BLOCKER: 0, CRITICAL: 1, HIGH: 2, MEDIUM: 3, LOW: 4, INFO: 5 },
+  findings: [{ file: 'a.js', line: 3, ruleId: 'hardcoded-secret', severity: 'CRITICAL', title: 'secret' }],
+});
+
+test('adapter emits session.open with critic source and root', async () => {
+  const col = await startCollector();
+  const a = createAdapter({ port: col.port, root: '/tmp/proj' });
+  await a.open();
+  assert.strictEqual(col.events.length, 1);
+  const ev = col.events[0];
+  assert.strictEqual(ev.type, 'session.open');
+  assert.strictEqual(ev.source, 'critic');
+  assert.strictEqual(ev.payload.root, '/tmp/proj');
+  assert.ok(ev.sessionId.startsWith('critic-'));
+  await col.close();
+});
+
+test('pass() maps an analysis batch, the finding diff, and severity metrics', async () => {
+  const col = await startCollector();
+  const a = createAdapter({ port: col.port });
+  await a.pass({
+    result: fakeResult(12),
+    added: [{ file: 'a.js', line: 3, ruleId: 'hardcoded-secret', severity: 'CRITICAL', title: 'secret' }],
+    resolved: [{ file: 'b.js', line: 9, ruleId: 'swallowed-error', severity: 'HIGH', title: 'catch' }],
+  });
+  const types = col.events.map((e) => e.type);
+  assert.ok(types.includes('bg.batch') && types.includes('metrics'));
+
+  const analysis = col.events.find((e) => e.type === 'bg.batch' && e.payload.category === 'analysis' && !e.payload.kind);
+  assert.strictEqual(analysis.payload.filesScanned, 12);
+  assert.strictEqual(analysis.payload.durationMs, 42);
+
+  const added = col.events.find((e) => e.payload.kind === 'finding-added');
+  assert.strictEqual(added.payload.ruleId, 'hardcoded-secret');
+  assert.strictEqual(added.payload.severity, 'CRITICAL'); // bus lowercases on ingest
+  const fixed = col.events.find((e) => e.payload.kind === 'finding-fixed');
+  assert.strictEqual(fixed.payload.file, 'b.js');
+
+  const metrics = col.events.find((e) => e.type === 'metrics');
+  assert.strictEqual(metrics.metrics.critical, 1); // CRITICAL + BLOCKER
+  assert.strictEqual(metrics.metrics.high, 2);
+  assert.strictEqual(metrics.metrics.filesScanned, 12);
+  assert.ok(Number.isFinite(metrics.metrics.rssMb) && metrics.metrics.rssMb > 0, 'rss heartbeat present');
+  await col.close();
+});
+
+test('close() emits session.close with a reason', async () => {
+  const col = await startCollector();
+  const a = createAdapter({ port: col.port });
+  await a.close('sigint');
+  const ev = col.events[col.events.length - 1];
+  assert.strictEqual(ev.type, 'session.close');
+  assert.strictEqual(ev.payload.reason, 'sigint');
+  await col.close();
+});
+
+test('ingest failures never reject the producer (dashboard down)', async () => {
+  const a = createAdapter({ port: 1 }); // nothing listening
+  // Should resolve quietly rather than throw.
+  await a.open();
+  await a.pass({ result: fakeResult(1), added: [], resolved: [] });
+  assert.ok(true);
+});
+
+test('healthProbe returns null when no observatory answers', async () => {
+  const h = await healthProbe(1);
+  assert.strictEqual(h, null);
+  assert.strictEqual(DEFAULT_PORT, 4780);
+});