simt-dev 0.7.0 → 0.8.0

package/src/sys/proc.mjs

@@ -0,0 +1,151 @@
+// One bounded child process and the environment a child inherits, for everything
+// that runs one (review 0003 Q47, Q72).
+//
+// `child.kill('SIGKILL')` kills the process the caller started and leaves its
+// grandchildren running: an adapter that ran `(sleep 15 &); sleep 60` kept the pipe open
+// and the caller waited 62.6 s against a 2 s timeout, then graded the result. A detached
+// child is its own process group, so the deadline kills the group, destroys the streams
+// and settles. A run cannot outlive its own deadline, whatever it spawned.
+//
+// Output is bounded so a runaway child cannot decide the caller's memory: past the cap
+// the oldest chunk is dropped and `truncated` says so, rather than the spawn failing.
+//
+// This module used to live in `src/bench/` because the bench was its only caller. The
+// bench is not the only thing that runs a child it does not trust, and a second copy of
+// the deadline logic is a second way for a run to outlive its deadline.
+
+import { spawn } from 'node:child_process';
+
+/** The most output one run may accumulate before the oldest bytes are dropped. */
+const DEFAULT_MAX_OUTPUT_BYTES = 8 << 20;
+
+/** How long to wait for streams to close after the process group is killed. */
+const HARD_STOP_GRACE_MS = 500;
+
+function boundedPush(chunks, state, chunk) {
+  state.bytes += chunk.length;
+  chunks.push(chunk);
+  while (state.bytes > state.max && chunks.length > 1) {
+    state.bytes -= chunks.shift().length;
+    state.truncated = true;
+  }
+}
+
+/**
+ * Run `cmd` with `args`, bounded by a deadline and an output cap.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{cwd?: string, env?: NodeJS.ProcessEnv, input?: Buffer|string|null, timeoutMs?: number, maxOutputBytes?: number}} [options]
+ * @returns {Promise<{code: number, timedOut: boolean, wallMs: number, stdout: Buffer, stderr: Buffer, truncated: boolean, spawnError: string|null}>}
+ *   `code` is 124 when the deadline fired, and `wallMs` is what the run actually took.
+ */
+export function spawnBounded(
+  cmd,
+  args,
+  { cwd, env, input = null, timeoutMs = 0, maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES } = {},
+) {
+  return new Promise((settle) => {
+    const startedAt = Date.now();
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        cwd,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: true,
+      });
+    } catch (error) {
+      settle({
+        code: 1,
+        timedOut: false,
+        wallMs: 0,
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.from(String(error?.message ?? error)),
+        truncated: false,
+        spawnError: String(error?.message ?? error),
+      });
+      return;
+    }
+
+    const out = [];
+    const err = [];
+    const outState = { bytes: 0, max: maxOutputBytes, truncated: false };
+    const errState = { bytes: 0, max: maxOutputBytes, truncated: false };
+    let timer = null;
+    let hardStop = null;
+    let timedOut = false;
+    let done = false;
+
+    const killGroup = () => {
+      try {
+        process.kill(-child.pid, 'SIGKILL');
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // Already gone; the close handler settles the promise.
+        }
+      }
+    };
+
+    const finish = (code, spawnError = null) => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      if (hardStop) clearTimeout(hardStop);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      settle({
+        code,
+        timedOut,
+        wallMs: Date.now() - startedAt,
+        stdout: Buffer.concat(out),
+        stderr: Buffer.concat(err),
+        truncated: outState.truncated || errState.truncated,
+        spawnError,
+      });
+    };
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        killGroup();
+        // A process that escaped the group can hold the pipes open after the kill, and a
+        // deadline that waits on a stranger's cleanup is not a deadline.
+        hardStop = setTimeout(() => finish(124), HARD_STOP_GRACE_MS);
+        hardStop.unref?.();
+      }, timeoutMs);
+      timer.unref?.();
+    }
+
+    child.stdout?.on('data', (chunk) => boundedPush(out, outState, chunk));
+    child.stderr?.on('data', (chunk) => boundedPush(err, errState, chunk));
+    child.on('error', (error) => {
+      const message = String(error?.message ?? error);
+      boundedPush(err, errState, Buffer.from(message));
+      finish(1, message);
+    });
+    child.on('close', (code) => finish(timedOut ? 124 : (code ?? 1)));
+
+    child.stdin?.end(input ?? undefined);
+  });
+}
+
+/**
+ * What a spawned child is allowed to inherit from the operator's shell.
+ *
+ * Three bench modules grew this identically, and the differences between what a child
+ * needs and what the shell carries are the whole point: `SIMT_DEV_WORKSPACE` is forced
+ * off so a child cannot resolve THIS repository's workspace, and the `NODE_TEST*`
+ * variables are dropped because they steer `node --test` at a test directory the child
+ * does not have. Nothing here names a credential or a state directory: those come from
+ * the caller's own `extra`.
+ */
+export function sanitizedEnv(extra = {}) {
+  const env = { ...process.env, SIMT_DEV_WORKSPACE: 'off', ...extra };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('NODE_TEST')) delete env[key];
+  }
+  return env;
+}

package/src/testing/parsers.mjs

@@ -0,0 +1,265 @@
+// Parsers for the report formats a test runner writes.
+//
+// A runner's verdict is read from one of four shapes: TAP, the Vitest/Jest JSON result,
+// JUnit XML, `go test -json`, and libtest's text. They are parsers, not graders, so the
+// gate, the index and the bench read a run the same way.
+import { readFile, readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+/**
+ * Sort and de-duplicate a list of ids.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+export function dedupeSorted(items) {
+  return [...new Set(items)].sort();
+}
+
+/**
+ * Parse TAP version 13 output from `node --test --test-reporter=tap`.
+ *
+ * Leaf test cases carry `type: 'test'` in their YAML block; suite headers carry
+ * `type: 'suite'` and are used only to build `parent > child` qualified IDs.
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseTapOutput(text) {
+  const passed = [];
+  const failed = [];
+  const lines = String(text ?? '').split('\n');
+  const stack = [];
+  let pending = null;
+
+  const flush = () => {
+    if (!pending) return;
+    if (pending.type !== 'suite' && !pending.hadChild && !pending.directive) {
+      const id = [...pending.ancestors, pending.name].join(' > ');
+      if (pending.ok) passed.push(id);
+      else failed.push(id);
+    }
+    pending = null;
+  };
+
+  for (const raw of lines) {
+    const sub = /^(\s*)# Subtest:\s+(.*)$/.exec(raw);
+    if (sub) {
+      flush();
+      const indent = sub[1].length;
+      while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop();
+      if (stack.length > 0) stack[stack.length - 1].hadChild = true;
+      stack.push({ indent, name: sub[2].trim(), hadChild: false });
+      continue;
+    }
+
+    const res = /^(\s*)(not ok|ok)\s+\d+(?:\s+-\s+(.*?))?(?:\s+#\s*(SKIP|TODO)\b.*)?$/i.exec(raw);
+    if (res) {
+      flush();
+      const indent = res[1].length;
+      while (stack.length > 0 && stack[stack.length - 1].indent > indent) stack.pop();
+      let hadChild = false;
+      if (stack.length > 0 && stack[stack.length - 1].indent === indent) {
+        hadChild = stack.pop().hadChild;
+      }
+      const ancestors = stack.map((entry) => entry.name);
+      const ok = res[2].toLowerCase() === 'ok';
+      const name = (res[3] ?? '').trim();
+      const directive = res[4] ? res[4].toUpperCase() : null;
+      if (name) pending = { indent, ok, name, ancestors, hadChild, directive, type: null };
+      continue;
+    }
+
+    if (pending) {
+      const typeMatch = /^\s*type:\s*['"]?(test|suite)['"]?\s*$/.exec(raw);
+      if (typeMatch) pending.type = typeMatch[1];
+      else if (/^\s*\.\.\.\s*$/.test(raw)) flush();
+    }
+  }
+  flush();
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/**
+ * Parse Vitest `--reporter=json` output. Jest emits the same
+ * `testResults`/`assertionResults` shape, so one parser serves both (review 0003 Q48).
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseVitestJson(text) {
+  const passed = [];
+  const failed = [];
+  const raw = String(text ?? '').trim();
+  const start = raw.indexOf('{');
+  const end = raw.lastIndexOf('}');
+  if (start === -1 || end === -1 || end < start) return { passed, failed };
+
+  let doc;
+  try {
+    doc = JSON.parse(raw.slice(start, end + 1));
+  } catch {
+    return { passed, failed };
+  }
+
+  for (const suite of doc.testResults ?? []) {
+    for (const assertion of suite.assertionResults ?? []) {
+      const parts = [...(assertion.ancestorTitles ?? []), assertion.title].filter(Boolean);
+      const id = parts.length > 0 ? parts.join(' > ') : (assertion.fullName ?? '').trim();
+      if (!id) continue;
+      if (assertion.status === 'passed') passed.push(id);
+      else if (assertion.status === 'failed') failed.push(id);
+    }
+  }
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+function xmlAttr(attrs, key) {
+  const match = new RegExp(`\\b${key}=["']([^"']*)["']`).exec(attrs);
+  if (!match) return '';
+  return match[1]
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&')
+    .trim();
+}
+
+/**
+ * Parse JUnit XML output (pytest `--junitxml`, Gradle and Maven).
+ *
+ * @param {string} xml
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseJunitXml(xml) {
+  const passed = [];
+  const failed = [];
+  const source = String(xml ?? '');
+  const tagRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+
+  for (const match of source.matchAll(tagRe)) {
+    const attrs = match[1] ?? '';
+    const inner = match[2] ?? '';
+    const name = xmlAttr(attrs, 'name');
+    const classname = xmlAttr(attrs, 'classname');
+    if (!name) continue;
+    if (/<skipped\b/i.test(inner)) continue;
+
+    const id = classname ? `${classname} > ${name}` : name;
+    if (/<(?:failure|error)\b/i.test(inner)) failed.push(id);
+    else passed.push(id);
+  }
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/**
+ * Parse `go test -json` JSONL event stream. Only leaf events (carrying `Test`) are
+ * results; package summaries without one are ignored.
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseGoTestJson(text) {
+  const passed = [];
+  const failed = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{')) continue;
+    let event;
+    try {
+      event = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (typeof event.Test !== 'string' || event.Test.length === 0) continue;
+    const id = event.Package ? `${event.Package} > ${event.Test}` : event.Test;
+    if (event.Action === 'pass') passed.push(id);
+    else if (event.Action === 'fail') failed.push(id);
+  }
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/**
+ * Parse libtest's text output, which `cargo test` prints for every test binary.
+ *
+ * A line is a result only when it has the `test <name> ... <status>` shape. `ignored` is
+ * neither a pass nor a failure: counting it as one would make a skipped test look like
+ * evidence the change works.
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseCargoTestOutput(text) {
+  const passed = [];
+  const failed = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const match = /^test\s+(.+?)\s+\.\.\.\s+(ok|FAILED|ignored)\s*$/.exec(line.trimEnd());
+    if (!match || match[2] === 'ignored') continue;
+    (match[2] === 'ok' ? passed : failed).push(match[1]);
+  }
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/** Every `*.xml` under `dir`, sorted, for a deterministic read order. */
+async function listXml(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await listXml(full)));
+    else if (entry.name.endsWith('.xml')) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Read every JUnit XML a run left behind, from report files or report *directories*
+ * (review 0003 Q48: Gradle writes one XML per class under `build/test-results/test/`,
+ * Maven under `target/surefire-reports/`; reading a single file saw none of them).
+ *
+ * @param {string[]} paths report files and/or directories
+ * @returns {Promise<string>} the concatenated XML, '' when nothing is there
+ */
+export async function readReports(paths) {
+  const chunks = [];
+  for (const path of paths ?? []) {
+    let isDir = false;
+    try {
+      isDir = (await stat(path)).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDir) {
+      for (const file of await listXml(path)) {
+        chunks.push(await readFile(file, 'utf8').catch(() => ''));
+      }
+    } else {
+      chunks.push(await readFile(path, 'utf8').catch(() => ''));
+    }
+  }
+  return chunks.join('\n');
+}
+
+/**
+ * Remove the report files a runner wrote outside its workspace.
+ *
+ * A report inside the workspace belongs to the workspace and is removed with it. A report
+ * this package directed to the temporary directory has no other owner, and leaving it
+ * there is how a repository ended up with `.bench-junit.xml` beside its sources (review
+ * 0003 Q79).
+ *
+ * @param {string[]} paths
+ */
+export async function cleanupReports(paths = []) {
+  const temp = tmpdir();
+  for (const path of paths ?? []) {
+    if (!String(path).startsWith(temp)) continue;
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/testing/patches.mjs

@@ -0,0 +1,23 @@
+// Which files a unified diff touches.
+//
+// A patch is read from its destination side (`b/`), because the destination is the file
+// that exists after the change; a deletion names `/dev/null` and contributes no path.
+// The grader uses it to measure the blast radius, and the skills compiler uses it to ask
+// which files a stored run touched — neither should have to import the bench's grader to
+// read a diff header (review 0003 Q79).
+
+/**
+ * Extract repository-relative file paths touched by a unified git diff.
+ *
+ * @param {Buffer|string} patch
+ * @returns {string[]} sorted, unique paths
+ */
+export function extractPatchFiles(patch) {
+  const text = Buffer.isBuffer(patch) ? patch.toString('utf8') : String(patch ?? '');
+  const files = new Set();
+  for (const line of text.split('\n')) {
+    const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+    if (match) files.add(match[2]);
+  }
+  return [...files].sort();
+}

package/src/testing/paths.mjs

@@ -0,0 +1,49 @@
+// The test-path convention: is this repository-relative path a test?
+//
+// The directories are structural (`test/`, `tests/`, `spec/`, `__tests__/`, `src/test/`)
+// and the suffixes are file conventions. A language's own convention arrives as data —
+// the ecosystem records' `testConventions` (ADR-013) — so a new language lands in a
+// record, not in this file.
+//
+// This module lives outside `src/bench/` because the index, the gate and the map all ask
+// this question. Production code importing it from the bench made the bench a
+// requirement for commands that never run a benchmark (review 0003 Q79).
+import { testConventions } from '../ecosystem/records.mjs';
+
+/**
+ * The `testConventions` records' `base` sources, compiled once.
+ *
+ * De-duplicated because a language may share a pattern with a sibling (the JVM pattern
+ * matches both `.java` and `.kt`); a duplicate RegExp is the same check run twice.
+ */
+const LANG_TEST_PATTERNS = [...new Set(testConventions().flatMap((record) => record.base ?? []))].map(
+  (src) => new RegExp(src),
+);
+
+const TEST_DIRECTORIES = ['test', 'tests', 'spec', '__tests__', 'src/test'];
+
+/**
+ * Classify whether a repository-relative path is a test file.
+ *
+ * @param {string} relPath forward-slash repository-relative path
+ * @returns {boolean}
+ */
+export function isTestPath(relPath) {
+  const norm = String(relPath).replaceAll('\\', '/').replace(/^\.\//, '');
+  if (!norm) return false;
+  const segments = norm.split('/');
+  const base = segments[segments.length - 1];
+
+  if (
+    TEST_DIRECTORIES.some((dir) => norm.startsWith(`${dir}/`)) ||
+    segments.some((segment) => ['__tests__', 'test', 'tests', 'spec'].includes(segment))
+  ) {
+    return true;
+  }
+
+  if (/\.(?:test|spec)\.[A-Za-z0-9]+$/.test(base)) return true;
+  if (/_(?:test|spec)\.[A-Za-z0-9]+$/.test(base)) return true;
+  if (LANG_TEST_PATTERNS.some((re) => re.test(base))) return true;
+
+  return false;
+}

package/src/testing/runners.mjs

@@ -0,0 +1,186 @@
+// Which runner a repository uses, and the command that runs one set of test files.
+//
+// Detection reads the repository's own manifest, never a guess from a directory name: the
+// runner that is installed is the runner a contributor runs. This module is
+// production-facing because `simt gate` runs the repository's tests (review 0003 Q79);
+// the bench uses the same answer, so a benchmarked run and a gated run cannot disagree
+// about what `test` means.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+import {
+  dedupeSorted,
+  parseCargoTestOutput,
+  parseGoTestJson,
+  parseJunitXml,
+  parseTapOutput,
+  parseVitestJson,
+} from './parsers.mjs';
+
+let junitCounter = 0;
+
+/**
+ * A JUnit report path this process owns.
+ *
+ * The report used to be written beside the sources as `.bench-junit.xml`, so running the
+ * gate in a Python repository left a file in the package directory (review 0003 Q79). It
+ * belongs to the run, so it lives in the temporary directory and `cleanupReports` removes
+ * it once the run has been read.
+ */
+function junitReportPath() {
+  junitCounter += 1;
+  return join(tmpdir(), `${CLI}-junit-${process.pid}-${junitCounter}.xml`);
+}
+
+/**
+ * Detect the test runner for a repository and build the command for a set of changed test
+ * files.
+ *
+ * @param {string} root
+ * @param {string[]} testFiles
+ * @returns {Promise<{runner: string, displayCmd: string,
+ *   buildExec: (worktree: string) => {cmd: string, args: string[], reportPaths?: string[]},
+ *   parse: (stdout: string, reportText?: string) => {passed: string[], failed: string[]}}|null>}
+ */
+export async function detectTestRunner(root, testFiles) {
+  const files = [...testFiles].sort();
+
+  if (existsSync(join(root, 'package.json'))) {
+    let pkg = {};
+    try {
+      pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    } catch {
+      pkg = {};
+    }
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    const testScript = String(pkg.scripts?.test ?? '');
+    if (deps.vitest || /\bvitest\b/.test(testScript)) {
+      const bin = join('node_modules', '.bin', 'vitest');
+      return {
+        runner: 'vitest',
+        displayCmd: `vitest run --reporter=json ${files.join(' ')}`,
+        buildExec: (worktree) => ({
+          cmd: existsSync(join(worktree, bin)) ? join(worktree, bin) : 'vitest',
+          args: ['run', '--reporter=json', ...files],
+        }),
+        parse: (stdout) => parseVitestJson(stdout),
+      };
+    }
+    // Jest emits the same `testResults`/`assertionResults` JSON shape as Vitest (Vitest
+    // copied it), so the JSON parser serves both (review 0003 Q48: a Jest repository fell
+    // through to `node --test` and parsed TAP out of JSON).
+    if (deps.jest || /\bjest\b/.test(testScript)) {
+      const bin = join('node_modules', '.bin', 'jest');
+      return {
+        runner: 'jest',
+        displayCmd: `jest --json ${files.join(' ')}`,
+        buildExec: (worktree) => ({
+          cmd: existsSync(join(worktree, bin)) ? join(worktree, bin) : 'jest',
+          args: ['--json', ...files],
+        }),
+        parse: (stdout) => parseVitestJson(stdout),
+      };
+    }
+    return {
+      runner: 'node-test',
+      displayCmd: `node --test ${files.join(' ')}`,
+      buildExec: () => ({
+        cmd: process.execPath,
+        args: ['--test', '--test-reporter=tap', ...files],
+      }),
+      parse: (stdout) => parseTapOutput(stdout),
+    };
+  }
+
+  if (existsSync(join(root, 'Cargo.toml'))) {
+    // Cargo has no "run this file" argument. An integration test is a target named after
+    // its file in `tests/`, so it can be selected with `--test`. A source file carries
+    // inline unit tests and can only be reached by the crate's test binary, so one such
+    // file means the whole crate runs.
+    const targets = dedupeSorted(
+      files.filter((file) => /^tests\/[^/]+\.rs$/.test(file)).map((file) => basename(file, '.rs')),
+    );
+    const integrationOnly = files.length > 0 && files.every((file) => /^tests\/[^/]+\.rs$/.test(file));
+    const args = ['test'];
+    if (integrationOnly) {
+      for (const target of targets) args.push('--test', target);
+    }
+    return {
+      runner: 'cargo-test',
+      displayCmd: ['cargo', ...args].join(' '),
+      buildExec: () => ({ cmd: 'cargo', args }),
+      parse: (stdout) => parseCargoTestOutput(stdout),
+    };
+  }
+
+  if (existsSync(join(root, 'go.mod'))) {
+    const packages = dedupeSorted(
+      files.map((file) => {
+        const dir = dirname(file);
+        return dir === '.' ? './...' : `./${dir}`;
+      }),
+    );
+    return {
+      runner: 'go-test',
+      displayCmd: `go test -json ${packages.join(' ')}`,
+      buildExec: () => ({ cmd: 'go', args: ['test', '-json', ...packages] }),
+      parse: (stdout) => parseGoTestJson(stdout),
+    };
+  }
+
+  if (
+    existsSync(join(root, 'pyproject.toml')) ||
+    existsSync(join(root, 'requirements.txt')) ||
+    existsSync(join(root, 'setup.py'))
+  ) {
+    return {
+      runner: 'pytest',
+      displayCmd: `pytest ${files.join(' ')}`,
+      buildExec: () => {
+        const reportPath = junitReportPath();
+        return {
+          cmd: 'pytest',
+          args: [`--junitxml=${reportPath}`, ...files],
+          reportPaths: [reportPath],
+        };
+      },
+      parse: (_stdout, reportText) => parseJunitXml(reportText ?? ''),
+    };
+  }
+
+  if (existsSync(join(root, 'build.gradle.kts')) || existsSync(join(root, 'build.gradle'))) {
+    const classes = files.map((file) => basename(file).replace(/\.(?:java|kt)$/, '')).filter(Boolean);
+    const filterArgs = classes.flatMap((name) => ['--tests', `*${name}*`]);
+    return {
+      runner: 'gradle',
+      displayCmd: `./gradlew test ${filterArgs.join(' ')}`.trim(),
+      buildExec: (worktree) => ({
+        cmd: existsSync(join(worktree, 'gradlew')) ? join(worktree, 'gradlew') : 'gradle',
+        args: ['test', ...filterArgs],
+        // One XML per test class; readReports walks the directory.
+        reportPaths: [join(worktree, 'build', 'test-results', 'test')],
+      }),
+      parse: (_stdout, reportText) => parseJunitXml(reportText ?? ''),
+    };
+  }
+
+  if (existsSync(join(root, 'pom.xml'))) {
+    const classes = files.map((file) => basename(file).replace(/\.(?:java|kt)$/, '')).filter(Boolean);
+    const arg = classes.length > 0 ? [`-Dtest=${classes.join(',')}`] : [];
+    return {
+      runner: 'maven',
+      displayCmd: `mvn test ${arg.join(' ')}`.trim(),
+      buildExec: (worktree) => ({
+        cmd: 'mvn',
+        args: ['test', ...arg],
+        // Surefire writes one XML per class here (review 0003 Q48).
+        reportPaths: [join(worktree, 'target', 'surefire-reports')],
+      }),
+      parse: (_stdout, reportText) => parseJunitXml(reportText ?? ''),
+    };
+  }
+
+  return null;
+}