botversion-sdk 2.2.3 → 2.3.0

package/scanner-sdk/scan/field-extractors.js

@@ -0,0 +1,779 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/field-extractors.js
+// PURPOSE: Finds request fields (body, query, file uploads) in handler code and guesses their types.
+// CONTAINS: inferFieldType, extractBodyFieldsFromFile, extractMultipartFieldsFromFile, mergeBodyWithMultipart, extractAppRouterBodyFields, extractQueryFieldsFromFile, findNamedHandlerCode, extractBodyFieldsForRoute, extractQueryFieldsFromHandlers
+// USED BY: scan/express.js, scan/express-files.js, scan/express-static.js, scan/nextjs.js, scan/fastify.js, scan/nestjs.js, scan/koa.js, scan/hapi.js, scan/adonis.js, scan/nuxt.js, scan/sveltekit.js, scan/remix.js
+// DEPENDS ON: ./text-utils, ./route-segments
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const {
+  findStaticClosingBrace,
+  sliceCallText,
+  splitStaticEntries,
+  readImportedFile,
+} = require("./text-utils");
+const { sliceRouteSegment } = require("./route-segments");
+
+function inferFieldType(fieldName, content) {
+  const debugHintLines = String(content)
+    .split("\n")
+    .filter(function (l) {
+      return l.indexOf(fieldName) !== -1; // TEMP-DEBUG: every line that mentions the field
+    })
+    .map(function (l) {
+      return l.trim();
+    });
+  // Treat "req.body.x" / "body?.x" the same as a bare "x" when guessing the type
+  const safeField = String(fieldName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  content = String(content).replace(
+    new RegExp(
+      "(?:(?:req|request)\\.body|(?:req|request)\\.query|body|payload|input|data|form|bodyData|reqBody|requestBody)\\s*\\??\\.\\s*" +
+        safeField +
+        "(?![\\w$])",
+      "g",
+    ),
+    function () {
+      return fieldName;
+    },
+  );
+  const arrayPatterns = [
+    new RegExp(`${fieldName}\\s*(?:\\?\\?|\\|\\|)\\s*\\[\\s*\\]`), // default empty array
+    new RegExp(
+      `${fieldName}\\s*\\.\\s*(map|filter|forEach|push|reduce|find|some|every|join|splice)\\b`,
+    ),
+    new RegExp(`Array\\.isArray\\s*\\(\\s*${fieldName}\\s*\\)`),
+    new RegExp(`for\\s*\\(.*of\\s+${fieldName}\\b`),
+    new RegExp(`\\[\\s*\\.\\.\\.${fieldName}\\s*\\]`),
+  ];
+  if (arrayPatterns.some((p) => p.test(content))) return "array";
+
+  const numberPatterns = [
+    new RegExp(`[{,]\\s*${fieldName}\\s*=\\s*-?\\d`), // default value in destructuring
+    new RegExp(`${fieldName}\\s*[+\\-*/%]\\s*\\d`),
+    new RegExp(`parseInt\\s*\\(\\s*(?:String\\s*\\(\\s*)?${fieldName}`),
+    new RegExp(`parseFloat\\s*\\(\\s*(?:String\\s*\\(\\s*)?${fieldName}`),
+    new RegExp(`Number\\s*\\(\\s*(?:String\\s*\\(\\s*)?${fieldName}`),
+  ];
+  if (numberPatterns.some((p) => p.test(content))) return "number";
+
+  const boolPatterns = [
+    new RegExp(`[{,]\\s*${fieldName}\\s*=\\s*(true|false)\\b`), // default value in destructuring
+    new RegExp(`${fieldName}\\s*===?\\s*(true|false)`),
+    new RegExp(`(true|false)\\s*===?\\s*${fieldName}`),
+    new RegExp(`typeof\\s+${fieldName}\\s*!==?\\s*["']boolean["']`),
+    new RegExp(`typeof\\s+${fieldName}\\s*===?\\s*["']boolean["']`),
+  ];
+  if (boolPatterns.some((p) => p.test(content))) return "boolean";
+
+  // used as an object: Object.keys(x), or defaulted to {}
+  const objectPatterns = [
+    new RegExp(
+      `Object\\s*\\.\\s*(?:keys|values|entries)\\s*\\(\\s*${fieldName}\\b`,
+    ),
+    new RegExp(`${fieldName}\\s*(?:\\?\\?|\\|\\|)\\s*\\{\\s*\\}`),
+  ];
+  if (objectPatterns.some((p) => p.test(content))) return "object";
+
+  return "string";
+}
+
+function extractBodyFieldsFromFile(content) {
+  // a body read as text and parsed (JSON.parse(req.body)) is the same body
+  content = String(content).replace(
+    /JSON\.parse\s*\(\s*((?:req|request)\.body)\s*\)/g,
+    "$1",
+  );
+  const fields = new Set();
+
+  // Pattern 1
+  const destructureMatches = content.matchAll(
+    /const\s*\{([^}]+)\}\s*=\s*req\.body/g,
+  );
+  for (const destructureMatch of destructureMatches) {
+    destructureMatch[1].split(",").forEach(function (f) {
+      const clean = f.trim().split(":")[0].split("=")[0].trim();
+      if (clean) fields.add(clean);
+    });
+  }
+
+  // Pattern 2
+  const dotMatches = content.matchAll(/req\.body\.([a-zA-Z_][a-zA-Z0-9_]*)/g);
+  for (const match of dotMatches) {
+    fields.add(match[1]);
+  }
+
+  // Pattern 3
+  const bodyDotMatches = content.matchAll(/body\.([a-zA-Z_][a-zA-Z0-9_]*)/g);
+  for (const match of bodyDotMatches) {
+    fields.add(match[1]);
+  }
+
+  // Pattern 4 — any variable that is a plain copy of req.body (const form = req.body)
+  const bodyAliases = [];
+  // also accepts a type annotation ("const p: T = req.body") or a cast ("req.body as T")
+  for (const aliasMatch of content.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*req\.body(?:\s+(?:as|satisfies)\s+[\w$.<>\[\]|&, ]+?)?\s*(?=;|\r?\n|\)|,|\|\||\?\?|$)/g,
+  )) {
+    bodyAliases.push(aliasMatch[1]);
+  }
+  bodyAliases.forEach(function (varName) {
+    const safeVar = varName.replace(/\$/g, "\\$");
+    for (const match of content.matchAll(
+      new RegExp(`\\b${safeVar}\\s*\\??\\.\\s*([a-zA-Z_][a-zA-Z0-9_]*)`, "g"),
+    )) {
+      fields.add(match[1]);
+    }
+    // so the type guesser below sees "req.body.x" for every copy of the body
+    content = content.replace(
+      new RegExp(`\\b${safeVar}\\s*(\\??\\.)`, "g"),
+      "req.body$1",
+    );
+  });
+
+  // Pattern 5 — optional chaining req.body?.name
+  const optionalMatches = content.matchAll(
+    /req\.body\?\.([a-zA-Z_][a-zA-Z0-9_]*)/g,
+  );
+  for (const match of optionalMatches) {
+    fields.add(match[1]);
+  }
+
+  if (fields.size === 0) return null;
+
+  const properties = {};
+  fields.forEach(function (field) {
+    const type = inferFieldType(field, content);
+    properties[field] =
+      type === "array"
+        ? { type: "array", items: { type: "object" } }
+        : { type };
+  });
+
+  return { type: "object", properties };
+}
+
+// Reads field names from multipart/file-upload handlers (formData, multer, formidable).
+// Returns null when the file is not an upload handler, so other routes are unaffected.
+function extractMultipartFieldsFromFile(content) {
+  const text = String(content || "");
+  const usesFormData =
+    /formData\s*\(|readFormData\s*\(|parseMultipartFormData\s*\(/.test(text);
+  const usesMulter = /multer|upload\.(single|array|fields|any)\s*\(/.test(text);
+  const usesFormidable = /formidable|koa-?body/i.test(text);
+  // NestJS interceptors, AdonisJS request.file("x"), Nuxt readMultipartFormData, Hapi multipart payloads
+  const usesNest =
+    /\b(?:FileInterceptor|FilesInterceptor|FileFieldsInterceptor|AnyFilesInterceptor)\s*\(/.test(
+      text,
+    );
+  const usesRequestFile = /\brequest\.(?:file|files)\s*\(\s*['"`]/.test(text);
+  const usesNuxtParts = /readMultipartFormData\s*\(/.test(text);
+  const usesHapiPayload = /\bmultipart\s*:\s*(?:true|\{)/.test(text);
+  const usesOtherUpload =
+    usesNest || usesRequestFile || usesNuxtParts || usesHapiPayload;
+  if (!usesFormData && !usesMulter && !usesFormidable && !usesOtherUpload)
+    return null;
+
+  const fields = {}; // name -> "file" | "string"
+  const hints = Object.create(null); // name -> { type } read from how the code uses the value
+
+  if (usesFormData) {
+    // Only read .get() calls on the variable that holds the parsed form,
+    // so headers.get(...) / searchParams.get(...) are never mistaken for form fields
+    const formVars = [];
+    for (const fv of text.matchAll(
+      /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?(?:[\w$.]+\.formData|readFormData|(?:unstable_)?parseMultipartFormData)\s*\(/g,
+    )) {
+      formVars.push(fv[1]);
+    }
+    const readFormGet = function (m) {
+      const varName = m[1];
+      const fieldName = m[2];
+      let kind = m[3] ? "file" : "string"; // "as File" cast right after the read
+      if (varName) {
+        const fileUse = new RegExp(
+          "\\b" +
+            varName +
+            "\\b\\s*(?:as\\s+File|instanceof\\s+File|\\.(?:arrayBuffer|stream|size|type|name)\\b)|instanceof\\s+File",
+        );
+        if (fileUse.test(text)) kind = "file";
+      }
+      if (fields[fieldName] !== "file") fields[fieldName] = kind;
+    };
+    formVars.forEach(function (formVar) {
+      const safeVar = formVar.replace(/\$/g, "\\$");
+      const getRe = new RegExp(
+        "(?:(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*)?\\b" +
+          safeVar +
+          "\\s*\\.(?:get|getAll)\\s*\\(\\s*['\"`]([^'\"`]+)['\"`]\\s*\\)(\\s*as\\s+File\\b)?",
+        "g",
+      );
+      for (const m of text.matchAll(getRe)) readFormGet(m);
+    });
+    // Inline form: (await request.formData()).get("file")
+    const inlineRe =
+      /(?:(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*)?\(\s*await\s+[\w$.]+\.formData\s*\(\s*\)\s*\)\s*\.(?:get|getAll)\s*\(\s*['"`]([^'"`]+)['"`]\s*\)(\s*as\s+File\b)?/g;
+    for (const m of text.matchAll(inlineRe)) readFormGet(m);
+    // Type clues from how each form value is used: getAll = list, has = flag, Number(...) = number, === "true" = flag
+    formVars.forEach(function (formVar) {
+      const safeVar = formVar.replace(/\$/g, "\\$");
+      const callRe = new RegExp(
+        "\\b" +
+          safeVar +
+          "\\s*\\.\\s*(get|getAll|has)\\s*\\(\\s*['\"`]([^'\"`]+)['\"`]\\s*\\)",
+        "g",
+      );
+      for (const m of text.matchAll(callRe)) {
+        const name = m[2];
+        const before = text
+          .slice(Math.max(0, m.index - 60), m.index)
+          .split("\n")
+          .pop();
+        const after = text
+          .slice(m.index + m[0].length, m.index + m[0].length + 40)
+          .split("\n")[0];
+        let hint = null;
+        if (m[1] === "has") hint = { type: "boolean" };
+        else if (m[1] === "getAll") hint = { type: "array" };
+        else if (/(?:Number|parseInt|parseFloat)\s*\([^;]*$/.test(before))
+          hint = { type: "number" };
+        else if (/^\s*\)?\s*===?\s*['"`](?:true|false|on)['"`]/.test(after))
+          hint = { type: "boolean" };
+        if (!fields[name]) fields[name] = "string"; // fields only read with has() still exist
+        if (hint && !hints[name]) hints[name] = hint;
+      }
+    });
+  }
+
+  if (usesMulter) {
+    // upload.single("file") / upload.array("files")
+    for (const m of text.matchAll(
+      /\.(single|array)\s*\(\s*['"`]([^'"`]+)['"`]/g,
+    )) {
+      // array() takes several files under one field name
+      fields[m[2]] = m[1] === "array" ? "files" : "file";
+    }
+    // upload.fields([{ name: "avatar" }, { name: "docs" }])
+    for (const block of text.matchAll(/\.fields\s*\(\s*\[([\s\S]*?)\]\s*\)/g)) {
+      for (const n of block[1].matchAll(/name\s*:\s*['"`]([^'"`]+)['"`]/g)) {
+        fields[n[1]] = "file";
+      }
+    }
+  }
+
+  if (usesFormidable) {
+    // files.file / files["file"]  and  fields.title / fields["title"]
+    for (const m of text.matchAll(
+      /\bfiles(?:\?\.|\.)([A-Za-z_$][\w$]*)|\bfiles\s*\[\s*['"`]([^'"`]+)['"`]\s*\]/g,
+    )) {
+      fields[m[1] || m[2]] = "file";
+    }
+    for (const m of text.matchAll(
+      /\bfields(?:\?\.|\.)([A-Za-z_$][\w$]*)|\bfields\s*\[\s*['"`]([^'"`]+)['"`]\s*\]/g,
+    )) {
+      const name = m[1] || m[2];
+      if (!fields[name]) fields[name] = "string";
+    }
+  }
+
+  if (usesNest) {
+    // @UseInterceptors(FileInterceptor("file")) / FilesInterceptor("files")
+    for (const m of text.matchAll(
+      /\b(FileInterceptor|FilesInterceptor)\s*\(\s*['"`]([^'"`]+)['"`]/g,
+    )) {
+      fields[m[2]] = m[1] === "FilesInterceptor" ? "files" : "file";
+    }
+    // FileFieldsInterceptor([{ name: "avatar" }, { name: "docs" }])
+    for (const block of text.matchAll(
+      /\bFileFieldsInterceptor\s*\(\s*\[([\s\S]*?)\]/g,
+    )) {
+      for (const n of block[1].matchAll(/name\s*:\s*['"`]([^'"`]+)['"`]/g)) {
+        fields[n[1]] = "file";
+      }
+    }
+  }
+
+  if (usesRequestFile) {
+    // request.file("avatar") / request.files("docs")
+    for (const m of text.matchAll(
+      /\brequest\.(?:file|files)\s*\(\s*['"`]([^'"`]+)['"`]/g,
+    )) {
+      fields[m[1]] = "file";
+    }
+  }
+
+  if (usesNuxtParts) {
+    // readMultipartFormData(event) -> parts.find((p) => p.name === "file")
+    // lines are matched from their start so the variable name is always captured
+    for (const m of text.matchAll(
+      /(?:^|\n)[ \t]*(?:(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*)?[^\n;]*?\.name\s*===?\s*['"`]([^'"`]+)['"`][^\n]*/g,
+    )) {
+      const line = m[0];
+      const safeVar = m[1] ? m[1].replace(/\$/g, "\\$") : null;
+      // a part that is turned into text is a text field; any other part is a file
+      const readAsText =
+        /\.toString\s*\(|\bString\s*\(/.test(line) ||
+        (safeVar &&
+          new RegExp(
+            "\\b" + safeVar + "\\s*\\??\\.\\s*data\\s*\\.\\s*toString\\s*\\(",
+          ).test(text));
+      const hasFileProps =
+        safeVar &&
+        new RegExp(
+          "\\b" + safeVar + "\\b\\s*(?:\\?\\.|\\.)\\s*(?:filename|type)\\b",
+        ).test(text);
+      if (/\.filter\s*\(/.test(line)) hints[m[2]] = { type: "array" }; // several parts under one name = list
+      const kind = hasFileProps || !readAsText ? "file" : "string";
+      if (fields[m[2]] !== "file") fields[m[2]] = kind;
+    }
+  }
+
+  if (usesHapiPayload) {
+    // request.payload.file / const { file, title } = request.payload
+    const addHapiField = function (name) {
+      if (!/^[A-Za-z_$][\w$]*$/.test(name) || fields[name]) return;
+      const safeName = name.replace(/\$/g, "\\$");
+      const fileLike = new RegExp(
+        "\\b" + safeName + "\\b\\s*(?:\\?\\.|\\.)\\s*(?:hapi|_data|pipe)\\b",
+      ).test(text);
+      fields[name] = fileLike ? "file" : "string";
+    };
+    for (const m of text.matchAll(/\bpayload(?:\?\.|\.)([A-Za-z_$][\w$]*)/g)) {
+      addHapiField(m[1]);
+    }
+    for (const d of text.matchAll(/\{([^}]+)\}\s*=\s*[\w$.]*\bpayload\b/g)) {
+      d[1].split(",").forEach(function (f) {
+        addHapiField(f.trim().split(":")[0].split("=")[0].trim());
+      });
+    }
+  }
+
+  const names = Object.keys(fields);
+  if (names.length === 0) return null;
+
+  const properties = {};
+  names.forEach(function (n) {
+    const hint = hints[n];
+    // several files under one field name (upload.array / FilesInterceptor) is a list of files
+    if (fields[n] === "files")
+      properties[n] = {
+        type: "array",
+        items: { type: "string", format: "binary" },
+      };
+    else if (hint && hint.type === "array")
+      properties[n] = {
+        type: "array",
+        items:
+          fields[n] === "file"
+            ? { type: "string", format: "binary" }
+            : { type: "string" },
+      };
+    else if (fields[n] === "file")
+      properties[n] = { type: "string", format: "binary" };
+    else properties[n] = hint ? { type: hint.type } : { type: "string" };
+  });
+  return {
+    type: "object",
+    properties: properties,
+    "x-content-type": "multipart/form-data",
+  };
+}
+
+// Combines text fields read from req.body with file fields from the upload parser
+function mergeBodyWithMultipart(bodyFields, multipartFields) {
+  if (!multipartFields) return bodyFields;
+  if (!bodyFields) return multipartFields;
+  return {
+    type: "object",
+    properties: Object.assign(
+      {},
+      bodyFields.properties,
+      multipartFields.properties,
+    ),
+    "x-content-type": "multipart/form-data",
+  };
+}
+
+// Rewrites the different ways of reading the JSON body into the plain form "await request.json()"
+function normalizeBodyReads(content) {
+  let t = String(content);
+  // request.clone().json()
+  t = t.replace(
+    /\bawait\s+([\w$]+)\s*\.\s*clone\s*\(\s*\)\s*\.\s*json\s*\(\s*\)/g,
+    function (all, v) {
+      return "await " + v + ".json()";
+    },
+  );
+  // const text = await request.text(); JSON.parse(text)
+  for (const m of t.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+([\w$]+)\s*\.\s*text\s*\(\s*\)/g,
+  )) {
+    const textVar = m[1].replace(/\$/g, "\\$");
+    const reqVar = m[2];
+    t = t.replace(
+      new RegExp("JSON\\.parse\\s*\\(\\s*" + textVar + "\\s*\\)", "g"),
+      function () {
+        return "(await " + reqVar + ".json())";
+      },
+    );
+  }
+  return t;
+}
+
+function extractAppRouterBodyFields(content) {
+  content = normalizeBodyReads(content); // handles body reads written in different styles
+  const fields = new Set();
+
+  // Pattern 1: const { userId, tokens } = await request.json() (a type may follow the braces)
+  const destructureMatches = content.matchAll(
+    /const\s*\{([^}]+)\}\s*(?::[^=;]+)?=\s*\(?\s*await\s+\w+\.json\(\)/g,
+  );
+  for (const match of destructureMatches) {
+    match[1].split(",").forEach(function (f) {
+      const clean = f.trim().split(":")[0].split("=")[0].trim(); // field name only, without a default value
+      if (clean) fields.add(clean);
+    });
+  }
+
+  // Pattern 2: const body = await request.json() then body.userId
+  const bodyVarMatch = content.match(
+    /const\s+(\w+)\s*=\s*\{?\s*(?:\.\.\.\s*)?\(?\s*await\s+\w+\.json\(\)/,
+  );
+  if (bodyVarMatch) {
+    const varName = bodyVarMatch[1];
+    const varMatches = content.matchAll(
+      new RegExp(`${varName}\\.([a-zA-Z_][a-zA-Z0-9_]*)`, "g"),
+    );
+    for (const match of varMatches) {
+      fields.add(match[1]);
+    }
+  }
+
+  // Pattern 3: (await request.json()).userId
+  const inlineMatches = content.matchAll(
+    /\(await\s+\w+\.json\(\)\)\.([a-zA-Z_][a-zA-Z0-9_]*)/g,
+  );
+  for (const match of inlineMatches) {
+    fields.add(match[1]);
+  }
+
+  if (fields.size === 0) return null;
+
+  const properties = {};
+  fields.forEach(function (field) {
+    const type = inferFieldType(field, content);
+    properties[field] =
+      type === "array"
+        ? { type: "array", items: { type: "object" } }
+        : { type };
+  });
+
+  return { type: "object", properties };
+}
+
+// Fields a validator function reads from the object it is given: validate(data) { typeof data.x ... }
+function readValidatorFields(text, method) {
+  const re = new RegExp(
+    "(?:^|[^\\w$.])" +
+      method +
+      "\\s*(?:[:=]\\s*)?(?:async\\s*)?(?:function\\s*)?\\(",
+    "g",
+  );
+  let h;
+  while ((h = re.exec(text)) !== null) {
+    const open = h.index + h[0].length - 1;
+    const params = sliceCallText(text, open);
+    if (!params) continue;
+    const param = (/^\(\s*([A-Za-z_$][\w$]*)/.exec(params) || [])[1];
+    if (!param) continue;
+    const tail = text.slice(open + params.length);
+    const a = /^\s*(=>\s*)?(\{)?/.exec(tail);
+    // a definition is followed by "{" or "=>"; anything else is a call
+    if (!a[1] && !a[2]) continue;
+    let body;
+    if (a[2]) {
+      const bo = open + params.length + a[0].length - 1;
+      const close = findStaticClosingBrace(text, bo);
+      if (close === null) continue;
+      body = text.slice(bo, close + 1);
+    } else {
+      body = tail.slice(a[0].length, a[0].length + 600);
+    }
+    const p = param.replace(/\$/g, "\\$");
+    const properties = {};
+    for (const f of body.matchAll(
+      new RegExp(
+        "\\b" + p + "\\s*\\??\\.\\s*([A-Za-z_$][\\w$]*)(?![\\w$])(?!\\s*\\()",
+        "g",
+      ),
+    )) {
+      const name = f[1];
+      const safe = name.replace(/\$/g, "\\$");
+      let type = "string";
+      const t = new RegExp(
+        "typeof\\s+" +
+          p +
+          "\\s*\\??\\.\\s*" +
+          safe +
+          "\\b\\s*(?:===?|!==?)\\s*['\"](string|number|boolean|object)['\"]",
+      ).exec(body);
+      if (t) type = t[1];
+      else if (
+        new RegExp(
+          "Array\\.isArray\\s*\\(\\s*" + p + "\\s*\\.\\s*" + safe + "\\b",
+        ).test(body)
+      )
+        type = "array";
+      properties[name] =
+        type === "array"
+          ? { type: "array", items: { type: "object" } }
+          : { type };
+    }
+    if (Object.keys(properties).length > 0)
+      return { type: "object", properties };
+  }
+  return null;
+}
+
+// Body fields from a validator written as plain code: schema.validate(ctx.request.body),
+// where the validate function lives in a neighbouring file
+function extractValidatorFunctionFields(code, content, filePath) {
+  const done = [];
+  for (const m of String(code).matchAll(
+    /\b([A-Za-z_$][\w$]*)\s*\.\s*(validate|validateSync|parse|safeParse|check|verify)\s*\(/g,
+  )) {
+    if (m[1] === "JSON") continue;
+    const call = sliceCallText(code, m.index + m[0].length - 1);
+    // only a call that is handed the request body
+    if (!call || !/body|payload|\.json\s*\(/.test(call)) continue;
+    const key = m[1] + "." + m[2];
+    if (done.indexOf(key) !== -1) continue;
+    done.push(key);
+    const text = readImportedFile(content, m[1], filePath);
+    if (!text) continue;
+    const fields = readValidatorFields(text, m[2]);
+    if (fields) return fields;
+  }
+  return null;
+}
+
+// Body fields listed by a validation schema (zod / yup / joi style), e.g. schema.parse(await request.json()).
+// The schema can be written in the same file or imported from a neighbouring file.
+function extractSchemaBodyFields(code, content, filePath) {
+  try {
+    const names = [];
+    for (const m of String(code).matchAll(
+      /\b([A-Za-z_$][\w$]*)\s*\.\s*(?:parse|safeParse|parseAsync|safeParseAsync|validate|validateSync)\s*(?:\(|\)|,)/g,
+    )) {
+      if (names.indexOf(m[1]) === -1) names.push(m[1]);
+    }
+    for (const name of names) {
+      const texts = [content];
+      const imported = readImportedFile(content, name, filePath);
+      if (imported) texts.push(imported);
+      const safe = name.replace(/\$/g, "\\$");
+      const declRe = new RegExp(
+        "(?:const|let|var)\\s+" +
+          safe +
+          "\\s*(?::[^=]+)?=\\s*[\\w$.]*object\\s*\\(\\s*(?:\\)\\s*\\.\\s*shape\\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 entries = splitStaticEntries(text.slice(open + 1, close)) || [];
+        const properties = {};
+        entries.forEach(function (entry) {
+          const e =
+            /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*:\s*([\s\S]+)$/.exec(
+              entry,
+            );
+          if (!e) return;
+          const kind =
+            (/^\s*[\w$]+\s*\.\s*(?:coerce\s*\.\s*)?(\w+)/.exec(e[4]) ||
+              [])[1] || "";
+
+          let type = { type: "string" };
+          if (/^(number|int|float|bigint)$/i.test(kind))
+            type = { type: "number" };
+          else if (/^(boolean|bool)$/i.test(kind)) type = { type: "boolean" };
+          else if (/^array$/i.test(kind))
+            type = { type: "array", items: { type: "object" } };
+          else if (/^object$/i.test(kind)) type = { type: "object" };
+          properties[e[1] || e[2] || e[3]] = type;
+        });
+        if (Object.keys(properties).length > 0)
+          return { type: "object", properties };
+      }
+    }
+    // no schema object found: the validator may be plain code that reads data.x / typeof data.x
+    return extractValidatorFunctionFields(code, content, filePath);
+  } catch (e) {}
+  return null;
+}
+
+function extractQueryFieldsFromFile(content) {
+  const fields = new Set();
+  const NAME = /^[A-Za-z_$][\w$.-]*$/;
+  const addField = function (raw) {
+    const name = String(raw).trim().split(":")[0].split("=")[0].trim();
+    if (name && NAME.test(name)) fields.add(name);
+  };
+
+  // const { id, page = 1 } = req.query
+  const destructureRe =
+    /(?:const|let|var)\s*\{([^}]+)\}\s*=\s*(?:await\s+)?(?:req|request|ctx(?:\.request)?)\.query\b/g;
+  for (const m of String(content).matchAll(destructureRe)) {
+    m[1].split(",").forEach(addField);
+  }
+
+  // req.query.id / req.query?.id
+  const dotRe =
+    /(?:req|request|ctx(?:\.request)?)\.query(?:\?\.|\.)([A-Za-z_$][\w$]*)/g;
+  for (const m of String(content).matchAll(dotRe)) addField(m[1]);
+
+  // req.query["id"]
+  const bracketRe =
+    /(?:req|request|ctx(?:\.request)?)\.query\s*\??\.?\[\s*['"`]([^'"`]+)['"`]\s*\]/g;
+  for (const m of String(content).matchAll(bracketRe)) addField(m[1]);
+
+  // url.searchParams.get("id") / nextUrl.searchParams.get("id")
+  const typeHints = Object.create(null); // type clues: getAll = list, has = flag, Number(...) = number
+  const queryText = String(content);
+  const searchParamsRe =
+    /searchParams\s*\??\.\s*(get|getAll|has)\s*\(\s*['"`]([^'"`]+)['"`]/g;
+  for (const m of queryText.matchAll(searchParamsRe)) {
+    addField(m[2]);
+    const lineBefore = queryText
+      .slice(Math.max(0, m.index - 80), m.index)
+      .split("\n")
+      .pop();
+    const lineAfter = queryText
+      .slice(m.index + m[0].length, m.index + m[0].length + 40)
+      .split("\n")[0];
+    let hint = null;
+    if (m[1] === "has") hint = { type: "boolean" };
+    else if (m[1] === "getAll")
+      hint = { type: "array", items: { type: "string" } };
+    else if (/(?:Number|parseInt|parseFloat)\s*\([^;]*$/.test(lineBefore))
+      hint = { type: "number" };
+    else if (/^\s*\)?\s*===?\s*['"`](?:true|false)['"`]/.test(lineAfter))
+      hint = { type: "boolean" };
+    if (hint && !typeHints[m[2]]) typeHints[m[2]] = hint;
+  }
+
+  if (fields.size === 0) return null;
+
+  const properties = {};
+  fields.forEach(function (field) {
+    // the type comes from how the code uses the value (Number(x), x.map, ...), otherwise text
+    let guessed = "string";
+    try {
+      guessed = inferFieldType(field, queryText);
+    } catch (e) {}
+    properties[field] =
+      typeHints[field] ||
+      (guessed === "array"
+        ? { type: "array", items: { type: "string" } }
+        : { type: guessed });
+  });
+
+  return { type: "object", properties };
+}
+
+// Finds the code of a handler declared by name in the same file (null if not found or not safely bounded)
+function findNamedHandlerCode(content, name) {
+  const safe = name.replace(/[$]/g, "\\$&");
+  const declRe = new RegExp(
+    "(?:^|\\n)(?:export\\s+)?(?:async\\s+)?function\\s+" +
+      safe +
+      "\\s*\\(|(?:^|\\n)(?:export\\s+)?(?:const|let|var)\\s+" +
+      safe +
+      "\\s*(?::[^=;]+)?=", // an optional type after the name is allowed
+  );
+  const decl = declRe.exec(content);
+  if (!decl) return null;
+  let start = decl.index + decl[0].length;
+  if (decl[0].endsWith("(")) {
+    // function form: skip the parameter list
+    const params = sliceCallText(content, start - 1);
+    if (!params) return null;
+    start = start - 1 + params.length;
+  } else {
+    // variable form: the body starts after the first arrow, if it comes before the statement ends
+    const arrow = content.indexOf("=>", start);
+    const semi = content.indexOf(";", start);
+    if (arrow !== -1 && (semi === -1 || arrow < semi)) start = arrow + 2;
+  }
+  const brace = content.indexOf("{", start);
+  const semi = content.indexOf(";", start);
+  // no braces before the statement ends: a one-line handler
+  if (semi !== -1 && (brace === -1 || semi < brace)) {
+    return content.slice(decl.index, semi + 1);
+  }
+  if (brace === -1) return null;
+  const close = findStaticClosingBrace(content, brace);
+  return close === null ? null : content.slice(decl.index, close + 1);
+}
+
+// Reads body fields from ONE route's own code, so fields from other routes in the same file are never mixed in
+function extractBodyFieldsForRoute(content, startIndex, routePatternSource) {
+  // Decorator routes (@Post) own the method below them; call-style routes own their call
+  const own =
+    content[startIndex] === "@"
+      ? sliceRouteSegment(content, startIndex, routePatternSource)
+      : sliceCallText(content, startIndex) ||
+        sliceRouteSegment(content, startIndex, routePatternSource);
+  const direct = extractBodyFieldsFromFile(own);
+  if (direct) return direct;
+
+  // Handler written separately in this file, e.g. app.post("/x", auth, createThing) or wrap(createThing)
+  const args =
+    /^[\w$.]*?\.\w+\s*\(\s*['"`][^'"`]+['"`]\s*,([^;{=]*?)\)\s*;?$/.exec(
+      own.trim(),
+    );
+  if (!args) return null;
+  const names = args[1].match(/[A-Za-z_$][\w$]*/g) || [];
+  for (const name of names) {
+    const code = findNamedHandlerCode(content, name);
+    const fields = code ? extractBodyFieldsFromFile(code) : null;
+    if (fields) return fields;
+  }
+  // Not found in this file: report "unknown" instead of guessing from the whole file
+  return null;
+}
+
+// For live Express routes: reads query fields from every handler's source code
+function extractQueryFieldsFromHandlers(stack) {
+  try {
+    const merged = {};
+    for (const layer of stack) {
+      const fn = layer.handle || layer;
+      if (typeof fn !== "function") continue;
+      const fields = extractQueryFieldsFromFile(
+        Function.prototype.toString.call(fn),
+      );
+      if (fields) Object.assign(merged, fields.properties);
+    }
+    return Object.keys(merged).length > 0
+      ? { type: "object", properties: merged }
+      : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+module.exports = {
+  extractSchemaBodyFields,
+  extractBodyFieldsFromFile,
+  extractMultipartFieldsFromFile,
+  mergeBodyWithMultipart,
+  extractAppRouterBodyFields,
+  extractQueryFieldsFromFile,
+  findNamedHandlerCode,
+  extractBodyFieldsForRoute,
+  inferFieldType,
+  extractQueryFieldsFromHandlers,
+};