@intentius/chant 0.90.0 → 0.93.0

package/src/workspace/checks/boxes.ts

@@ -0,0 +1,442 @@
+/**
+ * The box checks, WSP121 and WSP122 (#2726).
+ *
+ * A member whose entry has a `box` block is a box, or holds a box's
+ * declarations. A box holds no credential: each capability it needs outside
+ * itself (inference, Fountain, a third-party API) is reached through a
+ * broker, a runtime such as a lobby or a door, which holds the credential
+ * and enforces the scope the block declares. chant only states and checks
+ * this; it never runs a broker (ws-052).
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP121 | `box-credential-declared` | a file in the box member's directory carries a literal secret (fixed) |
+ * | WSP122 | `box-capability-unbrokered` | a capability in the block names no broker |
+ *
+ * WSP121 reads the member's files from the tree checked, so it works under
+ * `--at`, and runs no member code. A literal secret is either a value with a
+ * well-known credential shape (an AWS key id, a GitHub or Slack token, an
+ * `sk-` key, private key material), wherever it sits, or a literal string
+ * where a credential goes: under a key named like one (`API_KEY`, `token`,
+ * `credential`, `password`, ...), or the `value` of a `{ key, value }` vault
+ * secret. A reference is never one: `${VAR}` and `$VAR`, a secret-manager
+ * reference (`op://`, `bws://`, `infisical://`), a `{{...}}` template
+ * placeholder, and any expression, such as `process.env.X`, that is not a
+ * string literal. WSP121 is fixed: a credential in a box's files is in git.
+ *
+ * WSP123 and WSP124, box isolation (#2727), are in `./box-isolation.ts` and
+ * listed here after these two.
+ *
+ * WSP125 (`box-fountain-callback-undeclared`, #2780) is the one credential a
+ * box gets without asking. fountain v0.21.0 gives every persistent sandbox a
+ * callback token scoped to its owner (`FOUNTAIN_TOKEN`, `sandbox_api_access:
+ * owner`), and a fountain `Box` is always persistent, so its member's block
+ * has to say so: the capability `fountain-callback`, brokered by `fountain`,
+ * with scope `owner`. It is named apart from `fountain`, the API access a
+ * lobby may broker for the same box. A member builds a Box when one of its TypeScript or JavaScript files
+ * imports `Box` from `@intentius/chant-lexicon-fountain` and calls it, read as
+ * syntax and never run. Upstream, managoat/fountain#2497 asks for a way to run
+ * a persistent agent with no callback token.
+ */
+
+import * as ts from "typescript";
+import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
+import type { Member } from "../declaration";
+import type { ReasonCode } from "../reason-codes";
+import { joinPath, skippedDir, type WorkspaceTree } from "../tree";
+import { BOX_ISOLATION_CHECKS } from "./box-isolation";
+
+/** The read contract's codes for the box findings, carried as `code` on each. */
+export const BOX_FINDING_CODES = [
+  "box-credential-declared",
+  "box-capability-unbrokered",
+  "box-isolation-collision",
+  "box-isolation-literal",
+  "box-fountain-callback-undeclared",
+] as const satisfies readonly ReasonCode[];
+
+export const WSP_BOX_CREDENTIAL = "WSP121";
+export const WSP_BOX_UNBROKERED = "WSP122";
+export const WSP_BOX_FOUNTAIN_CALLBACK = "WSP125";
+
+/** The fountain lexicon's package, whose `Box` composite runs a persistent sandbox. */
+const FOUNTAIN_LEXICON = "@intentius/chant-lexicon-fountain";
+
+/**
+ * The capability a box block declares for fountain's callback token (#2780).
+ * The fountain lexicon exports the same value as `BOX_FOUNTAIN_CALLBACK_CAPABILITY`.
+ */
+export const FOUNTAIN_CALLBACK_CAPABILITY = { name: "fountain-callback", broker: "fountain", scope: ["owner"] } as const;
+
+/** Where a file calls the fountain lexicon's `Box`, 1-based. */
+export interface FountainBoxCall {
+  line: number;
+  column: number;
+}
+
+/**
+ * The first call of the fountain lexicon's `Box` in a TypeScript or
+ * JavaScript file, read as syntax and never run: `Box` imported by name
+ * (aliased or not) and called, or called through a namespace import. Any
+ * other `Box` is not the composite.
+ */
+export function fountainBoxCall(text: string, file: string, kind: ts.ScriptKind): FountainBoxCall | undefined {
+  if (!text.includes(FOUNTAIN_LEXICON)) return undefined;
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+  const names = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const stmt of source.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const from = stmt.moduleSpecifier.text;
+    if (from !== FOUNTAIN_LEXICON && !from.startsWith(`${FOUNTAIN_LEXICON}/`)) continue;
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else for (const el of bindings.elements) if ((el.propertyName ?? el.name).text === "Box") names.add(el.name.text);
+  }
+  if (names.size === 0 && namespaces.size === 0) return undefined;
+  let found: ts.Node | undefined;
+  const visit = (node: ts.Node) => {
+    if (found) return;
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (
+        (ts.isIdentifier(callee) && names.has(callee.text)) ||
+        (ts.isPropertyAccessExpression(callee) &&
+          callee.name.text === "Box" &&
+          ts.isIdentifier(callee.expression) &&
+          namespaces.has(callee.expression.text))
+      ) {
+        found = node;
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  if (!found) return undefined;
+  const { line, character } = source.getLineAndCharacterOfPosition(found.getStart(source));
+  return { line: line + 1, column: character + 1 };
+}
+
+/** Values whose shape alone says they are a credential. The list FTN001 uses, plus Anthropic keys. */
+export const CREDENTIAL_SHAPES: readonly { pattern: RegExp; label: string }[] = [
+  { pattern: /\bAKIA[0-9A-Z]{16}\b/, label: "an AWS access key id" },
+  { pattern: /\b(?:ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}/, label: "a GitHub token" },
+  { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}/, label: "a GitHub fine-grained token" },
+  { pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/, label: "an Anthropic API key" },
+  { pattern: /\bsk-[A-Za-z0-9_-]{20,}/, label: "a secret API key (sk-)" },
+  { pattern: /\bftn_[A-Za-z0-9]{16,}/, label: "a Fountain API key" },
+  { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}/, label: "a Slack token" },
+  { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/, label: "private key material" },
+];
+
+/** Secret-manager references a value may be instead of the secret. */
+export const SECRET_REFERENCE_SCHEMES = ["op://", "bws://", "infisical://"] as const;
+
+/**
+ * A key whose value is a credential: `API_KEY`, `GITHUB_TOKEN`, `apiKey`,
+ * `token`, `credential`, `password`, `AWS_SECRET_ACCESS_KEY`. A key that
+ * names where a secret is (`secretKey`, `TOKEN_FILE`, `tokenHash`) is not.
+ */
+const CREDENTIAL_KEY = /(?:^|[_-])(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_?KEY|ACCESS_?KEY)$|^(?:apiKey|token|secret|password|credentials?|privateKey|accessKey|authToken)$|[a-z](?:ApiKey|Token|Secret|Password|Credentials?|PrivateKey|AccessKey)$/i;
+
+/** Whether `key` names a credential. Exported for tests. */
+export function isCredentialKey(key: string): boolean {
+  return CREDENTIAL_KEY.test(key);
+}
+
+/** Whether `value` refers to a secret rather than being one. Exported for tests. */
+export function isSecretReference(value: string): boolean {
+  const v = value.trim();
+  if (v === "") return true;
+  if (v.includes("${")) return true;
+  // $VAR, $1, $(command): the shell fills it in.
+  if (v.startsWith("$")) return true;
+  if (/^\{\{[^}]*\}\}$/.test(v)) return true;
+  return SECRET_REFERENCE_SCHEMES.some((s) => v.startsWith(s));
+}
+
+/**
+ * Whether a value under a credential key says where a secret is rather than
+ * being one: a path (`~/box/llm-token`, `/run/secrets/token`), a URL, or an
+ * environment variable's name (`GIT_TOKEN`).
+ */
+function namesWhereSecretIs(value: string): boolean {
+  const v = value.trim();
+  return /^(?:\/|~|\.\.?\/)/.test(v) || /^[a-z][a-z0-9+.-]*:\/\//i.test(v) || /^[A-Z][A-Z0-9_]*$/.test(v);
+}
+
+/** The credential shape `value` has, or undefined. */
+export function credentialShape(value: string): string | undefined {
+  return CREDENTIAL_SHAPES.find((s) => s.pattern.test(value))?.label;
+}
+
+/** One literal secret found in a file. */
+export interface LiteralSecret {
+  /** 1-based. */
+  line: number;
+  column: number;
+  /** What was found, for the message: never the value itself. */
+  what: string;
+}
+
+const CODE_EXTENSIONS: Record<string, ts.ScriptKind> = {
+  ".ts": ts.ScriptKind.TS,
+  ".mts": ts.ScriptKind.TS,
+  ".cts": ts.ScriptKind.TS,
+  ".tsx": ts.ScriptKind.TSX,
+  ".js": ts.ScriptKind.JS,
+  ".mjs": ts.ScriptKind.JS,
+  ".cjs": ts.ScriptKind.JS,
+  ".jsx": ts.ScriptKind.JSX,
+  ".json": ts.ScriptKind.JSON,
+  ".jsonc": ts.ScriptKind.JSON,
+};
+
+const PROSE_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".html", ".rst"]);
+
+/** Files larger than this are not read: a box's declarations are small, and a large file is data or a build. */
+const MAX_FILE_BYTES = 1024 * 1024;
+
+function propertyName(name: ts.PropertyName | undefined): string | undefined {
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text;
+  return undefined;
+}
+
+const isStringLiteral = (n: ts.Node): n is ts.StringLiteral | ts.NoSubstitutionTemplateLiteral => ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n);
+
+/**
+ * The literal secrets in a TypeScript, JavaScript or JSON file, read as
+ * syntax and never run.
+ */
+export function literalSecretsInCode(text: string, file: string, kind: ts.ScriptKind): LiteralSecret[] {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+  const out: LiteralSecret[] = [];
+  const at = (node: ts.Node, what: string) => {
+    const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    out.push({ line: line + 1, column: character + 1, what });
+  };
+  const reported = new Set<ts.Node>();
+  const visit = (node: ts.Node) => {
+    if (isStringLiteral(node) && !reported.has(node)) {
+      const shape = credentialShape(node.text);
+      if (shape && !isSecretReference(node.text)) {
+        reported.add(node);
+        at(node, shape);
+      }
+    }
+    if (ts.isPropertyAssignment(node) && isStringLiteral(node.initializer) && !reported.has(node.initializer)) {
+      const key = propertyName(node.name);
+      const value = node.initializer.text;
+      // A value with a credential's shape is reported by that shape, below.
+      if (key !== undefined && !isSecretReference(value) && !namesWhereSecretIs(value) && credentialShape(value) === undefined) {
+        if (isCredentialKey(key)) {
+          reported.add(node.initializer);
+          at(node.initializer, `a literal value for ${key}`);
+        } else if (key === "value" && ts.isObjectLiteralExpression(node.parent) && isVaultSecret(node.parent)) {
+          reported.add(node.initializer);
+          at(node.initializer, `a literal vault secret value for ${vaultSecretKey(node.parent) ?? "a key"}`);
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return out;
+}
+
+/** `{ key, value }` with nothing else but a description: the shape of a vault secret. */
+function isVaultSecret(obj: ts.ObjectLiteralExpression): boolean {
+  const names = obj.properties.map((p) => (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p) ? propertyName(p.name) : undefined));
+  return names.includes("key") && names.includes("value") && names.every((n) => n === "key" || n === "value" || n === "description");
+}
+
+function vaultSecretKey(obj: ts.ObjectLiteralExpression): string | undefined {
+  for (const p of obj.properties) {
+    if (ts.isPropertyAssignment(p) && propertyName(p.name) === "key" && isStringLiteral(p.initializer)) return p.initializer.text;
+  }
+  return undefined;
+}
+
+/** `KEY=value`, `export KEY=value` or `KEY: value`, the value optionally quoted. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*[=:]\s*(["']?)([^"'\s#]+)\2\s*(?:#.*)?$/;
+
+/**
+ * The literal secrets in any other text file, such as a shell script, an
+ * env file or YAML: a credential shape anywhere, or a line assigning a
+ * literal to a credential-named key.
+ */
+export function literalSecretsInText(text: string, assignments = true): LiteralSecret[] {
+  const out: LiteralSecret[] = [];
+  text.split(/\r?\n/).forEach((lineText, i) => {
+    for (const { pattern, label } of CREDENTIAL_SHAPES) {
+      const m = pattern.exec(lineText);
+      if (m && !isSecretReference(m[0])) {
+        out.push({ line: i + 1, column: m.index + 1, what: label });
+        return;
+      }
+    }
+    const a = assignments ? ASSIGNMENT.exec(lineText) : null;
+    if (a && isCredentialKey(a[1]) && !isSecretReference(a[3]) && !namesWhereSecretIs(a[3])) {
+      out.push({ line: i + 1, column: lineText.indexOf(a[3]) + 1, what: `a literal value for ${a[1]}` });
+    }
+  });
+  return out;
+}
+
+function extension(path: string): string {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+
+/** The literal secrets in one file, or none when the file is binary or too large. */
+export function literalSecretsInFile(text: string, path: string): LiteralSecret[] {
+  if (text.length > MAX_FILE_BYTES || text.includes("\0")) return [];
+  const kind = CODE_EXTENSIONS[extension(path)];
+  if (kind !== undefined) return literalSecretsInCode(text, path, kind);
+  // Prose says "Token: ..." without meaning one, so only a credential's shape counts there.
+  return literalSecretsInText(text, !PROSE_EXTENSIONS.has(extension(path)));
+}
+
+/** Every file under `dir` in `tree`, skipping node_modules and dot-directories, sorted. */
+function filesUnder(tree: WorkspaceTree, dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of tree.list(d) ?? []) {
+      const p = joinPath(d, e.name);
+      if (e.type === "dir") {
+        if (!skippedDir(e.name)) walk(p);
+      } else out.push(p);
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+const boxMembers = (ctx: WorkspaceCheckContext): Member[] => ctx.declaration.members.filter((m) => m.box !== null);
+
+export const BOX_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_BOX_CREDENTIAL,
+    name: "box-credential-declared",
+    description:
+      "A box holds no credential: no file in a box member's directory carries a literal secret, in its declarations, an env or a vault's defaults. Variable references and secret-manager references (op://, bws://, infisical://) are not secrets.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of boxMembers(ctx)) {
+        const dir = m.dir === "." ? "" : m.dir;
+        if (ctx.tree.stat(dir) !== "dir") continue;
+        for (const path of filesUnder(ctx.tree, dir)) {
+          let text: string;
+          try {
+            text = ctx.tree.read(path);
+          } catch {
+            continue;
+          }
+          for (const s of literalSecretsInFile(text, path)) {
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: "box-credential-declared",
+              message: `box-credential-declared: ${path} holds ${s.what}, and member ${m.name} is a box, which holds no credential; replace it with a \${VAR} or secret-manager reference, or declare the capability as brokered in the member's box block`,
+              entity: m.name,
+              pointer: m.box!.pointer,
+              treeFile: path,
+              line: s.line,
+              column: s.column,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: WSP_BOX_UNBROKERED,
+    name: "box-capability-unbrokered",
+    description: "Every capability a box declares names the broker that holds its credential and enforces its scope.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of boxMembers(ctx)) {
+        for (const c of m.box!.capabilities) {
+          if (c.broker !== null) continue;
+          out.push({
+            checkId: this.id,
+            severity: this.severity,
+            code: "box-capability-unbrokered",
+            message: `box-capability-unbrokered: member ${m.name}'s box needs ${c.name} and names no broker for it, so the box would hold its credential; set broker to the runtime that holds it, such as the lobby`,
+            entity: m.name,
+            pointer: c.pointer,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  // Box isolation (#2727), WSP123 and WSP124.
+  ...BOX_ISOLATION_CHECKS,
+  {
+    id: WSP_BOX_FOUNTAIN_CALLBACK,
+    name: "box-fountain-callback-undeclared",
+    description:
+      "A box member that builds a fountain Box declares the callback token fountain gives its persistent sandbox: the fountain-callback capability, brokered by fountain, with scope owner.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      const want = FOUNTAIN_CALLBACK_CAPABILITY;
+      const expected = `{ "name": "${want.name}", "broker": "${want.broker}", "scope": ["${want.scope[0]}"] }`;
+      for (const m of boxMembers(ctx)) {
+        const dir = m.dir === "." ? "" : m.dir;
+        if (ctx.tree.stat(dir) !== "dir") continue;
+        let at: { path: string; call: FountainBoxCall } | undefined;
+        for (const path of filesUnder(ctx.tree, dir)) {
+          const kind = CODE_EXTENSIONS[extension(path)];
+          if (kind === undefined || kind === ts.ScriptKind.JSON) continue;
+          let text: string;
+          try {
+            text = ctx.tree.read(path);
+          } catch {
+            continue;
+          }
+          if (text.length > MAX_FILE_BYTES) continue;
+          const call = fountainBoxCall(text, path, kind);
+          if (call) {
+            at = { path, call };
+            break;
+          }
+        }
+        if (!at) continue;
+        const declared = m.box!.capabilities.find((c) => c.name === want.name);
+        if (declared && declared.broker === want.broker && declared.scope.includes(want.scope[0])) continue;
+        const why = !declared
+          ? "the member's box block does not declare it"
+          : declared.broker !== want.broker
+            ? `the box block's ${want.name} capability names the broker ${declared.broker ?? "(none)"}, but fountain hands this token to the sandbox itself`
+            : `the box block's ${want.name} capability has scope [${declared.scope.join(", ")}], not ${want.scope[0]}`;
+        out.push({
+          checkId: this.id,
+          severity: this.severity,
+          code: "box-fountain-callback-undeclared",
+          message:
+            `box-fountain-callback-undeclared: member ${m.name} builds a fountain Box (${at.path}), and fountain v0.21.0 gives a persistent box's sandbox ` +
+            `a callback token scoped to its owner (FOUNTAIN_TOKEN); ${why}. Declare ${expected} in the box block ` +
+            `(managoat/fountain#2497 tracks running without it)`,
+          entity: m.name,
+          pointer: declared?.pointer ?? m.box!.pointer,
+          treeFile: at.path,
+          line: at.call.line,
+          column: at.call.column,
+        });
+      }
+      return out;
+    },
+  },
+];

package/src/workspace/checks/diagrams.test.ts

@@ -0,0 +1,134 @@
+/**
+ * The diagram checks, WSP131 to WSP133 (#2764).
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, 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 { sha256Hex } from "../../content-digest";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-diagrams-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const renderer = { tool: "d2", version: "0.9.0", args: ["--layout=elk", "--theme=0", "--pad=40", "--omit-version"] };
+const diagram = (extra: Record<string, unknown> = {}) => ({
+  name: "architecture",
+  title: "Studio architecture",
+  source: "docs/diagrams/architecture.d2",
+  render: "docs/diagrams/architecture.svg",
+  renderer,
+  ...extra,
+});
+
+const declaration = (diagrams: unknown[], extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name: "acme", schema: 1, members: [{ name: "docs", dir: "docs", kind: "other", because: "the docs site", diagrams }], ...extra }, null, 2);
+
+/** The findings, less WSP009, which every member of kind other gets. */
+const found = async (root: string) => (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId !== "WSP009");
+
+describe("diagram-source-missing (WSP131) and diagram-render-missing (WSP132)", () => {
+  test("both files present passes", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.d2": "x -> y",
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a missing source fails WSP131, and a missing render fails WSP132, each once", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity])).toEqual([["WSP131", "diagram-source-missing", "docs"]]);
+    expect(d[0].message).toContain("member docs's diagram architecture names the source docs/diagrams/architecture.d2, which does not exist");
+  });
+
+  test("no source (an SVG with none) is never checked for a source", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ source: null })]),
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a missing render fails WSP132", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.d2": "x -> y",
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code])).toEqual([["WSP132", "diagram-render-missing"]]);
+  });
+
+  test("the top-level (workspace's own) diagrams are checked too, reported with no entity", async () => {
+    const root = repo({ "chant.workspace.json": declaration([], { diagrams: [diagram({ name: "boundary" })] }), "docs/README.md": "" });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.entity])).toEqual([
+      ["WSP131", undefined],
+      ["WSP132", undefined],
+    ]);
+    expect(d[0].message).toContain("the workspace's own diagram boundary names the source");
+  });
+});
+
+describe("diagram-render-drift (WSP133)", () => {
+  const SOURCE = "x -> y\n";
+  const HASH = sha256Hex(Buffer.from(SOURCE, "utf-8"));
+
+  test("no recorded sourceHash: never checked for drift, even when the source changed", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram()]),
+      "docs/diagrams/architecture.d2": "something else entirely",
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a recorded sourceHash that matches the source passes", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),
+      "docs/diagrams/architecture.d2": SOURCE,
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a source that changed since the recorded hash fails WSP133, without running any renderer", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),
+      "docs/diagrams/architecture.d2": "x -> y -> z\n",
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code])).toEqual([["WSP133", "diagram-render-drift"]]);
+    expect(d[0].message).toContain("source docs/diagrams/architecture.d2 changed since docs/diagrams/architecture.svg was rendered from it");
+    expect(d[0].message).toContain(`recorded sourceHash ${HASH.slice(0, 12)}`);
+  });
+
+  test("a missing source is left to WSP131; WSP133 finds nothing to compare", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([diagram({ sourceHash: HASH })]),
+      "docs/diagrams/architecture.svg": "<svg></svg>",
+    });
+    const d = await found(root);
+    expect(d.map((x) => x.ruleId)).toEqual(["WSP131"]);
+  });
+});

package/src/workspace/checks/diagrams.ts

@@ -0,0 +1,108 @@
+/**
+ * The diagram checks, WSP131 to WSP133 (#2764).
+ *
+ * A declared diagram names a source and a render, pinned to the renderer
+ * its render was made with. chant never runs a renderer (ws-052), on a read
+ * path or here: these checks read the declaration and the tree checked
+ * only, and a render's drift is caught by comparing a recorded content hash,
+ * never by re-rendering the source.
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP131 | `diagram-source-missing` | a diagram names a source, and it does not exist in the tree read |
+ * | WSP132 | `diagram-render-missing` | a diagram's render does not exist in the tree read |
+ * | WSP133 | `diagram-render-drift` | a diagram records a `sourceHash`, and the source's bytes now hash to something else |
+ *
+ * WSP133 is opt-in per diagram: without a recorded `sourceHash` there is
+ * nothing to compare, so the entry is silently not checked for drift. A
+ * declaration records one by hashing the source when it commits a fresh
+ * render, the way a decision's evidence pins a file by hash
+ * (`../record-assets.ts`). Comparing that one recorded hash against the
+ * source in the tree read is cheap and deterministic, unlike shelling out to
+ * the pinned renderer and diffing its output, which chant does nowhere.
+ */
+
+import { sha256Hex } from "../../content-digest";
+import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
+import { declaredDiagrams, type DiagramDeclaration } from "../declaration";
+import type { ReasonCode } from "../reason-codes";
+
+/** The read contract's codes for the diagram findings, carried as `code` on each. */
+export const DIAGRAM_FINDING_CODES = ["diagram-source-missing", "diagram-render-missing", "diagram-render-drift"] as const satisfies readonly ReasonCode[];
+
+export const WSP_DIAGRAM_SOURCE_MISSING = "WSP131";
+export const WSP_DIAGRAM_RENDER_MISSING = "WSP132";
+export const WSP_DIAGRAM_RENDER_DRIFT = "WSP133";
+
+const where = (d: DiagramDeclaration) => (d.member === null ? "the workspace's own" : `member ${d.member}'s`);
+
+function diagramFinding(check: WorkspaceCheck, d: DiagramDeclaration, field: "source" | "render" | "sourceHash", code: (typeof DIAGRAM_FINDING_CODES)[number], message: string): WorkspaceDiagnostic {
+  return {
+    checkId: check.id,
+    severity: check.severity,
+    code,
+    message: `${code}: ${message}`,
+    entity: d.member ?? undefined,
+    pointer: `${d.pointer}/${field}`,
+  };
+}
+
+export const DIAGRAM_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_DIAGRAM_SOURCE_MISSING,
+    name: "diagram-source-missing",
+    description: "A diagram's source file, when it names one, exists in the tree read.",
+    severity: "error",
+    configurable: true,
+    check(ctx: WorkspaceCheckContext) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const d of declaredDiagrams(ctx.declaration)) {
+        if (d.source === null || ctx.tree.stat(d.source) === "file") continue;
+        out.push(diagramFinding(this, d, "source", "diagram-source-missing", `${where(d)} diagram ${d.name} names the source ${d.source}, which does not exist${ctx.tree.label}`));
+      }
+      return out;
+    },
+  },
+  {
+    id: WSP_DIAGRAM_RENDER_MISSING,
+    name: "diagram-render-missing",
+    description: "A diagram's render exists in the tree read.",
+    severity: "error",
+    configurable: true,
+    check(ctx: WorkspaceCheckContext) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const d of declaredDiagrams(ctx.declaration)) {
+        if (ctx.tree.stat(d.render) === "file") continue;
+        out.push(diagramFinding(this, d, "render", "diagram-render-missing", `${where(d)} diagram ${d.name} names the render ${d.render}, which does not exist${ctx.tree.label}`));
+      }
+      return out;
+    },
+  },
+  {
+    id: WSP_DIAGRAM_RENDER_DRIFT,
+    name: "diagram-render-drift",
+    description: "A diagram that records a sourceHash is unchanged since its render was made: the source's bytes still hash to it. Runs no renderer.",
+    severity: "error",
+    configurable: true,
+    check(ctx: WorkspaceCheckContext) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const d of declaredDiagrams(ctx.declaration)) {
+        if (d.sourceHash === null || d.source === null) continue;
+        if (ctx.tree.stat(d.source) !== "file") continue; // diagram-source-missing already reports it
+        const bytes = ctx.tree.bytes ? ctx.tree.bytes(d.source) : Buffer.from(ctx.tree.read(d.source), "utf-8");
+        const actual = sha256Hex(bytes);
+        if (actual === d.sourceHash) continue;
+        out.push(
+          diagramFinding(
+            this,
+            d,
+            "sourceHash",
+            "diagram-render-drift",
+            `${where(d)} diagram ${d.name}'s source ${d.source} changed since ${d.render} was rendered from it: recorded sourceHash ${d.sourceHash.slice(0, 12)} does not match the source's current hash ${actual.slice(0, 12)}${ctx.tree.label}; rerun the renderer and commit the result, or update sourceHash`,
+          ),
+        );
+      }
+      return out;
+    },
+  },
+];