testguard-cli 0.18.3 → 0.20.0

package/src/commands/brief.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
-import { buildBrief, buildUnclaimedBrief, renderBriefMarkdown, renderUnclaimedMarkdown } from '../brief/brief.mjs';
+import { buildBrief, buildUnclaimedBrief, renderBriefMarkdown, renderUnclaimedMarkdown, installLabel } from '../brief/brief.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
@@ -39,7 +39,7 @@ export async function briefCommand({ projectDir, values, version }, io) {
     return 3;
   }
   // Where this binary came from, so a stale install is visible in the session-start context.
-  const install = /[\\/]node_modules[\\/]/.test(process.argv[1] ?? '') ? 'local install' : 'global';
+  const install = installLabel(process.argv[1]);
   const brief = buildBrief(evidence, baseline, { max, next: status?.next, changes: status?.changes, install });
   if (!values.text && !values.markdown) writeSpecDoc('brief', values.out ? resolve(values.out) : join(projectDir, '.testguard', 'brief.json'), brief);
   if (values.markdown) io.out(renderBriefMarkdown({ ...brief, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.length, install }).trimEnd());

package/src/commands/claims.mjs

@@ -41,7 +41,7 @@ export async function claimsCommand({ projectDir, values, suppliedOptions, versi
   const drift = reconcile(claims, annotations);
   const advisory = annotationAdvisory(claims, annotations, { customClaims: Boolean(values.claims) });
   const anchorChecks = values['check-anchors']
-    ? await checkAnchors(projectDir, claims, { python: values.python ? resolve(values.python) : undefined })
+    ? await checkAnchors(projectDir, claims, { python: values.python || undefined }) // a bare name is a PATH lookup; see explicitInterpreter
     : undefined;
 
   // A claim that disappeared is invisible to every other command; compare

package/src/commands/concerns.mjs

@@ -1,6 +1,5 @@
 import { resolve } from 'node:path';
 import { loadConcerns, renderConcerns } from '../supply/concerns.mjs';
-import { validate } from '../../spec/lib/validate.mjs';
 
 /**
  * `testguard concerns [dir]`: the one-sentence scopes a sweep can be aimed by.
@@ -13,16 +12,9 @@ import { validate } from '../../spec/lib/validate.mjs';
  */
 export async function concernsCommand({ projectDir, values, version }, io) {
   const path = values.concerns ? resolve(values.concerns) : undefined;
+  // A file that does not parse or does not conform throws a SpecDocError
+  // naming it, which the CLI reports as exit 2: wrong with the FILE.
   const loaded = loadConcerns(projectDir, { path });
-
-  if (loaded.source) {
-    const result = validate('concerns', { schemaVersion: 1, concerns: loaded.raw });
-    if (!result.ok) {
-      io.err(`${loaded.source} does not conform to the spec:`);
-      for (const e of result.errors) io.err(`  ${e.path}: ${e.message}`);
-      return 2;
-    }
-  }
   if (values.json) {
     io.out(JSON.stringify({ schemaVersion: 1, tool: { name: 'testguard', version }, source: loaded.source, shadowed: loaded.shadowed, concerns: loaded.concerns }, null, 2));
   } else {

package/src/commands/gate.mjs

@@ -1,5 +1,5 @@
 import { join, resolve } from 'node:path';
-import { computeChangedGate, resolveChangedRef, renderGate, DEFAULT_EXCLUDES } from '../gate/changed.mjs';
+import { computeChangedGate, resolveChangedRef, renderGate, explainExclusions } from '../gate/changed.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 
 export const gatePath = (projectDir) => join(projectDir, '.testguard', 'gate.json');
@@ -11,9 +11,7 @@ export const gatePath = (projectDir) => join(projectDir, '.testguard', 'gate.jso
  */
 export async function gateCommand({ projectDir, values, version }, io) {
   if (values.explain) {
-    io.out('Files that are source by extension but never carry claims (excluded by default; add more with --exclude <glob>):');
-    for (const g of DEFAULT_EXCLUDES) io.out(`  ${g}`);
-    io.out('Non-source files (anything but .js .mjs .cjs .ts .mts .cts .jsx .tsx) are excluded before these patterns apply.');
+    for (const line of explainExclusions()) io.out(line);
     return 0;
   }
   const resolved = resolveChangedRef({ explicit: values.changed, projectDir });

package/src/commands/init.mjs

@@ -1,7 +1,17 @@
-import { initProject } from '../init/init.mjs';
+import { initProject, InitUsageError } from '../init/init.mjs';
 
 export async function initCommand({ projectDir, values }, io) {
-  const r = initProject({ projectDir, force: values.force, here: values.here, ciEvidence: values['ci-evidence'], mcp: values.mcp });
+  let r;
+  try {
+    r = initProject({ projectDir, force: values.force, here: values.here, ciEvidence: values['ci-evidence'], mcp: values.mcp });
+  } catch (e) {
+    // A bad option is the caller's to fix, and init has written nothing yet:
+    // every option is checked before the first write.
+    if (!(e instanceof InitUsageError)) throw e;
+    io.err(e.message);
+    io.err("Run 'testguard init --help' for its options. Nothing was written.");
+    return 3;
+  }
   const { done, skipped, warnings, agentRoot, dir, mcpConfig } = r;
   if (values.json) {
     io.out(JSON.stringify({ done, skipped, warnings, agentRoot, dir, ...(mcpConfig ? { mcpConfig } : {}) }, null, 2));

package/src/commands/probe.mjs

@@ -14,6 +14,7 @@ import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
 import { originPolicyRequest, evaluateOriginPolicy } from '../probe/origin-policy.mjs';
 import { readNativeTestUniverse } from '../probe/universe.mjs';
 import { originPolicyInputsFresh } from '../probe/policy-freshness.mjs';
+import { runnerOptions } from './runner-options.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -57,6 +58,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.err('--command-budget must be at least 1000 milliseconds');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const commandBudget = createCommandBudget(commandBudgetMs);
   if (values.progress && !isProgressMode(values.progress)) {
     io.err(`--progress must be one of auto, tty, plain, ndjson, none (got ${values.progress})`);
@@ -113,10 +119,10 @@ export async function probeCommand({ projectDir, values, version }, io) {
     refExplicit: values.ref !== undefined,
     ignoreDirty: values['ignore-dirty'],
     onWarn: (m) => io.err(`warning: ${m}`),
-    runnerCommand: values['runner-cmd'],
+    runnerCommand: runner.runnerCommand,
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
-    python: values.python ? resolve(values.python) : undefined,
+    python: runner.python,
     only,
     escalate: !values['no-escalate'],
     toolVersion: version,
@@ -139,11 +145,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     let universe;
     // Custom commands carry a static universe, which cannot establish this
     // native policy boundary. Discovery failures are unavailability, not kills.
-    if (!values['runner-cmd']) {
+    if (!runner.runnerCommand) {
       try {
         universe = await readNativeTestUniverse({
           projectDir, sourceDir: projectDir, runnerName: values.runner,
-          python: values.python ? resolve(values.python) : undefined,
+          python: runner.python,
           budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs,
           budgetFor: () => commandBudget?.runBudget(budgetMs) ?? budgetMs,
           assertOpen: () => commandBudget?.assertOpen(),
@@ -187,7 +193,9 @@ export async function probeCommand({ projectDir, values, version }, io) {
     const killed = evidence.records.filter((r) => r.verdict === 'killed').length;
     if (killed) io.out(`  ${killed} killed (not listed; --verbose to see them)`);
   }
-  io.out(renderSummary(evidence.records, evidence.run) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
+  io.out(renderSummary(evidence.records, evidence.run));
+  // Its own line: the summary ends with the origins line, which is not a sentence to append to.
+  io.out(baseline ? `${g.new.length} new since baseline, ${g.baselined.length} baselined.` : 'No baseline.');
   if (policy) io.out(renderOriginPolicy(policy, { basis: 'current' }));
   if (values.cost) {
     io.out('');

package/src/commands/replay.mjs

@@ -2,6 +2,7 @@ import { dirname, join, resolve } from 'node:path';
 import { replay, calibrationFrom, renderReplay } from '../replay/replay.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
+import { runnerOptions } from './runner-options.mjs';
 
 export const replayPath = (projectDir) => join(projectDir, '.testguard', 'replay.json');
 export const calibrationPath = (projectDir) => join(projectDir, '.testguard', 'calibration.json');
@@ -29,6 +30,11 @@ export async function replayCommand({ projectDir, values, version }, io) {
     io.err('--command-budget must be at least 1000 milliseconds');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const commandBudget = createCommandBudget(commandBudgetMs);
 
   const doc = await replay({
@@ -39,9 +45,10 @@ export async function replayCommand({ projectDir, values, version }, io) {
     workers,
     serial: values.serial || workers === 1,
     commandBudget,
-    runnerCommand: values['runner-cmd'],
+    runnerCommand: runner.runnerCommand,
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    python: runner.python,
     limit,
     toolVersion: version,
     onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ commit, i, n, stage }) => process.stderr.write(`\r\x1b[K  … ${commit.slice(0, 9)} (${i}/${n}) ${stage}`) : undefined,
@@ -55,7 +62,7 @@ export async function replayCommand({ projectDir, values, version }, io) {
   // Beside the replay document, whatever --out says: the two are one result,
   // and splitting them across directories loses the pairing — and leaves a
   // file behind in a repository the run is only meant to read.
-  const calPath = values.baseline ? resolve(values.baseline) : values.out ? join(dirname(outPath), 'calibration.json') : calibrationPath(projectDir);
+  const calPath = values['calibration-out'] ? resolve(values['calibration-out']) : values.out ? join(dirname(outPath), 'calibration.json') : calibrationPath(projectDir);
   // Replay and calibration are one result. Cross the deadline boundary only
   // after both complete documents exist in memory; serialization is then the
   // documented non-interruptible final step, so expiry can never leave half

package/src/commands/runner-options.mjs

@@ -0,0 +1,28 @@
+import { parseCommandTemplate } from '../probe/runners/shared.mjs';
+
+/**
+ * The runner options every command that runs tests shares — probe, admit,
+ * sweep, replay — checked once, before any work. A malformed `--runner-cmd` is
+ * a usage error (exit 3) with the reason, never a RangeError surfacing as
+ * "this is a bug in testguard"; and an empty value was asked for, so it is
+ * refused rather than read as "no command".
+ *
+ * `python` is passed through as typed. Whether it is a command on PATH or a
+ * path is decided in one place (`explicitInterpreter`), the same way for
+ * `--python` and `TESTGUARD_PYTHON`.
+ */
+export function runnerOptions(values) {
+  const runnerCommand = values['runner-cmd'];
+  if (runnerCommand !== undefined) {
+    try {
+      parseCommandTemplate(runnerCommand);
+    } catch (error) {
+      return { error: error.message };
+    }
+  }
+  const python = values.python;
+  if (python !== undefined && python.trim() === '') {
+    return { error: '--python must name an interpreter: a path such as .venv/bin/python, or a command on PATH such as python3' };
+  }
+  return { runnerCommand, python };
+}

package/src/commands/sweep.mjs

@@ -3,6 +3,7 @@ import { sweep, renderSweep, ConcernError } from '../sweep/sweep.mjs';
 import { resolveChangedRef } from '../gate/changed.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
+import { runnerOptions } from './runner-options.mjs';
 
 export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.json');
 /**
@@ -46,6 +47,11 @@ export async function sweepCommand({ projectDir, values, version }, io) {
     io.err('--command-budget must be at least 1000 milliseconds');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const commandBudget = createCommandBudget(commandBudgetMs);
   // A concern that aims at the write surface or at a glob needs no diff, the
   // same as --save-paths. Only a concern that defers to the gate does.
@@ -85,9 +91,10 @@ export async function sweepCommand({ projectDir, values, version }, io) {
       workers,
       serial: values.serial || workers === 1,
       commandBudget,
-      runnerCommand: values['runner-cmd'],
+      runnerCommand: runner.runnerCommand,
       runnerName: values.runner,
       nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+      python: runner.python,
       toolVersion: version,
       claimsPath: values.claims ? resolve(values.claims) : undefined,
       ignorePath: values.ignore ? resolve(values.ignore) : undefined,

package/src/gate/changed.mjs

@@ -45,6 +45,17 @@ export const DEFAULT_EXCLUDES = Object.freeze([
 ]);
 const DEFAULT_EXCLUDE_RES = DEFAULT_EXCLUDES.map(globToRegExp);
 
+/**
+ * What `gate --explain` prints, built from the two lists the gate itself
+ * applies. A hand-written copy of the extension list omitted `.py` for as long
+ * as the gate had treated Python as source.
+ */
+export const explainExclusions = () => [
+  'Files that are source by extension but never carry claims (excluded by default; add more with --exclude <glob>):',
+  ...DEFAULT_EXCLUDES.map((g) => `  ${g}`),
+  `Non-source files (anything but ${[...SOURCE_EXT].join(' ')}) are excluded before these patterns apply.`,
+];
+
 /** Whether a source-shaped path is outside TestGuard's claimable module surface. */
 export const isDefaultExcluded = (file) => DEFAULT_EXCLUDE_RES.some((re) => re.test(file));
 

package/src/git.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { devNull, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
@@ -33,7 +33,17 @@ export function isAncestor(dir, ancestor, ref = 'HEAD') {
 /** True when any of `paths` (repo-relative; empty = whole tree) has uncommitted changes. */
 export const isDirty = (dir, paths = []) => git(['status', '--porcelain', '--', ...paths], dir).length > 0;
 
-export const addWorktree = (repo, dest, ref = 'HEAD') => git(['worktree', 'add', '--detach', dest, ref], repo);
+/**
+ * Leading options for a git command that checks files out into TestGuard's own
+ * scratch tree. That tree is the instrument, not a checkout the user made, so
+ * their post-checkout hook (husky, lefthook, Git LFS) must not run on it: a
+ * failing one fails the whole command after the files are already written, and
+ * Git LFS's fails whenever git-lfs is not on PATH. Filters, LFS smudge
+ * included, are config, not hooks, and still apply.
+ */
+export const NO_HOOKS = Object.freeze(['-c', `core.hooksPath=${devNull}`]);
+
+export const addWorktree = (repo, dest, ref = 'HEAD') => git([...NO_HOOKS, 'worktree', 'add', '--detach', dest, ref], repo);
 
 /**
  * A dangling commit holding the working tree exactly as it is — tracked