omp-conductor 0.3.25 → 0.4.0

package/src/diff-flags.ts

@@ -0,0 +1,696 @@
+/**
+ * The settlement audit: checking a worker's own account of its work against the
+ * pull request it actually pushed.
+ *
+ * Two lines of the worker report template were taken entirely on faith
+ * (`briefs/worker.md:161-164`):
+ *
+ * ```
+ * gates:   <exact commands run and their results>
+ * changed: <files touched, one line>
+ * ```
+ *
+ * #85 stopped believing the line above them — `state: pushed-green` is now
+ * checked against GitHub by `verifyPushedGreenClaim` rather than believed. This
+ * module does the same job for `changed:`, and for the epic's ranked item 7,
+ * "don't weaken tests you didn't write, checked by diff review", where until now
+ * the reviewer was the worker reviewing itself (#128).
+ *
+ * Everything here is **advisory**. A flag never changes a run's state, never
+ * blocks a merge and never fails a run. The judgement a flag invites — "was
+ * deleting that test correct?" — needs context this code does not have, so the
+ * code's whole job is to put the evidence in front of whoever does.
+ *
+ * That posture fixes the accuracy bar, and it is asymmetric. A missed weakening
+ * costs one unflagged PR that a reviewer might still catch. A false flag costs
+ * attention on a *clean* run, and an audit that cries wolf gets ignored — at
+ * which point it is worth less than nothing, because the fleet believes it is
+ * being checked. So **every heuristic below resolves ambiguity towards
+ * silence**, and each one names the blind spot it accepts to stay quiet.
+ *
+ * Pure by construction: the analyser takes a parsed diff, the report text and
+ * the dispatching issue's text, and returns flags. Fetching the diff is the
+ * tracker's job (`Tracker.prDiff`) — the same split `prStateFrom`/`prState`
+ * already use — so every rule here is pinned by a recorded diff rather than by
+ * a live repository.
+ */
+
+import type { PrDiff, PrDiffFile, SettlementFlag } from "./types.ts";
+
+// ------------------------------------------------------------------ diff parse
+
+const FILE_HEADER = "diff --git ";
+
+/**
+ * Unquote a git path. Paths containing a space, a quote, or a non-ASCII byte are
+ * emitted C-quoted (`"a/my file.ts"`), and only the escapes git actually writes
+ * are undone — an unrecognised escape keeps its backslash rather than being
+ * silently eaten, because a wrong path here is a flag naming a file that does
+ * not exist.
+ */
+function unquote(raw: string): string {
+  if (!raw.startsWith('"') || !raw.endsWith('"') || raw.length < 2) return raw;
+  return raw
+    .slice(1, -1)
+    .replaceAll(/\\([\\"nt])/g, (_, ch: string) =>
+      ch === "n" ? "\n" : ch === "t" ? "\t" : ch,
+    );
+}
+
+/**
+ * One path out of a diff header, or undefined for `/dev/null` (how git spells
+ * "this side has no file").
+ *
+ * `prefixed` is not cosmetic. `---`, `+++` and `diff --git` carry git's `a/`
+ * and `b/` prefixes; `rename from` and `rename to` do not. Stripping two
+ * characters off a rename header turns `a/old.ts` into `old.ts` — a path that
+ * exists nowhere, on a flag that tells a reviewer to go and look at it.
+ */
+function diffPath(raw: string, prefixed: boolean): string | undefined {
+  // Some producers append a tab and a timestamp; git does not, but a diff that
+  // travelled through another tool might.
+  const path = unquote(raw.split("\t")[0]?.trim() ?? "");
+  if (path === "" || path === "/dev/null") return undefined;
+  return prefixed && (path.startsWith("a/") || path.startsWith("b/")) ? path.slice(2) : path;
+}
+
+/**
+ * Both paths off a `diff --git` line. Only a fallback: the `---`/`+++` and
+ * `rename to` lines are unambiguous and are preferred everywhere they exist.
+ * This line is not parseable in general — `diff --git a/x b/y b/z` is genuinely
+ * ambiguous when a path contains ` b/` — so it is used only for the header
+ * shapes that carry nothing else (binary and mode-only changes).
+ */
+function headerPaths(line: string): { a?: string; b?: string } {
+  const rest = line.slice(FILE_HEADER.length);
+  const quoted = /^("(?:[^"\\]|\\.)*") ("(?:[^"\\]|\\.)*")$/.exec(rest);
+  if (quoted?.[1] !== undefined && quoted[2] !== undefined) {
+    return { a: diffPath(quoted[1], true), b: diffPath(quoted[2], true) };
+  }
+  const mid = rest.indexOf(" b/");
+  if (mid < 0) return {};
+  return { a: diffPath(rest.slice(0, mid), true), b: diffPath(rest.slice(mid + 1), true) };
+}
+
+function fileFrom(section: string[]): PrDiffFile | undefined {
+  let status: PrDiffFile["status"] = "modified";
+  let previousPath: string | undefined;
+  let renameTo: string | undefined;
+  let minus: string | undefined;
+  let plus: string | undefined;
+  let hunkAt = -1;
+
+  for (let i = 1; i < section.length; i++) {
+    const line = section[i] ?? "";
+    // Header lines run until the first hunk; everything after is content, and
+    // content can legitimately start with `--- ` or `+++ `.
+    if (line.startsWith("@@")) {
+      hunkAt = i;
+      break;
+    }
+    if (line.startsWith("new file mode")) status = "added";
+    else if (line.startsWith("deleted file mode")) status = "removed";
+    else if (line.startsWith("rename from ")) {
+      previousPath = diffPath(line.slice("rename from ".length), false);
+      status = "renamed";
+    } else if (line.startsWith("rename to ")) {
+      renameTo = diffPath(line.slice("rename to ".length), false);
+      status = "renamed";
+    } else if (line.startsWith("--- ")) minus = diffPath(line.slice(4), true);
+    else if (line.startsWith("+++ ")) plus = diffPath(line.slice(4), true);
+  }
+
+  const header = headerPaths(section[0] ?? "");
+  const path = plus ?? renameTo ?? (status === "removed" ? minus : undefined) ?? header.b ?? header.a;
+  if (path === undefined) return undefined;
+
+  const file: PrDiffFile = { path, status };
+  if (previousPath !== undefined && previousPath !== path) file.previousPath = previousPath;
+  // The trailing newline of the diff itself lands in the last file's section;
+  // it is not part of any hunk and would show up in every fixture comparison.
+  if (hunkAt >= 0) file.hunks = section.slice(hunkAt).join("\n").replace(/\n+$/, "");
+  return file;
+}
+
+/**
+ * Split a unified diff into per-file records.
+ *
+ * Kept here rather than in the GitHub adapter because the format is git's, not
+ * GitHub's: a Gitea or local-file tracker producing the same text gets the same
+ * parser, and the analyser below is pinned by raw diffs a human can read.
+ */
+export function parsePrDiff(raw: string, truncated = false): PrDiff {
+  const files: PrDiffFile[] = [];
+  let section: string[] | undefined;
+  const close = (): void => {
+    if (section === undefined) return;
+    const file = fileFrom(section);
+    if (file !== undefined) files.push(file);
+  };
+  for (const line of raw.split("\n")) {
+    if (line.startsWith(FILE_HEADER)) {
+      close();
+      section = [line];
+      continue;
+    }
+    section?.push(line);
+  }
+  close();
+  return { files, truncated };
+}
+
+/** One added or removed line of a hunk, with the line number of the side it
+ *  came from: the post-image for `+`, the pre-image for `-`. */
+interface ChangedLine {
+  added: boolean;
+  text: string;
+  line: number;
+}
+
+function* changedLines(hunks: string): Generator<ChangedLine> {
+  let oldLine = 0;
+  let newLine = 0;
+  for (const raw of hunks.split("\n")) {
+    const header = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+    if (header !== null) {
+      oldLine = Number(header[1]);
+      newLine = Number(header[2]);
+      continue;
+    }
+    // A blank context line is a single space, but tooling that trims trailing
+    // whitespace turns it into an empty string — treated as context so the
+    // line numbers downstream stay aligned with the file.
+    if (raw === "") {
+      oldLine++;
+      newLine++;
+      continue;
+    }
+    const sign = raw[0];
+    if (sign === "+") {
+      yield { added: true, text: raw.slice(1), line: newLine };
+      newLine++;
+    } else if (sign === "-") {
+      yield { added: false, text: raw.slice(1), line: oldLine };
+      oldLine++;
+    } else if (sign === " ") {
+      oldLine++;
+      newLine++;
+    }
+    // `` and any other marker advances neither side.
+  }
+}
+
+// ------------------------------------------------------------- path vocabulary
+
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+/**
+ * Files whose contents are data the audit must not read as code. A recorded
+ * fixture, a golden file or a snapshot legitimately *contains* the text
+ * `it.skip(` — that is what makes it a fixture — and this module's own test
+ * suite is the first thing that would trip over it.
+ */
+const DATA_DIR = /(?:^|\/)(?:__fixtures__|fixtures|testdata|test-data|__snapshots__|snapshots|golden|recordings|cassettes)\//;
+
+/** Code this repository did not write, so weakening it is not this fleet's
+ *  "tests you didn't write" case — it is a vendored upstream. */
+const VENDORED = /(?:^|\/)(?:node_modules|vendor|third_party|dist|build)\//;
+
+/**
+ * Test files, by the naming conventions of the languages this loop has actually
+ * dispatched work in. Deliberately conservative: a file this misses is a file
+ * the weakening rules stay silent about, which is the safe direction.
+ */
+const TEST_FILE_NAME =
+  /(?:^|\/)(?:test_[^/]+\.py|conftest\.py|[^/]+_test\.(?:py|go|rb|rs|ts|tsx|js|jsx)|[^/]+\.(?:test|spec)\.[cm]?[jt]sx?)$/;
+const TEST_DIR = /(?:^|\/)(?:tests?|__tests__|specs?)\//;
+
+function isTestPath(path: string): boolean {
+  return TEST_FILE_NAME.test(path) || TEST_DIR.test(path);
+}
+
+/**
+ * Lockfiles are derived from a manifest the worker did disclose, and no edit
+ * hides in one. Reconciling them produces an omission flag on most dependency
+ * changes — the single largest source of noise this check could have, bought
+ * for no signal at all.
+ */
+const DERIVED_FILE: Record<string, true> = {
+  "bun.lock": true,
+  "bun.lockb": true,
+  "package-lock.json": true,
+  "pnpm-lock.yaml": true,
+  "yarn.lock": true,
+  "Cargo.lock": true,
+  "poetry.lock": true,
+  "uv.lock": true,
+  "go.sum": true,
+  "Gemfile.lock": true,
+  "composer.lock": true,
+};
+
+// -------------------------------------------------------- `changed:` reconcile
+
+const CHANGED_LINE = /^[ \t>]*changed:[ \t]*(.*)$/im;
+
+/**
+ * A token from `changed:` that is worth holding the PR to. The line is prose
+ * written by a model — `omp/src/foo.ts, omp/src/foo.test.ts (new)` is a normal
+ * shape — so anything without a path separator is commentary unless it ends in
+ * an extension that starts with a letter and is at least two characters. That
+ * last clause is not fussiness: without it `e.g`, `i.e` and `0.3.18` all parse
+ * as filenames, and each one becomes a "claimed a file you never touched" flag
+ * on a report that did nothing wrong.
+ */
+const CLAIMED_PATH = /^(?:[\w.@~+-]+\/)+[\w.@~*+-]*$|^[\w.@~+-]*\.[A-Za-z][A-Za-z0-9]{1,7}$/;
+
+/** Every path-shaped token on the report's `changed:` line. An absent line and
+ *  a line naming nothing are the same answer: nothing was disclosed. */
+export function claimedPaths(report: string): string[] {
+  const line = CHANGED_LINE.exec(report)?.[1] ?? "";
+  const seen = new Set<string>();
+  for (const raw of line.split(/[\s,;]+/)) {
+    const token = raw.replace(/^[`'"([*-]+/, "").replace(/[`'")\].,:;]+$/, "");
+    if (token === "" || token === "none") continue;
+    const normalised = token.replace(/^\.?\//, "");
+    if (!CLAIMED_PATH.test(normalised)) continue;
+    seen.add(normalised);
+  }
+  return [...seen];
+}
+
+/**
+ * Whether one claim covers one path. Every rule here is deliberately generous,
+ * because each one that fails produces an omission flag on an honest report:
+ *
+ * - suffix match, so `foo.test.ts` covers `omp/src/foo.test.ts` and a worker
+ *   that wrote the full path is covered by a claim of either shape;
+ * - directory match, so `omp/src` covers everything under it — a token whose
+ *   last segment has an extension is a filename and never a directory;
+ * - `*` as a within-segment wildcard, because `omp/src/tracker/*` is how the
+ *   issues in this repo themselves name a file set.
+ */
+function covers(claim: string, path: string): boolean {
+  // Callers pass `previousPath ?? ""` for the rename side. Without this guard a
+  // directory-shaped claim like `omp/src/` "covers" the empty string, and every
+  // unmatched claim silently disappears.
+  if (path === "") return false;
+  if (claim === path) return true;
+  if (claim.includes("*")) {
+    const pattern = new RegExp(
+      `^${claim.replaceAll(/[.*+?^${}()|[\]\\]/g, (ch) => (ch === "*" ? "[^/]*" : `\\${ch}`))}$`,
+    );
+    return pattern.test(path) || pattern.test(basename(path));
+  }
+  if (path.endsWith(`/${claim}`) || claim.endsWith(`/${path}`)) return true;
+  const last = claim.slice(claim.lastIndexOf("/") + 1);
+  return !last.includes(".") && path.startsWith(`${claim}/`);
+}
+
+// ------------------------------------------------------ test-weakening lexicon
+
+/**
+ * Strip string literals and the trailing line comment, so a marker that is only
+ * *mentioned* is not read as a marker that was *added*. `it("skip the retry")`
+ * and `# it.skip(...) — see #91` are both silent after this.
+ *
+ * Single-line only, which is the accepted blind spot: a diff shows added lines
+ * without the file around them, so a line inside a multi-line template literal
+ * is indistinguishable from code. {@link DATA_DIR} covers the case that
+ * actually occurs — recorded fixtures — and the anchored patterns below cover
+ * most of the rest.
+ */
+function splitCode(line: string, hashComments: boolean): { code: string; comment: string } {
+  let code = "";
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (quote !== undefined) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = undefined;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      // A placeholder, not nothing: `it.skip("x", fn)` must still parse as a
+      // call, and `describe(name)` must not collapse into `describe()`.
+      code += '""';
+      continue;
+    }
+    if (ch === "/" && line[i + 1] === "/") return { code, comment: line.slice(i + 2) };
+    if (hashComments && ch === "#") return { code, comment: line.slice(i + 1) };
+    code += ch;
+  }
+  return { code, comment: "" };
+}
+
+/** `#` opens a comment here, and `#[ignore]` does not exist. Rust and TypeScript
+ *  are excluded on purpose: `#[ignore]` and `#private` are code. */
+const HASH_COMMENTS = /\.(?:py|rb|sh|bash|yml|yaml|toml|cfg|pl)$/;
+
+/**
+ * A disabled or focused test. Anchored on a runner identifier at the start of
+ * the statement, which is what keeps `iterator.skip(3)` and `{ skip: false }`
+ * out — an unanchored `\.skip\(` flags both.
+ *
+ * The marker must then be *called* (`it.skip(`) or chained into one
+ * (`test.skip.each(`). Accepting a bare `.` after it looked harmless and was
+ * not: `it("x", () => { plan.todo.push(1) })` reads as a todo-marked test.
+ */
+const DISABLED_TEST: readonly RegExp[] = [
+  /^(?:await\s+)?(?:it|test|describe|context|suite|bench)\b.*?\.\s*(?:skip|only|todo|failing)\s*(?:\(|\.\s*(?:each|for)\b)/,
+  /^(?:await\s+)?[xf](?:it|test|describe|context)\s*\(/,
+  /^@(?:pytest\.mark\.(?:skip|skipif|xfail)|unittest\.skip)/,
+  /^#\[ignore\b/,
+  // Go's is a statement anywhere in a line — `if testing.Short() { t.Skip() }`
+  // is the idiomatic form — and the `t.` receiver is specific enough to anchor
+  // on instead.
+  /\bt\.Skip(?:f|Now)?\s*\(/,
+];
+
+/**
+ * An assertion, as a whole statement. Anchored for the same reason as above: a
+ * mid-line `expect` is usually a helper's name or a comment about one.
+ */
+const ASSERTION =
+  /^(?:await\s+)?(?:expect|assert|assert_[a-z_]+|assertEquals?|assertTrue|assertFalse|assertThat|assertRaises|assertRaisesRegex|self\.assert[A-Za-z]*|should|chai\.|t\.(?:Error|Fatal)f?|require\.[A-Z][A-Za-z]*|Expect)\s*[.(]/;
+
+/**
+ * A named timeout and its value. Only a *raised* one is a finding — a brand-new
+ * timeout on a new test is not a weakening — so the value is compared against
+ * the same key on the pre-image side and silence is the answer whenever the key
+ * appears on only one side.
+ */
+const TIMEOUT =
+  /\b(timeout|timeoutMs|timeout_ms|timeoutSeconds|deadline|maxDuration|wallClock(?:Ms)?|setTimeout|jest\.setTimeout|retries)\b\s*[:=(]\s*(\d[\d_]*)/gi;
+
+function timeouts(text: string): { key: string; value: number }[] {
+  const found: { key: string; value: number }[] = [];
+  for (const match of text.matchAll(TIMEOUT)) {
+    const key = match[1]?.toLowerCase();
+    const raw = match[2]?.replaceAll("_", "");
+    if (key === undefined || raw === undefined) continue;
+    const value = Number(raw);
+    if (Number.isSafeInteger(value)) found.push({ key, value });
+  }
+  return found;
+}
+
+// ------------------------------------------------------------------- attribute
+
+/**
+ * Whether the dispatching issue named this file. A flag on a file the issue
+ * never mentions is the "tests you didn't write" case and is louder, so the
+ * match is lenient in the direction that produces *fewer* loud flags: the bare
+ * basename counts, and a common one like `index.test.ts` will match almost any
+ * issue that mentions a test at all.
+ *
+ * Deliberately *not* the containing directory. That rule was tried and it
+ * attributes everything: this package's entire source lives under `omp/src`,
+ * so any issue naming one file there would vouch for every test file in the
+ * repository, and the mark would stop distinguishing anything.
+ */
+function namedByIssue(issueText: string, file: PrDiffFile): boolean {
+  const haystack = issueText.toLowerCase();
+  for (const path of [file.path, file.previousPath]) {
+    if (path === undefined) continue;
+    const lower = path.toLowerCase();
+    if (haystack.includes(lower) || haystack.includes(basename(lower))) return true;
+  }
+  return false;
+}
+
+/** Evidence text is a source line, and a source line can be minified. */
+const EVIDENCE_LIMIT = 120;
+
+function evidence(text: string): string {
+  const trimmed = text.trim();
+  return trimmed.length <= EVIDENCE_LIMIT ? trimmed : `${trimmed.slice(0, EVIDENCE_LIMIT - 1)}…`;
+}
+
+// -------------------------------------------------------------------- analyser
+
+export interface SettlementAudit {
+  /** The worker's final report, verbatim. */
+  report: string;
+  /** The dispatching issue's title and body — the attribution source. */
+  issueText: string;
+  diff: PrDiff;
+}
+
+/**
+ * Every advisory finding about one settled pull request, in a stable order:
+ * the `changed:` reconciliation first, then test weakening in diff order.
+ *
+ * An empty array is the expected result for an honest run, and is load-bearing:
+ * the settlement report says nothing at all when this returns nothing.
+ */
+export function analyseSettlement(audit: SettlementAudit): SettlementFlag[] {
+  const flags: SettlementFlag[] = [];
+  reconcileChanged(audit, flags);
+  detectWeakening(audit, flags);
+  return flags;
+}
+
+function reconcileChanged(audit: SettlementAudit, flags: SettlementFlag[]): void {
+  const touched = audit.diff.files.filter((f) => DERIVED_FILE[basename(f.path)] !== true);
+  const claims = claimedPaths(audit.report);
+
+  if (claims.length === 0) {
+    // The degenerate case of the same check: with no usable `changed:` line
+    // every file is undisclosed, and saying so once beats saying it per file.
+    // Reporting it at all is what stops the check being defeated by writing
+    // `changed: see the PR` — or by dropping the line entirely.
+    if (touched.length > 0) {
+      flags.push({
+        kind: "changed-line-missing",
+        file: "(report)",
+        detail:
+          "the report's `changed:` line is missing or names no paths, so none of the " +
+          `${touched.length} file(s) the PR touched was disclosed`,
+      });
+    }
+    return;
+  }
+
+  for (const file of touched) {
+    if (claims.some((claim) => covers(claim, file.path))) continue;
+    if (file.previousPath !== undefined && claims.some((claim) => covers(claim, file.previousPath ?? ""))) {
+      continue;
+    }
+    flags.push({
+      kind: "undisclosed-file",
+      file: file.path,
+      detail: `${file.status} by the PR but absent from the report's \`changed:\` line`,
+    });
+  }
+
+  // The weaker direction, and it stays weak on purpose: a worker often names a
+  // file it edited and then reverted, or one it renamed away from. Worth
+  // surfacing because a `changed:` line that describes a different PR is the
+  // signature of a report written from memory rather than from `git diff`.
+  for (const claim of claims) {
+    if (audit.diff.files.some((f) => covers(claim, f.path) || covers(claim, f.previousPath ?? ""))) {
+      continue;
+    }
+    flags.push({
+      kind: "unmatched-claim",
+      file: claim,
+      detail: "named by the report's `changed:` line but not touched by the PR",
+    });
+  }
+}
+
+function detectWeakening(audit: SettlementAudit, flags: SettlementFlag[]): void {
+  // A test file that left one path and arrived at another is a move, not a
+  // deletion. `status: renamed` covers the renames git detected; the basename
+  // pairing covers the ones it did not, because a move plus a heavy edit is
+  // emitted as an unrelated delete and add. It can hide a genuine deletion that
+  // happens to share a basename with an added file — accepted, as a false
+  // negative for a false positive on every legitimate move.
+  const arrived = new Set(
+    audit.diff.files
+      .filter((f) => f.status === "added" && isTestPath(f.path))
+      .map((f) => basename(f.path)),
+  );
+
+  for (const file of audit.diff.files) {
+    // A recorded fixture legitimately *contains* `it.skip(`; that is what makes
+    // it a fixture. Vendored trees are somebody else's tests entirely.
+    if (DATA_DIR.test(file.path) || VENDORED.test(file.path)) continue;
+    if (!isTestPath(file.path) && !isTestPath(file.previousPath ?? "")) continue;
+    const unattributed = namedByIssue(audit.issueText, file) ? undefined : true;
+    const mark = (flag: Omit<SettlementFlag, "unattributed">): void => {
+      flags.push(unattributed === undefined ? flag : { ...flag, unattributed });
+    };
+
+    if (file.status === "removed") {
+      if (arrived.has(basename(file.path))) continue;
+      mark({
+        kind: "test-file-deleted",
+        file: file.path,
+        detail: "test file deleted, and no rename in this PR accounts for it",
+      });
+      // Its every line is a removal; listing them as separate findings would
+      // bury the one that matters.
+      continue;
+    }
+
+    if (file.hunks === undefined) continue;
+    scanHunks(file, file.hunks, mark);
+  }
+}
+
+function scanHunks(
+  file: PrDiffFile,
+  hunks: string,
+  mark: (flag: Omit<SettlementFlag, "unattributed">) => void,
+): void {
+  const hashComments = HASH_COMMENTS.test(file.path);
+  const disabledBefore = new Set<string>();
+  const disabledAfter: { line: number; text: string }[] = [];
+  const commentedAssertions: { line: number; text: string }[] = [];
+  const timeoutBefore = new Map<string, number>();
+  const timeoutAfter = new Map<string, { value: number; line: number; text: string }>();
+  let assertionsAdded = 0;
+  let assertionsRemoved = 0;
+  let firstRemovedAssertion: { line: number; text: string } | undefined;
+
+  for (const change of changedLines(hunks)) {
+    const { code, comment } = splitCode(change.text, hashComments);
+    const statement = code.trim();
+    const disabled = DISABLED_TEST.some((re) => re.test(statement));
+
+    if (disabled) {
+      if (change.added) disabledAfter.push({ line: change.line, text: change.text });
+      // Normalised, so a marker that only moved or was re-indented is not new.
+      else disabledBefore.add(statement.replaceAll(/\s+/g, " "));
+    }
+
+    if (ASSERTION.test(statement)) {
+      if (change.added) assertionsAdded++;
+      else {
+        assertionsRemoved++;
+        firstRemovedAssertion ??= { line: change.line, text: change.text };
+      }
+    }
+
+    // A commented-out assertion is unambiguous — nobody does it by accident —
+    // but only when the comment body is a whole statement. `// expect() is
+    // called by the helper` is prose and must stay silent, so the body has to
+    // end the way a statement ends.
+    const commented = comment.trim();
+    if (change.added && ASSERTION.test(commented) && /[;)]$/.test(commented)) {
+      commentedAssertions.push({ line: change.line, text: commented });
+    }
+
+    for (const { key, value } of timeouts(code)) {
+      if (change.added) {
+        const prior = timeoutAfter.get(key);
+        if (prior === undefined || value > prior.value) {
+          timeoutAfter.set(key, { value, line: change.line, text: change.text });
+        }
+      } else {
+        timeoutBefore.set(key, Math.max(timeoutBefore.get(key) ?? 0, value));
+      }
+    }
+  }
+
+  for (const found of disabledAfter) {
+    if (disabledBefore.has(splitCode(found.text, hashComments).code.trim().replaceAll(/\s+/g, " "))) {
+      continue;
+    }
+    mark({
+      kind: "test-disabled",
+      file: file.path,
+      line: found.line,
+      detail: `added \`${evidence(found.text)}\``,
+    });
+  }
+
+  for (const found of commentedAssertions) {
+    mark({
+      kind: "assertions-removed",
+      file: file.path,
+      line: found.line,
+      detail: `assertion commented out: \`${evidence(found.text)}\``,
+    });
+  }
+
+  // Net, not gross. A rewritten test moves its assertions, and counting removals
+  // alone flags every honest refactor — measured against this package's own
+  // history, that is most test edits.
+  if (assertionsRemoved > assertionsAdded && firstRemovedAssertion !== undefined) {
+    mark({
+      kind: "assertions-removed",
+      file: file.path,
+      line: firstRemovedAssertion.line,
+      detail:
+        `${assertionsRemoved - assertionsAdded} more assertion(s) removed than added ` +
+        `(first: \`${evidence(firstRemovedAssertion.text)}\`)`,
+    });
+  }
+
+  for (const [key, after] of timeoutAfter) {
+    const before = timeoutBefore.get(key);
+    if (before === undefined || after.value <= before) continue;
+    mark({
+      kind: "test-timeout-raised",
+      file: file.path,
+      line: after.line,
+      detail: `\`${key}\` raised from ${before} to ${after.value}`,
+    });
+  }
+}
+
+// -------------------------------------------------------------------- printing
+
+/** Beyond this the report is a wall of text nobody reads; the count still tells
+ *  the truth about how much was suppressed. */
+const RENDERED_FLAGS = 20;
+
+const HEADING = "settlement audit";
+
+/**
+ * The flag block appended to a settlement report, or no lines at all.
+ *
+ * Silence is the design: an honest run must add nothing to its report, or the
+ * block becomes furniture and stops being read. The one exception is a diff
+ * that could not be read in full — then the absence of flags is not evidence of
+ * anything, and saying so is the honest report.
+ */
+export function formatSettlementFlags(
+  flags: readonly SettlementFlag[],
+  diff: { truncated: boolean } = { truncated: false },
+): string[] {
+  if (flags.length === 0) {
+    return diff.truncated
+      ? [`${HEADING}: no flags, but the PR diff was too large to read in full — this is not a clean bill`]
+      : [];
+  }
+  const lines = [
+    `${HEADING}: ${flags.length} advisory flag(s) — the run's state is unchanged by them` +
+      (diff.truncated ? ", and the PR diff was too large to read in full" : ""),
+  ];
+  for (const flag of flags.slice(0, RENDERED_FLAGS)) {
+    lines.push(
+      `  ${flag.kind}  ${flag.file}${flag.line === undefined ? "" : `:${flag.line}`} — ${flag.detail}` +
+        (flag.unattributed === true ? "  [unattributed: the dispatching issue never names this file]" : ""),
+    );
+  }
+  if (flags.length > RENDERED_FLAGS) {
+    lines.push(`  … and ${flags.length - RENDERED_FLAGS} more`);
+  }
+  return lines;
+}
+
+/** The one-line form for `omp-conductor status`, where a flagged run has to be
+ *  visible long after its escalation was delivered and deduplicated. */
+export function settlementFlagSummary(flags: readonly SettlementFlag[] | undefined): string | undefined {
+  if (flags === undefined || flags.length === 0) return undefined;
+  const kinds = [...new Set(flags.map((f) => f.kind))].join(", ");
+  const loud = flags.some((f) => f.unattributed === true) ? ", some unattributed" : "";
+  return `${HEADING}: ${flags.length} flag(s) — ${kinds}${loud}`;
+}