@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/src/engine/feature-ast/extractors/resolve-import.ts

@@ -0,0 +1,187 @@
+// Syntactic cross-file resolution for feature-ast identifier extractors.
+// Deliberately avoids ts-morph's symbol/type-checker APIs (getSymbol,
+// getDefinitionNodes, getModuleSpecifierSourceFile, ...) — those build a full
+// TypeScript program on first use, which against this repo's workspace
+// packages pulls in ~1000 source files and costs seconds instead of
+// milliseconds.
+import type {
+  Node,
+  ParameterDeclaration,
+  SourceFile,
+  Statement,
+  VariableDeclaration,
+} from "ts-morph";
+import { SyntaxKind, ts } from "ts-morph";
+
+const MODULE_RESOLUTION_OPTIONS: ts.CompilerOptions = {
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  module: ts.ModuleKind.ESNext,
+  target: ts.ScriptTarget.ESNext,
+};
+
+const MAX_RESOLUTION_DEPTH = 24;
+
+export function resolveModuleFile(fromFile: SourceFile, specifier: string): SourceFile | undefined {
+  const project = fromFile.getProject();
+  // The project's own host, not ts.sys: it honours an in-memory file system
+  // (Designer) and exists outside Node.
+  const resolved = ts.resolveModuleName(
+    specifier,
+    fromFile.getFilePath(),
+    MODULE_RESOLUTION_OPTIONS,
+    project.getModuleResolutionHost(),
+  );
+  const resolvedFileName = resolved.resolvedModule?.resolvedFileName;
+  if (!resolvedFileName) return undefined;
+  // A declaration file has no initializers to read. Installed packages that
+  // ship .ts sources (the @cosmicdrift/* packages in a consumer repo) stay
+  // resolvable, as they were via the type checker.
+  if (resolvedFileName.endsWith(".d.ts")) return undefined;
+  return fromFile.getProject().addSourceFileAtPathIfExists(resolvedFileName);
+}
+
+export function findImportBindingForLocalName(
+  sourceFile: SourceFile,
+  localName: string,
+): { readonly moduleSpecifier: string; readonly importedName: string } | undefined {
+  for (const importDecl of sourceFile.getImportDeclarations()) {
+    const named = importDecl
+      .getNamedImports()
+      .find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === localName);
+    if (!named) continue;
+    return {
+      moduleSpecifier: importDecl.getModuleSpecifierValue(),
+      importedName: named.getName(),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * `visited` keys on `${filePath}#${name}`, not path alone — aliasing can
+ * legally re-export a different name from the same file — and doubles as
+ * the cycle guard; `depth` backstops pathological non-cyclic chains.
+ */
+export function resolveExportedVariable(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string> = new Set(),
+  depth = 0,
+): VariableDeclaration | undefined {
+  if (depth > MAX_RESOLUTION_DEPTH) return undefined;
+  const key = `${file.getFilePath()}#${exportedName}`;
+  if (visited.has(key)) return undefined;
+  visited.add(key);
+
+  const directDecl = file.getVariableDeclaration(exportedName);
+  if (directDecl?.getVariableStatement()?.hasExportKeyword()) return directDecl;
+
+  const namedExportMatch = resolveViaNamedExportSpecifier(file, exportedName, visited, depth);
+  if (namedExportMatch) return namedExportMatch;
+
+  return resolveViaStarExport(file, exportedName, visited, depth);
+}
+
+function resolveViaNamedExportSpecifier(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  for (const exportDecl of file.getExportDeclarations()) {
+    const specifier = exportDecl
+      .getNamedExports()
+      .find((spec) => (spec.getAliasNode()?.getText() ?? spec.getName()) === exportedName);
+    if (!specifier) continue;
+    const originalName = specifier.getName();
+
+    if (!exportDecl.hasModuleSpecifier()) {
+      const resolved = resolveLocalExportBinding(file, originalName, visited, depth);
+      if (resolved) return resolved;
+      continue;
+    }
+
+    const moduleSpecifierValue = exportDecl.getModuleSpecifierValue();
+    if (!moduleSpecifierValue) continue;
+    const target = resolveModuleFile(file, moduleSpecifierValue);
+    if (!target) continue;
+    const resolved = resolveExportedVariable(target, originalName, visited, depth + 1);
+    if (resolved) return resolved;
+  }
+  return undefined;
+}
+
+function resolveLocalExportBinding(
+  file: SourceFile,
+  originalName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  const localDecl = file.getVariableDeclaration(originalName);
+  if (localDecl) return localDecl;
+  const binding = findImportBindingForLocalName(file, originalName);
+  if (!binding) return undefined;
+  const target = resolveModuleFile(file, binding.moduleSpecifier);
+  if (!target) return undefined;
+  return resolveExportedVariable(target, binding.importedName, visited, depth + 1);
+}
+
+function resolveViaStarExport(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  for (const exportDecl of file.getExportDeclarations()) {
+    if (!exportDecl.hasModuleSpecifier()) continue;
+    if (exportDecl.getNamedExports().length > 0) continue;
+    if (exportDecl.getNamespaceExport()) continue; // `export * as ns from "./m"` is not a re-export target.
+    const moduleSpecifierValue = exportDecl.getModuleSpecifierValue();
+    if (!moduleSpecifierValue) continue;
+    const target = resolveModuleFile(file, moduleSpecifierValue);
+    if (!target) continue;
+    const resolved = resolveExportedVariable(target, exportedName, visited, depth + 1);
+    if (resolved) return resolved;
+  }
+  return undefined;
+}
+
+/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+export function findScopedVariableDeclaration(
+  identifier: Node,
+  name: string,
+): VariableDeclaration | undefined {
+  for (const ancestor of [identifier, ...identifier.getAncestors()]) {
+    const params = getShadowingParameters(ancestor);
+    if (params?.some((p) => p.getName() === name)) return undefined;
+
+    const statements = getDirectStatements(ancestor);
+    if (!statements) continue;
+    for (const stmt of statements) {
+      const varStmt = stmt.asKind(SyntaxKind.VariableStatement);
+      if (!varStmt) continue;
+      const decl = varStmt
+        .getDeclarationList()
+        .getDeclarations()
+        .find((d) => d.getName() === name);
+      if (decl) return decl;
+    }
+  }
+  return undefined;
+}
+
+function getShadowingParameters(node: Node): readonly ParameterDeclaration[] | undefined {
+  const fn =
+    node.asKind(SyntaxKind.ArrowFunction) ??
+    node.asKind(SyntaxKind.FunctionExpression) ??
+    node.asKind(SyntaxKind.FunctionDeclaration);
+  return fn?.getParameters();
+}
+
+function getDirectStatements(node: Node): readonly Statement[] | undefined {
+  const block = node.asKind(SyntaxKind.Block);
+  if (block) return block.getStatements();
+  const sourceFile = node.asKind(SyntaxKind.SourceFile);
+  if (sourceFile) return sourceFile.getStatements();
+  return undefined;
+}

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

@@ -2,6 +2,12 @@ import type { CallExpression, Node, ObjectLiteralExpression } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
+import {
+  findImportBindingForLocalName,
+  findScopedVariableDeclaration,
+  resolveExportedVariable,
+  resolveModuleFile,
+} from "./resolve-import";
 
 export type ExtractOutput<TPattern> =
   | { readonly kind: "pattern"; readonly pattern: TPattern }
@@ -200,28 +206,31 @@ function unwrapLiteralInitializer(node: Node): string | 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.
+ * following imports syntactically across files and packages against a
+ * real-filesystem Project without ever building a TypeScript program (see
+ * resolve-import.ts). Only descends into VariableDeclaration initializers; a
+ * function/class/type definition or an unresolvable import 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);
+  const name = id.getText();
+
+  const scoped = findScopedVariableDeclaration(id, name);
+  if (scoped) {
+    const init = scoped.getInitializer();
+    const value = init ? unwrapLiteralInitializer(init) : undefined;
     if (value !== undefined) return value;
   }
-  return undefined;
+
+  const binding = findImportBindingForLocalName(id.getSourceFile(), name);
+  if (!binding) return undefined;
+  const targetFile = resolveModuleFile(id.getSourceFile(), binding.moduleSpecifier);
+  if (!targetFile) return undefined;
+  const decl = resolveExportedVariable(targetFile, binding.importedName);
+  const init = decl?.getInitializer();
+  return init ? unwrapLiteralInitializer(init) : undefined;
 }
 
 /**
@@ -279,9 +288,7 @@ export function resolveSameFileObjectLiteral(node: Node): ObjectLiteralExpressio
   if (direct) return direct;
   const identifier = node.asKind(SyntaxKind.Identifier);
   if (!identifier) return undefined;
-  const valueDecl = identifier.getSymbol()?.getValueDeclaration();
-  const fromSymbol = valueDecl?.asKind(SyntaxKind.VariableDeclaration);
-  const varDecl = fromSymbol ?? node.getSourceFile().getVariableDeclaration(identifier.getText());
+  const varDecl = findScopedVariableDeclaration(identifier, identifier.getText());
   return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
 }
 

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

@@ -73,7 +73,9 @@ import {
   extractWorkspace,
   extractWriteHandler,
   findFunctionLiteral,
+  findImportBindingForLocalName,
   readObjectPropertyInitializer,
+  resolveModuleFile,
   resolveSameFileObjectLiteral,
 } from "./extractors";
 import type { FeaturePattern, UnknownPattern } from "./patterns";
@@ -296,13 +298,13 @@ function walkSetupCallback(
 /**
  * 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).
+ * declared in the same file, or imported by name from another file —
+ * resolved syntactically via resolveModuleFile, which only works against a
+ * real-filesystem Project; the in-memory Designer Project has no files to
+ * resolve against and returns undefined there, same as any other
+ * unresolvable reference. Does not follow re-exports in the target file — a
+ * wrapper function is expected to be declared directly in the module it's
+ * imported from.
  */
 function resolveRegistrarWrapperCall(
   call: CallExpression,
@@ -328,21 +330,12 @@ function resolveRegistrarWrapperCall(
   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();
+  const binding = findImportBindingForLocalName(callSourceFile, name);
+  if (!binding) return undefined;
+  const targetFile = resolveModuleFile(callSourceFile, binding.moduleSpecifier);
   if (!targetFile) return undefined; // Unresolvable: in-memory project, external package, or missing file.
 
-  const imported = resolveWrapperDeclarationInFile(targetFile, exportedName, argIndex);
+  const imported = resolveWrapperDeclarationInFile(targetFile, binding.importedName, argIndex);
   return imported ? { ...imported, sourceFile: targetFile } : undefined;
 }
 

package/src/engine/index.ts

@@ -267,6 +267,7 @@ export {
 export type { ParsedRefTarget } from "./parse-ref-target";
 export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline";
+export { projectAppSchemaForRoles } from "./project-app-schema-for-roles";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name";