turbine-orm 0.40.1 → 0.41.0

package/README.md

@@ -360,10 +360,12 @@ A few client options tune how `with` relations are loaded and encoded. All are o
 ```typescript
 const db = turbine({
   connectionString: process.env.DATABASE_URL,
-  // How with-clause relations resolve: 'join' (default, one correlated-subquery
-  // statement) or 'batched' (base query + one flat follow-up per relation).
-  // Override per query on findMany/findFirst/findUnique. See Relations.
-  relationLoadStrategy: 'join',
+  // How with-clause relations resolve: 'auto' (default since 0.41.0: the
+  // single-statement join plan, with a per-relation batched fallback when the
+  // correlation column has no covering index), 'join' (always one correlated-
+  // subquery statement), or 'batched' (base query + one flat follow-up per
+  // relation). Override per query on findMany/findFirst/findUnique.
+  relationLoadStrategy: 'auto',
   // 'positional' (Postgres-only) drops repeated JSON keys from relation
   // subqueries — ~39% fewer wire bytes on wide relations, byte-identical output.
   // Default 'object'.
@@ -887,6 +889,22 @@ const db = await turbinePowDB({ embedded: './data', syncMode: 'normal' }, schema
 // const db = await turbinePowDB('powdb://127.0.0.1:7070', schema);
 ```
 
+Migrating from Prisma? `turbine migrate-from-prisma` emits a typed `PRISMA_MAP`, and the
+`turbine-orm/prisma-compat` subpath wraps a `TurbineClient` in Prisma's `db.Model.*`
+surface (no new dependencies):
+
+```ts
+import { TurbineClient } from 'turbine-orm';
+import { createPrismaCompatClient } from 'turbine-orm/prisma-compat';
+import { SCHEMA } from './generated/turbine/metadata.js';
+import { PRISMA_MAP } from './generated/turbine/prisma-map.js';
+
+const db = new TurbineClient({ connectionString: process.env.DATABASE_URL }, SCHEMA);
+const prisma = createPrismaCompatClient(db, PRISMA_MAP);
+
+const users = await prisma.User.findMany({ include: { posts: { take: 5 } } });
+```
+
 ### Capability matrix
 
 Everything is honest about what ports and what doesn't. Features marked **PG-only** throw a typed `UnsupportedFeatureError` (`TURBINE_E017`) on other engines rather than silently degrading.

package/dist/cjs/cli/config.js

@@ -185,6 +185,9 @@ function resolveConfig(fileConfig, overrides) {
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
         seedFile: fileConfig.seed ?? fileConfig.seedFile,
         schemaFile: fileConfig.schemaFile ?? './turbine/schema.ts',
+        importExtension: overrides.importExtension ?? fileConfig.importExtension ?? 'auto',
+        keepColumnNames: overrides.keepColumnNames ?? fileConfig.keepColumnNames ?? false,
+        legacyToManyUniques: overrides.legacyToManyUniques ?? fileConfig.legacyToManyUniques ?? false,
     };
 }
 /**

package/dist/cjs/cli/index.js

@@ -6,6 +6,7 @@
  * Commands:
  *   turbine init                  — Initialize a Turbine project
  *   turbine generate | pull       — Introspect database and generate TypeScript types
+ *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
  *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
  *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
  *   turbine migrate up            — Apply pending migrations
@@ -80,6 +81,9 @@ const loader_js_1 = require("./loader.js");
 const mcp_js_1 = require("./mcp.js");
 const migrate_js_1 = require("./migrate.js");
 const observe_js_1 = require("./observe.js");
+const prisma_report_js_1 = require("./prisma-report.js");
+const prisma_resolve_js_1 = require("./prisma-resolve.js");
+const prisma_schema_js_1 = require("./prisma-schema.js");
 const studio_js_1 = require("./studio.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs(argv = process.argv.slice(2)) {
@@ -169,6 +173,21 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--no-timestamp':
                 result.noTimestamp = true;
                 break;
+            case '--import-ext':
+            case '--import-extension':
+                if (next !== 'js' && next !== 'none' && next !== 'auto') {
+                    console.error(`--import-ext requires one of: js, none, auto (got ${next ?? '(nothing)'})`);
+                    process.exit(1);
+                }
+                result.importExtension = next;
+                i++;
+                break;
+            case '--keep-column-names':
+                result.keepColumnNames = true;
+                break;
+            case '--legacy-to-many-uniques':
+                result.legacyToManyUniques = true;
+                break;
             case '--allow-destructive':
                 result.allowDestructive = true;
                 break;
@@ -215,6 +234,12 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--demo':
                 result.demo = true;
                 break;
+            case '--allow-partial':
+                result.allowPartial = true;
+                break;
+            case '--no-db':
+                result.noDb = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -930,17 +955,25 @@ async function cmdGenerate(args, config) {
     (0, ui_js_1.newline)();
     // Introspect
     const spinner = new ui_js_1.Spinner('Introspecting database schema').start();
+    const skippedInternalTables = [];
     const schema = await (0, introspect_js_1.introspect)({
         connectionString: url,
         schema: config.schema,
         include: config.include.length ? config.include : undefined,
         exclude: config.exclude.length ? config.exclude : undefined,
         includeViews: args.includeViews,
+        legacyToManyUniques: config.legacyToManyUniques,
+        onDefaultTableExclusion: (tables) => skippedInternalTables.push(...tables),
     });
     const tableNames = Object.keys(schema.tables);
     const totalColumns = Object.values(schema.tables).reduce((sum, t) => sum + t.columns.length, 0);
     const totalRelations = Object.values(schema.tables).reduce((sum, t) => sum + Object.keys(t.relations).length, 0);
     spinner.succeed(`Found ${(0, ui_js_1.bold)(String(tableNames.length))} tables, ${(0, ui_js_1.bold)(String(totalColumns))} columns, ${(0, ui_js_1.bold)(String(totalRelations))} relations`);
+    // F12: make the default bookkeeping-table exclusions discoverable rather than
+    // silent. `include` re-adds any of them byte-for-byte.
+    for (const t of skippedInternalTables) {
+        console.log(`    ${(0, ui_js_1.dim)(`${ui_js_1.symbols.teeEnd} skipped internal table ${t} (add it to include to keep it)`)}`);
+    }
     // Guard: zero tables means the generated client would be empty. That is almost
     // always a misconfiguration (wrong `schema`, an include/exclude that filtered
     // everything, or a database with no tables yet) rather than intent. Fail loudly
@@ -980,6 +1013,8 @@ async function cmdGenerate(args, config) {
         connectionString: url,
         zod: args.zod,
         noTimestamp: args.noTimestamp,
+        importExtension: config.importExtension,
+        keepColumnNames: config.keepColumnNames,
     });
     genSpinner.succeed(`Generated ${(0, ui_js_1.bold)(String(result.files.length))} files in ${(0, ui_js_1.elapsed)(startTime)}`);
     // List files
@@ -998,6 +1033,112 @@ async function cmdGenerate(args, config) {
     (0, ui_js_1.newline)();
 }
 // ---------------------------------------------------------------------------
+// migrate-from-prisma
+// ---------------------------------------------------------------------------
+/**
+ * `turbine migrate-from-prisma --schema prisma/schema.prisma` parses a Prisma
+ * schema, resolve its models/fields/relations/compound-uniques against the live
+ * database (unless `--no-db`), and emit (a) a Markdown resolution report and
+ * (b) a typed `prisma-map.ts` name map next to the generated client.
+ *
+ * NOTE: within THIS command `--schema` names the Prisma schema FILE (not the
+ * Postgres namespace, which the rest of the CLI's `--schema` means). The
+ * Postgres namespace is `public` here; multi-schema (`@@schema`) is unsupported
+ * in v1 and listed as a parser note in the report.
+ */
+async function cmdMigrateFromPrisma(args, config) {
+    (0, ui_js_1.banner)();
+    // `--schema` is the Prisma schema file path in this command.
+    const prismaPath = (0, node_path_1.resolve)(args.schema ?? 'prisma/schema.prisma');
+    if (!(0, node_fs_1.existsSync)(prismaPath)) {
+        (0, ui_js_1.error)(`Prisma schema file not found: ${(0, ui_js_1.cyan)(prismaPath)}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Point at it with')} ${(0, ui_js_1.cyan)('--schema <path/to/schema.prisma>')} ${(0, ui_js_1.dim)('(default: prisma/schema.prisma).')}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
+    // Parse (fatal only on a construct we must understand).
+    const source = (0, node_fs_1.readFileSync)(prismaPath, 'utf-8');
+    let ast;
+    try {
+        ast = (0, prisma_schema_js_1.parsePrismaSchema)(source);
+    }
+    catch (err) {
+        if (err instanceof prisma_schema_js_1.PrismaParseError) {
+            (0, ui_js_1.newline)();
+            (0, ui_js_1.error)(`Could not parse ${(0, ui_js_1.cyan)(prismaPath)}`);
+            console.log(`  ${(0, ui_js_1.red)(err.message)}`);
+            (0, ui_js_1.newline)();
+            process.exit(1);
+        }
+        throw err;
+    }
+    (0, ui_js_1.label)('Prisma schema', prismaPath);
+    (0, ui_js_1.label)('Models', String(ast.models.length));
+    (0, ui_js_1.label)('Enums', String(ast.enums.length));
+    // Resolve against the live database, unless --no-db (parse-only).
+    let schemaMeta = null;
+    if (args.noDb) {
+        (0, ui_js_1.info)('Parse-only mode (--no-db): names will not be resolved.');
+    }
+    else {
+        const url = requireUrl(config);
+        (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
+        const spinner = new ui_js_1.Spinner('Introspecting database schema').start();
+        schemaMeta = await (0, introspect_js_1.introspect)({
+            connectionString: url,
+            // The Postgres NAMESPACE is fixed to `public` here (`--schema` names the
+            // Prisma file, not the namespace).
+            schema: 'public',
+            // Prisma `view` models resolve against introspected views.
+            includeViews: true,
+            // Inherit the shared bookkeeping-table exclusions (Turbine + Prisma).
+            exclude: [...new Set([...config.exclude, ...prisma_resolve_js_1.DEFAULT_EXCLUDED_TABLES])],
+        });
+        spinner.succeed(`Introspected ${(0, ui_js_1.bold)(String(Object.keys(schemaMeta.tables).length))} tables`);
+    }
+    (0, ui_js_1.newline)();
+    const result = (0, prisma_resolve_js_1.resolvePrismaSchema)(ast, schemaMeta);
+    // Console summary.
+    (0, ui_js_1.header)('Resolution');
+    for (const line of (0, prisma_report_js_1.summaryLines)(result)) {
+        const marker = line.includes('[UNRESOLVED]') ? (0, ui_js_1.red)(ui_js_1.symbols.cross) : (0, ui_js_1.green)(ui_js_1.symbols.check);
+        console.log(`  ${marker} ${line}`);
+    }
+    (0, ui_js_1.newline)();
+    // Write outputs into the generate outDir.
+    const outDir = (0, node_path_1.resolve)(config.out);
+    const rel = (0, node_path_1.relative)(process.cwd(), outDir);
+    if (rel.startsWith('..') || (0, node_path_1.resolve)(rel) !== outDir) {
+        (0, ui_js_1.error)(`Output directory must be within the project root. Got: ${config.out}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    const reportPath = (0, node_path_1.join)(outDir, 'prisma-migration-report.md');
+    (0, node_fs_1.writeFileSync)(reportPath, (0, prisma_report_js_1.formatPrismaReport)(result, { schemaPath: prismaPath, noTimestamp: args.noTimestamp }), 'utf-8');
+    console.log(`  ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.cyan)(reportPath)} ${(0, ui_js_1.dim)('(report)')}`);
+    if (!args.noDb) {
+        const mapPath = (0, node_path_1.join)(outDir, 'prisma-map.ts');
+        (0, node_fs_1.writeFileSync)(mapPath, (0, generate_js_1.generatePrismaMap)(result.map, { noTimestamp: args.noTimestamp }), 'utf-8');
+        console.log(`  ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.cyan)(mapPath)} ${(0, ui_js_1.dim)('(typed name map)')}`);
+    }
+    (0, ui_js_1.newline)();
+    // Exit non-zero when anything is UNRESOLVED, unless --allow-partial.
+    if (result.hasUnresolved && !args.allowPartial) {
+        (0, ui_js_1.warn)('Some items could not be resolved (see the report). Re-run with --allow-partial to accept a partial map.');
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
+    if (args.noDb) {
+        (0, ui_js_1.info)(`Parse-only report written. Re-run without ${(0, ui_js_1.cyan)('--no-db')} against your database to resolve names.`);
+    }
+    else {
+        (0, ui_js_1.success)('Prisma name map generated.');
+    }
+    (0, ui_js_1.newline)();
+}
+// ---------------------------------------------------------------------------
 // Command: push
 // ---------------------------------------------------------------------------
 async function cmdPush(args, config) {
@@ -2164,6 +2305,7 @@ function showSubcommandHelp(command) {
         init: showInitHelp,
         generate: showGenerateHelp,
         pull: showGenerateHelp,
+        'migrate-from-prisma': showMigrateFromPrismaHelp,
         push: showPushHelp,
         migrate: showMigrateHelp,
         migration: showMigrateHelp,
@@ -2225,9 +2367,39 @@ function showGenerateHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--zod')}                 Also emit ${(0, ui_js_1.cyan)('zod.ts')} validation schemas ${(0, ui_js_1.dim)('(needs the zod dep)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--include-views')}       Include views + materialized views as read-only entities`);
     console.log(`    ${(0, ui_js_1.cyan)('--no-timestamp')}        Omit the ${(0, ui_js_1.dim)('Generated at:')} header line ${(0, ui_js_1.dim)('(reproducible, diff-stable output)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--import-ext')} ${(0, ui_js_1.dim)('<mode>')}    Sibling-import extension: ${(0, ui_js_1.cyan)('js')} / ${(0, ui_js_1.cyan)('none')} / ${(0, ui_js_1.cyan)('auto')} ${(0, ui_js_1.dim)('(default: auto)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--keep-column-names')}   Keep raw DB column names as field names ${(0, ui_js_1.dim)('(snake_case, not camelCase)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--legacy-to-many-uniques')} Emit ${(0, ui_js_1.cyan)('hasMany')} for unique-FK children ${(0, ui_js_1.dim)('(pre-0.41 shape; default flips to hasOne)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--allow-empty')}         Generate even when introspection matches 0 tables`);
     (0, ui_js_1.newline)();
 }
+function showMigrateFromPrismaHelp() {
+    (0, ui_js_1.banner)();
+    console.log(`  ${(0, ui_js_1.bold)('turbine migrate-from-prisma')} - Map a Prisma schema onto a Turbine client`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Usage:')}`);
+    console.log(`    npx turbine migrate-from-prisma ${(0, ui_js_1.dim)('--schema prisma/schema.prisma [options]')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  Parses your ${(0, ui_js_1.cyan)('schema.prisma')}, resolves models/fields/relations/compound`);
+    console.log(`  uniques against the live database, and writes into the output directory:`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('prisma-migration-report.md')} - per-model resolution + unresolved items`);
+    console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('prisma-map.ts')}              - typed PRISMA_MAP name map`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('Note:')} here ${(0, ui_js_1.cyan)('--schema')} names the Prisma FILE (not the Postgres namespace).`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema')} ${(0, ui_js_1.dim)('<file>')}     Path to schema.prisma ${(0, ui_js_1.dim)('(default: prisma/schema.prisma)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}     Postgres connection string ${(0, ui_js_1.dim)('(unless --no-db)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--out, -o')} ${(0, ui_js_1.dim)('<dir>')}     Output directory ${(0, ui_js_1.dim)('(default: ./generated/turbine)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-db')}             Parse-only: write the report without resolving names`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-partial')}     Exit 0 even when some items are UNRESOLVED`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-timestamp')}      Omit the ${(0, ui_js_1.dim)('Generated:')} lines ${(0, ui_js_1.dim)('(reproducible output)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} DATABASE_URL=postgres://... npx turbine migrate-from-prisma --schema prisma/schema.prisma`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate-from-prisma --schema prisma/schema.prisma --no-db`);
+    (0, ui_js_1.newline)();
+}
 function showPushHelp() {
     (0, ui_js_1.banner)();
     console.log(`  ${(0, ui_js_1.bold)('turbine push')} — Apply schema-builder definitions to database`);
@@ -2340,6 +2512,7 @@ function showHelp() {
     console.log(`  ${(0, ui_js_1.bold)('Commands:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('init')}               Initialize a Turbine project`);
     console.log(`    ${(0, ui_js_1.cyan)('generate')} ${(0, ui_js_1.dim)('| pull')}    Introspect database ${ui_js_1.symbols.arrow} generate types`);
+    console.log(`    ${(0, ui_js_1.cyan)('migrate-from-prisma')} Map a schema.prisma onto Turbine ${(0, ui_js_1.dim)('(report + typed name map)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('push')}               Apply schema definitions to database`);
     console.log(`    ${(0, ui_js_1.cyan)('migrate')} ${(0, ui_js_1.dim)('<sub>')}      SQL migration management`);
     console.log(`      ${(0, ui_js_1.dim)('create <name>')}    Create a new migration file`);
@@ -2500,6 +2673,9 @@ async function main() {
         schema: args.schema,
         include: args.include,
         exclude: args.exclude,
+        importExtension: args.importExtension,
+        keepColumnNames: args.keepColumnNames,
+        legacyToManyUniques: args.legacyToManyUniques,
     };
     const config = (0, config_js_1.resolveConfig)(fileConfig, overrides);
     // Warn (don't change precedence) when an .env-sourced DATABASE_URL is silently
@@ -2526,6 +2702,9 @@ async function main() {
             case 'pull':
                 await cmdGenerate(args, config);
                 break;
+            case 'migrate-from-prisma':
+                await cmdMigrateFromPrisma(args, config);
+                break;
             case 'push':
                 await cmdPush(args, config);
                 break;

package/dist/cjs/cli/prisma-report.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Render a {@link ResolutionResult} into the `prisma-migration-report.md`
+ * artifact and a short console summary. Pure leaf - string in, string out.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPrismaReport = formatPrismaReport;
+exports.collectUnresolved = collectUnresolved;
+exports.summaryLines = summaryLines;
+const CHECK = 'OK';
+const CROSS = 'UNRESOLVED';
+function modelDisplayStatus(m) {
+    if (m.status === 'parsed')
+        return 'parsed';
+    if (m.status === 'unresolved')
+        return CROSS;
+    return m.viaMap ? `${CHECK} (@@map)` : CHECK;
+}
+/**
+ * Build the full Markdown migration report.
+ */
+function formatPrismaReport(result, options = {}) {
+    const L = [];
+    L.push('# Prisma to Turbine migration report');
+    L.push('');
+    if (options.schemaPath)
+        L.push(`Source: \`${options.schemaPath}\``);
+    if (!options.noTimestamp)
+        L.push(`Generated: ${new Date().toISOString()}`);
+    L.push(`Mode: ${result.noDb ? 'parse-only (--no-db, no database resolution)' : 'resolved against live database'}`);
+    L.push('');
+    // ---- Summary ----------------------------------------------------------
+    const modelCount = result.models.length;
+    const resolvedModels = result.models.filter((m) => m.status === 'resolved').length;
+    const unresolvedModels = result.models.filter((m) => m.status === 'unresolved').length;
+    L.push('## Summary');
+    L.push('');
+    if (result.noDb) {
+        L.push(`- Parsed ${modelCount} model(s), ${result.enums.length} enum(s).`);
+        L.push('- No database URL provided - names were not resolved. Re-run without `--no-db` to resolve.');
+    }
+    else {
+        L.push(`- Models: ${resolvedModels}/${modelCount} resolved${unresolvedModels ? `, ${unresolvedModels} UNRESOLVED` : ''}.`);
+        L.push(`- Enums: ${result.enums.filter((e) => e.status === 'resolved').length}/${result.enums.length} resolved.`);
+        L.push(`- Overall: ${result.hasUnresolved ? 'INCOMPLETE (some items unresolved)' : 'complete (all items resolved)'}.`);
+    }
+    L.push('');
+    // ---- Model resolution table ------------------------------------------
+    L.push('## Models');
+    L.push('');
+    L.push('| Prisma model | Turbine accessor | Table | Status |');
+    L.push('| --- | --- | --- | --- |');
+    for (const m of result.models) {
+        L.push(`| ${m.prismaName} | ${m.accessor ?? '-'} | ${m.table ?? '-'} | ${modelDisplayStatus(m)} |`);
+    }
+    L.push('');
+    // ---- Per-model detail -------------------------------------------------
+    for (const m of result.models) {
+        L.push(`### ${m.prismaName}`);
+        L.push('');
+        if (m.status === 'unresolved') {
+            L.push(`> UNRESOLVED: ${m.reason ?? 'no matching table'}`);
+            L.push('');
+        }
+        if (m.fields.length > 0) {
+            L.push('Fields:');
+            L.push('');
+            for (const f of m.fields) {
+                if (f.status === 'resolved') {
+                    L.push(`- \`${f.prismaName}\` -> \`${f.turbineField}\` (column \`${f.column}\`)`);
+                }
+                else if (f.status === 'parsed') {
+                    L.push(`- \`${f.prismaName}\` (parsed)`);
+                }
+                else {
+                    L.push(`- \`${f.prismaName}\` UNRESOLVED: ${f.reason}`);
+                }
+            }
+            L.push('');
+        }
+        if (m.relations.length > 0) {
+            L.push('Relations:');
+            L.push('');
+            for (const r of m.relations) {
+                if (r.status === 'resolved') {
+                    const j = r.junction ? `, junction \`${r.junction}\`` : '';
+                    L.push(`- \`${r.prismaName}\` -> \`${r.turbineName}\` (${r.cardinality}${j})`);
+                }
+                else if (r.status === 'parsed') {
+                    L.push(`- \`${r.prismaName}\` -> ${r.targetModel} (parsed)`);
+                }
+                else {
+                    L.push(`- \`${r.prismaName}\` -> ${r.targetModel} UNRESOLVED: ${r.reason}`);
+                }
+            }
+            L.push('');
+        }
+        if (m.compoundUniques.length > 0) {
+            L.push('Compound unique / id selectors:');
+            L.push('');
+            for (const c of m.compoundUniques) {
+                if (c.status === 'resolved') {
+                    L.push(`- \`${c.selector}\` (@@${c.kind}) -> [${c.turbineFields.join(', ')}]`);
+                }
+                else if (c.status === 'parsed') {
+                    L.push(`- \`${c.selector}\` (@@${c.kind}, parsed): [${c.prismaFields.join(', ')}]`);
+                }
+                else {
+                    L.push(`- \`${c.selector}\` (@@${c.kind}) UNRESOLVED: ${c.reason}`);
+                }
+            }
+            L.push('');
+        }
+    }
+    // ---- Junction tables --------------------------------------------------
+    const junctions = new Set();
+    for (const m of result.models) {
+        for (const r of m.relations)
+            if (r.junction)
+                junctions.add(r.junction);
+    }
+    if (junctions.size > 0) {
+        L.push('## Junction tables (implicit m2m)');
+        L.push('');
+        for (const j of [...junctions].sort())
+            L.push(`- \`${j}\``);
+        L.push('');
+    }
+    // ---- Enums ------------------------------------------------------------
+    if (result.enums.length > 0) {
+        L.push('## Enums');
+        L.push('');
+        for (const e of result.enums) {
+            if (e.status === 'resolved')
+                L.push(`- \`${e.prismaName}\` -> \`${e.turbineName}\``);
+            else if (e.status === 'parsed')
+                L.push(`- \`${e.prismaName}\` (parsed)`);
+            else
+                L.push(`- \`${e.prismaName}\` UNRESOLVED: ${e.reason}`);
+        }
+        L.push('');
+    }
+    // ---- Unresolved roll-up ----------------------------------------------
+    const unresolved = collectUnresolved(result);
+    if (unresolved.length > 0) {
+        L.push('## Unresolved items');
+        L.push('');
+        for (const u of unresolved)
+            L.push(`- ${u}`);
+        L.push('');
+    }
+    // ---- Parser warnings --------------------------------------------------
+    if (result.parseWarnings.length > 0) {
+        L.push('## Parser notes');
+        L.push('');
+        for (const w of result.parseWarnings)
+            L.push(`- ${w}`);
+        L.push('');
+    }
+    // ---- Fixed semantic-divergence section --------------------------------
+    L.push(SEMANTIC_DIVERGENCE);
+    return `${L.join('\n')}\n`;
+}
+/** Flat list of unresolved item descriptions across the whole result. */
+function collectUnresolved(result) {
+    const out = [];
+    for (const m of result.models) {
+        if (m.status === 'unresolved')
+            out.push(`Model ${m.prismaName}: ${m.reason ?? 'no matching table'}`);
+        for (const f of m.fields) {
+            if (f.status === 'unresolved')
+                out.push(`${m.prismaName}.${f.prismaName} (field): ${f.reason}`);
+        }
+        for (const r of m.relations) {
+            if (r.status === 'unresolved')
+                out.push(`${m.prismaName}.${r.prismaName} (relation): ${r.reason}`);
+        }
+        for (const c of m.compoundUniques) {
+            if (c.status === 'unresolved')
+                out.push(`${m.prismaName}.${c.selector} (@@${c.kind}): ${c.reason}`);
+        }
+    }
+    for (const e of result.enums) {
+        if (e.status === 'unresolved')
+            out.push(`Enum ${e.prismaName}: ${e.reason}`);
+    }
+    return out;
+}
+/** Static section documenting known Prisma-vs-Turbine behavior differences. */
+const SEMANTIC_DIVERGENCE = `## Behavior notes (Prisma vs Turbine)
+
+These are deliberate semantic differences to keep in mind when porting queries.
+Phase 1 ships no runtime; it produces this report plus a typed name map. The
+phase-2 \`turbine-orm/prisma-compat\` adapter handles most of these translations.
+
+- Cursor pagination. Turbine cursors are EXCLUSIVE and the comparison direction
+  follows the \`orderBy\` entry for the cursor field. Prisma cursors are
+  INCLUSIVE and idiomatically paired with \`skip: 1\`. Port \`{ cursor, skip: n }\`
+  (n >= 1) to a Turbine cursor plus \`offset: n - 1\`.
+- Aggregate / groupBy \`_count\`. Prisma returns \`_count\` as a record
+  (\`{ _all: n }\` / per-field counts). Turbine's scalar \`_count: true\` returns a
+  number. Reshape as needed (the phase-2 adapter does this both directions).
+- Relation-array order. Without an \`orderBy\` on a \`with\`/\`include\` clause, the
+  order of a to-many relation array is unspecified in Turbine (\`json_agg\` order).
+  Add an explicit \`orderBy\` where order matters.
+- Connection URL. Prefer an explicit \`sslmode\` in the connection URL (or the
+  future-proof \`uselibpqcompat\` form) to avoid a per-boot pg SSL security
+  warning.`;
+/** A one-line-per-model console summary for the CLI. */
+function summaryLines(result) {
+    return result.models.map((m) => {
+        const status = modelDisplayStatus(m);
+        const target = m.accessor ? `${m.accessor} (${m.table})` : '-';
+        return `${m.prismaName} -> ${target}  [${status}]`;
+    });
+}