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

package/selection/value-rules.mjs

@@ -0,0 +1,142 @@
+import { listFiles, readText } from '../graph/js.mjs';
+import { lazyTs } from '../graph/typescript.mjs';
+
+const ts = lazyTs();
+
+export const FRAGMENT_MIN = 8;
+
+// ---------------------------------------------------------------- i18n value rule
+
+export class FullSignal extends Error {
+  constructor(path, rule) {
+    super(`${path}: ${rule}`);
+    this.path = path;
+    this.rule = rule;
+  }
+}
+
+export const unwrap = (e) => {
+  let x = e;
+  while (
+    x &&
+    (ts.isAsExpression(x) ||
+      ts.isSatisfiesExpression(x) ||
+      ts.isParenthesizedExpression(x))
+  )
+    x = x.expression;
+  return x;
+};
+
+/** The exported object literal of an i18n table as { map: dotted key -> value, outside }. */
+export function parseTable(text, path) {
+  const sf = ts.createSourceFile(
+    path,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  let obj = null;
+  for (const st of sf.statements) {
+    if (!ts.isVariableStatement(st)) continue;
+    if (!st.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
+      continue;
+    for (const d of st.declarationList.declarations) {
+      const init = unwrap(d.initializer);
+      if (init && ts.isObjectLiteralExpression(init)) obj = obj ?? init;
+    }
+  }
+  if (!obj) return null;
+  const map = new Map();
+  const walkObj = (o, prefix) => {
+    let i = 0;
+    for (const p of o.properties) {
+      const name =
+        ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) ||
+          ts.isStringLiteral(p.name) ||
+          ts.isNumericLiteral(p.name))
+          ? p.name.text
+          : null;
+      if (name === null) {
+        map.set(`${prefix}[${i++}:${p.getText(sf)}]`, {
+          nonLiteral: p.getText(sf),
+        });
+        continue;
+      }
+      const key = prefix ? `${prefix}.${name}` : name;
+      const v = unwrap(p.initializer);
+      if (ts.isStringLiteral(v) || ts.isNoSubstitutionTemplateLiteral(v))
+        map.set(key, v.text);
+      else if (ts.isObjectLiteralExpression(v)) walkObj(v, key);
+      else map.set(key, { nonLiteral: v.getText(sf) });
+    }
+  };
+  walkObj(obj, '');
+  return {
+    map,
+    outside: text.slice(0, obj.getStart(sf)) + text.slice(obj.getEnd()),
+  };
+}
+
+/** Placeholder-free fragments of at least FRAGMENT_MIN characters. */
+export const fragmentsOf = (value) =>
+  value
+    .split(/\{[^}]*\}/)
+    .map((s) => s.trim())
+    .filter((s) => s.length >= FRAGMENT_MIN);
+
+// ---------------------------------------------------------------- object-table rule
+
+/** Specs holding a changed or removed table key's key, value, or a long fragment of it. */
+function tableSpecs(path, ctx) {
+  const { root, cfg } = ctx;
+  const specDir = cfg.specs.dir;
+  const headText = ctx.readText(path);
+  const baseText = ctx.readBase(path);
+  const head = headText === null ? null : parseTable(headText, path);
+  const old = baseText === null ? null : parseTable(baseText, path);
+  if (!head || !old || head.outside !== old.outside)
+    throw new FullSignal(path, 'i18n-structure');
+  const needles = new Set();
+  for (const [key, oldValue] of old.map) {
+    const now = head.map.get(key);
+    if (now !== undefined && JSON.stringify(now) === JSON.stringify(oldValue))
+      continue;
+    if (
+      typeof oldValue !== 'string' ||
+      (now !== undefined && typeof now !== 'string')
+    )
+      throw new FullSignal(path, 'i18n-structure');
+    needles.add(key);
+    if (oldValue.length > 0) needles.add(oldValue);
+    for (const f of fragmentsOf(oldValue)) needles.add(f);
+  }
+  for (const [key, v] of head.map)
+    if (!old.map.has(key) && typeof v !== 'string')
+      throw new FullSignal(path, 'i18n-structure');
+  if (needles.size === 0) return [];
+  const hits = [];
+  for (const f of listFiles(
+    root,
+    specDir,
+    (p) => p.endsWith('.ts') && !(cfg.outside.testFile?.test(p) ?? false),
+  )) {
+    const text = readText(root, f) ?? '';
+    if (![...needles].some((n) => text.includes(n))) continue;
+    if (cfg.specs.match.test(f)) hits.push(f.slice(specDir.length + 1));
+    else hits.push(...ctx.graph().importersOf(f));
+  }
+  return hits;
+}
+
+/** The value rule for exported object-literal tables (today's i18n rule): only changed values select specs. */
+export function objectTable(tables) {
+  return {
+    name: 'object-table',
+    rule(path, ctx) {
+      if (!tables.includes(path)) return null;
+      return { specs: tableSpecs(path, ctx) };
+    },
+  };
+}

package/selection-config.mjs

@@ -0,0 +1,76 @@
+// The `selection` key of gate.config.mjs: the project values the e2e selection engine (./selection)
+// reads. Validated at load time; a bad value throws Error('gate.config: selection: <what>').
+// Graph sources, rules and test runners come from the config and from every pack's
+// selectionGraphs, selectionRules and testRunners hooks (config first, then packs in packs order).
+import { packHooksAll } from "./pack-hooks-all.mjs";
+import { ROOT } from "./root.mjs";
+import { SelectionConfigError, defineSelection } from "./selection/define.mjs";
+
+export const SELECTION_HOOKS = Object.freeze([
+  "selectionGraphs",
+  "selectionRules",
+  "testRunners",
+]);
+
+const KIND = {
+  selectionGraphs: "graph source",
+  selectionRules: "rule",
+  testRunners: "test runner",
+};
+
+/** `{ by, item }` for the config's own items then every pack's, each checked to be a named object. */
+function collect(hook, own, config, fail) {
+  const rows = [];
+  const add = (by, value) => {
+    for (const item of [].concat(value)) {
+      if (!item || typeof item !== "object" || typeof item.name !== "string")
+        fail(
+          "selection",
+          `${KIND[hook]} from ${by} must be an object with a string name`,
+        );
+      rows.push({ by, item });
+    }
+  };
+  if (own !== undefined) add("gate.config", own);
+  for (const { by, value } of packHooksAll(hook, config)) add(by, value);
+  const seen = new Map();
+  for (const { by, item } of rows) {
+    if (seen.has(item.name))
+      fail(
+        "selection",
+        `${KIND[hook]} "${item.name}" is given by ${seen.get(item.name)} and ${by}`,
+      );
+    seen.set(item.name, by);
+  }
+  return rows;
+}
+
+/** Validates `config.selection` and returns the defined selection; `fail(where, what)` throws. */
+export function selectionOf(config, fail) {
+  const sel = config.selection;
+  if (!sel || typeof sel !== "object" || Array.isArray(sel))
+    fail("selection", "must be an object");
+  const graphs = collect("selectionGraphs", sel.graphs, config, fail);
+  const rules = collect("selectionRules", sel.rules, config, fail);
+  const runners = collect("testRunners", undefined, config, fail);
+  let runner = sel.runner;
+  if (typeof runner === "string") {
+    const found = runners.find((r) => r.item.name === runner);
+    if (!found) {
+      fail("selection", `no test runner named "${runner}"`);
+    }
+    runner = found.item;
+  }
+  try {
+    return defineSelection({
+      ...sel,
+      root: sel.root ?? ROOT,
+      graphs: graphs.map((r) => r.item),
+      rules: rules.map((r) => r.item),
+      runner,
+    });
+  } catch (e) {
+    if (e instanceof SelectionConfigError) fail("selection", e.message);
+    throw e;
+  }
+}

package/serve.mjs

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { connect } from 'node:net';
+
+import { safeKillGroup } from './kill-group.mjs';
+import { LIMITS, tail } from './mutations/verdict.mjs';
+import { ROOT } from './root.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const connects = (host, port) =>
+  new Promise((resolve) => {
+    const s = connect({ host, port });
+    s.once('connect', () => (s.destroy(), resolve(true)));
+    s.once('error', () => (s.destroy(), resolve(false)));
+  });
+
+/** Is something listening on this port (IPv4 or IPv6 loopback)? */
+export const portInUse = async (port) =>
+  (await connects('127.0.0.1', port)) || (await connects('::1', port));
+
+const answers = (port) =>
+  fetch(`http://localhost:${port}`, { signal: AbortSignal.timeout(2000) })
+    .then(() => true)
+    .catch(() => false);
+
+// `opts.start` in its own process group; ready when `opts.port` answers.
+export async function startWebServer(opts, onSpawn) {
+  const c = spawn('bash', ['-lc', opts.start], {
+    cwd: ROOT,
+    env: { ...process.env, ...opts.env },
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let out = '';
+  let exited = false;
+  c.stdout.on('data', (d) => (out += d));
+  c.stderr.on('data', (d) => (out += d));
+  const gone = new Promise((resolve) => {
+    c.on('close', () => ((exited = true), resolve()));
+    c.on('error', (err) => ((out += String(err)), (exited = true), resolve()));
+  });
+  const stop = async () => {
+    if (!exited) {
+      safeKillGroup(c.pid, 'SIGTERM');
+      await Promise.race([gone, sleep(5000)]);
+    }
+    if (!exited) {
+      safeKillGroup(c.pid, 'SIGKILL');
+      await Promise.race([gone, sleep(2000)]);
+    }
+    for (let i = 0; i < 20 && (await portInUse(opts.port)); i++)
+      await sleep(250);
+  };
+  onSpawn?.(stop);
+  const died = () => exited;
+  const deadline = Date.now() + LIMITS.serve * 1000;
+  while (Date.now() < deadline && !exited) {
+    if (await answers(opts.port)) return { ok: true, out, stop, died };
+    await sleep(500);
+  }
+  return {
+    ok: false,
+    out: out || `no answer within ${LIMITS.serve} s`,
+    stop,
+    died,
+  };
+}
+
+/** Why a port cannot be served on. Shared with the mutation harness. */
+export const portBusy = (port) =>
+  `port ${port} is already in use: a stale server would serve old code. Stop it (lsof -i :${port}), then re-run.`;
+
+// Detached, in its own process group, so the timeout can kill the whole build (a compound
+// command forks, and a surviving worker holds the pipes open). A terminal Ctrl-C no longer
+// reaches it, so a SIGINT forwarder does, and is removed when the build ends.
+// How long a build gets to close after SIGINT before its group is killed.
+const INTERRUPT_GRACE_MS = 5000;
+
+function runBuild(build, env) {
+  return new Promise((resolve) => {
+    const c = spawn('bash', ['-lc', build], {
+      cwd: ROOT,
+      env: { ...process.env, ...env },
+      detached: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    let settled = false;
+    let escalation = null;
+    const forward = () => {
+      if (escalation !== null) return;
+      safeKillGroup(c.pid, 'SIGINT');
+      // Our listener replaced the default exit; keep it when nobody else handles the signal.
+      const exits = process.listenerCount('SIGINT') === 1;
+      // A build that ignores SIGINT must not outlive the run: kill the group after a bounded wait.
+      escalation = setTimeout(() => {
+        safeKillGroup(c.pid, 'SIGKILL');
+        if (exits) process.exit(130);
+      }, INTERRUPT_GRACE_MS);
+      if (exits)
+        c.once('close', () => {
+          safeKillGroup(c.pid, 'SIGKILL');
+          process.exit(130);
+        });
+    };
+    const done = (r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (escalation !== null) clearTimeout(escalation);
+      process.removeListener('SIGINT', forward);
+      resolve(r);
+    };
+    process.on('SIGINT', forward);
+    const timer = setTimeout(() => {
+      safeKillGroup(c.pid, 'SIGKILL');
+      done({ code: 124, out: `${out}timed out after ${LIMITS.webBuild} s` });
+    }, LIMITS.webBuild * 1000);
+    c.stdout.on('data', (d) => (out += d));
+    c.stderr.on('data', (d) => (out += d));
+    c.on('error', (err) => done({ code: 1, out: String(err) }));
+    c.on('close', (code) => done({ code: code ?? 1, out }));
+  });
+}
+
+/**
+ * Refuses a busy port, builds, starts the server and waits until `port` answers.
+ * `onSpawn(stop)` runs right after the spawn, so a Ctrl-C during startup can stop it.
+ * Throws on a busy port, a failed build or a server that never answers.
+ * @returns {Promise<{ stop: () => Promise<void> }>}
+ */
+export async function serve({ build, start, port, env }, { onSpawn } = {}) {
+  if (await portInUse(port)) throw new Error(portBusy(port));
+  const b = await runBuild(build, env);
+  if (b.code !== 0) throw new Error(`build failed (${build}): ${tail(b.out)}`);
+  const server = await startWebServer({ start, port, env }, onSpawn);
+  if (!server.ok) {
+    await server.stop();
+    throw new Error(`server did not start on port ${port}: ${tail(server.out)}`);
+  }
+  return { stop: server.stop };
+}

package/summary.mjs

@@ -0,0 +1,34 @@
+/** `(1m05s)`: whole seconds, rounded, seconds padded to two digits. */
+export function formatMs(ms) {
+  const total = Math.round(ms / 1000);
+  return `(${Math.floor(total / 60)}m${String(total % 60).padStart(2, '0')}s)`;
+}
+
+/** The lines inside the paste block's fence: one per result in run order, then one Not selected line. */
+export function renderSummary(results, notRun, { failures } = {}) {
+  const lines = results.map(
+    (r) =>
+      `${r.cmd}: ${r.summary}${r.ms === undefined ? '' : ` ${formatMs(r.ms)}`}${r.status === 'pass' ? '' : `  [${r.status.toUpperCase()}]`}`,
+  );
+  if (notRun.length)
+    lines.push(`Not selected: ${notRun.map((s) => s.id).join(', ')}`);
+  if (failures) lines.push(`Failures: ${failures}`);
+  return lines;
+}
+
+export const oneLine = (out) =>
+  String(out ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(' | ');
+
+const ERROR_LINE = /error|fail|stale|vanish|invalid|differ|drop|unguarded/i;
+
+export const firstError = (out) => {
+  const lines = String(out)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  return lines.find((l) => ERROR_LINE.test(l)) ?? lines[0] ?? 'failed';
+};

package/tree.mjs

@@ -0,0 +1,211 @@
+// Identifies the current working tree, so a verification receipt cannot outlive
+// the code it verified.
+//
+// The hash covers every path this branch changes or adds (measured from the
+// merge-base with `main`, not HEAD, so committing does not empty it), outside
+// the ticket docs. Each path contributes only its final state: mode plus git blob id
+// of the working-tree bytes, `-` if deleted, `d` for a directory. Committing,
+// staging or leaving a file untracked therefore does not move the hash; a
+// changed byte, a changed execute bit, a deletion or a rename does.
+//
+// treeHashAt(commit) is the same hash computed from a commit's tree instead of
+// the working tree, so ticket-gate can ask "was the tree a DoD tick was
+// committed on ever verified green?". verify-ticket records each green run's
+// hash in .turbo/ticket-verify-history.jsonl (readHistory reads it back).
+import { execFileSync, execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT } from './root.mjs';
+
+// `.ticket-gate/tree.json` { exclude: [dir, ...] }: paths under these are outside the tree hash.
+// Read once; a missing or unreadable file excludes nothing (stricter: more paths are hashed).
+let EXCLUDE = null;
+export function treeExclude() {
+  if (EXCLUDE) return EXCLUDE;
+  try {
+    const raw = JSON.parse(
+      readFileSync(join(ROOT, '.ticket-gate', 'tree.json'), 'utf8'),
+    );
+    EXCLUDE = Array.isArray(raw.exclude)
+      ? raw.exclude.filter((d) => typeof d === 'string' && d)
+      : [];
+  } catch {
+    EXCLUDE = [];
+  }
+  return EXCLUDE;
+}
+// prettier-ignore
+const excluded = (p) => treeExclude().some((d) => p === d || p.startsWith(`${d}/`));
+
+const sh = (cmd) =>
+  execSync(cmd, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    // The default 1 MiB overflows (ENOBUFS) on a large unrelated diff.
+    maxBuffer: 512 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+/**
+ * The ref this branch's work is measured from: the merge-base with `main`
+ * (or `origin/main`) when it exists, else HEAD. On `main` itself the two are
+ * the same commit.
+ */
+export function baseRef(preferred) {
+  for (const ref of [
+    ...(preferred ? [preferred] : []),
+    'main',
+    'origin/main',
+  ]) {
+    try {
+      return sh(`git merge-base ${ref} HEAD`).trim();
+    } catch {
+      /* ref missing: try the next one */
+    }
+  }
+  return 'HEAD';
+}
+
+const nul = (cmd) => sh(cmd).split('\0').filter(Boolean);
+
+export function untrackedFiles() {
+  return nul('git ls-files -z --others --exclude-standard');
+}
+
+/**
+ * Paths this branch changes: committed since the merge-base with main, plus
+ * the working tree, plus untracked files. `base` overrides the merge-base.
+ * `--no-renames` lists both sides of a rename; `-z` keeps odd names unquoted.
+ */
+export function changedPaths(base) {
+  const ref = base ?? baseRef();
+  const tracked = nul(`git diff -z --name-only --no-renames ${ref}`);
+  return [...new Set([...tracked, ...untrackedFiles()])].sort();
+}
+
+const blobId = (bytes) =>
+  createHash('sha1')
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest('hex');
+
+function stateOf(path) {
+  let st;
+  try {
+    st = lstatSync(join(ROOT, path));
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return '-';
+    throw err;
+  }
+  if (st.isSymbolicLink())
+    return `120000 ${blobId(Buffer.from(readlinkSync(join(ROOT, path))))}`;
+  if (st.isDirectory()) return 'd';
+  const mode = st.mode & 0o111 ? '100755' : '100644';
+  return `${mode} ${blobId(readFileSync(join(ROOT, path)))}`;
+}
+
+/**
+ * Sorted (path, state) for every changed path outside the ticket docs. `base`
+ * overrides the merge-base; `exclude` is a list of path prefixes ending `/`
+ * that are left out as well (a project's registry data).
+ */
+export function treeEntries(base = baseRef(), { exclude = [] } = {}) {
+  return changedPaths(base)
+    .filter((p) => !excluded(p) && !exclude.some((x) => p.startsWith(x)))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+    .map((p) => [p, stateOf(p)]);
+}
+
+function digest(entries) {
+  const h = createHash('sha256');
+  for (const [path, state] of entries) h.update(`${path}\0${state}\n`);
+  return h.digest('hex');
+}
+
+export function treeHash({ exclude = [] } = {}) {
+  return digest(treeEntries(baseRef(), { exclude }));
+}
+
+export const HISTORY_REL = '.turbo/ticket-verify-history.jsonl';
+
+const gitZ = (args) =>
+  execFileSync('git', args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    maxBuffer: 512 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+    .split('\0')
+    .filter(Boolean);
+
+/**
+ * Sorted [path, state] for `git diff -z --name-only --no-renames <base> <commit>`
+ * outside the ticket docs, states read from <commit> (same strings as stateOf).
+ */
+export function treeEntriesAt(commit, base = baseRef()) {
+  for (const ref of [commit, base])
+    if (typeof ref !== 'string' || ref === '' || ref.startsWith('-'))
+      throw new Error('treeHashAt: bad ref');
+  // prettier-ignore
+  const paths = gitZ(['diff', '-z', '--name-only', '--no-renames', base, commit]).filter((p) => !excluded(p));
+  const states = new Map();
+  for (const rec of gitZ(['ls-tree', '-r', '-t', '-z', commit])) {
+    const tab = rec.indexOf('\t');
+    const [mode, type, oid] = rec.slice(0, tab).split(' ');
+    states.set(rec.slice(tab + 1), type === 'blob' ? `${mode} ${oid}` : 'd');
+  }
+  return paths
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+    .map((p) => [p, states.get(p) ?? '-']);
+}
+
+/** digest(treeEntriesAt(commit, base)); equals treeHash() on a clean tree at HEAD. */
+export function treeHashAt(commit, base = baseRef()) {
+  return digest(treeEntriesAt(commit, base));
+}
+
+/**
+ * Entries of the history file in file order. Missing file -> []. A blank line,
+ * a line that is not JSON, or one without a string treeHash is skipped.
+ */
+export function readHistory(path = join(ROOT, HISTORY_REL)) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const raw of readFileSync(path, 'utf8').split('\n')) {
+    if (raw.trim() === '') continue;
+    let entry;
+    try {
+      entry = JSON.parse(raw);
+    } catch {
+      continue; // a corrupt line is skipped, never fatal
+    }
+    if (entry && typeof entry.treeHash === 'string') out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * sha of the commit that last changed line `line` (1-based) of working-tree
+ * `file`; null when uncommitted, untracked, or on any git error.
+ */
+export function lineCommit(file, line) {
+  try {
+    const first = execFileSync(
+      'git',
+      ['blame', '--porcelain', '-L', `${line},${line}`, '--', file],
+      {
+        cwd: ROOT,
+        encoding: 'utf8',
+        maxBuffer: 512 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    ).split('\n')[0];
+    const sha = /^([0-9a-f]{40}) /.exec(first)?.[1];
+    if (!sha) return null;
+    if (/^0{40}$/.test(sha)) return null;
+    return sha;
+  } catch {
+    return null; // untracked file, or no git: never settled
+  }
+}