@cosmicdrift/kumiko-framework 0.1.0

package/src/logging/__tests__/pino-trace-bridge.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { createConsoleProvider } from "../../observability";
+import { mergeTraceFields } from "../pino-logger";
+
+// The Pino trace-bridge hook is verified by directly exercising the helper
+// that wrapPino uses. Going through pino's JSON output is flaky because
+// pino buffers/async-writes; the helper is the actual contract, and the
+// fact that wrapPino calls it on every log method is visible by inspection.
+
+describe("mergeTraceFields", () => {
+  it("adds traceId/spanId when an active span exists", async () => {
+    const provider = createConsoleProvider({ writer: { log: () => {} } });
+    let captured: Record<string, unknown> | undefined;
+    await provider.tracer.withSpan("http.request", async () => {
+      captured = mergeTraceFields({ user: "bob" });
+    });
+    expect(captured).toMatchObject({
+      user: "bob",
+      traceId: expect.stringMatching(/^[0-9a-f]{32}$/),
+      spanId: expect.stringMatching(/^[0-9a-f]{16}$/),
+    });
+  });
+
+  it("returns data unchanged when no active span", () => {
+    const result = mergeTraceFields({ foo: "bar" });
+    expect(result).toEqual({ foo: "bar" });
+  });
+
+  it("returns undefined when neither span nor data", () => {
+    expect(mergeTraceFields(undefined)).toBeUndefined();
+  });
+
+  it("caller data overrides trace fields when conflicting", async () => {
+    const provider = createConsoleProvider({ writer: { log: () => {} } });
+    let captured: Record<string, unknown> | undefined;
+    await provider.tracer.withSpan("x", async () => {
+      captured = mergeTraceFields({ traceId: "override" });
+    });
+    expect(captured?.["traceId"]).toBe("override");
+  });
+
+  it("returns just trace fields when data is undefined and span is active", async () => {
+    const provider = createConsoleProvider({ writer: { log: () => {} } });
+    let captured: Record<string, unknown> | undefined;
+    await provider.tracer.withSpan("y", async () => {
+      captured = mergeTraceFields(undefined);
+    });
+    expect(Object.keys(captured ?? {}).sort()).toEqual(["spanId", "traceId"]);
+  });
+});

package/src/logging/index.ts

@@ -0,0 +1,3 @@
+export type { LoggerOptions } from "./pino-logger";
+export { createLogger } from "./pino-logger";
+export type { Logger } from "./types";

package/src/logging/pino-logger.ts

@@ -0,0 +1,64 @@
+import pino, { type DestinationStream } from "pino";
+import { observabilityContext } from "../observability";
+import type { Logger } from "./types";
+
+export type LoggerOptions = {
+  level?: "debug" | "info" | "warn" | "error";
+  pretty?: boolean;
+  // Optional custom sink — pino writes NDJSON to it instead of stdout. Used
+  // in tests that need to capture and parse log output.
+  destination?: DestinationStream;
+};
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const level = options.level ?? (process.env["LOG_LEVEL"] as LoggerOptions["level"]) ?? "info";
+  const pretty = options.pretty ?? process.env["LOG_FORMAT"] === "pretty";
+
+  const pinoConfig = {
+    level,
+    ...(pretty && !options.destination
+      ? { transport: { target: "pino-pretty", options: { colorize: true } } }
+      : {}),
+  };
+  const pinoLogger = options.destination ? pino(pinoConfig, options.destination) : pino(pinoConfig);
+
+  return wrapPino(pinoLogger);
+}
+
+// Pull traceId/spanId from the active observability context so every log
+// line carries them when tracing is active. Empty IDs (NoopProvider) skip —
+// nothing to correlate, no need to clutter output. Trace fields don't
+// overwrite caller-provided data so explicit overrides still win. Exported
+// for unit tests.
+export function mergeTraceFields(
+  data: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  const span = observabilityContext.getActiveSpan();
+  if (!span?.traceId) return data;
+  const traceFields = { traceId: span.traceId, spanId: span.spanId };
+  return data ? { ...traceFields, ...data } : traceFields;
+}
+
+function wrapPino(p: pino.Logger): Logger {
+  return {
+    info(msg, data) {
+      const merged = mergeTraceFields(data);
+      merged ? p.info(merged, msg) : p.info(msg);
+    },
+    warn(msg, data) {
+      const merged = mergeTraceFields(data);
+      merged ? p.warn(merged, msg) : p.warn(msg);
+    },
+    error(msg, data) {
+      const merged = mergeTraceFields(data);
+      merged ? p.error(merged, msg) : p.error(msg);
+    },
+    debug(msg, data) {
+      const merged = mergeTraceFields(data);
+      merged ? p.debug(merged, msg) : p.debug(msg);
+    },
+    child(context) {
+      return wrapPino(p.child(context));
+    },
+  };
+}

package/src/logging/types.ts

@@ -0,0 +1,7 @@
+export type Logger = {
+  info(msg: string, data?: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
+  error(msg: string, data?: Record<string, unknown>): void;
+  debug(msg: string, data?: Record<string, unknown>): void;
+  child(context: Record<string, unknown>): Logger;
+};

package/src/migrations/__tests__/compare-snapshots.test.ts

@@ -0,0 +1,150 @@
+// Unit-Tests für compareSnapshots — der Diff-Algorithmus zwischen zwei
+// Drizzle-Snapshots. Production-Behavior: bei Schema-Drift einer
+// Projection-Tabelle muss der Detector die richtigen Tabellen-Namen
+// melden, damit migrate apply den richtigen Rebuild triggert.
+
+import { describe, expect, test } from "vitest";
+import { compareSnapshots } from "../projection-detection";
+import type { Snapshot, SnapshotTable } from "../schema-drift";
+
+function snapshot(tables: Record<string, Partial<SnapshotTable>>): Snapshot {
+  const out: Record<string, SnapshotTable> = {};
+  for (const [key, partial] of Object.entries(tables)) {
+    out[key] = {
+      schema: partial.schema ?? "",
+      name: partial.name ?? key.replace(/^public\./, ""),
+      columns: partial.columns ?? {},
+    };
+  }
+  return { tables: out };
+}
+
+const userTable: SnapshotTable = {
+  schema: "",
+  name: "users",
+  columns: {
+    id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+    email: { name: "email", type: "text", notNull: true },
+  },
+};
+
+describe("compareSnapshots", () => {
+  test("prev=null → all current tables marked as added", () => {
+    const current = snapshot({ "public.users": userTable });
+    const changes = compareSnapshots(null, current);
+    expect(changes).toHaveLength(1);
+    expect(changes[0]).toMatchObject({ tableName: "users", kind: "added" });
+  });
+
+  test("identical snapshots → no changes", () => {
+    const s = snapshot({ "public.users": userTable });
+    expect(compareSnapshots(s, s)).toHaveLength(0);
+  });
+
+  test("table appears in current → kind=added", () => {
+    const prev = snapshot({});
+    const current = snapshot({ "public.users": userTable });
+    const changes = compareSnapshots(prev, current);
+    expect(changes).toEqual([{ fullName: "users", tableName: "users", kind: "added" }]);
+  });
+
+  test("table missing in current → kind=removed", () => {
+    const prev = snapshot({ "public.users": userTable });
+    const current = snapshot({});
+    const changes = compareSnapshots(prev, current);
+    expect(changes).toEqual([{ fullName: "users", tableName: "users", kind: "removed" }]);
+  });
+
+  test("column added → kind=modified", () => {
+    const prev = snapshot({ "public.users": userTable });
+    const current = snapshot({
+      "public.users": {
+        ...userTable,
+        columns: { ...userTable.columns, name: { name: "name", type: "text" } },
+      },
+    });
+    const changes = compareSnapshots(prev, current);
+    expect(changes).toEqual([{ fullName: "users", tableName: "users", kind: "modified" }]);
+  });
+
+  test("column type changed → kind=modified", () => {
+    const prev = snapshot({ "public.users": userTable });
+    const current = snapshot({
+      "public.users": {
+        ...userTable,
+        columns: {
+          ...userTable.columns,
+          email: { name: "email", type: "varchar(255)", notNull: true },
+        },
+      },
+    });
+    expect(compareSnapshots(prev, current)).toEqual([
+      { fullName: "users", tableName: "users", kind: "modified" },
+    ]);
+  });
+
+  test("notNull flipped → kind=modified", () => {
+    const prev = snapshot({ "public.users": userTable });
+    const current = snapshot({
+      "public.users": {
+        ...userTable,
+        columns: { ...userTable.columns, email: { name: "email", type: "text", notNull: false } },
+      },
+    });
+    expect(compareSnapshots(prev, current)).toEqual([
+      { fullName: "users", tableName: "users", kind: "modified" },
+    ]);
+  });
+
+  test("default value changed → kind=modified", () => {
+    const prev = snapshot({
+      "public.users": {
+        ...userTable,
+        columns: {
+          ...userTable.columns,
+          status: { name: "status", type: "text", default: "'active'" },
+        },
+      },
+    });
+    const current = snapshot({
+      "public.users": {
+        ...userTable,
+        columns: {
+          ...userTable.columns,
+          status: { name: "status", type: "text", default: "'pending'" },
+        },
+      },
+    });
+    expect(compareSnapshots(prev, current)).toEqual([
+      { fullName: "users", tableName: "users", kind: "modified" },
+    ]);
+  });
+
+  test("schema-prefix in fullName when set", () => {
+    const prev = snapshot({});
+    const current = snapshot({
+      "auth.users": { ...userTable, schema: "auth" },
+    });
+    const changes = compareSnapshots(prev, current);
+    expect(changes[0]?.fullName).toBe("auth.users");
+  });
+
+  test("multiple changes preserved with stable kind classification", () => {
+    const tableA: SnapshotTable = { ...userTable, name: "a" };
+    const tableB: SnapshotTable = { ...userTable, name: "b" };
+    const tableC: SnapshotTable = { ...userTable, name: "c" };
+    const prev = snapshot({
+      "public.a": tableA,
+      "public.b": tableB,
+    });
+    const current = snapshot({
+      "public.a": tableA, // unchanged
+      "public.c": tableC, // added
+      // b removed
+    });
+    const changes = compareSnapshots(prev, current);
+    expect(changes).toHaveLength(2);
+    expect(changes.find((c) => c.tableName === "c")?.kind).toBe("added");
+    expect(changes.find((c) => c.tableName === "b")?.kind).toBe("removed");
+  });
+});

package/src/migrations/__tests__/detect-drift.integration.ts

@@ -0,0 +1,320 @@
+// Integration-Test für detectDrift — vergleicht Journal vs.
+// __drizzle_migrations und expected-Tables vs. Reality. Production-
+// Behavior: assertSchemaCurrent ist der Boot-Gate, jeder False-Positive
+// hier blockiert Container-Starts; jeder False-Negative lässt
+// Schema-Drift unentdeckt durch.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sql } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createTestDb, type TestDb } from "../../stack";
+import { detectDrift } from "../schema-drift";
+
+let testDb: TestDb;
+let migrationsDir: string;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(() => {
+  migrationsDir = mkdtempSync(join(tmpdir(), "kumiko-drift-"));
+  mkdirSync(join(migrationsDir, "meta"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(migrationsDir, { recursive: true, force: true });
+});
+
+function writeJournal(entries: { idx: number; tag: string }[]): void {
+  const journal = {
+    version: "7",
+    dialect: "postgresql",
+    entries: entries.map((e) => ({
+      idx: e.idx,
+      version: "7",
+      when: 1700000000000 + e.idx,
+      tag: e.tag,
+      breakpoints: true,
+    })),
+  };
+  writeFileSync(join(migrationsDir, "meta/_journal.json"), JSON.stringify(journal));
+}
+
+type SnapshotColumn = {
+  readonly name: string;
+  readonly type: string;
+  readonly primaryKey?: boolean;
+  readonly notNull?: boolean;
+};
+
+function writeSnapshot(
+  idx: number,
+  tables: Array<{ name: string; columns?: Record<string, SnapshotColumn> }>,
+): void {
+  const out: Record<string, unknown> = {};
+  for (const t of tables) {
+    out[`public.${t.name}`] = {
+      schema: "",
+      name: t.name,
+      columns: t.columns ?? {
+        id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+      },
+    };
+  }
+  writeFileSync(
+    join(migrationsDir, "meta", `${String(idx).padStart(4, "0")}_snapshot.json`),
+    JSON.stringify({ tables: out }),
+  );
+}
+
+function writeSnapshotSimple(idx: number, tableNames: string[]): void {
+  writeSnapshot(
+    idx,
+    tableNames.map((name) => ({ name })),
+  );
+}
+
+async function ensureDrizzleMigrationsTable(): Promise<void> {
+  await testDb.db.execute(sql`CREATE SCHEMA IF NOT EXISTS drizzle`);
+  await testDb.db.execute(sql`
+    CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
+      id serial PRIMARY KEY,
+      hash text NOT NULL,
+      created_at bigint
+    )
+  `);
+}
+
+async function dropDrizzleMigrationsTable(): Promise<void> {
+  await testDb.db.execute(sql`DROP TABLE IF EXISTS drizzle.__drizzle_migrations`);
+}
+
+async function insertAppliedMigration(hash: string): Promise<void> {
+  await testDb.db.execute(
+    sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES (${hash}, ${Date.now()})`,
+  );
+}
+
+describe("detectDrift", () => {
+  beforeEach(async () => {
+    await dropDrizzleMigrationsTable();
+    // Cleanup test tables that might still exist from earlier runs
+    await testDb.db.execute(sql`DROP TABLE IF EXISTS drift_test_users`);
+    await testDb.db.execute(sql`DROP TABLE IF EXISTS drift_test_orders`);
+  });
+
+  test("frische DB ohne __drizzle_migrations + 1 Migration im Journal → 1 pending + table missing", async () => {
+    writeJournal([{ idx: 0, tag: "0000_init" }]);
+    writeSnapshotSimple(0, ["drift_test_users"]);
+
+    const report = await detectDrift(testDb.db, migrationsDir);
+    expect(report.ok).toBe(false);
+    expect(report.pendingMigrations).toHaveLength(1);
+    expect(report.pendingMigrations[0]?.tag).toBe("0000_init");
+    expect(report.missingTables).toEqual(["drift_test_users"]);
+  });
+
+  test("alle Migrations applied + alle Tabellen existieren → ok", async () => {
+    writeJournal([{ idx: 0, tag: "0000_init" }]);
+    writeSnapshotSimple(0, ["drift_test_users"]);
+    await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY)`);
+    await ensureDrizzleMigrationsTable();
+    await insertAppliedMigration("hash-0000");
+
+    const report = await detectDrift(testDb.db, migrationsDir);
+    expect(report.ok).toBe(true);
+    expect(report.pendingMigrations).toHaveLength(0);
+    expect(report.missingTables).toHaveLength(0);
+  });
+
+  test("partial applied: Journal hat 2, applied hat 1 → 1 pending", async () => {
+    writeJournal([
+      { idx: 0, tag: "0000_init" },
+      { idx: 1, tag: "0001_add_orders" },
+    ]);
+    writeSnapshotSimple(1, ["drift_test_users", "drift_test_orders"]);
+    await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY)`);
+    await testDb.db.execute(sql`CREATE TABLE drift_test_orders (id uuid PRIMARY KEY)`);
+    await ensureDrizzleMigrationsTable();
+    await insertAppliedMigration("hash-0000"); // nur eine applied
+
+    const report = await detectDrift(testDb.db, migrationsDir);
+    expect(report.ok).toBe(false);
+    expect(report.pendingMigrations).toHaveLength(1);
+    expect(report.pendingMigrations[0]?.tag).toBe("0001_add_orders");
+    expect(report.missingTables).toHaveLength(0);
+  });
+
+  test("alle Migrations applied aber Tabelle fehlt manuell → drift", async () => {
+    writeJournal([{ idx: 0, tag: "0000_init" }]);
+    writeSnapshotSimple(0, ["drift_test_users", "drift_test_orders"]);
+    await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY)`);
+    // drift_test_orders bewusst NICHT angelegt (simuliert manuellen DROP)
+    await ensureDrizzleMigrationsTable();
+    await insertAppliedMigration("hash-0000");
+
+    const report = await detectDrift(testDb.db, migrationsDir);
+    expect(report.ok).toBe(false);
+    expect(report.pendingMigrations).toHaveLength(0);
+    expect(report.missingTables).toEqual(["drift_test_orders"]);
+  });
+
+  describe("Layer 3 — column-diff", () => {
+    test("snapshot column NOT NULL aber DB nullable → nullability-mismatch", async () => {
+      writeJournal([{ idx: 0, tag: "0000_init" }]);
+      writeSnapshot(0, [
+        {
+          name: "drift_test_users",
+          columns: {
+            id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+            email: { name: "email", type: "text", notNull: true },
+          },
+        },
+      ]);
+      // DB hat email NULLABLE — drift.
+      await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY, email text)`);
+      await ensureDrizzleMigrationsTable();
+      await insertAppliedMigration("hash-0000");
+
+      const report = await detectDrift(testDb.db, migrationsDir);
+      expect(report.ok).toBe(false);
+      expect(report.columnIssues).toHaveLength(1);
+      const issue = report.columnIssues[0];
+      expect(issue?.kind).toBe("nullability-mismatch");
+      expect(issue?.table).toBe("drift_test_users");
+      expect(issue?.column).toBe("email");
+    });
+
+    test("snapshot column im DB nicht da → missing-column", async () => {
+      writeJournal([{ idx: 0, tag: "0000_init" }]);
+      writeSnapshot(0, [
+        {
+          name: "drift_test_users",
+          columns: {
+            id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+            email: { name: "email", type: "text", notNull: true },
+          },
+        },
+      ]);
+      // DB hat KEINE email-Spalte.
+      await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY)`);
+      await ensureDrizzleMigrationsTable();
+      await insertAppliedMigration("hash-0000");
+
+      const report = await detectDrift(testDb.db, migrationsDir);
+      expect(report.ok).toBe(false);
+      expect(report.columnIssues).toHaveLength(1);
+      expect(report.columnIssues[0]?.kind).toBe("missing-column");
+      expect(report.columnIssues[0]?.column).toBe("email");
+    });
+
+    test("DB hat extra Spalte die nicht im Snapshot ist → extra-column", async () => {
+      writeJournal([{ idx: 0, tag: "0000_init" }]);
+      writeSnapshot(0, [
+        {
+          name: "drift_test_users",
+          columns: {
+            id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+          },
+        },
+      ]);
+      // DB hat zusätzliche Spalte (z.B. manueller ALTER TABLE in Prod).
+      await testDb.db.execute(
+        sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY, secret_legacy text)`,
+      );
+      await ensureDrizzleMigrationsTable();
+      await insertAppliedMigration("hash-0000");
+
+      const report = await detectDrift(testDb.db, migrationsDir);
+      expect(report.ok).toBe(false);
+      expect(report.columnIssues).toHaveLength(1);
+      expect(report.columnIssues[0]?.kind).toBe("extra-column");
+      expect(report.columnIssues[0]?.column).toBe("secret_legacy");
+    });
+
+    test("snapshot type vs db type mismatch → type-mismatch", async () => {
+      writeJournal([{ idx: 0, tag: "0000_init" }]);
+      writeSnapshot(0, [
+        {
+          name: "drift_test_users",
+          columns: {
+            id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+            age: { name: "age", type: "integer" },
+          },
+        },
+      ]);
+      // DB hat age als TEXT statt INTEGER.
+      await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY, age text)`);
+      await ensureDrizzleMigrationsTable();
+      await insertAppliedMigration("hash-0000");
+
+      const report = await detectDrift(testDb.db, migrationsDir);
+      expect(report.ok).toBe(false);
+      const typeIssue = report.columnIssues.find((i) => i.kind === "type-mismatch");
+      expect(typeIssue).toBeDefined();
+      if (typeIssue && typeIssue.kind === "type-mismatch") {
+        expect(typeIssue.column).toBe("age");
+        expect(typeIssue.expected).toBe("integer");
+        expect(typeIssue.actual).toBe("text");
+      }
+    });
+
+    test("clean state: alle Spalten matchen Snapshot → ok + columnIssues=[]", async () => {
+      writeJournal([{ idx: 0, tag: "0000_init" }]);
+      writeSnapshot(0, [
+        {
+          name: "drift_test_users",
+          columns: {
+            id: { name: "id", type: "uuid", primaryKey: true, notNull: true },
+            email: { name: "email", type: "text", notNull: true },
+            age: { name: "age", type: "integer" },
+          },
+        },
+      ]);
+      await testDb.db.execute(sql`
+        CREATE TABLE drift_test_users (
+          id uuid PRIMARY KEY,
+          email text NOT NULL,
+          age integer
+        )
+      `);
+      await ensureDrizzleMigrationsTable();
+      await insertAppliedMigration("hash-0000");
+
+      const report = await detectDrift(testDb.db, migrationsDir);
+      expect(report.ok).toBe(true);
+      expect(report.columnIssues).toEqual([]);
+    });
+  });
+
+  test("public.__drizzle_migrations Fallback (Pre-0.20-Drizzle)", async () => {
+    writeJournal([{ idx: 0, tag: "0000_init" }]);
+    writeSnapshotSimple(0, ["drift_test_users"]);
+    await testDb.db.execute(sql`CREATE TABLE drift_test_users (id uuid PRIMARY KEY)`);
+    // Legacy: Tabelle in public-Schema statt drizzle-Schema
+    await dropDrizzleMigrationsTable();
+    await testDb.db.execute(sql`
+      CREATE TABLE public.__drizzle_migrations (
+        id serial PRIMARY KEY,
+        hash text NOT NULL,
+        created_at bigint
+      )
+    `);
+    try {
+      await testDb.db.execute(
+        sql`INSERT INTO public.__drizzle_migrations (hash, created_at) VALUES ('hash-0000', ${Date.now()})`,
+      );
+      const report = await detectDrift(testDb.db, migrationsDir);
+      expect(report.ok).toBe(true);
+    } finally {
+      await testDb.db.execute(sql`DROP TABLE public.__drizzle_migrations`);
+    }
+  });
+});