@brainervirus/workit-core 8.23.0 → 8.24.0

package/src/core/policy/substance.ts

@@ -0,0 +1,365 @@
+// Is a changed file cosmetic (#333, review finding mvkcoxgb)? Each side of
+// the file is reduced to its substance by a small lexer that knows the
+// file's strings and comments: comments drop out, whitespace outside strings
+// is normalized, strings stay verbatim. Equal substance on both sides is a
+// cosmetic change. The lexer fails closed: a syntax it does not know keeps
+// its comments, an indentation-sensitive or unknown type keeps all but
+// trailing whitespace, and anything it cannot read (invalid UTF-8, a NUL
+// byte, an unterminated string or comment, a regex across lines) is
+// substantive. Languages it would read wrongly stay unlexed (C-family, Rust,
+// SQL, shell, Ruby, YAML): only trailing whitespace is cosmetic there.
+
+type Syntax = {
+  /** Line comment openers. */
+  line: readonly string[];
+  /** Block comment delimiters (not nested). */
+  block: readonly (readonly [string, string])[];
+  /** String quotes with backslash escapes. */
+  quotes: string;
+  /** String quotes without escapes (TOML literal strings). */
+  literal?: string;
+  /** `"""` and `'''` strings. */
+  triple?: boolean;
+  /** JavaScript template literals with `${}` and regex literals. */
+  js?: boolean;
+  /** Go raw strings in backticks. */
+  rawBacktick?: boolean;
+  /** Strings may span lines. */
+  multiline?: boolean;
+  /** Python: an f-string with an unbalanced `{` holds a nested string this cannot read. */
+  fstring?: boolean;
+  /** CSS: an unquoted `url(` body is no string or comment this can read. */
+  cssUrl?: boolean;
+  /** Only trailing whitespace is cosmetic (indentation matters). */
+  indented?: boolean;
+};
+
+const SLASH_BLOCK = [["/*", "*/"]] as const;
+const C_LIKE: Syntax = { line: ["//"], block: SLASH_BLOCK, quotes: `"'` };
+const SYNTAXES: Record<string, Syntax> = Object.fromEntries([
+  // Not jsx or tsx: JSX text (`don't`, `</a>`) is no lexable string or regex.
+  ...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => [ext, { ...C_LIKE, js: true }]),
+  ...["java", "kt", "kts", "scala", "swift", "dart", "groovy"].map((ext) => [
+    ext,
+    { ...C_LIKE, triple: true },
+  ]),
+  ["go", { ...C_LIKE, rawBacktick: true }],
+  ...["css", "scss", "less"].map((ext) => [
+    ext,
+    { line: [], block: SLASH_BLOCK, quotes: `"'`, cssUrl: true },
+  ]),
+  ...["py", "pyi"].map((ext) => [
+    ext,
+    { line: ["#"], block: [], quotes: `"'`, triple: true, indented: true, fstring: true },
+  ]),
+  ["toml", { line: ["#"], block: [], quotes: `"`, literal: "'", triple: true }],
+  ...["html", "htm", "xml", "svg", "xhtml"].map((ext) => [
+    ext,
+    // Text and <pre> whitespace can matter: only trailing whitespace is cosmetic.
+    { line: [], block: [["<!--", "-->"]], quotes: "", indented: true },
+  ]),
+]);
+
+/** Comments that steer a compiler, linter, bundler or runtime are code. */
+const DIRECTIVE =
+  /@ts-|eslint|prettier|biome|oxlint|istanbul|\bc8\b|\bv8\b|@jsx|@flow|@vite|webpack|__PURE__|__NO_SIDE_EFFECTS__|source(?:Mapping)?URL|^\/\s*<|go:|\+build|nolint|noqa|type:|pyright|mypy|pylint|pragma|coding[:=]|fmt:|NOSONAR|@license|@preserve|@refresh|environment|language=|cython|ruff|isort|deno-|@vitest|@jest|swiftlint|ktlint|checkstyle|suppress|nullable|#(?:end)?region/iu;
+
+const extensionOf = (file: string): string => {
+  const name = file.slice(file.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+};
+
+/** CI and workflow definitions are read as written: their comments are never stripped. */
+const CI_PATH =
+  /^\.github\/|(?:^|\/)(?:\.gitlab-ci\.ya?ml|Jenkinsfile|azure-pipelines\.ya?ml|\.pre-commit-config\.ya?ml|\.circleci\/.*)$/u;
+
+/** The syntax `file` is lexed with; null keeps comments and all but trailing whitespace. */
+const syntaxOf = (file: string): Syntax | null =>
+  CI_PATH.test(file) ? null : (SYNTAXES[extensionOf(file)] ?? null);
+
+const SPACE = /[ \t\r\f\v]/u;
+const WORD = /[\w$]/u;
+const NO_SPACE_AFTER = "([{,;";
+const NO_SPACE_BEFORE = ")]},;";
+const REGEX_AFTER = "(,=:[!&|?{};+-*%<>~^";
+const REGEX_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "case",
+  "do",
+  "else",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "yield",
+  "await",
+]);
+
+type Frame = { kind: "code"; braces: number } | { kind: "template" };
+
+/**
+ * The substance of `text` for `file`: what stays after comments and
+ * insignificant whitespace are removed. Null when it cannot be read with
+ * certainty (the caller then counts the file as a behavior change).
+ */
+export function substanceOf(file: string, text: string): string | null {
+  const syntax = syntaxOf(file);
+  if (!syntax) return plainSubstance(text);
+  const markup = syntax.block.some(([open]) => open === "<!--");
+  // Markup with scripts, styles, CDATA or processing instructions holds
+  // other languages; a comment opener after anything but a tag end may sit
+  // in an attribute value.
+  if (
+    markup &&
+    (/<(?:script|style)\b|<!\[CDATA\[|<\?/iu.test(text) || /[^>\s][ \t]*<!--/u.test(text))
+  )
+    return plainSubstance(text);
+  return lex(syntax, text);
+}
+
+/** No lexer: only trailing whitespace and blank lines are cosmetic. */
+function plainSubstance(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => line.replace(/[ \t\r\f\v]+$/u, ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+function lex(syntax: Syntax, text: string): string | null {
+  const collapse = !syntax.indented;
+  let out = "";
+  let lineStart = 0;
+  /** Output before this index is string content: trailing-space trimming stops there. */
+  let kept = 0;
+  let pendingSpace = false;
+  const frames: Frame[] = [{ kind: "code", braces: 0 }];
+  let index = 0;
+
+  // A shebang line is code, read as written.
+  if (text.startsWith("#!")) {
+    const end = text.indexOf("\n");
+    out = end < 0 ? text : text.slice(0, end);
+    kept = out.length;
+    index = end < 0 ? text.length : end;
+  }
+
+  const emitCode = (chunk: string) => {
+    if (collapse && pendingSpace && out.length > lineStart) {
+      const before = out[out.length - 1];
+      if (!NO_SPACE_AFTER.includes(before) && !NO_SPACE_BEFORE.includes(chunk[0])) out += " ";
+    }
+    pendingSpace = false;
+    out += chunk;
+  };
+  const emitVerbatim = (chunk: string) => {
+    emitCode(chunk);
+    kept = out.length;
+  };
+  const newline = () => {
+    if (!collapse) {
+      let end = out.length;
+      while (end > Math.max(lineStart, kept) && SPACE.test(out[end - 1])) end -= 1;
+      out = out.slice(0, end);
+    }
+    pendingSpace = false;
+    if (out.length > lineStart) {
+      out += "\n";
+      lineStart = out.length;
+    }
+  };
+  /** Can a `/` start a regex here? After an operator or a keyword, not after a value. */
+  const regexAllowed = (): boolean => {
+    let end = out.length;
+    while (end > 0 && /\s/u.test(out[end - 1])) end -= 1;
+    if (end === 0 || REGEX_AFTER.includes(out[end - 1])) return true;
+    let start = end;
+    while (start > 0 && WORD.test(out[start - 1])) start -= 1;
+    return REGEX_KEYWORDS.has(out.slice(start, end));
+  };
+  /** Scan a quoted string from `index`; returns false when it does not close. */
+  const scanString = (quote: string, escapes: boolean, multiline: boolean): boolean => {
+    const prefix = text.slice(Math.max(0, index - 2), index).match(/[a-z]*$/iu)?.[0] ?? "";
+    const fstring = syntax.fstring === true && /f/iu.test(prefix);
+    let end = index + quote.length;
+    while (end < text.length) {
+      const char = text[end];
+      if (escapes && char === "\\") {
+        end += 2;
+        continue;
+      }
+      if (text.startsWith(quote, end)) {
+        if (fstring && unbalanced(text.slice(index + quote.length, end))) return false;
+        emitVerbatim(text.slice(index, end + quote.length));
+        index = end + quote.length;
+        return true;
+      }
+      if (char === "\n" && !multiline) return false;
+      end += 1;
+    }
+    return false;
+  };
+
+  while (index < text.length) {
+    const frame = frames[frames.length - 1];
+    const char = text[index];
+    if (frame.kind === "template") {
+      if (char === "\\") {
+        emitVerbatim(text.slice(index, index + 2));
+        index += 2;
+      } else if (char === "`") {
+        emitVerbatim(char);
+        frames.pop();
+        index += 1;
+      } else if (text.startsWith("${", index)) {
+        emitVerbatim("${");
+        frames.push({ kind: "code", braces: 0 });
+        index += 2;
+      } else {
+        // Template text, newlines included, is the string's value.
+        out += char;
+        kept = out.length;
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "\n") {
+      newline();
+      index += 1;
+      continue;
+    }
+    if (SPACE.test(char)) {
+      if (collapse) pendingSpace = true;
+      else out += char;
+      index += 1;
+      continue;
+    }
+    const lineOpener = syntax.line.find((opener) => text.startsWith(opener, index));
+    if (lineOpener) {
+      const end = text.indexOf("\n", index);
+      const comment = text.slice(index, end < 0 ? text.length : end);
+      if (DIRECTIVE.test(comment.slice(lineOpener.length))) emitVerbatim(comment);
+      else pendingSpace = true;
+      index = end < 0 ? text.length : end;
+      continue;
+    }
+    const block = syntax.block.find(([open]) => text.startsWith(open, index));
+    if (block) {
+      const end = text.indexOf(block[1], index + block[0].length);
+      if (end < 0) return null;
+      const comment = text.slice(index, end + block[1].length);
+      if (DIRECTIVE.test(comment.slice(block[0].length, -block[1].length))) emitVerbatim(comment);
+      else pendingSpace = true;
+      // A newline inside the comment still ends the code line before it.
+      if (comment.includes("\n")) newline();
+      index = end + block[1].length;
+      continue;
+    }
+    if (syntax.triple && (char === '"' || char === "'") && text.startsWith(char.repeat(3), index)) {
+      if (!scanString(char.repeat(3), !syntax.literal?.includes(char), true)) return null;
+      continue;
+    }
+    if (syntax.quotes.includes(char)) {
+      if (!scanString(char, true, Boolean(syntax.multiline))) return null;
+      continue;
+    }
+    if (syntax.literal?.includes(char)) {
+      if (!scanString(char, false, false)) return null;
+      continue;
+    }
+    if (syntax.rawBacktick && char === "`") {
+      if (!scanString("`", false, true)) return null;
+      continue;
+    }
+    if (syntax.js && char === "`") {
+      emitVerbatim(char);
+      frames.push({ kind: "template" });
+      index += 1;
+      continue;
+    }
+    if (syntax.cssUrl && /^url\(\s*[^"')\s]/iu.test(text.slice(index, index + 64))) return null;
+    if (syntax.js && char === "/" && !regexAllowed() && out.trimEnd().endsWith(")")) {
+      // Division after `)` may be a regex after `if (x)`: with another `/` on
+      // the line the two readings differ on what is code, so give up.
+      const lineEnd = text.indexOf("\n", index);
+      if (text.slice(index + 1, lineEnd < 0 ? text.length : lineEnd).includes("/")) return null;
+    }
+    if (syntax.js && char === "/" && regexAllowed()) {
+      let end = index + 1;
+      let inClass = false;
+      while (end < text.length && (inClass || text[end] !== "/")) {
+        if (text[end] === "\n") return null;
+        if (text[end] === "\\") end += 1;
+        else if (text[end] === "[") inClass = true;
+        else if (text[end] === "]") inClass = false;
+        end += 1;
+      }
+      if (end >= text.length) return null;
+      emitVerbatim(text.slice(index, end + 1));
+      index = end + 1;
+      continue;
+    }
+    if (frames.length > 1 && frame.kind === "code") {
+      if (char === "{") frame.braces += 1;
+      else if (char === "}") {
+        if (frame.braces === 0) {
+          emitVerbatim(char);
+          frames.pop();
+          index += 1;
+          continue;
+        }
+        frame.braces -= 1;
+      }
+    }
+    emitCode(char);
+    index += 1;
+  }
+  if (frames.length !== 1) return null;
+  newline();
+  return out;
+}
+
+/** Does an f-string body hold a `{` that never closes, once `{{` and `}}` are set aside? */
+function unbalanced(body: string): boolean {
+  let depth = 0;
+  for (const part of body.replaceAll("{{", "").replaceAll("}}", "")) {
+    if (part === "{") depth += 1;
+    else if (part === "}") depth = Math.max(0, depth - 1);
+  }
+  return depth > 0;
+}
+
+/**
+ * A lone CR (not followed by LF), U+2028 or U+2029: some readers end a line
+ * there and others do not, so a comment can hide code from one of them.
+ */
+export function hasOpaqueLineBreak(text: string): boolean {
+  return /\r(?!\n)|[\u2028\u2029]/u.test(text);
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** The UTF-8 text of `bytes`, or null for binary (a NUL byte) or invalid UTF-8. */
+export function textOf(bytes: Uint8Array): string | null {
+  if (bytes.includes(0)) return null;
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** Is the change from `before` to `after` of `file` cosmetic (equal substance)? */
+export function cosmeticChange(file: string, before: Uint8Array, after: Uint8Array): boolean {
+  const left = textOf(before);
+  const right = textOf(after);
+  if (left === null || right === null) return false;
+  if (hasOpaqueLineBreak(left) || hasOpaqueLineBreak(right)) return false;
+  const a = substanceOf(file, left);
+  return a !== null && a === substanceOf(file, right);
+}

package/src/core/workspaces.ts

@@ -142,7 +142,7 @@ const workspaceConfigSchema = z
      */
     defaultEndpoint: z.unknown().optional(),
     /** How a normal-risk behavior change is verified (S17); same rules as grants. */
-    verification: z.enum(["self", "independent"]).optional(),
+    verification: z.enum(["proportional", "self", "independent"]).optional(),
     /**
      * Who does the work (skills and `fanout plan` read it): `inline-first`
      * (default) keeps the lead working itself and refuses a slice without a

package/src/forge/pr-ops.ts

@@ -24,6 +24,7 @@ import {
   resolveAutonomy,
   type AutonomySource,
   type DefaultEndpoint,
+  type VerificationMode,
 } from "../autonomy";
 import { branchKindOf, flowRoute, gitFlowOf, isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
@@ -40,6 +41,8 @@ import {
   type LedgerActor,
   type VerdictCheck,
 } from "../ledger";
+import type { LaneNeed, ReviewLane } from "../core/policy/lane";
+import { laneLabel, prLaneGate } from "../core/policy/pr-lane";
 import { buildStatusDoc, selectPr, type PrStatusDoc } from "./report";
 import type { ResolvedForge } from "./resolve";
 import { failure, success, type ForgeResult, type MergeMethod, type PrRef } from "./types";
@@ -361,7 +364,22 @@ export type MergeOutcome = {
   head: string;
   method: MergeMethod;
   mergeSha: string | null;
-  verdict: { required: boolean; accepted: boolean; verdictId: string | null };
+  /**
+   * `required`: the gate asked for a verdict (false under lane none or a
+   * bypass); `accepted`: an accepted independent verdict covers the head;
+   * `verdictId`: the verdict the merge relied on (the author's own under lane
+   * self, shown as self-reviewed); `lane`/`need`: the review lane and what it
+   * asked (`need` is non-author outside `verification: proportional`).
+   */
+  verdict: {
+    required: boolean;
+    accepted: boolean;
+    verdictId: string | null;
+    review: "verified" | "self-reviewed" | "none";
+    lane: ReviewLane;
+    need: LaneNeed;
+    verification: VerificationMode;
+  };
   /** Set when `--unverified` bypassed the verdict: the reason and its ledger row. */
   unverified: { reason: string; recorded: string } | null;
   grant: { source: AutonomySource };
@@ -645,13 +663,24 @@ export async function mergePullRequest(
   const ledger = readLedger(cwd, { integrity: true });
   if (!ledger.ok) return ledger;
   const check = checkVerdicts(cwd, branch, ledger.value.rows);
-  const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
-  const covered = check.head === head && check.accepted.accepted;
+  const gate = prLaneGate(cwd, check, { branch, base: doc.base, head });
+  const summary = {
+    head: check.head,
+    accepted: check.accepted,
+    authors: check.authors,
+    lane: gate.lane.lane,
+    need: gate.need,
+  };
+  // Lane none needs no verdict, so no verdict head either.
+  const covered = gate.satisfied && (gate.need === "none" || check.head === head);
   let verdict: MergeOutcome["verdict"] = {
-    required: true,
-    accepted: covered,
-    verdictId:
-      covered && typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null,
+    required: gate.need !== "none",
+    accepted: check.head === head && check.accepted.accepted,
+    verdictId: covered ? gate.verdictId : null,
+    review: covered ? gate.review : "none",
+    lane: gate.lane.lane,
+    need: gate.need,
+    verification: gate.verification,
   };
   let unverified: MergeOutcome["unverified"] = null;
   // The bypass covers a missing verdict, never a rejection.
@@ -679,9 +708,9 @@ export async function mergePullRequest(
         "failed",
         `unverified_unrecorded: the --unverified bypass could not be recorded (${recorded.error}); nothing was merged`,
       );
-    verdict = { required: false, accepted: false, verdictId: null };
+    verdict = { ...verdict, required: false, accepted: false, verdictId: null, review: "none" };
     unverified = { reason, recorded: String(recorded.value.id) };
-  } else if (check.head !== head)
+  } else if (!covered && check.head !== head)
     return refuse(
       `head_mismatch: the verdict check reads ${branch} at ${check.head?.slice(0, 12) ?? "(missing)"} but ${label} is at ${head.slice(0, 12)}`,
       `git fetch && git switch ${branch} && git merge --ff-only @{u}  # then re-verify that head`,
@@ -693,12 +722,21 @@ export async function mergePullRequest(
       tamperedUnblock(cwd),
       { reason: "ledger_tampered", verdict: summary },
     );
-  else if (!covered)
+  else if (!covered) {
+    const bypassHint = grant.allowUnverified
+      ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"`
+      : "";
+    const lane = gate.verification === "proportional" ? `, ${laneLabel(gate)}` : "";
     return refuse(
-      `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)} (${check.accepted.reasons.join(", ")})`,
-      `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${grant.allowUnverified ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"` : ""}`,
+      gate.need === "self"
+        ? `NEEDS_VERDICT: ${label} has no verdict for ${head.slice(0, 12)}${lane}: the author's own --self verdict is enough (${check.accepted.reasons.join(", ")})`
+        : `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)}${lane} (${check.accepted.reasons.join(", ")})`,
+      gate.need === "self"
+        ? `after an observed passing \`workit check test\`, the author runs: workit ledger verdict tests-verified --self --how "<what you ran>" --branch ${branch} (or a verifier records one)${bypassHint}`
+        : `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${bypassHint}`,
       { reason: "needs_verdict", verdict: summary },
     );
+  }
 
   const squashMessage = squashMessageFor(cwd, resolved, input, doc);
   if (squashMessage && !squashMessage.ok) return squashMessage;
@@ -714,6 +752,8 @@ export async function mergePullRequest(
     base: doc.base,
     method: input.method,
     verdictId: verdict.verdictId,
+    review: verdict.review,
+    lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
   });
@@ -747,6 +787,8 @@ export async function mergePullRequest(
     mergeSha: merged.data.mergeSha,
     method: input.method,
     verdictId: verdict.verdictId,
+    review: verdict.review,
+    lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
     intent: intentId,

package/src/forge/report.ts

@@ -428,7 +428,7 @@ export function buildStatusDoc(
 
 /**
  * Record what the forge said about a PR as a CLI-observed `pr.status` row
- * (pr, branch, head, state: open|merged|closed, checks), only when it
+ * (pr, branch, head, base, state: open|merged|closed, checks), only when it
  * differs from the newest row for that PR, so polling never floods the
  * ledger. Hooks read it without calling the forge: an open PR's checks
  * (passing|failing|pending; one without gating checks is not recorded), and
@@ -455,7 +455,8 @@ export function recordPrStatus(cwd: string, doc: PrStatusDoc, actor: LedgerActor
       last &&
       last.head === doc.head.sha &&
       last.checks === checks &&
-      (last.state ?? "open") === state
+      (last.state ?? "open") === state &&
+      (last.base ?? null) === (doc.base ?? null)
     )
       return;
     appendObserved(cwd, {
@@ -468,6 +469,7 @@ export function recordPrStatus(cwd: string, doc: PrStatusDoc, actor: LedgerActor
       forge: doc.forge,
       state,
       checks,
+      base: doc.base,
     });
   } catch {
     // The row is an observation for hooks; the verb's answer stands without it.

package/src/git/rev.ts

@@ -515,6 +515,139 @@ export function resolveRef(cwd: string, ref: string): string | null {
   return line(git(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]));
 }
 
+/** Pinned diff options for the review-lane reads: user config never changes them. */
+const LANE_DIFF = [
+  "-c",
+  "core.quotePath=false",
+  "diff",
+  "--no-color",
+  "--no-ext-diff",
+  "--no-textconv",
+  "--no-renames",
+];
+
+/** `fork..head`, or with `head` null the working tree's tracked changes since `fork`. */
+const laneRange = (fork: string, head: string | null): string[] | null => {
+  if (!safeArg(fork) || (head !== null && !safeArg(head))) return null;
+  return head === null ? [fork] : [fork, head];
+};
+
+export type NumstatEntry = { path: string; added: number; deleted: number; binary: boolean };
+
+/** Added and deleted lines per file of `fork..head` (no renames); null when git fails. */
+export function diffNumstat(cwd: string, fork: string, head: string | null): NumstatEntry[] | null {
+  const range = laneRange(fork, head);
+  if (!range) return null;
+  const run = git(cwd, [...LANE_DIFF, "--numstat", "-z", ...range, "--"]);
+  if (!run.ok) return null;
+  const out: NumstatEntry[] = [];
+  for (const record of run.stdout.split("\0")) {
+    const match = /^(-|\d+)\t(-|\d+)\t(.+)$/su.exec(record.replace(/^\n/u, ""));
+    if (!match) continue;
+    const binary = match[1] === "-";
+    out.push({
+      path: match[3],
+      added: binary ? 0 : Number(match[1]),
+      deleted: binary ? 0 : Number(match[2]),
+      binary,
+    });
+  }
+  return out;
+}
+
+/** One file of `git diff --raw`: modes and blob ids on each side (zeros: absent or the working tree). */
+export type RawEntry = {
+  path: string;
+  oldMode: string;
+  newMode: string;
+  oldBlob: string;
+  newBlob: string;
+};
+
+/**
+ * The changed files of `fork..head` (or the working tree) with their modes
+ * and blob ids, read NUL-separated so no path is ever quoted or split.
+ * Null when git fails.
+ */
+export function diffRaw(cwd: string, fork: string, head: string | null): RawEntry[] | null {
+  const range = laneRange(fork, head);
+  if (!range) return null;
+  const run = git(cwd, [...LANE_DIFF, "--raw", "-z", "--no-abbrev", ...range, "--"]);
+  if (!run.ok) return null;
+  const fields = run.stdout.split("\0");
+  const out: RawEntry[] = [];
+  for (let index = 0; index + 1 < fields.length; index += 2) {
+    const meta = /^:(\d{6}) (\d{6}) ([0-9a-f]+) ([0-9a-f]+) [A-Z]\d*$/u.exec(
+      fields[index].replace(/^\n/u, ""),
+    );
+    if (!meta) return null;
+    out.push({
+      path: fields[index + 1],
+      oldMode: meta[1],
+      newMode: meta[2],
+      oldBlob: meta[3],
+      newBlob: meta[4],
+    });
+  }
+  return out;
+}
+
+/** The contents of `ids` (blob ids), by id; null when git fails. Missing objects are left out. */
+export function readBlobs(cwd: string, ids: readonly string[]): Map<string, Buffer> | null {
+  const out = new Map<string, Buffer>();
+  const wanted = [...new Set(ids)].filter((id) => /^[0-9a-f]{40,64}$/u.test(id));
+  if (!wanted.length) return out;
+  const run = spawnSync("git", ["cat-file", "--batch"], {
+    cwd,
+    input: `${wanted.join("\n")}\n`,
+    maxBuffer: MAX_BUFFER,
+    timeout: GIT_TIMEOUTS.local,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+  });
+  if (run.status !== 0 || !run.stdout) return null;
+  const bytes = run.stdout;
+  let at = 0;
+  for (const id of wanted) {
+    const end = bytes.indexOf(0x0a, at);
+    if (end < 0) return null;
+    const header = bytes.subarray(at, end).toString("utf8").split(" ");
+    at = end + 1;
+    if (header[1] === "missing") continue;
+    const size = Number(header[2]);
+    if (header[0] !== id || !Number.isSafeInteger(size)) return null;
+    out.set(id, bytes.subarray(at, at + size));
+    at += size + 1;
+  }
+  return out;
+}
+
+/** Blob ids of the files named `name` anywhere in the tree of `rev`, by path; null when git fails. */
+export function treeFilesNamed(cwd: string, rev: string, name: string): Map<string, string> | null {
+  if (!safeArg(rev)) return null;
+  const run = git(cwd, ["ls-tree", "-r", "-z", "--full-tree", rev]);
+  if (!run.ok) return null;
+  const out = new Map<string, string>();
+  for (const record of run.stdout.split("\0")) {
+    const match = /^\d{6} blob ([0-9a-f]+)\t(.+)$/su.exec(record);
+    if (match && (match[2] === name || match[2].endsWith(`/${name}`))) out.set(match[2], match[1]);
+  }
+  return out;
+}
+
+/** The text of `file` (a fixed repo path) at `rev`; null when it is absent or git fails. */
+export function fileAt(cwd: string, rev: string, file: string): string | null {
+  if (!safeArg(rev)) return null;
+  const run = git(cwd, ["cat-file", "blob", `${rev}:${file}`]);
+  return run.ok ? run.stdout : null;
+}
+
+/** Untracked, not ignored files of the working tree (repo-relative). */
+export function untrackedFiles(cwd: string): string[] {
+  const run = git(cwd, ["ls-files", "-z", "--others", "--exclude-standard"]);
+  return run.ok ? run.stdout.split("\0").filter(Boolean) : [];
+}
+
 /**
  * Commits `head` lacks from `base` (behind) and has on top of it (ahead), and
  * whether `base` is already an ancestor of `head`. Null when either side