@deeeed/metamask-harness 0.28.0 → 0.29.0

package/scripts/site-contrast.mjs

@@ -0,0 +1,538 @@
+#!/usr/bin/env node
+/*
+ * Browser acceptance and WCAG contrast gate for site/.
+ *
+ * Serves site/ locally, drives headless Chrome over CDP, and measures every
+ * element that renders its own text: the computed colour composited against the
+ * effective background, which is itself composited through transparent
+ * ancestors down to the page base. Collapsed disclosures are force-opened first
+ * so hidden text is measured too.
+ *
+ * Exits non-zero if navigation, copy, filtering, progress persistence, or
+ * contrast fails.
+ *
+ *   node scripts/site-contrast.mjs
+ *   node scripts/site-contrast.mjs --threshold 7      # AAA
+ *   node scripts/site-contrast.mjs --verbose          # list every failure
+ *
+ * Chrome is found via CHROME_PATH, or the usual macOS/Linux locations.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import WebSocket from 'ws';
+
+const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const siteDir = path.join(runnerDir, 'site');
+
+const args = process.argv.slice(2);
+const threshold = Number(readFlag('--threshold') ?? 4.5);
+const verbose = args.includes('--verbose');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+};
+
+/*
+ * Runs inside the page. Returns one record per element that renders its own
+ * text, with the ratio already composited.
+ */
+const AUDIT = String.raw`
+(() => {
+  function parse(c) {
+    const m = c.match(/rgba?\(([^)]+)\)/);
+    if (!m) return null;
+    const p = m[1].split(',').map((s) => parseFloat(s.trim()));
+    return { r: p[0], g: p[1], b: p[2], a: p.length > 3 ? p[3] : 1 };
+  }
+  function over(fg, bg) {
+    const a = fg.a;
+    return {
+      r: fg.r * a + bg.r * (1 - a),
+      g: fg.g * a + bg.g * (1 - a),
+      b: fg.b * a + bg.b * (1 - a),
+      a: 1,
+    };
+  }
+  function lum(c) {
+    const f = (v) => {
+      v /= 255;
+      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b);
+  }
+  function ratio(a, b) {
+    const l1 = lum(a);
+    const l2 = lum(b);
+    return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+  }
+  function effectiveBg(el) {
+    const stack = [];
+    let node = el;
+    while (node && node !== document.documentElement) {
+      const bg = parse(getComputedStyle(node).backgroundColor);
+      if (bg && bg.a > 0) {
+        stack.push(bg);
+        if (bg.a === 1) break;
+      }
+      node = node.parentElement;
+    }
+    const rootBg = parse(getComputedStyle(document.documentElement).backgroundColor);
+    let base = rootBg && rootBg.a === 1 ? rootBg : { r: 255, g: 255, b: 255, a: 1 };
+    for (let i = stack.length - 1; i >= 0; i--) base = over(stack[i], base);
+    return base;
+  }
+  function ownText(el) {
+    for (const n of el.childNodes) {
+      if (n.nodeType === 3 && n.textContent.trim().length) return true;
+    }
+    return false;
+  }
+  function hex(c) {
+    const h = (v) => Math.round(v).toString(16).padStart(2, '0');
+    return '#' + h(c.r) + h(c.g) + h(c.b);
+  }
+
+  const out = [];
+  document.querySelectorAll('*').forEach((el) => {
+    if (!ownText(el)) return;
+    const cs = getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none') return;
+    if (parseFloat(cs.opacity) === 0) return;
+    const rect = el.getBoundingClientRect();
+    if (!rect.width || !rect.height) return;
+    const raw = parse(cs.color);
+    if (!raw) return;
+    const bg = effectiveBg(el);
+    const fg = raw.a < 1 ? over(raw, bg) : raw;
+    let sel = el.tagName.toLowerCase();
+    if (typeof el.className === 'string' && el.className.trim()) {
+      sel += '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.');
+    }
+    out.push({
+      sel,
+      text: el.textContent.trim().slice(0, 48).replace(/\s+/g, ' '),
+      fg: hex(fg),
+      bg: hex(bg),
+      ratio: Math.round(ratio(fg, bg) * 100) / 100,
+      size: Math.round(parseFloat(cs.fontSize) * 10) / 10,
+      weight: parseInt(cs.fontWeight, 10) || 400,
+    });
+  });
+  return out;
+})()
+`;
+
+/* Open everything that hides text behind a disclosure. */
+const REVEAL = String.raw`
+(() => {
+  const style = document.createElement('style');
+  style.textContent = '*, *::before, *::after { animation: none !important; transition: none !important; }';
+  document.head.appendChild(style);
+  document.querySelectorAll('details').forEach((d) => { d.open = true; });
+  document.querySelectorAll('.layer[aria-controls]').forEach((l) => {
+    l.setAttribute('aria-expanded', 'true');
+    const d = document.getElementById(l.getAttribute('aria-controls'));
+    if (d) d.hidden = false;
+  });
+  return true;
+})()
+`;
+
+main().catch((err) => {
+  console.error(`site-contrast: ${err.message}`);
+  process.exit(1);
+});
+
+async function main() {
+  if (!fs.existsSync(siteDir)) {
+    throw new Error(`no site directory at ${siteDir}`);
+  }
+  const pages = listPages(siteDir);
+  if (pages.length === 0) throw new Error('no .html pages found under site/');
+
+  const server = await startServer(siteDir);
+  const chrome = await startChrome();
+  let failures = 0;
+  const rows = [];
+
+  try {
+    for (const page of pages) {
+      const url = `http://127.0.0.1:${server.port}/${page}`;
+      const measured = await auditPage(chrome.endpoint, url);
+      const under = measured.filter((m) => m.ratio < threshold);
+      const worst = measured.reduce((a, b) => (b.ratio < a.ratio ? b : a), measured[0]);
+      failures += under.length;
+      rows.push({ page, count: measured.length, under: under.length, worst });
+      if (verbose && under.length) {
+        for (const u of under) {
+          console.error(
+            `  ${u.ratio}:1  ${u.fg} on ${u.bg}  ${u.size}px/${u.weight}  ${u.sel}  "${u.text}"`,
+          );
+        }
+      }
+    }
+    await checkBehavior(chrome.endpoint, server.port, pages);
+  } finally {
+    await chrome.close();
+    await server.close();
+  }
+
+  report(rows, failures);
+  console.log('PASS — browser copy, filters, progress, and internal links');
+  process.exit(failures === 0 ? 0 : 1);
+}
+
+function report(rows, failures) {
+  const w = Math.max(...rows.map((r) => r.page.length), 4);
+  console.log(`WCAG contrast — threshold ${threshold}:1 — ${rows.length} pages\n`);
+  console.log(`  ${'page'.padEnd(w)}  elements  worst    element`);
+  console.log(`  ${'-'.repeat(w)}  --------  -------  -------`);
+  for (const r of rows) {
+    const mark = r.under === 0 ? ' ' : '!';
+    console.log(
+      `${mark} ${r.page.padEnd(w)}  ${String(r.count).padStart(8)}  ${String(r.worst.ratio).padStart(6)}:1  ${r.worst.sel}`,
+    );
+  }
+  const total = rows.reduce((n, r) => n + r.count, 0);
+  console.log('');
+  if (failures === 0) {
+    console.log(`PASS — 0 of ${total} text elements below ${threshold}:1`);
+  } else {
+    console.log(`FAIL — ${failures} of ${total} text elements below ${threshold}:1`);
+    if (!verbose) console.log('Re-run with --verbose to list them.');
+  }
+}
+
+function listPages(root) {
+  const out = [];
+  (function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.html')) {
+        out.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  })(root);
+  return out.sort();
+}
+
+function startServer(root) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const rel = decodeURIComponent((req.url || '/').split('?')[0]).replace(/^\/+/, '');
+      const file = path.join(root, rel);
+      if (!file.startsWith(root) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) {
+        res.writeHead(404).end('not found');
+        return;
+      }
+      res.writeHead(200, {
+        'Content-Type': MIME[path.extname(file)] ?? 'application/octet-stream',
+        'Cache-Control': 'no-store',
+      });
+      fs.createReadStream(file).pipe(res);
+    });
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: server.address().port,
+        close: () => new Promise((done) => server.close(done)),
+      });
+    });
+  });
+}
+
+function findChrome() {
+  if (process.env.CHROME_PATH) return process.env.CHROME_PATH;
+  const candidates = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+  ];
+  const found = candidates.find((c) => fs.existsSync(c));
+  if (!found) {
+    throw new Error('Chrome not found. Set CHROME_PATH to a Chrome or Chromium binary.');
+  }
+  return found;
+}
+
+async function startChrome() {
+  const binary = findChrome();
+  const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'site-contrast-'));
+  const child = spawn(
+    binary,
+    [
+      '--headless=new',
+      '--disable-gpu',
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--remote-debugging-port=0',
+      `--user-data-dir=${userDataDir}`,
+      'about:blank',
+    ],
+    { stdio: 'ignore' },
+  );
+
+  // Chrome writes the chosen port to DevToolsActivePort once it is listening.
+  const portFile = path.join(userDataDir, 'DevToolsActivePort');
+  const port = await waitFor(() => {
+    if (!fs.existsSync(portFile)) return null;
+    const line = fs.readFileSync(portFile, 'utf8').split('\n')[0].trim();
+    return line ? Number(line) : null;
+  }, 15000, 'Chrome did not report a debugging port');
+
+  const version = await getJson(`http://127.0.0.1:${port}/json/version`);
+  return {
+    endpoint: version.webSocketDebuggerUrl,
+    port,
+    close: async () => {
+      child.kill();
+      // Chrome holds the profile dir open until it exits; removing it early
+      // fails with ENOTEMPTY. Wait for exit, and never fail the gate on cleanup.
+      await new Promise((done) => {
+        if (child.exitCode !== null || child.signalCode !== null) return done();
+        const timer = setTimeout(done, 5000);
+        child.once('exit', () => {
+          clearTimeout(timer);
+          done();
+        });
+      });
+      try {
+        fs.rmSync(userDataDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+      } catch {
+        /* a leftover temp profile is not worth failing a contrast run over */
+      }
+    },
+  };
+}
+
+async function auditPage(browserEndpoint, url) {
+  return withPage(browserEndpoint, url, async (page) => {
+    await page.evaluate(REVEAL);
+    await new Promise((r) => setTimeout(r, 150));
+    return page.evaluate(AUDIT);
+  });
+}
+
+async function checkBehavior(browserEndpoint, port, pages) {
+  const base = `http://127.0.0.1:${port}/`;
+  await withPage(browserEndpoint, `${base}index.html`, async (page) => {
+    const copied = await page.evaluate(String.raw`
+      (async () => {
+        Object.defineProperty(navigator, 'clipboard', {
+          configurable: true,
+          value: {
+            writeText(text) {
+              window.__siteCopied = text;
+              return Promise.resolve();
+            },
+          },
+        });
+        const button = document.querySelector('.prompt .copy');
+        if (!button) throw new Error('copy button was not initialized');
+        button.click();
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        return window.__siteCopied;
+      })()
+    `);
+    const expected = 'mm-harness run <recipe> --artifacts-dir ./first-recipe-artifacts';
+    if (!copied?.includes(expected)) {
+      throw new Error(`copy prompt omitted "${expected}"`);
+    }
+
+    const progress = await page.evaluate(String.raw`
+      (() => {
+        const box = document.querySelector('.step-check');
+        box.click();
+        return {
+          stored: localStorage.getItem('mmh.progress.start'),
+          label: document.querySelector('.progress-label')?.textContent,
+        };
+      })()
+    `);
+    if (!progress.stored || progress.stored === '[]' || !/^1\//.test(progress.label ?? '')) {
+      throw new Error('checklist progress was not persisted and rendered');
+    }
+  });
+
+  await withPage(browserEndpoint, `${base}cheatsheet.html`, async (page) => {
+    const coreCommands = await page.evaluate(String.raw`
+      (() => {
+        document.querySelector('.chip[data-platform="core"]').click();
+        return [...document.querySelectorAll('tr[data-platforms]:not([hidden]) code')]
+          .map((node) => node.textContent.trim());
+      })()
+    `);
+    const forbidden = coreCommands.filter((command) =>
+      /mm-harness (logs|stop)|mm-harness call (read_state|navigate)|mm-harness actions --category ui/.test(command),
+    );
+    if (forbidden.length) {
+      throw new Error(`Core filter exposed unsupported commands: ${forbidden.join(', ')}`);
+    }
+    if (!coreCommands.some((command) => command.includes('call read_positions'))) {
+      throw new Error('Core filter omitted its headless read action');
+    }
+  });
+
+  for (const relative of pages) {
+    await withPage(browserEndpoint, `${base}${relative}`, async (page) => {
+      const broken = await page.evaluate(String.raw`
+        (async () => {
+          const links = [...document.querySelectorAll('a[href]')]
+            .map((link) => new URL(link.getAttribute('href'), location.href))
+            .filter((url) => url.origin === location.origin);
+          const failures = [];
+          for (const url of links) {
+            let response;
+            for (let attempt = 0; attempt < 2 && !response; attempt += 1) {
+              try {
+                response = await fetch(url.pathname);
+              } catch {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+              }
+            }
+            if (!response?.ok) failures.push(url.pathname + ' (' + (response?.status ?? 'network') + ')');
+          }
+          return failures;
+        })()
+      `);
+      if (broken.length) {
+        throw new Error(`${relative} has broken internal links: ${broken.join(', ')}`);
+      }
+    });
+  }
+}
+
+async function withPage(browserEndpoint, url, inspect) {
+  // A fresh target per page keeps one page's state out of the next one's.
+  const browser = await connect(browserEndpoint);
+  let targetId;
+  try {
+    ({ targetId } = await browser.send('Target.createTarget', { url: 'about:blank' }));
+    const { sessionId } = await browser.send('Target.attachToTarget', {
+      targetId,
+      flatten: true,
+    });
+    const page = browser.session(sessionId);
+    await page.send('Page.enable');
+    await page.send('Runtime.enable');
+    await page.send('Emulation.setDeviceMetricsOverride', {
+      width: 1440,
+      height: 1000,
+      deviceScaleFactor: 1,
+      mobile: false,
+    });
+    await page.send('Page.navigate', { url });
+    await waitFor(async () => {
+      const r = await page.evaluate('document.readyState');
+      return r === 'complete' ? true : null;
+    }, 15000, `page never finished loading: ${url}`);
+    // The stylesheet and module both land before readyState complete, but give
+    // the module a beat to run so injected controls are present.
+    await new Promise((r) => setTimeout(r, 250));
+    return await inspect(page);
+  } finally {
+    if (targetId) await browser.send('Target.closeTarget', { targetId }).catch(() => {});
+    browser.close();
+  }
+}
+
+function connect(endpoint) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(endpoint, { perMessageDeflate: false, maxPayload: 256 * 1024 * 1024 });
+    const pending = new Map();
+    let id = 0;
+
+    ws.on('message', (raw) => {
+      const msg = JSON.parse(raw.toString());
+      if (!msg.id || !pending.has(msg.id)) return;
+      const { ok, fail } = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.error) fail(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+      else ok(msg.result);
+    });
+    ws.on('error', reject);
+
+    const send = (method, params = {}, sessionId) =>
+      new Promise((ok, fail) => {
+        const mid = ++id;
+        pending.set(mid, { ok, fail });
+        ws.send(JSON.stringify({ id: mid, method, params, sessionId }));
+        setTimeout(() => {
+          if (pending.delete(mid)) fail(new Error(`timeout: ${method}`));
+        }, 30000);
+      });
+
+    const evaluate = async (expression, sessionId) => {
+      const r = await send(
+        'Runtime.evaluate',
+        { expression, returnByValue: true, awaitPromise: true },
+        sessionId,
+      );
+      if (r.exceptionDetails) {
+        throw new Error(r.exceptionDetails.exception?.description ?? 'evaluate failed');
+      }
+      return r.result.value;
+    };
+
+    ws.on('open', () =>
+      resolve({
+        send,
+        close: () => ws.close(),
+        session: (sessionId) => ({
+          send: (m, p) => send(m, p, sessionId),
+          evaluate: (e) => evaluate(e, sessionId),
+        }),
+      }),
+    );
+  });
+}
+
+async function waitFor(probe, timeoutMs, message) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await probe();
+    if (value !== null && value !== undefined && value !== false) return value;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error(message);
+}
+
+function getJson(url) {
+  return new Promise((resolve, reject) => {
+    http
+      .get(url, (res) => {
+        let body = '';
+        res.on('data', (c) => {
+          body += c;
+        });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch (err) {
+            reject(err);
+          }
+        });
+      })
+      .on('error', reject);
+  });
+}
+
+function readFlag(name) {
+  const at = args.indexOf(name);
+  return at === -1 ? undefined : args[at + 1];
+}