omp-conductor 0.15.9 → 0.15.11

package/src/diff-flags.ts

@@ -2,19 +2,21 @@
  * 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`):
+ * The report's `changed:` line — the one fact a reviewer needs to use a
+ * settlement report as a summary — is no longer hand-written at all. It is
+ * derived at settlement from the pull request's own file list: {@link
+ * deriveChangedLine} composes it and {@link withDerivedChangedLine} rewrites it
+ * into the report, so the disclosure is the diff's, never a model's memory of
+ * work that happened dozens of turns earlier (#488). Only the *narrative* — what
+ * changed and why — remains the worker's to write.
  *
- * ```
- * 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).
+ * What this module still checks by reading a report is content, not disclosure.
+ * `state: pushed-green` stopped being believed in #85 — a claim is now checked
+ * against GitHub by `verifyPushedGreenClaim` rather than taken at face value —
+ * and the epic's ranked item 7, "don't weaken tests you didn't write, checked
+ * by diff review", is the other half: a diff-level check of the test files a PR
+ * touched, 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
@@ -28,11 +30,11 @@
  * 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.
+ * Pure by construction: the analyser takes a parsed diff 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";
@@ -231,51 +233,51 @@ function isTestPath(path: string): boolean {
   return TEST_FILE_NAME.test(path) || TEST_DIR.test(path);
 }
 
+// --------------------------------------------------------- derived disclosure
+
 /**
- * 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.
+ * The `changed:` line is composed from the PR's own diff — every file it
+ * touched, lockfiles included. Nothing is exempted, because nothing is being
+ * held against the worker any more: the list is the diff's, so completeness
+ * costs nothing.
  */
-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
 
+/** The `changed:` line of the settlement report, as the rewrite targets it. */
 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.
+ * Any other report field heading: `word:` opening a line, possibly indented or
+ * blockquote-prefixed (`> next:`). A `changed:` disclosure never continues
+ * past one — the rewrite below ends its old-list scan at a following field,
+ * so `next:`/`gates:` values stay attached to the report (#435).
+ */
+const FIELD_LINE = /^[ \t>]*[A-Za-z_][A-Za-z0-9_-]*\s*:/;
+
+/**
+ * A token that reads as a path — the shape a hand-written file list is made
+ * of. The rewrite scans a wrapped old disclosure line by line and stops where
+ * the lines stop looking like paths: `omp/src/foo.ts` is a path, `(new)` and
+ * `e.g` are prose. The last clause is not fussiness: without it `e.g`, `i.e`
+ * and `0.3.18` would all count as paths and a wrapped list's boundary would
+ * land one line too late.
  */
 const CLAIMED_PATH = /^(?:[\w.@~+-]+\/)+[\w.@~*+-]*$|^[\w.@~+-]*\.[A-Za-z][A-Za-z0-9]{1,7}$/;
 
-/** A Python dotted module: `services.rule_purge`, `omp.routing`. Not a path —
- *  segments joined by `.` — but a legitimate way for a report to name the file
- *  it touched without disclosing the directory it lives in (#224).
- *
- *  Every segment is at least two characters so prose abbreviations (`e.g`,
- *  `i.e.`, `a.k.a`) stay commentary: they are exactly the prose the path
- *  heuristic exists to reject, and each one that slipped through would become
- *  an "you claimed a file you never touched" flag on an honest report. */
+/** A Python module name: `services.rule_purge`, `omp.routing` — a legitimate
+ *  way a report names a file by import path rather than location (#224), and
+ *  still a path-shaped token for the old-list scan. Every segment is at least
+ *  two characters so prose abbreviations (`e.g`, `i.e.`, `a.k.a`) stay
+ *  commentary. */
 const DOTTED_MODULE = /^[A-Za-z_]\w+(?:\.[A-Za-z_]\w+)+$/;
 
+/** A numeric diff statistic — `+1/-1`, `+12/-3`, `1/-1`, a bare `+1`. It is
+ *  slash-shaped enough to look like a path — every segment is a signed
+ *  integer, which CLAIMED_PATH's character classes accept — but it is a count,
+ *  not a path: the wrapped-list scan must cut at it, exactly where it appears
+ *  in real reports (`omp/package.json (…, +1/-1; …)`, the #388 report,
+ *  verbatim). */
+const DIFF_STAT = /^[+-]?\d+(?:\/[+-]?\d+)?$/;
+
 /** One-level brace expansion: `a/{b,c}.py` → [`a/b.py`, `a/c.py`]. Braces are
  *  how a report compresses adjacent files into one token; each comma-separated
  *  alternative is substituted into the skeleton. Nesting is deliberately
@@ -300,72 +302,71 @@ function expandExtensionAlternation(token: string): string[] {
   return [first, ...rest.split("/.").filter(Boolean)].map((extension) => `${base}.${extension}`);
 }
 
-/** 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. */
-function parseClaimedPaths(report: string, extensionAlternatives?: Set<string>): string[] {
-  const line = CHANGED_LINE.exec(report)?.[1] ?? "";
-  const seen = new Set<string>();
-  // Split on whitespace and semicolons, and on commas *outside* a brace group:
-  // the comma in `a/{b,c}.py` is an alternative separator, not a token
-  // separator, so a brace-compressed token must survive whole (#224).
-  for (const raw of line.split(/[\s;]+|,(?![^{}]*\})/)) {
-    const token = raw.replace(/^[`'"([*-]+/, "").replace(/[`'")\].,:;]+$/, "");
-    if (token === "" || token === "none") continue;
-    const normalised = token.replace(/^\.?\//, "");
-    // Expansion happens here so every downstream consumer — both `covers`
-    // directions — sees plain paths: a brace token dies earlier at the
-    // CLAIMED_PATH filter if it is never opened up (#224).
-    for (const expanded of expandBraces(normalised)) {
-      const alternatives = expandExtensionAlternation(expanded);
-      for (const path of alternatives) {
-        if (!CLAIMED_PATH.test(path) && !DOTTED_MODULE.test(path)) continue;
-        seen.add(path);
-        if (alternatives.length > 1) extensionAlternatives?.add(path);
-      }
-    }
-  }
-  return [...seen];
+/** One cleaned token of a `changed:` line, as claim parsing sees it: leading
+ *  quotes and brackets stripped, trailing punctuation stripped, empties, the
+ *  word `none`, and numeric diff statistics dropped. */
+function claimTokens(line: string): string[] {
+  return line
+    .split(/[\s;]+|,(?![^{}]*\})/)
+    .map((raw) => raw.replace(/^[`'"([*-]+/, "").replace(/[`'")\].,:;]+$/, ""))
+    .filter((token) => token !== "" && token !== "none" && !DIFF_STAT.test(token));
 }
 
-export function claimedPaths(report: string): string[] {
-  return parseClaimedPaths(report);
+/** Whether a cleaned token names at least one path once braces and extension
+ *  alternatives are expanded — the same filter the disclosure rewrite applies
+ *  to every continuation line it considers part of the old file list. */
+function tokenNamesAPath(token: string): boolean {
+  const normalised = token.replace(/^\.?\//, "");
+  return expandBraces(normalised).some((expanded) =>
+    expandExtensionAlternation(expanded).some((path) => CLAIMED_PATH.test(path) || DOTTED_MODULE.test(path)),
+  );
+}
+
+/**
+ * The file list the PR's own diff reports, in diff order, comma-separated —
+ * the settlement report's `changed:` line. Derived rather than asked for, so a
+ * worker that never writes a file list still settles with a correct one, and a
+ * report that contradicts the diff is rewritten to say what the diff says
+ * (never the other way round).
+ */
+export function deriveChangedLine(diff: PrDiff): string {
+  return diff.files.map((file) => file.path).join(", ");
 }
 
 /**
- * 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:
+ * Rewrite the worker's hand-written `changed:` line with the derived one,
+ * keeping the rest of the report — the narrative — verbatim.
  *
- * - 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.
+ * The old line and any wrapped continuation that still reads as a path list
+ * (#435) are removed wholesale and replaced by a single derived line. A report
+ * with no `changed:` line at all has one inserted before `next:`, so a settled
+ * report always carries the disclosure.
  */
-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));
+export function withDerivedChangedLine(report: string, changedLine: string): string {
+  const lines = report.split("\n");
+  const start = lines.findIndex((line) => CHANGED_LINE.test(line));
+  const disclosure = `changed: ${changedLine}`;
+  if (start === -1) {
+    const next = lines.findIndex((line) => /^[ \t>]*next:/.test(line));
+    lines.splice(next === -1 ? lines.length : next, 0, disclosure);
+    return lines.join("\n");
   }
-  if (path.endsWith(`/${claim}`) || claim.endsWith(`/${path}`)) return true;
-  // A Python dotted module names a file by import path, not by location:
-  // `services.rule_purge` covers `backend/app/services/rule_purge.py`. Only
-  // consulted after the path rules, because `foo.bar` is also a valid filename
-  // and a literal match must win. Matching several changed files is fine — the
-  // check wants evidence the worker knew, not a unique index (#224).
-  if (DOTTED_MODULE.test(claim)) {
-    const fragment = `${claim.replaceAll(".", "/")}.py`;
-    if (path === fragment || path.endsWith(`/${fragment}`)) return true;
+  // The old disclosure is the `changed:` line plus whatever following lines
+  // still read as a wrapped path list: indented, non-blank, not a field heading,
+  // not prose. Everything past it belongs to the report and survives.
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end] ?? "";
+    if (line.trim() === "") break;
+    if (!/^[ \t>]/.test(line)) break;
+    if (FIELD_LINE.test(line)) break;
+    const tokens = claimTokens(line);
+    if (tokens.length === 0 || !tokenNamesAPath(tokens[0] ?? "")) break;
+    end++;
   }
-  const last = claim.slice(claim.lastIndexOf("/") + 1);
-  return !last.includes(".") && path.startsWith(`${claim}/`);
+  const prefix = /^[ \t>]*/.exec(lines[start] ?? "")?.[0] ?? "";
+  lines.splice(start, end - start, `${prefix}${disclosure}`);
+  return lines.join("\n");
 }
 
 // ------------------------------------------------------ test-weakening lexicon
@@ -492,143 +493,41 @@ function evidence(text: string): string {
 // -------------------------------------------------------------------- analyser
 
 export interface SettlementAudit {
-  /** The worker's final report, verbatim. */
-  report: string;
-  /** Earlier attempts' reports for the same issue, oldest first. Their
-   *  `changed:` disclosures are pooled as coverage so a file disclosed in a
-   *  prior attempt is never flagged as undisclosed in the final one, while the
-   *  reverse (unmatched-claim) direction reads only the current report — a file
-   *  claimed in attempt 1 and reverted by attempt 3 must not come back as a new
-   *  finding (#199). Absent means this is the only attempt, or older rows never
-   *  stored a report. */
-  priorReports?: readonly 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.
+ * Every advisory finding about one settled pull request, in a stable order
+ * (test weakening in diff order).
+ *
+ * The file-list disclosure is not audited here at all: it is derived from
+ * `diff` itself ({@link deriveChangedLine}), so the `undisclosed-file` /
+ * `unmatched-claim` reconciliation flags are structurally gone. What remains
+ * is the diff-content check a human is worst placed to do by hand.
  *
  * 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 extensionAlternatives = new Set<string>();
-  const claims = parseClaimedPaths(audit.report, extensionAlternatives);
-  const priorClaims = claimedPaths((audit.priorReports ?? []).join("\n"));
-  // Coverage pools the current report with every prior attempt's disclosures:
-  // a file the final report no longer names was disclosed while the work was
-  // still in flight, so it must not be flagged undisclosed (#199).
-  const coverage = [...new Set([...claims, ...priorClaims])];
-
-  if (claims.length === 0 && priorClaims.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 (coverage.some((claim) => covers(claim, file.path))) continue;
-    if (file.previousPath !== undefined && coverage.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`.
-  //
-  // It iterates only the CURRENT report's claims (#199). A file claimed in
-  // attempt 1 and reverted by attempt 3 was true then and false now; pooling
-  // priors into this loop would turn every honest revert into a fresh finding.
-  for (const claim of claims) {
-    if (audit.diff.files.some((f) => covers(claim, f.path) || covers(claim, f.previousPath ?? ""))) {
-      continue;
-    }
-    if (extensionAlternatives.has(claim)) {
-      const stem = claim.slice(0, claim.lastIndexOf("."));
-      const matchedAlternative = claims.some(
-        (other) =>
-          other !== claim &&
-          extensionAlternatives.has(other) &&
-          other.slice(0, other.lastIndexOf(".")) === stem &&
-          audit.diff.files.some((f) => covers(other, f.path) || covers(other, f.previousPath ?? "")),
-      );
-      if (matchedAlternative) continue;
-    }
-    flags.push({
-      kind: "unmatched-claim",
-      file: claim,
-      detail: "named by the report's `changed:` line but not touched by the PR",
-    });
-  }
-
-  // A parser failure can otherwise accuse the report in both directions for
-  // the same file. Collapse only that self-refuting pair; unrelated findings
-  // remain intact.
-  const unmatched = flags.filter((flag) => flag.kind === "unmatched-claim");
-  const removed = new Set<SettlementFlag>();
-  let exampleClaim = "";
-  let examplePath = "";
-  for (const undisclosed of flags.filter((flag) => flag.kind === "undisclosed-file")) {
-    const name = basename(undisclosed.file);
-    const extension = name.lastIndexOf(".");
-    const stem = extension > 0 ? name.slice(0, extension) : name;
-    if (stem.length < 3) continue;
-    for (const claim of unmatched) {
-      if (!claim.file.includes(stem)) continue;
-      removed.add(undisclosed);
-      removed.add(claim);
-      if (exampleClaim === "") {
-        exampleClaim = claim.file;
-        examplePath = undisclosed.file;
-      }
-    }
-  }
-  if (removed.size === 0) return;
-
-  const kept = flags.filter((flag) => !removed.has(flag));
-  const removedClaims = unmatched.filter((flag) => removed.has(flag)).length;
-  flags.splice(
-    0,
-    flags.length,
-    ...kept,
-    {
-      kind: "report-format-unparsed",
-      file: "(report)",
-      detail:
-        `${removedClaims} claim(s) on the \`changed:\` line could not be parsed as paths yet name the same ` +
-        `file(s) the PR touched (e.g. ${exampleClaim} vs ${examplePath}) — read the diff directly`,
-    },
-  );
-}
+/**
+ * The one finding a settlement can carry without a diff at all. `changed-line-missing`
+ * used to mean "the worker's report disclosed nothing"; with the list derived
+ * from the PR's own diff it can only mean the tree could not be read — a real
+ * fault worth surfacing, never an empty list that reads as a clean bill.
+ */
+export const UNREADABLE_TREE_FLAG: SettlementFlag = {
+  kind: "changed-line-missing",
+  file: "(report)",
+  detail:
+    "the settlement could not read the PR's diff, so no `changed:` file list could be derived",
+};
 
 function detectWeakening(audit: SettlementAudit, flags: SettlementFlag[]): void {
   // A test file that left one path and arrived at another is a move, not a
@@ -788,30 +687,21 @@ const HEADING = "settlement audit";
  * that could not be read in full — then the absence of flags is not evidence of
  * anything, and saying so is the honest report.
  */
-/** Appended to the heading when a multi-attempt audit pooled prior disclosures,
- *  so a reader is told the coverage is wider than this one report (#199). */
-function pooledHeading(attempts: number | undefined): string {
-  return attempts !== undefined && attempts > 1
-    ? ` — disclosures pooled across ${attempts} attempt(s)`
-    : "";
-}
-
 export function formatSettlementFlags(
   flags: readonly SettlementFlag[],
-  diff: { truncated: boolean; attempts?: number } = { truncated: false },
+  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` +
-            `${pooledHeading(diff.attempts)} — this is not a clean bill`,
+            " — 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" : "") +
-      pooledHeading(diff.attempts),
+      (diff.truncated ? ", and the PR diff was too large to read in full" : ""),
   ];
   for (const flag of flags.slice(0, RENDERED_FLAGS)) {
     if (flag.kind === "pr-adopted") {