@pgpmjs/transform 0.21.0 → 0.22.0

package/esm/index.js

@@ -11,7 +11,7 @@ export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './part
 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 { coverChanges, diffChangeSets, diffSchemas, } from './semantic-diff-driver';
 export { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
 export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';

package/esm/module-source.js

@@ -1,10 +1,4 @@
-/**
- * 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 { parsePgpmHeader, parsePlanFile, readScript, resolveReference } from '@pgpmjs/ast';
 import * as path from 'path';
 const TX_LINE = /^\s*(BEGIN|COMMIT|ROLLBACK)\s*;\s*$/i;
 /**
@@ -17,6 +11,31 @@ export const stripTransactionWrapper = (sql) => sql
     .filter(line => !TX_LINE.test(line))
     .join('\n')
     .trim();
+/**
+ * Resolve a plan dependency token to a concrete change name.
+ *
+ * Non-tag tokens (a bare change name, or a `pkg:change` cross-package name)
+ * pass through unchanged — they are already the identity the ledger and
+ * generated plans record. A tag token (`@tag`) is resolved to its change via
+ * the plan that defines it, so a dependency written against a tag is not
+ * re-emitted verbatim into a generated plan or a ledger row. Cross-package
+ * tags (`pkg:@tag`) cannot be resolved from a single module's plan and are
+ * left as-is with a warning; the resolver returns them unchanged. Anything
+ * that fails to resolve is kept verbatim (never dropped) with a warning.
+ */
+const resolveDependencyToken = (token, plan, warnings, changeName) => {
+    if (!token.includes('@'))
+        return token;
+    const resolved = resolveReference(token, plan, plan.package);
+    if (resolved.error || !resolved.change) {
+        warnings.push(`${changeName}: could not resolve dependency tag "${token}" (${resolved.error ?? 'no matching change'}); left as-is`);
+        return token;
+    }
+    if (resolved.change === token) {
+        warnings.push(`${changeName}: dependency tag "${token}" is cross-package; left unresolved (resolve it in workspace context)`);
+    }
+    return resolved.change;
+};
 /**
  * Load a pgpm module from disk: parse pgpm.plan and read each change's
  * deploy script, stripping pgpm headers and transaction wrappers so the
@@ -30,9 +49,10 @@ export const loadModuleSource = (moduleDir) => {
         const reasons = planResult.errors.map(e => e.message).join(', ');
         throw new Error(`Failed to parse pgpm.plan in ${modulePath}: ${reasons}`);
     }
+    const plan = planResult.data;
     const warnings = [];
     const changes = [];
-    for (const change of planResult.data.changes) {
+    for (const change of plan.changes) {
         const raw = readScript(modulePath, 'deploy', change.name);
         if (!raw) {
             warnings.push(`${change.name}: no deploy script found, skipping`);
@@ -41,7 +61,7 @@ export const loadModuleSource = (moduleDir) => {
         const { body } = parsePgpmHeader(raw);
         changes.push({
             name: change.name,
-            dependencies: change.dependencies ?? [],
+            dependencies: (change.dependencies ?? []).map(dep => resolveDependencyToken(dep, plan, warnings, change.name)),
             deploy: stripTransactionWrapper(body)
         });
     }

package/esm/semantic-diff-driver.js

@@ -502,3 +502,38 @@ export function diffChangeSets(from, to, options = {}) {
     const flatten = (changes) => changes.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
     return diffSchemas(flatten(from), flatten(to), options);
 }
+/**
+ * Cover each `to`-side change against a semantic diff's per-object delta:
+ * which of the objects the change touches are already present and identical
+ * on the `from` side. A `satisfied` change deploys nothing new — its ledger
+ * entry can be backfilled instead of executing it; an `unsatisfied` change is
+ * the genuine delta. Identity keying is shared with the diff itself, so
+ * regrouped/renamed/reordered authorship of the same objects covers the same.
+ *
+ * `diff` must come from diffing the same `from` side against these changes
+ * (`diffChangeSets(fromChanges, toChanges)`).
+ */
+export function coverChanges(changes, diff, options = {}) {
+    const style = options.style ?? 'directory';
+    const deltaByKey = new Map();
+    for (const obj of diff.objects) {
+        deltaByKey.set(identityKey(obj.identity), obj.delta);
+    }
+    return changes.map(change => {
+        const sideWarnings = [];
+        const side = readSide(change.deploy, sideWarnings, change.name);
+        const objects = side.order.map(key => {
+            const unit = side.units.get(key);
+            return {
+                path: pathFor(unit.identity, { style }),
+                delta: deltaByKey.get(key) ?? 'unchanged'
+            };
+        });
+        const touched = objects.filter(o => o.delta !== 'unchanged').length;
+        const status = objects.length === 0 ? 'inert'
+            : touched === 0 ? 'satisfied'
+                : touched === objects.length ? 'unsatisfied'
+                    : 'partial';
+        return { name: change.name, status, objects };
+    });
+}

package/index.d.ts

@@ -24,8 +24,8 @@ 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 type { ChangeCoverage, ChangeObjectCoverage, ChangeObjectDelta, ChangeSatisfaction, DiffInputChange, ObjectDelta, SemanticDeltaChange, SemanticDiffOptions, SemanticDiffResult, SemanticObjectDiff, } from './semantic-diff-driver';
+export { coverChanges, 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,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.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;
+exports.loadModule = exports.subObjectIdentityOf = exports.nameUnnamedConstraints = exports.diffSchemas = exports.diffChangeSets = exports.coverChanges = 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; } });
@@ -65,6 +65,7 @@ Object.defineProperty(exports, "EXPORT_GRANULARITIES", { enumerable: true, get:
 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, "coverChanges", { enumerable: true, get: function () { return semantic_diff_driver_1.coverChanges; } });
 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");

package/module-source.js

@@ -34,12 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadModuleSource = exports.stripTransactionWrapper = void 0;
-/**
- * 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.
- */
 const ast_1 = require("@pgpmjs/ast");
 const path = __importStar(require("path"));
 const TX_LINE = /^\s*(BEGIN|COMMIT|ROLLBACK)\s*;\s*$/i;
@@ -54,6 +48,31 @@ const stripTransactionWrapper = (sql) => sql
     .join('\n')
     .trim();
 exports.stripTransactionWrapper = stripTransactionWrapper;
+/**
+ * Resolve a plan dependency token to a concrete change name.
+ *
+ * Non-tag tokens (a bare change name, or a `pkg:change` cross-package name)
+ * pass through unchanged — they are already the identity the ledger and
+ * generated plans record. A tag token (`@tag`) is resolved to its change via
+ * the plan that defines it, so a dependency written against a tag is not
+ * re-emitted verbatim into a generated plan or a ledger row. Cross-package
+ * tags (`pkg:@tag`) cannot be resolved from a single module's plan and are
+ * left as-is with a warning; the resolver returns them unchanged. Anything
+ * that fails to resolve is kept verbatim (never dropped) with a warning.
+ */
+const resolveDependencyToken = (token, plan, warnings, changeName) => {
+    if (!token.includes('@'))
+        return token;
+    const resolved = (0, ast_1.resolveReference)(token, plan, plan.package);
+    if (resolved.error || !resolved.change) {
+        warnings.push(`${changeName}: could not resolve dependency tag "${token}" (${resolved.error ?? 'no matching change'}); left as-is`);
+        return token;
+    }
+    if (resolved.change === token) {
+        warnings.push(`${changeName}: dependency tag "${token}" is cross-package; left unresolved (resolve it in workspace context)`);
+    }
+    return resolved.change;
+};
 /**
  * Load a pgpm module from disk: parse pgpm.plan and read each change's
  * deploy script, stripping pgpm headers and transaction wrappers so the
@@ -67,9 +86,10 @@ const loadModuleSource = (moduleDir) => {
         const reasons = planResult.errors.map(e => e.message).join(', ');
         throw new Error(`Failed to parse pgpm.plan in ${modulePath}: ${reasons}`);
     }
+    const plan = planResult.data;
     const warnings = [];
     const changes = [];
-    for (const change of planResult.data.changes) {
+    for (const change of plan.changes) {
         const raw = (0, ast_1.readScript)(modulePath, 'deploy', change.name);
         if (!raw) {
             warnings.push(`${change.name}: no deploy script found, skipping`);
@@ -78,7 +98,7 @@ const loadModuleSource = (moduleDir) => {
         const { body } = (0, ast_1.parsePgpmHeader)(raw);
         changes.push({
             name: change.name,
-            dependencies: change.dependencies ?? [],
+            dependencies: (change.dependencies ?? []).map(dep => resolveDependencyToken(dep, plan, warnings, change.name)),
             deploy: (0, exports.stripTransactionWrapper)(body)
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.21.0",
+  "version": "0.22.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,16 +39,16 @@
     "plpgsql"
   ],
   "devDependencies": {
-    "@pgpmjs/bundle": "^0.14.0",
+    "@pgpmjs/bundle": "^0.14.1",
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/ast": "^0.11.0",
+    "@pgpmjs/ast": "^0.11.1",
     "@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"
+    "@pgsql/scripts": "^18.3.4",
+    "@pgsql/semantics": "^18.1.2",
+    "@pgsql/transform": "^18.15.2",
+    "plpgsql-parser": "^18.5.3"
   },
-  "gitHead": "d508453a32a2f1d70ff6916871046615226e6f33"
+  "gitHead": "6da0705f8aa49d62dc2defb8b135b71674611483"
 }

package/semantic-diff-driver.d.ts

@@ -90,3 +90,38 @@ export interface DiffInputChange {
  * schema yields an identical diff.
  */
 export declare function diffChangeSets(from: DiffInputChange[], to: DiffInputChange[], options?: SemanticDiffOptions): SemanticDiffResult;
+/** How one object a change touches relates to the diff's delta. */
+export type ChangeObjectDelta = ObjectDelta | 'unchanged';
+/**
+ * Whether a `to`-side change is already satisfied by the `from` side:
+ * - `satisfied`: every object it touches is unchanged in the diff
+ * - `unsatisfied`: every object it touches is added/modified in the diff
+ * - `partial`: a mix of unchanged and delta objects
+ * - `inert`: no identifiable objects (seed data, grants-only, dynamic SQL)
+ */
+export type ChangeSatisfaction = 'satisfied' | 'unsatisfied' | 'partial' | 'inert';
+export interface ChangeObjectCoverage {
+    /** Canonical naming-spec path for the object. */
+    path: string;
+    delta: ChangeObjectDelta;
+}
+export interface ChangeCoverage {
+    /** The input change's name (as given, e.g. `pkg:change`). */
+    name: string;
+    status: ChangeSatisfaction;
+    objects: ChangeObjectCoverage[];
+}
+/**
+ * Cover each `to`-side change against a semantic diff's per-object delta:
+ * which of the objects the change touches are already present and identical
+ * on the `from` side. A `satisfied` change deploys nothing new — its ledger
+ * entry can be backfilled instead of executing it; an `unsatisfied` change is
+ * the genuine delta. Identity keying is shared with the diff itself, so
+ * regrouped/renamed/reordered authorship of the same objects covers the same.
+ *
+ * `diff` must come from diffing the same `from` side against these changes
+ * (`diffChangeSets(fromChanges, toChanges)`).
+ */
+export declare function coverChanges(changes: DiffInputChange[], diff: SemanticDiffResult, options?: {
+    style?: PathStyle;
+}): ChangeCoverage[];

package/semantic-diff-driver.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.diffSchemas = diffSchemas;
 exports.diffChangeSets = diffChangeSets;
+exports.coverChanges = coverChanges;
 /**
  * Semantic diff driver: identity-keyed schema delta between two deploy
  * surfaces.
@@ -506,3 +507,38 @@ function diffChangeSets(from, to, options = {}) {
     const flatten = (changes) => changes.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
     return diffSchemas(flatten(from), flatten(to), options);
 }
+/**
+ * Cover each `to`-side change against a semantic diff's per-object delta:
+ * which of the objects the change touches are already present and identical
+ * on the `from` side. A `satisfied` change deploys nothing new — its ledger
+ * entry can be backfilled instead of executing it; an `unsatisfied` change is
+ * the genuine delta. Identity keying is shared with the diff itself, so
+ * regrouped/renamed/reordered authorship of the same objects covers the same.
+ *
+ * `diff` must come from diffing the same `from` side against these changes
+ * (`diffChangeSets(fromChanges, toChanges)`).
+ */
+function coverChanges(changes, diff, options = {}) {
+    const style = options.style ?? 'directory';
+    const deltaByKey = new Map();
+    for (const obj of diff.objects) {
+        deltaByKey.set(identityKey(obj.identity), obj.delta);
+    }
+    return changes.map(change => {
+        const sideWarnings = [];
+        const side = readSide(change.deploy, sideWarnings, change.name);
+        const objects = side.order.map(key => {
+            const unit = side.units.get(key);
+            return {
+                path: (0, naming_spec_1.pathFor)(unit.identity, { style }),
+                delta: deltaByKey.get(key) ?? 'unchanged'
+            };
+        });
+        const touched = objects.filter(o => o.delta !== 'unchanged').length;
+        const status = objects.length === 0 ? 'inert'
+            : touched === 0 ? 'satisfied'
+                : touched === objects.length ? 'unsatisfied'
+                    : 'partial';
+        return { name: change.name, status, objects };
+    });
+}