testguard-cli 0.14.2 → 0.15.1

package/src/commands/probe.mjs

@@ -10,6 +10,7 @@ import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 import { costReport, renderCost } from '../probe/cost.mjs';
 import { progressMode, stageReporter, clearStageLine, recordEvent, isProgressMode, progressStream } from '../probe/progress.mjs';
 import { validate } from '../../spec/lib/validate.mjs';
+import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -36,10 +37,16 @@ export function partialScope(only, records) {
 export async function probeCommand({ projectDir, values, version }, io) {
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
+  const commandBudgetMs = parseCommandBudget(values['command-budget']);
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
     return 3;
   }
+  if (commandBudgetMs === null) {
+    io.err('--command-budget must be at least 1000 milliseconds');
+    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})`);
     return 3;
@@ -50,6 +57,19 @@ export async function probeCommand({ projectDir, values, version }, io) {
   const stageOut = stageReporter(progress, (s) => progressTo.write(s));
   const claims = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
   if (claims.claims.length === 0) {
+    if (values['allow-empty'] && values.claim === undefined) {
+      io.err('claims file declares no claims; verification skipped (--allow-empty); run gate to check changed-file coverage');
+      if (values.json) {
+        const doc = computeStatus({ projectDir, toolVersion: version, paths: {
+          claims: values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir),
+          evidence: evidencePath(projectDir), provisional: provisionalEvidencePath(projectDir), baseline: baselinePath(projectDir),
+        } });
+        const result = validate('status', doc);
+        if (!result.ok) throw new Error(`empty probe JSON document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+        io.out(JSON.stringify(doc, null, 2));
+      }
+      return 0;
+    }
     io.err('claims file declares no claims; nothing to verify');
     return 2;
   }
@@ -74,6 +94,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
     previous,
     confirmRuns,
     budgetMs,
+    commandBudget,
     mode: values['in-place'] ? 'in-place' : 'worktree',
     ref: values.ref ?? 'HEAD',
     refExplicit: values.ref !== undefined,
@@ -101,6 +122,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
       if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r, { provisional, showDiscovered: firstOfClaim }) + (r.reusedFrom ? '  (reused)' : ''));
     },
   });
+  commandBudget?.assertOpen();
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });

package/src/commands/replay.mjs

@@ -1,6 +1,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';
 
 export const replayPath = (projectDir) => join(projectDir, '.testguard', 'replay.json');
 export const calibrationPath = (projectDir) => join(projectDir, '.testguard', 'calibration.json');
@@ -13,17 +14,24 @@ export async function replayCommand({ projectDir, values, version }, io) {
   }
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
+  const commandBudgetMs = parseCommandBudget(values['command-budget']);
   const limit = values.max ? Number(values.max) : undefined;
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
     return 3;
   }
+  if (commandBudgetMs === null) {
+    io.err('--command-budget must be at least 1000 milliseconds');
+    return 3;
+  }
+  const commandBudget = createCommandBudget(commandBudgetMs);
 
   const doc = await replay({
     projectDir,
     range,
     confirmRuns,
     budgetMs,
+    commandBudget,
     runnerCommand: values['runner-cmd'],
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
@@ -36,12 +44,17 @@ export async function replayCommand({ projectDir, values, version }, io) {
   });
 
   const outPath = values.out ? resolve(values.out) : replayPath(projectDir);
-  writeSpecDoc('replay', outPath, doc);
   const calibration = calibrationFrom(doc, { toolVersion: version });
   // 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);
+  // 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
+  // of the pair as though it were complete.
+  commandBudget?.assertOpen();
+  writeSpecDoc('replay', outPath, doc);
   writeSpecDoc('calibration', calPath, calibration);
 
   if (values.json) {

package/src/commands/sweep.mjs

@@ -2,6 +2,7 @@ import { join, resolve } from 'node:path';
 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';
 
 export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.json');
 /**
@@ -29,6 +30,18 @@ export const sweepEvidencePath = (projectDir) => join(projectDir, '.testguard',
  */
 export async function sweepCommand({ projectDir, values, version }, io) {
   const mode = values['save-paths'] ? 'save-paths' : 'changed';
+  const confirmRuns = Number(values.confirm);
+  const budgetMs = Number(values.budget);
+  const commandBudgetMs = parseCommandBudget(values['command-budget']);
+  if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
+    io.err('--confirm must be a positive integer and --budget at least 1000');
+    return 3;
+  }
+  if (commandBudgetMs === null) {
+    io.err('--command-budget must be at least 1000 milliseconds');
+    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.
   const aimed = Boolean(values.concern) || mode === 'save-paths';
@@ -41,12 +54,6 @@ export async function sweepCommand({ projectDir, values, version }, io) {
     io.err('sweep needs a reference to measure the change against: --changed <ref> (e.g. origin/main), or set TESTGUARD_CHANGED_REF. CI bases and a safe local remote default or differently named upstream are detected automatically. Or sweep the write surface instead with --save-paths.');
     return 3;
   }
-  const confirmRuns = Number(values.confirm);
-  const budgetMs = Number(values.budget);
-  if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
-    io.err('--confirm must be a positive integer and --budget at least 1000');
-    return 3;
-  }
   let cap;
   if (values.cap !== undefined) {
     cap = Number(values.cap);
@@ -70,6 +77,7 @@ export async function sweepCommand({ projectDir, values, version }, io) {
       cap,
       confirmRuns,
       budgetMs,
+      commandBudget,
       runnerCommand: values['runner-cmd'],
       runnerName: values.runner,
       nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
@@ -95,6 +103,7 @@ export async function sweepCommand({ projectDir, values, version }, io) {
 
   const { evidence, ...document } = doc;
   const outPath = values.out ? resolve(values.out) : sweepPath(projectDir);
+  commandBudget?.assertOpen();
   writeSpecDoc('sweep', outPath, document);
   // Written only when something was actually probed: an empty document would
   // teach the next run that every class is unproductive.

package/src/gate/changed.mjs

@@ -1,7 +1,7 @@
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, realpathSync, lstatSync } from 'node:fs';
 import { extname, join, relative, resolve, dirname } from 'node:path';
 import { git, repoRoot, headSha, GitError } from '../git.mjs';
-import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { loadClaims, defaultClaimsPath, ClaimsError } from '../claims/load.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
@@ -49,6 +49,33 @@ export const isDefaultExcluded = (file) => DEFAULT_EXCLUDE_RES.some((re) => re.t
 
 export const defaultIgnorePath = (projectDir) => join(projectDir, 'testguard.ignore.json');
 
+/** Cache validated descendant boundaries for one measurement, never across runs. */
+export function nestedProjectResolver(projectDir) {
+  const root = realpathSync(resolve(projectDir));
+  const markers = new Map();
+  return (file) => {
+    const parts = file.split('/').slice(0, -1);
+    for (let i = 1; i <= parts.length; i++) {
+      const project = parts.slice(0, i).join('/');
+      if (!markers.has(project)) {
+        const marker = join(root, project, 'testguard.claims.json');
+        let stat;
+        try { stat = lstatSync(marker); }
+        catch (error) {
+          if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw new ClaimsError(`cannot inspect nested claims file ${marker}: ${error.message}`);
+        }
+        if (stat) {
+          if (!stat.isFile() || stat.isSymbolicLink() || realpathSync(marker) !== marker) throw new ClaimsError(`nested claims file must be a regular file without symlink traversal: ${marker}`);
+          loadClaims(marker);
+        }
+        markers.set(project, Boolean(stat));
+      }
+      if (markers.get(project)) return project;
+    }
+    return null;
+  };
+}
+
 /**
  * The reference the change is measured against. Environment overrides and CI
  * bases are handled here; local Git discovery is separate because it needs a
@@ -212,7 +239,15 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
   const excluded = [];
   const covered = [];
   const uncovered = [];
+  const nested = new Map();
+  const ownerOf = nestedProjectResolver(projectDir);
   for (const file of changed) {
+    const owner = ownerOf(file);
+    if (owner) {
+      if (!nested.has(owner)) nested.set(owner, []);
+      nested.get(owner).push(file);
+      continue;
+    }
     if (!SOURCE_EXT.has(extname(file))) { excluded.push({ file, by: 'non-source' }); continue; }
     const ux = userExcludes.find((x) => x.re.test(file));
     if (ux) { excluded.push({ file, by: `exclude:${ux.glob}` }); continue; }
@@ -256,6 +291,7 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
     changed: changed.length,
     evaluated,
     excluded,
+    ...(nested.size ? { nested: [...nested].map(([project, files]) => ({ project, files })) } : {}),
     covered,
     uncovered,
     reliedOn,
@@ -271,7 +307,8 @@ export function renderGate(doc) {
   for (const u of doc.uncovered) lines.push(`UNCLAIMED  ${u.file}  (${u.kind}${u.nearestClaimId ? `, nearest claim ${u.nearestClaimId}` : ''})\n           → ${u.suggestion}`);
   for (const r of doc.reliedOn) lines.push(`excused    ${r.files.join(', ')}  by ignore "${r.pattern}": ${r.reason}${r.expires ? ` (expires ${r.expires})` : ''}`);
   for (const e of doc.expired) lines.push(`EXPIRED    ignore "${e.pattern}" (expired ${e.expires}) no longer excuses ${e.files.join(', ')}`);
-  if (doc.changed > 0 && doc.evaluated === 0) lines.push(`note: every changed file was excluded (${[...new Set(doc.excluded.map((x) => x.by))].join(', ')}); 0 evaluated${doc.strict ? ' — --strict makes this a failure' : ''}`);
+  for (const n of doc.nested ?? []) lines.push(`delegated  ${n.files.length} file(s) belong to the TestGuard project at ${n.project}/; run testguard gate ${n.project} --changed ${doc.ref}${doc.includeDirty ? ' --include-dirty' : ''}; child coverage has not been evaluated here`);
+  if (doc.changed > 0 && doc.evaluated === 0) lines.push(`note: every changed file was excluded or delegated (${[...new Set(doc.excluded.map((x) => x.by))].join(', ')}); 0 evaluated${doc.strict ? ' — --strict makes this a failure' : ''}`);
   if (doc.changed === 0) lines.push(`no changes since ${doc.ref}; nothing to claim`);
   if (doc.uncovered.length === 0 && doc.exitCode === 0 && doc.evaluated > 0) lines.push('every changed source file carries a claim or an excusing ignore entry');
   return lines.join('\n');

package/src/git.mjs

@@ -6,12 +6,14 @@ import { randomBytes } from 'node:crypto';
 
 export class GitError extends Error {}
 
-export function git(args, cwd, env) {
+export function gitRaw(args, cwd, env) {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8', env: env ? { ...process.env, ...env } : process.env });
   if (r.status !== 0) throw new GitError(`git ${args.join(' ')}: ${(r.stderr || r.stdout).trim()}`);
-  return r.stdout.trim();
+  return r.stdout;
 }
 
+export const git = (args, cwd, env) => gitRaw(args, cwd, env).trim();
+
 export const repoRoot = (dir) => git(['rev-parse', '--show-toplevel'], dir);
 
 /** Full sha of `ref` (default HEAD), or null when it does not resolve. */

package/src/init/templates/SKILL.md

@@ -20,7 +20,7 @@ which files exist. `state` is one of:
 
 | state | meaning | you do |
 |---|---|---|
-| `no-claims` | no `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with what the code guarantees; keep or drop each proposal; move the claims into `testguard.claims.json` |
+| `no-claims` | missing or empty `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with the intended guarantee from a spec, ticket, or past bug; keep or drop each proposal; move the claims into `testguard.claims.json` |
 | `unclaimed-changes` | files you changed carry no claim (when a reference is explicit, supplied by CI, or safely inferred from local Git's remote default/upstream metadata) | `next.file` names the first; `testguard scaffold <file>` and state the claim, or add a `testguard.ignore.json` path entry with a reason a reviewer will accept. **Before** writing more code. |
 | `invalid-anchors` | an exact fault anchor moved or became ambiguous | run `testguard claims --check-anchors`; repair `next.target` in the claims file without changing what the fault means, then re-probe. Never guess or auto-fix an anchor. |
 | `unprobed` | claims never probed | `testguard probe` |

package/src/probe/attribution.mjs

@@ -117,6 +117,8 @@ export function isReusable(prior, current) {
   const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);
   return prior.inputs.targetHash === current.inputs.targetHash
     && same(prior.inputs.defenderHashes, current.inputs.defenderHashes)
+    && same(prior.inputs.testUniverseHash, current.inputs.testUniverseHash)
+    && same(prior.inputs.discoveryHashes, current.inputs.discoveryHashes)
     && same(prior.defenders.requested, current.requested)
     && same(prior.defenders.resolved, current.resolved)
     && prior.subject.contentHash === current.contentHash;

package/src/probe/discover.mjs

@@ -1,9 +1,10 @@
 import { join } from 'node:path';
 import { listTestFiles } from './runners/shared.mjs';
 import { testGlobs as PY_TEST_GLOBS } from './runners/python.mjs';
-import { fileImports } from './rank.mjs';
+import { fileImportRelation } from './rank.mjs';
 import { pyFileImports } from './pyimports.mjs';
 import { classifyDefenders } from './mocks.mjs';
+import { normalizeDiscoveredFiles } from './runners/discovery.mjs';
 
 /** A target's language decides how its importers are found. Nothing else about it matters here. */
 export const isPython = (rel) => rel.endsWith('.py');
@@ -17,13 +18,48 @@ export const isPython = (rel) => rel.endsWith('.py');
  * `nocover` therefore means exactly "no test file imports this source without
  * mocking it".
  */
-export function discoverDefendersDetailed(projectDir, targetRel) {
-  const importing = isPython(targetRel)
-    ? listTestFiles(projectDir, PY_TEST_GLOBS).filter((t) => pyFileImports(projectDir, join(projectDir, t), targetRel, t))
-    : listTestFiles(projectDir).filter((t) => fileImports(projectDir, join(projectDir, t), targetRel));
-  return { importing, ...classifyDefenders(projectDir, targetRel, importing) };
+const explicitFiles = (projectDir, testUniverse) => {
+  if (testUniverse === undefined) return null;
+  if (!Array.isArray(testUniverse) && !Object.isFrozen(testUniverse)) throw new TypeError('explicit test universe manifest must be immutable');
+  const files = Array.isArray(testUniverse) ? testUniverse : testUniverse?.files;
+  if (!Array.isArray(files)) throw new TypeError('explicit test universe must be an array or a manifest with files');
+  if (!Object.isFrozen(files)) throw new TypeError('explicit test universe must be immutable');
+  return normalizeDiscoveredFiles(projectDir, files);
+};
+
+export function discoverDefendersDetailed(projectDir, targetRel, testUniverse) {
+  const explicit = explicitFiles(projectDir, testUniverse);
+  const candidates = explicit ?? (isPython(targetRel) ? listTestFiles(projectDir, PY_TEST_GLOBS) : listTestFiles(projectDir));
+  if (isPython(targetRel)) {
+    const pythonCandidates = candidates.filter((t) => t.endsWith('.py'));
+    const importing = pythonCandidates.filter((t) => pyFileImports(projectDir, join(projectDir, t), targetRel, t));
+    return { importing, ...classifyDefenders(projectDir, targetRel, importing), indeterminate: [], dependencies: pythonCandidates, relations: new Map() };
+  }
+
+  const relations = new Map();
+  const importing = [];
+  const indeterminate = [];
+  const jsCandidates = candidates.filter((candidate) => !candidate.endsWith('.py'));
+  // Every candidate's source participates in the negative discovery result:
+  // editing an unrelated test so it starts importing the target must invalidate
+  // a prior `nocover`, not silently reuse it.
+  const dependencies = new Set(jsCandidates);
+  for (const file of jsCandidates) {
+    const relation = fileImportRelation(projectDir, join(projectDir, file), targetRel);
+    relations.set(file, relation);
+    for (const dependency of relation.dependencies) dependencies.add(dependency);
+    if (relation.status === 'matched') importing.push(file);
+    else if (relation.status === 'indeterminate') indeterminate.push({ file, reason: relation.reason, issues: relation.issues ?? [] });
+  }
+  return {
+    importing,
+    ...classifyDefenders(projectDir, targetRel, importing, relations),
+    indeterminate,
+    dependencies: [...dependencies].sort(),
+    relations,
+  };
 }
 
-export function discoverDefenders(projectDir, targetRel) {
-  return discoverDefendersDetailed(projectDir, targetRel).canDetect;
+export function discoverDefenders(projectDir, targetRel, testUniverse) {
+  return discoverDefendersDetailed(projectDir, targetRel, testUniverse).canDetect;
 }