@pgpmjs/transform 0.15.3 → 0.17.0

package/partition-driver.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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 { PathStyle } from '@pgpmjs/naming-spec';
+import { ObjectIdentity, ObjectIdentityKind, StatementKind } from '@pgsql/transform';
+/** One deployable unit: an object (by identity) and the statements that build it. */
+export interface PartitionUnit {
+    /** The object's identity, or `null` for split riders and the residual unit. */
+    identity: ObjectIdentity | null;
+    /** Statement kind of the unit's primary statement (`grant` for split grants, ...). */
+    primaryKind: StatementKind;
+    /** Canonical change path derived from the identity via the naming spec. */
+    path: string;
+    /** Indexes into the classified statement list, in source order. */
+    statements: number[];
+    /** The unit's deploy SQL (statement text joined in source order). */
+    sql: string;
+    /**
+     * A statement in this unit executes dynamic SQL: its edges are incomplete,
+     * so assignments involving it cannot be proven safe by the graph alone.
+     */
+    dynamicSql: boolean;
+}
+/**
+ * Matches units for assignment. Every given field must match (AND); array
+ * values match any element (OR). Omitted fields match everything, so
+ * `{ schema: 'billing' }` selects a whole schema, `{ kind: 'policy' }`
+ * selects every policy, and `{ path: 'schemas/app/tables/users/table' }`
+ * cherry-picks one object.
+ */
+export interface UnitSelector {
+    kind?: ObjectIdentityKind | ObjectIdentityKind[];
+    /**
+     * Statement-level kind of the unit's primary statement — selects units
+     * that have no object identity, like grants split out via
+     * {@link PartitionConfig.splitRiders} (`statementKind: 'grant'`).
+     */
+    statementKind?: StatementKind | StatementKind[];
+    schema?: string | string[];
+    name?: string | string[];
+    /** Owning table, for table-scoped kinds (trigger/policy/index/constraint/seed). */
+    table?: string | string[];
+    /** The derived naming-spec path — exact cherry-pick. */
+    path?: string | string[];
+}
+/** Assigns matching units to a package. Rules are tried in order; first match wins. */
+export interface PartitionRule {
+    package: string;
+    /** A unit matching ANY of these selectors is assigned to `package`. */
+    select: UnitSelector[];
+    /**
+     * Also pull in the transitive dependency closure (hard + fk edges) of the
+     * selected units. Only units that would otherwise land in the default
+     * package are pulled — a unit another rule claimed stays where it is and
+     * becomes an ordinary cross-package dependency.
+     */
+    closure?: boolean;
+}
+export interface PartitionConfig {
+    /** Assignment rules, in priority order. */
+    rules: PartitionRule[];
+    /** Package for units no rule matches. */
+    defaultPackage: string;
+    /** Naming-spec rendering style for derived paths (default `directory`). */
+    style?: PathStyle;
+    /**
+     * Statement kinds to split out of their host unit into standalone units
+     * (e.g. `['grant']` makes every GRANT its own selectable unit named
+     * `<hostPath>/grants/<role>`), so security surface can be partitioned
+     * independently of the objects it attaches to. Split units depend on
+     * their host, so ordering stays correct wherever they are assigned.
+     */
+    splitRiders?: StatementKind[];
+}
+/** One emitted change of a partitioned package. */
+export interface PartitionedChange {
+    /** Change path (naming spec). */
+    name: string;
+    /**
+     * Same-package dependencies as plain paths, cross-package dependencies as
+     * `<pkg>:<path>` — the pgpm cross-package requires convention.
+     */
+    dependencies: string[];
+    deploy: string;
+}
+export interface PartitionedPackage {
+    name: string;
+    /** Changes in a valid deploy order (statement-graph topological order). */
+    changes: PartitionedChange[];
+    /** Package names this package requires (from cross-package edges). */
+    requires: string[];
+}
+export interface PartitionUnitsResult {
+    packages: PartitionedPackage[];
+    /** unit path → package name, for every unit. */
+    assignments: Map<string, string>;
+    /** Units pulled in by closure rules: path → the rule's package. */
+    closureIncluded: Map<string, string>;
+    warnings: string[];
+}
+/** A partition whose packages require each other in a cycle — unshippable. */
+export declare class PartitionCycleError extends Error {
+    /** The packages forming the cycle. */
+    readonly packages: string[];
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    readonly edges: string[];
+    constructor(
+    /** The packages forming the cycle. */
+    packages: string[], 
+    /** One offending edge per hop: `fromPkg:fromPath -> toPkg:toPath`. */
+    edges: string[]);
+}
+/** Path of the residual unit for statements attributable to no object. */
+export declare const RESIDUAL_UNIT_PATH = "misc/statements";
+/** A change's deploy surface going into the partition (same seam as the granularity driver). */
+export interface PartitionInputChange {
+    name: string;
+    dependencies: string[];
+    deploy: string;
+}
+/**
+ * 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 declare function partitionUnits(input: string | PartitionInputChange[], config: PartitionConfig): PartitionUnitsResult;

package/partition-driver.js

@@ -0,0 +1,368 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESIDUAL_UNIT_PATH = exports.PartitionCycleError = void 0;
+exports.partitionUnits = partitionUnits;
+/**
+ * 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, ...).
+ */
+const naming_spec_1 = require("@pgpmjs/naming-spec");
+const transform_1 = require("@pgsql/transform");
+/** A partition whose packages require each other in a cycle — unshippable. */
+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';
+    }
+}
+exports.PartitionCycleError = 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. */
+exports.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 = (0, transform_1.classifyStatements)(sql);
+    const graph = (0, transform_1.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 (0, naming_spec_1.pathFor)(identity, { style });
+    };
+    const unitFor = (identity, kind) => {
+        const key = identity ? identityKey(identity) : exports.RESIDUAL_UNIT_PATH;
+        let u = byIdentity.get(key);
+        if (u === undefined) {
+            u = newUnit(identity, kind, identity ? unitPath(identity, kind) : exports.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 : exports.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 = (0, transform_1.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}).
+ */
+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/regen.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Regeneration driver: derive revert/verify scripts for a single pgpm
+ * change from its deploy SQL.
+ *
+ * Deploy scripts are classified into statement facts (`classifyStatements`)
+ * and fed through `revertFor`/`verifyFor` from `@pgsql/scripts`: revert is
+ * the mechanical inverses in reverse topological order, verify is one
+ * raise-on-failure existence check per created object. Transaction control
+ * statements (the BEGIN/COMMIT wrapper some modules carry inside their
+ * scripts) are excluded before classification — the caller owns the wrapper.
+ *
+ * Requires `loadModule()` from `plpgsql-parser` to have completed.
+ */
+import type { GeneratedScript } from '@pgsql/scripts';
+import type { StatementFacts } from '@pgsql/transform';
+export type { GeneratedScript } from '@pgsql/scripts';
+/** Generated revert and verify scripts for one change's deploy SQL. */
+export interface RegeneratedScripts {
+    revert: GeneratedScript;
+    verify: GeneratedScript;
+}
+/**
+ * Classify a pgpm script's substantive statements: every top-level statement
+ * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
+ */
+export declare function classifyScript(sql: string): StatementFacts[];
+/**
+ * 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 declare function isStubScript(sql: string): boolean;
+/**
+ * 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 declare function regenerateScripts(deploySql: string): RegeneratedScripts;

package/regen.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyScript = classifyScript;
+exports.isStubScript = isStubScript;
+exports.regenerateScripts = regenerateScripts;
+const scripts_1 = require("@pgsql/scripts");
+const transform_1 = require("@pgsql/transform");
+/**
+ * Classify a pgpm script's substantive statements: every top-level statement
+ * except transaction control (`BEGIN`/`COMMIT`/`ROLLBACK` wrappers).
+ */
+function classifyScript(sql) {
+    return (0, transform_1.classifyStatements)(sql).filter(f => f.nodeTag !== 'TransactionStmt');
+}
+/**
+ * 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).
+ */
+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.
+ */
+function regenerateScripts(deploySql) {
+    const facts = classifyScript(deploySql);
+    return {
+        revert: (0, scripts_1.revertFor)(facts),
+        verify: (0, scripts_1.verifyFor)(facts)
+    };
+}