@pgpmjs/transform 0.15.3 → 0.17.0

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