@intentius/chant 0.124.48 → 0.124.50

package/src/workspace/kind-readers.test.ts

@@ -132,3 +132,39 @@ describe("workspace graph reads a package kind with a graph block (#2874)", () =
     expect(planMembers("graph", root, { kinds: registry }).groups[0].units[0].reader).toMatchObject({ lexicon: "fake" });
   });
 });
+
+describe("a graph reader module from a package that is not a lexicon (#4413)", () => {
+  /** A fake chant that prints the reader project's config, so the test sees what the member's chant is handed. */
+  const MODULE_CHANT = `#!/bin/sh
+[ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
+printf '{"version":1,"nodes":[{"id":"org","kind":"Org","lexicon":"gov","attrs":{"config":'
+cat chant.config.json
+printf ',"linked":%s}}],"edges":[],"groups":{}}\\n' "$([ -e node_modules ] && echo true || echo false)"
+`;
+
+  test("the reader project names the module and links no lexicon", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "forge", dir: "gov", kind: "gov" }], { pins: [{ package: "@acme/warden", version: "1.0.0" }] }),
+      "gov/governance.yml": "org: acme\n",
+      ".gitignore": "node_modules\n",
+      "node_modules/.bin/chant": { text: MODULE_CHANT, mode: 0o755 },
+      "node_modules/@acme/warden/package.json": JSON.stringify({ name: "@acme/warden", version: "1.0.0", exports: { "./workspace-kinds": "./workspace-kinds.json" } }),
+      "node_modules/@acme/warden/graph.mjs": "export default () => ({ nodes: [], edges: [] });\n",
+      "node_modules/@acme/warden/workspace-kinds.json": JSON.stringify({
+        schema: 1,
+        kinds: [{ name: "gov", description: "governance", precedence: 500, probe: { anyFile: ["governance.yml"] }, graph: { reader: "graph.mjs", config: { dir: "{dir}" } } }],
+      }),
+    });
+    const { doc, failed } = await workspaceGraph({ cwd: root });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(false);
+    expect(g.members.map((m) => [m.name, m.status])).toEqual([["forge", "composed"]]);
+    const attrs = g.nodes[0].attrs as { config: Record<string, unknown>; linked: boolean };
+    expect(attrs.config).toEqual({
+      lexicons: [],
+      graph: { lint: "report", reader: { module: join(root, "node_modules/@acme/warden/graph.mjs"), config: { dir: `${root}/gov` } } },
+    });
+    expect(attrs.linked).toBe(false);
+  });
+});

package/src/workspace/kind-readers.ts

@@ -20,6 +20,12 @@
  *   package, found from the workspace root as the kind's pin was. The lexicon
  *   chant loads is then the one the declaration pins.
  *
+ * A kind whose `graph` names a `reader` module instead (#4413) gets a
+ * project with `lexicons: []` and `graph.reader` set to the module, which the
+ * supplying package ships, so any package can supply one. The member's own
+ * `chant graph` loads it there, under the member's toolchain, and prints the
+ * IR it returns. There is no lexicon to link.
+ *
  * Nothing is written under the workspace, and the projects are removed when
  * the read ends. A lexicon that can't be found where its pin says fails the
  * member with `command-failed` and says what to install; the other members
@@ -57,6 +63,7 @@ function real(path: string): string {
 /** Why a unit's lexicon can't be loaded from `root`, or the `node_modules` to link. */
 function lexiconModules(unit: RunUnit, root: string): { modules: string } | { message: string } {
   const reader = unit.reader!;
+  if (!reader.lexicon) return { message: `kind ${unit.kind} names no lexicon` };
   const name = lexiconPackageName(reader.lexicon);
   const installed = findInstalledPackage(name, root);
   if (!installed) {
@@ -89,6 +96,16 @@ export function prepareKindReaders(plan: MemberPlan, root: string): PreparedRead
     for (const group of plan.groups) {
       group.units = group.units.filter((unit) => {
         if (!unit.reader) return true;
+        if (unit.reader.readerFile) {
+          // A graph reader module (#4413): no lexicon and no node_modules link. The module sits in the pinned package and resolves its own imports from there.
+          scratch ??= mkdtempSync(join(tmpdir(), "chant-ws-reader-"));
+          const project = join(scratch, unit.id);
+          mkdirSync(project, { recursive: true });
+          const config = substituteGraphConfig(unit.reader.config, { member: unit.member, dir: unit.abs, workspace: root });
+          writeFileSync(join(project, "chant.config.json"), `${JSON.stringify({ lexicons: [], graph: { lint: "report", reader: { module: unit.reader.readerFile, config } } }, null, 2)}\n`);
+          unit.abs = project;
+          return true;
+        }
         const found = lexiconModules(unit, root);
         if ("message" in found) {
           failed.push({ name: unit.member, dir: unit.dir, kind: unit.kind, reason: { code: "command-failed", message: found.message } });
@@ -101,7 +118,7 @@ export function prepareKindReaders(plan: MemberPlan, root: string): PreparedRead
         // `graph.lint: "report"` (behold#919): chant did not author a reader
         // member's source, so a lint error there is a finding about it, carried
         // on the member's `meta.lint`, not a reason to leave it out of the graph.
-        writeFileSync(join(project, "chant.config.json"), `${JSON.stringify({ lexicons: [unit.reader.lexicon], [unit.reader.lexicon]: config, graph: { lint: "report" } }, null, 2)}\n`);
+        writeFileSync(join(project, "chant.config.json"), `${JSON.stringify({ lexicons: [unit.reader.lexicon!], [unit.reader.lexicon!]: config, graph: { lint: "report" } }, null, 2)}\n`);
         symlinkSync(found.modules, join(project, "node_modules"), "dir");
         unit.abs = project;
         return true;

package/src/workspace/kinds.test.ts

@@ -155,6 +155,29 @@ describe("a kind's graph block (#2874)", () => {
     expect(bad.registry.get("other-tf")).toBeDefined();
   });
 
+  test("a graph reader module is accepted from a package that is not a lexicon, and only inside the package (#4413)", () => {
+    const reader = { reader: "dist/graph.mjs", config: { dir: "{dir}" } };
+    const root = dir({
+      ...pkg("@acme/warden", "1.0.0", [{ ...tf, name: "gov", graph: reader }]),
+      "node_modules/@acme/warden/dist/graph.mjs": "export default () => ({ nodes: [], edges: [] });\n",
+      ...pkg("@acme/gone", "1.0.0", [{ ...tf, name: "gone", graph: reader }]),
+      ...pkg("@acme/up", "1.0.0", [{ ...tf, name: "up", graph: { reader: "../x.mjs" } }]),
+    });
+    const good = loadKindRegistry([{ package: "@acme/warden", version: "1.0.0", path: null }], root);
+    expect(good.problems).toEqual([]);
+    expect(good.registry.get("gov")?.graph).toEqual({ ...reader, readerFile: join(root, "node_modules/@acme/warden/dist/graph.mjs") });
+    const gone = loadKindRegistry([{ package: "@acme/gone", version: "1.0.0", path: null }], root);
+    expect(gone.problems.map((p) => p.message)).toEqual([expect.stringMatching(/graph reader dist\/graph.mjs, which does not exist/)]);
+    expect(gone.registry.get("gone")?.graph).toBeUndefined();
+    const up = loadKindRegistry([{ package: "@acme/up", version: "1.0.0", path: null }], root);
+    expect(up.problems.length).toBe(1);
+    expect(up.registry.get("up")?.graph).toBeUndefined();
+    // Not both, and an absolute path is refused.
+    expect(parseKindData(kindsFile([{ ...tf, graph: { reader: "a.mjs", lexicon: "tf", config: {} } }]), "p").problems.length).toBeGreaterThan(0);
+    expect(parseKindData(kindsFile([{ ...tf, graph: { reader: "/etc/x.mjs" } }]), "p").problems.length).toBeGreaterThan(0);
+    expect(parseKindData(kindsFile([{ ...tf, graph: { reader: "a.mjs" } }]), "p").problems).toEqual([]);
+  });
+
   test("the terraform lexicon's kinds read their members with it, named for the member at the workspace root", () => {
     const lexicon = join(import.meta.dirname, "..", "..", "..", "..", "lexicons", "terraform");
     const read = readPackageKinds(lexicon);

package/src/workspace/kinds.ts

@@ -17,7 +17,7 @@
  * fails ({@link resolveKind}).
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
@@ -63,6 +63,18 @@ export interface FileProbe {
    * directory of `.sql` files: its files carry `-- +goose Up`.
    */
   anyLine?: { in: string[]; starts: string[] };
+  /**
+   * A file directly in the directory whose name matches one of `in` parses
+   * as YAML or JSON (every document of a multi-document file is read), and
+   * one document satisfies one of the `match` entries. An entry maps JSON
+   * Pointers to the values allowed there, and a document satisfies it when
+   * every pointer holds a value that matches one of its patterns. A `*` in
+   * a pattern matches any run of characters, so `["*"]` means "has a
+   * value". This is how an Argo Application, a Flux Kustomization and a
+   * CloudFormation template are found by what they say, not by their file
+   * names (#3179). A file that doesn't parse is no evidence either way.
+   */
+  anyDocument?: { in: string[]; match: Record<string, string[]>[] };
 }
 
 /** A string, integer or boolean field a kind declares for its members (#3151). */
@@ -113,7 +125,15 @@ export type KindOutputs =
  * chant writes itself. See {@link substituteGraphConfig} for the placeholders.
  */
 export interface KindGraph {
-  lexicon: string;
+  /** The lexicon that reads the member; unset when `reader` is. */
+  lexicon?: string;
+  /**
+   * A graph reader module (#4413), as the kinds file names it: a path inside
+   * the supplying package, which may be any package. Unset when `lexicon` is.
+   */
+  reader?: string;
+  /** The reader module, absolute; set once the package directory is known. */
+  readerFile?: string;
   config: Record<string, unknown>;
 }
 
@@ -280,7 +300,7 @@ export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): b
   if ("directory" in kind.probe) return true;
   if ("chantProject" in kind.probe) return holdsChantProject(tree, dir);
   if ("repo" in kind.probe) return true;
-  const { anyFile, anyBlock, anyJsonKey, anyLine } = kind.probe;
+  const { anyFile, anyBlock, anyJsonKey, anyLine, anyDocument } = kind.probe;
   if (anyFile && filesMatching(tree, dir, anyFile).length > 0) return true;
   if (anyJsonKey) {
     for (const file of filesMatching(tree, dir, anyJsonKey.in)) {
@@ -302,6 +322,15 @@ export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): b
       }
     }
   }
+  if (anyDocument) {
+    for (const file of filesMatching(tree, dir, anyDocument.in)) {
+      try {
+        if (documentsOf(tree.read(file)).some((doc) => anyDocument.match.some((m) => documentMatches(doc, m)))) return true;
+      } catch {
+        // An unreadable file is no evidence either way.
+      }
+    }
+  }
   if (anyBlock) {
     const opener = new RegExp(`^\\s*(?:${anyBlock.blocks.map(escapeRegExp).join("|")})\\s*\\{`, "m");
     for (const file of filesMatching(tree, dir, anyBlock.in)) {
@@ -340,6 +369,37 @@ function filesMatching(tree: WorkspaceTree, dir: string, names: readonly string[
   return out.sort();
 }
 
+/**
+ * The documents in `text`, read as YAML (which holds JSON). A CloudFormation
+ * short-form tag such as `!Ref` or `!Sub` is not YAML js-yaml knows, so a
+ * file that fails to parse is read again with those tags dropped. Text that
+ * still doesn't parse has no documents.
+ */
+function documentsOf(text: string): unknown[] {
+  try {
+    return yaml.loadAll(text);
+  } catch {
+    try {
+      return yaml.loadAll(text.replace(/(^|[\s:\-[,{])!(?:[A-Za-z][\w]*:?)+/gm, "$1"));
+    } catch {
+      return [];
+    }
+  }
+}
+
+/** Whether every pointer in `match` holds a value matching one of its patterns. */
+function documentMatches(doc: unknown, match: Record<string, string[]>): boolean {
+  const pointers = Object.entries(match);
+  return (
+    pointers.length > 0 &&
+    pointers.every(([pointer, patterns]) => {
+      const value = atPointer(doc, pointer);
+      if (value === undefined) return false;
+      return patterns.some((pattern) => new RegExp(`^${pattern.split("*").map(escapeRegExp).join(".*")}$`).test(String(value)));
+    })
+  );
+}
+
 /** The value at JSON Pointer `pointer` in `json`, or undefined when there is none. */
 function atPointer(json: unknown, pointer: string): unknown {
   let at: unknown = json;
@@ -476,12 +536,15 @@ export function parseKindData(text: string, source: string): KindData {
         ...(k.probe.anyBlock ? { anyBlock: { in: [...k.probe.anyBlock.in], blocks: [...k.probe.anyBlock.blocks] } } : {}),
         ...(k.probe.anyJsonKey ? { anyJsonKey: { in: [...k.probe.anyJsonKey.in], pointers: [...k.probe.anyJsonKey.pointers] } } : {}),
         ...(k.probe.anyLine ? { anyLine: { in: [...k.probe.anyLine.in], starts: [...k.probe.anyLine.starts] } } : {}),
+        ...(k.probe.anyDocument ? { anyDocument: { in: [...k.probe.anyDocument.in], match: k.probe.anyDocument.match.map((m) => structuredClone(m)) } } : {}),
       },
       precedence: k.precedence,
       shape: "member",
       outputs: { from: "declared", names: [...(k.outputs ?? [])] },
       source,
-      ...(k.graph ? { graph: { lexicon: k.graph.lexicon, config: structuredClone(k.graph.config) } } : {}),
+      ...(k.graph
+        ? { graph: { ...(k.graph.lexicon ? { lexicon: k.graph.lexicon } : {}), ...(k.graph.reader ? { reader: k.graph.reader } : {}), config: structuredClone(k.graph.config ?? {}) } }
+        : {}),
       ...(k.fields ? { fields: structuredClone(k.fields) } : {}),
       ...(k.reader && (KIND_LINK_READERS as readonly string[]).includes(k.reader) ? { reader: k.reader as KindLinkReaderName } : {}),
       ...(k.memberFile ? { memberFile: { path: k.memberFile.path, schema: k.memberFile.schema } } : {}),
@@ -541,7 +604,20 @@ export function readPackageKinds(packageDir: string, source?: string): PackageKi
       const problem = loadMemberFileSchema(k.memberFile, packageDir);
       if (problem) data.problems.push(`${name}: kind ${k.name} ${problem}; members of the kind fail WSP012 until it is fixed`);
     }
-    if (k.graph && packageName !== lexiconPackageName(k.graph.lexicon)) {
+    if (k.graph?.reader) {
+      // A reader module is any package's own file (#4413): it must sit inside the package and exist. Nothing is imported here.
+      const file = resolve(packageDir, ...k.graph.reader.split("/"));
+      const inside = relative(packageDir, file);
+      if (inside.startsWith("..") || isAbsolute(inside)) {
+        data.problems.push(`${name}: kind ${k.name} names graph reader ${k.graph.reader}, which is outside the package; the kind is kept, and workspace graph lists its members with kind-not-run`);
+        delete k.graph;
+      } else if (!existsSync(file)) {
+        data.problems.push(`${name}: kind ${k.name} names graph reader ${k.graph.reader}, which does not exist in the package; the kind is kept, and workspace graph lists its members with kind-not-run`);
+        delete k.graph;
+      } else {
+        k.graph.readerFile = file;
+      }
+    } else if (k.graph?.lexicon && packageName !== lexiconPackageName(k.graph.lexicon)) {
       data.problems.push(
         `${name}: kind ${k.name} reads its members with lexicon ${k.graph.lexicon}, which is ${lexiconPackageName(k.graph.lexicon)}, ` +
           `and this package is ${packageName ?? "unnamed"}; the kind is kept, and workspace graph lists its members with kind-not-run`,

package/src/workspace/lineage-upgrade.test.ts

@@ -497,6 +497,26 @@ describe("chant workspace upgrade", () => {
     expect(port.pending[0].approval).toEqual({ mode: "log-only", quorum: { count: 2, roles: ["maintainer"] } });
   });
 
+  test("a gate's quorum at HEAD in identity.gates is the one asked for, and the patch can't lower it (#4404)", async () => {
+    // The Op's own quorum is 2 at HEAD and 1 in the upgrade; the declaration at HEAD asks 3 of the gate.
+    const op = (overview: string, count: number): string =>
+      `export default { props: { name: "release", overview: ${JSON.stringify(overview)}, phases: [{ name: "Ship", steps: [{ kind: "gate", gate: "ship", approval: { quorum: { count: ${count} } } }] }] } };\n`;
+    release("v1.1.0", {
+      "chant.workspace.json": JSON.stringify({ name: "proj", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }], identity: { gates: { ship: { quorum: { count: 3 } } } } }, null, 2) + "\n",
+      "delivery/chant.config.ts": "export default {};\n",
+      "delivery/ops/release.op.ts": op("v1", 2),
+    });
+    proj = join(root, "members-4404");
+    expect((await initFromCommand({ from: `${tpl}@v1.1.0`, path: proj })).error).toBeUndefined();
+    git(proj, ["init", "-q", "-b", "main"]);
+    commitProject("init from v1.1");
+    release("v2.0.0", { "delivery/ops/release.op.ts": op("v2", 1) });
+    const port = ledger();
+    const result = await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-09-23T10:00:00.000Z" });
+    expect(result.outcome).toBe("gated");
+    expect(result.staged!.governance).toMatchObject({ approval: { mode: "log-only", quorum: { count: 3 } } });
+  });
+
   test("refuses a scope with uncommitted changes, and a scope that does not exist", async () => {
     put(proj, "README.md", "dirty\n");
     await expect(stageUpgrade({ root: proj, to: "v1.0.0" })).rejects.toThrow(/uncommitted changes/);

package/src/workspace/lineage-upgrade.ts

@@ -573,16 +573,25 @@ export function isGovernancePath(path: string): boolean {
  * one. The Op files are read from the project's tree, which the upgrade
  * requires to match HEAD for every path the patch touches.
  *
+ * Both come from HEAD, never from the patch: the Op files are read from the
+ * clean project tree, and the declaration through `identityGatesAt(repo,
+ * head)` (`git show`). A change the upgrade itself makes to an Op or to
+ * `chant.workspace.json` cannot lower the approvals it asks for (#4404). A
+ * gate whose `identity.gates.<gate>.quorum` at HEAD sets one is asked for that
+ * quorum, as a run of the gate is (#4324), not the Op's own.
+ *
  * Discovery runs from each changed Op file's own directory, so it finds the
  * file under the project that owns it. Run from a workspace root, it would
  * skip every member's Op files (#2892).
  */
-async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateApproval> {
+async function rulesAtHead(repo: string, paths: string[], head: string): Promise<ResolvedGateApproval> {
   const opFiles = new Set(paths.filter((p) => GOVERNANCE[0].test(p)));
   let count = 1;
   let roles: string[] | undefined;
   if (opFiles.size > 0) {
     const { discoverOps } = await import("../op/discover");
+    const { identityGatesAt } = await import("../gate-decision");
+    const atBase = new Map(identityGatesAt(repo, head).map((g) => [g.gate, g.quorum]));
     const dirs = new Set([...opFiles].map((p) => dirname(join(repo, p))));
     for (const dir of dirs) {
       if (!existsSync(dir)) continue;
@@ -592,7 +601,7 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
         if (!opFiles.has(rel)) continue;
         // #4290: a quorum may be a list of rules; the strictest count is asked for.
         for (const approval of gateApprovals(config)) {
-          for (const rule of quorumRules(approval.quorum)) {
+          for (const rule of quorumRules(atBase.get(approval.gate) ?? approval.quorum)) {
             if (rule.count > count) {
               count = rule.count;
               roles = rule.roles;
@@ -605,12 +614,12 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
   return { mode: "log-only", quorum: { count, ...(roles && roles.length > 0 ? { roles } : {}) } };
 }
 
-type StepLike = { kind: string; approval?: { quorum?: GateQuorumSpec }; steps?: StepLike[] };
+type StepLike = { kind: string; gate?: string; signalName?: string; approval?: { quorum?: GateQuorumSpec }; steps?: StepLike[] };
 
-function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ quorum?: GateQuorumSpec }> {
-  const out: Array<{ quorum?: GateQuorumSpec }> = [];
+function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ gate: string; quorum?: GateQuorumSpec }> {
+  const out: Array<{ gate: string; quorum?: GateQuorumSpec }> = [];
   const visit = (step: StepLike): void => {
-    if (step.kind === "gate") out.push(step.approval ?? {});
+    if (step.kind === "gate") out.push({ gate: step.gate ?? step.signalName ?? "", ...(step.approval?.quorum !== undefined ? { quorum: step.approval.quorum } : {}) });
     if (step.kind === "effect") (step.steps ?? []).forEach(visit);
   };
   for (const p of [...(config.phases ?? []), ...(config.onFailure ?? [])]) p.steps.forEach(visit);
@@ -865,7 +874,7 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
       if (touched.length > 0) {
         throw new UpgradeError(`the upgrade changes governance files that have uncommitted edits (${touched.map((l) => l.slice(3)).join(", ")}). Commit them first: their gates are read at HEAD.`);
       }
-      governance = { paths: governed, approval: await rulesAtHead(repo, governed), rules: head };
+      governance = { paths: governed, approval: await rulesAtHead(repo, governed, head), rules: head };
     }
 
     // 5. Checks.

package/src/workspace/new-migrations.test.ts

@@ -0,0 +1,98 @@
+/**
+ * The new migration files of a pull request (#4407): which files count as
+ * new, and who classifies them. The trees are in memory; the classes come
+ * from the lexicon (`lexicons/sql/src/migration-classify.test.ts`).
+ */
+
+import { describe, expect, test } from "vitest";
+import { LINK_READERS, type KindLinkRead } from "./kind-link-readers";
+import { classifyNewMigrations, newMigrationGroups } from "./new-migrations";
+import type { WorkspaceTree } from "./tree";
+
+function memoryTree(files: Record<string, string>): WorkspaceTree {
+  const dirs = new Set([""]);
+  for (const f of Object.keys(files)) {
+    const parts = f.split("/");
+    for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join("/"));
+  }
+  return {
+    label: "",
+    stat: (p) => (p in files ? "file" : dirs.has(p) ? "dir" : undefined),
+    list(p) {
+      if (!dirs.has(p)) return undefined;
+      const prefix = p === "" ? "" : `${p}/`;
+      const seen = new Map<string, "file" | "dir">();
+      for (const f of Object.keys(files)) {
+        if (!f.startsWith(prefix)) continue;
+        const rest = f.slice(prefix.length);
+        seen.set(rest.split("/")[0]!, rest.includes("/") ? "dir" : "file");
+      }
+      return [...seen].map(([name, type]) => ({ name, type }));
+    },
+    read(p) {
+      if (!(p in files)) throw new Error(`no such file ${p}`);
+      return files[p]!;
+    },
+  };
+}
+
+const GOOSE = (sql: string) => `-- +goose Up\n${sql}\n-- +goose Down\nSELECT 1;\n`;
+const baseFiles = { "db/00001_init.sql": GOOSE("CREATE TABLE t (id bigint);") };
+const headFiles = { ...baseFiles, "db/00002_idx.sql": GOOSE("CREATE INDEX i ON t (id);") };
+
+const readGoose = (tree: WorkspaceTree): Map<string, KindLinkRead> =>
+  new Map([["ledger", LINK_READERS["goose-dir"]({ member: { name: "ledger" } as never, dir: "db", fields: { dialect: "postgres" }, tree })]]);
+const members = [{ name: "ledger", dir: "db" }];
+
+describe("newMigrationGroups", () => {
+  test("keeps the files the base lacks, in apply order", () => {
+    const groups = newMigrationGroups(members, readGoose(memoryTree(headFiles)), memoryTree(baseFiles));
+    expect(groups).toHaveLength(1);
+    expect(groups[0]).toMatchObject({ member: "ledger", dir: "db", reader: "goose-dir", dialect: "postgres" });
+    expect(groups[0]!.migrations.map((m) => m.file)).toEqual(["db/00002_idx.sql"]);
+  });
+
+  test("a changed file that the base has is not new", () => {
+    const head = { ...headFiles, "db/00001_init.sql": GOOSE("CREATE TABLE t (id bigint, a int);") };
+    expect(newMigrationGroups(members, readGoose(memoryTree(head)), memoryTree(baseFiles)).flatMap((g) => g.migrations.map((m) => m.file))).toEqual(["db/00002_idx.sql"]);
+  });
+
+  test("nothing new, no group; no base tree means every migration is new; --member limits", () => {
+    expect(newMigrationGroups(members, readGoose(memoryTree(baseFiles)), memoryTree(baseFiles))).toEqual([]);
+    expect(newMigrationGroups(members, readGoose(memoryTree(headFiles)), undefined)[0]!.migrations).toHaveLength(2);
+    expect(newMigrationGroups(members, readGoose(memoryTree(headFiles)), memoryTree(baseFiles), "other")).toEqual([]);
+  });
+});
+
+describe("classifyNewMigrations", () => {
+  const groups = () => newMigrationGroups(members, readGoose(memoryTree(headFiles)), memoryTree(baseFiles));
+
+  test("asks the lexicon for the new files only, with the head tree and the member's directory", async () => {
+    const asked: unknown[] = [];
+    const out = await classifyNewMigrations(groups(), memoryTree(headFiles), [
+      {
+        name: "fake",
+        classifyMigrations(o) {
+          asked.push({ reader: o.reader, dialect: o.dialect, dir: o.dir, files: o.files });
+          return o.files.map((file) => ({ file, statements: [] }));
+        },
+      },
+    ]);
+    expect(asked).toEqual([{ reader: "goose-dir", dialect: "postgres", dir: "db", files: ["db/00002_idx.sql"] }]);
+    expect(out).toMatchObject([{ member: "ledger", reader: "goose-dir", version: "2", name: "idx", type: "versioned", dialect: "postgres", file: "db/00002_idx.sql" }]);
+  });
+
+  test("a file no lexicon answers for is listed with the reason, and a throwing lexicon does not stop the note", async () => {
+    const none = await classifyNewMigrations(groups(), memoryTree(headFiles), []);
+    expect(none[0]!.error).toBe("no installed lexicon classifies postgres migrations");
+    const threw = await classifyNewMigrations(groups(), memoryTree(headFiles), [
+      {
+        name: "fake",
+        classifyMigrations() {
+          throw new Error("boom");
+        },
+      },
+    ]);
+    expect(threw[0]!.error).toBe("the fake lexicon could not classify it: boom");
+  });
+});

package/src/workspace/new-migrations.ts

@@ -0,0 +1,109 @@
+/**
+ * The migration files a pull request adds to a migration-directory workspace
+ * member (#4407), for the plan note. Reads the member's migrations at the
+ * pull request's head with the kind's own reader (`./kind-link-readers.ts`),
+ * keeps the files the base commit lacks, and asks a lexicon to classify
+ * them (`LexiconPlugin.classifyMigrations`). It reads git objects and files
+ * only: nothing is applied, no server is contacted, and no tool runs.
+ */
+
+import type { LexiconPlugin } from "../lexicon";
+import type { MigrationFileClassification, PrMigrationFile } from "../pr-migrations";
+import { readDeclaration } from "./declaration";
+import { readKindLinks, type KindLinkRead, type KindReadMigration } from "./kind-link-readers";
+import { loadKindRegistry } from "./kinds";
+import type { WorkspaceTree } from "./tree";
+import { locateWorkspace } from "./which-chant";
+
+/** One member's new migrations. */
+export interface NewMigrationGroup {
+  member: string;
+  /** The member's directory, tree-relative; "" for the workspace root. */
+  dir: string;
+  reader: string;
+  dialect: string;
+  /** The new files, in the order the tool applies them. */
+  migrations: KindReadMigration[];
+}
+
+/**
+ * Per member, the migrations whose file is not in `base`. An `undo` file is
+ * not an up migration and is left out. With no `base` tree (the workspace did
+ * not exist there) every migration is new. `only` limits the answer to one
+ * member, for a member's own pipeline.
+ */
+export function newMigrationGroups(
+  members: readonly { name: string; dir: string }[],
+  read: ReadonlyMap<string, KindLinkRead>,
+  base: WorkspaceTree | undefined,
+  only?: string,
+): NewMigrationGroup[] {
+  const out: NewMigrationGroup[] = [];
+  for (const m of members) {
+    if (only !== undefined && m.name !== only) continue;
+    const r = read.get(m.name);
+    if (!r?.migrations) continue;
+    const added = r.migrations.filter((mig) => mig.type !== "undo" && base?.stat(mig.file) !== "file");
+    if (added.length === 0) continue;
+    out.push({ member: m.name, dir: m.dir === "." ? "" : m.dir, reader: r.reader, dialect: added[0]!.dialect, migrations: added });
+  }
+  return out;
+}
+
+/**
+ * Classify the new files with the first lexicon that answers each. A file no
+ * lexicon answers for comes back with an `error` that says which dialect, so
+ * the note shows it instead of leaving it out.
+ */
+export async function classifyNewMigrations(groups: readonly NewMigrationGroup[], head: WorkspaceTree, plugins: readonly Pick<LexiconPlugin, "name" | "classifyMigrations">[]): Promise<PrMigrationFile[]> {
+  const out: PrMigrationFile[] = [];
+  for (const g of groups) {
+    const files = g.migrations.map((m) => m.file);
+    const answers = new Map<string, MigrationFileClassification>();
+    for (const p of plugins) {
+      if (!p.classifyMigrations || answers.size === files.length) continue;
+      const left = files.filter((f) => !answers.has(f));
+      try {
+        for (const a of await p.classifyMigrations({ reader: g.reader, dialect: g.dialect, tree: head, dir: g.dir, files: left })) answers.set(a.file, a);
+      } catch (err) {
+        for (const f of left) answers.set(f, { file: f, statements: [], error: `the ${p.name} lexicon could not classify it: ${err instanceof Error ? err.message : String(err)}` });
+      }
+    }
+    for (const m of g.migrations) {
+      const a = answers.get(m.file) ?? { file: m.file, statements: [], error: `no installed lexicon classifies ${g.dialect} migrations` };
+      out.push({ member: g.member, reader: g.reader, version: m.version, name: m.name, type: m.type, dialect: m.dialect, ...a });
+    }
+  }
+  return out;
+}
+
+/**
+ * The new migration files of the workspace holding `cwd`, between `base` and
+ * `head`. Empty outside a workspace or when the declaration cannot be read.
+ */
+export async function newMigrationFilesBetween(
+  cwd: string,
+  base: string,
+  head: string,
+  options: { member?: string; plugins: () => Promise<readonly Pick<LexiconPlugin, "name" | "classifyMigrations">[]> },
+): Promise<PrMigrationFile[]> {
+  let located;
+  let declaration;
+  try {
+    located = locateWorkspace(cwd, head);
+    declaration = readDeclaration(located.tree, "", { rootChant: true });
+  } catch {
+    return [];
+  }
+  const { registry } = loadKindRegistry(declaration.pins, located.rootOnDisk);
+  const read = readKindLinks(declaration, located.tree, registry);
+  let baseTree: WorkspaceTree | undefined;
+  try {
+    baseTree = locateWorkspace(cwd, base).tree;
+  } catch {
+    baseTree = undefined;
+  }
+  const groups = newMigrationGroups(declaration.members, read, baseTree, options.member);
+  if (groups.length === 0) return [];
+  return classifyNewMigrations(groups, located.tree, await options.plugins());
+}

package/src/workspace/pr-report.schema.json

@@ -92,6 +92,39 @@
         }
       }
     },
+    "migrations": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4407, written by chant 0.124.49 and newer. Plan stage: the migration files the pull request adds in a migration-directory workspace member (goose, golang-migrate, clickhouse-migrations, Flyway), each statement with the class the lexicon's classifier gives it, read offline. Absent when the pull request adds none.",
+      "items": {
+        "type": "object",
+        "required": ["member", "reader", "file", "version", "name", "type", "dialect", "statements"],
+        "properties": {
+          "member": { "type": "string" },
+          "reader": { "type": "string" },
+          "file": { "type": "string", "description": "Relative to the workspace root." },
+          "version": { "type": "string" },
+          "name": { "type": "string" },
+          "type": { "enum": ["versioned", "repeatable", "baseline", "undo"] },
+          "dialect": { "type": "string" },
+          "error": { "type": "string", "description": "Why the file could not be read; its statements are then empty." },
+          "statements": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["index", "sql", "outcome", "changes"],
+              "properties": {
+                "index": { "type": "integer", "minimum": 1 },
+                "sql": { "type": "string" },
+                "outcome": { "enum": ["classified", "undecided", "unclassified", "data"] },
+                "changes": { "type": "array", "items": { "$ref": "#/$defs/migrationChange" } },
+                "candidates": { "type": "array", "items": { "$ref": "#/$defs/migrationChange" }, "description": "With undecided: the rules that could apply." },
+                "note": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
     "plannedOutputs": {
       "type": "object",
       "description": "Added within contract version 1 by #3999, written by chant 0.124.32 and newer. Per dependency in the change that a member was planned against, the names of the outputs its plan knows, sorted. An output a member reads that is not listed is known only after apply, and the member lists it under unknownInputs. Absent when no member read one.",
@@ -258,6 +291,19 @@
     }
   },
   "$defs": {
+    "migrationChange": {
+      "type": "object",
+      "required": ["rule", "class", "label", "title"],
+      "properties": {
+        "rule": { "type": "string" },
+        "class": { "type": "string" },
+        "label": { "type": "string" },
+        "title": { "type": "string" },
+        "lock": { "type": "string" },
+        "destructive": { "type": "boolean" },
+        "note": { "type": "string" }
+      }
+    },
     "policyFinding": {
       "type": "object",
       "required": ["rule", "message"],