turbine-orm 0.65.0 → 0.66.0

package/dist/cli/index.js

@@ -24,12 +24,12 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
-import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate, generatePrismaMap } from '../generate.js';
-import { buildCreateIndexSql, buildDropIndexSql, collectDoctorProbeIndexNames, collectRelationProbeColumns, findMissingRelationIndexes, } from '../index-advisor.js';
+import { buildCreateIndexSql, buildCreateIndexStatements, buildDropIndexSql, collectDoctorProbeIndexNames, collectRelationProbeColumns, findMissingRelationIndexes, } from '../index-advisor.js';
 import { auditDoctorIndexes, collectStatsSnapshot, collectTableHeat, findInvalidIndexes, findRedundantIndexes, findUnusedIndexes, formatBytes, isSnapshotUsable, STATS_THRESHOLDS, scoreMissingIndex, } from '../index-stats.js';
 import { introspect } from '../introspect.js';
 import { collectDivergenceCandidateColumns, collectDivergenceOrderColumns, findPlanDivergence, PLAN_DIVERGENCE_THRESHOLDS, } from '../plan-divergence.js';
@@ -911,15 +911,21 @@ async function runInitPush(config, url) {
     }
     const schemaDef = await loadSchemaFile(config.schemaFile);
     const spinner = new Spinner('Computing schema diff').start();
-    const diff = await schemaDiff(schemaDef, url);
+    const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
     if (diff.statements.length === 0) {
         spinner.succeed('Database already in sync: nothing to push');
         return;
     }
     spinner.succeed(`Found ${bold(String(diff.statements.length))} change(s) to apply`);
+    // Same as `push`: a type change carries a warning naming what it costs the
+    // existing rows, and it is worth no less here than on the standalone command.
+    if (diff.warnings && diff.warnings.length > 0) {
+        for (const w of diff.warnings)
+            warn(w);
+    }
     const pushSpinner = new Spinner('Applying schema').start();
     try {
-        const result = await schemaPush(schemaDef, url, { precomputedDiff: diff });
+        const result = await schemaPush(schemaDef, url, { precomputedDiff: diff, schema: config.schema });
         pushSpinner.succeed(`Applied ${bold(String(result.statementsExecuted))} statement(s)`);
     }
     catch (err) {
@@ -930,7 +936,11 @@ async function runInitPush(config, url) {
             warn('Push aborted: no schema changes were applied.');
             return;
         }
-        const result = await schemaPush(schemaDef, url, { allowDestructive: true, precomputedDiff: diff });
+        const result = await schemaPush(schemaDef, url, {
+            allowDestructive: true,
+            precomputedDiff: diff,
+            schema: config.schema,
+        });
         success(`Applied ${bold(String(result.statementsExecuted))} statement(s)`);
     }
 }
@@ -1405,19 +1415,57 @@ export function resolveMigrateFromPrismaUrl(configUrl, ast, env) {
     }
     return { source: 'none', missingVariables: lookup.missingVariables };
 }
+/**
+ * Read a Prisma schema from a FILE or from a multi-file schema DIRECTORY
+ * (Prisma >= 5.15, GA). A directory used to reach `readFileSync` unchanged and
+ * die with a raw `EISDIR`, which is a stack trace rather than an answer.
+ *
+ * Prisma treats every `.prisma` file under the directory as one logical schema,
+ * so they are concatenated in sorted order (stable across machines) and parsed
+ * as a single source. Line numbers in any parse error then refer to that
+ * concatenation, so each file is introduced by a comment naming it.
+ */
+export function readPrismaSchemaSource(path) {
+    if (!statSync(path).isDirectory())
+        return readFileSync(path, 'utf-8');
+    const files = readdirSync(path)
+        .filter((f) => f.endsWith('.prisma'))
+        .sort();
+    if (files.length === 0) {
+        throw new Error(`No .prisma files found in directory ${path}.`);
+    }
+    return files.map((f) => `// file: ${f}\n${readFileSync(join(path, f), 'utf-8')}`).join('\n');
+}
 async function cmdMigrateFromPrisma(args, config) {
     banner();
-    // `--schema` is the Prisma schema file path in this command.
-    const prismaPath = resolve(args.schema ?? 'prisma/schema.prisma');
+    // `--schema` is the Prisma schema file path in this command. It may also name
+    // a DIRECTORY (Prisma's multi-file schema, GA since 5.15), and the default
+    // `prisma/schema.prisma` falls back to `prisma/schema/` for the same reason.
+    const explicit = args.schema !== undefined;
+    let prismaPath = resolve(args.schema ?? 'prisma/schema.prisma');
+    if (!explicit && !existsSync(prismaPath) && existsSync(resolve('prisma/schema'))) {
+        prismaPath = resolve('prisma/schema');
+    }
     if (!existsSync(prismaPath)) {
-        error(`Prisma schema file not found: ${cyan(prismaPath)}`);
+        error(`Prisma schema not found: ${cyan(prismaPath)}`);
         newline();
-        console.log(`  ${dim('Point at it with')} ${cyan('--schema <path/to/schema.prisma>')} ${dim('(default: prisma/schema.prisma).')}`);
+        console.log(`  ${dim('Point at it with')} ${cyan('--schema <path>')} ${dim('(a .prisma file, or a directory of them;')}`);
+        console.log(`  ${dim('default: prisma/schema.prisma, then prisma/schema/).')}`);
         newline();
         process.exit(1);
     }
     // Parse (fatal only on a construct we must understand).
-    const source = readFileSync(prismaPath, 'utf-8');
+    let source;
+    try {
+        source = readPrismaSchemaSource(prismaPath);
+    }
+    catch (err) {
+        newline();
+        error(`Could not read ${cyan(prismaPath)}`);
+        console.log(`  ${red(err instanceof Error ? err.message : String(err))}`);
+        newline();
+        process.exit(1);
+    }
     let ast;
     try {
         ast = parsePrismaSchema(source);
@@ -1489,6 +1537,18 @@ async function cmdMigrateFromPrisma(args, config) {
         console.log(`  ${marker} ${line}`);
     }
     newline();
+    // Parser notes on the CONSOLE, not only in the Markdown report.
+    //
+    // `--no-db` is the first command anyone runs and the one place a parse
+    // problem should surface, and it was the one place that could not: resolution
+    // is skipped, `hasUnresolved` is false by construction, so the run printed a
+    // clean summary and exited 0 no matter what the parser had thrown away.
+    if (result.parseWarnings.length > 0) {
+        header('Parser notes');
+        for (const w of result.parseWarnings)
+            console.log(`  ${yellow(symbols.warning)} ${w}`);
+        newline();
+    }
     // Write outputs into the generate outDir.
     const outDir = resolve(config.out);
     const rel = relative(process.cwd(), outDir);
@@ -1536,6 +1596,15 @@ async function cmdMigrateFromPrisma(args, config) {
         newline();
         process.exit(1);
     }
+    // `--no-db` has no resolution to fail on, so parser notes are the ONLY signal
+    // it can carry. Treated like an unresolved item, and cleared by the same
+    // `--allow-partial` opt-in, so "exit 0" means the same thing in both modes.
+    if (args.noDb && result.parseWarnings.length > 0 && !args.allowPartial) {
+        warn(`${result.parseWarnings.length} parser note(s) above (also in the report). ` +
+            'Re-run with --allow-partial to accept them.');
+        newline();
+        process.exit(1);
+    }
     if (args.noDb) {
         info(`Parse-only report written. Re-run without ${cyan('--no-db')} against your database to resolve names.`);
     }
@@ -1558,7 +1627,7 @@ async function cmdPush(args, config) {
     info(`Schema defines ${bold(String(tableCount))} tables`);
     // Compute diff
     const diffSpinner = new Spinner('Computing schema diff').start();
-    const diff = await schemaDiff(schemaDef, url);
+    const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
     if (diff.statements.length === 0 && diff.drop.length === 0) {
         diffSpinner.succeed('Database is already in sync');
         newline();
@@ -1633,7 +1702,11 @@ async function cmdPush(args, config) {
     const pushSpinner = new Spinner('Applying changes').start();
     let result;
     try {
-        result = await schemaPush(schemaDef, url, { allowDestructive: args.allowDestructive, precomputedDiff: diff });
+        result = await schemaPush(schemaDef, url, {
+            allowDestructive: args.allowDestructive,
+            precomputedDiff: diff,
+            schema: config.schema,
+        });
     }
     catch (err) {
         if (!(err instanceof DestructivePushRefusal))
@@ -1645,7 +1718,11 @@ async function cmdPush(args, config) {
             process.exit(1);
         }
         pushSpinner.start();
-        result = await schemaPush(schemaDef, url, { allowDestructive: true, precomputedDiff: diff });
+        result = await schemaPush(schemaDef, url, {
+            allowDestructive: true,
+            precomputedDiff: diff,
+            schema: config.schema,
+        });
     }
     pushSpinner.succeed(`Applied ${bold(String(result.statementsExecuted))} statement(s)`);
     if (result.tablesCreated.length > 0) {
@@ -1759,7 +1836,7 @@ async function cmdMigrateCreate(args, config) {
         newline();
         const schemaDef = await loadSchemaFile(config.schemaFile);
         const diffSpinner = new Spinner('Computing schema diff').start();
-        const diff = await schemaDiff(schemaDef, url);
+        const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
         if (diff.statements.length === 0) {
             diffSpinner.succeed('Database is already in sync: nothing to migrate');
             newline();
@@ -1836,7 +1913,7 @@ async function cmdMigrateCreate(args, config) {
         newline();
         const schemaDef = await loadSchemaFile(config.schemaFile);
         const diffSpinner = new Spinner('Computing schema diff').start();
-        const diff = await schemaDiff(schemaDef, url);
+        const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
         if (diff.statements.length === 0) {
             diffSpinner.succeed('Database is already in sync: nothing to migrate');
             newline();
@@ -2496,9 +2573,24 @@ const TIER_LABEL = {
     'take-deliberately': 'TAKE DELIBERATELY',
     scrutinize: 'SCRUTINIZE',
 };
-/** Build the `CREATE INDEX` for a finding, honoring the partial-null suggestion. */
+/**
+ * The `CREATE INDEX` for a finding (display / JSON only), honoring the
+ * partial-null suggestion. The migration writer uses
+ * {@link buildCreateIndexStatements} instead, which adds the preceding
+ * `DROP INDEX CONCURRENTLY IF EXISTS` that makes a rerun converge.
+ */
 function doctorCreateSql(f, opts) {
     return buildCreateIndexSql(f.missing.table, f.missing.columns, f.missing.indexName, {
+        concurrently: opts.concurrently,
+        // The report line is advice a human may copy into psql, where the
+        // guard is genuinely useful and there is no corpse to skip.
+        ifNotExists: true,
+        partialNotNull: f.score.partialNotNull,
+    });
+}
+/** The statements the fix migration's UP body runs for one finding. */
+function doctorCreateStatements(f, opts) {
+    return buildCreateIndexStatements(f.missing.table, f.missing.columns, f.missing.indexName, {
         concurrently: opts.concurrently,
         partialNotNull: f.score.partialNotNull,
     });
@@ -2511,13 +2603,17 @@ const CONCURRENTLY_RECIPE_COMMENT = [
     '--',
     '--   1. Idempotency is required. This migration is recorded only after ALL',
     '--      statements succeed; a mid-file failure leaves earlier indexes built and',
-    '--      the migration unrecorded, so a rerun must be safe. IF NOT EXISTS keeps',
-    '--      each CREATE idempotent.',
-    '--   2. The INVALID-index trap. A CREATE INDEX CONCURRENTLY that fails partway',
-    '--      leaves an INVALID index behind. On rerun, IF NOT EXISTS SKIPS that',
-    '--      corpse (the name already exists), so the index is never actually built.',
-    '--      Fix: DROP INDEX CONCURRENTLY the invalid index, then rerun. Run',
-    '--      "turbine doctor" to list invalid indexes.',
+    '--      the migration unrecorded, so a rerun must be safe.',
+    '--   2. The INVALID-index trap, and why each CREATE is preceded by a DROP.',
+    '--      A CREATE INDEX CONCURRENTLY that fails partway leaves an INVALID index',
+    '--      behind, under the name it was asked for. IF NOT EXISTS matches on the',
+    '--      NAME and not on validity, so with it a rerun SKIPS the corpse and the',
+    '--      index is never actually built: the migration records as applied while',
+    '--      the index doctor reported is still missing. The DROP INDEX',
+    '--      CONCURRENTLY IF EXISTS line ahead of each CREATE is a no-op on the',
+    '--      first run (the index does not exist yet, which is why it was',
+    '--      proposed) and clears the corpse on a rerun, so rerunning converges on',
+    '--      a VALID index. Run "turbine doctor" to list invalid indexes.',
     '--   3. Locking. CREATE INDEX CONCURRENTLY waits for every transaction that can',
     '--      see the table to finish. A long-running transaction makes it wait and',
     '--      makes "migrate up" look hung. For bounded waits, SET lock_timeout /',
@@ -3231,7 +3327,7 @@ function renderPlanDivergence(divergence, attached) {
 /** Write the --fix migration (CONCURRENTLY + directive by default; plain with --no-concurrently). */
 function renderFixMigration(findings, config, args) {
     const concurrently = args.noConcurrently !== true;
-    const up = findings.map((f) => doctorCreateSql(f, { concurrently })).join('\n');
+    const up = findings.flatMap((f) => doctorCreateStatements(f, { concurrently })).join('\n');
     const down = findings.map((f) => buildDropIndexSql(f.missing.indexName, { concurrently })).join('\n');
     let file;
     if (concurrently) {

package/dist/cli/mcp.d.ts

@@ -1,6 +1,6 @@
 import type { Readable, Writable } from 'node:stream';
 import pg from 'pg';
-import { type ColumnMetadata, type RelationDef } from '../schema.js';
+import { type ColumnMetadata, type IndexMetadata, type RelationDef } from '../schema.js';
 export interface McpServerOptions {
     url: string;
     schema: string;
@@ -31,6 +31,14 @@ export interface McpServerHandle {
 }
 export declare function startMcpServer(options: McpServerOptions, transport?: McpTransport): McpServerHandle;
 interface ForeignKeyRow {
+    /**
+     * `pg_constraint.oid` as text. THE grouping key: a constraint NAME is unique
+     * only per table (conrelid, conname), so two tables in one schema may both
+     * have a `shared_fk` and grouping on the name alone merges them, which loses
+     * one table's relation entirely and points the other at a column its target
+     * does not have. The OID is unique catalog-wide.
+     */
+    constraint_oid: string;
     source_table: string;
     source_column: string;
     target_table: string;
@@ -38,13 +46,25 @@ interface ForeignKeyRow {
     constraint_name: string;
 }
 /**
- * Group raw FK rows into constraint-level entries and delegate relation
- * naming to the SHARED introspection builder (`buildRelationsFromForeignKeys`
- * + `addAutoManyToManyRelations` in ../introspect.ts). MCP previously carried
- * a stale copy of a retired naming scheme, so `turbine mcp` and `turbine
- * generate` derived DIFFERENT relation names from the same database.
- * Exported for the parity unit test.
+ * Group raw FK rows into constraint-level entries and delegate relation naming
+ * to `deriveCatalogRelations` in ../introspect.ts, the SAME entry point
+ * `turbine generate` goes through. MCP introspects for itself (it cannot assume
+ * generated metadata exists), so any divergence here is a divergence a live MCP
+ * client trips over: it reads a relation name out of the MCP schema tool, passes
+ * it back in a query, and the core builder rejects it.
+ *
+ * MCP used to assemble the pipeline by hand and drifted twice over, both times
+ * by OMITTING an optional argument, which is silently type-correct and changes
+ * the answer: without `uniqueSetsByTable` a UNIQUE foreign key came back as
+ * `users.profiles` (hasMany) where generate said `users.profile` (hasOne), and
+ * without `uniqueIndexColsByTable` every Prisma-style PK-less junction lost its
+ * auto-m2m relations. Passing the whole input set to one shared function is what
+ * makes those two failures impossible rather than merely fixed.
+ *
+ * `uniqueByTable` and `indexesByTable` are therefore REQUIRED parameters, not
+ * optional ones: an optional catalog input is exactly how the hasOne flip went
+ * missing here in the first place. Exported for the parity unit test.
  */
-export declare function buildRelations(tableNames: string[], columnsByTable: Map<string, ColumnMetadata[]>, pkByTable: Map<string, string[]>, rows: ForeignKeyRow[], enums?: Record<string, string[]>): Map<string, Record<string, RelationDef>>;
+export declare function buildRelations(tableNames: string[], columnsByTable: Map<string, ColumnMetadata[]>, pkByTable: Map<string, string[]>, rows: ForeignKeyRow[], uniqueByTable: Map<string, string[][]>, indexesByTable: Map<string, IndexMetadata[]>, enums?: Record<string, string[]>): Map<string, Record<string, RelationDef>>;
 export declare function runMcpServer(options: McpServerOptions): Promise<void>;
 export {};