@intentius/chant 0.95.1 → 0.96.0

package/src/workspace/patch.test.ts

@@ -0,0 +1,198 @@
+/**
+ * The patch read, on a workspace one directory down in its repository, with a
+ * work branch the way the factory leaves one (`chant/work/<id>`) and a main
+ * branch that moved on after the branch was cut:
+ *
+ * - m0, the root commit, adds the workspace, app/server.mjs, app/old.mjs,
+ *   docs/claims.md and a file outside the workspace.
+ * - w1 and w2, on chant/work/W-001, edit app/server.mjs, rename app/old.mjs
+ *   to app/new.mjs, add a binary file and add docs/more.md.
+ * - m1, on main after the cut, edits docs/claims.md.
+ */
+
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { formatPatch, workspacePatch, type PatchDocument, type PatchFile } from "./patch";
+import patchSchema from "./patch.schema.json";
+
+let top: string;
+let ws: string;
+const sha: Record<string, string> = {};
+
+const SERVER = Array.from({ length: 40 }, (_, i) => `export const line${i} = ${i};`).join("\n") + "\n";
+const SERVER_2 = SERVER.replace("line3 = 3", "line3 = 33").replace("line30 = 30", "line30 = 300");
+const OLD = "// moved, not changed\nexport const a = 1;\nexport const b = 2;\nexport const c = 3;\n";
+
+function commit(message: string): string {
+  git(top, "add", "-A");
+  git(top, "commit", "-q", "-m", message);
+  return git(top, "rev-parse", "HEAD");
+}
+
+beforeAll(() => {
+  top = repo({
+    "ws/chant.workspace.json": JSON.stringify({ name: "studio", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "a server" }] }),
+    "ws/app/server.mjs": SERVER,
+    "ws/app/old.mjs": OLD,
+    "ws/docs/claims.md": "# Claims\n",
+    "outside.txt": "not in the workspace\n",
+  });
+  ws = join(top, "ws");
+  git(top, "symbolic-ref", "HEAD", "refs/heads/main");
+  sha.m0 = commit("the workspace");
+  git(top, "checkout", "-q", "-b", "chant/work/W-001");
+  writeFiles(top, { "ws/app/server.mjs": SERVER_2, "outside.txt": "changed outside\n" });
+  git(top, "mv", "ws/app/old.mjs", "ws/app/new.mjs");
+  sha.w1 = commit("edit the server and move old to new");
+  writeFiles(top, { "ws/app/logo.bin": { text: "\u0000\u0001\u0002binary\u0000", mode: 0o644 }, "ws/docs/more.md": "More.\n" });
+  sha.w2 = commit("a logo and more docs");
+  git(top, "checkout", "-q", "main");
+  writeFiles(top, { "ws/docs/claims.md": "# Claims\n\nOne.\n" });
+  sha.m1 = commit("a claim on main");
+});
+afterAll(cleanScratch);
+
+const { expectValid } = contract(patchSchema);
+type Result = Exclude<PatchDocument, { error: unknown }>;
+
+async function patch(range: string, options: { paths?: string[]; maxBytes?: number; worktree?: boolean } = {}): Promise<Result> {
+  const { doc } = await workspacePatch({ cwd: ws, range, ...options });
+  expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const summary = (f: PatchFile) => [f.change, f.path, f.from, f.additions, f.deletions, f.hunkCount, f.truncated];
+
+describe("workspace patch", () => {
+  test("a work branch from its merge base: each file under the workspace root, with renames, binaries and hunks", async () => {
+    const doc = await patch("main...chant/work/W-001");
+    expect(doc.range).toEqual({ spec: "main...chant/work/W-001", form: "merge-base", base: sha.m0, head: sha.w2 });
+    expect(doc.workspace).toEqual({ name: "studio", root: "ws" });
+    expect(doc.paths).toEqual([]);
+    expect(doc.limits).toEqual({ fileBytes: 65536, totalBytes: 1048576 });
+    expect(doc.files.map(summary)).toEqual([
+      ["added", "app/logo.bin", null, null, null, 0, false],
+      ["renamed", "app/new.mjs", "app/old.mjs", 0, 0, 0, false],
+      ["modified", "app/server.mjs", null, 2, 2, 2, false],
+      ["added", "docs/more.md", null, 1, 0, 1, false],
+    ]);
+    expect(doc.files[0].binary).toBe(true);
+    const server = doc.files[2];
+    expect(server.hunks.map((h) => [h.oldStart, h.oldLines, h.newStart, h.newLines])).toEqual([
+      [1, 7, 1, 7],
+      [28, 7, 28, 7],
+    ]);
+    expect(server.hunks[0].header).toBe("@@ -1,7 +1,7 @@");
+    expect(server.hunks[0].lines.filter((l) => /^[+-]/.test(l))).toEqual(["-export const line3 = 3;", "+export const line3 = 33;"]);
+    expect(doc.files[3].hunks).toEqual([{ header: "@@ -0,0 +1 @@", oldStart: 0, oldLines: 0, newStart: 1, newLines: 1, lines: ["+More."] }]);
+    expect(doc.summary).toEqual({ files: 4, additions: 3, deletions: 2, truncated: false });
+  });
+
+  test("two dots compare the trees as they are, so main's later edit shows as undone", async () => {
+    const doc = await patch("main..chant/work/W-001");
+    expect(doc.range.form).toBe("range");
+    expect(doc.range.base).toBe(sha.m1);
+    const claims = doc.files.find((f) => f.path === "docs/claims.md")!;
+    expect(claims.hunks[0].lines).toEqual([" # Claims", "-", "-One."]);
+  });
+
+  test("one commit reads against its first parent, and a root commit against the empty tree", async () => {
+    const w2 = await patch(sha.w2);
+    expect(w2.range).toEqual({ spec: sha.w2, form: "commit", base: sha.w1, head: sha.w2 });
+    expect(w2.files.map((f) => f.path)).toEqual(["app/logo.bin", "docs/more.md"]);
+    const m0 = await patch(sha.m0);
+    expect(m0.range.base).toBe("4b825dc642cb6eb9a060e54bf8d69288fbee4904");
+    expect(m0.files.map((f) => [f.change, f.path])).toEqual([
+      ["added", "app/old.mjs"],
+      ["added", "app/server.mjs"],
+      ["added", "chant.workspace.json"],
+      ["added", "docs/claims.md"],
+    ]);
+  });
+
+  test("--path keeps a file, or everything under a directory", async () => {
+    expect((await patch("main...chant/work/W-001", { paths: ["docs"] })).files.map((f) => f.path)).toEqual(["docs/more.md"]);
+    const one = await patch("main...chant/work/W-001", { paths: ["app/server.mjs", "docs/"] });
+    expect(one.paths).toEqual(["app/server.mjs", "docs"]);
+    expect(one.files.map((f) => f.path)).toEqual(["app/server.mjs", "docs/more.md"]);
+  });
+
+  test("a file's hunk text stops at maxBytes, mid-hunk if it must, and says so", async () => {
+    const doc = await patch(sha.w1, { paths: ["app/server.mjs"], maxBytes: 200 });
+    const f = doc.files[0];
+    expect(f.truncated).toBe(true);
+    expect(f.hunkCount).toBe(2);
+    expect(f.bytes).toBeGreaterThan(200);
+    const kept = f.hunks.reduce((n, h) => n + Buffer.byteLength(h.header) + 1 + h.lines.reduce((m, l) => m + Buffer.byteLength(l) + 1, 0), 0);
+    expect(kept).toBeLessThanOrEqual(200);
+    expect(f.hunks.length).toBe(1);
+    expect(f.hunks[0].lines.length).toBeLessThan(9);
+    expect(doc.summary.truncated).toBe(true);
+    expect(formatPatch(doc)).toContain("modified  app/server.mjs +2 -2; truncated, 1 of 2 hunks shown");
+  });
+
+  test("once every file's text passes the total, the files after it keep their counts and no hunks", async () => {
+    // Each file's hunk is 46 bytes: its 14-byte header and one 32-byte line. 800 bytes hold 17,
+    // then the 18th file's header, and nothing after.
+    const files = Object.fromEntries(Array.from({ length: 20 }, (_, i) => [`ws/many/f${String(i).padStart(2, "0")}.txt`, `${"x".repeat(30)}\n`]));
+    git(top, "checkout", "-q", "-b", "many", "main");
+    writeFiles(top, files);
+    const many = commit("twenty files");
+    git(top, "checkout", "-q", "main");
+    const doc = await patch(many, { maxBytes: 50 });
+    expect(doc.limits).toEqual({ fileBytes: 50, totalBytes: 800 });
+    expect(doc.files.map((f) => [f.hunks.length, f.truncated])).toEqual([...Array(17).fill([1, false]), [1, true], [0, true], [0, true]]);
+    expect(doc.files[17].hunks[0]).toMatchObject({ header: "@@ -0,0 +1 @@", lines: [] });
+    expect(doc.files.every((f) => f.additions === 1 && f.hunkCount === 1 && f.bytes === 46)).toBe(true);
+    expect(doc.summary.truncated).toBe(true);
+  });
+
+  test("--worktree reads the working tree against HEAD: edits staged or not, a deletion, and untracked files not ignored as added", async () => {
+    git(top, "checkout", "-q", "-b", "worktree", "main");
+    writeFiles(top, {
+      "ws/app/server.mjs": SERVER.replace("line5 = 5", "line5 = 55"),
+      "ws/docs/new.md": "# New\n\nTwo lines.\n",
+      "ws/.gitignore": "*.log\n",
+      "ws/debug.log": "ignored\n",
+      "outside-new.txt": "outside the workspace\n",
+    });
+    git(top, "add", "ws/.gitignore");
+    git(top, "rm", "-q", "ws/app/old.mjs");
+    try {
+      const doc = await patch("", { worktree: true });
+      expect(doc.range).toEqual({ spec: "", form: "worktree", base: sha.m1, head: null });
+      expect(doc.files.map(summary)).toEqual([
+        ["added", ".gitignore", null, 1, 0, 1, false],
+        ["deleted", "app/old.mjs", null, 0, 4, 1, false],
+        ["modified", "app/server.mjs", null, 1, 1, 1, false],
+        ["added", "docs/new.md", null, 3, 0, 1, false],
+      ]);
+      expect(doc.files[3].hunks).toEqual([{ header: "@@ -0,0 +1,3 @@", oldStart: 0, oldLines: 0, newStart: 1, newLines: 3, lines: ["+# New", "+", "+Two lines."] }]);
+      expect(doc.files[2].hunks[0].lines.filter((l) => /^[+-]/.test(l))).toEqual(["-export const line5 = 5;", "+export const line5 = 55;"]);
+      const one = await patch("HEAD", { worktree: true, paths: ["docs/new.md"] });
+      expect(one.files.map((f) => f.path)).toEqual(["docs/new.md"]);
+      expect(one.summary).toEqual({ files: 1, additions: 3, deletions: 0, truncated: false });
+      expect(formatPatch(one)).toContain("..worktree (HEAD, worktree)");
+      expect((await patch(sha.m0, { worktree: true, paths: ["docs/claims.md"] })).files.map((f) => [f.path, f.additions])).toEqual([["docs/claims.md", 2]]);
+    } finally {
+      git(top, "reset", "-q", "--hard");
+      git(top, "clean", "-qfdx");
+      git(top, "checkout", "-q", "main");
+    }
+  });
+
+  test("a revision that is no commit is revision-unknown, and a path outside the workspace patch-path-invalid", async () => {
+    for (const [range, paths, code] of [
+      ["main..nope", undefined, "revision-unknown"],
+      ["main...chant/work/W-001", ["../outside.txt"], "patch-path-invalid"],
+      ["main...chant/work/W-001", ["/etc"], "patch-path-invalid"],
+    ] as const) {
+      const { doc, failed } = await workspacePatch({ cwd: ws, range, paths: paths ? [...paths] : undefined });
+      expectValid(doc);
+      expect(failed).toBe(true);
+      expect("error" in doc && doc.error.code).toBe(code);
+    }
+  });
+});

package/src/workspace/patch.ts

@@ -0,0 +1,377 @@
+/**
+ * The hunks of a diff: `chant workspace patch <base>..<head>|<base>...<head>|<commit>
+ * [--path <p>...] [--max-bytes <n>] [--json]`, or `chant workspace patch [<commit>]
+ * --worktree` for the working tree's changes against a commit (HEAD unless given).
+ *
+ * `check --changes` maps the paths a diff changes to records and prints no
+ * lines of it. A reader showing what a work branch or a commit did needs the
+ * lines, and a reader that runs no git of its own (hud) gets them here. The
+ * range is read as `check --changes` reads one, except that a lone revision
+ * is that commit against its first parent, or against the empty tree for a
+ * root commit, since a reader drawing one commit wants that commit's change.
+ * With --worktree the head is the working tree as it is on disk: staged or
+ * not, and each untracked file git does not ignore, as added.
+ *
+ * Each changed file under the workspace root is listed, with renames
+ * followed, its added and deleted line counts, and its hunks. A file's hunk
+ * text stops at `maxBytes` (64 KiB unless given), and all files' together at
+ * sixteen times that; a file cut short, or left without hunks once the total
+ * is spent, says `truncated`. A binary file has counts of null and no hunks.
+ * Git is read through a local `git` subprocess only: no fetch, no network.
+ */
+
+import { execFileSync } from "node:child_process";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration";
+import { isWorkspacePath } from "./record-assets";
+import type { ReasonCode } from "./reason-codes";
+import { joinPath } from "./tree";
+import { locateWorkspace } from "./which-chant";
+
+/** The version of the `patch` document this chant writes. */
+export const PATCH_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const PATCH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/patch/v1/patch.schema.json";
+
+/** Why the read failed as a whole. */
+export const PATCH_ERROR_CODES = [
+  ...WORKSPACE_ERROR_CODES,
+  /** A --path is not a relative path inside the workspace. */
+  "patch-path-invalid",
+] as const satisfies readonly ReasonCode[];
+export type PatchErrorCode = (typeof PATCH_ERROR_CODES)[number];
+
+/** The hunk text one file gets unless `maxBytes` says otherwise. */
+export const PATCH_FILE_BYTES = 64 * 1024;
+
+/** The hunk text every file gets together, as a multiple of the per-file cap. */
+export const PATCH_TOTAL_FACTOR = 16;
+
+/** Git's empty tree, the base of a root commit. */
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+class PatchError extends Error {
+  constructor(
+    readonly code: PatchErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "PatchError";
+  }
+}
+
+export interface PatchHunk {
+  /** The `@@` line as git writes it. */
+  header: string;
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  /** Each line with its leading ` `, `+`, `-` or `\`, without its newline. Cut short when the file is truncated. */
+  lines: string[];
+}
+
+export interface PatchFile {
+  /** From the workspace root. */
+  path: string;
+  change: "added" | "modified" | "deleted" | "renamed" | "copied";
+  /** For a rename or a copy, the path it came from. */
+  from: string | null;
+  binary: boolean;
+  /** Lines added and deleted, as git counts them; null for a binary file. */
+  additions: number | null;
+  deletions: number | null;
+  /** How many hunks git wrote for the file; hunks may hold fewer when truncated. */
+  hunkCount: number;
+  /** The bytes of hunk text git wrote for the file, headers included, before any cut. */
+  bytes: number;
+  hunks: PatchHunk[];
+  /** Whether hunks holds less than git wrote. */
+  truncated: boolean;
+}
+
+interface Head {
+  $schema: string;
+  contract: number;
+  chant: string;
+}
+
+export type PatchDocument =
+  | (Head & {
+      workspace: { name: string; root: string };
+      /** What was asked, and the two commits compared. `form` says how the spec was read. */
+      /** head is null for the working tree (--worktree). */
+      range: { spec: string; form: "range" | "merge-base" | "commit" | "worktree"; base: string; head: string | null };
+      /** The --path filters, from the workspace root; empty for the whole workspace. */
+      paths: string[];
+      limits: { fileBytes: number; totalBytes: number };
+      files: PatchFile[];
+      summary: { files: number; additions: number; deletions: number; truncated: boolean };
+    })
+  | (Head & { error: { code: PatchErrorCode; message: string } });
+
+export interface PatchQuery {
+  cwd: string;
+  /** `<base>..<head>`, `<base>...<head>`, or one commit. */
+  range: string;
+  /** Paths from the workspace root: a file, or a directory for everything under it. */
+  paths?: string[];
+  /** The hunk text one file gets. */
+  maxBytes?: number;
+  /** Compare `range` (one commit, HEAD when empty) with the working tree. */
+  worktree?: boolean;
+}
+
+export interface PatchResult {
+  doc: PatchDocument;
+  failed: boolean;
+}
+
+function git(top: string, args: string[]): string {
+  return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024 * 1024 });
+}
+
+function commitOf(top: string, rev: string): string {
+  if (rev === "" || rev.startsWith("-")) throw new PatchError("revision-unknown", `the patch needs <base>..<head>, <base>...<head> or a commit, and ${JSON.stringify(rev)} is not a revision`);
+  try {
+    return git(top, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim();
+  } catch {
+    throw new PatchError("revision-unknown", `${rev} is no commit in this repository`);
+  }
+}
+
+function resolveRange(top: string, spec: string): { form: "range" | "merge-base" | "commit"; base: string; head: string } {
+  const three = spec.indexOf("...");
+  if (three >= 0) {
+    const head = commitOf(top, spec.slice(three + 3) || "HEAD");
+    const other = commitOf(top, spec.slice(0, three));
+    try {
+      return { form: "merge-base", base: git(top, ["merge-base", other, head]).trim(), head };
+    } catch {
+      throw new PatchError("revision-unknown", `${spec}: the two revisions have no merge base`);
+    }
+  }
+  const two = spec.indexOf("..");
+  if (two >= 0) return { form: "range", base: commitOf(top, spec.slice(0, two)), head: commitOf(top, spec.slice(two + 2) || "HEAD") };
+  const head = commitOf(top, spec);
+  let base = EMPTY_TREE;
+  try {
+    base = git(top, ["rev-parse", "--verify", "--quiet", `${head}^1`]).trim();
+  } catch {
+    // A root commit: against the empty tree.
+  }
+  return { form: "commit", base, head };
+}
+
+/** Each changed file, from the repository root, with its counts; renames and copies followed. */
+function changedFiles(top: string, revs: string[], pathspecs: string[]): Omit<PatchFile, "hunkCount" | "bytes" | "hunks" | "truncated">[] {
+  const spec = ["--", ...pathspecs];
+  const status = git(top, ["diff", "--name-status", "-z", "-M", "--no-color", ...revs, ...spec]).split("\0");
+  const counts = git(top, ["diff", "--numstat", "-z", "-M", "--no-color", ...revs, ...spec]).split("\0");
+  const numstat = new Map<string, { additions: number | null; deletions: number | null }>();
+  for (let i = 0; i < counts.length && counts[i] !== ""; ) {
+    const [a, d, path] = counts[i].split("\t");
+    const n = { additions: a === "-" ? null : Number(a), deletions: d === "-" ? null : Number(d) };
+    if (path === "") {
+      // A rename or a copy: the old path, then the new.
+      numstat.set(counts[i + 2], n);
+      i += 3;
+    } else {
+      numstat.set(path, n);
+      i += 1;
+    }
+  }
+  const out: Omit<PatchFile, "hunkCount" | "bytes" | "hunks" | "truncated">[] = [];
+  for (let i = 0; i < status.length && status[i] !== ""; ) {
+    const s = status[i];
+    const paired = s.startsWith("R") || s.startsWith("C");
+    const path = paired ? status[i + 2] : status[i + 1];
+    const from = paired ? status[i + 1] : null;
+    const change = s.startsWith("R") ? "renamed" : s.startsWith("C") ? "copied" : s === "A" ? "added" : s === "D" ? "deleted" : "modified";
+    const n = numstat.get(path) ?? { additions: null, deletions: null };
+    out.push({ path, change, from, binary: n.additions === null, ...n });
+    i += paired ? 3 : 2;
+  }
+  return out;
+}
+
+/** The hunks of one file's diff text, and the bytes of hunk text, before any cut. */
+function parseHunks(text: string): { hunks: PatchHunk[]; bytes: number } {
+  const hunks: PatchHunk[] = [];
+  let bytes = 0;
+  let current: PatchHunk | null = null;
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  for (const line of lines) {
+    const m = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (m) {
+      current = { header: line, oldStart: Number(m[1]), oldLines: m[2] === undefined ? 1 : Number(m[2]), newStart: Number(m[3]), newLines: m[4] === undefined ? 1 : Number(m[4]), lines: [] };
+      hunks.push(current);
+      bytes += Buffer.byteLength(line) + 1;
+    } else if (current && /^[ +\-\\]/.test(line)) {
+      current.lines.push(line);
+      bytes += Buffer.byteLength(line) + 1;
+    }
+  }
+  return { hunks, bytes };
+}
+
+/**
+ * Each file's section of the diff, in the order `--name-status` lists the
+ * files: one `git diff` for the whole range, split at its `diff --git` lines.
+ * When the count of sections is not the count of files, each file's diff is
+ * read on its own instead.
+ */
+function fileSections(top: string, revs: string[], pathspecs: string[], files: { path: string; from: string | null }[]): string[] {
+  const diff = (spec: string[]) => git(top, ["diff", "--no-color", "--no-ext-diff", "-M", ...revs, "--", ...spec]);
+  const text = diff(pathspecs);
+  const sections = text === "" ? [] : text.split(/^(?=diff --git )/m).filter((x) => x.startsWith("diff --git "));
+  if (sections.length === files.length) return sections;
+  return files.map((f) => diff(f.from ? [f.from, f.path] : [f.path]));
+}
+
+/** `git diff --no-index`, which exits 1 when the two differ: its output either way. */
+function gitNoIndex(top: string, args: string[]): string {
+  try {
+    return git(top, ["diff", "--no-index", "--no-color", "--no-ext-diff", ...args]);
+  } catch (err) {
+    const out = (err as { status?: number; stdout?: string }).stdout;
+    if ((err as { status?: number }).status === 1 && typeof out === "string") return out;
+    throw err;
+  }
+}
+
+/** Each untracked file git does not ignore, under the pathspecs, as an added file with its diff text. */
+function untrackedFiles(top: string, pathspecs: string[]): { file: Omit<PatchFile, "hunkCount" | "bytes" | "hunks" | "truncated">; section: string }[] {
+  const listed = git(top, ["ls-files", "--others", "--exclude-standard", "-z", "--", ...pathspecs]).split("\0").filter((p) => p !== "");
+  return listed.map((path) => {
+    const [a, d] = gitNoIndex(top, ["--numstat", "--", "/dev/null", path]).split("\t");
+    const binary = a === "-";
+    return {
+      file: { path, change: "added" as const, from: null, binary, additions: binary ? null : Number(a) || 0, deletions: binary ? null : Number(d) || 0 },
+      section: binary ? "" : gitNoIndex(top, ["--", "/dev/null", path]),
+    };
+  });
+}
+
+/** The hunks cut to `budget` bytes: whole hunks while they fit, then the lines of the next that fit. */
+function cut(hunks: PatchHunk[], budget: number): { hunks: PatchHunk[]; used: number; truncated: boolean } {
+  const out: PatchHunk[] = [];
+  let used = 0;
+  for (const h of hunks) {
+    const header = Buffer.byteLength(h.header) + 1;
+    if (used + header > budget) return { hunks: out, used, truncated: true };
+    const kept: string[] = [];
+    used += header;
+    for (const l of h.lines) {
+      const n = Buffer.byteLength(l) + 1;
+      if (used + n > budget) {
+        out.push({ ...h, lines: kept });
+        return { hunks: out, used, truncated: true };
+      }
+      kept.push(l);
+      used += n;
+    }
+    out.push(h);
+  }
+  return { hunks: out, used, truncated: false };
+}
+
+/** Build the document. Never throws a {@link WorkspaceReadError}. */
+export async function workspacePatch(query: PatchQuery): Promise<PatchResult> {
+  const head: Head = { $schema: PATCH_OUTPUT_SCHEMA_ID, contract: PATCH_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    return { doc: run(query, head), failed: false };
+  } catch (err) {
+    if (err instanceof PatchError || err instanceof WorkspaceReadError) {
+      return { doc: { ...head, error: { code: err.code as PatchErrorCode, message: err.message } }, failed: true };
+    }
+    throw err;
+  }
+}
+
+function run(query: PatchQuery, head: Head): Exclude<PatchDocument, { error: unknown }> {
+  const located = locateWorkspace(query.cwd);
+  const top = located.top;
+  if (!top) throw new PatchError("not-a-git-repository", "the patch read reads a git diff, and this directory is not in a git repository");
+  const declaration = readDeclaration(located.tree, "", { rootChant: true });
+  const prefix = located.root === "." ? "" : located.root;
+  const paths = (query.paths ?? []).map((p) => p.replace(/\/+$/, ""));
+  for (const p of paths) if (p !== "." && !isWorkspacePath(p)) throw new PatchError("patch-path-invalid", `--path ${p} is not a relative path inside the workspace`);
+  const pathspecs = paths.length === 0 ? [prefix === "" ? "." : prefix] : paths.map((p) => (joinPath(prefix, p) === "" ? "." : joinPath(prefix, p)));
+  const range = query.worktree
+    ? { form: "worktree" as const, base: commitOf(top, query.range === "" ? "HEAD" : query.range), head: null }
+    : resolveRange(top, query.range);
+  const revs = range.head === null ? [range.base] : [range.base, range.head];
+  const fileBytes = query.maxBytes ?? PATCH_FILE_BYTES;
+  const totalBytes = fileBytes * PATCH_TOTAL_FACTOR;
+  const fromWorkspace = (full: string) => (prefix === "" ? full : full.slice(prefix.length + 1));
+
+  let left = totalBytes;
+  const files: PatchFile[] = [];
+  const tracked = changedFiles(top, revs, pathspecs);
+  const trackedSections = tracked.length > 0 ? fileSections(top, revs, pathspecs, tracked) : [];
+  const fresh = range.head === null ? untrackedFiles(top, pathspecs) : [];
+  const both = [...tracked.map((file, i) => ({ file, section: trackedSections[i] })), ...fresh].sort((a, b) => (a.file.path < b.file.path ? -1 : a.file.path > b.file.path ? 1 : 0));
+  const changed = both.map((x) => x.file);
+  const sections = both.map((x) => x.section);
+  for (const [i, f] of changed.entries()) {
+    const entry = { ...f, path: fromWorkspace(f.path), from: f.from === null ? null : fromWorkspace(f.from) };
+    if (f.binary) {
+      files.push({ ...entry, hunkCount: 0, bytes: 0, hunks: [], truncated: false });
+      continue;
+    }
+    const all = parseHunks(sections[i]);
+    const kept = cut(all.hunks, Math.min(fileBytes, left));
+    left -= kept.used;
+    files.push({ ...entry, hunkCount: all.hunks.length, bytes: all.bytes, hunks: kept.hunks, truncated: kept.truncated });
+  }
+  return {
+    ...head,
+    workspace: { name: declaration.name, root: located.root },
+    range: { spec: query.range, ...range },
+    paths,
+    limits: { fileBytes, totalBytes },
+    files,
+    summary: {
+      files: files.length,
+      additions: files.reduce((n, f) => n + (f.additions ?? 0), 0),
+      deletions: files.reduce((n, f) => n + (f.deletions ?? 0), 0),
+      truncated: files.some((f) => f.truncated),
+    },
+  };
+}
+
+const USAGE = "chant workspace patch <base>..<head>|<base>...<head>|<commit> [--path <p>...] [--max-bytes <n>] [--json], or chant workspace patch [<commit>] --worktree [--path <p>...] [--max-bytes <n>] [--json]";
+
+/** Each file's line, then its hunks as git writes them, then a summary. */
+export function formatPatch(doc: Exclude<PatchDocument, { error: unknown }>): string {
+  const out = [`patch     ${doc.range.base.slice(0, 8)}..${doc.range.head === null ? "worktree" : doc.range.head.slice(0, 8)} (${doc.range.spec}, ${doc.range.form})`];
+  for (const f of doc.files) {
+    const counts = f.binary ? "binary" : `+${f.additions} -${f.deletions}`;
+    out.push(`${f.change.padEnd(9)} ${f.path}${f.from ? ` (from ${f.from})` : ""} ${counts}${f.truncated ? `; truncated, ${f.hunks.length} of ${f.hunkCount} hunks shown` : ""}`);
+    for (const h of f.hunks) out.push(h.header, ...h.lines);
+  }
+  const s = doc.summary;
+  out.push(`${s.files} files, +${s.additions} -${s.deletions}${s.truncated ? `; truncated at ${doc.limits.fileBytes} bytes a file, ${doc.limits.totalBytes} in all` : ""}`);
+  return out.join("\n");
+}
+
+export async function runWorkspacePatch(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const range = args.extraPositional ?? (args.worktree ? "" : undefined);
+  if (range === undefined) {
+    console.error(formatError({ message: "chant workspace patch needs a range or a commit", hint: USAGE }));
+    return 1;
+  }
+  const { doc, failed } = await workspacePatch({ cwd: process.cwd(), range, paths: args.paths, maxBytes: args.maxBytes, worktree: args.worktree === true });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if (!args.json) console.log(formatPatch(doc));
+  return failed ? 1 : 0;
+}

package/src/workspace/points-cli.ts

@@ -193,6 +193,24 @@ export async function workspacePoints(query: PointsQuery): Promise<PointsDocumen
   };
 }
 
+/**
+ * Every question's state in the workspace, by answer record id, read the way
+ * `points` reads them (the lifecycle ledger's questions included), or null
+ * when they can't all be read: an answer kind that could not be read might
+ * hold the question. The operator reads it to resume a waiting run, and
+ * `workspace status` to list a steward's waits.
+ */
+export async function readQuestionStates(cwd: string): Promise<Map<string, QuestionView["state"]> | null> {
+  try {
+    const doc = await workspacePoints({ cwd });
+    if (!("questions" in doc)) return null;
+    if (doc.sources.some((s) => s.reason !== null)) return null;
+    return new Map(doc.questions.map((q) => [q.id, q.state]));
+  } catch {
+    return null;
+  }
+}
+
 /** The document as lines for a person. */
 export function formatPoints(doc: Extract<PointsDocument, { points: unknown }>): string {
   const lines: string[] = [];

package/src/workspace/read-contract.test.ts

@@ -27,6 +27,10 @@ import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import { intentGraph } from "./intent";
 import intentSchema from "./intent.schema.json";
+import { intentRecord } from "./intent-record";
+import intentRecordSchema from "./intent-record.schema.json";
+import { workspacePatch } from "./patch";
+import patchSchema from "./patch.schema.json";
 import { runChecks } from "./lineage-check";
 import { listWorkspace } from "./ls";
 import lsSchema from "./ls.schema.json";
@@ -44,7 +48,7 @@ import statusSchema from "./status.schema.json";
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, composites: compositesSchema, points: pointsSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {
@@ -138,6 +142,30 @@ describe("every schema against the reference workspace (#2543)", () => {
     }
   });
 
+  test("graph --intent --record, in the working tree and at HEAD", async () => {
+    const { expectValid } = contract(intentRecordSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const { doc, failed } = await intentRecord({ cwd: FIXTURE, record: "ref-002", at, kinds: ["decisions/decision.kind.mjs", "work/work.kind.mjs"] });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(failed).toBe(false);
+      expect(doc.at).toBe(at ? head : null);
+      expect(doc.record.id).toBe("record:decision/ref-002");
+      expect(doc.record.decidedIn?.sha).toMatch(/^[0-9a-f]{40}$/);
+    }
+  });
+
+  test("patch, for the last commit that changed the reference workspace", async () => {
+    const { expectValid } = contract(patchSchema);
+    const last = git(REPO, "log", "-1", "--format=%H", "--", "reference-workspace");
+    const { doc, failed } = await workspacePatch({ cwd: FIXTURE, range: last });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(failed).toBe(false);
+    expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+    expect(doc.files.length).toBeGreaterThan(0);
+  });
+
   test(
     "graph --composites runs delivery's own component graph, and lists its app with the component that deploys it (#2662)",
     async () => {

package/src/workspace/reason-codes.test.ts

@@ -34,6 +34,7 @@ import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
 import { POINTS_ERROR_CODES, POINTS_SOURCE_REASON_CODES } from "./points-cli";
 import { POINTS_WRITE_ERROR_CODES } from "./decide";
+import { PATCH_ERROR_CODES } from "./patch";
 
 const HERE = import.meta.dirname;
 
@@ -82,6 +83,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   POINTS_ERROR_CODES,
   POINTS_SOURCE_REASON_CODES,
   POINTS_WRITE_ERROR_CODES,
+  PATCH_ERROR_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */