@pgpmjs/transform 0.18.0 → 0.20.0

package/fixture-closure.d.ts

@@ -1,5 +1,5 @@
-import { CategoryProfile, ChangeCategory } from './categorize';
 import { QualifiedName } from '@pgsql/transform';
+import { CategoryProfile, ChangeCategory } from './categorize';
 /**
  * A change plus its deploy SQL. Optional plan `dependencies` (from `pgpm.plan`)
  * are followed as authoritative prerequisites in addition to AST-derived edges.

package/fixture-closure.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveFixtureClosure = resolveFixtureClosure;
-const categorize_1 = require("./categorize");
 const transform_1 = require("@pgsql/transform");
+const categorize_1 = require("./categorize");
 function objectKey(schema, name) {
     return `${schema ?? ''}\u0000${name}`;
 }

package/granularity-driver.d.ts

@@ -1,5 +1,41 @@
+/**
+ * Granularity driver: restructure a pgpm module's deploy surface between the
+ * atomic, object, and consolidated shapes.
+ *
+ * The upstream pass (`restructureSql` in `@pgsql/transform`) rewrites one SQL
+ * script between equivalent shapes, guarded by the statement dependency
+ * graph. This driver lifts that to the pgpm change model: it flattens a
+ * module's deploy scripts in plan order into one program, restructures it to
+ * the target granularity, then re-slices the result into changes — one change
+ * per created object — with change dependencies recomputed from the statement
+ * graph. Like the other drivers in this package it is structurally typed on
+ * the bundle seams: no dependency on `@pgpmjs/bundle` or `@pgpmjs/core`.
+ *
+ * - `atomic`       — the machine-emitted shape: bare CREATE TABLE plus one
+ *                    ALTER per column/constraint.
+ * - `object`       — each table fully baked; cross-object statements
+ *                    (FKs, indexes, triggers, policies) stay separate.
+ * - `consolidated` — additionally inlines FKs proven safe by the graph.
+ */
+import type { ObjectIdentity as NamingIdentity } from '@pgpmjs/naming-spec';
 import type { Granularity, StatementFacts } from '@pgsql/transform';
 export type { Granularity } from '@pgsql/transform';
+/**
+ * How statements are distributed across pgpm changes — orthogonal to
+ * `Granularity`, which shapes the SQL *within* a change.
+ *
+ * - `alteration` — one change per alteration: every `ADD COLUMN` /
+ *                  `ADD CONSTRAINT` becomes its own plan entry with its own
+ *                  deploy/revert/verify and graph-derived requires, so a
+ *                  single column can deploy or revert independently.
+ * - `object`     — one change per created object (the default): a table's
+ *                  CREATE and all its ALTERs share one plan entry.
+ * - `single`     — one change for the whole module: every statement lands in
+ *                  a single plan entry with one deploy/revert/verify.
+ */
+export type ChangeGranularity = 'alteration' | 'object' | 'single';
+export declare const CHANGE_GRANULARITIES: readonly ChangeGranularity[];
+export declare const isChangeGranularity: (value: string) => value is ChangeGranularity;
 /** A change's deploy surface going into or out of the restructure. */
 export interface GranularityChange {
     /** Change name (plan token, e.g. `schemas/app/tables/users/table`). */
@@ -26,6 +62,27 @@ export interface RestructuredChange extends GranularityChange {
 }
 export interface RestructureModuleOptions {
     granularity: Granularity;
+    /**
+     * Change-level distribution (default `object`). With `alteration`, every
+     * single-command `ALTER TABLE ADD COLUMN` / `ADD CONSTRAINT` in the
+     * restructured script becomes its own change, named by the sub-object's
+     * naming-spec path (`.../columns/{name}/column`,
+     * `.../constraints/{name}/constraint`); unnamed constraints are first
+     * given their Postgres default name so each change stays revertible.
+     * With `single`, the whole restructured script becomes one change.
+     */
+    changeGranularity?: ChangeGranularity;
+    /**
+     * Plan token for the single change (used only with `changeGranularity:
+     * 'single'`). Defaults to `module/init`.
+     */
+    singleChangeName?: string;
+    /**
+     * Derive a change name for an alteration group from its sub-object
+     * identity (used only with `changeGranularity: 'alteration'`). Defaults to
+     * `pathFor` in `directory` style.
+     */
+    subObjectName?: (identity: NamingIdentity) => string;
     /**
      * Derive a change name for a statement group from the facts of its primary
      * (creating) statement. Defaults to {@link defaultChangeName}: naming spec

package/granularity-driver.js

@@ -1,29 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isChangeGranularity = exports.CHANGE_GRANULARITIES = void 0;
 exports.defaultChangeName = defaultChangeName;
 exports.restructureChanges = restructureChanges;
-/**
- * Granularity driver: restructure a pgpm module's deploy surface between the
- * atomic, object, and consolidated shapes.
- *
- * The upstream pass (`restructureSql` in `@pgsql/transform`) rewrites one SQL
- * script between equivalent shapes, guarded by the statement dependency
- * graph. This driver lifts that to the pgpm change model: it flattens a
- * module's deploy scripts in plan order into one program, restructures it to
- * the target granularity, then re-slices the result into changes — one change
- * per created object — with change dependencies recomputed from the statement
- * graph. Like the other drivers in this package it is structurally typed on
- * the bundle seams: no dependency on `@pgpmjs/bundle` or `@pgpmjs/core`.
- *
- * - `atomic`       — the machine-emitted shape: bare CREATE TABLE plus one
- *                    ALTER per column/constraint.
- * - `object`       — each table fully baked; cross-object statements
- *                    (FKs, indexes, triggers, policies) stay separate.
- * - `consolidated` — additionally inlines FKs proven safe by the graph.
- */
 const naming_spec_1 = require("@pgpmjs/naming-spec");
 const scripts_1 = require("@pgsql/scripts");
 const transform_1 = require("@pgsql/transform");
+const sub_object_1 = require("./sub-object");
+exports.CHANGE_GRANULARITIES = ['alteration', 'object', 'single'];
+const isChangeGranularity = (value) => exports.CHANGE_GRANULARITIES.includes(value);
+exports.isChangeGranularity = isChangeGranularity;
 const KIND_DIRS = {
     table: 'tables',
     view: 'views',
@@ -57,22 +43,50 @@ function defaultChangeName(facts) {
  */
 function restructureChanges(changes, options) {
     const nameFor = options.changeName ?? defaultChangeName;
+    const subNameFor = options.subObjectName ?? ((identity) => (0, naming_spec_1.pathFor)(identity));
+    const alteration = options.changeGranularity === 'alteration';
     const flattened = changes
         .map(c => c.deploy.trim())
         .filter(Boolean)
         .join('\n\n');
-    const { sql, warnings } = (0, transform_1.restructureSql)(flattened, {
+    const restructured = (0, transform_1.restructureSql)(flattened, {
         granularity: options.granularity
     });
+    const warnings = restructured.warnings;
+    const sql = alteration ? (0, sub_object_1.nameUnnamedConstraints)(restructured.sql) : restructured.sql;
     // Re-classify the emitted script; group statements by the object they
     // target (creates[0]), so a table's CREATE and its remaining ALTERs land
     // in the same change regardless of statement kind.
     const facts = (0, transform_1.classifyStatements)(sql);
+    if (options.changeGranularity === 'single') {
+        const name = options.singleChangeName ?? 'module/init';
+        const inputNames = new Set(changes.map(c => c.name));
+        const dependencies = [...new Set(changes.flatMap(c => c.dependencies).filter(d => !inputNames.has(d)))].sort();
+        const statements = facts
+            .map(f => sql.slice(f.span.start, f.span.start + f.span.len).trim())
+            .filter(Boolean)
+            .map(text => (text.endsWith(';') ? text : `${text};`));
+        const revert = (0, scripts_1.revertFor)(facts);
+        const verify = (0, scripts_1.verifyFor)(facts);
+        for (const warning of [...revert.warnings, ...verify.warnings]) {
+            warnings.push(`${name}: ${warning}`);
+        }
+        return {
+            changes: statements.length > 0
+                ? [{ name, dependencies, deploy: statements.join('\n\n'), revert: revert.sql, verify: verify.sql }]
+                : [],
+            warnings
+        };
+    }
     const graph = (0, transform_1.buildStatementGraph)(facts);
     const groupOf = new Array(facts.length).fill(-1);
     const groupKeys = [];
     const groupFacts = [];
     const groupKeyToIndex = new Map();
+    /** Sub-object path for alteration groups; null means name via `nameFor`. */
+    const groupSubName = [];
+    /** For alteration groups: the object-group key of the owning table. */
+    const groupOwnerKey = [];
     facts.forEach((f, i) => {
         const created = f.creates[0];
         if (!created) {
@@ -82,12 +96,31 @@ function restructureChanges(changes, options) {
                 groupOf[i] = groupOf[i - 1];
             return;
         }
+        if (alteration) {
+            const sub = (0, sub_object_1.subObjectIdentityOf)(f);
+            if (sub) {
+                const key = `sub\u0000${sub.kind}\u0000${sub.schema ?? ''}\u0000${sub.table}\u0000${sub.name}`;
+                let g = groupKeyToIndex.get(key);
+                if (g === undefined) {
+                    g = groupKeys.length;
+                    groupKeys.push(key);
+                    groupFacts.push(f);
+                    groupSubName.push(subNameFor(sub));
+                    groupOwnerKey.push(`${sub.schema ?? ''}.${sub.table}`);
+                    groupKeyToIndex.set(key, g);
+                }
+                groupOf[i] = g;
+                return;
+            }
+        }
         const key = `${created.schema ?? ''}.${created.name}`;
         let g = groupKeyToIndex.get(key);
         if (g === undefined) {
             g = groupKeys.length;
             groupKeys.push(key);
             groupFacts.push(f);
+            groupSubName.push(null);
+            groupOwnerKey.push(null);
             groupKeyToIndex.set(key, g);
         }
         else if (!(groupFacts[g].kind in KIND_DIRS) && groupFacts[g].kind !== 'schema' && (f.kind in KIND_DIRS || f.kind === 'schema')) {
@@ -96,7 +129,7 @@ function restructureChanges(changes, options) {
         }
         groupOf[i] = g;
     });
-    const groupNames = groupFacts.map(nameFor);
+    const groupNames = groupFacts.map((f, g) => groupSubName[g] ?? nameFor(f));
     // Schema producers, for schema-level change dependencies.
     const schemaGroup = new Map();
     facts.forEach((f, i) => {
@@ -142,6 +175,38 @@ function restructureChanges(changes, options) {
                 groupDeps[from].add(to);
         }
     });
+    // Alteration groups depend on their table's own change, and constraint
+    // groups additionally on the column changes they key on — the statement
+    // graph keys everything by the table, so these finer edges are added here.
+    if (alteration) {
+        const columnGroup = new Map();
+        groupKeys.forEach((key, g) => {
+            const parts = key.split('\u0000');
+            if (parts[0] === 'sub' && parts[1] === 'column') {
+                columnGroup.set(`${parts[2]}.${parts[3]}.${parts[4]}`, g);
+            }
+        });
+        groupKeys.forEach((key, g) => {
+            const owner = groupOwnerKey[g];
+            if (owner === null)
+                return;
+            const tableGroup = groupKeyToIndex.get(owner);
+            if (tableGroup !== undefined && tableGroup !== g)
+                groupDeps[g].add(tableGroup);
+            const parts = key.split('\u0000');
+            if (parts[1] !== 'constraint')
+                return;
+            const constraint = groupFacts[g].stmt?.AlterTableStmt?.cmds?.[0]?.AlterTableCmd?.def?.Constraint;
+            const referenced = [...(constraint?.keys ?? []), ...(constraint?.fk_attrs ?? [])]
+                .map(k => k.String?.sval)
+                .filter((s) => typeof s === 'string');
+            for (const col of referenced) {
+                const to = columnGroup.get(`${owner}.${col}`);
+                if (to !== undefined && to !== g)
+                    groupDeps[g].add(to);
+            }
+        });
+    }
     // Emit groups in first-statement order (already topological).
     const order = [...groupNames.keys()].sort((a, b) => {
         const firstA = groupOf.indexOf(a);

package/index.d.ts

@@ -1,18 +1,31 @@
-export * from '@pgsql/transform';
-export { loadModule } from 'plpgsql-parser';
 export type { BundleScriptContext, ExtensionRoutingInput, NamespaceValidatorOptions, SchemaObjectRoute, SchemaTranspiler, SchemaTranspilerOptions, } from './bundle-driver';
 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 { CatalogQueryable, CatalogSnapshot } from './catalog-check';
+export { diffCatalogSnapshots, snapshotCatalog, withoutColumnOrder } from './catalog-check';
 export type { CategoryProfile, ChangeCategory, } from './categorize';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
+export type { ConstraintNode } from './constraint-names';
+export { defaultConstraintName, firstColumnRef } from './constraint-names';
 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 { ChangeGranularity, GranularityChange, RestructuredChange, RestructureModuleOptions, RestructureModuleResult, } from './granularity-driver';
+export { CHANGE_GRANULARITIES, defaultChangeName, isChangeGranularity, restructureChanges, } from './granularity-driver';
+export type { AppendModuleResult, PgpmModuleModel } from './module-emit';
+export { appendModule, checkOverwrite, writeControlFile, writeModule } from './module-emit';
+export type { ModuleSource, ModuleSourceChange } from './module-source';
+export { loadModuleSource, stripTransactionWrapper } from './module-source';
+export type { PartitionedPackageRows, PartitionExportRowsResult } from './partition';
+export { parsePartitionConfig, partitionExportRows } from './partition';
+export type { PartitionConfig, PartitionedChange, PartitionedPackage, PartitionInputChange, PartitionRule, PartitionUnit, PartitionUnitsResult, UnitSelector, } from './partition-driver';
+export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
 export type { SqlProgram, SqlStatementAst, SqlStatementSpan, } from './program';
 export { emitSqlProgram, parseSqlProgram } from './program';
+export type { GeneratedScript, RegeneratedScripts, } from './regen';
+export { classifyScript, isStubScript, regenerateScripts, } from './regen';
+export type { ExportGranularity, RestructureExportRowsOptions, RestructureExportRowsResult } from './restructure';
+export { EXPORT_GRANULARITIES, isExportGranularity, restructureExportRows } from './restructure';
+export type { DiffInputChange, ObjectDelta, SemanticDeltaChange, SemanticDiffOptions, SemanticDiffResult, SemanticObjectDiff, } from './semantic-diff-driver';
+export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
+export { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
+export * from '@pgsql/transform';
+export { loadModule } from 'plpgsql-parser';

package/index.js

@@ -14,35 +14,62 @@ 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.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; } });
+exports.loadModule = exports.subObjectIdentityOf = exports.nameUnnamedConstraints = exports.diffSchemas = exports.diffChangeSets = exports.restructureExportRows = exports.isExportGranularity = exports.EXPORT_GRANULARITIES = exports.regenerateScripts = exports.isStubScript = exports.classifyScript = exports.parseSqlProgram = exports.emitSqlProgram = exports.RESIDUAL_UNIT_PATH = exports.partitionUnits = exports.PartitionCycleError = exports.partitionExportRows = exports.parsePartitionConfig = exports.stripTransactionWrapper = exports.loadModuleSource = exports.writeModule = exports.writeControlFile = exports.checkOverwrite = exports.appendModule = exports.restructureChanges = exports.isChangeGranularity = exports.defaultChangeName = exports.CHANGE_GRANULARITIES = exports.resolveFixtureClosure = exports.firstColumnRef = exports.defaultConstraintName = exports.TIER_PROFILE = exports.categorizeChange = exports.buildCategoryOf = exports.withoutColumnOrder = exports.snapshotCatalog = exports.diffCatalogSnapshots = exports.makeSchemaTranspiler = exports.makeNamespaceValidator = exports.buildSchemaRouter = exports.buildExtensionRouter = void 0;
 var bundle_driver_1 = require("./bundle-driver");
 Object.defineProperty(exports, "buildExtensionRouter", { enumerable: true, get: function () { return bundle_driver_1.buildExtensionRouter; } });
 Object.defineProperty(exports, "buildSchemaRouter", { enumerable: true, get: function () { return bundle_driver_1.buildSchemaRouter; } });
 Object.defineProperty(exports, "makeNamespaceValidator", { enumerable: true, get: function () { return bundle_driver_1.makeNamespaceValidator; } });
 Object.defineProperty(exports, "makeSchemaTranspiler", { enumerable: true, get: function () { return bundle_driver_1.makeSchemaTranspiler; } });
+var catalog_check_1 = require("./catalog-check");
+Object.defineProperty(exports, "diffCatalogSnapshots", { enumerable: true, get: function () { return catalog_check_1.diffCatalogSnapshots; } });
+Object.defineProperty(exports, "snapshotCatalog", { enumerable: true, get: function () { return catalog_check_1.snapshotCatalog; } });
+Object.defineProperty(exports, "withoutColumnOrder", { enumerable: true, get: function () { return catalog_check_1.withoutColumnOrder; } });
+var categorize_1 = require("./categorize");
+Object.defineProperty(exports, "buildCategoryOf", { enumerable: true, get: function () { return categorize_1.buildCategoryOf; } });
+Object.defineProperty(exports, "categorizeChange", { enumerable: true, get: function () { return categorize_1.categorizeChange; } });
+Object.defineProperty(exports, "TIER_PROFILE", { enumerable: true, get: function () { return categorize_1.TIER_PROFILE; } });
+var constraint_names_1 = require("./constraint-names");
+Object.defineProperty(exports, "defaultConstraintName", { enumerable: true, get: function () { return constraint_names_1.defaultConstraintName; } });
+Object.defineProperty(exports, "firstColumnRef", { enumerable: true, get: function () { return constraint_names_1.firstColumnRef; } });
+var fixture_closure_1 = require("./fixture-closure");
+Object.defineProperty(exports, "resolveFixtureClosure", { enumerable: true, get: function () { return fixture_closure_1.resolveFixtureClosure; } });
 var granularity_driver_1 = require("./granularity-driver");
+Object.defineProperty(exports, "CHANGE_GRANULARITIES", { enumerable: true, get: function () { return granularity_driver_1.CHANGE_GRANULARITIES; } });
 Object.defineProperty(exports, "defaultChangeName", { enumerable: true, get: function () { return granularity_driver_1.defaultChangeName; } });
+Object.defineProperty(exports, "isChangeGranularity", { enumerable: true, get: function () { return granularity_driver_1.isChangeGranularity; } });
 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 module_emit_1 = require("./module-emit");
+Object.defineProperty(exports, "appendModule", { enumerable: true, get: function () { return module_emit_1.appendModule; } });
+Object.defineProperty(exports, "checkOverwrite", { enumerable: true, get: function () { return module_emit_1.checkOverwrite; } });
+Object.defineProperty(exports, "writeControlFile", { enumerable: true, get: function () { return module_emit_1.writeControlFile; } });
+Object.defineProperty(exports, "writeModule", { enumerable: true, get: function () { return module_emit_1.writeModule; } });
+var module_source_1 = require("./module-source");
+Object.defineProperty(exports, "loadModuleSource", { enumerable: true, get: function () { return module_source_1.loadModuleSource; } });
+Object.defineProperty(exports, "stripTransactionWrapper", { enumerable: true, get: function () { return module_source_1.stripTransactionWrapper; } });
+var partition_1 = require("./partition");
+Object.defineProperty(exports, "parsePartitionConfig", { enumerable: true, get: function () { return partition_1.parsePartitionConfig; } });
+Object.defineProperty(exports, "partitionExportRows", { enumerable: true, get: function () { return partition_1.partitionExportRows; } });
 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; } });
 Object.defineProperty(exports, "RESIDUAL_UNIT_PATH", { enumerable: true, get: function () { return partition_driver_1.RESIDUAL_UNIT_PATH; } });
-var categorize_1 = require("./categorize");
-Object.defineProperty(exports, "buildCategoryOf", { enumerable: true, get: function () { return categorize_1.buildCategoryOf; } });
-Object.defineProperty(exports, "categorizeChange", { enumerable: true, get: function () { return categorize_1.categorizeChange; } });
-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 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; } });
 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; } });
+var restructure_1 = require("./restructure");
+Object.defineProperty(exports, "EXPORT_GRANULARITIES", { enumerable: true, get: function () { return restructure_1.EXPORT_GRANULARITIES; } });
+Object.defineProperty(exports, "isExportGranularity", { enumerable: true, get: function () { return restructure_1.isExportGranularity; } });
+Object.defineProperty(exports, "restructureExportRows", { enumerable: true, get: function () { return restructure_1.restructureExportRows; } });
+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 sub_object_1 = require("./sub-object");
+Object.defineProperty(exports, "nameUnnamedConstraints", { enumerable: true, get: function () { return sub_object_1.nameUnnamedConstraints; } });
+Object.defineProperty(exports, "subObjectIdentityOf", { enumerable: true, get: function () { return sub_object_1.subObjectIdentityOf; } });
+__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; } });

package/module-emit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Module emission — the single seam every dials command renders through.
+ *
+ * The engine (semantic diff, granularity, partition) produces plan-ordered
+ * {@link PgpmRow}s; a {@link PgpmModuleModel} is just those rows plus the
+ * module's name and control-file requires. `writeModule` is the one writer
+ * that turns a model into an on-disk pgpm module (`.control` + `pgpm.plan` +
+ * deploy/revert/verify trees) — so `pgpm diff`, `pgpm transform`, and
+ * `pgpm import` all emit byte-identical module layouts instead of each
+ * carrying its own copy of the writer.
+ */
+import { PgpmRow } from '@pgpmjs/ast';
+/**
+ * A pgpm module as an in-memory value: a name, the extensions it requires
+ * (control-file names), and its changes in plan order. `writeModule` and the
+ * other projections (linear SQL, bundle) are pure functions of this model.
+ */
+export interface PgpmModuleModel {
+    /** Package (module) name. */
+    name: string;
+    /** Module names this package requires (control-file names). */
+    requires: string[];
+    /** Changes in plan order. */
+    rows: PgpmRow[];
+}
+/** Write a module's Postgres extension `.control` file. */
+export declare const writeControlFile: (dir: string, name: string, requires: string[]) => void;
+/**
+ * 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 declare const writeModule: (outBase: string, model: PgpmModuleModel, extraRequires?: string[]) => string;
+/** Result of appending changes into an existing module (see {@link appendModule}). */
+export interface AppendModuleResult {
+    /** The module directory that was appended to. */
+    dir: string;
+    /** Change names that were added to the plan. */
+    added: string[];
+    /** Change names skipped because they already exist in the plan. */
+    skipped: string[];
+    /** Non-fatal notices (skips, dropped dangling dependencies). */
+    warnings: string[];
+}
+/**
+ * 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 declare const appendModule: (moduleDir: string, rows: PgpmRow[], options?: {
+    author?: string;
+}) => AppendModuleResult;
+/**
+ * Guard against clobbering: writing into the source directory requires
+ * `--write`, as does overwriting any existing package directory.
+ */
+export declare const checkOverwrite: (targetDir: string, sourcePath: string, write: boolean) => string | null;

package/module-emit.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkOverwrite = exports.appendModule = exports.writeModule = exports.writeControlFile = void 0;
+/**
+ * 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.
+ */
+const ast_1 = require("@pgpmjs/ast");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Write a module's Postgres extension `.control` file. */
+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');
+};
+exports.writeControlFile = writeControlFile;
+/**
+ * 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.
+ */
+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 });
+    (0, exports.writeControlFile)(dir, model.name, [...extraRequires, ...model.requires]);
+    const opts = {
+        outdir: outBase,
+        name: model.name,
+        replacer: (str) => str.split('constructive-extension-name').join(model.name)
+    };
+    (0, ast_1.writePgpmPlan)(model.rows, opts);
+    (0, ast_1.writePgpmFiles)(model.rows, opts);
+    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.
+ */
+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;
+};
+exports.checkOverwrite = checkOverwrite;