progmune-runtime 3.7.56 → 3.7.57

package/dist/frameworks/nestjs-detector.js

@@ -17,6 +17,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.analyzeNestJSProject = analyzeNestJSProject;
+exports.collectAppLevelProviders = collectAppLevelProviders;
 exports.analyzeNestJSFile = analyzeNestJSFile;
 exports.formatNestJSReport = formatNestJSReport;
 const ts_morph_1 = require("ts-morph");
@@ -38,51 +39,47 @@ function analyzeNestJSProject(projectRoot) {
             project.addSourceFilesAtPaths(`${projectRoot}/**/*.ts`);
         }
         catch {
-            return { controllers: [], routes: [], issues: [], globalAuthGuards: [] };
+            return {
+                controllers: [], routes: [], issues: [], globalAuthGuards: [],
+                globalValidationPipes: [], registrations: [],
+            };
         }
     }
+    // 需要跳过 node_modules / 测试文件（它们在多个扫描里重复出现，抽出来一次）
+    const sourceFiles = project
+        .getSourceFiles()
+        .filter((f) => !f.getFilePath().includes("node_modules") &&
+        !/\.(test|spec)\.ts$/.test(f.getFilePath()));
+    // ── 注册事件（§52）：一次性收集全部 app-level provider ──
+    const registrations = collectAppLevelProviders(sourceFiles);
     const analysis = {
         controllers: [],
         routes: [],
         issues: [],
         globalAuthGuards: [],
+        globalValidationPipes: registrations
+            .filter((r) => r.token === "APP_PIPE")
+            .map((r) => r.impl)
+            .filter((n) => !!n),
+        registrations,
     };
-    // ── 第一遍：全局守卫（@Module providers 里的 APP_GUARD）──
-    for (const file of project.getSourceFiles()) {
-        if (file.getFilePath().includes("node_modules"))
-            continue;
-        if (/\.(test|spec)\.ts$/.test(file.getFilePath()))
-            continue;
-        for (const cls of file.getClasses()) {
-            const moduleDec = cls.getDecorator("Module");
-            if (!moduleDec)
-                continue;
-            const guardNames = extractAppGuardNames(moduleDec, cls);
-            for (const name of guardNames) {
-                if (isAuthGuardName(name) && !analysis.globalAuthGuards.includes(name)) {
-                    analysis.globalAuthGuards.push(name);
-                }
-            }
+    // 全局认证守卫 = APP_GUARD 注册事件里名字分类为「认证」的那些
+    for (const reg of registrations.filter((r) => r.token === "APP_GUARD")) {
+        const name = reg.impl;
+        if (name && isAuthGuardName(name) && !analysis.globalAuthGuards.includes(name)) {
+            analysis.globalAuthGuards.push(name);
         }
     }
     const hasGlobalAuthGuard = analysis.globalAuthGuards.length > 0;
-    // ── 全局校验管道（2026-09-29：docmost 123 条 NO_VALIDATION 失明误报的根因）──
-    // NestJS 标准做法是 bootstrap 里 app.useGlobalPipes(new ValidationPipe(...))，
-    // 路由本身不带 @UsePipes 装饰器 ⇒ 此前全部报 NO_VALIDATION。
-    // 检测方式：任意非 node_modules 源文件出现 .useGlobalPipes( 调用（参数不限——
-    // hedgedoc 形态是 useGlobalPipes(setupValidationPipe(logger))，管道经辅助函数
-    // 创建，字面 ValidationPipe 不在调用处）。
-    // 保守判定：全局管道只豁免「入参是已校验 DTO」的路由（见下），裸类型入参仍报。
-    let hasGlobalValidationPipe = false;
-    for (const file of project.getSourceFiles()) {
-        if (file.getFilePath().includes("node_modules"))
-            continue;
-        if (/\.(test|spec)\.ts$/.test(file.getFilePath()))
-            continue;
-        if (/\.useGlobalPipes\s*\(/.test(file.getText())) {
-            hasGlobalValidationPipe = true;
-            break;
-        }
+    // ── 全局校验管道（两条官方注册途径：bootstrap useGlobalPipes / DI APP_PIPE）──
+    // 注：`useGlobalPipes()` 的参数不限管道类名——hedgedoc 的形态是
+    // useGlobalPipes(setupValidationPipe(logger))，管道经辅助函数创建，
+    // 字面 ValidationPipe 不在调用处。
+    const bootstrapPipeCall = sourceFiles.some((f) => /\.useGlobalPipes\s*\(/.test(f.getText()));
+    const hasGlobalValidationPipe = bootstrapPipeCall || analysis.globalValidationPipes.length > 0;
+    if (hasGlobalValidationPipe && bootstrapPipeCall) {
+        // bootstrap 途径拿不到实现名（参数可能是任意表达式），留占位便于报告展示
+        analysis.globalValidationPipes.push("useGlobalPipes()");
     }
     // ── 已校验 DTO 类名集合（E3 通道同款实现，import 落地代码而非重写）──
     const validatedDtos = hasGlobalValidationPipe
@@ -169,13 +166,13 @@ function analyzeNestJSProject(projectRoot) {
             const ctrlDec = cls.getDecorator("Controller");
             if (!ctrlDec)
                 continue;
-            const basePath = getStringArg(ctrlDec, 0) || "";
+            const basePaths = getRoutePaths(ctrlDec);
             for (const method of cls.getMethods()) {
-                const http = getHttpMethod(method);
-                if (!http)
+                const httpDec = method.getDecorators().find((d) => isHttpDecorator(d));
+                if (!httpDec)
                     continue;
-                const routePath = getStringArg(method.getDecorators().find((d) => isHttpDecorator(d)), 0) || "";
-                allRoutePaths.push(basePath + (routePath.startsWith("/") ? routePath : `/${routePath}`));
+                for (const p of joinRoutePaths(basePaths, getRoutePaths(httpDec)))
+                    allRoutePaths.push(p);
             }
         }
     }
@@ -192,7 +189,7 @@ function analyzeNestJSProject(projectRoot) {
                 continue;
             const controllerName = cls.getName() || "UnknownController";
             analysis.controllers.push(controllerName);
-            const basePath = getStringArg(ctrlDec, 0) || "";
+            const basePaths = getRoutePaths(ctrlDec);
             const classGuards = extractGuardNames(cls.getDecorator("UseGuards"));
             const classPipes = extractGuardNames(cls.getDecorator("UsePipes"));
             const classPublic = cls.getDecorator("Public") !== undefined
@@ -202,8 +199,9 @@ function analyzeNestJSProject(projectRoot) {
                 const httpMethod = getHttpMethod(method);
                 if (!httpMethod)
                     continue;
-                const routePath = getStringArg(method.getDecorators().find(d => isHttpDecorator(d)), 0) || "";
-                const fullPath = basePath + (routePath.startsWith("/") ? routePath : `/${routePath}`);
+                // 一条 handler 可以注册多个路径别名 ⇒ 每条路径各自出一条 route、各自判一次
+                // （§52：路径畸变会让依赖 path 的判据静默失准，见 getRoutePaths 注释）
+                const routePaths = joinRoutePaths(basePaths, getRoutePaths(method.getDecorators().find(d => isHttpDecorator(d))));
                 // Guards/Pipes: method-level overrides class-level
                 const methodGuards = extractGuardNames(method.getDecorator("UseGuards"));
                 const methodPipes = extractGuardNames(method.getDecorator("UsePipes"));
@@ -234,70 +232,73 @@ function analyzeNestJSProject(projectRoot) {
                 // auth/collab-token、auth/logout 等无 body 路由被误报 NO_VALIDATION）。
                 // 没有可校验的 DTO 输入，规则判定面不覆盖，不报。
                 const hasStructuredInput = method.getParameters().some((param) => param.getDecorators().some((d) => ["Body", "Query", "Param"].includes(d.getName())));
-                const route = {
-                    method: httpMethod,
-                    path: fullPath,
-                    controller: controllerName,
-                    handler: method.getName() || "unknown",
-                    hasAuthGuard: authGuards.length > 0,
-                    hasValidationPipe: pipes.length > 0,
-                    hasValidatedDto,
-                    guards,
-                    pipes,
-                    isPublicDecorated,
-                };
-                analysis.routes.push(route);
-                // 路由级保护判定：类/方法认证守卫，或全局 APP_GUARD（除非 @Public 豁免），
-                // 或模块级中间件 forRoutes 覆盖（Nest 5 惯用法）
-                const protectedByGlobal = hasGlobalAuthGuard && !isPublicDecorated;
-                const protectedByMiddleware = middlewareCovers(ctrlMiddleware, controllerName, httpMethod, fullPath);
-                // ── Security Checks ──
-                // POST/PUT/DELETE without auth guard
-                // Skip intentionally public routes (login, register, health, etc.)
-                if (["POST", "PUT", "DELETE", "PATCH"].includes(httpMethod) && !isPublicRoute(fullPath)) {
-                    const isRegisterPost = httpMethod === "POST" && (0, route_window_1.isRegisterRoot)(fullPath, registerRoots);
-                    if (!route.hasAuthGuard && !protectedByGlobal && !protectedByMiddleware && !isRegisterPost) {
-                        analysis.issues.push({
-                            type: "NESTJS_NO_AUTH",
-                            severity: "critical",
-                            route: `${httpMethod} ${fullPath}`,
-                            controller: controllerName,
-                            message: `Mutation route ${httpMethod} ${fullPath} has no auth guard and ` +
-                                (hasGlobalAuthGuard
-                                    ? `is explicitly marked public — it bypasses the global ${analysis.globalAuthGuards.join("/")}.`
-                                    : `no global APP_GUARD protects the app. Anyone can call it.`),
-                            fix: `Add @UseGuards(AuthGuard) to the method or controller class, or remove the @Public marker.`,
-                        });
-                    }
-                    // 豁免：@UsePipes 装饰器，或「全局 ValidationPipe + 入参是已校验 DTO」
-                    // （docmost 实测 123 条失明误报的修复——路由 DTO 在别的文件带
-                    // class-validator 装饰器，只看 @UsePipes 永远看不到），
-                    // 或路由无结构化输入（没有可校验的东西）
-                    const validatedByGlobalPipe = hasGlobalValidationPipe && route.hasValidatedDto;
-                    if (!route.hasValidationPipe && !validatedByGlobalPipe && hasStructuredInput) {
-                        analysis.issues.push({
-                            type: "NESTJS_NO_VALIDATION",
-                            severity: "medium",
-                            route: `${httpMethod} ${fullPath}`,
-                            controller: controllerName,
-                            message: `Mutation route ${httpMethod} ${fullPath} has no @UsePipes for input validation.`,
-                            fix: `Add @UsePipes(ValidationPipe) or a DTO class to validate input.`,
-                        });
+                for (const fullPath of routePaths) {
+                    const route = {
+                        method: httpMethod,
+                        path: fullPath,
+                        controller: controllerName,
+                        handler: method.getName() || "unknown",
+                        hasAuthGuard: authGuards.length > 0,
+                        hasValidationPipe: pipes.length > 0,
+                        hasValidatedDto,
+                        hasStructuredInput,
+                        guards,
+                        pipes,
+                        isPublicDecorated,
+                    };
+                    analysis.routes.push(route);
+                    // 路由级保护判定：类/方法认证守卫，或全局 APP_GUARD（除非 @Public 豁免），
+                    // 或模块级中间件 forRoutes 覆盖（Nest 5 惯用法）
+                    const protectedByGlobal = hasGlobalAuthGuard && !isPublicDecorated;
+                    const protectedByMiddleware = middlewareCovers(ctrlMiddleware, controllerName, httpMethod, fullPath);
+                    // ── Security Checks ──
+                    // POST/PUT/DELETE without auth guard
+                    // Skip intentionally public routes (login, register, health, etc.)
+                    if (["POST", "PUT", "DELETE", "PATCH"].includes(httpMethod) && !isPublicRoute(fullPath)) {
+                        const isRegisterPost = httpMethod === "POST" && (0, route_window_1.isRegisterRoot)(fullPath, registerRoots);
+                        if (!route.hasAuthGuard && !protectedByGlobal && !protectedByMiddleware && !isRegisterPost) {
+                            analysis.issues.push({
+                                type: "NESTJS_NO_AUTH",
+                                severity: "critical",
+                                route: `${httpMethod} ${fullPath}`,
+                                controller: controllerName,
+                                message: `Mutation route ${httpMethod} ${fullPath} has no auth guard and ` +
+                                    (hasGlobalAuthGuard
+                                        ? `is explicitly marked public — it bypasses the global ${analysis.globalAuthGuards.join("/")}.`
+                                        : `no global APP_GUARD protects the app. Anyone can call it.`),
+                                fix: `Add @UseGuards(AuthGuard) to the method or controller class, or remove the @Public marker.`,
+                            });
+                        }
+                        // 豁免：@UsePipes 装饰器，或「全局 ValidationPipe + 入参是已校验 DTO」
+                        // （docmost 实测 123 条失明误报的修复——路由 DTO 在别的文件带
+                        // class-validator 装饰器，只看 @UsePipes 永远看不到），
+                        // 或路由无结构化输入（没有可校验的东西）
+                        const validatedByGlobalPipe = hasGlobalValidationPipe && route.hasValidatedDto;
+                        if (!route.hasValidationPipe && !validatedByGlobalPipe && hasStructuredInput) {
+                            analysis.issues.push({
+                                type: "NESTJS_NO_VALIDATION",
+                                severity: "medium",
+                                route: `${httpMethod} ${fullPath}`,
+                                controller: controllerName,
+                                message: `Mutation route ${httpMethod} ${fullPath} has no @UsePipes for input validation.`,
+                                fix: `Add @UsePipes(ValidationPipe) or a DTO class to validate input.`,
+                            });
+                        }
                     }
-                }
-                // Sensitive GET routes without auth
-                if (httpMethod === "GET") {
-                    const sensitiveTerms = ["admin", "private", "secret", "manage"];
-                    if (sensitiveTerms.some(t => fullPath.toLowerCase().includes(t))
-                        && !route.hasAuthGuard && !protectedByGlobal && !protectedByMiddleware) {
-                        analysis.issues.push({
-                            type: "NESTJS_SENSITIVE_PUBLIC",
-                            severity: "high",
-                            route: `${httpMethod} ${fullPath}`,
-                            controller: controllerName,
-                            message: `Sensitive GET route ${fullPath} is publicly accessible without auth protection.`,
-                            fix: `Add @UseGuards(AuthGuard) to protect this route.`,
-                        });
+                    // Sensitive GET routes without auth
+                    if (httpMethod === "GET") {
+                        const sensitiveTerms = ["admin", "private", "secret", "manage"];
+                        if (sensitiveTerms.some(t => fullPath.toLowerCase().includes(t))
+                            && !route.hasAuthGuard && !protectedByGlobal && !protectedByMiddleware) {
+                            analysis.issues.push({
+                                type: "NESTJS_SENSITIVE_PUBLIC",
+                                severity: "high",
+                                route: `${httpMethod} ${fullPath}`,
+                                controller: controllerName,
+                                message: `Sensitive GET route ${fullPath} is publicly accessible without auth protection.`,
+                                fix: `Add @UseGuards(AuthGuard) to protect this route.`,
+                            });
+                        }
                     }
                 }
             }
@@ -316,10 +317,211 @@ function isAuthGuardName(name) {
         return false;
     return /auth|jwt|session|permission|role|access|apikey|api_key|token|login|passport/.test(lower);
 }
+// ═══════════════════════════════════════════════════════════════
+//  §52（2026-10-03）：App-level provider 注册事件收集
+// ═══════════════════════════════════════════════════════════════
+//
+// 三条发现途径，取并集，每条都留 (file, line) 供复核：
+//   A. `@Module({ providers: [...] })` 装饰器数组
+//   B. `providers = [...]` 类属性
+//   C. 任意数组常量 `const xxx = [...]`（含沿 spread 回溯）+ 逐行文本兜底
+//
+// C 存在的理由正是 immich：
+//     const commonMiddleware = [ { provide: APP_PIPE, useClass: ZodValidationPipe }, ... ];
+//     const apiMiddleware   = [ FileUploadInterceptor, ...commonMiddleware, {...} ];
+//     @Module({ providers: [...common, ...apiMiddleware, ...] })
+// `APP_PIPE` 离 `@Module` 隔了两跳 spread，只看装饰器那一层永远看不到。
+//
+// 「哪里表达了注册意图」与「它最终被挂在哪个模块上」是两件事 ——
+// 判定「是否存在全局校验管道」只需要前者；把两者绑死（要求 spread 必须
+// 追溯到某个 @Module）会让判定再次退化为形态枚举。见 §52 报告。
+const APP_TOKEN_RE = /^APP_(PIPE|GUARD|INTERCEPTOR|FILTER)$/;
+function appTokenOf(text) {
+    if (!text)
+        return null;
+    // 处理 import("@nestjs/core").APP_PIPE / 'APP_PIPE' 等形态
+    const cleaned = text.replace(/^['"]|['"]$/g, "").replace(/^.*\./, "").trim();
+    return APP_TOKEN_RE.test(cleaned) ? cleaned : null;
+}
+/** useClass/useExisting 的实现类名（useFactory/useValue 取不到 ⇒ null，保守不动） */
+function implNameOf(obj) {
+    const pick = (key) => {
+        const prop = obj.getProperty?.(key);
+        const init = prop?.getInitializer?.();
+        const text = init?.getText?.() ?? "";
+        const m = /^[A-Za-z_$][\w$]*$/.exec(text.trim());
+        return m ? m[0] : null;
+    };
+    return pick("useClass") ?? pick("useExisting");
+}
+function providersArrayOf(obj) {
+    if (!obj)
+        return undefined;
+    const lit = obj.asKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression);
+    if (!lit)
+        return undefined;
+    const prop = lit.getProperty("providers");
+    if (!prop)
+        return undefined;
+    return prop.getInitializer?.()?.asKind?.(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+}
+function collectAppLevelProviders(sourceFiles) {
+    const out = [];
+    const seen = new Set();
+    const add = (r) => {
+        const key = `${r.token}|${r.impl}|${r.file}|${r.line}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(r);
+    };
+    // 文件级预筛：没出现 APP_* token 的文件直接跳过（绝大多数文件）
+    const candidates = sourceFiles.filter((f) => /APP_(PIPE|GUARD|INTERCEPTOR|FILTER)\b/.test(f.getFullText()) &&
+        // 测试脚手架里的 providers 是给「测试 app」搭的，不是生产注册证据。
+        // immich 实测：`test/utils.ts` 里有一整套 APP_PIPE/APP_GUARD 用于构造测试用的
+        // Nest app —— 采信它等于拿测试环境的配置豁免生产代码。
+        !/\.(test|spec)\.ts$/.test(f.getFilePath()) &&
+        !/\/(test|tests|__tests__|__mocks__|e2e)\//.test(f.getFilePath()));
+    if (candidates.length === 0)
+        return out;
+    // ── 顶层/模块级变量索引（回溯用，§52）──
+    //   数组变量：spread 引用链 `...middleware` 的目标
+    //   对象变量：`@Module(configVar)` 的装饰器参数（nocodb 形态普查：7 个 @Module 里
+    //              **5 个（71%）是变量**而不是对象字面量 —— 主流写法，不是边角情况）
+    // ⚠ 索引**不做 APP_ 过滤**：中间变量往往不直接含 token
+    //   （immich 的 `apiMiddleware` 只含 APP_GUARD，APP_PIPE 在再下一跳的 `commonMiddleware` 里）。
+    const arrayVars = new Map();
+    const objectVars = new Map();
+    for (const sf of candidates) {
+        for (const vs of sf.getVariableStatements()) {
+            for (const vd of vs.getDeclarations()) {
+                const init = vd.getInitializer();
+                if (!init)
+                    continue;
+                const name = vd.getName();
+                const arr = init.asKind?.(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                if (arr) {
+                    if (!arrayVars.has(name))
+                        arrayVars.set(name, arr);
+                    continue;
+                }
+                const obj = init.asKind?.(ts_morph_1.SyntaxKind.ObjectLiteralExpression);
+                if (obj && !objectVars.has(name))
+                    objectVars.set(name, obj);
+            }
+        }
+    }
+    const recordFromObj = (obj, source, via) => {
+        const provideProp = obj.getProperty("provide");
+        if (!provideProp)
+            return;
+        const init = provideProp.getInitializer?.();
+        const token = appTokenOf(init?.getText?.() ?? provideProp.getText());
+        if (!token)
+            return;
+        add({
+            token,
+            impl: implNameOf(obj),
+            source,
+            via,
+            file: obj.getSourceFile().getFilePath(),
+            line: obj.getStartLineNumber(),
+        });
+    };
+    const parseArray = (arr, source, via, depth) => {
+        if (depth > 5)
+            return;
+        for (const el of arr.getElements()) {
+            const obj = el.asKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression);
+            if (obj) {
+                recordFromObj(obj, source, via);
+                continue;
+            }
+            const spread = el.asKind(ts_morph_1.SyntaxKind.SpreadElement);
+            if (!spread)
+                continue;
+            const id = /^[A-Za-z_$][\w$]*$/.exec(spread.getExpression().getText().trim());
+            if (!id)
+                continue;
+            if (via.includes(id[0]))
+                continue; // 防止循环引用
+            const target = arrayVars.get(id[0]);
+            if (target)
+                parseArray(target, "array-literal", [...via, id[0]], depth + 1);
+        }
+    };
+    for (const sf of candidates) {
+        // A + B：@Module 装饰器 / 类属性 providers
+        for (const cls of sf.getClasses()) {
+            const moduleDec = cls.getDecorator("Module");
+            if (!moduleDec)
+                continue;
+            const rawArg = moduleDec.getArguments()[0];
+            // `@Module(configVar)`：装饰器参数是变量 ⇒ 回溯到它的对象字面量定义
+            let decArg = rawArg;
+            if (rawArg?.getKind() === ts_morph_1.SyntaxKind.Identifier) {
+                decArg = objectVars.get(rawArg.getText().trim());
+            }
+            const decArr = providersArrayOf(decArg);
+            if (decArr)
+                parseArray(decArr, "module-decorator", [], 0);
+            for (const prop of cls.getProperties()) {
+                if (prop.getName() !== "providers")
+                    continue;
+                const pArr = prop.getInitializer()?.asKind?.(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                if (pArr)
+                    parseArray(pArr, "module-property", [], 0);
+            }
+        }
+        // C：数组常量（不要求被某个 @Module 引用）
+        for (const vs of sf.getVariableStatements()) {
+            for (const vd of vs.getDeclarations()) {
+                const arr = vd.getInitializer()?.asKind?.(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                if (!arr)
+                    continue;
+                if (!/APP_(PIPE|GUARD|INTERCEPTOR|FILTER)\b/.test(arr.getText()))
+                    continue;
+                parseArray(arr, "array-literal", [], 0);
+            }
+        }
+    }
+    // 逐行文本兜底：覆盖 AST 路径之外的写法（函数体内构造、动态拼装等）。
+    // 只补结构化解析没抓到的行，且跳过注释行。
+    const knownLines = new Set(out.map((r) => `${r.file}:${r.line}`));
+    for (const sf of candidates) {
+        const filePath = sf.getFilePath();
+        sf.getFullText()
+            .split("\n")
+            .forEach((line, i) => {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*"))
+                return;
+            const m = /\{\s*provide\s*:\s*(?:[^A-Za-z]*?)APP_(PIPE|GUARD|INTERCEPTOR|FILTER)\b/.exec(line);
+            if (!m)
+                return;
+            const key = `${filePath}:${i + 1}`;
+            if (knownLines.has(key))
+                return;
+            const implM = /useClass\s*:\s*([A-Za-z_$][\w$]*)/.exec(line);
+            add({
+                token: `APP_${m[1]}`,
+                impl: implM ? implM[1] : null,
+                source: "text-fallback",
+                via: [],
+                file: filePath,
+                line: i + 1,
+            });
+        });
+    }
+    return out;
+}
 /**
  * 从 @Module 装饰器的 providers 提取 APP_GUARD 类名：
  *   providers: [{ provide: APP_GUARD, useClass: AuthGuard }]
  * 支持装饰器参数对象字面量与类属性 providers 两种形态。
+ *
+ * ⚠ 保留仅为兼容（早期调用方）：内含 spread 的形态（`...commonMiddleware`）
+ * 解析不了，真实注册事件请用 collectAppLevelProviders()（§52）。
  */
 function extractAppGuardNames(moduleDec, cls) {
     const names = [];
@@ -477,6 +679,50 @@ function getHttpMethod(method) {
 function isHttpDecorator(dec) {
     return ["Get", "Post", "Put", "Delete", "Patch", "Options", "Head", "All"].includes(dec.getName());
 }
+/**
+ * HTTP/Controller 装饰器的**全部**路径（Nest 允许一条 handler 注册多个路径别名）。
+ *
+ * §52 形态普查发现这不是边角写法：nocodb 348 个路由装饰器里 **250 个（72%）是数组形态**
+ *   @Post(['/api/v1/db/meta/projects/:baseId/api-tokens',
+ *          '/api/v2/meta/bases/:baseId/api-tokens'])
+ * 旧实现把整段数组文本当成一个路径 ⇒ path 变成形如 `/[\n '/api/v1...',\n ...]` 的畸形串，
+ * 于是依赖 path 的判据 —— isPublicRoute / middlewareCovers / registerRoots —— **全线静默失效**：
+ * 既匹配不到公开端点（该豁免的没豁免），也匹配不到中间件覆盖。
+ * ⇒ 这是「读不出来」而不是「判错」，属于接线缺陷，不是判据缺陷。
+ *
+ * 处理：字符串/数组逐项展开；模板字符串含 `${}` 无法静态求值 ⇒ 保留原文（不静默丢弃）。
+ */
+function getRoutePaths(decorator) {
+    if (!decorator)
+        return [""];
+    const arg = decorator.getArguments()[0];
+    const strip = (t) => t.replace(/^['"`]|['"`]$/g, "");
+    if (!arg)
+        return [""];
+    const arr = arg.asKind(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+    if (arr) {
+        const out = [];
+        for (const el of arr.getElements()) {
+            const kind = el.getKind();
+            if (kind === ts_morph_1.SyntaxKind.StringLiteral || kind === ts_morph_1.SyntaxKind.NoSubstitutionTemplateLiteral) {
+                out.push(strip(el.getText()));
+            }
+            // 其它形态（模板表达式、标识符）不可静态求值 ⇒ 跳过（宁可不展开，不产生脏路径）
+        }
+        return out.length > 0 ? out : [""];
+    }
+    return [strip(arg.getText())];
+}
+/** 拼接 controller 基路径与方法路径（Nest 的 join 语义） */
+function joinRoutePaths(basePaths, routePaths) {
+    const out = [];
+    for (const b of basePaths) {
+        for (const r of routePaths) {
+            out.push(b + (r.startsWith("/") || r === "" ? r : `/${r}`));
+        }
+    }
+    return out;
+}
 function getStringArg(decorator, index) {
     if (!decorator)
         return undefined;
@@ -486,17 +732,34 @@ function getStringArg(decorator, index) {
     const text = args[index].getText();
     return text.replace(/^['"]|['"]$/g, "");
 }
+/**
+ * @UseGuards / @UsePipes 参数里被注册的类名（取每个参数的**首个**标识符）。
+ *
+ * §52 修正：此前只收 `(?:Guard|Pipe|Interceptor)` 后缀的名字 ⇒
+ * `@UsePipes(ZodValidationPipe)` 好用、`@UsePipes(customBodyValidator)` 或
+ * `@UseGuards(Auth)` 全都看不见。但 Nest 强制 @UsePipes 的参数实现
+ * PipeTransform、@UseGuards 的参数实现 CanActivate ——
+ * **装饰器本身已经确定了它们是管道/守卫，不需要再从名字上确认一遍。**
+ *
+ * 「它是不是认证守卫」（ThrottlerGuard ≠ 认证）是另一件事，由 isAuthGuardName
+ * 单独判断。这两个关注点此前混在一起，导致「名字不像 ⇒ 连存在都看不见」。
+ *
+ * 只取首个标识符是为了避免把 `AuthGuard('JWT')` 里的 JWT 也当成守卫名
+ * （那会凭空多出一条认证证据，属反向误判）。
+ */
 function extractGuardNames(decorator) {
     if (!decorator)
         return [];
-    const args = decorator.getArguments();
     const result = [];
-    for (const arg of args) {
-        const text = arg.getText();
-        // Handle: @UseGuards(AuthGuard) or @UseGuards(AuthGuard, AdminGuard)
-        const matches = text.match(/\b([A-Z][a-zA-Z0-9]*(?:Guard|Pipe|Interceptor))\b/g);
-        if (matches)
-            result.push(...matches);
+    for (const arg of decorator.getArguments()) {
+        const text = arg
+            .getText()
+            .trim()
+            .replace(/^(?:new|await|void|typeof)\s+/, "")
+            .replace(/^this\./, "");
+        const m = /^[A-Za-z_$][\w$]*/.exec(text);
+        if (m)
+            result.push(m[0]);
     }
     return result;
 }
@@ -525,6 +788,8 @@ function analyzeNestJSFile(filePath) {
         routes: [],
         issues: [],
         globalAuthGuards: [], // 单文件分析无全局守卫上下文（项目级请用 analyzeNestJSProject）
+        globalValidationPipes: [],
+        registrations: [],
     };
     for (const file of project.getSourceFiles()) {
         for (const cls of file.getClasses()) {
@@ -534,66 +799,68 @@ function analyzeNestJSFile(filePath) {
             // ... (same parsing logic)
             const controllerName = cls.getName() || "UnknownController";
             analysis.controllers.push(controllerName);
-            const basePath = getStringArg(ctrlDec, 0) || "";
+            const basePaths = getRoutePaths(ctrlDec);
             const classGuards = extractGuardNames(cls.getDecorator("UseGuards"));
             const classPipes = extractGuardNames(cls.getDecorator("UsePipes"));
             for (const method of cls.getMethods()) {
                 const httpMethod = getHttpMethod(method);
                 if (!httpMethod)
                     continue;
-                const routePath = getStringArg(method.getDecorators().find(d => isHttpDecorator(d)), 0) || "";
-                const fullPath = basePath + (routePath.startsWith("/") ? routePath : `/${routePath}`);
+                const routePaths = joinRoutePaths(basePaths, getRoutePaths(method.getDecorators().find(d => isHttpDecorator(d))));
                 const methodGuards = extractGuardNames(method.getDecorator("UseGuards"));
                 const methodPipes = extractGuardNames(method.getDecorator("UsePipes"));
                 const guards = methodGuards.length > 0 ? methodGuards : classGuards;
                 const pipes = methodPipes.length > 0 ? methodPipes : classPipes;
-                const route = {
-                    method: httpMethod,
-                    path: fullPath,
-                    controller: controllerName,
-                    handler: method.getName() || "unknown",
-                    hasAuthGuard: guards.filter(isAuthGuardName).length > 0,
-                    hasValidationPipe: pipes.length > 0,
-                    hasValidatedDto: false, // 单文件分析无跨文件 DTO 上下文（项目级用 analyzeNestJSProject）
-                    guards,
-                    pipes,
-                    isPublicDecorated: false, // 单文件分析不解析 @Public（项目级用 analyzeNestJSProject）
-                };
-                analysis.routes.push(route);
-                // Security checks
-                if (["POST", "PUT", "DELETE", "PATCH"].includes(httpMethod) && !isPublicRoute(fullPath)) {
-                    if (!route.hasAuthGuard) {
-                        analysis.issues.push({
-                            type: "NESTJS_NO_AUTH",
-                            severity: "critical",
-                            route: `${httpMethod} ${fullPath}`,
-                            controller: controllerName,
-                            message: `Mutation route ${httpMethod} ${fullPath} has no @UseGuards. Anyone can call it.`,
-                            fix: `Add @UseGuards(AuthGuard) to the method or controller class.`,
-                        });
-                    }
-                    if (!route.hasValidationPipe) {
-                        analysis.issues.push({
-                            type: "NESTJS_NO_VALIDATION",
-                            severity: "medium",
-                            route: `${httpMethod} ${fullPath}`,
-                            controller: controllerName,
-                            message: `Mutation route ${httpMethod} ${fullPath} has no @UsePipes for input validation.`,
-                            fix: `Add @UsePipes(ValidationPipe) or a DTO class to validate input.`,
-                        });
+                for (const fullPath of routePaths) {
+                    const route = {
+                        method: httpMethod,
+                        path: fullPath,
+                        controller: controllerName,
+                        handler: method.getName() || "unknown",
+                        hasAuthGuard: guards.filter(isAuthGuardName).length > 0,
+                        hasValidationPipe: pipes.length > 0,
+                        hasValidatedDto: false, // 单文件分析无跨文件 DTO 上下文（项目级用 analyzeNestJSProject）
+                        hasStructuredInput: true, // 单文件分析不区分（项目级解析真实入参）
+                        guards,
+                        pipes,
+                        isPublicDecorated: false, // 单文件分析不解析 @Public（项目级用 analyzeNestJSProject）
+                    };
+                    analysis.routes.push(route);
+                    // Security checks
+                    if (["POST", "PUT", "DELETE", "PATCH"].includes(httpMethod) && !isPublicRoute(fullPath)) {
+                        if (!route.hasAuthGuard) {
+                            analysis.issues.push({
+                                type: "NESTJS_NO_AUTH",
+                                severity: "critical",
+                                route: `${httpMethod} ${fullPath}`,
+                                controller: controllerName,
+                                message: `Mutation route ${httpMethod} ${fullPath} has no @UseGuards. Anyone can call it.`,
+                                fix: `Add @UseGuards(AuthGuard) to the method or controller class.`,
+                            });
+                        }
+                        if (!route.hasValidationPipe) {
+                            analysis.issues.push({
+                                type: "NESTJS_NO_VALIDATION",
+                                severity: "medium",
+                                route: `${httpMethod} ${fullPath}`,
+                                controller: controllerName,
+                                message: `Mutation route ${httpMethod} ${fullPath} has no @UsePipes for input validation.`,
+                                fix: `Add @UsePipes(ValidationPipe) or a DTO class to validate input.`,
+                            });
+                        }
                     }
-                }
-                if (httpMethod === "GET") {
-                    const sensitiveTerms = ["admin", "private", "secret", "manage"];
-                    if (sensitiveTerms.some(t => fullPath.toLowerCase().includes(t)) && !route.hasAuthGuard) {
-                        analysis.issues.push({
-                            type: "NESTJS_SENSITIVE_PUBLIC",
-                            severity: "high",
-                            route: `${httpMethod} ${fullPath}`,
-                            controller: controllerName,
-                            message: `Sensitive GET route ${fullPath} is publicly accessible without @UseGuards.`,
-                            fix: `Add @UseGuards(AuthGuard) to protect this route.`,
-                        });
+                    if (httpMethod === "GET") {
+                        const sensitiveTerms = ["admin", "private", "secret", "manage"];
+                        if (sensitiveTerms.some(t => fullPath.toLowerCase().includes(t)) && !route.hasAuthGuard) {
+                            analysis.issues.push({
+                                type: "NESTJS_SENSITIVE_PUBLIC",
+                                severity: "high",
+                                route: `${httpMethod} ${fullPath}`,
+                                controller: controllerName,
+                                message: `Sensitive GET route ${fullPath} is publicly accessible without @UseGuards.`,
+                                fix: `Add @UseGuards(AuthGuard) to protect this route.`,
+                            });
+                        }
                     }
                 }
             }