testguard-cli 0.5.0 → 0.7.0

package/src/replay/replay.mjs

@@ -0,0 +1,310 @@
+import { existsSync, rmSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { git, GitError, repoRoot, headSha } from '../git.mjs';
+import { createScratch, PreconditionError } from '../probe/worktree.mjs';
+import { selectRunner, RUNNERS } from '../probe/runners/index.mjs';
+import { parseCommandTemplate } from '../probe/runners/shared.mjs';
+import { fileImports } from '../probe/rank.mjs';
+import { IS_PY_TEST, pyFileImports } from '../probe/pyimports.mjs';
+import { labelDiff } from './label.mjs';
+
+const TEST_RE = /(^|\/)(__tests__|tests?)\//;
+const IS_TEST = (f) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(f) || IS_PY_TEST.test(f) || TEST_RE.test(f);
+const SOURCE_EXT = /\.([cm]?[jt]sx?|py)$/;
+
+/**
+ * Fix commits in a range: those that change source AND a test together.
+ *
+ * That pairing is the signal a human confirmed a defect — someone changed
+ * behaviour and shipped a test for it — which is what makes bug replay ground
+ * truth rather than a synthetic mutant of arguable relevance.
+ */
+export function findFixCommits({ dir, range, projectDir }) {
+  // In a monorepo a fix commit routinely touches several packages. Only the
+  // files under THIS project can be reverted or run here, so scope to them
+  // and drop a commit that has no source-and-test pair inside the project —
+  // otherwise most of the corpus comes back `revert-did-not-apply`, which
+  // looks like a tooling failure and hides the real verdicts.
+  const scope = projectDir && projectDir !== dir ? relative(dir, projectDir).split('\\').join('/') : '';
+  const inScope = (f) => !scope || f === scope || f.startsWith(`${scope}/`);
+  let log;
+  try {
+    log = git(['log', '--no-merges', '--format=%H%x1f%s', range], dir);
+  } catch (e) {
+    if (e instanceof GitError) throw new PreconditionError(`cannot read the range ${range}: ${e.message.split('\n')[0]}`);
+    throw e;
+  }
+  const out = [];
+  for (const line of log.split('\n').filter(Boolean)) {
+    const [commit, subject] = line.split('\x1f');
+    const files = git(['show', '--name-only', '--format=', '--diff-filter=d', commit], dir).split('\n').filter(Boolean);
+    const source = files.filter((f) => inScope(f) && SOURCE_EXT.test(f) && !IS_TEST(f));
+    const tests = files.filter((f) => inScope(f) && IS_TEST(f));
+    if (source.length === 0 || tests.length === 0) continue;
+    out.push({ commit, subject, source, tests });
+  }
+  return out;
+}
+
+/**
+ * De-duplicate by patch-id. A dual-branch topology carries the same fix under
+ * two or three shas; counting it twice corrupts the corpus the calibration is
+ * computed from, and it was a real defect in the first harness.
+ */
+export function dedupeByPatch({ dir, commits }) {
+  const seen = new Map();
+  const unique = [];
+  for (const c of commits) {
+    // `git patch-id` reads the patch on stdin, which git() does not do.
+    const r = spawnSync('git', ['patch-id', '--stable'], { cwd: dir, encoding: 'utf8', input: (() => { try { return git(['show', c.commit], dir); } catch { return ''; } })() });
+    const patchId = r.status === 0 ? (r.stdout.trim().split(' ')[0] || null) : null;
+    const id = patchId || c.commit;
+    if (seen.has(id)) continue;
+    seen.set(id, c.commit);
+    unique.push({ ...c, patchId: id });
+  }
+  return { unique, duplicates: commits.length - unique.length };
+}
+
+/**
+ * Would the suite as it stood have caught this bug?
+ *
+ * For each fix: check out the fix, revert ONLY its source files to the
+ * parent, delete the test files the fix shipped, and run what remains. A
+ * fix's own test proves nothing about what the suite knew before it.
+ *
+ * Runs in a scratch worktree; the caller's tree is never touched.
+ */
+export async function replay({
+  projectDir,
+  range,
+  confirmRuns = 3,
+  budgetMs = 120_000,
+  runnerCommand,
+  runnerName = 'auto',
+  nodeModules,
+  scratchBase,
+  limit,
+  toolVersion = '0.0.0',
+  onProgress = () => {},
+  onStage = () => {},
+}) {
+  projectDir = realpathSync(resolve(projectDir));
+  const root = repoRoot(projectDir);
+  if (!headSha(root)) throw new PreconditionError('repository has no commits; there is nothing to replay');
+
+  const found = findFixCommits({ dir: root, range, projectDir });
+  const { unique, duplicates } = dedupeByPatch({ dir: root, commits: found });
+  const selected = limit ? unique.slice(0, limit) : unique;
+  if (selected.length === 0) {
+    throw new PreconditionError(`no fix commits in ${range}: a fix commit changes source and a test together. Widen the range, or this history has none.`);
+  }
+
+  const startedAt = new Date().toISOString();
+  const records = [];
+  let runnerUsed = RUNNERS[runnerName === 'auto' ? 'vitest' : runnerName];
+  let runnerVersion;
+
+  for (const [i, fix] of selected.entries()) {
+    onStage({ commit: fix.commit, i: i + 1, n: selected.length, stage: 'prepare' });
+    const iso = createScratch({ repoRoot: root, projectDir, ref: fix.commit, scratchBase, nodeModules });
+    try {
+      const commandTemplate = runnerCommand ? parseCommandTemplate(runnerCommand) : undefined;
+      if (!commandTemplate) {
+        const sel = await selectRunner({ projectDir: iso.projectDir, name: runnerName });
+        if (sel.error) throw new PreconditionError(`test runner is not resolvable in the scratch worktree (${sel.error}). Pass --node-modules <path>.`);
+        runnerUsed = sel.runner;
+        runnerVersion = sel.version;
+      }
+      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandTemplate, runner: runnerUsed, onStage, index: i + 1, total: selected.length });
+      records.push(record);
+      onProgress(record);
+    } finally {
+      iso.cleanup();
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    tool: { name: 'testguard', version: toolVersion },
+    run: {
+      id: `replay-${startedAt.replace(/[-:.]/g, '').slice(0, 15)}`,
+      startedAt,
+      finishedAt: new Date().toISOString(),
+      range,
+      runner: { name: runnerUsed.name, ...(runnerVersion ? { version: runnerVersion } : {}) },
+      confirmRuns,
+      candidates: found.length,
+      duplicates,
+    },
+    records,
+  };
+}
+
+async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandTemplate, runner, onStage, index, total }) {
+  // git reports paths from the REPOSITORY root; the runner and every file
+  // operation here work inside the scratch worktree, relative to the PROJECT
+  // directory. Map once, and refuse anything that would land outside the
+  // worktree: this function deletes files, and a wrong mapping silently
+  // deleted them from the real repository.
+  const relProject = relative(root, projectDir).split('\\').join('/');
+  const rel = (repoPath) => (relProject && repoPath.startsWith(`${relProject}/`) ? repoPath.slice(relProject.length + 1) : repoPath);
+  const isoRoot = realpathSync(iso.projectDir);
+  const inside = (p) => {
+    const abs = realpathSync(dirname(p)) + '/' + basename(p);
+    if (!abs.startsWith(isoRoot + '/')) throw new PreconditionError(`refusing to touch ${p}: outside the scratch worktree ${isoRoot}`);
+    return abs;
+  };
+  const base = { commit: fix.commit, patchId: fix.patchId, subject: fix.subject, source: fix.source, removedTests: fix.tests };
+
+  // The label comes from the fix's SOURCE diff only: a test diff describes
+  // what was asserted, not what was broken.
+  let faultClass;
+  try {
+    const diff = git(['show', '--format=', '--unified=0', fix.commit, '--', ...fix.source], root);
+    faultClass = labelDiff(diff).faultClass;
+  } catch {
+    faultClass = 'other';
+  }
+
+  // Revert only the source, to the fix's parent. A fix routinely ADDS a file
+  // as well as changing others, and a file that did not exist at the parent
+  // cannot be checked out of it — reverting such a file means removing it.
+  // Getting this wrong turns half a real corpus into `revert-did-not-apply`,
+  // which reads as a tooling failure and hides every real verdict behind it.
+  const existedBefore = [];
+  const addedByTheFix = [];
+  for (const f of fix.source) {
+    try {
+      git(['cat-file', '-e', `${fix.commit}^:${f}`], iso.projectDir);
+      existedBefore.push(f);
+    } catch {
+      addedByTheFix.push(f);
+    }
+  }
+  // Every source file is new: this commit ADDS behaviour rather than
+  // correcting it. There is no earlier version to have been blind to, so it
+  // is not a bug the suite could have caught, and it must not enter a
+  // calibration as though it were.
+  if (existedBefore.length === 0) {
+    return { ...base, faultClass, verdict: 'unverifiable', reason: 'no-prior-version', runs: [{ outcome: 'error', durationMs: 0 }] };
+  }
+  try {
+    if (existedBefore.length) git(['checkout', `${fix.commit}^`, '--', ...existedBefore.map(rel)], iso.projectDir);
+    for (const f of addedByTheFix) {
+      const abs = join(iso.projectDir, rel(f));
+      if (existsSync(abs)) rmSync(inside(abs), { force: true });
+    }
+  } catch (e) {
+    return { ...base, faultClass, verdict: 'unverifiable', reason: 'revert-did-not-apply', runs: [{ outcome: 'error', durationMs: 0 }] };
+  }
+
+  // A fix's own test proves nothing about what the suite knew before it.
+  for (const t of fix.tests) {
+    const inWorktree = join(iso.projectDir, rel(t));
+    if (existsSync(inWorktree)) rmSync(inside(inWorktree), { force: true });
+  }
+
+  // What remains that could possibly notice: the test files importing any
+  // reverted source file. `nocover` means nothing does — worse than blind,
+  // and a coverage report shows it as a red line you can ignore.
+  const all = runner.tests(iso.projectDir).filter((t) => !fix.tests.some((ft) => rel(ft) === t));
+  const related = all.filter((t) => fix.source.some((sf) => fileImports(iso.projectDir, join(iso.projectDir, t), rel(sf))));
+  if (related.length === 0) {
+    return { ...base, faultClass, verdict: 'nocover', reason: 'no-test-imports-the-reverted-source', ranTests: 0, runs: [{ outcome: 'error', durationMs: 0 }] };
+  }
+
+  const runs = [];
+  for (let i = 0; i < confirmRuns; i++) {
+    onStage({ commit: fix.commit, i: index, n: total, stage: `run ${i + 1}/${confirmRuns}` });
+    const res = await runner.run({ projectDir: iso.projectDir, files: related, budgetMs, commandTemplate });
+    runs.push(res.run);
+    // A suite that cannot load says nothing about the bug.
+    if (res.run.outcome === 'error') return { ...base, faultClass, verdict: 'unverifiable', reason: 'suite-failed-to-load', ranTests: related.length, runs };
+  }
+
+  return { ...base, faultClass, ...classifyReplay(runs), ranTests: related.length, runs };
+}
+
+/**
+ * Runs in, verdict out. Pure, so every branch is unit-testable — the same
+ * discipline as the probe's `classify()`, for the same reason.
+ *
+ * The ordering matters. A flaky failure reads as "the suite detected it", so
+ * flakiness biases this metric OPTIMISTICALLY and hides exactly the blind
+ * spots the replay exists to find: mixed runs are never `caught`.
+ */
+export function classifyReplay(runs) {
+  const isCatch = (r) => r.outcome === 'fail' && (r.assertionFailures ?? 0) > 0;
+  if (runs.length === 0) return { verdict: 'unverifiable', reason: 'no-runs' };
+  if (runs.some((r) => r.outcome === 'error')) return { verdict: 'unverifiable', reason: 'suite-failed-to-load' };
+  if (runs.every(isCatch)) return { verdict: 'caught' };
+  if (runs.every((r) => r.outcome === 'pass')) return { verdict: 'blind' };
+  if (runs.some((r) => r.outcome === 'timeout')) return { verdict: 'unverifiable', reason: 'timed-out' };
+  // A failure that is not an assertion failure is not detection either.
+  if (runs.every((r) => r.outcome === 'fail') && !runs.every(isCatch)) return { verdict: 'unverifiable', reason: 'failed-without-an-assertion' };
+  return { verdict: 'flaky', reason: 'runs-disagreed' };
+}
+
+/** Wilson score interval: the reason a label carries n rather than a vibe. */
+export function wilson(positives, n, z = 1.96) {
+  if (n === 0) return { p: 0, ci: [0, 1] };
+  const p = positives / n;
+  const d = 1 + (z * z) / n;
+  const centre = (p + (z * z) / (2 * n)) / d;
+  const half = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / d;
+  const round = (x) => Number(Math.min(1, Math.max(0, x)).toFixed(4));
+  return { p: Number(p.toFixed(4)), ci: [round(centre - half), round(centre + half)] };
+}
+
+/**
+ * Calibration from a replay document: per fault class, the share of real
+ * escaped bugs of that shape the suite did NOT catch.
+ *
+ * Read it as "when a fault of this class survives, how often does that
+ * correspond to a bug that really escaped" — the number that turns an
+ * uninterpretable mutation score into a statement with a sample size.
+ * `caught` and `blind` are the only outcomes that carry information;
+ * `nocover`, `flaky` and `unverifiable` are excluded from both sides.
+ */
+export function calibrationFrom(replayDoc, { confidence = 0.95, computedAt = new Date().toISOString(), toolVersion } = {}) {
+  const buckets = {};
+  for (const r of replayDoc.records) {
+    if (!['caught', 'blind'].includes(r.verdict)) continue;
+    const key = r.faultClass ?? 'other';
+    buckets[key] ??= { n: 0, positives: 0 };
+    buckets[key].n += 1;
+    if (r.verdict === 'blind') buckets[key].positives += 1;
+  }
+  for (const [k, b] of Object.entries(buckets)) buckets[k] = { ...b, ...wilson(b.positives, b.n) };
+  return {
+    schemaVersion: 1,
+    tool: { name: 'testguard', version: toolVersion ?? replayDoc.tool.version },
+    computedAt,
+    method: 'wilson',
+    confidence,
+    bucketBy: 'faultClass',
+    source: { kind: 'bug-replay', ref: replayDoc.run.range },
+    buckets,
+  };
+}
+
+export function renderReplay(doc) {
+  const by = {};
+  for (const r of doc.records) by[r.verdict] = (by[r.verdict] ?? 0) + 1;
+  const lines = [];
+  for (const r of doc.records) {
+    if (r.verdict === 'caught') continue;
+    lines.push(`${r.verdict.toUpperCase().padEnd(13)} ${r.commit.slice(0, 9)} ${(r.faultClass ?? 'other').padEnd(20)} ${r.ranTests ?? 0} test${r.ranTests === 1 ? '' : 's'} ran  ${r.subject ?? ''}${r.reason ? `  [${r.reason}]` : ''}`);
+  }
+  const order = ['blind', 'nocover', 'flaky', 'unverifiable', 'caught'];
+  lines.push('');
+  lines.push(`${doc.records.length} fix commit${doc.records.length === 1 ? '' : 's'} replayed from ${doc.run.candidates} candidate${doc.run.candidates === 1 ? '' : 's'}` +
+    (doc.run.duplicates ? ` (${doc.run.duplicates} dropped as the same patch)` : '') + ': ' +
+    order.filter((v) => by[v]).map((v) => `${by[v]} ${v}`).join(', ') + '.');
+  const measurable = (by.caught ?? 0) + (by.blind ?? 0);
+  if (measurable) lines.push(`${by.blind ?? 0} of ${measurable} measurable bugs were invisible to the suite — the escaped-bug replay rate is ${(((by.blind ?? 0) / measurable) * 100).toFixed(0)}%.`);
+  lines.push('A bug that reached production is by construction one the suite missed, so a high rate is expected on a first run. The number to move is this one, over time.');
+  return lines.join('\n');
+}

package/src/scaffold/producers.mjs

@@ -1,10 +1,25 @@
 /**
  * Mechanical fault producers. Deterministic, line-oriented, no AST, no LLM.
  *
- * Two independent field reports found that ~80% of hand-written faults are
- * one of these shapes. Each producer looks at one line (plus a little
- * context) and proposes a fault whose `find` is the exact line, so the anchor
- * hits by construction. A human keeps or drops every proposal.
+ * Field reports found that most hand-written faults are one of a few shapes.
+ * Each producer looks at one line (plus a little context) and proposes a
+ * fault whose `find` is the exact line, so the anchor hits by construction.
+ * A human keeps or drops every proposal.
+ *
+ * Shapes:
+ *   condition-forced   `if (<guard>) {` → `if (false) {`
+ *   statement-deleted  a single-line guard or a state change removed
+ *   return-altered     `return <check>;` → `return true;`
+ *   literal-changed    a security flag / window / cost literal weakened
+ *   call-removed       a bare verify/validate/check call removed
+ *   field-dropped      a field removed from a persisted or transmitted object,
+ *                      an allow-list, a schema, or a spread merge (issue #14)
+ *   argument-swapped   a call kept, its parameter-derived argument swapped for
+ *                      a trivial value (issue #22)
+ *   element-removed    a one-line JSX element (self-closing or paired) removed
+ *                      (issue #15)
+ *   handler-dropped    an on<Event>={…} prop removed from a JSX element
+ *                      (issue #15)
  */
 
 const COMMENT = /^\s*(\/\/|\*|\/\*)/;
@@ -26,6 +41,36 @@ const FUNCTION_HEAD = [
 ];
 const NOT_A_FUNCTION = new Set(['if', 'for', 'while', 'switch', 'catch', 'else', 'return', 'function', 'constructor']);
 
+// ── field-dropped ──
+// An object literal counts as a payload when its opening line says so: it is
+// returned, built by an arrow, assigned to a payload-ish name, passed to a
+// persistence/transport call, or is a validation schema. Type-level braces
+// (`interface`, `type X = {`) are never payloads: dropping a key there is a
+// compile error, not a behaviour.
+const PAYLOAD_OPENER = /(\breturn\s*\{\s*$|=>\s*\(?\s*\{\s*$|\b(?:body|payload|input|item|params|data|record|row|attrs|attributes|values|fields|patch|update|updates|changes|doc|document|entity|dto|request|response|options|args|props|config|settings|message|event|entry|audit)\w*\s*[:=]\s*\{\s*$|\.(?:save|update|put|patch|post|send|write|insert|upsert|create|set|publish|emit|dispatch|persist|store|log|fetch|request|audit|record|track|notify)\w*\s*\(\s*(?:[^,{]*,\s*)*\{\s*$|\b(?:z|yup|joi|v|t)\.(?:object|shape|strictObject|looseObject)\s*\(\s*\{\s*$|\.(?:object|shape|extend|merge|pick|omit)\s*\(\s*\{\s*$|\bobject\s*\(\s*\{\s*$)/i;
+const TYPE_OPENER = /\b(?:interface|type|enum|declare)\b/;
+const ALLOWLIST_OPENER = /\b\w*(?:fields|keys|allowed|writable|columns|attributes|props|whitelist|allowlist|editable|mutable|updatable|permitted|selectable|sortable|filterable|required)\w*\b[^[]*\[\s*$/i;
+const PROP_LINE = /^\s*(?:[\w$]+|'[^']*'|"[^"]*"|\[[^\]]+\])\s*:\s*(?!\s*(?:async\s+)?(?:function\b|\([^)]*\)\s*=>|[\w$]+\s*=>))(.+?)(,?)\s*$/;
+const SHORTHAND_LINE = /^\s*[\w$]+\s*,\s*$/;
+const METHOD_LINE = /^\s*(?:async\s+)?(?:get\s+|set\s+)?[\w$]+\s*\([^)]*\)\s*\{\s*$/;
+const SPREAD_LINE = /^\s*\.\.\.[\w$.()]+\s*,?\s*$/;
+const STRING_ENTRY = /^\s*(['"])[^'"]+\1\s*,?\s*$/;
+const INLINE_SPREAD_MERGE = /\{\s*\.\.\.([\w$.()]+)\s*,\s*(?=[^}]*\S)/;
+
+// ── element-removed / handler-dropped (JSX) ──
+// One-line elements only, so the removal is syntactically safe by construction.
+const JSX_SELF_CLOSING = /^\s*<[A-Za-z][\w.-]*\b[^<>]*\/>\s*$/;
+const JSX_PAIRED_LINE = /^\s*<([A-Za-z][\w.-]*)\b[^<>]*>[^<>]*<\/\1>\s*$/;
+const JSX_HANDLER_PROP_LINE = /^\s*on[A-Z]\w*=\{(?:[^{}]|\{[^{}]*\})*\}\s*$/;
+const JSX_INLINE_HANDLER = /\s+on[A-Z]\w*=\{(?:[^{}]|\{[^{}]*\})*\}/;
+
+// ── argument-swapped ──
+// A call whose first argument is derived from a parameter or a request-like
+// value. `callee(` must not be a keyword, a constructor, an import, or a test
+// helper; the argument must not be a literal.
+const CALL_WITH_ARG = /(?<![\w$.])(?<!\bnew\s+)(?!(?:if|for|while|switch|catch|return|function|typeof|await|new|require|import|expect|describe|it|test|vi|jest|console|logger)\b)([\w$]+(?:\.[\w$]+)*)\(\s*((?:[\w$]+(?:\?\.|\.)[\w$?.]+)|(?:[\w$]+\([^()]*\))|(?:[\w$]+))\s*(?=,|\))/g;
+const REQUEST_LIKE = /^(?:req|request|res|ctx|context|event|input|args|params|options|opts|props|state|session|user|payload|body|query|headers|msg|message|job|task)$/;
+
 /** Name of the function whose head is on this line, or null. */
 export function functionHead(line) {
   for (const re of FUNCTION_HEAD) {
@@ -35,17 +80,177 @@ export function functionHead(line) {
   return null;
 }
 
+/**
+ * Parameter names declared on a function-head line: plain, defaulted,
+ * typed, rest, and the leaves of one level of destructuring. Best effort.
+ */
+export function functionParams(line) {
+  const open = line.indexOf('(');
+  const arrow = line.indexOf('=>');
+  if (open === -1 || (arrow !== -1 && arrow < open)) {
+    // `const f = x => …` style: a bare identifier before `=>`
+    const bare = /=\s*(?:async\s+)?([\w$]+)\s*=>/.exec(line);
+    return bare ? [bare[1]] : [];
+  }
+  let depth = 0;
+  let close = -1;
+  for (let i = open; i < line.length; i++) {
+    if (line[i] === '(') depth++;
+    else if (line[i] === ')' && --depth === 0) { close = i; break; }
+  }
+  if (close === -1) return [];
+  const inner = line.slice(open + 1, close);
+  const names = [];
+  for (const raw of inner.split(/,(?![^{[]*[}\]])/)) {
+    let p = raw.trim();
+    if (!p) continue;
+    p = p.replace(/^\.\.\./, '').replace(/\s*=[\s\S]*$/, '').replace(/\s*:[^,{}]*$/, '').replace(/\?$/, '');
+    const destructured = /^[{[]([\s\S]*)[}\]]$/.exec(p);
+    if (destructured) {
+      for (const part of destructured[1].split(',')) {
+        const leaf = part.trim().replace(/^\.\.\./, '').split(/\s*[:=]\s*/).pop().trim();
+        if (/^[\w$]+$/.test(leaf)) names.push(leaf);
+      }
+    } else if (/^[\w$]+$/.test(p)) {
+      names.push(p);
+    }
+  }
+  return names;
+}
+
 function isGuard(cond, lines, i) {
   if (/^\s*!/.test(cond)) return true;
   const tail = lines.slice(i, i + 4).join('\n');
   return GUARD_BODY.test(tail);
 }
 
-/** Proposals for one line. Each: { faultClass, description, replace } where find is the line itself. */
-export function proposalsForLine(lines, i) {
+const openerCache = new WeakMap();
+
+/**
+ * For every line, the innermost bracket left open before that line starts:
+ * `{ line, char }` or null. One forward pass with a stack; strings and
+ * comments are not parsed (deterministic heuristic, like everything here).
+ */
+export function openerIndex(lines) {
+  if (openerCache.has(lines)) return openerCache.get(lines);
+  const out = new Array(lines.length);
+  const stack = [];
+  for (let i = 0; i < lines.length; i++) {
+    out[i] = stack.length ? stack[stack.length - 1] : null;
+    const line = lines[i];
+    if (COMMENT.test(line)) continue;
+    for (const ch of line) {
+      if (ch === '{' || ch === '[' || ch === '(') stack.push({ line: i, char: ch });
+      else if (ch === '}' || ch === ']' || ch === ')') stack.pop();
+    }
+  }
+  openerCache.set(lines, out);
+  return out;
+}
+
+const balanced = (line) => {
+  const n = (re) => (line.match(re) ?? []).length;
+  return n(/\{/g) === n(/\}/g) && n(/\[/g) === n(/\]/g) && n(/\(/g) === n(/\)/g);
+};
+
+/** A line that can be removed on its own: balanced, and either comma-terminated or followed by the closer. */
+function removableAlone(lines, i) {
+  const line = lines[i];
+  if (!balanced(line)) return false;
+  if (/,\s*$/.test(line)) return true;
+  for (let j = i + 1; j < lines.length; j++) {
+    if (!lines[j].trim()) continue;
+    return /^\s*[}\])]/.test(lines[j]);
+  }
+  return false;
+}
+
+function fieldDropProposals(lines, i) {
+  const line = lines[i];
+  const out = [];
+  const opener = openerIndex(lines)[i];
+  const openerLine = opener ? lines[opener.line] : '';
+  const inPayload = opener?.char === '{' && PAYLOAD_OPENER.test(openerLine) && !TYPE_OPENER.test(openerLine);
+  const inAllowList = opener?.char === '[' && ALLOWLIST_OPENER.test(openerLine);
+
+  if (inPayload && !METHOD_LINE.test(line) && removableAlone(lines, i)) {
+    const schema = /\b(?:z|yup|joi|v|t)\.|\.(?:object|shape|extend|merge|pick|omit)\s*\(|\bobject\s*\(/i.test(openerLine);
+    if (SPREAD_LINE.test(line)) {
+      out.push({ faultClass: 'field-dropped', description: `Base object dropped from the merge: \`${line.trim()}\` no longer contributes its fields.`, replace: '' });
+    } else if (PROP_LINE.test(line) || SHORTHAND_LINE.test(line)) {
+      const name = line.trim().replace(/[,:].*$/, '').replace(/^['"[]|['"\]]$/g, '');
+      out.push({ faultClass: 'field-dropped', description: schema ? `Field dropped from the schema: \`${name}\` is no longer validated or serialised.` : `Field dropped: \`${name}\` is no longer written.`, replace: '' });
+    }
+  } else if (inAllowList && STRING_ENTRY.test(line) && removableAlone(lines, i)) {
+    out.push({ faultClass: 'field-dropped', description: `Field dropped from the allow-list: ${line.trim().replace(/,\s*$/, '')} is no longer permitted.`, replace: '' });
+  }
+
+  const merge = INLINE_SPREAD_MERGE.exec(line);
+  if (merge) {
+    out.push({ faultClass: 'field-dropped', description: `Base object dropped from the inline merge: \`...${merge[1]}\` no longer contributes its fields.`, replace: line.replace(merge[0], '{ ') });
+  }
+  return out;
+}
+
+function jsxProposals(lines, i) {
+  const line = lines[i];
+  const out = [];
+  if (JSX_SELF_CLOSING.test(line) || JSX_PAIRED_LINE.test(line)) {
+    const tag = /<([A-Za-z][\w.-]*)/.exec(line)[1];
+    out.push({ faultClass: 'element-removed', description: `Element removed: \`<${tag}>\` is no longer rendered.`, replace: '' });
+  }
+  if (JSX_HANDLER_PROP_LINE.test(line)) {
+    const name = /on[A-Z]\w*/.exec(line)[0];
+    out.push({ faultClass: 'handler-dropped', description: `Handler dropped: \`${name}\` is no longer wired.`, replace: '' });
+  } else {
+    const m = JSX_INLINE_HANDLER.exec(line);
+    if (m && /<[A-Za-z]/.test(line)) {
+      const name = /on[A-Z]\w*/.exec(m[0])[0];
+      out.push({ faultClass: 'handler-dropped', description: `Handler dropped: \`${name}\` is no longer wired.`, replace: line.replace(m[0], '') });
+    }
+  }
+  return out;
+}
+
+function isDerived(arg, params) {
+  const idents = arg.match(/[\w$]+/g) ?? [];
+  if (idents.some((id) => params.has(id))) return true;
+  const head = /^([\w$]+)/.exec(arg)?.[1] ?? '';
+  return REQUEST_LIKE.test(head) || arg === 'this' || /^this[.?]/.test(arg);
+}
+
+function argumentSwapProposals(lines, i, params) {
+  const line = lines[i];
+  const out = [];
+  const head = functionHead(line);
+  const seen = new Set();
+  for (const m of line.matchAll(CALL_WITH_ARG)) {
+    const [whole, callee, arg] = m;
+    if (head && callee.split('.').pop() === head) continue; // the head of a declaration, not a call
+    if (/^(?:'|"|`|\d|true$|false$|null$|undefined$)/.test(arg)) continue;
+    if (!isDerived(arg, params)) continue;
+    if (seen.has(whole)) continue;
+    seen.add(whole);
+    const swap = (value) => line.replace(whole, `${callee}(${value}`);
+    out.push({ faultClass: 'argument-swapped', description: `Argument swapped: \`${callee}(${arg}, …)\` is called with \`undefined\` instead of the derived value.`, replace: swap('undefined') });
+    if (/\(/.test(arg)) out.push({ faultClass: 'argument-swapped', description: `Argument swapped: \`${callee}(${arg}, …)\` is called with an empty object instead of the derived value.`, replace: swap('{}') });
+  }
+  return out;
+}
+
+/**
+ * Proposals for one line. Each: { faultClass, description, replace } where
+ * find is the line itself. `ctx.params` is the enclosing function's parameter
+ * set (for argument-swapped); `ctx.fieldDrops = false` disables the
+ * data/UI shapes — field-dropped, element-removed, handler-dropped — for
+ * test files, fixtures and migrations, where an object or element is data,
+ * not the product's output.
+ */
+export function proposalsForLine(lines, i, ctx = {}) {
   const line = lines[i];
   const out = [];
   if (!line.trim() || COMMENT.test(line)) return out;
+  const params = ctx.params ?? new Set();
 
   const ifm = IF_LINE.exec(line);
   if (ifm && isGuard(ifm[2], lines, i)) {
@@ -81,5 +286,11 @@ export function proposalsForLine(lines, i) {
   } else if ((m = WINDOW_NUM.exec(line))) {
     out.push({ faultClass: 'literal-changed', description: `Window widened ×1000: \`${m[1]}\` ${m[3]} becomes ${Number(m[3]) * 1000}.`, replace: line.replace(m[0], `${m[1]}${m[2] === ':' ? ': ' : ' = '}${Number(m[3]) * 1000}`) });
   }
+
+  if (ctx.fieldDrops !== false) {
+    out.push(...fieldDropProposals(lines, i));
+    out.push(...jsxProposals(lines, i));
+  }
+  out.push(...argumentSwapProposals(lines, i, params));
   return out;
 }