inviton-backduck 1.0.0

package/dist/apidoc/controller-parser.js

@@ -0,0 +1,686 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { ApiDocConfig } from './config';
+/**
+ * Parser for TypeScript controller files using ts-morph
+ */
+export class ControllerParser {
+    project;
+    serverDir;
+    routerCache = new Map();
+    controllerPathCache = new Map();
+    typeResolver = null;
+    constructor(serverDir) {
+        this.serverDir = path.resolve(serverDir);
+        this.project = new Project({
+            tsConfigFilePath: path.join(this.serverDir, 'tsconfig.json'),
+            skipAddingFilesFromTsConfig: true,
+        });
+    }
+    /**
+     * Add a source file to the project by file path
+     * @param filePath The path to the TS source file
+     * @returns The added SourceFile object
+     */
+    addSourceFileAtPath(filePath) {
+        return this.project.addSourceFileAtPath(filePath);
+    }
+    /**
+     * Set the TypeResolver instance for extracting service method JSDoc
+     */
+    setTypeResolver(typeResolver) {
+        this.typeResolver = typeResolver;
+    }
+    /**
+     * Parse endpoint info by controller class name
+     */
+    parseEndpoint(controllerClassName, apiType = 'shopApi') {
+        // Build controller path cache if not already built
+        if (this.controllerPathCache.size === 0) {
+            this.buildControllerPathCache(apiType);
+        }
+        const cached = this.controllerPathCache.get(controllerClassName);
+        if (!cached) {
+            return null;
+        }
+        // Parse the controller to get route path
+        const controllerInfo = this.parseController(cached.filePath);
+        if (!controllerInfo) {
+            return null;
+        }
+        return {
+            className: controllerClassName,
+            routePath: controllerInfo.routePath,
+            fullPath: cached.fullPath,
+            filePath: cached.filePath,
+            tag: cached.tag,
+        };
+    }
+    /**
+     * Build cache of controller -> full path mappings by traversing router hierarchy
+     */
+    buildControllerPathCache(apiType) {
+        const sourceDir = ApiDocConfig.getSourcePath(this.serverDir, apiType);
+        const basePath = apiType === 'shopApi' ? ApiDocConfig.basePaths.shop : ApiDocConfig.basePaths.admin;
+        const mainRouterPath = path.join(sourceDir, '_router.ts');
+        if (!fs.existsSync(mainRouterPath)) {
+            return;
+        }
+        this.traverseRouterHierarchy(mainRouterPath, basePath, '');
+    }
+    /**
+     * Recursively traverse router hierarchy and build controller path mappings
+     */
+    traverseRouterHierarchy(routerFilePath, pathPrefix, tag) {
+        const routerInfo = this.parseRouterFile(routerFilePath);
+        if (!routerInfo) {
+            return;
+        }
+        // Process registered controllers
+        for (const controller of routerInfo.controllers) {
+            const controllerFilePath = this.resolveImportPath(routerFilePath, controller.importPath);
+            if (!controllerFilePath || !fs.existsSync(controllerFilePath)) {
+                continue;
+            }
+            // Parse controller to get @Route path
+            const controllerInfo = this.parseController(controllerFilePath);
+            if (controllerInfo) {
+                const fullPath = this.normalizePath(pathPrefix + controllerInfo.routePath);
+                this.controllerPathCache.set(controller.controllerClassName, {
+                    fullPath,
+                    filePath: controllerFilePath,
+                    tag: tag || controllerInfo.tag,
+                });
+            }
+        }
+        // Process sub-routers
+        for (const subRouter of routerInfo.subRouters) {
+            const subRouterFilePath = this.resolveImportPath(routerFilePath, subRouter.importPath);
+            if (!subRouterFilePath || !fs.existsSync(subRouterFilePath)) {
+                continue;
+            }
+            const newPathPrefix = pathPrefix + subRouter.path;
+            const newTag = tag || subRouter.path.replace(/^\//, '');
+            this.traverseRouterHierarchy(subRouterFilePath, newPathPrefix, newTag);
+        }
+    }
+    /**
+     * Parse a _router.ts file to extract router.use() and router.registerController() calls
+     */
+    parseRouterFile(filePath) {
+        const cached = this.routerCache.get(filePath);
+        if (cached) {
+            return cached;
+        }
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const sourceFile = this.project.addSourceFileAtPath(filePath);
+        const imports = this.parseImports(sourceFile);
+        const subRouters = [];
+        const controllers = [];
+        // Find all call expressions
+        const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+        for (const callExpr of callExpressions) {
+            const expression = callExpr.getExpression();
+            if (!Node.isPropertyAccessExpression(expression)) {
+                continue;
+            }
+            const methodName = expression.getName();
+            const args = callExpr.getArguments();
+            if (methodName === 'use' && args.length >= 2) {
+                // router.use('/path', subRouter)
+                const pathArg = args[0];
+                const routerArg = args[1];
+                if (Node.isStringLiteral(pathArg)) {
+                    const routePath = pathArg.getLiteralValue();
+                    const routerVarName = routerArg.getText();
+                    const importPath = imports.get(routerVarName);
+                    if (importPath) {
+                        subRouters.push({
+                            path: routePath,
+                            routerVariableName: routerVarName,
+                            importPath,
+                        });
+                    }
+                }
+            }
+            else if (methodName === 'registerController' && args.length >= 1) {
+                // router.registerController(SomeController)
+                const controllerArg = args[0];
+                const controllerName = controllerArg.getText();
+                const importPath = imports.get(controllerName);
+                if (importPath) {
+                    controllers.push({
+                        controllerClassName: controllerName,
+                        importPath,
+                    });
+                }
+            }
+        }
+        const relativePath = path.relative(this.serverDir, filePath).replace(/\\/g, '/');
+        const directory = path.dirname(filePath);
+        const routerInfo = {
+            filePath,
+            relativePath,
+            directory,
+            subRouters,
+            controllers,
+        };
+        this.routerCache.set(filePath, routerInfo);
+        return routerInfo;
+    }
+    /**
+     * Parse import statements from a source file
+     */
+    parseImports(sourceFile) {
+        const imports = new Map();
+        const importDeclarations = sourceFile.getImportDeclarations();
+        for (const importDecl of importDeclarations) {
+            const moduleSpecifier = importDecl.getModuleSpecifierValue();
+            const defaultImport = importDecl.getDefaultImport();
+            if (defaultImport) {
+                imports.set(defaultImport.getText(), moduleSpecifier);
+            }
+            const namedImports = importDecl.getNamedImports();
+            for (const namedImport of namedImports) {
+                const name = namedImport.getAliasNode()?.getText() || namedImport.getName();
+                imports.set(name, moduleSpecifier);
+            }
+        }
+        return imports;
+    }
+    /**
+     * Resolve a relative import path to an absolute file path
+     */
+    resolveImportPath(fromFile, importPath) {
+        if (!importPath.startsWith('.')) {
+            return null;
+        }
+        const fromDir = path.dirname(fromFile);
+        const resolvedPath = path.resolve(fromDir, importPath);
+        // Try with .ts extension
+        if (fs.existsSync(`${resolvedPath}.ts`)) {
+            return `${resolvedPath}.ts`;
+        }
+        // Try as directory with index.ts
+        if (fs.existsSync(path.join(resolvedPath, 'index.ts'))) {
+            return path.join(resolvedPath, 'index.ts');
+        }
+        // Try as directory with _router.ts (for sub-router imports)
+        if (fs.existsSync(path.join(resolvedPath, '_router.ts'))) {
+            return path.join(resolvedPath, '_router.ts');
+        }
+        // Maybe it's already a complete path
+        if (fs.existsSync(resolvedPath)) {
+            return resolvedPath;
+        }
+        return null;
+    }
+    /**
+     * Normalize path by removing duplicate slashes and ensuring single leading slash
+     */
+    normalizePath(p) {
+        return (`/${p}`).replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+    }
+    /**
+     * Discover all controller files in the shop API directory
+     */
+    discoverControllers(apiType = 'shopApi') {
+        const sourceDir = ApiDocConfig.getSourcePath(this.serverDir, apiType);
+        const pattern = ApiDocConfig.patterns.controllerFiles;
+        return this.findFilesRecursive(sourceDir, pattern);
+    }
+    /**
+     * Parse a single controller file
+     */
+    parseController(filePath) {
+        // Try to get already-loaded source file first, otherwise add it
+        let sourceFile = this.project.getSourceFile(filePath);
+        if (!sourceFile) {
+            sourceFile = this.project.addSourceFileAtPath(filePath);
+        }
+        const classes = sourceFile.getClasses();
+        const controllerClass = classes.find(cls => cls.getExtends()?.getText()?.includes('ControllerBase')
+            || cls.getName()?.includes('Controller'));
+        if (!controllerClass) {
+            return null;
+        }
+        const className = controllerClass.getName() || 'UnknownController';
+        const routePath = this.extractRouteDecorator(controllerClass);
+        const methods = this.extractMethods(controllerClass);
+        const relativePath = path.relative(this.serverDir, filePath).replace(/\\/g, '/');
+        const tag = this.extractTagFromPath(relativePath);
+        return {
+            className,
+            routePath: routePath || this.inferRouteFromClassName(className),
+            filePath,
+            relativePath,
+            methods,
+            tag,
+        };
+    }
+    /**
+     * Parse all controllers in the shop API
+     */
+    parseAllControllers(apiType = 'shopApi') {
+        /* eslint-disable no-console */
+        console.time('🔍 Discovering controller files');
+        const files = this.discoverControllers(apiType);
+        console.timeEnd('🔍 Discovering controller files');
+        console.log(`📁 Found ${files.length} controller files`);
+        console.time('📦 Adding all source files to ts-morph project');
+        // Pre-load all source files into the project for faster parsing
+        for (const file of files) {
+            this.project.addSourceFileAtPath(file);
+        }
+        console.timeEnd('📦 Adding all source files to ts-morph project');
+        console.time('🔨 Parsing all controllers');
+        const controllers = [];
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const fileName = path.basename(file);
+            const startTime = performance.now();
+            const info = this.parseController(file);
+            const duration = performance.now() - startTime;
+            if (duration > 100) {
+                console.log(`  ⏱️  ${fileName} took ${duration.toFixed(0)}ms`);
+            }
+            if (info && info.methods.length > 0) {
+                controllers.push(info);
+            }
+        }
+        console.timeEnd('🔨 Parsing all controllers');
+        console.log(`✅ Parsed ${controllers.length} controllers with endpoints`);
+        /* eslint-enable no-console */
+        return controllers;
+    }
+    /**
+     * Extract the route path from @Route decorator
+     */
+    extractRouteDecorator(classDecl) {
+        const decorators = classDecl.getDecorators();
+        for (const decorator of decorators) {
+            const name = decorator.getName();
+            if (name === ApiDocConfig.decorators.route) {
+                return this.extractDecoratorStringArg(decorator);
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract methods from a controller class
+     */
+    extractMethods(classDecl) {
+        const methods = [];
+        const classMethods = classDecl.getMethods();
+        const sourceFile = classDecl.getSourceFile();
+        for (const method of classMethods) {
+            const methodName = method.getName();
+            const httpMethod = ApiDocConfig.getHttpMethod(methodName);
+            if (!httpMethod) {
+                continue;
+            }
+            const auth = this.extractAuthDecorator(method);
+            const { requestType, responseType } = this.extractMethodTypes(method);
+            const description = this.extractJsDocDescription(method);
+            const paramDescription = this.extractJsDocParams(method);
+            // Extract service description and extra parameters from service interface if available
+            let serviceDescription = null;
+            let extraParameterGenerator = null;
+            if (this.typeResolver) {
+                const serviceMapping = this.extractServiceMethodMapping(method, sourceFile);
+                if (serviceMapping) {
+                    serviceDescription = this.typeResolver.extractServiceMethodJsDoc(serviceMapping.interfaceType, serviceMapping.methodName);
+                    extraParameterGenerator = this.typeResolver.extractServiceMethodExtraParameters(serviceMapping.interfaceType, serviceMapping.methodName);
+                }
+            }
+            methods.push({
+                name: methodName,
+                httpMethod,
+                auth,
+                requestType,
+                responseType,
+                description,
+                serviceDescription,
+                paramDescription,
+                extraParameterGenerator,
+            });
+        }
+        return methods;
+    }
+    /**
+     * Extract authentication decorator information
+     */
+    extractAuthDecorator(method) {
+        const decorators = method.getDecorators();
+        const result = {
+            hasAuth: false,
+            requiresLogin: false,
+            requiresVerifiedAccount: false,
+            isEnterpriseOnly: false,
+        };
+        for (const decorator of decorators) {
+            const name = decorator.getName();
+            // Check for enterprise auth decorator
+            if (name === ApiDocConfig.decorators.shopEnterpriseAuth
+                || name === 'ShopApiEnterpriseAuthRequired'
+                || name === 'ShopApiEnterpriseAuthRequiresVerifiedAccount') {
+                result.hasAuth = true;
+                result.isEnterpriseOnly = true;
+                result.requiresLogin = true; // Enterprise auth always requires login (via API key)
+                if (name === 'ShopApiEnterpriseAuthRequiresVerifiedAccount') {
+                    result.requiresVerifiedAccount = true;
+                }
+                else {
+                    const args = this.extractDecoratorObjectArg(decorator);
+                    if (args) {
+                        result.requiresVerifiedAccount = args.requiresVerifiedAccount === true;
+                    }
+                }
+                break;
+            }
+            // Check for regular shop auth decorator
+            if (name === ApiDocConfig.decorators.shopAuth || name === 'ShopApiAuthRequiresLogin' || name === 'ShopApiAuthRequiresVerifiedAccount') {
+                result.hasAuth = true;
+                if (name === 'ShopApiAuthRequiresLogin') {
+                    result.requiresLogin = true;
+                }
+                else if (name === 'ShopApiAuthRequiresVerifiedAccount') {
+                    result.requiresLogin = true;
+                    result.requiresVerifiedAccount = true;
+                }
+                else {
+                    const args = this.extractDecoratorObjectArg(decorator);
+                    if (args) {
+                        result.requiresLogin = args.requiresLogin === true;
+                        result.requiresVerifiedAccount = args.requiresVerifiedAccount === true;
+                    }
+                }
+                break;
+            }
+        }
+        return result;
+    }
+    /**
+     * Extract request and response types from method signature
+     */
+    extractMethodTypes(method) {
+        let requestType = null;
+        let responseType = null;
+        // Get request type from first parameter
+        const params = method.getParameters();
+        if (params.length > 0) {
+            const firstParam = params[0];
+            const paramType = firstParam.getType();
+            requestType = this.cleanTypeName(paramType.getText());
+        }
+        // Get response type from return type
+        const returnType = method.getReturnType();
+        const returnTypeText = returnType.getText();
+        // Handle Promise<T>
+        const promiseMatch = returnTypeText.match(/Promise<(.+)>/);
+        if (promiseMatch) {
+            responseType = this.cleanTypeName(promiseMatch[1]);
+        }
+        else {
+            responseType = this.cleanTypeName(returnTypeText);
+        }
+        return { requestType, responseType };
+    }
+    /**
+     * Extract JSDoc description from a method
+     */
+    extractJsDocDescription(method) {
+        const jsDocs = method.getJsDocs();
+        if (jsDocs.length > 0) {
+            // Preserve newlines and indentation for complex descriptions with code blocks
+            const description = jsDocs[0].getDescription();
+            if (description) {
+                return description.trim() || null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract @param description from a method's JSDoc
+     * Returns the description of the first parameter (typically 'args')
+     */
+    extractJsDocParams(method) {
+        const jsDocs = method.getJsDocs();
+        if (jsDocs.length === 0) {
+            return null;
+        }
+        const tags = jsDocs[0].getTags();
+        const paramTags = tags.filter(tag => tag.getTagName() === 'param');
+        if (paramTags.length === 0) {
+            return null;
+        }
+        // Get the first @param tag (typically for the 'args' parameter)
+        const firstParamTag = paramTags[0];
+        // Extract the comment text from the param tag
+        // The tag format is: @param {type} paramName - description
+        // or: @param paramName - description
+        // or: @param paramName description
+        const tagText = firstParamTag.getText();
+        // Remove the @param prefix and extract description
+        // Pattern: @param {type}? paramName [-:]? description
+        const paramMatch = tagText.match(/@param\s+(?:\{[^}]+\}\s+)?(\w+)\s*[-:]?\s*(.*)/);
+        if (paramMatch && paramMatch[2]) {
+            const description = paramMatch[2].trim();
+            return description || null;
+        }
+        // Alternative: try to get the comment using getComment() if available
+        if ('getComment' in firstParamTag && typeof firstParamTag.getComment === 'function') {
+            const comment = firstParamTag.getComment();
+            if (typeof comment === 'string') {
+                return comment.trim() || null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract service method mapping from a controller method
+     * Parses the method body to find container.get<InterfaceType>() and service.methodName() calls
+     */
+    extractServiceMethodMapping(method, sourceFile) {
+        const imports = this.parseImports(sourceFile);
+        // Find variable declarations with container.get<InterfaceType>()
+        const variableDeclarations = method.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+        let serviceVariableName = null;
+        let interfaceType = null;
+        for (const varDecl of variableDeclarations) {
+            const initializer = varDecl.getInitializer();
+            if (!initializer || !Node.isCallExpression(initializer)) {
+                continue;
+            }
+            // Check if it's container.get() call
+            const callExpr = initializer;
+            const expression = callExpr.getExpression();
+            if (!Node.isPropertyAccessExpression(expression)) {
+                continue;
+            }
+            const objectName = expression.getExpression().getText();
+            const methodName = expression.getName();
+            if (objectName === 'container' && methodName === 'get') {
+                // Extract type argument (e.g., ICartService from container.get<ICartService>())
+                const typeArgs = callExpr.getTypeArguments();
+                if (typeArgs.length > 0) {
+                    interfaceType = typeArgs[0].getText();
+                    serviceVariableName = varDecl.getName();
+                    break;
+                }
+            }
+        }
+        if (!serviceVariableName || !interfaceType) {
+            return null;
+        }
+        // Find the import path for the interface type
+        const interfaceImportPath = imports.get(interfaceType);
+        if (!interfaceImportPath) {
+            return null;
+        }
+        // Find method call on the service variable (e.g., service.validateCart())
+        const callExpressions = method.getDescendantsOfKind(SyntaxKind.CallExpression);
+        for (const callExpr of callExpressions) {
+            const expression = callExpr.getExpression();
+            if (!Node.isPropertyAccessExpression(expression)) {
+                continue;
+            }
+            const objectExpr = expression.getExpression();
+            // Check if we're calling a method on our service variable
+            // Handle both `service.method()` and `await service.method()`
+            if (Node.isIdentifier(objectExpr) && objectExpr.getText() === serviceVariableName) {
+                const serviceMethodName = expression.getName();
+                return {
+                    interfaceType,
+                    interfaceImportPath,
+                    methodName: serviceMethodName,
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract string argument from decorator
+     */
+    extractDecoratorStringArg(decorator) {
+        const args = decorator.getArguments();
+        if (args.length > 0) {
+            const arg = args[0];
+            if (Node.isStringLiteral(arg)) {
+                return arg.getLiteralValue();
+            }
+            // Handle template literals or other string expressions
+            const text = arg.getText();
+            if (text.startsWith('\'') || text.startsWith('"') || text.startsWith('`')) {
+                return text.slice(1, -1);
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract object argument from decorator
+     */
+    extractDecoratorObjectArg(decorator) {
+        const args = decorator.getArguments();
+        if (args.length > 0) {
+            const arg = args[0];
+            if (Node.isObjectLiteralExpression(arg)) {
+                const result = {};
+                for (const prop of arg.getProperties()) {
+                    if (Node.isPropertyAssignment(prop)) {
+                        const name = prop.getName();
+                        const init = prop.getInitializer();
+                        if (init) {
+                            if (Node.isTrueLiteral(init)) {
+                                result[name] = true;
+                            }
+                            else if (Node.isFalseLiteral(init)) {
+                                result[name] = false;
+                            }
+                            else if (Node.isStringLiteral(init)) {
+                                result[name] = init.getLiteralValue();
+                            }
+                            else if (Node.isNumericLiteral(init)) {
+                                result[name] = Number(init.getText());
+                            }
+                        }
+                    }
+                }
+                return result;
+            }
+        }
+        return null;
+    }
+    /**
+     * Find files recursively matching a pattern
+     */
+    findFilesRecursive(dir, pattern) {
+        const results = [];
+        if (!fs.existsSync(dir)) {
+            return results;
+        }
+        const patternRegex = this.globToRegex(pattern);
+        this.walkDirectory(dir, '', patternRegex, results);
+        return results;
+    }
+    /**
+     * Walk directory recursively
+     */
+    walkDirectory(baseDir, relativePath, pattern, results) {
+        const currentDir = path.join(baseDir, relativePath);
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                // Skip node_modules and hidden directories
+                if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                    this.walkDirectory(baseDir, entryRelativePath, pattern, results);
+                }
+            }
+            else if (entry.isFile()) {
+                if (pattern.test(entryRelativePath)) {
+                    results.push(path.join(baseDir, entryRelativePath));
+                }
+            }
+        }
+    }
+    /**
+     * Convert glob pattern to regex
+     */
+    globToRegex(glob) {
+        const escaped = glob
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*\*/g, '{{DOUBLE_STAR}}')
+            .replace(/\*/g, '[^/]*')
+            .replace(/\{\{DOUBLE_STAR\}\}/g, '.*')
+            .replace(/\?/g, '.');
+        return new RegExp(`^${escaped}$`);
+    }
+    /**
+     * Infer route from controller class name
+     */
+    inferRouteFromClassName(className) {
+        // Remove 'Controller' suffix and convert to kebab-case
+        let name = className.replace(/Controller$/, '');
+        // Handle common prefixes
+        name = name.replace(/^Shop/, '');
+        // Convert PascalCase to kebab-case
+        const kebab = name
+            .replace(/([a-z])([A-Z])/g, '$1-$2')
+            .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+            .toLowerCase();
+        return `/${kebab}`;
+    }
+    /**
+     * Extract tag from file path
+     */
+    extractTagFromPath(relativePath) {
+        // Example: src/api/shop/cart/cartAddItemsController.ts -> cart
+        const parts = relativePath.split('/');
+        const apiIndex = parts.indexOf('api');
+        if (apiIndex >= 0 && apiIndex + 2 < parts.length) {
+            return parts[apiIndex + 2];
+        }
+        return 'general';
+    }
+    /**
+     * Clean type name by removing import paths and generics from common wrappers
+     */
+    cleanTypeName(typeName) {
+        // Remove import() syntax
+        let cleaned = typeName.replace(/import\([^)]+\)\./g, '');
+        // Remove namespace prefixes
+        cleaned = cleaned.replace(/\w+\./g, (match) => {
+            // Keep Temporal prefix for special types
+            if (match === 'Temporal.') {
+                return match;
+            }
+            return '';
+        });
+        return cleaned.trim();
+    }
+}
+//# sourceMappingURL=controller-parser.js.map