@pgsql/transform 18.8.0 → 18.10.0

package/graph.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStatementGraph = buildStatementGraph;
+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).
+ */
+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/index.d.ts

@@ -1,5 +1,11 @@
 export type { ExtensionAction, ExtensionFact, QualifiedName, StatementFacts, StatementKind, } from './facts';
 export { classifyStatements } from './facts';
+export type { EdgeKind, StatementEdge, StatementGraph, StatementNode, } from './graph';
+export { buildStatementGraph } from './graph';
+export type { ObjectIdentity, ObjectIdentityKind, } from './naming';
+export { identityOf } from './naming';
+export type { Granularity, RestructureOptions, RestructureResult, } from './restructure';
+export { orderStatements, restructureSql } from './restructure';
 export type { ExtensionDefinition, ExtensionRoute, ExtensionRouteSpec, ExtensionRouterOptions, ExtensionSymbol, ExtensionSymbolNamespace, SymbolRewrite, } from './extension-router';
 export { COMMON_EXTENSIONS, ExtensionRouter } from './extension-router';
 export type { ExtensionTransformResult } from './extension-transform';

package/index.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.walkPlpgsqlForSchemas = exports.validateNoUntransformedSchemas = exports.transformVerifyCalls = exports.transformSqlStatement = exports.transformSql = exports.transformSchemaName = exports.transformRelation = exports.transformPlpgsqlTypeString = exports.transformPlpgsqlTypeAst = exports.transformNameList = exports.transformJsonStringValues = exports.transformComments = exports.shouldTransformSchema = exports.extractPgpmHeader = exports.escapeRegexp = exports.createSqlVisitor = exports.createPlpgsqlVisitor = exports.trimDefElemBody = exports.normalizeTree = exports.cleanTree = exports.CLEAN_TREE_VOLATILE_KEYS = exports.validateRoundTrip = exports.normalizeParseTree = exports.firstDifference = exports.captureTransformAsts = exports.captureAstsFromSql = exports.SchemaRouter = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.transformRoles = exports.createRoleVisitor = exports.createRoleResult = exports.RoleRouter = exports.transformExtensions = exports.createExtensionVisitor = exports.createExtensionResult = exports.ExtensionRouter = exports.COMMON_EXTENSIONS = exports.classifyStatements = void 0;
+exports.walkPlpgsqlForSchemas = exports.validateNoUntransformedSchemas = exports.transformVerifyCalls = exports.transformSqlStatement = exports.transformSql = exports.transformSchemaName = exports.transformRelation = exports.transformPlpgsqlTypeString = exports.transformPlpgsqlTypeAst = exports.transformNameList = exports.transformJsonStringValues = exports.transformComments = exports.shouldTransformSchema = exports.extractPgpmHeader = exports.escapeRegexp = exports.createSqlVisitor = exports.createPlpgsqlVisitor = exports.trimDefElemBody = exports.normalizeTree = exports.cleanTree = exports.CLEAN_TREE_VOLATILE_KEYS = exports.validateRoundTrip = exports.normalizeParseTree = exports.firstDifference = exports.captureTransformAsts = exports.captureAstsFromSql = exports.SchemaRouter = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.transformRoles = exports.createRoleVisitor = exports.createRoleResult = exports.RoleRouter = exports.transformExtensions = exports.createExtensionVisitor = exports.createExtensionResult = exports.ExtensionRouter = exports.COMMON_EXTENSIONS = exports.restructureSql = exports.orderStatements = exports.identityOf = exports.buildStatementGraph = exports.classifyStatements = void 0;
 var facts_1 = require("./facts");
 Object.defineProperty(exports, "classifyStatements", { enumerable: true, get: function () { return facts_1.classifyStatements; } });
+var graph_1 = require("./graph");
+Object.defineProperty(exports, "buildStatementGraph", { enumerable: true, get: function () { return graph_1.buildStatementGraph; } });
+var naming_1 = require("./naming");
+Object.defineProperty(exports, "identityOf", { enumerable: true, get: function () { return naming_1.identityOf; } });
+var restructure_1 = require("./restructure");
+Object.defineProperty(exports, "orderStatements", { enumerable: true, get: function () { return restructure_1.orderStatements; } });
+Object.defineProperty(exports, "restructureSql", { enumerable: true, get: function () { return restructure_1.restructureSql; } });
 var extension_router_1 = require("./extension-router");
 Object.defineProperty(exports, "COMMON_EXTENSIONS", { enumerable: true, get: function () { return extension_router_1.COMMON_EXTENSIONS; } });
 Object.defineProperty(exports, "ExtensionRouter", { enumerable: true, get: function () { return extension_router_1.ExtensionRouter; } });

package/naming.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Object identity — the canonical, Postgres-native answer to "what object is
+ * this statement about?".
+ *
+ * Identity is the key used by dependency graphs, semantic diffing, and any
+ * downstream naming scheme. It is a pure function of classifier facts —
+ * grounded in the parser's node taxonomy (`CreateStmt`, `CreateTrigStmt`,
+ * `IndexStmt`, ...), never in surface syntax like RangeVars. Rendering an
+ * identity to a change path (e.g. a pgpm module layout) is deliberately NOT
+ * defined here: paths are derived projections that belong to whichever
+ * packaging layer consumes the identity, so nothing is ever attached to them.
+ *
+ * Identity tuple: `(kind, schema, name, table?)` — `table` scopes objects
+ * that are only unique per table (triggers, policies, indexes, constraints,
+ * seed data). Function overloads share an identity for now (signature
+ * disambiguation is a planned refinement).
+ */
+import { StatementFacts } from './facts';
+/** The kinds of objects an identity can describe. */
+export type ObjectIdentityKind = 'schema' | 'extension' | 'role' | 'table' | 'view' | 'sequence' | 'type' | 'function' | 'index' | 'trigger' | 'policy' | 'constraint' | 'seed_dml' | 'other';
+/**
+ * The identity of a database object. Identity is the diff/dependency key;
+ * any path or name is only a downstream rendering of it.
+ */
+export interface ObjectIdentity {
+    kind: ObjectIdentityKind;
+    /** Owning schema (`null` for non-schema objects: roles, extensions). */
+    schema: string | null;
+    /** Object name, unqualified (for table-scoped kinds: without the table). */
+    name: string;
+    /** Owning table, for objects only unique per table (trigger/policy/index/constraint/seed). */
+    table?: string;
+}
+/**
+ * Derive the identity of the object a statement primarily creates or
+ * targets, or `null` when the statement creates nothing (grants, comments —
+ * such statements ride with the change of the object they attach to).
+ *
+ * Table-scoped kinds are recovered from the classifier's table-qualified
+ * names (`table.trigger`) and, for indexes and constraints, from the
+ * targeted relation.
+ */
+export declare function identityOf(facts: StatementFacts): ObjectIdentity | null;

package/naming.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityOf = identityOf;
+/**
+ * Derive the identity of the object a statement primarily creates or
+ * targets, or `null` when the statement creates nothing (grants, comments —
+ * such statements ride with the change of the object they attach to).
+ *
+ * Table-scoped kinds are recovered from the classifier's table-qualified
+ * names (`table.trigger`) and, for indexes and constraints, from the
+ * targeted relation.
+ */
+function identityOf(facts) {
+    if (facts.kind === 'extension' && facts.extension) {
+        return { kind: 'extension', schema: null, name: facts.extension.name };
+    }
+    const created = facts.creates[0];
+    if (!created)
+        return null;
+    switch (facts.kind) {
+        case 'schema':
+            return { kind: 'schema', schema: null, name: created.name };
+        case 'trigger':
+        case 'policy': {
+            const dot = created.name.indexOf('.');
+            if (dot > 0) {
+                return {
+                    kind: facts.kind,
+                    schema: created.schema,
+                    name: created.name.slice(dot + 1),
+                    table: created.name.slice(0, dot)
+                };
+            }
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        }
+        case 'index': {
+            // IndexStmt records the index name in creates and the indexed relation
+            // in references (same-schema RangeVar).
+            const rel = facts.references.find(r => r.schema === created.schema) ?? facts.references[0];
+            return {
+                kind: 'index',
+                schema: created.schema,
+                name: created.name,
+                table: rel?.name
+            };
+        }
+        case 'fk_constraint':
+        case 'constraint':
+        case 'rls_enable':
+            // ALTER TABLE statements target their table.
+            return { kind: 'constraint', schema: created.schema, name: created.name, table: created.name };
+        case 'seed_dml':
+            return { kind: 'seed_dml', schema: created.schema, name: created.name, table: created.name };
+        case 'table':
+            // AlterTableStmt facts also classify as `table`-targeting; the created
+            // name is the table either way.
+            return { kind: 'table', schema: created.schema, name: created.name };
+        case 'view':
+        case 'function':
+        case 'type':
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        default:
+            if (facts.nodeTag === 'CreateSeqStmt') {
+                return { kind: 'sequence', schema: created.schema, name: created.name };
+            }
+            return { kind: 'other', schema: created.schema, name: created.name };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.8.0",
+  "version": "18.10.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "AST-based SQL transformation, qualification, classification and closure analysis for PostgreSQL",
   "main": "index.js",
@@ -49,5 +49,5 @@
     "classify",
     "plpgsql"
   ],
-  "gitHead": "979608121bc1e7daf2bd11473b2b894266e21bc7"
+  "gitHead": "ce8ea3fadd2549dfbe699c05c38c8a85090efc8c"
 }

package/restructure.d.ts

@@ -0,0 +1,29 @@
+/** The target shape of a restructured script. */
+export type Granularity = 'atomic' | 'object' | 'consolidated';
+export interface RestructureOptions {
+    granularity: Granularity;
+}
+export interface RestructureResult {
+    /** The restructured script, statements in stable topological order. */
+    sql: string;
+    /** Number of statements folded into a `CREATE TABLE` (fold direction). */
+    folded: number;
+    /** Number of statements produced by explosion (atomize direction). */
+    exploded: number;
+    /** Folds that were rejected (with the reason) and other non-fatal notes. */
+    warnings: string[];
+}
+type AnyNode = Record<string, any>;
+/**
+ * Restructure a DDL script to the requested granularity. The input and
+ * output scripts deploy to identical schemas; only statement shape and
+ * order change.
+ */
+export declare function restructureSql(sql: string, options: RestructureOptions): RestructureResult;
+/**
+ * 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 declare function orderStatements(stmts: AnyNode[]): AnyNode[];
+export {};