@pgpmjs/transform 0.19.0 → 0.21.0

package/module-emit.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkOverwrite = exports.writeModule = exports.writeControlFile = void 0;
+exports.checkOverwrite = exports.appendModule = exports.writeModule = exports.writeControlFile = void 0;
 /**
  * Module emission — the single seam every dials command renders through.
  *
@@ -86,6 +86,77 @@ const writeModule = (outBase, model, extraRequires = []) => {
     return dir;
 };
 exports.writeModule = writeModule;
+/**
+ * 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).
+ */
+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 = (0, ast_1.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 } = (0, ast_1.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
+        };
+        (0, ast_1.writePgpmFiles)(newRows, opts);
+        (0, ast_1.writePlanFile)(planPath, plan);
+    }
+    return { dir: moduleDir, added, skipped, warnings };
+};
+exports.appendModule = appendModule;
 /**
  * Guard against clobbering: writing into the source directory requires
  * `--write`, as does overwriting any existing package directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.19.0",
+  "version": "0.21.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",
@@ -39,15 +39,16 @@
     "plpgsql"
   ],
   "devDependencies": {
-    "@pgpmjs/bundle": "^0.13.3",
+    "@pgpmjs/bundle": "^0.14.0",
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/ast": "^0.10.3",
-    "@pgpmjs/naming-spec": "^0.1.2",
-    "@pgsql/scripts": "^18.3.1",
-    "@pgsql/transform": "^18.14.1",
+    "@pgpmjs/ast": "^0.11.0",
+    "@pgpmjs/naming-spec": "^0.3.0",
+    "@pgsql/scripts": "^18.3.2",
+    "@pgsql/semantics": "^18.1.0",
+    "@pgsql/transform": "^18.15.0",
     "plpgsql-parser": "^18.5.1"
   },
-  "gitHead": "c20b6be96b39bf71c0e2df0f4b51e05deacd006b"
+  "gitHead": "d508453a32a2f1d70ff6916871046615226e6f33"
 }

package/partition-driver.d.ts

@@ -1,7 +1,7 @@
 /**
  * Partition dial: project one deploy surface into a set of pgpm packages.
  *
- * The object graph (statements classified by `@pgsql/transform`, grouped
+ * The object graph (statements classified by `@pgsql/semantics`, grouped
  * into identity-keyed units) is the source of truth; which package a unit
  * lives in is a *derived projection* of a declarative partition config.
  * Units can be assigned by schema, by object kind, by explicit cherry-pick
@@ -21,7 +21,8 @@
  * pgpm.plan + deploy trees, feed a bundle, ...).
  */
 import { PathStyle } from '@pgpmjs/naming-spec';
-import { ObjectIdentity, ObjectIdentityKind, StatementKind } from '@pgsql/transform';
+import { StatementKind } from '@pgsql/semantics';
+import { ObjectIdentity, ObjectIdentityKind } from '@pgsql/transform';
 /** One deployable unit: an object (by identity) and the statements that build it. */
 export interface PartitionUnit {
     /** The object's identity, or `null` for split riders and the residual unit. */

package/partition-driver.js

@@ -5,7 +5,7 @@ exports.partitionUnits = partitionUnits;
 /**
  * Partition dial: project one deploy surface into a set of pgpm packages.
  *
- * The object graph (statements classified by `@pgsql/transform`, grouped
+ * The object graph (statements classified by `@pgsql/semantics`, grouped
  * into identity-keyed units) is the source of truth; which package a unit
  * lives in is a *derived projection* of a declarative partition config.
  * Units can be assigned by schema, by object kind, by explicit cherry-pick
@@ -25,6 +25,7 @@ exports.partitionUnits = partitionUnits;
  * pgpm.plan + deploy trees, feed a bundle, ...).
  */
 const naming_spec_1 = require("@pgpmjs/naming-spec");
+const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
 /** A partition whose packages require each other in a cycle — unshippable. */
 class PartitionCycleError extends Error {
@@ -84,7 +85,7 @@ exports.RESIDUAL_UNIT_PATH = 'misc/statements';
  * otherwise) that depend on their host unit.
  */
 function buildUnitGraph(sql, style, splitRiders) {
-    const facts = (0, transform_1.classifyStatements)(sql);
+    const facts = (0, semantics_1.classifyStatements)(sql);
     const graph = (0, transform_1.buildStatementGraph)(facts);
     const unitOf = new Array(facts.length).fill(-1);
     const units = [];

package/program.d.ts

@@ -9,7 +9,7 @@
  * untouched statements). A program with no dirty statements emits its source
  * byte-identically, so content-addressed hashes are preserved.
  */
-import type { StatementFacts } from '@pgsql/transform';
+import type { StatementFacts } from '@pgsql/semantics';
 /** A statement's location in the source script (byte offsets). */
 export type SqlStatementSpan = StatementFacts['span'];
 /** One statement of a parsed SQL script. */

package/program.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseSqlProgram = parseSqlProgram;
 exports.emitSqlProgram = emitSqlProgram;
-const transform_1 = require("@pgsql/transform");
+const semantics_1 = require("@pgsql/semantics");
 const plpgsql_parser_1 = require("plpgsql-parser");
 /**
  * Parse a SQL script into a statement program. Requires `loadModule()` from
@@ -11,7 +11,7 @@ const plpgsql_parser_1 = require("plpgsql-parser");
 function parseSqlProgram(source) {
     const parseResult = (0, plpgsql_parser_1.parseSql)(source);
     const stmts = parseResult?.stmts ?? [];
-    const facts = (0, transform_1.classifyStatements)(source);
+    const facts = (0, semantics_1.classifyStatements)(source);
     const statements = [];
     for (let i = 0; i < stmts.length; i++) {
         const rawStmt = stmts[i];

package/regen.d.ts

@@ -12,7 +12,7 @@
  * Requires `loadModule()` from `plpgsql-parser` to have completed.
  */
 import type { GeneratedScript } from '@pgsql/scripts';
-import type { StatementFacts } from '@pgsql/transform';
+import type { StatementFacts } from '@pgsql/semantics';
 export type { GeneratedScript } from '@pgsql/scripts';
 /** Generated revert and verify scripts for one change's deploy SQL. */
 export interface RegeneratedScripts {

package/regen.js

@@ -4,13 +4,13 @@ exports.classifyScript = classifyScript;
 exports.isStubScript = isStubScript;
 exports.regenerateScripts = regenerateScripts;
 const scripts_1 = require("@pgsql/scripts");
-const transform_1 = require("@pgsql/transform");
+const semantics_1 = require("@pgsql/semantics");
 /**
  * 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');
+    return (0, semantics_1.classifyStatements)(sql).filter(f => f.nodeTag !== 'TransactionStmt');
 }
 /**
  * Whether a script is an empty stub: nothing but comments, whitespace, and

package/restructure.d.ts

@@ -8,6 +8,7 @@
 import { PgpmRow } from '@pgpmjs/ast';
 import { PathStyle } from '@pgpmjs/naming-spec';
 import { Granularity } from '@pgsql/transform';
+import { ChangeGranularity } from './granularity-driver';
 export type ExportGranularity = Granularity;
 export declare const EXPORT_GRANULARITIES: readonly ExportGranularity[];
 export declare const isExportGranularity: (value: unknown) => value is ExportGranularity;
@@ -18,6 +19,12 @@ export interface RestructureExportRowsResult {
 export interface RestructureExportRowsOptions {
     /** Naming-spec rendering style for derived paths (default `directory`). */
     naming?: PathStyle;
+    /**
+     * Change-level distribution (default `object`): with `alteration`, each
+     * `ADD COLUMN` / `ADD CONSTRAINT` becomes its own change. See
+     * {@link ChangeGranularity}.
+     */
+    changeGranularity?: ChangeGranularity;
 }
 /**
  * Restructure exported migration rows to the target granularity.

package/restructure.js

@@ -37,7 +37,12 @@ const restructureExportRows = async (rows, granularity, options = {}) => {
         name: row.deploy,
         dependencies: row.deps ?? [],
         deploy: row.content
-    })), { granularity, changeName });
+    })), {
+        granularity,
+        changeGranularity: options.changeGranularity,
+        changeName,
+        subObjectName: identity => (0, naming_spec_1.pathFor)(identity, { style })
+    });
     const counters = new Map();
     const taken = new Set();
     const restructured = changes.map(change => {

package/semantic-diff-driver.d.ts

@@ -29,7 +29,7 @@
 import { PathStyle } from '@pgpmjs/naming-spec';
 import type { ObjectIdentity } from '@pgsql/transform';
 import { Granularity } from '@pgsql/transform';
-import { GranularityChange } from './granularity-driver';
+import { ChangeGranularity, GranularityChange } from './granularity-driver';
 /** How one object differs between the two sides. */
 export type ObjectDelta = 'added' | 'removed' | 'modified';
 export interface SemanticObjectDiff {
@@ -45,6 +45,8 @@ export interface SemanticObjectDiff {
 export interface SemanticDiffOptions {
     /** Granularity for the emitted CREATE/ALTER changes (default `object`). */
     granularity?: Granularity;
+    /** Change-level distribution for emitted changes (default `object`). */
+    changeGranularity?: ChangeGranularity;
     /** Naming-spec rendering style (default `directory`). */
     style?: PathStyle;
 }

package/semantic-diff-driver.js

@@ -32,8 +32,10 @@ exports.diffChangeSets = diffChangeSets;
  */
 const naming_spec_1 = require("@pgpmjs/naming-spec");
 const scripts_1 = require("@pgsql/scripts");
+const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
 const plpgsql_parser_1 = require("plpgsql-parser");
+const constraint_names_1 = require("./constraint-names");
 const granularity_driver_1 = require("./granularity-driver");
 const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
 /**
@@ -43,7 +45,7 @@ const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table
  * statements are reported via `warnings`.
  */
 function readSide(sql, warnings, label) {
-    const facts = (0, transform_1.classifyStatements)(sql);
+    const facts = (0, semantics_1.classifyStatements)(sql);
     const graph = (0, transform_1.buildStatementGraph)(facts);
     const units = new Map();
     const order = [];
@@ -103,7 +105,7 @@ 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') &&
+    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 };
     }
@@ -116,21 +118,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 = (0, transform_1.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 = (0, transform_1.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 (0, plpgsql_parser_1.parseSync)(text).sql.stmts) {
@@ -141,6 +183,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);
                 }
@@ -156,6 +201,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 });
                     }
@@ -166,6 +216,44 @@ function tableShape(unit) {
             }
         }
     }
+    for (const { node, column } of constraints) {
+        const canonical = { ...node };
+        canonical.conname = node.conname ?? (0, constraint_names_1.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 => (0, transform_1.cleanTree)(c))
+            .sort((x, y) => stablePrint(x).localeCompare(stablePrint(y)));
+        const clean = (0, transform_1.cleanTree)({ ...def, constraints: sorted });
+        shape.columns.set(colname, { def: clean, print: stablePrint(clean) });
+    }
     return shape;
 }
 const deparseStmt = (node) => `${plpgsql_parser_1.Deparser.deparse(node, { pretty: false })};`;
@@ -280,7 +368,7 @@ function diffSchemas(from, to, options = {}) {
      * statement to surface its not-derivable comment and warning.
      */
     const inverseOf = (deploy, context) => {
-        const facts = (0, transform_1.classifyStatements)(deploy);
+        const facts = (0, semantics_1.classifyStatements)(deploy);
         const graph = (0, transform_1.buildStatementGraph)(facts);
         const pieces = [];
         for (const i of [...graph.order].reverse()) {
@@ -303,7 +391,7 @@ function diffSchemas(from, to, options = {}) {
      */
     const verifyOf = (deploy, context) => {
         const pieces = [];
-        for (const fact of (0, transform_1.classifyStatements)(deploy)) {
+        for (const fact of (0, semantics_1.classifyStatements)(deploy)) {
             const nodes = (0, scripts_1.existenceCheck)(fact);
             if (nodes === null) {
                 const { warnings: w } = (0, scripts_1.verifyFor)([fact]);
@@ -389,7 +477,11 @@ function diffSchemas(from, to, options = {}) {
     }
     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' });
+        const { changes, warnings: w } = (0, granularity_driver_1.restructureChanges)([{ name: 'delta', dependencies: [], deploy: forwardSql.join('\n\n') }], {
+            granularity: options.granularity ?? 'object',
+            changeGranularity: options.changeGranularity,
+            subObjectName: identity => (0, naming_spec_1.pathFor)(identity, { style })
+        });
         forwardChanges = changes.map(c => ({
             ...c,
             revert: inverseOf(c.deploy, c.name),

package/sub-object.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sub-object identities: the column or constraint a single `ALTER TABLE`
+ * statement adds.
+ *
+ * `identityOf` summarizes an ALTER TABLE by the table it targets — the right
+ * grouping key for object-level changes, but lossy one level down: the added
+ * column's `colname` and the added constraint's `conname` stay behind in the
+ * raw parse node (`facts.stmt`). This module recovers them, giving the
+ * change-granularity pipeline a stable identity (and naming-spec path) for
+ * every alteration.
+ */
+import type { ObjectIdentity } from '@pgpmjs/naming-spec';
+import type { StatementFacts } from '@pgsql/semantics';
+/**
+ * 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 declare function subObjectIdentityOf(facts: StatementFacts): ObjectIdentity | 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 declare function nameUnnamedConstraints(sql: string): string;

package/sub-object.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subObjectIdentityOf = subObjectIdentityOf;
+exports.nameUnnamedConstraints = nameUnnamedConstraints;
+const plpgsql_parser_1 = require("plpgsql-parser");
+const constraint_names_1 = require("./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.
+ */
+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 ?? (0, constraint_names_1.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.
+ */
+function nameUnnamedConstraints(sql) {
+    const parsed = (0, plpgsql_parser_1.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 = (0, constraint_names_1.defaultConstraintName)(table, constraint);
+                    if (name) {
+                        constraint.conname = name;
+                        rewritten = true;
+                    }
+                }
+            }
+        }
+        if (rewritten) {
+            pieces.push(`${plpgsql_parser_1.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');
+}