@happyvertical/smrt-core 0.47.1 → 0.47.2

package/dist/migrations/differ.d.ts

@@ -220,6 +220,84 @@ export declare class SchemaComparer {
      *    that orphan gets an executable `DROP NOT NULL` where the engine allows.
      */
     private compareColumns;
+    /**
+     * Detect a pending rename backfill (#2752): a manifest-declared column
+     * that exists live but holds no data, paired with an orphan (undeclared)
+     * live column of a compatible type that does hold data — the shape a
+     * framework field rename leaves behind when `db:migrate` adds the new
+     * column additively and never moves data into it. For each such pair,
+     * emit the copy-then-drop repair as an advisory: never executed,
+     * PostgreSQL and SQLite only (DuckDB/JSON are out of scope). The repair
+     * is genuinely idempotent SQL on PostgreSQL (a self-guarding
+     * `DO $$ ... $$` block); SQLite has no conditional-DDL construct, so its
+     * repair is operator-mediated instead — a guard query plus instructions,
+     * not a blind-rerun-safe statement. See {@link describeRenameDataPending}.
+     */
+    private detectRenameDataPending;
+    /**
+     * Live-data probe: does the column hold any non-null, non-empty value?
+     * Used by {@link detectRenameDataPending}. Errors propagate to the
+     * caller, which skips the pair rather than guessing (#2752).
+     */
+    private columnHasNonEmptyValue;
+    /**
+     * Live-data probe: are every one of a column's non-empty values
+     * UUID-shaped ({@link CANONICAL_UUID_PATTERN})? PostgreSQL pushes the
+     * check into the query with its regex operator; SQLite has no regex
+     * operator, but its case-sensitive `GLOB` can still express the fixed
+     * 36-character canonical shape ({@link CANONICAL_UUID_SQLITE_GLOB_PATTERN}
+     * against `LOWER(...)`, guarded by an exact `LENGTH(...) = 36` check), so
+     * both engines run one server-side aggregate `count(*)` rather than
+     * fetching every non-empty value into JS to test in a loop — important on
+     * a production table with many rows (#2767 review).
+     */
+    private allNonEmptyValuesUuidShaped;
+    /**
+     * Render the repair for one rename-data-pending pair (#2752): copy
+     * non-empty `oldColumn` into `newColumn` only where `newColumn` is still
+     * empty (casting to `uuid` when the new column is native uuid, otherwise a
+     * plain copy), then drop `oldColumn`.
+     *
+     * Idempotency review findings and the fix:
+     *
+     * - (P1) The `newColumn`-is-empty predicate previously compared any
+     *   non-uuid destination to `''` (`col IS NULL OR col = ''`), which is
+     *   only valid for text-affinity types — PostgreSQL rejects `col = ''`
+     *   for `integer`/`boolean`/`timestamp`/etc. before a same-type rename
+     *   pair of one of those types ever copies anything. Fixed by comparing
+     *   `CAST(col AS TEXT) = ''` instead, mirroring the same portable
+     *   emptiness check {@link columnHasNonEmptyValue} already uses for
+     *   detection, so the predicate is valid for every column type.
+     * - (P2) An `UPDATE` unconditionally naming `oldColumn` fails once that
+     *   column is gone, on either engine, regardless of the DROP's own
+     *   idempotency — a guard query placed before the DROP (or even before
+     *   the UPDATE) still leaves a human decision between "run" and "don't",
+     *   which is not genuine SQL-level idempotency. PostgreSQL CAN express a
+     *   truly self-contained, unconditionally-safe-to-rerun statement here:
+     *   an anonymous `DO $$ ... $$` block (the same idiom this file already
+     *   uses for `generatePostgresIntegerPreflightSQL`) that checks
+     *   `information_schema.columns` and only runs the UPDATE + DROP when the
+     *   old column still exists — one executable statement, no operator
+     *   judgment required, safe to rerun any number of times. SQLite has no
+     *   procedural block or conditional-DDL construct at all (confirmed
+     *   against a real connection), so there the contract is explicitly
+     *   downgraded from "idempotent SQL" to "operator-mediated": a guard
+     *   query plus instructions, not a single statement that is itself safe
+     *   to blindly rerun.
+     *
+     * This is report-only either way: `db:migrate` never executes it.
+     */
+    private describeRenameDataPending;
+    /**
+     * Render the advisory for an ambiguous rename-data-pending match (#2767
+     * review): more than one orphan column is a populated, type-compatible
+     * candidate for the same empty declared column, so the real rename source
+     * cannot be inferred. Unlike {@link describeRenameDataPending}, this
+     * carries no `suggestedSql` — running a per-candidate copy-and-drop would
+     * let output order decide which candidate's data wins and then drop every
+     * one of them, which is not a repair an advisory should suggest blindly.
+     */
+    private describeRenameDataPendingAmbiguous;
     /**
      * Compare nullability and default between a manifest column and the live
      * column, emitting `alter_column` changes (#2369).

package/dist/migrations/differ.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"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"}

package/dist/migrations/differ.js

@@ -1,6 +1,6 @@
 import { normalizeForeignKeyAction, requireForeignKeyAction } from "../schema/foreign-key-policy.js";
 import { isJsonPathIndex, isStiSubtypeUniqueIndex, renderIndexTarget } from "../schema/index-utils.js";
-import { foreignKeyConstraintName, foreignKeyRelationshipKey, renderForeignKeyConstraint, renderForeignKeyOrphanDetector, renderForeignKeyOrphanRepair, schemaForeignKeys, schemaForeignKeysForEngine } from "../schema/foreign-key-ddl.js";
+import { CANONICAL_UUID_PATTERN, CANONICAL_UUID_SQLITE_GLOB_PATTERN, foreignKeyConstraintName, foreignKeyRelationshipKey, renderForeignKeyConstraint, renderForeignKeyOrphanDetector, renderForeignKeyOrphanRepair, schemaForeignKeys, schemaForeignKeysForEngine } from "../schema/foreign-key-ddl.js";
 import { detectEngine, getDDLStrategy } from "../schema/ddl/index.js";
 import { describeForeignKeyTypeConflict, planUuidConvergence, renderUuidConvergenceRepairHint, renderUuidShapeProbe } from "../schema/uuid-convergence.js";
 import "../schema/utils.js";
@@ -791,9 +791,199 @@ var SchemaComparer = class {
 			}
 			changes.push(this.describeOrphanColumn(tableName, colName, dbCol));
 		}
+		changes.push(...await this.detectRenameDataPending(tableName, manifest, dbSchema));
 		return changes;
 	}
 	/**
+	* Detect a pending rename backfill (#2752): a manifest-declared column
+	* that exists live but holds no data, paired with an orphan (undeclared)
+	* live column of a compatible type that does hold data — the shape a
+	* framework field rename leaves behind when `db:migrate` adds the new
+	* column additively and never moves data into it. For each such pair,
+	* emit the copy-then-drop repair as an advisory: never executed,
+	* PostgreSQL and SQLite only (DuckDB/JSON are out of scope). The repair
+	* is genuinely idempotent SQL on PostgreSQL (a self-guarding
+	* `DO $$ ... $$` block); SQLite has no conditional-DDL construct, so its
+	* repair is operator-mediated instead — a guard query plus instructions,
+	* not a blind-rerun-safe statement. See {@link describeRenameDataPending}.
+	*/
+	async detectRenameDataPending(tableName, manifest, dbSchema) {
+		if (this.engine !== "postgres" && this.engine !== "sqlite") return [];
+		const dbColumnNames = new Set(Object.keys(dbSchema.columns));
+		const manifestColumnNames = new Set(Object.keys(manifest.columns));
+		const orphanColumnNames = [...dbColumnNames].filter((name) => !manifestColumnNames.has(name));
+		if (orphanColumnNames.length === 0) return [];
+		const changes = [];
+		for (const [colName, colDef] of Object.entries(manifest.columns)) {
+			if (!dbSchema.columns[colName]) continue;
+			let declaredHasData;
+			try {
+				declaredHasData = await this.columnHasNonEmptyValue(tableName, colName);
+			} catch {
+				continue;
+			}
+			if (declaredHasData) continue;
+			const validatedType = isValidSQLDataType(colDef.type) ? colDef.type : "TEXT";
+			const isLogicalUuid = validatedType === "UUID";
+			const declaredNormalized = this.normalizeType(this.ddlStrategy.mapType(validatedType));
+			const candidates = [];
+			for (const orphanName of orphanColumnNames) {
+				const orphanCol = dbSchema.columns[orphanName];
+				const orphanNormalized = this.normalizeType(orphanCol.type);
+				const requiresShapeCheck = isLogicalUuid && orphanNormalized === "TEXT";
+				if (!requiresShapeCheck && !(orphanNormalized === declaredNormalized)) continue;
+				let orphanHasData;
+				try {
+					orphanHasData = await this.columnHasNonEmptyValue(tableName, orphanName);
+				} catch {
+					continue;
+				}
+				if (!orphanHasData) continue;
+				if (requiresShapeCheck) {
+					let shaped;
+					try {
+						shaped = await this.allNonEmptyValuesUuidShaped(tableName, orphanName);
+					} catch {
+						continue;
+					}
+					if (!shaped) continue;
+				}
+				candidates.push({
+					orphanName,
+					isUuidCast: declaredNormalized === "UUID"
+				});
+			}
+			if (candidates.length === 1) changes.push(this.describeRenameDataPending(tableName, colName, candidates[0].orphanName, candidates[0].isUuidCast));
+			else if (candidates.length > 1) changes.push(this.describeRenameDataPendingAmbiguous(tableName, colName, candidates.map((c) => c.orphanName)));
+		}
+		return changes;
+	}
+	/**
+	* Live-data probe: does the column hold any non-null, non-empty value?
+	* Used by {@link detectRenameDataPending}. Errors propagate to the
+	* caller, which skips the pair rather than guessing (#2752).
+	*/
+	async columnHasNonEmptyValue(tableName, colName) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		return ((await this.db.query(`SELECT 1 AS present FROM ${quotedTable} WHERE ${quotedCol} IS NOT NULL AND CAST(${quotedCol} AS TEXT) <> '' LIMIT 1`)).rows?.length ?? 0) > 0;
+	}
+	/**
+	* Live-data probe: are every one of a column's non-empty values
+	* UUID-shaped ({@link CANONICAL_UUID_PATTERN})? PostgreSQL pushes the
+	* check into the query with its regex operator; SQLite has no regex
+	* operator, but its case-sensitive `GLOB` can still express the fixed
+	* 36-character canonical shape ({@link CANONICAL_UUID_SQLITE_GLOB_PATTERN}
+	* against `LOWER(...)`, guarded by an exact `LENGTH(...) = 36` check), so
+	* both engines run one server-side aggregate `count(*)` rather than
+	* fetching every non-empty value into JS to test in a loop — important on
+	* a production table with many rows (#2767 review).
+	*/
+	async allNonEmptyValuesUuidShaped(tableName, colName) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedCol = this.quoteIdentifier(colName);
+		const nonEmptyPredicate = `${quotedCol} IS NOT NULL AND CAST(${quotedCol} AS TEXT) <> ''`;
+		if (this.engine === "postgres") {
+			const row = (await this.db.query(`SELECT count(*) AS invalid_count FROM ${quotedTable} WHERE ${nonEmptyPredicate} AND CAST(${quotedCol} AS TEXT) !~* '${CANONICAL_UUID_PATTERN}'`)).rows?.[0];
+			return Number(row?.invalid_count ?? 0) === 0;
+		}
+		const row = (await this.db.query(`SELECT count(*) AS invalid_count FROM ${quotedTable} WHERE ${nonEmptyPredicate} AND NOT (LENGTH(CAST(${quotedCol} AS TEXT)) = 36 AND LOWER(CAST(${quotedCol} AS TEXT)) GLOB '${CANONICAL_UUID_SQLITE_GLOB_PATTERN}')`)).rows?.[0];
+		return Number(row?.invalid_count ?? 0) === 0;
+	}
+	/**
+	* Render the repair for one rename-data-pending pair (#2752): copy
+	* non-empty `oldColumn` into `newColumn` only where `newColumn` is still
+	* empty (casting to `uuid` when the new column is native uuid, otherwise a
+	* plain copy), then drop `oldColumn`.
+	*
+	* Idempotency review findings and the fix:
+	*
+	* - (P1) The `newColumn`-is-empty predicate previously compared any
+	*   non-uuid destination to `''` (`col IS NULL OR col = ''`), which is
+	*   only valid for text-affinity types — PostgreSQL rejects `col = ''`
+	*   for `integer`/`boolean`/`timestamp`/etc. before a same-type rename
+	*   pair of one of those types ever copies anything. Fixed by comparing
+	*   `CAST(col AS TEXT) = ''` instead, mirroring the same portable
+	*   emptiness check {@link columnHasNonEmptyValue} already uses for
+	*   detection, so the predicate is valid for every column type.
+	* - (P2) An `UPDATE` unconditionally naming `oldColumn` fails once that
+	*   column is gone, on either engine, regardless of the DROP's own
+	*   idempotency — a guard query placed before the DROP (or even before
+	*   the UPDATE) still leaves a human decision between "run" and "don't",
+	*   which is not genuine SQL-level idempotency. PostgreSQL CAN express a
+	*   truly self-contained, unconditionally-safe-to-rerun statement here:
+	*   an anonymous `DO $$ ... $$` block (the same idiom this file already
+	*   uses for `generatePostgresIntegerPreflightSQL`) that checks
+	*   `information_schema.columns` and only runs the UPDATE + DROP when the
+	*   old column still exists — one executable statement, no operator
+	*   judgment required, safe to rerun any number of times. SQLite has no
+	*   procedural block or conditional-DDL construct at all (confirmed
+	*   against a real connection), so there the contract is explicitly
+	*   downgraded from "idempotent SQL" to "operator-mediated": a guard
+	*   query plus instructions, not a single statement that is itself safe
+	*   to blindly rerun.
+	*
+	* This is report-only either way: `db:migrate` never executes it.
+	*/
+	describeRenameDataPending(tableName, newColumn, oldColumn, newIsNativeUuid) {
+		const quotedTable = this.quoteIdentifier(tableName);
+		const quotedNew = this.quoteIdentifier(newColumn);
+		const quotedOld = this.quoteIdentifier(oldColumn);
+		const copySql = `UPDATE ${quotedTable} SET ${quotedNew} = ${newIsNativeUuid ? `${quotedOld}::uuid` : quotedOld} WHERE ${newIsNativeUuid ? `${quotedNew} IS NULL` : `(${quotedNew} IS NULL OR CAST(${quotedNew} AS TEXT) = '')`} AND ${quotedOld} IS NOT NULL AND CAST(${quotedOld} AS TEXT) <> ''`;
+		let suggestedSql;
+		let dropIdempotencyNote;
+		if (this.engine === "postgres") {
+			suggestedSql = [`DO $$ BEGIN IF ${`EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ${this.quoteLiteral(tableName)} AND column_name = ${this.quoteLiteral(oldColumn)})`} THEN ${copySql}; ${`ALTER TABLE ${quotedTable} DROP COLUMN ${quotedOld}`}; END IF; END $$`];
+			dropIdempotencyNote = `This single statement is idempotent: rerunning it after the rename is complete is a genuine no-op, because it only touches ${oldColumn} when the block finds it still exists.`;
+		} else {
+			suggestedSql = [
+				`SELECT count(*) AS old_column_still_present FROM pragma_table_info(${this.quoteLiteral(tableName)}) WHERE name = ${this.quoteLiteral(oldColumn)}`,
+				copySql,
+				this.generateDropColumnSQL(tableName, oldColumn)
+			];
+			dropIdempotencyNote = `SQLite has no conditional-DDL construct, so this is operator-mediated, not self-contained idempotent SQL: run the guard query first, and only run the UPDATE and DROP below when it reports ${oldColumn} still present.`;
+		}
+		return {
+			type: "rename_data_pending",
+			table: tableName,
+			name: newColumn,
+			mismatch: {
+				expected: `data in ${newColumn}`,
+				actual: `data appears to still be in ${oldColumn}`
+			},
+			advisory: {
+				severity: "warning",
+				message: `${tableName}.${newColumn} is declared but empty, while undeclared column ${tableName}.${oldColumn} holds data of a compatible type. This looks like a framework field rename whose data was never moved (db:migrate adds columns additively and never drops the old one). ${dropIdempotencyNote}`,
+				suggestedSql
+			}
+		};
+	}
+	/**
+	* Render the advisory for an ambiguous rename-data-pending match (#2767
+	* review): more than one orphan column is a populated, type-compatible
+	* candidate for the same empty declared column, so the real rename source
+	* cannot be inferred. Unlike {@link describeRenameDataPending}, this
+	* carries no `suggestedSql` — running a per-candidate copy-and-drop would
+	* let output order decide which candidate's data wins and then drop every
+	* one of them, which is not a repair an advisory should suggest blindly.
+	*/
+	describeRenameDataPendingAmbiguous(tableName, newColumn, candidateColumns) {
+		const candidateList = candidateColumns.map((name) => `${tableName}.${name}`).join(", ");
+		return {
+			type: "rename_data_pending",
+			table: tableName,
+			name: newColumn,
+			mismatch: {
+				expected: `data in ${newColumn}`,
+				actual: `data appears to still be in one of several columns: ${candidateList}`
+			},
+			advisory: {
+				severity: "warning",
+				message: `${tableName}.${newColumn} is declared but empty, while ${candidateColumns.length} undeclared columns of a compatible type hold data (${candidateList}). This looks like a framework field rename, but which column is the actual rename source is ambiguous — no suggested repair SQL is printed. An operator must identify the correct source column and write its own targeted copy-then-drop.`
+			}
+		};
+	}
+	/**
 	* Compare nullability and default between a manifest column and the live
 	* column, emitting `alter_column` changes (#2369).
 	*