@valkyrjaio/sindri 26.2.0 → 26.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/sindri",
-    "version": "26.2.0",
+    "version": "26.4.0",
     "description": "The Valkyrja Sindri build tool.",
     "homepage": "https://www.valkyrja.io/sindri",
     "keywords": [
@@ -38,7 +38,7 @@
         "node": ">=22"
     },
     "dependencies": {
-        "@valkyrjaio/valkyrja": "^26.2.0",
+        "@valkyrjaio/valkyrja": "^26.4.0",
         "ts-morph": "^28.0.0"
     },
     "scripts": {

package/src/Sindri/Ast/Abstract/AstReader.ts

@@ -13,12 +13,12 @@ import * as path from 'path';
 import {
     ClassDeclaration,
     Decorator,
+    Expression,
     MethodDeclaration,
     Node,
     ParameterDeclaration,
     Project,
     SourceFile,
-    SyntaxKind,
     ts,
 } from 'ts-morph';
 
@@ -34,6 +34,20 @@ import { HandlerData } from '../Data/HandlerData.ts';
  * All methods are protected so subclasses can override any step of the pipeline.
  */
 export abstract class AstReader {
+    /**
+     * Module resolution settings for {@link resolveModuleSpecifierToFilePath}.
+     *
+     * NodeNext mirrors how the application itself resolves its imports, and
+     * `allowImportingTsExtensions` matches the framework convention of writing
+     * the `.ts` extension in every import specifier.
+     */
+    protected static readonly MODULE_RESOLUTION_OPTIONS: ts.CompilerOptions = {
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        allowImportingTsExtensions: true,
+        noEmit: true,
+    };
+
     protected parseFileToSourceFile(filePath: string): SourceFile {
         if (!fs.existsSync(filePath)) {
             throw new AstFileReadException(`Cannot read file '${filePath}'.`);
@@ -98,14 +112,44 @@ export abstract class AstReader {
             return '';
         }
 
-        if (!moduleSpecifier.startsWith('.')) {
-            return '';
+        return this.resolveModuleSpecifierToFilePath(moduleSpecifier, currentFilePath);
+    }
+
+    /**
+     * Resolve a module specifier to the absolute path of the TypeScript file it points at.
+     *
+     * Relative specifiers resolve against the importing file's directory. Bare
+     * package specifiers (`@valkyrjaio/valkyrja/Cli/Routing/Data/Route.ts`) go
+     * through the TypeScript compiler's NodeNext resolver, which honors the
+     * package's `exports` map — so a provider tree that reaches into an
+     * installed package (the framework's own component providers, reached from
+     * the app config) is walked exactly like application source.
+     *
+     * Returns '' when the specifier cannot be resolved to an existing `.ts`
+     * source file. A package shipping only compiled `.js` — or only `.d.ts`
+     * declarations, which carry no `getRoutes()` body to read — has nothing for
+     * the AST readers to walk.
+     */
+    protected resolveModuleSpecifierToFilePath(moduleSpecifier: string, currentFilePath: string): string {
+        if (moduleSpecifier.startsWith('.')) {
+            const dir = path.dirname(currentFilePath);
+            const resolved = path.resolve(dir, moduleSpecifier.replace(/\.js$/, '.ts'));
+
+            return fs.existsSync(resolved) ? resolved : '';
         }
 
-        const dir = path.dirname(currentFilePath);
-        const resolved = path.resolve(dir, moduleSpecifier.replace(/\.js$/, '.ts'));
+        const resolved = ts.resolveModuleName(
+            moduleSpecifier,
+            currentFilePath,
+            AstReader.MODULE_RESOLUTION_OPTIONS,
+            ts.sys,
+        ).resolvedModule?.resolvedFileName;
 
-        return fs.existsSync(resolved) ? resolved : '';
+        if (resolved === undefined || !resolved.endsWith('.ts') || resolved.endsWith('.d.ts')) {
+            return '';
+        }
+
+        return resolved;
     }
 
     /**
@@ -141,6 +185,122 @@ export abstract class AstReader {
         return classes;
     }
 
+    /**
+     * Resolve a `new X()` or bare `X` identifier element to the absolute file
+     * path of the class it references, using the current file's import map.
+     *
+     * Returns undefined when the element is neither form, or when the name is
+     * not imported via a relative specifier (e.g. framework classes imported
+     * from a package — those are intentionally skipped by the provider walk).
+     */
+    protected resolveElementToFilePath(
+        element: ts.Expression,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+    ): string | undefined {
+        let name: string | undefined;
+
+        if (ts.isNewExpression(element)) {
+            name = ts.isIdentifier(element.expression) ? element.expression.text : undefined;
+        } else if (ts.isIdentifier(element)) {
+            name = element.text;
+        }
+
+        if (name === undefined) {
+            return undefined;
+        }
+
+        const resolved = this.resolveImportToFilePath(name, useMap, currentFilePath);
+
+        return resolved !== '' ? resolved : undefined;
+    }
+
+    /**
+     * Extract the absolute file paths of the classes referenced by a method
+     * returning [new A(), new B(), ...] (or [A, B, ...]).
+     *
+     * Unlike {@link extractClassListFromValues} (which returns bare class
+     * names), this resolves each reference through the import map so provider
+     * classes are located unambiguously — critical when the same short class
+     * name exists in more than one component tree (e.g. an Http and a Cli
+     * `ComponentProvider`).
+     */
+    protected extractClassPathListFromValues(
+        method: MethodDeclaration | undefined,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+    ): string[] {
+        if (method === undefined) {
+            return [];
+        }
+
+        const array = this.findReturnedArray(method);
+
+        if (array === undefined) {
+            return [];
+        }
+
+        return this.extractClassPathListFromArrayExpr(array, useMap, currentFilePath);
+    }
+
+    /**
+     * Extract the absolute file paths of the classes referenced by the elements
+     * of an array literal, using the current file's import map.
+     */
+    protected extractClassPathListFromArrayExpr(
+        array: ts.ArrayLiteralExpression,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+    ): string[] {
+        const paths: string[] = [];
+
+        for (const element of array.elements) {
+            const resolved = this.resolveElementToFilePath(element, useMap, currentFilePath);
+
+            if (resolved !== undefined) {
+                paths.push(resolved);
+            }
+        }
+
+        return paths;
+    }
+
+    /**
+     * Collect every identifier an expression references as a value.
+     *
+     * Expressions taken from a provider's `getRoutes()` body are emitted into
+     * the generated data cache verbatim, so the cache must import everything
+     * they name — not just the provider class, but the parameter/enum/constant
+     * classes the route arguments reach for. Property *names* are skipped (the
+     * `HELP` of `CommandName.HELP` is not an import) as are type positions,
+     * which erase at runtime and must never become a value import.
+     */
+    protected collectReferencedIdentifiers(node: ts.Node, names: Set<string> = new Set<string>()): Set<string> {
+        if (ts.isTypeNode(node)) {
+            return names;
+        }
+
+        if (ts.isIdentifier(node)) {
+            names.add(node.text);
+
+            return names;
+        }
+
+        if (ts.isPropertyAccessExpression(node)) {
+            return this.collectReferencedIdentifiers(node.expression, names);
+        }
+
+        if (ts.isPropertyAssignment(node)) {
+            return this.collectReferencedIdentifiers(node.initializer, names);
+        }
+
+        ts.forEachChild(node, (child: ts.Node): void => {
+            this.collectReferencedIdentifiers(child, names);
+        });
+
+        return names;
+    }
+
     /**
      * Extract service ID strings from keys of an object-returning method.
      *
@@ -296,7 +456,7 @@ export abstract class AstReader {
         }
 
         if (ts.isIdentifier(node)) {
-            return this.resolveStaticProperty(node.text, undefined, useMap, currentFilePath);
+            return this.resolveConstant(node.text, useMap, currentFilePath);
         }
 
         if (ts.isPropertyAccessExpression(node)) {
@@ -311,47 +471,108 @@ export abstract class AstReader {
     }
 
     /**
-     * Resolve a static property value by reading the imported source file.
+     * Resolve a static property value by reading the file that declares its class.
      */
     protected resolveStaticProperty(
         className: string,
-        propName: string | undefined,
+        propName: string,
         useMap: Record<string, string>,
         currentFilePath: string,
     ): string | undefined {
-        const importedFilePath = this.resolveImportToFilePath(className, useMap, currentFilePath);
+        const declaringClass = this.parseDeclaringSourceFile(className, useMap, currentFilePath)?.getClass(className);
 
-        if (importedFilePath === '') {
+        if (declaringClass === undefined) {
             return undefined;
         }
 
-        try {
-            const project = new Project({ skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: true });
-            const importedSource = project.addSourceFileAtPath(importedFilePath);
-            const importedClass = importedSource.getClass(className);
+        const prop = declaringClass.getStaticProperty(propName);
 
-            if (importedClass === undefined || propName === undefined) {
-                return undefined;
-            }
+        if (prop === undefined || !Node.isPropertyDeclaration(prop)) {
+            return undefined;
+        }
 
-            const prop = importedClass.getStaticProperty(propName);
+        return this.stringValueOf(prop.getInitializer());
+    }
 
-            if (prop === undefined) {
-                return undefined;
-            }
+    /**
+     * Resolve a module-level `const` to its string value.
+     *
+     * Not every binding key is a class static — some are plain exported
+     * constants, e.g. `export const LoggerContractId = 'Valkyrja.Log.Logger.LoggerContract' as const;`
+     */
+    protected resolveConstant(
+        name: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+    ): string | undefined {
+        const declaration = this.parseDeclaringSourceFile(name, useMap, currentFilePath)?.getVariableDeclaration(name);
 
-            if (Node.isPropertyDeclaration(prop)) {
-                const initializer = prop.getInitializer();
+        return this.stringValueOf(declaration?.getInitializer());
+    }
 
-                if (initializer?.isKind(SyntaxKind.StringLiteral) === true) {
-                    return (initializer as Node<ts.StringLiteral>).compilerNode.text;
-                }
-            }
+    /**
+     * Parse the file that declares a name: the module it is imported from, or
+     * the current file when the name is not imported.
+     *
+     * A provider commonly declares the binding keys for its own services
+     * alongside the publishers that use them, so `[Provider.SomeId]` names a
+     * constant that no import map can resolve — it lives in the file being read.
+     *
+     * Returns undefined when the file cannot be read.
+     */
+    protected parseDeclaringSourceFile(
+        name: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+    ): SourceFile | undefined {
+        const importedFilePath = this.resolveImportToFilePath(name, useMap, currentFilePath);
+        const filePath = importedFilePath !== '' ? importedFilePath : currentFilePath;
+
+        try {
+            const project = new Project({ skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: true });
+
+            return project.addSourceFileAtPath(filePath);
         } catch {
             // Silently skip unresolvable references
+            return undefined;
         }
+    }
 
-        return undefined;
+    /**
+     * The string a declaration's initializer holds, once its type-only wrappers are stripped.
+     */
+    protected stringValueOf(initializer: Expression | undefined): string | undefined {
+        if (initializer === undefined) {
+            return undefined;
+        }
+
+        const value = this.unwrapTypeAssertions(initializer.compilerNode);
+
+        return ts.isStringLiteral(value) ? value.text : undefined;
+    }
+
+    /**
+     * Strip the type-only wrappers an expression may be dressed in — `as`,
+     * `satisfies` and parentheses — to reach the value node underneath.
+     *
+     * Binding-key constants are declared `static readonly Data = 'Some.Id' as
+     * const;`, so the initializer node is an `AsExpression`, not the
+     * `StringLiteral` holding the value. Without unwrapping, every such key
+     * resolves to nothing and the publishers it names are dropped from the
+     * generated cache.
+     */
+    protected unwrapTypeAssertions(node: ts.Expression): ts.Expression {
+        let current = node;
+
+        while (
+            ts.isAsExpression(current) ||
+            ts.isSatisfiesExpression(current) ||
+            ts.isParenthesizedExpression(current)
+        ) {
+            current = current.expression;
+        }
+
+        return current;
     }
 
     /**

package/src/Sindri/Ast/ComponentProviderReader.ts

@@ -30,12 +30,16 @@ export class ComponentProviderReader extends AstReader implements ComponentProvi
         const useMap = this.buildUseMap(sourceFile);
         const methods = this.indexMethods(classDecl);
 
+        // Provider references are resolved through the file's import map to
+        // absolute paths (not bare names) so the walk locates each provider
+        // unambiguously — the same short name (e.g. `ComponentProvider`,
+        // `DataServiceProvider`) exists in both the Http and Cli trees.
         return new ComponentProviderResult(
-            this.extractClassListFromValues(methods[ComponentProviderReader.METHOD_COMPONENT], useMap, filePath),
-            this.extractClassListFromValues(methods[ComponentProviderReader.METHOD_CONTAINER], useMap, filePath),
-            this.extractClassListFromValues(methods[ComponentProviderReader.METHOD_EVENT], useMap, filePath),
-            this.extractClassListFromValues(methods[ComponentProviderReader.METHOD_CLI], useMap, filePath),
-            this.extractClassListFromValues(methods[ComponentProviderReader.METHOD_HTTP], useMap, filePath),
+            this.extractClassPathListFromValues(methods[ComponentProviderReader.METHOD_COMPONENT], useMap, filePath),
+            this.extractClassPathListFromValues(methods[ComponentProviderReader.METHOD_CONTAINER], useMap, filePath),
+            this.extractClassPathListFromValues(methods[ComponentProviderReader.METHOD_EVENT], useMap, filePath),
+            this.extractClassPathListFromValues(methods[ComponentProviderReader.METHOD_CLI], useMap, filePath),
+            this.extractClassPathListFromValues(methods[ComponentProviderReader.METHOD_HTTP], useMap, filePath),
         );
     }
 }

package/src/Sindri/Ast/ConfigReader.ts

@@ -190,21 +190,29 @@ export class ConfigReader extends AstReader implements ConfigReaderContract {
     }
 
     /**
-     * Extract provider class names from the providers argument.
-     * In CliConfig, providers is typically the 12th positional arg (index 11).
+     * Extract the absolute file paths of the configured provider classes.
+     *
+     * The providers array is the first array-literal argument after the
+     * `dataNamespace` (index 8) — every preceding argument is a scalar. Its
+     * exact position varies by config type (index 9 in `HttpConfig`, index 11
+     * in `CliConfig` after `applicationName`/`defaultCommandName`), so the
+     * array is located by scanning rather than by a fixed index.
+     *
+     * Each element (`new ComponentProvider()` or a bare `ComponentProvider`
+     * identifier) is resolved through the config file's import map to an
+     * absolute path, so the walk locates the right provider even when the same
+     * short name exists in multiple trees.
      */
     protected extractProvidersFromArgs(
         args: ts.NodeArray<ts.Expression>,
         useMap: Record<string, string>,
         filePath: string,
     ): string[] {
-        // Try to find the providers array in the argument list
-        // It's typically at index 11 in CliConfig
-        for (let i = 10; i < args.length; i++) {
+        for (let i = 9; i < args.length; i++) {
             const arg = args[i];
 
             if (arg !== undefined && ts.isArrayLiteralExpression(arg)) {
-                return this.extractClassListFromArrayExpr(arg, useMap, filePath);
+                return this.extractClassPathListFromArrayExpr(arg, useMap, filePath);
             }
         }
 

package/src/Sindri/Ast/Data/Result/RouteProviderResult.ts

@@ -10,15 +10,22 @@
 import type { ts } from 'ts-morph';
 
 export class RouteProviderResult {
+    /**
+     * @param routeImports Local name → absolute file path for every class the
+     *                     imperative `routes` expressions reference, so the
+     *                     generated data cache can import them.
+     */
     constructor(
         readonly controllerClasses: readonly string[] = [],
         readonly routes: readonly ts.Expression[] = [],
+        readonly routeImports: Readonly<Record<string, string>> = {},
     ) {}
 
     merge(other: RouteProviderResult): RouteProviderResult {
         return new RouteProviderResult(
             [...new Set([...this.controllerClasses, ...other.controllerClasses])],
             [...this.routes, ...other.routes],
+            { ...this.routeImports, ...other.routeImports },
         );
     }
 }

package/src/Sindri/Ast/RouteProviderReader.ts

@@ -7,7 +7,7 @@
  * file that was distributed with this source code.
  */
 
-import type { ts } from 'ts-morph';
+import { ts } from 'ts-morph';
 
 import { AstReader } from './Abstract/AstReader.ts';
 import { RouteProviderResult } from './Data/Result/RouteProviderResult.ts';
@@ -28,18 +28,69 @@ export class RouteProviderReader extends AstReader implements RouteProviderReade
 
         const useMap = this.buildUseMap(sourceFile);
         const methods = this.indexMethods(classDecl);
+        const routes = this.extractRoutes(methods[RouteProviderReader.METHOD_ROUTES], useMap, filePath);
 
         return new RouteProviderResult(
             this.extractClassListFromValues(methods[RouteProviderReader.METHOD_CONTROLLER_CLASSES], useMap, filePath),
-            this.extractRoutes(methods[RouteProviderReader.METHOD_ROUTES], useMap, filePath),
+            routes,
+            this.extractRouteImports(routes, useMap, filePath),
         );
     }
 
+    /**
+     * Resolve every class the imperative route expressions reference to its
+     * absolute file path, so the generated data cache can import them.
+     *
+     * Names that are not imported by the provider file — locals, globals, and
+     * the provider's own class (which the generator imports separately) — have
+     * no entry in the use map and are skipped.
+     */
+    protected extractRouteImports(
+        routes: readonly ts.Expression[],
+        useMap: Record<string, string>,
+        filePath: string,
+    ): Record<string, string> {
+        const imports: Record<string, string> = {};
+
+        for (const route of routes) {
+            for (const name of this.collectReferencedIdentifiers(route)) {
+                const resolved = this.resolveImportToFilePath(name, useMap, filePath);
+
+                if (resolved !== '') {
+                    imports[name] = resolved;
+                }
+            }
+        }
+
+        return imports;
+    }
+
+    /**
+     * Extract the route objects returned by a provider's `getRoutes()` method.
+     *
+     * TS route providers register routes imperatively — `getRoutes()` returns
+     * the concrete `new Route(...)` / `new DynamicRoute(...)` (or CLI
+     * `new Route(...)`) instances. Those expressions are returned verbatim for
+     * the data-cache generator to emit as route closures and to derive the
+     * path/regex lookup maps from. (Attribute/decorator scanning — the other,
+     * optional source of routes — is handled separately via
+     * {@link readFile}'s controller-class list.)
+     */
     protected extractRoutes(
-        _method: ReturnType<typeof this.indexMethods>[string] | undefined,
+        method: ReturnType<typeof this.indexMethods>[string] | undefined,
         _useMap: Record<string, string>,
         _filePath: string,
     ): ts.Expression[] {
-        return [];
+        if (method === undefined) {
+            return [];
+        }
+
+        const array = this.findReturnedArray(method);
+
+        if (array === undefined) {
+            return [];
+        }
+
+        return array.elements.filter((element): element is ts.NewExpression => ts.isNewExpression(element));
     }
 }

package/src/Sindri/Constant/SindriInfo.ts

@@ -8,8 +8,8 @@
  */
 
 export class SindriInfo {
-    static readonly VERSION = '26.2.0' as const;
-    static readonly VERSION_BUILD_DATE_TIME = 'July 25 2026 00:19:15 MST' as const;
+    static readonly VERSION = '26.4.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'July 27 2026 22:16:03 MST' as const;
     static readonly ICON = `\
     ██████████
     ████  ████