fullstack-critic 1.0.0 → 1.0.3

package/src/rules.js

@@ -177,6 +177,121 @@ const LINE_RULES = [
     fix: 'Add keyset/cursor pagination or an explicit LIMIT.',
     verify: 'endpoint returns a bounded page size.',
   },
+
+  // ---- API design ---------------------------------------------------------
+  {
+    id: 'api-numbered-endpoints', severity: 'INFO', category: 'add', dimension: 'API design',
+    title: 'Verb-in-URL endpoint (non-RESTful routing)',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.rb', '.php', '.java', '.go'],
+    test: /\.(get|post|put|patch|delete|route)\s*\(\s*["'][^"']*\/(create|update|delete|get|fetch|list|add|remove|edit)[A-Za-z]*/i,
+    problem: 'Endpoint path embeds the action verb instead of relying on the HTTP method.',
+    impact: 'Inconsistent contract; harder to version and document.',
+    fix: 'Use method + noun (POST /orders, PATCH /orders/:id, DELETE /orders/:id).',
+    verify: 'route list contains no verb segments.',
+  },
+  {
+    id: 'fetch-unhandled', severity: 'MEDIUM', category: 'fix', dimension: 'API design',
+    title: 'Network call without error handling (.ok/.catch missing)',
+    ext: ['.js', '.ts', '.jsx', '.tsx', '.mjs'],
+    test: /\bfetch\s*\(/,
+    skipIf: (line) => /\.ok\b|\.catch\s*\(|try\s*\{|await\s+safe|\bthen\s*\([^)]*\)\s*\.catch|critic-ignore/.test(line),
+    problem: 'fetch resolves on 4xx/5xx; without .ok or .catch failures are silently ignored.',
+    impact: 'Failed requests render empty/broken UIs instead of error states.',
+    fix: 'Check res.ok and wrap in try/catch, or route through one client that does.',
+    verify: 'a 500 response surfaces the error path in the UI/logs.',
+  },
+
+  // ---- Validation & routing (security-adjacent) ---------------------------
+  {
+    id: 'open-redirect', severity: 'MEDIUM', category: 'fix', dimension: 'Security',
+    title: 'Redirect target built from request input',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.rb', '.php'],
+    test: /redirect\s*\([^)]*(req\.(query|params|body)|location\.search|URLSearchParams|get\s*\(\s*["']next)/,
+    problem: 'A user-controlled value decides where the browser is sent.',
+    impact: 'Open redirect — phishing via a trusted domain.',
+    fix: 'Validate against an allowlist of internal paths; reject absolute URLs.',
+    verify: 'redirect to an external host is rejected.',
+  },
+  {
+    id: 'form-no-validation', severity: 'MEDIUM', category: 'fix', dimension: 'Correctness',
+    title: 'Form submit without validation',
+    ext: ['.jsx', '.tsx', '.js', '.ts', '.html', '.vue', '.svelte'],
+    test: /<form\b[^>]*\bonsubmit\s*=/i,
+    skipIf: (line) => /validate|isValid|\.checkValidity|zod|yup|joi|required/i.test(line),
+    problem: 'Submit path accepts whatever the fields contain.',
+    impact: 'Malformed or hostile data reaches the API; server must never be the only gate.',
+    fix: 'Validate on submit and surface field errors (or a schema library).',
+    verify: 'empty/invalid submit is blocked with messages.',
+  },
+  {
+    id: 'novalidate-form', severity: 'LOW', category: 'fix', dimension: 'Correctness',
+    title: 'Form disables browser validation',
+    test: /<form[^>]*novalidate/i,
+    skipIf: (line) => /customValidity|custom-validation|validateForm/i.test(line),
+    problem: 'novalidate turns off built-in required/type checks.',
+    impact: 'Users submit invalid values unless a custom validator fully replaces them.',
+    fix: 'Remove novalidate, or guarantee an equivalent custom validation path.',
+    verify: 'invalid field blocks submit.',
+  },
+
+  // ---- Frontend & a11y ------------------------------------------------------
+  {
+    id: 'a11y-clickable-div', severity: 'MEDIUM', category: 'fix', dimension: 'Frontend',
+    title: 'Click handler on a non-interactive element',
+    ext: ['.jsx', '.tsx', '.html', '.vue', '.svelte'],
+    test: /<(div|span|img|li|p)\b[^>]*\son(Click|KeyPress|KeyDown)\s*=/,
+    skipIf: (line) => /role\s*=|tabIndex/i.test(line),
+    problem: 'Interactive behaviour lives on an element keyboards and screen readers skip.',
+    impact: 'Primary actions unreachable for keyboard/AT users.',
+    fix: 'Use <button> or add role="button" + tabIndex + key handling.',
+    verify: 'the action is triggerable by Tab + Enter.',
+  },
+  {
+    id: 'img-missing-alt', severity: 'LOW', category: 'fix', dimension: 'Frontend',
+    title: 'Image without alt text',
+    ext: ['.jsx', '.tsx', '.html', '.vue', '.svelte'],
+    test: /<img\b(?![^>]*alt\s*=)[^>]*src=/i,
+    problem: '<img> lacks an alt attribute.',
+    impact: 'Screen readers announce nothing; Lighthouse a11y failures.',
+    fix: 'Add meaningful alt, or alt="" for decorative images.',
+    verify: 'axe/Lighthouse a11y passes the images rule.',
+  },
+  {
+    id: 'plain-img-next', severity: 'LOW', category: 'optimize', dimension: 'Frontend',
+    title: 'Plain <img> in Next.js (next/image preferred)',
+    ext: ['.jsx', '.tsx'],
+    test: /<img\s/,
+    skipIf: (line) => /next\/image|<Image\b/i.test(line),
+    problem: 'Hand-written <img> skips automatic resizing, lazy-loading and format negotiation.',
+    impact: 'Wasted bytes and worse LCP — the metric that decides search rank.',
+    fix: 'Use next/image with explicit width/height.',
+    verify: 'Lighthouse image credits improve.',
+  },
+  {
+    id: 'default-props-function', severity: 'LOW', category: 'optimize', dimension: 'Frontend',
+    title: 'defaultProps on function components (deprecated)',
+    ext: ['.jsx', '.tsx'],
+    test: /\.defaultProps\s*=/,
+    problem: 'React removed defaultProps support for function components.',
+    impact: 'Defaults silently stop applying on React 19+.',
+    fix: 'Use ES parameter defaults.',
+    verify: 'no .defaultProps assignments remain.',
+  },
+
+  // ---- Backend on async runtimes -------------------------------------------
+  {
+    id: 'sync-io-in-handler', severity: 'MEDIUM', category: 'fix', dimension: 'Backend',
+    title: 'Synchronous fs call inside a request handler',
+    ext: ['.js', '.ts', '.mjs', '.cjs'],
+    test: /fs\.(readFileSync|writeFileSync|appendFileSync|readdirSync|existsSync|statSync)\s*\(/,
+    // Only flag inside request-handler surfaces (routes/api/serverless handlers),
+    // where the block stalls every other in-flight request; scripts/CLI use sync fs freely.
+    skipIf: (line, ctx) => !(ctx && /(^|[\\/])(routes?|api|controllers?|handlers?|serverless|\.\/(pages|app)\/api|[\\/]pages\/api[\\/])/i.test(ctx.rel || '')),
+    problem: 'Blocking fs freezes the event loop for every other in-flight request.',
+    impact: 'Tail latency spikes and throughput collapse under load.',
+    fix: 'Use fs.promises / the async API, or preload at startup.',
+    verify: 'load test shows unchanged p95 while the file path is hit.',
+  },
 ];
 
 module.exports = { LINE_RULES, PLACEHOLDER };

package/src/sysinfo.js

@@ -0,0 +1,395 @@
+'use strict';
+/**
+ * Zero-dependency (Node core only) OS-level telemetry for the built-in critic
+ * dashboard. It answers one question the report never could: "what is actually
+ * running on this machine right now, app-by-app, and when will the critic finish?"
+ *
+ * Design rules (same discipline as the rest of the tool):
+ *   - Never crash the workflow. Every external probe is wrapped; a platform or
+ *     tool we cannot read degrades to an empty/partial snapshot, not an error.
+ *   - Cross-platform: Windows (Get-Process), macOS/Linux (ps). CPU% per process
+ *     uses deltas between samples so the numbers are real, not lifetime averages.
+ *   - "Project / app wise" grouping: processes are folded into apps and tagged
+ *     with a coarse category (project, runtime, browser, terminal, database,
+ *     system, other) so the live-task table is structured, not a raw dump.
+ *   - The critic's OWN process is highlighted — that is the concrete "live task"
+ *     this app is running — with its CPU/RSS and a scan-rate-based ETA.
+ */
+const os = require('os');
+const { spawnSync, exec } = require('child_process');
+
+const IS_WIN = process.platform === 'win32';
+
+// The machine-wide per-process probe is expensive on Windows (PowerShell cold
+// start ~3s) — it must therefore run ASYNC + throttled in the live dashboard and
+// is skipped entirely for one-shot `review`. System/self CPU, by contrast, is
+// read from Node core and is always instant.
+
+/* ------------------------------- primitives ------------------------------- */
+
+// Block the thread for `ms` without busy-spinning (used only for the one-shot
+// static snapshot, where there is no sample history to diff CPU against).
+function sleepMs(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch { /* SharedArrayBuffer disabled → just skip the wait */ }
+}
+
+function clamp(n, lo, hi) { return Math.max(lo, Math.min(hi, n)); }
+function round(n, d) { const m = Math.pow(10, d || 0); return Math.round((Number(n) || 0) * m) / m; }
+
+// Aggregate instantaneous system CPU% from two os.cpus() readings.
+function cpuPctFrom(prev, cur) {
+  if (!prev || !cur || prev.length !== cur.length) return null;
+  let prevIdle = 0, prevTotal = 0, curIdle = 0, curTotal = 0;
+  for (let i = 0; i < cur.length; i++) {
+    const p = prev[i].times, c = cur[i].times;
+    prevIdle += p.idle; curIdle += c.idle;
+    prevTotal += p.user + p.nice + p.sys + p.idle + p.irq;
+    curTotal += c.user + c.nice + c.sys + c.idle + c.irq;
+  }
+  const dt = curTotal - prevTotal;
+  if (dt <= 0) return null;
+  return clamp((1 - (curIdle - prevIdle) / dt) * 100, 0, 100);
+}
+
+function memInfo() {
+  const total = os.totalmem();
+  const free = os.freemem();
+  const used = Math.max(0, total - free);
+  return { memTotal: total, memFree: free, memUsed: used, memPct: total ? round((used / total) * 100, 1) : 0 };
+}
+
+function systemStatic() {
+  const cpus = os.cpus();
+  const load = os.loadavg ? os.loadavg() : [0, 0, 0];
+  return {
+    cores: cpus.length,
+    cpuModel: (cpus[0] && cpus[0].model ? cpus[0].model : '').trim(),
+    load1: round(load[0] || 0, 2),
+    uptimeSec: Math.round(os.uptime() || 0),
+    hostname: os.hostname(),
+    platform: process.platform,
+    arch: os.arch(),
+    nodeVersion: process.version,
+    pid: process.pid,
+  };
+}
+
+/* ------------------------------ process list ------------------------------ */
+
+// Coarse, honest categorisation so the live-task view is structured.
+const CAT_RULES = [
+  ['project', /fullstack-critic|critic[\\/]|bin\/fullstack/i],
+  ['runtime', /^(node|deno|bun|python|python3|java|ruby|php|dotnet|go|rustc|cargo|perl|jl)\b/i],
+  ['package', /^(npm|pnpm|yarn|npx|pip|pipenv|poetry|composer|bundle|gem|nuget)\b/i],
+  ['browser', /(chrome|chromium|msedge|edge|firefox|safari|brave|opera|vivaldi)/i],
+  ['terminal', /(powershell|pwsh|\bcmd\b|conhost|wt\b|terminal|iterm|\bbash\b|\bzsh\b|\bfish\b|codium)/i],
+  ['editor', /(code|cursor|idea|webstorm|pycharm|goland|clion|rubymine|phpstorm|sublime|atom|nvim|\bvim\b|emacs|eclipse|devenv)/i],
+  ['database', /(postgres|psql|mysqld|\bmariadb\b|mongod|redis|sqlite|clickhouse|influx|etcd)/i],
+  ['container', /(docker|com\.docker|kubelet|kubectl|containerd|podman|orbstack)/i],
+  ['vcs', /\bgit\b|git-lfs/i],
+  ['system', /(svchost|csrss|services|lsass|wininit|winlogon|dwm|explorer|ntoskrnl|system\b|\bsmss\b|\bwin32\b|taskhostw|\bsearch\b|fontdrvhost|memory\.diagnostic|registry|wmiprvse)/i],
+];
+function classify(name) {
+  const n = String(name || '');
+  for (const [cat, re] of CAT_RULES) if (re.test(n)) return cat;
+  return 'other';
+}
+
+function execCapture(cmd, args, timeoutMs) {
+  try {
+    const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: timeoutMs || 1500, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+    if (r.error || r.status == null) return null;
+    return r.stdout || '';
+  } catch { return null; }
+}
+
+// Return raw process rows: { pid, name, memBytes, cpuSec, path }. cpuSec is total
+// CPU-seconds consumed (POSIX returns an instantaneous % which we pass through as
+// cpuPctRaw instead). Callers diff successive samples to get a real CPU%.
+function processes() {
+  return IS_WIN ? winProcesses() : posixProcesses();
+}
+
+// Non-blocking process probe. cb(err, rows) — rows is [] on any failure so the
+// live dashboard simply keeps showing the last successful app table.
+function processesAsync(cb) {
+  if (IS_WIN) return runAsync('powershell.exe', WIN_ARGS, parseWinJson, cb);
+  return runAsync('ps', ['-axo', 'pid=,pcpu=,rss=,comm='], parsePosixText, cb);
+}
+
+const WIN_SCRIPT =
+  '$ErrorActionPreference="SilentlyContinue";' +
+  'Get-Process | ForEach-Object {' +
+  '$cpu=0; try{$cpu=$_.CPU}catch{$cpu=0}' +
+  '$ws=0; try{$ws=$_.WS}catch{$ws=0}' +
+  '[pscustomobject]@{Id=$_.Id;Name=$_.ProcessName;WS=$ws;CPU=$cpu}' +
+  '} | ConvertTo-Json -Compress';
+const WIN_ARGS = ['-NoProfile', '-NonInteractive', '-Command', WIN_SCRIPT];
+
+function runAsync(cmd, args, parser, cb) {
+  const { spawn } = require('child_process');
+  let child;
+  try { child = spawn(cmd, args, { windowsHide: true }); } catch (e) { return cb(e, []); }
+  let out = '';
+  let done = false;
+  const finish = (err) => { if (done) return; done = true; clearTimeout(timer); cb(err, err ? [] : parseSafe(parser, out)); };
+  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } finish(new Error('probe-timeout')); }, 15000);
+  child.stdout.on('data', (d) => { out += d; });
+  child.on('error', (e) => finish(e));
+  child.on('close', () => finish(null));
+}
+function parseSafe(parser, out) { try { return parser(out) || []; } catch { return []; } }
+
+function parseWinJson(stdout) {
+  if (!stdout) return [];
+  let rows; try { rows = JSON.parse(stdout); } catch { return []; }
+  if (!Array.isArray(rows)) rows = [rows];
+  return rows.filter((r) => r && r.Id != null).map((r) => ({
+    pid: Number(r.Id), name: String(r.Name || '?'),
+    memBytes: Number(r.WS) || 0, cpuSec: Number(r.CPU) || 0, path: '',
+  }));
+}
+function parsePosixText(stdout) { return parsePsText(stdout); }
+
+// Shared ps -text parser (POSIX). pcpu is an instantaneous-ish %; rss is KB.
+function parsePsText(stdout) {
+  if (!stdout) return [];
+  const out = [];
+  for (const line of stdout.split('\n')) {
+    const m = line.match(/^\s*(\d+)\s+([\d.]+)\s+(\d+)\s+(.*)$/);
+    if (!m) continue;
+    out.push({
+      pid: Number(m[1]),
+      name: String(m[4]).trim().split(/[\\/]/).pop(),
+      memBytes: (Number(m[3]) || 0) * 1024,
+      cpuSec: 0,
+      cpuPctRaw: Number(m[2]) || 0,
+      path: '',
+    });
+  }
+  return out;
+}
+
+// Synchronous variants — used only by tests and anywhere a blocking read is fine.
+function winProcesses() {
+  const stdout = execCapture('powershell.exe', WIN_ARGS, 6000);
+  return parseWinJson(stdout);
+}
+function posixProcesses() {
+  const stdout = execCapture('ps', ['-axo', 'pid=,pcpu=,rss=,comm='], 1500);
+  return parsePsText(stdout);
+}
+
+// Fold processes into apps and compute a real CPU% from the previous sample.
+// prevByPid: Map<pid,{cpuSec,ts}> | null.  nowMs: current epoch ms.
+function toAppRows(procs, prevByPid, nowMs, cores) {
+  const apps = new Map();
+  const updated = new Map();
+  for (const p of procs) {
+    let cpuPct = 0;
+    if (typeof p.cpuPctRaw === 'number') {
+      cpuPct = clamp(p.cpuPctRaw, 0, (cores || 1) * 100);
+    } else if (prevByPid) {
+      const prev = prevByPid.get(p.pid);
+      if (prev && nowMs > prev.ts) {
+        const dtSec = (nowMs - prev.ts) / 1000;
+        cpuPct = clamp(((p.cpuSec - prev.cpuSec) / dtSec) * 100, 0, (cores || 1) * 100);
+      }
+    }
+    updated.set(p.pid, { cpuSec: p.cpuSec, ts: nowMs });
+
+    const key = (p.name || '?').toLowerCase();
+    let a = apps.get(key);
+    if (!a) { a = { app: p.name || '?', category: classify(p.name), count: 0, cpuPct: 0, memBytes: 0, pids: [] }; apps.set(key, a); }
+    a.count++;
+    a.cpuPct += cpuPct;
+    a.memBytes += p.memBytes;
+    if (a.pids.length < 8) a.pids.push(p.pid);
+    if (!a.category || a.category === 'other') a.category = classify(p.name);
+  }
+  const rows = [...apps.values()].map((a) => ({ ...a, cpuPct: round(a.cpuPct, 1), memBytes: a.memBytes }));
+  return { rows, prevByPid: updated };
+}
+
+function byCategory(rows) {
+  const out = {};
+  for (const r of rows) {
+    const c = (out[r.category] || (out[r.category] = { count: 0, apps: 0, cpuPct: 0, memBytes: 0 }));
+    c.apps += 1; c.count += r.count; c.cpuPct += r.cpuPct; c.memBytes += r.memBytes;
+  }
+  for (const k of Object.keys(out)) { out[k].cpuPct = round(out[k].cpuPct, 1); }
+  return out;
+}
+
+/* ------------------------------ self (critic) ----------------------------- */
+
+// CPU% of THIS critic process between samples, plus its resident memory.
+function selfUsage(prev) {
+  const cpu = process.cpuUsage(prev && prev.cpuUsage); // microseconds since last
+  const wallMs = prev ? Date.now() - prev.ts : 0;
+  const cpuUs = (cpu.user || 0) + (cpu.system || 0);
+  const cpuPct = wallMs > 0 ? clamp((cpuUs / 1000 / (wallMs / 1000)) * 100, 0, (os.cpus().length || 1) * 100) : 0;
+  const mem = process.memoryUsage();
+  return {
+    cpuPct: round(cpuPct, 1),
+    rss: Math.round(mem.rss || 0),
+    heapUsed: Math.round(mem.heapUsed || 0),
+    rssMb: round((mem.rss || 0) / 1048576, 1),
+    next: { cpuUsage: process.cpuUsage(), ts: Date.now() },
+  };
+}
+
+/* -------------------------------- estimate -------------------------------- */
+
+/**
+ * Expected-completion math for the critic's own scan. Fully pure & testable:
+ * it turns the analyzer's measured throughput and pass history into an honest
+ * ETA — and refuses to overclaim when there is not enough signal yet.
+ */
+function computeEstimate(input) {
+  const o = input || {};
+  const now = o.now || Date.now();
+  const cores = o.cores || os.cpus().length || 1;
+  const passNo = Number(o.passNo) || 0;
+  const durationsMs = Array.isArray(o.durationsMs) ? o.durationsMs.filter((x) => x > 0) : [];
+  const lastPassMs = Number(o.lastPassMs) || (durationsMs.length ? durationsMs[durationsMs.length - 1] : 0);
+  const avgPassMs = durationsMs.length ? Math.round(durationsMs.reduce((s, x) => s + x, 0) / durationsMs.length) : lastPassMs;
+  const filesTotal = Number(o.filesTotal) || 0;
+  const totalLines = Number(o.totalLines) || 0;
+
+  const scanRateFps = lastPassMs > 0 ? round(filesTotal / (lastPassMs / 1000), 1) : 0;
+  const linesPerSec = lastPassMs > 0 ? round(totalLines / (lastPassMs / 1000), 0) : 0;
+  const timeOnTaskSec = o.startedAt ? round((now - o.startedAt) / 1000, 1) : 0;
+
+  // Under heavy system load the next pass will stretch; scale the estimate.
+  const loadFactor = o.cpuPct != null ? round(1 + Math.max(0, (o.cpuPct - 60) / 100), 2) : 1;
+  const estPassMs = avgPassMs ? Math.round(avgPassMs * loadFactor) : 0;
+
+  let etaLabel;
+  let complete = true;
+  if (o.mode === 'watch') {
+    const nextSec = round((estPassMs / 1000) + (Number(o.debounceMs) || 400) / 1000, 1);
+    etaLabel = `each re-scan completes in ~${nextSec}s after a change`;
+    complete = false; // watch never "finishes"; it waits for the next edit
+  } else if (estPassMs > 0) {
+    etaLabel = `full review completed in ~${round(estPassMs / 1000, 1)}s`;
+  } else {
+    etaLabel = 'measuring throughput…';
+  }
+
+  return {
+    mode: o.mode || 'review',
+    passNo, cores, filesTotal, totalLines,
+    lastPassMs, avgPassMs, estPassMs,
+    scanRateFps, linesPerSec, loadFactor,
+    timeOnTaskSec, serverNow: now, startedAt: o.startedAt || null,
+    etaLabel, complete,
+  };
+}
+
+/* -------------------------------- monitor --------------------------------- */
+
+// Stateful sampler used by the live dashboard: keeps system-CPU, per-process-CPU
+// and critic-process deltas between calls, plus a rolling history for the charts.
+function createMonitor(root) {
+  const state = {
+    root: root || process.cwd(),
+    prevCpus: os.cpus(),
+    prevTs: Date.now(),
+    prevByPid: null,
+    prevSelf: { cpuUsage: process.cpuUsage(), ts: Date.now() },
+    history: [],
+    maxHistory: 60,
+    lastRows: [],
+    lastProcs: 0,
+    lastErr: null,
+  };
+
+  // Cheap, always-current reading: system CPU% (Node-core delta), memory, and
+  // this critic process. Safe to call on every poll / history tick — never blocks.
+  function sample() {
+    const now = Date.now();
+    const sysStatic = systemStatic();
+    let cpuPct = cpuPctFrom(state.prevCpus, os.cpus());
+    if (cpuPct == null) cpuPct = state.history.length ? state.history[state.history.length - 1].cpu : 0;
+    state.prevCpus = os.cpus();
+    state.prevTs = now;
+    const mem = memInfo();
+    const self = selfUsage(state.prevSelf);
+    state.prevSelf = self.next;
+    delete self.next;
+    state.history.push({ t: now, cpu: round(cpuPct, 1), mem: mem.memPct, procCount: state.lastProcs, selfCpu: self.cpuPct });
+    if (state.history.length > state.maxHistory) state.history.shift();
+    return buildSnapshot(sysStatic, cpuPct, mem, self, now);
+  }
+
+  function buildSnapshot(sysStatic, cpuPct, mem, self, now) {
+    const byCpu = state.lastRows.slice().sort((a, b) => b.cpuPct - a.cpuPct || b.memBytes - a.memBytes);
+    const topMem = state.lastRows.slice().sort((a, b) => b.memBytes - a.memBytes).slice(0, 8);
+    return {
+      ts: now,
+      system: { ...sysStatic, cpuPct: round(cpuPct, 1), ...mem },
+      self,
+      apps: byCpu.slice(0, 24),
+      totals: {
+        procCount: state.lastProcs, appCount: state.lastRows.length, topMem,
+        byCategory: byCategory(state.lastRows), refreshing: !!state.refreshing,
+      },
+      history: state.history.slice(),
+      error: state.lastErr || null,
+    };
+  }
+
+  // Expensive: the machine-wide per-process table. Runs async so it never blocks
+  // the HTTP server or the watch loop; cb() fires once the rows are cached.
+  function refresh(cb) {
+    if (state.refreshing) { if (cb) cb(null); return; }
+    state.refreshing = true;
+    processesAsync((err, procs) => {
+      state.refreshing = false;
+      const list = Array.isArray(procs) ? procs : [];
+      if (err) { state.lastErr = err.message; if (cb) cb(err); return; }
+      const now = Date.now();
+      const folded = toAppRows(list, state.prevByPid, now, systemStatic().cores);
+      state.prevByPid = folded.prevByPid;
+      state.lastRows = folded.rows;
+      state.lastProcs = list.length;
+      state.lastErr = null;
+      if (cb) cb(null);
+    });
+  }
+
+  return { sample, refresh, get historyLen() { return state.history.length; } };
+}
+
+// One-shot snapshot for a single (non-looping) `critic review`. Only the cheap,
+// always-available readings (system CPU over a 60ms window, memory, this
+// process). The machine-wide per-app table is deliberately omitted here because
+// it needs the slow async probe — that lives in the live `watch` dashboard.
+function snapshotOnce(root) {
+  const p1 = os.cpus();
+  const self1 = { cpuUsage: process.cpuUsage(), ts: Date.now() };
+  sleepMs(60);
+  const cpuPct = cpuPctFrom(p1, os.cpus()) || 0;
+  const selfRaw = selfUsage(self1);
+  const self = { cpuPct: selfRaw.cpuPct, rss: selfRaw.rss, heapUsed: selfRaw.heapUsed, rssMb: selfRaw.rssMb };
+  const mem = memInfo();
+  const now = Date.now();
+  return {
+    ts: now,
+    system: { ...systemStatic(), cpuPct: round(cpuPct, 1), ...mem },
+    self,
+    apps: [],
+    totals: { procCount: 0, appCount: 0, topMem: [], byCategory: {}, refreshing: false },
+    history: [{ t: now, cpu: round(cpuPct, 1), mem: mem.memPct, procCount: 0, selfCpu: self.cpuPct }],
+    live: false,
+    error: null,
+  };
+}
+
+module.exports = {
+  createMonitor, snapshotOnce, processes, processesAsync, toAppRows, byCategory, classify,
+  selfUsage, computeEstimate, cpuPctFrom, systemStatic, memInfo, sleepMs, IS_WIN,
+};