@valkyrjaio/sindri 26.6.65 → 26.6.67

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/sindri",
-    "version": "26.6.65",
+    "version": "26.6.67",
     "description": "The Valkyrja Sindri build tool.",
     "homepage": "https://www.valkyrja.io/sindri",
     "keywords": [

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

@@ -285,21 +285,87 @@ export abstract class AstReader {
             return names;
         }
 
-        if (ts.isPropertyAccessExpression(node)) {
-            return this.collectReferencedIdentifiers(node.expression, names);
+        if (ts.isBindingElement(node)) {
+            // The `config` of `{ config: c }` names a property of the value, where the `CliA` of
+            // `{ [CliA.KEY]: c }` is an expression the generated file evaluates.
+            if (node.propertyName !== undefined && ts.isComputedPropertyName(node.propertyName)) {
+                this.collectReferencedIdentifiers(node.propertyName.expression, names);
+            }
+
+            this.collectReferencedIdentifiers(node.name, names);
+
+            return node.initializer === undefined ? names : this.collectReferencedIdentifiers(node.initializer, names);
         }
 
-        if (ts.isPropertyAssignment(node)) {
-            return this.collectReferencedIdentifiers(node.initializer, names);
+        // An identifier a `name` slot carries declares or keys the name, such as the `HELP` of
+        // `CommandName.HELP`, and only a shorthand property references the name it carries.
+        const slotName: ts.Node | undefined =
+            'name' in node &&
+            node.name !== undefined &&
+            ts.isIdentifier(node.name as ts.Node) &&
+            !ts.isShorthandPropertyAssignment(node)
+                ? (node.name as ts.Node)
+                : undefined;
+
+        ts.forEachChild(node, (child: ts.Node): void => {
+            if (child !== slotName) {
+                this.collectReferencedIdentifiers(child, names);
+            }
+        });
+
+        return names;
+    }
+
+    /**
+     * The names the provider file declares anywhere in itself, less the file's own base name, which
+     * is the name the generated data file imports the provider by.
+     */
+    protected collectFileNames(sourceFile: SourceFile, filePath: string): Set<string> {
+        const names = this.collectDeclaredNames(sourceFile.compilerNode);
+
+        names.delete(path.basename(filePath, '.ts'));
+
+        return names;
+    }
+
+    /**
+     * The names a node declares, such as the parameters of an inline handler.
+     *
+     * A name any part of an expression declares counts as declared throughout it, which reads a
+     * shadowed name as declared rather than stopping on it.
+     */
+    protected collectDeclaredNames(node: ts.Node, names: Set<string> = new Set<string>()): Set<string> {
+        if (AstReader.declaresName(node) && node.name !== undefined && ts.isIdentifier(node.name)) {
+            names.add(node.name.text);
         }
 
         ts.forEachChild(node, (child: ts.Node): void => {
-            this.collectReferencedIdentifiers(child, names);
+            this.collectDeclaredNames(child, names);
         });
 
         return names;
     }
 
+    /**
+     * Whether a node's `name` declares a binding rather than naming one.
+     *
+     * A property access, a shorthand property and an object-literal key all carry a `name` that
+     * references or keys instead of declaring, so the kind decides rather than the slot.
+     */
+    protected static declaresName(node: ts.Node): node is ts.NamedDeclaration {
+        return (
+            ts.isParameter(node) ||
+            ts.isVariableDeclaration(node) ||
+            ts.isBindingElement(node) ||
+            ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isClassExpression(node) ||
+            ts.isEnumDeclaration(node) ||
+            ts.isModuleDeclaration(node)
+        );
+    }
+
     /**
      * Extract service ID strings from keys of an object-returning method.
      *

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

@@ -9,5 +9,12 @@
 import type { ts } from 'ts-morph';
 
 export class ListenerAttributeResult {
-    constructor(readonly listeners: Record<string, ts.Expression> = {}) {}
+    /**
+     * @param listeners A Map, because an object reorders a key that reads as an integer
+     * @param importMap Class short name → absolute file path for the handler imports
+     */
+    constructor(
+        readonly listeners: ReadonlyMap<string, ts.Expression> = new Map(),
+        readonly importMap: Record<string, string> = {},
+    ) {}
 }

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

@@ -9,15 +9,21 @@
 import type { ts } from 'ts-morph';
 
 export class ListenerProviderResult {
+    /**
+     * @param listenerImports Local name → absolute file path for every class the `listeners`
+     *                        expressions reference
+     */
     constructor(
         readonly listenerClasses: readonly string[] = [],
         readonly listeners: readonly ts.Expression[] = [],
+        readonly listenerImports: Readonly<Record<string, string>> = {},
     ) {}
 
     merge(other: ListenerProviderResult): ListenerProviderResult {
         return new ListenerProviderResult(
             [...new Set([...this.listenerClasses, ...other.listenerClasses])],
             [...this.listeners, ...other.listeners],
+            { ...this.listenerImports, ...other.listenerImports },
         );
     }
 }

package/src/Sindri/Ast/ListenerAttributeReader.ts

@@ -35,13 +35,15 @@ export class ListenerAttributeReader extends AstReader implements ListenerAttrib
         }
 
         const { classDecl, useMap, currentClass } = context;
-        const listeners: Record<string, ts.Expression> = {};
+        const listeners = new Map<string, ts.Expression>();
+        const listenerData: ListenerData[] = [];
 
         for (const decorator of this.findDecoratorsOnNode(classDecl, 'Listener', useMap, filePath)) {
             const data = this.buildListenerData(decorator, useMap, filePath, currentClass, classDecl, undefined);
 
             if (data !== null) {
-                listeners[data.name] = this.buildListenerExpr(data);
+                listeners.set(data.name, this.buildListenerExpr(data));
+                listenerData.push(data);
             }
         }
 
@@ -50,12 +52,48 @@ export class ListenerAttributeReader extends AstReader implements ListenerAttrib
                 const data = this.buildListenerData(decorator, useMap, filePath, currentClass, classDecl, method);
 
                 if (data !== null) {
-                    listeners[data.name] = this.buildListenerExpr(data);
+                    listeners.set(data.name, this.buildListenerExpr(data));
+                    listenerData.push(data);
                 }
             }
         }
 
-        return new ListenerAttributeResult(listeners);
+        return new ListenerAttributeResult(
+            listeners,
+            this.buildImportMap(listenerData, useMap, filePath, currentClass),
+        );
+    }
+
+    /**
+     * Build the class-name → absolute-file-path map for every handler class the generated data
+     * cache references.
+     */
+    protected buildImportMap(
+        listenerData: readonly ListenerData[],
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): Record<string, string> {
+        const importMap: Record<string, string> = {};
+
+        for (const data of listenerData) {
+            if (data.handler === null) {
+                continue;
+            }
+
+            const shortName = data.handler.class.slice(data.handler.class.lastIndexOf('\\') + 1);
+
+            const filePath =
+                shortName === currentClass
+                    ? currentFilePath
+                    : this.resolveClassToFilePath(shortName, useMap, currentFilePath);
+
+            if (filePath !== '') {
+                importMap[shortName] = filePath;
+            }
+        }
+
+        return importMap;
     }
 
     protected buildListenerData(

package/src/Sindri/Ast/ListenerProviderReader.ts

@@ -6,10 +6,11 @@
  * Released under the MIT License. See LICENSE.md for details.
  */
 
-import type { ts } from 'ts-morph';
+import { ts } from 'ts-morph';
 
 import { AstReader } from './Abstract/AstReader.ts';
 import { ListenerProviderResult } from './Data/Result/ListenerProviderResult.ts';
+import { AstUnreadableListenerException } from './Throwable/Exception/AstUnreadableListenerException.ts';
 
 import type { ListenerProviderReaderContract } from './Contract/ListenerProviderReaderContract.ts';
 
@@ -27,18 +28,80 @@ export class ListenerProviderReader extends AstReader implements ListenerProvide
 
         const useMap = this.buildUseMap(sourceFile);
         const methods = this.indexMethods(classDecl);
+        const listeners = this.extractListeners(methods[ListenerProviderReader.METHOD_LISTENERS]);
 
         return new ListenerProviderResult(
             this.extractClassListFromValues(methods[ListenerProviderReader.METHOD_LISTENER_CLASSES], useMap, filePath),
-            this.extractListeners(methods[ListenerProviderReader.METHOD_LISTENERS], useMap, filePath),
+            listeners,
+            this.extractListenerImports(listeners, useMap, filePath, this.collectFileNames(sourceFile, filePath)),
         );
     }
 
+    /**
+     * Extract the listeners a provider's `getListeners()` method returns, which the generator
+     * emits verbatim.
+     */
     protected extractListeners(
-        _method: ReturnType<typeof this.indexMethods>[string] | undefined,
-        _useMap: Record<string, string>,
-        _filePath: string,
-    ): ts.Expression[] {
-        return [];
+        method: ReturnType<typeof this.indexMethods>[string] | undefined,
+    ): readonly ts.Expression[] {
+        if (method === undefined) {
+            return [];
+        }
+
+        const array = this.findReturnedArray(method);
+
+        if (array === undefined) {
+            return [];
+        }
+
+        return array.elements.filter((element) => this.isConstructedListener(element));
+    }
+
+    /** Whether an expression declares a listener through a construction, with or without a chain. */
+    protected isConstructedListener(expression: ts.Expression): boolean {
+        let current = this.unwrapTypeAssertions(expression);
+
+        while (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+            current = this.unwrapTypeAssertions(current.expression.expression);
+        }
+
+        return ts.isNewExpression(current);
+    }
+
+    /**
+     * Resolve every class the listener expressions reference to its absolute file path, so the
+     * generated data cache can import them.
+     */
+    protected extractListenerImports(
+        listeners: readonly ts.Expression[],
+        useMap: Record<string, string>,
+        filePath: string,
+        fileNames: ReadonlySet<string>,
+    ): Record<string, string> {
+        const imports: Record<string, string> = {};
+
+        for (const listener of listeners) {
+            const declaredNames = this.collectDeclaredNames(listener);
+
+            for (const name of this.collectReferencedIdentifiers(listener)) {
+                const resolved = this.resolveImportToFilePath(name, useMap, filePath);
+
+                if (resolved !== '') {
+                    imports[name] = resolved;
+
+                    continue;
+                }
+
+                // A name the provider file declares for itself is one the generated data file, in
+                // another module, cannot reach. Every other unresolved name is a global.
+                if (fileNames.has(name) && !declaredNames.has(name)) {
+                    throw new AstUnreadableListenerException(
+                        `Cannot read the listener '${listener.getText()}': the generated data cannot import '${name}', which the provider declares for itself.`,
+                    );
+                }
+            }
+        }
+
+        return imports;
     }
 }

package/src/Sindri/Ast/RouteProviderReader.ts

@@ -10,6 +10,7 @@ import { ts } from 'ts-morph';
 
 import { AstReader } from './Abstract/AstReader.ts';
 import { RouteProviderResult } from './Data/Result/RouteProviderResult.ts';
+import { AstUnreadableRouteException } from './Throwable/Exception/AstUnreadableRouteException.ts';
 
 import type { RouteProviderReaderContract } from './Contract/RouteProviderReaderContract.ts';
 
@@ -28,21 +29,22 @@ 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);
+        const routeImports = this.extractRouteImports(routes, useMap, filePath);
+
+        // A further list of route expressions needs a call of its own, because a name is validated
+        // against the expression that references it.
+        this.validateRouteImports(routes, routeImports, useMap, this.collectFileNames(sourceFile, filePath));
 
         return new RouteProviderResult(
             this.extractClassListFromValues(methods[RouteProviderReader.METHOD_CONTROLLER_CLASSES], useMap, filePath),
             routes,
-            this.extractRouteImports(routes, useMap, filePath),
+            routeImports,
         );
     }
 
     /**
-     * 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.
+     * Resolve every class the imperative route expressions reference to its absolute file path, so
+     * the generated data cache can import them.
      */
     protected extractRouteImports(
         routes: readonly ts.Expression[],
@@ -64,6 +66,38 @@ export class RouteProviderReader extends AstReader implements RouteProviderReade
         return imports;
     }
 
+    /** Stop on a name a route references that the generated data file, in another module, cannot reach. */
+    protected validateRouteImports(
+        routes: readonly ts.Expression[],
+        routeImports: Readonly<Record<string, string>>,
+        useMap: Record<string, string>,
+        fileNames: ReadonlySet<string>,
+    ): void {
+        for (const route of routes) {
+            const declaredNames = this.collectDeclaredNames(route);
+
+            for (const name of this.collectReferencedIdentifiers(route)) {
+                if (routeImports[name] !== undefined || declaredNames.has(name)) {
+                    continue;
+                }
+
+                if (fileNames.has(name)) {
+                    throw new AstUnreadableRouteException(
+                        `Cannot read the route '${route.getText()}': the generated data cannot import '${name}', which the provider declares for itself.`,
+                    );
+                }
+
+                // An import the reader resolves to no TypeScript file leaves the generated data no
+                // path to import the name from. Every name left is a global.
+                if (useMap[name] !== undefined) {
+                    throw new AstUnreadableRouteException(
+                        `Cannot read the route '${route.getText()}': the import of '${name}' resolves to no TypeScript file.`,
+                    );
+                }
+            }
+        }
+    }
+
     /**
      * Extract the route objects returned by a provider's `getRoutes()` method.
      *

package/src/Sindri/Ast/Throwable/Exception/AstUnreadableListenerException.ts

@@ -0,0 +1,11 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { AstInvalidArgumentException } from './Abstract/AstInvalidArgumentException.ts';
+
+export class AstUnreadableListenerException extends AstInvalidArgumentException {}

package/src/Sindri/Ast/Throwable/Exception/AstUnreadableRouteException.ts

@@ -0,0 +1,11 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { AstInvalidArgumentException } from './Abstract/AstInvalidArgumentException.ts';
+
+export class AstUnreadableRouteException extends AstInvalidArgumentException {}

package/src/Sindri/Constant/SindriInfo.ts

@@ -7,8 +7,8 @@
  */
 
 export class SindriInfo {
-    static readonly VERSION = '26.6.65' as const;
-    static readonly VERSION_BUILD_DATE_TIME = 'October 11 2026 10:55:09 MST' as const;
+    static readonly VERSION = '26.6.67' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'October 13 2026 12:46:02 MST' as const;
     static readonly ICON = `\
     ██████████
     ████  ████

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

@@ -264,7 +264,10 @@ export abstract class GenerateDataFromAst extends GenerateFromAst {
             .withAddedMessages(new Message('Generating Event Data..........................'))
             .writeMessages();
 
-        const allListeners: Record<string, ts.Expression> = {};
+        // A Map, because an object reorders a key that reads as an integer.
+        const allListeners = new Map<string, ts.Expression>();
+        const imperativeListeners: ts.Expression[] = [];
+        const importMap: Record<string, string> = {};
 
         for (const providerClass of listenerProviders) {
             const filePath = this.fqnToFilePath(providerClass, config.namespace, config.dir);
@@ -275,6 +278,13 @@ export abstract class GenerateDataFromAst extends GenerateFromAst {
 
             const providerResult = this.listenerProviderReader.readFile(filePath);
 
+            if (providerResult.listeners.length > 0) {
+                // The expressions are emitted verbatim, so every class they name is imported.
+                imperativeListeners.push(...providerResult.listeners);
+                importMap[path.basename(filePath, '.ts')] = this.importSpecifier(config.dataPath, filePath);
+                this.mergeReaderImports(importMap, providerResult.listenerImports, config);
+            }
+
             for (const listenerClass of providerResult.listenerClasses) {
                 const listenerPath = this.fqnToFilePath(listenerClass, config.namespace, config.dir);
 
@@ -284,15 +294,22 @@ export abstract class GenerateDataFromAst extends GenerateFromAst {
 
                 const attrResult = this.listenerAttributeReader.readFile(listenerPath);
 
-                Object.assign(allListeners, attrResult.listeners);
+                for (const [name, listener] of attrResult.listeners) {
+                    allListeners.set(name, listener);
+                }
+
+                this.mergeReaderImports(importMap, attrResult.importMap, config);
             }
         }
 
-        const status = this.eventGenerator.generateFile(
+        this.eventGenerator.classImportMap = importMap;
+
+        const status = this.eventGenerator.generateMergedFile(
             config.dataPath,
             'AppEventData',
             config.dataNamespace,
             allListeners,
+            imperativeListeners,
         );
 
         return this.addMessagesForGenerateStatus(output, status).withAddedMessages(new NewLine()).writeMessages();
@@ -428,16 +445,12 @@ export abstract class GenerateDataFromAst extends GenerateFromAst {
     }
 
     /**
-     * Merge the class-name → absolute-file-path imports a route attribute reader
-     * resolved (handler/help-text/middleware classes) into the generated data
-     * file's import map, converting each absolute path to the specifier the
-     * generated file imports it by — relative to the output directory for
-     * application source, or the owning package's own specifier for a class an
-     * installed package exposes.
+     * Merge the class-name → absolute-file-path imports a reader resolved into the generated data
+     * file's import map, by the specifier that file imports each one by.
      */
     protected mergeReaderImports(
         importMap: Record<string, string>,
-        readerImportMap: Record<string, string>,
+        readerImportMap: Readonly<Record<string, string>>,
         config: ConfigResult,
     ): void {
         for (const [name, absolutePath] of Object.entries(readerImportMap)) {