@pgpmjs/transform 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @pgpmjs/transform
+
+Change-aware SQL transformation for PGPM. A **superset of [`@pgsql/transform`](https://www.npmjs.com/package/@pgsql/transform)** — everything from the pure AST layer is re-exported, plus the layers that understand pgpm *changes*:
+
+- **`categorizeChange` / `buildCategoryOf` / `TIER_PROFILE`** — profile-driven categorization of migration changes (schema / functionality / security / fixtures) from their AST facts, ready for `@pgpmjs/core`'s `boundary: 'category'` rebundle mode.
+- **`resolveFixtureClosure`** — transitive dependency closure over a set of changes (name + deploy SQL + optional plan dependencies): forward producers of every referenced object/schema/role, attached fixtures (policies/grants/RLS targeting closure members), explicit unresolved-reference reporting.
+- **`makeSchemaTranspiler` / `makeNamespaceValidator`** — drivers plugging `transformSql`/`classifyStatements` into the pgpm migration-bundle seams (`transpileBundle`'s `renameChange`/`transformScript`, `applyBundle`'s `validateReferences`).
+
+Re-exported from `@pgsql/transform`: `transformSql` (schema-name rewriting incl. PL/pgSQL bodies), `classifyStatements` (per-statement AST facts), `qualifyUnqualified`, and round-trip validation utilities.
+
+## Installation
+
+```bash
+npm install @pgpmjs/transform
+```
+
+The parser runs on a WASM build of the real PostgreSQL parser; call `loadModule()` from `plpgsql-parser` once before using any synchronous API.
+
+## Usage
+
+```typescript
+import { loadModule } from 'plpgsql-parser';
+import { buildCategoryOf, resolveFixtureClosure, TIER_PROFILE, transformSql } from '@pgpmjs/transform';
+
+await loadModule();
+
+const categoryOf = buildCategoryOf(changes, TIER_PROFILE);
+const closure = resolveFixtureClosure(allChanges, ['schemas/api/procedures/get_totals']);
+```
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/bundle-driver.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bundle transpile/apply drivers.
+ *
+ * Adapters that plug this package's AST transforms into the pgpm migration
+ * bundle seams (`transpileBundle`'s `renameChange`/`transformScript` and
+ * `applyBundle`'s `validateReferences`). The seams are structurally typed on
+ * 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';
+/** Identity of the script being transformed/validated (matches the bundle seams). */
+export interface BundleScriptContext {
+    change: string;
+    kind: 'deploy' | 'revert' | 'verify';
+}
+export interface SchemaTranspilerOptions {
+    /** Old schema name → new schema name. Drives both dimensions. */
+    schemaMap: Record<string, string>;
+    /** Forwarded to {@link transformSql} (round-trip validation, extra passes). */
+    transform?: TransformSqlOptions;
+}
+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`.
+     */
+    renameChange: (name: string) => string;
+    /**
+     * SQL body rewrite (the AST dimension): full AST transform of every mapped
+     * schema reference via {@link transformSql}, including PL/pgSQL bodies.
+     * Throws if a mapped schema survives untransformed.
+     */
+    transformScript: (sql: string, ctx: BundleScriptContext) => string;
+    /**
+     * Accumulated report across every script this transpiler has transformed:
+     * schemas found/transformed and any per-script errors.
+     */
+    result: SchemaTransformResult;
+}
+/**
+ * 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.
+ */
+export declare function makeSchemaTranspiler(options: SchemaTranspilerOptions): SchemaTranspiler;
+export interface NamespaceValidatorOptions {
+    /** Schemas the bundle is allowed to create objects in or reference. */
+    allowedSchemas: string[];
+    /**
+     * Also flag statements whose PL/pgSQL bodies execute dynamic SQL — their
+     * references are invisible to the AST, so containment cannot be proven.
+     * Off by default (dynamic SQL is common in legitimate functions).
+     */
+    flagDynamicSql?: boolean;
+}
+/**
+ * Build an `applyBundle`-compatible `validateReferences` callback: returns a
+ * description of every schema-qualified object a script creates or references
+ * outside the allowed namespace. Unqualified references resolve via
+ * search_path and are not reported.
+ */
+export declare function makeNamespaceValidator(options: NamespaceValidatorOptions): (sql: string, ctx: BundleScriptContext) => string[];

package/bundle-driver.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Bundle transpile/apply drivers.
+ *
+ * Adapters that plug this package's AST transforms into the pgpm migration
+ * bundle seams (`transpileBundle`'s `renameChange`/`transformScript` and
+ * `applyBundle`'s `validateReferences`). The seams are structurally typed on
+ * purpose — no dependency on `@pgpmjs/bundle`/`@pgpmjs/core` — so the driver
+ * stays a pure function factory over `transformSql` and `classifyStatements`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+ */
+function makeSchemaTranspiler(options) {
+    const mapping = new Map(Object.entries(options.schemaMap));
+    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]);
+            }
+        }
+        return parts.join('/');
+    };
+    const transformScript = (sql, _ctx) => {
+        return (0, transform_2.transformSql)(sql, mapping, options.transform, result).content;
+    };
+    return { renameChange, transformScript, result };
+}
+/**
+ * Build an `applyBundle`-compatible `validateReferences` callback: returns a
+ * description of every schema-qualified object a script creates or references
+ * outside the allowed namespace. Unqualified references resolve via
+ * search_path and are not reported.
+ */
+function makeNamespaceValidator(options) {
+    const allowed = new Set(options.allowedSchemas);
+    return (sql, _ctx) => {
+        const violations = new Set();
+        for (const facts of (0, transform_1.classifyStatements)(sql)) {
+            for (const ref of [...facts.creates, ...facts.references, ...facts.fkTargets]) {
+                if (ref.schema && !allowed.has(ref.schema)) {
+                    violations.add(`${facts.nodeTag}: ${ref.schema}.${ref.name}`);
+                }
+            }
+            if (options.flagDynamicSql && facts.dynamicSql) {
+                violations.add(`${facts.nodeTag}: dynamic SQL — references not statically verifiable`);
+            }
+        }
+        return [...violations];
+    };
+}

package/categorize.d.ts

@@ -0,0 +1,52 @@
+import { StatementFacts } from '@pgsql/transform';
+/**
+ * A category is a chunk-seam key a change is assigned to. Free-form string; the
+ * built-in {@link TIER_PROFILE} uses `'security' | 'functionality' | 'fixtures'
+ * | 'schema'`.
+ *
+ * This module is the classifier-driven counterpart to `@pgpmjs/core`'s
+ * `boundary: 'category'` rebundle mode: core stays classifier-agnostic and only
+ * consumes a `categoryOf(changeName)` seam function, while the rules that decide
+ * *what* each change is (the profile) live here, next to the AST facts.
+ */
+export type ChangeCategory = string;
+/**
+ * Decides a change's category from the AST facts of its (deploy) statements.
+ * A profile is a pure function of the facts — swap it to carve a monolith along
+ * different seams (e.g. per-role admin/users modules) without touching core.
+ */
+export interface CategoryProfile {
+    /** Identifier for the profile (for logging / provenance). */
+    name: string;
+    /** Map a change's statement facts to its category. */
+    categorize: (facts: StatementFacts[], changeName: string) => ChangeCategory;
+}
+/**
+ * Default tier profile: isolates the security surface and procedural code out
+ * of the schema base. Precedence, highest first — a change is placed in the
+ * most specialized tier any of its statements reaches:
+ *
+ *   security       any securityRelevant statement (policy/grant/RLS/role/owner)
+ *   functionality  functions and triggers
+ *   fixtures       seed DML (INSERT/UPDATE/DELETE)
+ *   schema         schemas, tables, views, indexes, types, constraints (base)
+ *
+ * Ordering/dependencies across the resulting chunks are still resolved by
+ * core's rebundle graph, so this only decides *naming/grouping*, never deploy
+ * order.
+ */
+export declare const TIER_PROFILE: CategoryProfile;
+/**
+ * Classify a single change's deploy SQL into its category under `profile`
+ * (defaults to {@link TIER_PROFILE}).
+ */
+export declare function categorizeChange(sql: string, changeName: string, profile?: CategoryProfile): ChangeCategory;
+/**
+ * Build a `categoryOf(changeName)` seam function from a map of change name to
+ * its deploy SQL — ready to pass straight to `@pgpmjs/core`'s rebundle
+ * `boundary: 'category'` / `categoryOf` options.
+ *
+ * Changes absent from `changeSql` return `undefined`, letting core fall back to
+ * its folder key for anything the classifier did not see.
+ */
+export declare function buildCategoryOf(changeSql: Record<string, string>, profile?: CategoryProfile): (changeName: string) => ChangeCategory | undefined;

package/categorize.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIER_PROFILE = void 0;
+exports.categorizeChange = categorizeChange;
+exports.buildCategoryOf = buildCategoryOf;
+const transform_1 = require("@pgsql/transform");
+/**
+ * Default tier profile: isolates the security surface and procedural code out
+ * of the schema base. Precedence, highest first — a change is placed in the
+ * most specialized tier any of its statements reaches:
+ *
+ *   security       any securityRelevant statement (policy/grant/RLS/role/owner)
+ *   functionality  functions and triggers
+ *   fixtures       seed DML (INSERT/UPDATE/DELETE)
+ *   schema         schemas, tables, views, indexes, types, constraints (base)
+ *
+ * Ordering/dependencies across the resulting chunks are still resolved by
+ * core's rebundle graph, so this only decides *naming/grouping*, never deploy
+ * order.
+ */
+exports.TIER_PROFILE = {
+    name: 'tier',
+    categorize(facts) {
+        if (facts.length === 0)
+            return 'schema';
+        if (facts.some(f => f.securityRelevant))
+            return 'security';
+        if (facts.some(f => f.kind === 'function' || f.kind === 'trigger'))
+            return 'functionality';
+        if (facts.some(f => f.kind === 'seed_dml'))
+            return 'fixtures';
+        return 'schema';
+    },
+};
+/**
+ * Classify a single change's deploy SQL into its category under `profile`
+ * (defaults to {@link TIER_PROFILE}).
+ */
+function categorizeChange(sql, changeName, profile = exports.TIER_PROFILE) {
+    return profile.categorize((0, transform_1.classifyStatements)(sql), changeName);
+}
+/**
+ * Build a `categoryOf(changeName)` seam function from a map of change name to
+ * its deploy SQL — ready to pass straight to `@pgpmjs/core`'s rebundle
+ * `boundary: 'category'` / `categoryOf` options.
+ *
+ * Changes absent from `changeSql` return `undefined`, letting core fall back to
+ * its folder key for anything the classifier did not see.
+ */
+function buildCategoryOf(changeSql, profile = exports.TIER_PROFILE) {
+    const categories = new Map();
+    for (const [name, sql] of Object.entries(changeSql)) {
+        categories.set(name, categorizeChange(sql, name, profile));
+    }
+    return (changeName) => categories.get(changeName);
+}

package/esm/bundle-driver.js

@@ -0,0 +1,60 @@
+/**
+ * Bundle transpile/apply drivers.
+ *
+ * Adapters that plug this package's AST transforms into the pgpm migration
+ * bundle seams (`transpileBundle`'s `renameChange`/`transformScript` and
+ * `applyBundle`'s `validateReferences`). The seams are structurally typed on
+ * purpose — no dependency on `@pgpmjs/bundle`/`@pgpmjs/core` — so the driver
+ * stays a pure function factory over `transformSql` and `classifyStatements`.
+ */
+import { classifyStatements } from '@pgsql/transform';
+import { 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.
+ */
+export function makeSchemaTranspiler(options) {
+    const mapping = new Map(Object.entries(options.schemaMap));
+    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]);
+            }
+        }
+        return parts.join('/');
+    };
+    const transformScript = (sql, _ctx) => {
+        return transformSql(sql, mapping, options.transform, result).content;
+    };
+    return { renameChange, transformScript, result };
+}
+/**
+ * Build an `applyBundle`-compatible `validateReferences` callback: returns a
+ * description of every schema-qualified object a script creates or references
+ * outside the allowed namespace. Unqualified references resolve via
+ * search_path and are not reported.
+ */
+export function makeNamespaceValidator(options) {
+    const allowed = new Set(options.allowedSchemas);
+    return (sql, _ctx) => {
+        const violations = new Set();
+        for (const facts of classifyStatements(sql)) {
+            for (const ref of [...facts.creates, ...facts.references, ...facts.fkTargets]) {
+                if (ref.schema && !allowed.has(ref.schema)) {
+                    violations.add(`${facts.nodeTag}: ${ref.schema}.${ref.name}`);
+                }
+            }
+            if (options.flagDynamicSql && facts.dynamicSql) {
+                violations.add(`${facts.nodeTag}: dynamic SQL — references not statically verifiable`);
+            }
+        }
+        return [...violations];
+    };
+}

package/esm/categorize.js

@@ -0,0 +1,51 @@
+import { classifyStatements } from '@pgsql/transform';
+/**
+ * Default tier profile: isolates the security surface and procedural code out
+ * of the schema base. Precedence, highest first — a change is placed in the
+ * most specialized tier any of its statements reaches:
+ *
+ *   security       any securityRelevant statement (policy/grant/RLS/role/owner)
+ *   functionality  functions and triggers
+ *   fixtures       seed DML (INSERT/UPDATE/DELETE)
+ *   schema         schemas, tables, views, indexes, types, constraints (base)
+ *
+ * Ordering/dependencies across the resulting chunks are still resolved by
+ * core's rebundle graph, so this only decides *naming/grouping*, never deploy
+ * order.
+ */
+export const TIER_PROFILE = {
+    name: 'tier',
+    categorize(facts) {
+        if (facts.length === 0)
+            return 'schema';
+        if (facts.some(f => f.securityRelevant))
+            return 'security';
+        if (facts.some(f => f.kind === 'function' || f.kind === 'trigger'))
+            return 'functionality';
+        if (facts.some(f => f.kind === 'seed_dml'))
+            return 'fixtures';
+        return 'schema';
+    },
+};
+/**
+ * Classify a single change's deploy SQL into its category under `profile`
+ * (defaults to {@link TIER_PROFILE}).
+ */
+export function categorizeChange(sql, changeName, profile = TIER_PROFILE) {
+    return profile.categorize(classifyStatements(sql), changeName);
+}
+/**
+ * Build a `categoryOf(changeName)` seam function from a map of change name to
+ * its deploy SQL — ready to pass straight to `@pgpmjs/core`'s rebundle
+ * `boundary: 'category'` / `categoryOf` options.
+ *
+ * Changes absent from `changeSql` return `undefined`, letting core fall back to
+ * its folder key for anything the classifier did not see.
+ */
+export function buildCategoryOf(changeSql, profile = TIER_PROFILE) {
+    const categories = new Map();
+    for (const [name, sql] of Object.entries(changeSql)) {
+        categories.set(name, categorizeChange(sql, name, profile));
+    }
+    return (changeName) => categories.get(changeName);
+}

package/esm/fixture-closure.js

@@ -0,0 +1,197 @@
+import { TIER_PROFILE } from './categorize';
+import { classifyStatements } from '@pgsql/transform';
+function objectKey(schema, name) {
+    return `${schema ?? ''}\u0000${name}`;
+}
+function analyze(change, profile) {
+    const facts = classifyStatements(change.sql);
+    const category = profile.categorize(facts, change.name);
+    const creates = [];
+    const createsSchemas = [];
+    const createsRoles = [];
+    const needsObjects = [];
+    const needsSchemas = new Set();
+    const needsRoles = new Set();
+    for (const f of facts) {
+        for (const c of f.creates) {
+            if (f.kind === 'schema')
+                createsSchemas.push(c.name);
+            else {
+                creates.push(c);
+                if (c.schema)
+                    needsSchemas.add(c.schema);
+            }
+        }
+        if (f.nodeTag === 'CreateRoleStmt')
+            createsRoles.push(...f.roles);
+        for (const r of [...f.references, ...f.fkTargets]) {
+            if (r.schema)
+                needsObjects.push(r);
+        }
+        for (const s of f.referencedSchemas)
+            needsSchemas.add(s);
+    }
+    const created = new Set(createsRoles);
+    for (const f of facts) {
+        if (f.nodeTag === 'CreateRoleStmt')
+            continue;
+        for (const role of f.roles)
+            if (!created.has(role))
+                needsRoles.add(role);
+    }
+    for (const s of createsSchemas)
+        needsSchemas.delete(s);
+    return {
+        name: change.name,
+        category,
+        facts,
+        dependencies: change.dependencies ?? [],
+        creates,
+        createsSchemas,
+        createsRoles,
+        needsObjects,
+        needsSchemas: [...needsSchemas],
+        needsRoles: [...needsRoles],
+        isFixture: category === 'security' || category === 'fixtures'
+    };
+}
+/**
+ * Resolve the fixture closure of a schema slice.
+ *
+ * Pure and deterministic — no I/O — and runs to a fixpoint in both directions:
+ *   - forward: a selected change pulls in the producers of the objects/schemas/
+ *     roles it references, plus its declared plan dependencies (prerequisites);
+ *   - reverse: any fixture (security/fixtures-tier change) that attaches to an
+ *     object already in the closure is pulled in (attached fixtures), and then
+ *     resolved for its own prerequisites.
+ *
+ * Output order follows the input (plan) order, so it stays deploy-safe.
+ */
+export function resolveFixtureClosure(allChanges, selection, options = {}) {
+    const profile = options.profile ?? TIER_PROFILE;
+    const includePrerequisites = options.includePrerequisites ?? true;
+    const analyses = allChanges.map(c => analyze(c, profile));
+    const byName = new Map(analyses.map(a => [a.name, a]));
+    const producerByObject = new Map();
+    const producerBySchema = new Map();
+    const producerByRole = new Map();
+    for (const a of analyses) {
+        for (const c of a.creates) {
+            const key = objectKey(c.schema, c.name);
+            if (!producerByObject.has(key))
+                producerByObject.set(key, a.name);
+        }
+        for (const s of a.createsSchemas) {
+            if (!producerBySchema.has(s))
+                producerBySchema.set(s, a.name);
+        }
+        for (const r of a.createsRoles) {
+            if (!producerByRole.has(r))
+                producerByRole.set(r, a.name);
+        }
+    }
+    const reason = new Map();
+    for (const name of selection) {
+        if (byName.has(name))
+            reason.set(name, 'selected');
+    }
+    const producedObjectKeys = new Set();
+    const producedSchemas = new Set();
+    const refreshProduced = () => {
+        producedObjectKeys.clear();
+        producedSchemas.clear();
+        for (const name of reason.keys()) {
+            const a = byName.get(name);
+            for (const c of a.creates)
+                producedObjectKeys.add(objectKey(c.schema, c.name));
+            for (const s of a.createsSchemas)
+                producedSchemas.add(s);
+        }
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        // forward: pull producers of what current members need
+        for (const name of [...reason.keys()]) {
+            const a = byName.get(name);
+            const pull = (producer, r) => {
+                if (!producer || reason.has(producer))
+                    return;
+                const pa = byName.get(producer);
+                reason.set(producer, pa.isFixture ? 'fixture' : r);
+                changed = true;
+            };
+            for (const dep of a.dependencies) {
+                pull(byName.has(dep) ? dep : undefined, 'prerequisite');
+            }
+            if (!includePrerequisites)
+                continue;
+            for (const o of a.needsObjects)
+                pull(producerByObject.get(objectKey(o.schema, o.name)), 'prerequisite');
+            for (const s of a.needsSchemas)
+                pull(producerBySchema.get(s), 'prerequisite');
+            for (const role of a.needsRoles)
+                pull(producerByRole.get(role), 'prerequisite');
+        }
+        // reverse: pull attached fixtures that target current members
+        refreshProduced();
+        for (const a of analyses) {
+            if (reason.has(a.name) || !a.isFixture)
+                continue;
+            const objectAttaches = a.needsObjects.some(o => producedObjectKeys.has(objectKey(o.schema, o.name))) ||
+                a.creates.some(c => producedObjectKeys.has(objectKey(c.schema, c.name)));
+            // Schema-scoped fixtures (e.g. ALTER DEFAULT PRIVILEGES IN SCHEMA x) name no
+            // specific object; attach them by schema. Object-scoped fixtures attach only
+            // via their object refs, so a shared schema does not drag in every fixture.
+            const schemaScoped = a.needsObjects.length === 0 && a.creates.length === 0;
+            const schemaAttaches = schemaScoped &&
+                (a.needsSchemas.some(s => producedSchemas.has(s)) ||
+                    a.createsSchemas.some(s => producedSchemas.has(s)));
+            if (objectAttaches || schemaAttaches) {
+                reason.set(a.name, 'fixture');
+                changed = true;
+            }
+        }
+    }
+    const order = analyses.filter(a => reason.has(a.name)).map(a => a.name);
+    const changes = order.map(name => {
+        const a = byName.get(name);
+        return { name, category: a.category, reason: reason.get(name) };
+    });
+    const roles = new Set();
+    const unresolvedObjects = [];
+    const unresolvedObjectKeys = new Set();
+    const unresolvedSchemas = new Set();
+    const unresolvedRoles = new Set();
+    for (const name of order) {
+        const a = byName.get(name);
+        for (const role of a.needsRoles) {
+            roles.add(role);
+            if (!producerByRole.has(role))
+                unresolvedRoles.add(role);
+        }
+        for (const o of a.needsObjects) {
+            const key = objectKey(o.schema, o.name);
+            if (!producerByObject.has(key) && !unresolvedObjectKeys.has(key)) {
+                unresolvedObjectKeys.add(key);
+                unresolvedObjects.push(o);
+            }
+        }
+        for (const s of a.needsSchemas) {
+            if (!producerBySchema.has(s))
+                unresolvedSchemas.add(s);
+        }
+    }
+    return {
+        order,
+        changes,
+        fixtures: changes.filter(c => c.reason === 'fixture').map(c => c.name),
+        prerequisites: changes.filter(c => c.reason === 'prerequisite').map(c => c.name),
+        roles: [...roles],
+        unresolved: {
+            objects: unresolvedObjects,
+            schemas: [...unresolvedSchemas],
+            roles: [...unresolvedRoles]
+        }
+    };
+}

package/esm/index.js

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

package/fixture-closure.d.ts

@@ -0,0 +1,71 @@
+import { CategoryProfile, ChangeCategory } from './categorize';
+import { QualifiedName } from '@pgsql/transform';
+/**
+ * A change plus its deploy SQL. Optional plan `dependencies` (from `pgpm.plan`)
+ * are followed as authoritative prerequisites in addition to AST-derived edges.
+ */
+export interface ClosureInputChange {
+    name: string;
+    sql: string;
+    dependencies?: string[];
+}
+/** Why a change ended up in the closure. */
+export type ClosureReason = 'selected' | 'prerequisite' | 'fixture';
+/**
+ * A change included in the closure, with its category and the reason it was pulled.
+ */
+export interface ClosureChange {
+    name: string;
+    category: ChangeCategory;
+    reason: ClosureReason;
+}
+/**
+ * The fixture closure of a schema slice.
+ *
+ * Everything the selected changes need to actually *work*: schema/functionality
+ * prerequisites they depend on, plus the fixtures that attach to them (policies,
+ * grants, RLS enables, role bindings, seed rows / SPRT-style support changes).
+ * References that nothing in the input produces are surfaced in `unresolved`
+ * rather than silently dropped.
+ */
+export interface FixtureClosure {
+    /** Full closure (selection + prerequisites + fixtures) in input/plan order. */
+    order: string[];
+    /** Per-change detail in the same order as {@link order}. */
+    changes: ClosureChange[];
+    /** Closure members categorized as security/fixtures (attached fixtures). */
+    fixtures: string[];
+    /** Non-selected schema/functionality members pulled in as prerequisites. */
+    prerequisites: string[];
+    /** Roles required across the closure. */
+    roles: string[];
+    /** Requirements no input change produces — explicit, never dropped. */
+    unresolved: {
+        objects: QualifiedName[];
+        schemas: string[];
+        roles: string[];
+    };
+}
+export interface ResolveFixtureClosureOptions {
+    /** Category profile used to label changes (default {@link TIER_PROFILE}). */
+    profile?: CategoryProfile;
+    /**
+     * When false, do not follow AST references from selected changes to their
+     * schema/functionality producers (only pull attached fixtures + plan deps).
+     * Default true.
+     */
+    includePrerequisites?: boolean;
+}
+/**
+ * Resolve the fixture closure of a schema slice.
+ *
+ * Pure and deterministic — no I/O — and runs to a fixpoint in both directions:
+ *   - forward: a selected change pulls in the producers of the objects/schemas/
+ *     roles it references, plus its declared plan dependencies (prerequisites);
+ *   - reverse: any fixture (security/fixtures-tier change) that attaches to an
+ *     object already in the closure is pulled in (attached fixtures), and then
+ *     resolved for its own prerequisites.
+ *
+ * Output order follows the input (plan) order, so it stays deploy-safe.
+ */
+export declare function resolveFixtureClosure(allChanges: ClosureInputChange[], selection: string[], options?: ResolveFixtureClosureOptions): FixtureClosure;

package/fixture-closure.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFixtureClosure = resolveFixtureClosure;
+const categorize_1 = require("./categorize");
+const transform_1 = require("@pgsql/transform");
+function objectKey(schema, name) {
+    return `${schema ?? ''}\u0000${name}`;
+}
+function analyze(change, profile) {
+    const facts = (0, transform_1.classifyStatements)(change.sql);
+    const category = profile.categorize(facts, change.name);
+    const creates = [];
+    const createsSchemas = [];
+    const createsRoles = [];
+    const needsObjects = [];
+    const needsSchemas = new Set();
+    const needsRoles = new Set();
+    for (const f of facts) {
+        for (const c of f.creates) {
+            if (f.kind === 'schema')
+                createsSchemas.push(c.name);
+            else {
+                creates.push(c);
+                if (c.schema)
+                    needsSchemas.add(c.schema);
+            }
+        }
+        if (f.nodeTag === 'CreateRoleStmt')
+            createsRoles.push(...f.roles);
+        for (const r of [...f.references, ...f.fkTargets]) {
+            if (r.schema)
+                needsObjects.push(r);
+        }
+        for (const s of f.referencedSchemas)
+            needsSchemas.add(s);
+    }
+    const created = new Set(createsRoles);
+    for (const f of facts) {
+        if (f.nodeTag === 'CreateRoleStmt')
+            continue;
+        for (const role of f.roles)
+            if (!created.has(role))
+                needsRoles.add(role);
+    }
+    for (const s of createsSchemas)
+        needsSchemas.delete(s);
+    return {
+        name: change.name,
+        category,
+        facts,
+        dependencies: change.dependencies ?? [],
+        creates,
+        createsSchemas,
+        createsRoles,
+        needsObjects,
+        needsSchemas: [...needsSchemas],
+        needsRoles: [...needsRoles],
+        isFixture: category === 'security' || category === 'fixtures'
+    };
+}
+/**
+ * Resolve the fixture closure of a schema slice.
+ *
+ * Pure and deterministic — no I/O — and runs to a fixpoint in both directions:
+ *   - forward: a selected change pulls in the producers of the objects/schemas/
+ *     roles it references, plus its declared plan dependencies (prerequisites);
+ *   - reverse: any fixture (security/fixtures-tier change) that attaches to an
+ *     object already in the closure is pulled in (attached fixtures), and then
+ *     resolved for its own prerequisites.
+ *
+ * Output order follows the input (plan) order, so it stays deploy-safe.
+ */
+function resolveFixtureClosure(allChanges, selection, options = {}) {
+    const profile = options.profile ?? categorize_1.TIER_PROFILE;
+    const includePrerequisites = options.includePrerequisites ?? true;
+    const analyses = allChanges.map(c => analyze(c, profile));
+    const byName = new Map(analyses.map(a => [a.name, a]));
+    const producerByObject = new Map();
+    const producerBySchema = new Map();
+    const producerByRole = new Map();
+    for (const a of analyses) {
+        for (const c of a.creates) {
+            const key = objectKey(c.schema, c.name);
+            if (!producerByObject.has(key))
+                producerByObject.set(key, a.name);
+        }
+        for (const s of a.createsSchemas) {
+            if (!producerBySchema.has(s))
+                producerBySchema.set(s, a.name);
+        }
+        for (const r of a.createsRoles) {
+            if (!producerByRole.has(r))
+                producerByRole.set(r, a.name);
+        }
+    }
+    const reason = new Map();
+    for (const name of selection) {
+        if (byName.has(name))
+            reason.set(name, 'selected');
+    }
+    const producedObjectKeys = new Set();
+    const producedSchemas = new Set();
+    const refreshProduced = () => {
+        producedObjectKeys.clear();
+        producedSchemas.clear();
+        for (const name of reason.keys()) {
+            const a = byName.get(name);
+            for (const c of a.creates)
+                producedObjectKeys.add(objectKey(c.schema, c.name));
+            for (const s of a.createsSchemas)
+                producedSchemas.add(s);
+        }
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        // forward: pull producers of what current members need
+        for (const name of [...reason.keys()]) {
+            const a = byName.get(name);
+            const pull = (producer, r) => {
+                if (!producer || reason.has(producer))
+                    return;
+                const pa = byName.get(producer);
+                reason.set(producer, pa.isFixture ? 'fixture' : r);
+                changed = true;
+            };
+            for (const dep of a.dependencies) {
+                pull(byName.has(dep) ? dep : undefined, 'prerequisite');
+            }
+            if (!includePrerequisites)
+                continue;
+            for (const o of a.needsObjects)
+                pull(producerByObject.get(objectKey(o.schema, o.name)), 'prerequisite');
+            for (const s of a.needsSchemas)
+                pull(producerBySchema.get(s), 'prerequisite');
+            for (const role of a.needsRoles)
+                pull(producerByRole.get(role), 'prerequisite');
+        }
+        // reverse: pull attached fixtures that target current members
+        refreshProduced();
+        for (const a of analyses) {
+            if (reason.has(a.name) || !a.isFixture)
+                continue;
+            const objectAttaches = a.needsObjects.some(o => producedObjectKeys.has(objectKey(o.schema, o.name))) ||
+                a.creates.some(c => producedObjectKeys.has(objectKey(c.schema, c.name)));
+            // Schema-scoped fixtures (e.g. ALTER DEFAULT PRIVILEGES IN SCHEMA x) name no
+            // specific object; attach them by schema. Object-scoped fixtures attach only
+            // via their object refs, so a shared schema does not drag in every fixture.
+            const schemaScoped = a.needsObjects.length === 0 && a.creates.length === 0;
+            const schemaAttaches = schemaScoped &&
+                (a.needsSchemas.some(s => producedSchemas.has(s)) ||
+                    a.createsSchemas.some(s => producedSchemas.has(s)));
+            if (objectAttaches || schemaAttaches) {
+                reason.set(a.name, 'fixture');
+                changed = true;
+            }
+        }
+    }
+    const order = analyses.filter(a => reason.has(a.name)).map(a => a.name);
+    const changes = order.map(name => {
+        const a = byName.get(name);
+        return { name, category: a.category, reason: reason.get(name) };
+    });
+    const roles = new Set();
+    const unresolvedObjects = [];
+    const unresolvedObjectKeys = new Set();
+    const unresolvedSchemas = new Set();
+    const unresolvedRoles = new Set();
+    for (const name of order) {
+        const a = byName.get(name);
+        for (const role of a.needsRoles) {
+            roles.add(role);
+            if (!producerByRole.has(role))
+                unresolvedRoles.add(role);
+        }
+        for (const o of a.needsObjects) {
+            const key = objectKey(o.schema, o.name);
+            if (!producerByObject.has(key) && !unresolvedObjectKeys.has(key)) {
+                unresolvedObjectKeys.add(key);
+                unresolvedObjects.push(o);
+            }
+        }
+        for (const s of a.needsSchemas) {
+            if (!producerBySchema.has(s))
+                unresolvedSchemas.add(s);
+        }
+    }
+    return {
+        order,
+        changes,
+        fixtures: changes.filter(c => c.reason === 'fixture').map(c => c.name),
+        prerequisites: changes.filter(c => c.reason === 'prerequisite').map(c => c.name),
+        roles: [...roles],
+        unresolved: {
+            objects: unresolvedObjects,
+            schemas: [...unresolvedSchemas],
+            roles: [...unresolvedRoles]
+        }
+    };
+}

package/index.d.ts

@@ -0,0 +1,7 @@
+export * from '@pgsql/transform';
+export type { BundleScriptContext, NamespaceValidatorOptions, SchemaTranspiler, SchemaTranspilerOptions, } from './bundle-driver';
+export { 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';
+export { resolveFixtureClosure } from './fixture-closure';

package/index.js

@@ -0,0 +1,27 @@
+"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 __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;
+__exportStar(require("@pgsql/transform"), exports);
+var bundle_driver_1 = require("./bundle-driver");
+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");
+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 fixture_closure_1 = require("./fixture-closure");
+Object.defineProperty(exports, "resolveFixtureClosure", { enumerable: true, get: function () { return fixture_closure_1.resolveFixtureClosure; } });

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pgpmjs/transform",
+  "version": "0.2.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",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pgpm",
+    "pgpmjs",
+    "transform",
+    "classify",
+    "plpgsql"
+  ],
+  "devDependencies": {
+    "@pgpmjs/bundle": "^0.3.2",
+    "makage": "^0.3.0"
+  },
+  "dependencies": {
+    "@pgsql/transform": "^18.3.1",
+    "plpgsql-parser": "^18.2.1"
+  },
+  "gitHead": "cc1b2af2c73c23b99a221e6bd8a8ba76c7ce79e6"
+}