@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/migrate-links.ts

@@ -0,0 +1,108 @@
+/**
+ * The workspace links `chant migrate` writes (#4399).
+ *
+ * A migration reads one member (the Postgres tables) and writes into another
+ * (the ClickHouse mirrors). When both sit in a workspace, the migrated
+ * output reads the source member's outputs, and the declaration should say
+ * so: `chant workspace check` then fails when the source drops or renames an
+ * output until the mirror follows (WSP093, `./checks/links.ts`).
+ *
+ * {@link planMigrateLinks} finds the declaration above the source, the member
+ * that holds the source and the member that holds the output file, and adds
+ * a `links` entry on the second for each output the migration names. It
+ * changes only the text of that member's `links`, as the other declaration
+ * write commands do (`./json-edit.ts`). It returns a plan; the caller writes
+ * it. A migration with no workspace around it, or whose source and output
+ * are one member, has nothing to link and returns a reason when that is
+ * worth telling.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { DECLARATION_FILES, parseDeclaration, type Declaration, type Member } from "./declaration";
+import { appendElement, setProperty } from "./json-edit";
+
+export interface MigrateLinkPlan {
+  /** The declaration file, absolute. */
+  file: string;
+  /** The producer: the member that holds the source. */
+  producer: string;
+  /** The consumer: the member that holds the output file. */
+  consumer: string;
+  /** Outputs the consumer did not link to before. */
+  added: string[];
+  /** The declaration's new text; equal to the old when nothing was added. */
+  text: string;
+}
+
+export type MigrateLinkOutcome = { plan: MigrateLinkPlan } | { skipped: string } | undefined;
+
+/** The workspace declaration at or above `start`. */
+function findDeclaration(start: string): string | undefined {
+  let dir = resolve(start);
+  for (;;) {
+    for (const name of DECLARATION_FILES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** The deepest member whose directory holds `path`. */
+function memberHolding(declaration: Declaration, root: string, path: string): Member | undefined {
+  let best: { member: Member; depth: number } | undefined;
+  for (const m of declaration.members) {
+    const memberRoot = resolve(root, m.dir);
+    const rel = relative(memberRoot, path);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
+    // The longer root is the deeper member.
+    if (!best || memberRoot.length > best.depth) best = { member: m, depth: memberRoot.length };
+  }
+  return best?.member;
+}
+
+/**
+ * Plan the links from the member holding `sourcePath` to the outputs a
+ * migration read, on the member holding `outputPath`.
+ */
+export function planMigrateLinks(opts: { sourcePath: string; outputPath: string | undefined; outputs: readonly string[] }): MigrateLinkOutcome {
+  const source = resolve(opts.sourcePath);
+  const file = findDeclaration(source);
+  if (!file) return undefined;
+  if (opts.outputPath === undefined) return { skipped: "pass --output inside the ClickHouse member to link its columns to the Postgres member" };
+  const root = dirname(file);
+  const text = readFileSync(file, "utf8");
+  let declaration: Declaration;
+  try {
+    declaration = parseDeclaration(text, file);
+  } catch (err) {
+    return { skipped: `the workspace declaration ${file} does not read, so no link was written: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const producer = memberHolding(declaration, root, source);
+  const consumer = memberHolding(declaration, root, resolve(opts.outputPath));
+  if (!producer) return { skipped: `${opts.sourcePath} is in no member of ${file}, so no link was written` };
+  if (!consumer) return { skipped: `${opts.outputPath} is in no member of ${file}, so no link was written` };
+  if (producer.name === consumer.name) return { skipped: `the source and the output are both in member ${producer.name}; a member does not link to itself` };
+
+  const have = new Set(consumer.links.filter((l) => l.member === producer.name && l.kind === null).map((l) => l.output));
+  const added = [...new Set(opts.outputs)].filter((o) => !have.has(o));
+  if (added.length === 0) return { plan: { file, producer: producer.name, consumer: consumer.name, added, text } };
+
+  const jsonc = file.endsWith(".jsonc");
+  const links = added.map((output) => ({ member: producer.name, output }));
+  let next = text;
+  if (consumer.links.length === 0) {
+    next = setProperty(next, jsonc, consumer.pointer, "links", links);
+  } else {
+    for (const l of links) next = appendElement(next, jsonc, `${consumer.pointer}/links`, l);
+  }
+  // The edit is never written unless it reads back with the links it meant to add.
+  const back = parseDeclaration(next, file).members.find((m) => m.name === consumer.name);
+  if (!back || back.links.length !== consumer.links.length + added.length) {
+    return { skipped: `the edit to ${file} did not read back as the links it meant to add, so nothing was written` };
+  }
+  return { plan: { file, producer: producer.name, consumer: consumer.name, added, text: next } };
+}

package/src/workspace/migration-dirs.test.ts

@@ -0,0 +1,272 @@
+/**
+ * The migration-directory readers (#4400): goose, golang-migrate,
+ * clickhouse-migrations and Flyway. Each lists a fixture directory's
+ * migrations in the order the tool applies them. The trees are in memory:
+ * a reader parses files and never runs the tool.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { KindReaderInput } from "./kind-link-readers";
+import { LINK_READERS } from "./kind-link-readers";
+import { migrationDigest, REPLAY_FILE, replayFiles } from "./migration-dirs";
+import { withReaderOutputs } from "./links";
+import { classifyFlywayFile, compareVersions } from "./flyway-dir";
+import { parseToml, readFlywayConfig, substitute, FlywayPlaceholderError } from "./flyway-layout";
+import { builtinKindRegistry } from "./kinds";
+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);
+        const [head] = rest.split("/");
+        seen.set(head!, 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 run = (reader: keyof typeof LINK_READERS, files: Record<string, string>, fields: Record<string, string> = {}, dir = "") =>
+  LINK_READERS[reader]({ member: { name: "m" } as never, dir, fields: fields as KindReaderInput["fields"], tree: memoryTree(files) });
+/** The gaps about the files, without the one that asks for a first replay. */
+const gapsOf = (r: ReturnType<typeof run>) => r.gaps.filter((g) => !g.message.startsWith(`no ${REPLAY_FILE}`));
+const summary = (r: ReturnType<typeof run>) => (r.migrations ?? []).map((m) => `${String(m.position)} ${m.version} ${m.name} ${m.type}`);
+
+describe("the readers are registered", () => {
+  test("each kind of the sql lexicon names a reader chant has", () => {
+    const names = Object.keys(LINK_READERS);
+    expect(names).toEqual(expect.arrayContaining(["goose-dir", "golang-migrate-dir", "clickhouse-migrations-dir", "flyway-dir"]));
+    expect(builtinKindRegistry().get("goose")).toBeUndefined();
+  });
+});
+
+describe("goose", () => {
+  const up = (extra = "") => `-- +goose Up\n${extra}CREATE TABLE t (id int);\n`;
+  test("lists .sql files by version number, sequential and timestamp alike, with their dialect", () => {
+    const r = run("goose-dir", {
+      "00010_ten.sql": up(),
+      "00002_two.sql": `${up()}-- +goose Down\nDROP TABLE t;\n`,
+      "20240101120000_stamp.sql": up(),
+      "README.md": "x",
+    }, { dialect: "clickhouse" });
+    expect(summary(r)).toEqual(["1 2 two versioned", "2 10 ten versioned", "3 20240101120000 stamp versioned"]);
+    expect(r.migrations!.map((m) => m.down)).toEqual([true, false, false]);
+    expect(r.migrations!.every((m) => m.dialect === "clickhouse")).toBe(true);
+    expect(r.migrations![0]).toMatchObject({ file: "00002_two.sql", line: 1 });
+    expect(gapsOf(r)).toEqual([]);
+  });
+
+  test("annotations are case-insensitive and NO TRANSACTION is read", () => {
+    const r = run("goose-dir", { "1_a.sql": "-- +goose NO TRANSACTION\n-- +goose up\nselect 1;\n" });
+    expect(r.migrations![0]).toMatchObject({ transaction: false, line: 2 });
+  });
+
+  test("a file without Up, a Go migration, a bad name and a duplicate version are gaps", () => {
+    const r = run("goose-dir", { "1_a.sql": "select 1;\n", "2_b.go": "package m\n", "x_c.sql": up(), "3_d.sql": up(), "03_e.sql": up() });
+    expect(gapsOf(r).map((g) => `${g.file}: ${g.message.split(",")[0]}`)).toEqual([
+      "1_a.sql: 1_a.sql has no -- +goose Up annotation",
+      "2_b.go: 2_b.go is a Go migration; its code is not SQL",
+      "x_c.sql: x_c.sql has no version goose can read: the name starts with a positive integer",
+      "3_d.sql: version 3 is also 03_e.sql; goose refuses a duplicate version",
+    ]);
+    expect(summary(r)).toEqual(["1 3 e versioned", "2 3 d versioned"]);
+  });
+
+  test("migrationsDir names the directory under the member's", () => {
+    const r = run("goose-dir", { "db/migrations/1_a.sql": up() }, { migrationsDir: "migrations" }, "db");
+    expect(r.migrations![0]!.file).toBe("db/migrations/1_a.sql");
+  });
+});
+
+describe("golang-migrate", () => {
+  test("lists the up files by numeric version, and pairs each with its down file", () => {
+    const r = run("golang-migrate-dir", {
+      "10_ten.up.sql": "select 1;\n",
+      "2_two.up.sql": "select 1;\n",
+      "2_two.down.sql": "select 1;\n",
+      "1700000000_stamp.up.sql": "select 1;\n",
+      "notes.txt": "",
+    });
+    expect(summary(r)).toEqual(["1 2 two versioned", "2 10 ten versioned", "3 1700000000 stamp versioned"]);
+    expect(r.migrations!.map((m) => m.down)).toEqual(["2_two.down.sql", false, false]);
+    expect(gapsOf(r)).toEqual([]);
+  });
+
+  test("a down file with no up file, and a duplicate version, are gaps", () => {
+    const r = run("golang-migrate-dir", { "1_a.up.sql": "", "01_b.up.sql": "", "5_c.down.sql": "" });
+    expect(gapsOf(r).map((g) => g.message)).toEqual([
+      "1_a.up.sql: another up file already has version 1; golang-migrate refuses a duplicate",
+      "version 5 has a down file and no up file",
+    ]);
+  });
+});
+
+describe("clickhouse-migrations", () => {
+  test("lists <version>_<name>.sql in numeric order, with the Python tool's .down.sql rollbacks", () => {
+    const r = run("clickhouse-migrations-dir", { "10_b.sql": "", "002_a.sql": "", "002_a.down.sql": "", "README.md": "" });
+    expect(summary(r)).toEqual(["1 002 a versioned", "2 10 b versioned"]);
+    expect(r.migrations!.map((m) => m.down)).toEqual(["002_a.down.sql", false]);
+    expect(r.migrations!.every((m) => m.dialect === "clickhouse")).toBe(true);
+  });
+
+  test("a name with no version and a version written twice are gaps", () => {
+    const r = run("clickhouse-migrations-dir", { "init.sql": "", "1_a.sql": "", "001_b.sql": "" });
+    expect(gapsOf(r).map((g) => g.message.split(",")[0])).toEqual([
+      "init.sql has no version before its first _",
+      "version 1 is also 001_b.sql; leading zeros are not significant",
+    ]);
+  });
+});
+
+describe("flyway", () => {
+  test("orders versions as numbers, then repeatable migrations by description, and skips callbacks", () => {
+    const r = run("flyway-dir", {
+      "V10__ten.sql": "",
+      "V2__two.sql": "",
+      "V1_1__one_one.sql": "",
+      "R__views.sql": "",
+      "R__a_first.sql": "",
+      "beforeMigrate.sql": "",
+      "U2__undo_two.sql": "",
+      "schema.sql": "",
+    });
+    expect(summary(r)).toEqual(["1 1.1 one one versioned", "2 2 two versioned", "3 10 ten versioned", "4  a first repeatable", "5  views repeatable"]);
+    expect(r.migrations![1]!.down).toBe("U2__undo_two.sql");
+    expect(gapsOf(r)).toEqual([]);
+  });
+
+  test("locations come from flyway.toml, read recursively", () => {
+    const r = run("flyway-dir", {
+      "flyway.toml": '[flyway]\nlocations = ["filesystem:sql", "classpath:db/migration"]\n\n[environments.default]\nurl = "jdbc:clickhouse://localhost:8123/shop"\n',
+      "sql/V1__a.sql": "",
+      "sql/more/V2__b.sql": "",
+      "src/main/resources/db/migration/V3__c.sql": "",
+      "elsewhere/V9__x.sql": "",
+    });
+    expect(summary(r)).toEqual(["1 1 a versioned", "2 2 b versioned", "3 3 c versioned"]);
+    expect(r.migrations![0]!.dialect).toBe("clickhouse");
+  });
+
+  test("flyway.conf locations, a configuration above the member, and the dialect field", () => {
+    const r = run("flyway-dir", { "flyway.conf": "flyway.locations=filesystem:db/sql\nflyway.url=jdbc:postgresql://h/d\n", "db/sql/V1__a.sql": "" }, { dialect: "clickhouse" }, "db");
+    // The configuration sits above the member, so db/sql is relative to the root.
+    expect(r.migrations!.map((m) => `${m.file} ${m.dialect}`)).toEqual(["db/sql/V1__a.sql clickhouse"]);
+  });
+
+  test("without a configuration the member's directory is the location", () => {
+    expect(summary(run("flyway-dir", { "db/V1__a.sql": "" }, {}, "db"))).toEqual(["1 1 a versioned"]);
+  });
+
+  test("a code migration, a duplicate version and an outside location are gaps", () => {
+    const r = run("flyway-dir", {
+      "flyway.toml": '[flyway]\nlocations = ["filesystem:sql", "filesystem:../shared"]\n',
+      "sql/V1__a.sql": "",
+      "sql/V1_0__b.sql": "",
+      "sql/V2__Code.java": "",
+    });
+    expect(gapsOf(r).map((g) => g.message.split(",")[0])).toEqual([
+      "the location filesystem:../shared lies outside the workspace",
+      "V2__Code.java is a code migration; its code is not SQL",
+      "version 1 is also sql/V1_0__b.sql; Flyway refuses two migrations with one version",
+    ]);
+  });
+});
+
+describe("the shared Flyway layout", () => {
+  test("version comparison is numeric, part by part", () => {
+    expect(["10", "2", "1.10", "1.2", "1"].sort(compareVersions)).toEqual(["1", "1.2", "1.10", "2", "10"]);
+  });
+
+  test("file names follow the configured prefixes, separator and suffixes", () => {
+    const config = readFlywayConfig(memoryTree({ "flyway.conf": "flyway.sqlMigrationPrefix=M\nflyway.sqlMigrationSeparator=--\nflyway.sqlMigrationSuffixes=.ddl\n" }), "flyway.conf", "");
+    expect(classifyFlywayFile("M3--add.ddl", config)).toMatchObject({ type: "versioned", version: "3", description: "add" });
+    expect(classifyFlywayFile("V3__add.sql", config)).toBeUndefined();
+  });
+
+  test("toml tables, arrays and comments parse", () => {
+    expect(parseToml('# c\n[flyway]\nlocations = [\n "a", # x\n "b"\n]\nvalidateOnMigrate = true\n').flyway).toEqual({ locations: ["a", "b"], validateOnMigrate: true });
+  });
+
+  test("placeholders substitute, and a missing one names its file and line", () => {
+    const config = readFlywayConfig(memoryTree({ "flyway.conf": "flyway.placeholders.env=prod\nflyway.table=hist\n" }), "flyway.conf", "");
+    expect(substitute("a ${env}\nb ${flyway:table}", "V1__a.sql", config)).toBe("a prod\nb hist");
+    expect(() => substitute("ok\n${nope}", "V1__a.sql", config)).toThrow(FlywayPlaceholderError);
+    expect(() => substitute("ok\n${nope}", "V1__a.sql", config)).toThrow(/V1__a\.sql:2: no value for the placeholder \$\{nope\}/);
+  });
+});
+
+describe("the recorded replay", () => {
+  const goose = { "1_a.sql": "-- +goose Up\nCREATE TABLE a (id int);\n", "2_b.sql": "-- +goose Up\nALTER TABLE a ADD c int;\n" };
+  const snapshot = (files: Record<string, string>, outputs: string[]) => {
+    const tree = memoryTree(files);
+    const r = run("goose-dir", files);
+    const digest = migrationDigest((f) => tree.read(f), replayFiles(tree, r.migrations!));
+    return JSON.stringify({ schema: 1, dialect: "postgres", digest, outputs }, null, 2);
+  };
+
+  test("without a snapshot the outputs are a gap that says to replay", () => {
+    const r = run("goose-dir", goose);
+    expect(r.outputs).toBeUndefined();
+    expect(r.gaps).toEqual([expect.objectContaining({ outputs: true, message: expect.stringContaining("chant sql replay") })]);
+  });
+
+  test("a snapshot whose digest matches gives its names as outputs, with the line that states each", () => {
+    const r = run("goose-dir", { ...goose, [REPLAY_FILE]: snapshot(goose, ["public.a", "public.a.id", "public.a.c"]) });
+    expect(r.gaps).toEqual([]);
+    expect(r.outputs).toEqual([
+      { name: "public.a", file: REPLAY_FILE, line: 6 },
+      { name: "public.a.id", file: REPLAY_FILE, line: 7 },
+      { name: "public.a.c", file: REPLAY_FILE, line: 8 },
+    ]);
+  });
+
+  test("an edited migration makes the snapshot stale: no outputs and a gap", () => {
+    const stale = { ...goose, "2_b.sql": "-- +goose Up\nALTER TABLE a DROP COLUMN id;\n" };
+    const r = run("goose-dir", { ...stale, [REPLAY_FILE]: snapshot(goose, ["public.a"]) });
+    expect(r.outputs).toBeUndefined();
+    expect(r.gaps[0]).toMatchObject({ file: REPLAY_FILE, outputs: true, message: expect.stringContaining("changed since") });
+  });
+
+  test("a new migration makes it stale too, and a snapshot that is not one is a gap", () => {
+    expect(run("goose-dir", { ...goose, "3_c.sql": "-- +goose Up\nselect 1;\n", [REPLAY_FILE]: snapshot(goose, []) }).gaps[0]!.message).toContain("changed since");
+    expect(run("goose-dir", { ...goose, [REPLAY_FILE]: "{}" }).gaps[0]!.message).toContain("not a replay snapshot");
+    expect(run("goose-dir", { ...goose, [REPLAY_FILE]: "{" }).gaps[0]!.message).toContain("could not be read");
+  });
+
+  test("a Flyway snapshot also depends on the configuration, which holds the placeholders", () => {
+    const files = { "flyway.conf": "flyway.placeholders.t=a\n", "V1__a.sql": "create table ${t} (id int);\n" };
+    const tree = memoryTree(files);
+    const r = run("flyway-dir", files);
+    const digest = migrationDigest((f) => tree.read(f), replayFiles(tree, r.migrations!, ["flyway.conf"]));
+    const snap = JSON.stringify({ schema: 1, dialect: "postgres", digest, outputs: ["public.a"] });
+    expect(run("flyway-dir", { ...files, [REPLAY_FILE]: snap }).outputs!.map((o) => o.name)).toEqual(["public.a"]);
+    expect(run("flyway-dir", { ...files, "flyway.conf": "flyway.placeholders.t=b\n", [REPLAY_FILE]: snap }).outputs).toBeUndefined();
+  });
+
+  test("the outputs reach a consumer's link through withReaderOutputs: a column the migrations drop is missing", () => {
+    const base = new Map([["db", { outputs: [], complete: true, why: null, exposesNone: false }]]) as never;
+    const read = run("goose-dir", { ...goose, [REPLAY_FILE]: snapshot(goose, ["public.a", "public.a.id"]) });
+    const handles = withReaderOutputs(base, new Map([["db", read]]));
+    expect(handles.get("db")!.outputs.map((o) => o.name)).toEqual(["public.a", "public.a.id"]);
+    expect(handles.get("db")!.complete).toBe(true);
+    const unreplayed = withReaderOutputs(base, new Map([["db", run("goose-dir", goose)]]));
+    expect(unreplayed.get("db")!.complete).toBe(false);
+  });
+});

package/src/workspace/migration-dirs.ts

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