@intentius/chant 0.84.0 → 0.86.0

package/src/workspace/conformance/conformance.test.ts

@@ -0,0 +1,149 @@
+/**
+ * The reader conformance suite as a reader outside the chant repository runs
+ * it (#2679): on the workspace generated from `__fixture__/`, with no
+ * test runner, for a subset of the commands, and from the files the package
+ * ships.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import {
+  checkReaderRead,
+  CONFORMANCE_FIXTURE_DIR,
+  createConformanceWorkspace,
+  READ_CONTRACT_COMMANDS,
+  REFERENCE_READS,
+  runWorkspaceReaderConformance,
+  selectCommands,
+  type ChantRun,
+  type ChantTransport,
+  type ConformanceWorkspace,
+  type ReadContractCommand,
+} from "./index";
+import * as suite from "./index";
+
+const coreRoot = resolve(import.meta.dirname, "..", "..", "..");
+const repoRoot = resolve(coreRoot, "..", "..");
+
+const JSON_FLAG: Record<ReadContractCommand, string[]> = {
+  ls: ["--json"],
+  graph: [],
+  check: ["--format", "json"],
+  status: ["--json"],
+  records: ["--json"],
+  "graph --intent": ["--json"],
+  "graph --composites": ["--json"],
+};
+
+/** The smallest reader that conforms, with a hook to misbehave. */
+function reader(twist: (doc: Record<string, unknown>, chant: ChantTransport) => unknown = (doc) => doc) {
+  return (chant: ChantTransport) => ({
+    async read(command: ReadContractCommand, args: string[]) {
+      const run = await chant.run(["workspace", ...command.split(" "), ...args, ...JSON_FLAG[command]]);
+      return twist(JSON.parse(run.stdout) as Record<string, unknown>, chant);
+    },
+  });
+}
+
+let ws: ConformanceWorkspace;
+beforeAll(() => {
+  ws = createConformanceWorkspace();
+}, 300_000);
+afterAll(() => ws?.dispose());
+
+describe("the generated conformance workspace (#2679)", () => {
+  test("a conforming reader passes every command, graph --composites included, with nothing skipped", async () => {
+    const report = await runWorkspaceReaderConformance(reader(), { workspaceDir: ws.dir });
+    expect(report.problems).toEqual([]);
+    expect(report.checked).toEqual([...READ_CONTRACT_COMMANDS]);
+    expect(report.skipped).toEqual([]);
+  }, 300_000);
+
+  test("graph --composites joins the fixture's composite to its component", async () => {
+    const docs: Record<string, unknown>[] = [];
+    await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["graph --composites"] });
+    expect(docs[0]).toMatchObject({
+      composites: [{ id: "delivery/app", kinds: ["WebService"], components: [{ component: "delivery/app", by: "composites", via: "member" }] }],
+      summary: { composites: 1, withComponent: 1 },
+    });
+  }, 300_000);
+
+  test("the decision record and the region the intent read names are in the workspace", async () => {
+    const docs: Record<string, unknown>[] = [];
+    await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["records", "graph --intent"] });
+    expect((docs[0].records as { id: string }[]).map((r) => r.id)).toEqual(["fix-001"]);
+    expect(docs[1].region).toBe(`region:${REFERENCE_READS["graph --intent"][0]}`);
+  }, 300_000);
+});
+
+describe("commands (#2679)", () => {
+  test("only the listed commands are read, and the report names the rest as skipped", async () => {
+    const read: string[] = [];
+    const report = await runWorkspaceReaderConformance(
+      (chant) => ({ read: (command, args) => (read.push(command), reader()(chant).read(command, args)) }),
+      { workspaceDir: ws.dir, commands: ["status", "ls", "graph --composites"] },
+    );
+    expect(report.problems).toEqual([]);
+    expect(read).toEqual(["ls", "status", "graph --composites"]);
+    expect(report.checked).toEqual(["ls", "status", "graph --composites"]);
+    expect(report.skipped).toEqual(["graph", "check", "records", "graph --intent"]);
+  }, 300_000);
+
+  test("a name that is not a contract command, or an empty list, is refused", () => {
+    expect(() => selectCommands(["graph --kind" as ReadContractCommand])).toThrow(/not read-contract commands: graph --kind/);
+    expect(() => selectCommands([])).toThrow(/commands is empty/);
+  });
+});
+
+describe("what the runner-neutral suite catches (#2679)", () => {
+  test("a changed document, a reader that throws and a write to the workspace", async () => {
+    const changed = await runWorkspaceReaderConformance(reader((doc) => ({ ...doc, extra: 1 })), { workspaceDir: ws.dir, commands: ["ls"] });
+    expect(changed.problems.join("\n")).toMatch(/ls: the reader must return the document chant printed, unchanged/);
+
+    const thrown = await runWorkspaceReaderConformance(() => ({ read: () => { throw new Error("no chant"); } }), { workspaceDir: ws.dir, commands: ["status"] });
+    expect(thrown.problems).toEqual(["status: the reader threw: no chant"]);
+
+    const wrote = await runWorkspaceReaderConformance(
+      reader((doc) => (writeFileSync(join(ws.dir, "cache.json"), "{}"), doc)),
+      { workspaceDir: ws.dir, commands: ["ls"] },
+    );
+    expect(wrote.problems).toEqual(["workspace: the reads changed files: cache.json (added)"]);
+  }, 300_000);
+
+  test("checkReaderRead: the schema, the $schema id and the contract version", () => {
+    const argv = ["workspace", "ls", "--json"];
+    const doc = { $schema: "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json", contract: 2 };
+    const printed: ChantRun[] = [{ argv, status: 0, stdout: JSON.stringify(doc), stderr: "" }];
+    const problems = checkReaderRead("ls", [], [argv], printed, doc);
+    expect(problems.join("\n")).toMatch(/ls: the document does not validate against ls.schema.json/);
+    expect(problems.join("\n")).toMatch(/ls: contract is 2, expected 1/);
+    expect(checkReaderRead("ls", [], [argv], [{ ...printed[0], stdout: "" }], doc)).toEqual(["ls: chant workspace ls --json printed nothing"]);
+  });
+});
+
+describe("what the package ships (#2679)", () => {
+  const pkg = JSON.parse(readFileSync(join(coreRoot, "package.json"), "utf-8")) as { files: string[]; exports: Record<string, Record<string, string>> };
+
+  test("the fixture and both entries are in the package's files and exports", () => {
+    expect(pkg.files).toContain("src/");
+    for (const key of ["./workspace/conformance", "./workspace/conformance/vitest"]) {
+      const entry = pkg.exports[key];
+      for (const cond of ["development", "default"]) expect(existsSync(join(coreRoot, entry[cond])), `${key} ${cond}`).toBe(true);
+      expect(entry.types).toMatch(/^\.\/dist\/workspace\/conformance\/.+\.d\.ts$/);
+    }
+    expect(CONFORMANCE_FIXTURE_DIR).toBe(join(coreRoot, "src", "workspace", "conformance", "__fixture__"));
+  });
+
+  test("the plain-Node entry re-exports every runtime export of the suite", () => {
+    const text = readFileSync(join(import.meta.dirname, "index.mjs"), "utf-8");
+    const listed = [.../export const \{([^}]+)\}/.exec(text)![1].matchAll(/[A-Za-z_]+/g)].map((m) => m[0]).sort();
+    expect(listed).toEqual(Object.keys(suite).sort());
+  });
+
+  test("the fixture's decision kind and schema are the reference workspace's", () => {
+    for (const f of ["decision.kind.mjs", "decision.schema.json"]) {
+      expect(readFileSync(join(CONFORMANCE_FIXTURE_DIR, "decisions", f), "utf-8"), f).toBe(readFileSync(join(repoRoot, "reference-workspace", "decisions", f), "utf-8"));
+    }
+  });
+});

package/src/workspace/conformance/index.mjs

@@ -0,0 +1,31 @@
+// The entry of `@intentius/chant/workspace/conformance` for plain Node
+// (#2679). The suite is written in TypeScript like the rest of the package,
+// and Node does not strip types under node_modules, so this file loads it
+// through tsx, a dependency of this package. `node --test` runs a reader's
+// test file that imports it with no loader flag. Types come from
+// dist/workspace/conformance/index.d.ts.
+
+import { tsImport } from "tsx/esm/api";
+
+const suite = await tsImport("./index.ts", import.meta.url);
+
+export const {
+  READ_CONTRACT_COMMANDS,
+  READ_CONTRACT_SCHEMAS,
+  READ_CONTRACT_JSON_FLAGS,
+  REFERENCE_READS,
+  CONFORMANCE_FIXTURE_DIR,
+  defaultChantCommand,
+  referenceWorkspaceDir,
+  readContractSchema,
+  treeDigest,
+  treeChanges,
+  readerCallProblems,
+  checkReaderRead,
+  selectCommands,
+  createConformanceWorkspace,
+  conformanceTarget,
+  recordingTransport,
+  readAndCheck,
+  runWorkspaceReaderConformance,
+} = suite;

package/src/workspace/conformance/index.ts

@@ -0,0 +1,453 @@
+/**
+ * Workspace reader conformance (#2657, ws-052; published by #2679).
+ *
+ * A reader of a workspace, such as hud or behold, reads only through the
+ * read contract (#2524 D15, ws-017) and writes nothing. This module holds a
+ * reader to that, for each read-contract command it lists:
+ *
+ *   1. The reader's `read(command, args)` returns a document that validates
+ *      against that command's output schema, with the contract version this
+ *      chant writes.
+ *   2. Each read makes exactly one chant call, and that call is the contract
+ *      command with the suite's arguments and the command's JSON flag, and
+ *      nothing else.
+ *   3. What the reader returns is the document chant printed, unchanged.
+ *   4. The workspace's files are byte for byte the same after every read.
+ *
+ * How "touched nothing else" is checked: the reader is built by calling
+ * `reader(chant)`, where `chant` is a recording transport. The reader is
+ * never given the workspace's path, so the transport is its only way to the
+ * workspace, and every call through it is recorded and compared with the
+ * contract command (points 2 and 3). Every file under the workspace is
+ * hashed before the first read and after the last one (point 4), which
+ * catches a write by any route, the transport included.
+ *
+ * This module ships in `@intentius/chant` as the subpath
+ * `@intentius/chant/workspace/conformance` and imports no test runner.
+ * {@link runWorkspaceReaderConformance} returns the problems for `node:test`
+ * or any runner, {@link checkReaderRead} checks one read, and
+ * `@intentius/chant/workspace/conformance/vitest` wraps the same checks in
+ * `describe` and `it`.
+ *
+ * The workspace: inside the chant repository it is `reference-workspace/`.
+ * Anywhere else the suite generates one in a temporary directory from the
+ * `__fixture__/` this package ships beside this module (a decision kind and record, an
+ * app, and a chant member with one composite and one component), declared
+ * by `chant workspace init --yes`, so {@link REFERENCE_READS} resolve in
+ * both. `workspaceDir` names another workspace with the same files.
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { READ_CONTRACT_VERSION } from "../reason-codes";
+
+/** The read-contract commands, as a reader names them. */
+export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "graph --intent", "graph --composites"] as const;
+export type ReadContractCommand = (typeof READ_CONTRACT_COMMANDS)[number];
+
+/**
+ * Each command's output schema, beside this module's parent in `src/workspace/`.
+ * The write commands' schemas (`records-new`, `records-amend`,
+ * `records-review`, #2675) are not here: a reader never runs them.
+ */
+export const READ_CONTRACT_SCHEMAS: Record<ReadContractCommand, string> = {
+  ls: "ls.schema.json",
+  graph: "graph.schema.json",
+  check: "check.schema.json",
+  status: "status.schema.json",
+  records: "records.schema.json",
+  "graph --intent": "intent.schema.json",
+  "graph --composites": "composites.schema.json",
+};
+
+/** The flags that ask each command for its JSON document. A reader adds one of these and nothing else. */
+export const READ_CONTRACT_JSON_FLAGS: Record<ReadContractCommand, readonly (readonly string[])[]> = {
+  ls: [["--json"]],
+  graph: [[], ["--json"]],
+  check: [["--format", "json"]],
+  status: [["--json"]],
+  records: [["--json"]],
+  "graph --intent": [["--json"]],
+  "graph --composites": [[], ["--json"]],
+};
+
+/** The arguments the suite passes each read, on the reference workspace or the generated one. */
+export const REFERENCE_READS: Record<ReadContractCommand, string[]> = {
+  ls: [],
+  graph: ["--kind", "decisions/decision.kind.mjs"],
+  check: [],
+  status: ["dev"],
+  records: ["--kind", "decisions/decision.kind.mjs"],
+  "graph --intent": ["app/src/server.mjs:19", "--kind", "decisions/decision.kind.mjs"],
+  "graph --composites": [],
+};
+
+/** One chant run: the arguments after `chant`, and what it printed. */
+export interface ChantRun {
+  argv: string[];
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** How a reader runs chant. It runs in the workspace; the reader never sees the path. */
+export interface ChantTransport {
+  run(argv: string[]): Promise<ChantRun>;
+}
+
+export interface WorkspaceReader {
+  /** Run one read-contract command with `args`, and return the parsed JSON document. */
+  read(command: ReadContractCommand, args: string[]): Promise<unknown> | unknown;
+}
+
+/** Build the reader over the transport the suite gives it. */
+export type WorkspaceReaderFactory = (chant: ChantTransport) => WorkspaceReader;
+
+export interface WorkspaceReaderConformanceOptions {
+  /**
+   * The commands the reader reads. Only these are exercised; any other is
+   * not applicable and is reported as skipped. Defaults to every command in
+   * {@link READ_CONTRACT_COMMANDS}.
+   */
+  commands?: readonly ReadContractCommand[];
+  /**
+   * The workspace to read. Defaults to the chant repository's
+   * reference-workspace inside that repository, and to a workspace generated
+   * from this package's conformance fixture anywhere else.
+   */
+  workspaceDir?: string;
+  /**
+   * The chant to run, as a command and its leading arguments. Defaults to the
+   * checkout's CLI through tsx inside the chant repository, and anywhere else
+   * to the first `node_modules/.bin/chant` above the current directory, then
+   * this package's own `bin/chant`, then `chant` on PATH.
+   */
+  chantCommand?: string[];
+  /** How long one chant run may take, in milliseconds. Default 120000. */
+  timeoutMs?: number;
+}
+
+export interface WorkspaceReaderConformanceConfig extends WorkspaceReaderConformanceOptions {
+  /** Short label, used in the suite name. */
+  name: string;
+  reader: WorkspaceReaderFactory;
+}
+
+/** What one read found. */
+export interface ReaderReadResult {
+  command: ReadContractCommand;
+  args: string[];
+  problems: string[];
+}
+
+/** What {@link runWorkspaceReaderConformance} found. The reader conforms when `problems` is empty. */
+export interface WorkspaceReaderConformanceReport {
+  /** Every problem, each starting with the command it concerns, or `workspace:` for a changed file. */
+  problems: string[];
+  /** The commands read, in contract order. */
+  checked: ReadContractCommand[];
+  /** The commands not in `commands`, so not applicable to this reader. */
+  skipped: ReadContractCommand[];
+  results: ReaderReadResult[];
+  /** The workspace that was read. A generated one is removed before the report is returned. */
+  workspaceDir: string;
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** The package this module ships in: `packages/core` in the repository, `node_modules/@intentius/chant` when installed. */
+const packageRoot = resolve(here, "..", "..", "..");
+const workspaceSrc = resolve(here, "..");
+/**
+ * The fixture the generated workspace is copied from, shipped under `src/`.
+ * Its `__fixture__` name keeps `chant workspace init` on the chant repository
+ * from proposing its projects as members.
+ */
+export const CONFORMANCE_FIXTURE_DIR = join(here, "__fixture__");
+
+/** The chant repository this module is part of, when it is not an installed copy. */
+function chantCheckout(): string | undefined {
+  const root = resolve(packageRoot, "..", "..");
+  const inCheckout =
+    existsSync(join(root, "reference-workspace", "chant.workspace.json")) &&
+    existsSync(join(packageRoot, "src", "cli", "main.ts")) &&
+    existsSync(join(root, "node_modules", "tsx", "dist", "loader.mjs"));
+  return inCheckout ? root : undefined;
+}
+
+/** The chant the suite runs when `chantCommand` is not given. */
+export function defaultChantCommand(cwd: string = process.cwd()): string[] {
+  const checkout = chantCheckout();
+  if (checkout) {
+    return [process.execPath, "--import", pathToFileURL(join(checkout, "node_modules", "tsx", "dist", "loader.mjs")).href, join(packageRoot, "src", "cli", "main.ts")];
+  }
+  for (let at = resolve(cwd); ; at = dirname(at)) {
+    const bin = join(at, "node_modules", ".bin", "chant");
+    if (existsSync(bin)) return [bin];
+    if (dirname(at) === at) break;
+  }
+  // The chant this module shipped with, so the suite and the chant agree on the contract.
+  const own = join(packageRoot, "bin", "chant");
+  return [existsSync(own) ? own : "chant"];
+}
+
+/** The reference workspace in the chant repository, or undefined in an installed copy. */
+export function referenceWorkspaceDir(): string | undefined {
+  const checkout = chantCheckout();
+  return checkout ? join(checkout, "reference-workspace") : undefined;
+}
+
+type Validate = ((d: unknown) => boolean) & { errors?: unknown };
+const validators = new Map<ReadContractCommand, { validate: Validate; id: string }>();
+
+/** A command's output schema and a draft 2020-12 validator for it, from this package's own ajv 8. */
+export function readContractSchema(command: ReadContractCommand): { schema: { $id: string }; validate: Validate } {
+  const schema = JSON.parse(readFileSync(join(workspaceSrc, READ_CONTRACT_SCHEMAS[command]), "utf-8")) as { $id: string };
+  let v = validators.get(command);
+  if (!v) {
+    const mod = createRequire(import.meta.url)("ajv/dist/2020") as { default?: unknown };
+    const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+    v = { validate: new Ajv({ strict: true, allErrors: true }).compile(schema), id: schema.$id };
+    validators.set(command, v);
+  }
+  return { schema, validate: v.validate };
+}
+
+/** A digest of every file under `dir`, skipping node_modules. */
+export function treeDigest(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (at: string, prefix: string) => {
+    for (const e of readdirSync(at, { withFileTypes: true })) {
+      if (e.name === "node_modules") continue;
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(join(at, e.name), rel);
+      else if (e.isFile()) out[rel] = createHash("sha256").update(readFileSync(join(at, e.name))).digest("hex");
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+/** The files that differ between two {@link treeDigest}s: added, removed or changed. */
+export function treeChanges(before: Record<string, string>, after: Record<string, string>): string[] {
+  const out: string[] = [];
+  for (const [f, h] of Object.entries(after)) if (before[f] === undefined) out.push(`${f} (added)`);
+  else if (before[f] !== h) out.push(`${f} (changed)`);
+  for (const f of Object.keys(before)) if (after[f] === undefined) out.push(`${f} (removed)`);
+  return out.sort();
+}
+
+/**
+ * What is wrong with the chant calls one read made: anything but exactly one
+ * call, of `workspace <command>` with `args` in order and the command's JSON
+ * flag, and nothing else. Empty when the calls conform.
+ */
+export function readerCallProblems(command: ReadContractCommand, args: string[], calls: string[][]): string[] {
+  if (calls.length !== 1) return [`${command}: made ${calls.length} chant calls (${calls.map((c) => c.join(" ")).join("; ")}), expected exactly one`];
+  const argv = calls[0];
+  const prefix = ["workspace", ...command.split(" ")];
+  if (prefix.some((t, i) => argv[i] !== t)) return [`${command}: ran chant ${argv.join(" ")}, which is not workspace ${command}`];
+  const rest = argv.slice(prefix.length);
+  const at = rest.findIndex((_, i) => args.every((a, j) => rest[i + j] === a));
+  if (args.length > 0 && at === -1) return [`${command}: ran chant ${argv.join(" ")}, which does not pass ${args.join(" ")} in order`];
+  const extra = args.length > 0 ? [...rest.slice(0, at), ...rest.slice(at + args.length)] : rest;
+  const allowed = READ_CONTRACT_JSON_FLAGS[command];
+  if (!allowed.some((flags) => flags.length === extra.length && flags.every((f, i) => extra[i] === f))) {
+    return [`${command}: ran chant ${argv.join(" ")}; beyond the command and its arguments it may add only ${allowed.map((f) => (f.length ? f.join(" ") : "nothing")).join(" or ")}, and it added ${extra.join(" ") || "nothing"}`];
+  }
+  return [];
+}
+
+/**
+ * Everything wrong with one read: the chant calls it made (`calls`, and
+ * `printed`, what each printed), and the document the reader returned
+ * (`doc`). Checks points 1 to 3 of the suite; empty when the read conforms.
+ */
+export function checkReaderRead(command: ReadContractCommand, args: string[], calls: string[][], printed: ChantRun[], doc: unknown): string[] {
+  const problems = readerCallProblems(command, args, calls);
+  if (problems.length > 0) return problems;
+  const run = printed[0];
+  if (!run || run.stdout.trim() === "") return [`${command}: chant ${calls[0].join(" ")} printed nothing${run?.stderr ? `; stderr: ${run.stderr.trim()}` : ""}`];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(run.stdout);
+  } catch (e) {
+    return [`${command}: chant ${calls[0].join(" ")} printed something that is not JSON (${(e as Error).message}); stderr: ${run.stderr.trim()}`];
+  }
+  if (!isDeepStrictEqual(doc, parsed)) problems.push(`${command}: the reader must return the document chant printed, unchanged, and it returned something else`);
+  const { schema, validate } = readContractSchema(command);
+  if (!validate(doc)) problems.push(`${command}: the document does not validate against ${READ_CONTRACT_SCHEMAS[command]}: ${JSON.stringify(validate.errors)}`);
+  const head = (doc ?? {}) as { $schema?: unknown; contract?: unknown };
+  if (head.$schema !== schema.$id) problems.push(`${command}: $schema is ${JSON.stringify(head.$schema)}, expected ${schema.$id}`);
+  if (head.contract !== READ_CONTRACT_VERSION) problems.push(`${command}: contract is ${JSON.stringify(head.contract)}, expected ${READ_CONTRACT_VERSION}`);
+  return problems;
+}
+
+/** The commands to exercise and the ones skipped, from `commands`. Throws on a name that is not a contract command. */
+export function selectCommands(commands?: readonly ReadContractCommand[]): { checked: ReadContractCommand[]; skipped: ReadContractCommand[] } {
+  if (commands === undefined) return { checked: [...READ_CONTRACT_COMMANDS], skipped: [] };
+  const unknown = commands.filter((c) => !(READ_CONTRACT_COMMANDS as readonly string[]).includes(c));
+  if (unknown.length > 0) throw new Error(`not read-contract commands: ${unknown.join(", ")}; the commands are ${READ_CONTRACT_COMMANDS.join(", ")}`);
+  if (commands.length === 0) throw new Error("commands is empty; list at least one read-contract command");
+  return { checked: READ_CONTRACT_COMMANDS.filter((c) => commands.includes(c)), skipped: READ_CONTRACT_COMMANDS.filter((c) => !commands.includes(c)) };
+}
+
+const GIT_ENV = { GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync("git", ["-c", "user.name=chant", "-c", "user.email=chant@localhost", "-c", "commit.gpgsign=false", ...args], {
+    cwd,
+    env: { ...process.env, ...GIT_ENV },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/** A workspace generated for a conformance run, and how to remove it. */
+export interface ConformanceWorkspace {
+  dir: string;
+  dispose(): void;
+}
+
+/**
+ * Generate the conformance workspace in a temporary directory: copy
+ * `__fixture__/`, link this package in as `node_modules/@intentius/chant`
+ * so the chant member resolves it, declare the workspace with
+ * `chant workspace init --yes --name conformance` and commit it all to a new
+ * git repository on `main`.
+ */
+export function createConformanceWorkspace(options: { chantCommand?: string[]; timeoutMs?: number } = {}): ConformanceWorkspace {
+  const chant = options.chantCommand ?? defaultChantCommand();
+  const scratch = realpathSync(mkdtempSync(join(tmpdir(), "chant-reader-conformance-")));
+  const dispose = () => rmSync(scratch, { recursive: true, force: true });
+  try {
+    const dir = join(scratch, "ws");
+    cpSync(CONFORMANCE_FIXTURE_DIR, dir, { recursive: true });
+    // npm leaves .gitignore out of a package, so it is written here.
+    writeFileSync(join(dir, ".gitignore"), "node_modules/\n");
+    mkdirSync(join(dir, "node_modules", "@intentius"), { recursive: true });
+    symlinkSync(packageRoot, join(dir, "node_modules", "@intentius", "chant"), "junction");
+    git(dir, "init", "--quiet", "--initial-branch=main");
+    execFileSync(chant[0], [...chant.slice(1), "workspace", "init", "--yes", "--name", "conformance"], {
+      cwd: dir,
+      env: { ...process.env, ...GIT_ENV, NO_COLOR: "1" },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: options.timeoutMs ?? 120_000,
+    });
+    git(dir, "add", "-A");
+    git(dir, "commit", "--quiet", "-m", "the reader conformance workspace");
+    return { dir, dispose };
+  } catch (e) {
+    dispose();
+    const err = e as Error & { stderr?: Buffer | string };
+    throw new Error(`could not generate the reader conformance workspace: ${err.message}${err.stderr ? `\n${String(err.stderr)}` : ""}`);
+  }
+}
+
+/** The workspace and chant a run uses, from its options. `dispose` removes a generated workspace. */
+export function conformanceTarget(options: WorkspaceReaderConformanceOptions = {}): { workspaceDir: string; chantCommand: string[]; dispose(): void } {
+  const chantCommand = options.chantCommand ?? defaultChantCommand();
+  const given = options.workspaceDir ?? referenceWorkspaceDir();
+  if (given) return { workspaceDir: given, chantCommand, dispose: () => {} };
+  const ws = createConformanceWorkspace({ chantCommand, timeoutMs: options.timeoutMs });
+  return { workspaceDir: ws.dir, chantCommand, dispose: ws.dispose };
+}
+
+/** Run `command` in `cwd`, collecting what it printed. Resolves, never rejects. */
+function runChant(command: string[], argv: string[], cwd: string, timeoutMs: number): Promise<ChantRun> {
+  return new Promise((settle) => {
+    const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf-8").on("data", (s: string) => (stdout += s));
+    child.stderr.setEncoding("utf-8").on("data", (s: string) => (stderr += s));
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      settle({ argv: [...argv], status: null, stdout, stderr: `${stderr}${e.message}` });
+    });
+    child.on("close", (status) => {
+      clearTimeout(timer);
+      settle({ argv: [...argv], status, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * A transport that runs chant in the workspace `target()` names and records
+ * every call and what it printed. `reset()` clears the record before a read.
+ */
+export function recordingTransport(target: () => { workspaceDir: string; chantCommand: string[] }, timeoutMs = 120_000) {
+  const calls: string[][] = [];
+  const printed: ChantRun[] = [];
+  const transport: ChantTransport = {
+    async run(argv) {
+      calls.push([...argv]);
+      const t = target();
+      const run = await runChant(t.chantCommand, argv, t.workspaceDir, timeoutMs);
+      printed.push(run);
+      return run;
+    },
+  };
+  return {
+    transport,
+    calls,
+    printed,
+    reset() {
+      calls.length = 0;
+      printed.length = 0;
+    },
+  };
+}
+
+/** Make one read through a recording transport and check it. A reader that throws is a problem, not an error. */
+export async function readAndCheck(reader: WorkspaceReader, recorder: ReturnType<typeof recordingTransport>, command: ReadContractCommand): Promise<ReaderReadResult> {
+  const args = [...REFERENCE_READS[command]];
+  recorder.reset();
+  let doc: unknown;
+  try {
+    doc = await reader.read(command, [...args]);
+  } catch (e) {
+    const stderr = recorder.printed[0]?.stderr.trim();
+    return { command, args, problems: [`${command}: the reader threw: ${(e as Error).message}${stderr ? `; chant's stderr: ${stderr}` : ""}`] };
+  }
+  return { command, args, problems: checkReaderRead(command, args, recorder.calls, recorder.printed, doc) };
+}
+
+/**
+ * Hold a reader to the read contract, with no test runner: read each listed
+ * command once through a recording transport, check the four points, and
+ * return what is wrong. The reader conforms when `problems` is empty.
+ *
+ * ```js
+ * import { test } from "node:test";
+ * import assert from "node:assert/strict";
+ * import { runWorkspaceReaderConformance } from "@intentius/chant/workspace/conformance";
+ *
+ * test("my reader reads only through the contract", { timeout: 600_000 }, async () => {
+ *   const report = await runWorkspaceReaderConformance(myReader, { commands: ["ls", "status"] });
+ *   assert.deepEqual(report.problems, []);
+ * });
+ * ```
+ */
+export async function runWorkspaceReaderConformance(reader: WorkspaceReaderFactory, options: WorkspaceReaderConformanceOptions = {}): Promise<WorkspaceReaderConformanceReport> {
+  const { checked, skipped } = selectCommands(options.commands);
+  const target = conformanceTarget(options);
+  try {
+    const recorder = recordingTransport(() => target, options.timeoutMs);
+    const built = reader(recorder.transport);
+    const before = treeDigest(target.workspaceDir);
+    const results: ReaderReadResult[] = [];
+    for (const command of checked) results.push(await readAndCheck(built, recorder, command));
+    const changed = treeChanges(before, treeDigest(target.workspaceDir));
+    const problems = results.flatMap((r) => r.problems);
+    if (changed.length > 0) problems.push(`workspace: the reads changed files: ${changed.join(", ")}`);
+    return { problems, checked, skipped, results, workspaceDir: target.workspaceDir };
+  } finally {
+    target.dispose();
+  }
+}