@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/member-run.ts

@@ -0,0 +1,146 @@
+/**
+ * `chant workspace member-run` (#2537): the one process a toolchain runs for
+ * `chant workspace build|lint|audit|graph`.
+ *
+ * `member-commands.ts` groups the members by the chant each one resolves
+ * (#2524 D3, "one process per toolchain identity") and spawns that chant's
+ * `workspace member-run` once per group. The request arrives as JSON on
+ * stdin: the level-0 command line for each member, and the member's
+ * directory. This process runs them one after another, in-process, from
+ * inside each directory, so every member gets what `chant <verb> .` would
+ * print there. It answers on stdout with one {@link PROTOCOL_PREFIX} line per
+ * member, after a header line naming the protocol and this chant's version.
+ *
+ * A chant older than this command has no header to print. The caller sees
+ * that and falls back to one level-0 process per member.
+ *
+ * Internal: not listed in `chant --help`, and the protocol may change with
+ * the caller, which is always a chant of the same or a newer release.
+ */
+
+import { ENV_VAR } from "../env";
+import type { CommandContext } from "../cli/registry";
+import { readerVersion } from "./declaration";
+
+/** Marks the lines of this protocol on stdout; anything else there is stray output. */
+export const PROTOCOL_PREFIX = "@@chant-member-run@@ ";
+export const MEMBER_RUN_PROTOCOL = 1;
+
+export interface MemberRunRequest {
+  protocol: number;
+  units: MemberRunUnit[];
+}
+
+export interface MemberRunUnit {
+  /** Echoed back on the answer line. */
+  id: string;
+  /** The member's directory, absolute. The command runs from inside it. */
+  dir: string;
+  /** The level-0 command line, such as `["lint", ".", "--format", "sarif"]`. */
+  argv: string[];
+  /**
+   * Directories (relative to `dir`) to leave out of discovery. Set for member
+   * `.`, whose project is the root minus every other member. Kept in the
+   * protocol for a member-run from before #2527, which applied it itself;
+   * from #2527 on, discovery reads the same set from the declaration.
+   */
+  exclude?: string[];
+}
+
+export type MemberRunLine =
+  | { type: "header"; protocol: number; chant: string }
+  | { type: "result"; id: string; exitCode: number; stdout: string; stderr: string };
+
+/** A `process.exit` inside a command, turned into a value. */
+class ExitRequest extends Error {
+  constructor(readonly code: number) {
+    super(`process.exit(${code})`);
+  }
+}
+
+type Write = typeof process.stdout.write;
+
+/**
+ * Run `fn` with stdout, stderr and `process.exit` captured. Commands print
+ * through `console`, which writes through the stream's `write` at call time,
+ * so replacing `write` catches everything they print.
+ */
+export async function captureRun(fn: () => Promise<number>): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  const sink =
+    (into: string[]): Write =>
+    ((chunk: string | Uint8Array, encoding?: unknown, cb?: unknown) => {
+      into.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      const done = typeof encoding === "function" ? encoding : cb;
+      if (typeof done === "function") (done as () => void)();
+      return true;
+    }) as Write;
+  const saved = { out: process.stdout.write, err: process.stderr.write, exit: process.exit };
+  process.stdout.write = sink(out);
+  process.stderr.write = sink(err);
+  process.exit = ((code?: number) => {
+    throw new ExitRequest(typeof code === "number" ? code : 0);
+  }) as typeof process.exit;
+  let exitCode: number;
+  try {
+    exitCode = await fn();
+  } catch (e) {
+    if (e instanceof ExitRequest) {
+      exitCode = e.code;
+    } else {
+      err.push(`${e instanceof Error ? e.message : String(e)}\n`);
+      exitCode = 1;
+    }
+  } finally {
+    process.stdout.write = saved.out;
+    process.stderr.write = saved.err;
+    process.exit = saved.exit;
+  }
+  return { exitCode, stdout: out.join(""), stderr: err.join("") };
+}
+
+function emit(line: MemberRunLine): void {
+  process.stdout.write(`${PROTOCOL_PREFIX}${JSON.stringify(line)}\n`);
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** Run each unit of `request` in turn, answering on stdout. */
+export async function runMemberUnits(request: MemberRunRequest, run: (argv: string[]) => Promise<number>): Promise<number> {
+  emit({ type: "header", protocol: MEMBER_RUN_PROTOCOL, chant: readerVersion() });
+  const startDir = process.cwd();
+  const startEnv = process.env[ENV_VAR];
+  for (const unit of request.units) {
+    const result = await captureRun(async () => {
+      process.chdir(unit.dir);
+      // `unit.exclude` needs no action here: discovery reads the declaration
+      // itself and leaves member `.`'s exclusions out of every walk (#2527).
+      return run(unit.argv);
+    });
+    if (startEnv === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = startEnv;
+    process.chdir(startDir);
+    emit({ type: "result", id: unit.id, ...result });
+  }
+  return 0;
+}
+
+export async function runWorkspaceMemberRun(_ctx: CommandContext, run: (argv: string[]) => Promise<number>): Promise<number> {
+  let request: MemberRunRequest;
+  try {
+    request = JSON.parse(await readStdin()) as MemberRunRequest;
+  } catch (err) {
+    console.error(`chant workspace member-run: the request on stdin is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  if (request.protocol !== MEMBER_RUN_PROTOCOL || !Array.isArray(request.units)) {
+    console.error(`chant workspace member-run: this chant speaks protocol ${MEMBER_RUN_PROTOCOL}, and the request asks for ${String(request.protocol)}`);
+    return 1;
+  }
+  return runMemberUnits(request, run);
+}

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

@@ -0,0 +1,129 @@
+/**
+ * The read contract as a whole (#2536, #2524 D15): every output schema, run
+ * against the reference workspace (#2543) in this checkout.
+ *
+ * `reference-workspace/` is a nested workspace of the chant repo, with a
+ * `chant` member (`delivery`), three `other` members and decision records.
+ * Each read-contract command reads it here, and its output must validate
+ * against the command's schema: `ls`, `graph` (running delivery's real
+ * `chant graph`), `check`, `status` and `records`, in the working tree and,
+ * for `ls`, `graph` and `check`, at `HEAD` through `--at`.
+ *
+ * The schemas themselves are checked here too: each is a draft 2020-12
+ * document under `https://intentius.io/chant/schemas/workspace/<command>/v1/`,
+ * at the contract version this chant writes, naming the chant floor.
+ */
+
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
+import checkSchema from "./check.schema.json";
+import { workspaceGraph } from "./graph-cli";
+import graphSchema from "./graph.schema.json";
+import { runChecks } from "./lineage-check";
+import { listWorkspace } from "./ls";
+import lsSchema from "./ls.schema.json";
+import { readerBin, type Toolchain } from "./member-commands";
+import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION } from "./reason-codes";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import { workspaceStatus } from "./status";
+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 };
+
+/** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
+const reader: Toolchain = {
+  command: [process.execPath, "--import", pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href, join(REPO, "packages", "core", "src", "cli", "main.ts")],
+  identity: realpathSync(readerBin()),
+  source: "reader",
+};
+
+describe("the read contract's schemas", () => {
+  test.each(Object.entries(SCHEMAS))("%s is a valid draft 2020-12 document at the contract version, naming the floor", (name, schema) => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(`https://intentius.io/chant/schemas/workspace/${name}/v${READ_CONTRACT_VERSION}/${name}.schema.json`);
+    for (const branch of ["result", "failure"] as const) {
+      const props = (schema.$defs as Record<string, { properties: Record<string, unknown> }>)[branch].properties;
+      expect(props.contract, `${name} ${branch}`).toEqual({ const: READ_CONTRACT_VERSION });
+      expect(props.$schema, `${name} ${branch}`).toEqual({ const: schema.$id });
+    }
+    expect(schema.description).toContain(`chant ${READ_CONTRACT_FLOOR} and newer`);
+  });
+});
+
+describe("every schema against the reference workspace (#2543)", () => {
+  const head = git(REPO, "rev-parse", "HEAD");
+
+  test("ls, in the working tree and at HEAD", () => {
+    const { expectValid } = contract(lsSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const doc = listWorkspace({ cwd: join(FIXTURE, "delivery"), at });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.workspace).toMatchObject({ name: "reference", root: "reference-workspace" });
+      expect(doc.at).toBe(at ? head : null);
+      expect(doc.members.map((m) => [m.name, m.readable])).toEqual([
+        ["app", true],
+        ["delivery", true],
+        ["design-client", true],
+        ["design", true],
+      ]);
+    }
+  });
+
+  test(
+    "graph runs delivery's own chant graph, in the working tree and at HEAD",
+    async () => {
+      const { expectValid } = contract(graphSchema);
+      for (const at of [undefined, "HEAD"]) {
+        const { doc, failed } = await workspaceGraph({ cwd: FIXTURE, at, reader });
+        expectValid(doc);
+        if ("error" in doc) throw new Error(doc.error.message);
+        expect(failed, JSON.stringify(doc.members)).toBe(false);
+        expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+        expect(doc.at).toBe(at ? head : null);
+        const delivery = doc.members.find((m) => m.name === "delivery");
+        expect(delivery).toMatchObject({ status: "composed", reason: null, irVersion: 1 });
+        expect(doc.groups.byMember.delivery.length).toBeGreaterThan(0);
+        expect(doc.nodes.every((n) => n.id.startsWith("delivery/") && n.member === "delivery")).toBe(true);
+      }
+    },
+    TIMEOUT,
+  );
+
+  test("check, in the working tree and at HEAD", async () => {
+    const { expectValid } = contract(checkSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const doc = await runChecks(FIXTURE, at);
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+      expect(doc.declaration?.diagnostics.filter((d) => d.severity === "error")).toEqual([]);
+    }
+  });
+
+  test("status", async () => {
+    const doc = await workspaceStatus({ cwd: FIXTURE, env: "dev" });
+    contract(statusSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.workspace).toMatchObject({ name: "reference", root: "reference-workspace" });
+    expect(doc.members.map((m) => m.name)).toEqual(["app", "delivery", "design-client", "design"]);
+  });
+
+  test("records, in the working tree and at HEAD", async () => {
+    const { expectValid } = contract(recordsSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const doc = await queryRecords({ kind: "decisions/decision.kind.mjs", cwd: FIXTURE, at });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.summary.invalid).toBe(0);
+      expect(doc.records.map((r) => r.id)).toContain("ref-001");
+    }
+  });
+});

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

@@ -0,0 +1,113 @@
+/**
+ * One closed list of reason codes (#2536, #2524 D15): every command's own
+ * list is a subset of `REASON_CODES`, together they cover it, the output
+ * schemas name nothing outside it, and no source file under `workspace/`
+ * emits a code outside it. The read-contract page documents every code.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./__fixtures__/contract-repo";
+import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
+import { WORKSPACE_ERROR_CODES } from "./declaration";
+import { GRAPH_ERROR_CODES } from "./graph-cli";
+import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
+import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
+import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
+
+const HERE = import.meta.dirname;
+
+const PER_COMMAND: Record<string, readonly string[]> = {
+  WORKSPACE_ERROR_CODES,
+  MEMBER_REASON_CODES,
+  GROUP_REASON_CODES,
+  MEMBER_RUN_REASON_CODES,
+  GRAPH_ERROR_CODES,
+  CHECK_CODES,
+  CHECK_ERROR_CODES,
+  STATUS_REASON_CODES,
+  STATUS_ERROR_CODES,
+  RECORD_REASON_CODES,
+  READ_ERROR_CODES,
+};
+
+/** Every string in an `enum` under a property named `code`, anywhere in a schema. */
+function schemaCodes(node: unknown, underCode = false, out = new Set<string>()): Set<string> {
+  if (Array.isArray(node)) {
+    for (const n of node) schemaCodes(n, underCode, out);
+  } else if (node !== null && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "enum" && underCode) for (const e of v as unknown[]) out.add(String(e));
+      schemaCodes(v, k === "code" || (underCode && k !== "properties"), out);
+    }
+  }
+  return out;
+}
+
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const d of readdirSync(dir, { withFileTypes: true })) {
+    if (d.isDirectory() && d.name !== "__fixtures__") out.push(...sourceFiles(join(dir, d.name)));
+    else if (d.isFile() && d.name.endsWith(".ts") && !d.name.endsWith(".test.ts")) out.push(join(dir, d.name));
+  }
+  return out;
+}
+
+/** Codes that are someone else's: zod's issue codes. */
+const NOT_OURS = new Set(["custom"]);
+
+describe("the closed list of reason codes", () => {
+  test("has no duplicates, and every code says what it means", () => {
+    expect(new Set(REASON_CODES).size).toBe(REASON_CODES.length);
+    for (const c of REASON_CODES) {
+      expect(c).toMatch(/^[a-z]+(-[a-z0-9]+)*$/);
+      expect(REASONS[c].length).toBeGreaterThan(10);
+    }
+    expect(isReasonCode("dir-missing")).toBe(true);
+    expect(isReasonCode("toString")).toBe(false);
+  });
+
+  test("each command's list is a subset, and together they are the whole list", () => {
+    const union = new Set<string>();
+    for (const [name, codes] of Object.entries(PER_COMMAND)) {
+      for (const c of codes) {
+        expect(isReasonCode(c), `${name} has ${c}, which is not in reason-codes.ts`).toBe(true);
+        union.add(c);
+      }
+    }
+    expect([...union].sort()).toEqual([...REASON_CODES].sort());
+  });
+
+  test("the output schemas name exactly these codes", () => {
+    const named = new Set<string>();
+    for (const f of readdirSync(HERE).filter((f) => f.endsWith(".schema.json") && !f.startsWith("declaration") && !f.startsWith("workspace-kinds"))) {
+      for (const c of schemaCodes(JSON.parse(readFileSync(join(HERE, f), "utf-8")))) {
+        expect(isReasonCode(c), `${f} names ${c}, which is not in reason-codes.ts`).toBe(true);
+        named.add(c);
+      }
+    }
+    expect([...named].sort()).toEqual([...REASON_CODES].sort());
+  });
+
+  test("no source file emits a code outside the list", () => {
+    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError)\(\s*)"([a-z0-9-]+)"/g;
+    let seen = 0;
+    for (const file of sourceFiles(HERE)) {
+      const text = readFileSync(file, "utf-8");
+      for (const m of text.matchAll(emitted)) {
+        if (NOT_OURS.has(m[1])) continue;
+        seen++;
+        expect(isReasonCode(m[1]), `${file.slice(HERE.length + 1)} emits ${m[1]}, which is not in reason-codes.ts`).toBe(true);
+      }
+    }
+    expect(seen).toBeGreaterThan(30);
+  });
+
+  test("the read-contract page documents every code", () => {
+    const page = readFileSync(join(REPO, "docs", "src", "content", "docs", "reference", "workspace-read-contract.mdx"), "utf-8");
+    for (const c of REASON_CODES) expect(page, c).toContain(`| \`${c}\` |`);
+  });
+});

package/src/workspace/reason-codes.ts

@@ -0,0 +1,81 @@
+/**
+ * The workspace read contract's closed list of reason codes (#2536, #2524
+ * D15, ws-017, ws-020).
+ *
+ * Every code a `chant workspace` read prints is here: the error that stops a
+ * read, the reason an unreadable member, group, ledger or record is listed
+ * with, and the lineage lock findings of `check`. Each command's own list
+ * (`WORKSPACE_ERROR_CODES`, `MEMBER_REASON_CODES`, `STATUS_REASON_CODES`,
+ * `RECORD_REASON_CODES` and the rest) is a subset of this one, which the
+ * compiler checks through `satisfies`. `reason-codes.test.ts` checks that the
+ * output schemas and the source emit nothing outside it.
+ *
+ * The list is closed: a reader may switch on a code, and a new code is a
+ * contract change. Within contract version 1, before the floor release, codes
+ * may still be added; after it, a new code means a new contract version.
+ *
+ * `chant workspace check` also reports `WSP` ids. Those are the declaration
+ * check catalog (`checks.ts`), a separate closed list, and a finding whose
+ * cause is one of the codes here carries that code too.
+ */
+
+/** The version of the read contract this chant writes: the declaration format, the output schemas and these codes. */
+export const READ_CONTRACT_VERSION = 1;
+
+/** The first chant release that writes contract version 1. A reader that needs the contract refuses an older chant. */
+export const READ_CONTRACT_FLOOR = "0.81.0";
+
+/** Each code and what it means. The key order is the order the docs list them in. */
+export const REASONS = {
+  // Reading the declaration (ls, graph, check, status).
+  "declaration-missing": "No chant.workspace.json or .jsonc between the directory and the git root.",
+  "declaration-ambiguous": "Both chant.workspace.json and chant.workspace.jsonc exist.",
+  "declaration-unparseable": "The declaration is not valid JSON, or not valid JSONC for .jsonc.",
+  "declaration-invalid": "The declaration does not match its schema, repeats a name, or --member names no entry.",
+  "placement-invalid": "A member or group match breaks a placement rule.",
+  "reader-too-old": "The declaration's minReader is newer than the chant reading it.",
+  "root-chant-required": "The declaration pins a chant version other than the reader's, and that chant is not installed at the workspace root.",
+  // --at and git.
+  "not-a-git-repository": "--at, or a ledger read, needs a git repository and there is none.",
+  "revision-unknown": "--at names no commit.",
+  // status.
+  "environment-invalid": "An environment name that can't name a ledger directory.",
+  // A member or group that can't be read (ls, graph).
+  "dir-missing": "The member's directory does not exist.",
+  "unknown-kind": "No built-in kind or pinned package supplies the member's kind.",
+  "kind-probe-failed": "The member's directory is not what its kind reads.",
+  "no-matches": "An example group matches no directory holding a chant project.",
+  // A member graph leaves out (graph, and the other per-member commands).
+  "kind-not-run": "The member's kind is one the per-member commands don't run, such as other.",
+  "command-failed": "The member's own command exited with a failure.",
+  "output-unreadable": "The member's command printed something that isn't the document asked for.",
+  "ir-version-unsupported": "The member's IR has a version this chant can't read.",
+  // A ledger status can't fully read.
+  "ledger-unreadable": "Reading the ledger failed, so nothing from it is listed.",
+  "ledger-malformed": "Some lines of the ledger aren't release records; the rest are listed.",
+  // A record that isn't valid (records).
+  "record-unparseable": "No front matter, a YAML error, or a value outside the JSON subset of YAML.",
+  "record-schema-invalid": "The front matter does not match the kind's schema.",
+  "record-id-duplicate": "Another record earlier in path order has the same id.",
+  "record-supersedes-unknown": "A supersedes link names an id no record has.",
+  "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  // A records read that fails (records).
+  "kind-unreadable": "The record kind file is missing or could not be imported.",
+  "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
+  "schema-unreadable": "The schema file the record kind names is missing or is not JSON.",
+  "schema-id-mismatch": "The schema's $id differs from the id the record kind names.",
+  "schema-invalid": "The record schema itself does not compile.",
+  "location-missing": "The records directory does not exist, in the tree or at the revision.",
+  // The lineage lock (check).
+  "lock-invalid": "The lineage lock can't be read.",
+  "manual-step-open": "A scope in the lineage lock has an open manual step.",
+} as const;
+
+export type ReasonCode = keyof typeof REASONS;
+
+/** Every code, in the order of {@link REASONS}. */
+export const REASON_CODES = Object.keys(REASONS) as ReasonCode[];
+
+export function isReasonCode(value: unknown): value is ReasonCode {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(REASONS, value);
+}

package/src/workspace/record-source.ts

@@ -0,0 +1,117 @@
+/**
+ * Where records are read from: the working tree, or a commit's git objects
+ * (`--at <rev>`, #2536). Reading at a revision needs no checkout and no
+ * network; it asks the local git object store only.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { RecordReadError } from "./records";
+
+export interface RecordSource {
+  /** Appended to messages, such as " at 91c7547e". Empty for the working tree. */
+  label: string;
+  /** File names directly inside `dir` (relative to the root, `/`-separated), or undefined when `dir` is missing. */
+  list(dir: string): string[] | undefined;
+  /** The text of a file listed by `list`. */
+  read(path: string): string;
+}
+
+/** Records in the working tree under `root`. */
+export function workingTreeSource(root: string): RecordSource {
+  return {
+    label: "",
+    list(dir) {
+      try {
+        return readdirSync(join(root, dir), { withFileTypes: true })
+          .filter((d) => d.isFile())
+          .map((d) => d.name);
+      } catch {
+        return undefined;
+      }
+    },
+    read(path) {
+      return readFileSync(join(root, path), "utf-8");
+    },
+  };
+}
+
+function git(cwd: string, args: string[], input?: string): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    input,
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+/** The top of the git repository holding `cwd`, or undefined outside one. */
+export function gitRoot(cwd: string): string | undefined {
+  try {
+    return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The full commit id `rev` names in the repository at `root`. */
+export function resolveRevision(root: string, rev: string): string {
+  if (rev.startsWith("-")) throw new RecordReadError("revision-unknown", `--at ${rev} is not a revision`);
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim();
+  } catch {
+    throw new RecordReadError("revision-unknown", `--at ${rev} names no commit in this repository`);
+  }
+}
+
+/** Records as they were at `commit`, read from the object store of the repository at `root`. */
+export function gitRevisionSource(root: string, commit: string): RecordSource {
+  const blobs = new Map<string, string>();
+  return {
+    label: ` at ${commit.slice(0, 8)}`,
+    list(dir) {
+      const treeish = dir === "." ? `${commit}^{tree}` : `${commit}:${dir}`;
+      try {
+        if (git(root, ["cat-file", "-t", treeish]).trim() !== "tree") return undefined;
+      } catch {
+        return undefined;
+      }
+      const entries = git(root, ["ls-tree", "-z", treeish])
+        .split("\0")
+        .filter(Boolean)
+        .map((line) => {
+          const tab = line.indexOf("\t");
+          const [, type, oid] = line.slice(0, tab).split(" ");
+          return { type, oid, name: line.slice(tab + 1) };
+        })
+        .filter((e) => e.type === "blob");
+      // One `cat-file --batch` for the whole directory: records are small, and
+      // one process beats one per file.
+      if (entries.length > 0) {
+        const out = Buffer.from(
+          execFileSync("git", ["cat-file", "--batch"], {
+            cwd: root,
+            input: entries.map((e) => e.oid).join("\n") + "\n",
+            maxBuffer: 256 * 1024 * 1024,
+          }),
+        );
+        let at = 0;
+        for (const e of entries) {
+          const nl = out.indexOf(0x0a, at);
+          const size = Number(out.subarray(at, nl).toString("utf-8").split(" ")[2]);
+          const start = nl + 1;
+          blobs.set(dir === "." ? e.name : `${dir}/${e.name}`, out.subarray(start, start + size).toString("utf-8"));
+          at = start + size + 1;
+        }
+      }
+      return entries.map((e) => e.name);
+    },
+    read(path) {
+      const text = blobs.get(path);
+      if (text === undefined) throw new Error(`${path} was not listed at ${commit}`);
+      return text;
+    },
+  };
+}