@cosmicdrift/kumiko-framework 0.199.1 → 0.199.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.199.1",
+  "version": "0.199.2",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.199.1",
+    "@cosmicdrift/kumiko-types": "0.199.2",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.199.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.199.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/feature-ast/__tests__/fixtures/cross-file-name-const/constants.ts

@@ -0,0 +1 @@
+export const EXT_AUDIT = "audit" as const;

package/src/engine/feature-ast/__tests__/fixtures/cross-file-name-const/feature.ts

@@ -0,0 +1,8 @@
+import { EXT_AUDIT } from "./constants";
+
+// biome-ignore lint/suspicious/noExplicitAny: structural parser test fixture, never executed or type-checked at runtime
+declare function defineFeature(name: string, setup: (r: any) => void): void;
+
+defineFeature("cross-file-name-const", (r) => {
+  r.extendsRegistrar(EXT_AUDIT, {});
+});

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

@@ -473,7 +473,7 @@ defineFeature("f", (r) => {
     expect(result.errors[0]?.methodName).toBe("entity");
   });
 
-  test("emits a ParseError when the name is not a string literal", () => {
+  test("resolves the name when it's an identifier initialized to a string literal", () => {
     const result = parseInline(`
 const ENTITY = "task";
 defineFeature("f", (r) => {
@@ -481,6 +481,22 @@ defineFeature("f", (r) => {
 });
 `);
 
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "task",
+    });
+  });
+
+  test("emits a ParseError when the name identifier does not resolve to a string literal", () => {
+    const result = parseInline(`
+const ENTITY = computeEntityName();
+defineFeature("f", (r) => {
+  r.entity(ENTITY, { fields: {} });
+});
+`);
+
+    expect(result.patterns).toEqual([]);
     expect(result.errors[0]?.methodName).toBe("entity");
   });
 
@@ -2366,3 +2382,18 @@ describe("cross-file registrar-wrapper resolution against a real filesystem Proj
     expect(navPattern?.source.file).not.toBe(fixture);
   });
 });
+
+// #1746 — registrar-call name args authored as an imported constant
+// (`r.useExtension(EXT_TENANT_DATA, ...)`) instead of a string literal.
+// This is the dominant real-world style across the framework's own
+// bundled-features (see extension-names.ts), and previously ParseErrored
+// on every such call.
+describe("cross-file imported-constant name resolution against a real filesystem Project (#1746)", () => {
+  const fixture = resolve(__dirname, "fixtures/cross-file-name-const/feature.ts");
+  const result = parseFeatureFile(fixture);
+
+  test("resolves the identifier to the imported const's string value", () => {
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "extendsRegistrar", extensionName: "audit" }]);
+  });
+});

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

@@ -9,6 +9,7 @@ import {
   findFunctionLiteral,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
   readPropertyKey,
 } from "./shared";
@@ -146,12 +147,12 @@ export function extractDefineEvent(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const eventName = readNameLiteral(first);
+  if (eventName === undefined) {
     return fail(
       "defineEvent",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal event name (or use the object form)",
+      "first argument must be a string literal event name, or an identifier resolving to one (or use the object form)",
     );
   }
   const schemaArg = args[1];
@@ -186,7 +187,7 @@ export function extractDefineEvent(
   return ok({
     kind: "defineEvent",
     source: sourceLocationFromNode(call, sourceFile),
-    eventName: nameArg.getLiteralValue(),
+    eventName,
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     ...(version !== undefined && { version }),
     ...(migrations !== undefined && { migrations }),
@@ -207,31 +208,32 @@ export function extractNotification(
     );
   }
 
-  let nameLiteral: ReturnType<typeof first.asKind<SyntaxKind.StringLiteral>>;
+  let notificationName: string | undefined;
   let defObj: ReturnType<typeof first.asKind<SyntaxKind.ObjectLiteralExpression>>;
 
   const firstObj = first.asKind(SyntaxKind.ObjectLiteralExpression);
   if (firstObj && args.length === 1) {
-    nameLiteral = firstObj
+    const nameInit = firstObj
       .getProperty("name")
       ?.asKind(SyntaxKind.PropertyAssignment)
       ?.getInitializer()
       ?.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
+    if (!nameInit) {
       return fail(
         "notification",
         sourceLocationFromNode(call, sourceFile),
         "object form requires a string-literal `name` property",
       );
     }
+    notificationName = nameInit.getLiteralValue();
     defObj = firstObj;
   } else {
-    nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
+    notificationName = readNameLiteral(first);
+    if (notificationName === undefined) {
       return fail(
         "notification",
         sourceLocationFromNode(call, sourceFile),
-        "first argument must be a string literal notification name (or use the object form)",
+        "first argument must be a string literal notification name, or an identifier resolving to one (or use the object form)",
       );
     }
     defObj = args[1]?.asKind(SyntaxKind.ObjectLiteralExpression);
@@ -243,7 +245,6 @@ export function extractNotification(
       );
     }
   }
-  const nameArg = nameLiteral;
   const triggerObj = defObj
     .getProperty("trigger")
     ?.asKind(SyntaxKind.PropertyAssignment)
@@ -313,7 +314,7 @@ export function extractNotification(
   return ok({
     kind: "notification",
     source: sourceLocationFromNode(call, sourceFile),
-    notificationName: nameArg.getLiteralValue(),
+    notificationName,
     trigger: { on: onName },
     recipientBody: sourceLocationFromNode(recipientFn, sourceFile),
     dataBody: sourceLocationFromNode(dataFn, sourceFile),

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

@@ -14,6 +14,7 @@ import {
   ok,
   readBooleanProperty,
   readDataLiteralNode,
+  readNameLiteral,
 } from "./shared";
 
 export type ParsedHandlerCall = {
@@ -134,12 +135,12 @@ export function parseHandlerCall(
   if (args.length === 1 && isRawRefSentinel(readDataLiteralNode(first))) {
     return ok({ source: sourceLocationFromNode(call, sourceFile) });
   }
-  const nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameLiteral) {
+  const handlerName = readNameLiteral(first);
+  if (handlerName === undefined) {
     return fail(
       methodName,
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal handler name (or use the object form)",
+      "first argument must be a string literal handler name, or an identifier resolving to one (or use the object form)",
     );
   }
   const schemaArg = args[1];
@@ -178,7 +179,7 @@ export function parseHandlerCall(
   }
   return ok({
     source: sourceLocationFromNode(call, sourceFile),
-    handlerName: nameLiteral.getLiteralValue(),
+    handlerName,
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     handlerBody: sourceLocationFromNode(fn, sourceFile),
     ...(access !== undefined && { access }),

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

@@ -12,6 +12,7 @@ import {
   isPlainObject,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
   readNameOrRefOrList,
 } from "./shared";
@@ -155,15 +156,14 @@ export function extractHook(
     });
   }
 
-  const typeArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!typeArg) {
+  const hookType = readNameLiteral(first);
+  if (hookType === undefined) {
     return fail(
       "hook",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal hook type (or use the object form)",
+      "first argument must be a string literal hook type, or an identifier resolving to one (or use the object form)",
     );
   }
-  const hookType = typeArg.getLiteralValue();
   if (!isHookType(hookType)) {
     return fail(
       "hook",

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

@@ -12,6 +12,7 @@ import {
   ok,
   readBooleanProperty,
   readDataLiteralNode,
+  readNameLiteral,
   readPropertyKey,
 } from "./shared";
 
@@ -97,12 +98,12 @@ export function extractJob(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const jobName = readNameLiteral(first);
+  if (jobName === undefined) {
     return fail(
       "job",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal job name (or use the object form)",
+      "first argument must be a string literal job name, or an identifier resolving to one (or use the object form)",
     );
   }
   const optionsArg = args[1];
@@ -140,7 +141,7 @@ export function extractJob(
   return ok({
     kind: "job",
     source: sourceLocationFromNode(call, sourceFile),
-    jobName: nameArg.getLiteralValue(),
+    jobName,
     options: options as Omit<JobDefinition, "name" | "handler">,
     handlerBody: sourceLocationFromNode(fn, sourceFile),
   });

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

@@ -12,6 +12,7 @@ import {
   isPlainObject,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
 } from "./shared";
 
@@ -60,12 +61,12 @@ export function extractEntity(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const entityName = readNameLiteral(first);
+  if (entityName === undefined) {
     return fail(
       "entity",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal name (or use the object form)",
+      "first argument must be a string literal name, or an identifier resolving to one (or use the object form)",
     );
   }
   const defArg = args[1];
@@ -87,7 +88,7 @@ export function extractEntity(
   return ok({
     kind: "entity",
     source: sourceLocationFromNode(call, sourceFile),
-    entityName: nameArg.getLiteralValue(),
+    entityName,
     definition: definition as EntityDefinition,
   });
 }
@@ -165,12 +166,13 @@ export function extractRelation(
       'first argument must be a string literal or an inline { name: "..." } object (or use the object form)',
     );
   }
-  const nameArg = args[1]?.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const relationNameArg = args[1];
+  const relationName = relationNameArg && readNameLiteral(relationNameArg);
+  if (!relationName) {
     return fail(
       "relation",
       sourceLocationFromNode(call, sourceFile),
-      "second argument must be a string literal relation name",
+      "second argument must be a string literal relation name, or an identifier resolving to one",
     );
   }
   const defArg = args[2];
@@ -193,7 +195,7 @@ export function extractRelation(
     kind: "relation",
     source: sourceLocationFromNode(call, sourceFile),
     entityName,
-    relationName: nameArg.getLiteralValue(),
+    relationName,
     definition: definition as RelationDefinition,
   });
 }

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

@@ -20,6 +20,7 @@ import {
   isPlainObject,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
 } from "./shared";
 
@@ -68,12 +69,12 @@ export function readNamedOptions(
     return { kind: "ok", name: nameInit.getLiteralValue(), options: optionsWithoutName };
   }
 
-  const nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameLiteral) {
+  const name = readNameLiteral(first);
+  if (name === undefined) {
     return fail(
       methodName,
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal name (or use the object form)",
+      "first argument must be a string literal name, or an identifier resolving to one (or use the object form)",
     );
   }
   const optionsArg = args[1];
@@ -92,7 +93,7 @@ export function readNamedOptions(
       "options could not be read as a plain object",
     );
   }
-  return { kind: "ok", name: nameLiteral.getLiteralValue(), options };
+  return { kind: "ok", name, options };
 }
 
 export function extractConfig(
@@ -424,12 +425,12 @@ export function extractUseExtension(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const extensionName = readNameLiteral(first);
+  if (extensionName === undefined) {
     return fail(
       "useExtension",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal extension name (or use the object form)",
+      "first argument must be a string literal extension name, or an identifier resolving to one (or use the object form)",
     );
   }
   const entityRefArg = args[1];
@@ -464,7 +465,7 @@ export function extractUseExtension(
   return ok({
     kind: "useExtension",
     source: sourceLocationFromNode(call, sourceFile),
-    extensionName: nameArg.getLiteralValue(),
+    extensionName,
     entityName,
     ...(options !== undefined && { options }),
   });

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

@@ -1,5 +1,4 @@
 import type { CallExpression, SourceFile } from "ts-morph";
-import { SyntaxKind } from "ts-morph";
 import type {
   EnvSchemaPattern,
   ExposesApiPattern,
@@ -7,7 +6,7 @@ import type {
   UsesApiPattern,
 } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
-import { type ExtractOutput, fail, ok } from "./shared";
+import { type ExtractOutput, fail, ok, readNameLiteral } from "./shared";
 
 export function extractEnvSchema(
   call: CallExpression,
@@ -33,12 +32,13 @@ export function extractExtendsRegistrar(
   sourceFile: SourceFile,
 ): ExtractOutput<ExtendsRegistrarPattern> {
   const args = call.getArguments();
-  const nameArg = args[0]?.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const first = args[0];
+  const extensionName = first && readNameLiteral(first);
+  if (!extensionName) {
     return fail(
       "extendsRegistrar",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal extension name",
+      "first argument must be a string literal extension name, or an identifier resolving to one",
     );
   }
   const defArg = args[1];
@@ -52,7 +52,7 @@ export function extractExtendsRegistrar(
   return ok({
     kind: "extendsRegistrar",
     source: sourceLocationFromNode(call, sourceFile),
-    extensionName: nameArg.getLiteralValue(),
+    extensionName,
     defBody: sourceLocationFromNode(defArg, sourceFile),
   });
 }
@@ -61,18 +61,19 @@ export function extractUsesApi(
   call: CallExpression,
   sourceFile: SourceFile,
 ): ExtractOutput<UsesApiPattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
-  if (!arg) {
+  const arg = call.getArguments()[0];
+  const apiName = arg && readNameLiteral(arg);
+  if (!apiName) {
     return fail(
       "usesApi",
       sourceLocationFromNode(call, sourceFile),
-      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser"), or an identifier resolving to one',
     );
   }
   return ok({
     kind: "usesApi",
     source: sourceLocationFromNode(call, sourceFile),
-    apiName: arg.getLiteralValue(),
+    apiName,
   });
 }
 
@@ -80,18 +81,19 @@ export function extractExposesApi(
   call: CallExpression,
   sourceFile: SourceFile,
 ): ExtractOutput<ExposesApiPattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
-  if (!arg) {
+  const arg = call.getArguments()[0];
+  const apiName = arg && readNameLiteral(arg);
+  if (!apiName) {
     return fail(
       "exposesApi",
       sourceLocationFromNode(call, sourceFile),
-      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser"), or an identifier resolving to one',
     );
   }
   return ok({
     kind: "exposesApi",
     source: sourceLocationFromNode(call, sourceFile),
-    apiName: arg.getLiteralValue(),
+    apiName,
   });
 }
 

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

@@ -175,9 +175,65 @@ export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignmen
   return propAssign.getName();
 }
 
-export function readNameOrRef(node: Node): string | undefined {
+function unwrapLiteralInitializer(node: Node): string | undefined {
+  const literal =
+    node.asKind(SyntaxKind.StringLiteral) ?? node.asKind(SyntaxKind.NoSubstitutionTemplateLiteral);
+  if (literal) return literal.getLiteralValue();
+  const asExpr = node.asKind(SyntaxKind.AsExpression);
+  if (asExpr) return unwrapLiteralInitializer(asExpr.getExpression());
+  const satisfiesExpr = node.asKind(SyntaxKind.SatisfiesExpression);
+  if (satisfiesExpr) return unwrapLiteralInitializer(satisfiesExpr.getExpression());
+  const paren = node.asKind(SyntaxKind.ParenthesizedExpression);
+  if (paren) return unwrapLiteralInitializer(paren.getExpression());
+  return undefined;
+}
+
+/**
+ * Resolves a bare Identifier to the string value of its declaration's
+ * initializer (`export const EXT_TENANT_DATA = "tenant-data" as const`),
+ * following imports via ts-morph's definition lookup — works across files
+ * and packages against a real-filesystem Project (see #1008 precedent in
+ * parse.ts). Only descends into VariableDeclaration initializers; a
+ * function/class/type definition or an unresolvable import (external
+ * package, ambient declaration) yields undefined, never a throw.
+ */
+function resolveIdentifierToStringLiteral(identifier: Node): string | undefined {
+  const id = identifier.asKind(SyntaxKind.Identifier);
+  if (!id) return undefined;
+  let defs: readonly Node[];
+  try {
+    defs = id.getDefinitionNodes();
+  } catch {
+    return undefined;
+  }
+  for (const def of defs) {
+    const init = def.asKind(SyntaxKind.VariableDeclaration)?.getInitializer();
+    if (!init) continue;
+    const value = unwrapLiteralInitializer(init);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+/**
+ * A node's string value when it's a string literal, or when it's a bare
+ * Identifier that resolves to one via a `const X = "..."` declaration
+ * (same-file or imported) — the pattern used throughout the framework's
+ * own bundled-features for registrar-call names (`EXT_TENANT_DATA`,
+ * `TENANT_SECRET_READ_EVENT`, ...) instead of repeating string literals.
+ * undefined for anything unresolvable (factory call, member access,
+ * external/ambient identifier) — callers keep their existing ParseError
+ * fallback, no crash.
+ */
+export function readNameLiteral(node: Node): string | undefined {
   const literal = node.asKind(SyntaxKind.StringLiteral);
   if (literal) return literal.getLiteralValue();
+  return resolveIdentifierToStringLiteral(node);
+}
+
+export function readNameOrRef(node: Node): string | undefined {
+  const literal = readNameLiteral(node);
+  if (literal !== undefined) return literal;
   const obj = readDataLiteralNode(node);
   if (isPlainObject(obj) && typeof obj["name"] === "string") return obj["name"];
   return undefined;