@cosmicdrift/kumiko-framework 0.1.0

package/src/migrations/__tests__/detect-projections-to-rebuild.integration.ts

@@ -0,0 +1,134 @@
+// Integration-Test für detectProjectionsToRebuild — die Brücke zwischen
+// Snapshot-Diff (Welle 2) und ImplicitProjection (Sprint G). Beweist dass
+// `kumiko migrate generate` das richtige Marker-File schreibt: ein
+// Spalten-Add auf einer r.entity-Tabelle muss als
+// `<feature>:projection:<entity>-entity` rebuild-Kandidat erkannt werden.
+//
+// Production-Behavior: ohne diese Brücke würden die Welle-2- und
+// Sprint-G-Pieces nebeneinander leben aber sich nicht treffen — Marker
+// wäre leer, kein Rebuild würde ausgelöst.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createBooleanField, createEntity, createTextField, defineFeature } from "../../engine";
+import { createRegistry } from "../../engine/registry";
+import { detectProjectionsToRebuild } from "../projection-detection";
+
+let migrationsDir: string;
+
+beforeEach(() => {
+  migrationsDir = mkdtempSync(join(tmpdir(), "kumiko-detect-"));
+  mkdirSync(join(migrationsDir, "meta"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(migrationsDir, { recursive: true, force: true });
+});
+
+function writeJournal(entries: { idx: number; tag: string }[]): void {
+  writeFileSync(
+    join(migrationsDir, "meta/_journal.json"),
+    JSON.stringify({
+      version: "7",
+      dialect: "postgresql",
+      entries: entries.map((e) => ({
+        idx: e.idx,
+        version: "7",
+        when: 1700000000000 + e.idx,
+        tag: e.tag,
+        breakpoints: true,
+      })),
+    }),
+  );
+}
+
+function writeSnapshot(idx: number, tableName: string, columnNames: string[]): void {
+  const columns: Record<string, unknown> = {};
+  for (const name of columnNames) {
+    columns[name] = { name, type: "text" };
+  }
+  // Plus base-columns die jede Entity-Tabelle hat, damit wir nicht mit
+  // dem Test-Compare versehentlich kompletten neue Tabellen markieren.
+  columns["id"] = { name: "id", type: "uuid", primaryKey: true, notNull: true };
+  columns["tenant_id"] = { name: "tenant_id", type: "uuid", notNull: true };
+  columns["version"] = { name: "version", type: "integer", default: 1, notNull: true };
+  writeFileSync(
+    join(migrationsDir, "meta", `${String(idx).padStart(4, "0")}_snapshot.json`),
+    JSON.stringify({
+      tables: {
+        [`public.${tableName}`]: {
+          schema: "",
+          name: tableName,
+          columns,
+        },
+      },
+    }),
+  );
+}
+
+const widgetEntity = createEntity({
+  table: "test_widgets",
+  fields: {
+    name: createTextField({ required: true }),
+    isEnabled: createBooleanField({ default: true }),
+  },
+});
+
+const widgetFeature = defineFeature("detecttest", (r) => {
+  r.entity("widget", widgetEntity);
+});
+
+describe("detectProjectionsToRebuild", () => {
+  test("Spalten-Add auf r.entity-Tabelle → ImplicitProjection als Rebuild-Kandidat", () => {
+    // Initial-Migration: 2 Spalten
+    writeSnapshot(0, "test_widgets", ["name", "is_enabled"]);
+    // Folge-Migration: 3 Spalten (description dazu)
+    writeSnapshot(1, "test_widgets", ["name", "is_enabled", "description"]);
+    writeJournal([
+      { idx: 0, tag: "0000_init" },
+      { idx: 1, tag: "0001_add_description" },
+    ]);
+
+    const registry = createRegistry([widgetFeature]);
+    const projections = detectProjectionsToRebuild(registry, migrationsDir);
+
+    expect(projections).toEqual(["detecttest:projection:widget-entity"]);
+  });
+
+  test("identische Snapshots → keine Rebuild-Kandidaten", () => {
+    writeSnapshot(0, "test_widgets", ["name", "is_enabled"]);
+    writeSnapshot(1, "test_widgets", ["name", "is_enabled"]);
+    writeJournal([
+      { idx: 0, tag: "0000_init" },
+      { idx: 1, tag: "0001_no_op" },
+    ]);
+
+    const registry = createRegistry([widgetFeature]);
+    expect(detectProjectionsToRebuild(registry, migrationsDir)).toEqual([]);
+  });
+
+  test("Initial-Migration (nur ein Snapshot) → leer (keine historischen Events)", () => {
+    writeSnapshot(0, "test_widgets", ["name"]);
+    writeJournal([{ idx: 0, tag: "0000_init" }]);
+
+    const registry = createRegistry([widgetFeature]);
+    expect(detectProjectionsToRebuild(registry, migrationsDir)).toEqual([]);
+  });
+
+  test("Spalten-Add auf einer Tabelle die KEINE Projection ist → leer", () => {
+    // Tabelle "unrelated" ist nicht als Projection registriert (kein
+    // r.entity, keine r.projection). Schema-Change soll keinen
+    // Rebuild-Marker erzeugen.
+    writeSnapshot(0, "unrelated", ["a"]);
+    writeSnapshot(1, "unrelated", ["a", "b"]);
+    writeJournal([
+      { idx: 0, tag: "0000_init" },
+      { idx: 1, tag: "0001_add_b" },
+    ]);
+
+    const registry = createRegistry([widgetFeature]);
+    expect(detectProjectionsToRebuild(registry, migrationsDir)).toEqual([]);
+  });
+});

package/src/migrations/__tests__/rebuild-marker.test.ts

@@ -0,0 +1,79 @@
+// Unit-Tests für die Marker-File-IO. Production-Behavior:
+//   - Generate-Step schreibt Marker mit kanonischer Struktur
+//   - Apply-Step liest Marker zurück (oder null wenn keiner)
+//   - schemaVersion-Mismatch wirft (verhindert dass alte Markers gegen
+//     neue Lese-Logik fahren)
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { readRebuildMarker, writeRebuildMarker } from "../rebuild-marker";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "kumiko-marker-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("writeRebuildMarker / readRebuildMarker round-trip", () => {
+  test("schreibt File mit kanonischer Struktur", () => {
+    writeRebuildMarker(tmpDir, "0042_brave_taskmaster", [
+      "publicstatus:projection:incident-entity",
+      "publicstatus:projection:component-entity",
+    ]);
+    const raw = readFileSync(join(tmpDir, "0042_brave_taskmaster__rebuild.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    expect(parsed).toEqual({
+      schemaVersion: 1,
+      migrationTag: "0042_brave_taskmaster",
+      // sortiert — Reihenfolge der projections im Output ist deterministisch
+      projections: [
+        "publicstatus:projection:component-entity",
+        "publicstatus:projection:incident-entity",
+      ],
+    });
+  });
+
+  test("read returns parsed marker", () => {
+    writeRebuildMarker(tmpDir, "0001_foo", ["app:projection:bar-entity"]);
+    const marker = readRebuildMarker(tmpDir, "0001_foo");
+    expect(marker?.migrationTag).toBe("0001_foo");
+    expect(marker?.projections).toEqual(["app:projection:bar-entity"]);
+  });
+
+  test("leere Projection-Liste schreibt KEIN File (Noise-Reduktion)", () => {
+    writeRebuildMarker(tmpDir, "0003_only_index", []);
+    expect(readRebuildMarker(tmpDir, "0003_only_index")).toBeNull();
+  });
+
+  test("read returns null wenn File nicht existiert", () => {
+    expect(readRebuildMarker(tmpDir, "0099_never_written")).toBeNull();
+  });
+
+  test("schemaVersion-Mismatch wirft mit klarer Message", () => {
+    const path = join(tmpDir, "0042_future__rebuild.json");
+    writeFileSync(
+      path,
+      JSON.stringify({ schemaVersion: 999, migrationTag: "0042_future", projections: [] }),
+    );
+    expect(() => readRebuildMarker(tmpDir, "0042_future")).toThrow(/schemaVersion/);
+  });
+
+  test("korrupte JSON wirft (kein silent-null)", () => {
+    const path = join(tmpDir, "0050_corrupt__rebuild.json");
+    writeFileSync(path, "{ this is not json");
+    expect(() => readRebuildMarker(tmpDir, "0050_corrupt")).toThrow();
+  });
+
+  test("Idempotenz: zweiter write überschreibt", () => {
+    writeRebuildMarker(tmpDir, "0010_x", ["a:projection:one-entity"]);
+    writeRebuildMarker(tmpDir, "0010_x", ["a:projection:two-entity"]);
+    const marker = readRebuildMarker(tmpDir, "0010_x");
+    expect(marker?.projections).toEqual(["a:projection:two-entity"]);
+  });
+});

package/src/migrations/index.ts

@@ -0,0 +1,28 @@
+export {
+  buildProjectionTableIndex,
+  type ChangedTable,
+  compareSnapshots,
+  detectProjectionsToRebuild,
+  latestMigrationTag,
+  projectionsFromChanges,
+} from "./projection-detection";
+export { type RebuildMarker, readRebuildMarker, writeRebuildMarker } from "./rebuild-marker";
+export {
+  type AppliedMigration,
+  assertSchemaCurrent,
+  type ColumnIssue,
+  type ColumnSpec,
+  type DriftReport,
+  detectDrift,
+  formatDriftReport,
+  type Journal,
+  type JournalEntry,
+  loadAppliedMigrations,
+  loadJournal,
+  loadLatestSnapshot,
+  loadPreviousSnapshot,
+  loadSnapshot,
+  SchemaDriftError,
+  type Snapshot,
+  type SnapshotTable,
+} from "./schema-drift";

package/src/migrations/projection-detection.ts

@@ -0,0 +1,149 @@
+// Snapshot-Diff + Projection-Lookup für die Welle-2-Migration-Pipeline.
+//
+// Wenn `kumiko migrate generate` ein neues Drizzle-Snapshot-File erzeugt,
+// vergleichen wir es mit dem vorherigen. Tabellen die schema-changes
+// haben (Spalten dazu/weg, Spalten-Type-Änderung) sind Kandidaten für
+// einen Projection-Rebuild — vorausgesetzt sie gehören zu einer
+// registrierten Projection.
+//
+// Der Lookup geht über getTableName(projection.table) — die Drizzle-
+// public-API für den physischen Tabellen-Namen einer pgTable-Definition.
+// Damit muss niemand Tabellen-Namen doppelt pflegen (Truth liegt in der
+// Projection-Definition).
+
+import { getTableName } from "drizzle-orm";
+import type { Registry } from "../engine/types/feature";
+import {
+  type ColumnSpec,
+  loadJournal,
+  loadLatestSnapshot,
+  loadPreviousSnapshot,
+  type Snapshot,
+} from "./schema-drift";
+
+/** Welche Tabellen haben sich zwischen prev und current geändert?
+ *  Reine Tabellen-Existenz: in current aber nicht in prev → "added".
+ *  Spalten-Veränderungen: identische Tabelle aber Spalten unterscheiden. */
+export type ChangedTable = {
+  readonly fullName: string; // "schema.name" oder einfach "name" wenn empty schema
+  readonly tableName: string; // nur "name" für tableName-Lookup
+  readonly kind: "added" | "modified" | "removed";
+};
+
+export function compareSnapshots(
+  prev: Snapshot | null,
+  current: Snapshot,
+): readonly ChangedTable[] {
+  const changes: ChangedTable[] = [];
+  const prevKeys = new Set(prev ? Object.keys(prev.tables) : []);
+  const currentKeys = new Set(Object.keys(current.tables));
+
+  for (const key of currentKeys) {
+    const cur = current.tables[key];
+    if (!cur) continue;
+    const fullName = cur.schema && cur.schema.length > 0 ? `${cur.schema}.${cur.name}` : cur.name;
+    if (!prevKeys.has(key)) {
+      changes.push({ fullName, tableName: cur.name, kind: "added" });
+      continue;
+    }
+    const prevTable = prev?.tables[key];
+    if (!prevTable) continue;
+    if (!sameColumns(prevTable.columns, cur.columns)) {
+      changes.push({ fullName, tableName: cur.name, kind: "modified" });
+    }
+  }
+
+  for (const key of prevKeys) {
+    if (!currentKeys.has(key)) {
+      const prevTable = prev?.tables[key];
+      if (!prevTable) continue;
+      const fullName =
+        prevTable.schema && prevTable.schema.length > 0
+          ? `${prevTable.schema}.${prevTable.name}`
+          : prevTable.name;
+      changes.push({ fullName, tableName: prevTable.name, kind: "removed" });
+    }
+  }
+
+  return changes;
+}
+
+function sameColumns(
+  a: Readonly<Record<string, ColumnSpec>>,
+  b: Readonly<Record<string, ColumnSpec>>,
+): boolean {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    const colA = a[key];
+    const colB = b[key];
+    if (!colA || !colB) return false;
+    if (colA.name !== colB.name) return false;
+    if (colA.type !== colB.type) return false;
+    if (Boolean(colA.notNull) !== Boolean(colB.notNull)) return false;
+    if (Boolean(colA.primaryKey) !== Boolean(colB.primaryKey)) return false;
+    // Default-Vergleich bewusst per JSON — Drizzle serialisiert default-
+    // expressions als String, das passt für CREATE TABLE-Zwecke.
+    if (JSON.stringify(colA.default) !== JSON.stringify(colB.default)) return false;
+  }
+  return true;
+}
+
+/** Index `tableName → projection-name` aus der Registry. Nur Projections
+ *  mit table-Definition (single-stream + multi-stream-with-table) zählen.
+ *  Side-effect-only MSPs (table omitted) haben keinen Rebuild-Sinn. */
+export function buildProjectionTableIndex(registry: Registry): ReadonlyMap<string, string> {
+  const index = new Map<string, string>();
+  for (const [name, def] of registry.getAllProjections()) {
+    index.set(getTableName(def.table), name);
+  }
+  for (const [name, def] of registry.getAllMultiStreamProjections()) {
+    if (def.table) index.set(getTableName(def.table), name);
+  }
+  return index;
+}
+
+/** Aus einer Liste geänderter Tabellen die Projection-Namen extrahieren.
+ *  "removed" ignoriert: gelöschte Projection-Tabellen → die Projection
+ *  ist auch weg, kein Rebuild-Bedarf. "added" wird zurückgegeben — beim
+ *  ersten Migrate aus einer leeren DB sind das keine echten Rebuilds
+ *  (keine historischen Events), aber der Apply-Step filtert das selbst
+ *  über event-count > 0 heraus. */
+export function projectionsFromChanges(
+  changes: readonly ChangedTable[],
+  index: ReadonlyMap<string, string>,
+): readonly string[] {
+  const names = new Set<string>();
+  for (const change of changes) {
+    if (change.kind === "removed") continue;
+    const projection = index.get(change.tableName);
+    if (projection) names.add(projection);
+  }
+  return [...names].sort();
+}
+
+/** Convenience: gibt für die letzte Migration zurück welche Projections
+ *  rebuild brauchen würden. Empty wenn das gerade die erste Migration ist
+ *  (kein vorheriger Snapshot, alle Tabellen "added", aber keine Events). */
+export function detectProjectionsToRebuild(
+  registry: Registry,
+  migrationsDir: string,
+): readonly string[] {
+  const prev = loadPreviousSnapshot(migrationsDir);
+  // Initial migration: nur "added"-Changes, keine historischen Events
+  // zum Replayen → kein Rebuild nötig.
+  if (prev === null) return [];
+  const current = loadLatestSnapshot(migrationsDir);
+  const changes = compareSnapshots(prev, current);
+  const index = buildProjectionTableIndex(registry);
+  return projectionsFromChanges(changes, index);
+}
+
+/** Tag des letzten journal-Eintrags — nutzen wir als Marker-File-Name. */
+export function latestMigrationTag(migrationsDir: string): string {
+  const journal = loadJournal(migrationsDir);
+  const last = journal.entries[journal.entries.length - 1];
+  if (!last) throw new Error(`latestMigrationTag: empty journal in ${migrationsDir}`);
+  return last.tag;
+}

package/src/migrations/rebuild-marker.ts

@@ -0,0 +1,64 @@
+// Rebuild-Marker-File: zur generate-Zeit schreibt der Migration-Generator
+// ein Side-File `<tag>__rebuild.json` neben das SQL-File. Beim apply liest
+// der Apply-Step die Marker für alle neu-applied Migrations und ruft
+// rebuildProjection() für jede gelistete Projection.
+//
+// Format:
+//   {
+//     "schemaVersion": 1,
+//     "migrationTag": "0042_brave_taskmaster",
+//     "projections": ["publicstatus:projection:incident-state", ...]
+//   }
+//
+// Das File wird zum Migration-File committed und durchläuft Code-Review
+// — die Projection-Rebuild-Liste ist damit sichtbar im PR.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseJsonOrThrow } from "../utils/safe-json";
+
+const MARKER_VERSION = 1 as const;
+
+export type RebuildMarker = {
+  readonly schemaVersion: typeof MARKER_VERSION;
+  readonly migrationTag: string;
+  readonly projections: readonly string[];
+};
+
+function markerPath(migrationsDir: string, migrationTag: string): string {
+  return resolve(migrationsDir, `${migrationTag}__rebuild.json`);
+}
+
+export function writeRebuildMarker(
+  migrationsDir: string,
+  migrationTag: string,
+  projections: readonly string[],
+): void {
+  // skip: leere Projections-Liste → kein Marker-File. Reduziert Noise
+  // bei Migrations die keine Projection berühren (Infra-Tabellen, pure
+  // Index-Adds). Caller braucht keinen Confirm — File-Existenz ist die
+  // Truth-Quelle.
+  if (projections.length === 0) return;
+  const marker: RebuildMarker = {
+    schemaVersion: MARKER_VERSION,
+    migrationTag,
+    projections: [...projections].sort(),
+  };
+  writeFileSync(markerPath(migrationsDir, migrationTag), `${JSON.stringify(marker, null, 2)}\n`);
+}
+
+export function readRebuildMarker(
+  migrationsDir: string,
+  migrationTag: string,
+): RebuildMarker | null {
+  const path = markerPath(migrationsDir, migrationTag);
+  if (!existsSync(path)) return null;
+  const parsed = parseJsonOrThrow<RebuildMarker>(readFileSync(path, "utf-8"), `marker at ${path}`);
+  if (parsed.schemaVersion !== MARKER_VERSION) {
+    throw new Error(
+      `readRebuildMarker: ${path} hat schemaVersion ${parsed.schemaVersion}, ` +
+        `erwartet ${MARKER_VERSION}. Kumiko-Version-Mismatch?`,
+    );
+  }
+  return parsed;
+}