mandrel 2.67.0 → 2.68.0

package/.agents/scripts/lib/coverage-capture-affected.js

@@ -0,0 +1,345 @@
+/**
+ * `captureScope: "affected"` capture path for `coverage-capture.js`. The
+ * consumer owns how its suite is scoped; mandrel only names the base ref and
+ * keeps the artifact complete-looking for every per-file reader.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveChangedFilesRef } from './changed-files.js';
+import {
+  captureStampPath,
+  reportCaptureFailure,
+  stampCapturedTree,
+} from './coverage-capture.js';
+import {
+  describeStampFreshness,
+  planDeltaRefresh,
+  readHeadCommit,
+} from './coverage-capture-delta.js';
+import { tryIncrementalCapture } from './coverage-capture-incremental.js';
+
+const AFFECTED_CAPTURE_SCRIPT = 'test:coverage:affected';
+const COVERAGE_BASE_REF_ENV = 'MANDREL_COVERAGE_BASE_REF';
+
+/** A configured scope with no script warns, and the caller runs full scope. */
+function shouldCaptureAffected({
+  coverage,
+  scripts,
+  hasNpmScriptImpl,
+  logger,
+}) {
+  if (coverage?.captureScope !== 'affected') return false;
+  if (hasNpmScriptImpl(scripts, AFFECTED_CAPTURE_SCRIPT)) return true;
+  logger.warn(
+    `[coverage-capture] ⚠ captureScope is "affected" but package.json has no "${AFFECTED_CAPTURE_SCRIPT}" script — running the full npm run test:coverage instead.`,
+  );
+  return false;
+}
+
+/**
+ * Affected capture when it applies, else incremental mode; `null` means
+ * neither applies and the caller runs full scope.
+ *
+ * @returns {Promise<number | null>}
+ */
+export async function tryScopedCapture({
+  readPackageScriptsImpl,
+  hasNpmScriptImpl,
+  ...opts
+}) {
+  const applies = shouldCaptureAffected({
+    coverage: opts.coverage,
+    scripts: readPackageScriptsImpl(opts.args.cwd),
+    hasNpmScriptImpl,
+    logger: opts.logger,
+  });
+  return applies
+    ? await runAffectedCapture(opts)
+    : await tryIncrementalCapture(opts);
+}
+
+/**
+ * Scoped rows win; a prior row of a changed file is dropped, so a changed
+ * file the scoped run skipped stays absent and fails closed downstream.
+ * Under `keepPrior` (a delta refresh) a narrower run replaces only the
+ * dropped files: its partial rows for a file the prior run measured in full
+ * would undercount it.
+ */
+function mergeCoverageArtifacts({ prior, scoped, cwd, dropFiles, keepPrior }) {
+  const drop = new Set(dropFiles.map((f) => path.resolve(cwd, f)));
+  const merged = {};
+  for (const [abs, entry] of Object.entries(prior ?? {})) {
+    if (!drop.has(path.resolve(abs))) merged[abs] = entry;
+  }
+  return overlayScoped(merged, scoped, keepPrior);
+}
+
+function overlayScoped(merged, scoped, keepPrior) {
+  const take = ([abs]) => !keepPrior || !(abs in merged);
+  return Object.assign(
+    merged,
+    Object.fromEntries(Object.entries(scoped).filter(take)),
+  );
+}
+
+function readArtifact(abs, fsImpl) {
+  try {
+    return JSON.parse(fsImpl.readFileSync(abs, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** An unstamped artifact may be a red run's: its rows are never merged. */
+function readPriorArtifact(cwd, crap, fsImpl) {
+  const stamped = fsImpl.existsSync(captureStampPath(cwd, crap.coveragePath));
+  return stamped
+    ? readArtifact(path.resolve(cwd, crap.coveragePath), fsImpl)
+    : null;
+}
+
+function readChangedFiles({ getChangedFilesImpl, ref, cwd, logger }) {
+  try {
+    return getChangedFilesImpl({ ref, cwd });
+  } catch (err) {
+    logger.warn(
+      `[coverage-capture] ⚠ affected mode: ${err?.message ?? err} — capturing without a prior-artifact merge.`,
+    );
+    return null;
+  }
+}
+
+/** The tree a run is about to measure: its source digest and HEAD commit. */
+function snapshotTree({
+  args,
+  crap,
+  computeContentDigestImpl,
+  readHeadCommitImpl,
+}) {
+  return {
+    preDigest: computeContentDigestImpl(args.cwd, crap.targetDirs),
+    commit: readHeadCommitImpl(args.cwd),
+  };
+}
+
+/**
+ * Run the affected script against `baseRef`. The pre-spawn digest and
+ * commit are what the stamp records; see `stampCapturedTree`.
+ *
+ * @returns {Promise<{ code: number, preDigest: string | null, commit: string | null }>}
+ */
+async function runScoped({
+  crap,
+  coverage,
+  args,
+  baseRef,
+  probe,
+  runCaptureImpl,
+  computeContentDigestImpl,
+  readHeadCommitImpl,
+  logger,
+}) {
+  const tree = snapshotTree({
+    args,
+    crap,
+    computeContentDigestImpl,
+    readHeadCommitImpl,
+  });
+  const code = await runCaptureImpl({
+    cwd: args.cwd,
+    coveragePath: crap.coveragePath,
+    timeoutMs: coverage?.timeoutMs,
+    script: AFFECTED_CAPTURE_SCRIPT,
+    env: { [COVERAGE_BASE_REF_ENV]: baseRef },
+    log: (m) => logger.info(m),
+    recheckFresh: () => probe().fresh === true,
+  });
+  return { code, ...tree };
+}
+
+/**
+ * Merge the scoped rows over `prior`, dropping `dropFiles`' prior rows.
+ *
+ * @returns {boolean} False when the run wrote no readable artifact.
+ */
+function writeMerged({
+  crap,
+  args,
+  prior,
+  dropFiles,
+  keepPrior,
+  logger,
+  fsImpl,
+}) {
+  const artifactAbs = path.resolve(args.cwd, crap.coveragePath);
+  const scoped = readArtifact(artifactAbs, fsImpl);
+  if (scoped === null) {
+    logger.error(
+      `[coverage-capture] ✖ npm run ${AFFECTED_CAPTURE_SCRIPT} exited 0 but wrote no readable artifact at ${crap.coveragePath} — point its coverage output there.`,
+    );
+    return false;
+  }
+  const merged = mergeCoverageArtifacts({
+    prior,
+    scoped,
+    cwd: args.cwd,
+    dropFiles,
+    keepPrior,
+  });
+  fsImpl.writeFileSync(artifactAbs, JSON.stringify(merged));
+  return true;
+}
+
+/**
+ * Run, merge and stamp. A non-zero run is a red capture — never a fallback.
+ *
+ * @returns {Promise<number>}
+ */
+async function captureAndMerge(opts) {
+  const run = await runScoped(opts);
+  if (run.code !== 0) return reportCaptureFailure(run.code, opts.logger);
+  if (!writeMerged(opts)) return 1;
+  stampCapturedTree({
+    ...opts,
+    targetDirs: opts.crap.targetDirs,
+    coveragePath: opts.crap.coveragePath,
+    cwd: opts.args.cwd,
+    scope: 'affected',
+    preDigest: run.preDigest,
+    commit: run.commit,
+    ...opts.stamp,
+  });
+  return 0;
+}
+
+/** The affected-scope freshness probe, reused as the post-lock recheck. */
+function affectedProbe({ isCoverageFreshImpl, crap, args }) {
+  return () =>
+    isCoverageFreshImpl({
+      coveragePath: crap.coveragePath,
+      targetDirs: crap.targetDirs,
+      cwd: args.cwd,
+      requireScope: 'affected',
+    });
+}
+
+/**
+ * Probe at affected scope and log the verdict with its stamp detail.
+ *
+ * @returns {{ fresh: boolean, reason: string }}
+ */
+function probeAndReport({ probe, crap, args, logger }) {
+  const freshness = probe();
+  const detail = describeStampFreshness({
+    cwd: args.cwd,
+    coveragePath: crap.coveragePath,
+    requiredScope: 'affected',
+    verdict: freshness.reason,
+  });
+  const action = freshness.fresh ? ' — skipping capture.' : '.';
+  logger.info(
+    `[coverage-capture] Coverage at ${crap.coveragePath} is ${freshness.reason} (affected)${action} ${detail}`,
+  );
+  return freshness;
+}
+
+/** Under `skipWhenUnchanged`, a readable change set with nothing in scope skips. */
+function skipsUnchanged({ crap, changed, scopedFiles, ref, logger }) {
+  const skip =
+    crap.incrementalCoverage?.skipWhenUnchanged === true &&
+    Boolean(changed) &&
+    scopedFiles.length === 0;
+  if (skip) {
+    logger.info(
+      `[coverage-capture] Affected mode: no changed files under [${crap.targetDirs.join(', ')}] vs ${ref} — skipping capture.`,
+    );
+  }
+  return skip;
+}
+
+/**
+ * What the run merges over and is keyed on: the stamped commit and main's
+ * delta for an eligible delta refresh, else `ref` and the Story change set.
+ *
+ * @returns {{ prior: object | null, baseRef: string, dropFiles: string[], keepPrior: boolean }}
+ */
+function resolveRunBase({
+  freshness,
+  crap,
+  args,
+  changed,
+  ref,
+  fsImpl,
+  ...rest
+}) {
+  const prior = changed ? readPriorArtifact(args.cwd, crap, fsImpl) : null;
+  const delta = planDeltaRefresh({
+    ...rest,
+    freshness,
+    crap,
+    args,
+    changed,
+    prior,
+  });
+  return {
+    prior,
+    baseRef: delta?.baseRef ?? ref,
+    dropFiles: delta?.dropFiles ?? changed ?? [],
+    keepPrior: delta !== null,
+  };
+}
+
+/**
+ * Honours `skipWhenUnchanged` as incremental mode does. Nothing prior is
+ * merged with an unreadable change set (a stale row for a changed file must
+ * never read as fresh) or with no stamp on disk (an unstamped artifact may
+ * be a red run's, and its rows must not ride into a green one).
+ */
+async function runAffectedCapture({
+  crap,
+  args,
+  getChangedFilesImpl,
+  filterFilesUnderTargetsImpl,
+  isCoverageFreshImpl,
+  classifyDeltaRefreshImpl,
+  readHeadCommitImpl = readHeadCommit,
+  logger,
+  fsImpl = fs,
+  ...rest
+}) {
+  const ref = resolveChangedFilesRef({ crap, ref: args.ref });
+  const changed = readChangedFiles({
+    getChangedFilesImpl,
+    ref,
+    cwd: args.cwd,
+    logger,
+  });
+  const scopedFiles = filterFilesUnderTargetsImpl(changed, crap.targetDirs);
+  if (skipsUnchanged({ crap, changed, scopedFiles, ref, logger })) return 0;
+
+  const probe = affectedProbe({ isCoverageFreshImpl, crap, args });
+  const freshness = probeAndReport({ probe, crap, args, logger });
+  if (freshness.fresh) return 0;
+
+  const base = resolveRunBase({
+    freshness,
+    crap,
+    args,
+    changed,
+    ref,
+    fsImpl,
+    classifyDeltaRefreshImpl,
+    logger,
+  });
+  return captureAndMerge({
+    ...rest,
+    ...base,
+    crap,
+    args,
+    stamp: { files: scopedFiles, ref },
+    probe,
+    readHeadCommitImpl,
+    logger,
+    fsImpl,
+  });
+}

package/.agents/scripts/lib/coverage-capture-delta.js

@@ -0,0 +1,180 @@
+/**
+ * Delta refresh for `captureScope: "affected"`: after a base-sync merges main
+ * commits that share no file with the Story, re-measure only those commits'
+ * tests instead of re-running the Story's whole affected scope. Every
+ * uncertainty fails closed to an ordinary capture.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { captureStampPath, computeContentDigest } from './coverage-capture.js';
+import { gitSpawn } from './git-utils.js';
+
+/** Basenames whose change moves coverage beyond the files it names. */
+const COVERAGE_CONFIG_RE =
+  /^(package\.json|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|tsconfig.*\.json|(vitest|vite|jest|nyc)\.(config|workspace)\.[cm]?[jt]s|\.c8rc.*|\.nycrc.*)$/;
+
+/** @param {string} file @returns {boolean} */
+export function isCoverageConfigFile(file) {
+  return COVERAGE_CONFIG_RE.test(path.posix.basename(String(file)));
+}
+
+/** A spawn failure reads as a non-zero status, which callers treat as "unknown". */
+function git(cwd, args, spawn) {
+  const res = spawn(cwd, ...args);
+  return { status: res?.status ?? 1, stdout: res?.stdout ?? '' };
+}
+
+/** @returns {string | null} The HEAD sha, or `null` when unavailable. */
+export function readHeadCommit(cwd, io = {}) {
+  const res = git(cwd, ['rev-parse', 'HEAD'], io.gitSpawn ?? gitSpawn);
+  const sha = res?.status === 0 ? res.stdout.trim() : '';
+  return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+}
+
+/** @returns {Record<string, unknown> | null} */
+function readCaptureStamp(cwd, coveragePath, io = {}) {
+  const readFileSync = io.readFileSync ?? fs.readFileSync;
+  try {
+    const stamp = JSON.parse(
+      readFileSync(captureStampPath(cwd, coveragePath), 'utf8'),
+    );
+    return stamp && typeof stamp === 'object' ? stamp : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A stamp without `scope` is full-scope; no stamp at all is `none`. */
+function stampScopeOf(stamp) {
+  if (!stamp) return 'none';
+  return typeof stamp.scope === 'string' ? stamp.scope : 'full';
+}
+
+/** The suffix every freshness log line carries, so staleness is explainable from the log. */
+export function formatFreshnessDetail({
+  stamp,
+  requiredScope,
+  verdict,
+  deltaFiles,
+}) {
+  const delta =
+    typeof deltaFiles === 'number' ? `, delta: ${deltaFiles} file(s)` : '';
+  return `(stamp scope: ${stampScopeOf(stamp)}, required scope: ${requiredScope}, verdict: ${verdict}${delta})`;
+}
+
+/** {@link formatFreshnessDetail} for the stamp on disk. */
+export function describeStampFreshness({
+  cwd,
+  coveragePath,
+  requiredScope,
+  verdict,
+}) {
+  return formatFreshnessDetail({
+    stamp: readCaptureStamp(cwd, coveragePath),
+    requiredScope,
+    verdict,
+  });
+}
+
+/** A dirty file is in no git delta, so a dirty tree is ineligible. */
+function treeIneligibility({ cwd, commit, spawn }) {
+  if (typeof commit !== 'string' || commit.length === 0) {
+    return 'stamp records no commit';
+  }
+  const status = git(cwd, ['status', '--porcelain'], spawn);
+  if (status?.status !== 0) return 'git status failed';
+  if (status.stdout.trim().length > 0) return 'worktree is dirty';
+  const ancestor = git(
+    cwd,
+    ['merge-base', '--is-ancestor', commit, 'HEAD'],
+    spawn,
+  );
+  if (ancestor?.status !== 0)
+    return 'stamped commit is not an ancestor of HEAD';
+  return null;
+}
+
+function deltaIneligibility({ delta, storyFiles }) {
+  if (delta.length === 0) return 'no committed delta since the stamp';
+  const story = new Set(storyFiles);
+  const shared = delta.find((f) => story.has(f));
+  if (shared) return `delta shares ${shared} with the Story's change set`;
+  const config = delta.find(isCoverageConfigFile);
+  if (config) return `delta touches coverage-determining config ${config}`;
+  return null;
+}
+
+function parseNames(stdout) {
+  return stdout
+    .split('\n')
+    .map((l) => l.trim().replace(/\\/g, '/'))
+    .filter((l) => l.length > 0);
+}
+
+/** Any git error or unresolvable input is ineligible. */
+function classifyDeltaRefresh({
+  cwd,
+  crap,
+  storyFiles,
+  prior,
+  gitSpawnImpl: spawn = gitSpawn,
+  readFileSync = fs.readFileSync,
+  computeContentDigestImpl = computeContentDigest,
+}) {
+  const stamp = readCaptureStamp(cwd, crap.coveragePath, { readFileSync });
+  const no = (reason) => ({ eligible: false, reason, stamp });
+  if (typeof stamp?.digest !== 'string') return no('no digest stamp');
+  const current = computeContentDigestImpl(cwd, crap.targetDirs);
+  if (!current || current === stamp.digest) return no('not stale by digest');
+  if (!Array.isArray(storyFiles)) return no('Story change set unreadable');
+  if (!prior) return no('no prior artifact to merge over');
+  const commit = stamp.commit;
+  const treeReason = treeIneligibility({ cwd, commit, spawn });
+  if (treeReason) return no(treeReason);
+  const diff = git(cwd, ['diff', '--name-only', commit, 'HEAD'], spawn);
+  if (diff?.status !== 0) return no('git diff failed');
+  const delta = parseNames(diff.stdout);
+  const deltaReason = deltaIneligibility({ delta, storyFiles });
+  if (deltaReason) return no(deltaReason);
+  return { eligible: true, commit, delta, stamp };
+}
+
+/**
+ * A stale stamp whose staleness is wholly main's delta is re-measured keyed
+ * on the stamped commit; `null` means capture the Story's scope as usual.
+ *
+ * @returns {{ baseRef: string, dropFiles: string[] } | null}
+ */
+export function planDeltaRefresh({
+  freshness,
+  crap,
+  args,
+  changed,
+  prior,
+  classifyDeltaRefreshImpl = classifyDeltaRefresh,
+  logger,
+}) {
+  if (freshness.reason !== 'stale') return null;
+  const plan = classifyDeltaRefreshImpl({
+    cwd: args.cwd,
+    crap,
+    storyFiles: changed,
+    prior,
+  });
+  if (!plan.eligible) {
+    logger.info(
+      `[coverage-capture] Affected mode: delta refresh not eligible (${plan.reason}) — capturing the Story's affected scope.`,
+    );
+    return null;
+  }
+  const detail = formatFreshnessDetail({
+    stamp: plan.stamp,
+    requiredScope: 'affected',
+    verdict: 'delta-refresh',
+    deltaFiles: plan.delta.length,
+  });
+  logger.info(
+    `[coverage-capture] Coverage at ${crap.coveragePath} needs a delta refresh — re-measuring ${plan.delta.length} file(s) changed since ${plan.commit.slice(0, 12)}. ${detail}`,
+  );
+  return { baseRef: plan.commit, dropFiles: plan.delta };
+}

package/.agents/scripts/lib/coverage-capture-fullscope.js

@@ -7,6 +7,31 @@ import {
   reportCaptureFailure,
   stampCapturedTree,
 } from './coverage-capture.js';
+import {
+  describeStampFreshness,
+  readHeadCommit,
+} from './coverage-capture-delta.js';
+
+/**
+ * `--skip-when-no-crap-files`: true when no changed file is under
+ * `crap.targetDirs`. A bad ref must not relax the gate, so it answers false.
+ *
+ * @returns {boolean}
+ */
+function noCrapFilesChanged({ crap, args, getChangedFilesImpl, logger }) {
+  let changed = null;
+  try {
+    changed = getChangedFilesImpl({
+      ref: resolveChangedFilesRef({ crap, ref: args.ref }),
+      cwd: args.cwd,
+    });
+  } catch (err) {
+    logger.warn(
+      `[coverage-capture] ⚠ ${err?.message ?? err} — falling back to freshness check.`,
+    );
+  }
+  return Boolean(changed) && !anyChangedUnderTargets(changed, crap.targetDirs);
+}
 
 /**
  * Optional no-CRAP-files skip, freshness probe, then capture and stamp. The
@@ -22,6 +47,7 @@ import {
  *   runCaptureImpl: Function,
  *   computeContentDigestImpl: Function,
  *   writeCaptureStampImpl: Function,
+ *   readHeadCommitImpl?: typeof readHeadCommit,
  *   logger: { info: Function, warn: Function, error: Function },
  * }} opts
  * @returns {Promise<number>} process exit code
@@ -35,58 +61,52 @@ export async function runFullScopeCapture({
   runCaptureImpl,
   computeContentDigestImpl,
   writeCaptureStampImpl,
+  readHeadCommitImpl = readHeadCommit,
   logger,
 }) {
-  if (args.skipWhenNoCrapFiles) {
-    let changed;
-    try {
-      changed = getChangedFilesImpl({
-        ref: resolveChangedFilesRef({ crap, ref: args.ref }),
-        cwd: args.cwd,
-      });
-    } catch (err) {
-      // A bad ref must not relax the gate; fall through to freshness.
-      logger.warn(
-        `[coverage-capture] ⚠ ${err?.message ?? err} — falling back to freshness check.`,
-      );
-      changed = null;
-    }
-    if (changed && !anyChangedUnderTargets(changed, crap.targetDirs)) {
-      logger.info(
-        `[coverage-capture] No changed files under [${crap.targetDirs.join(', ')}] — skipping capture.`,
-      );
-      return 0;
-    }
+  if (
+    args.skipWhenNoCrapFiles &&
+    noCrapFilesChanged({ crap, args, getChangedFilesImpl, logger })
+  ) {
+    logger.info(
+      `[coverage-capture] No changed files under [${crap.targetDirs.join(', ')}] — skipping capture.`,
+    );
+    return 0;
   }
 
-  const freshness = isCoverageFreshImpl({
-    coveragePath: crap.coveragePath,
-    targetDirs: crap.targetDirs,
+  const probe = () =>
+    isCoverageFreshImpl({
+      coveragePath: crap.coveragePath,
+      targetDirs: crap.targetDirs,
+      cwd: args.cwd,
+    });
+  const freshness = probe();
+  const detail = describeStampFreshness({
     cwd: args.cwd,
+    coveragePath: crap.coveragePath,
+    requiredScope: 'full',
+    verdict: freshness.reason,
   });
   if (freshness.fresh) {
     logger.info(
-      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} — skipping capture.`,
+      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} — skipping capture. ${detail}`,
     );
     return 0;
   }
 
   logger.info(
-    `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run test:coverage…`,
+    `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run test:coverage… ${detail}`,
   );
-  // Pre-spawn digest; see `stampCapturedTree`.
+  // Pre-spawn digest and commit; see `stampCapturedTree`.
   const preDigest = computeContentDigestImpl(args.cwd, crap.targetDirs);
+  const commit = readHeadCommitImpl(args.cwd);
   const code = await runCaptureImpl({
     cwd: args.cwd,
+    coveragePath: crap.coveragePath,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
     // After queueing behind another suite, which may have stamped this tree.
-    recheckFresh: () =>
-      isCoverageFreshImpl({
-        coveragePath: crap.coveragePath,
-        targetDirs: crap.targetDirs,
-        cwd: args.cwd,
-      }).fresh === true,
+    recheckFresh: () => probe().fresh === true,
   });
   if (code !== 0) return reportCaptureFailure(code, logger);
 
@@ -95,6 +115,7 @@ export async function runFullScopeCapture({
     cwd: args.cwd,
     targetDirs: crap.targetDirs,
     coveragePath: crap.coveragePath,
+    commit,
     computeContentDigestImpl,
     writeCaptureStampImpl,
     logger,