@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/engine/feature-ast/extractors/projections-screens.ts

@@ -0,0 +1,269 @@
+import type { CallExpression, Node, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { RunIn } from "../../types/config";
+import type { MspErrorMode } from "../../types/projection";
+import type { ScreenDefinition } from "../../types/screen";
+import type {
+  MultiStreamProjectionPattern,
+  OpaquePropMap,
+  ProjectionPattern,
+  ScreenPattern,
+} from "../patterns";
+import { SCREEN_OPAQUE_MARKER } from "../patterns";
+import type { SourceLocation } from "../source-location";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  findFunctionLiteral,
+  isPlainObject,
+  isRawRefSentinel,
+  ok,
+  readDataLiteralNode,
+  readNameOrRefOrList,
+  readPropertyKey,
+} from "./shared";
+
+export function readApplyBodies(
+  defObj: ReturnType<Node["asKind"]>,
+  sourceFile: SourceFile,
+): Record<string, SourceLocation> | undefined {
+  if (!defObj) return undefined;
+  const obj = defObj.asKind?.(SyntaxKind.ObjectLiteralExpression);
+  if (!obj) return undefined;
+  const applyObj = obj
+    .getProperty("apply")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!applyObj) return undefined;
+  const out: Record<string, SourceLocation> = {};
+  for (const prop of applyObj.getProperties()) {
+    const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+    if (!propAssign) return undefined;
+    const init = propAssign.getInitializer();
+    if (!init) return undefined;
+    const fn = findFunctionLiteral(init);
+    if (!fn) return undefined;
+    out[readPropertyKey(propAssign)] = sourceLocationFromNode(fn, sourceFile);
+  }
+  return out;
+}
+
+export function extractProjection(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ProjectionPattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!arg) {
+    return fail(
+      "projection",
+      sourceLocationFromNode(call, sourceFile),
+      "argument must be an inline ProjectionDefinition object",
+    );
+  }
+  const nameLit = arg
+    .getProperty("name")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  if (!nameLit) {
+    return fail(
+      "projection",
+      sourceLocationFromNode(call, sourceFile),
+      "name must be a string literal",
+    );
+  }
+  const sourceInit = arg
+    .getProperty("source")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  if (!sourceInit) {
+    return fail(
+      "projection",
+      sourceLocationFromNode(call, sourceFile),
+      "missing `source` property",
+    );
+  }
+  const sourceEntity = readNameOrRefOrList(sourceInit);
+  if (!sourceEntity) {
+    return fail(
+      "projection",
+      sourceLocationFromNode(call, sourceFile),
+      "source must be a string literal or array of string literals",
+    );
+  }
+  const applyBodies = readApplyBodies(arg, sourceFile);
+  if (!applyBodies) {
+    return fail(
+      "projection",
+      sourceLocationFromNode(call, sourceFile),
+      "apply must be an inline object map of event-type → function",
+    );
+  }
+  return ok({
+    kind: "projection",
+    source: sourceLocationFromNode(call, sourceFile),
+    name: nameLit.getLiteralValue(),
+    sourceEntity,
+    applyBodies,
+  });
+}
+
+export function extractMultiStreamProjection(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<MultiStreamProjectionPattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!arg) {
+    return fail(
+      "multiStreamProjection",
+      sourceLocationFromNode(call, sourceFile),
+      "argument must be an inline MultiStreamProjectionDefinition object",
+    );
+  }
+  const nameLit = arg
+    .getProperty("name")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  if (!nameLit) {
+    return fail(
+      "multiStreamProjection",
+      sourceLocationFromNode(call, sourceFile),
+      "name must be a string literal",
+    );
+  }
+  const applyBodies = readApplyBodies(arg, sourceFile);
+  if (!applyBodies) {
+    return fail(
+      "multiStreamProjection",
+      sourceLocationFromNode(call, sourceFile),
+      "apply must be an inline object map of event-type → function",
+    );
+  }
+  const errorModeInit = arg
+    .getProperty("errorMode")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  const errorMode = errorModeInit ? readDataLiteralNode(errorModeInit) : undefined;
+  const runInLit = arg
+    .getProperty("runIn")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  const runIn = runInLit ? (runInLit.getLiteralValue() as RunIn) : undefined;
+  const deliveryLit = arg
+    .getProperty("delivery")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  const delivery = deliveryLit
+    ? (deliveryLit.getLiteralValue() as "shared" | "per-instance")
+    : undefined;
+  return ok({
+    kind: "multiStreamProjection",
+    source: sourceLocationFromNode(call, sourceFile),
+    name: nameLit.getLiteralValue(),
+    applyBodies,
+    ...(isPlainObject(errorMode) && { errorMode: errorMode as MspErrorMode }),
+    ...(runIn !== undefined && { runIn }),
+    ...(delivery !== undefined && { delivery }),
+  });
+}
+
+export function collectScreenOpaqueProps(
+  node: Node,
+  path: string,
+  sourceFile: SourceFile,
+  out: Record<string, SourceLocation>,
+): void {
+  const fn = findFunctionLiteral(node);
+  if (fn) {
+    out[path] = sourceLocationFromNode(fn, sourceFile);
+  } else if (node.isKind(SyntaxKind.ObjectLiteralExpression)) {
+    for (const prop of node.getProperties()) {
+      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+      if (!propAssign) continue;
+      const init = propAssign.getInitializer();
+      if (!init) continue;
+      const key = readPropertyKey(propAssign);
+      const childPath = path ? `${path}.${key}` : key;
+      collectScreenOpaqueProps(init, childPath, sourceFile, out);
+    }
+  } else if (node.isKind(SyntaxKind.ArrayLiteralExpression)) {
+    node.getElements().forEach((el, idx) => {
+      collectScreenOpaqueProps(el, `${path}.${idx}`, sourceFile, out);
+    });
+  }
+}
+
+export function readScreenStatic(node: Node): unknown {
+  if (findFunctionLiteral(node)) return SCREEN_OPAQUE_MARKER;
+  const obj = node.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (obj) {
+    const out: Record<string, unknown> = {};
+    for (const prop of obj.getProperties()) {
+      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+      if (!propAssign) continue;
+      const init = propAssign.getInitializer();
+      if (!init) continue;
+      out[readPropertyKey(propAssign)] = readScreenStatic(init);
+    }
+    return out;
+  }
+  const arr = node.asKind(SyntaxKind.ArrayLiteralExpression);
+  if (arr) {
+    return arr.getElements().map(readScreenStatic);
+  }
+  const value = readDataLiteralNode(node);
+  if (value === undefined) return SCREEN_OPAQUE_MARKER;
+  return value;
+}
+
+export function extractScreen(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ScreenPattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "screen",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a ScreenDefinition object as first argument",
+    );
+  }
+  const obj = arg.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!obj) {
+    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);
+  const definition = readScreenStatic(obj);
+  if (!isPlainObject(definition)) {
+    return fail(
+      "screen",
+      sourceLocationFromNode(call, sourceFile),
+      "definition could not be read structurally",
+    );
+  }
+  return ok({
+    kind: "screen",
+    source: sourceLocationFromNode(call, sourceFile),
+    definition: definition as ScreenDefinition,
+    opaqueProps: opaqueProps as OpaquePropMap,
+  });
+}

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/round5.ts

@@ -95,7 +95,7 @@ export function extractExposesApi(
   });
 }
 
-export function extractUnmanagedTable(
+export function extractStoreTable(
   call: CallExpression,
   sourceFile: SourceFile,
 ): ExtractOutput<never> {
@@ -104,8 +104,8 @@ export function extractUnmanagedTable(
   // so there is nothing to extract statically. A clean ParseError (not
   // UnknownPattern) marks it design-time-unreadable, like entity-by-identifier.
   return fail(
-    "unmanagedTable",
+    "storeTable",
     sourceLocationFromNode(call, sourceFile),
-    "unmanagedTable meta is a factory/identifier argument, not a static literal",
+    "storeTable meta is a factory/identifier argument, not a static literal",
   );
 }

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

@@ -1,15 +1,8 @@
 import type { CallExpression, SourceFile } from "ts-morph";
 import type { TreeActionDef } from "../../types/tree-node";
-import type { TreeActionsPattern, TreePattern } from "../patterns";
+import type { TreeActionsPattern } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
-import {
-  type ExtractOutput,
-  fail,
-  findFunctionLiteral,
-  isPlainObject,
-  ok,
-  readDataLiteralNode,
-} from "./shared";
+import { type ExtractOutput, fail, isPlainObject, ok, readDataLiteralNode } from "./shared";
 
 export function extractTreeActions(
   call: CallExpression,
@@ -37,30 +30,3 @@ export function extractTreeActions(
     definitions: definitions as Readonly<Record<string, TreeActionDef>>,
   });
 }
-
-export function extractTree(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<TreePattern> {
-  const arg = call.getArguments()[0];
-  if (!arg) {
-    return fail(
-      "tree",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a tree-provider function as first argument",
-    );
-  }
-  const fn = findFunctionLiteral(arg);
-  if (!fn) {
-    return fail(
-      "tree",
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be an inline arrow function or function expression",
-    );
-  }
-  return ok({
-    kind: "tree",
-    source: sourceLocationFromNode(call, sourceFile),
-    providerBody: sourceLocationFromNode(fn, sourceFile),
-  });
-}

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

@@ -47,6 +47,25 @@ export function readBooleanProperty(
   return undefined;
 }
 
+/**
+ * Marks a value the parser could not resolve into a literal (an Identifier
+ * reference, a call expression, ...) while preserving its exact source text.
+ * `renderValue` re-emits `__raw` verbatim instead of re-serializing the
+ * value, so round-tripping a reference like `eventEntity` never expands it
+ * into an inlined object literal.
+ */
+export type RawRefSentinel = { readonly __raw: string };
+
+export function isRawRefSentinel(value: unknown): value is RawRefSentinel {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    "__raw" in value &&
+    typeof (value as { __raw: unknown }).__raw === "string"
+  );
+}
+
 export function readDataLiteralNode(node: Node): unknown {
   const kind = node.getKind();
   switch (kind) {
@@ -103,11 +122,50 @@ export function readDataLiteralNode(node: Node): unknown {
       return readDataLiteralNode(
         node.asKindOrThrow(SyntaxKind.ParenthesizedExpression).getExpression(),
       );
+    case SyntaxKind.Identifier:
+    case SyntaxKind.CallExpression:
+    case SyntaxKind.PropertyAccessExpression:
+      // Unresolvable reference (const identifier, factory call, member access).
+      // Keep the exact source text so renderValue can re-emit it verbatim —
+      // resolving/inlining it would silently rewrite the source on the next
+      // parse->render roundtrip (see readDataLiteralNode doc above).
+      return { __raw: node.getText() } satisfies RawRefSentinel;
     default:
       return undefined;
   }
 }
 
+/**
+ * A node's literal string value, or the raw-ref sentinel when it resolves to
+ * an unresolvable identifier/factory-call/member-access (see
+ * readDataLiteralNode). undefined for anything else (number, boolean, ...).
+ */
+export function readStringOrRaw(node: Node): string | RawRefSentinel | undefined {
+  const value = readDataLiteralNode(node);
+  if (typeof value === "string") return value;
+  if (isRawRefSentinel(value)) return value;
+  return undefined;
+}
+
+/**
+ * Like readStringLiteralArgs, but an argument that resolves to a raw-ref
+ * sentinel is kept as that sentinel instead of failing the whole call. Used
+ * where a value stands in for a single name/key and inlining its resolved
+ * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`
+ * — see #1009).
+ */
+export function readStringOrRawArgs(
+  call: CallExpression,
+): readonly (string | RawRefSentinel)[] | undefined {
+  const out: (string | RawRefSentinel)[] = [];
+  for (const arg of call.getArguments()) {
+    const value = readStringOrRaw(arg);
+    if (value === undefined) return undefined;
+    out.push(value);
+  }
+  return out;
+}
+
 export { isPlainObject } from "../../../utils/is-plain-object";
 
 export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignment): string {
@@ -150,7 +208,7 @@ export function readNameOrRefOrList(node: Node): string | readonly string[] | un
 export function readVarargsOrArrayProp(
   call: CallExpression,
   arrayPropName: "features" | "keys",
-): readonly string[] | undefined {
+): readonly (string | RawRefSentinel)[] | undefined {
   const args = call.getArguments();
   if (args.length === 1) {
     const obj = args[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
@@ -162,15 +220,15 @@ export function readVarargsOrArrayProp(
       if (propInit) {
         const arr = propInit.asKind(SyntaxKind.ArrayLiteralExpression);
         if (!arr) return undefined;
-        const out: string[] = [];
+        const out: (string | RawRefSentinel)[] = [];
         for (const el of arr.getElements()) {
-          const lit = el.asKind(SyntaxKind.StringLiteral);
-          if (!lit) return undefined;
-          out.push(lit.getLiteralValue());
+          const value = readStringOrRaw(el);
+          if (value === undefined) return undefined;
+          out.push(value);
         }
         return out;
       }
     }
   }
-  return readStringLiteralArgs(call);
+  return readStringOrRawArgs(call);
 }

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

@@ -27,8 +27,6 @@ export type {
   AddConfigArgs,
   AddDefineEventArgs,
   AddEntityArgs,
-  AddEntityHookArgs,
-  AddEventMigrationArgs,
   AddHookArgs,
   AddHttpRouteArgs,
   AddJobArgs,
@@ -45,6 +43,7 @@ export type {
   AddRequiresArgs,
   AddScreenArgs,
   AddSecretArgs,
+  AddStreamHandlerArgs,
   AddToggleableArgs,
   AddTranslationsArgs,
   AddUseExtensionArgs,
@@ -59,10 +58,8 @@ export type {
   ConfigPattern,
   DefineEventPattern,
   Editability,
-  EntityHookPattern,
   // Static patterns
   EntityPattern,
-  EventMigrationPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
   FeaturePatternKind,
@@ -83,6 +80,7 @@ export type {
   // Mixed patterns
   ScreenPattern,
   SecretPattern,
+  StreamHandlerPattern,
   SystemScopePattern,
   ToggleablePattern,
   TranslationsPattern,