@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/migrations/checks.js

@@ -0,0 +1,97 @@
+/**
+ * Pre-migration checks (#52): what `checks` in `migration.json` may hold,
+ * and whether a query's rows pass one. Pure; `../versioned/checks.ts` runs
+ * them against a server.
+ *
+ * A check is part of `migration.json`, so of the migration's checksum and of
+ * the plan digest: editing, adding or removing one moves the digest, and an
+ * approval given before does not carry over.
+ */
+const NAME = /^[a-z0-9][a-z0-9_-]*$/;
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** What is wrong with a `checks` value read from `migration.json`, or `undefined` when it is well formed. */
+export function checksProblem(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        return "checks is not an array";
+    const seen = new Set();
+    for (const [i, c] of value.entries()) {
+        const at = `checks[${String(i)}]`;
+        if (!isRecord(c))
+            return `${at} is not an object`;
+        if (typeof c.name !== "string" || !NAME.test(c.name))
+            return `${at}.name must be lowercase letters, digits, - and _, got ${JSON.stringify(c.name)}`;
+        if (seen.has(c.name))
+            return `two checks are named ${c.name}`;
+        seen.add(c.name);
+        if (typeof c.sql !== "string" || c.sql.trim() === "")
+            return `${at} (${c.name}) has no sql`;
+        const e = c.expect;
+        if (e === undefined || e === "empty" || e === "true")
+            continue;
+        if (!isRecord(e))
+            return `${at} (${c.name}): expect must be "empty", "true" or { "min"?: n, "max"?: n }, got ${JSON.stringify(e)}`;
+        const extra = Object.keys(e).filter((k) => k !== "min" && k !== "max");
+        if (extra.length > 0 || (e.min === undefined && e.max === undefined))
+            return `${at} (${c.name}): expect { "min"?: n, "max"?: n } takes min, max or both, got ${JSON.stringify(e)}`;
+        for (const k of ["min", "max"]) {
+            if (e[k] !== undefined && (typeof e[k] !== "number" || !Number.isFinite(e[k])))
+                return `${at} (${c.name}): expect.${k} must be a number, got ${JSON.stringify(e[k])}`;
+        }
+    }
+    return undefined;
+}
+/** What a check expects, in words. */
+export function describeExpect(check) {
+    const e = check.expect ?? "empty";
+    if (e === "empty")
+        return "returns no rows";
+    if (e === "true")
+        return "returns true";
+    if (e.min !== undefined && e.max !== undefined)
+        return `returns a number from ${String(e.min)} to ${String(e.max)}`;
+    return e.min !== undefined ? `returns a number of at least ${String(e.min)}` : `returns a number of at most ${String(e.max ?? 0)}`;
+}
+const firstValue = (row) => (row ? Object.values(row)[0] : undefined);
+const asNumber = (v) => {
+    if (typeof v === "number")
+        return v;
+    if (typeof v === "bigint")
+        return Number(v);
+    if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)))
+        return Number(v);
+    return undefined;
+};
+const shown = (v) => (v === undefined ? "nothing" : typeof v === "bigint" ? v.toString() : JSON.stringify(v));
+/** Whether `rows`, what the check's query returned, pass it. */
+export function judgeCheck(check, rows) {
+    const e = check.expect ?? "empty";
+    const n = rows.length;
+    const count = `${String(n)} row${n === 1 ? "" : "s"}`;
+    if (e === "empty") {
+        return { name: check.name, passed: n === 0, detail: n === 0 ? "no rows" : `${count}, the first ${JSON.stringify(rows[0])}` };
+    }
+    if (n !== 1)
+        return { name: check.name, passed: false, detail: `${count}, not one` };
+    const v = firstValue(rows[0]);
+    if (e === "true") {
+        const passed = v === true || v === 1 || v === "1" || v === "true" || v === "t";
+        return { name: check.name, passed, detail: shown(v) };
+    }
+    const x = asNumber(v);
+    if (x === undefined)
+        return { name: check.name, passed: false, detail: `${shown(v)}, not a number` };
+    const passed = (e.min === undefined || x >= e.min) && (e.max === undefined || x <= e.max);
+    return { name: check.name, passed, detail: String(x) };
+}
+/**
+ * A `--check` argument: `<sql>`, or `<name>: <sql>`; the name defaults to
+ * `check-<n>`, n counting from 1. The check expects no rows.
+ */
+export function parseCheckArg(arg, n) {
+    const named = /^([a-z0-9][a-z0-9_-]*):\s+([\s\S]+)$/.exec(arg.trim());
+    const check = named ? { name: named[1] ?? "", sql: (named[2] ?? "").trim() } : { name: `check-${String(n)}`, sql: arg.trim() };
+    return check;
+}
+//# sourceMappingURL=checks.js.map

package/dist/migrations/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../../src/migrations/checks.ts"],"names":[],"mappings":"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"}

package/dist/migrations/checksum.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A migration's checksum: covers that migration's own files and nothing
+ * else, so editing, adding or removing another migration never changes it.
+ *
+ * Exactly:
+ *
+ *   sql  = migration.sql, with CRLF and lone CR turned into LF
+ *   json = migration.json parsed, its top-level "checksum" removed, then
+ *          written as JSON with every object's keys sorted and no whitespace
+ *   checksum = "sha256:" + lowercase hex of SHA-256 over the UTF-8 bytes of
+ *          "yodel-migration-checksum-v1\n"
+ *          + "migration.sql " + byteLength(sql) + "\n" + sql
+ *          + "migration.json " + byteLength(json) + "\n" + json
+ *          + for each other file in the migration's directory, by path:
+ *            path + " " + byteLength(text) + "\n" + text
+ *
+ * The other files are a migration's own besides the two, such as a backfill
+ * step's module (`backfill.ts`, see `../steps/backfill.ts`): every regular
+ * file under its directory, at any depth, except `migration.sql`,
+ * `migration.json` and anything whose name starts with `.`. `path` is
+ * relative to the directory with `/` separators; paths are taken in code
+ * point order, and each file's text has its line endings normalized as
+ * migration.sql's are. A migration with no other files hashes exactly as it
+ * did before they counted, so no existing checksum changes.
+ *
+ * The lengths frame each file, so no text can move from one file into the
+ * other and keep the hash. Because migration.json is hashed as parsed JSON,
+ * its whitespace, key order and line endings do not count; every value in it
+ * does, the parent id and the recorded schema included. Whitespace in
+ * migration.sql counts, except line endings.
+ */
+import { type MigrationDocument, type MigrationFiles } from "./document.js";
+export declare const CHECKSUM_PREFIX = "sha256:";
+/** The canonical JSON of a migration document, without its checksum: what the checksum hashes for `migration.json`. */
+export declare function canonicalDocument(doc: MigrationDocument | Record<string, unknown>): string;
+/**
+ * The checksum of a migration's files. `json` may be the file's text or the
+ * document already parsed; whatever `checksum` it holds is ignored. `extra`
+ * is the migration's other files, by path (see above).
+ */
+export declare function computeChecksum(files: {
+    sql: string;
+    json: string | MigrationDocument | Record<string, unknown>;
+    extra?: Readonly<Record<string, string>> | undefined;
+}): string;
+export interface ChecksumCheck {
+    ok: boolean;
+    /** The checksum `migration.json` records. */
+    recorded: string;
+    /** The checksum of the files as they are. */
+    actual: string;
+}
+/** Whether a migration's files still hash to the checksum its `migration.json` records. */
+export declare function verifyChecksum(m: {
+    files: MigrationFiles;
+} | MigrationFiles): ChecksumCheck;

package/dist/migrations/checksum.js

@@ -0,0 +1,72 @@
+/**
+ * A migration's checksum: covers that migration's own files and nothing
+ * else, so editing, adding or removing another migration never changes it.
+ *
+ * Exactly:
+ *
+ *   sql  = migration.sql, with CRLF and lone CR turned into LF
+ *   json = migration.json parsed, its top-level "checksum" removed, then
+ *          written as JSON with every object's keys sorted and no whitespace
+ *   checksum = "sha256:" + lowercase hex of SHA-256 over the UTF-8 bytes of
+ *          "yodel-migration-checksum-v1\n"
+ *          + "migration.sql " + byteLength(sql) + "\n" + sql
+ *          + "migration.json " + byteLength(json) + "\n" + json
+ *          + for each other file in the migration's directory, by path:
+ *            path + " " + byteLength(text) + "\n" + text
+ *
+ * The other files are a migration's own besides the two, such as a backfill
+ * step's module (`backfill.ts`, see `../steps/backfill.ts`): every regular
+ * file under its directory, at any depth, except `migration.sql`,
+ * `migration.json` and anything whose name starts with `.`. `path` is
+ * relative to the directory with `/` separators; paths are taken in code
+ * point order, and each file's text has its line endings normalized as
+ * migration.sql's are. A migration with no other files hashes exactly as it
+ * did before they counted, so no existing checksum changes.
+ *
+ * The lengths frame each file, so no text can move from one file into the
+ * other and keep the hash. Because migration.json is hashed as parsed JSON,
+ * its whitespace, key order and line endings do not count; every value in it
+ * does, the parent id and the recorded schema included. Whitespace in
+ * migration.sql counts, except line endings.
+ */
+import { createHash } from "node:crypto";
+import { MIGRATION_JSON, MIGRATION_SQL, normalizeLineEndings, sortKeys } from "./document.js";
+export const CHECKSUM_PREFIX = "sha256:";
+const DOMAIN = "yodel-migration-checksum-v1\n";
+/** The canonical JSON of a migration document, without its checksum: what the checksum hashes for `migration.json`. */
+export function canonicalDocument(doc) {
+    const rest = { ...doc };
+    delete rest.checksum;
+    return JSON.stringify(sortKeys(rest));
+}
+/**
+ * The checksum of a migration's files. `json` may be the file's text or the
+ * document already parsed; whatever `checksum` it holds is ignored. `extra`
+ * is the migration's other files, by path (see above).
+ */
+export function computeChecksum(files) {
+    const sql = normalizeLineEndings(files.sql);
+    const doc = typeof files.json === "string" ? JSON.parse(files.json) : files.json;
+    const json = canonicalDocument(doc);
+    const hash = createHash("sha256");
+    hash.update(DOMAIN, "utf8");
+    hash.update(`${MIGRATION_SQL} ${String(Buffer.byteLength(sql, "utf8"))}\n`, "utf8");
+    hash.update(sql, "utf8");
+    hash.update(`${MIGRATION_JSON} ${String(Buffer.byteLength(json, "utf8"))}\n`, "utf8");
+    hash.update(json, "utf8");
+    for (const path of Object.keys(files.extra ?? {}).sort()) {
+        const text = normalizeLineEndings(files.extra?.[path] ?? "");
+        hash.update(`${path} ${String(Buffer.byteLength(text, "utf8"))}\n`, "utf8");
+        hash.update(text, "utf8");
+    }
+    return `${CHECKSUM_PREFIX}${hash.digest("hex")}`;
+}
+/** Whether a migration's files still hash to the checksum its `migration.json` records. */
+export function verifyChecksum(m) {
+    const files = "files" in m ? m.files : m;
+    const doc = JSON.parse(files.json);
+    const recorded = typeof doc.checksum === "string" ? doc.checksum : "";
+    const actual = computeChecksum(files);
+    return { ok: recorded === actual, recorded, actual };
+}
+//# sourceMappingURL=checksum.js.map

package/dist/migrations/checksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.js","sourceRoot":"","sources":["../../src/migrations/checksum.ts"],"names":[],"mappings":"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"}

package/dist/migrations/create.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Making the next migration, offline: the newest migration's recorded
+ * schema (or an empty schema, for the first) diffed against the current
+ * build with chant's `diffStatements`. No server is read. The statements
+ * are written for a single node and the migration records no topology: it
+ * is rendered for each environment's topology when it is applied (#9). Pure: nothing
+ * here touches the disk; `yodel new` writes what it returns with
+ * `writeMigration`.
+ */
+import { type DiffStatementsOptions, type SchemaStatements } from "@intentius/chant-lexicon-sql/migration-statements";
+import type { BuildOutput } from "../chant/build.js";
+import { type MigrationCheck, type MigrationDocument, type MigrationFiles, type MigrationStep } from "./document.js";
+import { type Migration } from "./directory.js";
+export interface CreateMigrationOptions {
+    /** The migration's name, the part of its id after the timestamp. */
+    name: string;
+    /** The current `chant build` output: the schema after the migration. */
+    build: BuildOutput;
+    /** The newest migration, which the new one follows; `undefined` for the first. */
+    previous?: Migration | undefined;
+    /** When it is made. Default: now. Its UTC minute is the id's timestamp. */
+    now?: Date;
+    /** The ownership marker each `CREATE` carries. Default: chant's, `managed-by=chant`. */
+    marker?: DiffStatementsOptions["marker"];
+    /** ClickHouse: the database a bare name means. Default: chant's, `default`. */
+    defaultDatabase?: string;
+    /** Postgres: the schema a bare name means. Default: chant's, `public`. */
+    defaultSchema?: string;
+    /**
+     * A backfill step to end the migration with (#12): the module's text,
+     * written into the migration's directory as `file` (default `backfill.ts`)
+     * and counted in its checksum. With one, a migration is made even when the
+     * build has no schema change.
+     */
+    backfill?: {
+        text: string;
+        file?: string;
+    };
+    /** Pre-migration checks (#52), written to `migration.json`. */
+    checks?: MigrationCheck[];
+}
+export interface CreatedMigration {
+    id: string;
+    document: MigrationDocument;
+    files: MigrationFiles;
+    statements: SchemaStatements;
+}
+/** What {@link createMigration} returns when the build has no change from the recorded schema. */
+export interface NoChange {
+    id: undefined;
+    statements: SchemaStatements;
+}
+/** `YYYYMMDDTHHMM` in UTC. */
+export declare function migrationTimestamp(now: Date): string;
+/** `<YYYYMMDDTHHMM>-<name>`, or an error for a name that is not lowercase words joined by `-` or `_`. */
+export declare function migrationId(name: string, now: Date): string;
+/**
+ * The schema before the first migration: a build of the same dialect with no
+ * objects. `diffStatements` takes two build outputs and has no form for
+ * "nothing", so this is one. A Postgres build's `postgresMajor` is kept, so
+ * both sides classify for the same major.
+ */
+export declare function emptyBuild(like: BuildOutput): BuildOutput;
+/** The steps that are not statements: each Op or manual step, which a person has to act on. */
+export declare const refusedSteps: (steps: readonly MigrationStep[]) => Exclude<MigrationStep, {
+    kind: "statement";
+}>[];
+/** `migration.sql`: a header naming the migration, its parent, any Op or manual step and the diff's hints, then chant's rendered statements. */
+export declare function renderMigrationSql(doc: Pick<MigrationDocument, "id" | "parent" | "hints">, statements: SchemaStatements): string;
+/**
+ * The next migration, or a {@link NoChange} when the build declares the
+ * schema the previous migration recorded. Throws a YodelError when the
+ * recorded schema and the build are different dialects.
+ */
+export declare function createMigration(options: CreateMigrationOptions): CreatedMigration | NoChange;

package/dist/migrations/create.js

@@ -0,0 +1,120 @@
+/**
+ * Making the next migration, offline: the newest migration's recorded
+ * schema (or an empty schema, for the first) diffed against the current
+ * build with chant's `diffStatements`. No server is read. The statements
+ * are written for a single node and the migration records no topology: it
+ * is rendered for each environment's topology when it is applied (#9). Pure: nothing
+ * here touches the disk; `yodel new` writes what it returns with
+ * `writeMigration`.
+ */
+import { diffStatements, renderStatements } from "@intentius/chant-lexicon-sql/migration-statements";
+import { YodelError } from "../project.js";
+import { computeChecksum } from "./checksum.js";
+import { MIGRATION_FORMAT, serializeDocument } from "./document.js";
+import { MIGRATION_NAME } from "./directory.js";
+import { asBackfill, BACKFILL_FILE } from "../steps/kinds.js";
+import { backfillStep } from "../steps/backfill.js";
+/** `YYYYMMDDTHHMM` in UTC. */
+export function migrationTimestamp(now) {
+    const iso = now.toISOString(); // 2026-10-09T14:12:34.567Z
+    return `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}T${iso.slice(11, 13)}${iso.slice(14, 16)}`;
+}
+/** `<YYYYMMDDTHHMM>-<name>`, or an error for a name that is not lowercase words joined by `-` or `_`. */
+export function migrationId(name, now) {
+    if (!MIGRATION_NAME.test(name)) {
+        throw new YodelError(`migration name "${name}": use lowercase letters and digits, words joined by - or _ (e.g. add-country)`);
+    }
+    return `${migrationTimestamp(now)}-${name}`;
+}
+/**
+ * The schema before the first migration: a build of the same dialect with no
+ * objects. `diffStatements` takes two build outputs and has no form for
+ * "nothing", so this is one. A Postgres build's `postgresMajor` is kept, so
+ * both sides classify for the same major.
+ */
+export function emptyBuild(like) {
+    return {
+        dialect: like.dialect,
+        objects: [],
+        ...(typeof like.postgresMajor === "number" ? { postgresMajor: like.postgresMajor } : {}),
+    };
+}
+/** The steps that are not statements: each Op or manual step, which a person has to act on. */
+export const refusedSteps = (steps) => steps.filter((s) => s.kind !== "statement");
+function describeRefused(s) {
+    const backfill = asBackfill(s);
+    if (backfill)
+        return `a backfill: the Op ${backfill.options.file} exports, its effect() batches resumable from their receipts`;
+    const rules = s.changes.map((c) => c.rule).join(", ");
+    return s.kind === "op"
+        ? `${s.op} for ${s.object} (${s.name}), ${rules}: not SQL; migration.json holds its declaration`
+        : `a manual step for ${s.object} (${s.name}), ${rules}: no statement and no Op makes it`;
+}
+/** `migration.sql`: a header naming the migration, its parent, any Op or manual step and the diff's hints, then chant's rendered statements. */
+export function renderMigrationSql(doc, statements) {
+    const head = [`-- yodel migration ${doc.id}`, `-- parent: ${doc.parent ?? "none (the first migration)"}`];
+    const refused = refusedSteps(statements.steps);
+    if (refused.length > 0) {
+        head.push(`-- This migration contains ${refused.some((s) => s.kind === "op") ? "an Op step" : "a manual step"}, not only SQL:`);
+        for (const s of refused)
+            head.push(`--   ${describeRefused(s)}`);
+    }
+    for (const h of doc.hints)
+        head.push(`-- hint: ${h.replace(/\r?\n/g, " ")}`);
+    const body = statements.steps
+        .map((s) => {
+        const backfill = asBackfill(s);
+        return backfill ? `-- ${backfill.object} (${backfill.name}): made by the Op ${backfill.options.file} exports, not a statement\n` : renderStatements({ ...statements, steps: [s] });
+    })
+        .join("\n")
+        .replace(/\n+$/, "");
+    return `${head.join("\n")}\n\n${body}\n`;
+}
+/**
+ * The next migration, or a {@link NoChange} when the build declares the
+ * schema the previous migration recorded. Throws a YodelError when the
+ * recorded schema and the build are different dialects.
+ */
+export function createMigration(options) {
+    const now = options.now ?? new Date();
+    const id = migrationId(options.name, now);
+    const before = options.previous?.document.schema ?? emptyBuild(options.build);
+    let statements;
+    try {
+        statements = diffStatements(before, options.build, {
+            ...(options.marker ? { marker: options.marker } : {}),
+            ...(options.defaultDatabase !== undefined ? { defaultDatabase: options.defaultDatabase } : {}),
+            ...(options.defaultSchema !== undefined ? { defaultSchema: options.defaultSchema } : {}),
+        });
+    }
+    catch (e) {
+        throw new YodelError(e instanceof Error ? e.message : String(e));
+    }
+    if (options.backfill) {
+        const file = options.backfill.file ?? BACKFILL_FILE;
+        statements = { ...statements, refused: true, steps: [...statements.steps, backfillStep(options.name, file)] };
+    }
+    if (statements.steps.length === 0)
+        return { id: undefined, statements };
+    const unsigned = {
+        format: MIGRATION_FORMAT,
+        id,
+        parent: options.previous?.id ?? null,
+        checksum: "",
+        createdAt: `${now.toISOString().slice(0, 19)}Z`,
+        dialect: statements.dialect,
+        ...(statements.defaultDatabase !== undefined ? { defaultDatabase: statements.defaultDatabase } : {}),
+        ...(statements.defaultSchema !== undefined ? { defaultSchema: statements.defaultSchema } : {}),
+        ...(statements.major !== undefined ? { major: statements.major } : {}),
+        refused: statements.refused,
+        hints: statements.hints,
+        ...(options.checks && options.checks.length > 0 ? { checks: options.checks } : {}),
+        steps: statements.steps,
+        schema: options.build,
+    };
+    const sql = renderMigrationSql(unsigned, statements);
+    const extra = options.backfill ? { [options.backfill.file ?? BACKFILL_FILE]: options.backfill.text } : undefined;
+    const document = { ...unsigned, checksum: computeChecksum({ sql, json: unsigned, extra }) };
+    return { id, document, files: { sql, json: serializeDocument(document), ...(extra ? { extra } : {}) }, statements };
+}
+//# sourceMappingURL=create.js.map

package/dist/migrations/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/migrations/create.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAqD,MAAM,mDAAmD,CAAC;AACxJ,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAwF,MAAM,eAAe,CAAC;AAC1J,OAAO,EAAE,cAAc,EAAkB,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAyCpD,8BAA8B;AAC9B,MAAM,UAAU,kBAAkB,CAAC,GAAS;IAC1C,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,2BAA2B;IAC1D,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AAC5G,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,GAAS;IACjD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,mBAAmB,IAAI,gFAAgF,CAAC,CAAC;IAChI,CAAC;IACD,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAiB;IAC1C,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,EAAE;QACX,GAAG,CAAC,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzF,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAA+B,EAAmD,EAAE,CAC/G,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAsD,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;AAElG,SAAS,eAAe,CAAC,CAAgD;IACvE,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,QAAQ;QAAE,OAAO,sBAAsB,QAAQ,CAAC,OAAO,CAAC,IAAI,8DAA8D,CAAC;IAC/H,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC,IAAI,KAAK,IAAI;QACpB,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,KAAK,iDAAiD;QAChG,CAAC,CAAC,qBAAqB,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,KAAK,mCAAmC,CAAC;AAC7F,CAAC;AAED,gJAAgJ;AAChJ,MAAM,UAAU,kBAAkB,CAAC,GAAuD,EAAE,UAA4B;IACtH,MAAM,IAAI,GAAG,CAAC,sBAAsB,GAAG,CAAC,EAAE,EAAE,EAAE,cAAc,GAAG,CAAC,MAAM,IAAI,4BAA4B,EAAE,CAAC,CAAC;IAC1G,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,8BAA8B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,iBAAiB,CAAC,CAAC;QAChI,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO,QAAQ,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,IAAI,qBAAqB,QAAQ,CAAC,OAAO,CAAC,IAAI,6BAA6B,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrL,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvB,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,IAAI,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,UAA4B,CAAC;IACjC,IAAI,CAAC;QACH,UAAU,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE;YACjD,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9F,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,aAAa,CAAC;QACpD,UAAU,GAAG,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAA6B,CAAC,EAAE,CAAC;IAC5I,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;IAExE,MAAM,QAAQ,GAAsB;QAClC,MAAM,EAAE,gBAAgB;QACxB,EAAE;QACF,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,IAAI,IAAI;QACpC,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG;QAC/C,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,GAAG,CAAC,UAAU,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpG,GAAG,CAAC,UAAU,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9F,GAAG,CAAC,UAAU,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,MAAM,EAAE,OAAO,CAAC,KAAK;KACtB,CAAC;IACF,MAAM,GAAG,GAAG,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACjH,MAAM,QAAQ,GAAsB,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC/G,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC;AACtH,CAAC"}

package/dist/migrations/directory.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Reading and writing a project's `migrations/` directory.
+ *
+ * Order is the chain of parent ids, as in Alembic and pgroll: the first
+ * migration has `parent: null`, every other names the one it follows, and
+ * the list runs from the first to the newest. The ids' timestamps never
+ * decide the order. A directory is well formed when the parent links make
+ * one unbroken chain:
+ *
+ * - every directory under `migrations/` is named like an id and holds a
+ *   readable `migration.sql` and `migration.json` whose `id` is that name
+ *   (plain files directly under `migrations/`, such as a README, are
+ *   ignored; files inside a migration's directory are its own and count in
+ *   its checksum);
+ * - every parent names a migration in the directory;
+ * - no two migrations have the same parent, `null` included. Two branches
+ *   that each added a migration give one parent two children: a fork. It is
+ *   reported naming both, never ordered by timestamp or by name;
+ * - every migration is reachable from the first (no cycles).
+ *
+ * {@link scanMigrations} reports every problem and never throws on one, for
+ * `yodel lint`. {@link readMigrations} returns the ordered chain or throws a
+ * {@link MigrationDirectoryError} listing the problems, for the verbs that
+ * act on the chain (`new`, `apply`, `rebase`).
+ */
+import { YodelError } from "../project.js";
+import { type ChecksumCheck } from "./checksum.js";
+import { type MigrationDocument, type MigrationFiles } from "./document.js";
+/** Where a project keeps its migrations, relative to the project directory. */
+export declare const MIGRATIONS_DIR = "migrations";
+/** `<YYYYMMDDTHHMM>-<name>`; a name is lowercase letters and digits, words joined by `-` or `_`. */
+export declare const MIGRATION_ID: RegExp;
+export declare const MIGRATION_NAME: RegExp;
+/** One migration as read from disk. */
+export interface Migration {
+    id: string;
+    /** Its directory, absolute. */
+    dir: string;
+    parent: string | null;
+    /** The checksum `migration.json` records (not recomputed; see {@link verifyChecksum}). */
+    checksum: string;
+    document: MigrationDocument;
+    /** The files' text exactly as read. */
+    files: MigrationFiles;
+}
+export type MigrationProblem = {
+    kind: "unreadable";
+    path: string;
+    message: string;
+} | {
+    kind: "id-mismatch";
+    id: string;
+    recorded: string;
+    message: string;
+} | {
+    kind: "missing-parent";
+    id: string;
+    parent: string;
+    message: string;
+} | {
+    kind: "fork";
+    parent: string | null;
+    children: string[];
+    message: string;
+} | {
+    kind: "unreachable";
+    ids: string[];
+    message: string;
+} | {
+    kind: "checksum";
+    id: string;
+    check: ChecksumCheck;
+    message: string;
+};
+export interface MigrationScan {
+    /** The migrations directory, absolute. */
+    dir: string;
+    /** Every migration that could be read, sorted by id. */
+    migrations: Migration[];
+    /** From the first migration to the newest, when there is no structural problem; else `undefined`. */
+    ordered: Migration[] | undefined;
+    /** Every problem found. Checksum mismatches are listed here but never stop {@link MigrationScan.ordered} being computed. */
+    problems: MigrationProblem[];
+}
+/** A migrations directory that is not one unbroken chain, or (when asked) whose checksums do not match. */
+export declare class MigrationDirectoryError extends YodelError {
+    readonly dir: string;
+    readonly problems: MigrationProblem[];
+    constructor(dir: string, problems: MigrationProblem[]);
+}
+/**
+ * A migration's files besides migration.sql and migration.json, by path
+ * relative to its directory (`/` separators): every regular file at any
+ * depth, except those two and anything whose name starts with `.`.
+ */
+export declare function readExtraFiles(at: string): Record<string, string>;
+/** Every migration in `dir` and every problem with the directory. A missing `dir` is an empty directory. */
+export declare function scanMigrations(dir: string): MigrationScan;
+/**
+ * The migrations in `dir`, from the first to the newest. Throws a
+ * {@link MigrationDirectoryError} on any structural problem (unreadable,
+ * id mismatch, missing parent, fork, cycle), and, with `verify`, on a
+ * checksum mismatch too. A missing `dir` has no migrations.
+ */
+export declare function readMigrations(dir: string, options?: {
+    verify?: boolean;
+}): Migration[];
+/** The newest migration of an ordered list (the end of the chain), or `undefined` for none. */
+export declare const newestMigration: (ordered: readonly Migration[]) => Migration | undefined;
+/**
+ * Writes a migration's directory, `<dir>/<id>/`, creating `dir` as needed.
+ * The files go into a hidden directory first and are renamed into place, so
+ * a reader never sees half a migration. An existing `<id>` is an error.
+ * Returns the directory written.
+ */
+export declare function writeMigration(dir: string, migration: {
+    id: string;
+    files: MigrationFiles;
+}): string;