@valkyrjaio/sindri 26.1.3 → 26.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/sindri",
-    "version": "26.1.3",
+    "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.1.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/CliRouteAttributeReader.ts

@@ -73,7 +73,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
         }
 
         const updatedName = this.updateName(name, method, useMap, currentFilePath, currentClass);
-        const [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware] =
+        const [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware] =
             this.updateMiddleware(
                 method,
                 useMap,
@@ -93,7 +93,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
             routeMatchedMiddleware,
             routeDispatchedMiddleware,
             throwableCaughtMiddleware,
-            exitedMiddleware,
+            processExitingMiddleware,
             this.parameterReader.updateArguments(method, useMap, currentFilePath, currentClass),
             this.parameterReader.updateOptions(method, useMap, currentFilePath, currentClass),
         );
@@ -130,7 +130,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
         routeMatchedMiddleware: string[],
         routeDispatchedMiddleware: string[],
         throwableCaughtMiddleware: string[],
-        exitedMiddleware: string[],
+        processExitingMiddleware: string[],
     ): [string[], string[], string[], string[]] {
         for (const decorator of this.findDecoratorsOnNode(method, 'Middleware', useMap, currentFilePath)) {
             const mwName = this.extractExprValue(
@@ -144,7 +144,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
                 continue;
             }
 
-            [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware] =
+            [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware] =
                 this.classifyMiddleware(
                     mwName,
                     useMap,
@@ -152,11 +152,11 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
                     routeMatchedMiddleware,
                     routeDispatchedMiddleware,
                     throwableCaughtMiddleware,
-                    exitedMiddleware,
+                    processExitingMiddleware,
                 );
         }
 
-        return [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware];
+        return [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware];
     }
 
     protected classifyMiddleware(
@@ -166,7 +166,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
         routeMatchedMiddleware: string[],
         routeDispatchedMiddleware: string[],
         throwableCaughtMiddleware: string[],
-        exitedMiddleware: string[],
+        processExitingMiddleware: string[],
     ): [string[], string[], string[], string[]] {
         if (this.classImplementsInterface(mwName, 'RouteMatchedMiddlewareContract', useMap, currentFilePath)) {
             routeMatchedMiddleware = [...routeMatchedMiddleware, mwName];
@@ -180,11 +180,11 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
             throwableCaughtMiddleware = [...throwableCaughtMiddleware, mwName];
         }
 
-        if (this.classImplementsInterface(mwName, 'ExitedMiddlewareContract', useMap, currentFilePath)) {
-            exitedMiddleware = [...exitedMiddleware, mwName];
+        if (this.classImplementsInterface(mwName, 'ProcessExitingMiddlewareContract', useMap, currentFilePath)) {
+            processExitingMiddleware = [...processExitingMiddleware, mwName];
         }
 
-        return [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware];
+        return [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware];
     }
 
     protected buildRouteExpr(data: CliRouteData): ts.Expression {
@@ -213,7 +213,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
             this.buildClassArrayExpr(data.routeMatchedMiddleware),
             this.buildClassArrayExpr(data.routeDispatchedMiddleware),
             this.buildClassArrayExpr(data.throwableCaughtMiddleware),
-            this.buildClassArrayExpr(data.exitedMiddleware),
+            this.buildClassArrayExpr(data.processExitingMiddleware),
         ];
     }
 }

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/Contract/HttpRouteMiddlewareReaderContract.ts

@@ -38,7 +38,7 @@ export interface HttpRouteMiddlewareReaderContract {
         routeDispatchedMiddleware: string[],
         throwableCaughtMiddleware: string[],
         sendingResponseMiddleware: string[],
-        terminatedMiddleware: string[],
+        responseSentMiddleware: string[],
     ): [string[], string[], string[], string[], string[]];
 
     updateRequestStruct(

package/src/Sindri/Ast/Data/CliRouteData.ts

@@ -23,7 +23,7 @@ export class CliRouteData implements CliRouteDataContract {
         readonly routeMatchedMiddleware: readonly string[] = [],
         readonly routeDispatchedMiddleware: readonly string[] = [],
         readonly throwableCaughtMiddleware: readonly string[] = [],
-        readonly exitedMiddleware: readonly string[] = [],
+        readonly processExitingMiddleware: readonly string[] = [],
         args: readonly CliArgumentParameterData[] = [],
         readonly options: readonly CliOptionParameterData[] = [],
     ) {

package/src/Sindri/Ast/Data/Contract/CliRouteDataContract.ts

@@ -19,7 +19,7 @@ export interface CliRouteDataContract {
     readonly routeMatchedMiddleware: readonly string[];
     readonly routeDispatchedMiddleware: readonly string[];
     readonly throwableCaughtMiddleware: readonly string[];
-    readonly exitedMiddleware: readonly string[];
+    readonly processExitingMiddleware: readonly string[];
     readonly arguments: readonly CliArgumentParameterDataContract[];
     readonly options: readonly CliOptionParameterDataContract[];
 }

package/src/Sindri/Ast/Data/Contract/HttpRouteDataContract.ts

@@ -20,7 +20,7 @@ export interface HttpRouteDataContract {
     readonly routeDispatchedMiddleware: readonly string[];
     readonly throwableCaughtMiddleware: readonly string[];
     readonly sendingResponseMiddleware: readonly string[];
-    readonly terminatedMiddleware: readonly string[];
+    readonly responseSentMiddleware: readonly string[];
     readonly requestStruct: string | null;
     readonly responseStruct: string | null;
     readonly isDynamic: boolean;

package/src/Sindri/Ast/Data/HttpRouteData.ts

@@ -21,7 +21,7 @@ export class HttpRouteData implements HttpRouteDataContract {
         readonly routeDispatchedMiddleware: readonly string[] = [],
         readonly throwableCaughtMiddleware: readonly string[] = [],
         readonly sendingResponseMiddleware: readonly string[] = [],
-        readonly terminatedMiddleware: readonly string[] = [],
+        readonly responseSentMiddleware: readonly string[] = [],
         readonly requestStruct: string | null = null,
         readonly responseStruct: string | null = null,
         readonly isDynamic: boolean = false,

package/src/Sindri/Ast/HttpRouteAttributeReader.ts

@@ -188,7 +188,7 @@ export class HttpRouteAttributeReader extends RouteAttributeReader implements Ht
             routeDispatchedMiddleware,
             throwableCaughtMiddleware,
             sendingResponseMiddleware,
-            terminatedMiddleware,
+            responseSentMiddleware,
         ] = this.middlewareReader.updateMiddleware(
             method,
             useMap,
@@ -210,7 +210,7 @@ export class HttpRouteAttributeReader extends RouteAttributeReader implements Ht
             routeDispatchedMiddleware,
             throwableCaughtMiddleware,
             sendingResponseMiddleware,
-            terminatedMiddleware,
+            responseSentMiddleware,
             this.middlewareReader.updateRequestStruct(method, useMap, currentFilePath, currentClass),
             this.middlewareReader.updateResponseStruct(method, useMap, currentFilePath, currentClass),
             resolvedIsDynamic,

package/src/Sindri/Ast/HttpRouteMiddlewareReader.ts

@@ -75,7 +75,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
         routeDispatchedMiddleware: string[],
         throwableCaughtMiddleware: string[],
         sendingResponseMiddleware: string[],
-        terminatedMiddleware: string[],
+        responseSentMiddleware: string[],
     ): [string[], string[], string[], string[], string[]] {
         for (const decorator of this.findDecoratorsOnNode(method, 'Middleware', useMap, namespace)) {
             const mwName = this.extractExprValue(this.getDecoratorArg(decorator, 0), useMap, namespace, currentClass);
@@ -89,7 +89,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
                 routeDispatchedMiddleware,
                 throwableCaughtMiddleware,
                 sendingResponseMiddleware,
-                terminatedMiddleware,
+                responseSentMiddleware,
             ] = this.classifyMiddleware(
                 mwName,
                 useMap,
@@ -98,7 +98,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
                 routeDispatchedMiddleware,
                 throwableCaughtMiddleware,
                 sendingResponseMiddleware,
-                terminatedMiddleware,
+                responseSentMiddleware,
             );
         }
 
@@ -107,7 +107,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
             routeDispatchedMiddleware,
             throwableCaughtMiddleware,
             sendingResponseMiddleware,
-            terminatedMiddleware,
+            responseSentMiddleware,
         ];
     }
 
@@ -151,7 +151,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
             this.buildClassIdentifierArrayExpr(data.routeDispatchedMiddleware),
             this.buildClassIdentifierArrayExpr(data.throwableCaughtMiddleware),
             this.buildClassIdentifierArrayExpr(data.sendingResponseMiddleware),
-            this.buildClassIdentifierArrayExpr(data.terminatedMiddleware),
+            this.buildClassIdentifierArrayExpr(data.responseSentMiddleware),
         ];
     }
 
@@ -181,7 +181,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
         routeDispatchedMiddleware: string[],
         throwableCaughtMiddleware: string[],
         sendingResponseMiddleware: string[],
-        terminatedMiddleware: string[],
+        responseSentMiddleware: string[],
     ): [string[], string[], string[], string[], string[]] {
         if (this.classImplementsInterface(mwName, 'RouteMatchedMiddlewareContract', useMap, currentFilePath)) {
             routeMatchedMiddleware = [...routeMatchedMiddleware, mwName];
@@ -199,8 +199,8 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
             sendingResponseMiddleware = [...sendingResponseMiddleware, mwName];
         }
 
-        if (this.classImplementsInterface(mwName, 'TerminatedMiddlewareContract', useMap, currentFilePath)) {
-            terminatedMiddleware = [...terminatedMiddleware, mwName];
+        if (this.classImplementsInterface(mwName, 'ResponseSentMiddlewareContract', useMap, currentFilePath)) {
+            responseSentMiddleware = [...responseSentMiddleware, mwName];
         }
 
         return [
@@ -208,7 +208,7 @@ export class HttpRouteMiddlewareReader extends AstReader implements HttpRouteMid
             routeDispatchedMiddleware,
             throwableCaughtMiddleware,
             sendingResponseMiddleware,
-            terminatedMiddleware,
+            responseSentMiddleware,
         ];
     }
 }

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.1.3' as const;
-    static readonly VERSION_BUILD_DATE_TIME = 'June 21 2026 11:20:36 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`;