@applesnort/crosscheck 0.3.0 → 0.6.0

package/bin/crosscheck.mjs

@@ -17,9 +17,11 @@
 //    {"lens": "ux", "output": null}]        <- null means the lens died
 //
 // Usage:
-//   crosscheck run <path...>     --exec '<command>'  [--lenses dir] [--only a,b]
+//   crosscheck run <path...|--diff|--staged|--since <ref>>
+//                                --exec '<command>'  [--lenses dir] [--only a,b]
 //                                [--skip x,y] [--concurrency N] [--out run.json]
 //                                [--sarif f] [--baseline b] [--mixed] [--dry-run]
+//   crosscheck init              [--force]   scaffold config, lenses, workflow
 //   crosscheck lenses            [--lenses dir,dir] [--no-builtin]
 //   crosscheck report            [--in run.json] [--baseline b.json]
 //   crosscheck sarif             [--in run.json] [--baseline b.json] [--out x.sarif]
@@ -29,6 +31,13 @@
 //
 // Options: --overlap <file>  independence data from `overlap` (report/sarif)
 //          --lenses <dir>    lens directory (routing + SARIF rule metadata)
+//          --max-dispatches N  cap lens runs; dropped lenses are named, never
+//                            silently omitted. crosscheck cannot see tokens or
+//                            money (--exec is any command), so dispatches are
+//                            the only unit it can honestly cap.
+//          --comment-file <f>  write a pull-request summary comment
+//          --no-cache        do not read or write .crosscheck/cache
+//          --cache-dir <dir> relocate the cache
 //          --config <file>   config file (default: nearest .crosscheckrc.json,
 //                            searching upward and stopping at a repo root)
 //
@@ -44,29 +53,40 @@
 //   crosscheck run lib/ --exec 'my-wrapper --json' --concurrency 2
 // Use --dry-run to print the roster and prompts without spawning anything.
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import {
-  existsSync, readFileSync, readdirSync, statSync, writeFileSync
+  existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync
 } from 'node:fs';
-import { join, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { formatScore, score } from '../lib/calibrate.mjs';
 import { findConfig, mergeConfig, validateConfig } from '../lib/config.mjs';
 import { parseFrontmatter, resolveLensSet } from '../lib/lenses.mjs';
 import {
-  countsBySeverity, lensOverlap, mergeFindings, panelVerdict
+  applyVerdicts, countsBySeverity, lensOverlap, mergeFindings, panelVerdict
 } from '../lib/merge.mjs';
 import { filterAgainstBaseline, staleBaselineEntries, toBaseline }
   from '../lib/baseline.mjs';
 import { parseReports } from '../lib/parse.mjs';
-import { planRun, promptsFor, runPanel } from '../lib/run.mjs';
+import {
+  planRun, promptsFor, resolveExec, runPanel, verifyFindings
+} from '../lib/run.mjs';
+import { cacheKey, createCache } from '../lib/cache.mjs';
+import { buildComment } from '../lib/comment.mjs';
 import { toSarifJson } from '../lib/sarif.mjs';
+import { diffCommand, targetFromDiff, withContext } from '../lib/target.mjs';
 
 function fail(message) {
   process.stderr.write(`crosscheck: ${message}\n`);
   process.exit(2);
 }
 
-const BOOLEAN_FLAGS = new Set(['dry-run', 'mixed', 'no-builtin']);
+// --diff is boolean rather than taking an optional ref: `run --diff src/` would
+// otherwise be ambiguous about whether src/ is a ref or a path. Use --since <ref>
+// to compare against something.
+const BOOLEAN_FLAGS = new Set([
+  'dry-run', 'mixed', 'no-builtin', 'staged', 'verify', 'no-verify', 'diff',
+  'no-cache', 'force'
+]);
 
 function parseArgs(argv) {
   const [command, ...rest] = argv;
@@ -163,26 +183,40 @@ function lensSources(option, { includeBuiltin = true } = {}) {
   if (dirs.length === 0) {
     fail('no lens directories to load (--no-builtin with no --lenses?)');
   }
-  return dirs.map(dir => ({ origin: dir, lenses: loadLenses(dir) }));
+  const sources = dirs.map(dir => ({ origin: dir, lenses: loadLenses(dir) }));
+  if (sources.every(source => source.lenses.length === 0)) {
+    fail(`no usable lens definitions found in: ${dirs.join(', ')}`);
+  }
+  return sources;
 }
 
+// Documentation files that live alongside lenses and are not lens attempts.
+const NOT_A_LENS = /^(README|CONTRIBUTING|NOTES)\.md$/i;
+
+// Returns whatever lenses the directory holds, possibly none. A source with no
+// lenses is normal once sources layer — a project's own directory may hold only a
+// README while the packaged lenses do the work. Failing here would make an empty
+// local directory fatal; the combined set is what has to be non-empty, and
+// lensSources checks that.
 function loadLenses(dir) {
   const files = readdirSync(dir).filter(f => f.endsWith('.md'));
   const lenses = [];
   for (const file of files) {
+    if (NOT_A_LENS.test(file)) {
+      continue;
+    }
     const path = join(dir, file);
     const text = readFileSync(path, 'utf8');
     const meta = parseFrontmatter(text);
     if (!meta?.name) {
+      // Named, because a lens silently ignored for a malformed header is a
+      // coverage hole that looks like a working roster.
       process.stderr.write(
-        `crosscheck: skipping ${file} — no frontmatter with a name\n`);
+        `crosscheck: ignoring ${file} — no frontmatter with a name\n`);
       continue;
     }
     lenses.push({ ...meta, definition: text, definitionPath: path });
   }
-  if (lenses.length === 0) {
-    fail(`no usable lens definitions in ${dir}`);
-  }
   return lenses;
 }
 
@@ -222,6 +256,63 @@ function collectFiles(targets) {
 
 // Spawn the user's command with the prompt on stdin. crosscheck stays agnostic
 // about which model or framework produced the text.
+// Run git and return stdout. A failure here is fatal: a diff-scoped review that
+// silently falls back to reviewing everything would cost far more than intended.
+function git(args) {
+  const result = spawnSync('git', args, { encoding: 'utf8' });
+  if (result.error) {
+    fail(`could not run git: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail(`git ${args.join(' ')} failed: ${String(result.stderr).trim()}`);
+  }
+  return result.stdout;
+}
+
+// A preflight command lets a project impose its own gate — data classification,
+// a clean worktree, a branch policy — without crosscheck knowing what the rule
+// is. Non-zero aborts before any model is called.
+function runPreflight(commandLine) {
+  process.stderr.write(`crosscheck: preflight ${commandLine}\n`);
+  const result = spawnSync(commandLine, { shell: true, encoding: 'utf8' });
+  if (result.error) {
+    fail(`preflight could not run: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    process.stderr.write(String(result.stdout ?? ''));
+    process.stderr.write(String(result.stderr ?? ''));
+    fail(`preflight failed (exit ${result.status}); nothing was dispatched`);
+  }
+}
+
+// A disk-backed cache under .crosscheck/cache. Disabled entirely by --no-cache,
+// in which case nothing is read or written.
+function buildCache(options) {
+  if (options['no-cache']) {
+    return createCache();
+  }
+  const dir = resolve(options['cache-dir'] ?? '.crosscheck/cache');
+  return createCache({
+    read: key => {
+      const path = join(dir, `${key}.json`);
+      if (!existsSync(path)) {
+        return null;
+      }
+      try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+      } catch {
+        // A corrupt entry is a miss, not a crash: the run should proceed and
+        // simply pay for that lens again.
+        return null;
+      }
+    },
+    write: (key, entry) => {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, `${key}.json`), JSON.stringify(entry, null, 2));
+    }
+  });
+}
+
 function execCommand(commandLine) {
   return ({ prompt }) => new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(commandLine, {
@@ -255,7 +346,7 @@ function buildMerged(options) {
   };
 }
 
-function report({ merged, suppressed, stale }) {
+function report({ merged, suppressed, stale, refuted = [] }) {
   const counts = countsBySeverity(merged.findings);
   const out = [];
   out.push('# Crosscheck report');
@@ -270,6 +361,9 @@ function report({ merged, suppressed, stale }) {
     out.push('', `Baseline entries no longer reported: ${stale.length} — ` +
       'either fixed, or a lens stopped running.');
   }
+  // Always stated, including zero: a finding that vanished without a count is
+  // indistinguishable from one that was never found.
+  out.push('', `Refuted in verification: ${refuted.length}.`);
   if (merged.unparsed.length) {
     out.push('', `Unparsed lens lines: ${merged.unparsed.length} ` +
       `(${[...new Set(merged.unparsed.map(u => u.lens))].join(', ')}).`);
@@ -285,7 +379,12 @@ function report({ merged, suppressed, stale }) {
       const who = f.consensus
         ? `CONSENSUS ${f.consensusScore}: ${f.lenses.join(', ')}`
         : f.lenses.join(', ');
-      out.push(`- [${who}] ${f.file}:${f.line} — ${f.issue}` +
+      // More reports than lenses means nearby similar findings were collapsed;
+      // say so and give the lines, or the entry understates what was reported.
+      const collapsed = f.occurrences > f.lenses.length
+        ? ` (${f.occurrences} reports across lines ${f.lines.join(', ')})`
+        : '';
+      out.push(`- [${who}] ${f.file}:${f.line}${collapsed} — ${f.issue}` +
         (f.fix ? ` — ${f.fix}` : ''));
     }
   }
@@ -336,18 +435,185 @@ function loadConfig(explicitPath) {
   return { config, path };
 }
 
+const INIT_CONFIG = `{
+  "// exec": "any command that takes a lens prompt on stdin and returns findings",
+  "exec": "claude -p",
+  "concurrency": 2,
+  "// context": "lines of surrounding code given to a lens around each change",
+  "context": 20
+}
+`;
+
+const INIT_LENS_README = `# Project lenses
+
+Markdown files here are added to the packaged lenses. A file whose \`name\`
+matches a packaged lens overrides it, and the override is printed on every run.
+
+Run \`crosscheck lenses\` to see what resolved and where each lens came from.
+
+A lens needs five frontmatter keys and a body:
+
+    ---
+    name: house-rules
+    summary: conventions this team actually enforces
+    when: [**/*.{js,mjs}]
+    owns: violations of our written conventions
+    not-owns: correctness, security, architecture, usability
+    ---
+
+    # Lens: house-rules
+
+    ...what to look for...
+
+    Findings only, one per line: \`file:line — SEVERITY — issue — fix\`.
+    SEVERITY is BLOCK, FIX, or CONSIDER. Reply exactly \`NO FINDINGS\` if none.
+
+Nothing in this directory is published or uploaded by crosscheck. It is read off
+disk at dispatch and goes nowhere else, so a lens here can encode conventions,
+domain detail, or house rules that would make no sense upstream.
+`;
+
+const INIT_WORKFLOW = `name: crosscheck
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  # Required to upload SARIF to code scanning.
+  security-events: write
+  # Required to post the summary comment.
+  pull-requests: write
+
+concurrency:
+  group: crosscheck-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # crosscheck reviews a diff, so it needs the base commit too.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Review the change
+        env:
+          # Provide whatever your --exec command needs. crosscheck itself never
+          # talks to a model.
+          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          npx @applesnort/crosscheck run \\
+            --since origin/\${{ github.base_ref }} \\
+            --sarif crosscheck.sarif \\
+            --comment-file comment.md
+
+      - name: Upload SARIF
+        if: always() && hashFiles('crosscheck.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: crosscheck.sarif
+
+      - name: Post or update the summary comment
+        if: always() && hashFiles('comment.md') != ''
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Edit our previous comment rather than stacking a new one.
+          id=$(gh api "repos/\${{ github.repository }}/issues/\${{ github.event.number }}/comments" \\
+                 --jq '[.[] | select(.body | contains("<!-- crosscheck:report -->"))] | last | .id // empty')
+          if [ -n "$id" ]; then
+            gh api --method PATCH "repos/\${{ github.repository }}/issues/comments/$id" \\
+              -F body=@comment.md
+          else
+            gh api --method POST "repos/\${{ github.repository }}/issues/\${{ github.event.number }}/comments" \\
+              -F body=@comment.md
+          fi
+`;
+
+// Scaffold, without overwriting anything. A tool that silently replaces a config
+// someone tuned is worse than one that refuses.
+function initCommand(options) {
+  const force = Boolean(options.force);
+  const targets = [
+    { path: '.crosscheckrc.json', content: INIT_CONFIG },
+    { path: '.crosscheck/lenses/README.md', content: INIT_LENS_README },
+    { path: '.github/workflows/crosscheck.yml', content: INIT_WORKFLOW }
+  ];
+  const written = [];
+  const kept = [];
+  for (const { path, content } of targets) {
+    const full = resolve(path);
+    if (existsSync(full) && !force) {
+      kept.push(path);
+      continue;
+    }
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+    written.push(path);
+  }
+  const out = [];
+  if (written.length) {
+    out.push('Created:', ...written.map(p => `  ${p}`));
+  }
+  if (kept.length) {
+    out.push('Left alone (already present; --force overwrites):',
+      ...kept.map(p => `  ${p}`));
+  }
+  out.push('',
+    'Next: set "exec" in .crosscheckrc.json to the command that runs your model,',
+    'then try a dry run:',
+    '',
+    '  crosscheck run --diff --dry-run',
+    '');
+  process.stdout.write(out.join('\n'));
+}
+
 async function runCommand(cliOptions, positional) {
   const { config, path: configPath } = loadConfig(cliOptions.config);
   const options = mergeConfig(config, cliOptions);
   if (configPath) {
     process.stderr.write(`crosscheck: config ${configPath}\n`);
   }
-  if (positional.length === 0) {
-    fail('run needs at least one path to audit');
+  if (options.preflight) {
+    runPreflight(options.preflight);
+  }
+  const diffMode = options.staged || options.since != null ||
+    options.diff != null;
+  if (positional.length === 0 && !diffMode) {
+    fail('run needs a path to audit, or --diff / --staged / --since <ref>');
+  }
+
+  // Resolve the target first: a bad path or an empty diff is the more
+  // fundamental error, and reporting a missing flag instead sends the user after
+  // the wrong problem.
+  let files;
+  let rangesByFile = null;
+  if (diffMode) {
+    const cmd = diffCommand({
+      diff: options.diff, staged: options.staged, since: options.since
+    });
+    process.stderr.write(`crosscheck: git ${cmd.join(' ')}\n`);
+    const target = targetFromDiff(git(cmd));
+    if (target.files.length === 0) {
+      process.stderr.write(
+        'crosscheck: the diff contains no reviewable changes — nothing to do\n');
+      return;
+    }
+    files = target.files;
+    // Widen to give a lens the surrounding code. A defect introduced by a change
+    // is often only visible against the lines the change did not touch.
+    const context = Number(options.context ?? 20);
+    rangesByFile = Object.fromEntries(Object.entries(target.rangesByFile)
+      .map(([file, ranges]) => [file, withContext(ranges, context)]));
+  } else {
+    files = collectFiles(positional);
   }
-  // Resolve the target first: a bad path is the more fundamental error, and
-  // reporting a missing flag instead sends the user after the wrong problem.
-  const files = collectFiles(positional);
   if (!options.exec && !options['dry-run']) {
     fail("run needs --exec '<command>' (or --dry-run to see the prompts)");
   }
@@ -380,7 +646,10 @@ async function runCommand(cliOptions, positional) {
     fail('no lens matched the target; nothing to run');
   }
 
-  const promptOptions = { mixedCorpus: Boolean(options.mixed) };
+  const promptOptions = {
+    mixedCorpus: Boolean(options.mixed),
+    rangesByFile
+  };
 
   if (options['dry-run']) {
     for (const job of promptsFor(roster, promptOptions)) {
@@ -390,17 +659,57 @@ async function runCommand(cliOptions, positional) {
     return;
   }
 
-  const { reports, failures } = await runPanel({
+  // Each lens may run under its own command, so dispatch resolves per lens
+  // rather than sharing one executor.
+  const byLens = new Map(roster.map(l => [l.name, l]));
+  const dispatch = async ({ prompt, lens, files }) => {
+    const commandLine = resolveExec(byLens.get(lens), options.exec);
+    if (!commandLine) {
+      throw new Error(
+        `no exec for lens "${lens}" — set exec, or an exec map entry for it`);
+    }
+    return execCommand(commandLine)({ prompt, lens, files });
+  };
+
+  const cache = buildCache(options);
+  const { reports, failures, dropped, cacheStats } = await runPanel({
     roster,
     skipped,
-    exec: execCommand(options.exec),
+    exec: dispatch,
     concurrency: Number(options.concurrency ?? 4),
     promptOptions,
+    cache: cache.enabled ? cache : null,
+    cacheKeyFor: cache.enabled
+      ? job => cacheKey({
+        lens: job.lens,
+        definition: byLens.get(job.lens)?.definition,
+        files: job.files.map(path => ({
+          path,
+          content: existsSync(path) ? readFileSync(path, 'utf8') : ''
+        })),
+        promptOptions
+      })
+      : null,
+    maxDispatches: options['max-dispatches'] == null
+      ? null : Number(options['max-dispatches']),
     onLensStart: lens => process.stderr.write(`  → ${lens}\n`),
     onLensDone: (lens, r) => process.stderr.write(
-      r.ok ? `  ✓ ${lens} (${r.findings} finding(s))\n` : `  ✗ ${lens} did not complete\n`)
+      r.ok
+        ? `  ✓ ${lens} (${r.findings} finding(s))${r.cached ? ' [cached]' : ''}\n`
+        : `  ✗ ${lens} did not complete\n`)
   });
 
+  // Both of these are coverage holes, and this tool states its holes.
+  if (dropped.length) {
+    process.stderr.write(
+      `crosscheck: BUDGET REACHED — ${dropped.length} lens(es) not run: ` +
+      `${dropped.map(d => d.lens).join(', ')}\n`);
+  }
+  if (cacheStats?.hits) {
+    process.stderr.write(
+      `crosscheck: ${cacheStats.hits} lens(es) served from cache\n`);
+  }
+
   for (const f of failures) {
     process.stderr.write(`crosscheck: ${f.lens} failed — ${f.reason}\n`);
   }
@@ -416,6 +725,39 @@ async function runCommand(cliOptions, positional) {
 
   const overlap = loadJson(options.overlap) ?? undefined;
   let merged = mergeFindings(reports, { overlap });
+
+  // Verification is on by default for BLOCK findings: false positives cost more
+  // than misses, because a panel that cries wolf stops being read at all.
+  let refuted = [];
+  const verifyWanted = options['no-verify'] ? false : true;
+  if (verifyWanted) {
+    const candidates = merged.findings.filter(f =>
+      options.verify ? true : f.severity === 'BLOCK');
+    if (candidates.length > 0) {
+      process.stderr.write(
+        `crosscheck: verifying ${candidates.length} finding(s)\n`);
+      const { verdicts, failures: verifyFailures } = await verifyFindings({
+        findings: candidates,
+        exec: execCommand(options.exec),
+        concurrency: Number(options.concurrency ?? 4),
+        onVerdict: (f, v) => process.stderr.write(
+          `  ${v.refuted ? '✗ refuted' : '✓ confirmed'} ${f.file}:${f.line}\n`)
+      });
+      for (const f of verifyFailures) {
+        // A verifier that did not run is not agreement; the finding stands.
+        process.stderr.write(
+          `crosscheck: verifier failed for ${f.finding} — ${f.reason}; ` +
+          'the finding is kept\n');
+      }
+      const applied = applyVerdicts(merged.findings, verdicts);
+      refuted = applied.refuted;
+      merged = { ...merged, findings: applied.findings };
+      if (refuted.length) {
+        process.stderr.write(
+          `crosscheck: ${refuted.length} finding(s) refuted and removed\n`);
+      }
+    }
+  }
   let suppressed = [];
   let stale = [];
   const baseline = loadJson(options.baseline);
@@ -426,11 +768,27 @@ async function runCommand(cliOptions, positional) {
     merged = { ...merged, findings: filtered.findings };
   }
 
-  process.stdout.write(report({ merged, suppressed, stale }));
+  process.stdout.write(report({ merged, suppressed, stale, refuted }));
+
+  if (options['comment-file']) {
+    writeFileSync(options['comment-file'], buildComment({
+      merged,
+      refuted,
+      suppressed,
+      dropped,
+      skipped,
+      target: diffMode
+        ? `${files.length} changed file(s)`
+        : `${files.length} file(s)`,
+      sarifPath: options.sarif ?? null
+    }));
+    process.stderr.write(`crosscheck: wrote ${options['comment-file']}\n`);
+  }
 
   if (options.sarif) {
     writeFileSync(options.sarif, toSarifJson(merged, {
-      lensMeta: Object.fromEntries(lenses.map(l => [l.name, l]))
+      lensMeta: Object.fromEntries(lenses.map(l => [l.name, l])),
+      refuted
     }));
     process.stderr.write(`crosscheck: wrote ${options.sarif}\n`);
   }
@@ -457,6 +815,11 @@ async function main() {
     return;
   }
 
+  if (command === 'init') {
+    initCommand(options);
+    return;
+  }
+
   if (command === 'lenses') {
     const sources = lensSources(options.lenses,
       { includeBuiltin: !options['no-builtin'] });

package/lib/cache.mjs

@@ -0,0 +1,100 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Result cache.
+//
+// A panel that re-reviews unchanged files on every run costs money for nothing,
+// and a tool that costs money for nothing gets switched off. Caching is keyed on
+// everything that could change the answer: the lens definition, the files, their
+// contents, and the prompt options.
+//
+// The lens definition is part of the key on purpose. Editing a lens must
+// invalidate its cached results — a cache that survives a prompt change would
+// quietly serve answers from the old lens and there would be no way to tell.
+//
+// Pure key computation; IO is injected so this is testable without a disk.
+
+// FNV-1a over the inputs. Not cryptographic: it only has to distinguish inputs
+// within one project, and a collision costs a stale result rather than a
+// security failure.
+export function digest(parts) {
+  let h = 0x811c9dc5;
+  for (const part of parts) {
+    const s = String(part);
+    for (let i = 0; i < s.length; i++) {
+      h = Math.imul(h ^ s.charCodeAt(i), 0x01000193) >>> 0;
+    }
+    // Separator, so ['ab','c'] and ['a','bc'] do not collide.
+    h = Math.imul(h ^ 0x1f, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+export const CACHE_VERSION = 1;
+
+// files: [{path, content}] in the order the lens will see them.
+export function cacheKey({ lens, definition, files, promptOptions = {} }) {
+  if (!lens) {
+    throw new Error('cacheKey requires a lens name');
+  }
+  return digest([
+    `v${CACHE_VERSION}`,
+    lens,
+    // The definition body decides what the lens does, so it decides the answer.
+    definition ?? '',
+    ...(files ?? []).flatMap(f => [f.path, f.content ?? '']),
+    JSON.stringify(promptOptions ?? {})
+  ]);
+}
+
+// entry: {key, lens, output, storedAt}
+export function isUsableEntry(entry, key) {
+  return Boolean(
+    entry &&
+    entry.key === key &&
+    entry.version === CACHE_VERSION &&
+    typeof entry.output === 'string' &&
+    entry.output.length > 0);
+}
+
+export function makeEntry({ key, lens, output, now }) {
+  return {
+    version: CACHE_VERSION,
+    key,
+    lens,
+    // Recorded for a human reading the cache directory, not used for matching.
+    storedAt: now ?? null,
+    output
+  };
+}
+
+// A cache wired to injected IO. `read` returns a parsed entry or null; `write`
+// persists one. Both may be omitted to disable caching entirely, which is what
+// --no-cache does.
+export function createCache({ read = null, write = null } = {}) {
+  const stats = { hits: 0, misses: 0, writes: 0, hitLenses: [] };
+  return {
+    stats,
+    enabled: Boolean(read || write),
+    get(key, lens) {
+      if (!read) {
+        return null;
+      }
+      const entry = read(key);
+      if (isUsableEntry(entry, key)) {
+        stats.hits += 1;
+        stats.hitLenses.push(lens);
+        return entry.output;
+      }
+      stats.misses += 1;
+      return null;
+    },
+    set(key, lens, output, now = null) {
+      if (!write || !output) {
+        return;
+      }
+      write(key, makeEntry({ key, lens, output, now }));
+      stats.writes += 1;
+    }
+  };
+}