@pgpmjs/transform 0.17.0 → 0.19.0

package/bundle-driver.d.ts

@@ -7,7 +7,7 @@
  * purpose — no dependency on `@pgpmjs/bundle`/`@pgpmjs/core` — so the driver
  * stays a pure function factory over `transformSql` and `classifyStatements`.
  */
-import { ExtensionDefinition, ExtensionRouteSpec, ExtensionRouter, ExtensionTransformResult, RoleRouteSpec, RoleTransformResult, SchemaRouter, SchemaTransformResult, TransformSqlOptions } from '@pgsql/transform';
+import { ExtensionDefinition, ExtensionRouter, ExtensionRouteSpec, 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;

package/catalog-check.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Structural catalog snapshot + equivalence check, used by
+ * `pgpm transform --check` to prove a transform is lossless: deploy the
+ * original and the transformed module(s) into two scratch databases and
+ * assert the resulting catalogs describe the same schema.
+ *
+ * The snapshot is intentionally order-insensitive per object class (objects
+ * are keyed by identity and compared by definition), but column order within
+ * a table IS part of the comparison — the dials pipeline preserves it.
+ */
+/** Minimal query surface: satisfied by pg Pool/PoolClient and test clients. */
+export interface CatalogQueryable {
+    query(text: string): Promise<{
+        rows: any[];
+    }>;
+}
+/** Catalog snapshot: object identity -> normalized definition. */
+export interface CatalogSnapshot {
+    schemas: Record<string, string>;
+    tables: Record<string, string>;
+    columns: Record<string, string>;
+    constraints: Record<string, string>;
+    indexes: Record<string, string>;
+    functions: Record<string, string>;
+    triggers: Record<string, string>;
+    policies: Record<string, string>;
+    rls: Record<string, string>;
+    grants: Record<string, string>;
+}
+/**
+ * Snapshot the user-schema surface of a database: schemas, tables, columns,
+ * constraints, indexes, functions, triggers, policies, RLS flags, and table
+ * grants. System schemas, `public`, and the pgpm ledger are excluded.
+ */
+export declare const snapshotCatalog: (db: CatalogQueryable) => Promise<CatalogSnapshot>;
+/**
+ * Column-order-insensitive view of a snapshot. Migrations that drop and add
+ * columns can never reproduce a fresh deploy's physical column order
+ * (Postgres appends), so migration-equivalence checks (`pgpm diff --verify`)
+ * compare columns by name and definition only.
+ */
+export declare const withoutColumnOrder: (snap: CatalogSnapshot) => CatalogSnapshot;
+/**
+ * Compare two catalog snapshots. Returns a flat list of human-readable
+ * differences; an empty list means the catalogs are structurally equivalent.
+ */
+export declare const diffCatalogSnapshots: (a: CatalogSnapshot, b: CatalogSnapshot) => string[];

package/catalog-check.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCatalogSnapshots = exports.withoutColumnOrder = exports.snapshotCatalog = void 0;
+const SYSTEM_SCHEMAS = `('pg_catalog', 'information_schema', 'pg_toast', 'pgpm_migrate', 'public')`;
+const record = (rows, key, value) => {
+    const out = {};
+    for (const row of rows)
+        out[key(row)] = value(row);
+    return out;
+};
+/**
+ * Snapshot the user-schema surface of a database: schemas, tables, columns,
+ * constraints, indexes, functions, triggers, policies, RLS flags, and table
+ * grants. System schemas, `public`, and the pgpm ledger are excluded.
+ */
+const snapshotCatalog = async (db) => {
+    const schemas = await db.query(`
+    SELECT nspname FROM pg_namespace
+    WHERE nspname NOT IN ${SYSTEM_SCHEMAS} AND nspname NOT LIKE 'pg_temp%' AND nspname NOT LIKE 'pg_toast%'
+    ORDER BY nspname
+  `);
+    const tables = await db.query(`
+    SELECT table_schema, table_name FROM information_schema.tables
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS} AND table_type = 'BASE TABLE'
+  `);
+    const columns = await db.query(`
+    SELECT table_schema, table_name, column_name, ordinal_position,
+           data_type, is_nullable, column_default, character_maximum_length
+    FROM information_schema.columns
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const constraints = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, c.conname,
+           pg_get_constraintdef(c.oid) AS def
+    FROM pg_constraint c
+    JOIN pg_class cl ON cl.oid = c.conrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const indexes = await db.query(`
+    SELECT schemaname, tablename, indexname, indexdef
+    FROM pg_indexes WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const functions = await db.query(`
+    SELECT n.nspname AS schema, p.proname,
+           pg_get_function_identity_arguments(p.oid) AS args,
+           pg_get_functiondef(p.oid) AS def
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const triggers = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, t.tgname,
+           pg_get_triggerdef(t.oid) AS def
+    FROM pg_trigger t
+    JOIN pg_class cl ON cl.oid = t.tgrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE NOT t.tgisinternal AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const policies = await db.query(`
+    SELECT schemaname, tablename, policyname, permissive, roles, cmd,
+           qual, with_check
+    FROM pg_policies WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const rls = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table,
+           cl.relrowsecurity, cl.relforcerowsecurity
+    FROM pg_class cl
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE cl.relkind = 'r' AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const grants = await db.query(`
+    SELECT table_schema, table_name, grantee, privilege_type
+    FROM information_schema.role_table_grants
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+      AND grantee <> (SELECT current_user)
+  `);
+    return {
+        schemas: record(schemas.rows, r => r.nspname, () => 'schema'),
+        tables: record(tables.rows, r => `${r.table_schema}.${r.table_name}`, () => 'table'),
+        columns: record(columns.rows, r => `${r.table_schema}.${r.table_name}.${r.column_name}`, r => `#${r.ordinal_position} ${r.data_type}${r.character_maximum_length ? `(${r.character_maximum_length})` : ''} nullable=${r.is_nullable} default=${r.column_default ?? 'none'}`),
+        constraints: record(constraints.rows, r => `${r.schema}.${r.table}.${r.conname}`, r => r.def),
+        indexes: record(indexes.rows, r => `${r.schemaname}.${r.tablename}.${r.indexname}`, r => r.indexdef),
+        functions: record(functions.rows, r => `${r.schema}.${r.proname}(${r.args})`, r => r.def),
+        triggers: record(triggers.rows, r => `${r.schema}.${r.table}.${r.tgname}`, r => r.def),
+        policies: record(policies.rows, r => `${r.schemaname}.${r.tablename}.${r.policyname}`, r => `permissive=${r.permissive} roles=${[...(r.roles ?? [])].sort().join(',')} cmd=${r.cmd} qual=${r.qual ?? 'none'} check=${r.with_check ?? 'none'}`),
+        rls: record(rls.rows, r => `${r.schema}.${r.table}`, r => `enabled=${r.relrowsecurity} forced=${r.relforcerowsecurity}`),
+        grants: record(grants.rows, r => `${r.table_schema}.${r.table_name}:${r.grantee}:${r.privilege_type}`, () => 'grant')
+    };
+};
+exports.snapshotCatalog = snapshotCatalog;
+/**
+ * Column-order-insensitive view of a snapshot. Migrations that drop and add
+ * columns can never reproduce a fresh deploy's physical column order
+ * (Postgres appends), so migration-equivalence checks (`pgpm diff --verify`)
+ * compare columns by name and definition only.
+ */
+const withoutColumnOrder = (snap) => {
+    const columns = {};
+    for (const [key, value] of Object.entries(snap.columns)) {
+        columns[key] = value.replace(/^#\d+ /, '');
+    }
+    return { ...snap, columns };
+};
+exports.withoutColumnOrder = withoutColumnOrder;
+/**
+ * Compare two catalog snapshots. Returns a flat list of human-readable
+ * differences; an empty list means the catalogs are structurally equivalent.
+ */
+const diffCatalogSnapshots = (a, b) => {
+    const diffs = [];
+    for (const section of Object.keys(a)) {
+        const left = a[section];
+        const right = b[section];
+        for (const key of Object.keys(left).sort()) {
+            if (!(key in right)) {
+                diffs.push(`${section}: ${key} only in original`);
+            }
+            else if (left[key] !== right[key]) {
+                diffs.push(`${section}: ${key} differs\n  original:    ${left[key]}\n  transformed: ${right[key]}`);
+            }
+        }
+        for (const key of Object.keys(right).sort()) {
+            if (!(key in left))
+                diffs.push(`${section}: ${key} only in transformed`);
+        }
+    }
+    return diffs;
+};
+exports.diffCatalogSnapshots = diffCatalogSnapshots;

package/esm/catalog-check.js

@@ -0,0 +1,124 @@
+const SYSTEM_SCHEMAS = `('pg_catalog', 'information_schema', 'pg_toast', 'pgpm_migrate', 'public')`;
+const record = (rows, key, value) => {
+    const out = {};
+    for (const row of rows)
+        out[key(row)] = value(row);
+    return out;
+};
+/**
+ * Snapshot the user-schema surface of a database: schemas, tables, columns,
+ * constraints, indexes, functions, triggers, policies, RLS flags, and table
+ * grants. System schemas, `public`, and the pgpm ledger are excluded.
+ */
+export const snapshotCatalog = async (db) => {
+    const schemas = await db.query(`
+    SELECT nspname FROM pg_namespace
+    WHERE nspname NOT IN ${SYSTEM_SCHEMAS} AND nspname NOT LIKE 'pg_temp%' AND nspname NOT LIKE 'pg_toast%'
+    ORDER BY nspname
+  `);
+    const tables = await db.query(`
+    SELECT table_schema, table_name FROM information_schema.tables
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS} AND table_type = 'BASE TABLE'
+  `);
+    const columns = await db.query(`
+    SELECT table_schema, table_name, column_name, ordinal_position,
+           data_type, is_nullable, column_default, character_maximum_length
+    FROM information_schema.columns
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const constraints = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, c.conname,
+           pg_get_constraintdef(c.oid) AS def
+    FROM pg_constraint c
+    JOIN pg_class cl ON cl.oid = c.conrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const indexes = await db.query(`
+    SELECT schemaname, tablename, indexname, indexdef
+    FROM pg_indexes WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const functions = await db.query(`
+    SELECT n.nspname AS schema, p.proname,
+           pg_get_function_identity_arguments(p.oid) AS args,
+           pg_get_functiondef(p.oid) AS def
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const triggers = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table, t.tgname,
+           pg_get_triggerdef(t.oid) AS def
+    FROM pg_trigger t
+    JOIN pg_class cl ON cl.oid = t.tgrelid
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE NOT t.tgisinternal AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const policies = await db.query(`
+    SELECT schemaname, tablename, policyname, permissive, roles, cmd,
+           qual, with_check
+    FROM pg_policies WHERE schemaname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const rls = await db.query(`
+    SELECT n.nspname AS schema, cl.relname AS table,
+           cl.relrowsecurity, cl.relforcerowsecurity
+    FROM pg_class cl
+    JOIN pg_namespace n ON n.oid = cl.relnamespace
+    WHERE cl.relkind = 'r' AND n.nspname NOT IN ${SYSTEM_SCHEMAS}
+  `);
+    const grants = await db.query(`
+    SELECT table_schema, table_name, grantee, privilege_type
+    FROM information_schema.role_table_grants
+    WHERE table_schema NOT IN ${SYSTEM_SCHEMAS}
+      AND grantee <> (SELECT current_user)
+  `);
+    return {
+        schemas: record(schemas.rows, r => r.nspname, () => 'schema'),
+        tables: record(tables.rows, r => `${r.table_schema}.${r.table_name}`, () => 'table'),
+        columns: record(columns.rows, r => `${r.table_schema}.${r.table_name}.${r.column_name}`, r => `#${r.ordinal_position} ${r.data_type}${r.character_maximum_length ? `(${r.character_maximum_length})` : ''} nullable=${r.is_nullable} default=${r.column_default ?? 'none'}`),
+        constraints: record(constraints.rows, r => `${r.schema}.${r.table}.${r.conname}`, r => r.def),
+        indexes: record(indexes.rows, r => `${r.schemaname}.${r.tablename}.${r.indexname}`, r => r.indexdef),
+        functions: record(functions.rows, r => `${r.schema}.${r.proname}(${r.args})`, r => r.def),
+        triggers: record(triggers.rows, r => `${r.schema}.${r.table}.${r.tgname}`, r => r.def),
+        policies: record(policies.rows, r => `${r.schemaname}.${r.tablename}.${r.policyname}`, r => `permissive=${r.permissive} roles=${[...(r.roles ?? [])].sort().join(',')} cmd=${r.cmd} qual=${r.qual ?? 'none'} check=${r.with_check ?? 'none'}`),
+        rls: record(rls.rows, r => `${r.schema}.${r.table}`, r => `enabled=${r.relrowsecurity} forced=${r.relforcerowsecurity}`),
+        grants: record(grants.rows, r => `${r.table_schema}.${r.table_name}:${r.grantee}:${r.privilege_type}`, () => 'grant')
+    };
+};
+/**
+ * Column-order-insensitive view of a snapshot. Migrations that drop and add
+ * columns can never reproduce a fresh deploy's physical column order
+ * (Postgres appends), so migration-equivalence checks (`pgpm diff --verify`)
+ * compare columns by name and definition only.
+ */
+export const withoutColumnOrder = (snap) => {
+    const columns = {};
+    for (const [key, value] of Object.entries(snap.columns)) {
+        columns[key] = value.replace(/^#\d+ /, '');
+    }
+    return { ...snap, columns };
+};
+/**
+ * Compare two catalog snapshots. Returns a flat list of human-readable
+ * differences; an empty list means the catalogs are structurally equivalent.
+ */
+export const diffCatalogSnapshots = (a, b) => {
+    const diffs = [];
+    for (const section of Object.keys(a)) {
+        const left = a[section];
+        const right = b[section];
+        for (const key of Object.keys(left).sort()) {
+            if (!(key in right)) {
+                diffs.push(`${section}: ${key} only in original`);
+            }
+            else if (left[key] !== right[key]) {
+                diffs.push(`${section}: ${key} differs\n  original:    ${left[key]}\n  transformed: ${right[key]}`);
+            }
+        }
+        for (const key of Object.keys(right).sort()) {
+            if (!(key in left))
+                diffs.push(`${section}: ${key} only in transformed`);
+        }
+    }
+    return diffs;
+};

package/esm/fixture-closure.js

@@ -1,5 +1,5 @@
-import { TIER_PROFILE } from './categorize';
 import { classifyStatements } from '@pgsql/transform';
+import { TIER_PROFILE } from './categorize';
 function objectKey(schema, name) {
     return `${schema ?? ''}\u0000${name}`;
 }

package/esm/index.js

@@ -1,10 +1,15 @@
-export * from '@pgsql/transform';
-export { loadModule } from 'plpgsql-parser';
 export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
-export { defaultChangeName, restructureChanges, } from './granularity-driver';
-export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
-export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
+export { diffCatalogSnapshots, snapshotCatalog, withoutColumnOrder } from './catalog-check';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export { resolveFixtureClosure } from './fixture-closure';
-export { classifyScript, isStubScript, regenerateScripts, } from './regen';
+export { defaultChangeName, restructureChanges, } from './granularity-driver';
+export { checkOverwrite, writeControlFile, writeModule } from './module-emit';
+export { loadModuleSource, stripTransactionWrapper } from './module-source';
+export { parsePartitionConfig, partitionExportRows } from './partition';
+export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
 export { emitSqlProgram, parseSqlProgram } from './program';
+export { classifyScript, isStubScript, regenerateScripts, } from './regen';
+export { EXPORT_GRANULARITIES, isExportGranularity, restructureExportRows } from './restructure';
+export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
+export * from '@pgsql/transform';
+export { loadModule } from 'plpgsql-parser';

package/esm/module-emit.js

@@ -0,0 +1,65 @@
+/**
+ * Module emission — the single seam every dials command renders through.
+ *
+ * The engine (semantic diff, granularity, partition) produces plan-ordered
+ * {@link PgpmRow}s; a {@link PgpmModuleModel} is just those rows plus the
+ * module's name and control-file requires. `writeModule` is the one writer
+ * that turns a model into an on-disk pgpm module (`.control` + `pgpm.plan` +
+ * deploy/revert/verify trees) — so `pgpm diff`, `pgpm transform`, and
+ * `pgpm import` all emit byte-identical module layouts instead of each
+ * carrying its own copy of the writer.
+ */
+import { writePgpmFiles, writePgpmPlan } from '@pgpmjs/ast';
+import * as fs from 'fs';
+import * as path from 'path';
+/** Write a module's Postgres extension `.control` file. */
+export const writeControlFile = (dir, name, requires) => {
+    const lines = [
+        `# ${name} extension`,
+        `comment = '${name} extension'`,
+        `default_version = '0.0.1'`,
+        `relocatable = false`,
+        `superuser = false`
+    ];
+    if (requires.length) {
+        lines.push(`requires = '${requires.join(',')}'`);
+    }
+    fs.writeFileSync(path.join(dir, `${name}.control`), lines.join('\n') + '\n');
+};
+/**
+ * Write a {@link PgpmModuleModel} to `<outBase>/<name>` as a full pgpm module:
+ * a `.control` file, `pgpm.plan`, and deploy/revert/verify script trees.
+ * The deploy/revert/verify directories are cleared first so a re-emit never
+ * leaves stale scripts behind. Returns the module directory.
+ */
+export const writeModule = (outBase, model, extraRequires = []) => {
+    const dir = path.join(outBase, model.name);
+    fs.rmSync(path.join(dir, 'deploy'), { recursive: true, force: true });
+    fs.rmSync(path.join(dir, 'revert'), { recursive: true, force: true });
+    fs.rmSync(path.join(dir, 'verify'), { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    writeControlFile(dir, model.name, [...extraRequires, ...model.requires]);
+    const opts = {
+        outdir: outBase,
+        name: model.name,
+        replacer: (str) => str.split('constructive-extension-name').join(model.name)
+    };
+    writePgpmPlan(model.rows, opts);
+    writePgpmFiles(model.rows, opts);
+    return dir;
+};
+/**
+ * Guard against clobbering: writing into the source directory requires
+ * `--write`, as does overwriting any existing package directory.
+ */
+export const checkOverwrite = (targetDir, sourcePath, write) => {
+    const resolvedTarget = path.resolve(targetDir);
+    const resolvedSource = path.resolve(sourcePath);
+    if (resolvedTarget === resolvedSource && !write) {
+        return `Refusing to overwrite the source module at ${resolvedSource} (pass --write to allow).`;
+    }
+    if (resolvedTarget !== resolvedSource && fs.existsSync(resolvedTarget) && !write) {
+        return `Output directory ${resolvedTarget} already exists (pass --write to overwrite).`;
+    }
+    return null;
+};

package/esm/module-source.js

@@ -0,0 +1,54 @@
+/**
+ * Module ingestion for the dials pipeline: load an on-disk pgpm module into
+ * the flattened, classified change list the transform/partition drivers
+ * consume. `pgpm transform` uses this today; a future `pgpm import` (dumps)
+ * and `pgpm diff` are expected to reuse the same seam.
+ */
+import { parsePgpmHeader, parsePlanFile, readScript } from '@pgpmjs/ast';
+import * as path from 'path';
+const TX_LINE = /^\s*(BEGIN|COMMIT|ROLLBACK)\s*;\s*$/i;
+/**
+ * Strip the transaction wrapper some modules carry inside their scripts
+ * (standalone `BEGIN;` / `COMMIT;` / `ROLLBACK;` lines). The caller owns
+ * transaction control.
+ */
+export const stripTransactionWrapper = (sql) => sql
+    .split('\n')
+    .filter(line => !TX_LINE.test(line))
+    .join('\n')
+    .trim();
+/**
+ * Load a pgpm module from disk: parse pgpm.plan and read each change's
+ * deploy script, stripping pgpm headers and transaction wrappers so the
+ * result can be flattened straight into the dials pipeline
+ * (`restructureChanges` / `partitionUnits`).
+ */
+export const loadModuleSource = (moduleDir) => {
+    const modulePath = path.resolve(moduleDir);
+    const planResult = parsePlanFile(path.join(modulePath, 'pgpm.plan'));
+    if (!planResult.data) {
+        const reasons = planResult.errors.map(e => e.message).join(', ');
+        throw new Error(`Failed to parse pgpm.plan in ${modulePath}: ${reasons}`);
+    }
+    const warnings = [];
+    const changes = [];
+    for (const change of planResult.data.changes) {
+        const raw = readScript(modulePath, 'deploy', change.name);
+        if (!raw) {
+            warnings.push(`${change.name}: no deploy script found, skipping`);
+            continue;
+        }
+        const { body } = parsePgpmHeader(raw);
+        changes.push({
+            name: change.name,
+            dependencies: change.dependencies ?? [],
+            deploy: stripTransactionWrapper(body)
+        });
+    }
+    return {
+        name: planResult.data.package,
+        modulePath,
+        changes,
+        warnings
+    };
+};

package/esm/partition.js

@@ -0,0 +1,89 @@
+import * as fs from 'fs';
+import { loadModule } from 'plpgsql-parser';
+import { partitionUnits } from './partition-driver';
+import { regenerateScripts } from './regen';
+const PATH_STYLES = ['directory', 'flat'];
+/**
+ * Parse and validate a partition config file (JSON matching
+ * `PartitionConfig`: rules, defaultPackage, optional style/splitRiders).
+ * Throws with a message naming the offending field.
+ */
+export const parsePartitionConfig = (filePath) => {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Partition config not found: ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Partition config is not valid JSON (${filePath}): ${err?.message ?? err}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Partition config must be a JSON object (${filePath})`);
+    }
+    if (typeof parsed.defaultPackage !== 'string' || !parsed.defaultPackage) {
+        throw new Error('Partition config: "defaultPackage" must be a non-empty string');
+    }
+    if (!Array.isArray(parsed.rules)) {
+        throw new Error('Partition config: "rules" must be an array');
+    }
+    parsed.rules.forEach((rule, i) => {
+        if (typeof rule !== 'object' || rule === null) {
+            throw new Error(`Partition config: rules[${i}] must be an object`);
+        }
+        if (typeof rule.package !== 'string' || !rule.package) {
+            throw new Error(`Partition config: rules[${i}].package must be a non-empty string`);
+        }
+        if (!Array.isArray(rule.select) || rule.select.length === 0) {
+            throw new Error(`Partition config: rules[${i}].select must be a non-empty array of selectors`);
+        }
+    });
+    if (parsed.style !== undefined && !PATH_STYLES.includes(parsed.style)) {
+        throw new Error(`Partition config: "style" must be one of: ${PATH_STYLES.join(', ')}`);
+    }
+    if (parsed.splitRiders !== undefined && !Array.isArray(parsed.splitRiders)) {
+        throw new Error('Partition config: "splitRiders" must be an array of statement kinds');
+    }
+    return parsed;
+};
+/**
+ * Partition changes into packages and generate revert/verify for every
+ * emitted change. Cross-package dependencies keep the `<pkg>:<path>`
+ * convention in `deps`. May throw `PartitionCycleError`.
+ */
+export const partitionExportRows = async (rows, config) => {
+    await loadModule();
+    const input = rows.map(row => ({
+        name: row.deploy,
+        dependencies: row.deps ?? [],
+        deploy: row.content
+    }));
+    const { packages, warnings } = partitionUnits(input, config);
+    const result = packages.map(pkg => ({
+        name: pkg.name,
+        requires: pkg.requires,
+        rows: pkg.changes.map(change => {
+            const scripts = regenerateScripts(change.deploy);
+            for (const warning of scripts.revert.warnings) {
+                warnings.push(`${pkg.name}:${change.name}: ${warning}`);
+            }
+            for (const warning of scripts.verify.warnings) {
+                warnings.push(`${pkg.name}:${change.name}: ${warning}`);
+            }
+            return {
+                name: change.name,
+                deploy: change.name,
+                deps: change.dependencies,
+                content: change.deploy,
+                revert: scripts.revert.sql,
+                verify: scripts.verify.sql
+            };
+        })
+    }));
+    return { packages: result, warnings };
+};

package/esm/restructure.js

@@ -0,0 +1,62 @@
+import { alterationPathFor, pathFor } from '@pgpmjs/naming-spec';
+import { identityOf } from '@pgsql/transform';
+import { loadModule } from 'plpgsql-parser';
+import { restructureChanges } from './granularity-driver';
+export const EXPORT_GRANULARITIES = ['atomic', 'object', 'consolidated'];
+export const isExportGranularity = (value) => typeof value === 'string' && EXPORT_GRANULARITIES.includes(value);
+/**
+ * Restructure exported migration rows to the target granularity.
+ *
+ * The rows' deploy SQL is flattened in export order, restructured, and
+ * re-sliced into per-object changes whose paths come from the naming spec and
+ * whose deps come from the statement graph. When two changes derive the same
+ * path (the same object altered again), later occurrences get the spec's
+ * alteration convention via `alterationPathFor` (monotonic per-parent
+ * counter), with the parent added to their deps.
+ *
+ * Revert/verify scripts are not carried through from the original rows (the
+ * restructured grouping no longer matches them one-to-one); instead each
+ * change gets scripts generated from its own statements via
+ * `revertFor`/`verifyFor` (drops in reverse topological order, one existence
+ * check per created object).
+ */
+export const restructureExportRows = async (rows, granularity, options = {}) => {
+    await loadModule();
+    const style = options.naming ?? 'directory';
+    const changeName = (facts) => {
+        const identity = identityOf(facts);
+        if (identity)
+            return pathFor(identity, { style });
+        return 'misc/statements';
+    };
+    const { changes, warnings } = restructureChanges(rows.map(row => ({
+        name: row.deploy,
+        dependencies: row.deps ?? [],
+        deploy: row.content
+    })), { granularity, changeName });
+    const counters = new Map();
+    const taken = new Set();
+    const restructured = changes.map(change => {
+        let deploy = change.name;
+        const deps = [...change.dependencies];
+        if (taken.has(deploy)) {
+            let n = (counters.get(change.name) ?? 0) + 1;
+            while (taken.has(alterationPathFor(change.name, n)))
+                n++;
+            counters.set(change.name, n);
+            deploy = alterationPathFor(change.name, n);
+            if (!deps.includes(change.name))
+                deps.push(change.name);
+        }
+        taken.add(deploy);
+        return {
+            name: deploy,
+            deploy,
+            deps,
+            content: change.deploy,
+            revert: change.revert,
+            verify: change.verify
+        };
+    });
+    return { rows: restructured, warnings };
+};