@ticket-gate/engine 0.0.0 → 0.1.0-rc.1

package/mutations/served.mjs

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+
+import { portBusy, portInUse, startWebServer } from '../serve.mjs';
+import { applyPatch, restorePatch, sessionOf } from './harness.mjs';
+import { projectSetup } from './project.mjs';
+import { LIMITS, tail, verdict } from './verdict.mjs';
+
+/** A patch claimed by a harness that defers to a slower run: built and served once per distinct patch. */
+export const isServed = (m, setup = projectSetup()) =>
+  sessionOf(m, setup)?.defer !== undefined;
+
+/** Twelve hex chars naming one distinct patch. */
+export const patchKey = (m) =>
+  createHash('sha256')
+    .update(`${m.file}\0${m.within ?? ''}\0${m.find}\0${m.replace}`)
+    .digest('hex')
+    .slice(0, 12);
+
+// A patch under opts.skipBuild (an e2e spec) changes no app code: it runs on the clean server.
+const buildNeeded = (m, opts) => !m.file.startsWith(opts.skipBuild);
+
+const needsWebBuild = (m, setup = projectSetup()) => {
+  const opts = sessionOf(m, setup)?.opts;
+  return opts === undefined || buildNeeded(m, opts);
+};
+
+/** Every entry of a group that could not be built or started is `error`, never `killed`. */
+function groupError(group, phase, r) {
+  return {
+    results: group.entries.map((m) => ({
+      id: m.id,
+      status: 'error',
+      detail: `group ${group.key}: ${phase} failed: ${tail(r.out)}`,
+    })),
+    build: phase === 'build' ? 'failed' : (group.built ?? 'none'),
+  };
+}
+
+// Apply one patch, build, serve, run each entry's test against that one server,
+// stop the server, restore the file byte-exact. Returns { results, build }.
+async function runGroup(group, io, state, ctx, opts) {
+  const m0 = group.entries[0];
+  const rules = ctx.rulesFor(m0);
+  const needsBuild = buildNeeded(m0, opts);
+  let server = null;
+  const body = async () => {
+    for (const rule of rules) state[rule.flag] = true;
+    applyPatch([m0], io, state);
+    for (const rule of rules) {
+      const cb = await io[rule.io]();
+      if (cb.code !== 0) return groupError(group, 'build', cb);
+    }
+    if (needsBuild) {
+      const build = await io.buildWeb();
+      if (build.code !== 0) return groupError(group, 'build', build);
+      group.built = 'ok';
+    }
+    server = await io.startServer();
+    state.server = server;
+    if (!server.ok) return groupError(group, 'start', server);
+    const results = [];
+    for (const m of group.entries) {
+      const t = await io.run(m.test, { reuse: true });
+      if (server.died?.())
+        return groupError(group, 'start', {
+          out: `server died mid-group: ${tail(t.out)}`,
+        });
+      results.push(verdict(m, t));
+    }
+    return { results, build: group.built ?? 'none' };
+  };
+  let res;
+  try {
+    res = await body();
+  } catch (err) {
+    res = groupError(group, 'start', { out: String(err?.message ?? err) });
+  } finally {
+    try {
+      await server?.stop();
+    } catch {
+      /* best effort: the next group's port check reports a leak */
+    }
+    state.server = null;
+    try {
+      restorePatch(state, io);
+    } catch (err) {
+      const detail = `RESTORE FAILED: ${err.message}. Run ${ctx.setup.commands.restoreHint}`;
+      res = {
+        ...res,
+        results: group.entries.map((m) => ({
+          id: m.id,
+          status: 'error',
+          detail,
+        })),
+      };
+    }
+    state.restore = null;
+  }
+  for (const rule of rules) {
+    const b = await io[rule.io]();
+    if (b.code === 0) state[rule.flag] = false;
+    else
+      ctx.fatal = `${rule.cmd} failed after restoring ${m0.file}: ${rule.drift}. Run ${rule.cmd}`;
+  }
+  return res;
+}
+
+// One clean build and server prove every distinct served test passes unmutated.
+async function cleanPhase(entries, io, state, opts) {
+  const build = await io.buildWeb();
+  if (build.code !== 0)
+    return { fatal: `clean ${opts.build} failed: ${tail(build.out)}` };
+  const server = await io.startServer();
+  state.server = server;
+  const base = new Map();
+  try {
+    if (!server.ok)
+      return {
+        fatal: `clean server did not start on port ${opts.port}: ${tail(server.out)}`,
+      };
+    for (const m of entries) {
+      if (base.has(m.test)) continue;
+      let r;
+      try {
+        r = await io.run(m.test, { reuse: true });
+      } catch (err) {
+        r = { code: 1, out: String(err) };
+      }
+      base.set(m.test, r);
+    }
+  } finally {
+    try {
+      await server.stop();
+    } catch {
+      /* best effort */
+    }
+    state.server = null;
+  }
+  return { base };
+}
+
+/**
+ * The harness for patches tested through a built and served app: one clean
+ * build proves the baselines, then one build and server per distinct patch.
+ * `opts` = { name, order, port, env, build, start, skipBuild,
+ * claims: RegExp, defer }; the harness exposes them as `opts`.
+ */
+export function served(opts) {
+  return {
+    name: opts.name,
+    order: opts.order,
+    claims: (m) => m.kind === 'patch' && opts.claims.test(m.test),
+    defer: opts.defer,
+    opts,
+    ioMethods: ({ exec }) => ({
+      buildWeb: () =>
+        exec('bash', ['-lc', opts.build], {
+          limitS: LIMITS.webBuild,
+          env: opts.env,
+        }),
+      startServer: () => startWebServer(opts),
+      portInUse,
+    }),
+    async refuse(_entries, io) {
+      return (await io.portInUse(opts.port))
+        ? portBusy(opts.port)
+        : null;
+    },
+    async open(entries, io, state) {
+      if (entries.length === 0)
+        return { baselines: new Map(), groups: [], builds: 0 };
+      const clean = await cleanPhase(entries, io, state, opts);
+      if (clean.fatal) return { fatal: clean.fatal, groups: [], builds: 1 };
+      return { baselines: clean.base, builds: 1 };
+    },
+    // Groups that rebuild leave their mutated build behind, so the groups that do
+    // not rebuild (e2e patches) run first, on the clean phase's build.
+    group(entries) {
+      const byKey = new Map();
+      for (const m of entries) {
+        const key = patchKey(m);
+        if (!byKey.has(key)) byKey.set(key, { key, entries: [] });
+        byKey.get(key).entries.push(m);
+      }
+      const built = (g) => Number(buildNeeded(g.entries[0], opts));
+      return [...byKey.values()].sort((a, b) => built(a) - built(b));
+    },
+    async run(groups, io, emit, state, ctx) {
+      const done = [];
+      let builds = 0;
+      for (const group of groups) {
+        const t0 = Date.now();
+        const r = await runGroup(group, io, state, ctx, opts);
+        if (r.build !== 'none') builds++;
+        done.push({
+          key: group.key,
+          ids: group.entries.map((m) => m.id),
+          build: r.build,
+          ms: Date.now() - t0,
+        });
+        for (const x of r.results) emit(x, group.key);
+        if (ctx.fatal) break;
+      }
+      return { groups: done, builds, fatal: ctx.fatal ?? undefined };
+    },
+    async interrupt(state) {
+      try {
+        await state.server?.stop();
+      } catch {
+        /* best effort */
+      }
+    },
+  };
+}
+
+export { needsWebBuild, portInUse, startWebServer };

package/mutations/validate.mjs

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ROOT } from '../root.mjs';
+import { projectSetup } from './project.mjs';
+import { CARET_FILTER, CARET_HINT, locate } from './registry.mjs';
+
+/** Schema errors, one string each. [] when valid. Nothing runs before this. */
+export function validateSpec(spec, readFile, setup = projectSetup()) {
+  const errors = [];
+  if (!spec || typeof spec !== 'object' || !Array.isArray(spec.mutations))
+    return ['file must be an object with a "mutations" array'];
+  if (spec.mutations.length === 0) errors.push('"mutations" is empty');
+  const seen = new Set();
+  for (const [i, m] of spec.mutations.entries()) {
+    const at = `mutation #${i + 1}${m?.id ? ` (${m.id})` : ''}`;
+    if (!m || typeof m !== 'object') {
+      errors.push(`${at}: not an object`);
+      continue;
+    }
+    if (typeof m.id !== 'string' || m.id === '') errors.push(`${at}: no id`);
+    else if (seen.has(m.id)) errors.push(`${at}: duplicate id ${m.id}`);
+    else seen.add(m.id);
+    if (typeof m.test !== 'string' || m.test.trim() === '')
+      errors.push(`${at}: "test" must be a non-empty command`);
+    else if (CARET_FILTER.test(m.test)) errors.push(`${at}: ${CARET_HINT}`);
+    const kind = setup.kinds.get(m.kind);
+    if (kind?.runs && kind.validate) {
+      errors.push(...kind.validate(m, readFile).map((e) => `${at}: ${e}`));
+    } else if (m.kind === 'patch') {
+      if (m.restore !== undefined)
+        errors.push(`${at}: "restore" is only for sql mutations`);
+      if (
+        typeof m.file !== 'string' ||
+        typeof m.find !== 'string' ||
+        m.find === ''
+      )
+        errors.push(`${at}: patch needs "file" and a non-empty "find"`);
+      else if (typeof m.replace !== 'string')
+        errors.push(`${at}: patch needs a string "replace" (may be empty)`);
+      else {
+        let src = null;
+        try {
+          src = readFile(m.file);
+        } catch {
+          errors.push(`${at}: file ${m.file} does not exist`);
+        }
+        if (src !== null) {
+          const n = locate(src, m.find, m.within).count;
+          if (n !== 1)
+            errors.push(
+              `${at}: "find" occurs ${n} times in ${m.file}, must be exactly 1 (stale or ambiguous mutation: update "find")`,
+            );
+        }
+      }
+    } else {
+      const names = [...setup.kinds.values()]
+        .filter((k) => k.runs && k.name !== 'patch')
+        .map((k) => k.name)
+        .concat('patch');
+      errors.push(
+        `${at}: kind must be ${names.map((n) => `"${n}"`).join(' or ')}`,
+      );
+    }
+  }
+  return errors;
+}
+
+/** Reads and validates; throws with every error listed. */
+export function loadSpec(
+  path,
+  readFile = (p) => readFileSync(join(ROOT, p), 'utf8'),
+) {
+  let spec;
+  try {
+    spec = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`cannot read ${path}: ${err.message}`);
+  }
+  const errors = validateSpec(spec, readFile);
+  if (errors.length)
+    throw new Error(
+      `${path} is invalid:\n  - ${errors.join('\n  - ')}\nFix the mutations file; nothing was run.`,
+    );
+  return spec;
+}

package/mutations/verdict.mjs

@@ -0,0 +1,159 @@
+const ANSI = /\x1b\[[0-9;]*m/g;
+const VITEST_NO_FILES = /^No test files found, exiting with code \d+$/m;
+const JEST_NO_TESTS = /^No tests found, exiting with code \d+$/m;
+const count = (line, word) =>
+  Number(line.match(new RegExp(`(\\d+) ${word}`))?.[1] ?? 0);
+const lastMatch = (text, re) => [...text.matchAll(re)].at(-1);
+
+const PW_NO_TESTS = /^Error: No tests found\.?$/m;
+// prettier-ignore
+const PW_NO_SERVER = /Process from config\.webServer (?:was not able to start|exited early)|Timed out waiting \d+ms from config\.webServer/;
+
+// Playwright: the last block of "  <n> passed|failed|flaky|skipped|did not run|interrupted" lines.
+function playwrightSummary(text) {
+  const re =
+    /^ {2}(\d+) (passed|failed|flaky|skipped|did not run|interrupted)\b.*$/;
+  let block = [];
+  let prev = false;
+  for (const l of text.split('\n')) {
+    const m = l.match(re);
+    if (/^ {4}/.test(l)) continue; // a failed test's header sits inside the block
+    if (m) {
+      if (!prev) block = [];
+      block.push({ n: Number(m[1]), kind: m[2], line: l.trim() });
+      prev = true;
+    } else prev = false;
+  }
+  if (!block.length) return null;
+  const ran = block
+    .filter((b) => b.kind !== 'skipped' && b.kind !== 'did not run')
+    .reduce((a, b) => a + b.n, 0);
+  return { line: block.map((b) => b.line).join(', '), ran };
+}
+
+function vitestSummary(text) {
+  const m = lastMatch(text, /^ +(Tests {2}(.+))$/gm);
+  if (!m) return null;
+  return {
+    line: m[1].trim(),
+    passed: count(m[2], 'passed'),
+    failed: count(m[2], 'failed'),
+    filesFailed: /^ +Test Files {2}.*\bfailed\b/m.test(text),
+  };
+}
+
+function jestSummary(text) {
+  const m = lastMatch(text, /^(Tests: +(.+))$/gm);
+  if (!m) return null;
+  return {
+    line: m[1].trim(),
+    passed: count(m[2], 'passed'),
+    failed: count(m[2], 'failed'),
+    suitesFailed: /^Test Suites:.*\bfailed\b/m.test(text),
+  };
+}
+
+// node --test: the last summary block (spec "ℹ tests N" or TAP "# tests N").
+// With process isolation a filter that matched nothing reports one passing
+// "test" named after the file; those top-level file-only passes do not count.
+function nodeSummary(text, cmd) {
+  const block = { tests: null, pass: 0, fail: 0, cancelled: 0 };
+  let line = null;
+  for (const m of text.matchAll(
+    /^[ℹ#] (tests|pass|fail|cancelled) (\d+)\s*$/gm,
+  )) {
+    if (m[1] === 'tests') {
+      Object.assign(block, { pass: 0, fail: 0, cancelled: 0 });
+      line = m[0].trim();
+    }
+    block[m[1]] = Number(m[2]);
+  }
+  if (line === null) return null;
+  const tokens = new Set(
+    cmd.split(/\s+/).map((t) => t.replace(/^['"]|['"]$/g, '')),
+  );
+  let fileOnly = 0;
+  for (const m of text.matchAll(
+    /^(?:✔ (.+?) \(\d+(?:\.\d+)?ms\)|ok \d+ - (.+?))\s*$/gm,
+  ))
+    if (tokens.has(m[1] ?? m[2])) fileOnly++;
+  return { ...block, line: line.replace(/^[ℹ#] /, ''), fileOnly };
+}
+
+/**
+ * Did this test output run zero tests? A reason string ('<runner>: <summary>')
+ * or null. Positive per runner; output with no recognised summary (shell
+ * `true`, grep, playwright) is null and classified by exit code. A run that
+ * reports a failure is never zero: a load failure is a kill. `extra` holds the
+ * harness parsers (cmd, out) -> reason | null, tried after the built-in ones.
+ */
+// prettier-ignore
+export function zeroTestRun(cmd, out, extra = []) {
+  out = String(out ?? '');
+  const text = out.replace(ANSI, '');
+  // A failing node --test run can echo other runners' summaries in an assertion diff.
+  const n = nodeSummary(text, cmd);
+  if (n && n.fail + n.cancelled > 0) return null;
+  if (VITEST_NO_FILES.test(text)) return 'vitest: No test files found';
+  const v = vitestSummary(text);
+  if (v && v.passed + v.failed === 0 && !v.filesFailed) return `vitest: ${v.line}`;
+  if (JEST_NO_TESTS.test(text)) return 'jest: No tests found';
+  const j = jestSummary(text);
+  if (j && j.passed + j.failed === 0 && !j.suitesFailed) return `jest: ${j.line}`;
+  if (n && n.pass - n.fileOnly <= 0 && n.fail + n.cancelled === 0) return `node --test: ${n.line}`;
+  if (PW_NO_TESTS.test(text)) return 'playwright: No tests found';
+  if (PW_NO_SERVER.test(text)) return 'playwright: webServer did not start';
+  const pw = playwrightSummary(text);
+  if (pw && pw.ran === 0) return `playwright: ${pw.line}`;
+  const extraHit = extra.map((z) => z(cmd, out)).find((r) => r != null);
+  return extraHit ?? null;
+}
+
+function zeroResult(m, why, when) {
+  const fix =
+    when === 'before the mutation'
+      ? 'fix the "test" filter or path; it selects nothing'
+      : 'neither killed nor survived; check the filter';
+  return {
+    id: m.id,
+    status: 'error',
+    detail: `ran zero tests ${when} (${why}): ${fix}`,
+  };
+}
+
+/** Per-child limits in seconds (R10): a child past its limit is an `error`, never a kill. */
+export const LIMITS = {
+  run: 900,
+  reset: 300,
+  build: 300,
+  sql: 120,
+  probe: 10,
+  webBuild: 600,
+  serve: 120,
+};
+
+function timedOutResult(m, t) {
+  return {
+    id: m.id,
+    status: 'error',
+    detail: `TIMEOUT after ${t.limitS ?? LIMITS.run} s: ${m.test}`,
+  };
+}
+
+// Killed, survived, or (zero tests ran) error; zero is checked before the exit code.
+function verdict(m, t, extra = []) {
+  if (t.timedOut === true) return timedOutResult(m, t);
+  const zero = zeroTestRun(m.test, t.out, extra);
+  if (zero) return zeroResult(m, zero, 'under the mutation');
+  return t.code !== 0
+    ? { id: m.id, status: 'killed', detail: tail(t.out) }
+    : {
+        id: m.id,
+        status: 'survived',
+        detail: `the test still passes with the guard removed (${m.protects ?? m.id}): it does not bite; strengthen the test, then re-run`,
+      };
+}
+
+const tail = (out) => out.trim().split('\n').slice(-5).join('\n');
+
+export { tail, verdict, zeroResult };

package/nightly/cli.mjs

@@ -0,0 +1,30 @@
+// `ticket-gate nightly run [--now] | install | status`: the sub-command switch over the runner,
+// the scheduler install and the status printer, with the io the config's payloads add.
+import { loadRegistry } from '../mutations/registry.mjs';
+import { realIo } from './io.mjs';
+import { main as runMain } from './run.mjs';
+import { main as statusMain } from './status.mjs';
+
+export const NIGHTLY_USAGE = 'usage: ticket-gate nightly run [--now] | install | status';
+
+/** The runner's io: the real one, the registry loader, then every payload's `io` entries. */
+export function nightlyIo(cfg) {
+  return {
+    ...realIo(),
+    registry: cfg.rotate?.registry ?? ((root) => loadRegistry(root)),
+    ...Object.assign({}, ...cfg.payloads.map((p) => p.io ?? {})),
+  };
+}
+
+/** Run one sub-command; resolves to the exit code. */
+export async function nightlyMain([sub, ...rest], cfg) {
+  if (sub === 'run' && !rest.includes('--install')) return runMain(rest, cfg, nightlyIo(cfg));
+  if (sub === 'install' && rest.length === 0 && !cfg.scheduler) {
+    console.error('nightly: FAIL install needs nightly.scheduler in gate.config.mjs');
+    return 2;
+  }
+  if (sub === 'install' && rest.length === 0) return runMain(['--install'], cfg, nightlyIo(cfg));
+  if (sub === 'status') return statusMain(rest, cfg);
+  console.error(NIGHTLY_USAGE);
+  return 2;
+}

package/nightly/define.mjs

@@ -0,0 +1,111 @@
+// The nightly's one config object. `defineNightly` fills the defaults
+// and rejects a config the runner cannot honour; the engine reads nothing else
+// about the project. Dependency-free Node ESM.
+
+export const NIGHTLY_DEFAULTS = Object.freeze({
+  window: { start: '00:50', end: '06:00', catchUpBy: '00:30' },
+  remote: { name: 'origin', branch: 'main' },
+  payloads: [],
+  keep: { reports: 'history' },
+  selects: { interim: () => false, load: null },
+  commands: {
+    run: 'ticket-gate nightly run',
+    install: 'ticket-gate nightly install',
+    status: 'ticket-gate nightly status',
+  },
+});
+
+const bad = (reason) => {
+  throw new Error(`nightly config: ${reason}`);
+};
+const posInt = (n) => Number.isInteger(n) && n > 0;
+
+function checkKeep(keep, where) {
+  if (keep.reports !== undefined) {
+    const r = keep.reports;
+    if (r !== 'all' && r !== 'history' && !posInt(r))
+      bad(
+        `${where} keep.reports must be 'all', 'history' or a positive integer`,
+      );
+  }
+  if (keep.traces !== undefined && !posInt(keep.traces))
+    bad(`${where} keep.traces must be a positive integer`);
+}
+
+function checkSuites(suites) {
+  if (!Array.isArray(suites) || suites.length === 0)
+    bad('suites must list at least one suite');
+  const seen = new Set();
+  for (const [i, s] of suites.entries()) {
+    if (typeof s?.name !== 'string' || s.name === '')
+      bad(`suite ${i} has no name`);
+    if (seen.has(s.name)) bad(`duplicate suite name '${s.name}'`);
+    seen.add(s.name);
+    if (typeof s.runner?.run !== 'function')
+      bad(`suite '${s.name}' has no runner.run`);
+    if (typeof s.limitS !== 'number' || !(s.limitS > 0))
+      bad(`suite '${s.name}' limitS must be greater than 0`);
+    if (i > 0 && typeof s.runner.statusLine !== 'function')
+      bad(
+        `suite '${s.name}' needs runner.statusLine (only the first suite may omit it)`,
+      );
+    checkKeep(s.keep ?? {}, `suite '${s.name}'`);
+    if (i === 0 && s.keep?.traces !== undefined)
+      bad(`suite '${s.name}' is the first suite and keeps no traces dirs`);
+  }
+}
+
+function checkPayloads(payloads) {
+  const seen = new Set();
+  for (const p of payloads) {
+    if (
+      typeof p?.name !== 'string' ||
+      p.name === '' ||
+      typeof p.preflight !== 'function'
+    )
+      bad('a payload needs a name and a preflight function');
+    if (seen.has(p.name)) bad(`duplicate payload name '${p.name}'`);
+    seen.add(p.name);
+  }
+}
+
+/** Fill defaults, validate, freeze. Idempotent. */
+export function defineNightly(cfg) {
+  const d = NIGHTLY_DEFAULTS;
+  const out = {
+    ...cfg,
+    window: { ...d.window, ...cfg.window },
+    remote: { ...d.remote, ...cfg.remote },
+    payloads: cfg.payloads ?? [],
+    keep: { ...d.keep, ...cfg.keep },
+    selects: { ...d.selects, ...cfg.selects },
+    commands: { ...d.commands, ...cfg.commands },
+  };
+  checkKeep(out.keep, 'config');
+  checkSuites(out.suites);
+  checkPayloads(out.payloads);
+  const w = out.worktree;
+  if (
+    typeof w?.dir !== 'string' ||
+    w.dir === '' ||
+    !Array.isArray(w.install) ||
+    w.install.length === 0
+  )
+    bad('worktree needs dir and install');
+  // rotate is optional (no rotation runs without it) but never half-formed.
+  if (
+    out.rotate !== undefined &&
+    (!Array.isArray(out.rotate.command) || out.rotate.command.length === 0)
+  )
+    bad('rotate needs command');
+  // The top-level keep is the default for a suite that names none of its own;
+  // the first suite keeps no traces dirs, so it inherits reports only.
+  out.suites = out.suites.map((s, i) => ({
+    ...s,
+    keep:
+      i === 0
+        ? { reports: out.keep.reports, ...s.keep }
+        : { ...out.keep, ...s.keep },
+  }));
+  return Object.freeze(out);
+}

package/nightly/e2e-runs.mjs

@@ -0,0 +1,73 @@
+// The gate's own e2e runs, one JSON line each, beside the nightly record. The nightly
+// status reads them to say how much of the last two weeks the gate spent in a forced
+// full run. Dependency-free Node ESM (`node:` only).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const E2E_RUNS_FILE = 'e2e-runs.jsonl';
+export const E2E_RUNS_MAX = 1000;
+export const FORCED_WINDOW_MS = 14 * 24 * 3_600_000;
+export const FORCED_MAX = 0.25;
+
+/** The e2e step's line for one gate run, or null when it did not pass or fail. */
+export function e2eRunOf(results, id, ranAt) {
+  const r = results.find(
+    (x) =>
+      x.id === id &&
+      ['pass', 'fail'].includes(x.status) &&
+      typeof x.mode === 'string',
+  );
+  return r ? { ranAt, ms: r.ms, mode: r.mode, why: r.why ?? null } : null;
+}
+
+/** Every parsable line of `<dir>/e2e-runs.jsonl`; a missing file is []. */
+export function readE2eRuns(dir) {
+  let text;
+  try {
+    text = readFileSync(join(dir, E2E_RUNS_FILE), 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // an unparsable line is skipped
+    }
+  }
+  return out;
+}
+
+/** Append `line`, keeping the newest `max` lines. */
+export function appendE2eRun(dir, line, max = E2E_RUNS_MAX) {
+  mkdirSync(dir, { recursive: true });
+  const lines = [...readE2eRuns(dir), line];
+  writeFileSync(
+    join(dir, E2E_RUNS_FILE),
+    `${lines
+      .slice(-max)
+      .map((l) => JSON.stringify(l))
+      .join('\n')}\n`,
+  );
+}
+
+/** Share of the last 14 days' gate e2e time spent in a forced full run. */
+export function forcedShare(runs, nowMs) {
+  const recent = runs.filter(
+    (r) =>
+      Number.isFinite(r.ms) && nowMs - Date.parse(r.ranAt) <= FORCED_WINDOW_MS,
+  );
+  const totalMs = recent.reduce((a, r) => a + r.ms, 0);
+  if (totalMs === 0) return { share: null, totalMs: 0 };
+  const forced = recent
+    .filter(
+      (r) =>
+        r.mode === 'full' &&
+        typeof r.why === 'string' &&
+        r.why.startsWith('nightly '),
+    )
+    .reduce((a, r) => a + r.ms, 0);
+  return { share: forced / totalMs, totalMs };
+}