botversion-sdk 2.2.3 → 2.3.0

package/scanner-sdk/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "botversion-sdk",
+  "version": "2.2.3",
+  "description": "BotVersion SDK — auto-detect and register your API endpoints",
+  "main": "index.js",
+  "bin": {
+    "botversion-scan-frontend-routes": "bin/scan-frontend.js",
+    "botversion-scan-endpoints": "bin/scan-backend.js"
+  },
+  "keywords": [
+    "botversion",
+    "sdk",
+    "ai",
+    "agent",
+    "api"
+  ],
+  "author": "Saurav Dhakal",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.29.3",
+    "@babel/traverse": "^7.29.0",
+    "dotenv": "^16.4.5",
+    "express": "^4.18.2"
+  }
+}

package/scanner-sdk/scan/adonis.js

@@ -0,0 +1,177 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/adonis.js
+// PURPOSE: Finds API routes in AdonisJS projects (Route.get / router.post ..., group prefixes, resource routes, controller methods).
+// CONTAINS: scanAdonisRoutes
+// USED BY: scanner.js (scanAdonisRoutes)
+// DEPENDS ON: ./route-calls, ./nest-source, ./text-utils
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const rc = require("./route-calls");
+const src = require("./nest-source");
+const { joinMountPath, sliceCallText } = require("./text-utils");
+
+const TAG = "ADONIS-DEBUG";
+const ROUTER = /^(?:Route|router|route|Router|server\.router|app\.router)$/;
+
+// Text of the method chain written right after a call: .prefix("/api").middleware("auth")
+function chainAfter(c, end) {
+  const m = /^(?:\s*\.\s*[A-Za-z_$][\w$]*\s*\((?:[^()]|\([^()]*\))*\))+/.exec(
+    c.slice(end),
+  );
+  return m ? m[0] : "";
+}
+
+function singular(name) {
+  return name.replace(/ies$/, "y").replace(/s$/, "");
+}
+
+const RESOURCE_ACTIONS = [
+  { name: "index", method: "GET", suffix: "" },
+  { name: "create", method: "GET", suffix: "/create" },
+  { name: "store", method: "POST", suffix: "" },
+  { name: "show", method: "GET", suffix: "/:id" },
+  { name: "edit", method: "GET", suffix: "/:id/edit" },
+  { name: "update", method: "PUT", suffix: "/:id" },
+  { name: "update", method: "PATCH", suffix: "/:id" },
+  { name: "destroy", method: "DELETE", suffix: "/:id" },
+];
+
+function scanAdonisRoutes(cwd) {
+  const endpoints = [];
+  const seen = new Set();
+  src.setProjectRoot(cwd);
+  const files = rc.listSourceFiles(cwd, TAG);
+
+  // controller class name -> file (so "UsersController.index" can be read)
+  const classIndex = {};
+  files.forEach(function (f) {
+    const c = src.readSource(f);
+    if (c && /class\s/.test(c))
+      src.findClasses(c).forEach(function (k) {
+        if (!classIndex[k.name]) classIndex[k.name] = { file: f };
+      });
+  });
+
+  files.forEach(function (file) {
+    const c = src.readSource(file);
+    if (
+      !c ||
+      !(
+        c.indexOf("@adonisjs") !== -1 ||
+        /\b(?:Route|router)\s*\.\s*(?:get|post|put|patch|delete|group|resource)\b/.test(
+          c,
+        )
+      )
+    )
+      return;
+
+    const ranges = [];
+    for (const m of c.matchAll(/\.\s*group\s*\(/g)) {
+      const call = sliceCallText(c, m.index + m[0].length - 1);
+      if (!call) continue;
+      const end = m.index + m[0].length - 1 + call.length;
+      const pm = /\.\s*prefix\s*\(\s*(['"`][^'"`]*['"`])\s*\)/.exec(
+        chainAfter(c, end),
+      );
+      const prefix = pm ? src.resolveStringExpr(pm[1], file) : "";
+      ranges.push({
+        start: m.index,
+        end: end,
+        prefix: prefix === null ? "" : prefix,
+      });
+    }
+
+    function add(method, rawPath, index, code, how) {
+      if (rawPath.indexOf("*") !== -1) return;
+      const fullPath = joinMountPath(rc.rangePrefixAt(ranges, index), rawPath);
+      const key = method + ":" + fullPath;
+      if (seen.has(key)) {
+        return;
+      }
+      seen.add(key);
+      const ep = rc.buildEndpoint(method, fullPath, code, "static-scan-adonis");
+      endpoints.push(ep);
+    }
+
+    rc.verbCalls(c, file, TAG, { allowStringHandlers: true }).forEach(
+      function (call) {
+        if (!ROUTER.test(call.receiver)) return;
+        const code = rc.handlerCode(
+          call.args.slice(call.pathIdx + 1),
+          c,
+          file,
+          classIndex,
+        );
+        call.paths.forEach(function (p) {
+          add(
+            call.method,
+            p,
+            call.index,
+            code,
+            call.receiver + "." + call.method.toLowerCase(),
+          );
+        });
+      },
+    );
+
+    // Route.resource("users", "UsersController").apiOnly()
+    for (const m of c.matchAll(/\b(?:Route|router)\s*\.\s*resource\s*\(/g)) {
+      const call = sliceCallText(c, m.index + m[0].length - 1);
+      if (!call) continue;
+      const args = src.splitTopLevel(call.slice(1, -1)) || [];
+      const name = args[0] ? src.resolveStringExpr(args[0], file) : null;
+      if (!name) continue;
+      const chain = chainAfter(c, m.index + m[0].length - 1 + call.length);
+      const apiOnly = /\.\s*apiOnly\s*\(/.test(chain);
+      const only = /\.\s*only\s*\(\s*\[([^\]]*)\]/.exec(chain);
+      const except = /\.\s*except\s*\(\s*\[([^\]]*)\]/.exec(chain);
+      const names = function (t) {
+        return (t[1].match(/['"`]([^'"`]+)['"`]/g) || []).map(function (x) {
+          return x.slice(1, -1);
+        });
+      };
+      const parts = name.split(".");
+      let base = "";
+      parts.forEach(function (part, i) {
+        base +=
+          "/" +
+          part +
+          (i < parts.length - 1 ? "/:" + singular(part) + "_id" : "");
+      });
+      const controllerName = /^['"`]([^'"`]+)['"`]$/.test(
+        (args[1] || "").trim(),
+      )
+        ? args[1].trim().slice(1, -1)
+        : (args[1] || "").trim();
+      RESOURCE_ACTIONS.forEach(function (a) {
+        if (apiOnly && (a.name === "create" || a.name === "edit")) return;
+        if (only && names(only).indexOf(a.name) === -1) return;
+        if (except && names(except).indexOf(a.name) !== -1) return;
+        const hit =
+          classIndex[controllerName.split(".").pop().split("/").pop()];
+        const c2 = hit ? src.readSource(hit.file) : null;
+        const code = c2
+          ? rc.handlerCode(
+              ["'" + controllerName + "." + a.name + "'"],
+              c,
+              file,
+              classIndex,
+            )
+          : "";
+        add(
+          a.method,
+          base + a.suffix,
+          m.index,
+          code,
+          "resource(" + name + ")." + a.name,
+        );
+      });
+    }
+  });
+  return endpoints;
+}
+
+module.exports = {
+  scanAdonisRoutes,
+};

package/scanner-sdk/scan/express-files.js

@@ -0,0 +1,326 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/express-files.js
+// PURPOSE: Express helpers: finds the Express files in a project, works out mount prefixes, builds the handler-name -> body-fields map.
+// CONTAINS: buildMountPrefixMap, scanAllExpressFiles, buildBodyMap
+// USED BY: scan/express.js, scan/fastify.js
+// DEPENDS ON: ./text-utils, ./field-extractors
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const {
+  blankOutComments,
+  joinMountPath,
+  sliceCallText,
+  splitStaticEntries,
+} = require("./text-utils");
+const { extractBodyFieldsFromFile } = require("./field-extractors");
+
+// Works out which URL prefix(es) each router file is mounted under, by reading
+// X.use("/prefix", router) calls across files. Files nobody mounts get "" (no prefix).
+function buildMountPrefixMap(files) {
+  const fs = require("fs");
+  const path = require("path");
+  const known = {};
+  files.forEach(function (f) {
+    known[path.resolve(f)] = f;
+  });
+  const incoming = {};
+
+  function resolveLocal(fromFile, rel) {
+    if (!/^\.{1,2}([\\/]|$)/.test(rel)) return null;
+    const base = path.resolve(path.dirname(fromFile), rel);
+    const tries = [
+      base,
+      base + ".js",
+      base + ".ts",
+      path.join(base, "index.js"),
+      path.join(base, "index.ts"),
+    ];
+    for (const t of tries) {
+      if (known[t]) return known[t];
+    }
+    return null;
+  }
+
+  files.forEach(function (file) {
+    let content;
+    try {
+      content = blankOutComments(fs.readFileSync(file, "utf8"));
+    } catch (e) {
+      return;
+    }
+
+    const bindings = {};
+    for (const m of content.matchAll(
+      /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\(\s*['"]([^'"]+)['"]\s*\)/g,
+    )) {
+      bindings[m[1]] = m[2];
+    }
+    for (const m of content.matchAll(
+      /import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+)['"]/g,
+    )) {
+      bindings[m[1]] = m[2];
+    }
+
+    for (const call of content.matchAll(
+      /\b[A-Za-z_$][\w$]*\s*\.\s*use\s*\(/g,
+    )) {
+      const text = sliceCallText(content, call.index);
+      if (!text) continue;
+      const args = splitStaticEntries(
+        text.slice(text.indexOf("(") + 1, text.length - 1),
+      );
+      if (!args || args.length === 0) continue;
+      let prefix = "";
+      let handlers = args;
+      const lit = /^(['"`])([^'"`$]*)\1$/.exec(args[0]);
+      if (lit) {
+        prefix = lit[2];
+        handlers = args.slice(1);
+      }
+      handlers.forEach(function (arg) {
+        let rel = null;
+        const inline = /^require\(\s*['"]([^'"]+)['"]\s*\)$/.exec(arg);
+        if (inline) rel = inline[1];
+        else if (/^[A-Za-z_$][\w$]*$/.test(arg) && bindings[arg])
+          rel = bindings[arg];
+        if (!rel) return;
+        const child = resolveLocal(file, rel);
+        if (!child || child === file) return;
+        (incoming[child] = incoming[child] || []).push({
+          parent: file,
+          prefix: prefix,
+        });
+      });
+    }
+  });
+
+  function prefixesOf(file, trail) {
+    const ins = incoming[file];
+    if (!ins || ins.length === 0) return [""];
+    const out = [];
+    ins.forEach(function (e) {
+      if (trail.indexOf(e.parent) !== -1) return;
+      prefixesOf(e.parent, trail.concat(file)).forEach(function (pp) {
+        const full = e.prefix ? joinMountPath(pp, e.prefix) : pp;
+        if (out.indexOf(full) === -1) out.push(full);
+      });
+    });
+    return out.length ? out : [""];
+  }
+
+  const result = {};
+  files.forEach(function (f) {
+    result[f] = prefixesOf(f, []);
+  });
+  return result;
+}
+
+// Prefix of routers that are created AND mounted in the same file: const r = express.Router(); app.use("/api", r)
+function buildLocalMountMap(content) {
+  const routers = new Set();
+  for (const m of content.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:[A-Za-z_$][\w$]*\s*\.\s*)?Router\s*\(/g,
+  ))
+    routers.add(m[1]);
+  const parentOf = {};
+  for (const call of content.matchAll(
+    /\b([A-Za-z_$][\w$]*)\s*\.\s*use\s*\(/g,
+  )) {
+    const text = sliceCallText(content, call.index);
+    if (!text) continue;
+    const args = splitStaticEntries(
+      text.slice(text.indexOf("(") + 1, text.length - 1),
+    );
+    if (!args || args.length < 2) continue;
+    const lit = /^(['"`])([^'"`$]*)\1$/.exec(args[0]);
+    if (!lit) continue;
+    args.slice(1).forEach(function (a) {
+      if (routers.has(a) && a !== call[1])
+        parentOf[a] = { parent: call[1], prefix: lit[2] };
+    });
+  }
+  const result = {};
+  function prefixOf(name, trail) {
+    const p = parentOf[name];
+    if (!p || trail.indexOf(name) !== -1) return "";
+    return joinMountPath(prefixOf(p.parent, trail.concat(name)), p.prefix);
+  }
+  Object.keys(parentOf).forEach(function (n) {
+    result[n] = prefixOf(n, []);
+  });
+  return result;
+}
+
+function scanAllExpressFiles(cwd) {
+  const fs = require("fs");
+  const path = require("path");
+
+  const SKIP_DIRS = [
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".cache",
+    "coverage",
+    "out",
+    "tests",
+    "test",
+    "__tests__",
+    "__mocks__",
+  ];
+
+  const routeFiles = [];
+
+  function walk(dir, depth) {
+    if (depth > 12) {
+      return;
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRS.includes(entry)) continue;
+
+      const fullPath = path.join(dir, entry);
+      let stat;
+      try {
+        stat = fs.statSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        walk(fullPath, depth + 1);
+      } else if (
+        /\.(js|ts)$/.test(entry) &&
+        !/\.(test|spec)\.(js|ts)$/i.test(entry)
+      ) {
+        try {
+          const content = fs.readFileSync(fullPath, "utf8");
+          // Check if file contains Express route definitions
+          const isExpressFile =
+            content.includes("express()") ||
+            content.includes("express.Router()") ||
+            content.includes("Router()") ||
+            // Match only route-like patterns: app.get('/...) or router.post('/...)
+            /(?:app|router|server)\.(get|post|put|delete|patch|all)\s*\(\s*['"`]\//.test(
+              content,
+            );
+
+          if (isExpressFile) {
+            routeFiles.push(fullPath);
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+
+  walk(cwd, 0);
+  return routeFiles;
+}
+
+function buildBodyMap(cwd) {
+  const fs = require("fs");
+  const path = require("path");
+  const bodyMap = {}; // { functionName: { type: "object", properties: {...} } }
+
+  const SKIP_DIRS = [
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".cache",
+    "coverage",
+    "out",
+  ];
+
+  function walk(dir, depth) {
+    if (depth > 12) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRS.includes(entry)) continue;
+      const fullPath = path.join(dir, entry);
+      let stat;
+      try {
+        stat = fs.statSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        walk(fullPath, depth + 1);
+        continue;
+      }
+
+      if (!/\.(js|ts)$/.test(entry)) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(fullPath, "utf8");
+      } catch {
+        continue;
+      }
+
+      // Skip files with no req.body at all
+      // Split file into individual function chunks more reliably
+      // by finding each function and extracting a reasonable chunk after it
+
+      const fnPatterns = [
+        // function loginUser(req, res) {
+        /(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\([^)]*\)\s*\{/g,
+        // const loginUser = async (req, res) => {
+        /const\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{/g,
+        // exports.loginUser = async (req, res) => {
+        /exports\.([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{/g,
+        // export const loginUser = async (req, res) => {
+        /export\s+const\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{/g,
+      ];
+
+      // Map every function name in this file to the whole file's body fields.
+      // Brace-counting is unreliable across JS/TS variations, so we use
+      // file-level field extraction here. Per-function accuracy is handled
+      // at runtime by Strategy 2 (fn.toString()) in extractRoutes.
+      const fileFields = extractBodyFieldsFromFile(content);
+      if (fileFields) {
+        const fnNames = new Set();
+        for (const pattern of fnPatterns) {
+          pattern.lastIndex = 0; // reset regex state before each use
+          let m;
+          while ((m = pattern.exec(content)) !== null) fnNames.add(m[1]);
+        }
+        for (const name of fnNames) {
+          if (!bodyMap[name]) {
+            // don't overwrite a more precise entry
+            bodyMap[name] = fileFields;
+          }
+        }
+      }
+    }
+  }
+
+  walk(cwd, 0);
+  return bodyMap;
+}
+
+module.exports = {
+  buildLocalMountMap,
+  buildMountPrefixMap,
+  scanAllExpressFiles,
+  buildBodyMap,
+};