@rebasepro/server-postgresql 0.0.1-canary.ca2cb6e → 0.0.1-canary.dbf160a

package/src/schema/introspect-db.ts

@@ -0,0 +1,211 @@
+import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+import pg from "pg";
+import arg from "arg";
+import * as dotenv from "dotenv";
+
+import {
+    TableRow,
+    TableColumn,
+    EnumValue,
+    PrimaryKeyRow,
+    ForeignKeyRow,
+    buildTablesMap,
+    buildEnumMap,
+    identifyJoinTables,
+    generateCollectionFile,
+    generateIndexContent,
+    mergeIndexContent,
+    safeHostFromUrl,
+} from "./introspect-db-logic";
+
+async function main() {
+    const args = arg(
+        {
+            "--output": String,
+            "--force": Boolean,
+            "--schema": String,
+            "-o": "--output",
+            "-f": "--force",
+        },
+        { permissive: true }
+    );
+
+    const outDir = args["--output"] || path.resolve(process.cwd(), "config", "collections");
+    const force = args["--force"] || false;
+    const pgSchema = args["--schema"] || "public";
+
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+
+    // Load env
+    const envPaths = [
+        process.env.DOTENV_CONFIG_PATH,
+        path.resolve(process.cwd(), ".env"),
+        path.resolve(process.cwd(), "../.env"),
+        path.resolve(process.cwd(), "../../.env")
+    ].filter(Boolean) as string[];
+
+    for (const p of envPaths) {
+        if (fs.existsSync(p)) {
+            dotenv.config({ path: p });
+            break;
+        }
+    }
+
+    const databaseUrl = process.env.DATABASE_URL || process.env.ADMIN_CONNECTION_STRING;
+    if (!databaseUrl) {
+        console.error(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
+        process.exit(1);
+    }
+
+    const client = new pg.Client({ connectionString: databaseUrl });
+
+    try {
+        await client.connect();
+    } catch (err) {
+        console.error(chalk.red(`✗ Failed to connect to database: ${err instanceof Error ? err.message : String(err)}`));
+        console.error(chalk.gray("  Check your DATABASE_URL and ensure the database is reachable."));
+        process.exit(1);
+    }
+
+    // Log the host portion safely — handle URLs without "@"
+    const hostPart = safeHostFromUrl(databaseUrl);
+    console.log(chalk.gray(`Connected to database: ${hostPart}`));
+    console.log(chalk.gray(`Introspecting schema '${pgSchema}'...`));
+
+    try {
+        // 1. Get Tables
+        const { rows: tables } = await client.query<TableRow>(`
+            SELECT table_name
+            FROM information_schema.tables
+            WHERE table_schema = $1 AND table_type = 'BASE TABLE'
+              AND table_name NOT LIKE 'drizzle_%'
+              AND table_name NOT LIKE 'rebase_%'
+            ORDER BY table_name
+        `, [pgSchema]);
+
+        // 2. Get Columns
+        const { rows: columns } = await client.query<TableColumn>(`
+            SELECT table_name, column_name, data_type, udt_name, is_nullable, column_default
+            FROM information_schema.columns
+            WHERE table_schema = $1
+        `, [pgSchema]);
+
+        // 2b. Get Enum Types and their values
+        const { rows: enumValues } = await client.query<EnumValue>(`
+            SELECT t.typname AS enum_name,
+                   e.enumlabel AS enum_value,
+                   e.enumsortorder AS sort_order
+            FROM pg_type t
+            JOIN pg_enum e ON t.oid = e.enumtypid
+            JOIN pg_namespace n ON t.typnamespace = n.oid
+            WHERE n.nspname = $1
+            ORDER BY t.typname, e.enumsortorder
+        `, [pgSchema]);
+
+        // Build a map: enum_name -> ordered list of values
+        const enumMap = buildEnumMap(enumValues);
+
+        // 3. Get Primary Keys
+        const { rows: pks } = await client.query<PrimaryKeyRow>(`
+            SELECT t.relname as table_name, a.attname as column_name
+            FROM   pg_index i
+            JOIN   pg_attribute a ON a.attrelid = i.indrelid
+                                AND a.attnum = ANY(i.indkey)
+            JOIN   pg_class t ON t.oid = i.indrelid
+            JOIN   pg_namespace n ON n.oid = t.relnamespace
+            WHERE  i.indisprimary AND n.nspname = $1
+        `, [pgSchema]);
+
+        // 4. Get Foreign Keys
+        const { rows: fks } = await client.query<ForeignKeyRow>(`
+            SELECT
+                tc.table_name, 
+                kcu.column_name, 
+                ccu.table_name AS foreign_table_name,
+                ccu.column_name AS foreign_column_name 
+            FROM 
+                information_schema.table_constraints AS tc 
+                JOIN information_schema.key_column_usage AS kcu
+                  ON tc.constraint_name = kcu.constraint_name
+                  AND tc.table_schema = kcu.table_schema
+                JOIN information_schema.constraint_column_usage AS ccu
+                  ON ccu.constraint_name = tc.constraint_name
+                  AND ccu.table_schema = tc.table_schema
+            WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = $1
+        `, [pgSchema]);
+
+        const tablesMap = buildTablesMap(tables, columns, pks, fks);
+        const joinTables = identifyJoinTables(tablesMap);
+
+        console.log(chalk.blue(`Found ${tablesMap.size} tables (including ${joinTables.size} detected join tables).`));
+
+        // Generate Collections
+        const generatedFiles: string[] = [];
+        const skippedFiles: string[] = [];
+
+        for (const [tableName, meta] of tablesMap.entries()) {
+            if (joinTables.has(tableName)) continue; // We don't generate base collections for pure join tables
+
+            // ── File overwrite protection ──────────────────────────────
+            const filePath = path.join(outDir, `${tableName}.ts`);
+            if (fs.existsSync(filePath) && !force) {
+                skippedFiles.push(tableName);
+                continue;
+            }
+
+            const fileContent = generateCollectionFile(
+                tableName,
+                meta,
+                fks,
+                joinTables,
+                tablesMap,
+                enumMap,
+            );
+
+            fs.writeFileSync(filePath, fileContent, "utf-8");
+            generatedFiles.push(tableName);
+            console.log(chalk.green(`  ✓ ${filePath}`));
+        }
+
+        // Generate index.ts (sorted alphabetically for deterministic output)
+        if (generatedFiles.length > 0) {
+            const indexPath = path.join(outDir, "index.ts");
+
+            if (fs.existsSync(indexPath) && !force) {
+                // Merge: read existing index, add new exports that don't already exist
+                const existing = fs.readFileSync(indexPath, "utf-8");
+                const merged = mergeIndexContent(existing, generatedFiles);
+                fs.writeFileSync(indexPath, merged, "utf-8");
+            } else {
+                const indexContent = generateIndexContent(generatedFiles);
+                fs.writeFileSync(indexPath, indexContent, "utf-8");
+            }
+            console.log(chalk.green(`  ✓ ${indexPath}`));
+        }
+
+        console.log("");
+        if (skippedFiles.length > 0) {
+            console.log(chalk.yellow(`⚠ Skipped ${skippedFiles.length} existing file(s): ${skippedFiles.join(", ")}`));
+            console.log(chalk.gray(`  Use --force to overwrite existing files.`));
+            console.log("");
+        }
+        console.log(chalk.bold.green(`✓ Introspected ${tablesMap.size} tables — generated ${generatedFiles.length} collection(s).`));
+        console.log(chalk.gray(`  Review the generated files in ${outDir} and customize properties as needed.`));
+        console.log("");
+
+    } catch (e) {
+        console.error(chalk.red(`✗ Error introspecting database: ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+    } finally {
+        await client.end();
+    }
+}
+
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/test/introspect-db-generation.test.ts

@@ -0,0 +1,436 @@
+import {
+    generateCollectionFile, buildTablesMap, buildEnumMap,
+    identifyJoinTables, TableRow, TableColumn, PrimaryKeyRow,
+    ForeignKeyRow, EnumValue, TableMeta,
+} from "../src/schema/introspect-db-logic";
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+const mkCol = (table: string, col: string, opts: Partial<TableColumn> = {}): TableColumn => ({
+    table_name: table, column_name: col, data_type: "character varying",
+    udt_name: "varchar", is_nullable: "YES", column_default: null, ...opts,
+});
+
+const mkFk = (table: string, col: string, fTable: string, fCol = "id"): ForeignKeyRow => ({
+    table_name: table, column_name: col, foreign_table_name: fTable, foreign_column_name: fCol,
+});
+
+function makeSimpleTable(name: string, columns: TableColumn[], pks: string[] = ["id"], fks: ForeignKeyRow[] = []): TableMeta {
+    return { name, columns, pks, fks };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// generateCollectionFile() — property generation
+// ═══════════════════════════════════════════════════════════════════════
+describe("generateCollectionFile", () => {
+    describe("basic property generation", () => {
+        it("generates a simple collection with slug, name, singularName and table", () => {
+            const meta = makeSimpleTable("products", [
+                mkCol("products", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("products", "name", { is_nullable: "NO" }),
+            ]);
+            const result = generateCollectionFile("products", meta, [], new Set(), new Map([["products", meta]]), new Map());
+            expect(result).toContain('slug: "products"');
+            expect(result).toContain('name: "Products"');
+            expect(result).toContain('singularName: "Product"');
+            expect(result).toContain('table: "products"');
+        });
+
+        it("generates correct property types from columns", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "count", { data_type: "integer", udt_name: "int4" }),
+                mkCol("items", "active", { data_type: "boolean", udt_name: "bool" }),
+                mkCol("items", "created_at", { data_type: "timestamp", udt_name: "timestamp" }),
+                mkCol("items", "metadata", { data_type: "jsonb", udt_name: "jsonb" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            expect(result).toContain('type: "string"');   // id
+            expect(result).toContain('type: "number"');
+            expect(result).toContain('type: "boolean"');
+            expect(result).toContain('type: "date"');
+            expect(result).toContain('type: "map"');
+        });
+
+        it("skips FK columns from properties (they become relations)", () => {
+            const fks = [mkFk("posts", "author_id", "users")];
+            const meta = makeSimpleTable("posts", [
+                mkCol("posts", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("posts", "title", { is_nullable: "NO" }),
+                mkCol("posts", "author_id", { is_nullable: "NO" }),
+            ], ["id"], fks);
+            const result = generateCollectionFile("posts", meta, fks, new Set(), new Map([["posts", meta]]), new Map());
+            // author_id should NOT appear as a regular property
+            expect(result).not.toMatch(/author_id:\s*\{[^}]*type:\s*"string"/);
+            // but author should appear as a relation
+            expect(result).toContain('type: "relation"');
+        });
+    });
+
+    describe("propertiesOrder correctness", () => {
+        it("includes relation property key, not FK column name", () => {
+            const fks = [mkFk("posts", "author_id", "users")];
+            const meta = makeSimpleTable("posts", [
+                mkCol("posts", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("posts", "title"),
+                mkCol("posts", "author_id"),
+            ], ["id"], fks);
+            const result = generateCollectionFile("posts", meta, fks, new Set(), new Map([["posts", meta]]), new Map());
+            // propertiesOrder should contain "author" (the relation key), not "author_id" (the FK column)
+            const orderMatch = result.match(/propertiesOrder:\s*(\[[\s\S]*?\])/);
+            expect(orderMatch).toBeTruthy();
+            const orderBlock = orderMatch![1];
+            expect(orderBlock).toContain('"author"');
+            // author_id should NOT appear in propertiesOrder (it may appear in localKey elsewhere)
+            expect(orderBlock).not.toContain('"author_id"');
+        });
+    });
+
+    describe("ID detection", () => {
+        it("marks uuid PK as isId uuid", () => {
+            const meta = makeSimpleTable("users", [
+                mkCol("users", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+            ]);
+            const result = generateCollectionFile("users", meta, [], new Set(), new Map([["users", meta]]), new Map());
+            expect(result).toContain('isId: "uuid"');
+        });
+
+        it("marks integer PK as isId increment", () => {
+            const meta = makeSimpleTable("counters", [
+                mkCol("counters", "id", { data_type: "integer", udt_name: "int4", is_nullable: "NO", column_default: "nextval" }),
+            ]);
+            const result = generateCollectionFile("counters", meta, [], new Set(), new Map([["counters", meta]]), new Map());
+            expect(result).toContain('isId: "increment"');
+        });
+
+        it("flags composite primary keys with a comment", () => {
+            const meta = makeSimpleTable("scores", [
+                mkCol("scores", "user_id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("scores", "game_id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("scores", "score", { data_type: "integer", udt_name: "int4" }),
+            ], ["user_id", "game_id"]);
+            const result = generateCollectionFile("scores", meta, [], new Set(), new Map([["scores", meta]]), new Map());
+            expect(result).toContain("composite primary key");
+            expect(result).toContain("user_id, game_id");
+        });
+    });
+
+    describe("validation.required", () => {
+        it("adds required when is_nullable is NO, not a PK, and no default", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "name", { is_nullable: "NO" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            // name should have required
+            expect(result).toContain("required: true");
+        });
+
+        it("does NOT add required for nullable columns", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "bio", { is_nullable: "YES" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            const bioSection = result.split("bio:")[1].split("},")[0];
+            expect(bioSection).not.toContain("required");
+        });
+
+        it("does NOT add required for columns with defaults", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "role", { is_nullable: "NO", column_default: "'user'" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            const roleSection = result.split("role:")[1].split("},")[0];
+            expect(roleSection).not.toContain("required");
+        });
+    });
+
+    describe("enum support", () => {
+        it("generates enumValues for USER-DEFINED columns with matching enum", () => {
+            const enumMap = new Map([["order_status", ["pending", "shipped", "delivered"]]]);
+            const meta = makeSimpleTable("orders", [
+                mkCol("orders", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("orders", "status", { data_type: "USER-DEFINED", udt_name: "order_status" }),
+            ]);
+            const result = generateCollectionFile("orders", meta, [], new Set(), new Map([["orders", meta]]), enumMap);
+            expect(result).toContain('enumValues:');
+            expect(result).toContain('{ id: "pending", label: "Pending" }');
+            expect(result).toContain('{ id: "shipped", label: "Shipped" }');
+            expect(result).toContain('{ id: "delivered", label: "Delivered" }');
+            expect(result).toContain('type: "string"');
+        });
+
+        it("does NOT add enumValues for USER-DEFINED without matching enum", () => {
+            const meta = makeSimpleTable("things", [
+                mkCol("things", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("things", "geom", { data_type: "USER-DEFINED", udt_name: "geometry" }),
+            ]);
+            const result = generateCollectionFile("things", meta, [], new Set(), new Map([["things", meta]]), new Map());
+            expect(result).not.toContain("enumValues");
+        });
+
+        it("humanizes enum value labels with underscores", () => {
+            const enumMap = new Map([["my_enum", ["in_progress", "on_hold"]]]);
+            const meta = makeSimpleTable("tasks", [
+                mkCol("tasks", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("tasks", "state", { data_type: "USER-DEFINED", udt_name: "my_enum" }),
+            ]);
+            const result = generateCollectionFile("tasks", meta, [], new Set(), new Map([["tasks", meta]]), enumMap);
+            expect(result).toContain('label: "In Progress"');
+            expect(result).toContain('label: "On Hold"');
+        });
+    });
+
+    describe("date auto-value heuristics", () => {
+        it("sets autoValue on_create for created_at", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "created_at", { data_type: "timestamp", udt_name: "timestamp" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            expect(result).toContain('autoValue: "on_create"');
+            expect(result).toContain("hideFromCollection: true");
+        });
+
+        it("sets autoValue on_update for updated_at", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "updated_at", { data_type: "timestamp", udt_name: "timestamp" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            expect(result).toContain('autoValue: "on_update"');
+        });
+
+        it("sets autoValue on_create for columns with now() default", () => {
+            const meta = makeSimpleTable("items", [
+                mkCol("items", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("items", "published_at", { data_type: "timestamp", udt_name: "timestamp", column_default: "now()" }),
+            ]);
+            const result = generateCollectionFile("items", meta, [], new Set(), new Map([["items", meta]]), new Map());
+            expect(result).toContain('autoValue: "on_create"');
+        });
+    });
+
+    describe("string sub-type heuristics", () => {
+        it("adds storage config for image-like column names", () => {
+            for (const name of ["profile_image", "avatar", "photo_url", "logo", "cover_image"]) {
+                const meta = makeSimpleTable("t", [
+                    mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                    mkCol("t", name),
+                ]);
+                const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), new Map());
+                expect(result).toContain("storagePath:");
+            }
+        });
+
+        it("adds multiline for description/summary/excerpt", () => {
+            for (const name of ["description", "summary", "excerpt"]) {
+                const meta = makeSimpleTable("t", [
+                    mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                    mkCol("t", name),
+                ]);
+                const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), new Map());
+                expect(result).toContain("multiline: true");
+            }
+        });
+
+        it("adds markdown for content/body", () => {
+            for (const name of ["content", "body"]) {
+                const meta = makeSimpleTable("t", [
+                    mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                    mkCol("t", name),
+                ]);
+                const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), new Map());
+                expect(result).toContain("markdown: true");
+            }
+        });
+
+        it("adds multiline for text data_type columns", () => {
+            const meta = makeSimpleTable("t", [
+                mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("t", "notes", { data_type: "text", udt_name: "text" }),
+            ]);
+            const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), new Map());
+            expect(result).toContain("multiline: true");
+        });
+
+        it("does NOT apply string heuristics to enum columns", () => {
+            const enumMap = new Map([["img_type", ["png", "jpg"]]]);
+            const meta = makeSimpleTable("t", [
+                mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("t", "image_type", { data_type: "USER-DEFINED", udt_name: "img_type" }),
+            ]);
+            const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), enumMap);
+            expect(result).not.toContain("storagePath");
+            expect(result).toContain("enumValues");
+        });
+    });
+
+    describe("owning relation (FK -> other table)", () => {
+        it("generates a one-to-one owning relation with correct import", () => {
+            const fks = [mkFk("posts", "author_id", "users")];
+            const meta = makeSimpleTable("posts", [
+                mkCol("posts", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("posts", "author_id"),
+            ], ["id"], fks);
+            const result = generateCollectionFile("posts", meta, fks, new Set(), new Map([["posts", meta]]), new Map());
+            expect(result).toContain('import usersCollection from "./users"');
+            expect(result).toContain('author: {');
+            expect(result).toContain('cardinality: "one"');
+            expect(result).toContain('direction: "owning"');
+            expect(result).toContain('localKey: "author_id"');
+        });
+    });
+
+    describe("inverse relation (other table -> this table)", () => {
+        it("generates a one-to-many inverse relation", () => {
+            const allFks: ForeignKeyRow[] = [mkFk("comments", "post_id", "posts")];
+            const meta = makeSimpleTable("posts", [
+                mkCol("posts", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+            ]);
+            const result = generateCollectionFile("posts", meta, allFks, new Set(), new Map([["posts", meta]]), new Map());
+            expect(result).toContain('import commentsCollection from "./comments"');
+            expect(result).toContain('cardinality: "many"');
+            expect(result).toContain('direction: "inverse"');
+            expect(result).toContain('inverseRelationName: "post"');
+            expect(result).toContain('foreignKeyOnTarget: "post_id"');
+        });
+    });
+
+    describe("many-to-many relations", () => {
+        it("generates owning M2M with through config for alphabetically-first table", () => {
+            const jtFks: ForeignKeyRow[] = [
+                mkFk("articles_tags", "article_id", "articles"),
+                mkFk("articles_tags", "tag_id", "tags"),
+            ];
+            const jtMeta: TableMeta = {
+                name: "articles_tags", pks: [],
+                columns: [mkCol("articles_tags", "article_id"), mkCol("articles_tags", "tag_id")],
+                fks: jtFks,
+            };
+            const articlesMeta = makeSimpleTable("articles", [
+                mkCol("articles", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+            ]);
+            const tablesMap = new Map([["articles", articlesMeta], ["articles_tags", jtMeta]]);
+            const joinTables = new Set(["articles_tags"]);
+
+            const result = generateCollectionFile("articles", articlesMeta, [], joinTables, tablesMap, new Map());
+            expect(result).toContain('direction: "owning"');
+            expect(result).toContain('table: "articles_tags"');
+            expect(result).toContain('sourceColumn: "article_id"');
+            expect(result).toContain('targetColumn: "tag_id"');
+        });
+
+        it("generates inverse M2M for alphabetically-second table", () => {
+            const jtFks: ForeignKeyRow[] = [
+                mkFk("articles_tags", "article_id", "articles"),
+                mkFk("articles_tags", "tag_id", "tags"),
+            ];
+            const jtMeta: TableMeta = {
+                name: "articles_tags", pks: [],
+                columns: [mkCol("articles_tags", "article_id"), mkCol("articles_tags", "tag_id")],
+                fks: jtFks,
+            };
+            const tagsMeta = makeSimpleTable("tags", [
+                mkCol("tags", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+            ]);
+            const tablesMap = new Map([["tags", tagsMeta], ["articles_tags", jtMeta]]);
+            const joinTables = new Set(["articles_tags"]);
+
+            const result = generateCollectionFile("tags", tagsMeta, [], joinTables, tablesMap, new Map());
+            expect(result).toContain('direction: "inverse"');
+        });
+    });
+
+    describe("self-referencing M2M", () => {
+        it("generates self-ref M2M with _via_ property name", () => {
+            const jtFks: ForeignKeyRow[] = [
+                mkFk("user_friends", "user_id", "users"),
+                mkFk("user_friends", "friend_id", "users"),
+            ];
+            const jtMeta: TableMeta = {
+                name: "user_friends", pks: [],
+                columns: [mkCol("user_friends", "user_id"), mkCol("user_friends", "friend_id")],
+                fks: jtFks,
+            };
+            const usersMeta = makeSimpleTable("users", [
+                mkCol("users", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+            ]);
+            const tablesMap = new Map([["users", usersMeta], ["user_friends", jtMeta]]);
+            const joinTables = new Set(["user_friends"]);
+
+            const result = generateCollectionFile("users", usersMeta, [], joinTables, tablesMap, new Map());
+            expect(result).toContain("users_via_friend");
+            expect(result).toContain('table: "user_friends"');
+            expect(result).toContain('sourceColumn: "user_id"');
+            expect(result).toContain('targetColumn: "friend_id"');
+            // Self-ref should reference its own collection variable
+            expect(result).toContain("usersCollection");
+        });
+    });
+
+    describe("icon mapping", () => {
+        it("assigns correct icons based on table name", () => {
+            const make = (name: string) => {
+                const meta = makeSimpleTable(name, [mkCol(name, "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" })]);
+                return generateCollectionFile(name, meta, [], new Set(), new Map([[name, meta]]), new Map());
+            };
+            expect(make("users")).toContain('icon: "Users"');
+            expect(make("blog_posts")).toContain('icon: "FileText"');
+            expect(make("products")).toContain('icon: "Package"');
+            expect(make("orders")).toContain('icon: "ShoppingCart"');
+            expect(make("app_settings")).toContain('icon: "Settings"');
+            expect(make("random_xyz")).toContain('icon: "Database"');
+        });
+    });
+
+    describe("humanized names", () => {
+        it("uses Title Case for collection name from snake_case table", () => {
+            const meta = makeSimpleTable("user_profiles", [
+                mkCol("user_profiles", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+            ]);
+            const result = generateCollectionFile("user_profiles", meta, [], new Set(), new Map([["user_profiles", meta]]), new Map());
+            expect(result).toContain('name: "User Profiles"');
+            expect(result).toContain('singularName: "User Profile"');
+        });
+
+        it("humanizes property names", () => {
+            const meta = makeSimpleTable("t", [
+                mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("t", "first_name"),
+            ]);
+            const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), new Map());
+            expect(result).toContain('name: "First Name"');
+        });
+    });
+
+    describe("import generation", () => {
+        it("always imports PostgresCollection", () => {
+            const meta = makeSimpleTable("t", [mkCol("t", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" })]);
+            const result = generateCollectionFile("t", meta, [], new Set(), new Map([["t", meta]]), new Map());
+            expect(result).toContain('import { PostgresCollection } from "@rebasepro/types"');
+        });
+
+        it("does not duplicate imports for multiple relations to same table", () => {
+            const fks = [mkFk("posts", "author_id", "users"), mkFk("posts", "reviewer_id", "users")];
+            const meta = makeSimpleTable("posts", [
+                mkCol("posts", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" }),
+                mkCol("posts", "author_id"),
+                mkCol("posts", "reviewer_id"),
+            ], ["id"], fks);
+            const result = generateCollectionFile("posts", meta, fks, new Set(), new Map([["posts", meta]]), new Map());
+            const importMatches = result.match(/import usersCollection/g);
+            expect(importMatches).toHaveLength(1);
+        });
+    });
+
+    describe("export default", () => {
+        it("exports the collection variable as default", () => {
+            const meta = makeSimpleTable("orders", [mkCol("orders", "id", { data_type: "uuid", udt_name: "uuid", is_nullable: "NO" })]);
+            const result = generateCollectionFile("orders", meta, [], new Set(), new Map([["orders", meta]]), new Map());
+            expect(result).toContain("export default ordersCollection;");
+        });
+    });
+});