botversion-sdk 2.2.3 → 2.3.1

package/scanner-sdk/scan/nestjs.js

@@ -0,0 +1,660 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/nestjs.js
+// PURPOSE: Finds API routes in NestJS projects (@Controller, @Get, @Post ...), with their full URL, request fields and reply shape.
+// CONTAINS: scanNestJsRoutes
+// USED BY: scanner.js (scanNestJsRoutes)
+// DEPENDS ON: ./field-extractors, ./text-utils, ./response-shape, ./nest-source
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const {
+  extractBodyFieldsFromFile,
+  extractMultipartFieldsFromFile,
+  extractQueryFieldsFromFile,
+  mergeBodyWithMultipart,
+} = require("./field-extractors");
+const {
+  buildRouteParamMap,
+  removePathParamFields,
+  sliceCallText,
+  splitStaticEntries,
+  findStaticClosingBrace,
+} = require("./text-utils");
+const {
+  parseStaticObjectFields,
+  guessStaticValueType,
+  extractResponseFieldsFromSegment,
+} = require("./response-shape");
+const src = require("./nest-source");
+
+const HTTP_DECORATORS = {
+  Get: "GET",
+  Post: "POST",
+  Put: "PUT",
+  Delete: "DELETE",
+  Patch: "PATCH",
+  All: "GET", // same convention as the Express scan: "all" routes are stored as GET
+  Sse: "GET",
+};
+
+const SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "build",
+  ".cache",
+  "coverage",
+  "out",
+  "tests",
+  "test",
+  "__tests__",
+  "__mocks__",
+];
+
+function joinParts(parts) {
+  const clean = parts
+    .map(function (p) {
+      return String(p || "").replace(/^\/+|\/+$/g, "");
+    })
+    .filter(Boolean);
+  return "/" + clean.join("/");
+}
+
+function listSourceFiles(cwd) {
+  const fs = require("fs");
+  const path = require("path");
+  const files = [];
+  (function walk(dir, depth) {
+    if (depth > 12) {
+      return;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch (e) {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.includes(entry)) continue;
+      const full = path.join(dir, entry);
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch (e) {
+        continue;
+      }
+      if (stat.isDirectory()) walk(full, depth + 1);
+      else if (
+        /\.(ts|js)$/.test(entry) &&
+        !/\.(test|spec|d)\.(ts|js)$/i.test(entry)
+      )
+        files.push(full);
+    }
+  })(cwd, 0);
+  return files;
+}
+
+// First argument written as a list of text values ("a" or ["a", "b"]); null if any part is unknown
+function resolvePathList(argText, file) {
+  const text = String(argText || "").trim();
+  if (!text) return [""];
+  if (text.charAt(0) === "[") {
+    const inner = text.slice(1, text.lastIndexOf("]"));
+    const out = [];
+    for (const part of splitStaticEntries(inner) || []) {
+      const v = src.resolveStringExpr(part, file);
+      if (v === null) return null;
+      out.push(v);
+    }
+    return out.length ? out : [""];
+  }
+  const v = src.resolveStringExpr(text, file);
+  return v === null ? null : [v];
+}
+
+// Reads "key: value" entries from an object written in code
+function readObjectEntries(objText) {
+  const t = objText.trim();
+  if (t.charAt(0) !== "{") return null;
+  const inner = t.slice(
+    1,
+    src.matchClose(t, 0) === -1 ? t.length : src.matchClose(t, 0),
+  );
+  const out = {};
+  for (const entry of splitStaticEntries(inner) || []) {
+    const m =
+      /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*(?::\s*([\s\S]+))?$/.exec(
+        entry,
+      );
+    if (m) {
+      const key = m[1] || m[2] || m[3];
+      out[key] = m[4] === undefined ? key : m[4].trim();
+    }
+  }
+  return out;
+}
+
+// Versions written as "1", ["1","2"] or VERSION_NEUTRAL; [] means no version segment
+function resolveVersions(text, file) {
+  if (text === undefined || text === null) return null;
+  const t = String(text).trim();
+  if (!t || /VERSION_NEUTRAL/.test(t)) return [];
+  const list = resolvePathList(t, file);
+  return list === null ? undefined : list;
+}
+
+// Global prefix and URI versioning, read from wherever the project sets them (usually main.ts)
+function readAppSettings(files) {
+  const settings = {
+    prefix: "",
+    prefixFile: null,
+    exclude: [],
+    versioningUri: false,
+    versionPrefix: "v",
+    defaultVersions: null,
+  };
+  for (const file of files) {
+    const c = src.readSource(file);
+    if (!c) continue;
+    const gp = /\.\s*setGlobalPrefix\s*\(/.exec(c);
+    if (gp && !settings.prefixFile) {
+      const call = sliceCallText(c, gp.index);
+      const args = call
+        ? splitStaticEntries(
+            call.slice(call.indexOf("(") + 1, call.length - 1),
+          ) || []
+        : [];
+      const v = args[0] ? src.resolveStringExpr(args[0], file) : null;
+      if (v !== null) {
+        settings.prefix = v.replace(/^\/+|\/+$/g, "");
+        settings.prefixFile = file;
+        const opts = args[1] ? readObjectEntries(args[1]) : null;
+        if (opts && opts.exclude) {
+          const inner = opts.exclude
+            .trim()
+            .replace(/^\[/, "")
+            .replace(/\]$/, "");
+          (splitStaticEntries(inner) || []).forEach(function (e) {
+            const obj = readObjectEntries(e);
+            const raw = obj && obj.path ? obj.path : e;
+            const val = src.resolveStringExpr(raw, file);
+            if (val !== null)
+              settings.exclude.push(val.replace(/^\/+|\/+$/g, ""));
+          });
+        }
+      }
+    }
+    const ev = /\.\s*enableVersioning\s*\(/.exec(c);
+    if (ev && !settings.versioningFile) {
+      const call = sliceCallText(c, ev.index);
+      const args = call
+        ? splitStaticEntries(
+            call.slice(call.indexOf("(") + 1, call.length - 1),
+          ) || []
+        : [];
+      const opts = args[0] ? readObjectEntries(args[0]) : null;
+      settings.versioningFile = file;
+      if (opts && /\bURI\b/.test(opts.type || "")) {
+        settings.versioningUri = true;
+        if (opts.prefix !== undefined) {
+          const pv = /^false$/.test(opts.prefix.trim())
+            ? ""
+            : src.resolveStringExpr(opts.prefix, file);
+          if (pv !== null) settings.versionPrefix = pv;
+        }
+        if (opts.defaultVersion !== undefined) {
+          const dv = resolveVersions(opts.defaultVersion, file);
+          if (dv !== undefined) settings.defaultVersions = dv;
+        }
+      }
+    }
+  }
+  return settings;
+}
+
+// RouterModule.register([...]) paths per module, and which module declares which controllers
+function readModuleRouting(files) {
+  const modulePath = {};
+  const controllerModule = {};
+
+  function walkRoutes(arrText, file, parent) {
+    const inner = arrText.trim().replace(/^\[/, "").replace(/\]$/, "");
+    for (const entry of splitStaticEntries(inner) || []) {
+      if (/^[A-Za-z_$][\w$]*$/.test(entry)) {
+        modulePath[entry] = parent;
+        continue;
+      }
+      const obj = readObjectEntries(entry);
+      if (!obj) continue;
+      let own = "";
+      if (obj.path !== undefined) {
+        const v = src.resolveStringExpr(obj.path, file);
+        if (v === null) {
+          continue;
+        }
+        own = v;
+      }
+      const full = joinParts([parent, own]);
+      if (obj.module && /^[A-Za-z_$][\w$]*$/.test(obj.module))
+        modulePath[obj.module] = full === "/" ? "" : full;
+      if (obj.children)
+        walkRoutes(obj.children, file, full === "/" ? "" : full);
+    }
+  }
+
+  for (const file of files) {
+    const c = src.readSource(file);
+    if (!c) continue;
+    for (const m of c.matchAll(/RouterModule\s*\.\s*register\s*\(/g)) {
+      const call = sliceCallText(c, m.index);
+      if (!call) continue;
+      const arg = (splitStaticEntries(
+        call.slice(call.indexOf("(") + 1, call.length - 1),
+      ) || [])[0];
+      if (!arg) continue;
+      let arrText = arg;
+      if (/^[A-Za-z_$][\w$]*$/.test(arg)) {
+        const found = src.lookupConst(arg, file);
+        arrText = found ? found.expr : null;
+      }
+      if (arrText && arrText.trim().charAt(0) === "[")
+        walkRoutes(arrText, file, "");
+    }
+    for (const m of c.matchAll(/@Module\s*\(/g)) {
+      const call = sliceCallText(c, m.index);
+      if (!call) continue;
+      const obj = readObjectEntries(
+        call.slice(call.indexOf("(") + 1, call.length - 1),
+      );
+      const after = c.slice(m.index + call.length);
+      const cls = /class\s+([A-Za-z_$][\w$]*)/.exec(after);
+      if (!obj || !obj.controllers || !cls) continue;
+      const inner = obj.controllers
+        .trim()
+        .replace(/^\[/, "")
+        .replace(/\]$/, "");
+      (splitStaticEntries(inner) || []).forEach(function (n) {
+        if (/^[A-Za-z_$][\w$]*$/.test(n)) controllerModule[n] = cls[1];
+      });
+    }
+  }
+  return { modulePath: modulePath, controllerModule: controllerModule };
+}
+
+// Collects every route-decorated method of a class, including the ones it inherits
+function collectRoutes(file, cls, depth) {
+  const c = src.readSource(file);
+  const routes = [];
+  if (depth > 5) return routes;
+  if (cls.extendsText) {
+    const baseName = cls.extendsText.replace(/<[\s\S]*$/, "").trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(baseName)) {
+      const base = src.resolveClassByName(baseName, file);
+      if (base)
+        collectRoutes(base.file, base.cls, depth + 1).forEach(function (r) {
+          routes.push(r);
+        });
+    }
+  }
+  src.parseMembers(c, cls.open, cls.close).forEach(function (mem) {
+    if (mem.kind !== "method") return;
+    const http = mem.decorators.filter(function (d) {
+      return HTTP_DECORATORS[d.name];
+    });
+    if (http.length === 0) return;
+    routes.push({ file: file, member: mem, http: http });
+  });
+  return routes;
+}
+
+function schemaIsUseful(s) {
+  if (!s) return false;
+  if (s.type === "array")
+    return schemaIsUseful(s.items) && s.items.type !== "unknown";
+  if (s.type === "object")
+    return !!(s.properties && Object.keys(s.properties).length);
+  return false;
+}
+
+// Request fields for one route: declared types first, then how the code uses the request
+function buildRequestFields(route, httpMethod, routeFile) {
+  const mem = route.member;
+  const params = src.parseParams(mem.paramsText || "");
+  let body = {};
+  let query = {};
+  let usesWholeBodyVar = null;
+  let wholeBodyDeclared = false;
+
+  params.forEach(function (p) {
+    p.decorators.forEach(function (d) {
+      if (d.name !== "Body" && d.name !== "Query") return;
+      const target = d.name === "Body" ? body : query;
+      const first = (splitStaticEntries(d.argsText) || [])[0] || "";
+      const lit = /^(['"`])([^'"`]+)\1$/.exec(first);
+      if (lit) {
+        // single field: @Body("email") email: string
+        const s = p.typeText
+          ? src.typeToSchema(p.typeText, route.file)
+          : { type: "string" };
+        target[lit[2]] = s && s.type !== "unknown" ? s : { type: "string" };
+        return;
+      }
+      // whole object: @Body() dto: CreateUserDto  /  @Query() q: { a?: string }
+      const s = p.typeText ? src.typeToSchema(p.typeText, route.file) : null;
+      if (
+        s &&
+        s.type === "object" &&
+        s.properties &&
+        Object.keys(s.properties).length
+      ) {
+        Object.assign(target, s.properties);
+        if (d.name === "Body") wholeBodyDeclared = true;
+      } else if (d.name === "Body" && p.name) {
+        usesWholeBodyVar = p.name;
+      }
+    });
+  });
+
+  const code = mem.bodyText || "";
+  // Body not described by a type: read how the code uses it (req.body.x, or the @Body variable)
+  if (Object.keys(body).length === 0) {
+    let usage = code;
+    if (usesWholeBodyVar) {
+      const v = usesWholeBodyVar.replace(/\$/g, "\\$");
+      usage = usage
+        .replace(new RegExp("=\\s*" + v + "\\b", "g"), "= req.body")
+        .replace(new RegExp("\\b" + v + "\\b(?=\\s*\\??\\.)", "g"), "body");
+    }
+    const f = extractBodyFieldsFromFile(usage);
+    if (f) body = f.properties;
+  }
+  if (Object.keys(query).length === 0) {
+    const f = extractQueryFieldsFromFile(code);
+    if (f) query = f.properties;
+  }
+
+  const bodyObj = Object.keys(body).length
+    ? { type: "object", properties: body }
+    : null;
+  const queryObj = Object.keys(query).length
+    ? { type: "object", properties: query }
+    : null;
+  return { body: bodyObj, query: queryObj };
+}
+
+// Upload fields from the interceptors written on the method
+function buildMultipart(route) {
+  const mem = route.member;
+  const text =
+    mem.decorators
+      .map(function (d) {
+        return "@" + d.name + "(" + d.argsText + ")";
+      })
+      .join("\n") +
+    "\n" +
+    (mem.paramsText || "") +
+    "\n" +
+    (mem.bodyText || "");
+  let mp = extractMultipartFieldsFromFile(text);
+  if (mp) {
+    // FilesInterceptor("photos") takes several files in one field
+    for (const m of text.matchAll(
+      /\bFilesInterceptor\s*\(\s*['"`]([^'"`]+)['"`]/g,
+    )) {
+      if (mp.properties[m[1]])
+        mp.properties[m[1]] = {
+          type: "array",
+          items: { type: "string", format: "binary" },
+        };
+    }
+    for (const block of text.matchAll(
+      /\bFileFieldsInterceptor\s*\(\s*\[([\s\S]*?)\]\s*\)/g,
+    )) {
+      for (const n of block[1].matchAll(
+        /\{\s*name\s*:\s*['"`]([^'"`]+)['"`]\s*,\s*maxCount\s*:\s*(\d+)/g,
+      )) {
+        if (Number(n[2]) > 1 && mp.properties[n[1]])
+          mp.properties[n[1]] = {
+            type: "array",
+            items: { type: "string", format: "binary" },
+          };
+      }
+    }
+  } else if (/\bAnyFilesInterceptor\s*\(/.test(text)) {
+    // any field name is accepted, so only the upload type can be known
+    mp = {
+      type: "object",
+      properties: {},
+      "x-content-type": "multipart/form-data",
+    };
+  }
+  return mp;
+}
+
+// First "return { ... }" / "return [ ... ]" that is not inside a nested function
+function findTopLevelReturn(code) {
+  let depth = 0;
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const e = require("./text-utils").skipStaticString(code, i, code.length);
+      if (e === -1) return null;
+      i = e;
+      continue;
+    }
+    if (ch === "{" || ch === "(" || ch === "[") depth++;
+    else if (ch === "}" || ch === ")" || ch === "]") depth--;
+    else if (
+      depth === 0 &&
+      ch === "r" &&
+      /^return\b/.test(code.slice(i, i + 7)) &&
+      !/[\w$.]/.test(code[i - 1] || " ")
+    ) {
+      const rest = code.slice(i + 6);
+      const m = /^\s*([{\[])/.exec(rest);
+      if (m) {
+        const open = i + 6 + m[0].length - 1;
+        if (m[1] === "{") {
+          const close = findStaticClosingBrace(code, open);
+          if (close !== null)
+            return parseStaticObjectFields(code.slice(open + 1, close));
+        } else {
+          const close = src.matchClose(code, open);
+          if (close !== -1) {
+            const first = (splitStaticEntries(code.slice(open + 1, close)) ||
+              [])[0];
+            if (first && first.charAt(0) === "{") {
+              const item = parseStaticObjectFields(
+                first.slice(1, first.lastIndexOf("}")),
+              );
+              if (item) {
+                delete item._source;
+                return { type: "array", items: item, _source: "static" };
+              }
+            } else if (first) {
+              return {
+                type: "array",
+                items: guessStaticValueType(first),
+                _source: "static",
+              };
+            }
+            return {
+              type: "array",
+              items: { type: "unknown" },
+              _source: "static",
+            };
+          }
+        }
+      }
+      return null;
+    }
+  }
+  return null;
+}
+
+// Best-effort reply shape: declared return type, then a literal return, then res.json(...)
+function buildResponse(route) {
+  const mem = route.member;
+  const names = route.member.decorators.map(function (d) {
+    return d.name;
+  });
+  if (names.indexOf("Redirect") !== -1 || names.indexOf("Sse") !== -1)
+    return null;
+  const hc = mem.decorators.find(function (d) {
+    return d.name === "HttpCode";
+  });
+  if (hc && /^\s*204\b/.test(hc.argsText)) return null;
+
+  if (mem.returnType) {
+    const s = src.typeToSchema(mem.returnType, route.file);
+    if (schemaIsUseful(s)) return Object.assign({}, s, { _source: "static" });
+  }
+  const lit = findTopLevelReturn(mem.bodyText || "");
+  if (lit) return lit;
+  return extractResponseFieldsFromSegment(mem.bodyText || "");
+}
+
+function scanNestJsRoutes(cwd) {
+  const endpoints = [];
+  const seen = new Set();
+  src.setProjectRoot(cwd);
+
+  const files = listSourceFiles(cwd);
+  const settings = readAppSettings(files);
+  const routing = readModuleRouting(files);
+
+  for (const file of files) {
+    const c = src.readSource(file);
+    if (!c || c.indexOf("@Controller") === -1) continue;
+    try {
+      const classes = src.findClasses(c);
+      classes.forEach(function (cls, idx) {
+        // The @Controller(...) written just above this class
+        const regionStart = idx > 0 ? classes[idx - 1].close : 0;
+        const region = c.slice(regionStart, cls.kwIdx);
+        const dm = /@Controller\b(?!\w)\s*(\()?/g;
+        let last = null;
+        let mm;
+        while ((mm = dm.exec(region)) !== null) last = mm;
+        if (!last) return;
+        const absIdx = regionStart + last.index;
+        let argsText = "";
+        if (last[1]) {
+          const call = sliceCallText(c, absIdx);
+          if (!call) return;
+          argsText = call.slice(call.indexOf("(") + 1, call.length - 1);
+        }
+
+        // Controller path (+ version) from: nothing, "text", ["a","b"], CONSTANT, or { path, version }
+        const firstArg = (splitStaticEntries(argsText) || [])[0] || "";
+        let pathArg = firstArg;
+        let ctrlVersionText;
+        if (firstArg.charAt(0) === "{") {
+          const obj = readObjectEntries(firstArg) || {};
+          pathArg = obj.path || "";
+          ctrlVersionText = obj.version;
+        }
+        const ctrlPaths = resolvePathList(pathArg, file);
+        if (ctrlPaths === null) {
+          return;
+        }
+        const ctrlVersions = resolveVersions(ctrlVersionText, file);
+        const modName = routing.controllerModule[cls.name];
+        const modPrefix =
+          modName && routing.modulePath[modName]
+            ? routing.modulePath[modName]
+            : "";
+
+        const routes = collectRoutes(file, cls, 0);
+
+        routes.forEach(function (route) {
+          route.http.forEach(function (dec) {
+            const httpMethod = HTTP_DECORATORS[dec.name];
+            const arg0 = (splitStaticEntries(dec.argsText) || [])[0] || "";
+            const methodPaths =
+              dec.name === "Sse" || arg0.charAt(0) !== "{"
+                ? resolvePathList(arg0, route.file)
+                : [""];
+            if (methodPaths === null) {
+              return;
+            }
+            // Version: method @Version wins over the controller's, then the app default
+            const vDec = route.member.decorators.find(function (d) {
+              return d.name === "Version";
+            });
+            let versions = vDec
+              ? resolveVersions(vDec.argsText, route.file)
+              : ctrlVersions;
+            if (versions === undefined) versions = null;
+            if (versions === null) versions = settings.defaultVersions || [];
+            const versionSegs = settings.versioningUri
+              ? (versions.length ? versions : [null]).map(function (v) {
+                  return v === null ? "" : settings.versionPrefix + v;
+                })
+              : [""];
+
+            const fields = buildRequestFields(route, httpMethod);
+            const multipart =
+              httpMethod === "GET" ? null : buildMultipart(route);
+            const response = buildResponse(route);
+
+            ctrlPaths.forEach(function (ctrlPath) {
+              methodPaths.forEach(function (methodPath) {
+                versionSegs.forEach(function (vSeg) {
+                  const unprefixed = joinParts([
+                    vSeg,
+                    modPrefix,
+                    ctrlPath,
+                    methodPath,
+                  ]);
+                  const excluded =
+                    settings.exclude.indexOf(unprefixed.replace(/^\//, "")) !==
+                    -1;
+                  const fullPath = joinParts([
+                    excluded ? "" : settings.prefix,
+                    vSeg,
+                    modPrefix,
+                    ctrlPath,
+                    methodPath,
+                  ]);
+                  const key = httpMethod + ":" + fullPath;
+                  if (seen.has(key)) {
+                    return;
+                  }
+                  seen.add(key);
+
+                  const needsBody =
+                    ["POST", "PUT", "PATCH"].indexOf(httpMethod) !== -1;
+                  let requestBody = null;
+                  if (needsBody)
+                    requestBody = mergeBodyWithMultipart(
+                      fields.body,
+                      multipart,
+                    );
+                  else if (httpMethod === "GET" || httpMethod === "DELETE")
+                    requestBody = removePathParamFields(fields.query, fullPath);
+                  else requestBody = fields.body;
+                  endpoints.push({
+                    method: httpMethod,
+                    path: fullPath,
+                    description: "",
+                    requestBody: requestBody,
+                    responseBody: response,
+                    routeParamMap: buildRouteParamMap(fullPath, []),
+                    detectedBy: "static-scan-nestjs",
+                  });
+                });
+              });
+            });
+          });
+        });
+      });
+    } catch (e) {}
+  }
+  return endpoints;
+}
+
+module.exports = {
+  scanNestJsRoutes,
+};