@pgsql/transform 18.1.1 → 18.3.0

package/index.js

@@ -1,78 +1,45 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PG18Types = exports.PG17Types = exports.PG16Types = exports.PG15Types = exports.PG14Types = exports.PG13Types = exports.PG17ToPG18Transformer = exports.PG16ToPG18Transformer = exports.PG15ToPG18Transformer = exports.PG14ToPG18Transformer = exports.PG13ToPG18Transformer = exports.PG16ToPG17Transformer = exports.PG15ToPG17Transformer = exports.PG14ToPG17Transformer = exports.PG13ToPG17Transformer = exports.V17ToV18Transformer = exports.V16ToV17Transformer = exports.V15ToV16Transformer = exports.V14ToV15Transformer = exports.V13ToV14Transformer = exports.ASTTransformer = void 0;
-const PG13Types = __importStar(require("./13/types"));
-exports.PG13Types = PG13Types;
-const PG14Types = __importStar(require("./14/types"));
-exports.PG14Types = PG14Types;
-const PG15Types = __importStar(require("./15/types"));
-exports.PG15Types = PG15Types;
-const PG16Types = __importStar(require("./16/types"));
-exports.PG16Types = PG16Types;
-const PG17Types = __importStar(require("./17/types"));
-exports.PG17Types = PG17Types;
-const PG18Types = __importStar(require("./18/types"));
-exports.PG18Types = PG18Types;
-var multi_version_transformer_1 = require("./multi-version-transformer");
-Object.defineProperty(exports, "ASTTransformer", { enumerable: true, get: function () { return multi_version_transformer_1.ASTTransformer; } });
-var v13_to_v14_1 = require("./transformers/v13-to-v14");
-Object.defineProperty(exports, "V13ToV14Transformer", { enumerable: true, get: function () { return v13_to_v14_1.V13ToV14Transformer; } });
-var v14_to_v15_1 = require("./transformers/v14-to-v15");
-Object.defineProperty(exports, "V14ToV15Transformer", { enumerable: true, get: function () { return v14_to_v15_1.V14ToV15Transformer; } });
-var v15_to_v16_1 = require("./transformers/v15-to-v16");
-Object.defineProperty(exports, "V15ToV16Transformer", { enumerable: true, get: function () { return v15_to_v16_1.V15ToV16Transformer; } });
-var v16_to_v17_1 = require("./transformers/v16-to-v17");
-Object.defineProperty(exports, "V16ToV17Transformer", { enumerable: true, get: function () { return v16_to_v17_1.V16ToV17Transformer; } });
-var v17_to_v18_1 = require("./transformers/v17-to-v18");
-Object.defineProperty(exports, "V17ToV18Transformer", { enumerable: true, get: function () { return v17_to_v18_1.V17ToV18Transformer; } });
-var v13_to_v17_1 = require("./transformers-direct/v13-to-v17");
-Object.defineProperty(exports, "PG13ToPG17Transformer", { enumerable: true, get: function () { return v13_to_v17_1.PG13ToPG17Transformer; } });
-var v14_to_v17_1 = require("./transformers-direct/v14-to-v17");
-Object.defineProperty(exports, "PG14ToPG17Transformer", { enumerable: true, get: function () { return v14_to_v17_1.PG14ToPG17Transformer; } });
-var v15_to_v17_1 = require("./transformers-direct/v15-to-v17");
-Object.defineProperty(exports, "PG15ToPG17Transformer", { enumerable: true, get: function () { return v15_to_v17_1.PG15ToPG17Transformer; } });
-var v16_to_v17_2 = require("./transformers-direct/v16-to-v17");
-Object.defineProperty(exports, "PG16ToPG17Transformer", { enumerable: true, get: function () { return v16_to_v17_2.PG16ToPG17Transformer; } });
-var v13_to_v18_1 = require("./transformers-direct/v13-to-v18");
-Object.defineProperty(exports, "PG13ToPG18Transformer", { enumerable: true, get: function () { return v13_to_v18_1.PG13ToPG18Transformer; } });
-var v14_to_v18_1 = require("./transformers-direct/v14-to-v18");
-Object.defineProperty(exports, "PG14ToPG18Transformer", { enumerable: true, get: function () { return v14_to_v18_1.PG14ToPG18Transformer; } });
-var v15_to_v18_1 = require("./transformers-direct/v15-to-v18");
-Object.defineProperty(exports, "PG15ToPG18Transformer", { enumerable: true, get: function () { return v15_to_v18_1.PG15ToPG18Transformer; } });
-var v16_to_v18_1 = require("./transformers-direct/v16-to-v18");
-Object.defineProperty(exports, "PG16ToPG18Transformer", { enumerable: true, get: function () { return v16_to_v18_1.PG16ToPG18Transformer; } });
-var v17_to_v18_2 = require("./transformers-direct/v17-to-v18");
-Object.defineProperty(exports, "PG17ToPG18Transformer", { enumerable: true, get: function () { return v17_to_v18_2.PG17ToPG18Transformer; } });
+exports.walkPlpgsqlForSchemas = exports.validateNoUntransformedSchemas = exports.transformVerifyCalls = exports.transformSqlStatement = exports.transformSql = exports.transformSchemaName = exports.transformRelation = exports.transformPlpgsqlTypeString = exports.transformPlpgsqlTypeAst = exports.transformNameList = exports.transformJsonStringValues = exports.transformComments = exports.shouldTransformSchema = exports.extractPgpmHeader = exports.escapeRegexp = exports.createSqlVisitor = exports.createPlpgsqlVisitor = exports.trimDefElemBody = exports.normalizeTree = exports.cleanTree = exports.CLEAN_TREE_VOLATILE_KEYS = exports.validateRoundTrip = exports.normalizeParseTree = exports.firstDifference = exports.captureTransformAsts = exports.captureAstsFromSql = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.resolveFixtureClosure = exports.classifyStatements = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = void 0;
+var categorize_1 = require("./categorize");
+Object.defineProperty(exports, "buildCategoryOf", { enumerable: true, get: function () { return categorize_1.buildCategoryOf; } });
+Object.defineProperty(exports, "categorizeChange", { enumerable: true, get: function () { return categorize_1.categorizeChange; } });
+Object.defineProperty(exports, "TIER_PROFILE", { enumerable: true, get: function () { return categorize_1.TIER_PROFILE; } });
+var facts_1 = require("./facts");
+Object.defineProperty(exports, "classifyStatements", { enumerable: true, get: function () { return facts_1.classifyStatements; } });
+var fixture_closure_1 = require("./fixture-closure");
+Object.defineProperty(exports, "resolveFixtureClosure", { enumerable: true, get: function () { return fixture_closure_1.resolveFixtureClosure; } });
+var qualify_1 = require("./qualify");
+Object.defineProperty(exports, "collectCreatedObjects", { enumerable: true, get: function () { return qualify_1.collectCreatedObjects; } });
+Object.defineProperty(exports, "createQualifyVisitor", { enumerable: true, get: function () { return qualify_1.createQualifyVisitor; } });
+Object.defineProperty(exports, "mergeInventories", { enumerable: true, get: function () { return qualify_1.mergeInventories; } });
+Object.defineProperty(exports, "qualifyUnqualified", { enumerable: true, get: function () { return qualify_1.qualifyUnqualified; } });
+var round_trip_1 = require("./round-trip");
+Object.defineProperty(exports, "captureAstsFromSql", { enumerable: true, get: function () { return round_trip_1.captureAstsFromSql; } });
+Object.defineProperty(exports, "captureTransformAsts", { enumerable: true, get: function () { return round_trip_1.captureTransformAsts; } });
+Object.defineProperty(exports, "firstDifference", { enumerable: true, get: function () { return round_trip_1.firstDifference; } });
+Object.defineProperty(exports, "normalizeParseTree", { enumerable: true, get: function () { return round_trip_1.normalizeParseTree; } });
+Object.defineProperty(exports, "validateRoundTrip", { enumerable: true, get: function () { return round_trip_1.validateRoundTrip; } });
+var round_trip_core_1 = require("./round-trip-core");
+Object.defineProperty(exports, "CLEAN_TREE_VOLATILE_KEYS", { enumerable: true, get: function () { return round_trip_core_1.CLEAN_TREE_VOLATILE_KEYS; } });
+Object.defineProperty(exports, "cleanTree", { enumerable: true, get: function () { return round_trip_core_1.cleanTree; } });
+Object.defineProperty(exports, "normalizeTree", { enumerable: true, get: function () { return round_trip_core_1.normalizeTree; } });
+Object.defineProperty(exports, "trimDefElemBody", { enumerable: true, get: function () { return round_trip_core_1.trimDefElemBody; } });
+var transform_1 = require("./transform");
+Object.defineProperty(exports, "createPlpgsqlVisitor", { enumerable: true, get: function () { return transform_1.createPlpgsqlVisitor; } });
+Object.defineProperty(exports, "createSqlVisitor", { enumerable: true, get: function () { return transform_1.createSqlVisitor; } });
+Object.defineProperty(exports, "escapeRegexp", { enumerable: true, get: function () { return transform_1.escapeRegexp; } });
+Object.defineProperty(exports, "extractPgpmHeader", { enumerable: true, get: function () { return transform_1.extractPgpmHeader; } });
+Object.defineProperty(exports, "shouldTransformSchema", { enumerable: true, get: function () { return transform_1.shouldTransformSchema; } });
+Object.defineProperty(exports, "transformComments", { enumerable: true, get: function () { return transform_1.transformComments; } });
+Object.defineProperty(exports, "transformJsonStringValues", { enumerable: true, get: function () { return transform_1.transformJsonStringValues; } });
+Object.defineProperty(exports, "transformNameList", { enumerable: true, get: function () { return transform_1.transformNameList; } });
+Object.defineProperty(exports, "transformPlpgsqlTypeAst", { enumerable: true, get: function () { return transform_1.transformPlpgsqlTypeAst; } });
+Object.defineProperty(exports, "transformPlpgsqlTypeString", { enumerable: true, get: function () { return transform_1.transformPlpgsqlTypeString; } });
+Object.defineProperty(exports, "transformRelation", { enumerable: true, get: function () { return transform_1.transformRelation; } });
+Object.defineProperty(exports, "transformSchemaName", { enumerable: true, get: function () { return transform_1.transformSchemaName; } });
+Object.defineProperty(exports, "transformSql", { enumerable: true, get: function () { return transform_1.transformSql; } });
+Object.defineProperty(exports, "transformSqlStatement", { enumerable: true, get: function () { return transform_1.transformSqlStatement; } });
+Object.defineProperty(exports, "transformVerifyCalls", { enumerable: true, get: function () { return transform_1.transformVerifyCalls; } });
+Object.defineProperty(exports, "validateNoUntransformedSchemas", { enumerable: true, get: function () { return transform_1.validateNoUntransformedSchemas; } });
+Object.defineProperty(exports, "walkPlpgsqlForSchemas", { enumerable: true, get: function () { return transform_1.walkPlpgsqlForSchemas; } });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.1.1",
+  "version": "18.3.0",
   "author": "Constructive <developers@constructive.io>",
-  "description": "Transform PostgreSQL AST types for pgsql-parser",
+  "description": "AST-based SQL transformation, qualification, classification and closure analysis for PostgreSQL",
   "main": "index.js",
   "module": "esm/index.js",
   "types": "index.d.ts",
@@ -23,23 +23,31 @@
     "copy": "makage assets",
     "clean": "makage clean dist",
     "prepublishOnly": "npm run build",
-    "build": "npm run build:proto && npm run clean && tsc && tsc -p tsconfig.esm.json && npm run copy",
+    "build": "npm run clean && tsc && tsc -p tsconfig.esm.json && npm run copy",
     "build:dev": "npm run clean && tsc --declarationMap && tsc -p tsconfig.esm.json && npm run copy",
-    "build:proto": "ts-node scripts/pg-proto-parser",
     "lint": "eslint . --fix",
     "test": "jest",
     "test:watch": "jest --watch",
-    "kitchen-sink": "ts-node scripts/make-kitchen-sink.ts",
-    "test:ast": "ts-node scripts/test-ast.ts"
+    "fixtures": "ts-node scripts/make-fixtures.ts",
+    "scan-corpus": "node scripts/scan-corpus.js"
+  },
+  "dependencies": {
+    "@pgsql/quotes": "18.1.0",
+    "@pgsql/traverse": "18.3.0",
+    "plpgsql-parser": "18.2.1"
   },
   "devDependencies": {
-    "@pgsql/parser": "^1.2.1",
-    "@pgsql/types": "^18.0.0",
-    "libpg-query": "18.1.2",
-    "makage": "^0.1.8",
-    "pg-proto-parser": "1.31.0",
-    "pgsql-deparser": "18.1.1"
+    "makage": "^0.1.8"
   },
-  "keywords": [],
-  "gitHead": "d57254a6bae519c2ce7c54f88dff44105124a821"
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pg",
+    "ast",
+    "transform",
+    "classify",
+    "plpgsql"
+  ],
+  "gitHead": "b59056454e08e3b7f71019c988150af2019ceda6"
 }

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