@pgpmjs/transform 0.21.0 → 0.23.0

package/byte-slice.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Byte-correct statement slicing.
+ *
+ * libpg-query reports statement offsets (`stmt_location` / `stmt_len`, and the
+ * `span` that `@pgsql/semantics` derives from them) as UTF-8 **byte** offsets,
+ * but JavaScript string indexing is UTF-16. The two agree only while a script
+ * is pure ASCII; a single non-ASCII byte (an em dash in a comment, an accented
+ * word in a seed row, an emoji) shifts every later byte offset past its JS
+ * index, so slicing the source string directly with `String.prototype.slice`
+ * mis-cuts every statement that follows it — e.g. `COMMENT ON ...` reappears as
+ * `MMENT ON ...` and fails to reparse.
+ *
+ * Slice on the UTF-8 bytes instead and decode back to text. Statement offsets
+ * always fall on character boundaries, so decoding a byte range never splits a
+ * multibyte character.
+ */
+export declare const sqlSourceBytes: (source: string) => Buffer;
+/**
+ * Slice a statement's verbatim text out of the source bytes by its byte-offset
+ * span. `len === undefined` slices to the end of the source (libpg-query omits
+ * `stmt_len` for the final statement).
+ */
+export declare const sliceStatementBytes: (sourceBytes: Buffer, start: number, len?: number) => string;

package/byte-slice.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sliceStatementBytes = exports.sqlSourceBytes = void 0;
+/**
+ * Byte-correct statement slicing.
+ *
+ * libpg-query reports statement offsets (`stmt_location` / `stmt_len`, and the
+ * `span` that `@pgsql/semantics` derives from them) as UTF-8 **byte** offsets,
+ * but JavaScript string indexing is UTF-16. The two agree only while a script
+ * is pure ASCII; a single non-ASCII byte (an em dash in a comment, an accented
+ * word in a seed row, an emoji) shifts every later byte offset past its JS
+ * index, so slicing the source string directly with `String.prototype.slice`
+ * mis-cuts every statement that follows it — e.g. `COMMENT ON ...` reappears as
+ * `MMENT ON ...` and fails to reparse.
+ *
+ * Slice on the UTF-8 bytes instead and decode back to text. Statement offsets
+ * always fall on character boundaries, so decoding a byte range never splits a
+ * multibyte character.
+ */
+const sqlSourceBytes = (source) => Buffer.from(source, 'utf8');
+exports.sqlSourceBytes = sqlSourceBytes;
+/**
+ * Slice a statement's verbatim text out of the source bytes by its byte-offset
+ * span. `len === undefined` slices to the end of the source (libpg-query omits
+ * `stmt_len` for the final statement).
+ */
+const sliceStatementBytes = (sourceBytes, start, len) => {
+    const end = len === undefined ? sourceBytes.length : start + len;
+    return sourceBytes.subarray(start, end).toString('utf8');
+};
+exports.sliceStatementBytes = sliceStatementBytes;

package/esm/byte-slice.js

@@ -0,0 +1,26 @@
+/**
+ * Byte-correct statement slicing.
+ *
+ * libpg-query reports statement offsets (`stmt_location` / `stmt_len`, and the
+ * `span` that `@pgsql/semantics` derives from them) as UTF-8 **byte** offsets,
+ * but JavaScript string indexing is UTF-16. The two agree only while a script
+ * is pure ASCII; a single non-ASCII byte (an em dash in a comment, an accented
+ * word in a seed row, an emoji) shifts every later byte offset past its JS
+ * index, so slicing the source string directly with `String.prototype.slice`
+ * mis-cuts every statement that follows it — e.g. `COMMENT ON ...` reappears as
+ * `MMENT ON ...` and fails to reparse.
+ *
+ * Slice on the UTF-8 bytes instead and decode back to text. Statement offsets
+ * always fall on character boundaries, so decoding a byte range never splits a
+ * multibyte character.
+ */
+export const sqlSourceBytes = (source) => Buffer.from(source, 'utf8');
+/**
+ * Slice a statement's verbatim text out of the source bytes by its byte-offset
+ * span. `len === undefined` slices to the end of the source (libpg-query omits
+ * `stmt_len` for the final statement).
+ */
+export const sliceStatementBytes = (sourceBytes, start, len) => {
+    const end = len === undefined ? sourceBytes.length : start + len;
+    return sourceBytes.subarray(start, end).toString('utf8');
+};

package/esm/granularity-driver.js

@@ -2,6 +2,7 @@ import { pathFor } from '@pgpmjs/naming-spec';
 import { revertFor, verifyFor } from '@pgsql/scripts';
 import { classifyStatements } from '@pgsql/semantics';
 import { buildStatementGraph, identityOf, restructureSql } from '@pgsql/transform';
+import { sliceStatementBytes, sqlSourceBytes } from './byte-slice';
 import { nameUnnamedConstraints, subObjectIdentityOf } from './sub-object';
 export const CHANGE_GRANULARITIES = ['alteration', 'object', 'single'];
 export const isChangeGranularity = (value) => CHANGE_GRANULARITIES.includes(value);
@@ -53,12 +54,13 @@ export function restructureChanges(changes, options) {
     // target (creates[0]), so a table's CREATE and its remaining ALTERs land
     // in the same change regardless of statement kind.
     const facts = classifyStatements(sql);
+    const sqlBytes = sqlSourceBytes(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())
+            .map(f => sliceStatementBytes(sqlBytes, f.span.start, f.span.len).trim())
             .filter(Boolean)
             .map(text => (text.endsWith(';') ? text : `${text};`));
         const revert = revertFor(facts);
@@ -137,7 +139,7 @@ export function restructureChanges(changes, options) {
     const groupSql = groupNames.map(() => []);
     const groupStatements = groupNames.map(() => []);
     facts.forEach((f, i) => {
-        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        const text = sliceStatementBytes(sqlBytes, f.span.start, f.span.len).trim();
         const g = groupOf[i];
         if (g !== -1 && text) {
             groupSql[g].push(text.endsWith(';') ? text : `${text};`);

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,22 +11,64 @@ export const stripTransactionWrapper = (sql) => sql
     .filter(line => !TX_LINE.test(line))
     .join('\n')
     .trim();
+const CROSS_PACKAGE_TAG = /^([^:]+):@(.+)$/;
+/**
+ * Resolve a plan dependency token to a concrete change identity.
+ *
+ * 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 is resolved so a dependency written
+ * against a tag is never re-emitted verbatim into a generated plan or a
+ * ledger row:
+ * - a local tag (`@tag`) resolves to its change name via this plan;
+ * - a cross-package tag (`pkg:@tag`) resolves to the canonical `pkg:change`
+ *   qualified name via `crossPackagePlans[pkg]` when available.
+ *
+ * Anything that cannot be resolved (unknown tag, or a cross-package tag with
+ * no plan in context) is kept verbatim — never dropped — with a warning.
+ */
+const resolveDependencyToken = (token, plan, warnings, changeName, crossPackagePlans) => {
+    if (!token.includes('@'))
+        return token;
+    const cross = token.match(CROSS_PACKAGE_TAG);
+    if (cross && cross[1] !== plan.package) {
+        const pkg = cross[1];
+        const otherPlan = crossPackagePlans?.get(pkg);
+        if (!otherPlan) {
+            warnings.push(`${changeName}: dependency tag "${token}" is cross-package; left unresolved (no plan for "${pkg}" in context)`);
+            return token;
+        }
+        const resolved = resolveReference(token, otherPlan, pkg);
+        if (resolved.error || !resolved.change) {
+            warnings.push(`${changeName}: could not resolve cross-package dependency tag "${token}" (${resolved.error ?? 'no matching change'}); left as-is`);
+            return token;
+        }
+        return `${pkg}:${resolved.change}`;
+    }
+    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;
+    }
+    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
  * result can be flattened straight into the dials pipeline
  * (`restructureChanges` / `partitionUnits`).
  */
-export const loadModuleSource = (moduleDir) => {
+export const loadModuleSource = (moduleDir, options = {}) => {
     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 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 +77,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, options.crossPackagePlans)),
             deploy: stripTransactionWrapper(body)
         });
     }

package/esm/partition-driver.js

@@ -23,6 +23,7 @@
 import { pathFor } from '@pgpmjs/naming-spec';
 import { classifyStatements } from '@pgsql/semantics';
 import { buildStatementGraph, identityOf } from '@pgsql/transform';
+import { sliceStatementBytes, sqlSourceBytes } from './byte-slice';
 /** A partition whose packages require each other in a cycle — unshippable. */
 export class PartitionCycleError extends Error {
     packages;
@@ -81,6 +82,7 @@ export const RESIDUAL_UNIT_PATH = 'misc/statements';
  */
 function buildUnitGraph(sql, style, splitRiders) {
     const facts = classifyStatements(sql);
+    const sqlBytes = sqlSourceBytes(sql);
     const graph = buildStatementGraph(facts);
     const unitOf = new Array(facts.length).fill(-1);
     const units = [];
@@ -163,7 +165,7 @@ function buildUnitGraph(sql, style, splitRiders) {
         unitOf[i] = unitFor(null, f.kind);
     });
     facts.forEach((f, i) => {
-        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        const text = sliceStatementBytes(sqlBytes, f.span.start, f.span.len).trim();
         if (!text)
             return;
         const unit = units[unitOf[i]];

package/esm/program.js

@@ -1,5 +1,6 @@
 import { classifyStatements } from '@pgsql/semantics';
 import { Deparser, parseSql } from 'plpgsql-parser';
+import { sliceStatementBytes, sqlSourceBytes } from './byte-slice';
 /**
  * Parse a SQL script into a statement program. Requires `loadModule()` from
  * `plpgsql-parser` to have completed.
@@ -8,6 +9,7 @@ export function parseSqlProgram(source) {
     const parseResult = parseSql(source);
     const stmts = parseResult?.stmts ?? [];
     const facts = classifyStatements(source);
+    const sourceBytes = sqlSourceBytes(source);
     const statements = [];
     for (let i = 0; i < stmts.length; i++) {
         const rawStmt = stmts[i];
@@ -18,7 +20,7 @@ export function parseSqlProgram(source) {
             stmt: rawStmt.stmt,
             facts: facts[i],
             span: { start, len },
-            raw: source.slice(start, start + len),
+            raw: sliceStatementBytes(sourceBytes, start, len),
             dirty: false
         });
     }
@@ -34,16 +36,22 @@ export function emitSqlProgram(program) {
     const { source, statements } = program;
     if (!statements.some(s => s.dirty))
         return source;
+    // Spans are UTF-8 byte offsets; slice statements and the verbatim gaps
+    // between them on the bytes so a multibyte character never mis-cuts the
+    // reassembly. Statement boundaries fall on character boundaries.
+    const sourceBytes = sqlSourceBytes(source);
     const pieces = [];
     let cursor = 0;
     for (const statement of statements) {
         const { start, len } = statement.span;
         if (start > cursor)
-            pieces.push(source.slice(cursor, start));
-        pieces.push(statement.dirty ? Deparser.deparse(statement.stmt) : source.slice(start, start + len));
+            pieces.push(sliceStatementBytes(sourceBytes, cursor, start - cursor));
+        pieces.push(statement.dirty
+            ? Deparser.deparse(statement.stmt)
+            : sliceStatementBytes(sourceBytes, start, len));
         cursor = start + len;
     }
-    if (cursor < source.length)
-        pieces.push(source.slice(cursor));
+    if (cursor < sourceBytes.length)
+        pieces.push(sliceStatementBytes(sourceBytes, cursor));
     return pieces.join('');
 }

package/esm/semantic-diff-driver.js

@@ -31,6 +31,7 @@ import { existenceCheck, invertStatement, revertFor, verifyFor } from '@pgsql/sc
 import { classifyStatements } from '@pgsql/semantics';
 import { buildStatementGraph, cleanTree, identityOf } from '@pgsql/transform';
 import { Deparser, parseSync } from 'plpgsql-parser';
+import { sliceStatementBytes, sqlSourceBytes } from './byte-slice';
 import { defaultConstraintName } from './constraint-names';
 import { restructureChanges } from './granularity-driver';
 const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
@@ -47,8 +48,9 @@ function readSide(sql, warnings, label) {
     const order = [];
     const unitOf = new Array(facts.length).fill(null);
     const byObject = new Map();
+    const sqlBytes = sqlSourceBytes(sql);
     facts.forEach((f, i) => {
-        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        const text = sliceStatementBytes(sqlBytes, f.span.start, f.span.len).trim();
         if (!text)
             return;
         let identity = groupingIdentity(f);
@@ -502,3 +504,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/esm/sub-object.js

@@ -1,4 +1,5 @@
 import { Deparser, parseSync } from 'plpgsql-parser';
+import { sliceStatementBytes, sqlSourceBytes } from './byte-slice';
 import { defaultConstraintName } from './constraint-names';
 /** The single AlterTableCmd of a one-command ALTER TABLE, or null. */
 function singleCmd(stmt) {
@@ -46,6 +47,7 @@ export function subObjectIdentityOf(facts) {
  */
 export function nameUnnamedConstraints(sql) {
     const parsed = parseSync(sql);
+    const sqlBytes = sqlSourceBytes(sql);
     const pieces = [];
     for (const raw of parsed.sql.stmts) {
         const node = raw.stmt;
@@ -71,7 +73,7 @@ export function nameUnnamedConstraints(sql) {
         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 text = sliceStatementBytes(sqlBytes, start, len);
             const trimmed = text.trim();
             pieces.push(trimmed.endsWith(';') ? trimmed : `${trimmed};`);
         }

package/granularity-driver.js

@@ -7,6 +7,7 @@ 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 byte_slice_1 = require("./byte-slice");
 const sub_object_1 = require("./sub-object");
 exports.CHANGE_GRANULARITIES = ['alteration', 'object', 'single'];
 const isChangeGranularity = (value) => exports.CHANGE_GRANULARITIES.includes(value);
@@ -59,12 +60,13 @@ function restructureChanges(changes, options) {
     // target (creates[0]), so a table's CREATE and its remaining ALTERs land
     // in the same change regardless of statement kind.
     const facts = (0, semantics_1.classifyStatements)(sql);
+    const sqlBytes = (0, byte_slice_1.sqlSourceBytes)(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())
+            .map(f => (0, byte_slice_1.sliceStatementBytes)(sqlBytes, f.span.start, f.span.len).trim())
             .filter(Boolean)
             .map(text => (text.endsWith(';') ? text : `${text};`));
         const revert = (0, scripts_1.revertFor)(facts);
@@ -143,7 +145,7 @@ function restructureChanges(changes, options) {
     const groupSql = groupNames.map(() => []);
     const groupStatements = groupNames.map(() => []);
     facts.forEach((f, i) => {
-        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        const text = (0, byte_slice_1.sliceStatementBytes)(sqlBytes, f.span.start, f.span.len).trim();
         const g = groupOf[i];
         if (g !== -1 && text) {
             groupSql[g].push(text.endsWith(';') ? text : `${text};`);

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.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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 type { ExtendedPlanFile } from '@pgpmjs/ast';
 /** One change of a loaded module: headerless, unwrapped deploy SQL. */
 export interface ModuleSourceChange {
     /** Change name (plan token). */
@@ -24,10 +31,21 @@ export interface ModuleSource {
  * transaction control.
  */
 export declare const stripTransactionWrapper: (sql: string) => string;
+/** Options controlling how {@link loadModuleSource} ingests a module. */
+export interface LoadModuleSourceOptions {
+    /**
+     * Parsed plans of the other packages in the same workspace, keyed by
+     * package name (`%project`). Lets a cross-package tag dependency
+     * (`pkg:@tag`) resolve against the plan that defines the tag. Without it,
+     * cross-package tags cannot be resolved from a single module's plan and are
+     * left verbatim with a warning.
+     */
+    crossPackagePlans?: Map<string, ExtendedPlanFile>;
+}
 /**
  * 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 declare const loadModuleSource: (moduleDir: string) => ModuleSource;
+export declare const loadModuleSource: (moduleDir: string, options?: LoadModuleSourceOptions) => ModuleSource;

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,22 +48,64 @@ const stripTransactionWrapper = (sql) => sql
     .join('\n')
     .trim();
 exports.stripTransactionWrapper = stripTransactionWrapper;
+const CROSS_PACKAGE_TAG = /^([^:]+):@(.+)$/;
+/**
+ * Resolve a plan dependency token to a concrete change identity.
+ *
+ * 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 is resolved so a dependency written
+ * against a tag is never re-emitted verbatim into a generated plan or a
+ * ledger row:
+ * - a local tag (`@tag`) resolves to its change name via this plan;
+ * - a cross-package tag (`pkg:@tag`) resolves to the canonical `pkg:change`
+ *   qualified name via `crossPackagePlans[pkg]` when available.
+ *
+ * Anything that cannot be resolved (unknown tag, or a cross-package tag with
+ * no plan in context) is kept verbatim — never dropped — with a warning.
+ */
+const resolveDependencyToken = (token, plan, warnings, changeName, crossPackagePlans) => {
+    if (!token.includes('@'))
+        return token;
+    const cross = token.match(CROSS_PACKAGE_TAG);
+    if (cross && cross[1] !== plan.package) {
+        const pkg = cross[1];
+        const otherPlan = crossPackagePlans?.get(pkg);
+        if (!otherPlan) {
+            warnings.push(`${changeName}: dependency tag "${token}" is cross-package; left unresolved (no plan for "${pkg}" in context)`);
+            return token;
+        }
+        const resolved = (0, ast_1.resolveReference)(token, otherPlan, pkg);
+        if (resolved.error || !resolved.change) {
+            warnings.push(`${changeName}: could not resolve cross-package dependency tag "${token}" (${resolved.error ?? 'no matching change'}); left as-is`);
+            return token;
+        }
+        return `${pkg}:${resolved.change}`;
+    }
+    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;
+    }
+    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
  * result can be flattened straight into the dials pipeline
  * (`restructureChanges` / `partitionUnits`).
  */
-const loadModuleSource = (moduleDir) => {
+const loadModuleSource = (moduleDir, options = {}) => {
     const modulePath = path.resolve(moduleDir);
     const planResult = (0, ast_1.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 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 +114,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, options.crossPackagePlans)),
             deploy: (0, exports.stripTransactionWrapper)(body)
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/transform",
-  "version": "0.21.0",
+  "version": "0.23.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": "c9dcb0c96174dfb0bc6fd63e46cc7776ea7af173"
 }

package/partition-driver.js

@@ -27,6 +27,7 @@ exports.partitionUnits = partitionUnits;
 const naming_spec_1 = require("@pgpmjs/naming-spec");
 const semantics_1 = require("@pgsql/semantics");
 const transform_1 = require("@pgsql/transform");
+const byte_slice_1 = require("./byte-slice");
 /** A partition whose packages require each other in a cycle — unshippable. */
 class PartitionCycleError extends Error {
     packages;
@@ -86,6 +87,7 @@ exports.RESIDUAL_UNIT_PATH = 'misc/statements';
  */
 function buildUnitGraph(sql, style, splitRiders) {
     const facts = (0, semantics_1.classifyStatements)(sql);
+    const sqlBytes = (0, byte_slice_1.sqlSourceBytes)(sql);
     const graph = (0, transform_1.buildStatementGraph)(facts);
     const unitOf = new Array(facts.length).fill(-1);
     const units = [];
@@ -168,7 +170,7 @@ function buildUnitGraph(sql, style, splitRiders) {
         unitOf[i] = unitFor(null, f.kind);
     });
     facts.forEach((f, i) => {
-        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        const text = (0, byte_slice_1.sliceStatementBytes)(sqlBytes, f.span.start, f.span.len).trim();
         if (!text)
             return;
         const unit = units[unitOf[i]];

package/program.js

@@ -4,6 +4,7 @@ exports.parseSqlProgram = parseSqlProgram;
 exports.emitSqlProgram = emitSqlProgram;
 const semantics_1 = require("@pgsql/semantics");
 const plpgsql_parser_1 = require("plpgsql-parser");
+const byte_slice_1 = require("./byte-slice");
 /**
  * Parse a SQL script into a statement program. Requires `loadModule()` from
  * `plpgsql-parser` to have completed.
@@ -12,6 +13,7 @@ function parseSqlProgram(source) {
     const parseResult = (0, plpgsql_parser_1.parseSql)(source);
     const stmts = parseResult?.stmts ?? [];
     const facts = (0, semantics_1.classifyStatements)(source);
+    const sourceBytes = (0, byte_slice_1.sqlSourceBytes)(source);
     const statements = [];
     for (let i = 0; i < stmts.length; i++) {
         const rawStmt = stmts[i];
@@ -22,7 +24,7 @@ function parseSqlProgram(source) {
             stmt: rawStmt.stmt,
             facts: facts[i],
             span: { start, len },
-            raw: source.slice(start, start + len),
+            raw: (0, byte_slice_1.sliceStatementBytes)(sourceBytes, start, len),
             dirty: false
         });
     }
@@ -38,16 +40,22 @@ function emitSqlProgram(program) {
     const { source, statements } = program;
     if (!statements.some(s => s.dirty))
         return source;
+    // Spans are UTF-8 byte offsets; slice statements and the verbatim gaps
+    // between them on the bytes so a multibyte character never mis-cuts the
+    // reassembly. Statement boundaries fall on character boundaries.
+    const sourceBytes = (0, byte_slice_1.sqlSourceBytes)(source);
     const pieces = [];
     let cursor = 0;
     for (const statement of statements) {
         const { start, len } = statement.span;
         if (start > cursor)
-            pieces.push(source.slice(cursor, start));
-        pieces.push(statement.dirty ? plpgsql_parser_1.Deparser.deparse(statement.stmt) : source.slice(start, start + len));
+            pieces.push((0, byte_slice_1.sliceStatementBytes)(sourceBytes, cursor, start - cursor));
+        pieces.push(statement.dirty
+            ? plpgsql_parser_1.Deparser.deparse(statement.stmt)
+            : (0, byte_slice_1.sliceStatementBytes)(sourceBytes, start, len));
         cursor = start + len;
     }
-    if (cursor < source.length)
-        pieces.push(source.slice(cursor));
+    if (cursor < sourceBytes.length)
+        pieces.push((0, byte_slice_1.sliceStatementBytes)(sourceBytes, cursor));
     return pieces.join('');
 }

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.
@@ -35,6 +36,7 @@ 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 byte_slice_1 = require("./byte-slice");
 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}`;
@@ -51,8 +53,9 @@ function readSide(sql, warnings, label) {
     const order = [];
     const unitOf = new Array(facts.length).fill(null);
     const byObject = new Map();
+    const sqlBytes = (0, byte_slice_1.sqlSourceBytes)(sql);
     facts.forEach((f, i) => {
-        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        const text = (0, byte_slice_1.sliceStatementBytes)(sqlBytes, f.span.start, f.span.len).trim();
         if (!text)
             return;
         let identity = groupingIdentity(f);
@@ -506,3 +509,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 };
+    });
+}

package/sub-object.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.subObjectIdentityOf = subObjectIdentityOf;
 exports.nameUnnamedConstraints = nameUnnamedConstraints;
 const plpgsql_parser_1 = require("plpgsql-parser");
+const byte_slice_1 = require("./byte-slice");
 const constraint_names_1 = require("./constraint-names");
 /** The single AlterTableCmd of a one-command ALTER TABLE, or null. */
 function singleCmd(stmt) {
@@ -50,6 +51,7 @@ function subObjectIdentityOf(facts) {
  */
 function nameUnnamedConstraints(sql) {
     const parsed = (0, plpgsql_parser_1.parseSync)(sql);
+    const sqlBytes = (0, byte_slice_1.sqlSourceBytes)(sql);
     const pieces = [];
     for (const raw of parsed.sql.stmts) {
         const node = raw.stmt;
@@ -75,7 +77,7 @@ function nameUnnamedConstraints(sql) {
         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 text = (0, byte_slice_1.sliceStatementBytes)(sqlBytes, start, len);
             const trimmed = text.trim();
             pieces.push(trimmed.endsWith(';') ? trimmed : `${trimmed};`);
         }