@ticket-gate/react 0.0.0-stage → 0.1.0-rc.1

package/index.mjs

@@ -0,0 +1,27 @@
+import { profile } from './profile.mjs';
+
+/** The react pack. `profile` is a function returning the profile config, loaded only when the command runs. */
+export function reactPack({ profile: load } = {}) {
+  if (load !== undefined && typeof load !== 'function')
+    throw new TypeError(
+      'reactPack: profile must be a function returning the profile config',
+    );
+  return {
+    name: 'react',
+    version: '0.0.0-local',
+    packCommands:
+      load === undefined
+        ? {}
+        : {
+            profile: async (args) => {
+              try {
+                await profile(await load()).run(args);
+              } catch (err) {
+                console.error(err);
+                return 1;
+              }
+              return process.exitCode ?? 0;
+            },
+          },
+  };
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@ticket-gate/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.1",
+  "description": "The React Compiler bailout ratchet for @ticket-gate/engine.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": { "node": ">=22" },
+  "exports": {
+    "./*": "./*",
+    "./package.json": "./package.json"
+  },
+  "imports": { "#engine/*": "@ticket-gate/engine/*" },
+  "dependencies": { "@ticket-gate/engine": "0.1.0-rc.1" },
+  "files": ["*", "!test"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmitry-prohorov/ticket-gate.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": { "access": "public", "provenance": true }
+}

package/profile.mjs

@@ -0,0 +1,27 @@
+import { profiler } from './profiler/cli.mjs';
+
+const BUILD_TEXT = ['command', 'unmangle', 'start', 'noBuildLabel'];
+
+/** Binds the profiler to one project's config; see the README. */
+export function profile(cfg) {
+  if (cfg.lock !== false && (typeof cfg.lock !== 'string' || cfg.lock === ''))
+    throw new TypeError('profile: lock must be a stack lock owner or false');
+  if (
+    BUILD_TEXT.some((k) => typeof cfg.build?.[k] !== 'string') ||
+    !Number.isInteger(cfg.build?.port)
+  )
+    throw new TypeError(
+      `profile: build needs ${BUILD_TEXT.join(', ')} and an integer port`,
+    );
+  return profiler(cfg);
+}
+
+/** A Vite app aliases react-dom/client to react-dom/profiling and sets esbuild.keepNames itself; a wrong build is caught by the trace guards. */
+export const viteProfiling = ({ cmd, preview }) => ({
+  command: cmd,
+  unmangle: 'esbuild.keepNames in the Vite config',
+  start: preview,
+  port: 4173,
+  noBuildLabel: 'unknown (existing server on :4173)',
+});
+export { reactProfile } from './profiler/nightly.mjs';

package/profiler/capture.mjs

@@ -0,0 +1,36 @@
+// Browser capture for the React profiler: context, DevTools hook stub, trace.
+import { createRequire } from 'node:module';
+
+export const TRACE_CATEGORIES = [
+  'devtools.timeline',
+  'disabled-by-default-devtools.timeline',
+  'blink.user_timing',
+];
+
+/** Loads Playwright's chromium from the package.json that depends on it. */
+export function resolveChromium(playwrightFrom) {
+  const require = createRequire(playwrightFrom);
+  return require('@playwright/test').chromium;
+}
+
+/** A fresh context with the stub hook, and its first page. The caller signs in. */
+export async function openContext(browser, context) {
+  const ctx = await browser.newContext(context);
+  // React sets ProfileMode on the root, and so writes the Components track, only when a
+  // DevTools hook exists. A disabled stub turns that on without injecting a backend.
+  await ctx.addInitScript(() => {
+    window.__REACT_DEVTOOLS_GLOBAL_HOOK__ = { isDisabled: true };
+  });
+  const page = await ctx.newPage();
+  return { context: ctx, page };
+}
+
+/** Traces `act` into `file`. */
+export async function captureRun(browser, page, act, file) {
+  await browser.startTracing(page, {
+    path: file,
+    categories: TRACE_CATEGORIES,
+  });
+  await act();
+  await browser.stopTracing();
+}

package/profiler/cli.mjs

@@ -0,0 +1,206 @@
+// The profiler run loop and its binding to one project config. Every project
+// value (scenarios, urls, build command, login, reset) arrives in `cfg`; see the shim
+// that calls `profiler(cfg)` for the shape.
+import { execSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { takeOrExit } from '#engine/lock.mjs';
+import { serve } from '#engine/serve.mjs';
+import { captureRun, openContext, resolveChromium } from './capture.mjs';
+import {
+  SETUP_MISSING,
+  applyBudget,
+  budgetFailures,
+  compare,
+  parseArgs,
+  parseBudgets,
+  scenarioRenders,
+  setupDiff,
+} from './stats.mjs';
+import {
+  analyse,
+  median,
+  problemHints,
+  reduceRun,
+  traceProblem,
+} from './trace.mjs';
+
+/** Every problem at once, [] when ready. `probe(url)` resolves to a boolean; `hasEnv()` says whether the app env exists. */
+export async function preflight({ build }, cfg, probe, hasEnv) {
+  const [appUp, ...up] = await Promise.all([
+    probe(cfg.appUrl),
+    ...cfg.services.map((s) => probe(s.url)),
+  ]);
+  const problems = [];
+  if (build && appUp) problems.push(cfg.preflight.portInUse);
+  if (!build && !appUp) problems.push(cfg.preflight.noApp);
+  cfg.services.forEach((s, i) => {
+    if (!up[i]) problems.push(s.problem);
+  });
+  if (!hasEnv()) problems.push(cfg.preflight.noWebEnv);
+  return problems;
+}
+
+export function loadBaseline(path) {
+  let baseline;
+  try {
+    baseline = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `--compare ${path}: cannot read it as JSON (${err.message})`,
+    );
+  }
+  if (typeof baseline?.summary !== 'object' || baseline.summary === null)
+    throw new Error(
+      `--compare ${path}: not a results file (no "summary" object)`,
+    );
+  return baseline;
+}
+
+function gitOut(cfg, args) {
+  return execSync(`git ${args}`, { cwd: cfg.root }).toString().trim();
+}
+
+export async function run(cfg, argv) {
+  // Refuses at once while another run holds the stack.
+  if (cfg.lock !== false) takeOrExit(cfg.lock);
+  const hints = problemHints(cfg);
+  const opts = parseArgs(argv, cfg);
+  const baseline = opts.compare === null ? null : loadBaseline(opts.compare);
+  const problems = await preflight(
+    { build: opts.build },
+    cfg,
+    cfg.probe,
+    cfg.hasEnv,
+  );
+  if (problems.length > 0) throw new Error(problems.join('\n'));
+  mkdirSync(join(opts.out, 'traces'), { recursive: true });
+
+  const results = {};
+  let chromiumVersion = '';
+  let stopServer = null;
+  const onSigint = async () => {
+    if (stopServer !== null) await stopServer();
+    process.exit(130);
+  };
+  try {
+    if (opts.build) {
+      await serve(
+        {
+          build: cfg.build.command,
+          start: cfg.build.start,
+          port: cfg.build.port,
+          env: cfg.build.env,
+        },
+        {
+          onSpawn: (stop) => {
+            stopServer = stop;
+            process.once('SIGINT', onSigint);
+          },
+        },
+      );
+    }
+    const chromium = resolveChromium(cfg.playwrightFrom);
+    const browser = await chromium.launch({ handleSIGINT: false });
+    chromiumVersion = browser.version();
+    try {
+      for (const sc of opts.scenarios) {
+        results[sc] = [];
+        for (let run = 0; run <= opts.runs; run++) {
+          if (cfg.writing.includes(sc) || run === 0) await cfg.reset();
+          const { context, page } = await openContext(browser, cfg.context);
+          await cfg.open(page);
+          const act = await cfg.scenarios[sc](page);
+          const file = join(
+            opts.out,
+            'traces',
+            `${cfg.tracePrefix}${sc}-run${run}.json`,
+          );
+          await captureRun(browser, page, act, file);
+          await context.close();
+          const r = reduceRun(
+            JSON.parse(readFileSync(file, 'utf8')),
+            cfg.componentsFor(sc),
+            hints,
+          );
+          console.log(
+            `${sc} ${run === 0 ? 'warm-up' : `run ${run}`} ${JSON.stringify(r)}`,
+          );
+          if (run > 0) results[sc].push(r);
+        }
+      }
+    } finally {
+      await browser.close();
+      await cfg.reset();
+    }
+  } finally {
+    if (stopServer !== null) {
+      await stopServer();
+      process.removeListener('SIGINT', onSigint);
+    }
+  }
+
+  const summary = {};
+  for (const [sc, list] of Object.entries(results))
+    summary[sc] = Object.fromEntries(
+      Object.keys(list[0]).map((k) => [k, median(list.map((r) => r[k]))]),
+    );
+  const meta = {
+    sha: gitOut(cfg, 'rev-parse HEAD'),
+    dirty: gitOut(cfg, 'status --porcelain') !== '',
+    buildFlags: opts.build ? cfg.build.command : cfg.build.noBuildLabel,
+    chromium: chromiumVersion,
+    runs: opts.runs,
+    scenarios: opts.scenarios,
+    date: new Date().toISOString(),
+  };
+  const file = join(opts.out, `results-${Date.now()}.json`);
+  writeFileSync(file, JSON.stringify({ meta, results, summary }, null, 2));
+  console.log(`median of ${opts.runs}:`);
+  console.table(summary);
+  console.log(`traces and results: ${opts.out}`);
+  if (baseline !== null) {
+    console.log('this run:', meta);
+    console.log('baseline:', baseline.meta ?? '(no setup record)');
+    for (const line of setupDiff(meta, baseline.meta))
+      console.log(`setup differs: ${line}`);
+    console.table(compare(summary, baseline));
+  }
+  const { lines, code } = applyBudget(
+    summary,
+    opts.maxRenders,
+    cfg.componentsFor,
+  );
+  for (const line of lines) console.error(line);
+  if (code !== 0) process.exitCode = code;
+}
+
+/** Binds the module-level functions to one config; the shim re-exports these names. */
+export function profiler(cfg) {
+  const firstScenario = Object.keys(cfg.scenarios)[0];
+  const first = cfg.componentsFor(firstScenario);
+  const hints = problemHints(cfg);
+  return {
+    PROBLEM: hints,
+    PREFLIGHT: cfg.preflight,
+    SETUP_MISSING,
+    analyse: (trace, names = first) => analyse(trace, names),
+    traceProblem: (r, names = first) => traceProblem(r, names, hints),
+    reduceRun: (trace, scenario = firstScenario) =>
+      reduceRun(trace, cfg.componentsFor(scenario), hints),
+    median,
+    compare,
+    setupDiff,
+    parseBudgets: (text) => parseBudgets(text, cfg),
+    parseArgs: (argv) => parseArgs(argv, cfg),
+    budgetFailures: (summary, budgets) =>
+      budgetFailures(summary, budgets, cfg.componentsFor),
+    applyBudget: (summary, budgets) =>
+      applyBudget(summary, budgets, cfg.componentsFor),
+    scenarioRenders: (row, scenario) =>
+      scenarioRenders(row, scenario, cfg.componentsFor),
+    preflight: ({ build }, probe = cfg.probe, hasEnv = cfg.hasEnv) =>
+      preflight({ build }, cfg, probe, hasEnv),
+    run: (argv) => run(cfg, argv),
+  };
+}

package/profiler/nightly-child.mjs

@@ -0,0 +1,26 @@
+// Spawned by the nightly suite: one profiler run in the worktree. The nightly already holds the
+// stack lock, so the profiler takes none. It leaves results.json and numbers.json in the run directory.
+import { readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { profiler } from './cli.mjs';
+import { numbersOf } from './nightly.mjs';
+
+const [config, out, ...args] = process.argv.slice(2);
+try {
+  const { default: cfg } = await import(pathToFileURL(resolve(config)).href);
+  await profiler({ ...cfg, lock: false }).run([...args, `--out=${out}`]);
+  const written = readdirSync(out)
+    .filter((f) => /^results-\d+\.json$/.test(f))
+    .sort()
+    .at(-1);
+  renameSync(join(out, written), join(out, 'results.json'));
+  const { summary } = JSON.parse(readFileSync(join(out, 'results.json'), 'utf8'));
+  writeFileSync(join(out, 'numbers.json'), JSON.stringify(numbersOf(summary, cfg)));
+} catch (err) {
+  console.error(String(err.message).replace(/\s*\n\s*/g, ' '));
+  process.exitCode = 1;
+}
+// A handle a project config left open must not hold the suite until its time limit.
+process.exit(process.exitCode ?? 0);

package/profiler/nightly.mjs

@@ -0,0 +1,202 @@
+// The nightly suite runner: it profiles one build in a child process, so the suite's time
+// limit can stop it, and turns the numbers the child leaves in the run directory into a result.
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { byRanAtDesc, readNightly, suiteView } from '#engine/nightly/record.mjs';
+import { fixSeed, realGit, short } from '#engine/nightly/seed.mjs';
+import { scenarioRenders } from './stats.mjs';
+
+export const NIGHTLY_CHILD = fileURLToPath(new URL('./nightly-child.mjs', import.meta.url));
+const STABLE_NIGHTS = 7;
+const GRACE_S = 30;
+const LOG_TAIL = 2000;
+const SHOWN_MERGES = 3;
+const NO_FLAKY = [];
+
+/** Medians of each scenario's own component renders, and the scenarios over their budget. */
+export function numbersOf(summary, { budgets = {}, componentsFor }) {
+  const medians = {};
+  const over = [];
+  const advisory = [];
+  for (const [scenario, row] of Object.entries(summary)) {
+    const renders = scenarioRenders(row, scenario, componentsFor);
+    medians[scenario] = renders;
+    const b = budgets[scenario];
+    if (b === undefined) continue;
+    if (typeof b?.max !== 'number') throw new Error(`budget for ${scenario} needs a numeric max`);
+    const blocking = b.blocking === true;
+    if (!blocking) advisory.push(scenario);
+    if (renders > b.max) over.push({ scenario, renders, budget: b.max, blocking });
+  }
+  return { medians, over, advisory };
+}
+
+/** Advisory scenarios in budget for the last 7 nights whose medians stayed within 10%. */
+export function promotable(history, suite, tonight) {
+  const nights = history
+    .map((l) => ({ ranAt: l.ranAt, view: suiteView(l, suite) }))
+    .filter((n) => n.view !== null)
+    .sort(byRanAtDesc)
+    .slice(0, STABLE_NIGHTS - 1);
+  if (nights.length < STABLE_NIGHTS - 1) return [];
+  const series = [tonight, ...nights.map((n) => n.view.extra)];
+  return tonight.advisory.filter((sc) => {
+    if (
+      !series.every(
+        (e) => typeof e?.medians?.[sc] === 'number' && !(e.over ?? []).some((o) => o.scenario === sc),
+      )
+    )
+      return false;
+    const values = series.map((e) => e.medians[sc]);
+    return (Math.max(...values) - Math.min(...values)) * 10 <= Math.min(...values);
+  });
+}
+
+function suspectsText({ lastGreenSha, merges }) {
+  const since = lastGreenSha ? short(lastGreenSha) : 'no green night';
+  const shown = merges.slice(0, SHOWN_MERGES).map((m) => `${short(m.sha)} ${m.subject}`);
+  const more = merges.length > SHOWN_MERGES ? ` +${merges.length - SHOWN_MERGES} more` : '';
+  return `suspect merges since ${since}: ${shown.join(', ') || 'none'}${more}`;
+}
+
+/** The one line `nightly status` prints for this suite. */
+export function statusLine(view) {
+  const e = view.extra ?? {};
+  const parts = [];
+  if (e.noNumbers !== undefined)
+    parts.push(e.noNumbers === 'cut-short' ? 'cut-short' : `no numbers: ${e.noNumbers}`);
+  else if (view.status === 'error') parts.push(view.reason ?? 'error');
+  for (const o of e.over ?? [])
+    parts.push(`${o.scenario} renders ${o.renders} > ${o.budget}, ${o.blocking ? 'blocking' : 'advisory'}`);
+  for (const sc of e.promote ?? [])
+    parts.push(`${sc} stable ${STABLE_NIGHTS} of ${STABLE_NIGHTS} nights: promote with blocking: true`);
+  if (e.suspects === null) parts.push('suspect merges unavailable');
+  else if (e.suspects !== undefined) parts.push(suspectsText(e.suspects));
+  const word = view.status === 'error' ? 'red' : view.status;
+  return `nightly profile: ${word}${parts.length > 0 ? ` (${parts.join('; ')})` : ''}`;
+}
+
+const noNumbers = ({ runs, out, reason, suspects }) => ({
+  timedOut: false,
+  summary: summaryOf({ expected: 0, unexpected: 1, flaky: 0, scenarios: 0, runs, failed: ['no numbers'] }),
+  report: { results: null, log: out.slice(-LOG_TAIL) },
+  extra: { medians: {}, over: [], advisory: [], noNumbers: reason, suspects },
+});
+
+const summaryOf = ({ expected, unexpected, flaky, scenarios, runs, failed }) => ({
+  stats: { expected, unexpected, flaky, skipped: 0, scenarios, runs },
+  failedSpecs: failed,
+  flakySpecs: NO_FLAKY,
+  redTests: [],
+});
+
+const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+function readNumbers(io, dir) {
+  const file = join(dir, 'numbers.json');
+  if (!io.exists(file)) return null;
+  try {
+    const n = JSON.parse(io.readFile(file));
+    const shaped = isPlain(n?.medians) && Array.isArray(n.over) && Array.isArray(n.advisory);
+    return shaped && Object.keys(n.medians).length > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A runner for `nightly.suites`. The suite entry passes `keep: runner.keep`.
+ * `config` is the profile config module, relative to the worktree.
+ */
+export function reactProfile({ config, runs, scenarios, keepTraces }, { git = realGit } = {}) {
+  if (typeof config !== 'string' || config === '')
+    throw new TypeError('reactProfile: config must be a path relative to the worktree');
+  if (!Number.isInteger(runs) || runs < 1)
+    throw new TypeError('reactProfile: runs must be a positive integer');
+  if (scenarios !== 'all' && !(Array.isArray(scenarios) && scenarios.length > 0))
+    throw new TypeError("reactProfile: scenarios must be 'all' or a non-empty list");
+  if (!Number.isInteger(keepTraces) || keepTraces < 1)
+    throw new TypeError('reactProfile: keepTraces must be a positive integer');
+  const flags = ['--build', `--runs=${runs}`, ...(scenarios === 'all' ? [] : [`--scenarios=${scenarios.join(',')}`])];
+  return {
+    name: 'profile',
+    keep: { reports: 'all', traces: keepTraces },
+    statusLine,
+    async run({ wt, io, args = [], limitS, env = {}, dir }) {
+      let history = [];
+      const suite = basename(dirname(dir));
+      const suspectsOf = () => {
+        try {
+          const lines = history.flatMap((l) => {
+            const v = suiteView(l, suite);
+            return v === null ? [] : [{ sha: l.sha, ranAt: l.ranAt, status: v.status }];
+          });
+          const { lastGreenSha, merges } = fixSeed({
+            latest: { sha: basename(dir).slice(0, 12) },
+            history: lines,
+            git,
+          });
+          return { lastGreenSha, merges: merges.map(({ sha, subject }) => ({ sha, subject })) };
+        } catch {
+          return null; // no suspects without git
+        }
+      };
+      try {
+        history = readNightly(dirname(dirname(dir))).history;
+        io.rm(dir);
+        io.mkdir(dir);
+        const r = await io.run(process.execPath, [NIGHTLY_CHILD, config, dir, ...flags, ...args], {
+          cwd: wt,
+          env: { ...env, TICKET_GATE_ROOT: wt },
+          limitS,
+          killSignal: 'SIGINT',
+          graceS: GRACE_S,
+        });
+        if (r.timedOut)
+          return {
+            timedOut: true,
+            summary: null,
+            report: null,
+            extra: { noNumbers: 'cut-short', suspects: suspectsOf() },
+          };
+        const numbers = r.code === 0 ? readNumbers(io, dir) : null;
+        if (numbers === null)
+          return noNumbers({
+            runs,
+            out: r.out,
+            reason: r.out.trim().split('\n').at(-1) || `exit ${r.code}`,
+            suspects: suspectsOf(),
+          });
+        const blocking = numbers.over.filter((o) => o.blocking);
+        const advisoryOver = numbers.over.length - blocking.length;
+        const red = blocking.length > 0;
+        const count = Object.keys(numbers.medians).length;
+        return {
+          timedOut: false,
+          summary: summaryOf({
+            expected: count - numbers.over.length,
+            unexpected: blocking.length,
+            flaky: advisoryOver,
+            scenarios: count,
+            runs,
+            failed: blocking.map((o) => o.scenario),
+          }),
+          report: { results: 'results.json', traces: 'traces' },
+          extra: {
+            ...numbers,
+            promote: promotable(history, suite, numbers),
+            ...(red ? { suspects: suspectsOf() } : {}),
+          },
+        };
+      } catch (e) {
+        return noNumbers({
+          runs,
+          out: '',
+          reason: e instanceof Error ? e.message : String(e),
+          suspects: suspectsOf(),
+        });
+      }
+    },
+  };
+}

package/profiler/stats.mjs

@@ -0,0 +1,130 @@
+// Argument parsing, render budgets and result comparison for the React profiler.
+// Every project value arrives in `cfg`.
+import { round } from './trace.mjs';
+
+export const usageOf = (cfg) =>
+  `usage: ${cfg.command} [--build] [--scenarios=${Object.keys(cfg.scenarios).join(',')}] [--runs=N (integer >= 1)] [--out=<dir>] [--compare=<results.json>] [--max-renders=${cfg.usage.maxRenders}]`;
+
+/** 'a:12,b:8' -> { a: 12, b: 8 }. Throws on a malformed pair, unknown scenario or non-integer. */
+export function parseBudgets(text, cfg) {
+  const usage = usageOf(cfg);
+  const budgets = {};
+  for (const pair of text.split(',')) {
+    const [sc, n, ...rest] = pair.split(':');
+    if (rest.length > 0 || n === undefined || !/^\d+$/.test(n))
+      throw new Error(
+        `--max-renders: "${pair}" is not <scenario>:<integer>. ${usage}`,
+      );
+    if (!(sc in cfg.scenarios)) throw new Error(`unknown scenario ${sc}`);
+    budgets[sc] = Number(n);
+  }
+  return budgets;
+}
+
+/** What the run does with a budget: stderr lines and the exit code (1 over budget, else 0). */
+export function applyBudget(summary, budgets, componentsFor) {
+  if (budgets === null) return { lines: [], code: 0 };
+  const lines = budgetFailures(summary, budgets, componentsFor).map(
+    (line) => `render budget exceeded: ${line}`,
+  );
+  return { lines, code: lines.length > 0 ? 1 : 0 };
+}
+
+/** A scenario's median renders of its own components; null when it did not run. */
+export function scenarioRenders(row, scenario, componentsFor) {
+  if (row === undefined) return null;
+  return componentsFor(scenario).reduce(
+    (sum, name) => sum + (row[name] ?? 0),
+    0,
+  );
+}
+
+/** Lines naming each scenario whose component renders exceed its budget; [] when all are within. */
+export function budgetFailures(summary, budgets, componentsFor) {
+  return Object.entries(budgets)
+    .map(([sc, max]) => [
+      sc,
+      max,
+      scenarioRenders(summary[sc], sc, componentsFor),
+    ])
+    .filter(([, max, renders]) => renders === null || renders > max)
+    .map(
+      ([sc, max, renders]) =>
+        `${sc}: median ${componentsFor(sc).join(' + ')} renders ${renders ?? 'missing'} > budget ${max}`,
+    );
+}
+
+/** argv = process.argv.slice(2). Throws on anything it does not know. */
+export function parseArgs(argv, cfg) {
+  const usage = usageOf(cfg);
+  const opts = {
+    scenarios: Object.keys(cfg.scenarios),
+    runs: 3,
+    out: cfg.out,
+    build: false,
+    compare: null,
+    maxRenders: null,
+  };
+  for (const a of argv) {
+    if (a === '--build') opts.build = true;
+    else if (a.startsWith('--scenarios='))
+      opts.scenarios = a.slice('--scenarios='.length).split(',');
+    else if (a.startsWith('--runs='))
+      opts.runs = Number(a.slice('--runs='.length));
+    else if (a.startsWith('--out=')) opts.out = a.slice('--out='.length);
+    else if (a.startsWith('--compare='))
+      opts.compare = a.slice('--compare='.length);
+    else if (a.startsWith('--max-renders='))
+      opts.maxRenders = parseBudgets(a.slice('--max-renders='.length), cfg);
+    else throw new Error(usage);
+  }
+  const { runs } = opts;
+  if (!Number.isInteger(runs) || runs < 1) throw new Error(usage);
+  for (const sc of opts.scenarios)
+    if (!(sc in cfg.scenarios)) throw new Error(`unknown scenario ${sc}`);
+  for (const sc of Object.keys(opts.maxRenders ?? {}))
+    if (!opts.scenarios.includes(sc))
+      throw new Error(
+        `--max-renders names ${sc}, which --scenarios does not run`,
+      );
+  return opts;
+}
+
+function percent(now, base) {
+  const pct =
+    base === 0 ? (now === 0 ? 0 : null) : round(((now - base) / base) * 100);
+  return pct;
+}
+
+/** One row per (scenario, metric) of `summary`; base/delta/pct are null when the baseline lacks it. */
+export function compare(summary, baseline) {
+  const rows = [];
+  for (const [scenario, metrics] of Object.entries(summary))
+    for (const [metric, now] of Object.entries(metrics)) {
+      const base = baseline.summary?.[scenario]?.[metric] ?? null;
+      if (base === null) {
+        rows.push({ scenario, metric, now, base, delta: null, pct: null });
+        continue;
+      }
+      rows.push({
+        scenario,
+        metric,
+        now,
+        base,
+        delta: round(now - base),
+        pct: percent(now, base),
+      });
+    }
+  return rows;
+}
+
+export const SETUP_MISSING =
+  'baseline has no setup record (written before setup records existed)';
+
+/** Lines naming each differing setup field. The commit sha is never flagged. */
+export function setupDiff(meta, baseMeta) {
+  if (!baseMeta) return [SETUP_MISSING];
+  return ['buildFlags', 'chromium', 'runs']
+    .filter((field) => meta[field] !== baseMeta[field])
+    .map((field) => `${field}: ${baseMeta[field]} -> ${meta[field]}`);
+}