@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/member-file-schema.test.ts

@@ -0,0 +1,124 @@
+/**
+ * A member kind names a JSON Schema its member's file must pass (#3672): the
+ * kinds file's memberFile block, the schema read as data from the package,
+ * and WSP012 from `chant workspace check`.
+ */
+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 { checkMemberFile, parseKindData, readPackageKinds } from "./kinds";
+
+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-3672-")));
+  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 controlSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  required: ["estates"],
+  properties: { estates: { type: "array", items: { type: "string" } } },
+  additionalProperties: false,
+};
+
+const controlKind = (memberFile: unknown = { path: "terragucci.yml", schema: "schemas/control.schema.json" }) => ({
+  name: "control",
+  description: "a terragucci control repo, with a terragucci.yml",
+  precedence: 300,
+  probe: { anyFile: ["terragucci.yml"] },
+  memberFile,
+});
+
+/** A kinds-only package at kinds/control, and a workspace that pins it. */
+function workspace(files: Record<string, string>, opts: { schema?: string | null; kind?: unknown } = {}): string {
+  const schemaText = opts.schema === undefined ? JSON.stringify(controlSchema) : opts.schema;
+  return repo({
+    "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, pins: [{ path: "kinds/control" }], members: [{ name: "ctl", dir: "ctl", kind: "control" }] }),
+    "kinds/control/package.json": JSON.stringify({ name: "control-kinds", exports: { "./workspace-kinds": "./workspace-kinds.json" } }),
+    "kinds/control/workspace-kinds.json": JSON.stringify({ schema: 1, kinds: [opts.kind ?? controlKind()] }),
+    ...(schemaText === null ? {} : { "kinds/control/schemas/control.schema.json": schemaText }),
+    ...files,
+  });
+}
+
+const wsp012 = async (root: string) =>
+  (await runDeclarationChecks(root)).diagnostics.filter((d) => d.ruleId === "WSP012" || d.ruleId === "WSP002").map((d) => `${d.ruleId}: ${d.message}`);
+
+describe("the kinds file's memberFile block", () => {
+  test("is kind data: a path in the member and a .json schema in the package", () => {
+    const ok = parseKindData(JSON.stringify({ schema: 1, kinds: [controlKind()] }), "p");
+    expect(ok.problems).toEqual([]);
+    expect(ok.kinds[0].memberFile).toEqual({ path: "terragucci.yml", schema: "schemas/control.schema.json" });
+    for (const bad of [{ path: "../x.yml", schema: "s.json" }, { path: "x.yml", schema: "s.yaml" }, { path: "x.yml", schema: "../s.json" }, { path: "x.yml" }]) {
+      expect(parseKindData(JSON.stringify({ schema: 1, kinds: [controlKind(bad)] }), "p").problems).not.toEqual([]);
+    }
+  });
+
+  test("reading the package compiles the schema as data, and reports one that is missing or not a schema", () => {
+    const good = workspace({});
+    const read = readPackageKinds(join(good, "kinds/control"));
+    expect(read.problems).toEqual([]);
+    expect(typeof read.kinds[0].memberFile?.validate).toBe("function");
+    expect(readPackageKinds(join(workspace({}, { schema: null }), "kinds/control")).problems[0]).toMatch(/does not exist/);
+    expect(readPackageKinds(join(workspace({}, { schema: "{ nope" }), "kinds/control")).problems[0]).toMatch(/is not JSON/);
+    expect(readPackageKinds(join(workspace({}, { schema: JSON.stringify({ type: 12 }) }), "kinds/control")).problems[0]).toMatch(/does not compile/);
+  });
+});
+
+describe("checkMemberFile", () => {
+  const mf = () => readPackageKinds(join(workspace({}), "kinds/control")).kinds[0].memberFile!;
+  test("parses YAML by extension and JSON otherwise, and names each failing place", () => {
+    expect(checkMemberFile(mf(), "terragucci.yml", "estates: [a, b]\n")).toEqual([]);
+    expect(checkMemberFile(mf(), "t.json", '{"estates":["a"]}')).toEqual([]);
+    expect(checkMemberFile(mf(), "terragucci.yml", "estates: [1]\nextra: true\n").map((p) => p.message).sort()).toEqual(["/estates/0 must be string", "the file must NOT have additional properties (extra)"]);
+    expect(checkMemberFile(mf(), "t.json", "estates: []")[0].message).toMatch(/^is not JSON/);
+  });
+});
+
+describe("WSP012: a member's file passes its kind's schema", () => {
+  test("a member whose file passes has no finding", async () => {
+    expect(await wsp012(workspace({ "ctl/terragucci.yml": "estates: [prod]\n" }))).toEqual([]);
+  });
+
+  test("a file that fails the schema fails the check, once per reason", async () => {
+    const report = await runDeclarationChecks(workspace({ "ctl/terragucci.yml": "estates: prod\n" }));
+    expect(report.ok).toBe(false);
+    const found = report.diagnostics.filter((d) => d.ruleId === "WSP012");
+    expect(found.map((d) => d.message)).toEqual(["member ctl's terragucci.yml fails kind control's schema schemas/control.schema.json: /estates must be array"]);
+    expect(found[0].file).toMatch(/ctl\/terragucci\.yml$/);
+  });
+
+  test("a member without the file fails it", async () => {
+    // The probe also wants the file; the declared kind still names the schema, so WSP012 says what is missing.
+    expect(await wsp012(workspace({ "ctl/README.md": "" }))).toEqual(["WSP012: member ctl (ctl) has no terragucci.yml, which kind control requires"]);
+  });
+
+  test("a schema that doesn't load is WSP002, and its members can't pass WSP012", async () => {
+    const found = await wsp012(workspace({ "ctl/terragucci.yml": "estates: []\n" }, { schema: null }));
+    expect(found).toHaveLength(2);
+    expect(found[0]).toMatch(/^WSP002: .*kind control names member-file schema schemas\/control.schema.json, which does not exist/);
+    expect(found[1]).toMatch(/^WSP012: .*did not load/);
+  });
+
+  test("the declaration can turn it down", async () => {
+    const root = workspace({ "ctl/terragucci.yml": "nope: 1\n" });
+    const decl = JSON.parse(execFileSync("cat", [join(root, "chant.workspace.json")], { encoding: "utf-8" }));
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ ...decl, checks: { WSP012: "warning" } }));
+    const report = await runDeclarationChecks(root);
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.filter((d) => d.ruleId === "WSP012").every((d) => d.severity === "warning")).toBe(true);
+  });
+});

package/src/workspace/migrate-links.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The links `chant migrate` writes into a workspace declaration (#4399):
+ * which members are the producer and the consumer, that the edit touches only
+ * the consumer's `links`, that a second run adds nothing, and that every case
+ * with nothing to link says why.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseDeclaration } from "./declaration";
+import { planMigrateLinks } from "./migrate-links";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function repo(declaration: string, file = "chant.workspace.json"): string {
+  const root = mkdtempSync(join(tmpdir(), "chant-migrate-links-"));
+  scratch.push(root);
+  for (const [path, text] of Object.entries({ [file]: declaration, "db/schema.sql": "", "mirror/mirrors.ts": "", "other/x.ts": "" })) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const decl = (members: unknown[]) => `${JSON.stringify({ name: "shop", schema: 1, members }, null, 2)}\n`;
+const MEMBERS = [
+  { name: "db", dir: "db", kind: "chant" },
+  { name: "mirror", dir: "mirror", kind: "chant" },
+];
+const outputs = ["public.users.id", "public.users.email"];
+
+describe("planMigrateLinks", () => {
+  test("adds one link per output to the member holding the output file, and changes nothing else", () => {
+    const root = repo(decl(MEMBERS));
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    if (!r || !("plan" in r)) throw new Error(JSON.stringify(r));
+    expect(r.plan).toMatchObject({ producer: "db", consumer: "mirror", added: outputs });
+    const members = parseDeclaration(r.plan.text, "chant.workspace.json").members;
+    expect(members.find((m) => m.name === "mirror")!.links.map((l) => `${l.member} ${l.output}`)).toEqual(outputs.map((o) => `db ${o}`));
+    expect(members.find((m) => m.name === "db")!.links).toEqual([]);
+    expect(r.plan.text.startsWith('{\n  "name": "shop"')).toBe(true);
+  });
+
+  test("keeps the links already there and adds only the new ones; a second plan adds nothing", () => {
+    const root = repo(decl([MEMBERS[0], { ...MEMBERS[1], links: [{ member: "db", output: "public.users.id" }, { member: "other", output: "x" }] }, { name: "other", dir: "other", kind: "chant" }]));
+    const r = planMigrateLinks({ sourcePath: join(root, "db"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    if (!r || !("plan" in r)) throw new Error(JSON.stringify(r));
+    expect(r.plan.added).toEqual(["public.users.email"]);
+    const links = parseDeclaration(r.plan.text, "x.json").members.find((m) => m.name === "mirror")!.links;
+    expect(links.map((l) => `${l.member} ${l.output}`)).toEqual(["db public.users.id", "other x", "db public.users.email"]);
+    writeFileSync(join(root, "chant.workspace.json"), r.plan.text);
+    const again = planMigrateLinks({ sourcePath: join(root, "db"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    expect(again).toMatchObject({ plan: { added: [] } });
+  });
+
+  test("reads a jsonc declaration and keeps its comments", () => {
+    const text = `{\n  // the shop\n  "name": "shop", "schema": 1,\n  "members": [\n    { "name": "db", "dir": "db", "kind": "chant" },\n    { "name": "mirror", "dir": "mirror", "kind": "chant" } // the mirror\n  ]\n}\n`;
+    const root = repo(text, "chant.workspace.jsonc");
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    if (!r || !("plan" in r)) throw new Error(JSON.stringify(r));
+    expect(r.plan.text).toContain("// the shop");
+    expect(r.plan.text).toContain("// the mirror");
+    expect(r.plan.added).toEqual(outputs);
+  });
+
+  test("the deepest member holds a path: a nested member is not its parent's", () => {
+    const root = repo(decl([{ name: "all", dir: ".", kind: "chant" }, { name: "db", dir: "db", kind: "chant" }, { name: "mirror", dir: "mirror", kind: "chant" }]));
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    expect(r).toMatchObject({ plan: { producer: "db", consumer: "mirror" } });
+  });
+
+  test("no workspace above the source is no outcome at all", () => {
+    const root = mkdtempSync(join(tmpdir(), "chant-no-workspace-"));
+    scratch.push(root);
+    writeFileSync(join(root, "schema.sql"), "");
+    expect(planMigrateLinks({ sourcePath: join(root, "schema.sql"), outputPath: join(root, "out.ts"), outputs })).toBeUndefined();
+  });
+
+  test.each([
+    ["output to stdout", (root: string) => ({ sourcePath: join(root, "db/schema.sql"), outputPath: undefined }), "pass --output inside the ClickHouse member"],
+    ["a source in no member", (root: string) => ({ sourcePath: join(root, "elsewhere/schema.sql"), outputPath: join(root, "mirror/mirrors.ts") }), "is in no member"],
+    ["an output in no member", (root: string) => ({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "elsewhere/out.ts") }), "is in no member"],
+    ["a source and output in one member", (root: string) => ({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "db/out.ts") }), "does not link to itself"],
+  ])("%s is skipped with a reason", (_name, paths, reason) => {
+    const root = repo(decl(MEMBERS));
+    const r = planMigrateLinks({ ...paths(root), outputs });
+    expect(r && "skipped" in r ? r.skipped : r).toContain(reason);
+  });
+
+  test("a declaration that does not read is skipped with its error, never rewritten", () => {
+    const root = repo("{ not json");
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    expect(r && "skipped" in r ? r.skipped : r).toContain("does not read, so no link was written");
+  });
+});

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);
+  });
+});