@valkyrjaio/sindri 26.3.0 → 26.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/sindri",
-    "version": "26.3.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.3.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;
+
+        if (resolved === undefined || !resolved.endsWith('.ts') || resolved.endsWith('.d.ts')) {
+            return '';
+        }
 
-        return fs.existsSync(resolved) ? resolved : '';
+        return resolved;
     }
 
     /**
@@ -221,6 +265,42 @@ export abstract class AstReader {
         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.
      *
@@ -376,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)) {
@@ -391,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/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

@@ -28,13 +28,43 @@ 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.
      *

package/src/Sindri/Constant/SindriInfo.ts

@@ -8,8 +8,8 @@
  */
 
 export class SindriInfo {
-    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 VERSION = '26.4.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'July 27 2026 22:16:03 MST' as const;
     static readonly ICON = `\
     ██████████
     ████  ████

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

@@ -222,6 +222,146 @@ export abstract class GenerateDataFromAst {
         return relative.startsWith('.') ? relative : `./${relative}`;
     }
 
+    /**
+     * Build the specifier a generated data file should import a class file by.
+     *
+     * Application source is imported by a path relative to the data directory;
+     * a file belonging to an installed package is imported by that package's
+     * own public specifier — so the framework classes the cache references are
+     * written exactly as hand-written application code writes them
+     * (`@valkyrjaio/valkyrja/Cli/Routing/Data/Route.ts`), never as a brittle
+     * reach into `node_modules`.
+     */
+    protected importSpecifier(fromDir: string, toFile: string): string {
+        return this.packageSpecifier(toFile) ?? this.relativeSpecifier(fromDir, toFile);
+    }
+
+    /**
+     * Map an absolute path inside an installed package back to the specifier
+     * that package publicly exposes it as, or undefined when the file is not
+     * part of one.
+     *
+     * The package's `exports` map is inverted: for `"./*.ts": "./src/*.ts"` a
+     * file at `<package>/src/Foo.ts` maps back to `<name>/Foo.ts`. Packages
+     * with no matching pattern fall back to the path as written under the
+     * package root, which is what a package without an `exports` map exposes.
+     */
+    protected packageSpecifier(filePath: string): string | undefined {
+        const normalized = filePath.split(path.sep).join('/');
+        const marker = normalized.lastIndexOf('/node_modules/');
+
+        if (marker === -1) {
+            return undefined;
+        }
+
+        const subject = normalized.substring(marker + '/node_modules/'.length);
+        const segments = subject.split('/');
+        const nameLength = subject.startsWith('@') ? 2 : 1;
+
+        if (segments.length <= nameLength) {
+            return undefined;
+        }
+
+        const packageName = segments.slice(0, nameLength).join('/');
+        const packageDir = normalized.substring(0, marker + '/node_modules/'.length) + packageName;
+        const relative = segments.slice(nameLength).join('/');
+
+        return `${packageName}/${this.exportedSubpath(packageDir, relative) ?? relative}`;
+    }
+
+    /**
+     * Invert a package's `exports` patterns to find the subpath a file inside
+     * it is exposed as, or undefined when no pattern matches it.
+     */
+    protected exportedSubpath(packageDir: string, relative: string): string | undefined {
+        for (const [key, target] of Object.entries(this.readPackageExports(packageDir))) {
+            const star = key.indexOf('*');
+            const targetStar = target.indexOf('*');
+
+            if (star === -1 || targetStar === -1) {
+                continue;
+            }
+
+            const prefix = target.substring(0, targetStar).replace(/^\.\//, '');
+            const suffix = target.substring(targetStar + 1);
+
+            if (!relative.startsWith(prefix) || !relative.endsWith(suffix)) {
+                continue;
+            }
+
+            const value = relative.substring(prefix.length, relative.length - suffix.length);
+
+            return (key.substring(0, star) + value + key.substring(star + 1)).replace(/^\.\//, '');
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Read a package's `exports` map, flattened to subpath → file target.
+     *
+     * Conditional targets are collapsed to their first string value; every
+     * condition a package declares for a subpath points at the same source
+     * file in the layouts sindri generates for.
+     */
+    protected readPackageExports(packageDir: string): Record<string, string> {
+        const manifestPath = path.join(packageDir, 'package.json');
+
+        if (!fs.existsSync(manifestPath)) {
+            return {};
+        }
+
+        let manifest: { exports?: unknown };
+
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as { exports?: unknown };
+        } catch {
+            return {};
+        }
+
+        const exports = manifest.exports;
+
+        if (typeof exports !== 'object' || exports === null) {
+            return {};
+        }
+
+        const flattened: Record<string, string> = {};
+
+        for (const [subpath, target] of Object.entries(exports as Record<string, unknown>)) {
+            const resolved = this.firstStringTarget(target);
+
+            if (resolved !== undefined) {
+                flattened[subpath] = resolved;
+            }
+        }
+
+        return flattened;
+    }
+
+    /**
+     * Reduce an `exports` target — a string, or a nested map of conditions — to
+     * the first file path it names.
+     */
+    protected firstStringTarget(target: unknown): string | undefined {
+        if (typeof target === 'string') {
+            return target;
+        }
+
+        if (typeof target !== 'object' || target === null) {
+            return undefined;
+        }
+
+        for (const value of Object.values(target as Record<string, unknown>)) {
+            const resolved = this.firstStringTarget(value);
+
+            if (resolved !== undefined) {
+                return resolved;
+            }
+        }
+
+        return undefined;
+    }
+
     protected generateContainerData(
         serviceProviders: readonly string[],
         config: ConfigResult,
@@ -246,7 +386,7 @@ export abstract class GenerateDataFromAst {
             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);
+                importMap[path.basename(filePath, '.ts')] = this.importSpecifier(config.dataPath, filePath);
             }
 
             Object.assign(publishers, result.publishers);
@@ -331,9 +471,15 @@ export abstract class GenerateDataFromAst {
 
             if (providerResult.routes.length > 0) {
                 // Imperative routes reference the provider's static handlers,
-                // so the generated data cache must import the provider class.
+                // so the generated data cache must import the provider class —
+                // along with every parameter/constant class the route arguments
+                // themselves name, since those are emitted verbatim.
                 imperativeRoutes.push(...providerResult.routes);
-                importMap[path.basename(filePath, '.ts')] = this.relativeSpecifier(config.dataPath, filePath);
+                importMap[path.basename(filePath, '.ts')] = this.importSpecifier(config.dataPath, filePath);
+
+                for (const [name, importPath] of Object.entries(providerResult.routeImports)) {
+                    importMap[name] = this.importSpecifier(config.dataPath, importPath);
+                }
             }
 
             for (const controllerClass of providerResult.controllerClasses) {
@@ -389,9 +535,15 @@ export abstract class GenerateDataFromAst {
 
             if (providerResult.routes.length > 0) {
                 // Imperative routes reference the provider's static handlers,
-                // so the generated data cache must import the provider class.
+                // so the generated data cache must import the provider class —
+                // along with every parameter/constant class the route arguments
+                // themselves name, since those are emitted verbatim.
                 imperativeRoutes.push(...providerResult.routes);
-                importMap[path.basename(filePath, '.ts')] = this.relativeSpecifier(config.dataPath, filePath);
+                importMap[path.basename(filePath, '.ts')] = this.importSpecifier(config.dataPath, filePath);
+
+                for (const [name, importPath] of Object.entries(providerResult.routeImports)) {
+                    importMap[name] = this.importSpecifier(config.dataPath, importPath);
+                }
             }
 
             for (const controllerClass of providerResult.controllerClasses) {

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

@@ -35,15 +35,29 @@ export abstract class AstFileGenerator {
      * 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).
+     *
+     * Names the generated file's fixed framework header already binds are
+     * dropped: those are the same framework classes under the same names, and
+     * emitting them twice is a duplicate-identifier error.
      */
-    protected buildUserImportsBlock(classImportMap: Record<string, string>): string {
+    protected buildUserImportsBlock(classImportMap: Record<string, string>, reservedNames: readonly string[]): string {
         const userImports = Object.entries(classImportMap)
+            .filter(([name]) => !reservedNames.includes(name))
             .map(([name, specifier]) => `import { ${name} } from '${specifier}';`)
             .join('\n');
 
         return userImports ? `${userImports}\n` : '';
     }
 
+    /**
+     * Render the fixed framework imports a generated data file always carries.
+     */
+    protected buildFrameworkImportLines(imports: Readonly<Record<string, string>>, isType: boolean = false): string[] {
+        const keyword = isType ? 'import type' : 'import';
+
+        return Object.entries(imports).map(([name, specifier]) => `${keyword} { ${name} } from '${specifier}';`);
+    }
+
     protected writeFile(directory: string, className: string, data: string): GenerateStatus {
         const filePath = directory.replace(/\/$/, '') + `/${className}.ts`;