@pgsql/transform 18.4.1 → 18.6.0

package/extension-transform.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * AST transform that applies an {@link ExtensionRouter}.
+ *
+ * Unlike the schema transform — which only rewrites string *fields* already
+ * present on a node — moving an extension changes the **shape** of the AST:
+ *
+ * - `CREATE EXTENSION <e>` with no `SCHEMA` clause must gain one, which means
+ *   constructing a new `DefElem` node and attaching it to a (possibly absent)
+ *   `options` array; the reverse strips the `DefElem` (and empties `options`).
+ * - a bare `crypt(...)` reference gains a schema qualifier (a `String` node is
+ *   prepended to `funcname`), and the reverse removes it.
+ *
+ * All rewrites are AST-precise and driven by the router's version-aware symbol
+ * inventory, so built-ins that merely share a name with an extension symbol
+ * (and symbols that have graduated into core) are left untouched.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExtensionResult = createExtensionResult;
+exports.createExtensionVisitor = createExtensionVisitor;
+exports.transformExtensions = transformExtensions;
+const traverse_1 = require("@pgsql/traverse");
+const plpgsql_parser_1 = require("plpgsql-parser");
+const extension_router_1 = require("./extension-router");
+/** Create a fresh result tracker. */
+function createExtensionResult() {
+    return { installsMoved: new Map(), symbolsRewritten: new Map() };
+}
+function schemaStringNode(schema) {
+    return { String: { sval: schema } };
+}
+/**
+ * Rewrite a (possibly schema-qualified) name list in place against the router.
+ * `names` is the node's own array (`funcname`, `TypeName.names`, ...); it is
+ * mutated in place so the enclosing node keeps referring to it.
+ */
+function rewriteNameList(names, router, ns, result) {
+    if (!Array.isArray(names) || names.length === 0)
+        return;
+    const parts = names.map((n) => n?.String?.sval);
+    if (parts.some(p => typeof p !== 'string'))
+        return; // non-identifier element (e.g. %type)
+    const name = parts[parts.length - 1];
+    const schema = parts.length >= 2 ? parts[parts.length - 2] : null;
+    const rewrite = router.resolveSymbol(schema, name, ns);
+    if (!rewrite)
+        return;
+    if (rewrite.to === null) {
+        // Strip qualification: keep only the bare name node.
+        names.splice(0, names.length - 1);
+    }
+    else if (schema === null) {
+        // Qualify a bare reference: prepend the target schema.
+        names.unshift(schemaStringNode(rewrite.to));
+    }
+    else {
+        // Requalify: rewrite the existing schema element.
+        names[names.length - 2].String.sval = rewrite.to;
+    }
+    result.symbolsRewritten.set(name, (result.symbolsRewritten.get(name) ?? 0) + 1);
+}
+/** Read/replace the `schema` DefElem inside a `CreateExtensionStmt.options`. */
+function setExtensionSchemaOption(node, target) {
+    const options = Array.isArray(node.options) ? node.options : [];
+    const idx = options.findIndex((opt) => opt?.DefElem?.defname === 'schema');
+    if (target === null) {
+        // Install with no explicit SCHEMA clause: remove any existing option.
+        if (idx === -1)
+            return false;
+        options.splice(idx, 1);
+        if (options.length === 0)
+            delete node.options;
+        else
+            node.options = options;
+        return true;
+    }
+    const defElem = {
+        DefElem: {
+            defname: 'schema',
+            arg: { String: { sval: target } },
+            defaction: 'DEFELEM_UNSPEC'
+        }
+    };
+    if (idx === -1) {
+        options.push(defElem);
+    }
+    else {
+        const existing = options[idx].DefElem;
+        if (existing.arg?.String?.sval === target)
+            return false;
+        existing.arg = { String: { sval: target } };
+    }
+    node.options = options;
+    return true;
+}
+/**
+ * Create a SQL AST visitor that applies extension routing. Composable with the
+ * walkers used by the core transform and by PL/pgSQL body traversal.
+ */
+function createExtensionVisitor(router, result) {
+    const rewriteBody = router.hasSymbolRoutes();
+    return {
+        CreateExtensionStmt: (path) => {
+            const node = path.node;
+            const target = router.resolveInstall(node.extname);
+            if (target === undefined)
+                return;
+            if (setExtensionSchemaOption(node, target)) {
+                result.installsMoved.set(node.extname, target);
+            }
+        },
+        // ALTER EXTENSION <e> SET SCHEMA <newschema>. The walker does not recurse
+        // into AlterObjectSchemaStmt.object; a null target has no SET SCHEMA form
+        // (a schema must be named), so it is left unchanged.
+        AlterObjectSchemaStmt: (path) => {
+            const node = path.node;
+            if (node.objectType !== 'OBJECT_EXTENSION')
+                return;
+            const extname = node.object?.String?.sval;
+            const target = router.resolveInstall(extname);
+            if (typeof target !== 'string' || target === node.newschema)
+                return;
+            node.newschema = target;
+            result.installsMoved.set(extname, target);
+        },
+        FuncCall: (path) => {
+            rewriteNameList(path.node.funcname, router, 'function', result);
+        },
+        // The walker does not auto-recurse into CallStmt.funccall.
+        CallStmt: (path) => {
+            if (path.node.funccall) {
+                rewriteNameList(path.node.funccall.funcname, router, 'function', result);
+            }
+        },
+        TypeName: (path) => {
+            rewriteNameList(path.node.names, router, 'type', result);
+        },
+        CreateFunctionStmt: (path) => {
+            const node = path.node;
+            if (!rewriteBody)
+                return;
+            // LANGUAGE sql bodies are opaque strings to the walker; parse and rewrite
+            // them separately (PL/pgSQL bodies ride the hydrated walk in transformExtensions).
+            const isPlpgsql = (node.options ?? []).some((opt) => opt?.DefElem?.defname === 'language' &&
+                opt.DefElem.arg?.String?.sval === 'plpgsql');
+            if (isPlpgsql || !Array.isArray(node.options))
+                return;
+            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 = rewriteSqlBodyString(item.String.sval, router, result);
+                            }
+                            catch {
+                                // Not parseable standalone (e.g. C symbol names) — leave as-is.
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+}
+/** Rewrite extension references inside a `LANGUAGE sql` body string. */
+function rewriteSqlBodyString(body, router, result) {
+    const stmts = (0, plpgsql_parser_1.parseSql)(body)?.stmts ?? [];
+    if (stmts.length === 0)
+        return body;
+    const visitor = createExtensionVisitor(router, result);
+    const pieces = [];
+    for (const stmt of stmts) {
+        if (!stmt?.stmt)
+            continue;
+        (0, traverse_1.walk)(stmt.stmt, visitor);
+        pieces.push(plpgsql_parser_1.Deparser.deparse(stmt.stmt));
+    }
+    return pieces.join(';\n');
+}
+/**
+ * Apply extension routing to a SQL string: parse -> walk -> deparse, including
+ * PL/pgSQL and `LANGUAGE sql` bodies. Returns the rewritten SQL and a summary
+ * of what changed.
+ */
+function transformExtensions(sql, router, options = {}) {
+    const resolved = extension_router_1.ExtensionRouter.from(router, options);
+    const result = createExtensionResult();
+    const out = (0, plpgsql_parser_1.transformSync)(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        const visitor = createExtensionVisitor(resolved, result);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                (0, traverse_1.walk)(stmt.stmt, visitor);
+        }
+        if (resolved.hasSymbolRoutes()) {
+            for (const fn of ctx.functions ?? []) {
+                if (fn.plpgsql?.hydrated) {
+                    (0, plpgsql_parser_1.walk)(fn.plpgsql.hydrated, {}, {
+                        walkSqlExpressions: true,
+                        sqlVisitor: visitor
+                    });
+                }
+            }
+        }
+    }, { hydrate: true, pretty: true });
+    return { sql: out, result };
+}

package/facts.d.ts

@@ -8,7 +8,38 @@ export interface QualifiedName {
 /**
  * Coarse statement classification used for tier/package sorting.
  */
-export type StatementKind = 'schema' | 'table' | 'view' | 'index' | 'type' | 'function' | 'trigger' | 'policy' | 'grant' | 'rls_enable' | 'fk_constraint' | 'constraint' | 'comment' | 'seed_dml' | 'other';
+export type StatementKind = 'schema' | 'extension' | 'table' | 'view' | 'index' | 'type' | 'function' | 'trigger' | 'policy' | 'grant' | 'rls_enable' | 'fk_constraint' | 'constraint' | 'comment' | 'seed_dml' | 'other';
+/**
+ * The action a statement performs on a PostgreSQL extension.
+ *
+ * - `create` — `CREATE EXTENSION` (`CreateExtensionStmt`).
+ * - `set_schema` — `ALTER EXTENSION ... SET SCHEMA` (`AlterObjectSchemaStmt`
+ *   with `objectType: OBJECT_EXTENSION`); only succeeds for relocatable
+ *   extensions, so it is surfaced as its own action.
+ * - `drop` — `DROP EXTENSION` (`DropStmt` with `removeType: OBJECT_EXTENSION`).
+ */
+export type ExtensionAction = 'create' | 'set_schema' | 'drop';
+/**
+ * Facts about an extension-level statement. Unlike ordinary objects, an
+ * extension is installed into exactly one schema and its member objects are
+ * renamed with it, so the relevant fact is the extension name plus the schema
+ * it is (being) placed in.
+ */
+export interface ExtensionFact {
+    /** The extension name (`CREATE EXTENSION <name>`). */
+    name: string;
+    /**
+     * The schema the statement places the extension in, or `null` when none is
+     * specified (`CREATE EXTENSION <name>` with no `SCHEMA` clause installs into
+     * the current default — typically `public` or the extension's fixed schema).
+     * `DROP EXTENSION` carries no schema.
+     */
+    schema: string | null;
+    /** Which extension operation this statement performs. */
+    action: ExtensionAction;
+    /** `CREATE EXTENSION IF NOT EXISTS`. */
+    ifNotExists?: boolean;
+}
 /**
  * AST-derived facts about a single top-level SQL statement.
  *
@@ -42,6 +73,11 @@ export interface StatementFacts {
     referencedSchemas: string[];
     /** Role names granted to, owning, or bound by this statement. */
     roles: string[];
+    /**
+     * For extension-level statements (`kind: 'extension'`): the extension being
+     * created, relocated, or dropped. Absent for every other statement.
+     */
+    extension?: ExtensionFact;
     /** Foreign-key target tables (from column/table FK constraints). */
     fkTargets: QualifiedName[];
     /**

package/facts.js

@@ -16,6 +16,7 @@ const SECURITY_TAGS = new Set([
 ]);
 const KIND_BY_TAG = {
     CreateSchemaStmt: 'schema',
+    CreateExtensionStmt: 'extension',
     CreateStmt: 'table',
     ViewStmt: 'view',
     IndexStmt: 'index',
@@ -40,6 +41,23 @@ const KIND_BY_TAG = {
 function qn(schema, name) {
     return { schema: schema ?? null, name };
 }
+/**
+ * Read the `SCHEMA <name>` clause of a `CreateExtensionStmt` from its options
+ * (`{ DefElem: { defname: 'schema', arg: { String: { sval } } } }`), or `null`
+ * when the statement specifies no schema.
+ */
+function extensionSchemaOption(options) {
+    if (!Array.isArray(options))
+        return null;
+    for (const opt of options) {
+        const def = opt?.DefElem;
+        if (def?.defname === 'schema') {
+            const sval = def.arg?.String?.sval;
+            return typeof sval === 'string' ? sval : null;
+        }
+    }
+    return null;
+}
 function nameListToQualified(names) {
     if (!Array.isArray(names) || names.length === 0)
         return null;
@@ -145,6 +163,14 @@ function classifyOne(nodeTag, node) {
         case 'CreateSchemaStmt':
             facts.creates.push(qn(null, node.schemaname));
             break;
+        case 'CreateExtensionStmt':
+            facts.extension = {
+                name: node.extname,
+                schema: extensionSchemaOption(node.options),
+                action: 'create',
+                ifNotExists: node.if_not_exists === true
+            };
+            break;
         case 'CreateStmt':
         case 'ViewStmt': {
             const rel = nodeTag === 'ViewStmt' ? node.view : node.relation;
@@ -206,6 +232,34 @@ function classifyOne(nodeTag, node) {
                 facts.creates.push(name);
             break;
         }
+        case 'AlterObjectSchemaStmt':
+            // ALTER EXTENSION <name> SET SCHEMA <newschema>. Other object types
+            // (TABLE/TYPE/FUNCTION ... SET SCHEMA) keep their default classification.
+            if (node.objectType === 'OBJECT_EXTENSION') {
+                const name = node.object?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = {
+                        name,
+                        schema: typeof node.newschema === 'string' ? node.newschema : null,
+                        action: 'set_schema'
+                    };
+                }
+            }
+            break;
+        case 'DropStmt':
+            // DROP EXTENSION <name> [, ...]. Extension names are bare String nodes.
+            // Other DROP object types keep their default classification. When
+            // several extensions are dropped in one statement the first names the
+            // fact; the full list stays available via the raw node.
+            if (node.removeType === 'OBJECT_EXTENSION' && Array.isArray(node.objects)) {
+                const name = node.objects[0]?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = { name, schema: null, action: 'drop' };
+                }
+            }
+            break;
         case 'AlterTableStmt': {
             if (node.relation) {
                 facts.creates.push(qn(node.relation.schemaname ?? null, node.relation.relname));
@@ -244,6 +298,43 @@ function classifyOne(nodeTag, node) {
     collectRoles(node, facts.roles);
     return facts;
 }
+/** Read a `CreateFunctionStmt` DefElem option's scalar/list value. */
+function functionOption(node, defname) {
+    for (const opt of node.options ?? []) {
+        if (opt?.DefElem?.defname === defname)
+            return opt.DefElem.arg;
+    }
+    return undefined;
+}
+/**
+ * Collect references from a `LANGUAGE sql` function body supplied as a string
+ * literal (`AS $$ ... $$`). That body is an opaque String node the AST walker
+ * never parses, so — mirroring the schema transformer's body rewrite — parse
+ * it standalone and walk each statement with the facts visitor. The standard
+ * `BEGIN ATOMIC` / `RETURN` `sql_body` form is already part of the AST and is
+ * covered by the outer walk, so only the string form needs this.
+ */
+function collectSqlBodyReferences(node, facts) {
+    const language = functionOption(node, 'language')?.String?.sval;
+    if (typeof language !== 'string' || language.toLowerCase() !== 'sql')
+        return;
+    const asArg = functionOption(node, 'as');
+    const items = asArg?.List?.items ?? [];
+    const body = items[0]?.String?.sval;
+    if (typeof body !== 'string')
+        return;
+    try {
+        const stmts = (0, plpgsql_parser_1.parseSql)(body)?.stmts ?? [];
+        const visitor = createFactsVisitor(facts, facts.bodyReferences);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                (0, traverse_1.walk)(stmt.stmt, visitor);
+        }
+    }
+    catch {
+        // A non-parseable body (C symbol name, etc.) contributes no references.
+    }
+}
 /**
  * Classify each top-level statement in a SQL script into {@link StatementFacts}.
  *
@@ -263,6 +354,9 @@ function classifyStatements(sql) {
             if (stmtNode) {
                 (0, traverse_1.walk)(stmtNode, createFactsVisitor(facts));
             }
+            if (nodeTag === 'CreateFunctionStmt') {
+                collectSqlBodyReferences(node, facts);
+            }
             allFacts.push(facts);
         }
         for (const fn of ctx.functions ?? []) {

package/index.d.ts

@@ -1,5 +1,13 @@
-export type { QualifiedName, StatementFacts, StatementKind, } from './facts';
+export type { ExtensionAction, ExtensionFact, QualifiedName, StatementFacts, StatementKind, } from './facts';
 export { classifyStatements } from './facts';
+export type { ExtensionDefinition, ExtensionRoute, ExtensionRouteSpec, ExtensionRouterOptions, ExtensionSymbol, ExtensionSymbolNamespace, SymbolRewrite, } from './extension-router';
+export { COMMON_EXTENSIONS, ExtensionRouter } from './extension-router';
+export type { ExtensionTransformResult } from './extension-transform';
+export { createExtensionResult, createExtensionVisitor, transformExtensions, } from './extension-transform';
+export type { RoleRouteSpec } from './role-router';
+export { RoleRouter } from './role-router';
+export type { RoleTransformResult } from './role-transform';
+export { createRoleResult, createRoleVisitor, transformRoles, } from './role-transform';
 export type { ObjectInventory, QualifyResult, QualifyRoutes, QualifyTargetSelector, QualifyUnqualifiedOptions, } from './qualify';
 export { collectCreatedObjects, createQualifyVisitor, mergeInventories, qualifyUnqualified, } from './qualify';
 export type { ObjectNamespace, RouteNamespace, RouteSpec, SchemaRoute, } from './router';

package/index.js

@@ -1,8 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.SchemaRouter = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.classifyStatements = void 0;
+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.SchemaRouter = exports.qualifyUnqualified = exports.mergeInventories = exports.createQualifyVisitor = exports.collectCreatedObjects = exports.transformRoles = exports.createRoleVisitor = exports.createRoleResult = exports.RoleRouter = exports.transformExtensions = exports.createExtensionVisitor = exports.createExtensionResult = exports.ExtensionRouter = exports.COMMON_EXTENSIONS = exports.classifyStatements = void 0;
 var facts_1 = require("./facts");
 Object.defineProperty(exports, "classifyStatements", { enumerable: true, get: function () { return facts_1.classifyStatements; } });
+var extension_router_1 = require("./extension-router");
+Object.defineProperty(exports, "COMMON_EXTENSIONS", { enumerable: true, get: function () { return extension_router_1.COMMON_EXTENSIONS; } });
+Object.defineProperty(exports, "ExtensionRouter", { enumerable: true, get: function () { return extension_router_1.ExtensionRouter; } });
+var extension_transform_1 = require("./extension-transform");
+Object.defineProperty(exports, "createExtensionResult", { enumerable: true, get: function () { return extension_transform_1.createExtensionResult; } });
+Object.defineProperty(exports, "createExtensionVisitor", { enumerable: true, get: function () { return extension_transform_1.createExtensionVisitor; } });
+Object.defineProperty(exports, "transformExtensions", { enumerable: true, get: function () { return extension_transform_1.transformExtensions; } });
+var role_router_1 = require("./role-router");
+Object.defineProperty(exports, "RoleRouter", { enumerable: true, get: function () { return role_router_1.RoleRouter; } });
+var role_transform_1 = require("./role-transform");
+Object.defineProperty(exports, "createRoleResult", { enumerable: true, get: function () { return role_transform_1.createRoleResult; } });
+Object.defineProperty(exports, "createRoleVisitor", { enumerable: true, get: function () { return role_transform_1.createRoleVisitor; } });
+Object.defineProperty(exports, "transformRoles", { enumerable: true, get: function () { return role_transform_1.transformRoles; } });
 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; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.4.1",
+  "version": "18.6.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "AST-based SQL transformation, qualification, classification and closure analysis for PostgreSQL",
   "main": "index.js",
@@ -49,5 +49,5 @@
     "classify",
     "plpgsql"
   ],
-  "gitHead": "df667707ab725d762cac0daab26a07d1b202d1e1"
+  "gitHead": "6d3c28348fab5cace76f7c0167f3b73e8f9f67c8"
 }

package/role-router.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Role-name routing for the core transform.
+ *
+ * Two databases can express the *same* access model with *different* role
+ * names — one calls the unauthenticated role `anonymous`, another `anon`; one
+ * calls the privileged role `administrator`, another something else. Portable
+ * SQL must be able to translate role identifiers between these conventions.
+ *
+ * Scope, deliberately narrow: a {@link RoleRouter} only renames role
+ * *identifiers* in the AST positions where a role name legitimately appears
+ * (grants, ownership, policies, default privileges, role membership, role
+ * settings). It does **not** alter role *attributes* (`BYPASSRLS`, `LOGIN`,
+ * ...): two roles that share a name across conventions do not necessarily
+ * share privilege scope, and inventing attribute changes would silently
+ * misrepresent the security model. Privilege-semantics reconciliation is a
+ * downstream, policy-level concern; the router restricts itself to the
+ * deterministic, reversible part — the name.
+ *
+ * Renaming is a pure identifier substitution, so a router is trivially
+ * invertible ({@link RoleRouter.invert}) for bidirectional translation.
+ */
+/** Role-rename specification: source role name -> target role name. */
+export type RoleRouteSpec = Record<string, string>;
+/** Resolves a target role name for a source role name. */
+export declare class RoleRouter {
+    private readonly map;
+    constructor(routes?: RoleRouteSpec | Map<string, string>);
+    /** Coerce a spec, map, or existing router into a router. */
+    static from(source: RoleRouter | RoleRouteSpec | Map<string, string>): RoleRouter;
+    /** Number of configured renames. */
+    get size(): number;
+    /**
+     * Resolve the target name for `role`, or `undefined` when it is not routed
+     * or already at its destination.
+     */
+    resolve(role: string | undefined | null): string | undefined;
+    /**
+     * The inverse router (target -> source), for translating in the opposite
+     * direction. Throws if the mapping is not one-to-one.
+     */
+    invert(): RoleRouter;
+}

package/role-router.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Role-name routing for the core transform.
+ *
+ * Two databases can express the *same* access model with *different* role
+ * names — one calls the unauthenticated role `anonymous`, another `anon`; one
+ * calls the privileged role `administrator`, another something else. Portable
+ * SQL must be able to translate role identifiers between these conventions.
+ *
+ * Scope, deliberately narrow: a {@link RoleRouter} only renames role
+ * *identifiers* in the AST positions where a role name legitimately appears
+ * (grants, ownership, policies, default privileges, role membership, role
+ * settings). It does **not** alter role *attributes* (`BYPASSRLS`, `LOGIN`,
+ * ...): two roles that share a name across conventions do not necessarily
+ * share privilege scope, and inventing attribute changes would silently
+ * misrepresent the security model. Privilege-semantics reconciliation is a
+ * downstream, policy-level concern; the router restricts itself to the
+ * deterministic, reversible part — the name.
+ *
+ * Renaming is a pure identifier substitution, so a router is trivially
+ * invertible ({@link RoleRouter.invert}) for bidirectional translation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleRouter = void 0;
+/** Resolves a target role name for a source role name. */
+class RoleRouter {
+    map;
+    constructor(routes = {}) {
+        this.map = routes instanceof Map ? new Map(routes) : new Map(Object.entries(routes));
+    }
+    /** Coerce a spec, map, or existing router into a router. */
+    static from(source) {
+        return source instanceof RoleRouter ? source : new RoleRouter(source);
+    }
+    /** Number of configured renames. */
+    get size() {
+        return this.map.size;
+    }
+    /**
+     * Resolve the target name for `role`, or `undefined` when it is not routed
+     * or already at its destination.
+     */
+    resolve(role) {
+        if (!role)
+            return undefined;
+        const target = this.map.get(role);
+        if (target === undefined || target === role)
+            return undefined;
+        return target;
+    }
+    /**
+     * The inverse router (target -> source), for translating in the opposite
+     * direction. Throws if the mapping is not one-to-one.
+     */
+    invert() {
+        const inverted = new Map();
+        for (const [from, to] of this.map) {
+            if (inverted.has(to)) {
+                throw new Error(`RoleRouter.invert: mapping is not one-to-one (two sources map to "${to}")`);
+            }
+            inverted.set(to, from);
+        }
+        return new RoleRouter(inverted);
+    }
+}
+exports.RoleRouter = RoleRouter;

package/role-transform.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AST transform that applies a {@link RoleRouter}.
+ *
+ * Role identifiers surface in many statement forms. Most flow through a single
+ * `RoleSpec` node (grantees, ownership `... OWNER TO`, `CREATE POLICY ... TO`,
+ * `ALTER DEFAULT PRIVILEGES [FOR ROLE ...] ... TO`, `ALTER ROLE`, `DROP ROLE`,
+ * role-membership grantees, `GRANTED BY`, `REASSIGN OWNED BY`), which the
+ * traversal reaches automatically. Four positions carry a role name outside a
+ * `RoleSpec` and are handled explicitly:
+ *
+ * - `CREATE ROLE <name>` — a bare string on `CreateRoleStmt.role`.
+ * - `GRANT <role> TO ...` — the *granted* roles are `AccessPriv.priv_name`
+ *   strings on `GrantRoleStmt.granted_roles` (not `RoleSpec`s).
+ * - `SET ROLE` / `SET SESSION AUTHORIZATION` — the role is a string constant
+ *   in `VariableSetStmt.args`.
+ * - `ALTER ROLE <old> RENAME TO <new>` — `RenameStmt` with string
+ *   `subname`/`newname`.
+ *
+ * Reserved role specifications (`PUBLIC`, `CURRENT_USER`, `SESSION_USER`, ...)
+ * carry no `rolename` and a non-`CSTRING` `roletype`, so they are never
+ * rewritten.
+ */
+import type { RoleRouteSpec } from './role-router';
+import { RoleRouter } from './role-router';
+/** What a role transform changed: role name -> number of positions rewritten. */
+export interface RoleTransformResult {
+    rolesRenamed: Map<string, number>;
+}
+export declare function createRoleResult(): RoleTransformResult;
+/**
+ * Create a SQL AST visitor that renames role identifiers against a router.
+ * Composable with the walkers used by the core transform.
+ */
+export declare function createRoleVisitor(router: RoleRouter, result: RoleTransformResult): {
+    RoleSpec: (path: any) => void;
+    CreateRoleStmt: (path: any) => void;
+    GrantRoleStmt: (path: any) => void;
+    VariableSetStmt: (path: any) => void;
+    RenameStmt: (path: any) => void;
+};
+/**
+ * Apply role renaming to a SQL string: parse -> walk -> deparse. Role names in
+ * PL/pgSQL / `LANGUAGE sql` bodies are string literals (e.g. inside dynamic
+ * `EXECUTE`) and are intentionally not rewritten — see the module docs on why
+ * arbitrary string contents are out of scope.
+ */
+export declare function transformRoles(sql: string, router: RoleRouter | RoleRouteSpec | Map<string, string>): {
+    sql: string;
+    result: RoleTransformResult;
+};