@pgsql/transform 18.5.0 → 18.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/transform",
-  "version": "18.5.0",
+  "version": "18.7.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": "a2b52f04fca42931150378d5b4966b7d5a922de6"
+  "gitHead": "057e427849438bfea946d6d85557603ba7fea134"
 }

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

package/role-transform.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRoleResult = createRoleResult;
+exports.createRoleVisitor = createRoleVisitor;
+exports.transformRoles = transformRoles;
+const traverse_1 = require("@pgsql/traverse");
+const plpgsql_parser_1 = require("plpgsql-parser");
+const role_router_1 = require("./role-router");
+function createRoleResult() {
+    return { rolesRenamed: new Map() };
+}
+const ROLE_SET_PARAMS = new Set(['role', 'session_authorization']);
+/**
+ * Create a SQL AST visitor that renames role identifiers against a router.
+ * Composable with the walkers used by the core transform.
+ */
+function createRoleVisitor(router, result) {
+    const record = (name) => {
+        result.rolesRenamed.set(name, (result.rolesRenamed.get(name) ?? 0) + 1);
+    };
+    return {
+        RoleSpec: (path) => {
+            const node = path.node;
+            // Only named roles (ROLESPEC_CSTRING) carry a rolename; PUBLIC /
+            // CURRENT_USER / SESSION_USER are encoded by roletype and left alone.
+            if (node.roletype !== 'ROLESPEC_CSTRING')
+                return;
+            const target = router.resolve(node.rolename);
+            if (target === undefined)
+                return;
+            node.rolename = target;
+            record(node.rolename);
+        },
+        CreateRoleStmt: (path) => {
+            const node = path.node;
+            const target = router.resolve(node.role);
+            if (target === undefined)
+                return;
+            node.role = target;
+            record(target);
+        },
+        GrantRoleStmt: (path) => {
+            // granted_roles are role names carried as AccessPriv.priv_name (the
+            // grantee_roles RoleSpecs are handled by the RoleSpec visitor).
+            const granted = path.node.granted_roles;
+            if (!Array.isArray(granted))
+                return;
+            for (const g of granted) {
+                const priv = g?.AccessPriv;
+                if (!priv || typeof priv.priv_name !== 'string')
+                    continue;
+                const target = router.resolve(priv.priv_name);
+                if (target === undefined)
+                    continue;
+                priv.priv_name = target;
+                record(target);
+            }
+        },
+        VariableSetStmt: (path) => {
+            const node = path.node;
+            if (!ROLE_SET_PARAMS.has(node.name) || !Array.isArray(node.args))
+                return;
+            for (const arg of node.args) {
+                const sval = arg?.A_Const?.sval?.sval ?? arg?.String?.sval;
+                if (typeof sval !== 'string')
+                    continue;
+                const target = router.resolve(sval);
+                if (target === undefined)
+                    continue;
+                if (arg.A_Const?.sval)
+                    arg.A_Const.sval.sval = target;
+                else if (arg.String)
+                    arg.String.sval = target;
+                record(target);
+            }
+        },
+        RenameStmt: (path) => {
+            const node = path.node;
+            if (node.renameType !== 'OBJECT_ROLE')
+                return;
+            const subTarget = router.resolve(node.subname);
+            if (subTarget !== undefined) {
+                node.subname = subTarget;
+                record(subTarget);
+            }
+            const newTarget = router.resolve(node.newname);
+            if (newTarget !== undefined) {
+                node.newname = newTarget;
+                record(newTarget);
+            }
+        }
+    };
+}
+/**
+ * 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.
+ */
+function transformRoles(sql, router) {
+    const resolved = role_router_1.RoleRouter.from(router);
+    const result = createRoleResult();
+    const out = (0, plpgsql_parser_1.transformSync)(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        const visitor = createRoleVisitor(resolved, result);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                (0, traverse_1.walk)(stmt.stmt, visitor);
+        }
+    }, { hydrate: true, pretty: true });
+    return { sql: out, result };
+}

package/router.d.ts

@@ -20,6 +20,19 @@
  * `types` — matching `pg_class` / `pg_proc` / `pg_type`), mirroring the routing
  * model already used by {@link qualifyUnqualified}. Resolution is
  * object-route-first, then the schema-level default, then "leave unchanged".
+ *
+ * An object route may also *rebind* — change the object's **name**, not just
+ * the schema it lives in. Routing preserves identity (the same function, a new
+ * address); rebinding repoints a reference at a *different* object, which is
+ * what lets one implementation of a contract be substituted for another:
+ *
+ * ```ts
+ * { auth: { functions: { uid: { schema: null, name: 'current_user_id' } } } }
+ * // auth.uid()  ->  current_user_id()
+ * ```
+ *
+ * A `null` target schema de-qualifies the reference (relying on `search_path`),
+ * matching the convention used by the extension router.
  */
 /** PostgreSQL object namespaces relevant to schema routing. */
 export type ObjectNamespace = 'relation' | 'function' | 'type';
@@ -30,6 +43,24 @@ export type ObjectNamespace = 'relation' | 'function' | 'type';
  * which case only the schema-level default applies.
  */
 export type RouteNamespace = ObjectNamespace | 'schema' | 'unknown';
+/**
+ * Where a specific object should be reached instead. Either field may be
+ * omitted: omitting `schema` keeps the schema-level default (or the current
+ * schema when the route has none), and omitting `name` keeps the object's own
+ * name — so `{ name }` alone is a pure rebind and `{ schema }` alone is
+ * equivalent to the shorthand string form.
+ */
+export interface ObjectRoute {
+    /** Target schema, or `null` to make the reference unqualified. */
+    schema?: string | null;
+    /** Target object name — rebinds the reference to a different object. */
+    name?: string;
+}
+/**
+ * An object route target. The shorthand `string` form is the target schema,
+ * identical to `{ schema: target }`.
+ */
+export type ObjectRouteTarget = string | ObjectRoute;
 /** Per-source-schema routing: a schema-level default plus per-object routes. */
 export interface SchemaRoute {
     /**
@@ -38,12 +69,12 @@ export interface SchemaRoute {
      * and leave the rest (and the schema itself) untouched.
      */
     schema?: string;
-    /** Relation name (table/view/sequence/matview) → target schema. */
-    relations?: Record<string, string>;
-    /** Function/procedure/aggregate name → target schema. */
-    functions?: Record<string, string>;
-    /** Type/domain name → target schema. */
-    types?: Record<string, string>;
+    /** Relation name (table/view/sequence/matview) → target schema or rebind. */
+    relations?: Record<string, ObjectRouteTarget>;
+    /** Function/procedure/aggregate name → target schema or rebind. */
+    functions?: Record<string, ObjectRouteTarget>;
+    /** Type/domain name → target schema or rebind. */
+    types?: Record<string, ObjectRouteTarget>;
 }
 /** The full routing specification: one {@link SchemaRoute} per source schema. */
 export type RouteSpec = Record<string, SchemaRoute>;
@@ -68,6 +99,22 @@ export declare class SchemaRouter {
      * bodies; whole-schema routes are handled by the cheaper string passes.
      */
     hasObjectRoutes(): boolean;
+    /**
+     * True when any object route changes a name or de-qualifies (rather than
+     * only moving between schemas). Such rewrites cannot be expressed by the
+     * string-level passes at all, so callers use this to require the AST path.
+     */
+    hasNameRebinds(): boolean;
+    /**
+     * Every object route that rebinds a name or de-qualifies, keyed by source
+     * schema and namespace. Callers use this to report or verify substitutions.
+     */
+    nameRebinds(): Array<{
+        schema: string;
+        ns: ObjectNamespace;
+        from: string;
+        to: ObjectRoute;
+    }>;
     /** Every source schema this router may touch. */
     sourceSchemas(): string[];
     /**
@@ -77,6 +124,16 @@ export declare class SchemaRouter {
      * to any object without a specific route.
      */
     resolve(sourceSchema: string | undefined | null, name?: string, ns?: RouteNamespace): string | undefined;
+    /**
+     * Resolve the full target for `(sourceSchema, name)` in namespace `ns` — both
+     * the schema the reference should live in and, when the route rebinds, the
+     * name it should be reached by. Returns `undefined` to leave it unchanged.
+     *
+     * In the result, `schema` is `null` when the reference should become
+     * unqualified and `undefined` when only the name changes; `name` is
+     * `undefined` when only the schema changes.
+     */
+    resolveObject(sourceSchema: string | undefined | null, name?: string, ns?: RouteNamespace): ObjectRoute | undefined;
     /**
      * Source schemas whose *every* object is guaranteed to move — i.e. those
      * with a schema-level default. After a transform, none of these should

package/router.js

@@ -21,6 +21,19 @@
  * `types` — matching `pg_class` / `pg_proc` / `pg_type`), mirroring the routing
  * model already used by {@link qualifyUnqualified}. Resolution is
  * object-route-first, then the schema-level default, then "leave unchanged".
+ *
+ * An object route may also *rebind* — change the object's **name**, not just
+ * the schema it lives in. Routing preserves identity (the same function, a new
+ * address); rebinding repoints a reference at a *different* object, which is
+ * what lets one implementation of a contract be substituted for another:
+ *
+ * ```ts
+ * { auth: { functions: { uid: { schema: null, name: 'current_user_id' } } } }
+ * // auth.uid()  ->  current_user_id()
+ * ```
+ *
+ * A `null` target schema de-qualifies the reference (relying on `search_path`),
+ * matching the convention used by the extension router.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchemaRouter = void 0;
@@ -74,6 +87,36 @@ class SchemaRouter {
         }
         return false;
     }
+    /**
+     * True when any object route changes a name or de-qualifies (rather than
+     * only moving between schemas). Such rewrites cannot be expressed by the
+     * string-level passes at all, so callers use this to require the AST path.
+     */
+    hasNameRebinds() {
+        return this.nameRebinds().length > 0;
+    }
+    /**
+     * Every object route that rebinds a name or de-qualifies, keyed by source
+     * schema and namespace. Callers use this to report or verify substitutions.
+     */
+    nameRebinds() {
+        const out = [];
+        for (const [schema, route] of this.routes) {
+            for (const ns of ['relation', 'function', 'type']) {
+                const bucket = route[NS_BUCKET[ns]];
+                if (!bucket)
+                    continue;
+                for (const [from, target] of Object.entries(bucket)) {
+                    if (typeof target === 'string')
+                        continue;
+                    if (target.name === undefined && target.schema !== null)
+                        continue;
+                    out.push({ schema, ns, from, to: target });
+                }
+            }
+        }
+        return out;
+    }
     /** Every source schema this router may touch. */
     sourceSchemas() {
         return [...this.routes.keys()];
@@ -85,18 +128,39 @@ class SchemaRouter {
      * to any object without a specific route.
      */
     resolve(sourceSchema, name, ns = 'unknown') {
+        // A `null` target de-qualifies the reference; the schema-only API cannot
+        // express that, so it reads as "unchanged" here.
+        return this.resolveObject(sourceSchema, name, ns)?.schema ?? undefined;
+    }
+    /**
+     * Resolve the full target for `(sourceSchema, name)` in namespace `ns` — both
+     * the schema the reference should live in and, when the route rebinds, the
+     * name it should be reached by. Returns `undefined` to leave it unchanged.
+     *
+     * In the result, `schema` is `null` when the reference should become
+     * unqualified and `undefined` when only the name changes; `name` is
+     * `undefined` when only the schema changes.
+     */
+    resolveObject(sourceSchema, name, ns = 'unknown') {
         if (!sourceSchema)
             return undefined;
         const route = this.routes.get(sourceSchema);
         if (!route)
             return undefined;
         if (name && (ns === 'relation' || ns === 'function' || ns === 'type')) {
-            const bucket = route[NS_BUCKET[ns]];
-            const mapped = bucket?.[name];
-            if (mapped !== undefined)
-                return mapped;
+            const target = route[NS_BUCKET[ns]]?.[name];
+            if (target !== undefined) {
+                if (typeof target === 'string')
+                    return { schema: target };
+                // An object route naming no schema inherits the schema-level default,
+                // so a pure rebind leaves placement alone.
+                return {
+                    schema: target.schema !== undefined ? target.schema : route.schema,
+                    name: target.name
+                };
+            }
         }
-        return route.schema;
+        return route.schema !== undefined ? { schema: route.schema } : undefined;
     }
     /**
      * Source schemas whose *every* object is guaranteed to move — i.e. those

package/transform.js

@@ -101,12 +101,24 @@ function transformNameList(names, schemaMapping, result, ns = 'unknown') {
     const first = names[0];
     if (first?.String?.sval) {
         const schemaName = first.String.sval;
-        const objName = names[names.length - 1]?.String?.sval;
-        const newName = router.resolve(schemaName, objName, ns);
-        if (newName && newName !== schemaName) {
+        const last = names[names.length - 1];
+        const objName = last?.String?.sval;
+        const target = router.resolveObject(schemaName, objName, ns);
+        if (!target)
+            return;
+        if (target.name !== undefined && last?.String?.sval) {
             result.schemasFound.add(schemaName);
-            first.String.sval = newName;
-            result.schemasTransformed.set(schemaName, newName);
+            last.String.sval = target.name;
+        }
+        if (target.schema === null) {
+            // De-qualify: drop the schema element and rely on search_path.
+            result.schemasFound.add(schemaName);
+            names.splice(0, 1);
+        }
+        else if (target.schema && target.schema !== schemaName) {
+            result.schemasFound.add(schemaName);
+            first.String.sval = target.schema;
+            result.schemasTransformed.set(schemaName, target.schema);
         }
     }
 }
@@ -138,11 +150,22 @@ function transformRelation(relation, schemaMapping, result) {
     const oldName = relation.schemaname;
     // A RangeVar names a relation (table/view/sequence/matview); route by the
     // relation name so object-level routes can send it to its own schema.
-    const newName = asRouter(schemaMapping).resolve(oldName, relation.relname, 'relation');
-    if (newName && newName !== oldName) {
+    const target = asRouter(schemaMapping).resolveObject(oldName, relation.relname, 'relation');
+    if (!target)
+        return;
+    if (target.name !== undefined && relation.relname) {
+        result.schemasFound.add(oldName);
+        relation.relname = target.name;
+    }
+    if (target.schema === null) {
+        // De-qualify: drop the schema qualifier and rely on search_path.
+        result.schemasFound.add(oldName);
+        delete relation.schemaname;
+    }
+    else if (target.schema && target.schema !== oldName) {
         result.schemasFound.add(oldName);
-        relation.schemaname = newName;
-        result.schemasTransformed.set(oldName, newName);
+        relation.schemaname = target.schema;
+        result.schemasTransformed.set(oldName, target.schema);
     }
 }
 /**