@synovitec/trellis 0.0.0-stage → 0.6.0-rc.2

package/src/verify/rules.mjs

@@ -0,0 +1,163 @@
+// The rules a change is held to at the commit checkpoint, as a pure function: a change (paths and
+// blobs), the evidence window, who made it, and the results of the checks Trellis ran itself.
+// Which rule blocks and which warns follows the evidence (docs/design/0001-evidence-v2.md):
+// block only what is deterministic; warn on the heuristic rules.
+import { matchesAny } from "../agents/glob.mjs";
+import { DEFAULTS } from "../agents/rules.mjs";
+import { isTestCommand } from "./test-commands.mjs";
+
+/** @typedef {"block" | "warn" | "off"} Mode */
+/** @typedef {{ rule: string, mode: "block" | "warn", message: string }} Finding */
+
+/** @type {Record<string, Record<string, Mode>>} */
+export const PRESETS = Object.freeze({
+  recommended: {
+    "secrets-scanned": "block",
+    "deps-verified": "block",
+    "deps-pinned": "warn",
+    "deps-registry": "warn",
+    "tests-protected": "block",
+    escalation: "block",
+    "tests-run": "warn",
+    "graph-before-edit": "warn",
+    "docs-looked-up": "warn",
+    "ui-verified": "warn",
+    "schema-before-change": "warn",
+    review: "off",
+    "plan-before-change": "off",
+  },
+  strict: {
+    "secrets-scanned": "block",
+    "deps-verified": "block",
+    "deps-pinned": "warn",
+    "deps-registry": "block",
+    "tests-protected": "block",
+    escalation: "block",
+    "tests-run": "block",
+    "graph-before-edit": "warn",
+    "docs-looked-up": "warn",
+    "ui-verified": "warn",
+    "schema-before-change": "warn",
+    review: "warn",
+    "plan-before-change": "warn",
+  },
+});
+
+/** Test files: an agent may add new ones, never change or delete existing ones. */
+const TEST_FILES = Object.freeze(["**/*.{test,spec}.*", "**/test/**", "**/tests/**", "**/__tests__/**", "**/spec/**", "**/*_spec.rb", "**/*_test.go", "**/test_*.py", "**/*_test.py"]);
+
+/**
+ * What decides which tests run and what judges them: a new one bends as much as an edited one
+ * (a conftest.py, a pytest.ini or a vitest.config that deselects every test), so an agent may
+ * neither add nor change one without a person.
+ */
+const GATES = Object.freeze([
+  "**/conftest.py",
+  "**/{setupTests,jest.setup,vitest.setup}.*",
+  "**/{jest,vitest,playwright,cypress,karma,vite}.config.*",
+  "**/vitest.workspace.*",
+  "**/.mocharc*",
+  "**/{pytest,tox}.ini",
+  ".github/workflows/**",
+  ".gitlab-ci.yml",
+  ".woodpecker.yml",
+  ".woodpecker/**",
+  ".circleci/**",
+  "azure-pipelines.yml",
+  "Jenkinsfile",
+  "bitbucket-pipelines.yml",
+  ".github/actions/**",
+  // The checkpoint's own settings and gates: bending them passes everything at once.
+  "trellis.config.json",
+  ".trellis/**",
+  ".gitleaks.toml",
+  ".gitleaksignore",
+  ".githooks/**",
+  ".husky/**",
+  // The agents' own hooks and MCP configs: the checks an agent runs under.
+  ".claude/settings.json",
+  ".cursor/{hooks,mcp}.json",
+  ".codex/{hooks.json,config.toml}",
+  ".github/hooks/**",
+  ".vscode/mcp.json",
+  ".mcp.json",
+]);
+
+/** Test, grader and CI files, and the checkpoint's own settings: what an agent bends to pass. */
+export const TEST_PATHS = Object.freeze([...TEST_FILES, ...GATES]);
+
+/** @param {string[]} paths */
+const list = (paths) => `${paths.slice(0, 6).join(", ")}${paths.length > 6 ? `, and ${paths.length - 6} more` : ""}`;
+
+/**
+ * @param {object} input
+ * @param {import("../core/diff.mjs").Change[]} input.changes
+ * @param {import("../core/evidence.mjs").Event[]} input.events   the window since the last commit
+ * @param {"agent" | "person"} input.actor
+ * @param {string} input.preset
+ * @param {Record<string, Mode>} [input.modes]   per-rule overrides
+ * @param {import("./secrets.mjs").SecretScan} input.secrets
+ * @param {import("./deps.mjs").DependencyCheck} input.deps
+ * @param {string[]} input.depNames               dependencies the change adds, by name
+ * @param {string[] | null} [input.testCommands]   the project's test commands (null: any command counts)
+ * @param {string} [input.tree]                  the tree being committed: a test run counts only for it
+ * @param {string[]} [input.testScripts]          manifests whose test script the change rewrites (as `testScriptChanges` reads them)
+ * @returns {Finding[]}
+ */
+export function evaluate(input) {
+  const modes = { ...(PRESETS[input.preset] ?? PRESETS.recommended), ...(input.modes ?? {}) };
+  const { changes, events, actor } = input;
+  const agent = actor === "agent";
+  /** @type {Finding[]} */
+  const out = [];
+  const report = (/** @type {string} */ rule, /** @type {string} */ message) => {
+    const mode = modes[rule] ?? "off";
+    if (mode !== "off") out.push({ rule, mode, message });
+  };
+  // A tests event counts only as a run of the project's own tests (./test-commands.mjs).
+  const of = (/** @type {string} */ kind) => events.filter((e) => e.kind === kind && (kind !== "tests" || (isTestCommand(e.tool, input.testCommands) && (input.tree == null || e.tree === input.tree))));
+  const live = changes.filter((c) => c.status !== "D");
+  const code = live.filter((c) => matchesAny(c.path, DEFAULTS.codePaths) && !matchesAny(c.path, DEFAULTS.codeIgnore));
+  /** A file is covered by an event of `kind` holding its current blob (and exit 0 when it has one). */
+  const covered = (/** @type {string} */ kind, /** @type {import("../core/diff.mjs").Change} */ c) =>
+    of(kind).some((e) => e.blobs?.[c.path] === c.newBlob && (e.result == null || e.result === 0));
+
+  // Deterministic: everyone.
+  if (input.secrets.status === "leaks") report("secrets-scanned", `${input.secrets.count ?? "some"} secret(s) found in this change. Remove them and rotate them.`);
+  if (input.secrets.status === "unavailable") report("secrets-scanned", `This change could not be scanned for secrets: ${input.secrets.detail ?? "gitleaks did not run"}.`);
+  if (input.deps.status === "findings") report("deps-verified", input.deps.findings.map((f) => `${f.name}@${f.version ?? "?"}: ${f.problem}`).join("; "));
+  if (input.deps.status === "unavailable") report("deps-verified", `The dependencies this change adds could not be checked: ${input.deps.detail ?? "registry or OSV unreachable"}.`);
+  if (input.deps.unchecked.length) report("deps-registry", `Not checked on a registry: ${list(input.deps.unchecked)}. Trellis cannot tell whether they exist as named or have known vulnerabilities; check them, or install them from their registry.`);
+  if (input.deps.unpinned.length) report("deps-pinned", `No exact version for ${list(input.deps.unpinned)}: their known vulnerabilities cannot be checked. Commit the lockfile, or pin them.`);
+
+  // What an agent bends to pass: existing tests, graders and CI. Adding tests is welcome.
+  if (agent) {
+    const approved = of("approval");
+    const bent = changes.filter(
+      (c) => ((c.status !== "A" && matchesAny(c.path, TEST_FILES)) || matchesAny(c.path, GATES) || (input.testScripts ?? []).includes(c.path)) && !approved.some((e) => e.blobs?.[c.path] === (c.newBlob ?? "deleted")),
+    );
+    if (bent.length) report("tests-protected", `An agent changed or deleted existing tests, CI or the checkpoint's own settings: ${list(bent.map((c) => c.path))}. If the test is wrong, stop with \`trellis escalate "<why>"\`; a person approves the exact change with \`trellis approve\`.`);
+    const lastEscalation = events.map((e) => e.kind).lastIndexOf("escalation");
+    if (lastEscalation !== -1 && !events.slice(lastEscalation + 1).some((e) => e.kind === "approval")) {
+      report("escalation", `The agent asked for a person: "${events[lastEscalation].subject ?? "no reason given"}". It lands once a person reviews it and runs \`trellis approve\`.`);
+    }
+  }
+
+  const untested = code.filter((c) => !covered("tests", c));
+  if (untested.length) report("tests-run", `No passing test run on the current content of ${list(untested.map((c) => c.path))}. Run them through \`trellis check tests\`.`);
+
+  const ui = live.filter((c) => matchesAny(c.path, DEFAULTS.uiPaths) && !matchesAny(c.path, DEFAULTS.uiIgnore) && !covered("browser", c));
+  if (ui.length) report("ui-verified", `No browser check of the current content of ${list(ui.map((c) => c.path))}.`);
+
+  if (agent) {
+    if (code.length > 1 && !of("graph").length) report("graph-before-edit", `${code.length} code files changed with no code-graph query in this work.`);
+    const docs = of("docs").map((e) => String(e.subject ?? "").toLowerCase());
+    const unlooked = input.depNames.filter((n) => !docs.some((s) => s.includes(n.toLowerCase())));
+    if (unlooked.length) report("docs-looked-up", `No documentation lookup for the new dependencies ${list(unlooked)}.`);
+    const schema = live.filter((c) => matchesAny(c.path, DEFAULTS.schemaPaths));
+    if (schema.length && !of("schema").length) report("schema-before-change", `Schema files changed (${list(schema.map((c) => c.path))}) with no schema lookup.`);
+    if (!of("review").length && live.length) report("review", "No independent review of this change.");
+    if (live.length > 5 && !of("plan").length) report("plan-before-change", `${live.length} files changed with no plan recorded.`);
+  }
+  return out;
+}

package/src/verify/secrets.mjs

@@ -0,0 +1,169 @@
+// The secret scan of a change: what is about to be committed, or one commit's own change. Trellis
+// runs gitleaks itself; what the agent ran proves nothing.
+//
+// What is scanned is the content of each changed file, as git stores it, written at its own path
+// into a folder of Trellis's own: never diff text, which the change can shape (a `.gitattributes`
+// line `*.ini -diff` turns a file's diff into "Binary files differ"). UTF-16 text is also read as
+// text, gzip content unpacked. The rules are gitleaks's defaults without their global path
+// allowlist (src/verify/gitleaks-default.toml: gitleaks skips *.pdf, package-lock.json and
+// node_modules/ by path, and a pull request chooses its own file names), and the team's own
+// .gitleaks.toml and .gitleaksignore as committed before the change (HEAD for a commit, the base
+// in CI), applied by gitleaks itself: every allowlist form it reads, as it reads it. An allowlist
+// the change itself writes is scanned like any other file and never loaded, and an inline
+// `gitleaks:allow` never counts.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+import { commitDiff, stagedDiff } from "../core/diff.mjs";
+
+/** @typedef {{ status: "clean" | "leaks" | "unavailable", count?: number, detail?: string }} SecretScan */
+
+/** gitleaks's default rules, without the global path allowlist. */
+const DEFAULT_RULES = fileURLToPath(new URL("./gitleaks-default.toml", import.meta.url));
+
+/** A file gitleaks would load as its own settings if it found it in the folder it scans. */
+const SETTINGS = /^\.gitleaks/;
+
+/** A file as it stands at `rev`, or "" when it is not there. @param {string} root @param {string} rev @param {string} path */
+const fileAt = (root, rev, path) => {
+  const r = spawnSync("git", ["show", `${rev}:${path}`], { cwd: root, encoding: "utf8", windowsHide: true });
+  return r.status === 0 ? r.stdout : "";
+};
+
+/**
+ * What a blob also holds as text a scanner reads: UTF-16 decoded, gzip unpacked.
+ * @param {Buffer} bytes
+ * @returns {Buffer[]}
+ */
+function decoded(bytes) {
+  const out = [];
+  if (bytes[0] === 0xff && bytes[1] === 0xfe) out.push(Buffer.from(bytes.subarray(2).toString("utf16le"), "utf8"));
+  if (bytes[0] === 0xfe && bytes[1] === 0xff) out.push(Buffer.from(Buffer.from(bytes.subarray(2)).swap16().toString("utf16le"), "utf8"));
+  if (bytes[0] === 0x1f && bytes[1] === 0x8b) {
+    try {
+      const inner = gunzipSync(bytes, { maxOutputLength: 256 * 1024 * 1024 });
+      out.push(inner, ...decoded(inner));
+    } catch {
+      /* not gzip after all */
+    }
+  }
+  return out;
+}
+
+/** A path as a TOML basic string. @param {string} path */
+const tomlPath = (path) => JSON.stringify(path.replace(/\\/g, "/"));
+
+/**
+ * The team's config made to run from Trellis's folder: `[extend] useDefault = true` points at
+ * gitleaks's defaults without their path allowlist, and `[extend] path = "..."` at the file it
+ * names, as committed at `rev` (followed the same way, three deep). The rest is left as written.
+ * @param {string} root @param {string} rev @param {string} text @param {string} work @param {number} depth
+ */
+function resolveConfig(root, rev, text, work, depth = 0) {
+  const at = text.search(/^\s*\[extend\]\s*(#.*)?$/m);
+  if (at === -1) return text;
+  const rest = text.slice(at);
+  const next = rest.slice(1).search(/^\s*\[/m);
+  const section = next === -1 ? rest : rest.slice(0, next + 1);
+  let changed = section.replace(/^(\s*)useDefault\s*=\s*true\b.*$/m, (_, indent) => `${indent}path = ${tomlPath(DEFAULT_RULES)}`);
+  changed = changed.replace(/^(\s*)path\s*=\s*(["'])(.+?)\2/m, (whole, indent, _q, target) => {
+    if (target === DEFAULT_RULES.replace(/\\/g, "/") || depth >= 3) return whole;
+    const file = join(work, `extended-${depth}.toml`);
+    writeFileSync(file, resolveConfig(root, rev, fileAt(root, rev, target.replace(/^\.\//, "")), work, depth + 1));
+    return `${indent}path = ${tomlPath(file)}`;
+  });
+  return text.slice(0, at) + changed + text.slice(at + section.length);
+}
+
+/**
+ * Scans the new content of `changes` with the rules committed at `rulesAt`.
+ * @param {string} root
+ * @param {import("../core/diff.mjs").Change[]} changes
+ * @param {string | null} rulesAt  the revision whose .gitleaks.toml and .gitleaksignore apply; null: none yet
+ * @param {{ gitleaks?: string }} opts
+ * @returns {SecretScan}
+ */
+function scanContent(root, changes, rulesAt, opts) {
+  const bin = opts.gitleaks ?? "gitleaks";
+  const work = mkdtempSync(join(tmpdir(), "trellis-gitleaks-"));
+  try {
+    const src = join(work, "src");
+    mkdirSync(src);
+    for (const c of changes) {
+      if (!c.newBlob) continue;
+      const blob = spawnSync("git", ["cat-file", "blob", c.newBlob], { cwd: root, maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+      if (blob.status !== 0) continue; // a submodule's commit, not a file
+      const parts = c.path.split("/");
+      const name = parts.pop() ?? "";
+      const file = join(src, ...parts, SETTINGS.test(name) ? `${name}.scanned` : name);
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, blob.stdout);
+      // Beside it, under a name with none of its dots: gitleaks takes "x.gz.anything" for an archive.
+      decoded(blob.stdout).forEach((bytes, i) => writeFileSync(join(dirname(file), `${name.replace(/\./g, "_")}_decoded_${i + 1}.txt`), bytes));
+    }
+    const team = rulesAt ? fileAt(root, rulesAt, ".gitleaks.toml") : "";
+    const config = join(work, "gitleaks.toml");
+    if (team.trim()) writeFileSync(config, resolveConfig(root, /** @type {string} */ (rulesAt), team, work));
+    else copyFileSync(DEFAULT_RULES, config);
+    writeFileSync(join(work, "ignore"), (rulesAt && fileAt(root, rulesAt, ".gitleaksignore")) || "");
+    const args = ["dir", ".", "--redact", "--no-banner", "--exit-code", "1", "--ignore-gitleaks-allow", "--config", config, "--gitleaks-ignore-path", join(work, "ignore")];
+    const { GITLEAKS_CONFIG: _, GITLEAKS_CONFIG_TOML: __, ...env } = process.env;
+    const r = spawnSync(bin, args, { cwd: src, encoding: "utf8", timeout: 120_000, windowsHide: true, env });
+    if (r.error) return { status: "unavailable", detail: `gitleaks could not run (${r.error.message})` };
+    if (r.status === 0) return { status: "clean" };
+    const found = `${r.stdout}${r.stderr}`.match(/leaks found:\s*(\d+)/i);
+    if (r.status === 1 && found) return { status: "leaks", count: Number(found[1]) };
+    return { status: "unavailable", detail: `gitleaks did not complete (exit ${r.status ?? "killed"}): ${`${r.stderr}`.trim().split(/\r?\n/).pop() ?? ""}` };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Any set of changes (CI's net change of a pull request), with the rules committed at `rulesAt`.
+ * @param {string} root
+ * @param {import("../core/diff.mjs").Change[]} changes
+ * @param {string} rulesAt
+ * @param {{ gitleaks?: string }} [opts]
+ * @returns {SecretScan}
+ */
+export const scanChanges = (root, changes, rulesAt, opts = {}) => scanContent(root, changes, rulesAt, opts);
+
+/** HEAD, or null before the first commit. @param {string} root */
+const head = (root) => {
+  const r = spawnSync("git", ["rev-parse", "-q", "--verify", "HEAD^{commit}"], { cwd: root, encoding: "utf8", windowsHide: true });
+  return r.status === 0 ? r.stdout.trim() : null;
+};
+
+/**
+ * What is about to be committed, with the allowlist of the last commit.
+ * @param {string} root
+ * @param {{ gitleaks?: string }} [opts]
+ * @returns {SecretScan}
+ */
+export function scanStaged(root, opts = {}) {
+  return scanContent(root, stagedDiff(root), head(root), opts);
+}
+
+/**
+ * One commit's own change (a merge's own part: what each side brought is its own commits'),
+ * wherever it sits (a branch, a tag, nothing). The allowlist is the base's in CI, else the
+ * commit's first parent's.
+ * @param {string} root
+ * @param {string} commit
+ * @param {{ gitleaks?: string, base?: string }} [opts]
+ * @returns {SecretScan}
+ */
+export function scanCommit(root, commit, opts = {}) {
+  let changes;
+  try {
+    changes = commitDiff(root, commit);
+  } catch (e) {
+    return { status: "unavailable", detail: e instanceof Error ? e.message : String(e) };
+  }
+  const parent = spawnSync("git", ["rev-parse", "-q", "--verify", `${commit}^1`], { cwd: root, encoding: "utf8", windowsHide: true });
+  return scanContent(root, changes, opts.base ?? (parent.status === 0 ? parent.stdout.trim() : null), opts);
+}

package/src/verify/test-commands.mjs

@@ -0,0 +1,116 @@
+// Which commands are the project's tests: a run of anything else (`true`, `echo ok`) is not a
+// test run, whatever its exit code. `verify.tests` in trellis.config.json names them; without
+// it they are read from the project itself. CI reads them at the base, so a pull request cannot
+// redefine what counts as its own tests.
+import { spawnSync } from "node:child_process";
+import { parseJson } from "../core/context.mjs";
+
+/** npm's placeholder for a package with no tests. */
+const NO_TESTS = /no test specified/;
+
+/**
+ * The project's test commands, or null when Trellis cannot tell (then any command counts, and
+ * `verify.tests` closes the gap).
+ * @param {(path: string) => string | null} read  a file of the repository, as it stands where judged
+ * @returns {string[] | null}
+ */
+export function testCommands(read) {
+  const configured = parseJson(read("trellis.config.json") ?? "null")?.verify?.tests;
+  if (Array.isArray(configured) && configured.length) return configured.map(normalise);
+  const found = [];
+  const script = parseJson(read("package.json") ?? "null")?.scripts?.test;
+  if (typeof script === "string" && script.trim() && !NO_TESTS.test(script)) {
+    found.push("npm test", "npm run test", "npm t", "pnpm test", "pnpm run test", "yarn test", "yarn run test", "bun run test", normalise(script));
+  }
+  if (["pytest.ini", "pyproject.toml", "setup.cfg", "tox.ini"].some((f) => read(f) != null)) found.push("pytest", "python -m pytest", "uv run pytest");
+  if (read("go.mod") != null) found.push("go test ./...");
+  if (read("Cargo.toml") != null) found.push("cargo test");
+  return found.length ? found : null;
+}
+
+/** What a test run's environment may not carry: settings that change what a runner runs. */
+const STEERS = /^(npm_config_.*|YARN_.*|PNPM_.*|BUN_.*|PYTEST_.*|PYTHONPATH|PYTHONSTARTUP|PYTHONHOME|PYTHONUSERBASE|NODE_OPTIONS|NODE_PATH|JEST_.*|VITEST.*|MOCHA_.*|CARGO_.*|RUSTC.*|RUSTDOC.*|RUSTFLAGS|GOFLAGS|GOENV|BASH_ENV|ENV|COMSPEC|PERL5OPT|RUBYOPT|JAVA_TOOL_OPTIONS|_JAVA_OPTIONS|JDK_JAVA_OPTIONS|GRADLE_OPTS|MAVEN_OPTS)$/i;
+
+/**
+ * The environment a test run gets: the session's, without what steers a runner
+ * (`npm_config_script_shell=true` makes every script pass; `PYTEST_ADDOPTS=--collect-only` runs
+ * none), and with npm's user and global config files set to an empty one (`script-shell` in
+ * ~/.npmrc does the same).
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} emptyFile
+ */
+export function testEnv(env, emptyFile) {
+  const out = Object.fromEntries(Object.entries(env).filter(([k]) => !STEERS.test(k)));
+  // Node's `shell: true` on Windows runs %ComSpec%: the system's cmd.exe, never another program.
+  if (process.platform === "win32") out.ComSpec = `${env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows"}\\System32\\cmd.exe`;
+  return { ...out, npm_config_userconfig: emptyFile, npm_config_globalconfig: `${emptyFile}.global` };
+}
+
+/** Runner settings that change what runs, even when git ignores them: a run with one present proves nothing. */
+export const RUNNER_SETTINGS = Object.freeze(["**/conftest.py", "**/{pytest,tox,.pytest}.ini", "**/.yarnrc{,.yml}", "**/.cargo/config{,.toml}", "**/{jest,vitest,playwright,cypress,karma,vite}.config.*", "**/vitest.workspace.*", "**/.mocharc*", "**/{setupTests,jest.setup,vitest.setup}.*", "**/.npmrc"]);
+
+/** @param {string} command */
+export const normalise = (command) => command.trim().replace(/\s+/g, " ");
+
+/** A script another one runs: `npm run unit`, `yarn unit`, `pnpm unit`, `bun run unit`. */
+const CALLS = /\b(?:npm|pnpm|yarn|bun)\s+(?:run(?:-script)?\s+)?([\w:.-]+)/g;
+
+/**
+ * The scripts that decide what `npm test` runs: the test scripts and every script they run, to
+ * any depth (`"test": "npm run unit"` makes `unit` part of the tests), and the test runner's
+ * settings package.json can hold.
+ * @param {string | null} text
+ */
+const testScripts = (text) => {
+  const doc = parseJson(text ?? "null") ?? {};
+  const scripts = doc.scripts ?? {};
+  const seen = new Set(Object.keys(scripts).filter((k) => /^(pre|post)?test(:|$)/.test(k)));
+  for (const name of seen) for (const [, called] of String(scripts[name] ?? "").matchAll(CALLS)) if (called in scripts) for (const k of [called, `pre${called}`, `post${called}`]) if (k in scripts) seen.add(k);
+  return JSON.stringify([[...seen].sort().map((k) => [k, scripts[k]]), doc.jest ?? null, doc.mocha ?? null, doc.ava ?? null]);
+};
+
+/** pytest's sections of a pyproject.toml or setup.cfg: `[tool.pytest...]`, `[tool:pytest]`. @param {string | null} text */
+const pytestSections = (text) => {
+  const out = [];
+  let on = false;
+  for (const line of (text ?? "").split(/\r?\n/)) {
+    const header = line.match(/^\s*\[([^\]]+)\]/);
+    if (header) on = /^(tool\.pytest|tool:pytest|pytest)/.test(header[1].trim());
+    if (on) out.push(line);
+  }
+  return out.join("\n");
+};
+
+/** @param {string} root @param {string | null} blob */
+const blobText = (root, blob) => (blob ? spawnSync("git", ["cat-file", "blob", blob], { cwd: root, encoding: "utf8", windowsHide: true }).stdout : null);
+
+/**
+ * The manifests whose test settings the change rewrites: package.json's test scripts (`"test":
+ * "true"` bends every test at once, while the file itself is no test file), pyproject.toml's and
+ * setup.cfg's pytest sections. A new manifest that brings them counts too.
+ * @param {string} root
+ * @param {import("../core/diff.mjs").Change[]} changes
+ * @returns {string[]}
+ */
+export const testScriptChanges = (root, changes) =>
+  changes
+    .filter((c) => {
+      if (c.status === "D") return false;
+      const read = /(^|\/)package\.json$/.test(c.path) ? testScripts : /(^|\/)(pyproject\.toml|setup\.cfg)$/.test(c.path) ? pytestSections : null;
+      return read != null && read(blobText(root, c.oldBlob)) !== read(blobText(root, c.newBlob));
+    })
+    .map((c) => c.path);
+
+/**
+ * Whether `command` is exactly one of `accepted`. Arguments of its own are not accepted: a filter
+ * that matches nothing (`-t nomatch --passWithNoTests`) passes without running a test. A team
+ * that counts a narrower run names it in `verify.tests`.
+ * @param {string} command
+ * @param {string[] | null | undefined} accepted
+ */
+export function isTestCommand(command, accepted) {
+  // A line break is a second command to a shell (`go<newline>test ./...` runs the builtin test).
+  if (/[\r\n\0]/.test(command)) return false;
+  if (!accepted) return true;
+  return accepted.includes(normalise(command));
+}