@pgsql/transform 18.7.0 → 18.9.0

package/esm/facts.js

@@ -154,7 +154,8 @@ function classifyOne(nodeTag, node) {
         bodyReferences: [],
         securityRelevant: SECURITY_TAGS.has(nodeTag),
         securityDefiner: false,
-        dynamicSql: false
+        dynamicSql: false,
+        span: { start: 0, len: 0 }
     };
     switch (nodeTag) {
         case 'CreateSchemaStmt':
@@ -348,6 +349,8 @@ export function classifyStatements(sql) {
             const nodeTag = stmtNode ? Object.keys(stmtNode)[0] : 'other';
             const node = stmtNode?.[nodeTag] ?? {};
             const facts = classifyOne(nodeTag, node);
+            const start = stmt?.stmt_location ?? 0;
+            facts.span = { start, len: stmt?.stmt_len ?? Math.max(0, sql.length - start) };
             if (stmtNode) {
                 walkSql(stmtNode, createFactsVisitor(facts));
             }

package/esm/graph.js

@@ -0,0 +1,184 @@
+const keyOf = (q) => `${q.schema ?? ''}.${q.name}`;
+/**
+ * Build the typed statement dependency graph for a classified script.
+ *
+ * Edges only exist between statements of the same script: a reference with
+ * no in-script producer is an external dependency and induces no edge (the
+ * caller decides what to do with those — pgpm expresses them as
+ * cross-package requires).
+ */
+export function buildStatementGraph(facts) {
+    const nodes = facts.map((f, index) => ({
+        index,
+        facts: f,
+        out: [],
+        in: []
+    }));
+    const producers = new Map();
+    facts.forEach((f, i) => {
+        for (const created of f.creates) {
+            const key = keyOf(created);
+            const list = producers.get(key) ?? [];
+            list.push(i);
+            producers.set(key, list);
+        }
+    });
+    // The producer a reference binds to is the closest preceding statement
+    // that creates the object (redefinitions shadow earlier ones); when the
+    // reference precedes every producer, it binds to the first one — that is
+    // exactly the forward edge a reordering pass must satisfy.
+    const bind = (ref, from) => {
+        const list = producers.get(keyOf(ref));
+        if (!list || list.length === 0)
+            return undefined;
+        let found;
+        for (const i of list) {
+            if (i === from)
+                return undefined; // self-dependency: never an edge
+            if (i < from)
+                found = i;
+        }
+        return found ?? list[0];
+    };
+    const edges = [];
+    const addEdge = (from, to, kind, via) => {
+        if (edges.some(e => e.from === from && e.to === to && e.kind === kind))
+            return;
+        const edge = { from, to, kind, via };
+        edges.push(edge);
+        nodes[from].out.push(edge);
+        nodes[to].in.push(edge);
+    };
+    facts.forEach((f, i) => {
+        const bodyOnly = new Set(f.bodyReferences.map(keyOf));
+        const fkKeys = new Set(f.fkTargets.map(keyOf));
+        for (const ref of f.references) {
+            const to = bind(ref, i);
+            if (to === undefined)
+                continue;
+            const key = keyOf(ref);
+            const kind = fkKeys.has(key) ? 'fk' : bodyOnly.has(key) ? 'late' : 'hard';
+            addEdge(i, to, kind, ref);
+        }
+    });
+    const components = condense(nodes);
+    const order = stableTopoOrder(nodes, components);
+    return { nodes, edges, producers, components, order };
+}
+/**
+ * Tarjan SCC over `hard` + `fk` edges (`late` edges are ignored — they are
+ * call-time bindings and legitimately cyclic). Components are returned in
+ * reverse-topological completion order and then re-sorted topologically with
+ * source-order tie-breaking by {@link stableTopoOrder}; here we only sort
+ * each component's members and order components by their smallest member so
+ * output is deterministic.
+ */
+function condense(nodes) {
+    const n = nodes.length;
+    const indexOf = new Array(n).fill(-1);
+    const low = new Array(n).fill(0);
+    const onStack = new Array(n).fill(false);
+    const stack = [];
+    const components = [];
+    let counter = 0;
+    const orderingEdges = (v) => nodes[v].out.filter(e => e.kind !== 'late').map(e => e.to);
+    // Iterative Tarjan (DDL scripts can be tens of thousands of statements).
+    const visit = (root) => {
+        const frames = [{ v: root, edges: orderingEdges(root), i: 0 }];
+        indexOf[root] = low[root] = counter++;
+        stack.push(root);
+        onStack[root] = true;
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            if (frame.i < frame.edges.length) {
+                const w = frame.edges[frame.i++];
+                if (indexOf[w] === -1) {
+                    indexOf[w] = low[w] = counter++;
+                    stack.push(w);
+                    onStack[w] = true;
+                    frames.push({ v: w, edges: orderingEdges(w), i: 0 });
+                }
+                else if (onStack[w]) {
+                    low[frame.v] = Math.min(low[frame.v], indexOf[w]);
+                }
+            }
+            else {
+                frames.pop();
+                if (frames.length > 0) {
+                    const parent = frames[frames.length - 1];
+                    low[parent.v] = Math.min(low[parent.v], low[frame.v]);
+                }
+                if (low[frame.v] === indexOf[frame.v]) {
+                    const component = [];
+                    for (;;) {
+                        const w = stack.pop();
+                        onStack[w] = false;
+                        component.push(w);
+                        if (w === frame.v)
+                            break;
+                    }
+                    component.sort((a, b) => a - b);
+                    components.push(component);
+                }
+            }
+        }
+    };
+    for (let v = 0; v < n; v++) {
+        if (indexOf[v] === -1)
+            visit(v);
+    }
+    components.sort((a, b) => a[0] - b[0]);
+    return components;
+}
+/**
+ * Topologically order the condensation with source order breaking ties
+ * (Kahn's algorithm over components, min-heap on smallest member index),
+ * then flatten: members of each component stay in source order.
+ */
+function stableTopoOrder(nodes, components) {
+    const componentOf = new Array(nodes.length).fill(0);
+    components.forEach((members, c) => {
+        for (const m of members)
+            componentOf[m] = c;
+    });
+    const succ = components.map(() => new Set());
+    const indegree = new Array(components.length).fill(0);
+    for (const node of nodes) {
+        for (const e of node.out) {
+            if (e.kind === 'late')
+                continue;
+            const from = componentOf[e.from];
+            const to = componentOf[e.to];
+            if (from === to)
+                continue;
+            // Dependency edge from → to means `to` must come first.
+            if (!succ[to].has(from)) {
+                succ[to].add(from);
+                indegree[from]++;
+            }
+        }
+    }
+    const ready = [];
+    for (let c = 0; c < components.length; c++) {
+        if (indegree[c] === 0)
+            ready.push(c);
+    }
+    const takeMin = () => {
+        let best = 0;
+        for (let i = 1; i < ready.length; i++) {
+            if (components[ready[i]][0] < components[ready[best]][0])
+                best = i;
+        }
+        return ready.splice(best, 1)[0];
+    };
+    const order = [];
+    while (ready.length > 0) {
+        const c = takeMin();
+        order.push(...components[c]);
+        for (const next of succ[c]) {
+            if (--indegree[next] === 0)
+                ready.push(next);
+        }
+    }
+    return order;
+}

package/esm/index.js

@@ -1,4 +1,6 @@
 export { classifyStatements } from './facts';
+export { buildStatementGraph } from './graph';
+export { orderStatements, restructureSql } from './restructure';
 export { COMMON_EXTENSIONS, ExtensionRouter } from './extension-router';
 export { createExtensionResult, createExtensionVisitor, transformExtensions, } from './extension-transform';
 export { RoleRouter } from './role-router';

package/esm/restructure.js

@@ -0,0 +1,327 @@
+/**
+ * Granularity restructuring: rewrite a DDL script between equivalent shapes
+ * without changing the schema it produces.
+ *
+ * Three levels, two directions:
+ *
+ * - `atomic` — every table is a bare `CREATE TABLE ()` followed by one
+ *   `ALTER TABLE ADD COLUMN` per column and one `ADD CONSTRAINT` per
+ *   constraint (the shape machine emitters produce).
+ * - `object` — each table is fully baked: columns and same-table constraints
+ *   (PK / UNIQUE / CHECK / NOT NULL / DEFAULT) fold into the `CREATE TABLE`;
+ *   cross-object statements (FKs, indexes, triggers, policies) stay separate.
+ * - `consolidated` — additionally inlines foreign keys into the table
+ *   definition whenever the dependency graph proves it safe (the referenced
+ *   table can be ordered first); FKs on cycles stay as `ALTER TABLE`.
+ *
+ * Every fold is validated against the {@link buildStatementGraph} statement
+ * graph: a candidate merge is rejected if it would create an ordering cycle,
+ * so the pass degrades gracefully to the atomic form instead of emitting an
+ * undeployable script. Output statements are re-emitted in the graph's
+ * stable topological order.
+ */
+import { Deparser, parseSql } from 'plpgsql-parser';
+import { classifyStatements } from './facts';
+import { buildStatementGraph } from './graph';
+const relKey = (rel) => rel ? `${rel.schemaname ?? ''}.${rel.relname}` : null;
+const sameRel = (a, b) => !!a && !!b && relKey(a) === relKey(b);
+/**
+ * Restructure a DDL script to the requested granularity. The input and
+ * output scripts deploy to identical schemas; only statement shape and
+ * order change.
+ */
+export function restructureSql(sql, options) {
+    const warnings = [];
+    const parsed = parseSql(sql);
+    const stmts = (parsed?.stmts ?? [])
+        .map((s) => s?.stmt)
+        .filter(Boolean);
+    let outStmts;
+    let folded = 0;
+    let exploded = 0;
+    if (options.granularity === 'atomic') {
+        const result = explodeStatements(stmts);
+        outStmts = result.stmts;
+        exploded = result.exploded;
+    }
+    else {
+        const facts = classifyStatements(sql);
+        const graph = buildStatementGraph(facts);
+        const result = foldStatements(stmts, graph, options.granularity === 'consolidated', warnings);
+        outStmts = result.stmts;
+        folded = result.folded;
+    }
+    const ordered = orderStatements(outStmts);
+    const text = ordered.map(s => `${Deparser.deparse(s)};`).join('\n\n');
+    return { sql: text, folded, exploded, warnings };
+}
+/**
+ * Re-emit statements in the stable topological order of their dependency
+ * graph. Statements are deparsed and re-classified so the ordering reflects
+ * exactly what will be emitted.
+ */
+export function orderStatements(stmts) {
+    if (stmts.length <= 1)
+        return stmts;
+    const script = stmts.map(s => `${Deparser.deparse(s)};`).join('\n');
+    const graph = buildStatementGraph(classifyStatements(script));
+    if (graph.order.length !== stmts.length)
+        return stmts;
+    return graph.order.map(i => stmts[i]);
+}
+/**
+ * Fold `ALTER TABLE` commands into their table's `CREATE TABLE` statement.
+ * `inlineFks` additionally folds `ADD FOREIGN KEY` when the graph proves the
+ * referenced table can be created first.
+ */
+function foldStatements(stmts, graph, inlineFks, warnings) {
+    // Locate the CREATE TABLE for each relation.
+    const createIndex = new Map();
+    stmts.forEach((s, i) => {
+        const create = s?.CreateStmt;
+        if (create?.relation) {
+            const key = relKey(create.relation);
+            if (key && !createIndex.has(key))
+                createIndex.set(key, i);
+        }
+    });
+    // Fold bookkeeping is a union-find over statements: folding j into the
+    // CREATE at i merges their graph nodes, and the merged node's dependency
+    // set is the union of both. Reachability is then computed over merged
+    // nodes so a second fold cannot silently complete a cycle the first one
+    // started (the mutual-FK case).
+    const rep = new Map();
+    const find = (v) => {
+        let r = v;
+        while (rep.has(r))
+            r = rep.get(r);
+        return r;
+    };
+    // Per-statement dependencies: typed graph edges plus the implicit edge
+    // from every ALTER to its own table's CREATE (the facts model records the
+    // alter as *targeting* the table, so the graph carries no self edge).
+    const deps = new Map();
+    stmts.forEach((s, j) => {
+        const set = new Set();
+        for (const e of graph.nodes[j]?.out ?? []) {
+            if (e.kind !== 'late')
+                set.add(e.to);
+        }
+        const alterKey = relKey(s?.AlterTableStmt?.relation);
+        const own = alterKey ? createIndex.get(alterKey) : undefined;
+        if (own !== undefined && own !== j)
+            set.add(own);
+        deps.set(j, set);
+    });
+    const depsOf = (v) => [...(deps.get(find(v)) ?? [])].map(find).filter(t => t !== find(v));
+    const dependsOn = (from, target) => {
+        const goal = find(target);
+        const seen = new Set();
+        const stack = [find(from)];
+        while (stack.length > 0) {
+            const v = stack.pop();
+            if (v === goal)
+                return true;
+            if (seen.has(v))
+                continue;
+            seen.add(v);
+            stack.push(...depsOf(v));
+        }
+        return false;
+    };
+    /**
+     * A command at statement `j` may fold into the CREATE at statement `i`
+     * iff none of j's dependencies (other than i itself) transitively depend
+     * on i — otherwise the merged node would sit on a cycle.
+     */
+    const safeToFold = (j, i) => !depsOf(j).some(t => t !== find(i) && dependsOn(t, i));
+    /** Merge statement `j` into the CREATE at `i`. */
+    const absorb = (i, j) => {
+        const target = find(i);
+        const merged = deps.get(target) ?? new Set();
+        for (const t of deps.get(find(j)) ?? [])
+            merged.add(t);
+        deps.set(target, merged);
+        if (find(j) !== target)
+            rep.set(find(j), target);
+    };
+    const remove = new Set();
+    let folded = 0;
+    stmts.forEach((s, j) => {
+        const alter = s?.AlterTableStmt;
+        if (!alter || alter.objtype !== 'OBJECT_TABLE')
+            return;
+        const key = relKey(alter.relation);
+        const i = key ? createIndex.get(key) : undefined;
+        if (i === undefined || i === j)
+            return;
+        const create = stmts[i].CreateStmt;
+        const remaining = [];
+        for (const wrapped of alter.cmds ?? []) {
+            const cmd = wrapped?.AlterTableCmd;
+            if (!cmd) {
+                remaining.push(wrapped);
+                continue;
+            }
+            const constraint = cmd.def?.Constraint;
+            const isFk = cmd.subtype === 'AT_AddConstraint' && constraint?.contype === 'CONSTR_FOREIGN';
+            const selfFk = isFk && sameRel(constraint?.pktable, alter.relation);
+            let foldable = false;
+            switch (cmd.subtype) {
+                case 'AT_AddColumn':
+                    foldable = !!cmd.def?.ColumnDef;
+                    break;
+                case 'AT_ColumnDefault':
+                    foldable = !!cmd.name && cmd.def !== undefined;
+                    break;
+                case 'AT_SetNotNull':
+                    foldable = !!cmd.name;
+                    break;
+                case 'AT_AddConstraint':
+                    foldable = isFk ? selfFk || inlineFks : true;
+                    break;
+                default:
+                    foldable = false;
+            }
+            if (foldable && !selfFk && !safeToFold(j, i)) {
+                warnings.push(`kept atomic: statement ${j} on ${key} would create an ordering cycle if folded`);
+                foldable = false;
+            }
+            if (!foldable) {
+                remaining.push(wrapped);
+                continue;
+            }
+            if (!applyFold(create, cmd)) {
+                remaining.push(wrapped);
+                continue;
+            }
+            absorb(i, j);
+            folded++;
+        }
+        if (remaining.length === 0) {
+            remove.add(j);
+        }
+        else {
+            alter.cmds = remaining;
+        }
+    });
+    return { stmts: stmts.filter((_, i) => !remove.has(i)), folded };
+}
+/** Apply one foldable ALTER TABLE command onto a CreateStmt. */
+function applyFold(create, cmd) {
+    create.tableElts = create.tableElts ?? [];
+    const findColumn = (name) => create.tableElts.find((e) => e?.ColumnDef?.colname === name)?.ColumnDef;
+    switch (cmd.subtype) {
+        case 'AT_AddColumn':
+            create.tableElts.push({ ColumnDef: cmd.def.ColumnDef });
+            return true;
+        case 'AT_ColumnDefault': {
+            const col = findColumn(cmd.name);
+            if (!col)
+                return false;
+            col.constraints = col.constraints ?? [];
+            col.constraints.push({ Constraint: { contype: 'CONSTR_DEFAULT', raw_expr: cmd.def } });
+            return true;
+        }
+        case 'AT_SetNotNull': {
+            const col = findColumn(cmd.name);
+            if (!col)
+                return false;
+            col.constraints = col.constraints ?? [];
+            col.constraints.push({ Constraint: { contype: 'CONSTR_NOTNULL' } });
+            return true;
+        }
+        case 'AT_AddConstraint':
+            create.tableElts.push({ Constraint: cmd.def.Constraint });
+            return true;
+        default:
+            return false;
+    }
+}
+/** Column-level constraint types that stay inline on `ADD COLUMN`. */
+const INLINE_COLUMN_CONSTRAINTS = new Set(['CONSTR_DEFAULT', 'CONSTR_NOTNULL', 'CONSTR_NULL', 'CONSTR_IDENTITY', 'CONSTR_GENERATED']);
+/**
+ * Explode consolidated `CREATE TABLE` statements into the atomic shape:
+ * bare create, one `ADD COLUMN` per column (keeping column-local defaults /
+ * NOT NULL inline), one `ADD CONSTRAINT` per table-level or key constraint.
+ */
+function explodeStatements(stmts) {
+    const out = [];
+    let exploded = 0;
+    const alterFor = (relation, cmd) => ({
+        AlterTableStmt: {
+            objtype: 'OBJECT_TABLE',
+            relation,
+            cmds: [{ AlterTableCmd: cmd }]
+        }
+    });
+    for (const s of stmts) {
+        const create = s?.CreateStmt;
+        const elts = create?.tableElts ?? [];
+        // Typed tables / partitions / inheritance keep their shape.
+        if (!create || elts.length === 0 || create.ofTypename || create.partbound || create.inhRelations) {
+            out.push(s);
+            continue;
+        }
+        const relation = create.relation;
+        const columns = [];
+        const constraints = [];
+        for (const elt of elts) {
+            if (elt?.ColumnDef)
+                columns.push(elt.ColumnDef);
+            else if (elt?.Constraint)
+                constraints.push(elt.Constraint);
+            else {
+                // Unknown element (e.g. LIKE clause): keep the table intact.
+                columns.length = 0;
+                constraints.length = 0;
+                break;
+            }
+        }
+        if (columns.length === 0 && constraints.length === 0) {
+            out.push(s);
+            continue;
+        }
+        out.push({ CreateStmt: { ...create, tableElts: [] } });
+        for (const col of columns) {
+            const inline = [];
+            for (const wrapped of col.constraints ?? []) {
+                const c = wrapped?.Constraint;
+                if (c && INLINE_COLUMN_CONSTRAINTS.has(c.contype)) {
+                    inline.push(wrapped);
+                }
+                else if (c) {
+                    // Promote a column constraint (PK/UNIQUE/CHECK/FK) to table level.
+                    constraints.push(columnConstraintToTable(c, col.colname));
+                }
+            }
+            out.push(alterFor(relation, {
+                subtype: 'AT_AddColumn',
+                def: { ColumnDef: { ...col, constraints: inline.length > 0 ? inline : undefined } }
+            }));
+            exploded++;
+        }
+        for (const constraint of constraints) {
+            out.push(alterFor(relation, {
+                subtype: 'AT_AddConstraint',
+                def: { Constraint: constraint }
+            }));
+            exploded++;
+        }
+    }
+    return { stmts: out, exploded };
+}
+/** Rewrite a column-level constraint as its table-level equivalent. */
+function columnConstraintToTable(constraint, colname) {
+    const strNode = (sval) => ({ String: { sval } });
+    switch (constraint.contype) {
+        case 'CONSTR_PRIMARY':
+        case 'CONSTR_UNIQUE':
+            return { ...constraint, keys: [strNode(colname)] };
+        case 'CONSTR_FOREIGN':
+            return { ...constraint, fk_attrs: [strNode(colname)] };
+        default:
+            // CHECK and others are valid table constraints as-is.
+            return constraint;
+    }
+}