testguard-cli 0.18.3 → 0.19.0

package/src/probe/probe.mjs

@@ -21,7 +21,7 @@ import { hashFile, sha256 } from '../util/hash.mjs';
 import { fingerprint } from '../../spec/lib/fingerprint.mjs';
 import { recordedOriginSummary } from '../../spec/lib/origins.mjs';
 import { persistenceSignalsFor } from '../supply/persistence.mjs';
-import { collectOwnedManifests, hashNativeTestUniverse } from './universe.mjs';
+import { collectOwnedManifests, hashNativeTestUniverse, hashCustomCommandUniverse } from './universe.mjs';
 
 
 /** Is `child` the same file as `root`, or under it? Both must already be real paths. */
@@ -62,6 +62,27 @@ export function sameWorkerPolicy(previousRun, { workers = 1, serial = workers ==
   return previousRun?.workers === (serial ? 1 : workers) && Boolean(previousRun?.serial) === serial;
 }
 
+/**
+ * What the evidence says ran: the engine's name, the version it reported, and
+ * where it was resolved from (`project`, `path`, `builtin`). A custom command
+ * resolves nothing, so it claims no source.
+ */
+export function runnerRecord(name, version, source) {
+  return { name, ...(version ? { version } : {}), ...(source ? { source } : {}) };
+}
+
+/**
+ * Reuse cannot stand in for a measurement by a different runner. pytest and
+ * unittest are one adapter and two engines; a global vitest of the same
+ * version is a different binary from the project's. Evidence that recorded no
+ * runner cannot vouch for this one.
+ */
+export function sameRunner(previousRun, current) {
+  const recorded = previousRun?.runner;
+  if (!recorded) return false;
+  return recorded.name === current.name && recorded.version === current.version && recorded.source === current.source;
+}
+
 /**
  * Probe every fault of every claim. Returns a spec-conformant evidence
  * document; writing it is the caller's job.
@@ -205,13 +226,14 @@ export async function probe({
   // Contention: name it before the first run, and record it, so a later
   // reader of a TIMEOUT or FLAKY-DEFENDER knows the machine was loaded.
   const contention = detectContention();
-  if (contention.detected) onWarn(contentionWarning(contention));
+  if (contention.detected) onWarn(contentionWarning(contention, { serial, workers, custom: Boolean(runnerCommand) }));
 
   const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref: snapshot ?? ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
   const isoReal = realpathSync(iso.projectDir);
   const records = [];
   let runnerVersion;
   let runnerSource;
+  let recordedRunner;
   let primaryManifest;
   let runner = RUNNERS[runnerName === 'auto' ? 'vitest' : runnerName];
   // A runner with more than one engine (Python: pytest or unittest) is recorded
@@ -236,7 +258,8 @@ export async function probe({
       primaryManifest = sel.manifest;
       if (sel.engine) engines.set(sel.runner, sel.engine);
     }
-    runnersUsed.set(labelOf(runner), runnerVersion ?? readRunnerVersion(projectDir, runner.name));
+    recordedRunner = runnerRecord(labelOf(runner), runnerVersion ?? readRunnerVersion(projectDir, runner.name), runnerSource);
+    runnersUsed.set(recordedRunner.name, recordedRunner.version);
     // Files an owning runner (Playwright) claims run under it, whatever the
     // project runner is; it must resolve before the first such defender runs.
     const owned = OWNED_RUNNERS.filter((r) => r !== runner
@@ -283,7 +306,7 @@ export async function probe({
       ? [...new Set([...runner.tests(iso.projectDir).filter((t) => !owned.some((r) => r.owns(iso.projectDir, t))), ...owned.flatMap((r) => r.tests(iso.projectDir))])]
       : [...ownerByFile.keys()]).sort());
     const testUniverseHash = commandTemplate
-      ? sha256(JSON.stringify({ schemaVersion: 1, source: 'custom-command-static', files: allTests }))
+      ? hashCustomCommandUniverse(allTests, commandTemplate)
       : hashNativeTestUniverse(manifests);
     const baselineCache = new Map();
     const discoveryHashCache = new Map();
@@ -295,6 +318,7 @@ export async function probe({
     const fatalEditFor = (file) => runnerFor(iso.projectDir, file, runner).fatalEdit?.();
     const prior = previous && previous.run.confirmRuns === confirmRuns
       && sameWorkerPolicy(previous.run, { workers, serial, runnerCommand })
+      && sameRunner(previous.run, recordedRunner)
       ? new Map(previous.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]))
       : new Map();
     const partitionConfigured = (files) => {
@@ -403,7 +427,9 @@ export async function probe({
       startedAt,
       finishedAt: new Date().toISOString(),
       repo: { head, dirty, ...(snapshot ? { snapshot } : {}), ...(ignoredDirty.length ? { ignoredDirty } : {}) },
-      runner: { name: labelOf(runner), ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}), ...(runnerSource === 'builtin' ? { source: runnerSource } : {}) },
+      // Where the runner came from is part of what was measured: recorded for
+      // every resolved runner, as the schema documents, not only the builtin.
+      runner: recordedRunner,
       ...(runnersUsed.size > 1 ? { runners: [...runnersUsed].map(([n, v]) => ({ name: n, ...(v ? { version: v } : {}) })) } : {}),
       confirmRuns,
       measurements,

package/src/probe/runners/python.mjs

@@ -2,7 +2,7 @@ import { performance } from 'node:perf_hooks';
 import { existsSync, readFileSync } from 'node:fs';
 import { registerChild } from './lifecycle.mjs';
 import { spawn } from 'node:child_process';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runProcess, listTestFiles, firstInformativeLine, terminateProcessTree } from './shared.mjs';
 
@@ -69,6 +69,20 @@ export const testGlobs = ['**/test_*.py', '**/test*.py', '**/*_test.py'];
 const PY_FILE = /\.py$/;
 const TIMEOUT = /\bTimeout >|\btimed out\b|\bTimeoutError\b/i;
 
+/**
+ * The interpreter the operator named, with `--python` or `TESTGUARD_PYTHON` —
+ * both the same way, as a shell would. A bare command name (`python3`, no path
+ * separator) is looked up on PATH: resolving it against the working directory
+ * produced `<cwd>/python3`, which is never an interpreter. Anything with a
+ * separator is a path, resolved once against the working directory. An empty
+ * value names nothing.
+ */
+export function explicitInterpreter(value) {
+  if (typeof value !== 'string' || value === '') return undefined;
+  const bare = !value.includes('/') && !(process.platform === 'win32' && value.includes('\\'));
+  return bare ? { path: value, source: 'path' } : { path: resolve(value), source: 'project' };
+}
+
 /**
  * Interpreters to try, best first: the active virtualenv, the project's own,
  * then PATH.
@@ -82,8 +96,8 @@ function candidates(projectDir, python) {
   const out = [];
   const win = process.platform === 'win32';
   const binOf = (root) => (win ? join(root, 'Scripts', 'python.exe') : join(root, 'bin', 'python'));
-  const explicit = python ?? process.env.TESTGUARD_PYTHON;
-  if (explicit) return [{ path: explicit, source: 'project', explicit: true }];
+  const explicit = explicitInterpreter(python ?? process.env.TESTGUARD_PYTHON);
+  if (explicit) return [{ ...explicit, explicit: true }];
   if (process.env.VIRTUAL_ENV) out.push({ path: binOf(process.env.VIRTUAL_ENV), source: 'project' });
   for (const dir of ['.venv', 'venv', '.env']) out.push({ path: binOf(join(projectDir, dir)), source: 'project' });
   out.push({ path: win ? 'python.exe' : 'python3', source: 'path' });
@@ -159,9 +173,9 @@ export function resolveInterpreter({ projectDir, python, budgetMs = 30_000, budg
       if (answer) return { ...candidate, ...answer };
       tried.push(candidate.path);
     }
-    const explicit = python ?? process.env.TESTGUARD_PYTHON;
+    const explicit = explicitInterpreter(python ?? process.env.TESTGUARD_PYTHON);
     return { error: explicit
-      ? `${explicit} is not a usable Python interpreter`
+      ? `${explicit.path} is not a usable Python interpreter${explicit.source === 'path' ? ' (looked up on PATH)' : ''}`
       : `no usable Python interpreter (tried ${tried.join(', ') || 'nothing'}); install Python 3.8+, or point --python / TESTGUARD_PYTHON at one` };
   })();
   interpreters.set(key, task);

package/src/probe/universe.mjs

@@ -18,6 +18,17 @@ export function hashNativeTestUniverse(manifests) {
   return sha256(JSON.stringify(bound));
 }
 
+/**
+ * A custom `--runner-cmd` has no native listing, so its universe is the static
+ * file set — and the command itself. The files alone cannot tell a broken
+ * command from the fixed one, and a verdict measured by one is not an answer
+ * from the other. The parsed argv is hashed, so reformatting whitespace is not
+ * a change and the command text never appears in the evidence.
+ */
+export function hashCustomCommandUniverse(files, commandTemplate) {
+  return sha256(JSON.stringify({ schemaVersion: 2, source: 'custom-command-static', command: commandTemplate, files }));
+}
+
 /** Shared owning-adapter collection; check failures retain existing probe semantics. */
 export async function collectOwnedManifests(runner, primaryManifest, { projectDir, sourceDir, python, budgetMs, budgetFor, assertOpen = () => {} }) {
   const owned = OWNED_RUNNERS.filter((r) => r !== runner
@@ -41,7 +52,8 @@ export async function readNativeTestUniverse(options) {
   options.assertOpen?.();
   if (selected.error) throw new DiscoveryError(selected.error);
   const collection = await collectOwnedManifests(selected.runner, selected.manifest, options);
-  const primaryRunner = { name: selected.engine ?? selected.runner.name, version: selected.version };
-  const runners = [primaryRunner, ...[...collection.ownedChecked].filter(([, check]) => check.ok).map(([runner, check]) => ({ name: check.engine ?? runner.name, version: check.version }))];
+  const identity = (name, version, source) => ({ name, version, ...(source ? { source } : {}) });
+  const primaryRunner = identity(selected.engine ?? selected.runner.name, selected.version, selected.source);
+  const runners = [primaryRunner, ...[...collection.ownedChecked].filter(([, check]) => check.ok).map(([runner, check]) => identity(check.engine ?? runner.name, check.version, check.source))];
   return { ...collection, primary: selected.runner, primaryRunner, runners, testUniverseHash: hashNativeTestUniverse(collection.manifests) };
 }

package/src/replay/replay.mjs

@@ -2,7 +2,7 @@ import { resetInterpreterCache } from '../probe/runners/python.mjs';
 import { existsSync, rmSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { git, GitError, repoRoot, headSha } from '../git.mjs';
+import { git, GitError, NO_HOOKS, repoRoot, headSha } from '../git.mjs';
 import { createScratch, PreconditionError } from '../probe/worktree.mjs';
 import { selectRunner, discoverRunnerManifest, RUNNERS, OWNED_RUNNERS, mergeRuns } from '../probe/runners/index.mjs';
 import { parseCommandTemplate } from '../probe/runners/shared.mjs';
@@ -90,6 +90,7 @@ export async function replay({
   runnerCommand,
   runnerName = 'auto',
   nodeModules,
+  python,
   scratchBase,
   limit,
   toolVersion = '0.0.0',
@@ -123,7 +124,7 @@ export async function replay({
       let universe;
       if (!commandTemplate) {
         const budgetFor = () => commandBudget?.runBudget(budgetMs) ?? budgetMs;
-        const sel = await selectRunner({ projectDir: iso.projectDir, sourceDir: projectDir, name: runnerName, budgetMs: budgetFor(), budgetFor });
+        const sel = await selectRunner({ projectDir: iso.projectDir, sourceDir: projectDir, python, name: runnerName, budgetMs: budgetFor(), budgetFor });
         commandBudget?.assertOpen();
         if (sel.error) throw new PreconditionError(`test runner is not resolvable in the scratch worktree (${sel.error}). Pass --node-modules <path>.`);
         runnerUsed = sel.runner;
@@ -135,7 +136,7 @@ export async function replay({
         const primaryIsPython = ['python', 'pytest', 'unittest'].includes(runnerUsed.name);
         const owned = OWNED_RUNNERS.filter((candidate) => candidate !== runnerUsed && !(candidate.name === 'python' && primaryIsPython));
         for (const candidate of owned) {
-          const check = await candidate.check({ projectDir: iso.projectDir, sourceDir: projectDir, budgetMs: budgetFor(), budgetFor });
+          const check = await candidate.check({ projectDir: iso.projectDir, sourceDir: projectDir, python, budgetMs: budgetFor(), budgetFor });
           commandBudget?.assertOpen();
           if (!check.ok) continue;
           try {
@@ -146,7 +147,7 @@ export async function replay({
         }
         universe = buildReplayRunnerUniverse(runnerUsed, manifests);
       }
-      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
+      const record = await replayOne({ fix, iso, root, projectDir, python, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
       records.push(record);
       onProgress(record);
     } finally {
@@ -213,7 +214,7 @@ export function partitionReplayDefenders(files, primary, universe) {
   return groups;
 }
 
-async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner, universe, onStage, index, total }) {
+async function replayOne({ fix, iso, root, projectDir, python, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner, universe, onStage, index, total }) {
   // git reports paths from the REPOSITORY root; the runner and every file
   // operation here work inside the scratch worktree, relative to the PROJECT
   // directory. Map once, and refuse anything that would land outside the
@@ -262,7 +263,7 @@ async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, co
     return { ...base, faultClass, verdict: 'unverifiable', reason: 'no-prior-version', runs: [{ outcome: 'error', durationMs: 0 }] };
   }
   try {
-    if (existedBefore.length) git(['checkout', `${fix.commit}^`, '--', ...existedBefore.map(rel)], iso.projectDir);
+    if (existedBefore.length) git([...NO_HOOKS, 'checkout', `${fix.commit}^`, '--', ...existedBefore.map(rel)], iso.projectDir);
     for (const f of addedByTheFix) {
       const abs = join(iso.projectDir, rel(f));
       if (existsSync(abs)) rmSync(inside(abs), { force: true });
@@ -329,12 +330,12 @@ async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, co
       // A custom command is one explicit execution boundary. Preserve that
       // contract exactly; TestGuard cannot infer several native engines from
       // an opaque user command.
-      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate, workers, serial });
+      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, python, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate, workers, serial });
     } else {
       const parts = [];
       for (const [configuredRunner, files] of partitionReplayDefenders(related, runner, universe)) {
         commandBudget?.assertOpen();
-        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, workers, serial }));
+        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, python, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, workers, serial }));
         commandBudget?.assertOpen();
       }
       res = mergeRuns(parts);

package/src/supply/concerns.mjs

@@ -27,9 +27,10 @@
  * look; the probe says what it found; a human states the sentence worth
  * defending. Nothing here is written to `testguard.claims.json`.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { saveSurface } from './savepath.mjs';
+import { readSpecDoc } from '../evidence/writer.mjs';
 import { globToRegExp, walk } from '../util/glob.mjs';
 
 export const defaultConcernsPath = (projectDir) => join(projectDir, 'testguard.concerns.json');
@@ -80,8 +81,13 @@ export function loadConcerns(projectDir, { path } = {}) {
   let project = [];
   let source = null;
   if (existsSync(p)) {
-    const doc = JSON.parse(readFileSync(p, 'utf8'));
-    project = doc.concerns ?? [];
+    // Through the spec reader, for every caller: a file that does not parse or
+    // does not conform is a SpecDocError naming the file (exit 2), never a
+    // crash reported as a bug in this tool — and never a concern sweep quietly
+    // aims at nothing. A glob concern with no globs matches no file, and a
+    // sweep over no file reports clean.
+    const doc = readSpecDoc('concerns', p);
+    project = doc.concerns;
     source = p;
   }
   const overridden = new Set(project.map((c) => c.id));
@@ -91,11 +97,11 @@ export function loadConcerns(projectDir, { path } = {}) {
   ];
   return {
     concerns,
-    // The project's own entries, exactly as written. Validation runs against
-    // these: the enriched objects above carry a `builtin` marker this tool
-    // added, and a schema that refuses unknown properties is right to reject
-    // them. Validating what we constructed instead of what the user wrote
-    // would report OUR bug as THEIR malformed file.
+    // The project's own entries, exactly as written — and as validated above,
+    // before enrichment: the objects in `concerns` carry a `builtin` marker
+    // this tool added, and a schema that refuses unknown properties is right to
+    // reject them. Validating what we constructed instead of what the user
+    // wrote would report OUR bug as THEIR malformed file.
     raw: project.map(({ builtin, ...c }) => c),
     source,
     shadowed: BUILTIN_CONCERNS.filter((c) => overridden.has(c.id)).map((c) => c.id),

package/src/sweep/sweep.mjs

@@ -169,6 +169,7 @@ export async function sweep({
   runnerCommand,
   runnerName,
   nodeModules,
+  python,
   toolVersion = '0.0.0',
   generatedAt = new Date().toISOString(),
   claimsPath,
@@ -274,6 +275,7 @@ export async function sweep({
       runnerCommand,
       runnerName,
       nodeModules,
+      python,
       toolVersion,
       onStage,
       onWarn,