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

package/mutations/harness.mjs

@@ -0,0 +1,240 @@
+// Sessions and harnesses (entry kinds and setup): which session runs an entry, and
+// how a patch is put on disk and taken off again. The pure grouping and
+// attribution functions disjointGroups/attribute join this
+// file; none names a platform.
+import { patchedSource } from './locate.mjs';
+import { tail, verdict } from './verdict.mjs';
+
+/**
+ * Applies each patch in order on the progressively patched text of its file.
+ * Each file's original is recorded once in `state.live` and `state.restore`
+ * puts every live file back. A `find` that no longer occurs once throws and
+ * leaves the tree as it was.
+ */
+export function applyPatch(patches, io, state) {
+  const live = (state.live ??= new Map());
+  const texts = new Map();
+  const fresh = [];
+  try {
+    for (const m of patches) {
+      if (!texts.has(m.file)) {
+        const original = io.readFile(m.file);
+        texts.set(m.file, original);
+        if (!live.has(m.file)) {
+          live.set(m.file, original);
+          fresh.push(m.file);
+        }
+      }
+      try {
+        texts.set(m.file, patchedSource(texts.get(m.file), m));
+      } catch (err) {
+        if (patches.length === 1) throw err;
+        throw new Error(
+          `${m.id}: find no longer occurs once with the other patches applied`,
+        );
+      }
+    }
+  } catch (err) {
+    for (const file of fresh) live.delete(file);
+    throw err;
+  }
+  state.restore = () => restorePatch(state, io);
+  try {
+    for (const [file, text] of texts) io.writeFile(file, text);
+  } catch (err) {
+    try {
+      restorePatch(state, io);
+    } catch {
+      /* the write error is the one to report */
+    }
+    throw err;
+  }
+}
+
+/** Writes every live file back and checks it; a no-op when nothing is live. */
+export function restorePatch(state, io) {
+  if (!state.live) {
+    state.restore = null;
+    return;
+  }
+  let failed = null;
+  for (const [file, original] of state.live) {
+    try {
+      io.writeFile(file, original);
+      if (io.readFile(file) !== original)
+        throw new Error(`restore of ${file} is not byte-identical`);
+    } catch (err) {
+      failed ??= err;
+    }
+  }
+  state.live.clear();
+  state.restore = null;
+  if (failed) throw failed;
+}
+
+/**
+ * The inline fallback harness: runs every patch no other harness claims, one at
+ * a time. Rebuild rules (`ctx.rulesFor`) bracket the run: the flag is set while
+ * the patch is live, and the build runs again once the file is back.
+ */
+export const localHarness = {
+  name: 'local',
+  order: 0,
+  inline: true,
+  claims: () => true,
+  async runOne(m, io, state, ctx) {
+    const rules = ctx.rulesFor(m);
+    let result;
+    try {
+      for (const rule of rules) state[rule.flag] = true;
+      applyPatch([m], io, state);
+      for (const rule of rules) {
+        const b = await io[rule.io]();
+        if (b.code !== 0)
+          throw new Error(`${rule.cmd} failed after apply: ${tail(b.out)}`);
+      }
+      result = verdict(m, await io.run(m.test));
+    } catch (err) {
+      result = {
+        id: m.id,
+        status: 'error',
+        detail: String(err?.message ?? err),
+      };
+    } finally {
+      try {
+        restorePatch(state, io);
+      } catch (err) {
+        const detail = `RESTORE FAILED: ${err.message}. Run ${ctx.setup.commands.restoreHint}`;
+        if (result) result = { ...result, status: 'error', detail };
+        else result = { id: m.id, status: 'error', detail };
+      }
+      state.restore = null;
+    }
+    for (const rule of rules) {
+      // The built output must match the source again before the next mutation.
+      const b = await io[rule.io]();
+      if (b.code === 0) state[rule.flag] = false;
+      else {
+        ctx.fatal = `${rule.cmd} failed after restoring ${m.file}: ${rule.drift}. Run ${rule.cmd}`;
+        result = { id: m.id, status: 'error', detail: ctx.fatal };
+      }
+    }
+    return result;
+  },
+};
+
+const claimedTwice = (entry, claimants) =>
+  new Error(
+    `mutations config: ${entry.id} is claimed by both ${claimants[0].name} and ${claimants[1].name}`,
+  );
+
+/**
+ * The session that runs an entry: a non-patch kind's own `session`, or the
+ * harness claiming a patch (localHarness claims every patch nobody else does).
+ * Throws when two harnesses claim one entry.
+ */
+export function sessionOf(entry, setup) {
+  if (entry.kind !== 'patch') return setup.kinds.get(entry.kind)?.session;
+  const claimants = setup.harnesses.filter(
+    (h) => h !== localHarness && h.claims(entry),
+  );
+  if (claimants.length > 1) throw claimedTwice(entry, claimants);
+  return claimants[0] ?? localHarness;
+}
+
+// ---- grouping and attribution (pure; no io, no platform name) -------------
+
+const shares = (a, b) => a.some((x) => b.includes(x));
+const overlaps = (a, b) => a.start <= b.end && b.start <= a.end;
+const soloGroup = (entry, why) => ({
+  key: entry.id,
+  entries: [entry],
+  solo: why,
+});
+
+// prettier-ignore
+function compatible(a, b) {
+  if (shares(a.tests, b.tests)) return false;
+  if (shares(a.cover, b.tests) || shares(b.cover, a.tests)) return false;
+  if (a.span.file === b.span.file && overlaps(a.span, b.span)) return false;
+  return true;
+}
+
+/**
+ * Greedy first-fit grouping in input order. A member joins a group only when
+ * it is compatible with every member: no shared test, no test of one covering
+ * the other's site, no overlapping lines in one file. `testsOf(entry)` is the
+ * tests that own the entry (null: unparsable); `coverOf(entry)` is
+ * `{ cover, span }` (null: no coverage). Both fall back to a solo group.
+ */
+export function disjointGroups(entries, testsOf, coverOf) {
+  const out = [];
+  const open = [];
+  for (const entry of entries) {
+    const tests = testsOf(entry);
+    if (tests == null) {
+      out.push(soloGroup(entry, 'tests unparsable'));
+      continue;
+    }
+    const facts = coverOf(entry);
+    if (facts == null) {
+      out.push(soloGroup(entry, 'no coverage'));
+      continue;
+    }
+    const m = { entry, tests, cover: facts.cover, span: facts.span };
+    const home = open.find((g) => g.members.every((o) => compatible(o, m)));
+    if (home) {
+      home.members.push(m);
+      home.entries.push(entry);
+    } else {
+      const g = { key: entry.id, entries: [entry], members: [m] };
+      open.push(g);
+      out.push(g);
+    }
+  }
+  return out;
+}
+
+const holds = (span, c) =>
+  span.file === c.file && span.start <= c.line && c.line <= span.end;
+
+/**
+ * Maps one run of a group back to its members. `{ solo }` means the run cannot
+ * be attributed and each member must be run alone. A compile error that lands
+ * in exactly one member's span marks that member an error and returns the rest
+ * to be deployed again.
+ */
+// prettier-ignore
+export function attribute(group, run) {
+  if (!run.complete) return { solo: 'run cut short' };
+  const members = group.members;
+  if (run.compile) {
+    const owners = members.filter((m) => holds(m.span, run.compile));
+    if (owners.length !== 1) return { solo: 'compile error not attributable' };
+    return {
+      results: [
+        {
+          id: owners[0].entry.id,
+          status: 'error',
+          detail: `compile: ${run.compile.message}`,
+        },
+      ],
+      redeploy: members.filter((m) => m !== owners[0]),
+    };
+  }
+  for (const row of run.rows) {
+    if (row.outcome !== 'fail') continue;
+    const owner = members.find((m) => m.tests.includes(row.test));
+    if (owner === undefined) return { solo: `row owned by no member: ${row.test}` };
+  }
+  const results = members.map((m) => {
+    const own = run.rows.filter((r) => m.tests.includes(r.test));
+    const id = m.entry.id;
+    if (own.some((r) => r.outcome === 'fail'))
+      return { id, status: 'killed', detail: 'a covering test failed' };
+    if (own.length > 0)
+      return { id, status: 'survived', detail: 'every covering test passed' };
+    return { id, status: 'error', detail: 'no rows' };
+  });
+  return { results };
+}

package/mutations/kinds.mjs

@@ -0,0 +1,148 @@
+// Entry kinds and the setup a project hands the engine.
+//
+// @typedef {object} Kind
+//   name, runs: boolean, fields: string[], shape(entry, readFile) -> string[],
+//   stale?(entry, readFile) -> string[], area?(entry, dir) -> string,
+//   runFields?: string[], selectRules?: [name, (ctx, key, rec) -> boolean][],
+//   repair?(entry, diff) -> { entry, notes? } | { left: string },
+//   planNote?(entry) -> string | null, session?: Session,
+//   validate?(entry, readFile) -> string[]   (what validateSpec adds for a runnable entry),
+//   paths?(entry) -> string[]                (files the entry guards, for `affected`),
+//   strays?(entry) -> string[]               (a field this kind owns, checked on an entry of any kind)
+// readFile(rel) returns the text of a repo file and throws when it is missing.
+// @typedef {object} Setup
+//   dir, receipts: { ticket, registry }, area(entry), fieldOrder, legacy | null,
+//   rebuild: Rule[], childEnv: { drop }, commands, kinds: Map<name, Kind & { by }>,
+//   harnesses: Harness[], reuseEnv
+import { dirname } from 'node:path';
+
+import { localHarness } from './harness.mjs';
+
+const isStr = (v) => typeof v === 'string' && v.trim() !== '';
+
+const defaultArea = (entry, dir) => {
+  const d = dirname(entry.file);
+  return d === '.' ? `${dir}/_root.json` : `${dir}/${d}.json`;
+};
+
+export const ENGINE_DEFAULTS = Object.freeze({
+  dir: 'mutation-registry',
+  receipts: Object.freeze({
+    ticket: '.turbo/mutation-check.json',
+    registry: '.turbo/mutation-registry.json',
+  }),
+  area: (entry) => defaultArea(entry, 'mutation-registry'),
+  fieldOrder: Object.freeze([
+    'kind',
+    'protects',
+    'file',
+    'within',
+    'find',
+    'replace',
+    'test',
+    'testFile',
+    'testName',
+    'why',
+    'retired',
+    'reaimed',
+  ]),
+  legacy: null,
+  rebuild: Object.freeze([]),
+  childEnv: Object.freeze({ drop: Object.freeze([]) }),
+  commands: Object.freeze({
+    mutate: 'ticket-gate mutate',
+    checkMutations: 'ticket-gate mutations check',
+    checkMutationsScript: 'ticket-gate mutations check',
+    afterFatal: 'restore the tree, then re-run',
+    restoreHint: 'git checkout on the file',
+  }),
+  reuseEnv: Object.freeze({}),
+});
+
+/** A patch: replace `find` by `replace` in `file`; the harness that claims it runs `test`. */
+export const patchKind = {
+  name: 'patch',
+  runs: true,
+  fields: [
+    'protects',
+    'file',
+    'within',
+    'find',
+    'replace',
+    'test',
+    'testFile',
+    'testName',
+  ],
+  runFields: [
+    'file',
+    'within',
+    'find',
+    'replace',
+    'apply',
+    'restore',
+    'test',
+    'object',
+    'also',
+  ],
+  shape(entry) {
+    const out = [];
+    for (const f of ['protects', 'file', 'find', 'test', 'testFile'])
+      if (!isStr(entry[f])) out.push(`${f} must be a non-empty string`);
+    if (typeof entry.replace !== 'string') out.push('replace must be a string');
+    if (entry.within !== undefined && !isStr(entry.within))
+      out.push('within must be a non-empty string');
+    return out;
+  },
+};
+
+const kindTwice = (name, a, b) =>
+  new Error(`mutations config: kind "${name}" is named by both ${a} and ${b}`);
+
+/**
+ * Merges a project config over the engine defaults. Kinds resolve in order
+ * engine (`patch`), each pack's `mutationKinds`, then `config.kinds`; harnesses
+ * are every pack's `mutationHarnesses` in pack order, then `localHarness` last.
+ */
+export function resolveSetup(config = {}) {
+  const packs = config.packs ?? [];
+  const kinds = new Map();
+  const add = (name, kind, by) => {
+    if (kinds.has(name)) throw kindTwice(name, kinds.get(name).by, by);
+    kinds.set(name, { ...kind, by });
+  };
+  add('patch', patchKind, 'engine');
+  for (const p of packs)
+    for (const [name, kind] of Object.entries(p.mutationKinds ?? {}))
+      add(name, kind, p.name);
+  for (const [name, kind] of Object.entries(config.kinds ?? {}))
+    add(name, kind, 'config');
+  const dir = config.dir ?? ENGINE_DEFAULTS.dir;
+  return {
+    dir,
+    receipts: config.receipts ?? ENGINE_DEFAULTS.receipts,
+    area: config.area ?? ((entry) => defaultArea(entry, dir)),
+    fieldOrder: config.fieldOrder ?? ENGINE_DEFAULTS.fieldOrder,
+    legacy: config.legacy ?? ENGINE_DEFAULTS.legacy,
+    rebuild: config.rebuild ?? ENGINE_DEFAULTS.rebuild,
+    childEnv: config.childEnv ?? ENGINE_DEFAULTS.childEnv,
+    commands: { ...ENGINE_DEFAULTS.commands, ...config.commands },
+    reuseEnv: config.reuseEnv ?? ENGINE_DEFAULTS.reuseEnv,
+    kinds,
+    harnesses: [
+      ...packs.flatMap((p) => p.mutationHarnesses ?? []),
+      localHarness,
+    ],
+  };
+}
+
+const isRef = (w) => /\d/.test(w) || /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(w);
+
+/** Why a `protects` is too thin (null when fine): 4+ words, at least one a row or spec id. */
+export function checkProtects(protects) {
+  if (typeof protects !== 'string') return 'protects must be a string';
+  const words = protects.split(/\s+/).filter(Boolean);
+  if (words.length < 4)
+    return `protects has ${words.length} words, needs 4 or more`;
+  if (!words.some(isRef)) return 'protects names no contract row or spec id';
+  return null;
+}

package/mutations/locate.mjs

@@ -0,0 +1,71 @@
+// Where a patch's `find` sits in a source (moved out of registry.mjs so a kind
+// module can use it without reaching the project setup).
+const WS_RUN = /\s+/g;
+
+/** A global RegExp for `find`: every whitespace run in it matches `\s+`. */
+export function findPattern(find) {
+  const escaped = find.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(escaped.replace(WS_RUN, '\\s+'), 'g');
+}
+
+const lineStart = (src, i) => src.lastIndexOf('\n', i - 1) + 1;
+const indentOf = (src, ls) => /^[ \t]*/.exec(src.slice(ls))[0].length;
+
+/**
+ * The block an anchor opens: from the anchor's line up to, not including, the
+ * first later non-blank line indented <= the anchor's whose first character is
+ * not `}`, `)` or `]` (end of file when none). { count } when the anchor does
+ * not occur exactly once.
+ */
+export function blockSpan(src, anchor) {
+  const hits = [...src.matchAll(findPattern(anchor))];
+  if (hits.length !== 1) return { count: hits.length };
+  const start = lineStart(src, hits[0].index);
+  const indent = indentOf(src, start);
+  const from = hits[0].index + hits[0][0].length;
+  let pos = src.indexOf('\n', from);
+  while (pos !== -1) {
+    const ls = pos + 1;
+    const line = src.slice(
+      ls,
+      src.indexOf('\n', ls) === -1 ? src.length : src.indexOf('\n', ls),
+    );
+    if (
+      line.trim() !== '' &&
+      indentOf(src, ls) <= indent &&
+      !'})]'.includes(line.trim()[0])
+    )
+      return { start, end: ls };
+    pos = src.indexOf('\n', ls);
+  }
+  return { start, end: src.length };
+}
+
+/** Where `find` sits: { count, index, length }; index and length only when count is 1. */
+export function locate(src, find, within) {
+  if (typeof find !== 'string' || find === '') return { count: 0 };
+  let base = 0;
+  let hay = src;
+  if (within !== undefined) {
+    const span = blockSpan(src, within);
+    if (span.count !== undefined) return { count: 0, anchorCount: span.count };
+    base = span.start;
+    hay = src.slice(span.start, span.end);
+  }
+  const hits = [...hay.matchAll(findPattern(find))];
+  if (hits.length !== 1) return { count: hits.length };
+  return { count: 1, index: base + hits[0].index, length: hits[0][0].length };
+}
+
+export function patchedSource(original, m) {
+  const hit = locate(original, m.find, m.within);
+  if (hit.count !== 1)
+    throw new Error(
+      `"find" occurs ${hit.count} times in ${m.file}, must be exactly 1`,
+    );
+  return (
+    original.slice(0, hit.index) +
+    m.replace +
+    original.slice(hit.index + hit.length)
+  );
+}

package/mutations/project.mjs

@@ -0,0 +1,23 @@
+// The mutation engine's injection point. The engine modules read the project's Setup through
+// `projectSetup()`; whoever drives them (the bin, a script, a test) binds one first with
+// `bindSetup(setupOf(gate))`. This module imports nothing outside `node:`: the pack is in the
+// gate config's import graph, so importing the config from here would deadlock.
+let bound = null;
+
+/** Bind the Setup the engine modules will read; returns it. */
+export function bindSetup(setup) {
+  bound = setup;
+  return setup;
+}
+
+function notBound() {
+  return new Error(
+    'mutations: no setup bound. Run ticket-gate mutate or ticket-gate mutations, or call bindSetup(setupOf(gate)) first',
+  );
+}
+
+/** The bound Setup. Throws when nothing was bound. */
+export const projectSetup = () => {
+  if (bound === null) throw notBound();
+  return bound;
+};

package/mutations/registry.mjs

@@ -0,0 +1,173 @@
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, relative } from 'node:path';
+
+import { ROOT } from '../root.mjs';
+import { treeHash } from '../tree.mjs';
+import { projectSetup } from './project.mjs';
+
+// jest, vitest and playwright match -t / -g against the FULL name (describe
+// titles + test title), so a leading ^ selects nothing. node's pattern matches
+// each level's own name and is exempt.
+export const CARET_FILTER =
+  /(?:^|\s)(?:-t|--testNamePattern|-g|--grep)(?:=|\s+)['"]?\^/;
+export const CARET_HINT =
+  '"test" filter starts with ^: jest and vitest -t (and playwright -g) match the full name (describe titles + test title), so a leading ^ selects no test; drop the ^';
+
+export const KEY_RE = /^[A-Z][A-Za-z0-9-]*\/[A-Z]{1,2}\d+$/;
+export const FILTER_RE =
+  /(?:^|\s)(?:-t|--testNamePattern|-g|--grep|--test-name-pattern)(?:=|\s)|(?<=\bdeno test\b.*)\s--filter(?:=|\s)/;
+
+/** Orders keys `<ID>/<Mn>`: digit runs numerically, everything else by code unit. */
+export function compareKeys(a, b) {
+  const parts = (k) => k.match(/\d+|\D+/g) ?? [];
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < Math.min(pa.length, pb.length); i++) {
+    const x = pa[i];
+    const y = pb[i];
+    if (x === y) continue;
+    const dx = /^\d/.test(x);
+    const dy = /^\d/.test(y);
+    if (dx && dy) {
+      const d = Number(x) - Number(y);
+      if (d !== 0) return d < 0 ? -1 : 1;
+      continue;
+    }
+    return x < y ? -1 : 1;
+  }
+  return pa.length === pb.length ? 0 : pa.length < pb.length ? -1 : 1;
+}
+
+/** The repo-relative area file an entry belongs in: its kind's `area`, else the setup's. */
+export function areaFor(entry, setup = projectSetup()) {
+  const kind = setup.kinds.get(entry.kind);
+  return kind?.area ? kind.area(entry, setup.dir) : setup.area(entry);
+}
+
+const lineOf = (text, needle) => {
+  const i = text.indexOf(needle);
+  return i === -1 ? 1 : text.slice(0, i).split('\n').length;
+};
+
+function walkJson(dir, out = []) {
+  let names;
+  try {
+    names = readdirSync(dir).sort();
+  } catch {
+    return out;
+  }
+  for (const n of names) {
+    const p = join(dir, n);
+    if (statSync(p).isDirectory()) walkJson(p, out);
+    else if (n.endsWith('.json')) out.push(p);
+  }
+  return out;
+}
+
+function addArea(entries, errors, rel, text) {
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch (err) {
+    errors.push(`${rel}: not valid JSON (${err.message})`);
+    return;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    errors.push(`${rel}: must be an object of { "<ID>/<Mn>": entry }`);
+    return;
+  }
+  for (const [key, entry] of Object.entries(obj)) {
+    if (entries.has(key)) {
+      errors.push(
+        `${rel}: duplicate key ${key} (also in ${entries.get(key).path})`,
+      );
+      continue;
+    }
+    entries.set(key, { path: rel, line: lineOf(text, `"${key}"`), entry });
+  }
+}
+
+/** The registry in the working tree: { entries: Map<key, { path, line, entry }>, errors }. */
+export function loadRegistry(root = ROOT, setup = projectSetup()) {
+  const entries = new Map();
+  const errors = [];
+  for (const abs of walkJson(join(root, setup.dir))) {
+    const rel = relative(root, abs);
+    addArea(entries, errors, rel, readFileSync(abs, 'utf8'));
+  }
+  return { entries, errors };
+}
+
+const gitAt = (root, args) =>
+  execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 512 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+/**
+ * The registry at a git ref. A ref without the registry folder is read by the
+ * setup's `legacy` reader (when it has one).
+ */
+export function registryAt(ref, root = ROOT, setup = projectSetup()) {
+  const entries = new Map();
+  const errors = [];
+  const ls = (pathspec) =>
+    gitAt(root, ['ls-tree', '-r', '-z', '--name-only', ref, '--', pathspec])
+      .split('\0')
+      .filter(Boolean);
+  const show = (path) => gitAt(root, ['show', `${ref}:${path}`]);
+  const areas = ls(setup.dir).filter((p) => p.endsWith('.json'));
+  if (areas.length) {
+    for (const p of areas) addArea(entries, errors, p, show(p));
+    return { entries, errors };
+  }
+  return setup.legacy ? setup.legacy.atRef(ref, root) : { entries, errors };
+}
+
+/** [key, entry][] of `<ticket>/*`, in compareKeys order, retired entries included. */
+export function entriesFor(registry, ticket) {
+  return [...registry.entries]
+    .filter(([k]) => k.startsWith(`${ticket}/`))
+    .sort(([a], [b]) => compareKeys(a, b))
+    .map(([k, v]) => [k, v.entry]);
+}
+
+/** The runnable spec for runMutations: live entries whose kind runs (no retired). */
+export function toSpec(pairs, ticket, setup = projectSetup()) {
+  return {
+    ticket,
+    mutations: pairs
+      .filter(([, e]) => !e.retired && setup.kinds.get(e.kind)?.runs !== false)
+      .map(([key, e]) => ({ id: key, ...e })),
+  };
+}
+
+const sortKeysDeep = (v) =>
+  Array.isArray(v)
+    ? v.map(sortKeysDeep)
+    : v && typeof v === 'object'
+      ? Object.fromEntries(
+          Object.keys(v)
+            .sort()
+            .map((k) => [k, sortKeysDeep(v[k])]),
+        )
+      : v;
+
+/** sha256 of the pairs with every object's keys sorted. */
+export function entriesDigest(pairs) {
+  return createHash('sha256')
+    .update(JSON.stringify(sortKeysDeep(pairs)))
+    .digest('hex');
+}
+
+/** The tree hash a ticket receipt binds: the registry folder is data, left out. */
+export function ticketTreeHash(setup = projectSetup()) {
+  return treeHash({ exclude: [`${setup.dir}/`] });
+}
+
+export { blockSpan, findPattern, locate, patchedSource } from './locate.mjs';
+export { addArea };