@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -21,7 +21,13 @@
 // Per-pattern extractors fill in iteratively (C1.5) — each round adds
 // one extractor + a focused test.
 
-import type { ArrowFunction, CallExpression, ParameterDeclaration, SourceFile } from "ts-morph";
+import type {
+  ArrowFunction,
+  CallExpression,
+  Node,
+  ParameterDeclaration,
+  SourceFile,
+} from "ts-morph";
 import { Project, SyntaxKind } from "ts-morph";
 
 import {
@@ -32,9 +38,7 @@ import {
   extractDefineEvent,
   extractDescribe,
   extractEntity,
-  extractEntityHook,
   extractEnvSchema,
-  extractEventMigration,
   extractExposesApi,
   extractExtendsRegistrar,
   extractHook,
@@ -53,17 +57,18 @@ import {
   extractRequires,
   extractScreen,
   extractSecret,
+  extractStoreTable,
+  extractStreamHandler,
   extractSystemScope,
   extractToggleable,
   extractTranslations,
-  extractTree,
   extractTreeActions,
   extractUiHints,
-  extractUnmanagedTable,
   extractUseExtension,
   extractUsesApi,
   extractWorkspace,
   extractWriteHandler,
+  findFunctionLiteral,
 } from "./extractors";
 import type { FeaturePattern, UnknownPattern } from "./patterns";
 import { type SourceLocation, sourceLocationFromNode } from "./source-location";
@@ -146,7 +151,7 @@ export function parseSourceFile(sourceFile: SourceFile): ParseResult {
   const patterns: FeaturePattern[] = [];
   const errors: ParseError[] = [];
 
-  walkSetupCallback(setupCallback, registrarParamName, sourceFile, patterns, errors);
+  walkSetupCallback(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
 
   return { featureName, patterns, errors };
 }
@@ -229,25 +234,131 @@ function extractRegistrarParamName(setup: ArrowFunction): string | undefined {
  * structurally impossible.
  */
 function walkSetupCallback(
-  setup: ArrowFunction,
+  body: Node,
   registrarParamName: string,
   sourceFile: SourceFile,
   patterns: FeaturePattern[],
   errors: ParseError[],
+  visitedWrapperDecls: Set<Node> = new Set(),
 ): void {
-  const body = setup.getBody();
   for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const methodName = extractRegistrarMethodName(call, registrarParamName);
-    if (!methodName) continue; // Not a registrar call — ignore.
-    const result = dispatchExtractor(methodName, call, sourceFile);
-    if (result.kind === "pattern") {
-      patterns.push(result.pattern);
-    } else {
-      errors.push(result.error);
+    if (methodName) {
+      const result = dispatchExtractor(methodName, call, sourceFile);
+      if (result.kind === "pattern") {
+        patterns.push(result.pattern);
+      } else {
+        errors.push(result.error);
+      }
+      continue;
     }
+
+    // Not a direct `<registrarParam>.<method>(...)` call. Check whether it's
+    // a registrar-wrapper call — a function that receives the registrar as
+    // a bare argument, e.g. `registerShowPonyScreens(r)`. Such wrappers are
+    // invisible to a receiver-shape match, so we resolve the callee (same
+    // file, or the declaring file of a named import — #1008) and recurse
+    // into its body with its own parameter name for the registrar slot.
+    const wrapper = resolveRegistrarWrapperCall(call, registrarParamName);
+    if (!wrapper) continue; // Free function call unrelated to the registrar — ignore.
+    if (visitedWrapperDecls.has(wrapper.declNode)) continue; // Cycle guard.
+    visitedWrapperDecls.add(wrapper.declNode);
+    // wrapper.sourceFile, not the outer `sourceFile` param: a cross-file
+    // wrapper's body lives in a different file, and sourceLocationFromNode
+    // uses whichever SourceFile it's given for both the `file` path and
+    // the line/column table — passing the wrong one silently corrupts
+    // both for every pattern found inside the wrapper.
+    walkSetupCallback(
+      wrapper.body,
+      wrapper.paramName,
+      wrapper.sourceFile,
+      patterns,
+      errors,
+      visitedWrapperDecls,
+    );
   }
 }
 
+/**
+ * Resolves a bare call like `registerShowPonyScreens(r)` to the callee's
+ * body + its own parameter name for the registrar slot. The callee may be
+ * declared in the same file (function declaration, or a const initialized
+ * with an arrow/function expression), or imported by name from another
+ * file — resolved via the module specifier's SourceFile (#1008; only
+ * works against a real-filesystem Project, e.g. parseFeatureFile's. The
+ * in-memory Designer Project has no files to resolve against and
+ * getModuleSpecifierSourceFile() returns undefined there, same as any
+ * other unresolvable reference).
+ */
+function resolveRegistrarWrapperCall(
+  call: CallExpression,
+  registrarParamName: string,
+):
+  | {
+      readonly body: Node;
+      readonly paramName: string;
+      readonly declNode: Node;
+      readonly sourceFile: SourceFile;
+    }
+  | undefined {
+  const callee = call.getExpression().asKind(SyntaxKind.Identifier);
+  if (!callee) return undefined;
+
+  const args = call.getArguments();
+  const argIndex = args.findIndex((arg) => arg.getText() === registrarParamName);
+  if (argIndex === -1) return undefined; // Registrar not passed to this call.
+
+  const callSourceFile = call.getSourceFile();
+  const name = callee.getText();
+
+  const local = resolveWrapperDeclarationInFile(callSourceFile, name, argIndex);
+  if (local) return { ...local, sourceFile: callSourceFile };
+
+  const importDecl = callSourceFile
+    .getImportDeclarations()
+    .find((d) =>
+      d.getNamedImports().some((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name),
+    );
+  if (!importDecl) return undefined;
+  const exportedName =
+    importDecl
+      .getNamedImports()
+      .find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name)
+      ?.getName() ?? name;
+  const targetFile = importDecl.getModuleSpecifierSourceFile();
+  if (!targetFile) return undefined; // Unresolvable: in-memory project, external package, or missing file.
+
+  const imported = resolveWrapperDeclarationInFile(targetFile, exportedName, argIndex);
+  return imported ? { ...imported, sourceFile: targetFile } : undefined;
+}
+
+function resolveWrapperDeclarationInFile(
+  sourceFile: SourceFile,
+  name: string,
+  argIndex: number,
+): { readonly body: Node; readonly paramName: string; readonly declNode: Node } | undefined {
+  const fnDecl = sourceFile.getFunction(name);
+  if (fnDecl) {
+    const param = fnDecl.getParameters()[argIndex];
+    const body = fnDecl.getBody();
+    if (!param || !body) return undefined;
+    return { body, paramName: param.getName(), declNode: fnDecl };
+  }
+
+  const varDecl = sourceFile.getVariableDeclaration(name);
+  const init = varDecl?.getInitializer();
+  const literal = init ? findFunctionLiteral(init) : undefined;
+  const fnLiteral =
+    literal?.asKind(SyntaxKind.ArrowFunction) ?? literal?.asKind(SyntaxKind.FunctionExpression);
+  if (fnLiteral) {
+    const param = fnLiteral.getParameters()[argIndex];
+    if (!param) return undefined;
+    return { body: fnLiteral.getBody(), paramName: param.getName(), declNode: fnLiteral };
+  }
+
+  return undefined;
+}
+
 /**
  * Returns the method name when the call has the form
  * `<registrarParamName>.<method>(...)`, otherwise undefined.
@@ -331,22 +442,20 @@ function dispatchExtractor(
     // Round 4 — mixed (header + body) patterns
     case "hook":
       return extractHook(call, sourceFile);
-    case "entityHook":
-      return extractEntityHook(call, sourceFile);
     case "authClaims":
       return extractAuthClaims(call, sourceFile);
     case "writeHandler":
       return extractWriteHandler(call, sourceFile);
     case "queryHandler":
       return extractQueryHandler(call, sourceFile);
+    case "streamHandler":
+      return extractStreamHandler(call, sourceFile);
     case "job":
       return extractJob(call, sourceFile);
     case "httpRoute":
       return extractHttpRoute(call, sourceFile);
     case "defineEvent":
       return extractDefineEvent(call, sourceFile);
-    case "eventMigration":
-      return extractEventMigration(call, sourceFile);
     case "notification":
       return extractNotification(call, sourceFile);
     case "projection":
@@ -362,13 +471,11 @@ function dispatchExtractor(
       return extractUsesApi(call, sourceFile);
     case "exposesApi":
       return extractExposesApi(call, sourceFile);
-    case "unmanagedTable":
-      return extractUnmanagedTable(call, sourceFile);
-    // Round 6 — Visual-Tree patterns
+    case "storeTable":
+      return extractStoreTable(call, sourceFile);
+    // Round 6 — Tree-Actions pattern
     case "treeActions":
       return extractTreeActions(call, sourceFile);
-    case "tree":
-      return extractTree(call, sourceFile);
     // Round 7 — env-schema contract (opaque, Zod-expression argument)
     case "envSchema":
       return extractEnvSchema(call, sourceFile);

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

@@ -53,8 +53,12 @@ export type PatternId =
   | { readonly kind: "screen"; readonly id: string }
   | { readonly kind: "writeHandler"; readonly handlerName: string }
   | { readonly kind: "queryHandler"; readonly handlerName: string }
-  | { readonly kind: "hook"; readonly hookType: string; readonly target: string }
-  | { readonly kind: "entityHook"; readonly hookType: string; readonly entityName: string }
+  | { readonly kind: "streamHandler"; readonly handlerName: string }
+  | {
+      readonly kind: "hook";
+      readonly hookType: string;
+      readonly target: string | { readonly allOf: string };
+    }
   | { readonly kind: "metric"; readonly shortName: string }
   | { readonly kind: "secret"; readonly shortName: string }
   | { readonly kind: "claimKey"; readonly shortName: string }
@@ -66,12 +70,6 @@ export type PatternId =
   | { readonly kind: "projection"; readonly name: string }
   | { readonly kind: "multiStreamProjection"; readonly name: string }
   | { readonly kind: "defineEvent"; readonly eventName: string }
-  | {
-      readonly kind: "eventMigration";
-      readonly eventName: string;
-      readonly fromVersion: number;
-      readonly toVersion: number;
-    }
   | { readonly kind: "extendsRegistrar"; readonly extensionName: string }
   // Singleton patterns — only one per feature, kind alone identifies them.
   | { readonly kind: "requires" }
@@ -84,8 +82,7 @@ export type PatternId =
   | { readonly kind: "config" }
   | { readonly kind: "translations" }
   | { readonly kind: "authClaims" }
-  | { readonly kind: "treeActions" }
-  | { readonly kind: "tree" };
+  | { readonly kind: "treeActions" };
 
 // =============================================================================
 // Change ops — generic apply API
@@ -277,10 +274,9 @@ export const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]> = new Set([
   "config",
   "translations",
   "authClaims",
-  // Visual-Tree slots — at-most-one per feature, mirrors the registrar's
+  // Tree-Actions slot — at-most-one per feature, mirrors the registrar's
   // only-once-guard in define-feature.ts.
   "treeActions",
-  "tree",
 ]);
 
 /**
@@ -336,7 +332,6 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "translations":
     case "authClaims":
     case "treeActions":
-    case "tree":
       return true;
 
     case "entity":
@@ -359,12 +354,25 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
       return matchObjectProperty(call, "id", id.id);
     case "writeHandler":
     case "queryHandler":
+    case "streamHandler":
       return (
         matchFirstArgString(call, id.handlerName) ||
         matchObjectProperty(call, "name", id.handlerName)
       );
     case "hook":
       // Positional: r.hook(type, target, fn) | Object: { type, target }
+      if (typeof id.target === "object") {
+        // Entity-wide { allOf } target — only ever appears as the object
+        // literal { allOf: entity } (positional or nested in the object
+        // form), never as a bare string, so check both call shapes.
+        if (matchFirstArgString(call, id.hookType)) {
+          return matchAllOfArg(call.getArguments()[1], id.target.allOf);
+        }
+        return (
+          matchObjectProperty(call, "type", id.hookType) &&
+          matchObjectAllOfProperty(call, "target", id.target.allOf)
+        );
+      }
       if (matchFirstArgString(call, id.hookType)) {
         const target = call.getArguments()[1]?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
         return target === id.target;
@@ -373,15 +381,6 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
         matchObjectProperty(call, "type", id.hookType) &&
         matchObjectProperty(call, "target", id.target)
       );
-    case "entityHook":
-      if (matchFirstArgString(call, id.hookType)) {
-        const ent = call.getArguments()[1]?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
-        return ent === id.entityName;
-      }
-      return (
-        matchObjectProperty(call, "type", id.hookType) &&
-        matchObjectProperty(call, "entity", id.entityName)
-      );
     case "metric":
     case "secret":
     case "claimKey":
@@ -422,20 +421,6 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
       return (
         matchFirstArgString(call, id.eventName) || matchObjectProperty(call, "name", id.eventName)
       );
-    case "eventMigration": {
-      // Positional: r.eventMigration(name, from, to, fn)
-      if (matchFirstArgString(call, id.eventName)) {
-        const from = numericArg(call, 1);
-        const to = numericArg(call, 2);
-        return from === id.fromVersion && to === id.toVersion;
-      }
-      // Object: { event, fromVersion, toVersion }
-      return (
-        matchObjectProperty(call, "event", id.eventName) &&
-        matchObjectNumericProperty(call, "fromVersion", id.fromVersion) &&
-        matchObjectNumericProperty(call, "toVersion", id.toVersion)
-      );
-    }
     case "extendsRegistrar":
       return matchFirstArgString(call, id.extensionName);
     default: {
@@ -462,25 +447,29 @@ function matchObjectProperty(call: CallExpression, propName: string, expected: s
   return init?.getLiteralValue() === expected;
 }
 
-function matchObjectNumericProperty(
-  call: CallExpression,
-  propName: string,
-  expected: number,
-): boolean {
-  const obj = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!obj) return false;
+// Matches an r.hook `{ allOf: entity }` target — as the arg node directly
+// (positional call form) or as a nested object property (object call form).
+function matchAllOfArg(node: Node | undefined, expectedEntity: string): boolean {
+  const obj = node?.asKind(SyntaxKind.ObjectLiteralExpression);
   const init = obj
-    .getProperty(propName)
+    ?.getProperty("allOf")
     ?.asKind(SyntaxKind.PropertyAssignment)
     ?.getInitializer()
-    ?.asKind(SyntaxKind.NumericLiteral);
-  return init !== undefined && Number(init.getText()) === expected;
+    ?.asKind(SyntaxKind.StringLiteral);
+  return init?.getLiteralValue() === expectedEntity;
 }
 
-function numericArg(call: CallExpression, idx: number): number | undefined {
-  const lit = call.getArguments()[idx]?.asKind(SyntaxKind.NumericLiteral);
-  if (!lit) return undefined;
-  return Number(lit.getText());
+function matchObjectAllOfProperty(
+  call: CallExpression,
+  propName: string,
+  expectedEntity: string,
+): boolean {
+  const obj = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+  const propInit = obj
+    ?.getProperty(propName)
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  return matchAllOfArg(propInit, expectedEntity);
 }
 
 // =============================================================================

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

@@ -104,17 +104,21 @@ export type AddQueryHandlerArgs = {
   readonly rateLimit?: RateLimitOption;
 };
 
-export type AddHookArgs = {
-  readonly type: LifecycleHookType | "validation";
-  readonly target: string | readonly string[];
-  /** Source text of the closure, e.g. `"async (event, ctx) => { ... }"`. */
+export type AddStreamHandlerArgs = {
+  readonly name: string;
+  readonly schemaSource: string;
   readonly handlerSource: string;
-  readonly phase?: HookPhase;
+  readonly access?: AccessRule;
+  readonly rateLimit?: RateLimitOption;
 };
 
-export type AddEntityHookArgs = {
-  readonly type: "postSave" | "preDelete" | "postDelete";
-  readonly entity: string;
+export type AddHookArgs = {
+  readonly type: LifecycleHookType | "validation";
+  // `{ allOf: entity }` — entity-wide target, fires for every write/query
+  // handler of that entity; replaces the old addEntityHook(). Only valid
+  // for postSave/preDelete/postDelete/postQuery, same as r.hook() itself.
+  readonly target: string | readonly string[] | { readonly allOf: string };
+  /** Source text of the closure, e.g. `"async (event, ctx) => { ... }"`. */
   readonly handlerSource: string;
   readonly phase?: HookPhase;
 };
@@ -144,13 +148,10 @@ export type AddDefineEventArgs = {
   readonly name: string;
   readonly schemaSource: string;
   readonly version?: number;
-};
-
-export type AddEventMigrationArgs = {
-  readonly event: string;
-  readonly fromVersion: number;
-  readonly toVersion: number;
-  readonly transformSource: string;
+  // Keyed by fromVersion (as a string) → the transform source text for the
+  // fromVersion -> fromVersion+1 step. Folded in from the former
+  // addEventMigration (#1082 step 8).
+  readonly migrations?: Readonly<Record<string, string>>;
 };
 
 export type AddProjectionArgs = {
@@ -240,8 +241,8 @@ export type FeaturePatcher = {
   readonly addScreen: (args: AddScreenArgs) => void;
   readonly addWriteHandler: (args: AddWriteHandlerArgs) => void;
   readonly addQueryHandler: (args: AddQueryHandlerArgs) => void;
+  readonly addStreamHandler: (args: AddStreamHandlerArgs) => void;
   readonly addHook: (args: AddHookArgs) => void;
-  readonly addEntityHook: (args: AddEntityHookArgs) => void;
   readonly addJob: (args: AddJobArgs) => void;
   readonly addNotification: (args: AddNotificationArgs) => void;
   readonly addAuthClaims: (args: AddAuthClaimsArgs) => void;
@@ -249,7 +250,6 @@ export type FeaturePatcher = {
   readonly addProjection: (args: AddProjectionArgs) => void;
   readonly addMultiStreamProjection: (args: AddMultiStreamProjectionArgs) => void;
   readonly addDefineEvent: (args: AddDefineEventArgs) => void;
-  readonly addEventMigration: (args: AddEventMigrationArgs) => void;
   // --- Symmetric ops (id-driven) ---
   readonly replace: (id: PatternId, pattern: FeaturePattern) => void;
   readonly remove: (id: PatternId) => void;
@@ -401,23 +401,24 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addHook({ type, target, handlerSource, phase }) {
+    addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit }) {
       add({
-        kind: "hook",
+        kind: "streamHandler",
         source: SYNTHETIC_LOC,
-        hookType: type,
-        target,
-        fnBody: rawLoc(handlerSource),
-        ...(phase !== undefined && { phase }),
+        handlerName: name,
+        schemaSource: rawLoc(schemaSource),
+        handlerBody: rawLoc(handlerSource),
+        ...(access !== undefined && { access }),
+        ...(rateLimit !== undefined && { rateLimit }),
       });
     },
 
-    addEntityHook({ type, entity, handlerSource, phase }) {
+    addHook({ type, target, handlerSource, phase }) {
       add({
-        kind: "entityHook",
+        kind: "hook",
         source: SYNTHETIC_LOC,
         hookType: type,
-        entityName: entity,
+        target,
         fnBody: rawLoc(handlerSource),
         ...(phase !== undefined && { phase }),
       });
@@ -495,24 +496,22 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addDefineEvent({ name, schemaSource, version }) {
+    addDefineEvent({ name, schemaSource, version, migrations }) {
+      const migrationLocs = migrations
+        ? Object.fromEntries(
+            Object.entries(migrations).map(([fromVersion, source]) => [
+              fromVersion,
+              rawLoc(source),
+            ]),
+          )
+        : undefined;
       add({
         kind: "defineEvent",
         source: SYNTHETIC_LOC,
         eventName: name,
         schemaSource: rawLoc(schemaSource),
         ...(version !== undefined && { version }),
-      });
-    },
-
-    addEventMigration({ event, fromVersion, toVersion, transformSource }) {
-      add({
-        kind: "eventMigration",
-        source: SYNTHETIC_LOC,
-        eventName: event,
-        fromVersion,
-        toVersion,
-        transformBody: rawLoc(transformSource),
+        ...(migrationLocs !== undefined && { migrations: migrationLocs }),
       });
     },