testguard-cli 0.6.0 → 0.8.0

package/src/replay/replay.mjs

@@ -6,11 +6,13 @@ 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';
+import { wilsonInterval, roundTo } from '../../spec/lib/wilson.mjs';
 
 const TEST_RE = /(^|\/)(__tests__|tests?)\//;
-const IS_TEST = (f) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(f) || TEST_RE.test(f);
-const SOURCE_EXT = /\.[cm]?[jt]sx?$/;
+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.
@@ -246,35 +248,50 @@ export function classifyReplay(runs) {
   return { verdict: 'flaky', reason: 'runs-disagreed' };
 }
 
-/** Wilson score interval: the reason a label carries n rather than a vibe. */
+/**
+ * Wilson score interval at 4 dp — the reason a label carries n rather than a
+ * vibe. Computed by the spec's single implementation, which the validator
+ * recomputes with: an emitter and a validator with separate arithmetic can
+ * drift, and did (see `spec/lib/wilson.mjs`).
+ */
 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)] };
+  if (n === 0) return { p: null, ci: [0, 1] };
+  const [lo, hi] = wilsonInterval(positives, n, z);
+  return { p: roundTo(positives / n, 4), ci: [roundTo(lo, 4), roundTo(hi, 4)] };
 }
 
+/**
+ * Replay verdicts that are measurements of the suite. `caught` is a hit.
+ * `blind` is a miss. `nocover` is also a miss — the worst kind, no test even
+ * imported the broken file — and it counts as one: excluding it would score a
+ * project with no tests for a subsystem BETTER than one with weak tests,
+ * because its worst outcomes would leave the denominator before the ratio is
+ * taken. Stryker and PIT count no-coverage mutants against the headline score
+ * for the same reason. `flaky` and `unverifiable` are failed measurements
+ * and enter neither side.
+ */
+export const MEASURED_VERDICTS = Object.freeze(['caught', 'blind', 'nocover']);
+
 /**
  * Calibration from a replay document: per fault class, the share of real
- * escaped bugs of that shape the suite did NOT catch.
+ * escaped bugs of that shape the suite failed to 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.
+ * `p` is P(the suite misses it | a bug of this class escapes) — a miss rate,
+ * so a HIGH number is bad. It is the number that turns an uninterpretable
+ * mutation score into a statement with a sample size. `positives` counts the
+ * misses; see MEASURED_VERDICTS for which verdicts are measurements at all
+ * and why `nocover` is a miss rather than an exclusion.
  */
 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;
+    if (!MEASURED_VERDICTS.includes(r.verdict)) continue;
     const key = r.faultClass ?? 'other';
-    buckets[key] ??= { n: 0, positives: 0 };
+    buckets[key] ??= { n: 0, positives: 0, breakdown: {} };
     buckets[key].n += 1;
-    if (r.verdict === 'blind') buckets[key].positives += 1;
+    buckets[key].breakdown[r.verdict] = (buckets[key].breakdown[r.verdict] ?? 0) + 1;
+    // Anything measured that was not caught is a miss — blind and nocover alike.
+    if (r.verdict !== 'caught') buckets[key].positives += 1;
   }
   for (const [k, b] of Object.entries(buckets)) buckets[k] = { ...b, ...wilson(b.positives, b.n) };
   return {
@@ -283,8 +300,18 @@ export function calibrationFrom(replayDoc, { confidence = 0.95, computedAt = new
     computedAt,
     method: 'wilson',
     confidence,
+    // What p is the probability of. Without it the document is unattributed
+    // and a consumer may quote nothing from it — see GATE-SEMANTICS.
+    measures: 'escape-missed',
     bucketBy: 'faultClass',
-    source: { kind: 'bug-replay', ref: replayDoc.run.range },
+    source: {
+      kind: 'bug-replay',
+      ref: replayDoc.run.range,
+      // The ground truth is this repository's own history, which `ref` names,
+      // so there is no external corpus to list. The caveat is the sentence a
+      // consumer shows beside any number it quotes from here.
+      caveat: 'measured on this repository\'s own fix history: every replayed bug is one that escaped, so a first run is expected to be high — the number to move is this one, over time',
+    },
     buckets,
   };
 }
@@ -302,8 +329,9 @@ export function renderReplay(doc) {
   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)}%.`);
+  const measurable = MEASURED_VERDICTS.reduce((s, v) => s + (by[v] ?? 0), 0);
+  const missed = measurable - (by.caught ?? 0);
+  if (measurable) lines.push(`${missed} of ${measurable} measurable bugs were invisible to the suite (${by.blind ?? 0} blind, ${by.nocover ?? 0} with no test at all) — the escaped-bug miss rate is ${((missed / 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.python.mjs

@@ -0,0 +1,209 @@
+/**
+ * Mechanical fault producers for Python. Deterministic, line-oriented, no AST,
+ * no LLM — the same contract as `producers.mjs`, expressed in the syntax the
+ * file is actually written in.
+ *
+ * The fault classes are the ones the spec already closes over; none is new.
+ * The two JSX shapes (`element-removed`, `handler-dropped`) have no Python
+ * meaning and are absent rather than faked.
+ *
+ * One deliberate difference from JavaScript: a statement is removed by
+ * replacing it with `pass`, not by deleting the line. A block whose only
+ * statement is deleted is an IndentationError in Python, and a fault that
+ * cannot compile is a `fault-invalid` verdict — a wasted probe run that says
+ * nothing about the tests. `pass` removes the behaviour and always parses.
+ */
+
+const COMMENT = /^\s*#/;
+
+// `if <cond>:` and `elif <cond>:`, with an optional same-line body.
+const IF_LINE = /^(\s*)(el)?if\s+(.+?)\s*:\s*(\S.*)?$/;
+const GUARD_BODY = /\braise\b|\breturn\b|\babort\b|\bsys\.exit\b|\bFalse\b|\bNone\b|\bHTTPException\b|\b4\d\d\b/;
+const RETURN_CHECK = /^(\s*)return\s+(.+?)\s*$/;
+const CHECK_EXPR = /(==|!=|\bin\b|\bis\b|\bnot\b|\band\b|\bor\b|\.startswith\(|\.endswith\(|\.match\(|\.search\(|\.fullmatch\(|isinstance\(|\.issubset\(|>=|<=|>|<)/;
+const CHECK_CALL = /^\s*(?:await\s+)?(?:[\w.]+\.)?(verify|validate|assert|check|require|ensure|authoriz|authentic|rate_limit|throttle|enforce|guard|sanitiz|escape|audit)\w*\s*\(.*\)\s*$/i;
+const MUTATION = /^\s*(?!(?:return|if|elif|else|for|while|with|try|except|finally|raise|assert|import|from|def|class|yield|pass|global|nonlocal)\b)[\w.\[\]'"]+\s*(=|\+=|-=|\|=|&=)\s*(?!=)\S.*$/;
+
+const FLAG_TRUE = /\b(verify|secure|httponly|check_hostname|require_tls|validate_certs|strict|signed|use_tls|ssl)\s*=\s*True\b/i;
+const SAME_SITE = /\b(samesite)\s*=\s*(['"])(strict|lax)\2/i;
+const COST_NUM = /\b(\w*(?:cost|rounds|iterations|work_factor)\w*)\s*=\s*(\d+)\b/i;
+const WINDOW_NUM = /\b(\w*(?:ttl|expir|tolerance|window|max_age|maxage|timeout|limit|attempts|length|min_length|clock_skew|skew|leeway)\w*)\s*=\s*(\d+)\b/i;
+
+const DEF_LINE = /^(\s*)(?:async\s+)?def\s+([\w]+)\s*\(/;
+// A definition is not a call site and not a statement: `def f(x)` must never
+// be read as `f(x)` with a swappable argument.
+const DEFINITION = /^\s*(?:async\s+)?(?:def|class)\b/;
+
+/**
+ * Does this line leave a bracket open, or continue onto the next?
+ *
+ * `COLOURS = {` is an assignment by every regex here, but replacing it with
+ * `pass` orphans the lines below it and the file stops parsing. Python has no
+ * statement terminator to lean on the way the JavaScript producers lean on
+ * `;`, so the balance is counted instead. A fault that cannot compile is a
+ * `fault-invalid` verdict: a probe run spent saying nothing about the tests.
+ */
+function isIncomplete(line) {
+  const code = line.replace(/#.*$/, '');
+  if (/\\\s*$/.test(code)) return true;
+  let depth = 0;
+  let quote = null;
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+  }
+  return depth > 0;
+}
+
+/** The function a `def` line opens, or null. */
+export function functionHead(line) {
+  const m = DEF_LINE.exec(line);
+  return m ? m[2] : null;
+}
+
+/** The indentation of a line, in characters. Blank lines have none. */
+export const indentOf = (line) => (line.trim() ? line.length - line.trimStart().length : null);
+
+/** Parameter names of a `def` line, without `self`/`cls`, defaults or annotations. */
+export function functionParams(line) {
+  const m = /^\s*(?:async\s+)?def\s+\w+\s*\(([^)]*)\)/.exec(line);
+  if (!m) return [];
+  return m[1]
+    .split(',')
+    .map((p) => p.trim().replace(/^[*]+/, '').split(/[:=]/)[0].trim())
+    .filter((p) => /^\w+$/.test(p) && p !== 'self' && p !== 'cls');
+}
+
+export const isComment = (line) => COMMENT.test(line);
+
+/** Does this `if` guard something — does its body reject, raise or return? */
+function isGuard(sameLineBody, lines, i) {
+  if (sameLineBody) return GUARD_BODY.test(sameLineBody);
+  const next = lines[i + 1] ?? '';
+  return GUARD_BODY.test(next);
+}
+
+// ── field-dropped ─────────────────────────────────────────────────────────
+// A dict literal counts as a payload when its opening line says so: it is
+// returned, assigned to a payload-ish name, or passed to a persistence or
+// transport call. A TypedDict or a class body is never a payload — dropping a
+// key there changes a type, not a behaviour.
+const PAYLOAD_OPENER = /(\breturn\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|claims|headers|context)\w*\s*=\s*\{\s*$|\.(?:save|update|put|patch|post|send|write|insert|upsert|create|set|publish|emit|dispatch|persist|store|log|audit|record|track|notify|write_audit)\w*\s*\(\s*(?:[^,{]*,\s*)*\{\s*$)/i;
+const DICT_ENTRY = /^(\s*)(['"])([\w.-]+)\2\s*:\s*(.+?),\s*$/;
+const ALLOWLIST_OPENER = /\b\w*(?:fields|keys|allowed|writable|columns|attributes|props|allowlist|whitelist|editable|mutable|updatable|permitted|required|scopes|roles)\w*\s*=\s*[\[({]\s*$/i;
+const STRING_ENTRY = /^\s*(['"])[^'"]+\1\s*,\s*$/;
+
+function fieldDropProposals(lines, i) {
+  const line = lines[i];
+  const entry = DICT_ENTRY.exec(line);
+  const isStringEntry = STRING_ENTRY.test(line);
+  if (!entry && !isStringEntry) return [];
+  const lineIndent = indentOf(line);
+  for (let j = i - 1; j >= 0 && j >= i - 40; j--) {
+    const opener = lines[j];
+    if (!opener.trim() || COMMENT.test(opener)) continue;
+    const openerIndent = indentOf(opener);
+    // The first line above that is less indented opens the literal this entry
+    // belongs to. Anything at the same indentation is a sibling entry.
+    if (openerIndent !== null && lineIndent !== null && openerIndent < lineIndent) {
+      if (entry && PAYLOAD_OPENER.test(opener)) {
+        return [{ faultClass: 'field-dropped', description: `Field dropped: \`${entry[3]}\` no longer appears in the object built at line ${j + 1}.`, replace: '' }];
+      }
+      if (isStringEntry && ALLOWLIST_OPENER.test(opener)) {
+        return [{ faultClass: 'field-dropped', description: `Entry removed from the list at line ${j + 1}: \`${line.trim().replace(/,$/, '')}\`.`, replace: '' }];
+      }
+      return [];
+    }
+  }
+  return [];
+}
+
+// ── argument-swapped ──────────────────────────────────────────────────────
+// A call is kept and one parameter-derived argument is swapped for a trivial
+// value, so the call still happens and still proves nothing.
+const CALL_WITH_ARGS = /\b([\w.]+)\s*\(([^()]*)\)/g;
+
+function argumentSwapProposals(lines, i, params) {
+  const line = lines[i];
+  if (!params.size || COMMENT.test(line)) return [];
+  const out = [];
+  for (const m of line.matchAll(CALL_WITH_ARGS)) {
+    const args = m[2];
+    if (!args.trim()) continue;
+    const parts = args.split(',').map((a) => a.trim());
+    for (let n = 0; n < parts.length; n++) {
+      const arg = parts[n];
+      const named = /^(\w+)\s*=\s*(\w+)$/.exec(arg);
+      const bare = /^\w+$/.test(arg) ? arg : null;
+      const value = named ? named[2] : bare;
+      if (!value || !params.has(value)) continue;
+      const trivial = named ? `${named[1]}=None` : 'None';
+      const swapped = [...parts.slice(0, n), trivial, ...parts.slice(n + 1)].join(', ');
+      out.push({
+        faultClass: 'argument-swapped',
+        description: `Call kept, argument neutralised: \`${m[1]}(…)\` receives ${trivial} in place of \`${arg}\`.`,
+        replace: line.replace(m[0], `${m[1]}(${swapped})`),
+      });
+      break; // one proposal per call is enough for a human to judge
+    }
+  }
+  return out;
+}
+
+/**
+ * Every fault this line supports. `ctx.params` is the enclosing function's
+ * parameter names; `ctx.fieldDrops` disables payload shapes in files where a
+ * dict literal is data rather than something the product sends.
+ */
+export function proposalsForLine(lines, i, ctx = {}) {
+  const out = [];
+  const line = lines[i];
+  if (!line.trim() || COMMENT.test(line) || DEFINITION.test(line)) return out;
+  const params = ctx.params ?? new Set();
+  const indent = ' '.repeat(indentOf(line) ?? 0);
+
+  const ifm = IF_LINE.exec(line);
+  if (ifm && isGuard(ifm[4], lines, i)) {
+    if (ifm[4]) {
+      // `if not allowed: raise …` — the whole guard is this one line.
+      out.push({ faultClass: 'statement-deleted', description: `Guard removed: \`${line.trim()}\` no longer runs.`, replace: `${indent}pass` });
+    } else {
+      out.push({ faultClass: 'condition-forced', description: `Guard never triggers: \`${ifm[2] ?? ''}if ${ifm[3].trim()}\` becomes \`${ifm[2] ?? ''}if False\`.`, replace: `${ifm[1]}${ifm[2] ?? ''}if False:` });
+    }
+    return out; // an `if` line is not also a mutation, a return or a call
+  }
+
+  const rm = RETURN_CHECK.exec(line);
+  if (rm && CHECK_EXPR.test(rm[2]) && !/^(await|yield)\b/.test(rm[2])) {
+    out.push({ faultClass: 'return-altered', description: `Check always passes: \`return ${rm[2]}\` becomes \`return True\`.`, replace: `${rm[1]}return True` });
+  }
+
+  const complete = !isIncomplete(line);
+  if (complete && CHECK_CALL.test(line)) {
+    out.push({ faultClass: 'call-removed', description: `Check call removed: \`${line.trim()}\` no longer runs.`, replace: `${indent}pass` });
+  } else if (complete && MUTATION.test(line)) {
+    out.push({ faultClass: 'statement-deleted', description: `State change removed: \`${line.trim()}\` no longer runs.`, replace: `${indent}pass` });
+  }
+
+  let m;
+  if ((m = FLAG_TRUE.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Security flag flipped: \`${m[1]}=True\` becomes \`${m[1]}=False\`.`, replace: line.replace(m[0], `${m[1]}=False`) });
+  }
+  if ((m = SAME_SITE.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `samesite weakened: \`${m[3]}\` becomes \`none\`.`, replace: line.replace(m[0], `${m[1]}=${m[2]}none${m[2]}`) });
+  }
+  if ((m = COST_NUM.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Work factor collapsed: \`${m[1]}\` ${m[2]} becomes 1.`, replace: line.replace(m[0], `${m[1]}=1`) });
+  } else if ((m = WINDOW_NUM.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Window widened ×1000: \`${m[1]}\` ${m[2]} becomes ${Number(m[2]) * 1000}.`, replace: line.replace(m[0], `${m[1]}=${Number(m[2]) * 1000}`) });
+  }
+
+  if (ctx.fieldDrops !== false) out.push(...fieldDropProposals(lines, i));
+  out.push(...argumentSwapProposals(lines, i, params));
+  return out;
+}

package/src/scaffold/scaffold.mjs

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { basename, extname, join } from 'node:path';
 import { proposalsForLine, functionHead, functionParams } from './producers.mjs';
+import * as py from './producers.python.mjs';
 import { locate } from '../probe/inject.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
 import { validate } from '../../spec/lib/validate.mjs';
@@ -9,9 +10,91 @@ const ANNOTATION = /@claim\s+([A-Za-z0-9]+(?:[._]?[A-Za-z0-9]+)*-[A-Za-z0-9._-]*
 // field-dropped is never proposed inside tests, fixtures or migrations: an
 // object literal there is data, not a payload the product writes.
 const NO_FIELD_DROPS = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(__tests__|__fixtures__|__mocks__|fixtures|migrations)\//;
+// Python names its tests by file rather than by a dotted suffix, so the JS
+// rule would not recognise one. Kept separate so adding Python cannot quietly
+// change which proposals a JavaScript file gets.
+const NO_FIELD_DROPS_PY = /(^|\/)(test[^/]*\.py|[^/]*_test\.py|conftest\.py)$|(^|\/)(tests?|__fixtures__|fixtures|migrations)\//;
 
 const idPart = (s) => s.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').toUpperCase();
 
+const isPython = (file) => file.endsWith('.py');
+
+/**
+ * JavaScript line scan: enclosing function tracked by brace depth, `@claim`
+ * annotations read from `//` and `/* *\u002f` comments.
+ */
+function scanJs({ source, lines, fieldDrops, keep, anchor }) {
+  const proposals = [];
+  let offset = 0;
+  let fn = null;
+  let fnDepth = 0;
+  let params = new Set();
+  let depth = 0;
+  let pendingAnnotation = null;
+  lines.forEach((line, i) => {
+    const ann = ANNOTATION.exec(line);
+    if (ann && /^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = ann[1];
+
+    const head = functionHead(line);
+    if (head) {
+      fn = head;
+      fnDepth = depth;
+      params = new Set(functionParams(line));
+    }
+
+    for (const p of proposalsForLine(lines, i, { params, fieldDrops })) {
+      const { hits, occurrence } = anchor(line, offset);
+      const fault = { ...p, find: line, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
+      if (keep(fault)) proposals.push(fault); // never propose an anchor that would be unverifiable
+    }
+
+    depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
+    if (fn && depth <= fnDepth && !head) { fn = null; params = new Set(); }
+    if (pendingAnnotation && !ann && !head && line.trim() && !/^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = null;
+    offset += line.length + 1;
+  });
+  return proposals;
+}
+
+/**
+ * Python line scan. Scope is indentation, not braces, and it must be read
+ * BEFORE the line is attributed: a line dedented out of a function belongs to
+ * whatever follows, not to the function that just ended. `@claim` annotations
+ * are read from `#` comments.
+ */
+function scanPython({ source, lines, fieldDrops, keep, anchor }) {
+  const proposals = [];
+  let offset = 0;
+  let fn = null;
+  let fnIndent = 0;
+  let params = new Set();
+  let pendingAnnotation = null;
+  lines.forEach((line, i) => {
+    const indent = py.indentOf(line);
+    if (fn !== null && indent !== null && indent <= fnIndent) { fn = null; params = new Set(); }
+
+    const ann = ANNOTATION.exec(line);
+    if (ann && py.isComment(line)) pendingAnnotation = ann[1];
+
+    const head = py.functionHead(line);
+    if (head) {
+      fn = head;
+      fnIndent = indent ?? 0;
+      params = new Set(py.functionParams(line));
+    }
+
+    for (const p of py.proposalsForLine(lines, i, { params, fieldDrops })) {
+      const { hits, occurrence } = anchor(line, offset);
+      const fault = { ...p, find: line, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
+      if (keep(fault)) proposals.push(fault);
+    }
+
+    if (pendingAnnotation && !ann && !head && line.trim() && !py.isComment(line)) pendingAnnotation = null;
+    offset += line.length + 1;
+  });
+  return proposals;
+}
+
 /** How many times `find` occurs, and which occurrence the line at `offset` is. */
 function anchorFor(source, find, offset) {
   let hits = 0;
@@ -43,38 +126,9 @@ export function scaffoldFile({ projectDir, file, claimId, existingClaims, toolVe
     return groups.get(key);
   };
 
-  let offset = 0;
-  let fn = null;
-  let fnDepth = 0;
-  let params = new Set();
-  const fieldDrops = !NO_FIELD_DROPS.test(file);
-  let depth = 0;
-  let pendingAnnotation = null;
-  const proposals = [];
-  lines.forEach((line, i) => {
-    const ann = ANNOTATION.exec(line);
-    if (ann && /^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = ann[1];
-
-    const head = functionHead(line);
-    if (head) {
-      fn = head;
-      fnDepth = depth;
-      params = new Set(functionParams(line));
-    }
-
-    for (const p of proposalsForLine(lines, i, { params, fieldDrops })) {
-      const find = line;
-      const { hits, occurrence } = anchorFor(source, find, offset);
-      const fault = { ...p, find, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
-      if (locate(source, fault).status !== 'ok') continue; // never propose an anchor that would be unverifiable
-      proposals.push(fault);
-    }
-
-    depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
-    if (fn && depth <= fnDepth && !head) { fn = null; params = new Set(); }
-    if (pendingAnnotation && !ann && !head && line.trim() && !/^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = null;
-    offset += line.length + 1;
-  });
+  const fieldDrops = !(isPython(file) ? NO_FIELD_DROPS_PY : NO_FIELD_DROPS).test(file);
+  const scan = isPython(file) ? scanPython : scanJs;
+  const proposals = scan({ source, lines, fieldDrops, keep: (fault) => locate(source, fault).status === 'ok', anchor: (find, offset) => anchorFor(source, find, offset) });
 
   const existing = new Map((existingClaims?.claims ?? []).map((c) => [c.id, c]));
   const usedIds = new Set();

package/src/util/glob.mjs

@@ -1,7 +1,13 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.testguard']);
+// Dependency and tool directories. The Python entries are not cosmetic: a
+// virtualenv inside the project holds thousands of `test_*.py` files belonging
+// to installed packages, and without skipping it every one of them would be
+// collected as a test file of the project under probe.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.testguard',
+  '__pycache__', '.venv', 'venv', 'site-packages', '.tox', '.nox',
+  '.pytest_cache', '.mypy_cache', '.ruff_cache', '.eggs']);
 
 /** Translate a minimal glob (`**`, `*`, `?`) into an anchored RegExp over posix paths. */
 export function globToRegExp(glob) {