supaschema 0.1.0-rc.1

package/dist/migrations-status.d.ts

@@ -0,0 +1,35 @@
+import type { Diagnostic } from "./core.js";
+import type { MigrationLineage } from "./lineage.js";
+export interface MigrationsStatusOptions {
+    databaseUrl?: string;
+    directory: string;
+    historyTable?: string;
+}
+export interface MigrationsStatusReport {
+    /** Versions present both on disk and in the target's history table. */
+    applied: string[];
+    /** Disk files whose version the target has not applied yet. */
+    pending: string[];
+    /** Versions in the target's history with no file on disk. */
+    ghosts: string[];
+    /** Pending files older than the target's newest applied version. */
+    outOfOrder: string[];
+    /** Pending files generated by supaschema, with their lineage markers. */
+    pendingLineage: MigrationLineage[];
+    files: string[];
+    historyTable: string;
+    target?: string;
+}
+/**
+ * Three states can diverge independently: migration files in the worktree,
+ * the history table on one database (local), and the history table on
+ * another (remote/linked). This report reconciles the worktree against one
+ * target; run it once per target to see all three. Ghost versions and
+ * out-of-order pending files are integrity defects, not normal pending work.
+ */
+export declare function migrationsStatus(options: MigrationsStatusOptions): Promise<{
+    diagnostics: Diagnostic[];
+    report: MigrationsStatusReport;
+}>;
+export declare function renderMigrationsStatus(report: MigrationsStatusReport): string;
+//# sourceMappingURL=migrations-status.d.ts.map

package/dist/migrations-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-status.d.ts","sourceRoot":"","sources":["../src/migrations-status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIrD,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oEAAoE;IACpE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yEAAyE;IACzE,cAAc,EAAE,gBAAgB,EAAE,CAAC;IACnC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC;IAAE,WAAW,EAAE,UAAU,EAAE,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAAC,CAsExE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAmB7E"}

package/dist/migrations-status.js

@@ -0,0 +1,131 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Client } from "pg";
+import { diagnostic } from "./diagnostics.js";
+import { parseLineage } from "./lineage.js";
+import { quoteIdent } from "./sql/identifiers.js";
+const defaultHistoryTable = "supabase_migrations.schema_migrations";
+const versionPattern = /^(\d{8,})/u;
+const lineageScanBytes = 4096;
+/**
+ * Three states can diverge independently: migration files in the worktree,
+ * the history table on one database (local), and the history table on
+ * another (remote/linked). This report reconciles the worktree against one
+ * target; run it once per target to see all three. Ghost versions and
+ * out-of-order pending files are integrity defects, not normal pending work.
+ */
+export async function migrationsStatus(options) {
+    const diagnostics = [];
+    const historyTable = options.historyTable ?? defaultHistoryTable;
+    const files = (await readdir(options.directory))
+        .filter((name) => name.endsWith(".sql") && versionPattern.test(name))
+        .sort((left, right) => left.localeCompare(right));
+    const versionsByFile = new Map(files.map((name) => [name, versionPattern.exec(name)?.[1] ?? ""]));
+    const report = {
+        applied: [],
+        files,
+        ghosts: [],
+        historyTable,
+        outOfOrder: [],
+        pending: [],
+        pendingLineage: [],
+    };
+    if (!options.databaseUrl) {
+        report.pending = files;
+        diagnostics.push(diagnostic("SUPA_MIGRATIONS_NO_TARGET", "warning", "no database URL resolved; reporting disk files only", { hint: "Pass --database-url or set SUPASCHEMA_DATABASE_URL to compare against a target." }));
+        await annotateLineage(options.directory, report);
+        return { diagnostics, report };
+    }
+    report.target = redactUrl(options.databaseUrl);
+    const appliedVersions = await readHistory(options.databaseUrl, historyTable, diagnostics);
+    if (appliedVersions === undefined) {
+        return { diagnostics, report };
+    }
+    const diskVersions = new Set(versionsByFile.values());
+    const newestApplied = [...appliedVersions].sort().at(-1) ?? "";
+    for (const file of files) {
+        const version = versionsByFile.get(file) ?? "";
+        if (appliedVersions.has(version)) {
+            report.applied.push(file);
+            continue;
+        }
+        report.pending.push(file);
+        if (version < newestApplied) {
+            report.outOfOrder.push(file);
+        }
+    }
+    report.ghosts = [...appliedVersions].filter((version) => !diskVersions.has(version)).sort();
+    await annotateLineage(options.directory, report);
+    if (report.ghosts.length > 0) {
+        diagnostics.push(diagnostic("SUPA_MIGRATIONS_GHOST_VERSIONS", "error", `${report.ghosts.length} applied version(s) have no migration file on disk`, { hint: `ghost versions: ${report.ghosts.slice(0, 8).join(", ")}` }));
+    }
+    if (report.outOfOrder.length > 0) {
+        diagnostics.push(diagnostic("SUPA_MIGRATIONS_OUT_OF_ORDER", "error", `${report.outOfOrder.length} pending file(s) are older than the target's newest applied version`, { hint: `out-of-order: ${report.outOfOrder.slice(0, 8).join(", ")}` }));
+    }
+    return { diagnostics, report };
+}
+export function renderMigrationsStatus(report) {
+    const lines = [];
+    lines.push(`migrations: ${report.files.length} file(s) on disk vs ${report.target ?? "no target"} (${report.historyTable})`);
+    lines.push(`  applied: ${report.applied.length}  pending: ${report.pending.length}  ghosts: ${report.ghosts.length}  out-of-order: ${report.outOfOrder.length}`);
+    for (const file of report.pending) {
+        const lineage = report.pendingLineage.find((item) => item.file === file);
+        lines.push(`  pending: ${file}${lineage ? " (supaschema lineage)" : ""}`);
+    }
+    for (const version of report.ghosts) {
+        lines.push(`  ghost: ${version} (applied on target, no file on disk)`);
+    }
+    for (const file of report.outOfOrder) {
+        lines.push(`  out-of-order: ${file}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function readHistory(databaseUrl, historyTable, diagnostics) {
+    const parts = historyTable.split(".");
+    if (parts.length !== 2 || parts.some((part) => part.length === 0)) {
+        diagnostics.push(diagnostic("SUPA_MIGRATIONS_HISTORY_TABLE", "error", `history table "${historyTable}" must be schema-qualified`));
+        return undefined;
+    }
+    const client = new Client({ connectionString: databaseUrl });
+    try {
+        await client.connect();
+        const exists = await client.query("select exists (select 1 from pg_catalog.pg_class c join pg_catalog.pg_namespace n on n.oid = c.relnamespace where n.nspname = $1 and c.relname = $2) as found", [parts[0], parts[1]]);
+        if (exists.rows[0]?.found !== true) {
+            diagnostics.push(diagnostic("SUPA_MIGRATIONS_HISTORY_TABLE", "error", `history table ${historyTable} does not exist on the target`, { hint: "Pass --history-table for runners that record history elsewhere." }));
+            return undefined;
+        }
+        const result = await client.query(`select version::text as version from ${quoteIdent(parts[0] ?? "")}.${quoteIdent(parts[1] ?? "")}`);
+        return new Set(result.rows.map((row) => row.version));
+    }
+    catch (error) {
+        diagnostics.push(diagnostic("SUPA_MIGRATIONS_TARGET_UNAVAILABLE", "error", error instanceof Error ? error.message : String(error), { hint: "Confirm the database URL is reachable." }));
+        return undefined;
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+async function annotateLineage(directory, report) {
+    for (const file of report.pending) {
+        const handle = await readFile(join(directory, file), "utf8").catch(() => undefined);
+        if (handle === undefined) {
+            continue;
+        }
+        const lineage = parseLineage(handle.slice(0, lineageScanBytes));
+        if (lineage) {
+            report.pendingLineage.push({ file, ...lineage });
+        }
+    }
+}
+function redactUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.password) {
+            url.password = "***";
+        }
+        return url.toString();
+    }
+    catch {
+        return "<database>";
+    }
+}

package/dist/plan-order.d.ts

@@ -0,0 +1,4 @@
+import type { Diagnostic, MigrationOperation } from "./core.js";
+export declare function sortOperations(operations: MigrationOperation[], diagnostics: Diagnostic[]): MigrationOperation[];
+export declare function compareOperations(left: MigrationOperation, right: MigrationOperation): number;
+//# sourceMappingURL=plan-order.d.ts.map

package/dist/plan-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-order.d.ts","sourceRoot":"","sources":["../src/plan-order.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAyB,MAAM,WAAW,CAAC;AAgCvF,wBAAgB,cAAc,CAC5B,UAAU,EAAE,kBAAkB,EAAE,EAChC,WAAW,EAAE,UAAU,EAAE,GACxB,kBAAkB,EAAE,CAyDtB;AAoFD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAU7F"}

package/dist/plan-order.js

@@ -0,0 +1,178 @@
+import { diagnostic } from "./diagnostics.js";
+const createOrder = new Map([
+    ["schema", 10],
+    ["extension", 20],
+    ["enum", 30],
+    ["type", 40],
+    ["domain", 50],
+    ["sequence", 60],
+    ["foreign-data-wrapper", 70],
+    ["foreign-server", 80],
+    ["table", 90],
+    ["foreign-table", 100],
+    ["constraint", 110],
+    ["index", 120],
+    ["function", 130],
+    ["procedure", 140],
+    ["view", 150],
+    ["materialized-view", 160],
+    ["trigger", 170],
+    ["rls", 180],
+    ["policy", 190],
+    ["default-privilege", 200],
+    ["grant", 210],
+    ["comment", 220],
+]);
+const dropOrder = new Map([...createOrder.entries()].map(([kind, rank]) => [kind, 1000 - rank]));
+export function sortOperations(operations, diagnostics) {
+    const base = [...operations].sort(compareOperations);
+    const operationByKey = new Map(base.map((operation) => [operation.key, operation]));
+    const operationKeyByIdentity = identityIndex(base);
+    const outgoing = new Map();
+    const incomingCount = new Map();
+    for (const operation of base) {
+        outgoing.set(operation.key, new Set());
+        incomingCount.set(operation.key, 0);
+    }
+    for (const operation of base) {
+        for (const dependencyKey of operationDependencyKeys(operation, operationKeyByIdentity)) {
+            if (dependencyKey === operation.key || !operationByKey.has(dependencyKey)) {
+                continue;
+            }
+            if (operation.kind === "drop") {
+                addEdge(operation.key, dependencyKey, outgoing, incomingCount);
+            }
+            else {
+                addEdge(dependencyKey, operation.key, outgoing, incomingCount);
+            }
+        }
+    }
+    const remainingIncoming = new Map(incomingCount);
+    const ready = base.filter((operation) => remainingIncoming.get(operation.key) === 0);
+    const sorted = [];
+    while (ready.length > 0) {
+        ready.sort(compareOperations);
+        const operation = ready.shift();
+        if (!operation) {
+            break;
+        }
+        sorted.push(operation);
+        for (const target of outgoing.get(operation.key) ?? []) {
+            const nextCount = (remainingIncoming.get(target) ?? 0) - 1;
+            remainingIncoming.set(target, nextCount);
+            if (nextCount === 0) {
+                const targetOperation = operationByKey.get(target);
+                if (targetOperation) {
+                    ready.push(targetOperation);
+                }
+            }
+        }
+    }
+    if (sorted.length !== base.length) {
+        const leftover = new Set(base
+            .filter((operation) => (remainingIncoming.get(operation.key) ?? 0) > 0)
+            .map((operation) => operation.key));
+        diagnostics.push(diagnostic("SUPA_PLAN_DEPENDENCY_CYCLE", "error", "dependency ordering has a cycle", {
+            hint: traceCycle(leftover, outgoing) ?? [...leftover].join(", "),
+        }));
+        return base;
+    }
+    return sorted;
+}
+function identityIndex(operations) {
+    const index = new Map();
+    for (const operation of operations) {
+        for (const object of [operation.before, operation.after]) {
+            if (!object) {
+                continue;
+            }
+            index.set(refIdentity(object.ref), operation.key);
+        }
+    }
+    return index;
+}
+function refIdentity(ref) {
+    if (ref.kind === "schema") {
+        return ref.name;
+    }
+    return `${ref.schema ?? "public"}.${ref.name}`;
+}
+function operationDependencyKeys(operation, operationKeyByIdentity) {
+    const source = operation.kind === "drop" ? operation.before : (operation.after ?? operation.before);
+    if (!source) {
+        return [];
+    }
+    const keys = new Set();
+    for (const reference of source.dependencies) {
+        const operationKey = operationKeyByIdentity.get(reference);
+        if (operationKey) {
+            keys.add(operationKey);
+        }
+        const schemaOperationKey = operationKeyByIdentity.get(reference.split(".")[0] ?? "");
+        if (schemaOperationKey) {
+            keys.add(schemaOperationKey);
+        }
+    }
+    const ownSchema = source.ref.schema;
+    if (ownSchema) {
+        const schemaOperationKey = operationKeyByIdentity.get(ownSchema);
+        if (schemaOperationKey) {
+            keys.add(schemaOperationKey);
+        }
+    }
+    return [...keys];
+}
+function addEdge(from, to, outgoing, incomingCount) {
+    const targets = outgoing.get(from);
+    if (!targets || targets.has(to)) {
+        return;
+    }
+    targets.add(to);
+    incomingCount.set(to, (incomingCount.get(to) ?? 0) + 1);
+}
+function traceCycle(leftover, outgoing) {
+    for (const start of leftover) {
+        const path = [];
+        const seen = new Set();
+        let current = start;
+        while (current !== undefined && !seen.has(current)) {
+            seen.add(current);
+            path.push(current);
+            current = [...(outgoing.get(current) ?? [])].find((target) => leftover.has(target));
+        }
+        if (current !== undefined) {
+            const cycleStart = path.indexOf(current);
+            return [...path.slice(cycleStart), current].join(" -> ");
+        }
+    }
+    return undefined;
+}
+export function compareOperations(left, right) {
+    const rank = operationRank(left) - operationRank(right);
+    if (rank !== 0) {
+        return rank;
+    }
+    const ordinal = operationOrdinal(left) - operationOrdinal(right);
+    if (ordinal !== 0) {
+        return ordinal;
+    }
+    return left.key.localeCompare(right.key);
+}
+function operationRank(operation) {
+    if (operation.kind === "drop") {
+        return dropOrder.get(operation.ref.kind) ?? 500;
+    }
+    if (operation.kind === "rename") {
+        return 900 + (createOrder.get(operation.ref.kind) ?? 500);
+    }
+    if (operation.kind === "alter") {
+        return 1050 + (createOrder.get(operation.ref.kind) ?? 500);
+    }
+    return 1000 + (createOrder.get(operation.ref.kind) ?? 500);
+}
+function operationOrdinal(operation) {
+    if (operation.kind === "drop") {
+        return -(operation.before?.ordinal ?? 0);
+    }
+    return operation.after?.ordinal ?? operation.before?.ordinal ?? 0;
+}

package/dist/planner-replace.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationOperation, SupaschemaConfig } from "./core.js";
+export declare function isDestructiveAllowed(key: string, config: SupaschemaConfig): boolean;
+export declare function refineReplaceOperation(operation: MigrationOperation, config: SupaschemaConfig): MigrationOperation;
+//# sourceMappingURL=planner-replace.d.ts.map

package/dist/planner-replace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-replace.d.ts","sourceRoot":"","sources":["../src/planner-replace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAgB,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAIpF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CASnF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,gBAAgB,GACvB,kBAAkB,CAQpB"}

package/dist/planner-replace.js

@@ -0,0 +1,76 @@
+import { diagnostic } from "./diagnostics.js";
+import { stableJson } from "./hash.js";
+export function isDestructiveAllowed(key, config) {
+    if (config.destructiveChanges === "allow") {
+        return true;
+    }
+    if (config.destructiveChanges === "block") {
+        return false;
+    }
+    const hints = config.hints.destructive ?? [];
+    return hints.includes("*") || hints.includes(key);
+}
+export function refineReplaceOperation(operation, config) {
+    if (operation.ref.kind === "view") {
+        return refineViewReplace(operation, config);
+    }
+    if (operation.ref.kind === "function" || operation.ref.kind === "procedure") {
+        return refineRoutineReplace(operation, config);
+    }
+    return operation;
+}
+function refineViewReplace(operation, config) {
+    const before = viewColumns(operation.before);
+    const after = viewColumns(operation.after);
+    if (!before || !after) {
+        return operation;
+    }
+    operation.diagnostics = operation.diagnostics.filter((item) => item.code !== "SUPA_PLAN_VIEW_REPLACE_VERIFY_REQUIRED");
+    const prefixCompatible = after.length >= before.length && before.every((column, index) => after[index] === column);
+    if (prefixCompatible) {
+        return operation;
+    }
+    return markDropRequired(operation, config, "viewDropRequired", {
+        code: "SUPA_PLAN_VIEW_REPLACE_INCOMPATIBLE",
+        hint: `Add "${operation.key}" to hints.destructive to render a guarded DROP VIEW + CREATE after review.`,
+        message: "view replacement drops, renames, or reorders output columns; CREATE OR REPLACE VIEW cannot apply it",
+    });
+}
+function refineRoutineReplace(operation, config) {
+    const before = routineShape(operation.before);
+    const after = routineShape(operation.after);
+    if (before === after) {
+        return operation;
+    }
+    return markDropRequired(operation, config, "routineDropRequired", {
+        code: "SUPA_PLAN_ROUTINE_RETURN_TYPE_CHANGED",
+        hint: `Add "${operation.key}" to hints.destructive to render a guarded DROP + CREATE after review.`,
+        message: "routine replacement changes the return type or OUT parameters; CREATE OR REPLACE cannot apply it",
+    });
+}
+function markDropRequired(operation, config, metadataFlag, failure) {
+    operation.metadata[metadataFlag] = true;
+    operation.destructive = true;
+    if (!isDestructiveAllowed(operation.key, config)) {
+        operation.blocked = true;
+        operation.diagnostics.push(diagnostic(failure.code, "error", failure.message, {
+            hint: failure.hint,
+            ref: operation.ref,
+        }));
+    }
+    return operation;
+}
+function viewColumns(object) {
+    const columns = object?.metadata.viewColumns;
+    if (!Array.isArray(columns)) {
+        return undefined;
+    }
+    const names = columns.filter((column) => typeof column === "string");
+    return names.length === columns.length ? names : undefined;
+}
+function routineShape(object) {
+    return stableJson({
+        outParams: object?.metadata.outParams ?? null,
+        returns: object?.metadata.returns ?? null,
+    });
+}

package/dist/planner-table.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationOperation, SchemaObject, SupaschemaConfig } from "./core.js";
+export declare function makeTableAlterOperation(before: SchemaObject, after: SchemaObject, config: SupaschemaConfig): MigrationOperation | undefined;
+//# sourceMappingURL=planner-table.d.ts.map

package/dist/planner-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-table.d.ts","sourceRoot":"","sources":["../src/planner-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAEjB,MAAM,WAAW,CAAC;AAgBnB,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,gBAAgB,GACvB,kBAAkB,GAAG,SAAS,CAmFhC"}

package/dist/planner-table.js

@@ -0,0 +1,165 @@
+import { diagnostic } from "./diagnostics.js";
+import { stableJson } from "./hash.js";
+import { isDestructiveAllowed } from "./planner-replace.js";
+export function makeTableAlterOperation(before, after, config) {
+    if (before.ref.kind !== "table" || after.ref.kind !== "table") {
+        return undefined;
+    }
+    const beforeShape = canonicalShape(before);
+    const afterShape = canonicalShape(after);
+    if (!beforeShape || !afterShape) {
+        return undefined;
+    }
+    if (stableJson({ ...beforeShape, columns: undefined }) !==
+        stableJson({ ...afterShape, columns: undefined })) {
+        return undefined;
+    }
+    const beforeColumns = canonicalColumns(beforeShape);
+    const afterColumns = canonicalColumns(afterShape);
+    if (!beforeColumns || !afterColumns) {
+        return undefined;
+    }
+    const beforeByName = new Map(beforeColumns.map((column) => [column.name, column]));
+    const afterByName = new Map(afterColumns.map((column) => [column.name, column]));
+    const dropColumns = beforeColumns
+        .filter((column) => !afterByName.has(column.name))
+        .map((column) => column.name);
+    const addColumns = tableColumns(after).filter((column) => !beforeByName.has(column.name));
+    const alterColumns = [];
+    for (const column of afterColumns) {
+        const previous = beforeByName.get(column.name);
+        if (!previous || stableJson(previous) === stableJson(column)) {
+            continue;
+        }
+        const alteration = columnAlteration(previous, column, tableColumns(after));
+        if (!alteration) {
+            return undefined;
+        }
+        alterColumns.push(alteration);
+    }
+    if (dropColumns.length === 0 && addColumns.length === 0 && alterColumns.length === 0) {
+        return undefined;
+    }
+    const diagnostics = [];
+    let blocked = false;
+    for (const column of addColumns) {
+        const unsafeReason = unsafeAddColumnReason(column);
+        if (!unsafeReason) {
+            continue;
+        }
+        blocked = true;
+        diagnostics.push(diagnostic("SUPA_PLAN_ADD_COLUMN_UNSAFE", "error", unsafeReason, {
+            hint: "Use an explicit reviewed migration for column rewrites, backfills, constraints, or table scans.",
+            ref: after.ref,
+        }));
+    }
+    const destructive = dropColumns.length > 0 || alterColumns.some((alteration) => alteration.type !== undefined);
+    if (destructive && !isDestructiveAllowed(after.key, config)) {
+        blocked = true;
+        diagnostics.push(diagnostic("SUPA_PLAN_COLUMN_ALTER_HINT_REQUIRED", "error", "column drops and type changes require an explicit destructive-change hint", {
+            hint: `Add "${after.key}" to hints.destructive after reviewing the rendered column ALTERs.`,
+            ref: after.ref,
+        }));
+    }
+    return {
+        after,
+        before,
+        blocked,
+        destructive,
+        diagnostics,
+        key: after.key,
+        kind: "alter",
+        metadata: { addColumns, alterColumns, dropColumns },
+        ref: after.ref,
+    };
+}
+function columnAlteration(before, after, afterColumns) {
+    if (stableJson(before.identity ?? null) !== stableJson(after.identity ?? null) ||
+        stableJson(before.generated ?? null) !== stableJson(after.generated ?? null)) {
+        return undefined;
+    }
+    const alteration = { name: after.name };
+    let facetsExplained = 0;
+    let facetsChanged = 0;
+    if (before.type !== after.type) {
+        facetsChanged += 1;
+        if (typeof after.type === "string") {
+            alteration.type = after.type;
+            facetsExplained += 1;
+        }
+    }
+    if (before.notNull !== after.notNull) {
+        facetsChanged += 1;
+        facetsExplained += 1;
+        if (after.notNull === true) {
+            alteration.setNotNull = true;
+        }
+        else {
+            alteration.dropNotNull = true;
+        }
+    }
+    if (stableJson(before.default ?? null) !== stableJson(after.default ?? null)) {
+        facetsChanged += 1;
+        if (after.default === undefined) {
+            alteration.dropDefault = true;
+            facetsExplained += 1;
+        }
+        else {
+            const expression = afterColumns.find((column) => column.name === after.name)?.defaultExpression;
+            if (expression !== undefined) {
+                alteration.setDefault = expression;
+                facetsExplained += 1;
+            }
+        }
+    }
+    const residual = (entry) => {
+        const { default: _default, notNull: _notNull, type: _type, ...rest } = entry;
+        return stableJson(rest);
+    };
+    if (residual(before) !== residual(after)) {
+        return undefined;
+    }
+    if (facetsChanged === 0 || facetsExplained !== facetsChanged) {
+        return undefined;
+    }
+    return alteration;
+}
+function canonicalShape(object) {
+    const shape = object.metadata.canonicalShape;
+    return shape && typeof shape === "object" ? shape : undefined;
+}
+function canonicalColumns(shape) {
+    const columns = shape.columns;
+    if (!Array.isArray(columns)) {
+        return undefined;
+    }
+    const entries = [];
+    for (const column of columns) {
+        if (!column ||
+            typeof column !== "object" ||
+            typeof column.name !== "string") {
+            return undefined;
+        }
+        entries.push(column);
+    }
+    return entries;
+}
+function tableColumns(object) {
+    const columns = object.metadata.columns;
+    if (!Array.isArray(columns)) {
+        return [];
+    }
+    return columns.filter((column) => Boolean(column) &&
+        typeof column === "object" &&
+        typeof column.name === "string" &&
+        typeof column.definition === "string");
+}
+function unsafeAddColumnReason(column) {
+    if (column.identity || column.generated || column.hasInlineConstraint) {
+        return `column "${column.name}" adds inline constraints or generated behavior that requires explicit review`;
+    }
+    if (column.notNull === true && column.hasDefault !== true) {
+        return `column "${column.name}" is NOT NULL without a default and can fail on populated tables`;
+    }
+    return undefined;
+}

package/dist/planner.d.ts

@@ -0,0 +1,5 @@
+import type { MigrationPlan, RenderOptions, SchemaModel } from "./core.js";
+type DiffOptions = Pick<RenderOptions, "config">;
+export declare function planSchemaDiff(from: SchemaModel, to: SchemaModel, options?: DiffOptions): MigrationPlan;
+export {};
+//# sourceMappingURL=planner.d.ts.map

package/dist/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIV,aAAa,EAGb,aAAa,EACb,WAAW,EAGZ,MAAM,WAAW,CAAC;AAOnB,KAAK,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;AAEjD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,WAAgB,GACxB,aAAa,CAkFf"}