testguard-cli 0.4.0 → 0.6.0

package/src/status/status.mjs

@@ -7,6 +7,8 @@ import { hashFile, sha256 } from '../util/hash.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';
+import { headSha, isAncestor } from '../git.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
@@ -22,7 +24,13 @@ 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 }) {
+/**
+ * `evidence` overrides the project's own evidence file: a document taken on
+ * ANOTHER commit (CI's, fetched as an artifact) is legitimate input. Staleness
+ * is computed from the recorded input hashes exactly as for a local run, so a
+ * foreign document is trusted only for the faults whose inputs still match.
+ */
+export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20, changedRef, includeDirty = false, evidence: evidenceOverride }) {
   const rel = (p) => relative(projectDir, p) || '.';
   const doc = {
     schemaVersion: 1,
@@ -35,9 +43,35 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     stale: [],
     changedFaults: [],
     findings: [],
+    notes: [],
     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,7 +80,15 @@ 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 });
 
-  const hasEvidence = existsSync(paths.evidence);
+  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 evidenceFile = evidenceOverride ?? paths.evidence;
+  const hasEvidence = existsSync(evidenceFile);
   const hasProvisional = existsSync(paths.provisional);
   if (hasProvisional) doc.paths.provisionalEvidence = rel(paths.provisional);
   if (!hasEvidence) {
@@ -60,11 +102,29 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     }
     return doc;
   }
-  doc.paths.evidence = rel(paths.evidence);
-  const evidence = readSpecDoc('evidence', paths.evidence);
+  doc.paths.evidence = rel(evidenceFile);
+  doc.evidenceSource = evidenceOverride ? 'provided' : 'local';
+  const evidence = readSpecDoc('evidence', evidenceFile);
+  // A verdict is about a commit. When the evidence describes a different one,
+  // say both: "looks right and is not" is the failure mode this prevents.
+  doc.evidenceHead = evidence.run.repo.snapshot ?? evidence.run.repo.head;
+  const localHead = (() => { try { return headSha(projectDir); } catch { return null; } })();
+  if (localHead) doc.head = localHead;
+
   const baseline = existsSync(paths.baseline) ? readSpecDoc('baseline', paths.baseline) : undefined;
   if (baseline) doc.paths.baseline = rel(paths.baseline);
 
+  // ── Baseline provenance: informational, never a state. A baseline frozen
+  // from a snapshot or a dirty tree names the PARENT of the commit that carries
+  // its tests; once HEAD moved on, say so and name the way to re-stamp. ──
+  if (baseline?.head) {
+    const head = headSha(projectDir);
+    if (head && head !== baseline.head) {
+      if (baseline.snapshot || baseline.dirty) doc.notes.push(`baseline was frozen from a ${baseline.snapshot ? 'working-tree snapshot' : 'dirty tree'} at ${baseline.head.slice(0, 7)}; HEAD is ${head.slice(0, 7)} — it predates the commit that carries its tests. After a clean probe of HEAD reproduces the same fingerprints: testguard baseline --restamp`);
+      else if (!isAncestor(projectDir, baseline.head, head)) doc.notes.push(`baseline head ${baseline.head.slice(0, 7)} is not an ancestor of HEAD ${head.slice(0, 7)} (rewritten or foreign history); re-probe and re-baseline if the fingerprints changed`);
+    }
+  }
+
   // ── Staleness: does the evidence still describe this claims file and this tree? ──
   const probed = new Map(evidence.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]));
   for (const key of faultIndex.keys()) if (!probed.has(key)) doc.stale.push(`fault ${key} has never been probed`);
@@ -91,6 +151,14 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   const counts = {};
   for (const r of evidence.records) counts[r.verdict] = (counts[r.verdict] ?? 0) + 1;
   doc.counts.byVerdict = counts;
+  // L3 independence and observed flakiness, as numbers rather than adjectives.
+  const kills = evidence.records.filter((r) => r.verdict === 'killed');
+  if (kills.length) doc.counts.killedCoAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
+  const flaky = evidence.records.filter((r) => r.detail.flakeRate?.failures > 0);
+  if (flaky.length) {
+    doc.counts.flakyDefenderSets = new Set(flaky.map((r) => r.defenders.resolved.join('\n'))).size;
+    doc.counts.worstFlakeRate = Math.max(...flaky.map((r) => r.detail.flakeRate.failures / r.detail.flakeRate.runs));
+  }
   doc.counts.new = g.new.length + g.belowFloor.length;
   doc.counts.baselined = g.baselined.length;
   const ranked = sortForReport([...g.new, ...g.belowFloor, ...g.baselined]);
@@ -137,7 +205,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
       action: fixClaim ? 'probe' : 'write-test',
       command: fixClaim
         ? `edit ${top.claimId}/${top.subjectId} in testguard.claims.json, then: testguard probe --claim ${top.claimId} --include-dirty`
-        : `write a test in ${where} that fails on ${top.claimId}/${top.subjectId} and passes on HEAD, then: testguard probe --claim ${top.claimId} --include-dirty`,
+        : `write a test in ${where} that fails on ${top.claimId}/${top.subjectId} and passes on HEAD, then: testguard admit ${defenders[0] ?? '<that test file>'} --claim ${top.claimId}`,
       why: whyByVerdict[top.verdict] ?? `${top.claimId}/${top.subjectId} is ${top.verdict}.`,
       target: { claimId: top.claimId, subjectId: top.subjectId, ...(top.file ? { file: top.file } : {}), verdict: top.verdict },
     };
@@ -154,9 +222,22 @@ 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` : '')];
+  const lines = [];
+  if (doc.evidenceSource === 'provided') {
+    lines.push(`evidence: ${doc.paths.evidence} (provided)` + (doc.evidenceHead ? ` describes ${doc.evidenceHead.slice(0, 7)}` : '') + (doc.head && doc.evidenceHead && doc.head !== doc.evidenceHead ? `; this tree is ${doc.head.slice(0, 7)}` : ''));
+  }
+  lines.push(`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}`);
+  for (const n of doc.notes ?? []) lines.push(`note      ${n}`);
   lines.push(`next:     [${doc.next.action}] ${doc.next.command}`);
   lines.push(`why:      ${doc.next.why}`);
   return lines.join('\n');