@cosmicdrift/kumiko-framework 0.154.0 → 0.154.2

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -301,21 +301,16 @@ describe("patch coverage for the remaining pattern-kinds", () => {
     expect(parseSourceFile(sf).patterns.find((p) => p.kind === "authClaims")).toBeUndefined();
   });
 
-  test("add + remove via PatternId for eventMigration (event+versions key)", () => {
+  test("add + remove via PatternId for defineEvent with migrations", () => {
     const sf = makeSourceFile(STARTER);
-    createFeaturePatcher(sf).addEventMigration({
-      event: "itemCreated",
-      fromVersion: 1,
-      toVersion: 2,
-      transformSource: "(old) => old",
-    });
-    removePattern(sf, {
-      kind: "eventMigration",
-      eventName: "itemCreated",
-      fromVersion: 1,
-      toVersion: 2,
+    createFeaturePatcher(sf).addDefineEvent({
+      name: "itemCreated",
+      schemaSource: "z.object({ id: z.string() })",
+      version: 2,
+      migrations: { "1": "(old) => old" },
     });
-    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "eventMigration")).toBeUndefined();
+    removePattern(sf, { kind: "defineEvent", eventName: "itemCreated" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "defineEvent")).toBeUndefined();
   });
 });
 

package/src/engine/feature-ast/__tests__/patcher.test.ts

@@ -157,48 +157,38 @@ describe("FeaturePatcher — typed add helpers for mixed (closure-bearing) patte
     });
   });
 
-  test("addEntityHook routes type + entity correctly", () => {
+  test("addHook routes entity-wide { allOf } target correctly", () => {
     const sf = makeSourceFile(STARTER);
-    createFeaturePatcher(sf).addEntityHook({
+    createFeaturePatcher(sf).addHook({
       type: "postDelete",
-      entity: "task",
+      target: { allOf: "task" },
       handlerSource: "async (event, ctx) => { /* cleanup */ }",
     });
     const result = parseSourceFile(sf);
     expect(result.patterns[0]).toMatchObject({
-      kind: "entityHook",
+      kind: "hook",
       hookType: "postDelete",
-      entityName: "task",
+      target: { allOf: "task" },
     });
   });
 
-  test("addDefineEvent + addEventMigration form a complete event-versioning chain", () => {
+  test("addDefineEvent with migrations forms a complete event-versioning chain", () => {
     const sf = makeSourceFile(STARTER);
     const p = createFeaturePatcher(sf);
     p.addDefineEvent({
       name: "stepCompleted",
       schemaSource: "z.object({ id: z.string() })",
       version: 2,
-    });
-    p.addEventMigration({
-      event: "stepCompleted",
-      fromVersion: 1,
-      toVersion: 2,
-      transformSource: '(old) => ({ id: old.id ?? "" })',
+      migrations: { "1": '(old) => ({ id: old.id ?? "" })' },
     });
     const result = parseSourceFile(sf);
     expect(result.errors).toEqual([]);
-    expect(result.patterns).toHaveLength(2);
+    expect(result.patterns).toHaveLength(1);
     expect(result.patterns[0]).toMatchObject({
       kind: "defineEvent",
       eventName: "stepCompleted",
       version: 2,
-    });
-    expect(result.patterns[1]).toMatchObject({
-      kind: "eventMigration",
-      eventName: "stepCompleted",
-      fromVersion: 1,
-      toVersion: 2,
+      migrations: { "1": expect.anything() },
     });
   });
 });
@@ -452,9 +442,9 @@ defineFeature("tasks", (r) => {
       handlerSource: "async (q, ctx) => []",
       access: { openToAll: true },
     });
-    p.addEntityHook({
+    p.addHook({
       type: "postDelete",
-      entity: "task",
+      target: { allOf: "task" },
       handlerSource: "async (event, ctx) => { /* cascade-clean */ }",
     });
     const result = parseSourceFile(sf);
@@ -463,7 +453,7 @@ defineFeature("tasks", (r) => {
       "entity",
       "writeHandler",
       "queryHandler",
-      "entityHook",
+      "hook",
     ]);
   });
 });

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -9,7 +9,8 @@
 // up at canonical positions). We compare every other field.
 
 import { describe, expect, test } from "bun:test";
-import { Project } from "ts-morph";
+import * as path from "node:path";
+import { Project, ts } from "ts-morph";
 import { parseSourceFile } from "../parse";
 import type { FeaturePattern } from "../patterns";
 import { renderFeatureFile, renderPattern } from "../render";
@@ -29,10 +30,10 @@ defineFeature("inventory", (r) => {
     },
   });
 
-  r.relation("item", "supplier", { kind: "belongsTo", to: "user" });
+  r.relation("item", "supplier", { type: "belongsTo", target: "user", foreignKey: "supplierId" });
 
   r.metric("created", { type: "counter" });
-  r.secret("apiKey", { description: "Stripe key" });
+  r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });
   r.claimKey("teamId", { type: "string" });
 
   r.referenceData(
@@ -44,7 +45,16 @@ defineFeature("inventory", (r) => {
     { upsertKey: "id" },
   );
 
-  r.config({ keys: { maxRows: { type: "number", default: 50 } } });
+  r.config({
+    keys: {
+      maxRows: {
+        type: "number",
+        default: 50,
+        scope: "tenant",
+        access: { read: ["user"], write: ["admin"] },
+      },
+    },
+  });
 });
 `;
 
@@ -114,7 +124,7 @@ function stripLocations(value: unknown): unknown {
         out[k] = { raw: normalizeBodyRaw((v as { raw: string }).raw) };
         continue;
       }
-      if (k === "opaqueProps" && v && typeof v === "object") {
+      if ((k === "opaqueProps" || k === "migrations") && v && typeof v === "object") {
         const op: Record<string, unknown> = {};
         for (const [pk, pv] of Object.entries(v as Record<string, unknown>)) {
           if (pv && typeof pv === "object" && "raw" in pv) {
@@ -359,6 +369,41 @@ describe("renderPattern — single-pattern shape", () => {
   });
 });
 
+// Regression guard for the class of bug the r.exposesApi/r.usesApi fold
+// hit: a registrar-shape change must survive the Designer's parse→render→
+// parse cycle, not just a TS compile of the framework itself. r.hook()'s
+// `{ allOf: entity }` target (replacing r.entityHook) reuses HookPattern's
+// already-generic target field, so this is the cheap case — but proving it
+// beats assuming it.
+const HOOK_ALL_OF_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("shop", (r) => {
+  r.entity("product", { fields: { name: { type: "text" } } });
+  r.hook("postSave", { allOf: "product" }, async (result) => {
+    console.log(result);
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.hook({ allOf }) entity-wide target", () => {
+  test("allOf target survives parse → render → parse unchanged", () => {
+    const initial = parse(HOOK_ALL_OF_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const hookPattern = reparsed.patterns.find((p) => p.kind === "hook");
+    expect(hookPattern?.kind).toBe("hook");
+    if (hookPattern?.kind === "hook") {
+      expect(hookPattern.target).toEqual({ allOf: "product" });
+    }
+  });
+});
+
 // Regression guard for the class of bug the r.exposesApi/r.usesApi fold
 // hit: a registrar-shape change (there, removing a method; here, adding a
 // nested optional field) must survive the Designer's parse→render→parse
@@ -400,3 +445,200 @@ describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () =>
     }
   });
 });
+
+const DEFINE_EVENT_WITH_MIGRATIONS_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("billing", (r) => {
+  r.defineEvent("invoicePaid", z.object({ totalCents: z.number() }), {
+    version: 2,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        transform: (payload) => ({ totalCents: Math.round(payload.total * 100) }),
+      },
+    ],
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.defineEvent({ migrations }) fold", () => {
+  test("migrations array survives parse → render → parse unchanged", () => {
+    const initial = parse(DEFINE_EVENT_WITH_MIGRATIONS_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const eventPattern = reparsed.patterns.find((p) => p.kind === "defineEvent");
+    expect(eventPattern?.kind).toBe("defineEvent");
+    if (eventPattern?.kind === "defineEvent") {
+      expect(eventPattern.version).toBe(2);
+      expect(Object.keys(eventPattern.migrations ?? {})).toEqual(["1"]);
+    }
+  });
+});
+
+// --- Real-compile check ---------------------------------------------------
+//
+// Everything above proves parse(render(patterns)) is structurally faithful.
+// It does NOT prove the rendered code actually compiles against the real
+// FeatureRegistrar type — parse() runs against a bare in-memory Project with
+// no lib/module resolution, so a rendered call can be well-formed AST and
+// still be a type error against the real registrar (e.g. a removed method).
+// That gap let the r.usesApi removal (folded into r.requires({apis})) pass
+// the full 4960-test suite silently; only the visual Designer would have hit
+// the broken shape.
+//
+// This Project resolves `@cosmicdrift/kumiko-framework/*` against the real
+// framework source (unlike parse()'s Project, dependency resolution is NOT
+// skipped), so `r` in a compiled fixture is the real FeatureRegistrar, not a
+// structural stand-in.
+const FRAMEWORK_TSCONFIG_PATH = path.join(import.meta.dir, "../../../../tsconfig.json");
+
+const compileProject = new Project({
+  tsConfigFilePath: FRAMEWORK_TSCONFIG_PATH,
+  skipAddingFilesFromTsConfig: true,
+});
+
+let compileCheckCounter = 0;
+
+function compileAgainstRegistrar(source: string): readonly string[] {
+  compileCheckCounter += 1;
+  const filePath = path.join(
+    import.meta.dir,
+    `__generated__/compile-check-${compileCheckCounter}.gen.ts`,
+  );
+  const sourceFile = compileProject.createSourceFile(filePath, source, { overwrite: true });
+  const diagnostics = sourceFile.getPreEmitDiagnostics().map((d) => {
+    const text = ts.flattenDiagnosticMessageText(d.compilerObject.messageText, "\n");
+    return `${d.getLineNumber()}: ${text}`;
+  });
+  sourceFile.forget();
+  return diagnostics;
+}
+
+function renderAndCompile(source: string): readonly string[] {
+  const { featureName, patterns } = parse(source);
+  const rendered = renderFeatureFile({ featureName: featureName ?? "", patterns });
+  return compileAgainstRegistrar(rendered);
+}
+
+describe("render → compiles against the real FeatureRegistrar type", () => {
+  test("compile check has teeth: an unknown registrar method is reported", () => {
+    const diagnostics = compileAgainstRegistrar(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("teeth-check", (r) => {
+  r.methodThatDoesNotExist({ nope: true });
+});
+`);
+    expect(diagnostics.length).toBeGreaterThan(0);
+    expect(diagnostics.join("\n")).toContain("methodThatDoesNotExist");
+  }, 20_000);
+
+  test("positive control: a minimal always-matched-the-real-shape fixture compiles clean", () => {
+    const diagnostics = compileAgainstRegistrar(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("teeth-check-positive", (r) => {
+  r.systemScope();
+  r.describe("Minimal fixture proving the harness returns [] on real success.");
+  r.toggleable({ default: true });
+});
+`);
+    expect(diagnostics).toEqual([]);
+  }, 20_000);
+
+  test("STATIC_FEATURE's rendered header-data patterns compile clean", () => {
+    expect(renderAndCompile(STATIC_FEATURE)).toEqual([]);
+  }, 20_000);
+});
+
+// One self-contained, compile-clean fixture per remaining pattern kind not
+// already exercised above (STATIC_FEATURE / MIXED_FEATURE / HOOK_ALL_OF /
+// SCREEN_WITH_NAV / DEFINE_EVENT_WITH_MIGRATIONS). Deliberately separate
+// from the parse-roundtrip fixtures above: those were written to test
+// parse/render symmetry, not to be type-correct (e.g. DEFINE_EVENT_WITH_
+// MIGRATIONS_FEATURE uses `z` without importing it) — reusing them here
+// would produce diagnostics unrelated to the registrar shape and defeat the
+// point of an exact-match assertion.
+//
+// RAW_REF_FEATURE and the "unknown" pattern kind are excluded on purpose:
+// raw-ref sentinels reference symbols that don't exist by design, and
+// "unknown" is the parser's catch-all bucket for unrecognized r.calls, not
+// a real user-authored pattern.
+const MANIFEST_AND_CONFIG_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+defineFeature("catalog", (r) => {
+  r.systemScope();
+  r.describe("Product catalog and pricing.");
+  r.optionalRequires("promotions");
+  r.uiHints({ displayLabel: "Catalog", category: "Commerce", recommended: true });
+  r.readsConfig("auth.smtpHost");
+  r.translations({ keys: { en: { title: "Catalog" } } });
+  r.useExtension("audit-log", "item");
+  r.extendsRegistrar("audit-log", {});
+  r.envSchema(z.object({ CATALOG_API_KEY: z.string() }));
+  r.usesApi("compliance.forTenant");
+  r.exposesApi("catalog.pricingFor");
+});
+`;
+
+// r.projection is deliberately excluded here: its `table` field (a Drizzle
+// table reference) is dropped by the feature-ast renderer independent of
+// the object-form/positional-form issue this fixture targets — a
+// pre-existing, separately tracked gap (public-api-registrar-consolidation
+// plan doc, kumiko-platform). multiStreamProjection below covers the
+// `apply`-map shape without hitting it (its `table` is optional).
+const INTEGRATION_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("fulfillment", (r) => {
+  r.job("reconcile-counts", { trigger: { manual: true } }, async (payload, context) => {
+    console.log(payload, context);
+  });
+
+  r.notification("itemLowStock", {
+    trigger: { on: "item:lowStock" },
+    recipient: () => null,
+    data: () => ({}),
+  });
+
+  r.authClaims(async () => ({}));
+
+  r.httpRoute({
+    method: "GET",
+    path: "/fulfillment/feed.xml",
+    handler: (c) => c.text("ok"),
+  });
+
+  r.multiStreamProjection({
+    name: "item-audit",
+    apply: {
+      "item.created": async (event, tx, ctx) => {
+        console.log(event, tx, ctx);
+      },
+    },
+  });
+
+  r.workspace({ id: "ops", label: "fulfillment:workspace.ops" });
+
+  r.treeActions({ list: {} });
+});
+`;
+
+describe("render → compiles against the real FeatureRegistrar type — full pattern-kind coverage", () => {
+  test("manifest/config-only patterns compile clean", () => {
+    expect(renderAndCompile(MANIFEST_AND_CONFIG_FEATURE)).toEqual([]);
+  }, 20_000);
+
+  test("job/notification/httpRoute/projection/workspace patterns compile clean", () => {
+    expect(renderAndCompile(INTEGRATION_FEATURE)).toEqual([]);
+  }, 20_000);
+});

package/src/engine/feature-ast/extractors/index.ts

@@ -29,8 +29,6 @@ export {
   collectScreenOpaqueProps,
   extractAuthClaims,
   extractDefineEvent,
-  extractEntityHook,
-  extractEventMigration,
   extractHook,
   extractHttpRoute,
   extractJob,
@@ -40,7 +38,6 @@ export {
   extractQueryHandler,
   extractScreen,
   extractWriteHandler,
-  isEntityHookType,
   isHookType,
   isHttpRouteMethod,
   type ParsedHandlerCall,