arkgate 4.8.24 → 4.8.26

package/bin/lib/invariant-probe-io.mjs

@@ -0,0 +1,165 @@
+/**
+ * Invariant probe evidence reader — Tooling (ADR 0039).
+ *
+ * Reads the committed `.ark/invariant-probe.json` (at most 1 MiB, 500 rows),
+ * hashes the inputs each row was bound to as they stand now, and attaches a
+ * `probe` summary to coverage rows. Read-only: this module never runs a test
+ * and never imports the runner or the workspace, so the gate entry points that
+ * load it (--promote, the policy delta, status, rules inventory) can never
+ * spawn anything. A malformed or stale artifact changes nothing.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  INVARIANT_PROBE_ARTIFACT_PATH,
+  INVARIANT_PROBE_MAX_BYTES,
+  invariantProbeIdentity,
+  probeRowLine,
+  probeRowStaleness,
+  probeStatusLabel,
+  readInvariantProbeArtifact,
+  summarizeProbeForCoverage,
+  verdictRefusesPromotion,
+} from './invariant-probe.mjs';
+
+export function sha256Text(text) {
+  return `sha256:${crypto.createHash('sha256').update(text).digest('hex')}`;
+}
+
+/** Content hash of a project file, or null when it is gone or outside the root. */
+export function hashProjectFile(root, rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return null;
+  const rootResolved = path.resolve(root);
+  const absolute = path.resolve(rootResolved, rel);
+  if (absolute !== rootResolved && !absolute.startsWith(`${rootResolved}${path.sep}`)) return null;
+  try {
+    return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(absolute)).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
+export function invariantIdentityHash(invariant) {
+  return sha256Text(invariantProbeIdentity(invariant));
+}
+
+/**
+ * @returns {{ present: false }
+ *          | { present: true, ok: false, note: string }
+ *          | { present: true, ok: true, artifact: object, note?: string }}
+ */
+function loadInvariantProbeArtifact(root) {
+  const absolute = path.join(root, INVARIANT_PROBE_ARTIFACT_PATH);
+  let stat;
+  try {
+    stat = fs.lstatSync(absolute);
+  } catch {
+    return { present: false };
+  }
+  const ignored = (why) => ({
+    present: true,
+    ok: false,
+    note: `${INVARIANT_PROBE_ARTIFACT_PATH} was ignored (${why}), so it changes no promotion.`,
+  });
+  if (!stat.isFile()) return ignored('not a regular file');
+  if (stat.size > INVARIANT_PROBE_MAX_BYTES) return ignored('larger than 1 MiB');
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  } catch {
+    return ignored('not valid JSON');
+  }
+  const read = readInvariantProbeArtifact(parsed);
+  if (!read.ok) return ignored(read.reason);
+  const skipped = read.droppedRows + read.truncatedRows;
+  return {
+    present: true,
+    ok: true,
+    artifact: read.artifact,
+    ...(skipped > 0
+      ? { note: `${skipped} row(s) in ${INVARIANT_PROBE_ARTIFACT_PATH} were malformed or past the 500-row cap and were ignored.` }
+      : {}),
+  };
+}
+
+/**
+ * Probe summary per catalogued invariant id, each judged fresh or stale
+ * against the tree as it stands now. Rows for ids no longer declared are ignored.
+ */
+function probeSummariesFor(root, catalogInvariants, loaded = loadInvariantProbeArtifact(root)) {
+  const byId = new Map();
+  if (!loaded.present || !loaded.ok) return byId;
+  const catalog = new Map((catalogInvariants ?? []).map((inv) => [inv.id, inv]));
+  const fileHashes = new Map();
+  const hashOf = (rel) => {
+    if (!fileHashes.has(rel)) fileHashes.set(rel, hashProjectFile(root, rel));
+    return fileHashes.get(rel);
+  };
+  for (const row of loaded.artifact.invariants) {
+    const inv = catalog.get(row.invariantId);
+    if (!inv || byId.has(row.invariantId)) continue;
+    const current = {
+      invariantHash: invariantIdentityHash(inv),
+      symbolFileHash: row.symbolFile ? hashOf(row.symbolFile) : null,
+      testHashes: Object.fromEntries(row.tests.map((test) => [test.path, hashOf(test.path)])),
+    };
+    const stale = probeRowStaleness(row, current, loaded.artifact.operatorSet);
+    byId.set(row.invariantId, { summary: summarizeProbeForCoverage(row, stale, loaded.artifact.probedOn), row });
+  }
+  return byId;
+}
+
+/** Coverage rows with `probe` attached where the artifact has a row. Absent artifact: rows unchanged. */
+export function attachProbeEvidence(root, coverageRows, catalogInvariants) {
+  const loaded = loadInvariantProbeArtifact(root);
+  if (!loaded.present) return { rows: coverageRows, loaded };
+  const summaries = probeSummariesFor(root, catalogInvariants, loaded);
+  const rows = (coverageRows ?? []).map((row) => {
+    const hit = summaries.get(row.invariantId);
+    return hit ? { ...row, probe: hit.summary } : row;
+  });
+  return { rows, loaded };
+}
+
+/**
+ * Status / inventory projection. Null when there is no artifact: absence is
+ * silent, so a project that never ran the probe sees nothing new.
+ */
+export function probeStatusSection(root, catalogInvariants) {
+  const loaded = loadInvariantProbeArtifact(root);
+  if (!loaded.present) return null;
+  if (!loaded.ok) return { notAScore: true, artifact: INVARIANT_PROBE_ARTIFACT_PATH, note: loaded.note, rows: [] };
+  const summaries = probeSummariesFor(root, catalogInvariants, loaded);
+  const rows = (catalogInvariants ?? []).map((inv) => {
+    const hit = summaries.get(inv.id);
+    const status = probeStatusLabel(hit?.summary);
+    const refuses = Boolean(hit?.summary.fresh && verdictRefusesPromotion(hit.summary.verdict));
+    return {
+      id: inv.id,
+      status,
+      ...(refuses ? { ruleId: 'INVARIANT_PROBE_SURVIVED', line: probeRowLine(hit.row) } : {}),
+      ...(hit?.summary.staleBecause ? { staleBecause: hit.summary.staleBecause } : {}),
+    };
+  });
+  return {
+    notAScore: true,
+    artifact: INVARIANT_PROBE_ARTIFACT_PATH,
+    probedOn: loaded.artifact.probedOn,
+    rows,
+    ...(loaded.note ? { note: loaded.note } : {}),
+  };
+}
+
+/** One status line per probed invariant, plus the artifact note. Empty without an artifact. */
+export function formatProbeStatusLines(section) {
+  if (!section) return [];
+  const lines = [];
+  if (section.note) lines.push(`ArkRules: ${section.note}`);
+  for (const row of section.rows ?? []) {
+    if (row.status === 'not run') continue;
+    if (row.ruleId) lines.push(`ArkRules: ${row.line} (${row.ruleId}, advisory; promotion refuses)`);
+    else lines.push(`ArkRules: ${row.id} probe: ${row.status}${row.staleBecause ? ` (${row.staleBecause[0]})` : ''}`);
+  }
+  return lines;
+}

package/bin/lib/invariant-probe-runner.mjs

@@ -0,0 +1,268 @@
+/**
+ * Runner adapters for the invariant probe — Tooling (ADR 0039).
+ *
+ * Detects the project's own runner (vitest, jest, node:test) from the nearest
+ * package.json, resolves its binary from the project, and runs it with
+ * `process.execPath`, an argv array and no shell. A timeout kills the whole
+ * process group. The environment is an allowlist: no tokens, no cloud
+ * credentials, proxies pointed at a dead port, HOME and TMPDIR inside the
+ * probe workspace. Best effort — not a sandbox.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const PROBE_RUNNERS = ['vitest', 'jest', 'node'];
+const TS_TEST = /\.[cm]?tsx?$/;
+const MAX_CAPTURE = 4 * 1024 * 1024;
+const PROBE_TIMEOUT_FLOOR_MS = 10_000;
+export const PROBE_TIMEOUT_CEILING_MS = 120_000;
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Nearest directory at or above `fromDir` (inside `root`) holding a package.json. */
+function nearestPackageRoot(root, fromDir) {
+  let dir = path.resolve(fromDir);
+  const top = path.resolve(root);
+  while (dir.startsWith(top)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    if (dir === top) break;
+    dir = path.dirname(dir);
+  }
+  return top;
+}
+
+function hasConfig(pkgRoot, stem) {
+  try {
+    return fs.readdirSync(pkgRoot).some((name) => name.startsWith(`${stem}.config.`));
+  } catch {
+    return false;
+  }
+}
+
+/** Runner ids the package declares, from `scripts.test` first, then dependency + config. */
+function runnerEvidence(pkgRoot) {
+  const pkg = readJson(path.join(pkgRoot, 'package.json')) ?? {};
+  const script = typeof pkg.scripts?.test === 'string' ? pkg.scripts.test : '';
+  const fromScript = [];
+  if (/\bvitest\b/.test(script)) fromScript.push('vitest');
+  if (/\bjest\b/.test(script)) fromScript.push('jest');
+  if (/\bnode\b[^&|;]*\s--test\b/.test(script)) fromScript.push('node');
+  if (fromScript.length > 0) return fromScript;
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  const fromDeps = [];
+  if (deps.vitest && hasConfig(pkgRoot, 'vitest')) fromDeps.push('vitest');
+  if (deps.jest && hasConfig(pkgRoot, 'jest')) fromDeps.push('jest');
+  return fromDeps;
+}
+
+function resolveBin(pkgRoot, id) {
+  if (id === 'node') return { bin: null, version: process.versions.node };
+  try {
+    const require = createRequire(path.join(pkgRoot, 'package.json'));
+    const manifestPath = require.resolve(`${id}/package.json`);
+    const manifest = readJson(manifestPath) ?? {};
+    const binField = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[id];
+    if (typeof binField !== 'string') return null;
+    return { bin: path.resolve(path.dirname(manifestPath), binField), version: manifest.version ?? null };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick the runner for a set of covering tests.
+ * @param {{ root: string, tests: string[], override?: string }} input tests are root-relative
+ */
+export function detectRunner({ root, tests, override }) {
+  const first = tests[0];
+  const pkgRoot = nearestPackageRoot(root, path.dirname(path.join(root, first ?? '.')));
+  const evidence = runnerEvidence(pkgRoot);
+  let id;
+  if (evidence.length === 1) {
+    id = evidence[0];
+    if (override && override !== id) {
+      return {
+        ok: false,
+        reasonCode: 'PROBE_RUNNER_UNKNOWN',
+        reason: `--runner ${override} does not match the runner this package declares (${id}). --runner only settles an unclear detection.`,
+      };
+    }
+  } else if (override && PROBE_RUNNERS.includes(override)) {
+    id = override;
+  } else {
+    return {
+      ok: false,
+      reasonCode: 'PROBE_RUNNER_UNKNOWN',
+      reason:
+        evidence.length > 1
+          ? `The package declares more than one test runner (${evidence.join(', ')}). Next: pass --runner ${evidence.join('|')}.`
+          : 'No test runner was found in package.json (scripts.test, or a vitest / jest dependency with its config file). Next: pass --runner vitest|jest|node.',
+    };
+  }
+  if (id === 'node' && tests.some((test) => TS_TEST.test(test))) {
+    return {
+      ok: false,
+      reasonCode: 'PROBE_RUNNER_UNSUPPORTED',
+      reason: 'node:test cannot run TypeScript test files without a loader, so the probe does not run them.',
+    };
+  }
+  const resolved = resolveBin(pkgRoot, id);
+  if (!resolved) {
+    return {
+      ok: false,
+      reasonCode: 'PROBE_RUNNER_UNKNOWN',
+      reason: `${id} is not installed in ${path.relative(root, pkgRoot) || '.'}, so the probe cannot run it.`,
+    };
+  }
+  return { ok: true, id, bin: resolved.bin, version: resolved.version, pkgRoot };
+}
+
+/** Allowlisted environment for the runner. Nothing else from the parent passes. */
+export function buildProbeEnv({ home, tmp, parentEnv = process.env }) {
+  const env = {
+    PATH: parentEnv.PATH ?? parentEnv.Path ?? '',
+    LANG: parentEnv.LANG ?? 'C.UTF-8',
+    TZ: 'UTC',
+    CI: '1',
+    NODE_ENV: 'test',
+    FORCE_COLOR: '0',
+    NO_COLOR: '1',
+    HOME: home,
+    USERPROFILE: home,
+    TMPDIR: tmp,
+    TMP: tmp,
+    TEMP: tmp,
+    HTTP_PROXY: 'http://127.0.0.1:9',
+    HTTPS_PROXY: 'http://127.0.0.1:9',
+    http_proxy: 'http://127.0.0.1:9',
+    https_proxy: 'http://127.0.0.1:9',
+    NO_PROXY: '',
+    no_proxy: '',
+    npm_config_offline: 'true',
+  };
+  if (process.platform === 'win32' && parentEnv.SystemRoot) env.SystemRoot = parentEnv.SystemRoot;
+  return env;
+}
+
+/** argv for one run. `files` are relative to the package root in the copy. */
+export function runnerArgv(runner, files, { outputFile, cacheDir }) {
+  switch (runner.id) {
+    case 'vitest':
+      return [runner.bin, 'run', '--no-coverage', '--reporter=json', `--outputFile=${outputFile}`, ...files];
+    case 'jest':
+      return [
+        runner.bin,
+        '--ci',
+        '--json',
+        `--outputFile=${outputFile}`,
+        '--coverage=false',
+        '--watchman=false',
+        `--cacheDirectory=${cacheDir}`,
+        '--runTestsByPath',
+        ...files,
+      ];
+    case 'node':
+      return ['--test', '--test-reporter=tap', ...files];
+    default:
+      throw new Error(`unknown runner ${runner.id}`);
+  }
+}
+
+/** clamp(3 × baseline + 5 s, 10 s, 120 s). */
+export function probeTimeoutMs(baselineMs) {
+  const wanted = 3 * Math.max(0, baselineMs) + 5000;
+  return Math.min(PROBE_TIMEOUT_CEILING_MS, Math.max(PROBE_TIMEOUT_FLOOR_MS, wanted));
+}
+
+function killGroup(child) {
+  if (!child.pid) return;
+  try {
+    if (process.platform === 'win32') {
+      spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    } else {
+      process.kill(-child.pid, 'SIGKILL');
+    }
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** Failure counts from the runner's own report. Null: no report to read. */
+function readFailures(runner, outputFile, stdout) {
+  if (runner.id === 'node') {
+    const fail = /^# fail (\d+)/m.exec(stdout);
+    const tests = /^# tests (\d+)/m.exec(stdout);
+    if (!fail) return null;
+    return { failed: Number(fail[1]), total: tests ? Number(tests[1]) : null };
+  }
+  const report = readJson(outputFile);
+  if (!report || typeof report !== 'object') return null;
+  const failed = (Number(report.numFailedTests) || 0) + (Number(report.numFailedTestSuites) || 0);
+  return { failed, total: Number(report.numTotalTests) || 0 };
+}
+
+/**
+ * Run the covering tests once.
+ * @returns {Promise<{ outcome: 'passed' | 'failed' | 'timeout' | 'runtime-error', durationMs: number, detail?: string }>}
+ */
+export function runCoveringTests({ runner, cwd, files, timeoutMs, env, scratch }) {
+  const outputFile = path.join(scratch, `runner-report-${process.hrtime.bigint()}.json`);
+  const argv = runnerArgv(runner, files, { outputFile, cacheDir: path.join(scratch, 'jest-cache') });
+  const started = process.hrtime.bigint();
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const child = spawn(process.execPath, argv, {
+      cwd,
+      env,
+      shell: false,
+      detached: process.platform !== 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    child.stdout.on('data', (chunk) => {
+      stdout = stdout.length < MAX_CAPTURE ? stdout + chunk.toString('utf8') : stdout;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = stderr.length < MAX_CAPTURE ? stderr + chunk.toString('utf8') : stderr;
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup(child);
+    }, timeoutMs);
+    let done = false;
+    const finish = (code, spawnError) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      const durationMs = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+      if (timedOut) return resolve({ outcome: 'timeout', durationMs });
+      if (spawnError) return resolve({ outcome: 'runtime-error', durationMs, detail: spawnError.message });
+      const failures = readFailures(runner, outputFile, stdout);
+      try {
+        fs.rmSync(outputFile, { force: true });
+      } catch {
+        /* scratch is removed with the workspace */
+      }
+      if (failures && failures.failed > 0) return resolve({ outcome: 'failed', durationMs });
+      if (code === 0) return resolve({ outcome: 'passed', durationMs });
+      // A non-zero exit with no reported failure is a crash, never a caught change.
+      return resolve({ outcome: 'runtime-error', durationMs, detail: stderr.slice(-2000) });
+    };
+    child.on('error', (error) => finish(null, error));
+    child.on('close', (code) => finish(code, null));
+  });
+}

package/bin/lib/invariant-probe-sites.mjs

@@ -0,0 +1,174 @@
+/**
+ * Where the invariant probe may change code — Tooling (ADR 0039).
+ *
+ * Parses the symbol file with the TypeScript the CLI already loaded, locates
+ * the declaration `coverage.symbol` names (the same shapes coverage accepts:
+ * function, `const x = () => {}` / function expression / literal, class or
+ * object-literal method, `Class.member`), and emits the sites inside that
+ * declaration only. Which sites become mutants is decided in Domain
+ * (`planMutants` in invariant-probe.mjs).
+ */
+
+const COMPARISON_TOKENS = new Set(['<', '>', '<=', '>=', '===', '!==', '==', '!=']);
+const DECLARATION_ONLY = new Map([
+  ['ClassDeclaration', 'class'],
+  ['InterfaceDeclaration', 'interface'],
+  ['TypeAliasDeclaration', 'type'],
+  ['EnumDeclaration', 'enum'],
+]);
+
+function nameOf(ts, node) {
+  return node.name && (ts.isIdentifier(node.name) || ts.isPrivateIdentifier?.(node.name)) ? node.name.text : null;
+}
+
+function isFunctionLike(ts, node) {
+  return Boolean(node) && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+}
+
+/** Body shape of a function-like node: a block to insert into, or an arrow expression. */
+function bodyOf(ts, sourceFile, fn) {
+  if (!fn.body) return null;
+  if (ts.isBlock(fn.body)) return { node: fn.body, body: { kind: 'block', insertAt: fn.body.getStart(sourceFile) + 1 } };
+  return {
+    node: fn.body,
+    body: { kind: 'expression', start: fn.body.getStart(sourceFile), end: fn.body.end },
+  };
+}
+
+/** Members of a class body or object literal named `member`. */
+function memberTarget(ts, sourceFile, members, member) {
+  for (const node of members) {
+    if (nameOf(ts, node) !== member) continue;
+    if ((ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node)) && node.body) {
+      return { shape: 'method', ...bodyOf(ts, sourceFile, node) };
+    }
+    const init = node.initializer;
+    if ((ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node)) && isFunctionLike(ts, init)) {
+      return { shape: 'method', ...bodyOf(ts, sourceFile, init) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the declaration for `symbol` (`name` or `Container.member`).
+ * @returns {{ found: true, shape: string, node: object, body: object } | { found: false, declarationOnly?: string }}
+ */
+function locate(ts, sourceFile, symbol) {
+  const parts = String(symbol).split('.');
+  const name = parts[parts.length - 1];
+  const container = parts.length > 1 ? parts[parts.length - 2] : null;
+  let found = null;
+  let declarationOnly = null;
+  const visit = (node) => {
+    if (found) return;
+    const kindName = ts.SyntaxKind[node.kind];
+    if (container === null) {
+      if (ts.isFunctionDeclaration(node) && nameOf(ts, node) === name && node.body) {
+        found = { shape: 'function', ...bodyOf(ts, sourceFile, node) };
+        return;
+      }
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer) {
+        const init = node.initializer;
+        found = isFunctionLike(ts, init)
+          ? { shape: 'const', ...bodyOf(ts, sourceFile, init) }
+          : {
+              shape: 'const',
+              node: init,
+              body: { kind: 'initializer', start: init.getStart(sourceFile), end: init.end },
+            };
+        return;
+      }
+      if (DECLARATION_ONLY.has(kindName) && nameOf(ts, node) === name) {
+        declarationOnly ??= DECLARATION_ONLY.get(kindName);
+      }
+    } else {
+      if ((ts.isClassDeclaration(node) || ts.isClassExpression(node)) && nameOf(ts, node) === container) {
+        found = memberTarget(ts, sourceFile, node.members, name);
+      } else if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === container &&
+        node.initializer
+      ) {
+        const init = node.initializer;
+        if (ts.isObjectLiteralExpression(init)) found = memberTarget(ts, sourceFile, init.properties, name);
+        else if (ts.isClassExpression(init)) found = memberTarget(ts, sourceFile, init.members, name);
+      } else if (ts.isModuleDeclaration(node) && nameOf(ts, node) === container && node.body) {
+        const fn = (node.body.statements ?? []).find(
+          (statement) => ts.isFunctionDeclaration(statement) && nameOf(ts, statement) === name && statement.body
+        );
+        if (fn) found = { shape: 'function', ...bodyOf(ts, sourceFile, fn) };
+      }
+      if (found && !found.node) found = null;
+    }
+    if (!found) ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  if (found) return { found: true, ...found };
+  return { found: false, ...(declarationOnly ? { declarationOnly } : {}) };
+}
+
+function thenExits(ts, statement) {
+  if (!statement) return false;
+  if (ts.isThrowStatement(statement) || ts.isReturnStatement(statement)) return true;
+  return ts.isBlock(statement) && statement.statements.some((s) => ts.isThrowStatement(s) || ts.isReturnStatement(s));
+}
+
+function siteAt(sourceFile, text, kind, start, end) {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(start);
+  return { kind, start, end, line: line + 1, column: character + 1, text: text.slice(start, end) };
+}
+
+/**
+ * Sites and body shape for the probe.
+ * @param {object} ts the loaded TypeScript module
+ * @param {string} fileName project-relative path (decides JS vs TS parsing)
+ * @param {string} text file contents
+ * @param {string} symbol `coverage.symbol`
+ * @returns {{ ok: true, shape: string, body: object, line: number, sites: object[] }
+ *          | { ok: false, reason: 'symbol-not-found' | 'declaration-only', shape?: string }}
+ */
+export function findProbeSites(ts, fileName, text, symbol) {
+  const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true);
+  const located = locate(ts, sourceFile, symbol);
+  if (!located.found) {
+    return located.declarationOnly
+      ? { ok: false, reason: 'declaration-only', shape: located.declarationOnly }
+      : { ok: false, reason: 'symbol-not-found' };
+  }
+  const sites = [];
+  const walk = (node) => {
+    if (ts.isIfStatement(node) && thenExits(ts, node.thenStatement)) {
+      sites.push(siteAt(sourceFile, text, 'guard', node.expression.getStart(sourceFile), node.expression.end));
+    } else if (ts.isThrowStatement(node)) {
+      sites.push(siteAt(sourceFile, text, 'throw', node.getStart(sourceFile), node.end));
+    } else if (ts.isBinaryExpression(node) && COMPARISON_TOKENS.has(node.operatorToken.getText(sourceFile))) {
+      sites.push(
+        siteAt(sourceFile, text, 'comparison', node.operatorToken.getStart(sourceFile), node.operatorToken.end)
+      );
+    } else if (ts.isNumericLiteral(node)) {
+      sites.push(siteAt(sourceFile, text, 'numeric', node.getStart(sourceFile), node.end));
+    } else if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) {
+      sites.push(siteAt(sourceFile, text, 'boolean', node.getStart(sourceFile), node.end));
+    }
+    ts.forEachChild(node, walk);
+  };
+  walk(located.node);
+  const { line } = sourceFile.getLineAndCharacterOfPosition(located.node.getStart(sourceFile));
+  return { ok: true, shape: located.shape, body: located.body, line: line + 1, sites };
+}
+
+/** True when `text` has no syntax errors (a mutant that does not parse is `invalid`). */
+export function parsesCleanly(ts, fileName, text) {
+  try {
+    const out = ts.transpileModule(text, {
+      fileName,
+      reportDiagnostics: true,
+      compilerOptions: { allowJs: true, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.Latest },
+    });
+    return (out.diagnostics ?? []).length === 0;
+  } catch {
+    return false;
+  }
+}