@pgsql/transform 18.1.1 → 18.3.1

package/qualify.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+/** Named objects eligible for qualification, bucketed by namespace. */
+export interface ObjectInventory {
+    /** Tables, views, sequences — anything a RangeVar can reference. */
+    relations: Set<string>;
+    /** Function and procedure names. */
+    functions: Set<string>;
+    /** Enum/domain/range/composite type names. */
+    types: Set<string>;
+}
+/** The objects a target schema should receive, by namespace. */
+export interface QualifyTargetSelector {
+    relations?: Iterable<string>;
+    functions?: Iterable<string>;
+    types?: Iterable<string>;
+}
+export interface QualifyUnqualifiedOptions {
+    /**
+     * Single-target form: schema to pin unqualified references to (e.g.
+     * `'public'`). Mutually exclusive with `targets`.
+     */
+    schema?: string;
+    /**
+     * Names eligible for qualification (single-target form only). Defaults to
+     * the objects created by the content itself ({@link collectCreatedObjects}).
+     * When qualifying scripts that reference objects created elsewhere (e.g.
+     * the scripts of a whole module), collect the inventory across all scripts
+     * and pass it here.
+     */
+    inventory?: ObjectInventory;
+    /**
+     * Multi-target form: route specific objects to specific schemas in one
+     * pass. Mutually exclusive with `schema`/`inventory`.
+     *
+     * ```ts
+     * qualifyUnqualified(sql, {
+     *   targets: {
+     *     auth:   { relations: ['users'] },
+     *     shop:   { relations: ['products'], functions: ['get_products'] },
+     *     shared: { types: ['widget'] }
+     *   }
+     * });
+     * ```
+     *
+     * Routing a name to two schemas in the same namespace is a conflict and
+     * throws.
+     */
+    targets?: Record<string, QualifyTargetSelector>;
+    /**
+     * Prepend `CREATE SCHEMA IF NOT EXISTS <schema>;` for every target schema
+     * the content does not already create. Useful when ingesting standalone
+     * handwritten SQL whose target schemas may not exist.
+     */
+    injectCreateSchema?: boolean;
+}
+export interface QualifyResult {
+    /** Count of references qualified, keyed by object name. */
+    qualified: Map<string, number>;
+    /** Schema each qualified object was routed to. */
+    routed: Map<string, string>;
+}
+/** Resolved name → schema routing, by namespace. */
+export interface QualifyRoutes {
+    relations: Map<string, string>;
+    functions: Map<string, string>;
+    types: Map<string, string>;
+}
+/**
+ * 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 declare function collectCreatedObjects(sql: string): ObjectInventory;
+/** Merge inventories collected from multiple scripts. */
+export declare function mergeInventories(inventories: ObjectInventory[]): ObjectInventory;
+/**
+ * Create a SQL AST visitor that qualifies unqualified references against a
+ * routing table. Composable with the walkers used by the core transform.
+ */
+export declare function createQualifyVisitor(options: {
+    routes: QualifyRoutes;
+    cteNames?: Set<string>;
+}, result: QualifyResult): {
+    RangeVar: (path: any) => void;
+    FuncCall: (path: any) => void;
+    CallStmt: (path: any) => void;
+    TypeName: (path: any) => void;
+    CreateFunctionStmt: (path: any) => void;
+    CreateTrigStmt: (path: any) => void;
+    ObjectWithArgs: (path: any) => void;
+    CreateEnumStmt: (path: any) => void;
+    CreateRangeStmt: (path: any) => void;
+    CreateDomainStmt: (path: any) => void;
+};
+/**
+ * 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 declare function qualifyUnqualified(sql: string, options: QualifyUnqualifiedOptions): {
+    sql: string;
+    result: QualifyResult;
+};

package/qualify.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectCreatedObjects = collectCreatedObjects;
+exports.mergeInventories = mergeInventories;
+exports.createQualifyVisitor = createQualifyVisitor;
+exports.qualifyUnqualified = qualifyUnqualified;
+const traverse_1 = require("@pgsql/traverse");
+const plpgsql_parser_1 = require("plpgsql-parser");
+const facts_1 = require("./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.
+ */
+function collectCreatedObjects(sql) {
+    const inventory = {
+        relations: new Set(),
+        functions: new Set(),
+        types: new Set()
+    };
+    for (const facts of (0, facts_1.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. */
+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();
+    (0, traverse_1.walk)(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 = (0, plpgsql_parser_1.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);
+        (0, traverse_1.walk)(stmt.stmt, visitor);
+        pieces.push(plpgsql_parser_1.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.
+ */
+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.
+ */
+function qualifyUnqualified(sql, options) {
+    const result = { qualified: new Map(), routed: new Map() };
+    const routes = resolveRoutes(sql, options);
+    let qualified = (0, plpgsql_parser_1.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);
+                (0, traverse_1.walk)(stmt.stmt, visitor);
+            }
+        }
+        const bodyVisitor = createQualifyVisitor({ routes }, result);
+        for (const fn of ctx.functions) {
+            if (fn.plpgsql?.hydrated) {
+                (0, plpgsql_parser_1.walk)(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 (0, facts_1.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/round-trip-core.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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).
+ */
+export interface NormalizeTreeOptions {
+    /** Object keys dropped entirely (volatile / non-semantic fields). */
+    volatileKeys?: ReadonlySet<string>;
+    /** Sort object keys so comparison is insensitive to key order. Default false. */
+    sortKeys?: boolean;
+    /** Array items for which this returns true are removed before recursing. */
+    dropArrayItem?: (item: unknown) => boolean;
+    /**
+     * Per-key transform hooks keyed by object-property name. The hook receives
+     * the value at that key plus a `recurse` callback (which re-enters
+     * `normalizeTree` with the same options) and returns the replacement value.
+     */
+    keyHandlers?: Record<string, (value: any, recurse: (node: any) => any) => any>;
+}
+/**
+ * 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 declare function normalizeTree(node: any, options?: NormalizeTreeOptions): any;
+/**
+ * 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 declare function firstDifference(a: any, b: any, path?: string): string | null;
+/** Position/length fields stripped by the upstream `cleanTree`. */
+export declare const CLEAN_TREE_VOLATILE_KEYS: ReadonlySet<string>;
+/**
+ * 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 declare function trimDefElemBody(defElem: any): void;
+/**
+ * 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 declare function cleanTree(tree: any): any;

package/round-trip-core.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLEAN_TREE_VOLATILE_KEYS = void 0;
+exports.normalizeTree = normalizeTree;
+exports.firstDifference = firstDifference;
+exports.trimDefElemBody = trimDefElemBody;
+exports.cleanTree = cleanTree;
+/**
+ * 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).
+ */
+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.
+ */
+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`. */
+exports.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.
+ */
+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.
+ */
+function cleanTree(tree) {
+    return normalizeTree(tree, {
+        volatileKeys: exports.CLEAN_TREE_VOLATILE_KEYS,
+        keyHandlers: {
+            DefElem: (defElem, recurse) => {
+                trimDefElemBody(defElem);
+                return recurse(defElem);
+            },
+        },
+    });
+}

package/round-trip.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { firstDifference } from './round-trip-core';
+export { firstDifference };
+/**
+ * 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 declare function normalizeParseTree(node: any): any;
+export interface CapturedAsts {
+    sqlAst: any;
+    plpgsqlAsts: any[];
+}
+/**
+ * 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 declare function captureTransformAsts(ctx: any): CapturedAsts;
+/**
+ * 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 declare function captureAstsFromSql(sql: string): CapturedAsts;
+/**
+ * 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 declare function validateRoundTrip(before: CapturedAsts, transformedSql: string): void;