@pgpmjs/transform 0.15.3 → 0.17.0

package/esm/granularity-driver.js

@@ -1,4 +1,25 @@
-import { buildStatementGraph, classifyStatements, restructureSql } from '@pgsql/transform';
+/**
+ * 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 { pathFor } from '@pgpmjs/naming-spec';
+import { revertFor, verifyFor } from '@pgsql/scripts';
+import { buildStatementGraph, classifyStatements, identityOf, restructureSql } from '@pgsql/transform';
 const KIND_DIRS = {
     table: 'tables',
     view: 'views',
@@ -10,21 +31,15 @@ const KIND_DIRS = {
     seed_dml: 'fixtures'
 };
 /**
- * Default pgpm-style change name for a statement group:
- * `schemas/<schema>` for schemas, `schemas/<schema>/<kind>/<name>` for
- * objects, `misc/<n>` when nothing better is known.
+ * Default change name for a statement group: the object's canonical naming
+ * spec v1 path — `identityOf(facts)` (Postgres-native identity, from
+ * `@pgsql/transform`) rendered through `pathFor` (`@pgpmjs/naming-spec`).
+ * Paths are pure projections of identity, never authored.
  */
 export function defaultChangeName(facts) {
-    const created = facts.creates[0];
-    if (facts.kind === 'schema' && created)
-        return `schemas/${created.name}`;
-    if (created) {
-        const dir = KIND_DIRS[facts.kind] ?? 'objects';
-        const schema = created.schema ?? 'public';
-        // Trigger/policy names are table-qualified (`table.trigger`).
-        const name = created.name.replace(/\./g, '/');
-        return `schemas/${schema}/${dir}/${name}`;
-    }
+    const identity = identityOf(facts);
+    if (identity)
+        return pathFor(identity);
     return 'misc/statements';
 }
 /**
@@ -85,13 +100,16 @@ export function restructureChanges(changes, options) {
             schemaGroup.set(f.creates[0].name, groupOf[i]);
         }
     });
-    // Slice statement text per group, in the emitted (topological) order.
+    // Slice statement text per group, in the emitted (topological) order,
+    // and collect each group's facts for revert/verify generation.
     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 g = groupOf[i];
         if (g !== -1 && text) {
             groupSql[g].push(text.endsWith(';') ? text : `${text};`);
+            groupStatements[g].push(f);
         }
     });
     // Change dependencies = statement edges projected onto groups, plus
@@ -128,10 +146,22 @@ export function restructureChanges(changes, options) {
     });
     const result = order
         .filter(g => groupSql[g].length > 0)
-        .map(g => ({
-        name: groupNames[g],
-        dependencies: [...groupDeps[g]].map(d => groupNames[d]).sort(),
-        deploy: groupSql[g].join('\n\n')
-    }));
+        .map(g => {
+        const revert = revertFor(groupStatements[g]);
+        const verify = verifyFor(groupStatements[g]);
+        for (const warning of revert.warnings) {
+            warnings.push(`${groupNames[g]}: ${warning}`);
+        }
+        for (const warning of verify.warnings) {
+            warnings.push(`${groupNames[g]}: ${warning}`);
+        }
+        return {
+            name: groupNames[g],
+            dependencies: [...groupDeps[g]].map(d => groupNames[d]).sort(),
+            deploy: groupSql[g].join('\n\n'),
+            revert: revert.sql,
+            verify: verify.sql
+        };
+    });
     return { changes: result, warnings };
 }

package/esm/index.js

@@ -2,6 +2,9 @@ export * from '@pgsql/transform';
 export { loadModule } from 'plpgsql-parser';
 export { buildExtensionRouter, buildSchemaRouter, makeNamespaceValidator, makeSchemaTranspiler, } from './bundle-driver';
 export { defaultChangeName, restructureChanges, } from './granularity-driver';
+export { diffChangeSets, diffSchemas, } from './semantic-diff-driver';
+export { PartitionCycleError, partitionUnits, RESIDUAL_UNIT_PATH, } from './partition-driver';
 export { buildCategoryOf, categorizeChange, TIER_PROFILE, } from './categorize';
 export { resolveFixtureClosure } from './fixture-closure';
+export { classifyScript, isStubScript, regenerateScripts, } from './regen';
 export { emitSqlProgram, parseSqlProgram } from './program';

package/esm/partition-driver.js

@@ -0,0 +1,363 @@
+/**
+ * Partition dial: project one deploy surface into a set of pgpm packages.
+ *
+ * The object graph (statements classified by `@pgsql/transform`, grouped
+ * into identity-keyed units) is the source of truth; which package a unit
+ * lives in is a *derived projection* of a declarative partition config.
+ * Units can be assigned by schema, by object kind, by explicit cherry-pick
+ * (identity or derived path), or dragged in as the dependency closure of a
+ * package's seeds. `requires` headers are a mechanical post-pass over the
+ * statement graph: intra-package edges become `requires: <path>`,
+ * cross-package edges become `requires: <pkg>:<path>` — both rendered
+ * through the naming spec, never authored.
+ *
+ * A partition is rejected (hard error) when packages require each other in
+ * a cycle: that is the one unshippable configuration, because no package
+ * install order can satisfy it.
+ *
+ * Like the other drivers in this package the emit shape is structurally
+ * typed on the change seam — no dependency on `@pgpmjs/bundle` or
+ * `@pgpmjs/core`. Callers materialize packages however they like (write
+ * pgpm.plan + deploy trees, feed a bundle, ...).
+ */
+import { pathFor } from '@pgpmjs/naming-spec';
+import { buildStatementGraph, classifyStatements, identityOf } from '@pgsql/transform';
+/** A partition whose packages require each other in a cycle — unshippable. */
+export class PartitionCycleError extends Error {
+    packages;
+    edges;
+    constructor(
+    /** The packages forming the cycle. */
+    packages, 
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    edges) {
+        super(`cross-package dependency cycle: ${packages.join(' -> ')} -> ${packages[0]}\n` +
+            edges.map(e => `  ${e}`).join('\n'));
+        this.packages = packages;
+        this.edges = edges;
+        this.name = 'PartitionCycleError';
+    }
+}
+const identityKey = (id) => `${id.kind}\u0000${id.schema ?? ''}\u0000${id.table ?? ''}\u0000${id.name}`;
+const matchField = (value, wanted) => {
+    if (wanted === undefined)
+        return true;
+    return Array.isArray(wanted) ? wanted.includes(value) : wanted === value;
+};
+function matches(unit, selector) {
+    if (!matchField(unit.path, selector.path))
+        return false;
+    if (!matchField(unit.primaryKind, selector.statementKind))
+        return false;
+    const id = unit.identity;
+    if (selector.kind === undefined && selector.schema === undefined &&
+        selector.name === undefined && selector.table === undefined) {
+        return true;
+    }
+    if (!id)
+        return false;
+    // A schema object's own name counts as its schema, so `{ schema: 'x' }`
+    // selects the schema together with everything in it.
+    const schema = id.kind === 'schema' ? id.name : id.schema;
+    return (matchField(id.kind, selector.kind) &&
+        matchField(schema, selector.schema) &&
+        matchField(id.name, selector.name) &&
+        matchField(id.table, selector.table));
+}
+/** Path of the residual unit for statements attributable to no object. */
+export const RESIDUAL_UNIT_PATH = 'misc/statements';
+/**
+ * Group a classified script into identity-keyed units and compute unit-level
+ * dependencies from the statement graph.
+ *
+ * Statements with no identity of their own (grants, comments) ride with the
+ * unit of the object they target — resolved through the statement graph's
+ * edges — falling back to the closest preceding statement's unit; lead-in
+ * statements with no unit at all land in a residual unit so nothing is
+ * silently dropped. Kinds listed in `splitRiders` become standalone units
+ * (named `<hostPath>/grants/<role>` for grants, `<hostPath>/<kind>/<n>`
+ * otherwise) that depend on their host unit.
+ */
+function buildUnitGraph(sql, style, splitRiders) {
+    const facts = classifyStatements(sql);
+    const graph = buildStatementGraph(facts);
+    const unitOf = new Array(facts.length).fill(-1);
+    const units = [];
+    const byIdentity = new Map();
+    const takenPaths = new Set();
+    const newUnit = (identity, primaryKind, path) => {
+        units.push({ identity, primaryKind, path, statements: [], sql: '', dynamicSql: false });
+        takenPaths.add(path);
+        return units.length - 1;
+    };
+    // Naming-spec path for a unit; ENABLE ROW LEVEL SECURITY uses the spec's
+    // dedicated rls template rather than its constraint-shaped identity.
+    const unitPath = (identity, kind) => {
+        if (kind === 'rls_enable' && identity.table) {
+            return `schemas/${identity.schema ?? 'public'}/tables/${identity.table}/policies/enable_row_level_security`;
+        }
+        return pathFor(identity, { style });
+    };
+    const unitFor = (identity, kind) => {
+        const key = identity ? identityKey(identity) : RESIDUAL_UNIT_PATH;
+        let u = byIdentity.get(key);
+        if (u === undefined) {
+            u = newUnit(identity, kind, identity ? unitPath(identity, kind) : RESIDUAL_UNIT_PATH);
+            byIdentity.set(key, u);
+        }
+        return u;
+    };
+    // Object-owning units by qualified name, for rider host resolution. Only
+    // top-level objects qualify (table-scoped identities share the table's
+    // qualified name and must not shadow it).
+    const objectUnits = new Map();
+    const registerObject = (identity, u) => {
+        if (identity.table)
+            return;
+        objectUnits.set(`${identity.schema ?? ''}.${identity.name}`, u);
+    };
+    /** Host unit of a rider statement: the unit owning the first object it
+     *  references, falling back to the preceding statement's unit. */
+    const hostOf = (i) => {
+        for (const r of facts[i].references) {
+            const u = objectUnits.get(`${r.schema ?? ''}.${r.name}`);
+            if (u !== undefined)
+                return u;
+        }
+        if (i > 0 && unitOf[i - 1] !== -1)
+            return unitOf[i - 1];
+        return -1;
+    };
+    const riderPath = (f, host) => {
+        const base = host !== -1 ? units[host].path : RESIDUAL_UNIT_PATH;
+        const dir = f.kind === 'grant' ? 'grants' : f.kind;
+        const label = f.roles.length > 0 ? f.roles.join('_') : f.kind;
+        let path = `${base}/${dir}/${label}`;
+        for (let n = 2; takenPaths.has(path); n++)
+            path = `${base}/${dir}/${label}-${n}`;
+        return path;
+    };
+    const hostUnit = new Map();
+    facts.forEach((f, i) => {
+        const identity = identityOf(f);
+        if (identity && !splitRiders.has(f.kind)) {
+            unitOf[i] = unitFor(identity, f.kind);
+            registerObject(identity, unitOf[i]);
+            return;
+        }
+        const host = hostOf(i);
+        if (splitRiders.has(f.kind)) {
+            unitOf[i] = newUnit(identity, f.kind, identity ? unitPath(identity, f.kind) : riderPath(f, host));
+            if (identity)
+                registerObject(identity, unitOf[i]);
+            if (host !== -1)
+                hostUnit.set(unitOf[i], host);
+            return;
+        }
+        // No identity: ride with the host unit.
+        if (host !== -1) {
+            unitOf[i] = host;
+            return;
+        }
+        unitOf[i] = unitFor(null, f.kind);
+    });
+    facts.forEach((f, i) => {
+        const text = sql.slice(f.span.start, f.span.start + f.span.len).trim();
+        if (!text)
+            return;
+        const unit = units[unitOf[i]];
+        unit.statements.push(i);
+        unit.sql += (unit.sql ? '\n\n' : '') + (text.endsWith(';') ? text : `${text};`);
+        if (f.dynamicSql)
+            unit.dynamicSql = true;
+    });
+    // Unit dependencies: statement edges (late edges do not constrain deploy
+    // order), plus schema membership (an object requires its schema's unit).
+    const deps = units.map(() => new Set());
+    for (const edge of graph.edges) {
+        if (edge.kind === 'late')
+            continue;
+        const from = unitOf[edge.from];
+        const to = unitOf[edge.to];
+        if (from !== -1 && to !== -1 && from !== to)
+            deps[from].add(to);
+    }
+    // A split rider requires its host object; a table-scoped object (trigger,
+    // policy, index, constraint, RLS) requires its table.
+    for (const [u, host] of hostUnit) {
+        if (u !== host)
+            deps[u].add(host);
+    }
+    units.forEach((u, i) => {
+        const id = u.identity;
+        if (!id?.table)
+            return;
+        const table = objectUnits.get(`${id.schema ?? ''}.${id.table}`);
+        if (table !== undefined && table !== i)
+            deps[i].add(table);
+    });
+    const schemaUnit = new Map();
+    units.forEach((u, i) => {
+        if (u.identity?.kind === 'schema')
+            schemaUnit.set(u.identity.name, i);
+    });
+    facts.forEach((f, i) => {
+        const from = unitOf[i];
+        if (from === -1)
+            return;
+        const schemas = new Set(f.referencedSchemas);
+        for (const created of f.creates) {
+            if (created.schema)
+                schemas.add(created.schema);
+        }
+        for (const schema of schemas) {
+            const to = schemaUnit.get(schema);
+            if (to !== undefined && to !== from)
+                deps[from].add(to);
+        }
+    });
+    return { facts, units, unitOf, deps, source: sql };
+}
+/**
+ * Partition a deploy surface into packages.
+ *
+ * Accepts either raw SQL or pgpm changes (whose deploy scripts are flattened
+ * in the given order — run the granularity dial first if a different unit
+ * shape is wanted). Requires `loadModule()` from `plpgsql-parser` first.
+ *
+ * Assignment: for each unit the first matching rule wins; unmatched units go
+ * to `defaultPackage`. Closure rules then pull the transitive dependency
+ * closure (hard + fk) of their units out of the default package. Finally the
+ * requires post-pass renders every unit dependency through the naming spec —
+ * same package as `<path>`, cross-package as `<pkg>:<path>` — and the
+ * package-level graph is checked for cycles ({@link PartitionCycleError}).
+ */
+export function partitionUnits(input, config) {
+    const style = config.style ?? 'directory';
+    const sql = typeof input === 'string'
+        ? input
+        : input.map(c => c.deploy.trim()).filter(Boolean).join('\n\n');
+    const { units, deps } = buildUnitGraph(sql, style, new Set(config.splitRiders ?? []));
+    const warnings = [];
+    // 1. Assignment: first matching rule wins.
+    const packageOf = units.map(unit => {
+        for (const rule of config.rules) {
+            if (rule.select.some(s => matches(unit, s)))
+                return rule.package;
+        }
+        return config.defaultPackage;
+    });
+    // 2. Closure: pull each closure rule's dependency closure out of the
+    // default package (never out of another rule's package).
+    const closureIncluded = new Map();
+    for (const rule of config.rules) {
+        if (!rule.closure)
+            continue;
+        const queue = units.map((_, i) => i).filter(i => packageOf[i] === rule.package);
+        const seen = new Set(queue);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const dep of deps[current]) {
+                if (seen.has(dep))
+                    continue;
+                seen.add(dep);
+                if (packageOf[dep] === rule.package) {
+                    queue.push(dep);
+                    continue;
+                }
+                if (packageOf[dep] !== config.defaultPackage)
+                    continue;
+                packageOf[dep] = rule.package;
+                closureIncluded.set(units[dep].path, rule.package);
+                queue.push(dep);
+            }
+        }
+    }
+    // Dynamic SQL makes edges incomplete: surface it, do not guess.
+    units.forEach((unit, i) => {
+        if (unit.dynamicSql && unit.statements.length > 0) {
+            warnings.push(`${units[i].path} (${packageOf[i]}) executes dynamic SQL; hidden references cannot be checked against the partition`);
+        }
+    });
+    // 3. Requires post-pass + package-level graph.
+    const pkgNames = [...new Set([...packageOf, config.defaultPackage])];
+    const pkgIndex = new Map(pkgNames.map((p, i) => [p, i]));
+    const pkgEdges = new Map();
+    const changesByPkg = new Map();
+    for (const p of pkgNames)
+        changesByPkg.set(p, []);
+    units.forEach((unit, i) => {
+        if (unit.statements.length === 0)
+            return;
+        const pkg = packageOf[i];
+        const dependencies = [...deps[i]]
+            .filter(d => units[d].statements.length > 0)
+            .map(d => {
+            const depPkg = packageOf[d];
+            if (depPkg === pkg)
+                return units[d].path;
+            const key = `${pkg}\u0000${depPkg}`;
+            if (!pkgEdges.has(key)) {
+                pkgEdges.set(key, {
+                    from: pkgIndex.get(pkg),
+                    to: pkgIndex.get(depPkg),
+                    via: `${pkg}:${unit.path} -> ${depPkg}:${units[d].path}`
+                });
+            }
+            return `${depPkg}:${units[d].path}`;
+        })
+            .sort();
+        changesByPkg.get(pkg).push({ name: unit.path, dependencies, deploy: unit.sql });
+    });
+    // 4. Cross-package cycle detection over the package graph.
+    detectCycles(pkgNames, [...pkgEdges.values()]);
+    const assignments = new Map();
+    units.forEach((unit, i) => {
+        if (unit.statements.length > 0)
+            assignments.set(unit.path, packageOf[i]);
+    });
+    const packages = pkgNames
+        .map(name => ({
+        name,
+        changes: changesByPkg.get(name),
+        requires: [...new Set([...pkgEdges.values()]
+                .filter(e => pkgNames[e.from] === name)
+                .map(e => pkgNames[e.to]))].sort()
+    }))
+        .filter(p => p.changes.length > 0);
+    return { packages, assignments, closureIncluded, warnings };
+}
+function detectCycles(pkgNames, edges) {
+    const out = new Map();
+    for (const e of edges) {
+        const list = out.get(e.from) ?? [];
+        list.push({ to: e.to, via: e.via });
+        out.set(e.from, list);
+    }
+    const state = new Array(pkgNames.length).fill(0); // 0 unseen, 1 on stack, 2 done
+    const stack = [];
+    const viaStack = [];
+    const visit = (v) => {
+        state[v] = 1;
+        stack.push(v);
+        for (const { to, via } of out.get(v) ?? []) {
+            if (state[to] === 2)
+                continue;
+            viaStack.push(via);
+            if (state[to] === 1) {
+                const start = stack.indexOf(to);
+                const cyclePkgs = stack.slice(start).map(i => pkgNames[i]);
+                const cycleEdges = viaStack.slice(viaStack.length - cyclePkgs.length);
+                throw new PartitionCycleError(cyclePkgs, cycleEdges);
+            }
+            visit(to);
+            viaStack.pop();
+        }
+        stack.pop();
+        state[v] = 2;
+    };
+    for (let v = 0; v < pkgNames.length; v++) {
+        if (state[v] === 0)
+            visit(v);
+    }
+}

package/esm/regen.js

@@ -0,0 +1,39 @@
+import { revertFor, verifyFor } from '@pgsql/scripts';
+import { classifyStatements } from '@pgsql/transform';
+/**
+ * Classify a pgpm script's substantive statements: every top-level statement
+ * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
+ */
+export function classifyScript(sql) {
+    return classifyStatements(sql).filter(f => f.nodeTag !== 'TransactionStmt');
+}
+/**
+ * Whether a script is an empty stub: nothing but comments, whitespace, and
+ * a transaction wrapper — no substantive statements. Scaffolded
+ * `-- Add your revert SQL here` files and bare `BEGIN; ... COMMIT;` shells
+ * are stubs. A script that fails to parse is NOT a stub (never treat content
+ * we cannot understand as safe to overwrite).
+ */
+export function isStubScript(sql) {
+    if (!sql || !sql.trim())
+        return true;
+    try {
+        return classifyScript(sql).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate revert and verify scripts (headerless, unwrapped) for one
+ * change's deploy SQL. Statements with no derivable inverse contribute a
+ * `-- revert not derivable: <reason>` comment and a warning; statements
+ * whose effect cannot be existence-checked add a verify warning.
+ */
+export function regenerateScripts(deploySql) {
+    const facts = classifyScript(deploySql);
+    return {
+        revert: revertFor(facts),
+        verify: verifyFor(facts)
+    };
+}