hermes-agent/optional-skills/creative/auteur/scripts/systemscan.mjs

#!/usr/bin/env node
/**
 * systemscan.mjs — the multi-screen gate: does this product still have ONE design system?
 *
 * slopscan reads source and catches defaults. shoot.mjs photographs one page. Neither can see the
 * failure mode of a real app: drift. Screen 1 has three button variants, screen 7 invents a fourth,
 * and nobody notices because every screen looks fine on its own. This crawls every route, reads what
 * the browser ACTUALLY PAINTED, and reports the system as built rather than as documented.
 *
 * Usage:
 *   node scripts/systemscan.mjs <url> [<url>...]
 *   node scripts/systemscan.mjs http://localhost:3000 --routes /,/settings,/billing
 *
 * Options:
 *   --routes a,b,c   paths to append to the first url (instead of listing full urls)
 *   --out DIR        output dir (default design/system)
 *   --max-variants B  variant budget: a number, or per kind — `button=5,select=1,4` (default 4)
 *   --width N        viewport width (default 1440)
 *   --no-shots       skip the component contact sheet
 *
 * Writes DIR/SYSTEM-REPORT.md (read it), DIR/system.json, DIR/components.png.
 * Exit 1 when the system is provably broken: a control type over budget, an interactive element with
 * no visible focus state, or a token used on exactly one route.
 */

import { mkdir, writeFile } from 'fs/promises';
import { resolve, join } from 'path';

const args = process.argv.slice(2);
if (!args.length || args.includes('--help')) {
  console.log(`systemscan.mjs — cross-route design-system drift gate

  node scripts/systemscan.mjs <url> [<url>...]
  node scripts/systemscan.mjs http://localhost:3000 --routes /,/settings,/billing

  --out DIR  --max-variants 4|button=5,select=1  --width 1440  --no-shots`);
  process.exit(0);
}
const get = (f, d) => { const i = args.indexOf(f); return i !== -1 ? args[i + 1] : d; };
const has = f => args.includes(f);

const outDir = resolve(get('--out', 'design/system'));
// Per-kind budgets: `--max-variants button=5,select=1` (a bare number sets the default for the rest).
// One global number meant a sheet declaring button:5 and select:1 had to pass 5, leaving every
// smaller kind unpoliced — the sheet's central promise enforced for exactly one control kind.
const rawBudget = get('--max-variants', '4');
const budget = { default: 4, byKind: {} };
for (const part of String(rawBudget).split(',').map(s => s.trim()).filter(Boolean)) {
  const m = part.match(/^([a-z]+)\s*=\s*(\d+)$/i);
  if (m) budget.byKind[m[1].toLowerCase()] = +m[2];
  else if (/^\d+$/.test(part)) budget.default = +part;
  else console.error(`[systemscan] ignoring unparseable budget "${part}" — use 4 or button=5,select=1`);
}
const budgetFor = kind => budget.byKind[kind] ?? budget.default;
const width = parseInt(get('--width', '1440'), 10) || 1440;
const shots = !has('--no-shots');

let urls = args.filter(a => /^https?:\/\//.test(a) || a.startsWith('file://'));
const routes = get('--routes', null);
if (routes && urls.length) {
  const base = urls[0].replace(/\/$/, '');
  urls = routes.split(',').map(r => base + (r.startsWith('/') ? r : '/' + r));
}
if (!urls.length) { console.error('[systemscan] no urls. Pass them, or a base url + --routes /a,/b'); process.exit(1); }

let chromium;
try { ({ chromium } = await import('playwright')); }
catch { console.error('playwright not found. Install: npm i -D playwright && npx playwright install chromium'); process.exit(2); }

// Everything below is read off getComputedStyle, i.e. the system as PAINTED. A token that exists in
// the stylesheet but is never rendered is not part of the system; a one-off inline style is.
const COLLECT = () => {
  const cs = getComputedStyle;
  const px = v => Math.round(parseFloat(v) || 0);
  const vis = el => {
    const s = cs(el);
    if (s.display === 'none' || s.visibility === 'hidden' || +s.opacity === 0) return false;
    const r = el.getBoundingClientRect();
    return r.width > 1 && r.height > 1;
  };
  const all = [...document.querySelectorAll('*')].slice(0, 6000).filter(vis);

  const controlKind = el => {
    const t = el.tagName.toLowerCase();
    const role = el.getAttribute('role');
    if (t === 'button' || role === 'button') return 'button';
    if (t === 'a' && /(^|\s)(btn|button)/i.test(el.className || '')) return 'button';
    if (t === 'a') return 'link';
    if (t === 'input') return ['checkbox', 'radio'].includes(el.type) ? 'toggle' : 'input';
    if (t === 'select') return 'select';
    if (t === 'textarea') return 'input';
    if (role === 'tab') return 'tab';
    return null;
  };

  // The signature is what a user can SEE. Two buttons with different class names but identical
  // paint are one variant; two with the same class and different paint are two.
  const sig = el => {
    const s = cs(el);
    return [
      s.backgroundColor, s.color, s.borderColor,
      `${px(s.borderTopWidth)}b`, `${px(s.borderTopLeftRadius)}r`,
      `${px(s.fontSize)}/${s.fontWeight}`,
      `${px(s.paddingTop)}x${px(s.paddingLeft)}`,
      s.boxShadow === 'none' ? 'noshadow' : 'shadow',
    ].join(' | ');
  };

  // A STATE is not a variant. A disabled secondary button paints differently from an enabled one by
  // design — that is the state matrix system.md demands, and counting it as a fifth button punishes
  // the team that built it while a system with no disabled state at all sails through. Same for a
  // control that inverts because the row it sits in is in an alert state: the component did not
  // multiply, its container changed colour underneath it. Both are counted and reported separately.
  const stateOf = el => {
    if (el.disabled || el.getAttribute('aria-disabled') === 'true') return 'disabled';
    if (el.getAttribute('aria-current') || el.getAttribute('aria-selected') === 'true') return 'current';
    for (let n = el.parentElement, hops = 0; n && hops < 4; n = n.parentElement, hops++) {
      const st = n.getAttribute?.('data-state');
      if (st && st !== 'default') return `in-${st}`;
    }
    return null;
  };

  const controls = {};
  const states = {};
  let shotId = 0;
  for (const el of all) {
    const kind = controlKind(el);
    if (!kind) continue;
    const state = stateOf(el);
    if (state) { (states[kind] ??= {})[state] = ((states[kind] ??= {})[state] || 0) + 1; continue; }
    const k = sig(el);
    (controls[kind] ??= {});
    if (!controls[kind][k]) {
      // Tag the exemplar NOW and re-select it by attribute in the screenshot pass. Handing a
      // positional index between two independent DOM walks produced tiles that showed a parent or a
      // sibling rather than the control they were captioned with — which destroys the sheet's whole
      // purpose, because a tile showing the wrong element looks different for the wrong reason.
      const tag = `ss${shotId++}`;
      el.setAttribute('data-ss-shot', tag);
      controls[kind][k] = { count: 0, sample: (el.innerText || el.value || el.type || '').trim().slice(0, 24), tag };
    }
    controls[kind][k].count++;
  }

  const tally = (map, key) => { map[key] = (map[key] || 0) + 1; };
  const colors = {}, type = {}, radii = {}, shadows = {}, space = {};
  for (const el of all) {
    const s = cs(el);
    if (s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)') tally(colors, s.backgroundColor);
    // `color` on a wrapper paints no glyph. Tallying it unfiltered made <html>'s inherited initial
    // colour the most common "colour in the product" and inflates the headline count for everyone.
    const leafText = el.children.length === 0 && (el.textContent || '').trim();
    if (s.color && leafText) tally(colors, s.color);
    if (leafText) {
      tally(type, `${px(s.fontSize)}px/${s.fontWeight}/${s.fontFamily.split(',')[0].replace(/["']/g, '')}`);
    }
    const r = px(s.borderTopLeftRadius); if (r) tally(radii, `${r}px`);
    if (s.boxShadow && s.boxShadow !== 'none') tally(shadows, s.boxShadow.slice(0, 60));
    for (const v of [s.paddingTop, s.paddingLeft, s.marginTop]) { const n = px(v); if (n) tally(space, `${n}px`); }
  }

  return {
    controls, states, colors, type, radii, shadows, space,
    focusable: all.filter(el => el.matches('a[href],button,input,select,textarea,[tabindex]:not([tabindex="-1"])')).length,
    hasDisabled: all.some(el => el.matches('[disabled],[aria-disabled="true"]')),
    title: document.title.slice(0, 60),
    landmarks: ['header', 'nav', 'main', 'footer', 'aside'].filter(t => document.querySelector(t)).join(','),
    h1: document.querySelectorAll('h1').length,
  };
};

/**
 * Focus state cannot be read from a stylesheet: a `:focus-visible` rule may exist and be overridden,
 * and `:focus-visible` itself is a heuristic that programmatic `.focus()` does not reliably trigger.
 * So drive the real thing — press Tab and look at what the browser actually paints. Tabbing also
 * skips disabled and unfocusable elements for free, which a `.focus()` loop reports as failures.
 */
const PROBE_FOCUS = async (page, maxStops = 40) => {
  const paint = () => {
    const cs = getComputedStyle;
    // Only properties that actually PAINT. outline-offset alone draws nothing, and including it
    // let an element that kills its outline still read as "focus state changed".
    const sig = el => { const s = cs(el); return `${s.outlineStyle === 'none' ? 'no-outline' : s.outline} ${s.boxShadow} ${s.borderColor} ${s.backgroundColor} ${s.color} ${s.textDecorationLine}`; };
    const els = [...document.querySelectorAll('a[href],button,input,select,textarea,summary,[tabindex]:not([tabindex="-1"])')];
    els.forEach((el, i) => el.setAttribute('data-ss-i', String(i)));
    return els.map(sig);
  };
  const unfocused = await page.evaluate(paint);
  await page.evaluate(() => (document.activeElement || document.body).blur?.());

  const bad = [], seen = new Set();
  for (let i = 0; i < maxStops; i++) {
    await page.keyboard.press('Tab');
    const stop = await page.evaluate(() => {
      const el = document.activeElement;
      if (!el || el === document.body || !el.hasAttribute?.('data-ss-i')) return null;
      const s = getComputedStyle(el);
      const r = el.getBoundingClientRect();
      return {
        i: +el.getAttribute('data-ss-i'),
        sig: `${s.outlineStyle === 'none' ? 'no-outline' : s.outline} ${s.boxShadow} ${s.borderColor} ${s.backgroundColor} ${s.color} ${s.textDecorationLine}`,
        label: el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + ' “' + (el.innerText || el.value || el.getAttribute('aria-label') || '').trim().slice(0, 20) + '”',
        offscreen: r.width < 1 || r.height < 1,
      };
    });
    if (!stop) continue;
    if (seen.has(stop.i)) break;                 // wrapped around the tab ring
    seen.add(stop.i);
    if (!stop.offscreen && unfocused[stop.i] === stop.sig) bad.push(stop.label);
  }
  return { probed: seen.size, noFocusRing: bad };
};

const browser = await chromium.launch({ headless: true });
const ctx = await browser.newContext({ viewport: { width, height: 900 } });
await mkdir(outDir, { recursive: true });

const perRoute = [];
for (const url of urls) {
  const page = await ctx.newPage();
  const errs = [];
  page.on('pageerror', e => errs.push(e.message));
  page.on('console', m => m.type() === 'error' && errs.push(m.text()));
  try {
    process.stderr.write(`[systemscan] ${url}\n`);
    const resp = await page.goto(url, { waitUntil: 'commit', timeout: 30_000 });
    const dcl = await page.waitForLoadState('domcontentloaded', { timeout: 15_000 }).then(() => true).catch(() => false);
    await page.waitForTimeout(dcl ? 2500 : 6000);
    if (!dcl) await page.evaluate(() => window.stop()).catch(() => {});
    const data = await page.evaluate(COLLECT);
    const focus = await PROBE_FOCUS(page);
    const status = resp?.status?.() ?? 0;
    // A route that renders nothing contributes nothing to the counts, so a mistyped route list made
    // the gate QUIETER instead of louder. A gate that goes green on a 404 is worse than no gate.
    const empty = !data.landmarks && !data.h1 && !data.focusable;
    perRoute.push({ url, ...data, focus, errors: errs, status, empty });
    if (status >= 400) console.error(`[systemscan] ${url} → HTTP ${status}`);
    else if (empty) console.error(`[systemscan] ${url} → rendered nothing measurable (no landmark, no h1, no focusable)`);

    if (shots) {
      // one exemplar screenshot per distinct control variant, so the report has a picture of the
      // drift and not only a count of it
      for (const [kind, variants] of Object.entries(data.controls)) {
        let i = 0;
        for (const [, v] of Object.entries(variants)) {
          if (!v.tag) continue;
          const name = `${kind}-${perRoute.length}-${i++}.png`;
          try {
            const box = await page.$(`[data-ss-shot="${v.tag}"]`);   // the element we actually measured
            if (box) { await box.scrollIntoViewIfNeeded({ timeout: 4000 }); await box.screenshot({ path: join(outDir, 'components', name), timeout: 8000 }); v.shot = `components/${name}`; }
          } catch { /* an element that will not sit still is not worth failing the run over */ }
        }
      }
    }
  } catch (e) {
    perRoute.push({ url, error: e.message.split('\n')[0] });
  } finally { await page.close(); }
}

// ---- aggregate across routes -------------------------------------------------
const ok = perRoute.filter(r => !r.error);
if (!ok.length) { console.error('[systemscan] no route could be read.'); await browser.close(); process.exit(1); }

// A document scanned twice (`/settings` and `/settings#state-error` are the same DOM) must not count
// twice — summing across URLs meant scanning MORE thoroughly hid genuine one-off variants, which is
// the opposite of what `system.md` tells you to do. Count per document, take the max, then sum.
const docOf = u => u.split('#')[0];
const docs = [...new Set(ok.map(r => docOf(r.url)))];

const mergeCount = key => {
  const m = {};
  for (const r of ok) for (const [k, n] of Object.entries(r[key] || {})) {
    (m[k] ??= { perDoc: {} });
    const d = docOf(r.url);
    m[k].perDoc[d] = Math.max(m[k].perDoc[d] || 0, n);
  }
  return Object.entries(m)
    .map(([k, v]) => ({ k, total: Object.values(v.perDoc).reduce((a, b) => a + b, 0), routes: Object.keys(v.perDoc).length }))
    .sort((a, b) => b.total - a.total);
};

const controlVariants = {};
for (const r of ok) for (const [kind, vars] of Object.entries(r.controls || {})) {
  (controlVariants[kind] ??= {});
  for (const [sig, v] of Object.entries(vars)) {
    const slot = (controlVariants[kind][sig] ??= { perDoc: {}, sample: v.sample, shot: v.shot });
    const d = docOf(r.url);
    slot.perDoc[d] = Math.max(slot.perDoc[d] || 0, v.count);
    slot.shot ??= v.shot;
  }
}
for (const vars of Object.values(controlVariants)) for (const v of Object.values(vars)) {
  v.count = Object.values(v.perDoc).reduce((a, b) => a + b, 0);
  v.routes = new Set(Object.keys(v.perDoc));
}

// States, gathered the same way but never counted against the variant budget.
const controlStates = {};
for (const r of ok) for (const [kind, st] of Object.entries(r.states || {}))
  for (const [name, n] of Object.entries(st)) {
    ((controlStates[kind] ??= {})[name] ??= 0);
    controlStates[kind][name] += n;
  }

const fails = [], warns = [];
for (const [kind, vars] of Object.entries(controlVariants)) {
  const n = Object.keys(vars).length, b = budgetFor(kind);
  if (n > b) fails.push(`${kind}: ${n} distinct rendered variants (budget ${b}). A variant nobody can name is drift.`);
  for (const [sig, v] of Object.entries(vars)) {
    if (v.count === 1 && n > 1) warns.push(`${kind} variant used exactly once ("${v.sample}") — either promote it into the system or delete it: ${sig}`);
  }
}
const blank = perRoute.filter(r => !r.error && (r.status >= 400 || r.empty));
if (blank.length) fails.push(`${blank.length} route(s) rendered nothing measurable or returned an error status — a gate that goes green on a 404 is worse than no gate: ${blank.map(r => `${r.url}${r.status >= 400 ? ` (HTTP ${r.status})` : ''}`).join(', ')}`);
const noFocus = ok.flatMap(r => (r.focus?.noFocusRing || []).map(t => `${r.url} → ${t}`));
if (noFocus.length) fails.push(`${noFocus.length} interactive element(s) paint identically when focused — keyboard users cannot see where they are`);

const colors = mergeCount('colors'), type = mergeCount('type'), radii = mergeCount('radii'), shadows = mergeCount('shadows');
if (docs.length > 1) {
  for (const [label, list] of [['colour', colors], ['type step', type], ['radius', radii]]) {
    const singles = list.filter(x => x.routes === 1 && x.total >= 3);
    if (singles.length) warns.push(`${singles.length} ${label}(s) appear on exactly one route and nowhere else — that is where the system is splitting: ${singles.slice(0, 4).map(s => s.k).join(' · ')}`);
  }
}
if (type.length > 12) warns.push(`${type.length} distinct type steps across the product — a scale nobody can hold in their head is not a scale`);
if (!ok.some(r => r.hasDisabled)) warns.push('no disabled control appeared on any route — the disabled state is probably undesigned, not absent');

// ---- component contact sheet -------------------------------------------------
let sheet = null;
const tiles = Object.entries(controlVariants).flatMap(([kind, vars]) =>
  Object.entries(vars).filter(([, v]) => v.shot).map(([, v], i) => ({ kind, i, ...v })));
if (shots && tiles.length) {
  const html = `<!doctype html><meta charset="utf-8"><style>
    body{margin:0;background:#141414;font:12px/1.3 ui-monospace,monospace;color:#ddd}
    .g{display:grid;grid-template-columns:repeat(4,1fr);gap:12px;padding:12px}
    figure{margin:0;background:#1e1e1e;border-radius:4px;overflow:hidden;padding:10px}
    img{display:block;max-width:100%;margin:0 auto 8px}
    b{color:#fff}
  </style><div class=g>${tiles.map(t =>
    `<figure><img src="${t.shot}"><figcaption><b>${t.kind}</b> ×${t.count} · ${t.routes.size} route(s)</figcaption></figure>`).join('')}</div>`;
  const f = join(outDir, '_components.html');
  await writeFile(f, html, 'utf8');
  const p = await ctx.newPage();
  await p.setViewportSize({ width: 1200, height: 900 });
  await p.goto('file:///' + f.replace(/\\/g, '/'), { waitUntil: 'load', timeout: 20_000 }).catch(() => {});
  await p.waitForTimeout(900);
  // shoot the grid, not the viewport — a fullPage shot of a two-row sheet is mostly empty canvas
  const grid = await p.$('.g');
  await (grid || p).screenshot({ path: join(outDir, 'components.png') });
  await p.close();
  sheet = 'components.png';
}
await browser.close();

// ---- report ------------------------------------------------------------------
const L = [];
L.push(`# SYSTEM-REPORT — ${ok.length} route(s), ${new Date().toISOString().slice(0, 10)}`);
L.push('');
L.push('The system as **painted**, not as documented. A token in the stylesheet that never renders is');
L.push('not part of the system; a one-off inline style is. Read this against `design/DESIGN.md` — every');
L.push('number below that DESIGN.md does not account for is drift.');
L.push('');
if (sheet) L.push(`**Look at \`${sheet}\`** — one tile per distinct rendered control variant. Two tiles that look the same to you but appear separately are the drift.\n`);

L.push('## Controls');
L.push('');
L.push('| kind | distinct variants | budget | total instances |');
L.push('|---|---|---|---|');
for (const [kind, vars] of Object.entries(controlVariants)) {
  const n = Object.keys(vars).length;
  L.push(`| ${kind} | **${n}** | ${budgetFor(kind)} | ${Object.values(vars).reduce((s, v) => s + v.count, 0)} |`);
}
L.push('');
for (const [kind, vars] of Object.entries(controlVariants)) {
  L.push(`### ${kind}`);
  for (const [sig, v] of Object.entries(vars)) L.push(`- ×${v.count} on ${v.routes.size} route(s) — "${v.sample}" — \`${sig}\``);
  if (controlStates[kind]) {
    const st = Object.entries(controlStates[kind]).map(([n, c]) => `${n} ×${c}`).join(' · ');
    L.push(`- *states (not counted as variants): ${st}*`);
  }
  L.push('');
}
if (Object.keys(controlStates).length) {
  L.push('> States — disabled, current, and controls inside a row carrying a `data-state` — are');
  L.push('> excluded from the variant budget. A disabled button paints differently on purpose; a');
  L.push('> product that has no disabled state at all should not score better than one that does.');
  L.push('');
}

L.push('## Tokens as rendered');
L.push('');
for (const [label, list] of [['Colour', colors], ['Type step', type], ['Radius', radii], ['Shadow', shadows]]) {
  L.push(`**${label}** (${list.length} distinct)`);
  for (const x of list.slice(0, 10)) L.push(`- \`${x.k}\` — ${x.total}× on ${x.routes} route(s)`);
  if (list.length > 10) L.push(`- …and ${list.length - 10} more`);
  L.push('');
}

L.push('## Per route');
L.push('');
L.push('| route | landmarks | h1 | focusable | console errors |');
L.push('|---|---|---|---|---|');
for (const r of ok) L.push(`| ${r.url} | ${r.landmarks || '—'} | ${r.h1} | ${r.focusable} | ${r.errors.length} |`);
for (const r of perRoute.filter(r => r.error)) L.push(`| ${r.url} | **unreachable** — ${r.error} | | | |`);
L.push('');

if (fails.length) { L.push('## FAIL'); fails.forEach(f => L.push(`- ${f}`)); L.push(''); }
if (noFocus.length) { L.push('### Elements with no visible focus state'); noFocus.slice(0, 20).forEach(t => L.push(`- ${t}`)); L.push(''); }
if (warns.length) { L.push('## WARN'); warns.forEach(w => L.push(`- ${w}`)); L.push(''); }
if (!fails.length && !warns.length) L.push('No drift detected. The product renders one system.\n');

await writeFile(join(outDir, 'SYSTEM-REPORT.md'), L.join('\n'), 'utf8');
await writeFile(join(outDir, 'system.json'), JSON.stringify({
  routes: perRoute.map(r => ({ ...r, controls: undefined })),
  controls: Object.fromEntries(Object.entries(controlVariants).map(([k, v]) =>
    [k, Object.entries(v).map(([sig, x]) => ({ sig, count: x.count, routes: [...x.routes], sample: x.sample }))])),
  colors, type, radii, shadows, fails, warns,
}, null, 2), 'utf8');

console.log(`\n=== systemscan ===`);
console.log(`routes  : ${ok.length}/${perRoute.length} read (${docs.length} distinct document(s))`);
console.log(`controls: ${Object.entries(controlVariants).map(([k, v]) => `${k} ${Object.keys(v).length}`).join(' · ') || '—'}`);
console.log(`tokens  : ${colors.length} colours · ${type.length} type steps · ${radii.length} radii · ${shadows.length} shadows`);
console.log(`report  : ${join(outDir, 'SYSTEM-REPORT.md')}${sheet ? `\nsheet   : ${join(outDir, sheet)}` : ''}`);
for (const f of fails) console.log(`FAIL ${f}`);
for (const w of warns.slice(0, 5)) console.log(`WARN ${w}`);
process.exit(fails.length ? 1 : 0);