@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/change-set.js

@@ -0,0 +1,250 @@
+/**
+ * SQL plans as change-set parts (#3767, the document is #3181).
+ *
+ * The sql lexicon's declarative plans reach the change set through `chant
+ * lifecycle plan`. Two kinds of SQL plan do not, and this module is their
+ * adapter:
+ *
+ * - a versioned plan: the migrations a product (SQL Yodeler) would apply to
+ *   an environment, each a list of steps in the shape `diffStatements`
+ *   writes (`./core/statements.ts`). {@link sqlVersionedPlanPart}.
+ * - the plan step of the lexicon's own migration Ops, `ClickHouseRebuildOp`
+ *   and `PostgresMigrationOp`. {@link clickhouseRebuildPart} and
+ *   {@link postgresMigrationPart}.
+ *
+ * Each returns a part with planner `sql`, so it composes with every other
+ * member's in `composeChangeSet`, and a gate that binds the document gets its
+ * Cedar `context.plan` (#3182). A part written to a file as JSON reads back
+ * through core's `readChangeSetPart` with `planner: "sql"`.
+ *
+ * ## Entries
+ *
+ * One entry per object a plan touches, at the object's server name (`db.name`
+ * or `schema.name`), however many steps or migrations touch it. The action
+ * and disruption come from the change classes the steps carry, as the
+ * dialects' `CHANGE_CLASSES` and `PG_CHANGE_CLASSES` price them:
+ *
+ * - a `drop` class is a `delete` (`destroy`); a `create` class a `create`;
+ * - a `rebuild` or `expand` class, or a step a migration Op makes, is a
+ *   `replace` (`replace`): the object, or a column of it, is built again;
+ * - anything else is an `update`, its disruption the worst class's
+ *   (`metadata` in-place; `validate`, `concurrently` and `rewrite` rolling).
+ *   A step marked destructive (a column drop) makes it `destroy`. A class
+ *   neither dialect knows makes it `unknown`.
+ *
+ * A step may name its `action` itself, which wins over its classes.
+ *
+ * ## The import graph
+ *
+ * Like `@intentius/chant/change-set`, this module bundles small for a tool
+ * that runs it in CI with no TypeScript toolchain: it imports chant's plan
+ * hashing code and types only. `change-set.test.ts` holds that.
+ */
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+/** The lexicon a SQL part's member and entries name. */
+export const SQL_CHANGE_SET_LEXICON = "sql";
+/**
+ * What each change class costs, both dialects together. The same values as
+ * `CHANGE_CLASSES.disruption` (ClickHouse) and `PG_CHANGE_CLASSES.disruption`
+ * (Postgres), copied so the rule tables stay out of the bundle; the test
+ * holds the two together.
+ */
+export const SQL_CLASS_DISRUPTION = {
+    create: "in-place",
+    metadata: "in-place",
+    validate: "rolling",
+    concurrently: "rolling",
+    rewrite: "rolling",
+    rebuild: "replace",
+    expand: "replace",
+    drop: "destroy",
+};
+const RANK = { "in-place": 0, rolling: 1, unknown: 2, replace: 3, destroy: 4 };
+const worst = (a, b) => (a === undefined || RANK[b] > RANK[a] ? b : a);
+const ACTION_ORDER = ["delete", "replace", "create", "update", "forget", "read", "no-op"];
+const unwrap = (s) => "step" in s && s.step && typeof s.step === "object" ? { ...s.step, ...(s.done ? { done: true } : {}) } : s;
+function gather(steps) {
+    const byAddress = new Map();
+    for (const step of steps) {
+        if (step.done)
+            continue;
+        let o = byAddress.get(step.name);
+        if (!o) {
+            o = { address: step.name, type: step.type, classes: [], actions: [], destructive: false, ops: [], manual: [], sql: [], fields: new Map() };
+            byAddress.set(step.name, o);
+        }
+        if (step.action)
+            o.actions.push(step.action);
+        const changes = step.changes ?? [];
+        if (step.kind === "statement") {
+            o.classes.push(step.class);
+            o.sql.push(step.sql);
+            if (step.destructive)
+                o.destructive = true;
+        }
+        else if (step.kind === "op") {
+            o.ops.push(step.op);
+        }
+        else {
+            o.manual.push(step.detail);
+        }
+        for (const c of changes) {
+            o.classes.push(c.class);
+            if (c.destructive)
+                o.destructive = true;
+            const had = o.fields.get(c.field);
+            // The first step's before, the last step's after.
+            o.fields.set(c.field, had ? { ...c, ...(had.before !== undefined ? { before: had.before } : {}) } : c);
+        }
+    }
+    return [...byAddress.values()];
+}
+function attributesOf(o) {
+    const attributes = [...o.fields.values()]
+        .sort((a, b) => (a.field < b.field ? -1 : a.field > b.field ? 1 : 0))
+        .map((c) => ({
+        path: c.field,
+        ...(c.before !== undefined ? { before: c.before } : {}),
+        ...(c.after !== undefined ? { after: c.after } : {}),
+        ...(SQL_CLASS_DISRUPTION[c.class] === "replace" ? { forcesReplacement: true } : {}),
+    }));
+    if (o.sql.length > 0)
+        attributes.push({ path: "sql", after: o.sql });
+    if (o.ops.length > 0)
+        attributes.push({ path: "op", after: [...new Set(o.ops)] });
+    if (o.manual.length > 0)
+        attributes.push({ path: "manual", after: o.manual });
+    return attributes;
+}
+/** The action and disruption of one object's changes, as the module's header says. */
+export function sqlChangeAction(o) {
+    let disruption;
+    for (const c of o.classes)
+        disruption = worst(disruption, SQL_CLASS_DISRUPTION[c] ?? "unknown");
+    if (o.ops.length > 0)
+        disruption = worst(disruption, "replace");
+    if (o.destructive)
+        disruption = worst(disruption, "destroy");
+    let action;
+    if (o.actions.length > 0)
+        action = ACTION_ORDER.find((a) => o.actions.includes(a));
+    else if (o.classes.includes("drop"))
+        action = "delete";
+    else if (o.classes.includes("create"))
+        action = "create";
+    else if (o.ops.length > 0 || o.classes.some((c) => SQL_CLASS_DISRUPTION[c] === "replace"))
+        action = "replace";
+    else
+        action = "update";
+    switch (action) {
+        case "create":
+        case "read":
+        case "no-op":
+        case "forget":
+            return { action };
+        case "delete":
+            return { action, disruption: "destroy" };
+        case "replace":
+            return { action, disruption: worst(disruption, "replace") };
+        default:
+            return { action, disruption: disruption ?? "unknown" };
+    }
+}
+function entriesOf(member, lexicon, scope, objects) {
+    return objects.map((o) => ({
+        member,
+        lexicon,
+        planner: "sql",
+        address: o.address,
+        type: o.type,
+        ...sqlChangeAction(o),
+        ...(scope !== undefined ? { scope } : {}),
+        attributes: attributesOf(o),
+    }));
+}
+/**
+ * A versioned plan's part ({@link SqlVersionedPlan}): one entry per object
+ * its pending steps touch, `scope` the environment. A refusal makes the
+ * member `failed` with no plan digest; its entries stay, for a reader.
+ */
+export function sqlVersionedPlanPart(input) {
+    const { plan } = input;
+    const lexicon = input.lexicon ?? SQL_CHANGE_SET_LEXICON;
+    const migrations = (plan.migrations ?? plan.pending ?? []).map((m) => ({ id: m.id, steps: m.steps.map(unwrap) }));
+    const objects = gather(migrations.flatMap((m) => m.steps));
+    const refusal = plan.refusal === undefined ? undefined : typeof plan.refusal === "string" ? plan.refusal : plan.refusal.message;
+    const planDigest = refusal !== undefined
+        ? null
+        : (plan.digest ??
+            computePlanDigest("sql-versioned-plan", {
+                dialect: plan.dialect,
+                environment: plan.environment ?? null,
+                migrations: migrations.map((m) => ({ id: m.id, steps: m.steps.filter((s) => !s.done) })),
+            }));
+    return {
+        member: {
+            member: input.member,
+            lexicon,
+            planner: "sql",
+            ...(plan.environment !== undefined ? { scope: plan.environment } : {}),
+            status: refusal !== undefined ? "failed" : "planned",
+            ...(refusal !== undefined ? { error: refusal } : {}),
+            planDigest,
+            holes: plan.holes ?? [],
+        },
+        entries: entriesOf(input.member, lexicon, plan.environment, objects),
+    };
+}
+/** A change as a plain string, read back as far as its rule and field go. */
+function changeOf(line) {
+    const m = /^(\S+)\s+([^\s:]+)/.exec(line);
+    return { rule: m?.[1] ?? line, class: "unknown", field: m?.[2] ?? line };
+}
+function opPart(input, op, active, address, type) {
+    const { plan } = input;
+    const lexicon = input.lexicon ?? SQL_CHANGE_SET_LEXICON;
+    const running = plan.state === active;
+    const changes = plan.classified ?? plan.changes.map(changeOf);
+    const objects = running
+        ? gather([{ kind: "op", object: address, type, name: address, op, importPath: "", options: {}, declaration: "", changes, detail: "" }])
+        : [];
+    // Swapped or done: the Op has nothing left to change in the schema; the digest says which.
+    const planDigest = running && plan.planDigest ? plan.planDigest : computePlanDigest("sql-op-plan", { op, address, state: plan.state, planDigest: plan.planDigest ?? null });
+    return {
+        member: {
+            member: input.member,
+            lexicon,
+            planner: "sql",
+            ...(input.environment !== undefined ? { scope: input.environment } : {}),
+            status: "planned",
+            planDigest,
+            holes: [],
+        },
+        entries: entriesOf(input.member, lexicon, input.environment, objects),
+    };
+}
+/**
+ * The part of a `ClickHouseRebuildOp`'s plan step: while the state is
+ * `rebuild`, one `replace` of the table, its plan digest the step's (the
+ * value before the verification, not the swap gate's). `swapped` and `done`
+ * propose nothing.
+ */
+export function clickhouseRebuildPart(input) {
+    const table = input.plan.table;
+    if (!table)
+        throw new Error("clickhouseRebuildPart: the plan names no table");
+    return opPart(input, "ClickHouseRebuildOp", "rebuild", table, "ClickHouse::Table");
+}
+/**
+ * The part of a `PostgresMigrationOp`'s plan step: while the state is
+ * `migrate`, one `replace` of the table (`schema.table`) whose column it
+ * expands and contracts, its plan digest the step's. `switched` and `done`
+ * propose nothing.
+ */
+export function postgresMigrationPart(input) {
+    const migration = input.plan.migration;
+    if (!migration)
+        throw new Error("postgresMigrationPart: the plan names no migration");
+    const table = migration.split(".").slice(0, -1).join(".") || migration;
+    return opPart(input, "PostgresMigrationOp", "migrate", table, "Postgres::Table");
+}