@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/migration-dirs.ts

@@ -0,0 +1,267 @@
+/**
+ * The readers for goose, golang-migrate and clickhouse-migrations
+ * directories (#4400). Each lists the migrations in the order the tool
+ * applies them. None runs the tool or a server: the schema the migrations
+ * produce comes from a replay.
+ *
+ * File layouts, checked against the tools' own docs and source:
+ *
+ * - goose (pressly/goose 9a201bb): `<version>_<name>.sql` directly in the
+ *   directory, the version a positive integer before the first `_`
+ *   (`NumericComponent`, migration.go); ordered by that number, so a
+ *   sequential `00001` and a timestamp `20240101120000` sort together.
+ *   A file holds `-- +goose Up` and, optionally, a later `-- +goose Down`
+ *   (internal/sqlparser/parser.go); `-- +goose NO TRANSACTION` runs it
+ *   outside a transaction. `.go` migrations are listed in the version order
+ *   but are code, so each is a gap.
+ * - golang-migrate (golang-migrate/migrate 504568a): `<version>_<name>.up.<ext>`
+ *   and `.down.<ext>` directly in the directory, matched by
+ *   `^([0-9]+)_(.*)\.(down|up)\.(.*)$` (source/parse.go); ordered by the
+ *   version, a 64-bit unsigned integer. The up files are the migrations; a
+ *   version with a down file and no up file, or two files for one version
+ *   and direction, is a gap.
+ * - clickhouse-migrations, the Python tool (zifter/clickhouse-migrations) and
+ *   the Node tool (npm clickhouse-migrations): `<version>_<name>.sql` directly
+ *   in the migrations directory, the version an integer before the first `_`,
+ *   applied in ascending numeric order. The Python tool also reads an
+ *   optional `<version>_<name>.down.sql` rollback beside it. The dialect is
+ *   always ClickHouse.
+ *
+ * What the migrations produce comes from a replay (`chant sql replay`), which
+ * records the tables and columns in {@link REPLAY_FILE} beside the
+ * migrations. Each reader returns them as the member's outputs when the
+ * recorded digest still matches the files, and a gap that says to replay
+ * again when it does not (see {@link withReplay}).
+ *
+ * The member's `migrationsDir` field names the directory under the member's
+ * own, and `dialect` names the dialect for goose and golang-migrate, whose
+ * tools take it from a driver or URL the directory does not hold.
+ */
+
+import { createHash } from "node:crypto";
+import type { KindLinkRead, KindReadGap, KindReadMigration, KindReaderInput } from "./kind-link-readers";
+import type { FieldValue } from "./kinds";
+import { joinPath, type WorkspaceTree } from "./tree";
+
+/** The dialects a migration directory's `dialect` field names. */
+export const MIGRATION_DIALECTS = ["postgres", "clickhouse"] as const;
+
+export function fieldString(fields: KindReaderInput["fields"], name: string, fallback: string): string {
+  const v = fields?.[name] as FieldValue | null | undefined;
+  return typeof v === "string" && v !== "" ? v : fallback;
+}
+
+/** The directory a reader lists: the member's `migrationsDir` under its own directory. */
+export function migrationsDirOf(input: KindReaderInput): string {
+  const sub = fieldString(input.fields, "migrationsDir", ".");
+  return joinPath(input.dir, sub.replace(/^\.\/?/, ""));
+}
+
+function filesIn(tree: WorkspaceTree, dir: string): string[] {
+  return (tree.list(dir) ?? []).filter((e) => e.type === "file").map((e) => e.name).sort();
+}
+
+const lineOf = (text: string, pred: (line: string) => boolean): number => {
+  const i = text.split(/\r?\n/).findIndex(pred);
+  return i < 0 ? 0 : i + 1;
+};
+
+/** The goose annotation on `line` (`up`, `down`, `no transaction`, ...), or undefined when it holds none. Mirrors the parser's rule: a comment that contains `+goose`. */
+export function gooseAnnotation(line: string): string | undefined {
+  const t = line.trim();
+  if (!t.startsWith("--") || !t.includes("+goose")) return undefined;
+  return t.replace("+goose", "").replace(/^--\s*/, "").trim().toLowerCase();
+}
+
+function listGooseDir(input: KindReaderInput): KindLinkRead {
+  const { tree } = input;
+  const dir = migrationsDirOf(input);
+  const dialect = fieldString(input.fields, "dialect", "postgres");
+  const gaps: KindReadGap[] = [];
+  const result: KindLinkRead = { reader: "goose-dir", links: [], gaps, migrations: [] };
+  const found: { n: number; migration: KindReadMigration | null; file: string }[] = [];
+  for (const name of filesIn(tree, dir)) {
+    const ext = name.endsWith(".sql") ? ".sql" : name.endsWith(".go") && !name.endsWith("_test.go") ? ".go" : null;
+    if (!ext) continue;
+    const file = joinPath(dir, name);
+    const before = name.split("_")[0] ?? "";
+    const n = /^[0-9]+$/.test(before) && name.includes("_") ? Number(before) : NaN;
+    if (!Number.isSafeInteger(n) || n < 1) {
+      gaps.push({ file, line: 1, message: `${name} has no version goose can read: the name starts with a positive integer, then _, so goose would stop here` });
+      continue;
+    }
+    if (ext === ".go") {
+      gaps.push({ file, line: 1, message: `${name} is a Go migration; its code is not SQL, so it is not listed` });
+      found.push({ n, migration: null, file });
+      continue;
+    }
+    const text = tree.read(file);
+    const up = lineOf(text, (l) => gooseAnnotation(l) === "up");
+    if (up === 0) {
+      gaps.push({ file, line: 1, message: `${name} has no -- +goose Up annotation, so goose refuses it` });
+      continue;
+    }
+    const down = lineOf(text, (l) => gooseAnnotation(l) === "down");
+    if (down !== 0 && down < up) gaps.push({ file, line: down, message: `${name}: -- +goose Down comes before -- +goose Up, which goose refuses` });
+    found.push({
+      n,
+      file,
+      migration: {
+        position: 0,
+        version: String(n),
+        name: name.slice(before.length + 1, -ext.length),
+        type: "versioned",
+        file,
+        line: up,
+        down: down !== 0,
+        dialect,
+        transaction: !text.split(/\r?\n/).some((l) => gooseAnnotation(l) === "no transaction"),
+      },
+    });
+  }
+  found.sort((a, b) => a.n - b.n || (a.file < b.file ? -1 : 1));
+  const seen = new Map<number, string>();
+  for (const f of found) {
+    const prior = seen.get(f.n);
+    if (prior) gaps.push({ file: f.file, line: 1, message: `version ${String(f.n)} is also ${prior}; goose refuses a duplicate version` });
+    else seen.set(f.n, f.file);
+  }
+  for (const f of found) if (f.migration) result.migrations!.push(f.migration);
+  result.migrations!.forEach((m, i) => (m.position = i + 1));
+  return result;
+}
+
+const MIGRATE_NAME = /^([0-9]+)_(.*)\.(down|up)\.(.*)$/;
+
+function listGolangMigrateDir(input: KindReaderInput): KindLinkRead {
+  const { tree } = input;
+  const dir = migrationsDirOf(input);
+  const dialect = fieldString(input.fields, "dialect", "postgres");
+  const gaps: KindReadGap[] = [];
+  const result: KindLinkRead = { reader: "golang-migrate-dir", links: [], gaps, migrations: [] };
+  const ups = new Map<bigint, { name: string; file: string; version: string }>();
+  const downs = new Map<bigint, string>();
+  for (const name of filesIn(tree, dir)) {
+    const m = MIGRATE_NAME.exec(name);
+    if (!m) continue;
+    const version = BigInt(m[1]!);
+    const file = joinPath(dir, name);
+    if (version > 18446744073709551615n) {
+      gaps.push({ file, line: 1, message: `${name}: the version does not fit a 64-bit unsigned integer, which golang-migrate requires` });
+      continue;
+    }
+    const table = m[3] === "up" ? ups : downs;
+    if (table.has(version)) {
+      gaps.push({ file, line: 1, message: `${name}: another ${m[3]!} file already has version ${m[1]!}; golang-migrate refuses a duplicate` });
+      continue;
+    }
+    if (m[3] === "up") ups.set(version, { name: m[2]!, file, version: m[1]! });
+    else downs.set(version, file);
+  }
+  for (const [v, file] of downs) if (!ups.has(v)) gaps.push({ file, line: 1, message: `version ${String(v)} has a down file and no up file` });
+  [...ups.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .forEach(([v, u], i) => result.migrations!.push({ position: i + 1, version: u.version, name: u.name, type: "versioned", file: u.file, line: 1, down: downs.get(v) ?? false, dialect }));
+  return result;
+}
+
+const CLICKHOUSE_NAME = /^([0-9]+)_(.+)\.sql$/;
+
+function listClickHouseMigrationsDir(input: KindReaderInput): KindLinkRead {
+  const { tree } = input;
+  const dir = migrationsDirOf(input);
+  const gaps: KindReadGap[] = [];
+  const result: KindLinkRead = { reader: "clickhouse-migrations-dir", links: [], gaps, migrations: [] };
+  const names = filesIn(tree, dir).filter((n) => n.endsWith(".sql"));
+  const rollbacks = new Map(names.filter((n) => n.endsWith(".down.sql")).map((n) => [n.slice(0, -".down.sql".length), joinPath(dir, n)]));
+  const ups: { n: bigint; version: string; name: string; file: string }[] = [];
+  for (const name of names) {
+    if (name.endsWith(".down.sql")) continue;
+    const m = CLICKHOUSE_NAME.exec(name);
+    if (!m) {
+      gaps.push({ file: joinPath(dir, name), line: 1, message: `${name} has no version before its first _, so clickhouse-migrations reports a bad file name` });
+      continue;
+    }
+    ups.push({ n: BigInt(m[1]!), version: m[1]!, name: m[2]!, file: joinPath(dir, name) });
+  }
+  ups.sort((a, b) => (a.n < b.n ? -1 : a.n > b.n ? 1 : a.file < b.file ? -1 : 1));
+  const seen = new Map<bigint, string>();
+  for (const u of ups) {
+    const prior = seen.get(u.n);
+    if (prior) gaps.push({ file: u.file, line: 1, message: `version ${u.version} is also ${prior}; leading zeros are not significant, so clickhouse-migrations reports a duplicate version` });
+    else seen.set(u.n, u.file);
+  }
+  ups.forEach((u, i) => result.migrations!.push({ position: i + 1, version: u.version, name: u.name, type: "versioned", file: u.file, line: 1, down: rollbacks.get(u.file.split("/").pop()!.slice(0, -".sql".length)) ?? false, dialect: "clickhouse" }));
+  return result;
+}
+
+/** The file a replay writes in the member's directory: the tables and columns the migrations produced, and the digest of the files it ran (#4400). */
+export const REPLAY_FILE = "chant.replay.json";
+
+/** What {@link REPLAY_FILE} holds. */
+export interface ReplaySnapshot {
+  schema: 1;
+  dialect: string;
+  /** {@link migrationDigest} of the files the replay ran. */
+  digest: string;
+  /** Names as `<schema>.<table>` and `<schema>.<table>.<column>` (Postgres), or `<database>...` (ClickHouse), the contract of #3931. */
+  outputs: string[];
+}
+
+/** A digest of the migration files in order, so a snapshot can tell the files changed. `extra` are files beside them that change what runs, such as Flyway's configuration. */
+export function migrationDigest(read: (file: string) => string, files: readonly string[]): string {
+  const h = createHash("sha256");
+  for (const f of files) {
+    h.update(f);
+    h.update("\0");
+    h.update(read(f));
+    h.update("\0");
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+/** The files a replay of `migrations` depends on, in order. */
+export function replayFiles(tree: WorkspaceTree, migrations: readonly KindReadMigration[], extra: readonly string[] = []): string[] {
+  return [...extra.filter((f) => tree.stat(f) === "file"), ...migrations.map((m) => m.file)];
+}
+
+/**
+ * Add the recorded replay to a reader's result: the snapshot's names as
+ * outputs when its digest matches the files, else a gap flagged `outputs`
+ * (a link into the member is then unresolved, not missing). A snapshot
+ * that does not parse is a gap too.
+ */
+export function withReplay(result: KindLinkRead, tree: WorkspaceTree, dir: string, extra: readonly string[] = []): KindLinkRead {
+  const file = joinPath(dir, REPLAY_FILE);
+  const migrations = result.migrations ?? [];
+  const gap = (message: string, line = 1) => result.gaps.push({ file: tree.stat(file) === "file" ? file : dir || ".", line, message, outputs: true });
+  if (tree.stat(file) !== "file") {
+    gap(`no ${REPLAY_FILE}: replay the migrations to record the tables and columns they produce (chant sql replay ${dir || "."})`);
+    return result;
+  }
+  let text: string;
+  let snap: Partial<ReplaySnapshot>;
+  try {
+    text = tree.read(file);
+    snap = JSON.parse(text) as Partial<ReplaySnapshot>;
+  } catch (err) {
+    gap(`${REPLAY_FILE} could not be read (${(err as Error).message}), so the tables the migrations produce are unknown`);
+    return result;
+  }
+  if (snap.schema !== 1 || typeof snap.digest !== "string" || !Array.isArray(snap.outputs) || snap.outputs.some((o) => typeof o !== "string")) {
+    gap(`${REPLAY_FILE} is not a replay snapshot (schema 1 with a digest and outputs), so the tables the migrations produce are unknown`);
+    return result;
+  }
+  const digest = migrationDigest((f) => tree.read(f), replayFiles(tree, migrations, extra));
+  if (digest !== snap.digest) {
+    gap(`the migrations changed since ${REPLAY_FILE} was recorded, so the tables they produce are unknown; replay again (chant sql replay ${dir || "."})`);
+    return result;
+  }
+  const lines = text.split("\n");
+  result.outputs = (snap.outputs as string[]).map((name) => ({ name, file, line: Math.max(1, lines.findIndex((l) => l.includes(JSON.stringify(name))) + 1) }));
+  return result;
+}
+
+export const readGooseDir = (input: KindReaderInput): KindLinkRead => withReplay(listGooseDir(input), input.tree, input.dir);
+export const readGolangMigrateDir = (input: KindReaderInput): KindLinkRead => withReplay(listGolangMigrateDir(input), input.tree, input.dir);
+export const readClickHouseMigrationsDir = (input: KindReaderInput): KindLinkRead => withReplay(listClickHouseMigrationsDir(input), input.tree, input.dir);

package/src/workspace/org-scope.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Org scope (#3168): a member of kind repo names another repository's
+ * workspace by URL and pinned revision, read read-only through that
+ * repository's own read contract; an org workspace holds only such members;
+ * `chant workspace check --forge-repos` compares them with the forge's list;
+ * and the read contract's identity names the repository a document came
+ * from. Every remote here is a local bare repository: nothing reaches a forge.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { parseForgeRepos, repoKey, urlCredential } from "./checks/org";
+import { readDeclaration, repoMemberDir } from "./declaration";
+import { workspaceGraph } from "./graph-cli";
+import { listWorkspace } from "./ls";
+import { fetchRepoAt, redactUrl, repoIdentity } from "./repo-ref";
+import { workingTree } from "./tree";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function tmp(prefix = "chant-3168-"): string {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+  scratch.push(d);
+  return d;
+}
+const git = (cwd: string, ...args: string[]) =>
+  execFileSync("git", ["-c", "user.email=t@example.com", "-c", "user.name=t", "-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf-8" }).trim();
+function write(root: string, files: Record<string, string>): void {
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+}
+
+/** A repository with a workspace, pushed to a local bare remote. Returns the bare URL and the commit. */
+function remoteWorkspace(name: string): { url: string; rev: string } {
+  const work = tmp();
+  git(work, "init", "-q", "-b", "main");
+  write(work, { "chant.workspace.json": JSON.stringify({ name, schema: 1, members: [{ name: "docs", dir: "docs", kind: "other", because: "prose" }] }), "docs/README.md": "" });
+  git(work, "add", "-A");
+  git(work, "commit", "-q", "-m", "init");
+  const bare = join(tmp(), `${name}.git`);
+  git(work, "clone", "-q", "--bare", work, bare);
+  return { url: bare, rev: git(work, "rev-parse", "HEAD") };
+}
+
+/** An org workspace in a git repository of its own, with origin set. */
+function orgWorkspace(members: unknown[], extra: Record<string, unknown> = {}): string {
+  const root = tmp();
+  git(root, "init", "-q");
+  git(root, "remote", "add", "origin", "https://bot:secret@forge.example/acme/org.git");
+  write(root, { "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, scope: "org", members, ...extra }) });
+  return root;
+}
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+const repoMember = (name: string, url: string, rev = SHA) => ({ name, kind: "repo", repo: { url, rev } });
+
+describe("the declaration: repo members and scope", () => {
+  test("a repo member has repo and no dir, and reads with a marker dir", () => {
+    const root = orgWorkspace([repoMember("chant", "https://github.com/INTENTIUS/chant"), { ...repoMember("ops", "git@github.com:INTENTIUS/ops.git"), repo: { url: "git@github.com:INTENTIUS/ops.git", rev: SHA, workspace: "infra" } }]);
+    const d = readDeclaration(workingTree(root));
+    expect(d.scope).toBe("org");
+    expect(d.members.map((m) => [m.dir, m.repo])).toEqual([
+      [repoMemberDir("chant"), { url: "https://github.com/INTENTIUS/chant", rev: SHA, workspace: "." }],
+      [repoMemberDir("ops"), { url: "git@github.com:INTENTIUS/ops.git", rev: SHA, workspace: "infra" }],
+    ]);
+  });
+
+  test("refuses a repo member with a dir, another kind with repo, and a revision that isn't a full commit id", () => {
+    const read = (members: unknown[]) => () => readDeclaration(workingTree(orgWorkspace(members)));
+    expect(read([{ ...repoMember("a", "x"), dir: "a" }])).toThrow(/a member of kind repo has no dir/);
+    expect(read([{ name: "a", dir: "a", kind: "other", because: "x", repo: { url: "x", rev: SHA } }])).toThrow(/only a member of kind repo has repo/);
+    expect(read([repoMember("a", "x", "main")])).toThrow(/"main" is not allowed here/);
+    expect(read([{ name: "a", kind: "repo" }])).toThrow(/needs "repo"/);
+  });
+});
+
+describe("repoKey and credentials", () => {
+  test("https, ssh and scp-style URLs of one repository compare equal", () => {
+    const keys = ["https://github.com/INTENTIUS/Chant.git", "https://github.com/intentius/chant/", "git@github.com:INTENTIUS/chant.git", "ssh://git@github.com/INTENTIUS/chant"].map((u) => repoKey(u));
+    expect(new Set(keys)).toEqual(new Set(["github.com/intentius/chant"]));
+    expect(repoKey("./x.git", "/base")).toBe("/base/x");
+    expect(repoKey("file:///srv/x.git")).toBe("/srv/x");
+  });
+
+  test("a password, or a user on https, is a credential; ssh's git user is not", () => {
+    expect(urlCredential("https://bot:tok@forge.example/a/b")).toBe(true);
+    expect(urlCredential("https://tok@forge.example/a/b")).toBe(true);
+    expect(urlCredential("ssh://git@forge.example/a/b")).toBe(false);
+    expect(urlCredential("git@forge.example:a/b")).toBe(false);
+    expect(redactUrl("https://bot:tok@forge.example/a/b")).toBe("https://forge.example/a/b");
+  });
+});
+
+describe("parseForgeRepos", () => {
+  test("reads an object with repos, a bare array, strings and objects", () => {
+    expect(parseForgeRepos(JSON.stringify({ forge: "github", org: "acme", repos: ["https://f/a/x", { url: "https://f/a/y", archived: true }] }), "f.json").repos).toEqual([
+      { url: "https://f/a/x", archived: false },
+      { url: "https://f/a/y", archived: true },
+    ]);
+    expect(parseForgeRepos(JSON.stringify(["https://f/a/x"]), "f.json").repos).toHaveLength(1);
+    expect(() => parseForgeRepos("{}", "f.json")).toThrow(/repos array/);
+    expect(() => parseForgeRepos("[1]", "f.json")).toThrow(/repos\[0\]/);
+    expect(() => parseForgeRepos("nope", "f.json")).toThrow(/not JSON/);
+  });
+});
+
+describe("chant workspace check on an org workspace", () => {
+  const ids = async (root: string, forge?: unknown) =>
+    (await runDeclarationChecks(root, (f) => f, forge ? { forgeRepos: parseForgeRepos(JSON.stringify(forge), "forge.json") } : {})).diagnostics
+      .filter((d) => /^WSP0(0[1-9]|1[0-6])$/.test(d.ruleId))
+      .map((d) => `${d.ruleId}:${d.entity ?? ""}`);
+
+  test("repo members need no directory: no WSP004, and nothing else fires", async () => {
+    expect(await ids(orgWorkspace([repoMember("a", "https://forge.example/acme/a")]))).toEqual([]);
+  });
+
+  test("WSP013: an org workspace holds only repo members", async () => {
+    const root = orgWorkspace([repoMember("a", "https://forge.example/acme/a"), { name: "docs", dir: "docs", kind: "other", because: "x" }]);
+    mkdirSync(join(root, "docs"));
+    expect(await ids(root)).toContain("WSP013:docs");
+  });
+
+  test("WSP014 names a repository the forge has and the declaration lacks; WSP015 one the forge dropped; archived ones need not be declared", async () => {
+    const root = orgWorkspace([repoMember("a", "git@forge.example:acme/a.git"), repoMember("gone", "https://forge.example/acme/gone")]);
+    const forge = { repos: ["https://forge.example/acme/a", "https://forge.example/acme/new", { url: "https://forge.example/acme/old", archived: true }] };
+    const report = await runDeclarationChecks(root, (f) => f, { forgeRepos: parseForgeRepos(JSON.stringify(forge), "forge.json") });
+    const found = report.diagnostics.filter((d) => d.ruleId === "WSP014" || d.ruleId === "WSP015").map((d) => `${d.ruleId}: ${d.message}`);
+    expect(found).toEqual([
+      expect.stringMatching(/^WSP014: the forge lists https:\/\/forge.example\/acme\/new \(forge.json\), and no repo member names it/),
+      expect.stringMatching(/^WSP015: member gone names https:\/\/forge.example\/acme\/gone, which the forge no longer lists/),
+    ]);
+    expect(report.ok).toBe(false);
+    // Without the list, neither runs: check never asks the forge.
+    expect(await ids(root)).toEqual([]);
+  });
+
+  test("WSP016: a repo url never carries a credential", async () => {
+    expect(await ids(orgWorkspace([repoMember("a", "https://bot:tok@forge.example/acme/a")]))).toEqual(["WSP016:a"]);
+  });
+});
+
+describe("the read contract's identity names the repository", () => {
+  test("ls prints workspace.repo, redacted, and each repo member's reference", () => {
+    const root = orgWorkspace([repoMember("a", "https://forge.example/acme/a")]);
+    const doc = listWorkspace({ cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.workspace.repo).toBe("https://forge.example/acme/org.git");
+    expect(doc.members[0]).toMatchObject({ name: "a", kind: "repo", readable: true, reason: null, repo: { url: "https://forge.example/acme/a", rev: SHA, workspace: "." } });
+  });
+
+  test("is null without an origin, or outside git", () => {
+    const plain = tmp();
+    git(plain, "init", "-q");
+    expect(repoIdentity(plain)).toBeNull();
+    expect(repoIdentity(tmp())).toBeNull();
+  });
+});
+
+describe("fetching a repo member's revision into the cache", () => {
+  test("fetches the pinned commit from a local bare remote into the user cache, once, and reports a commit it lacks", () => {
+    const remote = remoteWorkspace("payments");
+    const cache = tmp("chant-3168-cache-");
+    const env = { ...process.env, CHANT_CACHE_DIR: cache };
+    const first = fetchRepoAt({ url: remote.url, rev: remote.rev, workspace: "." }, "/", env);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    expect(first.dir.startsWith(join(cache, "repos"))).toBe(true);
+    expect(JSON.parse(readFileSync(join(first.dir, "chant.workspace.json"), "utf-8")).name).toBe("payments");
+    expect(git(first.dir, "rev-parse", "HEAD")).toBe(remote.rev);
+    expect(fetchRepoAt({ url: remote.url, rev: remote.rev, workspace: "." }, "/", env)).toEqual(first);
+    const missing = fetchRepoAt({ url: remote.url, rev: SHA, workspace: "." }, "/", env);
+    expect(missing).toMatchObject({ ok: false, message: expect.stringContaining(SHA) });
+  });
+});
+
+describe("chant workspace graph reads a repo member through its own read contract", () => {
+  test("runs the other repository's workspace graph at the pinned revision and folds it in, writing nothing in the workspace", async () => {
+    const remote = remoteWorkspace("payments");
+    const root = orgWorkspace([repoMember("payments", remote.url, remote.rev)]);
+    // A stand-in for the other repository's chant: it prints a graph document of the contract, with its argv and identity.
+    const bin = join(tmp(), "fake-chant.mjs");
+    writeFileSync(
+      bin,
+      `import { execFileSync } from "node:child_process";
+const argv = process.argv.slice(2);
+const at = argv[argv.indexOf("--at") + 1];
+const repo = execFileSync("git", ["config", "--get", "remote.origin.url"], { encoding: "utf-8" }).trim();
+const member = { name: "docs", dir: "docs", kind: "other", status: "composed", reason: null, chant: "9.9.9", irVersion: 1, live: false };
+console.log(JSON.stringify({ $schema: "https://intentius.io/chant/schemas/workspace/graph/v1/graph.schema.json", contract: 1, chant: "9.9.9", at, version: 1,
+  workspace: { name: "payments", root: ".", repo }, members: [member],
+  nodes: [{ id: "docs/Page", kind: "Page", lexicon: "x", attrs: {}, member: "docs" }], edges: [], groups: { byMember: { docs: ["docs/Page"] } },
+  exports: [], imports: [], links: [], collectors: [], records: [] }));
+`,
+    );
+    const cache = tmp("chant-3168-cache-");
+    const before = process.env.CHANT_CACHE_DIR;
+    process.env.CHANT_CACHE_DIR = cache;
+    try {
+      const { doc } = await workspaceGraph({ cwd: root, reader: { command: [process.execPath, bin], identity: bin, source: "path" } as never });
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.workspace).toMatchObject({ name: "acme", repo: "https://forge.example/acme/org.git" });
+      const m = doc.members.find((x) => x.name === "payments")!;
+      expect(m).toMatchObject({ kind: "repo", status: "composed", repo: { url: remote.url, rev: remote.rev, workspace: ".", read: remote.url } });
+      expect(m.nested?.name).toBe("payments");
+      expect(m.nested?.members.map((x) => x.name)).toEqual(["docs"]);
+      expect(doc.nodes.map((n) => n.id)).toEqual(["payments/docs/Page"]);
+      expect(existsSync(join(root, "@repo"))).toBe(false);
+      expect(git(root, "status", "--porcelain")).toBe("?? chant.workspace.json");
+    } finally {
+      if (before === undefined) delete process.env.CHANT_CACHE_DIR;
+      else process.env.CHANT_CACHE_DIR = before;
+    }
+  });
+
+  test("a revision the remote lacks fails the member with command-failed", async () => {
+    const remote = remoteWorkspace("payments");
+    const root = orgWorkspace([repoMember("payments", remote.url, SHA)]);
+    const before = process.env.CHANT_CACHE_DIR;
+    process.env.CHANT_CACHE_DIR = tmp("chant-3168-cache-");
+    try {
+      const { doc, failed } = await workspaceGraph({ cwd: root, reader: { command: ["false"], identity: "false", source: "path" } as never });
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(failed).toBe(true);
+      expect(doc.members[0]).toMatchObject({ status: "failed", reason: { code: "command-failed", message: expect.stringContaining(SHA) } });
+    } finally {
+      if (before === undefined) delete process.env.CHANT_CACHE_DIR;
+      else process.env.CHANT_CACHE_DIR = before;
+    }
+  });
+});

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

@@ -11,7 +11,7 @@ import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES, COMMIT_LINK_FINDING_CODES } from "./changes";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
-import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
+import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_EXECUTOR_REASON_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES, INTENT_WHY_CODES } from "./intent";
@@ -30,9 +30,11 @@ import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
 import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
+import { CI_BRANCH_FINDING_CODES } from "./checks/ci-branch";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
 import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
+import { LEDGER_READ_ERROR_CODES } from "../lifecycle/ledger-read";
 import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
@@ -72,6 +74,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   DIAGRAM_FINDING_CODES,
   SECURITY_FINDING_CODES,
   CI_WORKFLOW_FINDING_CODES,
+  CI_BRANCH_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,
@@ -100,6 +103,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   COMPOSITES_REASON_CODES,
   COMPOSITES_RUNTIME_REASON_CODES,
   COMPOSITES_ENVIRONMENT_REASON_CODES,
+  COMPOSITES_EXECUTOR_REASON_CODES,
   WORK_ERROR_CODES,
   WORK_HISTORY_ERROR_CODES,
   WORK_LEASE_REFUSALS,
@@ -108,6 +112,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RUNS_WRITE_ERROR_CODES,
   RUN_STATEMENT_ERROR_CODES,
   RUN_STATEMENT_FAILURE_CODES,
+  LEDGER_READ_ERROR_CODES,
   WORK_EVIDENCE_ERROR_CODES,
   RECORD_FINDING_CODES,
   FLAG_WARNING_CODES,

package/src/workspace/reason-codes.ts

@@ -66,6 +66,9 @@ export const REASONS = {
   // 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.",
+  // chant ledger (#4363): a read that can't start.
+  "filter-invalid": "A --where or --since names a field the read doesn't have, an operator its type doesn't take, or a value not of its type; nothing was read.",
+  "table-unknown": "chant ledger was given a table that is not one of resources, snapshots, runs, gates, deploys, releases or cuts.",
   // A member's gates status can't list (status, #2674).
   "gates-no-ledger": "The checkout has no chant/lifecycle branch, so there is no gate ledger to read.",
   "gates-no-gate-ledger": "The branch has no gate ledger for the member: no run of it has reached a gate.",
@@ -237,6 +240,9 @@ export const REASONS = {
   "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
   "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
   "environments-component-undeclared": "A component declares an environment its member's chant.config.ts environments don't cover, so chant run --env would refuse it and it is not listed (#3153).",
+  // The forge workflow that deploys an environment (graph --composites, #4402): an environment row's executor.reason.
+  "executor-none-declared": "The member's chant.config.ts declares no executor for the environment, so nothing names the forge workflow that deploys it.",
+  "executor-config-unreadable": "The member's chant.config.ts could not be read, so whether a forge workflow deploys the environment is unknown.",
   // A declared diagram's source or render (check, #2764). Each is also a WSP finding.
   "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
   "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
@@ -269,6 +275,7 @@ export const REASONS = {
   "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
   "ci-workflow-pipeline-differs": "Under ci.workflow, the pipeline does not match the workflow: it applies on merge under trunk-curated, records under trunk-curated+apply-on-merge, or applies before merge, or fails to, against apply-before-merge.",
   "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
+  "ci-branch-route-differs": "A member's generated pull-request pipeline targets a branch other than the one ci.branches routes the member to.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
@@ -291,6 +298,10 @@ export const REASONS = {
   "lease-held": "Someone holds a live lease on the work item: another worker, or, for a claim, the same one.",
   "lease-not-held": "Nobody holds a live lease on the work item: it expired, was released or was never claimed.",
   "lease-token-mismatch": "The live lease on the work item carries another fencing token than the one given.",
+  // Evidence that cites an ops result (work evidence, #3171): why the citation was refused. Nothing is written.
+  "work-evidence-ops-missing": "Work evidence cites a run, deploy, gate answer or release plan the local chant/lifecycle branch does not hold.",
+  "work-evidence-ops-mismatch": "Work evidence cites an ops record that does not hash to the sha256 given, or a run whose outcome disagrees with the evidence's result.",
+  "work-evidence-ops-unfinished": "Work evidence cites a run that is still gated or waiting, so it has no outcome to show.",
   "lease-race": "Another writer changed the lease between this command's read and its write.",
   "lease-push-rejected": "The remote refused the lease push: another clone claimed the item first, or the remote could not be reached.",
   // The agent run record (chant workspace runs, #3033): why a write was refused, and what a read could not see. Nothing is written on a refusal.