testguard-cli 0.10.4 → 0.12.0

package/src/cli.mjs

@@ -18,6 +18,7 @@ import { gateCommand } from './commands/gate.mjs';
 import { replayCommand } from './commands/replay.mjs';
 import { mcpCommand } from './commands/mcp.mjs';
 import { admitCommand } from './commands/admit.mjs';
+import { sweepCommand } from './commands/sweep.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 const ISSUES = 'https://github.com/raccioly/testguard/issues';
@@ -32,6 +33,7 @@ export const USAGE = `testguard ${VERSION} — proves a test suite defends the c
   testguard brief [dir]      emit the blind-spot block for an agent's session-start context
   testguard gate [dir]       fail when a changed source file carries no claim and no excusing ignore entry
   testguard scaffold <file>  propose faults mechanically for one source file, as a draft claims document
+  testguard sweep [dir]      propose faults for the changed source files that carry no claim, probe a bounded selection, and report what nothing noticed
   testguard mcp              serve the read-only status/brief/claims/evidence tools over MCP on stdio, so the loop works in any agent harness
   testguard replay [dir]     would this suite have caught the bugs that already escaped? Replays real fix commits and calibrates fault classes against them
   testguard admit <test> --claim <ID>   the two-gate rule as one verb: is this test green on HEAD and does it fail on every fault of the claim?
@@ -74,6 +76,13 @@ probe
   --json               the status document plus this run's result (records, newSinceBaseline, exitCode)
 
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
+sweep      --changed <ref> (required unless --save-paths; CI bases and a safe local default are detected)  --cap <n>
+           --save-paths      sweep every file that WRITES TO STORAGE instead of the diff, and report the surface as the
+                             denominator: "120 writes across 38 files, swept 12". A clean sweep over an unstated
+                             denominator is a sample of unknown size, not a guarantee that saving works
+           --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --max <n>  --out <path>  --json
+           the cold start: no claim and no concern needed. Everything it proposes is a DRAFT — it never writes testguard.claims.json,
+           and its evidence never replaces .testguard/evidence.json. exit 1 on a fault that survived, or a file no test imports
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
                    · security flag/window/cost literal weakened · verify/validate/check call removed
                    · field dropped from a payload/allow-list/schema/merge · parameter-derived argument swapped for undefined/{}
@@ -117,7 +126,7 @@ brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only;
 exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift, or unclaimed changes) · 2 precondition failed · 3 usage
 `;
 
-const COMMANDS = { mcp: mcpCommand, replay: replayCommand, probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand, admit: admitCommand };
+const COMMANDS = { mcp: mcpCommand, replay: replayCommand, probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand, admit: admitCommand, sweep: sweepCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -143,6 +152,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         changed: { type: 'string' },
         since: { type: 'string' },
         exclude: { type: 'string', multiple: true },
+        cap: { type: 'string' },
+        'save-paths': { type: 'boolean', default: false },
         strict: { type: 'boolean', default: false },
         explain: { type: 'boolean', default: false },
         ignore: { type: 'string' },

package/src/commands/sweep.mjs

@@ -0,0 +1,80 @@
+import { join, resolve } from 'node:path';
+import { sweep, renderSweep } from '../sweep/sweep.mjs';
+import { resolveChangedRef } from '../gate/changed.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+
+export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.json');
+
+/**
+ * `testguard sweep [dir] --changed <ref>`: propose faults for the changed
+ * source files that carry no claim, probe a bounded selection, and report what
+ * a green suite did not notice.
+ *
+ * Exit 0 nothing survived · 1 a survivor or an untested file · 2 cannot
+ * evaluate · 3 no reference.
+ *
+ * The sweep document goes to `.testguard/sweep.json` and NEVER to
+ * `.testguard/evidence.json`. The canonical evidence is the record of what the
+ * project claims; a sweep probes faults nobody stated, under TODO statements,
+ * and folding one into the other would corrupt what `status` and `baseline`
+ * read.
+ */
+export async function sweepCommand({ projectDir, values, version }, io) {
+  const mode = values['save-paths'] ? 'save-paths' : 'changed';
+  // `--save-paths` scans the whole write surface, so it needs no diff. The gate
+  // is still computed underneath (the document reports `changed`), and HEAD is
+  // a reference every repository has.
+  const resolved = resolveChangedRef({ explicit: values.changed, projectDir })
+    ?? (mode === 'save-paths' ? { ref: 'HEAD', from: 'save-paths', required: false } : null);
+  if (!resolved) {
+    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);
+    if (!Number.isInteger(cap) || cap < 1) {
+      io.err('--cap must be a positive integer');
+      return 3;
+    }
+  }
+  if (mode === 'changed' && !resolved.required && !values.json && !values.quiet) io.err(`sweep: comparing against ${resolved.ref} (${resolved.from})`);
+
+  const doc = await sweep({
+    projectDir,
+    ref: resolved.ref,
+    mode,
+    includeDirty: values['include-dirty'],
+    exclude: values.exclude ?? [],
+    cap,
+    confirmRuns,
+    budgetMs,
+    runnerCommand: values['runner-cmd'],
+    runnerName: values.runner,
+    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    toolVersion: version,
+    claimsPath: values.claims ? resolve(values.claims) : undefined,
+    ignorePath: values.ignore ? resolve(values.ignore) : undefined,
+    onStage: !values.quiet && !values.json && process.stderr.isTTY
+      ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`)
+      : undefined,
+    onWarn: (m) => { if (!values.quiet) io.err(`warning: ${m}`); },
+  });
+  if (process.stderr.isTTY && !values.quiet && !values.json) process.stderr.write('\r\x1b[K');
+
+  const outPath = values.out ? resolve(values.out) : sweepPath(projectDir);
+  writeSpecDoc('sweep', outPath, doc);
+  if (values.json) {
+    io.out(JSON.stringify(doc, null, 2));
+  } else {
+    io.out(renderSweep(doc, { limit: Number(values.max) || 20 }));
+    if (!values.quiet) io.out(`\nsweep: ${outPath}`);
+  }
+  return doc.exitCode;
+}

package/src/supply/persistence.mjs

@@ -0,0 +1,173 @@
+/**
+ * The save-button signal: why a fault on the persistence path survived.
+ *
+ * `mocks.mjs` answers "does this test replace the SUBJECT?", and a file that
+ * does cannot detect any fault in it. This is the other half, and it is the
+ * one that explains a green suite over a save that does not save. Such a test
+ * does NOT mock the subject — it mocks the persistence layer underneath it —
+ * so it is a legitimate defender and stays one. It can catch a deleted write.
+ * What it cannot catch is a wrong PAYLOAD, and only because of how it asserts.
+ *
+ * Measured on a real AI-authored Next.js application (2026-09-21): 10 of 10
+ * server-action tests mocked `@/lib/prisma`, and 12 of 12 surviving faults on
+ * the persistence path were a field dropped from a `data` / `where` object.
+ * The assertion that should have caught them was `toHaveBeenCalledWith(
+ * expect.objectContaining({...}))` naming every field except the one carrying
+ * the data — the pathology this project's README reports from the field.
+ *
+ * DESCRIPTIVE, NOT PREDICTIVE — and that is a correction the measurement
+ * forced. The first version of this file silenced itself when a test contained
+ * any exact payload assertion. On the same 26 probed faults that rule fired on
+ * 1 of 10 files while 4 had survivors, because a file asserts many calls and
+ * the one exact assertion is usually about something else:
+ * `identity-password-recovery.test.ts` has one exact assertion among forty and
+ * every one of its payload faults survived, while `contact.test.ts` has the
+ * same one exact assertion and none did. No file-level threshold separates
+ * those two, so this reports the SHAPE and refuses to score it.
+ *
+ * It is therefore attached to a verdict the probe already reached, never used
+ * to predict one or to select what gets probed. The probe says a fault
+ * survived; this says the structural reason and what to write instead.
+ *
+ * Line- and regex-oriented, like the scaffold producers: no AST, no type
+ * information, and an honest miss rather than a confident wrong claim. In
+ * particular there is no read-back detection here. A regex for "the test asked
+ * for the row again" matched every file that mocks `findUnique` and asserts
+ * anything, including files whose payload faults all survived, so it measured
+ * nothing and was removed rather than shipped as a silencer.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Module specifiers that mean "the database". A project-local path counts when
+ * it names one of these — `@/lib/prisma`, `../db`, `~/server/drizzle` — which
+ * is how these layers are named in practice.
+ */
+const PERSISTENCE_SPECIFIER = /(?:^|[/@~.])(?:prisma|db|database|knex|sequelize|mongoose|typeorm|drizzle|supabase|pg|mysql2?|sqlite3?|dynamodb|mongodb)(?:$|[/.])/i;
+
+/** `vi.mock('x')` / `jest.mock('x')` — the same call shapes mocks.mjs reads. */
+const MOCK_CALL = /\b(?:vi|jest)\.(?:mock|doMock|unstable_mockModule)\(\s*(['"])([^'"]+)\1/g;
+
+/** Partial matchers: true of a subset, so a dropped field outside the subset passes. */
+const PARTIAL_MATCHER = /expect\.(?:objectContaining|arrayContaining|any|anything|stringContaining|stringMatching)\s*\(/;
+
+/** The persistence specifiers this source mocks, with line numbers. */
+export function persistenceMocks(source) {
+  const out = [];
+  source.split('\n').forEach((text, i) => {
+    for (const m of text.matchAll(MOCK_CALL)) {
+      if (PERSISTENCE_SPECIFIER.test(m[2])) out.push({ specifier: m[2], line: i + 1 });
+    }
+  });
+  return out;
+}
+
+/**
+ * The text between an open parenthesis at `open` and its match, so one
+ * assertion's arguments are read without reading the next one's.
+ *
+ * A fixed-width window cannot do this: two assertions on adjacent lines put the
+ * second one's `expect.objectContaining` inside the first one's window, and
+ * every exact assertion in a dense test file is reported as partial. Measured —
+ * the first version of this scored a file with one exact and one partial
+ * assertion as two partials.
+ *
+ * Quotes are tracked because a parenthesis inside a string is not a
+ * parenthesis; anything unbalanced returns what it read, which errs toward
+ * reporting a partial matcher that is really there.
+ */
+function balancedArgs(source, open) {
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < source.length; i++) {
+    const c = source[i];
+    if (quote) {
+      if (c === '\\') i += 1;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+    else if (c === '(') depth += 1;
+    else if (c === ')') {
+      depth -= 1;
+      if (depth === 0) return source.slice(open + 1, i);
+    }
+  }
+  return source.slice(open + 1);
+}
+
+/**
+ * How this source asserts on its mocks: how many assertions name the exact
+ * arguments, how many name them only partially, and how many assert that a
+ * call happened without saying with what.
+ *
+ * Counting rather than deciding. The counts go into the reason string so a
+ * reader can disagree with the inference instead of only with a verdict.
+ */
+export function payloadAssertions(source) {
+  let exact = 0;
+  let partial = 0;
+  let argless = 0;
+  for (const m of source.matchAll(/\.toHaveBeenCalledWith\s*\(/g)) {
+    const open = m.index + m[0].length - 1;
+    if (PARTIAL_MATCHER.test(balancedArgs(source, open))) partial += 1;
+    else exact += 1;
+  }
+  for (const _ of source.matchAll(/\.(?:toHaveBeenCalled|toHaveBeenCalledTimes|toHaveBeenCalledOnce)\s*\(/g)) argless += 1;
+  return { exact, partial, argless };
+}
+
+/**
+ * The shape of one defender's relationship to the persistence layer, or null
+ * when it does not mock one. Shaped like the records `mocks.mjs` produces so a
+ * caller can merge the two lists without reshaping either.
+ */
+export function analyzePersistence(projectDir, testRel) {
+  let source;
+  try {
+    source = readFileSync(join(projectDir, testRel), 'utf8');
+  } catch {
+    return null;
+  }
+  const mocks = persistenceMocks(source);
+  if (mocks.length === 0) return null;
+  const counts = payloadAssertions(source);
+  const specifiers = [...new Set(mocks.map((m) => m.specifier))].sort();
+  const shape = [
+    counts.exact ? `${counts.exact} exact` : '',
+    counts.partial ? `${counts.partial} partial` : '',
+    counts.argless ? `${counts.argless} argument-free` : '',
+  ].filter(Boolean).join(', ') || 'no';
+  return {
+    file: testRel,
+    signal: 'persistence-payload-unasserted',
+    reason: `mocks ${specifiers.join(', ')}; ${shape} call assertion${counts.exact + counts.partial + counts.argless === 1 ? '' : 's'} in the file. A field dropped from the write payload fails only against an assertion that names that field exactly.`,
+    counts,
+    specifiers,
+  };
+}
+
+/**
+ * The signal for a claim's defenders. Only ever consulted for a SURVIVOR whose
+ * fault is on the persistence path: on a kill it explains nothing, and on any
+ * other line a loose mock assertion is not evidence of anything. Reporting it
+ * everywhere would be the non-actionable noise that gets a check switched off.
+ */
+export function persistenceSignals(projectDir, defenders) {
+  return defenders.map((d) => analyzePersistence(projectDir, d)).filter(Boolean);
+}
+
+/**
+ * One line an agent can act on, in the register `hintFor()` uses.
+ *
+ * The field name is read from either property form. Shorthand is not an edge
+ * case here: every surviving payload fault measured on the register action was
+ * shorthand — `email,` `username,` `password_hash,` — so a pattern that only
+ * matched `name: value` would fail to name the field in exactly the cases that
+ * prompted this signal.
+ */
+export function persistenceHint(signal, faultLine) {
+  const field = /^\s*([A-Za-z_$][\w$]*)\s*(?::|,\s*$)/.exec(faultLine ?? '')?.[1];
+  return `${signal.file} ${signal.reason} Assert the whole object written by the call this fault changes${field ? `, including \`${field}\`` : ''} — or read the record back and assert on what was stored.`;
+}

package/src/supply/savepath.mjs

@@ -0,0 +1,216 @@
+/**
+ * Where this project writes to storage, and what it writes.
+ *
+ * A probe answers "would a test notice if this were wrong". It cannot answer
+ * "how many places write to the database, and how many of those has anyone
+ * looked at" — and on an application with two hundred screens that second
+ * question is the one that decides whether a clean report means anything. A
+ * verdict with no denominator is not a guarantee; it is a sample of unknown
+ * size.
+ *
+ * So this enumerates the surface. Measured on a real AI-authored Next.js
+ * application: 115 write sites across 34 source files, of which 46% of the
+ * probed persistence faults survived a fully green suite, and every survivor
+ * was a field dropped from the payload. The faults are already produced by
+ * `field-dropped` and already ranked up by `onWritePath`; what was missing was
+ * the list of places to point them at.
+ *
+ * DELIBERATELY SHALLOW. This finds call sites, not data flow. It does not know
+ * whether a write is reachable, whether two writes are the same transaction,
+ * or whether a helper wraps one. A site it cannot see is reported as nothing
+ * at all rather than as an absence of risk — the same rule the scaffold
+ * producers follow, and the reason `skipped` exists on a sweep. Its output is
+ * a denominator and a set of targets, never a verdict.
+ */
+import { readFileSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { walk } from '../util/glob.mjs';
+
+/**
+ * A call that puts data into storage.
+ *
+ * The receiver is matched by NAME because that is how these layers are bound
+ * in practice — `prisma.user.create`, `tx.invitation.upsert`, `db.orders.insertOne`.
+ * Matching by import would be more correct and would miss the common case
+ * where the client is a module-scope singleton imported under a project alias.
+ *
+ * `delete` is included: a save path that stops deleting is as broken as one
+ * that stops writing, and account deletion is where that matters most.
+ */
+const WRITE_CALL = /\b(prisma|tx|trx|db|database|knex|sequelize|mongoose|supabase|drizzle|client|conn)\s*\.\s*(?:([A-Za-z_$][\w$]*)\s*\.\s*)?(create|createMany|createOne|update|updateMany|updateOne|upsert|insert|insertOne|insertMany|save|delete|deleteMany|deleteOne|destroy|remove|set|put)\s*\(/g;
+
+/**
+ * Raw SQL that writes. A template literal or a string argument, either way.
+ *
+ * Two regexes for one pattern, deliberately. A `g`-flagged RegExp carries
+ * `lastIndex` across calls, so `WRITE_SQL.test(a)` followed by
+ * `WRITE_SQL.test(b)` answers the second question from where the first one
+ * stopped — which makes a scan's result depend on the order the files were
+ * read. `matchAll` needs the flag; the cheap reject must not have it.
+ */
+const WRITE_SQL = /\b(INSERT\s+INTO|UPDATE\s+[A-Za-z_"`[]|DELETE\s+FROM|UPSERT\s+INTO)\b/gi;
+const HAS_SQL = new RegExp(WRITE_SQL.source, 'i');
+
+/**
+ * Every operation name the call pattern accepts, as one alternation. Derived
+ * rather than written twice: the cheap reject below used a shorter list, and a
+ * `deleteMany(` call matched the full pattern while failing the reject, so
+ * every file whose only write was a `...Many` or `...One` call was dropped
+ * from the surface before it was ever scanned.
+ */
+const OPERATIONS = 'create|createMany|createOne|update|updateMany|updateOne|upsert|insert|insertOne|insertMany|save|delete|deleteMany|deleteOne|destroy|remove|set|put';
+const HAS_WRITE_CALL = new RegExp(`\\b(?:${OPERATIONS})\\s*\\(`);
+
+/**
+ * Files that contain writes but are never the product's own save path.
+ *
+ * Seed and migration scripts write, and a real run surfaced
+ * `prisma/seed-badges.ts` as NOCOVER — true, and not a finding: nobody tests a
+ * seed script, and reporting it teaches the reader to skim. The directory
+ * forms are matched as well as the file stems, because a seed lives in
+ * `prisma/seed.ts` as often as in `seeds/`.
+ */
+const NOT_SOURCE = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|__tests__|__mocks__|__fixtures__|fixtures|migrations|seeds?|scripts?|prisma|drizzle)\/|(^|\/)seeds?[.-][^/]*$|(^|\/)seeds?\.[cm]?[jt]sx?$/;
+
+const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']);
+
+/**
+ * The text of one call's arguments, from its open parenthesis to the matching
+ * close, with quotes tracked so a parenthesis inside a string is not counted.
+ *
+ * The same scan `payloadAssertions` uses, and for the same reason: a
+ * fixed-width window reads into the NEXT call, and on a file with several
+ * writes in a row that silently attributes one write's payload to another.
+ */
+export function balancedArgs(source, open) {
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < source.length; i++) {
+    const c = source[i];
+    if (quote) {
+      if (c === '\\') i += 1;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+    else if (c === '(') depth += 1;
+    else if (c === ')') {
+      depth -= 1;
+      if (depth === 0) return { start: open + 1, end: i, text: source.slice(open + 1, i) };
+    }
+  }
+  return { start: open + 1, end: source.length, text: source.slice(open + 1) };
+}
+
+/**
+ * The keys of a write's payload, each with the line it sits on.
+ *
+ * Both property forms, because shorthand is not an edge case here: every
+ * surviving payload fault measured on the register action was shorthand
+ * (`email,` `username,` `password_hash,`). A pattern requiring a colon would
+ * miss exactly the fields this exists to find.
+ *
+ * Keys are read only where they sit on their own line, which is what the
+ * `field-dropped` producer can anchor to. A single-line write like
+ * `update({ where, data })` therefore reports no keys — correctly, because
+ * there is no line to delete.
+ */
+export function payloadKeys(argsText, firstLine) {
+  const keys = [];
+  argsText.split('\n').forEach((line, i) => {
+    const m = /^\s*(?:['"`])?([A-Za-z_$][\w$]*)(?:['"`])?\s*(?::|,\s*$)/.exec(line);
+    if (m) keys.push({ key: m[1], line: firstLine + i });
+  });
+  return keys;
+}
+
+/** Line number (1-based) of an index into a source string. */
+const lineAt = (source, index) => source.slice(0, index).split('\n').length;
+
+/**
+ * Every write this file performs. Pure apart from the read; exported so the
+ * shape can be tested against a string without a project on disk.
+ */
+export function writeSitesIn(source, file) {
+  const sites = [];
+  for (const m of source.matchAll(WRITE_CALL)) {
+    const open = m.index + m[0].length - 1;
+    const args = balancedArgs(source, open);
+    const line = lineAt(source, m.index);
+    sites.push({
+      file,
+      line,
+      endLine: lineAt(source, args.end),
+      receiver: m[1],
+      model: m[2] ?? null,
+      operation: m[3],
+      keys: payloadKeys(args.text, lineAt(source, args.start)),
+    });
+  }
+  for (const m of source.matchAll(WRITE_SQL)) {
+    sites.push({
+      file,
+      line: lineAt(source, m.index),
+      endLine: lineAt(source, m.index),
+      receiver: 'sql',
+      model: null,
+      operation: m[1].split(/\s+/)[0].toLowerCase(),
+      keys: [],
+    });
+  }
+  // Deterministic: a surface that reorders between runs is not a denominator.
+  return sites.sort((a, b) => a.line - b.line || a.operation.localeCompare(b.operation));
+}
+
+/** Is this path part of the product's own save surface? */
+export const isSaveSource = (rel) => SOURCE_EXT.has(extname(rel)) && !NOT_SOURCE.test(rel);
+
+/**
+ * The project's whole write surface: every source file that writes, and every
+ * write in it.
+ *
+ * `files` may be given to scope the scan (a diff, a directory); the default is
+ * every source file the glob walker can see.
+ */
+export function saveSurface(projectDir, { files } = {}) {
+  const candidates = (files ?? walk(projectDir)).filter(isSaveSource);
+  const byFile = [];
+  let siteCount = 0;
+  let keyCount = 0;
+  for (const rel of candidates) {
+    let source;
+    try {
+      source = readFileSync(join(projectDir, rel), 'utf8');
+    } catch {
+      continue;
+    }
+    // Cheap reject before the balanced scan: most files never write.
+    if (!HAS_WRITE_CALL.test(source) && !HAS_SQL.test(source)) continue;
+    const sites = writeSitesIn(source, rel);
+    if (!sites.length) continue;
+    byFile.push({ file: rel, sites });
+    siteCount += sites.length;
+    keyCount += sites.reduce((a, s) => a + s.keys.length, 0);
+  }
+  byFile.sort((a, b) => a.file.localeCompare(b.file));
+  return { files: byFile, fileCount: byFile.length, siteCount, keyCount };
+}
+
+/**
+ * The surface as text — the denominator, said out loud.
+ *
+ * A report that lists findings without saying how much was looked at invites
+ * the reader to assume the rest is fine, which is the assumption this whole
+ * tool exists to remove.
+ */
+export function renderSurface(surface, { limit = 10 } = {}) {
+  if (surface.fileCount === 0) return 'no write to storage found in this project.';
+  const out = [`${surface.siteCount} write${surface.siteCount === 1 ? '' : 's'} to storage across ${surface.fileCount} file${surface.fileCount === 1 ? '' : 's'}, carrying ${surface.keyCount} payload field${surface.keyCount === 1 ? '' : 's'} on their own lines.`];
+  const ranked = [...surface.files].sort((a, b) => b.sites.length - a.sites.length || a.file.localeCompare(b.file));
+  for (const f of ranked.slice(0, limit)) {
+    const ops = [...new Set(f.sites.map((s) => s.operation))].sort().join(', ');
+    out.push(`  ${String(f.sites.length).padStart(3)}  ${f.file}  (${ops})`);
+  }
+  if (ranked.length > limit) out.push(`  … ${ranked.length - limit} more files`);
+  return out.join('\n');
+}