@cosmicdrift/kumiko-framework 0.146.4 → 0.147.0

package/src/engine/feature-ast/__tests__/fixtures/cross-file-registrar/feature.ts

@@ -0,0 +1,9 @@
+import { registerFooScreens } from "./screens";
+
+// biome-ignore lint/suspicious/noExplicitAny: structural parser test fixture, never executed or type-checked at runtime
+declare function defineFeature(name: string, setup: (r: any) => void): void;
+
+defineFeature("cross-file-registrar", (r) => {
+  r.requires("config");
+  registerFooScreens(r);
+});

package/src/engine/feature-ast/__tests__/fixtures/cross-file-registrar/screens.ts

@@ -0,0 +1,4 @@
+// biome-ignore lint/suspicious/noExplicitAny: structural parser test fixture, never executed or type-checked at runtime
+export function registerFooScreens(r: any) {
+  r.nav({ id: "foo", label: "Foo" });
+}

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

@@ -46,26 +46,36 @@ const FEATURES: readonly RealFeature[] = [
   {
     path: "packages/bundled-features/src/tenant/feature.ts",
     expectedFeatureName: "tenant",
-    recognisedKinds: ["requires", "systemScope"],
-    errorMethodNames: ["entity", "config", "writeHandler", "queryHandler"],
+    // entity + config used to ParseError here: their definitions reference
+    // local consts/factory calls, which readDataLiteralNode now resolves
+    // to a raw-ref sentinel instead of bailing to undefined (#998).
+    recognisedKinds: [
+      "requires",
+      "systemScope",
+      "entity",
+      "config",
+      "writeHandler",
+      "queryHandler",
+    ],
+    errorMethodNames: [],
   },
   {
     path: "packages/bundled-features/src/audit/feature.ts",
     expectedFeatureName: "audit",
-    recognisedKinds: [],
-    errorMethodNames: ["queryHandler"],
+    recognisedKinds: ["queryHandler"],
+    errorMethodNames: [],
   },
   {
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
-    recognisedKinds: ["entityHook"],
-    errorMethodNames: ["unmanagedTable", "writeHandler", "queryHandler", "job"],
+    recognisedKinds: ["entityHook", "writeHandler", "queryHandler"],
+    errorMethodNames: ["unmanagedTable", "job"],
   },
   {
     path: "packages/bundled-features/src/auth-email-password/feature.ts",
     expectedFeatureName: "auth-email-password",
-    recognisedKinds: ["requires"],
-    errorMethodNames: ["writeHandler"],
+    recognisedKinds: ["requires", "writeHandler"],
+    errorMethodNames: [],
   },
 ];
 

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

@@ -11,8 +11,10 @@
 // Designer/AI know the call exists.
 
 import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
 import { Project } from "ts-morph";
-import { parseSourceFile } from "../parse";
+import { isRawRefSentinel, readDataLiteralNode } from "../extractors/shared";
+import { parseFeatureFile, parseSourceFile } from "../parse";
 
 function createProject() {
   return new Project({
@@ -122,6 +124,102 @@ defineFeature("isolated", (r) => {
     expect(result.featureName).toBe("nameOnly");
     expect(result.patterns).toEqual([]);
   });
+
+  test("recurses into a locally declared registrar-wrapper function", () => {
+    const result = parseInline(`
+function registerTaskScreens(registrar) {
+  registrar.entity("task", { fields: {} });
+  registrar.requires("auth");
+}
+defineFeature("wrapped", (r) => {
+  r.systemScope();
+  registerTaskScreens(r);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns.map((p) => p.kind)).toEqual(["systemScope", "entity", "requires"]);
+  });
+
+  test("recurses into a registrar-wrapper declared as a const arrow function", () => {
+    const result = parseInline(`
+const registerTaskScreens = (registrar) => {
+  registrar.entity("task", { fields: {} });
+};
+defineFeature("wrapped", (r) => {
+  registerTaskScreens(r);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "entity", entityName: "task" }]);
+  });
+
+  test("ignores a bare call that does not receive the registrar as an argument", () => {
+    const result = parseInline(`
+function unrelated() {
+  return 1;
+}
+defineFeature("f", (r) => {
+  unrelated();
+  r.systemScope();
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "systemScope" }]);
+  });
+
+  test("does not infinite-loop on a registrar-wrapper cycle", () => {
+    const result = parseInline(`
+function a(registrar) {
+  registrar.systemScope();
+  b(registrar);
+}
+function b(registrar) {
+  a(registrar);
+}
+defineFeature("f", (r) => {
+  a(r);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "systemScope" }]);
+  });
+});
+
+describe("readDataLiteralNode — raw-ref sentinel", () => {
+  function readExpression(source: string) {
+    const project = createProject();
+    const sourceFile = project.createSourceFile("inline.ts", `const __probe__ = (${source});`);
+    const decl = sourceFile.getVariableDeclarationOrThrow("__probe__");
+    return readDataLiteralNode(decl.getInitializerOrThrow());
+  }
+
+  test("Identifier reference resolves to a raw-ref sentinel with the exact source text", () => {
+    const value = readExpression("eventEntity");
+    expect(isRawRefSentinel(value)).toBe(true);
+    expect(value).toEqual({ __raw: "eventEntity" });
+  });
+
+  test("zero-arg call expression resolves to a raw-ref sentinel with the exact source text", () => {
+    const value = readExpression("createInviteBrandingQuery()");
+    expect(isRawRefSentinel(value)).toBe(true);
+    expect(value).toEqual({ __raw: "createInviteBrandingQuery()" });
+  });
+
+  test("member access resolves to a raw-ref sentinel", () => {
+    const value = readExpression("config.timeout");
+    expect(isRawRefSentinel(value)).toBe(true);
+    expect(value).toEqual({ __raw: "config.timeout" });
+  });
+
+  test("a single unresolvable property no longer bubbles the whole object to undefined", () => {
+    const value = readExpression("{ timeout: 30, query: createQuery() }");
+    expect(isRawRefSentinel(value)).toBe(false);
+    expect(value).toEqual({ timeout: 30, query: { __raw: "createQuery()" } });
+  });
 });
 
 // =============================================================================
@@ -143,12 +241,26 @@ defineFeature("f", (r) => {
     expect(result.errors).toEqual([]);
   });
 
-  test("emits a ParseError when an argument is not a string literal", () => {
+  test("resolves a local const identifier arg via the raw-ref sentinel (#1009)", () => {
     const result = parseInline(`
 const dep = "auth";
 defineFeature("f", (r) => {
   r.requires(dep);
 });
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "requires",
+      featureNames: [{ __raw: "dep" }],
+    });
+    expect(result.errors).toEqual([]);
+  });
+
+  test("emits a ParseError when an argument cannot be resolved at all", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.requires(5);
+});
 `);
 
     expect(result.patterns).toEqual([]);
@@ -170,6 +282,21 @@ defineFeature("f", (r) => {
       featureNames: ["billing"],
     });
   });
+
+  test("keeps a computed feature-name arg as a raw-ref sentinel instead of failing (#1009)", () => {
+    const result = parseInline(`
+const someFeature = { name: "billing" };
+defineFeature("f", (r) => {
+  r.optionalRequires(someFeature.name);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "optionalRequires",
+      featureNames: [{ __raw: "someFeature.name" }],
+    });
+    expect(result.errors).toEqual([]);
+  });
 });
 
 describe("extractReadsConfig", () => {
@@ -185,6 +312,21 @@ defineFeature("f", (r) => {
       qualifiedKeys: ["auth:config:jwt-ttl", "tenant:config:locale"],
     });
   });
+
+  test("keeps a computed key arg as a raw-ref sentinel instead of failing (#1009)", () => {
+    const result = parseInline(`
+const cfg = { key: "auth:config:jwt-ttl" };
+defineFeature("f", (r) => {
+  r.readsConfig(cfg.key, "tenant:config:locale");
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "readsConfig",
+      qualifiedKeys: [{ __raw: "cfg.key" }, "tenant:config:locale"],
+    });
+    expect(result.errors).toEqual([]);
+  });
 });
 
 describe("extractSystemScope", () => {
@@ -269,6 +411,40 @@ defineFeature("f", (r) => {
     expect(result.errors).toEqual([]);
   });
 
+  test("keeps an unresolved const reference as a raw-ref sentinel instead of erroring", () => {
+    const result = parseInline(`
+const eventEntity = { fields: { name: { type: "text" } } };
+defineFeature("f", (r) => {
+  r.entity("event", eventEntity);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "event",
+      definition: { __raw: "eventEntity" },
+    });
+  });
+
+  test("keeps a factory call reference inside a nested property as a raw-ref sentinel", () => {
+    const result = parseInline(`
+function buildFields() {
+  return { name: { type: "text" } };
+}
+defineFeature("f", (r) => {
+  r.entity("task", { fields: buildFields() });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "task",
+      definition: { fields: { __raw: "buildFields()" } },
+    });
+  });
+
   test("walks through `as const` and `satisfies` wrappers", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
@@ -681,6 +857,40 @@ defineFeature("f", (r) => {
       access: { openToAll: true },
     });
   });
+
+  test("resolves a same-file identifier arg to its object-literal form (#1007)", () => {
+    const result = parseInline(`
+const h = {
+  name: "task:archive",
+  schema: z.object({ id: z.string() }),
+  handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
+};
+defineFeature("f", (r) => {
+  r.writeHandler(h);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:archive",
+    });
+    expect(result.errors).toEqual([]);
+  });
+
+  test("keeps an unresolvable ref (import, factory call) as an opaque pattern instead of failing (#1007)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler(eventCreateHandler);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: undefined,
+      source: { raw: "r.writeHandler(eventCreateHandler)" },
+    });
+    expect(result.errors).toEqual([]);
+  });
 });
 
 describe("extractQueryHandler", () => {
@@ -886,3 +1096,82 @@ defineFeature("f", (r) => {
     });
   });
 });
+
+// =============================================================================
+// Regression — show-pony-shaped feature (#998)
+// =============================================================================
+// Mirrors the real-world idioms from show-pony/src/features/show-pony/feature.ts
+// that motivated #998 — inline here (not the live external repo path) so this
+// test doesn't depend on the show-pony checkout being present in this repo's CI.
+
+describe("show-pony-shaped feature (regression, #998)", () => {
+  const result = parseInline(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { eventEntity } from "./schema";
+import { eventCreateHandler } from "./handlers/event-create.write";
+import { createInviteBrandingQuery } from "./handlers/invite-branding.query";
+import { registerShowPonyScreens } from "./register/screens";
+
+const someFeature = { name: "mail-foundation" };
+
+defineFeature("showpony", (r) => {
+  r.requires(someFeature.name, "config");
+  r.entity("event", eventEntity);
+  r.writeHandler(eventCreateHandler);
+  r.queryHandler(createInviteBrandingQuery());
+  registerShowPonyScreens(r);
+});
+`);
+
+  test("requires()'s computed name and entity's imported const resolve via the raw-ref sentinel (#998/#1009 fix)", () => {
+    expect(result.patterns[0]).toMatchObject({
+      kind: "requires",
+      featureNames: [{ __raw: "someFeature.name" }, "config"],
+    });
+    expect(result.patterns[1]).toMatchObject({
+      kind: "entity",
+      entityName: "event",
+      definition: { __raw: "eventEntity" },
+    });
+  });
+
+  test("writeHandler/queryHandler(handlerRef) resolve as opaque patterns (#998/#1007 fix)", () => {
+    expect(result.patterns).toMatchObject([
+      { kind: "requires" },
+      { kind: "entity" },
+      { kind: "writeHandler", handlerName: undefined },
+      { kind: "queryHandler", handlerName: undefined },
+    ]);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("an imported registrar-wrapper stays invisible when its file can't be resolved (in-memory project, #1008)", () => {
+    // parseInline uses an in-memory ts-morph Project — "./register/screens"
+    // isn't a real file, so getModuleSpecifierSourceFile() returns
+    // undefined and the wrapper is skipped like any other unresolvable
+    // call. Real cross-file resolution against on-disk files is covered by
+    // the parseFeatureFile fixture tests below.
+    expect(result.patterns.some((p) => p.kind === "screen" || p.kind === "nav")).toBe(false);
+  });
+});
+
+describe("cross-file registrar-wrapper resolution against a real filesystem Project (#1008)", () => {
+  const fixture = resolve(__dirname, "fixtures/cross-file-registrar/feature.ts");
+  const result = parseFeatureFile(fixture);
+
+  test("resolves the imported wrapper and recognises the nav pattern it registers", () => {
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([
+      { kind: "requires", featureNames: ["config"] },
+      { kind: "nav", definition: { id: "foo", label: "Foo" } },
+    ]);
+  });
+
+  test("the resolved pattern's source points at the imported file, not the entry file", () => {
+    const navPattern = result.patterns.find((p) => p.kind === "nav");
+    expect(navPattern?.source.file).toBe(
+      resolve(__dirname, "fixtures/cross-file-registrar/screens.ts"),
+    );
+    expect(navPattern?.source.file).not.toBe(fixture);
+  });
+});

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

@@ -120,7 +120,7 @@ describe("FeaturePatcher — typed add helpers for mixed (closure-bearing) patte
     expect(pattern?.kind).toBe("writeHandler");
     if (pattern?.kind === "writeHandler") {
       expect(pattern.handlerName).toBe("task:create");
-      expect(pattern.handlerBody.raw).toContain("isSuccess: true");
+      expect(pattern.handlerBody?.raw).toContain("isSuccess: true");
       expect(pattern.access).toMatchObject({ roles: ["user"] });
     }
   });

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

@@ -237,6 +237,79 @@ 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";
+
+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.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: "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.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);

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

@@ -33,7 +33,7 @@ export function extractRequires(
   return ok({
     kind: "requires",
     source: sourceLocationFromNode(call, sourceFile),
-    featureNames: names,
+    featureNames: names as readonly string[],
   });
 }
 
@@ -52,7 +52,7 @@ export function extractOptionalRequires(
   return ok({
     kind: "optionalRequires",
     source: sourceLocationFromNode(call, sourceFile),
-    featureNames: names,
+    featureNames: names as readonly string[],
   });
 }
 
@@ -71,7 +71,7 @@ export function extractReadsConfig(
   return ok({
     kind: "readsConfig",
     source: sourceLocationFromNode(call, sourceFile),
-    qualifiedKeys: keys,
+    qualifiedKeys: keys as readonly string[],
   });
 }
 

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

@@ -31,6 +31,7 @@ import {
   fail,
   findFunctionLiteral,
   isPlainObject,
+  isRawRefSentinel,
   ok,
   readBooleanProperty,
   readDataLiteralNode,
@@ -408,14 +409,29 @@ export function extractAuthClaims(
 
 export type ParsedHandlerCall = {
   readonly source: SourceLocation;
-  readonly handlerName: string;
-  readonly schemaSource: SourceLocation;
-  readonly handlerBody: SourceLocation;
+  readonly handlerName?: string;
+  readonly schemaSource?: SourceLocation;
+  readonly handlerBody?: SourceLocation;
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
 };
 
+/**
+ * Resolves an argument standing in for a handler-call's object-form body:
+ * either it's already an object literal, or a bare identifier declared
+ * locally (same file only) with one as its initializer. Anything else
+ * (imported binding, factory call, ...) is not resolvable here.
+ */
+function resolveObjectLiteralArg(node: Node) {
+  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (direct) return direct;
+  const identifier = node.asKind(SyntaxKind.Identifier);
+  if (!identifier) return undefined;
+  const varDecl = node.getSourceFile().getVariableDeclaration(identifier.getText());
+  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
+}
+
 export function parseHandlerCall(
   call: CallExpression,
   sourceFile: SourceFile,
@@ -431,8 +447,8 @@ export function parseHandlerCall(
     );
   }
 
-  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj && args.length === 1) {
+  const obj = args.length === 1 ? resolveObjectLiteralArg(first) : undefined;
+  if (obj) {
     const nameLiteral = obj
       .getProperty("name")
       ?.asKind(SyntaxKind.PropertyAssignment)
@@ -499,6 +515,16 @@ export function parseHandlerCall(
     });
   }
 
+  // A single reference standing in for the whole handler argument set
+  // (`r.writeHandler(eventCreateHandler)`, `r.queryHandler(someQuery())`)
+  // that resolveObjectLiteralArg above couldn't turn into an object literal
+  // (imported binding, factory call, ...). Keep it recognised as this kind
+  // instead of ParseErroring — see #1007. Opaque: renderWriteHandler/
+  // renderQueryHandler re-emit `source.raw` verbatim when handlerName is
+  // undefined.
+  if (args.length === 1 && isRawRefSentinel(readDataLiteralNode(first))) {
+    return ok({ source: sourceLocationFromNode(call, sourceFile) });
+  }
   const nameLiteral = first.asKind(SyntaxKind.StringLiteral);
   if (!nameLiteral) {
     return fail(
@@ -1341,11 +1367,20 @@ export function extractScreen(
   }
   const obj = arg.asKind(SyntaxKind.ObjectLiteralExpression);
   if (!obj) {
-    return fail(
-      "screen",
-      sourceLocationFromNode(call, sourceFile),
-      "argument must be an inline object literal",
-    );
+    const raw = readDataLiteralNode(arg);
+    if (!isRawRefSentinel(raw)) {
+      return fail(
+        "screen",
+        sourceLocationFromNode(call, sourceFile),
+        "argument must be an inline object literal",
+      );
+    }
+    return ok({
+      kind: "screen",
+      source: sourceLocationFromNode(call, sourceFile),
+      definition: raw as unknown as ScreenDefinition,
+      opaqueProps: {} as OpaquePropMap,
+    });
   }
   const opaqueProps: Record<string, SourceLocation> = {};
   collectScreenOpaqueProps(obj, "", sourceFile, opaqueProps);