@pgpmjs/transform 0.16.0 → 0.17.0

package/esm/index.js

@@ -2,7 +2,9 @@ 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 { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export { resolveFixtureClosure } from './fixture-closure';
+export { classifyScript, isStubScript, regenerateScripts, } from './regen';
 export { emitSqlProgram, parseSqlProgram } from './program';

package/esm/regen.js

@@ -0,0 +1,39 @@
+import { revertFor, verifyFor } from '@pgsql/scripts';
+import { classifyStatements } from '@pgsql/transform';
+/**
+ * Classify a pgpm script's substantive statements: every top-level statement
+ * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
+ */
+export function classifyScript(sql) {
+    return classifyStatements(sql).filter(f => f.nodeTag !== 'TransactionStmt');
+}
+/**
+ * Whether a script is an empty stub: nothing but comments, whitespace, and
+ * a transaction wrapper — no substantive statements. Scaffolded
+ * `-- Add your revert SQL here` files and bare `BEGIN; ... COMMIT;` shells
+ * are stubs. A script that fails to parse is NOT a stub (never treat content
+ * we cannot understand as safe to overwrite).
+ */
+export function isStubScript(sql) {
+    if (!sql || !sql.trim())
+        return true;
+    try {
+        return classifyScript(sql).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate revert and verify scripts (headerless, unwrapped) for one
+ * change's deploy SQL. Statements with no derivable inverse contribute a
+ * `-- revert not derivable: <reason>` comment and a warning; statements
+ * whose effect cannot be existence-checked add a verify warning.
+ */
+export function regenerateScripts(deploySql) {
+    const facts = classifyScript(deploySql);
+    return {
+        revert: revertFor(facts),
+        verify: verifyFor(facts)
+    };
+}

package/esm/semantic-diff-driver.js

@@ -0,0 +1,366 @@
+/**
+ * Semantic diff driver: identity-keyed schema delta between two deploy
+ * surfaces.
+ *
+ * Where `diffBundles` (in `@pgpmjs/bundle`) compares change names and content
+ * digests — which breaks the moment a dial regroups or renames changes — this
+ * driver re-keys the comparison on object identity (`identityOf`), so the
+ * same schema authored at different granularities or partitions diffs as
+ * equal. Objects are compared at the AST level (normalized parse trees, so
+ * formatting never matters); tables are compared column-by-column and
+ * constraint-by-constraint so an added column emits `ALTER TABLE ADD COLUMN`,
+ * not a table rebuild.
+ *
+ * The emitted delta is a set of pgpm changes: DROPs for removed objects
+ * (reverse topological order), then CREATE/ALTER changes for added and
+ * modified objects routed through the granularity pipeline
+ * (`restructureChanges`), so names come from the naming spec and `requires`
+ * from the statement graph — the same derivation every other projection uses.
+ * Every emitted change carries a full deploy/revert/verify triple: drops are
+ * `@pgsql/scripts`' `revertFor` inverses of the object's own deploy
+ * statements (never hand-templated), reverts recreate what was dropped, and
+ * verifies come from `verifyFor`.
+ *
+ * Requires `loadModule()` from `plpgsql-parser` before use.
+ */
+import { pathFor } from '@pgpmjs/naming-spec';
+import { revertFor, verifyFor } from '@pgsql/scripts';
+import { buildStatementGraph, classifyStatements, cleanTree, identityOf } from '@pgsql/transform';
+import { Deparser, parseSync } from 'plpgsql-parser';
+import { restructureChanges } from './granularity-driver';
+const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
+/**
+ * Group one side's script into identity-keyed object units. Statements with
+ * no identity (grants, comments) attach to the unit of the first object they
+ * reference, falling back to the preceding statement's unit; truly homeless
+ * statements are reported via `warnings`.
+ */
+function readSide(sql, warnings, label) {
+    const facts = classifyStatements(sql);
+    const graph = buildStatementGraph(facts);
+    const units = new Map();
+    const order = [];
+    const unitOf = new Array(facts.length).fill(null);
+    const byObject = new Map();
+    facts.forEach((f, i) => {
+        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        if (!text)
+            return;
+        let identity = groupingIdentity(f);
+        if (identity && identity.kind === 'other') {
+            const asTable = identityKey({ kind: 'table', schema: identity.schema, name: identity.name });
+            if (units.has(asTable))
+                identity = units.get(asTable).identity;
+        }
+        let key = null;
+        if (identity) {
+            key = identityKey(identity);
+            if (!units.has(key)) {
+                units.set(key, { identity, statements: [], texts: [] });
+                order.push(key);
+            }
+            if (!identity.table) {
+                byObject.set(`${identity.schema ?? ''}.${identity.name}`, key);
+            }
+        }
+        else {
+            for (const r of f.references) {
+                const host = byObject.get(`${r.schema ?? ''}.${r.name}`);
+                if (host) {
+                    key = host;
+                    break;
+                }
+            }
+            if (!key && i > 0)
+                key = unitOf[i - 1];
+        }
+        if (!key) {
+            warnings.push(`${label}: statement ${i} (${f.kind}) belongs to no object; ignored in the diff`);
+            return;
+        }
+        unitOf[i] = key;
+        const unit = units.get(key);
+        unit.statements.push(i);
+        unit.texts.push(text.endsWith(';') ? text : `${text};`);
+    });
+    return { facts, units, order, graph };
+}
+/**
+ * The identity a statement groups under. Table-shaping statements — ALTER
+ * TABLE column/constraint additions, RLS enablement — fold into their table's
+ * unit so that atomic and consolidated authorships of the same table land in
+ * the same unit and compare shape-to-shape. Generic ALTERs (`kind: 'other'`)
+ * fold in `readSide` when a table unit for the same object already exists.
+ */
+function groupingIdentity(f) {
+    const identity = identityOf(f);
+    if (!identity)
+        return null;
+    if ((f.kind === 'table' || f.kind === 'constraint' || f.kind === 'rls_enable') &&
+        identity.kind !== 'table') {
+        return { kind: 'table', schema: identity.schema, name: identity.table ?? identity.name };
+    }
+    return identity;
+}
+/** Normalized-AST fingerprint of one statement (formatting/position-proof). */
+function fingerprint(text) {
+    const parsed = parseSync(text);
+    return JSON.stringify(cleanTree(parsed.sql.stmts.map(s => s.stmt)));
+}
+/** Multiset fingerprint of a whole unit. */
+const unitFingerprint = (unit) => unit.texts.map(fingerprint).sort().join('\n');
+/**
+ * Fold a table unit's statements (CREATE TABLE plus any ALTER TABLE
+ * ADD COLUMN / ADD CONSTRAINT) into an effective shape, so atomic and
+ * consolidated authorships of the same table compare equal.
+ */
+function tableShape(unit) {
+    const shape = { relation: null, columns: new Map(), extras: new Map() };
+    const addColumn = (node) => {
+        const def = node;
+        const clean = cleanTree(node);
+        shape.columns.set(def.colname ?? '', { def: clean, print: JSON.stringify(clean) });
+    };
+    const addExtra = (node) => {
+        const clean = cleanTree(node);
+        shape.extras.set(JSON.stringify(clean), clean);
+    };
+    for (const text of unit.texts) {
+        for (const raw of parseSync(text).sql.stmts) {
+            const stmt = raw.stmt;
+            if (stmt.CreateStmt) {
+                shape.relation = stmt.CreateStmt.relation;
+                const elts = stmt.CreateStmt.tableElts ?? [];
+                for (const elt of elts) {
+                    if (elt.ColumnDef)
+                        addColumn(elt.ColumnDef);
+                    else
+                        addExtra(elt);
+                }
+            }
+            else if (stmt.AlterTableStmt) {
+                shape.relation ??= stmt.AlterTableStmt.relation;
+                const cmds = stmt.AlterTableStmt.cmds ?? [];
+                for (const cmd of cmds) {
+                    const at = cmd.AlterTableCmd;
+                    if (!at)
+                        continue;
+                    const def = at.def;
+                    if (at.subtype === 'AT_AddColumn' && def?.ColumnDef) {
+                        addColumn(def.ColumnDef);
+                    }
+                    else {
+                        addExtra({ AlterTableCmd: at });
+                    }
+                }
+            }
+            else {
+                addExtra(stmt);
+            }
+        }
+    }
+    return shape;
+}
+const deparseStmt = (node) => `${Deparser.deparse(node, { pretty: false })};`;
+/** Column-level ALTERs between two table shapes. */
+function diffTable(from, to, diff, warnings) {
+    const stmts = [];
+    const relation = to.relation ?? from.relation;
+    const alter = (cmd) => deparseStmt({
+        AlterTableStmt: {
+            relation,
+            cmds: [{ AlterTableCmd: { behavior: 'DROP_RESTRICT', ...cmd } }],
+            objtype: 'OBJECT_TABLE'
+        }
+    });
+    diff.columnsAdded = [];
+    diff.columnsRemoved = [];
+    diff.columnsModified = [];
+    for (const [name, col] of to.columns) {
+        const prior = from.columns.get(name);
+        if (!prior) {
+            diff.columnsAdded.push(name);
+            stmts.push(alter({ subtype: 'AT_AddColumn', def: { ColumnDef: col.def } }));
+        }
+        else if (prior.print !== col.print) {
+            diff.columnsModified.push(name);
+            const fromDef = prior.def;
+            const toDef = col.def;
+            const typeChanged = JSON.stringify(fromDef.typeName) !== JSON.stringify(toDef.typeName);
+            const restChanged = JSON.stringify({ ...fromDef, typeName: null }) !==
+                JSON.stringify({ ...toDef, typeName: null });
+            if (typeChanged) {
+                stmts.push(alter({
+                    subtype: 'AT_AlterColumnType',
+                    name,
+                    def: { ColumnDef: { typeName: toDef.typeName } }
+                }));
+            }
+            if (restChanged) {
+                warnings.push(`${diff.path}: column "${name}" changed beyond its type (constraints/defaults); emit a manual ALTER`);
+            }
+        }
+    }
+    for (const name of from.columns.keys()) {
+        if (!to.columns.has(name)) {
+            diff.columnsRemoved.push(name);
+            stmts.push(alter({ subtype: 'AT_DropColumn', name }));
+        }
+    }
+    for (const [print, extra] of to.extras) {
+        if (!from.extras.has(print)) {
+            const at = extra.AlterTableCmd;
+            if (at)
+                stmts.push(alter(at));
+            else if (extra.Constraint) {
+                stmts.push(alter({ subtype: 'AT_AddConstraint', def: extra }));
+            }
+            else {
+                warnings.push(`${diff.path}: unrecognized added table element; emit a manual ALTER`);
+            }
+        }
+    }
+    for (const [print, extra] of from.extras) {
+        if (to.extras.has(print))
+            continue;
+        const conname = extra.Constraint?.conname
+            ?? extra
+                .AlterTableCmd?.def?.Constraint?.conname;
+        if (conname) {
+            stmts.push(alter({ subtype: 'AT_DropConstraint', name: conname }));
+        }
+        else {
+            warnings.push(`${diff.path}: removed table element has no name to drop; emit a manual ALTER`);
+        }
+    }
+    return stmts;
+}
+/**
+ * Diff two deploy surfaces by object identity and emit the migration delta.
+ *
+ * `from`/`to` are whole deploy scripts (flatten changes in plan order to
+ * diff bundles/modules). The result's `changes` deploy `to`'s shape on top
+ * of `from`: reverse-topological DROPs, then CREATE/ALTERs named and
+ * ordered by `restructureChanges`.
+ */
+export function diffSchemas(from, to, options = {}) {
+    const style = options.style ?? 'directory';
+    const warnings = [];
+    const a = readSide(from, warnings, 'from');
+    const b = readSide(to, warnings, 'to');
+    const objects = [];
+    const forwardSql = [];
+    const modifiedChanges = [];
+    const dropUnits = [];
+    /** `@pgsql/scripts` inverse of a deploy script (drops in reverse topo order). */
+    const inverseOf = (deploy, context) => {
+        const { sql, warnings: w } = revertFor(classifyStatements(deploy));
+        warnings.push(...w.map(x => `${context}: ${x}`));
+        return sql;
+    };
+    /** `@pgsql/scripts` existence checks for a deploy script. */
+    const verifyOf = (deploy, context) => {
+        const { sql, warnings: w } = verifyFor(classifyStatements(deploy));
+        warnings.push(...w.map(x => `${context}: ${x}`));
+        return sql;
+    };
+    for (const key of b.order) {
+        const unit = b.units.get(key);
+        const prior = a.units.get(key);
+        const path = pathFor(unit.identity, { style });
+        if (!prior) {
+            objects.push({ identity: unit.identity, path, delta: 'added' });
+            forwardSql.push(...unit.texts);
+            continue;
+        }
+        if (unit.identity.kind === 'table') {
+            const shapeFrom = tableShape(prior);
+            const shapeTo = tableShape(unit);
+            const diff = { identity: unit.identity, path, delta: 'modified' };
+            const stmts = diffTable(shapeFrom, shapeTo, diff, warnings);
+            const columnsTouched = diff.columnsAdded.length + diff.columnsRemoved.length + diff.columnsModified.length > 0;
+            if (stmts.length > 0 || columnsTouched) {
+                objects.push(diff);
+                if (stmts.length > 0) {
+                    // The inverse alteration is the same diff with the sides swapped.
+                    const scratch = { identity: unit.identity, path, delta: 'modified' };
+                    const deploy = stmts.join('\n');
+                    modifiedChanges.push({
+                        name: `${path}/alter`,
+                        dependencies: [],
+                        deploy,
+                        revert: diffTable(shapeTo, shapeFrom, scratch, []).join('\n'),
+                        verify: verifyOf(deploy, path)
+                    });
+                }
+            }
+            continue;
+        }
+        if (unitFingerprint(prior) !== unitFingerprint(unit)) {
+            objects.push({ identity: unit.identity, path, delta: 'modified' });
+            const priorDeploy = prior.texts.join('\n');
+            const newDeploy = unit.texts.join('\n');
+            modifiedChanges.push({
+                name: path,
+                dependencies: [],
+                deploy: [inverseOf(priorDeploy, path), newDeploy].filter(Boolean).join('\n'),
+                revert: [inverseOf(newDeploy, path), priorDeploy].filter(Boolean).join('\n'),
+                verify: verifyOf(newDeploy, path)
+            });
+        }
+    }
+    for (const key of a.order) {
+        if (b.units.has(key))
+            continue;
+        const unit = a.units.get(key);
+        objects.push({ identity: unit.identity, path: pathFor(unit.identity, { style }), delta: 'removed' });
+        dropUnits.push(unit);
+    }
+    // Removed objects drop in reverse topological order of the `from` graph
+    // (dependents before dependencies), one change per object.
+    const position = new Map(dropUnits.map(u => [u, Math.min(...u.statements.map(s => a.graph.order.indexOf(s)))]));
+    dropUnits.sort((x, y) => position.get(y) - position.get(x));
+    const dropChanges = [];
+    for (const unit of dropUnits) {
+        const path = pathFor(unit.identity, { style });
+        const recreate = unit.texts.join('\n');
+        const drop = inverseOf(recreate, path);
+        if (!drop.trim() || drop.trim().startsWith('--')) {
+            warnings.push(`${path}: no DROP derivable for kind "${unit.identity.kind}"; drop manually`);
+            continue;
+        }
+        dropChanges.push({
+            name: `${path}/drop`,
+            dependencies: dropChanges.length > 0 ? [dropChanges[dropChanges.length - 1].name] : [],
+            deploy: drop,
+            revert: recreate,
+            verify: ''
+        });
+    }
+    let forwardChanges = [];
+    if (forwardSql.length > 0) {
+        const { changes, warnings: w } = restructureChanges([{ name: 'delta', dependencies: [], deploy: forwardSql.join('\n\n') }], { granularity: options.granularity ?? 'object' });
+        forwardChanges = changes.map(c => ({
+            ...c,
+            revert: inverseOf(c.deploy, c.name),
+            verify: verifyOf(c.deploy, c.name)
+        }));
+        warnings.push(...w);
+    }
+    return {
+        identical: objects.length === 0,
+        objects,
+        changes: [...dropChanges, ...forwardChanges, ...modifiedChanges],
+        warnings
+    };
+}
+/**
+ * Identity-keyed diff over pgpm changes: flattens each side's deploy scripts
+ * in plan order and delegates to {@link diffSchemas}. Change names never
+ * enter the comparison — regrouping, renaming, or repartitioning the same
+ * schema yields an identical diff.
+ */
+export function diffChangeSets(from, to, options = {}) {
+    const flatten = (changes) => changes.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
+    return diffSchemas(flatten(from), flatten(to), options);
+}

package/index.d.ts

@@ -4,11 +4,15 @@ export type { BundleScriptContext, ExtensionRoutingInput, NamespaceValidatorOpti
 export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
 export type { GranularityChange, RestructuredChange, RestructureModuleOptions, RestructureModuleResult, } from './granularity-driver';
 export { defaultChangeName, restructureChanges, } from './granularity-driver';
+export type { DiffInputChange, ObjectDelta, SemanticDeltaChange, SemanticDiffOptions, SemanticDiffResult, SemanticObjectDiff, } from './semantic-diff-driver';
+export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
 export type { PartitionConfig, PartitionedChange, PartitionedPackage, PartitionInputChange, PartitionRule, PartitionUnit, PartitionUnitsResult, UnitSelector, } from './partition-driver';
 export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-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';
+export type { GeneratedScript, RegeneratedScripts, } from './regen';
+export { classifyScript, isStubScript, regenerateScripts, } from './regen';
 export type { SqlProgram, SqlStatementAst, SqlStatementSpan, } from './program';
 export { emitSqlProgram, parseSqlProgram } from './program';

package/index.js

@@ -14,7 +14,7 @@ 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.parseSqlProgram = exports.emitSqlProgram = exports.resolveFixtureClosure = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.RESIDUAL_UNIT_PATH = exports.partitionUnits = exports.PartitionCycleError = exports.restructureChanges = exports.defaultChangeName = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = exports.loadModule = void 0;
+exports.parseSqlProgram = exports.emitSqlProgram = exports.regenerateScripts = exports.isStubScript = exports.classifyScript = exports.resolveFixtureClosure = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.RESIDUAL_UNIT_PATH = exports.partitionUnits = exports.PartitionCycleError = exports.diffSchemas = exports.diffChangeSets = exports.restructureChanges = exports.defaultChangeName = 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; } });
@@ -26,6 +26,9 @@ Object.defineProperty(exports, "makeSchemaTranspiler", { enumerable: true, get:
 var granularity_driver_1 = require("./granularity-driver");
 Object.defineProperty(exports, "defaultChangeName", { enumerable: true, get: function () { return granularity_driver_1.defaultChangeName; } });
 Object.defineProperty(exports, "restructureChanges", { enumerable: true, get: function () { return granularity_driver_1.restructureChanges; } });
+var semantic_diff_driver_1 = require("./semantic-diff-driver");
+Object.defineProperty(exports, "diffChangeSets", { enumerable: true, get: function () { return semantic_diff_driver_1.diffChangeSets; } });
+Object.defineProperty(exports, "diffSchemas", { enumerable: true, get: function () { return semantic_diff_driver_1.diffSchemas; } });
 var partition_driver_1 = require("./partition-driver");
 Object.defineProperty(exports, "PartitionCycleError", { enumerable: true, get: function () { return partition_driver_1.PartitionCycleError; } });
 Object.defineProperty(exports, "partitionUnits", { enumerable: true, get: function () { return partition_driver_1.partitionUnits; } });
@@ -36,6 +39,10 @@ Object.defineProperty(exports, "categorizeChange", { enumerable: true, get: func
 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; } });
+var regen_1 = require("./regen");
+Object.defineProperty(exports, "classifyScript", { enumerable: true, get: function () { return regen_1.classifyScript; } });
+Object.defineProperty(exports, "isStubScript", { enumerable: true, get: function () { return regen_1.isStubScript; } });
+Object.defineProperty(exports, "regenerateScripts", { enumerable: true, get: function () { return regen_1.regenerateScripts; } });
 var program_1 = require("./program");
 Object.defineProperty(exports, "emitSqlProgram", { enumerable: true, get: function () { return program_1.emitSqlProgram; } });
 Object.defineProperty(exports, "parseSqlProgram", { enumerable: true, get: function () { return program_1.parseSqlProgram; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.16.0",
+  "version": "0.17.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",
@@ -44,9 +44,9 @@
   },
   "dependencies": {
     "@pgpmjs/naming-spec": "^0.1.2",
-    "@pgsql/scripts": "^18.0.0",
+    "@pgsql/scripts": "^18.1.0",
     "@pgsql/transform": "^18.11.0",
-    "plpgsql-parser": "^18.2.2"
+    "plpgsql-parser": "^18.2.3"
   },
-  "gitHead": "7a37da1f5655c36813343f09c6efa62ca0d7a855"
+  "gitHead": "45cd961cf956d2d28e4d09b20db4204982c33593"
 }

package/regen.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Regeneration driver: derive revert/verify scripts for a single pgpm
+ * change from its deploy SQL.
+ *
+ * Deploy scripts are classified into statement facts (`classifyStatements`)
+ * and fed through `revertFor`/`verifyFor` from `@pgsql/scripts`: revert is
+ * the mechanical inverses in reverse topological order, verify is one
+ * raise-on-failure existence check per created object. Transaction control
+ * statements (the BEGIN/COMMIT wrapper some modules carry inside their
+ * scripts) are excluded before classification — the caller owns the wrapper.
+ *
+ * Requires `loadModule()` from `plpgsql-parser` to have completed.
+ */
+import type { GeneratedScript } from '@pgsql/scripts';
+import type { StatementFacts } from '@pgsql/transform';
+export type { GeneratedScript } from '@pgsql/scripts';
+/** Generated revert and verify scripts for one change's deploy SQL. */
+export interface RegeneratedScripts {
+    revert: GeneratedScript;
+    verify: GeneratedScript;
+}
+/**
+ * Classify a pgpm script's substantive statements: every top-level statement
+ * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
+ */
+export declare function classifyScript(sql: string): StatementFacts[];
+/**
+ * Whether a script is an empty stub: nothing but comments, whitespace, and
+ * a transaction wrapper — no substantive statements. Scaffolded
+ * `-- Add your revert SQL here` files and bare `BEGIN; ... COMMIT;` shells
+ * are stubs. A script that fails to parse is NOT a stub (never treat content
+ * we cannot understand as safe to overwrite).
+ */
+export declare function isStubScript(sql: string): boolean;
+/**
+ * Generate revert and verify scripts (headerless, unwrapped) for one
+ * change's deploy SQL. Statements with no derivable inverse contribute a
+ * `-- revert not derivable: <reason>` comment and a warning; statements
+ * whose effect cannot be existence-checked add a verify warning.
+ */
+export declare function regenerateScripts(deploySql: string): RegeneratedScripts;

package/regen.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyScript = classifyScript;
+exports.isStubScript = isStubScript;
+exports.regenerateScripts = regenerateScripts;
+const scripts_1 = require("@pgsql/scripts");
+const transform_1 = require("@pgsql/transform");
+/**
+ * Classify a pgpm script's substantive statements: every top-level statement
+ * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
+ */
+function classifyScript(sql) {
+    return (0, transform_1.classifyStatements)(sql).filter(f => f.nodeTag !== 'TransactionStmt');
+}
+/**
+ * Whether a script is an empty stub: nothing but comments, whitespace, and
+ * a transaction wrapper — no substantive statements. Scaffolded
+ * `-- Add your revert SQL here` files and bare `BEGIN; ... COMMIT;` shells
+ * are stubs. A script that fails to parse is NOT a stub (never treat content
+ * we cannot understand as safe to overwrite).
+ */
+function isStubScript(sql) {
+    if (!sql || !sql.trim())
+        return true;
+    try {
+        return classifyScript(sql).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate revert and verify scripts (headerless, unwrapped) for one
+ * change's deploy SQL. Statements with no derivable inverse contribute a
+ * `-- revert not derivable: <reason>` comment and a warning; statements
+ * whose effect cannot be existence-checked add a verify warning.
+ */
+function regenerateScripts(deploySql) {
+    const facts = classifyScript(deploySql);
+    return {
+        revert: (0, scripts_1.revertFor)(facts),
+        verify: (0, scripts_1.verifyFor)(facts)
+    };
+}

package/semantic-diff-driver.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Semantic diff driver: identity-keyed schema delta between two deploy
+ * surfaces.
+ *
+ * Where `diffBundles` (in `@pgpmjs/bundle`) compares change names and content
+ * digests — which breaks the moment a dial regroups or renames changes — this
+ * driver re-keys the comparison on object identity (`identityOf`), so the
+ * same schema authored at different granularities or partitions diffs as
+ * equal. Objects are compared at the AST level (normalized parse trees, so
+ * formatting never matters); tables are compared column-by-column and
+ * constraint-by-constraint so an added column emits `ALTER TABLE ADD COLUMN`,
+ * not a table rebuild.
+ *
+ * The emitted delta is a set of pgpm changes: DROPs for removed objects
+ * (reverse topological order), then CREATE/ALTER changes for added and
+ * modified objects routed through the granularity pipeline
+ * (`restructureChanges`), so names come from the naming spec and `requires`
+ * from the statement graph — the same derivation every other projection uses.
+ * Every emitted change carries a full deploy/revert/verify triple: drops are
+ * `@pgsql/scripts`' `revertFor` inverses of the object's own deploy
+ * statements (never hand-templated), reverts recreate what was dropped, and
+ * verifies come from `verifyFor`.
+ *
+ * Requires `loadModule()` from `plpgsql-parser` before use.
+ */
+import { PathStyle } from '@pgpmjs/naming-spec';
+import type { ObjectIdentity } from '@pgsql/transform';
+import { Granularity } from '@pgsql/transform';
+import { GranularityChange } from './granularity-driver';
+/** How one object differs between the two sides. */
+export type ObjectDelta = 'added' | 'removed' | 'modified';
+export interface SemanticObjectDiff {
+    identity: ObjectIdentity;
+    /** Canonical naming-spec path for the object. */
+    path: string;
+    delta: ObjectDelta;
+    /** For modified tables: the column/constraint-level detail. */
+    columnsAdded?: string[];
+    columnsRemoved?: string[];
+    columnsModified?: string[];
+}
+export interface SemanticDiffOptions {
+    /** Granularity for the emitted CREATE/ALTER changes (default `object`). */
+    granularity?: Granularity;
+    /** Naming-spec rendering style (default `directory`). */
+    style?: PathStyle;
+}
+/** One emitted delta change: a full deploy/revert/verify triple. */
+export interface SemanticDeltaChange extends GranularityChange {
+    revert: string;
+    verify: string;
+}
+export interface SemanticDiffResult {
+    /** True when both sides describe the same objects with the same shapes. */
+    identical: boolean;
+    /** Per-object dispositions, in `to`-then-removed order. */
+    objects: SemanticObjectDiff[];
+    /**
+     * The migration delta: DROP changes for removed objects first (reverse
+     * topological order), then CREATE/ALTER changes named and ordered by the
+     * granularity pipeline.
+     */
+    changes: SemanticDeltaChange[];
+    warnings: string[];
+}
+/**
+ * Diff two deploy surfaces by object identity and emit the migration delta.
+ *
+ * `from`/`to` are whole deploy scripts (flatten changes in plan order to
+ * diff bundles/modules). The result's `changes` deploy `to`'s shape on top
+ * of `from`: reverse-topological DROPs, then CREATE/ALTERs named and
+ * ordered by `restructureChanges`.
+ */
+export declare function diffSchemas(from: string, to: string, options?: SemanticDiffOptions): SemanticDiffResult;
+/** A change's deploy surface (same seam as the other drivers). */
+export interface DiffInputChange {
+    name: string;
+    dependencies: string[];
+    deploy: string;
+}
+/**
+ * Identity-keyed diff over pgpm changes: flattens each side's deploy scripts
+ * in plan order and delegates to {@link diffSchemas}. Change names never
+ * enter the comparison — regrouping, renaming, or repartitioning the same
+ * schema yields an identical diff.
+ */
+export declare function diffChangeSets(from: DiffInputChange[], to: DiffInputChange[], options?: SemanticDiffOptions): SemanticDiffResult;

package/semantic-diff-driver.js

@@ -0,0 +1,370 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffSchemas = diffSchemas;
+exports.diffChangeSets = diffChangeSets;
+/**
+ * Semantic diff driver: identity-keyed schema delta between two deploy
+ * surfaces.
+ *
+ * Where `diffBundles` (in `@pgpmjs/bundle`) compares change names and content
+ * digests — which breaks the moment a dial regroups or renames changes — this
+ * driver re-keys the comparison on object identity (`identityOf`), so the
+ * same schema authored at different granularities or partitions diffs as
+ * equal. Objects are compared at the AST level (normalized parse trees, so
+ * formatting never matters); tables are compared column-by-column and
+ * constraint-by-constraint so an added column emits `ALTER TABLE ADD COLUMN`,
+ * not a table rebuild.
+ *
+ * The emitted delta is a set of pgpm changes: DROPs for removed objects
+ * (reverse topological order), then CREATE/ALTER changes for added and
+ * modified objects routed through the granularity pipeline
+ * (`restructureChanges`), so names come from the naming spec and `requires`
+ * from the statement graph — the same derivation every other projection uses.
+ * Every emitted change carries a full deploy/revert/verify triple: drops are
+ * `@pgsql/scripts`' `revertFor` inverses of the object's own deploy
+ * statements (never hand-templated), reverts recreate what was dropped, and
+ * verifies come from `verifyFor`.
+ *
+ * Requires `loadModule()` from `plpgsql-parser` before use.
+ */
+const naming_spec_1 = require("@pgpmjs/naming-spec");
+const scripts_1 = require("@pgsql/scripts");
+const transform_1 = require("@pgsql/transform");
+const plpgsql_parser_1 = require("plpgsql-parser");
+const granularity_driver_1 = require("./granularity-driver");
+const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
+/**
+ * Group one side's script into identity-keyed object units. Statements with
+ * no identity (grants, comments) attach to the unit of the first object they
+ * reference, falling back to the preceding statement's unit; truly homeless
+ * statements are reported via `warnings`.
+ */
+function readSide(sql, warnings, label) {
+    const facts = (0, transform_1.classifyStatements)(sql);
+    const graph = (0, transform_1.buildStatementGraph)(facts);
+    const units = new Map();
+    const order = [];
+    const unitOf = new Array(facts.length).fill(null);
+    const byObject = new Map();
+    facts.forEach((f, i) => {
+        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        if (!text)
+            return;
+        let identity = groupingIdentity(f);
+        if (identity && identity.kind === 'other') {
+            const asTable = identityKey({ kind: 'table', schema: identity.schema, name: identity.name });
+            if (units.has(asTable))
+                identity = units.get(asTable).identity;
+        }
+        let key = null;
+        if (identity) {
+            key = identityKey(identity);
+            if (!units.has(key)) {
+                units.set(key, { identity, statements: [], texts: [] });
+                order.push(key);
+            }
+            if (!identity.table) {
+                byObject.set(`${identity.schema ?? ''}.${identity.name}`, key);
+            }
+        }
+        else {
+            for (const r of f.references) {
+                const host = byObject.get(`${r.schema ?? ''}.${r.name}`);
+                if (host) {
+                    key = host;
+                    break;
+                }
+            }
+            if (!key && i > 0)
+                key = unitOf[i - 1];
+        }
+        if (!key) {
+            warnings.push(`${label}: statement ${i} (${f.kind}) belongs to no object; ignored in the diff`);
+            return;
+        }
+        unitOf[i] = key;
+        const unit = units.get(key);
+        unit.statements.push(i);
+        unit.texts.push(text.endsWith(';') ? text : `${text};`);
+    });
+    return { facts, units, order, graph };
+}
+/**
+ * The identity a statement groups under. Table-shaping statements — ALTER
+ * TABLE column/constraint additions, RLS enablement — fold into their table's
+ * unit so that atomic and consolidated authorships of the same table land in
+ * the same unit and compare shape-to-shape. Generic ALTERs (`kind: 'other'`)
+ * fold in `readSide` when a table unit for the same object already exists.
+ */
+function groupingIdentity(f) {
+    const identity = (0, transform_1.identityOf)(f);
+    if (!identity)
+        return null;
+    if ((f.kind === 'table' || f.kind === 'constraint' || f.kind === 'rls_enable') &&
+        identity.kind !== 'table') {
+        return { kind: 'table', schema: identity.schema, name: identity.table ?? identity.name };
+    }
+    return identity;
+}
+/** Normalized-AST fingerprint of one statement (formatting/position-proof). */
+function fingerprint(text) {
+    const parsed = (0, plpgsql_parser_1.parseSync)(text);
+    return JSON.stringify((0, transform_1.cleanTree)(parsed.sql.stmts.map(s => s.stmt)));
+}
+/** Multiset fingerprint of a whole unit. */
+const unitFingerprint = (unit) => unit.texts.map(fingerprint).sort().join('\n');
+/**
+ * Fold a table unit's statements (CREATE TABLE plus any ALTER TABLE
+ * ADD COLUMN / ADD CONSTRAINT) into an effective shape, so atomic and
+ * consolidated authorships of the same table compare equal.
+ */
+function tableShape(unit) {
+    const shape = { relation: null, columns: new Map(), extras: new Map() };
+    const addColumn = (node) => {
+        const def = node;
+        const clean = (0, transform_1.cleanTree)(node);
+        shape.columns.set(def.colname ?? '', { def: clean, print: JSON.stringify(clean) });
+    };
+    const addExtra = (node) => {
+        const clean = (0, transform_1.cleanTree)(node);
+        shape.extras.set(JSON.stringify(clean), clean);
+    };
+    for (const text of unit.texts) {
+        for (const raw of (0, plpgsql_parser_1.parseSync)(text).sql.stmts) {
+            const stmt = raw.stmt;
+            if (stmt.CreateStmt) {
+                shape.relation = stmt.CreateStmt.relation;
+                const elts = stmt.CreateStmt.tableElts ?? [];
+                for (const elt of elts) {
+                    if (elt.ColumnDef)
+                        addColumn(elt.ColumnDef);
+                    else
+                        addExtra(elt);
+                }
+            }
+            else if (stmt.AlterTableStmt) {
+                shape.relation ??= stmt.AlterTableStmt.relation;
+                const cmds = stmt.AlterTableStmt.cmds ?? [];
+                for (const cmd of cmds) {
+                    const at = cmd.AlterTableCmd;
+                    if (!at)
+                        continue;
+                    const def = at.def;
+                    if (at.subtype === 'AT_AddColumn' && def?.ColumnDef) {
+                        addColumn(def.ColumnDef);
+                    }
+                    else {
+                        addExtra({ AlterTableCmd: at });
+                    }
+                }
+            }
+            else {
+                addExtra(stmt);
+            }
+        }
+    }
+    return shape;
+}
+const deparseStmt = (node) => `${plpgsql_parser_1.Deparser.deparse(node, { pretty: false })};`;
+/** Column-level ALTERs between two table shapes. */
+function diffTable(from, to, diff, warnings) {
+    const stmts = [];
+    const relation = to.relation ?? from.relation;
+    const alter = (cmd) => deparseStmt({
+        AlterTableStmt: {
+            relation,
+            cmds: [{ AlterTableCmd: { behavior: 'DROP_RESTRICT', ...cmd } }],
+            objtype: 'OBJECT_TABLE'
+        }
+    });
+    diff.columnsAdded = [];
+    diff.columnsRemoved = [];
+    diff.columnsModified = [];
+    for (const [name, col] of to.columns) {
+        const prior = from.columns.get(name);
+        if (!prior) {
+            diff.columnsAdded.push(name);
+            stmts.push(alter({ subtype: 'AT_AddColumn', def: { ColumnDef: col.def } }));
+        }
+        else if (prior.print !== col.print) {
+            diff.columnsModified.push(name);
+            const fromDef = prior.def;
+            const toDef = col.def;
+            const typeChanged = JSON.stringify(fromDef.typeName) !== JSON.stringify(toDef.typeName);
+            const restChanged = JSON.stringify({ ...fromDef, typeName: null }) !==
+                JSON.stringify({ ...toDef, typeName: null });
+            if (typeChanged) {
+                stmts.push(alter({
+                    subtype: 'AT_AlterColumnType',
+                    name,
+                    def: { ColumnDef: { typeName: toDef.typeName } }
+                }));
+            }
+            if (restChanged) {
+                warnings.push(`${diff.path}: column "${name}" changed beyond its type (constraints/defaults); emit a manual ALTER`);
+            }
+        }
+    }
+    for (const name of from.columns.keys()) {
+        if (!to.columns.has(name)) {
+            diff.columnsRemoved.push(name);
+            stmts.push(alter({ subtype: 'AT_DropColumn', name }));
+        }
+    }
+    for (const [print, extra] of to.extras) {
+        if (!from.extras.has(print)) {
+            const at = extra.AlterTableCmd;
+            if (at)
+                stmts.push(alter(at));
+            else if (extra.Constraint) {
+                stmts.push(alter({ subtype: 'AT_AddConstraint', def: extra }));
+            }
+            else {
+                warnings.push(`${diff.path}: unrecognized added table element; emit a manual ALTER`);
+            }
+        }
+    }
+    for (const [print, extra] of from.extras) {
+        if (to.extras.has(print))
+            continue;
+        const conname = extra.Constraint?.conname
+            ?? extra
+                .AlterTableCmd?.def?.Constraint?.conname;
+        if (conname) {
+            stmts.push(alter({ subtype: 'AT_DropConstraint', name: conname }));
+        }
+        else {
+            warnings.push(`${diff.path}: removed table element has no name to drop; emit a manual ALTER`);
+        }
+    }
+    return stmts;
+}
+/**
+ * Diff two deploy surfaces by object identity and emit the migration delta.
+ *
+ * `from`/`to` are whole deploy scripts (flatten changes in plan order to
+ * diff bundles/modules). The result's `changes` deploy `to`'s shape on top
+ * of `from`: reverse-topological DROPs, then CREATE/ALTERs named and
+ * ordered by `restructureChanges`.
+ */
+function diffSchemas(from, to, options = {}) {
+    const style = options.style ?? 'directory';
+    const warnings = [];
+    const a = readSide(from, warnings, 'from');
+    const b = readSide(to, warnings, 'to');
+    const objects = [];
+    const forwardSql = [];
+    const modifiedChanges = [];
+    const dropUnits = [];
+    /** `@pgsql/scripts` inverse of a deploy script (drops in reverse topo order). */
+    const inverseOf = (deploy, context) => {
+        const { sql, warnings: w } = (0, scripts_1.revertFor)((0, transform_1.classifyStatements)(deploy));
+        warnings.push(...w.map(x => `${context}: ${x}`));
+        return sql;
+    };
+    /** `@pgsql/scripts` existence checks for a deploy script. */
+    const verifyOf = (deploy, context) => {
+        const { sql, warnings: w } = (0, scripts_1.verifyFor)((0, transform_1.classifyStatements)(deploy));
+        warnings.push(...w.map(x => `${context}: ${x}`));
+        return sql;
+    };
+    for (const key of b.order) {
+        const unit = b.units.get(key);
+        const prior = a.units.get(key);
+        const path = (0, naming_spec_1.pathFor)(unit.identity, { style });
+        if (!prior) {
+            objects.push({ identity: unit.identity, path, delta: 'added' });
+            forwardSql.push(...unit.texts);
+            continue;
+        }
+        if (unit.identity.kind === 'table') {
+            const shapeFrom = tableShape(prior);
+            const shapeTo = tableShape(unit);
+            const diff = { identity: unit.identity, path, delta: 'modified' };
+            const stmts = diffTable(shapeFrom, shapeTo, diff, warnings);
+            const columnsTouched = diff.columnsAdded.length + diff.columnsRemoved.length + diff.columnsModified.length > 0;
+            if (stmts.length > 0 || columnsTouched) {
+                objects.push(diff);
+                if (stmts.length > 0) {
+                    // The inverse alteration is the same diff with the sides swapped.
+                    const scratch = { identity: unit.identity, path, delta: 'modified' };
+                    const deploy = stmts.join('\n');
+                    modifiedChanges.push({
+                        name: `${path}/alter`,
+                        dependencies: [],
+                        deploy,
+                        revert: diffTable(shapeTo, shapeFrom, scratch, []).join('\n'),
+                        verify: verifyOf(deploy, path)
+                    });
+                }
+            }
+            continue;
+        }
+        if (unitFingerprint(prior) !== unitFingerprint(unit)) {
+            objects.push({ identity: unit.identity, path, delta: 'modified' });
+            const priorDeploy = prior.texts.join('\n');
+            const newDeploy = unit.texts.join('\n');
+            modifiedChanges.push({
+                name: path,
+                dependencies: [],
+                deploy: [inverseOf(priorDeploy, path), newDeploy].filter(Boolean).join('\n'),
+                revert: [inverseOf(newDeploy, path), priorDeploy].filter(Boolean).join('\n'),
+                verify: verifyOf(newDeploy, path)
+            });
+        }
+    }
+    for (const key of a.order) {
+        if (b.units.has(key))
+            continue;
+        const unit = a.units.get(key);
+        objects.push({ identity: unit.identity, path: (0, naming_spec_1.pathFor)(unit.identity, { style }), delta: 'removed' });
+        dropUnits.push(unit);
+    }
+    // Removed objects drop in reverse topological order of the `from` graph
+    // (dependents before dependencies), one change per object.
+    const position = new Map(dropUnits.map(u => [u, Math.min(...u.statements.map(s => a.graph.order.indexOf(s)))]));
+    dropUnits.sort((x, y) => position.get(y) - position.get(x));
+    const dropChanges = [];
+    for (const unit of dropUnits) {
+        const path = (0, naming_spec_1.pathFor)(unit.identity, { style });
+        const recreate = unit.texts.join('\n');
+        const drop = inverseOf(recreate, path);
+        if (!drop.trim() || drop.trim().startsWith('--')) {
+            warnings.push(`${path}: no DROP derivable for kind "${unit.identity.kind}"; drop manually`);
+            continue;
+        }
+        dropChanges.push({
+            name: `${path}/drop`,
+            dependencies: dropChanges.length > 0 ? [dropChanges[dropChanges.length - 1].name] : [],
+            deploy: drop,
+            revert: recreate,
+            verify: ''
+        });
+    }
+    let forwardChanges = [];
+    if (forwardSql.length > 0) {
+        const { changes, warnings: w } = (0, granularity_driver_1.restructureChanges)([{ name: 'delta', dependencies: [], deploy: forwardSql.join('\n\n') }], { granularity: options.granularity ?? 'object' });
+        forwardChanges = changes.map(c => ({
+            ...c,
+            revert: inverseOf(c.deploy, c.name),
+            verify: verifyOf(c.deploy, c.name)
+        }));
+        warnings.push(...w);
+    }
+    return {
+        identical: objects.length === 0,
+        objects,
+        changes: [...dropChanges, ...forwardChanges, ...modifiedChanges],
+        warnings
+    };
+}
+/**
+ * Identity-keyed diff over pgpm changes: flattens each side's deploy scripts
+ * in plan order and delegates to {@link diffSchemas}. Change names never
+ * enter the comparison — regrouping, renaming, or repartitioning the same
+ * schema yields an identical diff.
+ */
+function diffChangeSets(from, to, options = {}) {
+    const flatten = (changes) => changes.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
+    return diffSchemas(flatten(from), flatten(to), options);
+}