@pgsql/transform 18.1.1 → 18.3.1

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;
+};