@cosmicdrift/kumiko-framework 0.155.1 → 0.156.0

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

@@ -709,6 +709,93 @@ defineFeature("f", (r) => {
       upsertKey: "id",
     });
   });
+
+  test("object form captures entity, data and upsertKey", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({
+    entity: "status",
+    data: [{ id: "open" }, { id: "closed" }],
+    upsertKey: "id",
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "referenceData",
+      entityName: "status",
+      data: [{ id: "open" }, { id: "closed" }],
+      upsertKey: "id",
+    });
+  });
+
+  test("accepts an inline { name: '...' } entity ref, both forms", () => {
+    const positional = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ name: "status" }, [{ id: "open" }]);
+});
+`);
+    expect(positional.patterns[0]).toMatchObject({ kind: "referenceData", entityName: "status" });
+
+    const objectForm = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ entity: { name: "status" }, data: [{ id: "open" }] });
+});
+`);
+    expect(objectForm.patterns[0]).toMatchObject({ kind: "referenceData", entityName: "status" });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData();
+});
+`);
+
+    expect(result.patterns).toEqual([]);
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when object form is missing the data property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ entity: "status" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when object form's data is not an array of plain objects", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ entity: "status", data: "not-an-array" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when the positional data argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when positional upsertKey option is not a string", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status", [{ id: "open" }], { upsertKey: 123 });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
 });
 
 describe("extractUseExtension", () => {
@@ -740,6 +827,89 @@ defineFeature("f", (r) => {
       options: { mode: "verbose" },
     });
   });
+
+  test("object form captures name, entity ref and options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit", entity: "task", options: { mode: "verbose" } });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "useExtension",
+      extensionName: "audit",
+      entityName: "task",
+      options: { mode: "verbose" },
+    });
+  });
+
+  test("accepts an inline { name: '...' } entity ref, both forms", () => {
+    const positional = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit", { name: "task" });
+});
+`);
+    expect(positional.patterns[0]).toMatchObject({ kind: "useExtension", entityName: "task" });
+
+    const objectForm = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit", entity: { name: "task" } });
+});
+`);
+    expect(objectForm.patterns[0]).toMatchObject({ kind: "useExtension", entityName: "task" });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension();
+});
+`);
+
+    expect(result.patterns).toEqual([]);
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when object form is missing the entity property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when object form's options is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit", entity: "task", options: "not-an-object" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when the positional entity argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when positional options argument is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit", "task", "not-an-object");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
 });
 
 // =============================================================================

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

@@ -312,6 +312,37 @@ describe("patch coverage for the remaining pattern-kinds", () => {
     removePattern(sf, { kind: "defineEvent", eventName: "itemCreated" });
     expect(parseSourceFile(sf).patterns.find((p) => p.kind === "defineEvent")).toBeUndefined();
   });
+
+  test("add + remove via PatternId for nav (id key)", () => {
+    const sf = makeSourceFile(STARTER);
+    createFeaturePatcher(sf).addNav({
+      definition: { id: "items", label: "Items", screen: "inventory:screen:list" },
+    });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "nav")).toBeDefined();
+    removePattern(sf, { kind: "nav", id: "items" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "nav")).toBeUndefined();
+  });
+
+  test("add + remove via PatternId for workspace (id key)", () => {
+    const sf = makeSourceFile(STARTER);
+    createFeaturePatcher(sf).addWorkspace({ definition: { id: "admin", label: "Admin" } });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "workspace")).toBeDefined();
+    removePattern(sf, { kind: "workspace", id: "admin" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "workspace")).toBeUndefined();
+  });
+
+  test("add + remove via PatternId for extendsRegistrar (extensionName key)", () => {
+    const sf = makeSourceFile(STARTER);
+    addPattern(sf, {
+      kind: "extendsRegistrar",
+      source: SAMPLE_LOC,
+      extensionName: "auditLog",
+      defBody: { ...SAMPLE_LOC, raw: "{ hooks: {} }" },
+    });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "extendsRegistrar")).toBeDefined();
+    removePattern(sf, { kind: "extendsRegistrar", extensionName: "auditLog" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "extendsRegistrar")).toBeUndefined();
+  });
 });
 
 describe("singleton-pattern guards", () => {

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

@@ -448,6 +448,7 @@ describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () =>
 
 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() }), {
@@ -456,7 +457,7 @@ defineFeature("billing", (r) => {
       {
         fromVersion: 1,
         toVersion: 2,
-        transform: (payload) => ({ totalCents: Math.round(payload.total * 100) }),
+        transform: (payload: unknown) => ({ totalCents: Math.round((payload as { total: number }).total * 100) }),
       },
     ],
   });
@@ -556,6 +557,10 @@ defineFeature("teeth-check-positive", (r) => {
   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

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

@@ -0,0 +1,322 @@
+import type { CallExpression, Node, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { DefineEventPattern, NotificationPattern } from "../patterns";
+import type { SourceLocation } from "../source-location";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  findFunctionLiteral,
+  ok,
+  readDataLiteralNode,
+  readNameOrRef,
+  readPropertyKey,
+} from "./shared";
+
+// Reads defineEvent's `migrations` option — either the array-of-steps shape
+// used by hand-authored calls (`[{ fromVersion, toVersion, transform }]`,
+// toVersion is redundant on-disk since it is always fromVersion + 1) or the
+// keyed-object canonical shape the Designer renders (`{ "1": transform }`).
+// Keyed by fromVersion (as a string) → the transform closure's location.
+// Skips malformed entries rather than failing the whole defineEvent extract
+// — same "best-effort, degrade gracefully" posture as readDataLiteralNode.
+function extractEventMigrationsFromArray(
+  arr: Node,
+  sourceFile: SourceFile,
+): Record<string, SourceLocation> {
+  const result: Record<string, SourceLocation> = {};
+  const arrLit = arr.asKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+  for (const el of arrLit.getElements()) {
+    const obj = el.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (!obj) continue;
+    const fromInit = obj
+      .getProperty("fromVersion")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const fromVersion = fromInit ? readDataLiteralNode(fromInit) : undefined;
+    if (typeof fromVersion !== "number") continue;
+    const transformInit = obj
+      .getProperty("transform")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const fn = transformInit ? findFunctionLiteral(transformInit) : undefined;
+    if (!fn) continue;
+    result[String(fromVersion)] = sourceLocationFromNode(fn, sourceFile);
+  }
+  return result;
+}
+
+function extractEventMigrationsFromKeyedObject(
+  objLit: Node,
+  sourceFile: SourceFile,
+): Record<string, SourceLocation> {
+  const result: Record<string, SourceLocation> = {};
+  const obj = objLit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+  for (const prop of obj.getProperties()) {
+    const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+    const initializer = propAssign?.getInitializer();
+    const fn = initializer ? findFunctionLiteral(initializer) : undefined;
+    if (!propAssign || !fn) continue;
+    result[readPropertyKey(propAssign)] = sourceLocationFromNode(fn, sourceFile);
+  }
+  return result;
+}
+
+// Reads defineEvent's `migrations` option — either the array-of-steps shape
+// used by hand-authored calls (`[{ fromVersion, toVersion, transform }]`,
+// toVersion is redundant on-disk since it is always fromVersion + 1) or the
+// keyed-object canonical shape the Designer renders (`{ "1": transform }`).
+// Keyed by fromVersion (as a string) → the transform closure's location.
+// Skips malformed entries rather than failing the whole defineEvent extract
+// — same "best-effort, degrade gracefully" posture as readDataLiteralNode.
+function extractEventMigrationsField(
+  node: Node,
+  sourceFile: SourceFile,
+): Readonly<Record<string, SourceLocation>> | undefined {
+  const result = node.asKind(SyntaxKind.ArrayLiteralExpression)
+    ? extractEventMigrationsFromArray(node, sourceFile)
+    : node.asKind(SyntaxKind.ObjectLiteralExpression)
+      ? extractEventMigrationsFromKeyedObject(node, sourceFile)
+      : undefined;
+  return result && Object.keys(result).length > 0 ? result : undefined;
+}
+
+export function extractDefineEvent(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<DefineEventPattern> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail(
+      "defineEvent",
+      sourceLocationFromNode(call, sourceFile),
+      "expected at least one argument",
+    );
+  }
+
+  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (obj && args.length === 1) {
+    const nameInit = obj
+      .getProperty("name")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
+    if (!nameInit) {
+      return fail(
+        "defineEvent",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `name` property",
+      );
+    }
+    const schemaInit = obj
+      .getProperty("schema")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!schemaInit) {
+      return fail(
+        "defineEvent",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a `schema` property",
+      );
+    }
+    let version: number | undefined;
+    const versionInit = obj
+      .getProperty("version")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (versionInit) {
+      const v = readDataLiteralNode(versionInit);
+      if (typeof v === "number") version = v;
+    }
+    const migrationsInit = obj
+      .getProperty("migrations")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const migrations = migrationsInit
+      ? extractEventMigrationsField(migrationsInit, sourceFile)
+      : undefined;
+    return ok({
+      kind: "defineEvent",
+      source: sourceLocationFromNode(call, sourceFile),
+      eventName: nameInit.getLiteralValue(),
+      schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
+      ...(version !== undefined && { version }),
+      ...(migrations !== undefined && { migrations }),
+    });
+  }
+
+  const nameArg = first.asKind(SyntaxKind.StringLiteral);
+  if (!nameArg) {
+    return fail(
+      "defineEvent",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be a string literal event name (or use the object form)",
+    );
+  }
+  const schemaArg = args[1];
+  if (!schemaArg) {
+    return fail(
+      "defineEvent",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a Zod schema as second argument",
+    );
+  }
+  let version: number | undefined;
+  let migrations: Readonly<Record<string, SourceLocation>> | undefined;
+  const optionsArg = args[2];
+  const optionsObj = optionsArg?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (optionsObj) {
+    const versionInit = optionsObj
+      .getProperty("version")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (versionInit) {
+      const v = readDataLiteralNode(versionInit);
+      if (typeof v === "number") version = v;
+    }
+    const migrationsInit = optionsObj
+      .getProperty("migrations")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (migrationsInit) {
+      migrations = extractEventMigrationsField(migrationsInit, sourceFile);
+    }
+  }
+  return ok({
+    kind: "defineEvent",
+    source: sourceLocationFromNode(call, sourceFile),
+    eventName: nameArg.getLiteralValue(),
+    schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
+    ...(version !== undefined && { version }),
+    ...(migrations !== undefined && { migrations }),
+  });
+}
+
+export function extractNotification(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<NotificationPattern> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail(
+      "notification",
+      sourceLocationFromNode(call, sourceFile),
+      "expected at least one argument",
+    );
+  }
+
+  let nameLiteral: ReturnType<typeof first.asKind<SyntaxKind.StringLiteral>>;
+  let defObj: ReturnType<typeof first.asKind<SyntaxKind.ObjectLiteralExpression>>;
+
+  const firstObj = first.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (firstObj && args.length === 1) {
+    nameLiteral = firstObj
+      .getProperty("name")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
+    if (!nameLiteral) {
+      return fail(
+        "notification",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `name` property",
+      );
+    }
+    defObj = firstObj;
+  } else {
+    nameLiteral = first.asKind(SyntaxKind.StringLiteral);
+    if (!nameLiteral) {
+      return fail(
+        "notification",
+        sourceLocationFromNode(call, sourceFile),
+        "first argument must be a string literal notification name (or use the object form)",
+      );
+    }
+    defObj = args[1]?.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (!defObj) {
+      return fail(
+        "notification",
+        sourceLocationFromNode(call, sourceFile),
+        "second argument must be an inline definition object",
+      );
+    }
+  }
+  const nameArg = nameLiteral;
+  const triggerObj = defObj
+    .getProperty("trigger")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!triggerObj) {
+    return fail(
+      "notification",
+      sourceLocationFromNode(call, sourceFile),
+      "missing or non-object `trigger` property",
+    );
+  }
+  const onInit = triggerObj
+    .getProperty("on")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  const onName = onInit ? readNameOrRef(onInit) : undefined;
+  if (!onName) {
+    return fail(
+      "notification",
+      sourceLocationFromNode(call, sourceFile),
+      "trigger.on must be a string literal or inline { name } object",
+    );
+  }
+  const recipientInit = defObj
+    .getProperty("recipient")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  const recipientFn = recipientInit ? findFunctionLiteral(recipientInit) : undefined;
+  if (!recipientFn) {
+    return fail(
+      "notification",
+      sourceLocationFromNode(call, sourceFile),
+      "recipient must be an inline arrow function or function expression",
+    );
+  }
+  const dataInit = defObj
+    .getProperty("data")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  const dataFn = dataInit ? findFunctionLiteral(dataInit) : undefined;
+  if (!dataFn) {
+    return fail(
+      "notification",
+      sourceLocationFromNode(call, sourceFile),
+      "data must be an inline arrow function or function expression",
+    );
+  }
+  let templates: Record<string, SourceLocation> | undefined;
+  const templatesObj = defObj
+    .getProperty("templates")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (templatesObj) {
+    templates = {};
+    for (const prop of templatesObj.getProperties()) {
+      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+      if (!propAssign) continue;
+      const init = propAssign.getInitializer();
+      if (!init) continue;
+      const tfn = findFunctionLiteral(init);
+      if (!tfn) continue;
+      templates[readPropertyKey(propAssign)] = sourceLocationFromNode(tfn, sourceFile);
+    }
+  }
+  return ok({
+    kind: "notification",
+    source: sourceLocationFromNode(call, sourceFile),
+    notificationName: nameArg.getLiteralValue(),
+    trigger: { on: onName },
+    recipientBody: sourceLocationFromNode(recipientFn, sourceFile),
+    dataBody: sourceLocationFromNode(dataFn, sourceFile),
+    ...(templates !== undefined && { templates }),
+  });
+}