@cosmicdrift/kumiko-framework 0.155.0 → 0.156.0

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

@@ -0,0 +1,222 @@
+import type { CallExpression, Node, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { AccessRule, RateLimitOption } from "../../types/handlers";
+import type { QueryHandlerPattern, 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",
+): 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 }),
+  });
+}
+
+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",
+    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 }),
+  });
+}

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

@@ -0,0 +1,243 @@
+import type { CallExpression, Node, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { LifecycleHookType } from "../../constants";
+import type { AccessRule, RateLimitOption } from "../../types/handlers";
+import type { HookPhase } from "../../types/hooks";
+import type { AuthClaimsPattern, HookPattern } from "../patterns";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  findFunctionLiteral,
+  isPlainObject,
+  ok,
+  readDataLiteralNode,
+  readNameOrRef,
+  readNameOrRefOrList,
+} from "./shared";
+
+export function isHookType(value: string): value is LifecycleHookType | "validation" {
+  return (
+    value === "preSave" ||
+    value === "postSave" ||
+    value === "preDelete" ||
+    value === "postDelete" ||
+    value === "preQuery" ||
+    value === "validation"
+  );
+}
+
+export function readOptionalPhase(node: Node | undefined): HookPhase | undefined {
+  if (!node) return undefined;
+  const obj = readDataLiteralNode(node);
+  if (!isPlainObject(obj)) return undefined;
+  const phase = obj["phase"];
+  if (phase === "inTransaction" || phase === "afterCommit") return phase as HookPhase;
+  return undefined;
+}
+
+export function readOptionalAccessRule(value: unknown): AccessRule | undefined {
+  if (!isPlainObject(value)) return undefined;
+  if (Array.isArray(value["roles"]) && value["roles"].every((r) => typeof r === "string")) {
+    return { roles: value["roles"] as readonly string[] };
+  }
+  if (value["openToAll"] === true) {
+    return { openToAll: true };
+  }
+  return undefined;
+}
+
+export function readOptionalRateLimit(value: unknown): RateLimitOption | undefined {
+  if (!isPlainObject(value)) return undefined;
+  if (typeof value["per"] !== "string") return undefined;
+  if (typeof value["limit"] !== "number") return undefined;
+  if (typeof value["windowSeconds"] !== "number") return undefined;
+  return value as unknown as RateLimitOption;
+}
+
+// r.hook's target: a NameOrRef, a list of them, or an entity-wide
+// `{ allOf: entityRef }` (replaces the old r.entityHook(type, entity, fn)).
+// Checked first so a malformed `{ allOf }` doesn't silently fall through
+// to being read as some other object shape.
+function readHookTarget(
+  node: Node,
+): string | readonly string[] | { readonly allOf: string } | undefined {
+  const obj = node.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (obj) {
+    const allOfProp = obj.getProperty("allOf")?.asKind(SyntaxKind.PropertyAssignment);
+    if (allOfProp) {
+      const initializer = allOfProp.getInitializer();
+      const entityName = initializer && readNameOrRef(initializer);
+      return entityName ? { allOf: entityName } : undefined;
+    }
+  }
+  return readNameOrRefOrList(node);
+}
+
+export function extractHook(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<HookPattern> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail("hook", sourceLocationFromNode(call, sourceFile), "expected at least one argument");
+  }
+
+  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (obj && args.length === 1) {
+    const typeInit = obj
+      .getProperty("type")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
+    if (!typeInit) {
+      return fail(
+        "hook",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `type` property",
+      );
+    }
+    const hookType = typeInit.getLiteralValue();
+    if (!isHookType(hookType)) {
+      return fail(
+        "hook",
+        sourceLocationFromNode(call, sourceFile),
+        `hook type "${hookType}" is not one of the lifecycle types or "validation"`,
+      );
+    }
+    const targetInit = obj
+      .getProperty("target")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!targetInit) {
+      return fail(
+        "hook",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a `target` property",
+      );
+    }
+    const target = readHookTarget(targetInit);
+    if (!target) {
+      return fail(
+        "hook",
+        sourceLocationFromNode(call, sourceFile),
+        "target must be a string literal, an inline { name } object, or an array",
+      );
+    }
+    const handlerInit = obj
+      .getProperty("handler")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!handlerInit) {
+      return fail(
+        "hook",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a `handler` property",
+      );
+    }
+    const fn = findFunctionLiteral(handlerInit);
+    if (!fn) {
+      return fail(
+        "hook",
+        sourceLocationFromNode(call, sourceFile),
+        "handler must be an inline arrow function or function expression",
+      );
+    }
+    const phase = readOptionalPhase(obj);
+    return ok({
+      kind: "hook",
+      source: sourceLocationFromNode(call, sourceFile),
+      hookType,
+      target,
+      fnBody: sourceLocationFromNode(fn, sourceFile),
+      ...(phase !== undefined && { phase }),
+    });
+  }
+
+  const typeArg = first.asKind(SyntaxKind.StringLiteral);
+  if (!typeArg) {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be a string literal hook type (or use the object form)",
+    );
+  }
+  const hookType = typeArg.getLiteralValue();
+  if (!isHookType(hookType)) {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      `hook type "${hookType}" is not one of the lifecycle types or "validation"`,
+    );
+  }
+  const targetArg = args[1];
+  if (!targetArg) {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a target (NameOrRef or array) as second argument",
+    );
+  }
+  const target = readHookTarget(targetArg);
+  if (!target) {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      "target must be a string literal, an inline { name } object, or an array",
+    );
+  }
+  const fnArg = args[2];
+  if (!fnArg) {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a hook function as third argument",
+    );
+  }
+  const fn = findFunctionLiteral(fnArg);
+  if (!fn) {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      "third argument must be an inline arrow function or function expression",
+    );
+  }
+  const phase = readOptionalPhase(args[3]);
+  return ok({
+    kind: "hook",
+    source: sourceLocationFromNode(call, sourceFile),
+    hookType,
+    target,
+    fnBody: sourceLocationFromNode(fn, sourceFile),
+    ...(phase !== undefined && { phase }),
+  });
+}
+
+// guard:dup-ok — intentionale Parallele zu extractTree (round6); verschiedene Feature-AST-Extraktoren by design
+export function extractAuthClaims(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<AuthClaimsPattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "authClaims",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a function as first argument",
+    );
+  }
+  const fn = findFunctionLiteral(arg);
+  if (!fn) {
+    return fail(
+      "authClaims",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be an inline arrow function or function expression",
+    );
+  }
+  return ok({
+    kind: "authClaims",
+    source: sourceLocationFromNode(call, sourceFile),
+    fnBody: sourceLocationFromNode(fn, sourceFile),
+  });
+}

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

@@ -1,3 +1,34 @@
+export {
+  extractDefineEvent,
+  extractNotification,
+} from "./events";
+export {
+  extractQueryHandler,
+  extractWriteHandler,
+  type ParsedHandlerCall,
+  parseHandlerCall,
+} from "./handlers";
+export {
+  extractAuthClaims,
+  extractHook,
+  isHookType,
+  readOptionalAccessRule,
+  readOptionalPhase,
+  readOptionalRateLimit,
+} from "./hooks";
+export {
+  extractHttpRoute,
+  extractJob,
+  isHttpRouteMethod,
+} from "./jobs-routes";
+export {
+  collectScreenOpaqueProps,
+  extractMultiStreamProjection,
+  extractProjection,
+  extractScreen,
+  readApplyBodies,
+  readScreenStatic,
+} from "./projections-screens";
 export {
   extractDescribe,
   extractOptionalRequires,
@@ -25,34 +56,11 @@ export {
   type NamedOptionsResult,
   readNamedOptions,
 } from "./round3";
-export {
-  collectScreenOpaqueProps,
-  extractAuthClaims,
-  extractDefineEvent,
-  extractHook,
-  extractHttpRoute,
-  extractJob,
-  extractMultiStreamProjection,
-  extractNotification,
-  extractProjection,
-  extractQueryHandler,
-  extractScreen,
-  extractWriteHandler,
-  isHookType,
-  isHttpRouteMethod,
-  type ParsedHandlerCall,
-  parseHandlerCall,
-  readApplyBodies,
-  readOptionalAccessRule,
-  readOptionalPhase,
-  readOptionalRateLimit,
-  readScreenStatic,
-} from "./round4";
 export {
   extractEnvSchema,
   extractExposesApi,
   extractExtendsRegistrar,
-  extractUnmanagedTable,
+  extractRawTable,
   extractUsesApi,
 } from "./round5";
 export { extractTreeActions } from "./round6";