@intentius/chant 0.124.48 → 0.124.49

package/src/workspace/promote.test.ts

@@ -0,0 +1,114 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { GateLedgerPort } from "../op/gate";
+import { nextRung, promoteCommand, setMemberKind, type PromoteRunner } from "./promote";
+
+const git = (cwd: string, ...a: string[]) => execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", ...a], { cwd, encoding: "utf-8" });
+
+function ledger(): GateLedgerPort & { approve(digest: string): void } {
+  const pending: never[] = [];
+  const resolutions: unknown[] = [];
+  return {
+    async read() {
+      return { resolutions, pending } as never;
+    },
+    async appendPending(input: Record<string, unknown>) {
+      (pending as unknown[]).push({ ...input, at: new Date().toISOString() });
+      return { record: input, pushed: false } as never;
+    },
+    approve(digest: string) {
+      resolutions.push({ gate: "net", planDigest: digest, resolvedBy: "alex", outcome: "approved", at: new Date().toISOString() });
+    },
+  } as never;
+}
+
+describe("the ladder (#3178)", () => {
+  test("terraform to choudoufu, choudoufu or other to chant, chant has no rung", () => {
+    expect(nextRung("terraform")).toEqual({ from: "terraform", to: "choudoufu" });
+    expect(nextRung("choudoufu")?.to).toBe("chant");
+    expect(nextRung("other")?.to).toBe("chant");
+    expect(nextRung("chant")).toBeUndefined();
+  });
+  test("setMemberKind changes only the named member", () => {
+    const text = JSON.stringify({ name: "w", schema: 1, members: [{ name: "a", dir: "a", kind: "terraform" }, { name: "b", dir: "b", kind: "terraform" }] }, null, 2);
+    const out = JSON.parse(setMemberKind(text, "chant.workspace.json", "b", "choudoufu"));
+    expect(out.members.map((m: { kind: string }) => m.kind)).toEqual(["terraform", "choudoufu"]);
+  });
+});
+
+describe("chant workspace promote (#3178)", () => {
+  let root: string;
+  let calls: { argv: string[]; cwd: string }[];
+  const runner: PromoteRunner = async (argv, cwd) => {
+    calls.push({ argv, cwd });
+    if (argv[0] === "chant") mkdirSync(join(cwd, "src"), { recursive: true });
+    if (argv[0] === "chant") writeFileSync(join(cwd, "src", "index.ts"), "export {};\n");
+    return { exitCode: 0, output: "" };
+  };
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    calls = [];
+    root = mkdtempSync(join(tmpdir(), "chant-promote-test-"));
+    git(root, "init", "-q", "-b", "main");
+    mkdirSync(join(root, "net"));
+    writeFileSync(join(root, "net", "main.tf"), "# tf\n");
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [{ name: "net", dir: "net", kind: "terraform" }] }, null, 2) + "\n");
+    git(root, "add", "-A");
+    git(root, "commit", "-qm", "init");
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+  const kind = () => JSON.parse(readFileSync(join(root, "chant.workspace.json"), "utf-8")).members[0].kind;
+
+  test("terraform to choudoufu: runs live-check and the adoption report in a worktree, gates, then applies and stamps", async () => {
+    const l = ledger();
+    const first = await promoteCommand({ root, member: "net", state: "/s/terraform.tfstate", runner, ledger: l });
+    expect(first.outcome).toBe("gated");
+    expect(first.exitCode).toBe(3);
+    expect(calls.map((c) => c.argv.slice(0, 2).join(" "))).toEqual(["choudoufu live-check", "choudoufu live-import"]);
+    expect(calls.every((c) => !c.argv.includes("-approve") && c.cwd !== join(realpathSync(root), "net"))).toBe(true);
+    expect(kind()).toBe("terraform");
+
+    l.approve(first.digest!);
+    calls = [];
+    const second = await promoteCommand({ root, member: "net", state: "/s/terraform.tfstate", runner, ledger: l });
+    expect(second.outcome).toBe("applied");
+    expect(second.digest).toBe(first.digest);
+    expect(kind()).toBe("choudoufu");
+    expect(calls.at(-1)?.argv).toContain("-approve");
+    expect(calls.at(-1)?.cwd).toBe(join(realpathSync(root), "net"));
+  });
+
+  test("a failing live-check stops before any gate and leaves the tree alone", async () => {
+    const l = ledger();
+    const failing: PromoteRunner = async (argv) => ({ exitCode: argv[1] === "live-check" ? 2 : 0, output: "unsupported construct" });
+    const r = await promoteCommand({ root, member: "net", state: "s", runner: failing, ledger: l });
+    expect(r.outcome).toBe("checks-failed");
+    expect(kind()).toBe("terraform");
+    expect(git(root, "status", "--porcelain")).toBe("");
+    expect((await l.read("workspace-promote")).pending).toHaveLength(0);
+  });
+
+  test("choudoufu to chant runs chant import and the patch carries the generated files", async () => {
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [{ name: "net", dir: "net", kind: "choudoufu" }] }, null, 2) + "\n");
+    git(root, "commit", "-qam", "kind");
+    const l = ledger();
+    const first = await promoteCommand({ root, member: "net", runner, ledger: l, dryRun: true });
+    expect(first.outcome).toBe("dry-run");
+    expect(first.patch).toContain("net/src/index.ts");
+    expect(calls[0].argv).toEqual(["chant", "import", ".", "--lexicon", "terraform", "--output", "src/"]);
+    expect(git(root, "status", "--porcelain")).toBe("");
+  });
+
+  test("terraform needs --state, other needs --lexicon, chant is the top", async () => {
+    await expect(promoteCommand({ root, member: "net", runner })).rejects.toThrow(/--state/);
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "w", schema: 1, members: [{ name: "net", dir: "net", kind: "other", because: "x" }] }, null, 2) + "\n");
+    git(root, "commit", "-qam", "other");
+    await expect(promoteCommand({ root, member: "net", runner })).rejects.toThrow(/--lexicon/);
+  });
+});

package/src/workspace/promote.ts

@@ -0,0 +1,302 @@
+/**
+ * `chant workspace promote <member>` (#3178): move one member one rung up the
+ * kind ladder, `other` or `terraform`, then `choudoufu`, then `chant`.
+ *
+ * The change is staged the way `workspace upgrade` stages one (#2550): in a
+ * git worktree at HEAD, so the tree is never touched until the gate passes.
+ * The gate is `workspace-promote/<member>` on the gate ledger and binds the
+ * digest of the patch the staging produced. The first run records a pending
+ * fact and exits 3. After `chant approve workspace-promote <member>`, the same
+ * command stages again, finds the approval for the same digest, applies the
+ * patch, and runs the rung's follow-up (for `choudoufu`, stamping the
+ * ownership markers with `live-import -approve`).
+ *
+ * Rungs:
+ *
+ * - `terraform` to `choudoufu`: `choudoufu live-check` in the member's
+ *   directory must pass, then `choudoufu live-import -state=<--state>
+ *   -estate=<member>` prints its ratification report (read-only: it stamps
+ *   nothing without `-approve`). The patch changes the member's kind.
+ * - `choudoufu` or `other` to `chant`: `chant import` writes TypeScript into
+ *   the member's directory. The patch holds those files and the kind change.
+ *
+ * Commands run through an injectable runner, so a test never starts a binary.
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note";
+import { approveCommand, describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { WORKSPACE_PROMOTE_GATE_OP } from "../op/gate-name";
+import { DECLARATION_FILES, readDeclaration } from "./declaration";
+import { setProperty } from "./json-edit";
+import { workingTree } from "./tree";
+
+export const PROMOTE_PLAN_KIND = "workspace-promote";
+export const PROMOTE_GATED_EXIT = 3;
+const USAGE = "chant workspace promote <member> [--state <terraform.tfstate>] [--lexicon <lexicon>] [--dry-run] [--output <patch file>] [--json]";
+
+export class PromoteError extends Error {}
+
+/** The ladder, lowest rung first. `other` and `terraform` share the bottom rung. */
+export const LADDER = ["terraform", "choudoufu", "chant"] as const;
+
+export interface Rung {
+  from: string;
+  to: "choudoufu" | "chant";
+}
+
+/** The next rung for a member of `kind`, or undefined at the top or off the ladder. */
+export function nextRung(kind: string): Rung | undefined {
+  if (kind === "terraform") return { from: kind, to: "choudoufu" };
+  if (kind === "choudoufu" || kind === "other") return { from: kind, to: "chant" };
+  return undefined;
+}
+
+export interface CommandRun {
+  label: string;
+  argv: string[];
+  /** Directory relative to the project root. */
+  cwd: string;
+}
+export type PromoteRunner = (argv: string[], cwd: string) => Promise<{ exitCode: number; output: string }>;
+
+export const spawnRunner: PromoteRunner = (argv, cwd) =>
+  new Promise((done) => {
+    const [bin, ...rest] = argv;
+    const child = spawn(bin, rest, { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    const out: Buffer[] = [];
+    child.stdout.on("data", (c: Buffer) => out.push(c));
+    child.stderr.on("data", (c: Buffer) => out.push(c));
+    child.on("error", (e) => done({ exitCode: 127, output: String(e.message) }));
+    child.on("close", (code) => done({ exitCode: code ?? 1, output: Buffer.concat(out).toString("utf-8") }));
+  });
+
+/** The commands the rung runs in the staging worktree. */
+export function stagingRuns(rung: Rung, member: { name: string; dir: string }, opts: { state?: string; lexicon?: string }): CommandRun[] {
+  if (rung.to === "choudoufu") {
+    if (!opts.state) throw new PromoteError(`promoting ${member.name} to choudoufu reads its state for the adoption report: pass --state <terraform.tfstate>`);
+    return [
+      { label: "choudoufu live-check", argv: ["choudoufu", "live-check"], cwd: member.dir },
+      { label: "choudoufu live-import (report)", argv: ["choudoufu", "live-import", `-state=${opts.state}`, `-estate=${member.name}`], cwd: member.dir },
+    ];
+  }
+  const lexicon = opts.lexicon ?? (rung.from === "choudoufu" ? "terraform" : undefined);
+  if (!lexicon) throw new PromoteError(`promoting ${member.name} (kind other) to chant needs --lexicon <lexicon>: what chant import should read it as`);
+  return [{ label: "chant import", argv: ["chant", "import", ".", "--lexicon", lexicon, "--output", "src/"], cwd: member.dir }];
+}
+
+/** After the approved patch is applied: stamping ownership markers on the live resources. */
+export function followUpRuns(rung: Rung, member: { name: string; dir: string }, opts: { state?: string }): CommandRun[] {
+  if (rung.to !== "choudoufu") return [];
+  return [{ label: "choudoufu live-import -approve", argv: ["choudoufu", "live-import", `-state=${opts.state}`, `-estate=${member.name}`, "-approve"], cwd: member.dir }];
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+
+export interface PromoteOptions {
+  root: string;
+  member: string;
+  state?: string;
+  lexicon?: string;
+  dryRun?: boolean;
+  output?: string;
+  json?: boolean;
+  /** For tests. */
+  runner?: PromoteRunner;
+  ledger?: GateLedgerPort;
+  now?: string;
+}
+
+export type PromoteOutcome = "top-of-ladder" | "checks-failed" | "dry-run" | "gated" | "applied";
+export interface PromoteResult {
+  outcome: PromoteOutcome;
+  exitCode: number;
+  member: string;
+  from?: string;
+  to?: string;
+  digest?: string;
+  patch?: string;
+  ran?: { label: string; exitCode: number }[];
+}
+
+function declarationFile(root: string): string {
+  const f = DECLARATION_FILES.find((n) => existsSync(join(root, n)));
+  if (!f) throw new PromoteError(`no ${DECLARATION_FILES.join(" or ")} in ${root}`);
+  return f;
+}
+
+/** Rewrite the member's `kind` in the declaration text. */
+export function setMemberKind(text: string, file: string, member: string, kind: string): string {
+  const raw = (file.endsWith(".jsonc") ? text.replace(/^\s*\/\/.*$/gm, "") : text);
+  const parsed = JSON.parse(raw) as { members?: { name?: string }[] };
+  const i = (parsed.members ?? []).findIndex((m) => m.name === member);
+  if (i < 0) throw new PromoteError(`the declaration has no member "${member}"`);
+  return setProperty(text, file.endsWith(".jsonc"), `/members/${i}`, "kind", kind);
+}
+
+export async function promoteCommand(opts: PromoteOptions): Promise<PromoteResult> {
+  const root = realpathSync(resolve(opts.root));
+  const run = opts.runner ?? spawnRunner;
+  const decl = readDeclaration(workingTree(root));
+  const found = decl.members.find((m) => m.name === opts.member);
+  if (!found) throw new PromoteError(`the declaration has no member "${opts.member}"; chant workspace ls lists them`);
+  const say = (m: string): void => {
+    if (!opts.json) console.error(m);
+  };
+  const rung = nextRung(found.kind);
+  if (!rung) {
+    say(formatInfo(`${found.name} is kind ${found.kind}, which has no rung above it on the ladder (terraform or other, choudoufu, chant)`));
+    return { outcome: "top-of-ladder", exitCode: 0, member: found.name, from: found.kind };
+  }
+  const member = { name: found.name, dir: found.dir === "." ? "" : found.dir };
+  const staging = stagingRuns(rung, member, opts);
+
+  let repo: string;
+  let head: string;
+  try {
+    repo = git(root, ["rev-parse", "--show-toplevel"]).trim();
+    head = git(root, ["rev-parse", "HEAD"]).trim();
+  } catch {
+    throw new PromoteError("chant workspace promote stages its change in a git worktree, so the project must be in a git repository with at least one commit");
+  }
+  const projectRel = relative(repo, root).split(sep).join("/");
+  const declFile = declarationFile(root);
+  const watched = [declFile, member.dir].filter(Boolean).map((p) => [projectRel, p].filter(Boolean).join("/"));
+  const dirty = git(repo, ["status", "--porcelain", "--untracked-files=all", "--", ...watched]).split("\n").filter(Boolean);
+  if (dirty.length > 0) {
+    throw new PromoteError(`${found.name} has uncommitted changes (${dirty.slice(0, 5).map((l) => l.slice(3)).join(", ")}). Commit them: promote stages from HEAD and applies its patch to the tree.`);
+  }
+
+  const holder = mkdtempSync(join(tmpdir(), "chant-promote-"));
+  const worktree = join(holder, "wt");
+  const dispose = (): void => {
+    try {
+      git(repo, ["worktree", "remove", "--force", worktree]);
+    } catch {
+      // Fall through to the directory removal and a prune.
+    }
+    rmSync(holder, { recursive: true, force: true });
+    try {
+      git(repo, ["worktree", "prune"]);
+    } catch {
+      // Nothing to prune.
+    }
+  };
+
+  try {
+    git(repo, ["worktree", "add", "-q", "--detach", worktree, head]);
+    const project = projectRel ? join(worktree, projectRel) : worktree;
+    const ran: { label: string; exitCode: number }[] = [];
+    for (const step of staging) {
+      const cwd = join(project, step.cwd);
+      mkdirSync(cwd, { recursive: true });
+      const result = await run(step.argv, cwd);
+      ran.push({ label: step.label, exitCode: result.exitCode });
+      if (!opts.json) say(formatInfo(`${step.label}: exit ${result.exitCode}`));
+      if (result.exitCode !== 0) {
+        say(formatError({ message: `${step.label} failed in the staging worktree`, hint: result.output.trimEnd().split("\n").slice(-20).join("\n") }));
+        say(formatError({ message: "the promotion was not gated: its checks must pass first. The tree is unchanged." }));
+        if (opts.json) console.log(JSON.stringify({ outcome: "checks-failed", member: found.name, ran }, null, 2));
+        return { outcome: "checks-failed", exitCode: 1, member: found.name, from: rung.from, to: rung.to, ran };
+      }
+    }
+    const declPath = join(project, declFile);
+    writeFileSync(declPath, setMemberKind(readFileSync(declPath, "utf-8"), declFile, found.name, rung.to));
+    git(worktree, ["add", "-A"]);
+    const patch = git(worktree, ["diff", "--cached", "--binary", "HEAD"]);
+    const digest = computePlanDigest(PROMOTE_PLAN_KIND, { member: found.name, from: rung.from, to: rung.to, patch });
+    const base: PromoteResult = { outcome: "dry-run", exitCode: 0, member: found.name, from: rung.from, to: rung.to, digest, patch, ran };
+    const report = (outcome: PromoteOutcome, exitCode: number, extra: Record<string, unknown> = {}): PromoteResult => {
+      if (opts.json) console.log(JSON.stringify({ outcome, member: found.name, from: rung.from, to: rung.to, digest, ran, ...extra }, null, 2));
+      return { ...base, outcome, exitCode };
+    };
+    say(formatInfo(`${found.name}: ${rung.from} to ${rung.to}, patch ${digest}`));
+    if (opts.output) writeFileSync(resolve(opts.output), patch);
+    if (opts.dryRun) {
+      say(formatInfo("--dry-run: staged and checked; no gate recorded, the tree is unchanged"));
+      return report("dry-run", 0);
+    }
+
+    const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: repo }), {
+      op: WORKSPACE_PROMOTE_GATE_OP,
+      gate: found.name,
+      description: `promote ${found.name} from ${rung.from} to ${rung.to}`,
+      planDigest: digest,
+      ...(opts.now ? { now: opts.now } : {}),
+    });
+    if (!check.satisfied) {
+      if (!opts.json) {
+        const sealed = await gateIsSealed(found.name);
+        if (check.mismatch) console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_PROMOTE_GATE_OP, found.name, check.mismatch, sealed) }));
+        if (isLifecycleLocalNote(check.pushWarning)) console.error(formatInfo(LIFECYCLE_LOCAL_NOTE));
+        else if (check.pushWarning) console.error(formatWarning({ message: check.pushWarning }));
+        console.error(
+          formatInfo(
+            `Gated: the patch ${digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_PROMOTE_GATE_OP, found.name, undefined, undefined, sealed)}\` and repeat this command to apply it.`,
+          ),
+        );
+      }
+      return report("gated", PROMOTE_GATED_EXIT, { pending: check.pending });
+    }
+
+    const patchDir = mkdtempSync(join(tmpdir(), "chant-promote-patch-"));
+    try {
+      const file = join(patchDir, "promote.patch");
+      writeFileSync(file, patch);
+      try {
+        git(repo, ["apply", "--binary", "--whitespace=nowarn", file]);
+      } catch (err) {
+        const stderr = (err as { stderr?: Buffer | string }).stderr?.toString().trim();
+        throw new PromoteError(`the approved patch no longer applies to the tree${stderr ? `: ${stderr}` : ""}`);
+      }
+    } finally {
+      rmSync(patchDir, { recursive: true, force: true });
+    }
+    for (const step of followUpRuns(rung, member, opts)) {
+      const result = await run(step.argv, join(root, step.cwd));
+      ran.push({ label: step.label, exitCode: result.exitCode });
+      if (result.exitCode !== 0) {
+        say(formatError({ message: `${step.label} failed after the patch was applied`, hint: result.output.trimEnd().split("\n").slice(-20).join("\n") }));
+        return report("applied", 1, { followUpFailed: step.label });
+      }
+    }
+    say(formatSuccess(`applied the approved promotion of "${found.name}" to ${rung.to} (${digest}). Review and commit it.`));
+    return report("applied", 0);
+  } finally {
+    dispose();
+  }
+}
+
+export async function runWorkspacePromote(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (!args.extraPositional || args.extraPositional2) {
+    console.error(formatError({ message: "promote takes exactly one member", hint: USAGE }));
+    return 1;
+  }
+  try {
+    const result = await promoteCommand({
+      root: process.cwd(),
+      member: args.extraPositional,
+      state: args.statePath,
+      lexicon: args.lexicon,
+      dryRun: args.dryRun,
+      output: args.output,
+      json: args.json,
+    });
+    return result.exitCode;
+  } catch (err) {
+    if (err instanceof PromoteError) {
+      console.error(formatError({ message: err.message, hint: USAGE }));
+      return 1;
+    }
+    throw err;
+  }
+}

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

@@ -31,6 +31,7 @@ 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 { GATE_APPROVAL_FINDING_CODES } from "./checks/gate-approval";
 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";
@@ -51,6 +52,7 @@ import { DECLARATION_WRITE_ERROR_CODES } from "./declaration-write";
 import { TRUST_WRITE_ERROR_CODES } from "./trust/trust-write";
 import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
 import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
+import { EXIT_CODES } from "./exit";
 import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
 import { CI_GREEN_ERROR_CODES } from "./ci-green";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
@@ -75,6 +77,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   SECURITY_FINDING_CODES,
   CI_WORKFLOW_FINDING_CODES,
   CI_BRANCH_FINDING_CODES,
+  GATE_APPROVAL_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,
@@ -144,6 +147,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   SEARCH_MEMBER_REASON_CODES,
   CAPABILITIES_ERROR_CODES,
   CAPABILITY_SUPPORT_CODES,
+  EXIT_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

package/src/workspace/reason-codes.ts

@@ -275,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.",
+  "gate-approval-unbased": "An Op gate's approval block sets a quorum, policy, mode or context that identity.gates does not set at base, so the change being run can edit it.",
   "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.",
@@ -376,6 +377,19 @@ export const REASONS = {
   // 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.",
+  // workspace exit (#3177): why a member can't be exited, and what the exit drill finds wrong with one that was.
+  "missing-dir": "The chant member's directory does not exist, so there is nothing to build.",
+  "no-lexicon": "No lexicon is named in the member's chant.config.* or package.json, so there is nothing to build.",
+  "lexicon-unsupported": "A lexicon the member uses has no native target in workspace exit.",
+  "exit-failed": "The member's exit did not finish: its build failed, or it was refused.",
+  "choudoufu-steps-missing": "A choudoufu member's exit listed no roundtrip steps.",
+  "native-missing": "A native file the exit wrote is missing or empty.",
+  "native-unreadable": "A native file the exit wrote is not valid JSON, or has no content.",
+  "no-deploy-command": "A native file that can be deployed has no stock deploy command.",
+  "chant-config-left": "A chant.config.* file is still in the exited member.",
+  "chant-dependency": "The member's package.json still has a chant dependency, or a script that calls chant.",
+  "chant-in-ci": "A CI file of the exited member still calls chant.",
+  "declaration-not-other": "The declaration still gives the exited member a kind other than other.",
 } as const;
 
 export type ReasonCode = keyof typeof REASONS;

package/src/workspace/workspace-kinds.schema.json

@@ -190,6 +190,45 @@
             }
           },
           "additionalProperties": false
+        },
+        "anyDocument": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, parses as YAML or JSON and one of its documents satisfies an entry of match (#3179). An entry maps JSON Pointers to the values allowed there, all of which must hold; a * in a value matches any run of characters, so [\"*\"] means the pointer has a value. A file that does not parse is no evidence either way.",
+          "required": [
+            "in",
+            "match"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "match": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "minProperties": 1,
+                "propertyNames": {
+                  "pattern": "^(/[^/]+)+$"
+                },
+                "additionalProperties": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -201,22 +240,26 @@
     },
     "graph": {
       "type": "object",
-      "description": "How chant workspace graph reads a member of this kind (#2874). chant writes a reader project of its own outside the workspace, with a chant.config.json that declares lexicon and puts config under that lexicon's key, and runs the member's chant graph there. In every string key and value of config, {member} becomes the member's name, {dir} its absolute directory and {workspace} the absolute workspace root. Without this field a member of the kind is listed with kind-not-run.",
-      "required": [
-        "lexicon",
-        "config"
-      ],
+      "description": "How chant workspace graph reads a member of this kind (#2874, #4413). chant writes a reader project of its own outside the workspace and runs the member's chant graph there. The project either declares a lexicon and puts config under that lexicon's key (lexicon), or names a graph reader module the supplying package ships (reader). In every string key and value of config, {member} becomes the member's name, {dir} its absolute directory and {workspace} the absolute workspace root. Without this field a member of the kind is listed with kind-not-run.",
       "properties": {
         "lexicon": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]{0,39}$",
-          "description": "The lexicon that reads the member, by name. The package that supplies the kind must be @intentius/chant-lexicon-<lexicon>, so the lexicon chant loads is the one the declaration pins."
+          "description": "The lexicon that reads the member, by name. The package that supplies the kind must be @intentius/chant-lexicon-<lexicon>, so the lexicon chant loads is the one the declaration pins. Not with reader."
+        },
+        "reader": {
+          "type": "string",
+          "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)[^\\u0000-\\u001f]+$",
+          "description": "A graph reader module, as a path inside the supplying package (#4413): an ES module whose default export is (input: { dir, config }) => GraphIR. The member's own chant graph loads it in the reader project, so it runs under the member's toolchain, and it must only read files. Any package may supply it, not only a lexicon. Not with lexicon. A chant older than this field can't read a kinds file that uses it."
         },
         "config": {
           "type": "object",
-          "description": "The lexicon's config namespace for the reader project, such as terraform's roots. Placeholders are substituted; nothing else is interpreted."
+          "description": "With lexicon, the lexicon's config namespace for the reader project, such as terraform's roots. With reader, the config object the module is called with (optional). Placeholders are substituted; nothing else is interpreted."
         }
       },
+      "if": { "properties": { "reader": true }, "required": ["reader"] },
+      "then": { "not": { "properties": { "lexicon": true }, "required": ["lexicon"] } },
+      "else": { "properties": { "lexicon": true, "config": true }, "required": ["lexicon", "config"] },
       "patternProperties": {
         "^x-": true
       },