@valkyrjaio/sindri 26.0.1

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

@@ -0,0 +1,50 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { MethodDeclaration } from 'ts-morph';
+
+import { AstReader } from './AstReader.ts';
+import { HandlerData } from '../Data/HandlerData.ts';
+
+/**
+ * Base for route attribute readers — provides shared handler resolution logic.
+ *
+ * Concrete subclasses supply the decorator name of their specific route handler
+ * decorator via getRouteHandlerDecoratorName(), and this class implements the
+ * common updateHandler() that uses it.
+ */
+export abstract class RouteAttributeReader extends AstReader {
+    /**
+     * Resolve the handler from a @RouteHandler decorator or fall back to ClassName.methodName.
+     */
+    protected updateHandler(
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): HandlerData {
+        const decoratorName = this.getRouteHandlerDecoratorName();
+
+        for (const decorator of this.findDecoratorsOnNode(method, decoratorName, useMap, currentFilePath)) {
+            const arg = this.getDecoratorArg(decorator, 0);
+            const raw = this.extractExprValue(arg, useMap, currentFilePath, currentClass);
+
+            if (raw instanceof HandlerData) {
+                return raw;
+            }
+        }
+
+        return new HandlerData(currentClass, method.getName());
+    }
+
+    /**
+     * Return the name of the route handler decorator used by this reader.
+     */
+    protected abstract getRouteHandlerDecoratorName(): string;
+}

package/src/Sindri/Ast/CliRouteAttributeReader.ts

@@ -0,0 +1,219 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ts } from 'ts-morph';
+
+import { RouteAttributeReader } from './Abstract/RouteAttributeReader.ts';
+import { CliRouteData } from './Data/CliRouteData.ts';
+import { CliRouteAttributeResult } from './Data/Result/CliRouteAttributeResult.ts';
+import { CliRouteParameterReader } from './CliRouteParameterReader.ts';
+
+import type { Decorator, MethodDeclaration } from 'ts-morph';
+
+import type { CliRouteAttributeReaderContract } from './Contract/CliRouteAttributeReaderContract.ts';
+import type { CliRouteParameterReaderContract } from './Contract/CliRouteParameterReaderContract.ts';
+
+/**
+ * Scans a CLI controller class file for @Route and related sub-decorators and
+ * returns TypeScript compiler API Expr nodes ready for the data cache generator.
+ *
+ * Mirrors the logic of the framework's runtime attribute collector but operates
+ * entirely on AST without executing any TypeScript code.
+ */
+export class CliRouteAttributeReader extends RouteAttributeReader implements CliRouteAttributeReaderContract {
+    constructor(protected readonly parameterReader: CliRouteParameterReaderContract = new CliRouteParameterReader()) {
+        super();
+    }
+
+    readFile(filePath: string): CliRouteAttributeResult {
+        const context = this.parseClassFile(filePath);
+
+        if (context === undefined) {
+            return new CliRouteAttributeResult();
+        }
+
+        const { classDecl, useMap, currentClass } = context;
+        const routes: Record<string, ts.Expression> = {};
+
+        for (const method of classDecl.getMethods()) {
+            for (const decorator of this.findDecoratorsOnNode(method, 'Route', useMap, filePath)) {
+                const data = this.buildRouteData(decorator, method, useMap, filePath, currentClass);
+
+                if (data !== null) {
+                    routes[data.name] = this.buildRouteExpr(data);
+                }
+            }
+        }
+
+        return new CliRouteAttributeResult(routes);
+    }
+
+    protected getRouteHandlerDecoratorName(): string {
+        return 'RouteHandler';
+    }
+
+    protected buildRouteData(
+        decorator: Decorator,
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): CliRouteData | null {
+        const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
+        const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+
+        if (name === '' || description === '') {
+            return null;
+        }
+
+        const updatedName = this.updateName(name, method, useMap, currentFilePath, currentClass);
+        const [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware] =
+            this.updateMiddleware(
+                method,
+                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),
+            );
+
+        return new CliRouteData(
+            updatedName,
+            description,
+            this.updateHandler(method, useMap, currentFilePath, currentClass),
+            null,
+            routeMatchedMiddleware,
+            routeDispatchedMiddleware,
+            throwableCaughtMiddleware,
+            exitedMiddleware,
+            this.parameterReader.updateArguments(method, useMap, currentFilePath, currentClass),
+            this.parameterReader.updateOptions(method, useMap, currentFilePath, currentClass),
+        );
+    }
+
+    protected updateName(
+        name: string,
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): string {
+        for (const decorator of this.findDecoratorsOnNode(method, 'Name', useMap, currentFilePath)) {
+            const override = this.extractExprValue(
+                this.getDecoratorArg(decorator, 0),
+                useMap,
+                currentFilePath,
+                currentClass,
+            );
+
+            if (typeof override === 'string' && override !== '') {
+                name = override;
+            }
+        }
+
+        return name;
+    }
+
+    protected updateMiddleware(
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+        routeMatchedMiddleware: string[],
+        routeDispatchedMiddleware: string[],
+        throwableCaughtMiddleware: string[],
+        exitedMiddleware: string[],
+    ): [string[], string[], string[], string[]] {
+        for (const decorator of this.findDecoratorsOnNode(method, 'Middleware', useMap, currentFilePath)) {
+            const mwName = this.extractExprValue(
+                this.getDecoratorArg(decorator, 0),
+                useMap,
+                currentFilePath,
+                currentClass,
+            );
+
+            if (typeof mwName !== 'string' || mwName === '') {
+                continue;
+            }
+
+            [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware] =
+                this.classifyMiddleware(
+                    mwName,
+                    useMap,
+                    currentFilePath,
+                    routeMatchedMiddleware,
+                    routeDispatchedMiddleware,
+                    throwableCaughtMiddleware,
+                    exitedMiddleware,
+                );
+        }
+
+        return [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware];
+    }
+
+    protected classifyMiddleware(
+        mwName: string,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        routeMatchedMiddleware: string[],
+        routeDispatchedMiddleware: string[],
+        throwableCaughtMiddleware: string[],
+        exitedMiddleware: string[],
+    ): [string[], string[], string[], string[]] {
+        if (this.classImplementsInterface(mwName, 'RouteMatchedMiddlewareContract', useMap, currentFilePath)) {
+            routeMatchedMiddleware = [...routeMatchedMiddleware, mwName];
+        }
+
+        if (this.classImplementsInterface(mwName, 'RouteDispatchedMiddlewareContract', useMap, currentFilePath)) {
+            routeDispatchedMiddleware = [...routeDispatchedMiddleware, mwName];
+        }
+
+        if (this.classImplementsInterface(mwName, 'ThrowableCaughtMiddlewareContract', useMap, currentFilePath)) {
+            throwableCaughtMiddleware = [...throwableCaughtMiddleware, mwName];
+        }
+
+        if (this.classImplementsInterface(mwName, 'ExitedMiddlewareContract', useMap, currentFilePath)) {
+            exitedMiddleware = [...exitedMiddleware, mwName];
+        }
+
+        return [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, exitedMiddleware];
+    }
+
+    protected buildRouteExpr(data: CliRouteData): ts.Expression {
+        const args: ts.Expression[] = [this.buildEnumCaseExpr(data.name), this.buildStringExpr(data.description)];
+
+        if (data.handler !== null) {
+            args.push(this.buildHandlerExpr(data.handler));
+        } else {
+            args.push(this.buildNullExpr());
+        }
+
+        if (data.helpText !== null) {
+            args.push(this.buildHandlerExpr(data.helpText));
+        } else {
+            args.push(this.buildNullExpr());
+        }
+
+        args.push(...this.buildRouteMiddlewareArgs(data));
+        args.push(...this.parameterReader.buildParameterArgs(data));
+
+        return this.buildNewExpr('Valkyrja\\Cli\\Routing\\Data\\Route', args);
+    }
+
+    protected buildRouteMiddlewareArgs(data: CliRouteData): ts.Expression[] {
+        return [
+            this.buildClassArrayExpr(data.routeMatchedMiddleware),
+            this.buildClassArrayExpr(data.routeDispatchedMiddleware),
+            this.buildClassArrayExpr(data.throwableCaughtMiddleware),
+            this.buildClassArrayExpr(data.exitedMiddleware),
+        ];
+    }
+}

package/src/Sindri/Ast/CliRouteParameterReader.ts

@@ -0,0 +1,204 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ts } from 'ts-morph';
+
+import { AstReader } from './Abstract/AstReader.ts';
+import { CliArgumentParameterData } from './Data/CliArgumentParameterData.ts';
+import { CliOptionParameterData } from './Data/CliOptionParameterData.ts';
+
+import type { MethodDeclaration } from 'ts-morph';
+
+import type { CliRouteData } from './Data/CliRouteData.ts';
+import type { CliRouteParameterReaderContract } from './Contract/CliRouteParameterReaderContract.ts';
+
+/**
+ * Builds AST expressions for CLI route argument and option parameters.
+ *
+ * Extracted from CliRouteAttributeReader to keep each class under the
+ * complexity threshold; injected as a constructor argument.
+ */
+export class CliRouteParameterReader extends AstReader implements CliRouteParameterReaderContract {
+    buildParameterArgs(data: CliRouteData): ts.Expression[] {
+        const args: ts.Expression[] = [];
+
+        if (data.arguments.length > 0) {
+            args.push(this.buildArgumentListExpr(data.arguments));
+        }
+
+        if (data.options.length > 0) {
+            args.push(this.buildOptionListExpr(data.options));
+        }
+
+        return args;
+    }
+
+    updateArguments(
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        namespace: string,
+        currentClass: string,
+    ): CliArgumentParameterData[] {
+        const arguments_: CliArgumentParameterData[] = [];
+
+        for (const decorator of this.findDecoratorsOnNode(method, 'ArgumentParameter', useMap, namespace)) {
+            const data = this.buildArgumentData(decorator, useMap, namespace, currentClass);
+
+            if (data !== null) {
+                arguments_.push(data);
+            }
+        }
+
+        return arguments_;
+    }
+
+    updateOptions(
+        method: MethodDeclaration,
+        useMap: Record<string, string>,
+        namespace: string,
+        currentClass: string,
+    ): CliOptionParameterData[] {
+        const options: CliOptionParameterData[] = [];
+
+        for (const decorator of this.findDecoratorsOnNode(method, 'OptionParameter', useMap, namespace)) {
+            const data = this.buildOptionData(decorator, useMap, namespace, currentClass);
+
+            if (data !== null) {
+                options.push(data);
+            }
+        }
+
+        return options;
+    }
+
+    protected buildArgumentData(
+        decorator: import('ts-morph').Decorator,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): CliArgumentParameterData | null {
+        const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
+        const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+
+        if (name === '' || description === '') {
+            return null;
+        }
+
+        return new CliArgumentParameterData(
+            name,
+            description,
+            this.extractStringArg(decorator, 2, useMap, currentFilePath, currentClass) || null,
+            this.extractStringArg(
+                decorator,
+                3,
+                useMap,
+                currentFilePath,
+                currentClass,
+                'Valkyrja\\Cli\\Routing\\Enum\\ArgumentMode::OPTIONAL',
+            ),
+            this.extractStringArg(
+                decorator,
+                4,
+                useMap,
+                currentFilePath,
+                currentClass,
+                'Valkyrja\\Cli\\Routing\\Enum\\ArgumentValueMode::DEFAULT',
+            ),
+        );
+    }
+
+    protected buildOptionData(
+        decorator: import('ts-morph').Decorator,
+        useMap: Record<string, string>,
+        currentFilePath: string,
+        currentClass: string,
+    ): CliOptionParameterData | null {
+        const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
+        const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+
+        if (name === '' || description === '') {
+            return null;
+        }
+
+        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,
+                useMap,
+                currentFilePath,
+                currentClass,
+                'Valkyrja\\Cli\\Routing\\Enum\\OptionMode::OPTIONAL',
+            ),
+            this.extractStringArg(
+                decorator,
+                8,
+                useMap,
+                currentFilePath,
+                currentClass,
+                'Valkyrja\\Cli\\Routing\\Enum\\OptionValueMode::DEFAULT',
+            ),
+        );
+    }
+
+    protected buildArgumentListExpr(arguments_: readonly CliArgumentParameterData[]): ts.ArrayLiteralExpression {
+        const elements = arguments_.map((a) => this.buildArgumentExpr(a));
+        return ts.factory.createArrayLiteralExpression(elements);
+    }
+
+    protected buildArgumentExpr(data: CliArgumentParameterData): ts.Expression {
+        const args: ts.Expression[] = [
+            this.buildStringExpr(data.name),
+            this.buildStringExpr(data.description),
+            data.cast !== null ? this.buildEnumCaseExpr(data.cast) : this.buildNullExpr(),
+            this.buildEnumCaseExpr(data.mode),
+            this.buildEnumCaseExpr(data.valueMode),
+        ];
+
+        return this.buildNewExpr('Valkyrja\\Cli\\Routing\\Data\\ArgumentParameter', args);
+    }
+
+    protected buildOptionListExpr(options: readonly CliOptionParameterData[]): ts.ArrayLiteralExpression {
+        const elements = options.map((o) => this.buildOptionExpr(o));
+        return ts.factory.createArrayLiteralExpression(elements);
+    }
+
+    protected buildOptionExpr(data: CliOptionParameterData): ts.Expression {
+        const args: ts.Expression[] = [
+            this.buildStringExpr(data.name),
+            this.buildStringExpr(data.description),
+            this.buildStringExpr(data.valueDisplayName),
+            data.cast !== null ? this.buildEnumCaseExpr(data.cast) : this.buildNullExpr(),
+            this.buildStringExpr(data.defaultValue),
+        ];
+
+        if (data.shortNames.length > 0) {
+            args.push(this.buildStringArrayExpr(data.shortNames));
+        } else {
+            args.push(ts.factory.createArrayLiteralExpression([]));
+        }
+
+        if (data.validValues.length > 0) {
+            args.push(this.buildStringArrayExpr(data.validValues));
+        } else {
+            args.push(ts.factory.createArrayLiteralExpression([]));
+        }
+
+        args.push(this.buildEnumCaseExpr(data.mode));
+        args.push(this.buildEnumCaseExpr(data.valueMode));
+
+        return this.buildNewExpr('Valkyrja\\Cli\\Routing\\Data\\OptionParameter', args);
+    }
+}

package/src/Sindri/Ast/ComponentProviderReader.ts

@@ -0,0 +1,41 @@
+/*
+ * This file is part of the Sindri package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { AstReader } from './Abstract/AstReader.ts';
+import { ComponentProviderResult } from './Data/Result/ComponentProviderResult.ts';
+
+import type { ComponentProviderReaderContract } from './Contract/ComponentProviderReaderContract.ts';
+
+export class ComponentProviderReader extends AstReader implements ComponentProviderReaderContract {
+    protected static readonly METHOD_COMPONENT = 'getComponentProviders';
+    protected static readonly METHOD_CONTAINER = 'getContainerProviders';
+    protected static readonly METHOD_EVENT = 'getEventProviders';
+    protected static readonly METHOD_CLI = 'getCliProviders';
+    protected static readonly METHOD_HTTP = 'getHttpProviders';
+
+    readFile(filePath: string): ComponentProviderResult {
+        const sourceFile = this.parseFileToSourceFile(filePath);
+        const classDecl = this.findClass(sourceFile);
+
+        if (classDecl === undefined) {
+            return new ComponentProviderResult();
+        }
+
+        const useMap = this.buildUseMap(sourceFile);
+        const methods = this.indexMethods(classDecl);
+
+        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),
+        );
+    }
+}