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

package/selection/check.mjs

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { listFiles } from '../graph/js.mjs';
+import { projectSelection } from './project.mjs';
+
+/**
+ * Every spec declares known areas on line 1, no new ticket-named spec, the smoke cap, then each
+ * config check (route table, drift guards).
+ * @param {string} root repo root @returns {string[]} one problem per line, sorted
+ */
+export function checkE2eAreas(root, cfg = projectSelection()) {
+  const problems = [];
+  const known = cfg.areas === null ? null : new Set(cfg.areas);
+  const { dir, match, header, ticketNamed, grandfathered, smokeMax } =
+    cfg.specs;
+  const specs = listFiles(root, dir, (p) => match.test(p));
+  let smoke = 0;
+  for (const p of specs) {
+    const name = p.slice(dir.length + 1);
+    const text = readFileSync(join(root, p), 'utf8');
+    const m = header.exec(text.split('\n', 1)[0].replace(/\r$/, ''));
+    if (!m) problems.push(`missing-header ${name}`);
+    else if (known)
+      for (const id of m[1].split(', '))
+        if (!known.has(id)) problems.push(`unknown-area ${name} ${id}`);
+    const base = name.split('/').pop();
+    if (ticketNamed?.test(base) && !grandfathered.has(base))
+      problems.push(`ticket-named ${name}`);
+    smoke += text.split(`'@smoke'`).length - 1;
+  }
+  if (smoke > smokeMax) problems.push(`smoke-cap ${smoke}`);
+
+  let entries = 0;
+  for (const check of cfg.checks) {
+    const out = check.run(root);
+    problems.push(...out.problems);
+    entries += out.entries ?? 0;
+  }
+  problems.sort();
+  Object.defineProperty(problems, 'counts', {
+    value: { specs: specs.length, entries },
+  });
+  return problems;
+}

package/selection/cli.mjs

@@ -0,0 +1,267 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { buildGraph, readText } from '../graph/js.mjs';
+import { loadTimeUnits } from '../graph/load-time.mjs';
+import { SelectionConfigError } from './define.mjs';
+import { projectSelection } from './project.mjs';
+import { select, specHeaders } from './select.mjs';
+import { summarizeReport, testListLines } from '../runners/playwright.mjs';
+import { forFiles, forLines, testCounts } from './for.mjs';
+
+// ---------------------------------------------------------------- drift
+
+/** Pages a spec visited outside its header's areas, mapped by the config's `drift.map`. */
+export async function driftOf(report, headers, cfg = projectSelection()) {
+  if (!cfg.drift)
+    throw new SelectionConfigError('selection.drift is required for --drift');
+  return cfg.drift.map(summarizeReport(report).navigation, headers);
+}
+
+// ---------------------------------------------------------------- CLI
+
+/** `quiet` drops git's stderr (a `git show` of a path the base lacks prints a fatal line). */
+function git(root, args, quiet = false) {
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 1 << 28,
+    ...(quiet ? { stdio: ['ignore', 'pipe', 'ignore'] } : {}),
+  });
+}
+
+async function driftCli(file, cfg) {
+  let report;
+  try {
+    report = JSON.parse(readFileSync(resolve(cfg.root, file), 'utf8'));
+  } catch (e) {
+    console.error(
+      `${cfg.label}: cannot read ${file} (${e.message}). Run ${cfg.commands.verify} (it writes .turbo/e2e-report.json) or pass a Playwright JSON report.`,
+    );
+    return 2;
+  }
+  let drift;
+  try {
+    drift = await driftOf(report, specHeaders(cfg.root, cfg), cfg);
+  } catch (e) {
+    if (!(e instanceof SelectionConfigError)) throw e;
+    console.error(`${cfg.label}: ${e.message}`);
+    return 2;
+  }
+  for (const d of drift)
+    console.log(
+      `drift: ${d.file} visited ${d.pathname} (${d.area}) not in its header`,
+    );
+  console.log(
+    drift.length === 0
+      ? 'drift: none'
+      : `drift: ${drift.length}. Add the area to that spec's // e2e-areas: header, then rerun the gate.`,
+  );
+  return drift.length === 0 ? 0 : 1;
+}
+
+/** Files every shell page evaluates that hold load-time code. */
+function loadTimeCli(cfg) {
+  const root = cfg.root;
+  const g = buildGraph(root, cfg);
+  const rows = [];
+  let outside = 0;
+  for (const f of g.evaluationSet()) {
+    const text = readText(root, f);
+    if (text === null) continue;
+    const n = loadTimeUnits(text, f).filter((u) => u.loadTime).length;
+    if (n === 0) continue;
+    const shell = g.reach(f).areas.has('*');
+    if (!shell) outside += 1;
+    rows.push(`${f} ${n}${shell ? ' shell' : ''}`);
+  }
+  for (const r of rows) console.log(r);
+  console.log(
+    `load-time: ${rows.length} files in E (${outside} outside the shell closure)`,
+  );
+  return 0;
+}
+
+/** R9: the selection for each of the last n first-parent merges touching apps/web, graph and headers from HEAD. */
+function replayCli(rev, count, cfg) {
+  const t0 = Date.now();
+  const root = cfg.root;
+  const merges = git(root, [
+    'log',
+    '--first-parent',
+    '--merges',
+    '--reverse',
+    `--max-count=${count}`,
+    '--format=%h%x09%s',
+    `${rev}`,
+    '--',
+    ...cfg.replayPaths,
+  ])
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => l.split('\t'));
+  // --reverse with --max-count keeps the newest n, printed oldest first.
+  const graph = buildGraph(root, cfg);
+  let full = 0;
+  for (const [sha, subject] of merges) {
+    const changed = git(root, [
+      'diff',
+      '--name-only',
+      '--no-renames',
+      `${sha}^1`,
+      sha,
+    ])
+      .split('\n')
+      .filter(Boolean);
+    const readBase = (p) => {
+      try {
+        return git(root, ['show', `${sha}^1:${p}`], true);
+      } catch {
+        return null;
+      }
+    };
+    const sel = select({ root, changed, readBase, graph, config: cfg });
+    if (sel.mode === 'full') full += 1;
+    const gone =
+      sel.mode === 'full' && sel.why.includes(': ')
+        ? !existsSync(join(root, sel.why.split(': ')[0]))
+        : false;
+    const title = subject
+      .replace(/^Merge pull request /, '')
+      .replace(/ from [^/]+\//, ' ');
+    console.log(
+      `${sha} ${title} -> ${sel.mode}: ${sel.why}${gone ? ' (absent at HEAD)' : ''}`,
+    );
+  }
+  console.log(`full: ${full} of ${merges.length}`);
+  console.log(`time: ${Date.now() - t0} ms`);
+  return 0;
+}
+
+function forCli(forArg, baseArg, budgetArg, base, usage, cfg) {
+  const root = cfg.root;
+  const files = forArg.slice('--for='.length).split(',').filter(Boolean);
+  const budget = budgetArg ? Number(budgetArg.slice('--budget='.length)) : 150;
+  if (files.length === 0 || !Number.isInteger(budget) || budget < 1) {
+    console.error(
+      `${cfg.label}: --for needs files and a positive budget. ${usage}`,
+    );
+    return 2;
+  }
+  const rev = baseArg ? baseArg.slice('--base='.length) : base;
+  const read = (p) => {
+    try {
+      return git(root, ['show', `${rev}:${p}`]);
+    } catch {
+      return null;
+    }
+  };
+  let counts;
+  try {
+    counts = testCounts(cfg.runner.list(root));
+  } catch (e) {
+    console.error(
+      `${cfg.label}: cannot list tests (${e.message}). Run: ${cfg.runner.command} --list`,
+    );
+    return 2;
+  }
+  const result = forFiles({
+    root,
+    files,
+    readBase: read,
+    counts,
+    budget,
+    config: cfg,
+  });
+  for (const l of forLines(result, budget)) console.log(l);
+  return 0;
+}
+
+export async function main(argv, cfg = projectSelection()) {
+  const root = cfg.root;
+  const { baseRef, changedPaths } = await import('../tree.mjs');
+  const base = baseRef();
+  const readBase = (p) => {
+    try {
+      return git(root, ['show', `${base}:${p}`]);
+    } catch {
+      return null;
+    }
+  };
+  const testList = argv.find(
+    (a) => a === '--test-list' || a.startsWith('--test-list='),
+  );
+  const driftArg = argv.find((a) => a.startsWith('--drift='));
+  const replayArg = argv.find((a) => a.startsWith('--replay='));
+  const countArg = argv.find((a) => a.startsWith('--count='));
+  const loadTimeArg = argv.find((a) => a === '--load-time');
+  const forArg = argv.find((a) => a.startsWith('--for='));
+  const budgetArg = argv.find((a) => a.startsWith('--budget='));
+  const baseArg = argv.find((a) => a.startsWith('--base='));
+  const unknown = argv.filter(
+    (a) =>
+      a !== testList &&
+      a !== driftArg &&
+      a !== replayArg &&
+      a !== countArg &&
+      a !== loadTimeArg &&
+      a !== forArg &&
+      a !== budgetArg &&
+      a !== baseArg,
+  );
+  const usage = `Usage: ${cfg.commands.self} [--test-list[=<out>] | --drift=<report.json> | --replay=<rev> --count=<n> | --load-time | --for=<files> [--budget=<tests>] [--base=<rev>]]`;
+  if (unknown.length > 0 || (countArg && !replayArg)) {
+    console.error(
+      `${cfg.label}: unknown argument ${unknown[0] ?? countArg}. ${usage}`,
+    );
+    return 2;
+  }
+  const others = [testList, driftArg, replayArg, loadTimeArg].some(Boolean);
+  if ((!forArg && (budgetArg || baseArg)) || (forArg && others)) {
+    console.error(
+      `${cfg.label}: --for stands alone (--budget and --base need it). ${usage}`,
+    );
+    return 2;
+  }
+  if (forArg) return forCli(forArg, baseArg, budgetArg, base, usage, cfg);
+  if (loadTimeArg) return loadTimeCli(cfg);
+  if (driftArg) return driftCli(driftArg.slice('--drift='.length), cfg);
+  if (replayArg) {
+    const count = countArg ? Number(countArg.slice('--count='.length)) : 19;
+    if (!Number.isInteger(count) || count < 1) {
+      console.error(
+        `${cfg.label}: --count must be a positive integer. ${usage}`,
+      );
+      return 2;
+    }
+    return replayCli(replayArg.slice('--replay='.length), count, cfg);
+  }
+  const t0 = Date.now();
+  const selection = select({
+    root,
+    changed: changedPaths(base),
+    readBase,
+    config: cfg,
+  });
+  if (!testList) {
+    console.log(`${selection.mode}: ${selection.why} (${Date.now() - t0} ms)`);
+    for (const s of selection.specs) console.log(`  ${s}`);
+    return 0;
+  }
+  if (selection.mode === 'full') {
+    console.log(`full: ${selection.why}`);
+    return 0;
+  }
+  const out = resolve(
+    root,
+    testList.split('=')[1] ?? '.turbo/e2e-selection.txt',
+  );
+  const lines = testListLines(cfg.runner.list(root), selection) ?? [];
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${lines.join('\n')}\n`);
+  console.log(
+    `${selection.why}; ${lines.length} tests -> ${relative(root, out)}`,
+  );
+  return 0;
+}

package/selection/define.mjs

@@ -0,0 +1,55 @@
+/**
+ * The selection config. `defineSelection(input)` fills the defaults and rejects a
+ * config that has no graph source or no spec location, so a wrong config fails at load, not mid-run.
+ * Dependency-free Node ESM.
+ */
+
+export class SelectionConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SelectionConfigError';
+  }
+}
+
+const missing = (key) =>
+  new SelectionConfigError(`selection.${key} is required`);
+
+export function defineSelection(input = {}) {
+  const specs = input.specs ?? {};
+  if (!specs.dir) throw missing('specs.dir');
+  if (!specs.match) throw missing('specs.match');
+  if (!specs.header) throw missing('specs.header');
+  const out = {
+    label: 'e2e-select',
+    root: process.cwd(),
+    areas: null,
+    ...input,
+    specs: {
+      setup: new Set(),
+      smokeMax: Infinity,
+      ticketNamed: null,
+      grandfathered: new Set(),
+      ...specs,
+    },
+    outside: {
+      prefixes: [],
+      rootRe: null,
+      testFile: null,
+      reach: [],
+      ...input.outside,
+    },
+    triggers: input.triggers ?? [],
+    ignored: input.ignored ?? [],
+    rules: input.rules ?? [],
+    unreachedOk: input.unreachedOk ?? [],
+    checks: input.checks ?? [],
+    runner: input.runner ?? null,
+    locale: input.locale ?? null,
+    drift: input.drift ?? null,
+    replayPaths: input.replayPaths ?? [],
+    commands: input.commands ?? {},
+  };
+  if (!Array.isArray(out.graphs) || out.graphs.length === 0)
+    throw missing('graphs');
+  return out;
+}

package/selection/for.mjs

@@ -0,0 +1,235 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { buildGraph, listFiles, readText } from '../graph/js.mjs';
+import { lazyTs } from '../graph/typescript.mjs';
+import { parseTable } from './value-rules.mjs';
+import { projectSelection } from './project.mjs';
+import { select, specHeaders } from './select.mjs';
+
+const ts = lazyTs();
+
+// ---------------------------------------------------------------- --for
+
+const LOCATOR_ATTRS = ['role', 'aria-label', 'data-testid', 'data-slot'];
+
+/** Per-file test counts from a `playwright test --list --reporter=json` listing. */
+export function testCounts(listJson) {
+  const counts = new Map();
+  const visit = (suites) => {
+    for (const s of suites ?? []) {
+      for (const spec of s.specs ?? []) {
+        const file = spec.file ?? s.file ?? '';
+        counts.set(file, (counts.get(file) ?? 0) + (spec.tests ?? []).length);
+      }
+      visit(s.suites);
+    }
+  };
+  visit(listJson?.suites);
+  return counts;
+}
+
+/** Literal attribute values and t('key') keys of a TSX text. */
+function locatorsIn(text) {
+  const values = new Set();
+  const keys = new Set();
+  if (text === null) return { values, keys };
+  const sf = ts.createSourceFile(
+    'x.tsx',
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const visit = (n) => {
+    if (ts.isJsxAttribute(n) && LOCATOR_ATTRS.includes(n.name.getText(sf))) {
+      let v = n.initializer;
+      if (v && ts.isJsxExpression(v)) v = v.expression;
+      if (v && (ts.isStringLiteral(v) || ts.isNoSubstitutionTemplateLiteral(v)))
+        values.add(v.text);
+    } else if (
+      ts.isCallExpression(n) &&
+      ts.isIdentifier(n.expression) &&
+      n.expression.text === 't' &&
+      n.arguments[0] &&
+      ts.isStringLiteral(n.arguments[0])
+    )
+      keys.add(n.arguments[0].text);
+    ts.forEachChild(n, visit);
+  };
+  visit(sf);
+  return { values, keys };
+}
+
+/** Locator values present in baseText and absent from headText, sorted. */
+export function removedLocators(baseText, headText, en) {
+  const was = locatorsIn(baseText);
+  const now = locatorsIn(headText);
+  const removed = new Set();
+  for (const v of was.values) if (!now.values.has(v)) removed.add(v);
+  for (const key of was.keys) {
+    if (now.keys.has(key)) continue;
+    const enValue = en.get(key);
+    if (typeof enValue === 'string') removed.add(enValue);
+  }
+  return [...removed].filter((v) => v.length > 0).sort();
+}
+
+/** The narrow run for named files (a dev aid; the gate's selection is untouched). */
+export function forFiles({
+  root: rootArg,
+  files,
+  readBase = () => null,
+  counts,
+  budget = 150,
+  graph = null,
+  config = null,
+}) {
+  const cfg = config ?? projectSelection();
+  const root = rootArg ?? cfg.root;
+  const specDir = cfg.specs.dir;
+  const enFile = cfg.locale?.table;
+  const g = graph ?? buildGraph(root, cfg);
+  const headers = specHeaders(root, cfg);
+  const gated = [];
+  const perFile = [];
+  const listed = new Map(); // spec -> areas declaring it (reached ones)
+  const reached = new Set();
+  const present = [];
+  for (const file of files) {
+    if (!existsSync(join(root, file))) {
+      perFile.push({ file, missing: true, areas: [] });
+      continue;
+    }
+    const one = select({
+      root,
+      changed: [file],
+      readBase,
+      graph: g,
+      config: cfg,
+    });
+    if (one.mode === 'full') {
+      gated.push({ file, rule: one.rule });
+      perFile.push({ file, rule: one.rule, areas: [] });
+      continue;
+    }
+    present.push(file);
+    perFile.push({ file, areas: [] });
+    for (const a of one.areas) reached.add(a);
+    for (const s of one.specs) {
+      const declared = (headers.get(s) ?? []).filter((a) =>
+        one.areas.includes(a),
+      );
+      listed.set(s, new Set([...(listed.get(s) ?? []), ...declared]));
+    }
+    perFile[perFile.length - 1].areas = one.areas;
+  }
+  const testsOf = (s) => counts.get(s) ?? 0;
+  const sizes = new Map();
+  for (const a of reached) {
+    const declaring = [...headers].filter(([, d]) => d.includes(a));
+    sizes.set(a, {
+      n: declaring.length,
+      tests: declaring.reduce((t, [s]) => t + testsOf(s), 0),
+    });
+  }
+  const groups = [...reached].map((area) => ({
+    area,
+    tests: sizes.get(area).tests,
+    size: sizes.get(area).n,
+    specs: [],
+  }));
+  groups.sort((a, b) => a.tests - b.tests || a.area.localeCompare(b.area));
+  const rank = new Map(groups.map((grp, i) => [grp.area, i]));
+  for (const f of perFile)
+    f.areas = [...f.areas].sort((a, b) => rank.get(a) - rank.get(b));
+  const direct = { area: 'direct', tests: 0, size: 0, specs: [] };
+  const placed = new Set();
+  for (const grp of groups)
+    for (const [s, declared] of [...listed].sort()) {
+      if (!declared.has(grp.area) || placed.has(s)) continue;
+      placed.add(s);
+      grp.specs.push({ spec: s, tests: testsOf(s) });
+    }
+  for (const [s] of [...listed].sort())
+    if (!placed.has(s)) direct.specs.push({ spec: s, tests: testsOf(s) });
+  for (const grp of [...groups, direct]) {
+    if (grp.area === 'direct') {
+      grp.size = grp.specs.length;
+      grp.tests = grp.specs.reduce((t, x) => t + x.tests, 0);
+    }
+  }
+  const out = direct.specs.length > 0 ? [direct, ...groups] : groups;
+  const all = [...listed.keys()].sort();
+  const tests = all.reduce((t, s) => t + testsOf(s), 0);
+  const overBudget = tests > budget;
+  let specs = all;
+  let filtered = null;
+  if (overBudget) {
+    const headEn = enFile ? readText(root, enFile) : null;
+    const baseEn = enFile ? readBase(enFile) : null;
+    const en = new Map([
+      ...(baseEn === null ? [] : (parseTable(baseEn, enFile)?.map ?? [])),
+      ...(headEn === null ? [] : (parseTable(headEn, enFile)?.map ?? [])),
+    ]);
+    const locators = [
+      ...new Set(
+        present.flatMap((f) =>
+          removedLocators(readBase(f), readText(root, f), en),
+        ),
+      ),
+    ].sort();
+    const keep = new Set();
+    const listedSet = new Set(all);
+    for (const f of listFiles(root, specDir, (p) => p.endsWith('.ts'))) {
+      const text = readText(root, f) ?? '';
+      if (!locators.some((l) => text.includes(l))) continue;
+      const rel = f.slice(specDir.length + 1);
+      for (const s of cfg.specs.match.test(f) ? [rel] : g.importersOf(f))
+        if (listedSet.has(s)) keep.add(s);
+    }
+    specs = all.filter((s) => keep.has(s));
+    filtered = { kept: specs.length, of: all.length, locators };
+  }
+  return {
+    gated,
+    files: perFile,
+    groups: out,
+    total: tests,
+    filtered,
+    specs,
+    command:
+      specs.length === 0
+        ? 'none'
+        : `${cfg.runner.command} ${specs.map((s) => `${cfg.runner.specPrefix}${s}`).join(' ')}`,
+  };
+}
+
+/** Printed lines for a ForResult. */
+export function forLines(result, budget) {
+  const lines = [];
+  for (const f of result.files) {
+    if (f.missing) lines.push(`${f.file}: not found`);
+    else if (f.rule) lines.push(`${f.file}: ${f.rule}: use the gate`);
+    else lines.push(`${f.file}: ${f.areas.join(', ') || 'no area'}`);
+  }
+  for (const grp of result.groups) {
+    lines.push(`  ${grp.area} ${grp.size} specs / ${grp.tests} tests`);
+    for (const s of grp.specs) lines.push(`    ${s.spec} (${s.tests})`);
+  }
+  const areas = result.groups.filter((x) => x.area !== 'direct').length;
+  const listedSpecs = result.groups.reduce((n, x) => n + x.specs.length, 0);
+  lines.push(
+    `for: ${result.files.length} files, ${areas} areas, ${listedSpecs} specs, ${result.total} tests (budget ${budget})`,
+  );
+  if (result.filtered) {
+    const f = result.filtered;
+    lines.push(
+      `filtered: ${f.kept} of ${f.of} specs by ${f.locators.length} removed locators`,
+      `locators: ${f.locators.join(', ')}`,
+      'limit: an implicit role change (a <button> becoming role="radio") is not a removed locator',
+    );
+  }
+  lines.push(result.command);
+  return lines;
+}

package/selection/graphs.mjs

@@ -0,0 +1,38 @@
+/**
+ * The union of graph sources. One source with no `expand` behaves exactly as that
+ * source. Dependency-free Node ESM.
+ */
+export function unionGraph(sources, root, cfg) {
+  const graphs = sources.map((s) => s.graph(root, cfg));
+  return {
+    get unresolved() {
+      for (const g of graphs) if (g.unresolved) return g.unresolved;
+      return null;
+    },
+    reach(path) {
+      const areas = new Set();
+      const specs = new Set();
+      const merge = (r) => {
+        for (const a of r.areas) areas.add(a);
+        for (const s of r.specs) specs.add(s);
+      };
+      const paths = [path, ...graphs.flatMap((g) => g.expand?.(path) ?? [])];
+      for (const g of graphs) for (const p of paths) merge(g.reach(p));
+      return { areas, specs };
+    },
+    expand: (path) => graphs.flatMap((g) => g.expand?.(path) ?? []),
+    evaluates: (path) => graphs.some((g) => g.evaluates?.(path) ?? false),
+    evaluationSet: () =>
+      [...new Set(graphs.flatMap((g) => g.evaluationSet?.() ?? []))].sort(),
+    newlyEvaluatedLoadTime(changed, readBase) {
+      const out = new Set();
+      for (const g of graphs)
+        for (const p of g.newlyEvaluatedLoadTime?.(changed, readBase) ?? [])
+          out.add(p);
+      return out;
+    },
+    importersOf: (file) => [
+      ...new Set(graphs.flatMap((g) => g.importersOf?.(file) ?? [])),
+    ],
+  };
+}

package/selection/project.mjs

@@ -0,0 +1,11 @@
+import { SelectionConfigError } from './define.mjs';
+
+/**
+ * The engine reads no project default: every caller passes its selection config. Reaching this
+ * function means a caller omitted it.
+ */
+export const projectSelection = () => {
+  throw new SelectionConfigError(
+    'no selection config: pass one (define it under `selection` in gate.config.mjs)',
+  );
+};