@pgpmjs/transform 0.9.0 → 0.11.0

package/bundle-driver.d.ts

@@ -7,23 +7,104 @@
  * purpose — no dependency on `@pgpmjs/bundle`/`@pgpmjs/core` — so the driver
  * stays a pure function factory over `transformSql` and `classifyStatements`.
  */
-import { SchemaTransformResult, TransformSqlOptions } from '@pgsql/transform';
+import { ExtensionDefinition, ExtensionRouteSpec, ExtensionRouter, ExtensionTransformResult, RoleRouteSpec, RoleTransformResult, SchemaRouter, SchemaTransformResult, TransformSqlOptions } from '@pgsql/transform';
 /** Identity of the script being transformed/validated (matches the bundle seams). */
 export interface BundleScriptContext {
     change: string;
     kind: 'deploy' | 'revert' | 'verify';
 }
+/**
+ * A single object-level route: send one named object out of a source schema to
+ * a different target schema, independent of the schema-level default. The
+ * object `kind` selects the routing namespace (relation / function / type) so a
+ * table and a function of the same name route independently.
+ */
+export interface SchemaObjectRoute {
+    /** Source schema the object is defined in (e.g. `users`). */
+    fromSchema: string;
+    /** Object namespace. `table`/`view` → relation, `procedure` → function. */
+    kind: 'table' | 'view' | 'function' | 'procedure' | 'type';
+    /** Unqualified object name (e.g. `accounts`). */
+    name: string;
+    /** Target schema this object is routed to (e.g. `reporting`). */
+    toSchema: string;
+}
+/**
+ * Extension routing for a transpile: where to install extensions and where the
+ * symbols they provide (functions/types/operators) should resolve. Distinct
+ * from schema routing — the objects are owned by an extension, not declared in
+ * the SQL — so it is driven by a version-aware symbol inventory. See the
+ * upstream `ExtensionRouter` for the full model. `toSchema: null` (or a `routes`
+ * entry with `to: null`) strips qualification — the "rely on search_path"
+ * direction — so the same mechanism moves symbols into a dedicated schema and
+ * back out again.
+ */
+export interface ExtensionRoutingInput {
+    /**
+     * Move the matched extensions and their provided symbols to this single
+     * schema (`null` strips qualification). Ignored when `routes` is given.
+     */
+    toSchema?: string | null;
+    /** With `toSchema`: limit to these extensions (default: every inventoried one). */
+    only?: string[];
+    /**
+     * With `toSchema`: which source qualifications to rewrite (a `null` entry
+     * also rewrites bare references). Defaults to `public` + bare.
+     */
+    from?: (string | null)[];
+    /** Advanced: explicit per-extension route spec. Overrides `toSchema`/`only`/`from`. */
+    routes?: ExtensionRouteSpec;
+    /** Target PostgreSQL major version, for core-graduation awareness (e.g. `gen_random_uuid`). */
+    serverVersion?: number;
+    /** Augmented or replacement symbol inventory (defaults to the curated common set). */
+    inventory?: ExtensionDefinition[];
+}
+/**
+ * Build an {@link ExtensionRouter} from the declarative {@link ExtensionRoutingInput}:
+ * an explicit `routes` spec when given, otherwise the "move everything matched
+ * to one schema" shortcut via `ExtensionRouter.toSchema`.
+ */
+export declare function buildExtensionRouter(input: ExtensionRoutingInput): ExtensionRouter;
 export interface SchemaTranspilerOptions {
-    /** Old schema name → new schema name. Drives both dimensions. */
-    schemaMap: Record<string, string>;
+    /**
+     * Whole-schema default: source schema → target schema. Optional when
+     * `routes` fully cover the objects being moved.
+     */
+    schemaMap?: Record<string, string>;
+    /**
+     * Object-level overrides. Each route wins over the schema-level default for
+     * its specific object, letting a single source schema fan out per object.
+     */
+    routes?: SchemaObjectRoute[];
+    /**
+     * Route extension installs and provided-symbol references (a dimension
+     * orthogonal to schema routing). See {@link ExtensionRoutingInput}.
+     */
+    extensions?: ExtensionRoutingInput;
+    /**
+     * Rename role identifiers (source role name → target role name), for
+     * translating between databases that name equivalent roles differently.
+     * Renames identifiers only — never role attributes.
+     */
+    roles?: RoleRouteSpec | Map<string, string>;
     /** Forwarded to {@link transformSql} (round-trip validation, extra passes). */
     transform?: TransformSqlOptions;
 }
+/**
+ * Build a {@link SchemaRouter} from a schema-level default map plus object
+ * routes. Object routes are grouped into the router's relation/function/type
+ * buckets; schema-level entries become each route's default target.
+ */
+export declare function buildSchemaRouter(options: SchemaTranspilerOptions): SchemaRouter;
 export interface SchemaTranspiler {
     /**
-     * Change-name/path rewrite (the pgpm structural dimension): renames the
-     * segment following any `schemas` path segment, e.g.
-     * `schemas/auth/tables/users` → `schemas/tenant_auth/tables/users`.
+     * Change-name/path rewrite (the pgpm structural dimension): rewrites the
+     * schema segment of a change path to the object's routed target. The object
+     * identity is read from the path itself — `schemas/<schema>/<kind>/<name>` —
+     * so a table and a function under the same source schema can land in
+     * different target schemas, e.g. `schemas/users/tables/accounts/table` →
+     * `schemas/tenant_a/tables/accounts/table` while
+     * `schemas/users/procedures/account_count` → `schemas/reporting/procedures/account_count`.
      */
     renameChange: (name: string) => string;
     /**
@@ -37,11 +118,21 @@ export interface SchemaTranspiler {
      * schemas found/transformed and any per-script errors.
      */
     result: SchemaTransformResult;
+    /**
+     * Accumulated extension-routing report (installs moved, symbols rewritten).
+     * Present only when `extensions` was configured.
+     */
+    extensionResult?: ExtensionTransformResult;
+    /**
+     * Accumulated role-routing report (role → rewrite count). Present only when
+     * `roles` was configured.
+     */
+    roleResult?: RoleTransformResult;
 }
 /**
- * Build the caller-supplied callbacks for `transpileBundle` from a single
- * schema map, so the folder/plan rename and the in-SQL rewrite stay in
- * lockstep.
+ * Build the caller-supplied callbacks for `transpileBundle` from a schema map
+ * and/or object routes, so the folder/plan rename (change identity) and the
+ * in-SQL rewrite (AST) stay in lockstep on the exact same {@link SchemaRouter}.
  */
 export declare function makeSchemaTranspiler(options: SchemaTranspilerOptions): SchemaTranspiler;
 export interface NamespaceValidatorOptions {

package/bundle-driver.js

@@ -9,35 +9,139 @@
  * stays a pure function factory over `transformSql` and `classifyStatements`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExtensionRouter = buildExtensionRouter;
+exports.buildSchemaRouter = buildSchemaRouter;
 exports.makeSchemaTranspiler = makeSchemaTranspiler;
 exports.makeNamespaceValidator = makeNamespaceValidator;
 const transform_1 = require("@pgsql/transform");
 const transform_2 = require("@pgsql/transform");
 /**
- * Build the caller-supplied callbacks for `transpileBundle` from a single
- * schema map, so the folder/plan rename and the in-SQL rewrite stay in
- * lockstep.
+ * Build an {@link ExtensionRouter} from the declarative {@link ExtensionRoutingInput}:
+ * an explicit `routes` spec when given, otherwise the "move everything matched
+ * to one schema" shortcut via `ExtensionRouter.toSchema`.
+ */
+function buildExtensionRouter(input) {
+    const opts = {};
+    if (input.serverVersion !== undefined)
+        opts.serverVersion = input.serverVersion;
+    if (input.inventory)
+        opts.inventory = input.inventory;
+    if (input.routes)
+        return new transform_2.ExtensionRouter(input.routes, opts);
+    return transform_2.ExtensionRouter.toSchema(input.toSchema ?? null, {
+        ...opts,
+        extensions: input.only,
+        from: input.from
+    });
+}
+/** pgpm change-path folder segment → transform routing namespace. */
+const PATH_KIND_NS = {
+    tables: 'relation',
+    views: 'relation',
+    procedures: 'function',
+    functions: 'function',
+    types: 'type'
+};
+/** Object route `kind` → the {@link SchemaRoute} bucket it belongs in. */
+const ROUTE_KIND_BUCKET = {
+    table: 'relations',
+    view: 'relations',
+    function: 'functions',
+    procedure: 'functions',
+    type: 'types'
+};
+/**
+ * Build a {@link SchemaRouter} from a schema-level default map plus object
+ * routes. Object routes are grouped into the router's relation/function/type
+ * buckets; schema-level entries become each route's default target.
+ */
+function buildSchemaRouter(options) {
+    const spec = {};
+    const ensure = (schema) => (spec[schema] ??= {});
+    for (const [from, to] of Object.entries(options.schemaMap ?? {})) {
+        ensure(from).schema = to;
+    }
+    for (const route of options.routes ?? []) {
+        const bucketKey = ROUTE_KIND_BUCKET[route.kind];
+        const target = ensure(route.fromSchema);
+        (target[bucketKey] ??= {})[route.name] = route.toSchema;
+    }
+    return new transform_2.SchemaRouter(spec);
+}
+/**
+ * Rewrite the schema segment of a pgpm change path to the object's routed
+ * target. Interprets `schemas/<schema>/<kind>/<name>...`: the bare
+ * `schemas/<schema>/schema` change resolves at the schema level; typed folders
+ * (`tables`, `procedures`, `types`, …) resolve the named object in its
+ * namespace, so object routes and the schema-level default both apply.
+ */
+function renameChangePath(name, router) {
+    const parts = name.split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+        if (parts[i] !== 'schemas')
+            continue;
+        const schema = parts[i + 1];
+        if (!router.has(schema))
+            continue;
+        const folder = parts[i + 2];
+        let target;
+        if (folder === undefined || folder === 'schema') {
+            target = router.resolve(schema, undefined, 'schema');
+        }
+        else {
+            const ns = PATH_KIND_NS[folder];
+            const objectName = parts[i + 3];
+            target = ns
+                ? router.resolve(schema, objectName, ns)
+                : router.resolve(schema, undefined, 'schema');
+        }
+        if (target && target !== schema)
+            parts[i + 1] = target;
+    }
+    return parts.join('/');
+}
+/**
+ * Build the caller-supplied callbacks for `transpileBundle` from a schema map
+ * and/or object routes, so the folder/plan rename (change identity) and the
+ * in-SQL rewrite (AST) stay in lockstep on the exact same {@link SchemaRouter}.
  */
 function makeSchemaTranspiler(options) {
-    const mapping = new Map(Object.entries(options.schemaMap));
+    const router = buildSchemaRouter(options);
     const result = {
         schemasFound: new Set(),
         schemasTransformed: new Map(),
         errors: []
     };
-    const renameChange = (name) => {
-        const parts = name.split('/');
-        for (let i = 0; i < parts.length - 1; i++) {
-            if (parts[i] === 'schemas' && mapping.has(parts[i + 1])) {
-                parts[i + 1] = mapping.get(parts[i + 1]);
+    // Extension/role routing are additional, orthogonal AST dimensions applied
+    // after schema routing on each script. Each is a self-contained parse →
+    // rewrite → deparse pass, so they compose by threading the SQL through.
+    const extRouter = options.extensions ? buildExtensionRouter(options.extensions) : undefined;
+    const roleRouter = options.roles ? transform_2.RoleRouter.from(options.roles) : undefined;
+    const extensionResult = extRouter ? (0, transform_2.createExtensionResult)() : undefined;
+    const roleResult = roleRouter ? (0, transform_2.createRoleResult)() : undefined;
+    const renameChange = (name) => renameChangePath(name, router);
+    const transformScript = (sql, _ctx) => {
+        let out = (0, transform_2.transformSql)(sql, router, options.transform, result).content;
+        if (extRouter) {
+            const r = (0, transform_2.transformExtensions)(out, extRouter);
+            out = r.sql;
+            for (const [name, schema] of r.result.installsMoved) {
+                extensionResult.installsMoved.set(name, schema);
+            }
+            for (const [name, count] of r.result.symbolsRewritten) {
+                extensionResult.symbolsRewritten.set(name, (extensionResult.symbolsRewritten.get(name) ?? 0) + count);
             }
         }
-        return parts.join('/');
-    };
-    const transformScript = (sql, _ctx) => {
-        return (0, transform_2.transformSql)(sql, mapping, options.transform, result).content;
+        if (roleRouter) {
+            const r = (0, transform_2.transformRoles)(out, roleRouter);
+            out = r.sql;
+            for (const [name, count] of r.result.rolesRenamed) {
+                roleResult.rolesRenamed.set(name, (roleResult.rolesRenamed.get(name) ?? 0) + count);
+            }
+        }
+        return out;
     };
-    return { renameChange, transformScript, result };
+    return { renameChange, transformScript, result, extensionResult, roleResult };
 }
 /**
  * Build an `applyBundle`-compatible `validateReferences` callback: returns a

package/esm/bundle-driver.js

@@ -8,32 +8,134 @@
  * stays a pure function factory over `transformSql` and `classifyStatements`.
  */
 import { classifyStatements } from '@pgsql/transform';
-import { transformSql } from '@pgsql/transform';
+import { createExtensionResult, createRoleResult, ExtensionRouter, RoleRouter, SchemaRouter, transformExtensions, transformRoles, transformSql } from '@pgsql/transform';
 /**
- * Build the caller-supplied callbacks for `transpileBundle` from a single
- * schema map, so the folder/plan rename and the in-SQL rewrite stay in
- * lockstep.
+ * Build an {@link ExtensionRouter} from the declarative {@link ExtensionRoutingInput}:
+ * an explicit `routes` spec when given, otherwise the "move everything matched
+ * to one schema" shortcut via `ExtensionRouter.toSchema`.
+ */
+export function buildExtensionRouter(input) {
+    const opts = {};
+    if (input.serverVersion !== undefined)
+        opts.serverVersion = input.serverVersion;
+    if (input.inventory)
+        opts.inventory = input.inventory;
+    if (input.routes)
+        return new ExtensionRouter(input.routes, opts);
+    return ExtensionRouter.toSchema(input.toSchema ?? null, {
+        ...opts,
+        extensions: input.only,
+        from: input.from
+    });
+}
+/** pgpm change-path folder segment → transform routing namespace. */
+const PATH_KIND_NS = {
+    tables: 'relation',
+    views: 'relation',
+    procedures: 'function',
+    functions: 'function',
+    types: 'type'
+};
+/** Object route `kind` → the {@link SchemaRoute} bucket it belongs in. */
+const ROUTE_KIND_BUCKET = {
+    table: 'relations',
+    view: 'relations',
+    function: 'functions',
+    procedure: 'functions',
+    type: 'types'
+};
+/**
+ * Build a {@link SchemaRouter} from a schema-level default map plus object
+ * routes. Object routes are grouped into the router's relation/function/type
+ * buckets; schema-level entries become each route's default target.
+ */
+export function buildSchemaRouter(options) {
+    const spec = {};
+    const ensure = (schema) => (spec[schema] ??= {});
+    for (const [from, to] of Object.entries(options.schemaMap ?? {})) {
+        ensure(from).schema = to;
+    }
+    for (const route of options.routes ?? []) {
+        const bucketKey = ROUTE_KIND_BUCKET[route.kind];
+        const target = ensure(route.fromSchema);
+        (target[bucketKey] ??= {})[route.name] = route.toSchema;
+    }
+    return new SchemaRouter(spec);
+}
+/**
+ * Rewrite the schema segment of a pgpm change path to the object's routed
+ * target. Interprets `schemas/<schema>/<kind>/<name>...`: the bare
+ * `schemas/<schema>/schema` change resolves at the schema level; typed folders
+ * (`tables`, `procedures`, `types`, …) resolve the named object in its
+ * namespace, so object routes and the schema-level default both apply.
+ */
+function renameChangePath(name, router) {
+    const parts = name.split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+        if (parts[i] !== 'schemas')
+            continue;
+        const schema = parts[i + 1];
+        if (!router.has(schema))
+            continue;
+        const folder = parts[i + 2];
+        let target;
+        if (folder === undefined || folder === 'schema') {
+            target = router.resolve(schema, undefined, 'schema');
+        }
+        else {
+            const ns = PATH_KIND_NS[folder];
+            const objectName = parts[i + 3];
+            target = ns
+                ? router.resolve(schema, objectName, ns)
+                : router.resolve(schema, undefined, 'schema');
+        }
+        if (target && target !== schema)
+            parts[i + 1] = target;
+    }
+    return parts.join('/');
+}
+/**
+ * Build the caller-supplied callbacks for `transpileBundle` from a schema map
+ * and/or object routes, so the folder/plan rename (change identity) and the
+ * in-SQL rewrite (AST) stay in lockstep on the exact same {@link SchemaRouter}.
  */
 export function makeSchemaTranspiler(options) {
-    const mapping = new Map(Object.entries(options.schemaMap));
+    const router = buildSchemaRouter(options);
     const result = {
         schemasFound: new Set(),
         schemasTransformed: new Map(),
         errors: []
     };
-    const renameChange = (name) => {
-        const parts = name.split('/');
-        for (let i = 0; i < parts.length - 1; i++) {
-            if (parts[i] === 'schemas' && mapping.has(parts[i + 1])) {
-                parts[i + 1] = mapping.get(parts[i + 1]);
+    // Extension/role routing are additional, orthogonal AST dimensions applied
+    // after schema routing on each script. Each is a self-contained parse →
+    // rewrite → deparse pass, so they compose by threading the SQL through.
+    const extRouter = options.extensions ? buildExtensionRouter(options.extensions) : undefined;
+    const roleRouter = options.roles ? RoleRouter.from(options.roles) : undefined;
+    const extensionResult = extRouter ? createExtensionResult() : undefined;
+    const roleResult = roleRouter ? createRoleResult() : undefined;
+    const renameChange = (name) => renameChangePath(name, router);
+    const transformScript = (sql, _ctx) => {
+        let out = transformSql(sql, router, options.transform, result).content;
+        if (extRouter) {
+            const r = transformExtensions(out, extRouter);
+            out = r.sql;
+            for (const [name, schema] of r.result.installsMoved) {
+                extensionResult.installsMoved.set(name, schema);
+            }
+            for (const [name, count] of r.result.symbolsRewritten) {
+                extensionResult.symbolsRewritten.set(name, (extensionResult.symbolsRewritten.get(name) ?? 0) + count);
             }
         }
-        return parts.join('/');
-    };
-    const transformScript = (sql, _ctx) => {
-        return transformSql(sql, mapping, options.transform, result).content;
+        if (roleRouter) {
+            const r = transformRoles(out, roleRouter);
+            out = r.sql;
+            for (const [name, count] of r.result.rolesRenamed) {
+                roleResult.rolesRenamed.set(name, (roleResult.rolesRenamed.get(name) ?? 0) + count);
+            }
+        }
+        return out;
     };
-    return { renameChange, transformScript, result };
+    return { renameChange, transformScript, result, extensionResult, roleResult };
 }
 /**
  * Build an `applyBundle`-compatible `validateReferences` callback: returns a

package/esm/index.js

@@ -1,4 +1,5 @@
 export * from '@pgsql/transform';
-export { makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
+export { loadModule } from 'plpgsql-parser';
+export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export { resolveFixtureClosure } from './fixture-closure';

package/index.d.ts

@@ -1,6 +1,7 @@
 export * from '@pgsql/transform';
-export type { BundleScriptContext, NamespaceValidatorOptions, SchemaTranspiler, SchemaTranspilerOptions, } from './bundle-driver';
-export { makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
+export { loadModule } from 'plpgsql-parser';
+export type { BundleScriptContext, ExtensionRoutingInput, NamespaceValidatorOptions, SchemaObjectRoute, SchemaTranspiler, SchemaTranspilerOptions, } from './bundle-driver';
+export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
 export type { CategoryProfile, ChangeCategory, } from './categorize';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export type { ClosureChange, ClosureInputChange, ClosureReason, FixtureClosure, ResolveFixtureClosureOptions, } from './fixture-closure';

package/index.js

@@ -14,9 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveFixtureClosure = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = void 0;
+exports.resolveFixtureClosure = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = exports.loadModule = void 0;
 __exportStar(require("@pgsql/transform"), exports);
+var plpgsql_parser_1 = require("plpgsql-parser");
+Object.defineProperty(exports, "loadModule", { enumerable: true, get: function () { return plpgsql_parser_1.loadModule; } });
 var bundle_driver_1 = require("./bundle-driver");
+Object.defineProperty(exports, "buildExtensionRouter", { enumerable: true, get: function () { return bundle_driver_1.buildExtensionRouter; } });
+Object.defineProperty(exports, "buildSchemaRouter", { enumerable: true, get: function () { return bundle_driver_1.buildSchemaRouter; } });
 Object.defineProperty(exports, "makeNamespaceValidator", { enumerable: true, get: function () { return bundle_driver_1.makeNamespaceValidator; } });
 Object.defineProperty(exports, "makeSchemaTranspiler", { enumerable: true, get: function () { return bundle_driver_1.makeSchemaTranspiler; } });
 var categorize_1 = require("./categorize");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Change-aware SQL transformation for PGPM — superset of @pgsql/transform plus change categorization, fixture closure, and bundle transpile/apply drivers",
   "main": "index.js",
@@ -39,12 +39,12 @@
     "plpgsql"
   ],
   "devDependencies": {
-    "@pgpmjs/bundle": "^0.10.0",
+    "@pgpmjs/bundle": "^0.12.0",
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgsql/transform": "^18.3.1",
+    "@pgsql/transform": "^18.6.0",
     "plpgsql-parser": "^18.2.1"
   },
-  "gitHead": "72961803894504c1a9308f9c6c349ff7b48bbe14"
+  "gitHead": "5ef8341033a8fbd85841b770e996e468dd15333b"
 }