@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/declaration.ts

@@ -22,7 +22,7 @@ import schema from "./declaration.schema.json" with { type: "json" };
 import { routeConflicts } from "./ci-branches";
 import { cloudIdentityProblems, CLOUDS, type CloudIdentityDeclaration } from "../ci-identity";
 import { expandGlob } from "./glob";
-import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
+import { EXAMPLES_KIND, holdsChantProject, REPO_KIND } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import type { ReasonCode } from "./reason-codes";
 import type { SecurityGroup } from "./security";
@@ -30,6 +30,7 @@ import { joinPath, type WorkspaceTree } from "./tree";
 import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
 import { assertPrLoopHooks, type OpWaveHooks } from "../op/op-waves";
+import { quorumProblems, type GateQuorumSpec } from "../op/gate-quorum";
 import { assertGatePolicySettings, type GatePolicySettings } from "../gate-policy";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
@@ -159,6 +160,13 @@ export interface SignedGate {
   gate: string;
   /** The class the signer must be in, or null for any signer the signers file at base lists. */
   class: PrincipalClass | null;
+  /**
+   * The approval rules an Op gate of this name takes (#4324): one rule or a
+   * list, as an Op's `approval.quorum`. Read here, at base, a change can't
+   * lower the quorum its own run needs. Null when the entry sets none, and
+   * the Op's own `approval.quorum` then applies.
+   */
+  quorum: GateQuorumSpec | null;
   pointer: string;
 }
 
@@ -212,13 +220,24 @@ export interface CiPhase {
   pointer: string;
 }
 
+/** Every branch `ci.green` judges (#4325): `branches` when the declaration names several, else `branch`. */
+export function greenBranches(green: Pick<CiGreen, "branch" | "branches">): string[] {
+  return green.branches ?? [green.branch];
+}
+
 /** The default `ci.green.window`. */
 export const DEFAULT_CI_WINDOW = "24h";
 
 /** The declaration's `ci.green` block (#3573, ws-103), with its defaults. */
 export interface CiGreen {
-  /** The branch whose first-parent commits are tagged. */
+  /** The branch whose first-parent commits are tagged. With several (#4325), the first one declared. */
   branch: string;
+  /**
+   * Every branch whose first-parent commits are tagged (#4325), in declaration
+   * order, the first being `branch`. Present only when the declaration names
+   * more than one, so a one-branch declaration reads as it always did.
+   */
+  branches?: string[];
   /** How far back a tick looks, such as `24h`. */
   window: string;
   /** The phases, in file order. */
@@ -638,9 +657,16 @@ export const DEFAULT_STATE_ROOT = "${XDG_STATE_HOME}/chant/boxes";
 export interface Member {
   type: "member";
   name: string;
-  /** Relative to the workspace root; `"."` is the root member. */
+  /**
+   * Relative to the workspace root; `"."` is the root member. A member of kind
+   * `repo` has no directory here: its `dir` is {@link repoMemberDir}, which
+   * names no directory of this repository, and every reader that looks at
+   * member directories leaves it out by its kind (#3168).
+   */
   dir: string;
   kind: string;
+  /** For a member of kind `repo`, the other repository's workspace it names (#3168); null for every other kind. */
+  repo: RepoRef | null;
   roles: MemberRole[];
   /** Declared generated files, in file order. The implicit ones are not listed here (see `generated-files.ts`). */
   generated: GeneratedFile[];
@@ -660,6 +686,12 @@ export interface Member {
   because: string | null;
   /** Whether `chant workspace export` takes the member (#2552, D10). False when the entry does not say. */
   travel: boolean;
+  /**
+   * Whether a workspace gate's approval may stand in for this member's own
+   * gates (#2554, ws-039), when its digest covers the member's plan. Read
+   * from the declaration at base. Set only when the entry says true.
+   */
+  acceptWorkspaceGates?: true;
   /** The security groups this member adds to the declaration's top-level `security` (#4168 step 7), in file order; empty when it names none. */
   security: SecurityGroup[];
   /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
@@ -691,10 +723,26 @@ export interface Pin {
   integrity: string | null;
 }
 
+/** Another repository's workspace, by URL and pinned revision (#3168). */
+export interface RepoRef {
+  url: string;
+  /** A full commit id. */
+  rev: string;
+  /** The workspace root inside that repository, relative to its git root; `"."` when the entry doesn't say. */
+  workspace: string;
+}
+
+/** The `dir` a `repo` member reads as (#3168): a marker, never a directory of this repository. */
+export function repoMemberDir(name: string): string {
+  return `@repo/${name}`;
+}
+
 export interface Declaration {
   name: string;
   schema: number;
   minReader: string | null;
+  /** `org` for an org-level workspace, which holds only `repo` members; `repo` otherwise, the default (#3168). */
+  scope: "repo" | "org";
   /** Members and groups, in file order. */
   entries: Entry[];
   members: Member[];
@@ -817,9 +865,13 @@ function explain(e: AjvError, value: unknown): string {
     const missing = String(e.params.missingProperty);
     if (missing === "because" && e.instancePath.endsWith("/handWritten")) return `a hand-written generated file needs "because", saying why it is kept by hand`;
     if (missing === "because") return `a member of kind other needs "because", saying why it is there`;
+    if (missing === "repo") return `a member of kind repo needs "repo", the other repository's url and pinned rev`;
     return `missing required field ${JSON.stringify(missing)}`;
   }
   if (e.keyword === "const" && e.instancePath === "/schema") return `schema must be 1, the only declaration format this chant reads`;
+  // A repo member has repo and no dir; every other member has dir and no repo (#3168).
+  if (e.keyword === "false schema" && e.instancePath.endsWith("/dir")) return `a member of kind repo has no dir: it names another repository's workspace with repo`;
+  if (e.keyword === "false schema" && e.instancePath.endsWith("/repo")) return `only a member of kind repo has repo`;
   return e.message ?? "is invalid";
 }
 
@@ -942,14 +994,17 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       protocol: l.protocol ?? null,
       pointer: `${pointer}/links/${j}`,
     }));
-    const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
+    const repoRaw = e.repo as { url: string; rev: string; workspace?: string } | undefined;
+    const dir = e.kind === REPO_KIND ? repoMemberDir(e.name as string) : (e.dir as string);
+    const records = recordKindsOf(e.records, dir, e.name as string, `${pointer}/records`);
     const diagrams = diagramsOf(e.diagrams, e.name as string, `${pointer}/diagrams`);
     const box = boxOf(e.box, `${pointer}/box`);
     return {
       type: "member",
       name: e.name as string,
-      dir: e.dir as string,
+      dir,
       kind: e.kind as string,
+      repo: repoRaw ? { url: repoRaw.url, rev: repoRaw.rev, workspace: repoRaw.workspace ?? "." } : null,
       roles,
       generated,
       outputs: e.outputs === undefined ? null : [...(e.outputs as string[])],
@@ -961,6 +1016,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
       travel: e.travel === true,
+      ...(e.acceptWorkspaceGates === true ? { acceptWorkspaceGates: true as const } : {}),
       security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
       ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
       ciHooks: ciHooksOf((e.ci as { hooks?: unknown } | undefined)?.hooks, `${pointer}/ci/hooks`, at),
@@ -986,8 +1042,10 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   // Placement (#2524 D2): one root member at most, no two members in one
   // directory, and only the root member contains other members.
   const members = entries.filter((e): e is Member => e.type === "member");
+  // A repo member has no directory here (#3168), so it takes no part in placement.
+  const placed = members.filter((m) => m.kind !== REPO_KIND);
   const byDir = new Map<string, Member>();
-  for (const m of members) {
+  for (const m of placed) {
     const other = byDir.get(m.dir);
     if (other) {
       throw new WorkspaceReadError(
@@ -998,8 +1056,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     }
     byDir.set(m.dir, m);
   }
-  for (const m of members) {
-    const outer = members.find((o) => o !== m && o.dir !== "." && isInside(m.dir, o.dir));
+  for (const m of placed) {
+    const outer = placed.find((o) => o !== m && o.dir !== "." && isInside(m.dir, o.dir));
     if (outer) {
       throw new WorkspaceReadError(
         "placement-invalid",
@@ -1109,6 +1167,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     name: obj.name as string,
     schema: obj.schema as number,
     minReader: (obj.minReader as string | undefined) ?? null,
+    scope: obj.scope === "org" ? "org" : "repo",
     entries,
     members,
     groups: entries.filter((e): e is Group => e.type === "group"),
@@ -1121,7 +1180,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     changes: changesOf(obj.changes as Record<string, unknown> | undefined),
     writeScope,
     agents,
-    identity: identityOf(obj.identity),
+    identity: identityOf(obj.identity, at),
     ci,
     retention: retentionOf(obj.retention),
     metrics: metricsOf(obj.metrics),
@@ -1181,13 +1240,22 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
  * (#2548, ws-101): names are unique, every member a session names is a
  * declared member, and a principal is listed by one session at most.
  */
-/** The `identity` block, already validated by the schema (#3163). */
-function identityOf(raw: unknown): IdentityPolicy | null {
+/**
+ * The `identity` block, already validated by the schema (#3163), with the
+ * quorum rules the schema can't say (#4324): `notAuthor` is refused, since an
+ * Op gate has no pull request to read the author from.
+ */
+function identityOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): IdentityPolicy | null {
   if (raw === undefined) return null;
-  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string }> };
+  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string; quorum?: GateQuorumSpec }> };
   const gates: Record<string, SignedGate> = {};
   for (const [gate, entry] of Object.entries(block.gates ?? {})) {
-    gates[gate] = { gate, class: entry.class ?? null, pointer: `/identity/gates/${gate.replace(/~/g, "~0").replace(/\//g, "~1")}` };
+    const pointer = `/identity/gates/${gate.replace(/~/g, "~0").replace(/\//g, "~1")}`;
+    if (entry.quorum !== undefined) {
+      const [problem] = quorumProblems(entry.quorum, `identity.gates.${gate}.quorum`, { notAuthor: false });
+      if (problem) throw new WorkspaceReadError("declaration-invalid", problem.replace(/`/g, ""), at(`${pointer}/quorum`));
+    }
+    gates[gate] = { gate, class: entry.class ?? null, quorum: entry.quorum !== undefined ? structuredClone(entry.quorum) : null, pointer };
   }
   return { attribution: block.attribution ?? "any", gates };
 }
@@ -1266,7 +1334,7 @@ function cloudIdentityOf(raw: CloudIdentityDeclaration, at: (pointer: string, ke
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string | string[]; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
   const hooks = ciHooksOf(block.hooks, "/ci/hooks", at);
   const policy = ciPolicyOf(block.policy, at);
   const workflow = {
@@ -1327,7 +1395,8 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/preMerge/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
+  const judged = Array.isArray(g.branch) ? g.branch : [g.branch];
+  return { green: { branch: judged[0]!, ...(judged.length > 1 ? { branches: [...judged] } : {}), window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/environments.ts

@@ -23,6 +23,13 @@
  * would take it, or left out with `environments-component-undeclared` when
  * the config's environments don't cover it.
  *
+ * Each environment also names its `executor` (#4402): the forge and committed
+ * workflow that deploys it, as the member's config declares on the
+ * environment's entry (`{ name: "prod", executor: { forge: "github",
+ * workflow: "deploy-prod.yml" } }`), a literal entry before a pattern. When
+ * none is declared, `forge` and `workflow` are null and `reason` says why.
+ * chant never derives it from a generated workflow's name.
+ *
  * `chant run --env` refuses a name the config's `environments` doesn't cover
  * whenever it declares any (`unknownEnvError` in `../env.ts`), so a ledger
  * environment the config no longer covers is left out, with a reason. The
@@ -36,7 +43,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { environmentName, isEnvironmentPattern, matchesDeclaredEnvironment, type EnvironmentDeclaration } from "../config";
+import { environmentExecutor, environmentName, isEnvironmentPattern, matchesDeclaredEnvironment, type EnvironmentDeclaration, type EnvironmentExecutor } from "../config";
 import type { ComponentEnvironmentDeclaration } from "../components/component";
 import type { ReasonCode } from "./reason-codes";
 import { LOCAL_RUNTIME, type MemberRuntimes } from "./runtimes";
@@ -60,6 +67,23 @@ export const ENVIRONMENT_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type EnvironmentReasonCode = (typeof ENVIRONMENT_REASON_CODES)[number];
 
+/** Why an environment names no executor (#4402). Closed: part of the read contract. */
+export const EXECUTOR_REASON_CODES = [
+  /** The member's chant.config.ts declares no executor for the environment, so nothing says which forge workflow deploys it. */
+  "executor-none-declared",
+  /** The member's chant.config.ts could not be read, so whether a forge workflow deploys the environment is unknown. */
+  "executor-config-unreadable",
+] as const satisfies readonly ReasonCode[];
+export type ExecutorReasonCode = (typeof EXECUTOR_REASON_CODES)[number];
+
+/** The forge workflow that deploys an environment (#4402), or why none is named. */
+export interface ComponentExecutor {
+  forge: EnvironmentExecutor["forge"] | null;
+  workflow: string | null;
+  /** Null when `forge` and `workflow` are set. */
+  reason: { code: ExecutorReasonCode; message: string } | null;
+}
+
 export interface EnvironmentReason {
   code: EnvironmentReasonCode;
   message: string;
@@ -75,6 +99,8 @@ export interface ComponentEnvironment {
   source: "config" | "ledger" | "builtin" | "component";
   /** Where a release of the component goes in this environment, as the component declares it (#3153), or null when it declares nothing for it. */
   site: ComponentSite | null;
+  /** The forge and committed workflow that deploys this environment, from the member's config (#4402). */
+  executor: ComponentExecutor;
   /** The command that deploys the component there, on the site's runtime when the member hosts it and else the default runtime, run in the member's directory. */
   command: string;
 }
@@ -99,7 +125,7 @@ export type LedgerEnvironmentReader = (member: { name: string; dir: string }, cw
 /** What one member's config and ledger say about environments. */
 export interface MemberEnvironments {
   /** Each environment in list order, without the per-component site and command. */
-  environments: Omit<ComponentEnvironment, "command" | "site">[];
+  environments: Omit<ComponentEnvironment, "command" | "site" | "executor">[];
   reasons: EnvironmentReason[];
   /** The config's environments, for whether `chant run --env` takes a name: null when the config couldn't be read, `[]` when it declares none. */
   declared?: EnvironmentDeclaration[] | null;
@@ -177,6 +203,16 @@ export function memberEnvironments(runtimes: MemberRuntimes | undefined, ledger:
   return { environments: out, reasons, declared };
 }
 
+/** The executor the member's config declares for `env`, or why there is none. */
+export function executorFor(env: string, member: MemberEnvironments | undefined): ComponentExecutor {
+  if (member && member.declared === null) {
+    return { forge: null, workflow: null, reason: { code: "executor-config-unreadable", message: `chant.config.ts could not be read, so no executor is known for ${env}` } };
+  }
+  const found = environmentExecutor(member?.declared ?? undefined, env);
+  if (found) return { forge: found.forge, workflow: found.workflow, reason: null };
+  return { forge: null, workflow: null, reason: { code: "executor-none-declared", message: `chant.config.ts declares no executor for ${env}` } };
+}
+
 /**
  * The environments one component may deploy to, each with its command line.
  * `declared` is what the component's contract says (#3153): an environment
@@ -194,7 +230,7 @@ export function componentEnvironments(
   hosts: readonly string[] = [],
   reasons: EnvironmentReason[] = [],
 ): ComponentEnvironment[] {
-  const list: Omit<ComponentEnvironment, "command" | "site">[] = [...(member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" as const }])];
+  const list: Omit<ComponentEnvironment, "command" | "site" | "executor">[] = [...(member?.environments ?? [{ name: LOCAL_ENVIRONMENT, default: true, source: "builtin" as const }])];
   const config = member?.declared;
   const takes = (env: string): boolean => !config || config.length === 0 || matchesDeclaredEnvironment(config, env);
   const sites = new Map<string, ComponentSite>();
@@ -212,6 +248,6 @@ export function componentEnvironments(
   return list.map((e) => {
     const site = sites.get(e.name) ?? null;
     const on = site?.runtime && (site.runtime === LOCAL_RUNTIME || hosts.includes(site.runtime)) ? site.runtime : runtime;
-    return { ...e, site, command: `chant run --components ${component}${on === LOCAL_RUNTIME ? "" : ` --on ${on}`}${e.default ? "" : ` --env ${e.name}`}` };
+    return { ...e, site, executor: executorFor(e.name, member), command: `chant run --components ${component}${on === LOCAL_RUNTIME ? "" : ` --on ${on}`}${e.default ? "" : ` --env ${e.name}`}` };
   });
 }

package/src/workspace/flyway-dir.ts

@@ -0,0 +1,113 @@
+/**
+ * The `flyway-dir` reader (#4400): the migrations of a Flyway project, in the
+ * order `flyway migrate` applies them. It reads the layout with
+ * `./flyway-layout.ts`, the reading `yodel check` shares, and never runs
+ * Flyway or substitutes placeholders (a replay does that).
+ *
+ * File names follow Flyway's migration naming
+ * (https://documentation.red-gate.com/fd/migrations-271585107.html):
+ *
+ * - versioned `V<version>__<description>.sql`, the version digits joined by
+ *   `.` or `_`;
+ * - repeatable `R__<description>.sql`, run after every versioned migration,
+ *   in the order of their descriptions;
+ * - baseline `B<version>__<description>.sql`, listed with the versioned ones;
+ * - undo `U<version>__<description>.sql`, which is the `down` file of the
+ *   versioned migration with that version and is not listed on its own.
+ *
+ * The prefixes, the separator and the suffixes come from the configuration.
+ * Versions compare part by part as numbers, so `V2` comes before `V10` and
+ * `V1.1` before `V1.2`. Callbacks are not migrations, and a Java or Kotlin
+ * migration is a gap: its code is not SQL.
+ */
+
+import type { KindLinkRead, KindReadGap, KindReadMigration, KindReaderInput } from "./kind-link-readers";
+import { codeMigrations, findFlywayConfig, isCallback, readFlywayConfig, walk, type FlywayConfig } from "./flyway-layout";
+import { fieldString, withReplay } from "./migration-dirs";
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Compare dotted versions part by part as numbers; a missing part is 0. */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(/[._]/).map(BigInt);
+  const pb = b.split(/[._]/).map(BigInt);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] ?? 0n;
+    const y = pb[i] ?? 0n;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+export interface FlywayFile {
+  type: KindReadMigration["type"];
+  /** The version written with `.` between its parts; empty for a repeatable migration. */
+  version: string;
+  description: string;
+  file: string;
+}
+
+/** The file's migration role under `config`'s naming, or undefined when its name is not a migration's. */
+export function classifyFlywayFile(file: string, config: FlywayConfig): FlywayFile | undefined {
+  const name = file.split("/").pop() ?? file;
+  if (isCallback(name)) return undefined;
+  const suffix = config.sqlMigrationSuffixes.find((s) => name.endsWith(s));
+  if (!suffix) return undefined;
+  const stem = name.slice(0, -suffix.length);
+  const sep = escape(config.sqlMigrationSeparator);
+  const repeatable = new RegExp(`^${escape(config.repeatableSqlMigrationPrefix)}${sep}(.+)$`).exec(stem);
+  if (repeatable) return { type: "repeatable", version: "", description: repeatable[1]!.replace(/_/g, " "), file };
+  const roles: [KindReadMigration["type"], string][] = [
+    ["versioned", config.sqlMigrationPrefix],
+    ["baseline", config.baselineMigrationPrefix],
+    ["undo", config.undoSqlMigrationPrefix],
+  ];
+  for (const [type, prefix] of roles) {
+    if (!prefix) continue;
+    const m = new RegExp(`^${escape(prefix)}([0-9]+(?:[._][0-9]+)*)${sep}(.+)$`).exec(stem);
+    if (m) return { type, version: m[1]!.replace(/_/g, "."), description: m[2]!.replace(/_/g, " "), file };
+  }
+  return undefined;
+}
+
+/** The configuration file the replay depends on, besides the migrations: it holds the placeholders. */
+export function flywayReplayFiles(input: Pick<KindReaderInput, "tree" | "dir">): string[] {
+  const f = findFlywayConfig(input.tree, input.dir);
+  return f === undefined ? [] : [f];
+}
+
+export const readFlywayDir = (input: KindReaderInput): KindLinkRead => withReplay(listFlywayDir(input), input.tree, input.dir, flywayReplayFiles(input));
+
+function listFlywayDir(input: KindReaderInput): KindLinkRead {
+  const { tree, dir } = input;
+  const gaps: KindReadGap[] = [];
+  const result: KindLinkRead = { reader: "flyway-dir", links: [], gaps, migrations: [] };
+  const configFile = findFlywayConfig(tree, dir);
+  let config: FlywayConfig;
+  try {
+    config = readFlywayConfig(tree, configFile, dir);
+  } catch (err) {
+    gaps.push({ file: configFile ?? dir, line: 1, message: `the Flyway configuration could not be read (${(err as Error).message}), so no migration was listed` });
+    return result;
+  }
+  const dialect = fieldString(input.fields, "dialect", config.dialect ?? "postgres");
+  for (const l of config.outside) gaps.push({ file: configFile ?? dir, line: 1, message: `the location ${l} lies outside the workspace, so its migrations were not listed` });
+
+  const files = [...new Set(config.locations.flatMap((d) => walk(tree, d)))];
+  const classified = files.map((f) => classifyFlywayFile(f, config)).filter((f): f is FlywayFile => f !== undefined);
+  for (const code of codeMigrations(tree, config)) gaps.push({ file: code, line: 1, message: `${code.split("/").pop()!} is a code migration; its code is not SQL, so it is not listed` });
+
+  const undo = new Map(classified.filter((f) => f.type === "undo").map((f) => [f.version, f.file]));
+  const ordered = classified.filter((f) => f.type === "versioned" || f.type === "baseline").sort((a, b) => compareVersions(a.version, b.version) || (a.type === "baseline" ? -1 : 1) || (a.file < b.file ? -1 : 1));
+  const repeatable = classified.filter((f) => f.type === "repeatable").sort((a, b) => (a.description < b.description ? -1 : a.description > b.description ? 1 : a.file < b.file ? -1 : 1));
+  const seen = new Map<string, string>();
+  for (const f of ordered.filter((x) => x.type === "versioned")) {
+    const prior = [...seen.keys()].find((v) => compareVersions(v, f.version) === 0);
+    if (prior !== undefined) gaps.push({ file: f.file, line: 1, message: `version ${f.version} is also ${seen.get(prior)!}; Flyway refuses two migrations with one version` });
+    else seen.set(f.version, f.file);
+  }
+  [...ordered, ...repeatable].forEach((f, i) =>
+    result.migrations!.push({ position: i + 1, version: f.version, name: f.description, type: f.type, file: f.file, line: 1, down: f.type === "versioned" ? (undo.get(f.version) ?? false) : false, dialect }),
+  );
+  return result;
+}