botversion-sdk 2.2.2 → 2.3.0

package/scanner-sdk/scan/remix-routes.js

@@ -0,0 +1,261 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/remix-routes.js
+// PURPOSE: Finds the route files of a Remix project and works out each file's URL (flat-file v2 rules, nested-folder v1 rules, custom routes from vite/remix config).
+// CONTAINS: isRemixProject, collectRemixRouteFiles
+// USED BY: scan/remix.js (API routes), scan/frontend.js (pages)
+// DEPENDS ON: ./text-utils
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { blankOutComments } = require("./text-utils");
+
+const ROUTE_EXT = /\.(?:js|jsx|ts|tsx|mjs|mts)$/;
+const NON_ROUTE_FILE = /\.(?:test|spec|stories)\.[jt]sx?$|\.d\.ts$/;
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "__tests__",
+  "__mocks__",
+  "__snapshots__",
+]);
+const FOLDER_MODULE = /^(?:route|index)\.(?:js|jsx|ts|tsx|mjs|mts)$/;
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return null;
+  }
+}
+
+function listDir(dir) {
+  try {
+    return fs.readdirSync(dir);
+  } catch (e) {
+    return [];
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch (e) {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+function readDeps(cwd) {
+  try {
+    const pkg = JSON.parse(readText(path.join(cwd, "package.json")) || "{}");
+    return Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+  } catch (e) {
+    return {};
+  }
+}
+
+// A Remix project lists @remix-run packages, or has app/root.* next to app/routes
+function isRemixProject(cwd) {
+  const deps = readDeps(cwd);
+  if (
+    Object.keys(deps).some(function (d) {
+      return d.indexOf("@remix-run/") === 0;
+    })
+  )
+    return true;
+  const appDir = path.join(cwd, "app");
+  const hasRoot = ["root.tsx", "root.jsx", "root.ts", "root.js"].some(
+    function (f) {
+      return isFile(path.join(appDir, f));
+    },
+  );
+  return hasRoot && isDir(path.join(appDir, "routes"));
+}
+
+// Remix 1.x projects use nested folders unless they opted in to the v2 flat-file convention
+function routingMode(cwd) {
+  const deps = readDeps(cwd);
+  const ver =
+    deps["@remix-run/dev"] ||
+    deps["@remix-run/react"] ||
+    deps["@remix-run/node"] ||
+    "";
+  const major = /(\d+)/.exec(String(ver));
+  if (major && major[1] === "1") {
+    const cfg = ["remix.config.js", "remix.config.mjs", "remix.config.cjs"]
+      .map(function (f) {
+        return readText(path.join(cwd, f)) || "";
+      })
+      .join("\n");
+    if (!/v2_routeConvention/.test(cfg)) return "v1";
+  }
+  return "v2";
+}
+
+// "projects.$id.edit" -> ["projects", "$id", "edit"]; dots inside [ ] are literal
+function splitFlatName(name) {
+  const parts = [];
+  let cur = "";
+  let depth = 0;
+  for (const ch of name) {
+    if (ch === "[") depth++;
+    else if (ch === "]") depth = Math.max(0, depth - 1);
+    if (ch === "." && depth === 0) {
+      parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+// One flat-file name part -> URL part ("" means it adds nothing to the URL)
+function convertFlatSegment(raw) {
+  let seg = raw;
+  let optional = false;
+  if (/^\(.+\)$/.test(seg)) {
+    optional = true;
+    seg = seg.slice(1, -1);
+  }
+  if (seg.charAt(0) === "_") return ""; // pathless layout or _index
+  // a trailing "_" only removes the parent nesting, the URL keeps the word
+  if (seg.length > 1 && seg.charAt(seg.length - 1) === "_")
+    seg = seg.slice(0, -1);
+  if (seg === "$") return "*"; // splat
+  if (seg.charAt(0) === "$") seg = ":" + seg.slice(1);
+  // [x] escapes: what is inside the brackets is written literally
+  seg = seg.replace(/\[([^\]]*)\]/g, function (all, inner) {
+    return inner;
+  });
+  return optional ? seg + "?" : seg;
+}
+
+function convertV1Segment(seg) {
+  if (seg.indexOf("__") === 0) return ""; // pathless layout
+  if (seg === "$") return "*";
+  if (seg.charAt(0) === "$") return ":" + seg.slice(1);
+  return seg;
+}
+
+function addFlat(out, file, routeId) {
+  const parts = splitFlatName(routeId);
+  const last = parts[parts.length - 1] || "";
+  out.push({
+    file: file,
+    routePath: "/" + parts.map(convertFlatSegment).filter(Boolean).join("/"),
+    // a last part starting with "_" (other than _index) is a layout with no URL of its own
+    pathless: last.charAt(0) === "_" && last !== "_index",
+  });
+}
+
+function collectFlat(dir) {
+  const out = [];
+  listDir(dir).forEach(function (name) {
+    if (name.charAt(0) === ".") return;
+    const full = path.join(dir, name);
+    if (isDir(full)) {
+      if (SKIP_DIRS.has(name)) return;
+      // Remix reads a first-level folder only through its route.* / index.* file; deeper folders and sibling files are ignored
+      const moduleFile = listDir(full).find(function (f) {
+        return FOLDER_MODULE.test(f);
+      });
+      if (moduleFile) addFlat(out, path.join(full, moduleFile), name);
+      return;
+    }
+    if (!ROUTE_EXT.test(name) || NON_ROUTE_FILE.test(name)) return;
+    addFlat(out, full, name.replace(ROUTE_EXT, ""));
+  });
+  return out;
+}
+
+function collectV1(dir, prefix) {
+  let out = [];
+  listDir(dir).forEach(function (name) {
+    if (name.charAt(0) === ".") return;
+    const full = path.join(dir, name);
+    if (isDir(full)) {
+      if (!SKIP_DIRS.has(name))
+        out = out.concat(collectV1(full, prefix.concat(name.split("."))));
+      return;
+    }
+    if (!ROUTE_EXT.test(name) || NON_ROUTE_FILE.test(name)) return;
+    const id = name.replace(ROUTE_EXT, "");
+    const parts = prefix.concat(id === "index" ? [] : id.split("."));
+    const last = parts[parts.length - 1] || "";
+    out.push({
+      file: full,
+      routePath: "/" + parts.map(convertV1Segment).filter(Boolean).join("/"),
+      pathless: last.indexOf("__") === 0,
+    });
+  });
+  return out;
+}
+
+// Routes added by hand in vite.config / remix.config: route("path", "file")
+function readCustomRoutes(cwd, appDir) {
+  const out = [];
+  [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.mts",
+    "remix.config.js",
+    "remix.config.mjs",
+    "remix.config.cjs",
+  ].forEach(function (f) {
+    const text = readText(path.join(cwd, f));
+    if (!text) return;
+    const clean = blankOutComments(text);
+    for (const m of clean.matchAll(
+      /\broute\s*\(\s*(['"`])([^'"`]*)\1\s*,\s*(['"`])([^'"`]+)\3/g,
+    )) {
+      const file = [path.resolve(appDir, m[4]), path.resolve(cwd, m[4])].find(
+        isFile,
+      );
+      if (!file) continue;
+      out.push({
+        file: file,
+        routePath: "/" + m[2].replace(/^\/+|\/+$/g, ""),
+      });
+    }
+  });
+  return out;
+}
+
+// Returns [{ file, routePath, pathless, custom? }] for every route module of the project
+function collectRemixRouteFiles(cwd) {
+  const mode = routingMode(cwd);
+  const appDir = isDir(path.join(cwd, "app")) ? path.join(cwd, "app") : cwd;
+  const byFile = new Map();
+  [path.join(cwd, "app", "routes"), path.join(cwd, "routes")].forEach(
+    function (dir) {
+      if (!isDir(dir)) return;
+      const found = mode === "v1" ? collectV1(dir, []) : collectFlat(dir);
+      found.forEach(function (r) {
+        byFile.set(r.file, r);
+      });
+    },
+  );
+  readCustomRoutes(cwd, appDir).forEach(function (r) {
+    byFile.set(r.file, {
+      file: r.file,
+      routePath: r.routePath,
+      pathless: false,
+      custom: true,
+    });
+  });
+  return Array.from(byFile.values());
+}
+
+module.exports = { isRemixProject, collectRemixRouteFiles };

package/scanner-sdk/scan/remix.js

@@ -0,0 +1,348 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/remix.js
+// PURPOSE: Finds Remix server routes (loader = GET, action = POST/PUT/DELETE/PATCH) with their body, query and reply fields.
+// CONTAINS: scanRemixServerRoutes
+// USED BY: scanner.js (scanRemixServerRoutes)
+// DEPENDS ON: ./field-extractors, ./text-utils, ./route-segments, ./route-calls, ./remix-routes, ./nest-source
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  extractMultipartFieldsFromFile,
+  mergeBodyWithMultipart,
+  findNamedHandlerCode,
+  extractSchemaBodyFields,
+} = require("./field-extractors");
+const {
+  buildRouteParamMap,
+  removePathParamFields,
+  blankOutComments,
+  splitStaticEntries,
+  findStaticClosingBrace,
+} = require("./text-utils");
+const { detectMethodsFromText, getMethodSegment } = require("./route-segments");
+const { collectRemixRouteFiles } = require("./remix-routes");
+const rc = require("./route-calls");
+const src = require("./nest-source");
+
+const MODULE_EXTS = [
+  "",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".mts",
+  "/index.ts",
+  "/index.tsx",
+  "/index.js",
+  "/index.jsx",
+];
+let aliasCache = {};
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+// Import aliases from tsconfig/jsconfig "paths", e.g. "~/*": ["./app/*"]
+function aliasTargets(cwd) {
+  if (aliasCache[cwd]) return aliasCache[cwd];
+  const out = [];
+  ["tsconfig.json", "jsconfig.json"].forEach(function (f) {
+    try {
+      const raw = fs.readFileSync(path.join(cwd, f), "utf8");
+      const json = JSON.parse(
+        blankOutComments(raw).replace(/,(\s*[}\]])/g, "$1"),
+      );
+      const opts = json.compilerOptions || {};
+      const baseDir = path.resolve(cwd, opts.baseUrl || ".");
+      const paths = opts.paths || {};
+      Object.keys(paths).forEach(function (key) {
+        const target = (paths[key] || [])[0];
+        if (!target || key.slice(-1) !== "*" || target.slice(-1) !== "*")
+          return;
+        out.push({
+          prefix: key.slice(0, -1),
+          dir: path.resolve(baseDir, target.slice(0, -1)),
+        });
+      });
+    } catch (e) {}
+  });
+  aliasCache[cwd] = out;
+  return out;
+}
+
+// Turns an import path into a project file: relative paths, tsconfig aliases, and the common "~/" and "@/" roots
+function resolveModule(fromFile, spec, cwd) {
+  const bases = [];
+  if (/^\.{1,2}([\\/]|$)/.test(spec)) {
+    bases.push(path.resolve(path.dirname(fromFile), spec));
+  } else {
+    aliasTargets(cwd).forEach(function (a) {
+      if (a.prefix && spec.indexOf(a.prefix) === 0)
+        bases.push(path.resolve(a.dir, spec.slice(a.prefix.length)));
+    });
+    const m = /^(?:~|@|~~|@@)\/(.*)$/.exec(spec);
+    if (m)
+      ["app", "src", ""].forEach(function (d) {
+        bases.push(path.resolve(cwd, d, m[1]));
+      });
+  }
+  for (const base of bases) {
+    for (const ext of MODULE_EXTS) {
+      if (isFile(base + ext)) return base + ext;
+    }
+  }
+  return null;
+}
+
+// How a route file exports "loader"/"action": directly, through a list, or re-exported from another file
+function findHandlerExport(content, name) {
+  const direct = new RegExp(
+    "export\\s+(?:async\\s+)?function\\s+" +
+      name +
+      "\\b|export\\s+(?:const|let|var)\\s+" +
+      name +
+      "\\b",
+  );
+  if (direct.test(content)) return { kind: "direct" };
+  for (const m of content.matchAll(
+    /export\s*\{([^}]*)\}\s*(?:from\s*['"]([^'"]+)['"])?/g,
+  )) {
+    for (const piece of m[1].split(",")) {
+      const parts = piece.trim().split(/\s+as\s+/);
+      const local = parts[0].trim();
+      const exported = (parts[1] || parts[0]).trim();
+      if (exported === name && /^[A-Za-z_$][\w$]*$/.test(local))
+        return { kind: m[2] ? "reexport" : "list", local: local, from: m[2] };
+    }
+  }
+  return null;
+}
+
+// Finds the code that really runs for "loader"/"action": follows re-exports and wrapper calls like withAuth(handler)
+function resolveHandler(content, file, name, cwd) {
+  const exp = findHandlerExport(content, name);
+  if (!exp) return null;
+  let text = content;
+  let textFile = file;
+  let localName = name;
+  if (exp.kind === "reexport") {
+    const target = resolveModule(file, exp.from, cwd);
+    const targetText = target ? src.readSource(target) : null;
+    // an unreadable re-export is reported without fields instead of guessing from this file
+    if (!targetText) return { code: "", file: file, text: content };
+    text = targetText;
+    textFile = target;
+    localName = exp.local;
+  } else if (exp.kind === "list") {
+    localName = exp.local;
+  }
+  let code = findNamedHandlerCode(text, localName);
+  if (!code) code = exp.kind === "direct" ? text : "";
+  const wrapped =
+    /=\s*(?:[A-Za-z_$][\w$.]*\s*\(\s*)+([A-Za-z_$][\w$]*)\s*\)+\s*;?\s*$/.exec(
+      code.trim(),
+    );
+  if (wrapped) code += "\n" + rc.handlerCode([wrapped[1]], text, textFile);
+  return { code: code, file: textFile, text: text };
+}
+
+// Project files imported by a route file (helpers, schemas), so replies and schemas defined elsewhere can be read
+function collectImports(text, file, cwd) {
+  const out = [];
+  const seen = new Set();
+  for (const m of text.matchAll(
+    /(?:from\s*|import\s*\(\s*|require\s*\(\s*)['"]([^'"]+)['"]/g,
+  )) {
+    if (out.length >= 25) break;
+    const target = resolveModule(file, m[1], cwd);
+    if (!target || seen.has(target)) continue;
+    seen.add(target);
+    const t = src.readSource(target);
+    if (t) out.push({ file: target, text: t });
+  }
+  return out;
+}
+
+// Body fields listed by a validation schema declared in the route file or in an imported file
+function schemaBody(code, handler, imports) {
+  const own = extractSchemaBodyFields(code, handler.text, handler.file);
+  if (own) return own;
+  for (const imp of imports) {
+    const found = extractSchemaBodyFields(code, imp.text, imp.file);
+    if (found) return found;
+  }
+  return null;
+}
+
+// Field types written in a TypeScript interface / type alias the body is cast to: (await request.json()) as Name
+function applyDeclaredTypes(body, segment, texts) {
+  try {
+    if (!body || !body.properties) return body;
+    const cast =
+      /\.json\s*\(\s*\)\s*\)?\s*(?:as|satisfies)\s+([A-Za-z_$][\w$]*)/.exec(
+        segment,
+      ) ||
+      /(?:const|let|var)\s+[\w$]+\s*:\s*([A-Za-z_$][\w$]*)\s*=\s*\(?\s*await\s+[\w$.]+\.json/.exec(
+        segment,
+      );
+    if (!cast) return body;
+    const name = cast[1].replace(/\$/g, "\\$");
+    const declRe = new RegExp(
+      "(?:interface\\s+" +
+        name +
+        "\\s*(?:extends[^{]*)?\\{|type\\s+" +
+        name +
+        "\\s*=\\s*\\{)",
+    );
+    for (const text of texts) {
+      const decl = declRe.exec(text);
+      if (!decl) continue;
+      const open = decl.index + decl[0].length - 1;
+      const close = findStaticClosingBrace(text, open);
+      if (close === null) continue;
+      const inner = blankOutComments(text.slice(open + 1, close)).replace(
+        /[;\n]+/g,
+        ",",
+      );
+      (splitStaticEntries(inner) || []).forEach(function (entry) {
+        const m =
+          /^(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:\s*([\s\S]+)$/.exec(
+            entry.trim(),
+          );
+        if (!m || !body.properties[m[1]]) return;
+        if (body.properties[m[1]].format) return; // uploaded files keep their type
+        const t = m[2].trim();
+        const el = /^(string|number|boolean)\[\]$/.exec(t);
+        if (/^(string|number|boolean)$/.test(t))
+          body.properties[m[1]] = { type: t };
+        else if (el)
+          body.properties[m[1]] = { type: "array", items: { type: el[1] } };
+        else if (/\[\]$|^Array\s*</.test(t))
+          body.properties[m[1]] = { type: "array", items: { type: "unknown" } };
+      });
+      return body;
+    }
+  } catch (e) {}
+  return body;
+}
+
+function describeHandler(h) {
+  return h
+    ? h.code
+      ? "found(" + h.code.length + ")"
+      : "code-missing"
+    : "none";
+}
+
+/**
+ * Scans Remix server routes
+ * loader = GET; action = POST/PUT/PATCH/DELETE (the methods the code checks for)
+ */
+function scanRemixServerRoutes(cwd) {
+  const endpoints = [];
+  const seen = new Set();
+  aliasCache = {};
+  src.setProjectRoot(cwd);
+
+  collectRemixRouteFiles(cwd).forEach(function (route) {
+    try {
+      if (route.pathless) return; // a pathless layout has no URL of its own
+      const content = src.readSource(route.file);
+      if (!content) return;
+      const routePath = route.routePath;
+      const loader = resolveHandler(content, route.file, "loader", cwd);
+      const action = resolveHandler(content, route.file, "action", cwd);
+      if (!loader && !action) return;
+
+      if (loader) {
+        const key = "GET:" + routePath;
+        if (!seen.has(key)) {
+          seen.add(key);
+          const imports = collectImports(loader.text, loader.file, cwd);
+          const endpoint = {
+            method: "GET",
+            path: routePath,
+            description: "",
+            requestBody: removePathParamFields(
+              rc.requestFields(loader.code).query,
+              routePath,
+            ),
+            responseBody: rc.responseShape(loader.code, {
+              sources: imports.map(function (i) {
+                return i.text;
+              }),
+            }),
+            routeParamMap: buildRouteParamMap(routePath, []),
+            detectedBy: "static-scan-remix",
+          };
+          endpoints.push(endpoint);
+        }
+      }
+
+      if (action) {
+        const imports = collectImports(action.text, action.file, cwd);
+        const sources = imports.map(function (i) {
+          return i.text;
+        });
+        const detected = detectMethodsFromText(action.code).filter(
+          function (m) {
+            return m !== "GET";
+          },
+        );
+        // an action that never checks the method runs for every non-GET method; it is listed once, as POST
+        const anyMethod = detected.length === 0;
+        const methods = anyMethod ? ["POST"] : detected;
+
+        methods.forEach(function (method) {
+          const key = method + ":" + routePath;
+          if (seen.has(key)) return;
+          seen.add(key);
+          // each method gets only its own code, so fields never leak between the methods of one action
+          const segment = anyMethod
+            ? action.code
+            : getMethodSegment(action.code, method, detected, "pages");
+          let requestBody = null;
+          let responseBody = null;
+          if (segment) {
+            const fields = rc.requestFields(segment);
+            const multipart = extractMultipartFieldsFromFile(segment);
+            const textBody =
+              fields.body ||
+              (multipart ? null : schemaBody(segment, action, imports));
+            requestBody = mergeBodyWithMultipart(textBody, multipart);
+            requestBody = applyDeclaredTypes(
+              requestBody,
+              segment,
+              [action.text].concat(sources),
+            );
+            if (!requestBody && method === "DELETE")
+              requestBody = removePathParamFields(fields.query, routePath);
+            responseBody = rc.responseShape(segment, { sources: sources });
+          }
+          endpoints.push({
+            method: method,
+            path: routePath,
+            description: "",
+            requestBody: requestBody,
+            responseBody: responseBody,
+            routeParamMap: buildRouteParamMap(routePath, []),
+            detectedBy: "static-scan-remix",
+          });
+        });
+      }
+    } catch (e) {}
+  });
+  return endpoints;
+}
+
+module.exports = {
+  scanRemixServerRoutes,
+};