@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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 }),
+  });
+}

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

@@ -0,0 +1,234 @@
+import type { CallExpression, Node, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { AccessRule, RateLimitOption } from "../../types/handlers";
+import type { QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "../patterns";
+import type { SourceLocation } from "../source-location";
+import { sourceLocationFromNode } from "../source-location";
+import { readOptionalAccessRule, readOptionalRateLimit } from "./hooks";
+import {
+  type ExtractOutput,
+  fail,
+  findFunctionLiteral,
+  isPlainObject,
+  isRawRefSentinel,
+  ok,
+  readBooleanProperty,
+  readDataLiteralNode,
+} from "./shared";
+
+export type ParsedHandlerCall = {
+  readonly source: 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,
+  methodName: "writeHandler" | "queryHandler" | "streamHandler",
+): ExtractOutput<ParsedHandlerCall> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail(
+      methodName,
+      sourceLocationFromNode(call, sourceFile),
+      "expected at least one argument",
+    );
+  }
+
+  const obj = args.length === 1 ? resolveObjectLiteralArg(first) : undefined;
+  if (obj) {
+    const nameLiteral = obj
+      .getProperty("name")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
+    if (!nameLiteral) {
+      return fail(
+        methodName,
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `name` property",
+      );
+    }
+    const schemaInit = obj
+      .getProperty("schema")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!schemaInit) {
+      return fail(
+        methodName,
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a `schema` property",
+      );
+    }
+    const handlerInit = obj
+      .getProperty("handler")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!handlerInit) {
+      return fail(
+        methodName,
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a `handler` property",
+      );
+    }
+    const fn = findFunctionLiteral(handlerInit);
+    if (!fn) {
+      return fail(
+        methodName,
+        sourceLocationFromNode(call, sourceFile),
+        "handler must be an inline arrow function or function expression",
+      );
+    }
+    const accessInit = obj
+      .getProperty("access")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const access = accessInit ? readOptionalAccessRule(readDataLiteralNode(accessInit)) : undefined;
+    const rateLimitInit = obj
+      .getProperty("rateLimit")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const rateLimit = rateLimitInit
+      ? readOptionalRateLimit(readDataLiteralNode(rateLimitInit))
+      : undefined;
+    const skip = readBooleanProperty(obj, "unsafeSkipTransitionGuard");
+    return ok({
+      source: sourceLocationFromNode(call, sourceFile),
+      handlerName: nameLiteral.getLiteralValue(),
+      schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
+      handlerBody: sourceLocationFromNode(fn, sourceFile),
+      ...(access !== undefined && { access }),
+      ...(rateLimit !== undefined && { rateLimit }),
+      ...(skip === true && { unsafeSkipTransitionGuard: true }),
+    });
+  }
+
+  // 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(
+      methodName,
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be a string literal handler name (or use the object form)",
+    );
+  }
+  const schemaArg = args[1];
+  if (!schemaArg) {
+    return fail(
+      methodName,
+      sourceLocationFromNode(call, sourceFile),
+      "expected a Zod schema as second argument",
+    );
+  }
+  const handlerArg = args[2];
+  if (!handlerArg) {
+    return fail(
+      methodName,
+      sourceLocationFromNode(call, sourceFile),
+      "expected a handler function as third argument",
+    );
+  }
+  const fn = findFunctionLiteral(handlerArg);
+  if (!fn) {
+    return fail(
+      methodName,
+      sourceLocationFromNode(call, sourceFile),
+      "third argument must be an inline arrow function or function expression",
+    );
+  }
+  const optionsArg = args[3];
+  let access: AccessRule | undefined;
+  let rateLimit: RateLimitOption | undefined;
+  if (optionsArg) {
+    const options = readDataLiteralNode(optionsArg);
+    if (isPlainObject(options)) {
+      access = readOptionalAccessRule(options["access"]);
+      rateLimit = readOptionalRateLimit(options["rateLimit"]);
+    }
+  }
+  return ok({
+    source: sourceLocationFromNode(call, sourceFile),
+    handlerName: nameLiteral.getLiteralValue(),
+    schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
+    handlerBody: sourceLocationFromNode(fn, sourceFile),
+    ...(access !== undefined && { access }),
+    ...(rateLimit !== undefined && { rateLimit }),
+  });
+}
+
+export function extractWriteHandler(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<WriteHandlerPattern> {
+  const parsed = parseHandlerCall(call, sourceFile, "writeHandler");
+  if (parsed.kind === "error") return parsed;
+  return ok({
+    kind: "writeHandler",
+    source: parsed.pattern.source,
+    handlerName: parsed.pattern.handlerName,
+    schemaSource: parsed.pattern.schemaSource,
+    handlerBody: parsed.pattern.handlerBody,
+    ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
+    ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
+    ...(parsed.pattern.unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
+  });
+}
+
+function readHandlerFields(parsed: Extract<ExtractOutput<ParsedHandlerCall>, { kind: "pattern" }>) {
+  return {
+    source: parsed.pattern.source,
+    handlerName: parsed.pattern.handlerName,
+    schemaSource: parsed.pattern.schemaSource,
+    handlerBody: parsed.pattern.handlerBody,
+    ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
+    ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
+  };
+}
+
+export function extractQueryHandler(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<QueryHandlerPattern> {
+  const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
+  if (parsed.kind === "error") return parsed;
+  return ok({ kind: "queryHandler", ...readHandlerFields(parsed) });
+}
+
+export function extractStreamHandler(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<StreamHandlerPattern> {
+  const parsed = parseHandlerCall(call, sourceFile, "streamHandler");
+  if (parsed.kind === "error") return parsed;
+  return ok({ kind: "streamHandler", ...readHandlerFields(parsed) });
+}