testguard-cli 0.3.1 → 0.5.0

package/src/probe/{runner-vitest.mjs → runners/shared.mjs}

@@ -3,12 +3,11 @@ import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { matchGlobs } from '../util/glob.mjs';
+import { matchGlobs } from '../../util/glob.mjs';
 
-const TEST_GLOBS = ['**/*.test.js', '**/*.test.mjs', '**/*.test.cjs', '**/*.test.ts', '**/*.test.mts', '**/*.test.tsx', '**/*.test.jsx',
+export const TEST_GLOBS = ['**/*.test.js', '**/*.test.mjs', '**/*.test.cjs', '**/*.test.ts', '**/*.test.mts', '**/*.test.tsx', '**/*.test.jsx',
   '**/*.spec.js', '**/*.spec.mjs', '**/*.spec.cjs', '**/*.spec.ts', '**/*.spec.mts', '**/*.spec.tsx', '**/*.spec.jsx'];
-
-export const name = 'vitest';
+export const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
 
 /**
  * Split a runner command template into argv. Supports double and single
@@ -45,14 +44,13 @@ export function parseCommandTemplate(template) {
 export const expandCommand = (words, files, outFile) => words.flatMap((w) => (w === '{files}' ? files : [w.replaceAll('{out}', outFile)]));
 
 /**
- * Can the runner be resolved at all from this directory? Run before any
- * verdict is attempted: an unresolvable runner is a precondition failure,
- * never a statement about the tests.
+ * Can `bin` be resolved at all from this directory? Run before any verdict
+ * is attempted: an unresolvable runner is a precondition failure, never a
+ * statement about the tests.
  */
-export function checkRunner({ projectDir, budgetMs = 60_000, env = process.env }) {
-  const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+export function checkBinary({ projectDir, bin, budgetMs = 60_000, env = process.env }) {
   return new Promise((resolve) => {
-    const child = spawn(npx, ['--no-install', 'vitest', '--version'], { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...env, CI: '1' } });
+    const child = spawn(npx, ['--no-install', bin, '--version'], { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...env, CI: '1' } });
     let out = '';
     let err = '';
     child.on('error', (e) => resolve({ ok: false, message: e.message }));
@@ -61,7 +59,7 @@ export function checkRunner({ projectDir, budgetMs = 60_000, env = process.env }
     const timer = setTimeout(() => child.kill('SIGKILL'), budgetMs);
     child.on('close', (code) => {
       clearTimeout(timer);
-      const version = out.trim().replace(/^vitest\//, '');
+      const version = out.trim().replace(/^vitest\//, '').split('\n').pop();
       resolve(code === 0 && version ? { ok: true, version } : { ok: false, message: (err || out).trim().split('\n').filter(Boolean).slice(-1)[0] ?? `exit ${code}` });
     });
   });
@@ -70,7 +68,7 @@ export function checkRunner({ projectDir, budgetMs = 60_000, env = process.env }
 /** Defender globs → existing files. Empty result is the `nocover` signal. */
 export const resolveDefenders = (projectDir, globs) => matchGlobs(projectDir, globs ?? []);
 
-export const listTestFiles = (projectDir) => matchGlobs(projectDir, TEST_GLOBS);
+export const listTestFiles = (projectDir, globs = TEST_GLOBS) => matchGlobs(projectDir, globs);
 
 /**
  * Turn vitest's JSON report into a spec `testRun`.
@@ -80,11 +78,16 @@ export const listTestFiles = (projectDir) => matchGlobs(projectDir, TEST_GLOBS);
  * can kill a fault. A suite that fails to load, or a test that times out, is
  * not evidence that the suite defends the claim.
  */
+function firstInformativeLine(message) {
+  const lines = message.split('\n').map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').trim()).filter(Boolean);
+  return lines.find((l) => /error|syntax|unexpected|expected .+ but found|cannot find|failed to parse|transform failed/i.test(l) && !/^●/.test(l)) ?? lines[0] ?? '';
+}
+
 export function parseReport(report, durationMs) {
   const files = report.testResults ?? [];
   const loadFailed = files.some((f) => f.status === 'failed' && (f.assertionResults?.length ?? 0) === 0);
   const results = files.flatMap((f) => (f.assertionResults ?? []).map((t) => ({ ...t, id: `${f.name}::${t.fullName ?? t.title ?? ''}` }))).filter((t) => t.status === 'failed');
-  const timeouts = results.filter((t) => (t.failureMessages ?? []).some((m) => /timed out/i.test(m))).length;
+  const timeouts = results.filter((t) => (t.failureMessages ?? []).some((m) => /timed out|exceeded timeout/i.test(m))).length;
   const failedTests = results.map((t) => t.id);
   const assertionFailures = results.length - timeouts;
   const tests = { total: report.numTotalTests ?? 0, passed: report.numPassedTests ?? 0, failed: report.numFailedTests ?? 0 };
@@ -95,20 +98,25 @@ export function parseReport(report, durationMs) {
   else outcome = 'fail';
 
   const run = { outcome, tests, assertionFailures, durationMs };
-  const loadMessage = loadFailed ? (files.find((f) => f.message)?.message ?? '').split('\n')[0] : undefined;
+  // jest opens a load failure with "● Test suite failed to run" and puts the
+  // cause lines below; vitest puts it on the first line. Take the first line
+  // that names an error, else the first non-empty one.
+  const loadMessage = loadFailed ? firstInformativeLine(files.find((f) => f.message)?.message ?? '') : undefined;
   return { run, timeouts, loadMessage, failedTests };
 }
 
 /**
- * Run vitest on `files` inside `projectDir` with a hard wall-clock budget.
- * The budget matters because a synchronous infinite loop is immune to
- * vitest's own test timeout; only killing the process ends it.
+ * Run a test process on `files` inside `projectDir` with a hard wall-clock
+ * budget and read back its jest-compatible JSON report. The budget matters
+ * because a synchronous infinite loop is immune to any runner's own test
+ * timeout; only killing the process ends it. `argv(files, outFile)` is the
+ * runner's command line; `command` (tests) or `commandTemplate` (--runner-cmd)
+ * override it.
  */
-export function runVitest({ projectDir, files, budgetMs = 120_000, command, commandTemplate }) {
-  const outFile = join(tmpdir(), `testguard-vitest-${randomBytes(6).toString('hex')}.json`);
-  const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+export function runProcess({ projectDir, files, budgetMs = 120_000, command, commandTemplate, argv }) {
+  const outFile = join(tmpdir(), `testguard-run-${randomBytes(6).toString('hex')}.json`);
   const [cmd, ...args] = command
-    ?? (commandTemplate ? expandCommand(commandTemplate, files, outFile) : [npx, 'vitest', 'run', ...files, '--reporter=json', `--outputFile=${outFile}`]);
+    ?? (commandTemplate ? expandCommand(commandTemplate, files, outFile) : argv(files, outFile));
   const started = Date.now();
 
   return new Promise((resolve) => {

package/src/probe/runners/vitest.mjs

@@ -0,0 +1,7 @@
+import { TEST_GLOBS, npx, runProcess, checkBinary, listTestFiles } from './shared.mjs';
+
+export const name = 'vitest';
+export const testGlobs = TEST_GLOBS;
+export const check = (opts) => checkBinary({ ...opts, bin: 'vitest' });
+export const tests = (projectDir) => listTestFiles(projectDir, testGlobs);
+export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => [npx, 'vitest', 'run', ...files, '--reporter=json', `--outputFile=${outFile}`] });

package/src/status/status.mjs

@@ -4,9 +4,10 @@ import { readSpecDoc } from '../evidence/writer.mjs';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { gate } from '../baseline/baseline.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
-import { resolveDefenders } from '../probe/runner-vitest.mjs';
+import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
 import { sortForReport } from '../render.mjs';
+import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
@@ -22,7 +23,7 @@ const P = (projectDir) => ({
  * Reads the claims file, evidence, baseline and the working tree; never
  * trusts a cached verdict whose inputs have changed.
  */
-export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20 }) {
+export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20, changedRef, includeDirty = false }) {
   const rel = (p) => relative(projectDir, p) || '.';
   const doc = {
     schemaVersion: 1,
@@ -37,7 +38,32 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     findings: [],
     paths: {},
   };
-  if (!existsSync(paths.claims)) return doc;
+  // ── Claim coverage of the change, when a reference is known ──
+  // Computed before anything about evidence: a change that touches unclaimed
+  // code is the finding every field report shared, and TestGuard is silent
+  // about unclaimed code by construction. The claim is written first.
+  // The reference is the caller's: this function never reads the environment,
+  // so a library caller or a test in a temp directory is never surprised by CI.
+  const ref = changedRef;
+  let changes;
+  if (ref) {
+    const g = computeChangedGate({ projectDir, ref, includeDirty, toolVersion });
+    changes = { ref: g.ref, base: g.base, includeDirty: g.includeDirty, changed: g.changed, evaluated: g.evaluated, excluded: g.excluded.length, uncovered: g.uncovered, reliedOn: g.reliedOn, expired: g.expired };
+    doc.changes = changes;
+    if (existsSync(defaultIgnorePath(projectDir))) doc.paths.ignore = rel(defaultIgnorePath(projectDir));
+  }
+  const unclaimedWhy = () => {
+    const files = changes.uncovered.map((u) => u.file);
+    return `${files.length} changed file${files.length === 1 ? '' : 's'} since ${changes.ref} carr${files.length === 1 ? 'ies' : 'y'} no claim and no excusing ignore entry: ${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}. State the claim before writing more code — TestGuard is silent about unclaimed code by construction.`;
+  };
+
+  if (!existsSync(paths.claims)) {
+    if (changes?.uncovered.length) {
+      const u = changes.uncovered[0];
+      doc.next = { action: 'scaffold', command: `testguard scaffold ${u.file}`, why: `No testguard.claims.json in this project, and ${unclaimedWhy()}`, file: u.file };
+    }
+    return doc;
+  }
   doc.paths.claims = rel(paths.claims);
 
   const claims = loadClaims(paths.claims);
@@ -46,6 +72,13 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   const faultIndex = new Map();
   for (const c of claims.claims) for (const f of c.faults) faultIndex.set(`${c.id}/${f.id}`, { claim: c, fault: f });
 
+  if (changes && changes.uncovered.length > 0) {
+    const u = changes.uncovered[0];
+    doc.state = 'unclaimed-changes';
+    doc.next = { action: 'claim', command: u.suggestion, why: unclaimedWhy(), file: u.file };
+    return doc;
+  }
+
   const hasEvidence = existsSync(paths.evidence);
   const hasProvisional = existsSync(paths.provisional);
   if (hasProvisional) doc.paths.provisionalEvidence = rel(paths.provisional);
@@ -155,6 +188,13 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
 
 export function renderStatus(doc) {
   const lines = [`state: ${doc.state}${doc.provisional ? ' (provisional)' : ''} — ${doc.counts.claims} claims / ${doc.counts.faults} faults` + (doc.counts.byVerdict ? `; ${Object.entries(doc.counts.byVerdict).map(([k, v]) => `${v} ${k}`).join(', ')}; ${doc.counts.new ?? 0} new, ${doc.counts.baselined ?? 0} baselined` : '')];
+  if (doc.changes) {
+    const c = doc.changes;
+    lines.push(`changes:  ${c.changed} file${c.changed === 1 ? '' : 's'} since ${c.ref}; ${c.evaluated} evaluated, ${c.excluded} excluded, ${c.uncovered.length} unclaimed`);
+    for (const u of c.uncovered) lines.push(`UNCLAIMED ${u.file} (${u.kind}) → ${u.suggestion}`);
+    for (const r of c.reliedOn) lines.push(`excused   ${r.files.join(', ')} by ignore "${r.pattern}": ${r.reason}`);
+    for (const e of c.expired) lines.push(`EXPIRED   ignore "${e.pattern}" no longer excuses ${e.files.join(', ')}`);
+  }
   for (const c of doc.changedFaults) lines.push(`CHANGED   ${c.claimId}/${c.subjectId} edited since it ${c.previousVerdict} (${c.file})`);
   for (const s of doc.stale.slice(0, 8)) lines.push(`stale     ${s}`);
   lines.push(`next:     [${doc.next.action}] ${doc.next.command}`);