@cosmicdrift/kumiko-framework 0.155.0 → 0.156.0

package/src/engine/feature-ast/extractors/jobs-routes.ts

@@ -0,0 +1,221 @@
+import type { CallExpression, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { JobDefinition } from "../../types/config";
+import type { HttpRouteMethod } from "../../types/http-route";
+import type { HttpRoutePattern, JobPattern } from "../patterns";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  findFunctionLiteral,
+  isPlainObject,
+  ok,
+  readBooleanProperty,
+  readDataLiteralNode,
+  readPropertyKey,
+} from "./shared";
+
+export function isHttpRouteMethod(value: string): value is HttpRouteMethod {
+  return (
+    value === "GET" ||
+    value === "POST" ||
+    value === "PUT" ||
+    value === "PATCH" ||
+    value === "DELETE" ||
+    value === "HEAD" ||
+    value === "OPTIONS"
+  );
+}
+
+export function extractJob(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<JobPattern> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail("job", 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(
+        "job",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `name` property",
+      );
+    }
+    const handlerInit = obj
+      .getProperty("handler")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!handlerInit) {
+      return fail(
+        "job",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a `handler` property",
+      );
+    }
+    const fn = findFunctionLiteral(handlerInit);
+    if (!fn) {
+      return fail(
+        "job",
+        sourceLocationFromNode(call, sourceFile),
+        "handler must be an inline arrow function or function expression",
+      );
+    }
+    const optionsBag: Record<string, unknown> = {};
+    for (const prop of obj.getProperties()) {
+      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+      if (!propAssign) continue;
+      const key = readPropertyKey(propAssign);
+      if (key === "name" || key === "handler") continue;
+      const init = propAssign.getInitializer();
+      if (!init) continue;
+      const value = readDataLiteralNode(init);
+      if (value === undefined) {
+        return fail(
+          "job",
+          sourceLocationFromNode(call, sourceFile),
+          `option "${key}" could not be read as a plain value`,
+        );
+      }
+      optionsBag[key] = value;
+    }
+    return ok({
+      kind: "job",
+      source: sourceLocationFromNode(call, sourceFile),
+      jobName: nameInit.getLiteralValue(),
+      options: optionsBag as Omit<JobDefinition, "name" | "handler">,
+      handlerBody: sourceLocationFromNode(fn, sourceFile),
+    });
+  }
+
+  const nameArg = first.asKind(SyntaxKind.StringLiteral);
+  if (!nameArg) {
+    return fail(
+      "job",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be a string literal job name (or use the object form)",
+    );
+  }
+  const optionsArg = args[1];
+  if (!optionsArg) {
+    return fail(
+      "job",
+      sourceLocationFromNode(call, sourceFile),
+      "expected an options object as second argument",
+    );
+  }
+  const options = readDataLiteralNode(optionsArg);
+  if (!isPlainObject(options)) {
+    return fail(
+      "job",
+      sourceLocationFromNode(call, sourceFile),
+      "options could not be read as a plain object",
+    );
+  }
+  const handlerArg = args[2];
+  if (!handlerArg) {
+    return fail(
+      "job",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a handler function as third argument",
+    );
+  }
+  const fn = findFunctionLiteral(handlerArg);
+  if (!fn) {
+    return fail(
+      "job",
+      sourceLocationFromNode(call, sourceFile),
+      "third argument must be an inline arrow function or function expression",
+    );
+  }
+  return ok({
+    kind: "job",
+    source: sourceLocationFromNode(call, sourceFile),
+    jobName: nameArg.getLiteralValue(),
+    options: options as Omit<JobDefinition, "name" | "handler">,
+    handlerBody: sourceLocationFromNode(fn, sourceFile),
+  });
+}
+
+export function extractHttpRoute(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<HttpRoutePattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!arg) {
+    return fail(
+      "httpRoute",
+      sourceLocationFromNode(call, sourceFile),
+      "argument must be an inline HttpRouteDefinition object",
+    );
+  }
+  const methodLiteral = arg
+    .getProperty("method")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  if (!methodLiteral) {
+    return fail(
+      "httpRoute",
+      sourceLocationFromNode(call, sourceFile),
+      "method must be a string literal",
+    );
+  }
+  const methodValue = methodLiteral.getLiteralValue();
+  if (!isHttpRouteMethod(methodValue)) {
+    return fail(
+      "httpRoute",
+      sourceLocationFromNode(call, sourceFile),
+      `method must be one of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS (got "${methodValue}")`,
+    );
+  }
+  const pathLiteral = arg
+    .getProperty("path")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  if (!pathLiteral) {
+    return fail(
+      "httpRoute",
+      sourceLocationFromNode(call, sourceFile),
+      "path must be a string literal",
+    );
+  }
+  const handlerInit = arg
+    .getProperty("handler")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  if (!handlerInit) {
+    return fail(
+      "httpRoute",
+      sourceLocationFromNode(call, sourceFile),
+      "missing `handler` property",
+    );
+  }
+  const fn = findFunctionLiteral(handlerInit);
+  if (!fn) {
+    return fail(
+      "httpRoute",
+      sourceLocationFromNode(call, sourceFile),
+      "handler must be an inline arrow function or function expression",
+    );
+  }
+  const anonymous = readBooleanProperty(arg, "anonymous");
+  return ok({
+    kind: "httpRoute",
+    source: sourceLocationFromNode(call, sourceFile),
+    method: methodValue,
+    path: pathLiteral.getLiteralValue(),
+    handlerBody: sourceLocationFromNode(fn, sourceFile),
+    ...(anonymous === true && { anonymous: true }),
+  });
+}

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

@@ -95,7 +95,7 @@ export function extractExposesApi(
   });
 }
 
-export function extractUnmanagedTable(
+export function extractRawTable(
   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",
+    "rawTable",
     sourceLocationFromNode(call, sourceFile),
-    "unmanagedTable meta is a factory/identifier argument, not a static literal",
+    "rawTable meta is a factory/identifier argument, not a static literal",
   );
 }

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

@@ -51,6 +51,7 @@ import {
   extractOptionalRequires,
   extractProjection,
   extractQueryHandler,
+  extractRawTable,
   extractReadsConfig,
   extractReferenceData,
   extractRelation,
@@ -62,7 +63,6 @@ import {
   extractTranslations,
   extractTreeActions,
   extractUiHints,
-  extractUnmanagedTable,
   extractUseExtension,
   extractUsesApi,
   extractWorkspace,
@@ -468,8 +468,8 @@ function dispatchExtractor(
       return extractUsesApi(call, sourceFile);
     case "exposesApi":
       return extractExposesApi(call, sourceFile);
-    case "unmanagedTable":
-      return extractUnmanagedTable(call, sourceFile);
+    case "rawTable":
+      return extractRawTable(call, sourceFile);
     // Round 6 — Tree-Actions pattern
     case "treeActions":
       return extractTreeActions(call, sourceFile);

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

@@ -491,19 +491,24 @@ function renderMultiStreamProjection(p: MultiStreamProjectionPattern): string {
 }
 
 function renderDefineEvent(p: DefineEventPattern): string {
-  const lines: string[] = ["r.defineEvent({"];
-  lines.push(`  name: ${JSON.stringify(p.eventName)},`);
-  lines.push(`  schema: ${p.schemaSource.raw},`);
+  const migrationEntries = p.migrations !== undefined ? Object.entries(p.migrations) : [];
+  const hasOptions = p.version !== undefined || migrationEntries.length > 0;
+  if (!hasOptions) {
+    return `r.defineEvent(${JSON.stringify(p.eventName)}, ${p.schemaSource.raw});`;
+  }
+  const lines: string[] = [
+    `r.defineEvent(${JSON.stringify(p.eventName)}, ${p.schemaSource.raw}, {`,
+  ];
   if (p.version !== undefined) lines.push(`  version: ${p.version},`);
-  if (p.migrations !== undefined) {
-    const entries = Object.entries(p.migrations);
-    if (entries.length > 0) {
-      lines.push("  migrations: {");
-      for (const [fromVersion, transformBody] of entries) {
-        lines.push(`    "${fromVersion}": ${transformBody.raw},`);
-      }
-      lines.push("  },");
+  if (migrationEntries.length > 0) {
+    lines.push("  migrations: [");
+    for (const [fromVersion, transformBody] of migrationEntries) {
+      const from = Number(fromVersion);
+      lines.push(
+        `    { fromVersion: ${from}, toVersion: ${from + 1}, transform: ${transformBody.raw} },`,
+      );
     }
+    lines.push("  ],");
   }
   lines.push("});");
   return lines.join("\n");

package/src/engine/feature-builder-state.ts

@@ -32,7 +32,6 @@ import type {
   TranslationKeys,
   TreeActionDef,
   UiHints,
-  UnmanagedTableEntry,
   ValidationHookFn,
   WriteHandlerDef,
 } from "./types";
@@ -88,7 +87,6 @@ export type FeatureBuilderState = {
   multiStreamProjections: Record<string, MultiStreamProjectionDefinition>;
   entityProjectionExtensions: Record<string, EntityProjectionExtension[]>;
   rawTables: Record<string, RawTableEntry>;
-  unmanagedTables: Record<string, UnmanagedTableEntry>;
   authClaimsHooks: AuthClaimsFn[];
   claimKeys: Record<string, ClaimKeyDefinition>;
   screens: Record<string, ScreenDefinition>;
@@ -147,7 +145,6 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     multiStreamProjections: {},
     entityProjectionExtensions: {},
     rawTables: {},
-    unmanagedTables: {},
     authClaimsHooks: [],
     claimKeys: {},
     screens: {},

package/src/engine/feature-config-events-jobs.ts

@@ -1,6 +1,6 @@
 import { ZodObject, type ZodType, type z } from "zod";
 import type { FeatureBuilderState } from "./feature-builder-state";
-import { splitNamedDefinition } from "./object-form";
+import { splitNamedDefinition, unwrapArrayForm } from "./object-form";
 import { QnTypes, qn, toKebab } from "./qualified-name";
 import type {
   AuthClaimsFn,
@@ -91,7 +91,7 @@ export function buildConfigEventsJobsMethods<TName extends string>(
       }
     }
     // Single-key call unwraps its own handle; multi-key returns the record.
-    return typeof arg1 === "string" ? handles[arg1] : handles; // @cast-boundary engine-bridge — overload impl signature widens to unknown, narrowed by the two public overloads above
+    return typeof arg1 === "string" ? handles[arg1] : handles;
   }
 
   // piiFields misconfiguration is a boot-time error, not a silent
@@ -272,10 +272,7 @@ export function buildConfigEventsJobsMethods<TName extends string>(
     readsConfig(
       ...args: readonly [{ readonly keys: readonly string[] }] | readonly string[]
     ): void {
-      const [first] = args;
-      const qualifiedKeys =
-        typeof first === "object" && first !== null ? first.keys : (args as readonly string[]);
-      state.configReads.push(...qualifiedKeys);
+      state.configReads.push(...unwrapArrayForm(args, "keys"));
     },
     metric(
       shortNameOrDefinition: string | ({ readonly name: string } & MetricOptions),

package/src/engine/feature-entity-handlers.ts

@@ -1,6 +1,8 @@
 import type { ZodType, z } from "zod";
 import { toTableName } from "../db/table-builder";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
+import type { RegisterEntityCrudOptions } from "./entity-handlers";
+import { registerEntityCrud } from "./entity-handlers";
 import type { FeatureBuilderState } from "./feature-builder-state";
 import { splitNamedDefinition } from "./object-form";
 import type {
@@ -51,7 +53,7 @@ export function buildEntityHandlerMethods<TName extends string>(
   state: FeatureBuilderState,
   name: TName,
 ) {
-  return {
+  const methods = {
     entity(
       nameOrDefinition: string | ({ readonly name: string } & EntityDefinition),
       definition?: EntityDefinition,
@@ -163,4 +165,10 @@ export function buildEntityHandlerMethods<TName extends string>(
       return { name: nameOrDef };
     },
   };
+  return {
+    ...methods,
+    crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void {
+      registerEntityCrud(methods, entityName, entity, options);
+    },
+  };
 }