testguard-cli 0.11.0 → 0.13.0

package/src/supply/concerns.mjs

@@ -0,0 +1,162 @@
+/**
+ * A concern: one sentence a human writes, that generates faults across a whole
+ * surface.
+ *
+ * The rung between "nothing written" and "a claim per behaviour". A claim names
+ * one promise and the faults that would break it; that is precise and it is why
+ * a repository with two hundred screens never finishes writing them. A concern
+ * names a KIND of promise — "every write persists the data it was given" — and
+ * says where to look for it and which shapes of break are relevant. One
+ * sentence, two hundred screens.
+ *
+ * The idea is Meta's. ACH has an engineer describe an area of concern in plain
+ * text, generates faults specific to it, and gates every step by execution
+ * ("Mutation-Guided LLM-based Test Generation at Meta", Foster et al., FSE
+ * 2025). What is taken here is the UNIT — the concern as the thing a human
+ * writes — not their generator.
+ *
+ * NO MODEL IS REQUIRED, and that is deliberate. A concern's useful core is a
+ * named scope plus a producer selection, both of which the mechanical
+ * producers already satisfy. An LLM can later propose faults a line-oriented
+ * producer cannot see, as an ADDITIONAL source for a concern that already
+ * works — rather than as the thing the rung depends on. That keeps every
+ * verifying command offline, which is the property this tool is least willing
+ * to trade.
+ *
+ * A concern is NOT a claim and never becomes one by itself. It says where to
+ * look; the probe says what it found; a human states the sentence worth
+ * defending. Nothing here is written to `testguard.claims.json`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { saveSurface } from './savepath.mjs';
+import { globToRegExp, walk } from '../util/glob.mjs';
+
+export const defaultConcernsPath = (projectDir) => join(projectDir, 'testguard.concerns.json');
+
+/**
+ * The concerns every project gets without writing anything.
+ *
+ * Two, because two are the ones whose targets can be enumerated honestly. An
+ * authorization concern would need a heuristic for "which files check
+ * permissions", and a guess there produces exactly the non-actionable noise
+ * that gets a check switched off. A project that knows its own auth layer can
+ * say so with a `glob` target in three lines; this file will not guess for it.
+ */
+export const BUILTIN_CONCERNS = Object.freeze([
+  Object.freeze({
+    id: 'SAVE-PERSISTS',
+    statement: 'Every write to storage persists the data it was given.',
+    severity: 'high',
+    targets: { kind: 'write-sites' },
+    // The shapes that break a persisted payload. Measured on a real
+    // application: 12 of 12 surviving faults on the persistence path were a
+    // field dropped from the payload, so the list leads with that.
+    faultClasses: ['field-dropped', 'call-removed', 'statement-deleted', 'literal-changed'],
+    builtin: true,
+  }),
+  Object.freeze({
+    id: 'CHANGED-CODE',
+    statement: 'Code changed in this branch is defended by something.',
+    severity: 'medium',
+    targets: { kind: 'changed' },
+    // Everything: a diff has no shape to narrow by.
+    faultClasses: null,
+    builtin: true,
+  }),
+]);
+
+/**
+ * Load the project's concerns, with the built-ins behind them.
+ *
+ * A project concern with the same id as a built-in REPLACES it, so a team can
+ * retune `SAVE-PERSISTS` for an ORM this tool does not recognise without
+ * forking anything. Shadowing is recorded rather than silent: a concern that
+ * quietly replaced a default would be the kind of surprise that costs an
+ * afternoon.
+ */
+export function loadConcerns(projectDir, { path } = {}) {
+  const p = path ?? defaultConcernsPath(projectDir);
+  let project = [];
+  let source = null;
+  if (existsSync(p)) {
+    const doc = JSON.parse(readFileSync(p, 'utf8'));
+    project = doc.concerns ?? [];
+    source = p;
+  }
+  const overridden = new Set(project.map((c) => c.id));
+  const concerns = [
+    ...project.map((c) => ({ ...c, builtin: false })),
+    ...BUILTIN_CONCERNS.filter((c) => !overridden.has(c.id)),
+  ];
+  return {
+    concerns,
+    // The project's own entries, exactly as written. Validation runs against
+    // these: the enriched objects above carry a `builtin` marker this tool
+    // added, and a schema that refuses unknown properties is right to reject
+    // them. Validating what we constructed instead of what the user wrote
+    // would report OUR bug as THEIR malformed file.
+    raw: project.map(({ builtin, ...c }) => c),
+    source,
+    shadowed: BUILTIN_CONCERNS.filter((c) => overridden.has(c.id)).map((c) => c.id),
+  };
+}
+
+/** One concern by id, or null. Ids are matched exactly: a near-miss is a typo, not an intention. */
+export const concernById = (concerns, id) => concerns.find((c) => c.id === id) ?? null;
+
+/**
+ * The files a concern applies to.
+ *
+ * `write-sites` asks the enumerator; `glob` matches the project's own paths;
+ * `changed` returns null, meaning "the caller's diff decides" — a concern does
+ * not get to re-derive what the gate already computed.
+ */
+export function targetsFor(projectDir, concern, { changedFiles } = {}) {
+  const t = concern.targets ?? { kind: 'changed' };
+  if (t.kind === 'write-sites') return saveSurface(projectDir).files.map((f) => f.file);
+  if (t.kind === 'glob') {
+    // Against the whole project, never the diff. A concern like "every admin
+    // route refuses an unauthorised caller" is about the admin routes, not
+    // about the ones that happened to change today — and pooling from the diff
+    // made such a concern report clean on a clean branch, which is the exact
+    // false reassurance a concern exists to prevent.
+    const res = (t.globs ?? []).map(globToRegExp);
+    return walk(projectDir).filter((f) => res.some((re) => re.test(f)));
+  }
+  return changedFiles ?? null;
+}
+
+/**
+ * Keep only the faults whose class this concern cares about.
+ *
+ * `faultClasses: null` means every class — the honest default for a concern
+ * with no shape to narrow by. Narrowing is what makes one sentence useful
+ * across two hundred files: a persistence concern that also reported every
+ * altered return value would bury the payload findings it exists to surface.
+ */
+export function filterByConcern(candidates, concern) {
+  if (!concern?.faultClasses) return candidates;
+  const keep = new Set(concern.faultClasses);
+  return candidates.filter((c) => keep.has(c.fault.faultClass));
+}
+
+/** The concerns as text, for someone deciding which to sweep. */
+export function renderConcerns({ concerns, source, shadowed }) {
+  const out = [];
+  out.push(source ? `${concerns.length} concern${concerns.length === 1 ? '' : 's'} (${source}, plus the built-ins)` : `${concerns.length} built-in concern${concerns.length === 1 ? '' : 's'} — none declared in this project.`);
+  out.push('');
+  for (const c of concerns) {
+    const shape = c.targets?.kind === 'glob' ? `glob ${(c.targets.globs ?? []).join(', ')}` : c.targets?.kind ?? 'changed';
+    out.push(`  ${c.id}${c.builtin ? '  (built-in)' : ''}`);
+    out.push(`    ${c.statement}`);
+    out.push(`    targets: ${shape} · faults: ${c.faultClasses ? c.faultClasses.join(', ') : 'every class'}`);
+    out.push('');
+  }
+  if (shadowed.length) out.push(`This project replaces the built-in ${shadowed.join(', ')}.`);
+  if (!source) {
+    out.push('Declare your own in testguard.concerns.json. A concern is one sentence and a');
+    out.push('scope: it says where to look, never what is true. Only a claim does that.');
+  }
+  return out.join('\n');
+}

package/src/supply/feedback.mjs

@@ -0,0 +1,146 @@
+/**
+ * What this project's own runs say about which faults are worth proposing.
+ *
+ * `select.mjs` ships a productivity prior measured on one real application.
+ * That is a reasonable starting point and a poor stopping point: the classes
+ * that survive a Next.js suite are not the classes that survive a Python one,
+ * and Google's mutation service got from a 15% productive rate to 89% on
+ * exactly this — feedback, accumulated over years, refining which candidates
+ * are worth a developer's attention ("Practical Mutation Testing at Scale",
+ * Petrović et al., 2021). The static table is the part of that idea this tool
+ * had not yet taken.
+ *
+ * THE FEEDBACK IS ALREADY ON DISK. Every evidence record carries a
+ * `faultClass` and a `verdict`, so "how often does a fault of this class
+ * survive here" is a tally, not a new thing to capture. There is no click to
+ * collect and no state to maintain: a project that has probed anything has
+ * already said what its own productive classes are.
+ *
+ * WHY THIS ESTIMATOR AND NOT A BETTER-SOUNDING ONE. The combination below is a
+ * Beta-Binomial posterior mean, and a posterior mean is what minimises Brier
+ * and log score in expectation — it is a STRICTLY PROPER estimate, which is
+ * the only kind that cannot be improved by reporting something other than an
+ * honest probability. Optimising the ordering for accuracy or F1 instead would
+ * maximise the number of survivors found while destroying the calibration of
+ * the number attached to each, which is the documented failure mode of naive
+ * optimisation and the reason Laya trains against proper scoring rules. If
+ * this file is ever changed to rank by anything but an honest probability,
+ * that is the invariant being broken.
+ *
+ * Pure apart from reading the documents it is given.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MEASURED_PRODUCTIVITY } from './select.mjs';
+
+/** The evidence a project may have produced, in the order they are most relevant. */
+export const EVIDENCE_PATHS = Object.freeze([
+  // A sweep probes MACHINE-proposed faults, the same distribution the ranker
+  // orders, so it is the closest observation available.
+  '.testguard/sweep-evidence.json',
+  // The canonical probe is human-authored faults: a real observation of the
+  // same classes, drawn slightly differently, and still worth counting.
+  '.testguard/evidence.json',
+]);
+
+/**
+ * Survival counts per fault class from one evidence document.
+ *
+ * Only `killed` and `survived` are counted. `nocover`, `unverifiable`,
+ * `fault-invalid`, `timeout` and `flaky-defender` say nothing about whether a
+ * fault of that class would be NOTICED — they say the question could not be
+ * asked — and folding them in either direction would be inventing data.
+ */
+export function tallyEvidence(doc) {
+  const by = {};
+  for (const r of doc?.records ?? []) {
+    const cls = r.subject?.faultClass;
+    if (!cls) continue;
+    if (r.verdict !== 'killed' && r.verdict !== 'survived') continue;
+    const e = (by[cls] ??= { survived: 0, n: 0 });
+    e.n += 1;
+    if (r.verdict === 'survived') e.survived += 1;
+  }
+  return by;
+}
+
+/** Merge tallies from several documents. Counts add; nothing is averaged twice. */
+export function mergeTallies(tallies) {
+  const by = {};
+  for (const t of tallies) {
+    for (const [cls, e] of Object.entries(t)) {
+      const m = (by[cls] ??= { survived: 0, n: 0 });
+      m.survived += e.survived;
+      m.n += e.n;
+    }
+  }
+  return by;
+}
+
+/**
+ * The productivity table to rank with: this project's own observations, with
+ * the shipped measurement as the prior they are shrunk toward.
+ *
+ * The shipped numbers become pseudo-counts rather than a competing estimate —
+ * `n` of them, so a class measured on twelve faults elsewhere carries the
+ * weight of twelve observations here and no more. A project with its own
+ * hundred records therefore overrides the shipping default; a project with
+ * three nudges it.
+ *
+ * `shipped` is injectable so the combination can be tested without depending
+ * on whatever the current measurement happens to be.
+ */
+export function combinedProductivity(local, shipped = MEASURED_PRODUCTIVITY) {
+  const out = {};
+  for (const cls of new Set([...Object.keys(shipped), ...Object.keys(local)])) {
+    const s = shipped[cls];
+    const l = local[cls];
+    const priorSurvived = s ? s.p * s.n : 0;
+    const priorN = s ? s.n : 0;
+    const n = priorN + (l?.n ?? 0);
+    if (n === 0) continue;
+    const survived = priorSurvived + (l?.survived ?? 0);
+    out[cls] = { p: survived / n, n, observed: l?.n ?? 0 };
+  }
+  return out;
+}
+
+/** Read whichever evidence documents this project has. Missing or malformed ones are skipped, never guessed at. */
+export function readEvidence(projectDir, paths = EVIDENCE_PATHS) {
+  const docs = [];
+  for (const rel of paths) {
+    const p = join(projectDir, rel);
+    if (!existsSync(p)) continue;
+    try {
+      docs.push({ path: rel, doc: JSON.parse(readFileSync(p, 'utf8')) });
+    } catch {
+      // A document this tool cannot parse is not evidence of anything. It is
+      // skipped rather than defaulted, because a ranking built on a guess
+      // about a corrupt file is worse than one built on the shipped prior.
+    }
+  }
+  return docs;
+}
+
+/**
+ * The learned table plus what it was learned from, so a report can say whether
+ * an ordering came from this project or from the shipping default. An ordering
+ * nobody can trace is a number nobody should trust.
+ */
+export function learnedProductivity(projectDir, { paths, shipped } = {}) {
+  const docs = readEvidence(projectDir, paths);
+  const local = mergeTallies(docs.map((d) => tallyEvidence(d.doc)));
+  const observed = Object.values(local).reduce((a, e) => a + e.n, 0);
+  return {
+    table: combinedProductivity(local, shipped),
+    sources: docs.map((d) => d.path),
+    observed,
+    classes: Object.keys(local).sort(),
+  };
+}
+
+/** One line for a report: where the ordering came from. */
+export function renderLearned(learned) {
+  if (learned.observed === 0) return 'ordering: the shipped productivity prior — this project has no probed evidence yet.';
+  return `ordering: ${learned.observed} probed fault${learned.observed === 1 ? '' : 's'} of this project's own, across ${learned.classes.length} class${learned.classes.length === 1 ? '' : 'es'} (${learned.sources.join(', ')}), shrunk toward the shipped prior.`;
+}

package/src/supply/persistence.mjs

@@ -171,3 +171,56 @@ 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.`;
 }
+
+/**
+ * What this claim's defenders are CAPABLE of proving about a write.
+ *
+ * The read-back question — "did the row actually land?" — cannot be answered by
+ * a test that replaced the database with a mock. Such a test can prove the call
+ * shape and nothing beyond it: the `where` may match no rows, the transaction
+ * may roll back, a constraint may reject the write, and every one of those
+ * passes against a mock that recorded the arguments and returned a plausible
+ * object.
+ *
+ * So rather than pretend to measure persistence, this states the LIMIT. It is
+ * the same discipline as `nocover` — which says "no test imports this" instead
+ * of guessing — one level finer: these tests exist, they run, and there is a
+ * class of failure they structurally cannot see.
+ *
+ *   `mocked`   every defender replaces the persistence layer. Call shape only.
+ *   `unmocked` at least one does not, so a real write is at least possible.
+ *              NOT a promise that one happens: a test may simply never reach
+ *              the database. Possible is the honest word.
+ *   `none`     no defender at all; `nocover` already covers this.
+ *
+ * Measured on a real AI-authored application: of 37 files that write to
+ * storage, 32 were defended only by mocking tests, 4 had no defender, and 1
+ * had an unmocked defender — a mailer, not a database write. Nothing in that
+ * suite could prove any save persisted.
+ */
+export function persistenceProvability(projectDir, defenders) {
+  if (!defenders || defenders.length === 0) return { class: 'none', mocking: [], unmocked: [] };
+  const mocking = [];
+  const unmocked = [];
+  for (const d of defenders) (analyzePersistence(projectDir, d) ? mocking : unmocked).push(d);
+  return { class: unmocked.length ? 'unmocked' : 'mocked', mocking, unmocked };
+}
+
+/**
+ * The provability of a whole surface, as counts. The headline a save-path
+ * report opens with, because "how many of these could be proven at all" is a
+ * different question from "how many were probed" and a far more alarming one.
+ */
+export function provabilitySummary(projectDir, targets, defendersOf) {
+  const counts = { mocked: 0, unmocked: 0, none: 0 };
+  for (const file of targets) {
+    let defenders = [];
+    try {
+      defenders = defendersOf(file);
+    } catch {
+      defenders = [];
+    }
+    counts[persistenceProvability(projectDir, defenders).class] += 1;
+  }
+  return counts;
+}

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');
+}