@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/lint/silences.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Silences: a line in `migration.sql`, above the statement it is for,
+ *
+ *     -- yodel:allow <rule> <reason>
+ *
+ * silences that statement rule for that one step. The reason is required
+ * and is recorded, with the rule and the step, in every history row the
+ * migration writes when it applies (the `silences` column), so the history
+ * says who accepted what and why. Because `migration.sql` is in the
+ * migration's checksum, a silence is part of what an approval covers.
+ *
+ * Which step a line is "above": `migration.sql` holds each step in the
+ * order `migration.json` lists them, a statement as its SQL followed by
+ * `;`, an Op or manual step as a comment starting `-- <object> (<name>):`
+ * (`renderStatements`). Each step is found in that order; a silence belongs
+ * to the first step found after it. A statement `migration.sql` does not
+ * hold as `migration.json` records it is reported (`migration-sql`): apply
+ * runs `migration.json`'s, so an edit to the SQL alone changes nothing.
+ */
+import type { MigrationStep } from "@intentius/chant-lexicon-sql/migration-statements";
+/** One `-- yodel:allow` line, read. */
+export interface Silence {
+    /** The step it is above, an index into `migration.json`'s `steps`. */
+    step: number;
+    rule: string;
+    reason: string;
+    /** Its line in migration.sql, from 1. */
+    line: number;
+}
+/** What was wrong with a migration.sql. */
+export interface SqlProblem {
+    rule: "migration-sql" | "silence";
+    message: string;
+    step?: number;
+    line?: number;
+}
+export interface SqlMap {
+    silences: Silence[];
+    problems: SqlProblem[];
+}
+/**
+ * Reads the silences in `sql` and assigns each to its step. `known` is the
+ * set of rule ids a silence may name. Problems: a silence that is
+ * malformed, names an unknown rule or one that cannot be silenced, has no
+ * reason, or follows the last step; a step migration.sql does not hold.
+ */
+export declare function mapMigrationSql(sql: string, steps: readonly MigrationStep[], silenceable: ReadonlySet<string>): SqlMap;
+/** The silences as the history's `silences` field holds them: JSON, `[{"step":0,"rule":"...","reason":"..."}]`. */
+export declare const silencesJson: (silences: readonly Silence[]) => string;

package/dist/lint/silences.js

@@ -0,0 +1,91 @@
+/**
+ * Silences: a line in `migration.sql`, above the statement it is for,
+ *
+ *     -- yodel:allow <rule> <reason>
+ *
+ * silences that statement rule for that one step. The reason is required
+ * and is recorded, with the rule and the step, in every history row the
+ * migration writes when it applies (the `silences` column), so the history
+ * says who accepted what and why. Because `migration.sql` is in the
+ * migration's checksum, a silence is part of what an approval covers.
+ *
+ * Which step a line is "above": `migration.sql` holds each step in the
+ * order `migration.json` lists them, a statement as its SQL followed by
+ * `;`, an Op or manual step as a comment starting `-- <object> (<name>):`
+ * (`renderStatements`). Each step is found in that order; a silence belongs
+ * to the first step found after it. A statement `migration.sql` does not
+ * hold as `migration.json` records it is reported (`migration-sql`): apply
+ * runs `migration.json`'s, so an edit to the SQL alone changes nothing.
+ */
+import { normalizeLineEndings } from "../migrations/document.js";
+const DIRECTIVE = /yodel:\s*allow\b/i;
+const SILENCE = /^\s*--\s*yodel:allow(?:\s+(\S+))?(?:\s+(.*?))?\s*$/;
+/** The text that marks a step in migration.sql. */
+function anchorOf(step) {
+    return step.kind === "statement" ? `${step.sql};` : `-- ${step.object} (${step.name}):`;
+}
+const describe = (step, i) => `step ${String(i)} (${step.kind === "statement" ? `${step.rule} ${step.class}` : step.kind}, ${step.name})`;
+/**
+ * Reads the silences in `sql` and assigns each to its step. `known` is the
+ * set of rule ids a silence may name. Problems: a silence that is
+ * malformed, names an unknown rule or one that cannot be silenced, has no
+ * reason, or follows the last step; a step migration.sql does not hold.
+ */
+export function mapMigrationSql(sql, steps, silenceable) {
+    const text = normalizeLineEndings(sql);
+    const lineAt = (offset) => text.slice(0, offset).split("\n").length;
+    const out = { silences: [], problems: [] };
+    const readRegion = (from, to, step) => {
+        const region = text.slice(from, to);
+        let offset = from;
+        for (const raw of region.split("\n")) {
+            const line = lineAt(offset);
+            offset += raw.length + 1;
+            if (!DIRECTIVE.test(raw) || !raw.trimStart().startsWith("--"))
+                continue;
+            const m = SILENCE.exec(raw);
+            const rule = m?.[1];
+            const reason = m?.[2]?.trim() ?? "";
+            if (!m || rule === undefined) {
+                out.problems.push({ rule: "silence", line, message: `migration.sql line ${String(line)}: expected -- yodel:allow <rule> <reason>` });
+                continue;
+            }
+            if (!silenceable.has(rule)) {
+                out.problems.push({ rule: "silence", line, message: `migration.sql line ${String(line)}: ${rule} is not a rule a statement can silence (${[...silenceable].join(", ")})` });
+                continue;
+            }
+            if (reason === "") {
+                out.problems.push({ rule: "silence", line, message: `migration.sql line ${String(line)}: silencing ${rule} needs a reason: -- yodel:allow ${rule} <why this is safe>` });
+                continue;
+            }
+            if (step === undefined) {
+                out.problems.push({ rule: "silence", line, message: `migration.sql line ${String(line)}: yodel:allow ${rule} comes after the last step, so it silences nothing; put it above the statement` });
+                continue;
+            }
+            out.silences.push({ step, rule, reason, line });
+        }
+    };
+    let cursor = 0;
+    steps.forEach((step, i) => {
+        const anchor = anchorOf(step);
+        const at = text.indexOf(anchor, cursor);
+        if (at === -1) {
+            if (step.kind === "statement") {
+                out.problems.push({
+                    rule: "migration-sql",
+                    step: i,
+                    message: `${describe(step, i)}: migration.sql does not hold its statement as migration.json records it (${step.sql.split("\n")[0] ?? ""}); yodel apply runs migration.json's`,
+                });
+            }
+            // An Op or manual step's comment is for people; a missing one moves nothing.
+            return;
+        }
+        readRegion(cursor, at, i);
+        cursor = at + anchor.length;
+    });
+    readRegion(cursor, text.length, undefined);
+    return out;
+}
+/** The silences as the history's `silences` field holds them: JSON, `[{"step":0,"rule":"...","reason":"..."}]`. */
+export const silencesJson = (silences) => JSON.stringify(silences.map((s) => ({ step: s.step, rule: s.rule, reason: s.reason })));
+//# sourceMappingURL=silences.js.map

package/dist/lint/silences.js.map

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

package/dist/lint/statements.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The statement rules: each step of a migration against the class chant's
+ * classifier gave it (`migration.json` records the rule and class of every
+ * statement, and the changes an Op or manual step makes). Pure.
+ *
+ * - `destructive`: a statement marked destructive (a table or column drop),
+ *   or an Op step one of whose changes is.
+ * - `ch-mutation`: a ClickHouse statement of class `rewrite`, or one that
+ *   waits for its mutation (a column type or TTL change).
+ * - `ch-rebuild`: a `ClickHouseRebuildOp` step.
+ * - `pg-rewrite`: a Postgres statement of class `rewrite` (ACCESS EXCLUSIVE
+ *   for a rewrite or a full scan).
+ * - `pg-lock`: a Postgres statement that blocks writes for a whole build or
+ *   scan: an index created or dropped on an existing table without
+ *   `CONCURRENTLY` (SQLPG240 to SQLPG243), a primary key or unique
+ *   constraint built in place rather than `USING INDEX` (SQLPG221), a
+ *   foreign key or domain constraint validated in place rather than added
+ *   `NOT VALID` (SQLPG219, SQLPG262).
+ *
+ * `COMMENT ON` statements are skipped: chant writes one after a `CREATE`
+ * with the same rule, and a comment is catalog only.
+ *
+ * A statement whose rule is not one of the lexicon's, or a step of a kind
+ * it does not know, is `unreadable-object`: lint cannot tell what it does,
+ * and never passes what it cannot read.
+ */
+import type { MigrationStep } from "@intentius/chant-lexicon-sql/migration-statements";
+export type Dialect = "clickhouse" | "postgres";
+export interface StepFinding {
+    rule: string;
+    message: string;
+}
+/** What lint cannot read in a step, or `undefined`. */
+export declare function unreadableStep(dialect: Dialect, step: MigrationStep): string | undefined;
+/** The statement-rule findings for one step, before levels and silences. */
+export declare function stepFindings(dialect: Dialect, step: MigrationStep): StepFinding[];
+/** Why yodel apply refuses a step, or `undefined` for one it runs. */
+export declare function refusedStep(step: MigrationStep): string | undefined;

package/dist/lint/statements.js

@@ -0,0 +1,120 @@
+/**
+ * The statement rules: each step of a migration against the class chant's
+ * classifier gave it (`migration.json` records the rule and class of every
+ * statement, and the changes an Op or manual step makes). Pure.
+ *
+ * - `destructive`: a statement marked destructive (a table or column drop),
+ *   or an Op step one of whose changes is.
+ * - `ch-mutation`: a ClickHouse statement of class `rewrite`, or one that
+ *   waits for its mutation (a column type or TTL change).
+ * - `ch-rebuild`: a `ClickHouseRebuildOp` step.
+ * - `pg-rewrite`: a Postgres statement of class `rewrite` (ACCESS EXCLUSIVE
+ *   for a rewrite or a full scan).
+ * - `pg-lock`: a Postgres statement that blocks writes for a whole build or
+ *   scan: an index created or dropped on an existing table without
+ *   `CONCURRENTLY` (SQLPG240 to SQLPG243), a primary key or unique
+ *   constraint built in place rather than `USING INDEX` (SQLPG221), a
+ *   foreign key or domain constraint validated in place rather than added
+ *   `NOT VALID` (SQLPG219, SQLPG262).
+ *
+ * `COMMENT ON` statements are skipped: chant writes one after a `CREATE`
+ * with the same rule, and a comment is catalog only.
+ *
+ * A statement whose rule is not one of the lexicon's, or a step of a kind
+ * it does not know, is `unreadable-object`: lint cannot tell what it does,
+ * and never passes what it cannot read.
+ */
+import { CLASSIFIER_RULES } from "@intentius/chant-lexicon-sql/clickhouse/plan/rules";
+import { PG_CLASSIFIER_RULES } from "@intentius/chant-lexicon-sql/postgres/plan/rules";
+import { planStep, REBUILD_OP } from "../steps/kinds.js";
+const catalog = (dialect) => (dialect === "clickhouse" ? CLASSIFIER_RULES : PG_CLASSIFIER_RULES);
+/** The classifier rule's id and title, e.g. `SQLCH202 Drop a column`. */
+function titled(dialect, rule) {
+    const r = catalog(dialect)[rule];
+    return r ? `${rule} ${r.title}` : rule;
+}
+const COMMENT = /^\s*COMMENT\s+ON\b/i;
+const INDEX_DDL = /^\s*(?:CREATE\s+(?:UNIQUE\s+)?INDEX|DROP\s+INDEX|REINDEX)\b/i;
+const CONCURRENTLY = /\bCONCURRENTLY\b/i;
+const NOT_VALID = /\bNOT\s+VALID\b/i;
+const USING_INDEX = /\bUSING\s+INDEX\b/i;
+const ALTER_TABLE = /^\s*ALTER\s+TABLE\b/i;
+/** Why a Postgres statement blocks writes for a whole build or scan, or `undefined`. */
+function pgLock(step) {
+    const sql = step.sql;
+    if (step.class === "create")
+        return undefined; // an index on a table created in the same migration blocks nobody
+    if (["SQLPG221", "SQLPG240", "SQLPG241", "SQLPG242", "SQLPG243"].includes(step.rule) && INDEX_DDL.test(sql) && !CONCURRENTLY.test(sql)) {
+        return /^\s*DROP/i.test(sql)
+            ? "drops an index without CONCURRENTLY: ACCESS EXCLUSIVE on the table, blocking reads and writes behind it; use DROP INDEX CONCURRENTLY"
+            : "builds an index without CONCURRENTLY: SHARE on the table, blocking every write until the build ends; declare the index CONCURRENTLY";
+    }
+    if (step.rule === "SQLPG221" && ALTER_TABLE.test(sql) && !USING_INDEX.test(sql)) {
+        return "builds the constraint's index under ACCESS EXCLUSIVE; build a unique index CONCURRENTLY first, then ADD CONSTRAINT ... USING INDEX";
+    }
+    if (step.rule === "SQLPG219" && !NOT_VALID.test(sql)) {
+        return "reads every row under SHARE ROW EXCLUSIVE on both tables, blocking writes to them for the scan; add it NOT VALID and validate it in a later migration";
+    }
+    if (step.rule === "SQLPG262" && !NOT_VALID.test(sql)) {
+        return "checks every column of the domain's type in every table while it holds its lock; add it NOT VALID and validate it later";
+    }
+    return undefined;
+}
+/** What lint cannot read in a step, or `undefined`. */
+export function unreadableStep(dialect, step) {
+    const kind = step.kind;
+    if (kind !== "statement" && kind !== "op" && kind !== "manual")
+        return `a step of kind ${JSON.stringify(kind)}, which is not statement, op or manual`;
+    if (step.kind === "statement") {
+        if (typeof step.sql !== "string" || step.sql.trim() === "")
+            return "a statement step with no SQL";
+        const known = catalog(dialect)[step.rule];
+        return known ? undefined : `a statement whose rule ${JSON.stringify(step.rule)} is not one of the ${dialect} classifier's, so what it does cannot be checked`;
+    }
+    for (const c of step.changes) {
+        if (!catalog(dialect)[c.rule])
+            return `a ${step.kind} step whose change ${JSON.stringify(c.rule)} is not one of the ${dialect} classifier's rules`;
+    }
+    return undefined;
+}
+/** The statement-rule findings for one step, before levels and silences. */
+export function stepFindings(dialect, step) {
+    const out = [];
+    if (step.kind === "statement") {
+        if (COMMENT.test(step.sql))
+            return out;
+        const what = `${titled(dialect, step.rule)} on ${step.name}`;
+        if (step.destructive)
+            out.push({ rule: "destructive", message: `${what}: removes data that cannot be recovered` });
+        if (dialect === "clickhouse" && (step.class === "rewrite" || step.waitsForMutation === true)) {
+            out.push({ rule: "ch-mutation", message: `${what}: a mutation that rewrites existing parts in the background, with no rollback` });
+        }
+        if (dialect === "postgres") {
+            if (step.class === "rewrite") {
+                const r = catalog(dialect)[step.rule];
+                out.push({ rule: "pg-rewrite", message: `${what}: blocks reads and writes on the table while it runs${r ? ` (${r.restriction})` : ""}` });
+            }
+            const lock = pgLock(step);
+            if (lock)
+                out.push({ rule: "pg-lock", message: `${what}: ${lock}` });
+        }
+        return out;
+    }
+    if (step.kind === "op") {
+        const destructive = step.changes.filter((c) => c.destructive);
+        if (destructive.length > 0) {
+            out.push({ rule: "destructive", message: `${step.op} for ${step.name} removes data that cannot be recovered: ${destructive.map((c) => `${titled(dialect, c.rule)} (${c.field})`).join(", ")}` });
+        }
+        if (step.op === REBUILD_OP) {
+            const why = step.changes.filter((c) => c.class === "rebuild").map((c) => `${titled(dialect, c.rule)} (${c.field})`);
+            out.push({ rule: "ch-rebuild", message: `${REBUILD_OP} rebuilds ${step.name}: every row is copied into a new table and swapped in${why.length > 0 ? `, for ${why.join(", ")}` : ""}` });
+        }
+    }
+    return out;
+}
+/** Why yodel apply refuses a step, or `undefined` for one it runs. */
+export function refusedStep(step) {
+    const plan = planStep(step);
+    return plan.run === "refused" ? plan.reason : undefined;
+}
+//# sourceMappingURL=statements.js.map

package/dist/lint/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../../src/lint/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAgBzD,MAAM,OAAO,GAAG,CAAC,OAAgB,EAAyC,EAAE,CAAC,CAAC,OAAO,KAAK,YAAY,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;AAEjJ,yEAAyE;AACzE,SAAS,MAAM,CAAC,OAAgB,EAAE,IAAY;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,GAAG,qBAAqB,CAAC;AACtC,MAAM,SAAS,GAAG,8DAA8D,CAAC;AACjF,MAAM,YAAY,GAAG,mBAAmB,CAAC;AACzC,MAAM,SAAS,GAAG,kBAAkB,CAAC;AACrC,MAAM,WAAW,GAAG,oBAAoB,CAAC;AACzC,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAE3C,wFAAwF;AACxF,SAAS,MAAM,CAAC,IAAmD;IACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC,CAAC,kEAAkE;IACjH,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvI,OAAO,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1B,CAAC,CAAC,sIAAsI;YACxI,CAAC,CAAC,qIAAqI,CAAC;IAC5I,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChF,OAAO,oIAAoI,CAAC;IAC9I,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO,uJAAuJ,CAAC;IACjK,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO,yHAAyH,CAAC;IACnI,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,IAAmB;IAClE,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI,CAAC;IAC/C,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,kBAAkB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,wCAAwC,CAAC;IACtJ,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,8BAA8B,CAAC;QAClG,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,sBAAsB,OAAO,kDAAkD,CAAC;IAChK,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,IAAI,CAAC,IAAI,sBAAsB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,sBAAsB,OAAO,qBAAqB,CAAC;IACrJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,IAAmB;IAChE,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACvC,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7D,IAAI,IAAI,CAAC,WAAW;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,IAAI,yCAAyC,EAAE,CAAC,CAAC;QACnH,IAAI,OAAO,KAAK,YAAY,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7F,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,IAAI,+EAA+E,EAAE,CAAC,CAAC;QACrI,CAAC;QACD,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,IAAI,uDAAuD,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC5I,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QAC9D,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,EAAE,QAAQ,IAAI,CAAC,IAAI,2CAA2C,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACnM,CAAC;QACD,IAAI,IAAI,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;YACpH,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,UAAU,aAAa,IAAI,CAAC,IAAI,wDAAwD,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1L,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC"}

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,73 @@
+/**
+ * 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 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;
+    };
+}
+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,119 @@
+/**
+ * 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,
+        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