@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/__tests__/boot-validator-s0-integration.test.ts

@@ -0,0 +1,160 @@
+// Integration-Test: alle Sprint-0-Surfaces in einem Mini-Feature-Set.
+//
+// Beweist dass die einzelnen S0-Komponenten (PII-Annotations, retention,
+// extension-names, exposesApi/usesApi, ROLES) zusammen funktionieren —
+// keine still-konkurrierenden Validierungen, keine Race-Conditions
+// zwischen Sub-Validatoren.
+//
+// Mini-Feature-Set:
+//   compliance-profiles  exposesApi("compliance.forTenant")
+//   user-data-rights     usesApi + extendsRegistrar(EXT_USER_DATA)
+//   tenant               useExtension(EXT_USER_DATA, "user", ...)
+//                        + entity mit pii / userOwned / tenantOwned-Fields
+//                        + retention.blockDelete + anonymize-Funktion
+//                        + handler-access mit ROLES.TenantAdmin
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { z } from "zod";
+import { ROLES } from "../../auth";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+  createTimestampField,
+  EXT_USER_DATA,
+} from "../index";
+
+describe("S0 Integration — full surface stack", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("alle S0-Surfaces zusammen passen Boot-Validation", () => {
+    const complianceProfiles = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+      r.queryHandler({
+        name: "compliance:query:for-tenant",
+        schema: z.object({}),
+        handler: async () => ({ profile: "eu-dsgvo" }) as never,
+        access: { openToAll: true },
+      });
+    });
+
+    const userDataRights = defineFeature("user-data-rights", (r) => {
+      r.requires("compliance-profiles");
+      r.usesApi("compliance.forTenant");
+      r.extendsRegistrar(EXT_USER_DATA, {
+        hooks: {},
+      });
+    });
+
+    const tenantFeature = defineFeature("tenant-app", (r) => {
+      r.requires("user-data-rights", "compliance-profiles");
+
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true }),
+            displayName: createTextField({ pii: true }),
+            lastLoginAt: createTimestampField({ pii: true }),
+          },
+          retention: {
+            keepFor: "10y",
+            strategy: "blockDelete",
+            reference: "createdAt",
+          },
+        }),
+      );
+
+      r.entity(
+        "comment",
+        createEntity({
+          fields: {
+            body: createLongTextField({
+              userOwned: { ownerField: "authorId" },
+              anonymize: () => "[ANONYMIZED]",
+            }),
+            authorId: { type: "reference", entity: "user" },
+          },
+        }),
+      );
+
+      r.queryHandler({
+        name: "user:list",
+        schema: z.object({}),
+        handler: async () => ({ rows: [], nextCursor: null }) as never,
+        access: { openToAll: true },
+      });
+
+      r.useExtension(EXT_USER_DATA, "user", {});
+      r.useExtension(EXT_USER_DATA, "comment", {});
+
+      r.writeHandler({
+        name: "user:rename",
+        schema: z.object({ id: z.string(), displayName: z.string() }),
+        handler: async () => undefined as never,
+        access: { roles: [ROLES.TenantAdmin] },
+      });
+    });
+
+    expect(() => validateBoot([complianceProfiles, userDataRights, tenantFeature])).not.toThrow();
+  });
+
+  test("missing requires() on usesApi-target throws even when other surfaces are clean", () => {
+    const complianceProfiles = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+
+    const userDataRights = defineFeature("user-data-rights", (r) => {
+      // VERGESSEN: r.requires("compliance-profiles")
+      r.usesApi("compliance.forTenant");
+    });
+
+    expect(() => validateBoot([complianceProfiles, userDataRights])).toThrow(
+      /not in requires\/optionalRequires\. Add r\.requires\("compliance-profiles"\)/,
+    );
+  });
+
+  test("retention.reference pointing to non-existent field throws even with valid PII annotations", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true }),
+          },
+          retention: {
+            keepFor: "30d",
+            strategy: "hardDelete",
+            reference: "notARealField",
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /retention\.reference "notARealField" does not exist/,
+    );
+  });
+
+  test("ROLES.TenantAdmin works as handler-access role string (no Admin/TenantAdmin drift)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ fields: { ts: createTimestampField() } }));
+      r.writeHandler({
+        name: "thing:create",
+        schema: z.object({}),
+        handler: async () => undefined as never,
+        access: { roles: [ROLES.TenantAdmin] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/__tests__/build-target.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "vitest";
+import { buildTarget, type TreeActionDef } from "../index";
+
+// createTreeActionsStub — Test-Helper für Phase-0-Stub-Features. Das
+// `const`-Generic-Modifier forciert Literal-Inference, sodass die
+// Action-Namen als string-literal-Union ankommen (statt zu `string`
+// widening). In V.1.1 wird der Helper überflüssig: echte defineFeature-
+// Outputs haben dieselbe Shape und Tests konsumieren die direkt.
+function createTreeActionsStub<const TActions extends Record<string, TreeActionDef>>(spec: {
+  readonly id: string;
+  readonly treeActions: TActions;
+}): { readonly id: string; readonly treeActions: TActions } {
+  return Object.freeze({ id: spec.id, treeActions: spec.treeActions });
+}
+
+const textContentStub = createTreeActionsStub({
+  id: "text-content",
+  treeActions: {
+    edit: { args: { slug: "" as string } },
+    create: { args: { folder: "" as string } },
+    list: {},
+  },
+});
+
+describe("buildTarget — NoArgs-Action", () => {
+  test("erzeugt TargetRef ohne args-Feld", () => {
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect(ref).toEqual({ featureId: "text-content", action: "list" });
+    expect("args" in ref).toBe(false);
+  });
+
+  test("output ist frozen (immutable)", () => {
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect(Object.isFrozen(ref)).toBe(true);
+  });
+});
+
+describe("buildTarget — WithArgs-Action", () => {
+  test("erzeugt TargetRef mit args", () => {
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref).toEqual({
+      featureId: "text-content",
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+  });
+
+  test("args sind frozen — Mutation am Input-Objekt schlägt nicht durch", () => {
+    const inputArgs = { slug: "imprint" };
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: inputArgs,
+    });
+    inputArgs.slug = "mutated";
+    expect(ref.args).toEqual({ slug: "imprint" });
+    expect(Object.isFrozen(ref.args)).toBe(true);
+  });
+
+  test("verschiedene Actions haben unterschiedliche Arg-Shapes", () => {
+    const editRef = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    const createRef = buildTarget({
+      target: textContentStub,
+      action: "create",
+      args: { folder: "/marketing" },
+    });
+    expect(editRef.args).toEqual({ slug: "imprint" });
+    expect(createRef.args).toEqual({ folder: "/marketing" });
+  });
+});
+
+describe("buildTarget — Compile-Time-Safety (verified via @ts-expect-error)", () => {
+  // Jeder Test paart ein @ts-expect-error-Block (compile-time-validation
+  // via TypeScript) mit einem runtime-expect über den korrespondierenden
+  // Happy-Path. Doppelt-Coverage: Compiler prüft Rejection, vitest prüft
+  // dass die korrekte Form bei valid input das richtige Ergebnis liefert.
+  // Memory `[Keine Fake-Tests]` — Tests müssen runtime-Verhalten prüfen,
+  // nicht nur Compile-Time (Fake-Test-Guard).
+
+  test("unbekannte action wird vom Compiler abgelehnt", () => {
+    // @ts-expect-error — "delet" ist keine Action von textContentStub
+    buildTarget({ target: textContentStub, action: "delet" });
+    // Runtime: bekannte Action liefert valid TargetRef
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect(ref.action).toBe("list");
+  });
+
+  test("falsche args-shape wird vom Compiler abgelehnt", () => {
+    // @ts-expect-error — slug muss string sein, nicht number
+    buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: 42 },
+    });
+    // Runtime: korrekt-typed args liefern valid TargetRef
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref.args).toEqual({ slug: "imprint" });
+  });
+
+  test("args bei NoArgs-Action wird vom Compiler abgelehnt", () => {
+    buildTarget({
+      target: textContentStub,
+      action: "list",
+      // @ts-expect-error — list hat keine args, args-Feld nicht erlaubt
+      args: { x: 1 },
+    });
+    // Runtime: NoArgs-Action ohne args-Feld liefert valid TargetRef
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect("args" in ref).toBe(false);
+  });
+
+  test("fehlende args bei WithArgs-Action wird vom Compiler abgelehnt", () => {
+    // @ts-expect-error — edit braucht args, fehlt
+    buildTarget({ target: textContentStub, action: "edit" });
+    // Runtime: WithArgs-Action mit args liefert valid TargetRef
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref.args).toBeDefined();
+  });
+});