@pgpmjs/transform 0.18.0 → 0.20.0

package/esm/index.js

@@ -1,10 +1,17 @@
-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 { defaultConstraintName, firstColumnRef } from './constraint-names';
 export { resolveFixtureClosure } from './fixture-closure';
-export { classifyScript, isStubScript, regenerateScripts, } from './regen';
+export { CHANGE_GRANULARITIES, defaultChangeName, isChangeGranularity, restructureChanges, } from './granularity-driver';
+export { appendModule, 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 { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
+export * from '@pgsql/transform';
+export { loadModule } from 'plpgsql-parser';

package/esm/module-emit.js

@@ -0,0 +1,135 @@
+/**
+ * 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 { parseAuthor, parsePlanFile, writePgpmFiles, writePgpmPlan, writePlanFile } 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;
+};
+/**
+ * Append plan-ordered {@link PgpmRow}s into an *existing* module rather than
+ * writing a fresh package. Existing changes, their scripts, and the `.control`
+ * file are left untouched; only the new changes are written (deploy/revert/
+ * verify) and appended to `pgpm.plan` after the current changes.
+ *
+ * Rows whose change name already exists are skipped (never overwritten).
+ * A new change's dependency bracket is filtered to names that resolve within
+ * the plan (existing changes, other appended changes, or `pkg:`-external
+ * references); a dangling internal dependency is dropped with a warning
+ * (plan order still sequences it after the current changes).
+ */
+export const appendModule = (moduleDir, rows, options = {}) => {
+    const planPath = path.join(moduleDir, 'pgpm.plan');
+    if (!fs.existsSync(planPath)) {
+        throw new Error(`No pgpm.plan found at ${planPath}; append mode expects an existing pgpm module directory.`);
+    }
+    const parsed = parsePlanFile(planPath);
+    if (!parsed.data) {
+        throw new Error(`Failed to parse ${planPath}: ${parsed.errors
+            .map(e => `line ${e.line}: ${e.message}`)
+            .join('; ')}`);
+    }
+    const plan = parsed.data;
+    const existingNames = new Set(plan.changes.map(c => c.name));
+    const incomingNames = new Set(rows.map(r => r.deploy));
+    const appended = new Set();
+    const added = [];
+    const skipped = [];
+    const warnings = [];
+    const newRows = [];
+    const { fullName, email } = parseAuthor(options.author || 'constructive');
+    const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    for (const row of rows) {
+        if (existingNames.has(row.deploy) || appended.has(row.deploy)) {
+            skipped.push(row.deploy);
+            warnings.push(`change ${row.deploy} already exists in ${plan.package}; left untouched`);
+            continue;
+        }
+        const deps = (row.deps ?? []).filter(dep => {
+            if (dep.includes(':'))
+                return true; // cross-package (pkg:change) external
+            if (existingNames.has(dep) || incomingNames.has(dep))
+                return true;
+            warnings.push(`change ${row.deploy}: dropped dependency ${dep} (not present in ${plan.package})`);
+            return false;
+        });
+        plan.changes.push({
+            name: row.deploy,
+            dependencies: deps,
+            timestamp,
+            planner: fullName,
+            email: email || `${fullName}@constructive.io`,
+            comment: `add ${row.name ?? row.deploy}`
+        });
+        newRows.push({ ...row, deps });
+        appended.add(row.deploy);
+        added.push(row.deploy);
+    }
+    if (newRows.length) {
+        const opts = {
+            outdir: path.dirname(moduleDir),
+            name: path.basename(moduleDir),
+            replacer: (str) => str
+        };
+        writePgpmFiles(newRows, opts);
+        writePlanFile(planPath, plan);
+    }
+    return { dir: moduleDir, added, skipped, warnings };
+};
+/**
+ * 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,67 @@
+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,
+        changeGranularity: options.changeGranularity,
+        changeName,
+        subObjectName: identity => pathFor(identity, { style })
+    });
+    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 };
+};

package/esm/semantic-diff-driver.js

@@ -30,6 +30,7 @@ import { pathFor } from '@pgpmjs/naming-spec';
 import { existenceCheck, invertStatement, revertFor, verifyFor } from '@pgsql/scripts';
 import { buildStatementGraph, classifyStatements, cleanTree, identityOf } from '@pgsql/transform';
 import { Deparser, parseSync } from 'plpgsql-parser';
+import { defaultConstraintName } from './constraint-names';
 import { restructureChanges } from './granularity-driver';
 const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
 /**
@@ -99,7 +100,7 @@ function groupingIdentity(f) {
     const identity = identityOf(f);
     if (!identity)
         return null;
-    if ((f.kind === 'table' || f.kind === 'constraint' || f.kind === 'rls_enable') &&
+    if ((f.kind === 'table' || f.kind === 'constraint' || f.kind === 'fk_constraint' || f.kind === 'rls_enable') &&
         identity.kind !== 'table') {
         return { kind: 'table', schema: identity.schema, name: identity.table ?? identity.name };
     }
@@ -112,21 +113,61 @@ function fingerprint(text) {
 }
 /** Multiset fingerprint of a whole unit. */
 const unitFingerprint = (unit) => unit.texts.map(fingerprint).sort().join('\n');
+/** JSON with recursively sorted object keys — an insertion-order-proof fingerprint. */
+function stablePrint(node) {
+    if (Array.isArray(node))
+        return `[${node.map(stablePrint).join(',')}]`;
+    if (node && typeof node === 'object') {
+        const entries = Object.entries(node)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${JSON.stringify(k)}:${stablePrint(v)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(node);
+}
+/** Constraint kinds that can move between column, table-elt, and ALTER form. */
+const RELOCATABLE = new Set(['CONSTR_PRIMARY', 'CONSTR_UNIQUE', 'CONSTR_FOREIGN', 'CONSTR_CHECK']);
 /**
  * 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.
+ *
+ * Constraint placement is representation, not semantics: `id bigint PRIMARY
+ * KEY`, a `PRIMARY KEY (id)` table elt, and `ALTER TABLE .. ADD CONSTRAINT
+ * t_pkey PRIMARY KEY (id)` all catalog identically. Relocatable constraints
+ * (PK/UNIQUE/FK/CHECK) are therefore lifted out of columns and ALTER
+ * commands into one canonical table-level set — keyed with the Postgres
+ * default name when unnamed, columns filled in from the owning column when
+ * column-attached — and PK columns gain the NOT NULL the catalog implies.
  */
 function tableShape(unit) {
     const shape = { relation: null, columns: new Map(), extras: new Map() };
+    const table = unit.identity.name;
+    const rawColumns = [];
+    const constraints = [];
+    const pkColumns = new Set();
     const addColumn = (node) => {
-        const def = node;
-        const clean = cleanTree(node);
-        shape.columns.set(def.colname ?? '', { def: clean, print: JSON.stringify(clean) });
+        const colname = node.colname ?? '';
+        const attached = node.constraints ?? [];
+        const residual = [];
+        for (const item of attached) {
+            const c = item.Constraint;
+            if (c && RELOCATABLE.has(c.contype ?? '')) {
+                constraints.push({ node: c, column: colname });
+            }
+            else {
+                residual.push(item);
+            }
+        }
+        rawColumns.push({ colname, def: { ...node, constraints: residual } });
+    };
+    const addConstraint = (node, column) => {
+        constraints.push({ node: node, column });
     };
     const addExtra = (node) => {
         const clean = cleanTree(node);
-        shape.extras.set(JSON.stringify(clean), clean);
+        shape.extras.set(stablePrint(clean), clean);
     };
     for (const text of unit.texts) {
         for (const raw of parseSync(text).sql.stmts) {
@@ -137,6 +178,9 @@ function tableShape(unit) {
                 for (const elt of elts) {
                     if (elt.ColumnDef)
                         addColumn(elt.ColumnDef);
+                    else if (elt.Constraint && RELOCATABLE.has(elt.Constraint.contype ?? '')) {
+                        addConstraint(elt.Constraint);
+                    }
                     else
                         addExtra(elt);
                 }
@@ -152,6 +196,11 @@ function tableShape(unit) {
                     if (at.subtype === 'AT_AddColumn' && def?.ColumnDef) {
                         addColumn(def.ColumnDef);
                     }
+                    else if (at.subtype === 'AT_AddConstraint' &&
+                        def?.Constraint &&
+                        RELOCATABLE.has(def.Constraint.contype ?? '')) {
+                        addConstraint(def.Constraint);
+                    }
                     else {
                         addExtra({ AlterTableCmd: at });
                     }
@@ -162,6 +211,44 @@ function tableShape(unit) {
             }
         }
     }
+    for (const { node, column } of constraints) {
+        const canonical = { ...node };
+        canonical.conname = node.conname ?? defaultConstraintName(table, node, column) ?? undefined;
+        if (column && (node.keys ?? []).length === 0 && node.contype !== 'CONSTR_FOREIGN' && node.contype !== 'CONSTR_CHECK') {
+            canonical.keys = [{ String: { sval: column } }];
+        }
+        if (column && node.contype === 'CONSTR_FOREIGN' && (node.fk_attrs ?? []).length === 0) {
+            canonical.fk_attrs = [{ String: { sval: column } }];
+        }
+        if (node.contype === 'CONSTR_PRIMARY') {
+            const keyed = canonical.keys ?? [];
+            for (const k of keyed)
+                if (k.String?.sval)
+                    pkColumns.add(k.String.sval);
+        }
+        addExtra({ Constraint: canonical });
+    }
+    for (const { colname, def } of rawColumns) {
+        const residual = (def.constraints ?? []).map(c => {
+            const constraint = c.Constraint;
+            // NOT NULL parses with parser-version-dependent extras (is_enforced,
+            // initially_valid); reduce to its semantic core so an authored NOT NULL
+            // equals the one a primary key implies.
+            if (constraint?.contype === 'CONSTR_NOTNULL') {
+                return { Constraint: { contype: 'CONSTR_NOTNULL', conname: constraint.conname } };
+            }
+            return c;
+        });
+        const hasNotNull = residual.some(c => c.Constraint?.contype === 'CONSTR_NOTNULL');
+        if (pkColumns.has(colname) && !hasNotNull) {
+            residual.push({ Constraint: { contype: 'CONSTR_NOTNULL' } });
+        }
+        const sorted = residual
+            .map(c => cleanTree(c))
+            .sort((x, y) => stablePrint(x).localeCompare(stablePrint(y)));
+        const clean = cleanTree({ ...def, constraints: sorted });
+        shape.columns.set(colname, { def: clean, print: stablePrint(clean) });
+    }
     return shape;
 }
 const deparseStmt = (node) => `${Deparser.deparse(node, { pretty: false })};`;
@@ -210,32 +297,46 @@ function diffTable(from, to, diff, warnings) {
             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`);
-            }
-        }
-    }
+    // Self-inverse ALTER TABLE subtypes: a removed extra with one of these
+    // undoes with the paired subtype rather than a DROP CONSTRAINT.
+    const INVERSE_SUBTYPE = {
+        AT_EnableRowSecurity: 'AT_DisableRowSecurity',
+        AT_DisableRowSecurity: 'AT_EnableRowSecurity',
+        AT_ForceRowSecurity: 'AT_NoForceRowSecurity',
+        AT_NoForceRowSecurity: 'AT_ForceRowSecurity'
+    };
+    // Removed extras drop before added ones: a changed constraint that keeps
+    // its name must DROP CONSTRAINT before the replacement ADD CONSTRAINT.
     for (const [print, extra] of from.extras) {
         if (to.extras.has(print))
             continue;
         const conname = extra.Constraint?.conname
             ?? extra
                 .AlterTableCmd?.def?.Constraint?.conname;
+        const subtype = extra.AlterTableCmd?.subtype;
         if (conname) {
             stmts.push(alter({ subtype: 'AT_DropConstraint', name: conname }));
         }
+        else if (subtype && INVERSE_SUBTYPE[subtype]) {
+            stmts.push(alter({ subtype: INVERSE_SUBTYPE[subtype] }));
+        }
         else {
             warnings.push(`${diff.path}: removed table element has no name to drop; emit a manual ALTER`);
         }
     }
+    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`);
+            }
+        }
+    }
     return stmts;
 }
 /**
@@ -371,7 +472,11 @@ export function diffSchemas(from, to, options = {}) {
     }
     let forwardChanges = [];
     if (forwardSql.length > 0) {
-        const { changes, warnings: w } = restructureChanges([{ name: 'delta', dependencies: [], deploy: forwardSql.join('\n\n') }], { granularity: options.granularity ?? 'object' });
+        const { changes, warnings: w } = restructureChanges([{ name: 'delta', dependencies: [], deploy: forwardSql.join('\n\n') }], {
+            granularity: options.granularity ?? 'object',
+            changeGranularity: options.changeGranularity,
+            subObjectName: identity => pathFor(identity, { style })
+        });
         forwardChanges = changes.map(c => ({
             ...c,
             revert: inverseOf(c.deploy, c.name),

package/esm/sub-object.js

@@ -0,0 +1,80 @@
+import { Deparser, parseSync } from 'plpgsql-parser';
+import { defaultConstraintName } from './constraint-names';
+/** The single AlterTableCmd of a one-command ALTER TABLE, or null. */
+function singleCmd(stmt) {
+    const cmds = stmt.cmds ?? [];
+    if (cmds.length !== 1)
+        return null;
+    return cmds[0].AlterTableCmd ?? null;
+}
+/**
+ * The column or constraint a one-command `ALTER TABLE .. ADD COLUMN` /
+ * `ADD CONSTRAINT` statement adds, as a naming-spec identity
+ * (`kind: 'column' | 'constraint'`, `table` set). Unnamed constraints get
+ * their Postgres default name. Returns `null` for anything else — multi-
+ * command ALTERs, other subtypes, non-ALTER statements — so callers fall
+ * back to object-level grouping.
+ */
+export function subObjectIdentityOf(facts) {
+    const stmt = facts.stmt?.AlterTableStmt;
+    if (!stmt?.relation?.relname)
+        return null;
+    const cmd = singleCmd(stmt);
+    if (!cmd)
+        return null;
+    const schema = stmt.relation.schemaname ?? null;
+    const table = stmt.relation.relname;
+    if (cmd.subtype === 'AT_AddColumn' && cmd.def?.ColumnDef?.colname) {
+        return { kind: 'column', schema, name: cmd.def.ColumnDef.colname, table };
+    }
+    if (cmd.subtype === 'AT_AddConstraint' && cmd.def?.Constraint) {
+        const constraint = cmd.def.Constraint;
+        const name = constraint.conname ?? defaultConstraintName(table, constraint);
+        if (!name)
+            return null;
+        return { kind: 'constraint', schema, name, table };
+    }
+    return null;
+}
+/**
+ * Rewrite a script so every unnamed `ALTER TABLE .. ADD <constraint>` carries
+ * its Postgres default name (`ADD PRIMARY KEY (id)` becomes `ADD CONSTRAINT
+ * {table}_pkey PRIMARY KEY (id)`) — the exact name the catalog would assign
+ * anyway. Naming them makes each constraint change independently revertible
+ * (`DROP CONSTRAINT <name>`) and verifiable. Statements that need no rewrite
+ * keep their original text.
+ */
+export function nameUnnamedConstraints(sql) {
+    const parsed = parseSync(sql);
+    const pieces = [];
+    for (const raw of parsed.sql.stmts) {
+        const node = raw.stmt;
+        const stmt = node.AlterTableStmt;
+        const table = stmt?.relation?.relname;
+        let rewritten = false;
+        if (stmt && table) {
+            for (const cmd of stmt.cmds ?? []) {
+                const at = cmd.AlterTableCmd;
+                const constraint = at?.subtype === 'AT_AddConstraint' ? at.def?.Constraint : undefined;
+                if (constraint && !constraint.conname) {
+                    const name = defaultConstraintName(table, constraint);
+                    if (name) {
+                        constraint.conname = name;
+                        rewritten = true;
+                    }
+                }
+            }
+        }
+        if (rewritten) {
+            pieces.push(`${Deparser.deparse(node, { pretty: true })};`);
+        }
+        else {
+            const start = raw.stmt_location ?? 0;
+            const len = raw.stmt_len;
+            const text = len === undefined ? sql.slice(start) : sql.slice(start, start + len);
+            const trimmed = text.trim();
+            pieces.push(trimmed.endsWith(';') ? trimmed : `${trimmed};`);
+        }
+    }
+    return pieces.join('\n\n');
+}