@valkyrjaio/sindri 26.5.0 → 26.6.0

package/package.json

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

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

@@ -612,6 +612,153 @@ export abstract class AstReader {
         return decorator.getArguments()[position];
     }
 
+    // -------------------------------------------------------------------------
+    // Object-literal decorator helpers — the shipped decorators accept a single
+    // options object (`@Route({ path, name, ... })`) rather than positional args.
+    // -------------------------------------------------------------------------
+
+    /**
+     * Return the decorator's first argument when it is an object literal, else undefined.
+     */
+    protected getDecoratorObjectArg(decorator: Decorator): ts.ObjectLiteralExpression | undefined {
+        const arg = this.getDecoratorArg(decorator, 0);
+
+        if (arg === undefined) {
+            return undefined;
+        }
+
+        const tsNode = arg.compilerNode;
+
+        return ts.isObjectLiteralExpression(tsNode) ? tsNode : undefined;
+    }
+
+    /**
+     * Return the value expression of the named property on an object literal, or
+     * undefined when the property is absent (or is not a plain property assignment).
+     */
+    protected getObjectProp(obj: ts.ObjectLiteralExpression, key: string): ts.Expression | undefined {
+        for (const prop of obj.properties) {
+            if (ts.isPropertyAssignment(prop) && this.propertyNameToString(prop.name) === key) {
+                return prop.initializer;
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Resolve a property name node (identifier or string literal) to its text.
+     */
+    protected propertyNameToString(name: ts.PropertyName): string | undefined {
+        if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+            return name.text;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Extract a string-valued object property, falling back to defaultValue.
+     */
+    protected getObjectStringProp(
+        obj: ts.ObjectLiteralExpression,
+        key: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+        defaultValue: string = '',
+    ): string {
+        const value = this.extractExprValue(this.getObjectProp(obj, key), useMap, currentFilePath, currentClass);
+
+        return typeof value === 'string' ? value : defaultValue;
+    }
+
+    /**
+     * Extract a boolean-valued object property, falling back to defaultValue.
+     */
+    protected getObjectBoolProp(
+        obj: ts.ObjectLiteralExpression,
+        key: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+        defaultValue: boolean = false,
+    ): boolean {
+        const value = this.extractExprValue(this.getObjectProp(obj, key), useMap, currentFilePath, currentClass);
+
+        return typeof value === 'boolean' ? value : defaultValue;
+    }
+
+    /**
+     * Extract a class-list object property (an array literal of class references),
+     * returning an empty array when the property is absent or not an array.
+     */
+    protected getObjectClassListProp(
+        obj: ts.ObjectLiteralExpression,
+        key: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): string[] {
+        const node = this.getObjectProp(obj, key);
+
+        if (node === undefined || !ts.isArrayLiteralExpression(node)) {
+            return [];
+        }
+
+        return this.extractClassListFromArrayExpr(node, useMap, currentFilePath, currentClass);
+    }
+
+    /**
+     * Extract a string-list object property (an array literal of string values),
+     * returning an empty array when the property is absent or not an array.
+     */
+    protected getObjectStringListProp(
+        obj: ts.ObjectLiteralExpression,
+        key: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): string[] {
+        const node = this.getObjectProp(obj, key);
+
+        if (node === undefined || !ts.isArrayLiteralExpression(node)) {
+            return [];
+        }
+
+        const values: string[] = [];
+
+        for (const element of node.elements) {
+            const value = this.extractExprValue(element, useMap, currentFilePath, currentClass);
+
+            if (typeof value === 'string') {
+                values.push(value);
+            }
+        }
+
+        return values;
+    }
+
+    /**
+     * Extract a handler-reference object property (`[Class, 'method']`), returning
+     * undefined when the property is absent or not a two-element handler array.
+     */
+    protected getObjectHandlerProp(
+        obj: ts.ObjectLiteralExpression,
+        key: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): HandlerData | undefined {
+        const node = this.getObjectProp(obj, key);
+
+        if (node === undefined || !ts.isArrayLiteralExpression(node)) {
+            return undefined;
+        }
+
+        return this.extractHandlerFromTsArray(node, useMap, currentFilePath, currentClass);
+    }
+
     /**
      * Convert a simple expression node to a scalar value or HandlerData.
      */
@@ -692,7 +839,12 @@ export abstract class AstReader {
             return undefined;
         }
 
-        const classValue = this.extractExprValue(array.elements[0], useMap, currentFilePath, currentClass);
+        const classValue = this.extractExprValue(
+            this.unwrapClassThunk(array.elements[0]),
+            useMap,
+            currentFilePath,
+            currentClass,
+        );
         const methodValue = this.extractExprValue(array.elements[1], useMap, currentFilePath, currentClass);
 
         if (typeof classValue !== 'string' || classValue === '') {
@@ -706,6 +858,35 @@ export abstract class AstReader {
         return new HandlerData(classValue, methodValue);
     }
 
+    /**
+     * Unwrap a class **thunk** to the class expression it returns —
+     * `() => HomeController` becomes `HomeController`.
+     *
+     * Every class reference in a decorator argument is authored as a thunk —
+     * `[() => SomeClass, 'method']` for a handler, `@Middleware(() => SomeClass)`
+     * for middleware — rather than as a bare class name. A TC39 Stage-3
+     * decorator runs while the class binding is still in its temporal dead zone,
+     * so naming the class directly throws at class-definition time on a circular
+     * or self-referential import. The thunk is purely a runtime deferral: the
+     * emitted cache is unchanged (`HttpRouteProvider.versionHandler`), so the
+     * reader simply looks through it. A bare class expression is returned
+     * untouched, and a block-bodied arrow (`() => { … }`) is left alone so it
+     * falls through to the usual "not a class reference" handling.
+     */
+    protected unwrapClassThunk(node: Node | ts.Node | undefined): Node | ts.Node | undefined {
+        if (node === undefined) {
+            return node;
+        }
+
+        const tsNode = Node.isNode(node) ? node.compilerNode : node;
+
+        if (!ts.isArrowFunction(tsNode) || tsNode.parameters.length !== 0) {
+            return node;
+        }
+
+        return ts.isBlock(tsNode.body) ? node : tsNode.body;
+    }
+
     protected extractClassListFromArrayExpr(
         array: ts.ArrayLiteralExpression,
         useMap: Record<string, string>,
@@ -715,7 +896,9 @@ export abstract class AstReader {
         const classes: string[] = [];
 
         for (const element of array.elements) {
-            const value = this.extractExprValue(element, useMap, currentFilePath, currentClass);
+            // A class list inside a decorator argument holds thunked references
+            // (`middleware: [() => AuthMiddleware]`), so look through the thunk.
+            const value = this.extractExprValue(this.unwrapClassThunk(element), useMap, currentFilePath, currentClass);
 
             if (typeof value === 'string' && value !== '') {
                 classes.push(value);

package/src/Sindri/Ast/CliRouteAttributeReader.ts

@@ -18,6 +18,7 @@ import type { Decorator, MethodDeclaration } from 'ts-morph';
 
 import type { CliRouteAttributeReaderContract } from './Contract/CliRouteAttributeReaderContract.ts';
 import type { CliRouteParameterReaderContract } from './Contract/CliRouteParameterReaderContract.ts';
+import type { HandlerData } from './Data/HandlerData.ts';
 
 /**
  * Scans a CLI controller class file for @Route and related sub-decorators and
@@ -40,6 +41,7 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
 
         const { classDecl, useMap, currentClass } = context;
         const routes: Record<string, ts.Expression> = {};
+        const routeData: Record<string, CliRouteData> = {};
 
         for (const method of classDecl.getMethods()) {
             for (const decorator of this.findDecoratorsOnNode(method, 'Route', useMap, filePath)) {
@@ -47,11 +49,14 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
 
                 if (data !== null) {
                     routes[data.name] = this.buildRouteExpr(data);
+                    routeData[data.name] = data;
                 }
             }
         }
 
-        return new CliRouteAttributeResult(routes);
+        const importMap = this.buildImportMap(routeData, useMap, filePath, currentClass);
+
+        return new CliRouteAttributeResult(routes, importMap);
     }
 
     protected getRouteHandlerDecoratorName(): string {
@@ -65,8 +70,14 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
         currentFilePath: string,
         currentClass: string,
     ): CliRouteData | null {
-        const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-        const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+        const obj = this.getDecoratorObjectArg(decorator);
+
+        if (obj === undefined) {
+            return null;
+        }
+
+        const name = this.getObjectStringProp(obj, 'name', useMap, currentFilePath, currentClass);
+        const description = this.getObjectStringProp(obj, 'description', useMap, currentFilePath, currentClass);
 
         if (name === '' || description === '') {
             return null;
@@ -79,17 +90,14 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
                 useMap,
                 currentFilePath,
                 currentClass,
-                this.extractClassListArgFromDecorator(decorator, 4, useMap, currentFilePath, currentClass),
-                this.extractClassListArgFromDecorator(decorator, 5, useMap, currentFilePath, currentClass),
-                this.extractClassListArgFromDecorator(decorator, 6, useMap, currentFilePath, currentClass),
-                this.extractClassListArgFromDecorator(decorator, 7, useMap, currentFilePath, currentClass),
+                this.getObjectClassListProp(obj, 'middleware', useMap, currentFilePath, currentClass),
             );
 
         return new CliRouteData(
             updatedName,
             description,
-            this.updateHandler(method, useMap, currentFilePath, currentClass),
-            null,
+            this.resolveHandler(obj, method, useMap, currentFilePath, currentClass),
+            this.getObjectHandlerProp(obj, 'helpText', useMap, currentFilePath, currentClass) ?? null,
             routeMatchedMiddleware,
             routeDispatchedMiddleware,
             throwableCaughtMiddleware,
@@ -99,6 +107,22 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
         );
     }
 
+    protected resolveHandler(
+        obj: ts.ObjectLiteralExpression,
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): HandlerData {
+        const fromObj = this.getObjectHandlerProp(obj, 'handler', useMap, currentFilePath, currentClass);
+
+        if (fromObj !== undefined) {
+            return fromObj;
+        }
+
+        return this.updateHandler(method, useMap, currentFilePath, currentClass);
+    }
+
     protected updateName(
         name: string,
         method: MethodDeclaration,
@@ -127,14 +151,30 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
         useMap: Record<string, string>,
         currentFilePath: string,
         currentClass: string,
-        routeMatchedMiddleware: string[],
-        routeDispatchedMiddleware: string[],
-        throwableCaughtMiddleware: string[],
-        processExitingMiddleware: string[],
+        middleware: string[],
     ): [string[], string[], string[], string[]] {
+        let routeMatchedMiddleware: string[] = [];
+        let routeDispatchedMiddleware: string[] = [];
+        let throwableCaughtMiddleware: string[] = [];
+        let processExitingMiddleware: string[] = [];
+
+        for (const mwName of middleware) {
+            [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware] =
+                this.classifyMiddleware(
+                    mwName,
+                    useMap,
+                    currentFilePath,
+                    routeMatchedMiddleware,
+                    routeDispatchedMiddleware,
+                    throwableCaughtMiddleware,
+                    processExitingMiddleware,
+                );
+        }
+
         for (const decorator of this.findDecoratorsOnNode(method, 'Middleware', useMap, currentFilePath)) {
+            // `@Middleware` takes a thunked class reference (`() => AuthMiddleware`).
             const mwName = this.extractExprValue(
-                this.getDecoratorArg(decorator, 0),
+                this.unwrapClassThunk(this.getDecoratorArg(decorator, 0)),
                 useMap,
                 currentFilePath,
                 currentClass,
@@ -216,4 +256,50 @@ export class CliRouteAttributeReader extends RouteAttributeReader implements Cli
             this.buildClassArrayExpr(data.processExitingMiddleware),
         ];
     }
+
+    /**
+     * Build the class-name → absolute-file-path map for every handler and
+     * help-text class the generated data cache references, so the generator can
+     * emit the matching import statements. (Middleware are emitted as string
+     * literals and therefore need no import.)
+     */
+    protected buildImportMap(
+        routeData: Record<string, CliRouteData>,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): Record<string, string> {
+        const importMap: Record<string, string> = {};
+
+        for (const data of Object.values(routeData)) {
+            if (data.handler !== null) {
+                this.addClassImport(importMap, data.handler.class, useMap, currentFilePath, currentClass);
+            }
+
+            if (data.helpText !== null) {
+                this.addClassImport(importMap, data.helpText.class, useMap, currentFilePath, currentClass);
+            }
+        }
+
+        return importMap;
+    }
+
+    protected addClassImport(
+        importMap: Record<string, string>,
+        className: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): void {
+        const shortName = className.slice(className.lastIndexOf('\\') + 1);
+
+        const filePath =
+            shortName === currentClass
+                ? currentFilePath
+                : this.resolveImportToFilePath(shortName, useMap, currentFilePath);
+
+        if (filePath !== '') {
+            importMap[shortName] = filePath;
+        }
+    }
 }

package/src/Sindri/Ast/CliRouteParameterReader.ts

@@ -28,7 +28,10 @@ export class CliRouteParameterReader extends AstReader implements CliRouteParame
     buildParameterArgs(data: CliRouteData): ts.Expression[] {
         const args: ts.Expression[] = [];
 
-        if (data.arguments.length > 0) {
+        // The `arguments_` constructor parameter precedes `options`, so an empty
+        // arguments array must still be emitted whenever options are present, to
+        // keep `options` in its correct positional slot.
+        if (data.arguments.length > 0 || data.options.length > 0) {
             args.push(this.buildArgumentListExpr(data.arguments));
         }
 
@@ -83,8 +86,14 @@ export class CliRouteParameterReader extends AstReader implements CliRouteParame
         currentFilePath: string,
         currentClass: string,
     ): CliArgumentParameterData | null {
-        const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-        const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+        const obj = this.getDecoratorObjectArg(decorator);
+
+        if (obj === undefined) {
+            return null;
+        }
+
+        const name = this.getObjectStringProp(obj, 'name', useMap, currentFilePath, currentClass);
+        const description = this.getObjectStringProp(obj, 'description', useMap, currentFilePath, currentClass);
 
         if (name === '' || description === '') {
             return null;
@@ -93,18 +102,18 @@ export class CliRouteParameterReader extends AstReader implements CliRouteParame
         return new CliArgumentParameterData(
             name,
             description,
-            this.extractStringArg(decorator, 2, useMap, currentFilePath, currentClass) || null,
-            this.extractStringArg(
-                decorator,
-                3,
+            this.getObjectStringProp(obj, 'cast', useMap, currentFilePath, currentClass) || null,
+            this.getObjectStringProp(
+                obj,
+                'mode',
                 useMap,
                 currentFilePath,
                 currentClass,
                 'Valkyrja\\Cli\\Routing\\Enum\\ArgumentMode::OPTIONAL',
             ),
-            this.extractStringArg(
-                decorator,
-                4,
+            this.getObjectStringProp(
+                obj,
+                'valueMode',
                 useMap,
                 currentFilePath,
                 currentClass,
@@ -119,8 +128,14 @@ export class CliRouteParameterReader extends AstReader implements CliRouteParame
         currentFilePath: string,
         currentClass: string,
     ): CliOptionParameterData | null {
-        const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-        const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+        const obj = this.getDecoratorObjectArg(decorator);
+
+        if (obj === undefined) {
+            return null;
+        }
+
+        const name = this.getObjectStringProp(obj, 'name', useMap, currentFilePath, currentClass);
+        const description = this.getObjectStringProp(obj, 'description', useMap, currentFilePath, currentClass);
 
         if (name === '' || description === '') {
             return null;
@@ -129,22 +144,22 @@ export class CliRouteParameterReader extends AstReader implements CliRouteParame
         return new CliOptionParameterData(
             name,
             description,
-            this.extractStringArg(decorator, 2, useMap, currentFilePath, currentClass),
-            this.extractStringArg(decorator, 3, useMap, currentFilePath, currentClass) || null,
-            this.extractStringArg(decorator, 4, useMap, currentFilePath, currentClass),
-            this.extractStringListArgFromDecorator(decorator, 5, useMap, currentFilePath, currentClass),
-            this.extractStringListArgFromDecorator(decorator, 6, useMap, currentFilePath, currentClass),
-            this.extractStringArg(
-                decorator,
-                7,
+            this.getObjectStringProp(obj, 'valueDisplayName', useMap, currentFilePath, currentClass),
+            this.getObjectStringProp(obj, 'cast', useMap, currentFilePath, currentClass) || null,
+            this.getObjectStringProp(obj, 'defaultValue', useMap, currentFilePath, currentClass),
+            this.getObjectStringListProp(obj, 'shortNames', useMap, currentFilePath, currentClass),
+            this.getObjectStringListProp(obj, 'validValues', useMap, currentFilePath, currentClass),
+            this.getObjectStringProp(
+                obj,
+                'mode',
                 useMap,
                 currentFilePath,
                 currentClass,
                 'Valkyrja\\Cli\\Routing\\Enum\\OptionMode::OPTIONAL',
             ),
-            this.extractStringArg(
-                decorator,
-                8,
+            this.getObjectStringProp(
+                obj,
+                'valueMode',
                 useMap,
                 currentFilePath,
                 currentClass,
@@ -196,6 +211,10 @@ export class CliRouteParameterReader extends AstReader implements CliRouteParame
             args.push(ts.factory.createArrayLiteralExpression([]));
         }
 
+        // The framework `OptionParameter` constructor carries a runtime-populated
+        // `options` array between `validValues` and `mode`; emit an empty array so
+        // `mode`/`valueMode` land in their correct positional slots.
+        args.push(ts.factory.createArrayLiteralExpression([]));
         args.push(this.buildEnumCaseExpr(data.mode));
         args.push(this.buildEnumCaseExpr(data.valueMode));
 

package/src/Sindri/Ast/Contract/HttpRouteMiddlewareReaderContract.ts

@@ -14,8 +14,8 @@ import type { MethodDeclaration } from 'ts-morph';
 import type { HttpRouteData } from '../Data/HttpRouteData.ts';
 
 export interface HttpRouteMiddlewareReaderContract {
-    extractInlineRequestMethods(
-        decoratorArgs: ts.NodeArray<ts.Expression> | ts.Expression[],
+    extractObjectRequestMethods(
+        obj: ts.ObjectLiteralExpression,
         useMap: Record<string, string>,
         namespace: string,
         currentClass: string,
@@ -34,11 +34,7 @@ export interface HttpRouteMiddlewareReaderContract {
         useMap: Record<string, string>,
         namespace: string,
         currentClass: string,
-        routeMatchedMiddleware: string[],
-        routeDispatchedMiddleware: string[],
-        throwableCaughtMiddleware: string[],
-        sendingResponseMiddleware: string[],
-        responseSentMiddleware: string[],
+        middleware: string[],
     ): [string[], string[], string[], string[], string[]];
 
     updateRequestStruct(

package/src/Sindri/Ast/Contract/HttpRouteParameterReaderContract.ts

@@ -9,14 +9,11 @@
 
 import type { ts } from 'ts-morph';
 
-import type { MethodDeclaration } from 'ts-morph';
-
 import type { HttpParameterData } from '../Data/HttpParameterData.ts';
 
 export interface HttpRouteParameterReaderContract {
     updateParameters(
-        decoratorArgs: ts.NodeArray<ts.Expression> | ts.Expression[],
-        method: MethodDeclaration,
+        obj: ts.ObjectLiteralExpression,
         useMap: Record<string, string>,
         namespace: string,
         currentClass: string,

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

@@ -14,4 +14,6 @@ export interface HttpParameterDataContract {
     readonly cast: string | null;
     readonly isOptional: boolean;
     readonly shouldCapture: boolean;
+    /** The default value for the parameter, or null when none was declared. */
+    readonly defaultValue: string | number | boolean | null;
 }

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

@@ -16,5 +16,6 @@ export class HttpParameterData implements HttpParameterDataContract {
         readonly cast: string | null = null,
         readonly isOptional: boolean = false,
         readonly shouldCapture: boolean = true,
+        readonly defaultValue: string | number | boolean | null = null,
     ) {}
 }

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

@@ -10,5 +10,9 @@
 import type { ts } from 'ts-morph';
 
 export class CliRouteAttributeResult {
-    constructor(readonly routes: Record<string, ts.Expression> = {}) {}
+    constructor(
+        readonly routes: Record<string, ts.Expression> = {},
+        /** Class short name → absolute file path for handler/help-text imports. */
+        readonly importMap: Record<string, string> = {},
+    ) {}
 }

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

@@ -15,5 +15,7 @@ export class HttpRouteAttributeResult {
     constructor(
         readonly routes: Record<string, ts.Expression> = {},
         readonly routeData: Record<string, HttpRouteData> = {},
+        /** Class short name → absolute file path for handler/middleware imports. */
+        readonly importMap: Record<string, string> = {},
     ) {}
 }