@cosmicdrift/kumiko-framework 0.1.0

package/src/db/__tests__/row-helpers.test.ts

@@ -0,0 +1,59 @@
+import type { SQL } from "drizzle-orm";
+import { describe, expect, test, vi } from "vitest";
+import { fetchOne } from "../row-helpers";
+
+// Drizzle builder chain mocked structurally — fetchOne only calls
+// db.select().from(table).where(where).limit(1) and reads the first row.
+function makeFakeDb(rows: unknown[]) {
+  const limit = vi.fn().mockResolvedValue(rows);
+  const where = vi.fn(() => ({ limit }));
+  const from = vi.fn(() => ({ where }));
+  const select = vi.fn(() => ({ from }));
+  // biome-ignore lint/suspicious/noExplicitAny: test shim — we never feed this to a real DbRunner type check.
+  return { db: { select } as any, select, from, where, limit };
+}
+
+const fakeTable = {} as never;
+const fakeCond1 = { __c: 1 } as unknown as SQL;
+const fakeCond2 = { __c: 2 } as unknown as SQL;
+
+describe("fetchOne", () => {
+  test("returns the first row when the query yields at least one match", async () => {
+    const { db } = makeFakeDb([
+      { id: 1, name: "alice" },
+      { id: 2, name: "bob" },
+    ]);
+    const row = await fetchOne<{ id: number; name: string }>(db, fakeTable, fakeCond1);
+    expect(row).toEqual({ id: 1, name: "alice" });
+  });
+
+  test("returns undefined on an empty result", async () => {
+    const { db } = makeFakeDb([]);
+    const row = await fetchOne(db, fakeTable, fakeCond1);
+    expect(row).toBeUndefined();
+  });
+
+  test("applies limit(1) — no need to pull the whole table", async () => {
+    const { db, limit } = makeFakeDb([]);
+    await fetchOne(db, fakeTable, fakeCond1);
+    expect(limit).toHaveBeenCalledWith(1);
+  });
+
+  test("passes the single condition directly to .where (no AND wrapping)", async () => {
+    const { db, where } = makeFakeDb([]);
+    await fetchOne(db, fakeTable, fakeCond1);
+    expect(where).toHaveBeenCalledWith(fakeCond1);
+  });
+
+  test("combines multiple conditions with AND", async () => {
+    const { db, where } = makeFakeDb([]);
+    await fetchOne(db, fakeTable, fakeCond1, fakeCond2);
+    const calls = where.mock.calls as unknown as readonly (readonly unknown[])[];
+    const arg = calls[0]?.[0];
+    // drizzle's and() returns an SQL expression — we can't cheaply inspect
+    // its innards, but it must not be the raw first condition and must be
+    // defined (i.e. the helper actually composed something).
+    expect(arg).toBeDefined();
+    expect(arg).not.toBe(fakeCond1);
+  });
+});

package/src/db/__tests__/schema-migration.integration.ts

@@ -0,0 +1,273 @@
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import {
+  createBooleanField,
+  createDateField,
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+} from "../../engine";
+import type { FeatureDefinition } from "../../engine/types";
+import { createTestDb, pushTables, type TestDb } from "../../stack";
+import { buildDrizzleTable } from "../table-builder";
+
+/**
+ * Integration tests for the schema migration workflow.
+ * Tests real developer scenarios: new feature, add field, change field, etc.
+ *
+ * Each test simulates:
+ *   1. Developer defines/changes entities
+ *   2. buildDrizzleTable creates Drizzle table objects
+ *   3. Schema is applied to a real database via pushTables (drizzle-kit push)
+ *   4. We verify the DB state matches expectations
+ */
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+});
+
+afterAll(async () => {
+  await testDb?.cleanup();
+});
+
+// Helper: apply schema by building Drizzle tables and pushing via drizzle-kit
+async function applySchema(features: readonly FeatureDefinition[]): Promise<void> {
+  const tables: Record<string, unknown> = {};
+  for (const feature of features) {
+    for (const [entityName, entity] of Object.entries(feature.entities)) {
+      tables[entityName] = buildDrizzleTable(entityName, entity);
+    }
+  }
+  await pushTables(testDb.db, tables);
+}
+
+// Helper: read column info from information_schema
+async function getTableColumns(
+  tableName: string,
+): Promise<Map<string, { dataType: string; isNullable: boolean }>> {
+  const rows = await testDb.db.execute<{
+    column_name: string;
+    data_type: string;
+    is_nullable: string;
+  }>(
+    sql`SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = ${tableName} ORDER BY ordinal_position`,
+  );
+
+  const result = new Map<string, { dataType: string; isNullable: boolean }>();
+  for (const row of rows) {
+    result.set(row.column_name, {
+      dataType: row.data_type,
+      isNullable: row.is_nullable === "YES",
+    });
+  }
+  return result;
+}
+
+describe("schema migration workflows", () => {
+  test("workflow 1: new feature creates table with all base + field columns", async () => {
+    const feature = defineFeature("blog", (r) => {
+      r.entity(
+        "post",
+        createEntity({
+          table: "wf1_posts",
+          fields: {
+            title: createTextField({ required: true }),
+            body: createTextField(),
+            viewCount: createNumberField(),
+            publishedAt: createDateField(),
+            isDraft: createBooleanField({ default: true }),
+          },
+        }),
+      );
+    });
+
+    await applySchema([feature]);
+
+    const columns = await getTableColumns("wf1_posts");
+
+    // Base columns
+    expect(columns.has("id")).toBe(true);
+    expect(columns.has("tenant_id")).toBe(true);
+    expect(columns.has("version")).toBe(true);
+    expect(columns.has("inserted_at")).toBe(true);
+    expect(columns.has("modified_at")).toBe(true);
+    expect(columns.has("inserted_by_id")).toBe(true);
+    expect(columns.has("modified_by_id")).toBe(true);
+
+    // Entity fields
+    expect(columns.get("title")?.dataType).toBe("text");
+    expect(columns.get("body")?.dataType).toBe("text");
+    expect(columns.get("view_count")?.dataType).toBe("integer");
+    expect(columns.get("published_at")?.dataType).toContain("timestamp");
+    expect(columns.get("is_draft")?.dataType).toBe("boolean");
+    expect(columns.get("is_draft")?.isNullable).toBe(false); // has default → NOT NULL
+
+    // No soft delete
+    expect(columns.has("is_deleted")).toBe(false);
+  });
+
+  test("workflow 1b: tenant_id index is created on every table", async () => {
+    const feature = defineFeature("indexed-blog", (r) => {
+      r.entity(
+        "article",
+        createEntity({
+          table: "wf1b_articles",
+          fields: { title: createTextField() },
+        }),
+      );
+    });
+    await applySchema([feature]);
+
+    const indexRows = await testDb.db.execute<{ indexname: string; indexdef: string }>(
+      sql.raw(
+        `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'wf1b_articles' AND indexname = 'wf1b_articles_tenant_id_idx'`,
+      ),
+    );
+    expect(indexRows.length).toBe(1);
+    expect(indexRows[0]?.indexdef).toContain("tenant_id");
+  });
+
+  test("workflow 2: add field to existing entity → ADD COLUMN", async () => {
+    // Initial entity with just email
+    const initialEntity = createEntity({
+      table: "wf2_users",
+      fields: { email: createTextField() },
+    });
+    await pushTables(testDb.db, { user: buildDrizzleTable("user", initialEntity) });
+
+    // Developer adds a new field
+    const updatedEntity = createEntity({
+      table: "wf2_users",
+      fields: {
+        email: createTextField(),
+        displayName: createTextField(), // NEW FIELD
+      },
+    });
+
+    // Push updated schema — drizzle-kit generates ALTER TABLE ADD COLUMN
+    await pushTables(
+      testDb.db,
+      { user: buildDrizzleTable("user", updatedEntity) },
+      { user: buildDrizzleTable("user", initialEntity) },
+    );
+
+    const columns = await getTableColumns("wf2_users");
+    expect(columns.has("display_name")).toBe(true);
+    expect(columns.has("email")).toBe(true);
+    expect(columns.get("display_name")?.dataType).toBe("text");
+  });
+
+  test("workflow 3: add required boolean field with default → safe ADD COLUMN", async () => {
+    // Initial entity with just name
+    const initialEntity = createEntity({
+      table: "wf3_projects",
+      fields: { name: createTextField() },
+    });
+    const initialTable = buildDrizzleTable("project", initialEntity);
+    await pushTables(testDb.db, { project: initialTable });
+
+    // Insert a row first (to prove ADD COLUMN with default doesn't break existing rows)
+    await testDb.db
+      .insert(initialTable)
+      .values({ tenantId: "00000000-0000-4000-8000-000000000001", name: "Test Project" });
+
+    // Developer adds boolean field with default
+    const updatedEntity = createEntity({
+      table: "wf3_projects",
+      fields: { name: createTextField(), isArchived: createBooleanField({ default: false }) },
+    });
+    const updatedTable = buildDrizzleTable("project", updatedEntity);
+    await pushTables(testDb.db, { project: updatedTable }, { project: initialTable });
+
+    // Existing row should have the default value
+    const rows = await testDb.db.select().from(updatedTable);
+
+    expect(rows[0]).toMatchObject({ name: "Test Project", isArchived: false });
+  });
+
+  test("workflow 3b: text field with default → DEFAULT-clause backfills existing rows", async () => {
+    // Pinned der text-default-bug: `createTextField({ default: "..." })`
+    // muss die DEFAULT-Klausel ins generierte SQL durchreichen, sonst
+    // bricht ALTER TABLE ADD COLUMN auf existing data (NOT NULL ohne
+    // DEFAULT failt). Vorher hat der text-Branch in table-builder das
+    // `field.default` ignoriert; dieser Test pinst dass es jetzt
+    // greift.
+    const initialEntity = createEntity({
+      table: "wf3b_users",
+      fields: { email: createTextField({ required: true }) },
+    });
+    const initialTable = buildDrizzleTable("user", initialEntity);
+    await pushTables(testDb.db, { user: initialTable });
+
+    await testDb.db
+      .insert(initialTable)
+      .values({ tenantId: "00000000-0000-4000-8000-000000000001", email: "x@y.z" });
+
+    const updatedEntity = createEntity({
+      table: "wf3b_users",
+      fields: {
+        email: createTextField({ required: true }),
+        roles: createTextField({ required: true, default: "[]" }),
+      },
+    });
+    const updatedTable = buildDrizzleTable("user", updatedEntity);
+    await pushTables(testDb.db, { user: updatedTable }, { user: initialTable });
+
+    const rows = await testDb.db.select().from(updatedTable);
+    expect(rows[0]).toMatchObject({ email: "x@y.z", roles: "[]" });
+  });
+
+  test("workflow 4: activate soft delete → adds 3 columns", async () => {
+    const feature = defineFeature("tasks", (r) => {
+      r.entity(
+        "task",
+        createEntity({
+          table: "wf4_tasks",
+          fields: { title: createTextField() },
+          softDelete: true,
+        }),
+      );
+    });
+
+    await applySchema([feature]);
+
+    const columns = await getTableColumns("wf4_tasks");
+
+    expect(columns.has("is_deleted")).toBe(true);
+    expect(columns.get("is_deleted")?.isNullable).toBe(false);
+    expect(columns.has("deleted_at")).toBe(true);
+    expect(columns.get("deleted_at")?.isNullable).toBe(true);
+    expect(columns.has("deleted_by_id")).toBe(true);
+  });
+
+  test("workflow 5: multiple features each create their own tables", async () => {
+    const blogFeature = defineFeature("blog", (r) => {
+      r.entity(
+        "article",
+        createEntity({ table: "wf5_articles", fields: { title: createTextField() } }),
+      );
+    });
+
+    const shopFeature = defineFeature("shop", (r) => {
+      r.entity(
+        "product",
+        createEntity({
+          table: "wf5_products",
+          fields: { name: createTextField(), price: createNumberField() },
+        }),
+      );
+    });
+
+    await applySchema([blogFeature, shopFeature]);
+
+    const articleColumns = await getTableColumns("wf5_articles");
+    const productColumns = await getTableColumns("wf5_products");
+
+    expect(articleColumns.has("title")).toBe(true);
+    expect(productColumns.has("name")).toBe(true);
+    expect(productColumns.has("price")).toBe(true);
+  });
+});

package/src/db/__tests__/table-builder-indexes.test.ts

@@ -0,0 +1,153 @@
+// Unit-Tests für entity.indexes — Composite-/Unique-Index-API.
+//
+// Vorher mussten Apps für unique-indices über mehrere Spalten daneben eine
+// hand-written pgTable-Definition halten — Single-Source-of-Truth gebrochen,
+// Schema-Drift programmiert. Mit entity.indexes pflegen Author die
+// Constraint deklarativ in der EntityDefinition; buildDrizzleTable rendert
+// sie via uniqueIndex/index.
+
+import { getTableConfig } from "drizzle-orm/pg-core";
+import { describe, expect, test } from "vitest";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineFeature,
+  validateBoot,
+} from "../../engine";
+import { buildDrizzleTable } from "../table-builder";
+
+describe("buildDrizzleTable — entity.indexes", () => {
+  test("composite unique-index landet als unique=true in Drizzle table-config", () => {
+    const entity = createEntity({
+      fields: {
+        key: createTextField({ required: true }),
+        userId: createTextField({}),
+      },
+      indexes: [{ unique: true, columns: ["key", "tenantId", "userId"] }],
+    });
+    const tbl = buildDrizzleTable("config-value", entity);
+    const { indexes } = getTableConfig(tbl);
+    const composite = indexes.find(
+      (i) => i.config.name === "read_config_values_key_tenant_id_user_id_unique",
+    );
+    expect(composite).toBeDefined();
+    expect(composite?.config.unique).toBe(true);
+    expect(composite?.config.columns.map((c) => (c as { name: string }).name)).toEqual([
+      "key",
+      "tenant_id",
+      "user_id",
+    ]);
+  });
+
+  test("composite non-unique-index landet als unique=false in Drizzle table-config", () => {
+    const entity = createEntity({
+      fields: {
+        startedAt: createTextField({}),
+        endedAt: createTextField({}),
+      },
+      indexes: [{ columns: ["startedAt", "endedAt"] }],
+    });
+    const tbl = buildDrizzleTable("session", entity);
+    const { indexes } = getTableConfig(tbl);
+    const composite = indexes.find(
+      (i) => i.config.name === "read_sessions_started_at_ended_at_idx",
+    );
+    expect(composite).toBeDefined();
+    expect(composite?.config.unique).toBe(false);
+  });
+
+  test("custom name override wird respektiert", () => {
+    const entity = createEntity({
+      fields: { slug: createTextField({ required: true }) },
+      indexes: [{ unique: true, columns: ["slug"], name: "my_custom_idx" }],
+    });
+    const tbl = buildDrizzleTable("page", entity);
+    const { indexes } = getTableConfig(tbl);
+    const idx = indexes.find((i) => i.config.name === "my_custom_idx");
+    expect(idx).toBeDefined();
+    expect(idx?.config.unique).toBe(true);
+  });
+
+  test("ohne indexes — keine zusätzlichen Indices, kein Error", () => {
+    const entity = createEntity({
+      fields: {
+        title: createTextField({}),
+      },
+    });
+    expect(() => buildDrizzleTable("widget", entity)).not.toThrow();
+  });
+
+  test("Spalten die keine DB-Spalte haben (multi-files) werden via Boot-Validator gecatched", () => {
+    // buildDrizzleTable selbst überspringt fehlende Columns silently —
+    // der Boot-Validator wirft.
+    const entity = createEntity({
+      fields: {
+        attachments: { type: "files" } as never,
+      },
+      indexes: [{ columns: ["attachments"] }],
+    });
+    // No throw at build time.
+    expect(() => buildDrizzleTable("widget", entity)).not.toThrow();
+    // But validateBoot does.
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", entity);
+    });
+    expect(() => validateBoot([feature])).toThrow(/multi-value field/);
+  });
+});
+
+describe("validateBoot — entity.indexes", () => {
+  test("Tippfehler im column-Namen wirft", () => {
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: { title: createTextField({}) },
+        indexes: [{ columns: ["titel"] }], // typo
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/does not match any field/);
+  });
+
+  test("leere column-Liste wirft", () => {
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: { title: createTextField({}) },
+        indexes: [{ columns: [] as never }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/empty columns list/);
+  });
+
+  test("single-column index nur auf tenantId ist redundant", () => {
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: { title: createTextField({}) },
+        indexes: [{ columns: ["tenantId"] }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/redundant/);
+  });
+
+  test("composite mit tenantId ist OK (z.B. für unique über 3 Cols)", () => {
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: {
+          key: createTextField({ required: true }),
+          archived: createBooleanField({}),
+        },
+        indexes: [{ unique: true, columns: ["key", "tenantId"] }],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("base columns (id, tenantId, version) sind erlaubt", () => {
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: { key: createTextField({}) },
+        indexes: [{ columns: ["tenantId", "version"] }],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});