@pgsql/transform 18.1.0 → 18.3.0

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;

package/round-trip.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstDifference = void 0;
+exports.normalizeParseTree = normalizeParseTree;
+exports.captureTransformAsts = captureTransformAsts;
+exports.captureAstsFromSql = captureAstsFromSql;
+exports.validateRoundTrip = validateRoundTrip;
+const plpgsql_parser_1 = require("plpgsql-parser");
+const round_trip_core_1 = require("./round-trip-core");
+Object.defineProperty(exports, "firstDifference", { enumerable: true, get: function () { return round_trip_core_1.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([
+    ...round_trip_core_1.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).
+ */
+function normalizeParseTree(node) {
+    return (0, round_trip_core_1.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.
+ */
+function captureTransformAsts(ctx) {
+    const plpgsqlAsts = [];
+    for (const fn of ctx.functions) {
+        if (fn.plpgsql?.hydrated) {
+            plpgsqlAsts.push(normalizeParseTree((0, plpgsql_parser_1.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.
+ */
+function captureAstsFromSql(sql) {
+    let captured;
+    (0, plpgsql_parser_1.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.
+ */
+function validateRoundTrip(before, transformedSql) {
+    const after = captureAstsFromSql(transformedSql);
+    const sqlDiff = (0, round_trip_core_1.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 = (0, round_trip_core_1.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}`);
+        }
+    }
+}

package/transform.d.ts

@@ -0,0 +1,259 @@
+/**
+ * AST-based Schema Name Transformer (Core Logic)
+ *
+ * Pure transformation functions for converting schema names in SQL strings.
+ * No file I/O — takes SQL strings in and returns transformed SQL strings out.
+ *
+ * The transformer handles:
+ * - Schema-qualified identifiers in RangeVar nodes (schema.table)
+ * - Schema names in CreateSchemaStmt nodes
+ * - Schema-qualified function names in FuncCall and CreateFunctionStmt nodes
+ * - Schema-qualified type names in TypeName nodes
+ * - Schema names in GrantStmt objects array
+ * - Schema names in VariableSetStmt (SET search_path)
+ * - Schema names in AlterDefaultPrivilegesStmt
+ * - Schema names in DropStmt (DROP SCHEMA)
+ * - Schema-qualified trigger function names in CreateTrigStmt
+ * - Schema-qualified object references in CommentStmt
+ * - Schema-qualified names in DefineStmt (CREATE TYPE, CREATE AGGREGATE)
+ * - Schema-qualified names in CreateDomainStmt, CreateEnumStmt, AlterEnumStmt
+ * - Schema-qualified names in AlterDomainStmt, AlterTypeStmt
+ * - Schema-qualified names in ObjectWithArgs (ALTER FUNCTION, etc.)
+ * - Schema name in AlterObjectSchemaStmt (ALTER ... SET SCHEMA)
+ * - Schema names inside PL/pgSQL function bodies (hydrated AST)
+ * - Comment headers, verify function calls, JSON string values (regex fallback)
+ */
+import type { QualifyUnqualifiedOptions } from './qualify';
+export interface SchemaTransformResult {
+    schemasFound: Set<string>;
+    schemasTransformed: Map<string, string>;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * A pluggable string-level transform pass.
+ *
+ * Extension passes run on the raw SQL text before or after the core AST
+ * transformation.  They exist for content that is opaque to the SQL parser
+ * (string literals, comments, JSON values, etc.).
+ *
+ * Each pass receives the current content string, the schema mapping, and the
+ * shared result tracker, and must return the (possibly transformed) content.
+ */
+export type SchemaTransformPass = (content: string, schemaMapping: Map<string, string>, result: SchemaTransformResult) => string;
+/**
+ * Options for transform_sql.
+ */
+export interface TransformSqlOptions {
+    /**
+     * Extension passes that run BEFORE the core AST transformation.
+     * Use these for app-specific string-level transforms that must happen
+     * before the parser sees the content (e.g. verify calls, JSON values).
+     */
+    prePasses?: SchemaTransformPass[];
+    /**
+     * Extension passes that run AFTER the core AST transformation.
+     * Use these for app-specific transforms on the deparsed output.
+     */
+    postPasses?: SchemaTransformPass[];
+    /**
+     * Validate that the emitted SQL re-parses to an AST structurally identical
+     * to the transformed AST that was deparsed (catches deparser fidelity bugs
+     * such as dropped array bounds). Adds a second parse per file.
+     */
+    roundTrip?: boolean;
+    /**
+     * Qualify unqualified object references BEFORE the schema mapping runs
+     * (an extra AST pass, opt-in). Pin unqualified references to a schema
+     * (typically `'public'`) so a mapping on that schema moves them too —
+     * the ingestion path for handwritten, unqualified SQL. Only names in the
+     * inventory (defaulting to objects the content itself creates) are
+     * qualified. See {@link qualifyUnqualified}.
+     */
+    qualifyUnqualified?: QualifyUnqualifiedOptions;
+    /**
+     * Schema names (post-mapping) whose `CREATE SCHEMA` statements should be
+     * emitted as `CREATE SCHEMA IF NOT EXISTS`. Use when mapping into a schema
+     * that always exists — e.g. mapping a named schema onto `public`.
+     */
+    assumeSchemasExist?: string[];
+}
+/**
+ * Transform a schema name if it exists in the mapping
+ */
+export declare function transformSchemaName(schemaName: string | undefined, schemaMapping: Map<string, string>): string | undefined;
+/**
+ * Check if a schema name should be transformed
+ */
+export declare function shouldTransformSchema(schemaName: string | undefined, schemaMapping: Map<string, string>): boolean;
+/**
+ * Transform schema names in a String node array (used for funcname, names, etc.)
+ * These arrays contain String nodes like { String: { sval: 'schema_name' } }
+ */
+export declare function transformNameList(names: any[] | undefined, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+/**
+ * Transform a bare schema-name field on a node (e.g. { String: { sval } }
+ * entries in GrantStmt.objects, RenameStmt.subname, CommentStmt.object).
+ * Returns the (possibly new) schema name.
+ */
+export declare function transformSchemaNameField(container: any, field: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+/**
+ * Transform a RangeVar-like relation object (has schemaname/relname fields).
+ * Many statement nodes embed a relation that the walker does NOT auto-recurse into.
+ */
+export declare function transformRelation(relation: any, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+/**
+ * Transform schema-qualified references embedded in a plain string
+ * (e.g. advisory-lock keys like 'schema-name.fn_name', COMMENT text,
+ * RAISE messages). Only occurrences of a mapped schema name immediately
+ * followed by a dot are rewritten.
+ */
+export declare function transformSchemaRefsInString(str: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+/**
+ * Create a SQL AST visitor that transforms schema names.
+ *
+ * The walker from @pgsql/traverse auto-recurses into child nodes, so visitors
+ * like RangeVar and TypeName fire for every occurrence regardless of parent.
+ * However, some node types carry schema names as plain strings or name lists
+ * that require explicit handlers.
+ */
+export declare function createSqlVisitor(schemaMapping: Map<string, string>, result: SchemaTransformResult, visitorOptions?: {
+    assumeSchemasExist?: Set<string>;
+}): {
+    RangeVar: (path: any) => void;
+    CreateSchemaStmt: (path: any) => void;
+    FuncCall: (path: any) => void;
+    CallStmt: (path: any) => void;
+    TypeName: (path: any) => void;
+    ColumnRef: (path: any) => void;
+    GrantStmt: (path: any) => void;
+    VariableSetStmt: (path: any) => void;
+    AlterDefaultPrivilegesStmt: (path: any) => void;
+    DropStmt: (path: any) => void;
+    InsertStmt: (path: any) => void;
+    CreateStmt: (path: any) => void;
+    UpdateStmt: (path: any) => void;
+    DeleteStmt: (path: any) => void;
+    MergeStmt: (path: any) => void;
+    IndexStmt: (path: any) => void;
+    Constraint: (path: any) => void;
+    CompositeTypeStmt: (path: any) => void;
+    ColumnDef: (path: any) => void;
+    ViewStmt: (path: any) => void;
+    AlterTableStmt: (path: any) => void;
+    CreateSeqStmt: (path: any) => void;
+    AlterSeqStmt: (path: any) => void;
+    CreatePolicyStmt: (path: any) => void;
+    RuleStmt: (path: any) => void;
+    CopyStmt: (path: any) => void;
+    ClusterStmt: (path: any) => void;
+    VacuumRelation: (path: any) => void;
+    RefreshMatViewStmt: (path: any) => void;
+    CreateTableAsStmt: (path: any) => void;
+    TypeCast: (path: any) => void;
+    CreateFunctionStmt: (path: any) => void;
+    CreateTrigStmt: (path: any) => void;
+    CommentStmt: (path: any) => void;
+    A_Const: (path: any) => void;
+    DefineStmt: (path: any) => void;
+    CreateDomainStmt: (path: any) => void;
+    CreateEnumStmt: (path: any) => void;
+    AlterEnumStmt: (path: any) => void;
+    AlterDomainStmt: (path: any) => void;
+    AlterTypeStmt: (path: any) => void;
+    ObjectWithArgs: (path: any) => void;
+    AlterObjectSchemaStmt: (path: any) => void;
+    RenameStmt: (path: any) => void;
+    AlterFunctionStmt: (path: any) => void;
+    AlterOwnerStmt: (path: any) => void;
+    CreateCastStmt: (path: any) => void;
+    CreateEventTrigStmt: (path: any) => void;
+    IndexElem: (path: any) => void;
+    SecLabelStmt: (path: any) => void;
+    DoStmt: (path: any) => void;
+};
+/**
+ * Validate that no untransformed schema names remain in the output.
+ * Checks both schema-qualified references (schema.object) and standalone
+ * schema name contexts (ON SCHEMA, IN SCHEMA, CREATE SCHEMA, etc.).
+ *
+ * Throws an error if any schema names from the mapping are found in the output,
+ * indicating that the AST visitor is missing a handler for that node type.
+ */
+export declare function validateNoUntransformedSchemas(content: string, schemaMapping: Map<string, string>): void;
+/**
+ * Create a PL/pgSQL visitor that transforms schema names in PL/pgSQL-specific nodes.
+ */
+export declare function createPlpgsqlVisitor(schemaMapping: Map<string, string>, result: SchemaTransformResult): {
+    PLpgSQL_type: (path: any) => void;
+    PLpgSQL_var: (path: any) => void;
+};
+/**
+ * Transform a PLpgSQL_type typname using proper AST parsing.
+ */
+export declare function transformPlpgsqlTypeAst(typname: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+/**
+ * Fallback string-based transformation for PLpgSQL_type typname.
+ * Uses @pgsql/quotes QuoteUtils for proper identifier quoting.
+ */
+export declare function transformPlpgsqlTypeString(typname: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+/**
+ * Recursively walk the PL/pgSQL AST to transform schema names.
+ */
+export declare function walkPlpgsqlForSchemas(node: any, schemaMapping: Map<string, string>, result: SchemaTransformResult): void;
+/**
+ * Escape a string for use in a regular expression
+ */
+export declare function escapeRegexp(str: string): string;
+/**
+ * Extract pgpm header comments from the beginning of SQL content.
+ */
+export declare function extractPgpmHeader(content: string): {
+    header: string;
+    body: string;
+};
+/**
+ * Transform comment headers (-- Deploy:, -- requires:, etc.)
+ * These are not part of the SQL AST, so we use regexp for these.
+ */
+export declare function transformComments(content: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+/**
+ * Transform verify function calls that use string literals.
+ * These are inside SQL strings and not part of the main AST.
+ */
+export declare function transformVerifyCalls(content: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+/**
+ * Transform schema names inside JSON/JSONB string values.
+ */
+export declare function transformJsonStringValues(content: string, schemaMapping: Map<string, string>, result: SchemaTransformResult): string;
+/**
+ * Transform a single SQL string using full AST-based transformation.
+ *
+ * This is the main entry point for transforming SQL content. It:
+ * 1. Runs any user-supplied pre-passes (string-level)
+ * 2. Extracts pgpm header comments and transforms them
+ * 3. Runs full AST transformation on the SQL body
+ * 4. Runs any user-supplied post-passes (string-level)
+ * 5. Validates no untransformed schema names remain
+ * 6. Returns the combined result
+ *
+ * App-specific string-level transforms (verify calls, JSON values, etc.)
+ * are NOT included by default — pass them via `options.pre_passes` or
+ * `options.post_passes`.  The built-in passes `transform_verify_calls`
+ * and `transform_json_string_values` are exported for convenience.
+ */
+export declare function transformSql(content: string, schemaMapping: Map<string, string>, options?: TransformSqlOptions | SchemaTransformResult, result?: SchemaTransformResult): {
+    content: string;
+    result: SchemaTransformResult;
+};
+/**
+ * Transform a single SQL statement string using AST.
+ * Unlike transform_sql, this does NOT handle headers, verify calls, or JSON values.
+ * Use this for testing individual SQL statements.
+ */
+export declare function transformSqlStatement(sql: string, schemaMapping: Map<string, string>, result?: SchemaTransformResult): {
+    sql: string;
+    result: SchemaTransformResult;
+};