@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/__tests__/parse-ref-target.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "vitest";
+import { parseRefTarget } from "../parse-ref-target";
+
+// Tier 2.7e Cross-Feature: parser-Konvention für ReferenceFieldDef.
+// Same-feature default ist der häufige Pfad; cross-feature verlangt
+// expliziten ":"-Prefix. Diese Tests pinnen die Aufteilungsregel
+// damit Boot-Validator und Renderer (über Re-Export) übereinstimmen.
+
+describe("parseRefTarget", () => {
+  test("kurzer name: featureName = currentFeature, entityName = raw", () => {
+    expect(parseRefTarget("user", "users")).toEqual({ featureName: "users", entityName: "user" });
+  });
+
+  test('qualifiziert "feature:entity": splittet am ersten Doppelpunkt', () => {
+    expect(parseRefTarget("users:user", "shop")).toEqual({
+      featureName: "users",
+      entityName: "user",
+    });
+  });
+
+  test("self-reference (kurz, gleicher entity-name) — currentFeature wandert durch", () => {
+    expect(parseRefTarget("category", "shop")).toEqual({
+      featureName: "shop",
+      entityName: "category",
+    });
+  });
+
+  test("kebab-case-feature: bleibt erhalten beim split", () => {
+    expect(parseRefTarget("public-status:incident", "shop")).toEqual({
+      featureName: "public-status",
+      entityName: "incident",
+    });
+  });
+
+  test("zweiter Doppelpunkt im entity-name (selten, aber möglich) — splittet nur am ERSTEN", () => {
+    // Konvention: feature und entity sind kebab-segments; der parser
+    // splittet conservative am ersten ":". Falls der Author einen
+    // entity-name mit ":" deklariert (was Boot-Validator ohnehin
+    // ablehnt), läuft er hier durch — der downstream-Lookup findet
+    // ihn dann nicht und failt.
+    expect(parseRefTarget("a:b:c", "shop")).toEqual({ featureName: "a", entityName: "b:c" });
+  });
+});

package/src/engine/__tests__/projection-helpers.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test, vi } from "vitest";
+import type { StoredEvent } from "../../event-store/event-store";
+import { setFields } from "../projection-helpers";
+import type { ProjectionTable } from "../types/projection";
+
+// Minimal fake table: only the `id` column is needed for setFields, and
+// setFields only hands it to `eq()` — no actual SQL runs in the unit test.
+// The cast mirrors ProjectionTable's deliberate erasure: the framework
+// doesn't know user table shapes at compile time, so real Drizzle tables
+// go through the same `any`-ish generic parameter.
+const fakeIdCol = { name: "id" };
+const fakeTable = { id: fakeIdCol, __name: "fake_table" } as unknown as ProjectionTable;
+
+function makeFakeEvent(overrides: Partial<StoredEvent> = {}): StoredEvent {
+  return {
+    id: "evt-1",
+    aggregateId: "agg-42",
+    aggregateType: "invoice",
+    // biome-ignore lint/suspicious/noExplicitAny: test shim — TenantId is a branded string and we don't exercise that branch here.
+    tenantId: "tenant-1" as any,
+    version: 1,
+    type: "invoice.sent",
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: "u-1", requestId: "r-1" },
+    createdAt: Temporal.Instant.from("2026-04-17T00:00:00Z"),
+    createdBy: "u-1",
+    ...overrides,
+  };
+}
+
+// Drizzle's tx.update(...).set(...).where(...) chain — capture each step.
+function makeFakeTx() {
+  const where = vi.fn().mockResolvedValue(undefined);
+  const set = vi.fn(() => ({ where }));
+  const update = vi.fn(() => ({ set }));
+  return { fakeTx: { update } as never, update, set, where };
+}
+
+describe("setFields", () => {
+  test("returns an apply fn that UPDATEs the passed fields WHERE id = aggregateId", async () => {
+    const apply = setFields(fakeTable, { status: "sent" });
+    const { fakeTx, update, set } = makeFakeTx();
+    await apply(makeFakeEvent(), fakeTx);
+    expect(update).toHaveBeenCalledWith(fakeTable);
+    expect(set).toHaveBeenCalledWith({ status: "sent" });
+  });
+
+  test("fields as a function receives the event and returns the field values", async () => {
+    const apply = setFields(fakeTable, (event) => ({
+      status: (event.payload as { newStatus: string }).newStatus,
+    }));
+    const { fakeTx, set } = makeFakeTx();
+    await apply(makeFakeEvent({ payload: { newStatus: "cancelled" } }), fakeTx);
+    expect(set).toHaveBeenCalledWith({ status: "cancelled" });
+  });
+
+  test("throws at construction time when the table has no 'id' column", () => {
+    const tableWithoutId = { __name: "weird_table" } as unknown as ProjectionTable;
+    expect(() => setFields(tableWithoutId, { status: "x" })).toThrow(/no 'id' column/);
+  });
+});

package/src/engine/__tests__/projection.test.ts

@@ -0,0 +1,191 @@
+import { integer, pgTable, uuid } from "drizzle-orm/pg-core";
+import { describe, expect, test } from "vitest";
+import type { ProjectionDefinition } from "../../engine/types";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+import { createRegistry } from "../registry";
+
+// Throwaway Drizzle table reused across these tests. The runtime-behaviour of
+// the projection itself (apply, TX semantics) is covered by the MietNomade
+// integration suite; this file focuses on the registrar/registry contracts
+// that fire BEFORE any write happens.
+const testTable = pgTable("test_projection", {
+  id: uuid("id").primaryKey(),
+  count: integer("count").notNull().default(0),
+});
+
+function exampleEntity(name = "unit") {
+  return createEntity({
+    table: name,
+    fields: { name: createTextField() },
+  });
+}
+
+function exampleProjection(overrides: Partial<ProjectionDefinition> = {}): ProjectionDefinition {
+  return {
+    name: "units-per-property",
+    source: "unit",
+    table: testTable,
+    apply: {},
+    ...overrides,
+  };
+}
+
+describe("r.projection() — registration", () => {
+  test("stores the projection on the FeatureDefinition", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection(exampleProjection());
+    });
+    expect(feature.projections["units-per-property"]).toBeDefined();
+    expect(feature.projections["units-per-property"]?.source).toBe("unit");
+  });
+
+  test("rejects duplicate projection names within the same feature", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("unit", exampleEntity());
+        r.projection(exampleProjection());
+        r.projection(exampleProjection());
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects non-kebab-case projection names", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("unit", exampleEntity());
+        r.projection(exampleProjection({ name: "units_per_property" }));
+      }),
+    ).toThrow(/kebab-case/);
+
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("unit", exampleEntity());
+        r.projection(exampleProjection({ name: "UnitsPerProperty" }));
+      }),
+    ).toThrow(/kebab-case/);
+  });
+
+  test("accepts kebab-case projection names", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("unit", exampleEntity());
+        r.projection(exampleProjection({ name: "units-per-property" }));
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("createRegistry — projection indexing", () => {
+  test("indexes projections by source entity for O(1) lookup", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection(exampleProjection());
+    });
+    const registry = createRegistry([feature]);
+    // Filter Implicit-Projections (Sprint G — eine pro r.entity auto-
+    // registriert). Dieser Test prüft die explicit-Projection-Indexierung.
+    const byUnit = registry.getProjectionsForSource("unit").filter((p) => !p.isImplicit);
+    expect(byUnit).toHaveLength(1);
+    expect(byUnit[0]?.source).toBe("unit");
+  });
+
+  test("returns empty list for entities with no explicit projections", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+    });
+    const registry = createRegistry([feature]);
+    // r.entity registriert eine Implicit-Projection — die filtern wir hier
+    // explizit raus, weil dieser Test die Abwesenheit von explicit
+    // Projections beweisen will.
+    expect(registry.getProjectionsForSource("unit").filter((p) => !p.isImplicit)).toHaveLength(0);
+  });
+
+  test("fans out a multi-source projection to each entity's index", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity("unit"));
+      r.entity("lease", exampleEntity("lease"));
+      r.projection(exampleProjection({ name: "combined", source: ["unit", "lease"] }));
+    });
+    const registry = createRegistry([feature]);
+    expect(registry.getProjectionsForSource("unit").filter((p) => !p.isImplicit)).toHaveLength(1);
+    expect(registry.getProjectionsForSource("lease").filter((p) => !p.isImplicit)).toHaveLength(1);
+  });
+
+  test("boot-validates source entity — typos must fail loudly", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      // Typo: "unti" instead of "unit". Without the source-validation guard
+      // this would silently be a no-op at runtime. Post "events-only-source"
+      // framework change the error message shifted: registry now accepts
+      // unregistered sources IF the apply-keys are domain-events — so a
+      // typo hits the "not registered AND no domain-event apply-keys"
+      // branch, which is what this test actually guards against.
+      r.projection(exampleProjection({ source: "unti" }));
+    });
+    expect(() => createRegistry([feature])).toThrow(/unti/);
+    expect(() => createRegistry([feature])).toThrow(/no domain-event apply-keys/);
+  });
+
+  test("boot-validates apply-keys against the source's event types", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection(
+        exampleProjection({
+          // Typo: "creatd" instead of "created". Same motivation as source-
+          // validation — catch silent no-ops at boot.
+          apply: {
+            "unit.creatd": async () => {},
+          },
+        }),
+      );
+    });
+    expect(() => createRegistry([feature])).toThrow(/apply handler for "unit\.creatd"/);
+  });
+
+  test("accepts all four auto-generated event-type apply-keys", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection(
+        exampleProjection({
+          apply: {
+            "unit.created": async () => {},
+            "unit.updated": async () => {},
+            "unit.deleted": async () => {},
+            "unit.restored": async () => {},
+          },
+        }),
+      );
+    });
+    expect(() => createRegistry([feature])).not.toThrow();
+  });
+
+  test("exposes all projections via getAllProjections", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection(exampleProjection());
+      r.projection(exampleProjection({ name: "other" }));
+    });
+    const registry = createRegistry([feature]);
+    // 2 explicit projections + 1 implicit (für r.entity "unit")
+    const explicit = [...registry.getAllProjections().values()].filter((p) => !p.isImplicit);
+    expect(explicit).toHaveLength(2);
+  });
+
+  test("rejects the same projection name registered by two features", () => {
+    const a = defineFeature("a", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection(exampleProjection({ name: "shared" }));
+    });
+    const b = defineFeature("b", (r) => {
+      r.entity("unit2", exampleEntity("unit2"));
+      r.projection(exampleProjection({ name: "shared", source: "unit2" }));
+    });
+    // Names get qualified with the feature-prefix so same short name from
+    // different features doesn't actually collide. Using the same name from
+    // the same qualified-name (only possible with the same feature) is the
+    // duplicate case — already covered by the r.projection() duplicate test.
+    expect(() => createRegistry([a, b])).not.toThrow();
+  });
+});

package/src/engine/__tests__/qualified-name.test.ts

@@ -0,0 +1,264 @@
+import { describe, expect, test } from "vitest";
+import {
+  isKebabSegment,
+  isValidQn,
+  type ParsedQn,
+  parseQn,
+  QnTypes,
+  qn,
+  toKebab,
+} from "../qualified-name";
+import type { CamelToKebab } from "../types/handlers";
+
+describe("qn()", () => {
+  test("builds scope:type:name string", () => {
+    expect(qn("tasks", QnTypes.write, "task:create")).toBe("tasks:write:task:create");
+    expect(qn("system", QnTypes.hook, "audit-trail")).toBe("system:hook:audit-trail");
+    expect(qn("billing", QnTypes.notify, "invoice-assigned")).toBe(
+      "billing:notify:invoice-assigned",
+    );
+  });
+
+  test("name can contain colons for sub-structure", () => {
+    expect(qn("tasks", "write", "task:create")).toBe("tasks:write:task:create");
+    expect(qn("hr", "write", "employee:promote")).toBe("hr:write:employee:promote");
+  });
+
+  test("name without colons works (standalone handlers, config, etc)", () => {
+    expect(qn("admin", "write", "reset")).toBe("admin:write:reset");
+    expect(qn("system", "hook", "audit-trail")).toBe("system:hook:audit-trail");
+  });
+
+  test("rejects invalid scope", () => {
+    expect(() => qn("Tasks", QnTypes.write, "create")).toThrow("Invalid QN scope");
+    expect(() => qn("", QnTypes.write, "create")).toThrow("Invalid QN scope");
+    expect(() => qn("my.feature", QnTypes.write, "create")).toThrow("Invalid QN scope");
+  });
+
+  test("rejects invalid name segment", () => {
+    expect(() => qn("tasks", QnTypes.write, "Create")).toThrow("Invalid QN name");
+    expect(() => qn("tasks", QnTypes.write, "")).toThrow("Invalid QN name");
+    expect(() => qn("tasks", QnTypes.write, "task_create")).toThrow("Invalid QN name");
+  });
+
+  test("allows numbers and dashes in segments", () => {
+    expect(qn("feature2", QnTypes.job, "sync-v2")).toBe("feature2:job:sync-v2");
+    expect(qn("my-app", QnTypes.event, "user:created")).toBe("my-app:event:user:created");
+  });
+});
+
+describe("parseQn()", () => {
+  test("parses 3-segment QN (no sub-structure in name)", () => {
+    const result: ParsedQn = parseQn("system:hook:audit-trail");
+    expect(result).toEqual({ scope: "system", type: "hook", name: "audit-trail" });
+  });
+
+  test("parses 4-segment QN (entity:action in name)", () => {
+    const result = parseQn("tasks:write:task:create");
+    expect(result).toEqual({ scope: "tasks", type: "write", name: "task:create" });
+  });
+
+  test("parses all built-in QN types", () => {
+    for (const type of Object.values(QnTypes)) {
+      const result = parseQn(`scope:${type}:name`);
+      expect(result.type).toBe(type);
+    }
+  });
+
+  test("accepts custom types (types are open)", () => {
+    const result = parseQn("billing:workflow:invoice:approval");
+    expect(result).toEqual({ scope: "billing", type: "workflow", name: "invoice:approval" });
+  });
+
+  test("rejects fewer than 3 segments", () => {
+    expect(() => parseQn("tasks:write")).toThrow("expected at least 3");
+    expect(() => parseQn("justonestring")).toThrow("expected at least 3");
+  });
+
+  test("rejects invalid type format", () => {
+    expect(() => parseQn("tasks:WRITE:name")).toThrow("Invalid QN type");
+    expect(() => parseQn("tasks:my_type:name")).toThrow("Invalid QN type");
+  });
+
+  test("rejects invalid scope or name in parsed string", () => {
+    expect(() => parseQn("Tasks:write:name")).toThrow("Invalid QN scope");
+    expect(() => parseQn("tasks:write:Name")).toThrow("Invalid QN name");
+  });
+});
+
+describe("isValidQn()", () => {
+  test("returns true for valid QNs", () => {
+    expect(isValidQn("tasks:write:task:create")).toBe(true);
+    expect(isValidQn("system:hook:audit-trail")).toBe(true);
+    expect(isValidQn("a:write:b")).toBe(true);
+  });
+
+  test("returns true for custom types", () => {
+    expect(isValidQn("billing:workflow:invoice:approval")).toBe(true);
+    expect(isValidQn("auth:rule:must-be-admin")).toBe(true);
+  });
+
+  test("returns false for invalid QNs", () => {
+    expect(isValidQn("tasks.write.create")).toBe(false);
+    expect(isValidQn("")).toBe(false);
+    expect(isValidQn("tasks:write")).toBe(false);
+    expect(isValidQn("Tasks:write:name")).toBe(false);
+  });
+});
+
+describe("toKebab()", () => {
+  test("converts dot-separated to kebab-case", () => {
+    expect(toKebab("task.create")).toBe("task-create");
+    expect(toKebab("billing-period.create")).toBe("billing-period-create");
+  });
+
+  test("converts camelCase to kebab-case", () => {
+    expect(toKebab("ticketAssigned")).toBe("ticket-assigned");
+    expect(toKebab("monthlyReport")).toBe("monthly-report");
+  });
+
+  test("leaves kebab-case unchanged", () => {
+    expect(toKebab("task-create")).toBe("task-create");
+    expect(toKebab("audit-trail")).toBe("audit-trail");
+  });
+
+  test("preserves colons", () => {
+    expect(toKebab("task:create")).toBe("task:create");
+    expect(toKebab("invoice:markPaid")).toBe("invoice:mark-paid");
+  });
+
+  test("handles mixed patterns", () => {
+    expect(toKebab("invoice.markPaid")).toBe("invoice-mark-paid");
+  });
+
+  test("handles uppercase sequences", () => {
+    expect(toKebab("parseJSON")).toBe("parse-json");
+    expect(toKebab("SSEBroadcast")).toBe("sse-broadcast");
+    expect(toKebab("getHTTPResponse")).toBe("get-http-response");
+  });
+});
+
+describe("CamelToKebab type === toKebab() runtime", () => {
+  // Each test cross-checks the compile-time type and the runtime function
+  // for the same input. Two layers of guarantee:
+  //
+  //   1. `expect(toKebab(X)).toBe(Y)` — runtime equality.
+  //   2. `const _: Equals<CamelToKebab<X>, Y> = true` — compile-time
+  //      equality. If the type doesn't reduce to exactly `Y`, the
+  //      assignment fails to type-check (`true` doesn't fit `false`).
+  //
+  // Both must agree — otherwise apps with such names get inconsistent
+  // augmentation keys. The Equals helper uses the function-bivariance
+  // trick to catch `never` divergence (a one-way `extends` check would
+  // silently pass `never extends X`).
+  type Equals<A, B> =
+    (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+  test("plain camelCase", () => {
+    expect(toKebab("orders")).toBe("orders");
+    expect(toKebab("driverOrders")).toBe("driver-orders");
+    expect(toKebab("monthlyReport")).toBe("monthly-report");
+    const _t1: Equals<CamelToKebab<"orders">, "orders"> = true;
+    const _t2: Equals<CamelToKebab<"driverOrders">, "driver-orders"> = true;
+    const _t3: Equals<CamelToKebab<"monthlyReport">, "monthly-report"> = true;
+    void _t1;
+    void _t2;
+    void _t3;
+  });
+
+  test("consecutive uppercase before camel-hump (the SSEFoo case)", () => {
+    expect(toKebab("SSEBroadcast")).toBe("sse-broadcast");
+    expect(toKebab("XMLId")).toBe("xml-id");
+    expect(toKebab("IOPort")).toBe("io-port");
+    expect(toKebab("getHTTPResponse")).toBe("get-http-response");
+    expect(toKebab("parseJSON")).toBe("parse-json");
+    const _t1: Equals<CamelToKebab<"SSEBroadcast">, "sse-broadcast"> = true;
+    const _t2: Equals<CamelToKebab<"XMLId">, "xml-id"> = true;
+    const _t3: Equals<CamelToKebab<"IOPort">, "io-port"> = true;
+    const _t4: Equals<CamelToKebab<"getHTTPResponse">, "get-http-response"> = true;
+    const _t5: Equals<CamelToKebab<"parseJSON">, "parse-json"> = true;
+    void _t1;
+    void _t2;
+    void _t3;
+    void _t4;
+    void _t5;
+  });
+
+  test("trailing uppercase run (no camel-hump)", () => {
+    expect(toKebab("IO")).toBe("io");
+    expect(toKebab("URL")).toBe("url");
+    expect(toKebab("userID")).toBe("user-id");
+    const _t1: Equals<CamelToKebab<"IO">, "io"> = true;
+    const _t2: Equals<CamelToKebab<"URL">, "url"> = true;
+    const _t3: Equals<CamelToKebab<"userID">, "user-id"> = true;
+    void _t1;
+    void _t2;
+    void _t3;
+  });
+
+  test("dot-separated", () => {
+    expect(toKebab("billing.period")).toBe("billing-period");
+    expect(toKebab("billing.PeriodCreate")).toBe("billing-period-create");
+    const _t1: Equals<CamelToKebab<"billing.period">, "billing-period"> = true;
+    const _t2: Equals<CamelToKebab<"billing.PeriodCreate">, "billing-period-create"> = true;
+    void _t1;
+    void _t2;
+  });
+
+  test("digits in name", () => {
+    expect(toKebab("MD5Hash")).toBe("md5-hash");
+    expect(toKebab("oauth2Provider")).toBe("oauth2-provider");
+    const _t1: Equals<CamelToKebab<"MD5Hash">, "md5-hash"> = true;
+    const _t2: Equals<CamelToKebab<"oauth2Provider">, "oauth2-provider"> = true;
+    void _t1;
+    void _t2;
+  });
+
+  test("already kebab-case (idempotent)", () => {
+    expect(toKebab("task-create")).toBe("task-create");
+    expect(toKebab("audit-trail")).toBe("audit-trail");
+    const _t1: Equals<CamelToKebab<"task-create">, "task-create"> = true;
+    const _t2: Equals<CamelToKebab<"audit-trail">, "audit-trail"> = true;
+    void _t1;
+    void _t2;
+  });
+});
+
+describe("isKebabSegment()", () => {
+  test("accepts valid kebab segments", () => {
+    expect(isKebabSegment("task")).toBe(true);
+    expect(isKebabSegment("task-create")).toBe(true);
+    expect(isKebabSegment("audit-trail-v2")).toBe(true);
+    expect(isKebabSegment("a")).toBe(true);
+    expect(isKebabSegment("x1")).toBe(true);
+  });
+
+  test("rejects camelCase", () => {
+    expect(isKebabSegment("taskCreate")).toBe(false);
+    expect(isKebabSegment("auditTrail")).toBe(false);
+  });
+
+  test("rejects dots", () => {
+    expect(isKebabSegment("task.create")).toBe(false);
+  });
+
+  test("rejects underscores (toKebab leaves them through — regex catches it)", () => {
+    expect(isKebabSegment("task_create")).toBe(false);
+    expect(isKebabSegment("my_projection")).toBe(false);
+  });
+
+  test("rejects uppercase", () => {
+    expect(isKebabSegment("Task")).toBe(false);
+    expect(isKebabSegment("TASK")).toBe(false);
+  });
+
+  test("rejects non-letter starts", () => {
+    expect(isKebabSegment("1task")).toBe(false);
+    expect(isKebabSegment("-task")).toBe(false);
+    expect(isKebabSegment("")).toBe(false);
+  });
+
+  test("rejects colons (single-segment check, not full QN)", () => {
+    expect(isKebabSegment("task:create")).toBe(false);
+  });
+});