@mmerterden/multi-agent-pipeline 20.33.0 → 20.34.0

package/pipeline/scripts/learnings-ledger.mjs

@@ -14,7 +14,10 @@
  * run re-discovers the same structure and reviewers re-flag preferences the team
  * already rejected.
  *
- * Each line conforms to pipeline/schemas/learnings-ledger.schema.json.
+ * Each line conforms to pipeline/schemas/learnings-ledger.schema.json. Every
+ * entry passes the secret scan in _secret-scan.mjs before it is written, and
+ * `<private>` spans are removed first; a refused entry is counted in
+ * `droppedBySecretScan`.
  *
  * Subcommands:
  *   add        --kind <fact|convention|rejected-preference> --statement "..."
@@ -43,6 +46,12 @@
  *                 severity rejections are NOT distilled - a wrong rejection of a
  *                 blocking issue must never permanently suppress that class. Exit 2
  *                 when nothing new was distilled (a repeat of the same triage).
+ *   feedback   --id <id> --outcome <useful|dead_end|corrected> [--task <id>] [--repo-slug <slug>]
+ *                 Record how an injected entry fared. An entry marked corrected,
+ *                 or judged a dead end at least twice and more often than useful,
+ *                 leaves brief and profile; one useful at least twice ranks by
+ *                 its strength too (_memory-policy.mjs). Kept beside the ledger
+ *                 in learnings-feedback.jsonl.
  *   forget     [--statement "..."] [--kind <kind>] [--repo-slug <slug>]
  *                 Remove ledger entries matching the statement substring and/or
  *                 kind (rewrites the file). Use to clear a bad/stale learning.
@@ -70,7 +79,15 @@ import {
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { join, basename, dirname } from "node:path";
-import { bm25, recencyRank, rrf, tokens, shortId, recallConfig } from "./_retrieval.mjs";
+import { bm25, recencyRank, rrf, tokens, recallConfig } from "./_retrieval.mjs";
+import {
+  checkedSlug,
+  ledgerRowId,
+  memoryExcluded,
+  nearDuplicate,
+  standing,
+} from "./_memory-policy.mjs";
+import { openScanner, stripPrivate } from "./_secret-scan.mjs";
 
 const argv = process.argv.slice(2);
 const SUB = argv[0];
@@ -110,6 +127,10 @@ function die(msg, code = 1) {
 // the learning replay always miss. `--git-common-dir` points at the main
 // repository's .git for every linked worktree.
 function repoSlug() {
+  return checkedSlug(rawRepoSlug());
+}
+
+function rawRepoSlug() {
   if (flags["repo-slug"]) return String(flags["repo-slug"]);
   if (process.env.MULTI_AGENT_REPO_SLUG) return process.env.MULTI_AGENT_REPO_SLUG;
   try {
@@ -150,6 +171,36 @@ function ledgerPath(slug) {
   );
 }
 
+function feedbackPath(slug) {
+  return join(dirname(ledgerPath(slug)), "learnings-feedback.jsonl");
+}
+
+/** id -> outcome rows recorded against it. */
+function readFeedback(slug) {
+  const p = feedbackPath(slug);
+  const byId = new Map();
+  if (!existsSync(p)) return byId;
+  for (const line of readFileSync(p, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const f = JSON.parse(line);
+      if (!byId.has(f.id)) byId.set(f.id, []);
+      byId.get(f.id).push(f);
+    } catch {
+      /* skip corrupted line */
+    }
+  }
+  return byId;
+}
+
+/** Rows with their standing; suppressed ones dropped. */
+function standingRows(slug, rows) {
+  const fb = readFeedback(slug);
+  return rows
+    .map((r) => ({ r, s: standing(fb.get(rowId(r)) ?? []) }))
+    .filter((x) => !x.s.suppressed);
+}
+
 function ensureDir(p) {
   mkdirSync(dirname(p), { recursive: true });
 }
@@ -171,9 +222,7 @@ function normStatement(s) {
 // Stable pointer for a ledger row, from the same fields the dedup key uses.
 // Not stored on the row: an existing ledger gets ids without a migration, and a
 // re-added entry keeps the id it already had.
-function rowId(row) {
-  return shortId("L", row.kind, normStatement(row.statement));
-}
+const rowId = ledgerRowId;
 
 function readLedger(slug) {
   const p = ledgerPath(slug);
@@ -197,8 +246,22 @@ function writeRow(slug, row) {
   appendFileSync(p, JSON.stringify(row) + "\n", "utf8");
 }
 
+// One scanner per process; every write goes through it (_secret-scan.mjs).
+let scanner = null;
+const secretScan = { dropped: 0 };
+function passesSecretScan(text) {
+  if (!scanner) {
+    scanner = openScanner();
+    process.on("exit", () => scanner.close());
+  }
+  if (scanner.isClean(text)) return true;
+  secretScan.dropped++;
+  return false;
+}
+
 /** Append one entry unless an entry with the same kind + normalized statement
- *  already exists (idempotent). Returns true when written. */
+ *  already exists (idempotent), or the text fails the secret scan. Returns
+ *  true when written. */
 function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, source }, existing) {
   // One line, enforced here rather than hoped for. The schema says "the
   // knowledge itself, in one line", and both blocks render one entry per line -
@@ -206,16 +269,23 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, s
   // `from-triage` builds statements out of model-written finding text, a
   // newline plus a plausible-looking `</repo-profile>` would break out of the
   // injected block itself. Collapsing whitespace closes both at the store.
-  const stmt = oneLine(statement);
+  const stmt = oneLine(stripPrivate(statement));
   if (!stmt) return false;
   const seenKey = `${kind}::${normStatement(stmt)}`;
   if (existing.has(seenKey)) return false;
+  const sameKind = [...existing]
+    .filter((k) => k.startsWith(`${kind}::`))
+    .map((k) => k.slice(kind.length + 2));
+  if (nearDuplicate(stmt.toLowerCase(), sameKind)) return false;
+  const diag = oneLine(stripPrivate(diagnosis));
+  const scopeText = scope || "global";
+  if (!passesSecretScan(`${stmt}\n${diag}\n${scopeText}`)) return false;
   const row = {
     v: "1.0.0",
     ts: new Date().toISOString(),
     repo_slug: slug,
     kind,
-    scope: scope || "global",
+    scope: scopeText,
     statement: stmt,
     source_task: task || null,
     confidence: CONFIDENCES.has(confidence) ? confidence : "medium",
@@ -223,7 +293,6 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, s
   // Optional causal diagnosis (Reflexion P5): the "why it failed" behind a
   // lesson. Verbal diagnosis is what turns a detected error into a prevented
   // one; a bare outcome does not. Stored only when supplied.
-  const diag = oneLine(diagnosis);
   if (diag) row.diagnosis = diag;
   // Who found it. Optional so old rows stay valid, but written whenever the
   // caller knows: a machine-mined path correction and a model's architectural
@@ -235,11 +304,19 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, s
   return true;
 }
 
+function refuseExcluded(slug) {
+  if (!memoryExcluded(slug)) return false;
+  process.stdout.write(JSON.stringify({ ok: true, slug, added: 0, excluded: true }) + "\n");
+  process.exitCode = 2;
+  return true;
+}
+
 function cmdAdd() {
   const kind = flags.kind;
   if (!KINDS.has(kind)) die(`--kind must be one of: ${[...KINDS].join(", ")}`, 1);
   if (!flags.statement || flags.statement === true) die('add needs --statement "..."', 1);
   const slug = repoSlug();
+  if (refuseExcluded(slug)) return;
   const existing = new Set(readLedger(slug).map((r) => `${r.kind}::${normStatement(r.statement)}`));
   const wrote = addEntry(
     slug,
@@ -256,7 +333,13 @@ function cmdAdd() {
     existing,
   );
   process.stdout.write(
-    JSON.stringify({ ok: true, slug, added: wrote ? 1 : 0, deduped: wrote ? 0 : 1 }) + "\n",
+    JSON.stringify({
+      ok: true,
+      slug,
+      added: wrote ? 1 : 0,
+      deduped: wrote || secretScan.dropped ? 0 : 1,
+      droppedBySecretScan: secretScan.dropped,
+    }) + "\n",
   );
   process.exit(wrote ? 0 : 2);
 }
@@ -267,6 +350,7 @@ function cmdFromTriage() {
   if (!existsSync(triagePath)) die(`triage file not found: ${triagePath}`, 1);
   const task = flags.task && flags.task !== true ? String(flags.task) : null;
   const slug = repoSlug();
+  if (refuseExcluded(slug)) return;
   let triage;
   try {
     triage = JSON.parse(readFileSync(triagePath, "utf8"));
@@ -311,7 +395,15 @@ function cmdFromTriage() {
       written++;
     }
   }
-  process.stdout.write(JSON.stringify({ ok: true, slug, added: written, skippedBlocking }) + "\n");
+  process.stdout.write(
+    JSON.stringify({
+      ok: true,
+      slug,
+      added: written,
+      skippedBlocking,
+      droppedBySecretScan: secretScan.dropped,
+    }) + "\n",
+  );
   process.exitCode = written ? 0 : 2;
   return;
 }
@@ -430,12 +522,14 @@ function compareCodepoints(a, b) {
 }
 
 function cmdBrief() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const cfg = recallConfig();
   const max = flags.max ? Math.max(1, Number(flags.max)) : 20;
   const task = flags.task && flags.task !== true ? String(flags.task) : null;
   const scope = flags.scope && flags.scope !== true ? String(flags.scope) : null;
-  const rows = readLedger(slug);
+  const scored = standingRows(slug, readLedger(slug));
+  const rows = scored.map((x) => x.r);
+  const strengthOf = new Map(scored.map((x) => [x.r, x.s.corroborated ? x.s.strength : 0]));
   if (rows.length === 0) {
     process.exit(2); // nothing to inject; caller skips silently
   }
@@ -471,8 +565,13 @@ function cmdBrief() {
     );
     const fresh = recencyRank(pool, { halfLifeDays: cfg.halfLifeDays });
     const matched = new Set(relevance.filter((x) => x.score > 0).map((x) => x.index));
-    const fused = rrf([relevance, fresh], { k: [10, 60], weights: [3, 1] }).filter((x) =>
-      matched.has(x.index),
+    // Entries recorded useful at least twice rank by their strength as well;
+    // with no feedback this list is empty and the fusion is unchanged.
+    const earned = pool
+      .map((r, index) => ({ index, score: strengthOf.get(r) || 0 }))
+      .sort((a, b) => b.score - a.score);
+    const fused = rrf([relevance, fresh, earned], { k: [10, 60, 60], weights: [3, 1, 1] }).filter(
+      (x) => matched.has(x.index),
     );
     ordered = fused.slice(0, max).map((x) => pool[x.index]);
     // A task whose words match nothing in the ledger must not silently inject an
@@ -527,10 +626,10 @@ function scopeMatches(entryScope, target) {
 // everything after it. Detail is deliberately absent; each line carries the
 // pointer that buys it back.
 function cmdProfile() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const cfg = recallConfig();
   const max = flags.max ? Math.max(1, Number(flags.max)) : 60;
-  const rows = readLedger(slug);
+  const rows = standingRows(slug, readLedger(slug)).map((x) => x.r);
   if (rows.length === 0) process.exit(2);
 
   const ordered = rows
@@ -565,7 +664,7 @@ function cmdProfile() {
 function cmdShow() {
   const id = flags.id && flags.id !== true ? String(flags.id) : null;
   if (!id) die("show needs --id <id>", 1);
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const want = id.startsWith("L:") ? id : `L:${id}`;
   const row = readLedger(slug).find((r) => rowId(r) === want);
   if (!row) {
@@ -592,7 +691,7 @@ function cmdShow() {
 function cmdTimeline() {
   const id = flags.anchor && flags.anchor !== true ? String(flags.anchor) : null;
   if (!id) die("timeline needs --anchor <id>", 1);
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const before = flags.before && flags.before !== true ? Math.max(0, Number(flags.before)) : 3;
   const after = flags.after && flags.after !== true ? Math.max(0, Number(flags.after)) : 3;
   const want = id.startsWith("L:") ? id : `L:${id}`;
@@ -622,15 +721,32 @@ function cmdTimeline() {
 }
 
 function cmdPath() {
-  process.stdout.write(
-    ledgerPath(flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug()) + "\n",
-  );
+  process.stdout.write(ledgerPath(repoSlug()) + "\n");
   process.exitCode = 0;
   return;
 }
 
+const OUTCOMES = new Set(["useful", "dead_end", "corrected"]);
+
+function cmdFeedback() {
+  const slug = repoSlug();
+  const raw = flags.id && flags.id !== true ? String(flags.id).replace(/^\[|\]$/g, "") : "";
+  const id = raw && !raw.startsWith("L:") ? `L:${raw}` : raw;
+  const outcome = String(flags.outcome || "");
+  if (!id || !OUTCOMES.has(outcome))
+    die("feedback needs --id <id> --outcome <useful|dead_end|corrected>", 1);
+  if (!readLedger(slug).some((r) => rowId(r) === id)) die(`no ledger entry ${id}`, 2);
+  if (refuseExcluded(slug)) return;
+  const row = { ts: new Date().toISOString(), id, outcome };
+  if (flags.task && flags.task !== true) row.task = String(flags.task);
+  ensureDir(feedbackPath(slug));
+  appendFileSync(feedbackPath(slug), JSON.stringify(row) + "\n", "utf8");
+  const s = standing(readFeedback(slug).get(id) ?? []);
+  process.stdout.write(JSON.stringify({ ok: true, slug, id, ...s }) + "\n");
+}
+
 function cmdStats() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const rows = readLedger(slug);
   const counts = { fact: 0, convention: 0, "rejected-preference": 0 };
   for (const r of rows) if (counts[r.kind] !== undefined) counts[r.kind]++;
@@ -651,6 +767,9 @@ switch (SUB) {
   case "forget":
     cmdForget();
     break;
+  case "feedback":
+    cmdFeedback();
+    break;
   case "brief":
     cmdBrief();
     break;
@@ -671,7 +790,7 @@ switch (SUB) {
     break;
   default:
     process.stderr.write(
-      "usage: learnings-ledger.mjs <add|from-triage|forget|brief|profile|show|timeline|path|stats> [flags]\n",
+      "usage: learnings-ledger.mjs <add|from-triage|feedback|forget|brief|profile|show|timeline|path|stats> [flags]\n",
     );
     process.exit(64);
 }

package/pipeline/scripts/plan-critique-gate.mjs

@@ -4,7 +4,9 @@
  * answer per objection, and a verdict decided by constitution rule id.
  *
  * At the end of Phase 1 the plan-critic persona writes objections to the plan
- * under four lenses (scope, feasibility, security, a cheaper alternative), and
+ * under six lenses (scope, feasibility, security, a cheaper alternative, an
+ * input the spec implies but no test exercises, a decision left to the
+ * implementer), and
  * the planner answers each one exactly once: accept and revise the plan, or
  * rebut with evidence. Both halves live in one file,
  * `<worktree>/.pipeline/plan-critique.json` (schemas/plan-critique.schema.json).
@@ -59,7 +61,14 @@ import { requirementIds } from "./spec-consistency-gate.mjs";
 import { resolveOne } from "./verify-citations.mjs";
 
 export const GATE = "plan-critique";
-export const LENSES = ["scope", "feasibility", "security", "alternative"];
+export const LENSES = [
+  "scope",
+  "feasibility",
+  "security",
+  "alternative",
+  "unstated-input",
+  "underspecified",
+];
 export const ANCHOR_KINDS = ["file", "plan", "analysis", "inference"];
 export const ACTIONS = ["accept", "rebut"];
 const OBJ_ID = /^OBJ-\d{2,3}$/;

package/pipeline/scripts/rework-rulings.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * rework-rulings.mjs  -  what happens to each open finding when the rework cap
+ * is reached.
+ *
+ * Phase 2 allows a fixed number of rework rounds. At the cap every accepted
+ * finding still open gets one ruling, recorded, never dropped:
+ *
+ *   escalate   load-bearing: blocking severity, or a security finding
+ *              (ruleId SEC-* / CON-SEC-*, a security criteriaSource, or the
+ *              security-auditor's `security` object). The run stops and the
+ *              user decides.
+ *   parked     anything else. It leaves the loop as a follow-up with its
+ *              reason, shown before commit (Phase 4 Step 0b), carried in the
+ *              PR follow-ups and recorded in the debt list, so the run can finish instead of stopping on a
+ *              finding that is safe to defer.
+ *
+ * The run escalates when any ruling is `escalate`; otherwise it continues.
+ *
+ * Usage:
+ *   rework-rulings.mjs --triage <triage-output.json> [--state <agent-state.json>]
+ *
+ *   --state records the result as reviewIterations[-1].rulings.
+ *
+ * Output: {escalate, parked, rulings[]} as JSON on stdout.
+ * Exit: 0 decided (either way) · 2 usage or unreadable triage · 3 state write failed
+ *
+ * @module pipeline/scripts/rework-rulings
+ */
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { updateState } from "./gate-ledger.mjs";
+
+const SECURITY_RULE = /^(CON-)?SEC-/i;
+
+/** True when a finding may not leave the loop without the user. */
+export function loadBearing(f) {
+  if (f?.severity === "blocking") return true;
+  if (typeof f?.ruleId === "string" && SECURITY_RULE.test(f.ruleId)) return true;
+  if (f?.security && typeof f.security === "object") return true;
+  return typeof f?.criteriaSource === "string" && /security/i.test(f.criteriaSource);
+}
+
+/** One ruling per accepted finding of a triage output. */
+export function rule(triage) {
+  const rulings = (triage?.accepted ?? []).map((f) => {
+    const escalate = loadBearing(f);
+    return {
+      fingerprint: f.fingerprint ?? null,
+      file: f.file ?? null,
+      line: Number.isInteger(f.line) ? f.line : null,
+      severity: f.severity ?? null,
+      ruling: escalate ? "escalate" : "parked",
+      reason: escalate
+        ? f.severity === "blocking"
+          ? "blocking finding open at the rework cap"
+          : "security finding open at the rework cap"
+        : `rework cap reached; ${f.severity ?? "unrated"} finding parked as a follow-up`,
+      issue: f.issue ?? "",
+    };
+  });
+  return {
+    escalate: rulings.some((r) => r.ruling === "escalate"),
+    parked: rulings.filter((r) => r.ruling === "parked").length,
+    rulings,
+  };
+}
+
+function flag(argv, name) {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const triagePath = flag(argv, "triage");
+  if (!triagePath) {
+    console.error("usage: rework-rulings.mjs --triage <path> [--state <path>]");
+    process.exit(2);
+  }
+  const triage = readRegularJson(triagePath, null);
+  if (!triage || !Array.isArray(triage.accepted)) {
+    console.error(`rework-rulings: no accepted[] in ${triagePath}`);
+    process.exit(2);
+  }
+  const result = rule(triage);
+  const statePath = flag(argv, "state");
+  if (statePath) {
+    try {
+      await updateState(statePath, (s) => {
+        const iterations = Array.isArray(s.reviewIterations) ? [...s.reviewIterations] : [];
+        if (!iterations.length) iterations.push({ iteration: 1 });
+        iterations[iterations.length - 1] = {
+          ...iterations[iterations.length - 1],
+          rulings: result.rulings,
+        };
+        return { ...s, reviewIterations: iterations };
+      });
+    } catch (e) {
+      console.error(`rework-rulings: state not written: ${e.message}`);
+      process.exitCode = 3;
+    }
+  }
+  process.stdout.write(JSON.stringify(result) + "\n");
+}

package/pipeline/scripts/scope-check-gate.mjs

@@ -10,21 +10,29 @@
  * Usage:
  *   git diff --name-only <base>...HEAD | node scope-check-gate.mjs --check .pipeline/scope-check.json --diff-files -
  *   node scope-check-gate.mjs --check scope-check.json --diff-files files.txt [--advisory]
+ *       [--patch <unified diff> | --repo <dir> --patch-range <a>...<b>]
  *
- * Output (stdout, JSON): {ok, justified, unjustified[], unlisted[], notDone}
+ * Output (stdout, JSON): {ok, justified, unjustified[], unlisted[], notDone, formatOnly[]}
  *   unjustified = in the diff, missing from files[] (or with an empty reason)
  *   unlisted    = in files[], not in the diff (stale entry; reported, never fatal)
+ *   formatOnly  = with --patch, hunks whose removed and added lines differ only
+ *                 in whitespace: a reformat of lines the task did not need to
+ *                 touch. Reported, never fatal. --patch-range reads that diff
+ *                 with git itself, its output format pinned, so a caller needs
+ *                 no file or process substitution for it.
  *
  * Exit codes: 0 every diff file justified (or --advisory), 1 otherwise or on
  * unreadable input, 64 usage.
  */
 
+import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 
 import { normalizeFile } from "./_fingerprint.mjs";
+import { parseUnifiedDiff } from "./_unified-diff.mjs";
 
 const USAGE =
-  "usage: scope-check-gate.mjs --check <scope-check.json> --diff-files <path|-> [--advisory]";
+  "usage: scope-check-gate.mjs --check <scope-check.json> --diff-files <path|-> [--advisory] [--patch <diff> | --repo <dir> --patch-range <a>...<b>]";
 
 function parseArgs(argv) {
   const opts = {};
@@ -33,15 +41,145 @@ function parseArgs(argv) {
     if (a === "--check") opts.check = argv[++i];
     else if (a === "--diff-files") opts.diffFiles = argv[++i];
     else if (a === "--advisory") opts.advisory = true;
+    else if (a === "--patch") opts.patch = argv[++i];
+    else if (a === "--patch-range") opts.patchRange = argv[++i];
+    else if (a === "--repo") opts.repo = argv[++i];
     else return null;
   }
+  if (opts.patchRange !== undefined && !/^[A-Za-z0-9_./~^@{}-]+$/.test(opts.patchRange))
+    return null;
+  if (opts.patchRange?.startsWith("-")) return null;
   return opts.check && opts.diffFiles ? opts : null;
 }
 
+/** The diff of a revision range, in the one shape formatOnlyHunks reads. */
+function rangeDiff(repo, range) {
+  return execFileSync(
+    "git",
+    [
+      "-C",
+      repo || ".",
+      "-c",
+      "core.quotePath=false",
+      "diff",
+      "--no-ext-diff",
+      "--no-color",
+      "--no-textconv",
+      "--src-prefix=a/",
+      "--dst-prefix=b/",
+      range,
+      "--",
+    ],
+    { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 30_000 },
+  );
+}
+
 function readText(path) {
   return path === "-" ? readFileSync(0, "utf-8") : readFileSync(path, "utf-8");
 }
 
+const INDENT_SENSITIVE = /(\.(py|pyi|ya?ml|coffee|haml|slim|pug)|(^|\/)(GNU)?[Mm]akefile)$/;
+
+const LINE_COMMENT = /(\.(py|pyi|ya?ml|sh|bash|zsh|rb|toml|coffee)|(^|\/)(GNU)?[Mm]akefile)$/;
+// Languages where a space next to a bracket, comma, semicolon or colon never
+// carries meaning. YAML, shell, Makefile and CSS are left out on purpose.
+const TIGHT_LANGS =
+  /\.(js|jsx|mjs|cjs|ts|tsx|java|go|cs|swift|kt|kts|json|rs|dart|scala|py|pyi|c|h|cc|cpp|hpp|m|mm)$/;
+const LEADING_OPERATOR_LANGS = /\.(kt|kts|swift|go|scala)$/;
+const BREAK_KEEPERS = /\b(return|throw|yield|break|continue)$/;
+const LEADING_OPERATOR = /^[+\-*/%&|^.?]/;
+const TIGHT = /\s*([(){}[\],;:])\s*/g;
+
+/** One line with string literals and comments verbatim and every other whitespace run as one space. */
+function foldLine(line, hashComments) {
+  const out = [];
+  let quote = null;
+  let gap = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      out.push(c);
+      if (c === "\\") out.push(line[++i] ?? "");
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === " " || c === "\t" || c === "\r") {
+      gap = true;
+      continue;
+    }
+    if (gap && out.length) out.push(" ");
+    gap = false;
+    if ((c === "/" && line[i + 1] === "/") || (hashComments && c === "#")) {
+      out.push(line.slice(i));
+      break;
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c;
+    out.push(c);
+  }
+  return out.join("");
+}
+
+/**
+ * The layout-free form of some lines. Each line is folded on its own (linear
+ * in the hunk), then the lines are joined by a space, except that a break
+ * after return, throw, yield, break or continue, and in Kotlin, Swift, Go or
+ * Scala a break before a leading operator, stays a break. Space next to
+ * brackets, commas, semicolons and colons is dropped only in TIGHT_LANGS, and
+ * never in a hunk that holds a C preprocessor line.
+ */
+function outsideStrings(text, file = "") {
+  const hashComments = LINE_COMMENT.test(file);
+  const lines = text.split("\n").map((l) => foldLine(l, hashComments));
+  let joined = "";
+  lines.forEach((line, i) => {
+    if (i === 0) {
+      joined = line;
+      return;
+    }
+    const keepBreak =
+      BREAK_KEEPERS.test(lines[i - 1]) ||
+      (LEADING_OPERATOR_LANGS.test(file) && LEADING_OPERATOR.test(line));
+    joined += (keepBreak ? "\u23ce" : " ") + line;
+  });
+  const preprocessor = lines.some((l) => l.startsWith("#")) && !hashComments;
+  const tight = TIGHT_LANGS.test(file) && !preprocessor;
+  return (tight ? joined.replace(TIGHT, "$1") : joined).trim();
+}
+
+const indentOf = (line) => /^[ \t]*/.exec(line)[0];
+
+/** True when the removed and added lines differ only in layout. */
+function layoutOnly(file, removed, added) {
+  if (!removed.length || !added.length) return false;
+  if (INDENT_SENSITIVE.test(file)) {
+    if (removed.length !== added.length) return false;
+    return removed.every(
+      (r, i) =>
+        indentOf(r.text) === indentOf(added[i].text) &&
+        outsideStrings(r.text, file) === outsideStrings(added[i].text, file),
+    );
+  }
+  const joined = (lines) => outsideStrings(lines.map((d) => d.text).join("\n"), file);
+  return joined(removed) === joined(added);
+}
+
+/**
+ * Hunks of a unified diff whose change is layout only: whitespace outside
+ * string literals, and in indentation-sensitive files never a leading indent.
+ */
+export function formatOnlyHunks(patch) {
+  const found = [];
+  for (const [file, diff] of parseUnifiedDiff(patch)) {
+    for (const h of diff.hunks) {
+      if (!h.removed.length && !h.added.length) continue;
+      if (layoutOnly(file, h.removed, h.added)) {
+        found.push({ file: normalizeFile(file), hunk: h.header });
+      }
+    }
+  }
+  return found;
+}
+
 export function evaluate(check, diffFiles) {
   const files = Array.isArray(check?.files) ? check.files : [];
   const reasons = new Map();
@@ -81,6 +219,15 @@ function main() {
     return fail;
   }
   const result = evaluate(check, diffFiles);
+  if (opts.patch || opts.patchRange) {
+    try {
+      const patch = opts.patch ? readText(opts.patch) : rangeDiff(opts.repo, opts.patchRange);
+      result.formatOnly = formatOnlyHunks(patch);
+    } catch (err) {
+      result.formatOnly = [];
+      result.patchError = err.message;
+    }
+  }
   process.stdout.write(JSON.stringify(result) + "\n");
   return result.ok ? 0 : fail;
 }