@pgsql/transform 18.1.1 → 18.3.1

package/esm/qualify.js

@@ -0,0 +1,297 @@
+/**
+ * Opt-in qualification of unqualified object references.
+ *
+ * Handwritten SQL is typically unqualified — objects implicitly land in (and
+ * resolve against) the `public` schema. The core schema transform only
+ * rewrites *explicitly* qualified references, so ingesting such code into
+ * named schemas needs a prior pass that pins every unqualified reference to a
+ * schema first. This module provides that pass.
+ *
+ * Safety model: only routed names are qualified — either everything in an
+ * {@link ObjectInventory} to a single schema, or per-object routes via
+ * `targets`. Builtin functions (`now()`, `count(...)`), builtin types, and
+ * column references are never touched because they are not routed. Names
+ * defined by a CTE in the same statement are excluded even when they collide
+ * with a routed relation.
+ */
+import { walk as walkSql } from '@pgsql/traverse';
+import { Deparser, parseSql, transformSync, walk as walkPlpgsql } from 'plpgsql-parser';
+import { classifyStatements } from './facts';
+const RELATION_TAGS = new Set([
+    'CreateStmt',
+    'ViewStmt',
+    'CreateSeqStmt',
+    'CreateTableAsStmt'
+]);
+const TYPE_TAGS = new Set([
+    'CreateEnumStmt',
+    'CreateDomainStmt',
+    'CreateRangeStmt',
+    'CompositeTypeStmt'
+]);
+/**
+ * Collect the objects a SQL script creates, bucketed for qualification.
+ * Only unqualified (schema-less) creations are collected — an explicitly
+ * qualified creation already declares where it lives.
+ */
+export function collectCreatedObjects(sql) {
+    const inventory = {
+        relations: new Set(),
+        functions: new Set(),
+        types: new Set()
+    };
+    for (const facts of classifyStatements(sql)) {
+        for (const created of facts.creates) {
+            if (created.schema)
+                continue;
+            if (RELATION_TAGS.has(facts.nodeTag)) {
+                inventory.relations.add(created.name);
+            }
+            else if (facts.nodeTag === 'CreateFunctionStmt') {
+                inventory.functions.add(created.name);
+            }
+            else if (TYPE_TAGS.has(facts.nodeTag)) {
+                inventory.types.add(created.name);
+            }
+        }
+    }
+    return inventory;
+}
+/** Merge inventories collected from multiple scripts. */
+export function mergeInventories(inventories) {
+    const merged = {
+        relations: new Set(),
+        functions: new Set(),
+        types: new Set()
+    };
+    for (const inv of inventories) {
+        for (const name of inv.relations)
+            merged.relations.add(name);
+        for (const name of inv.functions)
+            merged.functions.add(name);
+        for (const name of inv.types)
+            merged.types.add(name);
+    }
+    return merged;
+}
+/** Resolve the routing table from the option forms. */
+function resolveRoutes(sql, options) {
+    if (options.targets && options.schema) {
+        throw new Error('qualifyUnqualified: pass either `schema` or `targets`, not both');
+    }
+    const routes = {
+        relations: new Map(),
+        functions: new Map(),
+        types: new Map()
+    };
+    const route = (bucket, namespace, name, schema) => {
+        const existing = bucket.get(name);
+        if (existing && existing !== schema) {
+            throw new Error(`qualifyUnqualified: conflicting targets for ${namespace} "${name}": ${existing} vs ${schema}`);
+        }
+        bucket.set(name, schema);
+    };
+    if (options.targets) {
+        if (options.inventory) {
+            throw new Error('qualifyUnqualified: `inventory` only applies to the `schema` form');
+        }
+        for (const [schema, selector] of Object.entries(options.targets)) {
+            for (const name of selector.relations ?? [])
+                route(routes.relations, 'relation', name, schema);
+            for (const name of selector.functions ?? [])
+                route(routes.functions, 'function', name, schema);
+            for (const name of selector.types ?? [])
+                route(routes.types, 'type', name, schema);
+        }
+        return routes;
+    }
+    if (!options.schema) {
+        throw new Error('qualifyUnqualified: one of `schema` or `targets` is required');
+    }
+    const inventory = options.inventory ?? collectCreatedObjects(sql);
+    for (const name of inventory.relations)
+        routes.relations.set(name, options.schema);
+    for (const name of inventory.functions)
+        routes.functions.set(name, options.schema);
+    for (const name of inventory.types)
+        routes.types.set(name, options.schema);
+    return routes;
+}
+function collectCteNames(stmt) {
+    const names = new Set();
+    walkSql(stmt, {
+        CommonTableExpr: (path) => {
+            if (path.node?.ctename)
+                names.add(path.node.ctename);
+        }
+    });
+    return names;
+}
+/**
+ * Qualify unqualified references inside a LANGUAGE sql function body string.
+ * (`AS $$...$$` is a String under the 'as' DefElem; only PL/pgSQL bodies are
+ * exposed as a hydrated AST, so sql-language bodies need their own parse.)
+ */
+function qualifySqlBodyString(body, routes, result) {
+    const parseResult = parseSql(body);
+    const stmts = parseResult?.stmts ?? [];
+    if (stmts.length === 0)
+        return body;
+    const pieces = [];
+    for (const stmt of stmts) {
+        if (!stmt?.stmt)
+            continue;
+        const visitor = createQualifyVisitor({ routes, cteNames: collectCteNames(stmt.stmt) }, result);
+        walkSql(stmt.stmt, visitor);
+        pieces.push(Deparser.deparse(stmt.stmt));
+    }
+    return pieces.join(';\n');
+}
+function schemaStringNode(schema) {
+    return { String: { sval: schema } };
+}
+/**
+ * Create a SQL AST visitor that qualifies unqualified references against a
+ * routing table. Composable with the walkers used by the core transform.
+ */
+export function createQualifyVisitor(options, result) {
+    const { routes } = options;
+    const cteNames = options.cteNames ?? new Set();
+    const typeSchemaOf = (name) => routes.types.get(name) ?? routes.relations.get(name);
+    const record = (name, schema) => {
+        result.qualified.set(name, (result.qualified.get(name) ?? 0) + 1);
+        result.routed.set(name, schema);
+    };
+    const qualifyNameList = (names, schemaOf) => {
+        if (!names || names.length !== 1)
+            return;
+        const name = names[0]?.String?.sval;
+        if (!name)
+            return;
+        const schema = schemaOf(name);
+        if (schema) {
+            names.unshift(schemaStringNode(schema));
+            record(name, schema);
+        }
+    };
+    const functionSchemaOf = (name) => routes.functions.get(name);
+    return {
+        RangeVar: (path) => {
+            const node = path.node;
+            if (!node.schemaname && node.relname && !cteNames.has(node.relname)) {
+                const schema = routes.relations.get(node.relname);
+                if (schema) {
+                    node.schemaname = schema;
+                    record(node.relname, schema);
+                }
+            }
+        },
+        FuncCall: (path) => {
+            qualifyNameList(path.node.funcname, functionSchemaOf);
+        },
+        CallStmt: (path) => {
+            // The walker does not auto-recurse into CallStmt.funccall.
+            if (path.node.funccall) {
+                qualifyNameList(path.node.funccall.funcname, functionSchemaOf);
+            }
+        },
+        TypeName: (path) => {
+            qualifyNameList(path.node.names, typeSchemaOf);
+        },
+        CreateFunctionStmt: (path) => {
+            const node = path.node;
+            qualifyNameList(node.funcname, functionSchemaOf);
+            // LANGUAGE sql bodies are opaque strings to the walker; parse and
+            // qualify them separately (plpgsql bodies ride the hydrated AST walk).
+            const isPlpgsql = (node.options ?? []).some((opt) => opt?.DefElem?.defname === 'language' &&
+                opt.DefElem.arg?.String?.sval === 'plpgsql');
+            if (!isPlpgsql && Array.isArray(node.options)) {
+                for (const opt of node.options) {
+                    if (opt?.DefElem?.defname === 'as' && opt.DefElem.arg?.List?.items) {
+                        for (const item of opt.DefElem.arg.List.items) {
+                            if (typeof item?.String?.sval === 'string') {
+                                try {
+                                    item.String.sval = qualifySqlBodyString(item.String.sval, routes, result);
+                                }
+                                catch {
+                                    // Not parseable standalone (e.g. C symbol names) — leave as-is.
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        CreateTrigStmt: (path) => {
+            qualifyNameList(path.node.funcname, functionSchemaOf);
+        },
+        ObjectWithArgs: (path) => {
+            qualifyNameList(path.node.objname, functionSchemaOf);
+        },
+        CreateEnumStmt: (path) => {
+            qualifyNameList(path.node.typeName, name => routes.types.get(name));
+        },
+        CreateRangeStmt: (path) => {
+            qualifyNameList(path.node.typeName, name => routes.types.get(name));
+        },
+        CreateDomainStmt: (path) => {
+            qualifyNameList(path.node.domainname, name => routes.types.get(name));
+        }
+    };
+}
+/**
+ * Qualify unqualified references in a SQL string.
+ *
+ * Two forms:
+ * - `{ schema, inventory? }` — pin every inventoried name to one schema.
+ * - `{ targets }` — route specific objects to specific schemas in one pass.
+ *
+ * Runs as a standalone AST pass (parse → qualify → deparse). To combine with
+ * a schema rename, run this first (typically with `schema: 'public'`) and
+ * then map via the core transform — or use the `qualifyUnqualified` option on
+ * `transformSql`, which does exactly that.
+ */
+export function qualifyUnqualified(sql, options) {
+    const result = { qualified: new Map(), routed: new Map() };
+    const routes = resolveRoutes(sql, options);
+    let qualified = transformSync(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        for (const stmt of stmts) {
+            if (stmt?.stmt) {
+                const visitor = createQualifyVisitor({ routes, cteNames: collectCteNames(stmt.stmt) }, result);
+                walkSql(stmt.stmt, visitor);
+            }
+        }
+        const bodyVisitor = createQualifyVisitor({ routes }, result);
+        for (const fn of ctx.functions) {
+            if (fn.plpgsql?.hydrated) {
+                walkPlpgsql(fn.plpgsql.hydrated, {}, {
+                    walkSqlExpressions: true,
+                    sqlVisitor: bodyVisitor
+                });
+            }
+        }
+    }, { hydrate: true, pretty: true });
+    if (options.injectCreateSchema) {
+        const targetSchemas = new Set([
+            ...routes.relations.values(),
+            ...routes.functions.values(),
+            ...routes.types.values()
+        ]);
+        const created = new Set();
+        for (const facts of classifyStatements(qualified)) {
+            if (facts.nodeTag === 'CreateSchemaStmt') {
+                for (const createdSchema of facts.creates)
+                    created.add(createdSchema.name);
+            }
+        }
+        const missing = [...targetSchemas].filter(schema => !created.has(schema)).sort();
+        if (missing.length > 0) {
+            const prelude = missing
+                .map(schema => `CREATE SCHEMA IF NOT EXISTS ${schema};`)
+                .join('\n');
+            qualified = `${prelude}\n\n${qualified}`;
+        }
+    }
+    return { sql: qualified, result };
+}

package/esm/round-trip-core.js

@@ -0,0 +1,126 @@
+/**
+ * Shared, dependency-free core for round-trip AST validation.
+ *
+ * This module is intentionally self-contained — it imports no parser or
+ * deparser — so it can be lifted verbatim into an upstream package (e.g.
+ * `@pgsql/round-trip`) and shared between:
+ *
+ *  - pgsql-parser's test fixtures (`cleanTree` / `expectParseDeparse`), which
+ *    parse → deparse → re-parse and assert the normalized ASTs are equal, and
+ *  - downstream mutation-aware validators (this package's
+ *    round-trip check), which compare a *mutated* AST against the AST obtained
+ *    by re-parsing the deparsed output.
+ *
+ * The upstream `cleanTree` is expressed here as a preset over the generic
+ * `normalizeTree` engine; the downstream fortified normalizer layers extra
+ * volatile keys, lazy-datum filtering, and body-sentinel handling on top of
+ * the same engine (see round-trip.ts).
+ */
+/**
+ * Deep-clone an AST while dropping volatile keys, optionally sorting keys,
+ * filtering array items, and applying per-key transform hooks. Primitives are
+ * returned as-is; Dates are cloned (parity with the original upstream
+ * `transform` helper).
+ */
+export function normalizeTree(node, options = {}) {
+    const { volatileKeys, sortKeys, dropArrayItem, keyHandlers } = options;
+    const recurse = (n) => normalizeTree(n, options);
+    if (Array.isArray(node)) {
+        const items = dropArrayItem ? node.filter((i) => !dropArrayItem(i)) : node;
+        return items.map(recurse);
+    }
+    if (node instanceof Date) {
+        return new Date(node.getTime());
+    }
+    if (node && typeof node === 'object') {
+        const out = {};
+        const keys = sortKeys ? Object.keys(node).sort() : Object.keys(node);
+        for (const key of keys) {
+            if (volatileKeys?.has(key))
+                continue;
+            const handler = keyHandlers?.[key];
+            out[key] = handler ? handler(node[key], recurse) : recurse(node[key]);
+        }
+        return out;
+    }
+    return node;
+}
+/**
+ * Return the JSON path of the first structural difference between two trees,
+ * or null if they are deeply equal. Useful for actionable mismatch messages.
+ */
+export function firstDifference(a, b, path = '$') {
+    if (a === b)
+        return null;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return `${path} (array length ${a.length} vs ${b.length})`;
+        }
+        for (let i = 0; i < a.length; i++) {
+            const diff = firstDifference(a[i], b[i], `${path}[${i}]`);
+            if (diff)
+                return diff;
+        }
+        return null;
+    }
+    if (a && b && typeof a === 'object' && typeof b === 'object') {
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+        for (const key of keys) {
+            const diff = firstDifference(a[key], b[key], `${path}.${key}`);
+            if (diff)
+                return diff;
+        }
+        return null;
+    }
+    return `${path} (${JSON.stringify(a)} vs ${JSON.stringify(b)})`;
+}
+// ---------------------------------------------------------------------------
+// Upstream-compatible cleanTree preset
+// ---------------------------------------------------------------------------
+/** Position/length fields stripped by the upstream `cleanTree`. */
+export const CLEAN_TREE_VOLATILE_KEYS = new Set([
+    'stmt_len',
+    'stmt_location',
+    'location',
+    'rexpr_list_start',
+    'rexpr_list_end',
+    'list_start',
+    'list_end',
+]);
+/**
+ * Trim the function/DO body string carried by a `DefElem` with defname "as".
+ * Mirrors the in-place trimming in pgsql-parser's `cleanTree` so the body
+ * text (whose surrounding whitespace legitimately shifts on deparse) does not
+ * cause spurious AST mismatches. Mutates the passed DefElem in place.
+ */
+export function trimDefElemBody(defElem) {
+    if (!defElem || defElem.defname !== 'as')
+        return;
+    const arg = defElem.arg;
+    if (Array.isArray(arg) && arg.length && arg[0]?.String) {
+        arg[0].String.sval = arg[0].String.sval.trim();
+    }
+    else if (arg?.List?.items?.length && arg.List.items[0]?.String) {
+        arg.List.items[0].String.sval = arg.List.items[0].String.sval.trim();
+    }
+    else if (arg?.String) {
+        arg.String.sval = arg.String.sval.trim();
+    }
+}
+/**
+ * Upstream-compatible normalization: strips `stmt_len` / `stmt_location` /
+ * `location` and trims `DefElem` "as" body strings. Equivalent to
+ * pgsql-parser's deparser `cleanTree`, provided here so upstream can adopt the
+ * shared core without behavior change.
+ */
+export function cleanTree(tree) {
+    return normalizeTree(tree, {
+        volatileKeys: CLEAN_TREE_VOLATILE_KEYS,
+        keyHandlers: {
+            DefElem: (defElem, recurse) => {
+                trimDefElemBody(defElem);
+                return recurse(defElem);
+            },
+        },
+    });
+}

package/esm/round-trip.js

@@ -0,0 +1,116 @@
+/**
+ * Round-trip validation for the schema transform.
+ *
+ * After the transform deparses its mutated AST to SQL text, the emitted text
+ * must parse back to an AST that is structurally identical to the AST we
+ * deparsed (AST1 === AST2 after normalization). Any mismatch means the
+ * deparser dropped or mangled something (e.g. array bounds on a DECLAREd
+ * type), even though the output may still be syntactically valid SQL.
+ *
+ * Two comparisons are performed per file:
+ * - the SQL-level parse tree (with volatile fields and function body strings
+ *   normalized — PL/pgSQL bodies are compared separately)
+ * - each PL/pgSQL function body, compared in dehydrated form so both sides
+ *   go through the same hydrate -> dehydrate rendering
+ */
+import { dehydratePlpgsqlAst, transformSync } from 'plpgsql-parser';
+import { CLEAN_TREE_VOLATILE_KEYS, firstDifference, normalizeTree, } from './round-trip-core';
+export { firstDifference };
+/**
+ * Fields that legitimately differ between parses. Extends the upstream
+ * `cleanTree` volatile set (location/stmt_location/stmt_len) with:
+ * - lineno: source positions in PL/pgSQL nodes
+ * - dno/varno/recparentno: PL/pgSQL datum numbers — compiler bookkeeping
+ *   assigned in parse-encounter order, which shifts when the deparser
+ *   emits an equivalent-but-reordered statement (e.g. INTO placement).
+ *   Structural identity is still checked via names/fieldnames.
+ */
+const VOLATILE_KEYS = new Set([
+    ...CLEAN_TREE_VOLATILE_KEYS,
+    'lineno',
+    'dno',
+    'varno',
+    'recparentno',
+]);
+/**
+ * PLpgSQL_recfield datums are created lazily by the PL/pgSQL compiler as
+ * record.field references are encountered while parsing expressions, so
+ * their presence/order in the datums array depends on expression text
+ * layout, not semantics.
+ */
+function isRecfieldDatum(node) {
+    return !!node && typeof node === 'object' && 'PLpgSQL_recfield' in node;
+}
+/**
+ * Fortified, mutation-aware normalizer built on the shared round-trip core.
+ * Beyond the upstream `cleanTree` (position stripping + body trimming), it
+ * additionally sorts keys, drops lazily-created recfield datums, and replaces
+ * DefElem "as" bodies with a sentinel (PL/pgSQL body fidelity is checked
+ * separately via the dehydrated PL/pgSQL ASTs).
+ */
+export function normalizeParseTree(node) {
+    return normalizeTree(node, {
+        volatileKeys: VOLATILE_KEYS,
+        sortKeys: true,
+        dropArrayItem: isRecfieldDatum,
+        keyHandlers: {
+            DefElem: (defElem, recurse) => defElem?.defname === 'as'
+                ? { ...recurse(defElem), arg: '<body>' }
+                : recurse(defElem),
+        },
+    });
+}
+/**
+ * Capture the normalized SQL parse tree and dehydrated PL/pgSQL function
+ * ASTs from a transform context (as produced by plpgsql-parser's
+ * transformSync callback). Call this AFTER mutating the context.
+ */
+export function captureTransformAsts(ctx) {
+    const plpgsqlAsts = [];
+    for (const fn of ctx.functions) {
+        if (fn.plpgsql?.hydrated) {
+            plpgsqlAsts.push(normalizeParseTree(dehydratePlpgsqlAst(structuredClone(fn.plpgsql.hydrated))));
+        }
+    }
+    return {
+        sqlAst: normalizeParseTree(ctx.sql),
+        plpgsqlAsts,
+    };
+}
+/**
+ * Parse already-transformed SQL text and capture its ASTs the same way
+ * capture_transform_asts does for the pre-deparse context, so the two
+ * sides are directly comparable.
+ */
+export function captureAstsFromSql(sql) {
+    let captured;
+    transformSync(sql, (ctx) => {
+        captured = captureTransformAsts(ctx);
+    }, { hydrate: true, pretty: true });
+    if (!captured) {
+        throw new Error('round-trip: failed to capture ASTs from transformed SQL');
+    }
+    return captured;
+}
+/**
+ * Assert that the transformed AST (captured before deparse) matches the AST
+ * obtained by re-parsing the emitted SQL. Throws with the first differing
+ * path on mismatch.
+ */
+export function validateRoundTrip(before, transformedSql) {
+    const after = captureAstsFromSql(transformedSql);
+    const sqlDiff = firstDifference(before.sqlAst, after.sqlAst);
+    if (sqlDiff) {
+        throw new Error(`round-trip validation failed: SQL AST mismatch after deparse at ${sqlDiff}`);
+    }
+    if (before.plpgsqlAsts.length !== after.plpgsqlAsts.length) {
+        throw new Error(`round-trip validation failed: PL/pgSQL function count mismatch ` +
+            `(${before.plpgsqlAsts.length} before deparse vs ${after.plpgsqlAsts.length} after re-parse)`);
+    }
+    for (let i = 0; i < before.plpgsqlAsts.length; i++) {
+        const diff = firstDifference(before.plpgsqlAsts[i], after.plpgsqlAsts[i]);
+        if (diff) {
+            throw new Error(`round-trip validation failed: PL/pgSQL AST mismatch in function #${i} at ${diff}`);
+        }
+    }
+}