@valkyrjaio/sindri 26.2.0 → 26.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/sindri",
-    "version": "26.2.0",
+    "version": "26.3.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.3.0",
         "ts-morph": "^28.0.0"
     },
     "scripts": {

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

@@ -141,6 +141,86 @@ 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;
+    }
+
     /**
      * Extract service ID strings from keys of an object-returning method.
      *

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/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';
@@ -35,11 +35,32 @@ export class RouteProviderReader extends AstReader implements RouteProviderReade
         );
     }
 
+    /**
+     * 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.3.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'July 25 2026 21:11:03 MST' as const;
     static readonly ICON = `\
     ██████████
     ████  ████

package/src/Sindri/Generate/Abstract/GenerateDataFromAst.ts

@@ -211,6 +211,17 @@ export abstract class GenerateDataFromAst {
         return '';
     }
 
+    /**
+     * Build the `import { X } from '...'` specifier for a class file, relative
+     * to the generated data file's output directory. Used to import the
+     * provider/handler classes referenced by the generated data caches.
+     */
+    protected relativeSpecifier(fromDir: string, toFile: string): string {
+        const relative = path.relative(fromDir, toFile).split(path.sep).join('/');
+
+        return relative.startsWith('.') ? relative : `./${relative}`;
+    }
+
     protected generateContainerData(
         serviceProviders: readonly string[],
         config: ConfigResult,
@@ -221,6 +232,7 @@ export abstract class GenerateDataFromAst {
             .writeMessages();
 
         const publishers: Record<string, readonly [string, string]> = {};
+        const importMap: Record<string, string> = {};
 
         for (const providerClass of serviceProviders) {
             const filePath = this.fqnToFilePath(providerClass, config.namespace, config.dir);
@@ -231,9 +243,17 @@ export abstract class GenerateDataFromAst {
 
             const result = this.serviceProviderReader.readFile(filePath);
 
+            if (Object.keys(result.publishers).length > 0) {
+                // The publisher callbacks reference the provider's static methods,
+                // so the generated data cache must import the provider class.
+                importMap[path.basename(filePath, '.ts')] = this.relativeSpecifier(config.dataPath, filePath);
+            }
+
             Object.assign(publishers, result.publishers);
         }
 
+        this.containerGenerator.classImportMap = importMap;
+
         const status = this.containerGenerator.generateFile(
             config.dataPath,
             'AppContainerData',
@@ -297,6 +317,8 @@ export abstract class GenerateDataFromAst {
             .writeMessages();
 
         const allRoutes: Record<string, ts.Expression> = {};
+        const imperativeRoutes: ts.Expression[] = [];
+        const importMap: Record<string, string> = {};
 
         for (const providerClass of cliRouteProviders) {
             const filePath = this.fqnToFilePath(providerClass, config.namespace, config.dir);
@@ -307,6 +329,13 @@ export abstract class GenerateDataFromAst {
 
             const providerResult = this.routeProviderReader.readFile(filePath);
 
+            if (providerResult.routes.length > 0) {
+                // Imperative routes reference the provider's static handlers,
+                // so the generated data cache must import the provider class.
+                imperativeRoutes.push(...providerResult.routes);
+                importMap[path.basename(filePath, '.ts')] = this.relativeSpecifier(config.dataPath, filePath);
+            }
+
             for (const controllerClass of providerResult.controllerClasses) {
                 const controllerPath = this.fqnToFilePath(controllerClass, config.namespace, config.dir);
 
@@ -320,12 +349,17 @@ export abstract class GenerateDataFromAst {
             }
         }
 
-        const status = this.cliGenerator.generateFile(
-            config.dataPath,
-            'AppCliRoutingData',
-            config.dataNamespace,
-            allRoutes,
-        );
+        this.cliGenerator.classImportMap = importMap;
+
+        const status =
+            imperativeRoutes.length > 0
+                ? this.cliGenerator.generateFileFromRoutes(
+                      config.dataPath,
+                      'AppCliRoutingData',
+                      config.dataNamespace,
+                      imperativeRoutes,
+                  )
+                : this.cliGenerator.generateFile(config.dataPath, 'AppCliRoutingData', config.dataNamespace, allRoutes);
 
         return this.addMessagesForGenerateStatus(output, status).withAddedMessages(new NewLine()).writeMessages();
     }
@@ -341,6 +375,8 @@ export abstract class GenerateDataFromAst {
 
         const allRoutes: Record<string, ts.Expression> = {};
         const allRouteData: Record<string, HttpRouteData> = {};
+        const imperativeRoutes: ts.Expression[] = [];
+        const importMap: Record<string, string> = {};
 
         for (const providerClass of httpRouteProviders) {
             const filePath = this.fqnToFilePath(providerClass, config.namespace, config.dir);
@@ -351,6 +387,13 @@ export abstract class GenerateDataFromAst {
 
             const providerResult = this.routeProviderReader.readFile(filePath);
 
+            if (providerResult.routes.length > 0) {
+                // Imperative routes reference the provider's static handlers,
+                // so the generated data cache must import the provider class.
+                imperativeRoutes.push(...providerResult.routes);
+                importMap[path.basename(filePath, '.ts')] = this.relativeSpecifier(config.dataPath, filePath);
+            }
+
             for (const controllerClass of providerResult.controllerClasses) {
                 const controllerPath = this.fqnToFilePath(controllerClass, config.namespace, config.dir);
 
@@ -365,13 +408,23 @@ export abstract class GenerateDataFromAst {
             }
         }
 
-        const status = this.httpGenerator.generateFile(
-            config.dataPath,
-            'AppHttpRoutingData',
-            config.dataNamespace,
-            allRoutes,
-            allRouteData,
-        );
+        this.httpGenerator.classImportMap = importMap;
+
+        const status =
+            imperativeRoutes.length > 0
+                ? this.httpGenerator.generateFileFromRoutes(
+                      config.dataPath,
+                      'AppHttpRoutingData',
+                      config.dataNamespace,
+                      imperativeRoutes,
+                  )
+                : this.httpGenerator.generateFile(
+                      config.dataPath,
+                      'AppHttpRoutingData',
+                      config.dataNamespace,
+                      allRoutes,
+                      allRouteData,
+                  );
 
         return this.addMessagesForGenerateStatus(output, status).withAddedMessages(new NewLine()).writeMessages();
     }

package/src/Sindri/Generator/Abstract/AstFileGenerator.ts

@@ -31,6 +31,19 @@ export abstract class AstFileGenerator {
         return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(className), caseName);
     }
 
+    /**
+     * Build the `import { X } from '...';` block for the provider/handler classes
+     * a generated data cache references, followed by a trailing newline (or an
+     * empty string when there are no such imports).
+     */
+    protected buildUserImportsBlock(classImportMap: Record<string, string>): string {
+        const userImports = Object.entries(classImportMap)
+            .map(([name, specifier]) => `import { ${name} } from '${specifier}';`)
+            .join('\n');
+
+        return userImports ? `${userImports}\n` : '';
+    }
+
     protected writeFile(directory: string, className: string, data: string): GenerateStatus {
         const filePath = directory.replace(/\/$/, '') + `/${className}.ts`;
 

package/src/Sindri/Generator/Ast/Cli/AstCliDataFileGenerator.ts

@@ -32,11 +32,7 @@ export class AstCliDataFileGenerator extends AstFileGenerator implements CliData
         namespace: string,
         routes: Record<string, ts.Expression>,
     ): GenerateStatus {
-        const userImports = Object.entries(this.classImportMap)
-            .map(([name, specifier]) => `import { ${name} } from '${specifier}';`)
-            .join('\n');
-
-        const userImportsBlock = userImports ? `${userImports}\n` : '';
+        const userImportsBlock = this.buildUserImportsBlock(this.classImportMap);
 
         const contents = this.generateClassContents(routes);
 
@@ -64,6 +60,36 @@ export class AstCliDataFileGenerator extends AstFileGenerator implements CliData
         return this.writeFile(directory, className, data);
     }
 
+    /**
+     * Generate the CLI routing data file from imperative `getRoutes()` route
+     * objects — each `new Route(name, description, handler, ...)` is keyed by
+     * its command name (the first constructor argument) and emitted verbatim.
+     */
+    public generateFileFromRoutes(
+        directory: string,
+        className: string,
+        namespace: string,
+        routeExprs: readonly ts.Expression[],
+    ): GenerateStatus {
+        const routes: Record<string, ts.Expression> = {};
+
+        for (const expr of routeExprs) {
+            if (!ts.isNewExpression(expr)) {
+                continue;
+            }
+
+            const nameArg = (expr.arguments ?? [])[0];
+
+            if (nameArg === undefined || !ts.isStringLiteral(nameArg)) {
+                continue;
+            }
+
+            routes[nameArg.text] = expr;
+        }
+
+        return this.generateFile(directory, className, namespace, routes);
+    }
+
     public generateClassContents(routes: Record<string, ts.Expression>): string {
         const entries = Object.entries(routes);
 
@@ -74,15 +100,25 @@ export class AstCliDataFileGenerator extends AstFileGenerator implements CliData
         const lines: string[] = [];
 
         for (const [key, valueExpr] of entries) {
-            const keyExpr = this.buildEnumCaseExpr(key);
-            const printedKey = this.printer.printNode(ts.EmitHint.Unspecified, keyExpr, this.dummySourceFile);
-            const printedValue = this.printer.printNode(ts.EmitHint.Unspecified, valueExpr, this.dummySourceFile);
-
-            const formattedKey = key.includes('::') ? `[${printedKey}]` : `['${printedKey}']`;
+            const printedValue = this.printExpr(valueExpr);
+            const formattedKey = key.includes('::')
+                ? `[${this.printer.printNode(ts.EmitHint.Unspecified, this.buildEnumCaseExpr(key), this.dummySourceFile)}]`
+                : `['${key}']`;
 
             lines.push(`            ${formattedKey}: (): RouteContract => ${printedValue},`);
         }
 
-        return ['super({', '            routes: {', ...lines, '            },', '        });'].join('\n        ');
+        return ['super({', ...lines, '        });'].join('\n        ');
+    }
+
+    /**
+     * Print an expression to source. Parsed nodes (from a `getRoutes()` body)
+     * are emitted via their original source text; synthesized nodes (which
+     * carry no source positions) are emitted through the printer.
+     */
+    protected printExpr(expr: ts.Expression): string {
+        return expr.pos >= 0
+            ? expr.getText()
+            : this.printer.printNode(ts.EmitHint.Unspecified, expr, this.dummySourceFile);
     }
 }

package/src/Sindri/Generator/Ast/Container/AstContainerDataFileGenerator.ts

@@ -32,11 +32,7 @@ export class AstContainerDataFileGenerator extends AstFileGenerator implements C
         namespace: string,
         publishers: Readonly<Record<string, readonly [string, string]>>,
     ): GenerateStatus {
-        const userImports = Object.entries(this.classImportMap)
-            .map(([name, specifier]) => `import { ${name} } from '${specifier}';`)
-            .join('\n');
-
-        const userImportsBlock = userImports ? `${userImports}\n` : '';
+        const userImportsBlock = this.buildUserImportsBlock(this.classImportMap);
 
         const contents = this.generateClassContents(publishers);
 
@@ -67,12 +63,11 @@ export class AstContainerDataFileGenerator extends AstFileGenerator implements C
         const lines: string[] = [];
 
         for (const [serviceId, [providerClass, methodName]] of entries) {
-            const keyExpr = this.buildEnumCaseExpr(serviceId);
-            const printedKey = this.printer.printNode(ts.EmitHint.Unspecified, keyExpr, this.dummySourceFile);
-
             const shortProviderClass = providerClass.slice(providerClass.lastIndexOf('\\') + 1);
 
-            const formattedKey = serviceId.includes('::') ? `[${printedKey}]` : `['${printedKey}']`;
+            const formattedKey = serviceId.includes('::')
+                ? `[${this.printer.printNode(ts.EmitHint.Unspecified, this.buildEnumCaseExpr(serviceId), this.dummySourceFile)}]`
+                : `['${serviceId}']`;
 
             lines.push(
                 `            ${formattedKey}: (container: ContainerContract) => ${shortProviderClass}.${methodName}(container),`,

package/src/Sindri/Generator/Ast/Event/AstEventDataFileGenerator.ts

@@ -32,20 +32,26 @@ export class AstEventDataFileGenerator extends AstFileGenerator implements Event
         namespace: string,
         listeners: Record<string, ts.Expression>,
     ): GenerateStatus {
-        const userImports = Object.entries(this.classImportMap)
-            .map(([name, specifier]) => `import { ${name} } from '${specifier}';`)
-            .join('\n');
-
-        const userImportsBlock = userImports ? `${userImports}\n` : '';
+        const userImportsBlock = this.buildUserImportsBlock(this.classImportMap);
 
         const contents = this.generateClassContents(listeners);
 
+        // The Listener / ListenerContract imports are only referenced by the
+        // generated listener closures — omit them when there are no listeners
+        // so empty event data does not carry unused (and unresolved) imports.
+        const listenerImports =
+            Object.keys(listeners).length > 0
+                ? [
+                      `import { Listener } from '@valkyrjaio/valkyrja/Event/Data/Listener.ts';`,
+                      `import type { ListenerContract } from '@valkyrjaio/valkyrja/Event/Data/Contract/ListenerContract.ts';`,
+                  ]
+                : [];
+
         const data = [
             '// This file was automatically generated by Sindri.',
             '',
             `import { EventData } from '@valkyrjaio/valkyrja/Event/Data/EventData.ts';`,
-            `import { Listener } from '@valkyrjaio/valkyrja/Event/Data/Listener.ts';`,
-            `import type { ListenerContract } from '@valkyrjaio/valkyrja/Event/Data/Contract/ListenerContract.ts';`,
+            ...listenerImports,
             userImportsBlock,
             `export class ${className} extends EventData {`,
             `    constructor() {`,