@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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) {
@@ -196,6 +206,15 @@ defineFeature("workflow", (r) => {
     { access: { openToAll: true } },
   );
 
+  r.streamHandler(
+    "step:stream",
+    z.object({ prompt: z.string() }),
+    async function* (input, ctx) {
+      yield "token";
+    },
+    { access: { roles: ["user"] } },
+  );
+
   r.hook("postSave", "step", async (event, ctx) => {
     console.log("step saved");
   });
@@ -237,6 +256,83 @@ describe("render → parse roundtrip — mixed patterns (header data + opaque bo
 // guarantee than parse → render → parse, because it pins that the renderer
 // never depends on the input file's whitespace — its output is deterministic
 // from the parsed FeaturePattern shape alone.
+const RAW_REF_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { chatCompleteHandler } from "./handlers";
+
+const eventEntity = {
+  fields: { name: { type: "text", required: true } },
+};
+
+function buildFields() {
+  return { title: { type: "text" } };
+}
+
+const someFeature = { name: "mail-foundation" };
+
+const eventListScreen = {
+  id: "event-list",
+  type: "entityList",
+  entity: "event",
+};
+
+function makeHandler() {
+  return { name: "task:create", schema: null, handler: () => {} };
+}
+
+defineFeature("refs", (r) => {
+  r.requires(someFeature.name, "config");
+  r.entity("event", eventEntity);
+  r.entity("task", { fields: buildFields() });
+  r.writeHandler(makeHandler());
+  r.streamHandler(chatCompleteHandler);
+  r.screen(eventListScreen);
+});
+`;
+
+describe("render → parse roundtrip — unresolved references (raw-ref sentinel)", () => {
+  const initial = parse(RAW_REF_FEATURE);
+
+  test("parses requires + both entities + the opaque handler without error, keeping references unresolved", () => {
+    expect(initial.patterns).toMatchObject([
+      { kind: "requires", featureNames: [{ __raw: "someFeature.name" }, "config"] },
+      { kind: "entity", entityName: "event", definition: { __raw: "eventEntity" } },
+      { kind: "entity", entityName: "task", definition: { fields: { __raw: "buildFields()" } } },
+      { kind: "writeHandler", handlerName: undefined },
+      { kind: "streamHandler", handlerName: undefined },
+      { kind: "screen", definition: { __raw: "eventListScreen" } },
+    ]);
+  });
+
+  test("rendered output re-emits references verbatim, never inlines them", () => {
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    expect(rendered).toContain("someFeature.name");
+    expect(rendered).toContain("eventEntity");
+    expect(rendered).toContain("buildFields()");
+    expect(rendered).toContain("r.writeHandler(makeHandler())");
+    expect(rendered).toContain("r.streamHandler(chatCompleteHandler)");
+    expect(rendered).toContain("r.screen(eventListScreen);");
+    // Would only appear if buildFields()'s return value got inlined.
+    expect(rendered).not.toContain("title:");
+    expect(rendered).not.toContain("mail-foundation");
+    expect(rendered).not.toContain("task:create");
+    // Would only appear if the screen ref got resolved/inlined.
+    expect(rendered).not.toContain("entityList");
+  });
+
+  test("pattern shape survives a full render → reparse cycle", () => {
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+  });
+});
+
 describe("render idempotence", () => {
   test("rendered file → parse → render === rendered file", () => {
     const initial = parse(STATIC_FEATURE);
@@ -285,3 +381,282 @@ describe("renderPattern — single-pattern shape", () => {
     expect(out).toBe('r.metric({ name: "requests", type: "counter" });');
   });
 });
+
+// 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
+// cycle, not just a TS compile of the framework itself. r.screen()'s `nav`
+// sugar is a generic nested object on an already-generic pattern (no
+// per-field extractor/renderer), so this is the cheap case — but proving
+// it beats assuming it.
+const SCREEN_WITH_NAV_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("shop", (r) => {
+  r.entity("product", { fields: { name: { type: "text" } } });
+  r.screen({
+    id: "products",
+    type: "entityList",
+    entity: "product",
+    columns: ["name"],
+    nav: { label: "shop:nav.products", icon: "box", order: 5 },
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () => {
+  test("nested nav object survives parse → render → parse unchanged", () => {
+    const initial = parse(SCREEN_WITH_NAV_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 screenPattern = reparsed.patterns.find((p) => p.kind === "screen");
+    expect(screenPattern?.kind).toBe("screen");
+    if (screenPattern?.kind === "screen") {
+      expect(screenPattern.definition).toMatchObject({
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    }
+  });
+});
+
+const DEFINE_EVENT_WITH_MIGRATIONS_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+defineFeature("billing", (r) => {
+  r.defineEvent("invoicePaid", z.object({ totalCents: z.number() }), {
+    version: 2,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        transform: (payload: unknown) => ({ totalCents: Math.round((payload as { total: number }).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);
+
+  test("r.defineEvent's rendered migrations array compiles against the real registrar", () => {
+    expect(renderAndCompile(DEFINE_EVENT_WITH_MIGRATIONS_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);
+});