@happyvertical/smrt-core 0.30.0

package/dist/migrations/differ.d.ts

@@ -0,0 +1,186 @@
+import { SchemaChange, SchemaDefinition, SchemaDiff } from '../schema/types.js';
+import { DatabaseInterface } from './types.js';
+/**
+ * Options for schema comparison
+ */
+export interface DiffOptions {
+    /** Include dropped tables in diff (default: false for safety) */
+    includeDroppedTables?: boolean;
+    /** Include dropped columns in diff (default: false for safety) */
+    includeDroppedColumns?: boolean;
+    /**
+     * Drop indexes that exist in the database but are absent from the manifest
+     * AND are not functionally equivalent to anything in the manifest. Default:
+     * false. The differ always skips primary-key indexes (`*_pkey`) and the
+     * implicit indexes that PostgreSQL creates from inline UNIQUE constraints
+     * (`*_key`) — those are owned by table-level constraints, not by the
+     * index list, and dropping them here would break the constraint.
+     */
+    includeDroppedIndexes?: boolean;
+    /** Ignore type mismatches (just log warnings) */
+    ignoreTypeMismatches?: boolean;
+    /**
+     * Explicit engine hint forwarded to `detectEngine` when picking the DDL
+     * strategy used for *existing-table* SQL (ALTER/CREATE INDEX/etc.). Use
+     * this when `db.url` is empty or ambiguous (e.g. JSON adapter, in-memory
+     * wrappers where the URL lives on `db.config?.url`). Without it the
+     * comparer falls back to URL-only detection, which can produce SQLite-
+     * flavored SQL on a connection whose caller meant Postgres or DuckDB.
+     */
+    engineHint?: string;
+}
+/**
+ * SchemaComparer class for comparing manifest schemas to database
+ */
+export declare class SchemaComparer {
+    private db;
+    private options;
+    private engine;
+    private ddlStrategy;
+    constructor(db: DatabaseInterface, options?: DiffOptions);
+    /**
+     * Compare manifest schemas to database and return differences
+     */
+    compare(manifestSchemas: Record<string, SchemaDefinition>): Promise<SchemaDiff>;
+    /**
+     * Compare a single table's schema to manifest
+     */
+    compareTable(tableName: string, manifest: SchemaDefinition): Promise<SchemaChange[]>;
+    /**
+     * Compare columns between manifest and database
+     */
+    private compareColumns;
+    private isUuidTextEquivalentColumn;
+    private isStructuralUuidCompatibleColumn;
+    /**
+     * Compare indexes between manifest and database
+     *
+     * Three classes of drift the differ now detects:
+     *
+     * 1. **Missing index** — manifest has an index neither the DB has by name
+     *    nor any equivalent-by-signature. Emit `add_index`. (Issue #741: the
+     *    signature check protects against creating duplicates when STI child
+     *    classes register indexes with different name prefixes.)
+     *
+     * 2. **Same-name shape drift** — DB has an index with the manifest's name,
+     *    but its columns or uniqueness flag differ. This is the failure mode
+     *    in issue #1165: `tenants_slug_context_meta_type_idx` exists but is
+     *    non-unique, while the manifest declares it unique. Emit
+     *    `drop_index` + `add_index` so the next migrate cycle recreates it
+     *    with the correct shape.
+     *
+     * 3. **Orphan in DB** — DB has an index with no manifest counterpart by
+     *    name and no signature equivalent. Emit `drop_index` *only* when the
+     *    caller opts in via `includeDroppedIndexes`, and even then never for
+     *    PostgreSQL implicit indexes (`*_pkey`, `*_key`) — those are owned by
+     *    table-level constraints and need a separate `DROP CONSTRAINT` path
+     *    that the differ does not emit yet.
+     */
+    private compareIndexes;
+    /**
+     * Generate a signature for an index based on its columns and uniqueness.
+     * Used for functional equivalence checking (Issue #741).
+     *
+     * Note: Column order is preserved because it is semantically significant for
+     * composite indexes. An index on (a, b) is NOT equivalent to (b, a) - they
+     * have different query performance characteristics.
+     *
+     * Limitation: Partial indexes (with WHERE clauses) are not fully supported.
+     * The database introspection layer doesn't provide WHERE clause information,
+     * so two partial indexes with the same columns but different WHERE clauses
+     * cannot be distinguished and may be incorrectly treated as equivalent.
+     *
+     * For JSON-path indexes (`@meta({ indexed: true })`) the signature is
+     * derived from the JSON path instead of an empty column list, so the
+     * differ can distinguish two jsonPath indexes against different paths.
+     *
+     * @param idxOrColumns - Either an IndexDefinition or a column array (legacy)
+     * @param uniqueArg - Unique flag (used when first arg is a column array)
+     * @returns Signature string
+     */
+    private getIndexSignature;
+    /**
+     * Get list of existing tables from database
+     */
+    private getExistingTables;
+    /**
+     * Normalize SQL types for comparison
+     */
+    private normalizeType;
+    /**
+     * Check if a type change is a safe upgrade that can be auto-migrated.
+     *
+     * SMRT controls the data lifecycle for these columns, so we know:
+     * - TEXT→JSON: The column stores JSON data serialized as text (arrays, objects)
+     * - TEXT/JSON→TIMESTAMP: Legacy system columns stored timestamp strings
+     *   before newer manifests normalized the column type.
+     * - INTEGER→REAL: Safe widening of integer to floating point
+     * - TEXT/REAL→INTEGER on PostgreSQL: explicit data-checked repairs for
+     *   legacy integer columns that were previously stored as text/real.
+     *
+     * @param manifestType - The abstract type from the manifest (e.g., 'JSON')
+     * @param dbType - The actual type in the database (e.g., 'TEXT')
+     * @returns true if the change from dbType to manifestType is a safe upgrade
+     */
+    private isCompatibleTypeUpgrade;
+    /**
+     * Generate SQL for a type upgrade migration.
+     *
+     * Engine-specific SQL:
+     * - SQLite: TEXT and JSON are equivalent, no-op or comment
+     * - DuckDB: ALTER COLUMN TYPE (native type conversion)
+     * - PostgreSQL: ALTER COLUMN TYPE with USING clause
+     */
+    private generateTypeUpgradeSQL;
+    /**
+     * Quote a SQL identifier
+     */
+    private quoteIdentifier;
+    /**
+     * Generate a PostgreSQL preflight guard for narrowing legacy columns to
+     * INTEGER. PostgreSQL's REAL→INTEGER cast rounds fractional values, so the
+     * generated migration must fail before the ALTER can silently change data.
+     */
+    private generatePostgresIntegerPreflightSQL;
+    private quoteLiteral;
+    /**
+     * Generate SQL for adding a column
+     */
+    private generateAddColumnSQL;
+    /**
+     * Generate SQL for dropping a column
+     */
+    private generateDropColumnSQL;
+    /**
+     * Generate SQL for adding an index
+     */
+    private generateAddIndexSQL;
+    /**
+     * Generate SQL for dropping an index.
+     *
+     * This SQL is consumed by the manifest-driven execution path:
+     *
+     * - `db:migrate` runs the SQL we put in `change.sql` directly, with the
+     *   tracker's `executePostgresStatements` adding CONCURRENTLY when
+     *   `--postgres-safe` is on.
+     *
+     * PostgreSQL ends up with `CONCURRENTLY` when it should.
+     * Keeping this method engine-agnostic also means the diff preview text
+     * stays readable (no engine-specific noise) for engines like SQLite
+     * where CONCURRENTLY isn't a thing.
+     */
+    private generateDropIndexSQL;
+}
+/**
+ * Generate a SchemaDiff from manifest and database
+ */
+export declare function generateSchemaDiff(db: DatabaseInterface, manifestSchemas: Record<string, SchemaDefinition>, options?: DiffOptions): Promise<SchemaDiff>;
+/**
+ * Check if a diff has any actionable changes (excluding type mismatches)
+ */
+export declare function hasActionableChanges(diff: SchemaDiff): boolean;
+/**
+ * Get SQL statements from a diff for execution
+ */
+export declare function getSQLFromDiff(diff: SchemaDiff): string[];
+//# sourceMappingURL=differ.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/migrations/differ.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAGV,YAAY,EACZ,gBAAgB,EAChB,UAAU,EAEX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,YAAY,CAAC;AA8BxE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAuBD;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAoC;gBAE3C,EAAE,EAAE,iBAAiB,EAAE,OAAO,GAAE,WAAgB;IAsB5D;;OAEG;IACG,OAAO,CACX,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAChD,OAAO,CAAC,UAAU,CAAC;IA4CtB;;OAEG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC;IAqB1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAwItB,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,gCAAgC;IAexC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,cAAc;IAoJtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;YACW,iBAAiB;IAgB/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAmDrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,uBAAuB;IAiD/B;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAoI9B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,mCAAmC;IAgB3C,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiD5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,oBAAoB;CAG7B;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,iBAAiB,EACrB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACjD,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAI9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAgBzD"}