botversion-sdk 2.2.3 → 2.3.0

package/scanner-sdk/scan/fastify.js

@@ -0,0 +1,1162 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/fastify.js
+// PURPOSE: Finds API routes in Fastify projects, with their FULL url (plugin prefixes and
+//          @fastify/autoload folder prefixes included), request fields, query fields and reply shape.
+// CONTAINS: scanFastifyRoutes (+ private helpers)
+// USED BY: scanner.js (scanFastifyRoutes)
+// DEPENDS ON: ./field-extractors, ./text-utils, ./response-shape, ./nest-source (only its generic
+//             file/import/constant/type readers)
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  extractBodyFieldsFromFile,
+  extractMultipartFieldsFromFile,
+  mergeBodyWithMultipart,
+  extractQueryFieldsFromFile,
+  findNamedHandlerCode,
+} = require("./field-extractors");
+const {
+  buildRouteParamMap,
+  removePathParamFields,
+  joinMountPath,
+  blankOutComments,
+  sliceCallText,
+  splitStaticEntries,
+  findStaticClosingBrace,
+  skipStaticString,
+} = require("./text-utils");
+const src = require("./nest-source");
+
+// Receiver names always treated as a Fastify instance (kept from the old scanner).
+// Other names (instance, f, api, ...) are detected from the code itself.
+const BASE_NAMES = ["fastify", "app", "server", "router"];
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"];
+const SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "build",
+  ".cache",
+  "coverage",
+  "out",
+];
+// fastify.all(...) has no single method; same convention as the NestJS/Express scans: stored as GET
+const ALL_METHOD_STORED_AS = "GET";
+
+function esc(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function lineAt(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+
+// Same-length copy of the text where comments and the INSIDE of strings are blanked,
+// so route-looking text in comments, strings and logs is never read as code.
+function maskNonCode(text) {
+  const out = text.split("");
+  const n = text.length;
+  let i = 0;
+  while (i < n) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (ch === "/" && next === "/") {
+      while (i < n && text[i] !== "\n") out[i++] = " ";
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const end = text.indexOf("*/", i + 2);
+      const stop = end === -1 ? n : end + 2;
+      for (; i < stop; i++) if (text[i] !== "\n") out[i] = " ";
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const close = skipStaticString(text, i, n);
+      if (close === -1) {
+        i++;
+        continue;
+      }
+      for (let k = i + 1; k < close; k++) if (text[k] !== "\n") out[k] = " ";
+      i = close + 1;
+      continue;
+    }
+    i++;
+  }
+  return out.join("");
+}
+
+// Test, mock and type-declaration files are never part of the real API
+function isIgnoredFile(rel) {
+  return (
+    /(^|[\\/])(tests?|__tests__|__mocks__|e2e)[\\/]/i.test(rel) ||
+    /\.(test|spec)\.[cm]?[jt]sx?$/i.test(rel) ||
+    /\.d\.ts$/i.test(rel)
+  );
+}
+
+// Reads "key: value" entries of an object written in code (shorthand keys and methods included)
+function readObj(text) {
+  const t = String(text || "").trim();
+  if (t.charAt(0) !== "{") return null;
+  const close = src.matchClose(t, 0);
+  const inner = t.slice(1, close === -1 ? t.length : close);
+  const entries = splitStaticEntries(inner);
+  if (!entries) return null;
+  const out = {};
+  for (const e of entries) {
+    const m =
+      /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*)|(\d+))\s*(?::\s*([\s\S]+))?$/.exec(
+        e,
+      );
+    if (m) {
+      const k = m[1] || m[2] || m[3] || m[4];
+      out[k] = m[5] === undefined ? k : m[5].trim();
+      continue;
+    }
+    const mm = /^(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(/.exec(e);
+    if (mm) out[mm[1]] = e;
+  }
+  return out;
+}
+
+// Index of the first top-level (outside brackets and strings) spot where test() is true
+function topLevelIndex(expr, test) {
+  let depth = 0;
+  for (let i = 0; i < expr.length; i++) {
+    const ch = expr[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const e = skipStaticString(expr, i, expr.length);
+      if (e === -1) return -1;
+      i = e;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") depth--;
+    else if (depth === 0 && test(expr, i)) return i;
+  }
+  return -1;
+}
+
+// End of an expression that starts at "start" (a ";" or line end outside any brackets)
+function readExpr(c, start) {
+  let depth = 0;
+  for (let i = start; i < c.length; i++) {
+    const ch = c[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const e = skipStaticString(c, i, c.length);
+      if (e === -1) return c.length;
+      i = e;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+      if (depth < 0) return i;
+    } else if (depth === 0 && ch === ";") return i;
+    else if (depth === 0 && ch === "\n") {
+      const rest = c.slice(i + 1).trimStart();
+      const t = c.slice(start, i).trimEnd();
+      if (!/^[|&+.?:]/.test(rest) && !/[|&+:=?,]$/.test(t)) return i;
+    }
+  }
+  return c.length;
+}
+
+// ── Reading what a handler returns ───────────────────────────────────────────
+const UNKNOWN = { type: "unknown" };
+
+function objectSchemaFromLiteral(text, ctx, depth) {
+  const close = src.matchClose(text, 0);
+  const inner = text.slice(1, close === -1 ? text.length : close);
+  const entries = splitStaticEntries(inner);
+  if (!entries) return { type: "object" };
+  const properties = {};
+  let count = 0;
+  for (const entry of entries) {
+    if (count >= 50) break;
+    if (!entry || entry.startsWith("...") || entry.startsWith("[")) continue;
+    let m = /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*:\s*([\s\S]+)$/.exec(
+      entry,
+    );
+    if (m) {
+      properties[m[1] || m[2] || m[3]] = valueType(m[4], ctx, depth + 1);
+      count++;
+      continue;
+    }
+    m = /^([A-Za-z_$][\w$]*)$/.exec(entry);
+    if (m) {
+      properties[m[1]] = valueType(m[1], ctx, depth + 1);
+      count++;
+    }
+  }
+  return Object.keys(properties).length
+    ? { type: "object", properties: properties }
+    : { type: "object" };
+}
+
+// Best-effort type of a value written in code; anything that cannot be known stays "unknown"
+function valueType(expr, ctx, depth) {
+  let t = String(expr || "").trim();
+  if (!t || depth > 5) return UNKNOWN;
+  if (/^await\s/.test(t)) return UNKNOWN;
+  t = t.replace(/\s+as\s+[\w$.<>\[\]]+$/, "");
+  if (t.charAt(0) === "(" && src.matchClose(t, 0) === t.length - 1)
+    return valueType(t.slice(1, -1), ctx, depth + 1);
+
+  const q = topLevelIndex(t, function (e, i) {
+    return (
+      e[i] === "?" && e[i + 1] !== "?" && e[i + 1] !== "." && e[i - 1] !== "?"
+    );
+  });
+  if (q > 0) {
+    const rest = t.slice(q + 1);
+    const c = topLevelIndex(rest, function (e, i) {
+      return e[i] === ":";
+    });
+    if (c >= 0) {
+      const a = valueType(rest.slice(0, c), ctx, depth + 1);
+      return a.type !== "unknown"
+        ? a
+        : valueType(rest.slice(c + 1), ctx, depth + 1);
+    }
+  }
+  const orAt = topLevelIndex(t, function (e, i) {
+    return e.startsWith("||", i) || e.startsWith("??", i);
+  });
+  if (orAt > 0) {
+    const l = valueType(t.slice(0, orAt), ctx, depth + 1);
+    return l.type !== "unknown"
+      ? l
+      : valueType(t.slice(orAt + 2), ctx, depth + 1);
+  }
+  if (t.charAt(0) === "!") return { type: "boolean" };
+  if (
+    topLevelIndex(t, function (e, i) {
+      return /^(===|!==|==|!=|>=|<=)/.test(e.slice(i, i + 3));
+    }) > 0
+  )
+    return { type: "boolean" };
+
+  if (/^["'`]/.test(t)) return { type: "string" };
+  if (/^-?\d+(\.\d+)?$/.test(t)) return { type: "number" };
+  if (/^(true|false)$/.test(t)) return { type: "boolean" };
+  if (t.charAt(0) === "{") return objectSchemaFromLiteral(t, ctx, depth);
+  if (t.charAt(0) === "[") {
+    const close = src.matchClose(t, 0);
+    const first = (splitStaticEntries(
+      t.slice(1, close === -1 ? t.length : close),
+    ) || [])[0];
+    return {
+      type: "array",
+      items: first ? valueType(first, ctx, depth + 1) : UNKNOWN,
+    };
+  }
+  if (/^(?:Number|parseInt|parseFloat)\s*\(/.test(t) || /^Math\./.test(t))
+    return { type: "number" };
+  if (/^String\s*\(/.test(t)) return { type: "string" };
+  if (/^Boolean\s*\(/.test(t)) return { type: "boolean" };
+  if (/\.length$/.test(t)) return { type: "number" };
+  if (/\.(?:map|filter|slice|concat|sort|reverse)\s*\([\s\S]*\)$/.test(t))
+    return { type: "array", items: UNKNOWN };
+  if (
+    /\.(?:join|toLowerCase|toUpperCase|trim|toISOString|toFixed)\s*\([^()]*\)$/.test(
+      t,
+    )
+  )
+    return { type: "string" };
+  if (/^new\s+Date\b/.test(t)) return { type: "string" };
+
+  let m = /^req\s*\.\s*(params|query)\s*\??\.\s*[\w$]+$/.exec(t);
+  if (m) return { type: "string" };
+  m = /^req\s*\.\s*body\s*\??\.\s*([\w$]+)$/.exec(t);
+  if (m) return ctx.bodyTypes[m[1]] || UNKNOWN;
+  m = /^([A-Za-z_$][\w$]*)\s*\??\.\s*([\w$]+)$/.exec(t);
+  if (m && ctx.aliases.has(m[1])) return ctx.bodyTypes[m[2]] || UNKNOWN;
+
+  if (/^[A-Za-z_$][\w$]*$/.test(t)) {
+    const decl = new RegExp(
+      "(?:^|[\\s;{}(,])(?:const|let|var)\\s+" +
+        esc(t) +
+        "\\s*(?::[^=;]+)?=(?!=)\\s*",
+    ).exec(ctx.code);
+    if (decl) {
+      const s = decl.index + decl[0].length;
+      return valueType(
+        ctx.code.slice(s, readExpr(ctx.code, s)),
+        ctx,
+        depth + 1,
+      );
+    }
+    for (const d of ctx.code.matchAll(
+      /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?req\s*\.\s*(params|query|body)\b/g,
+    )) {
+      for (const piece of d[1].split(",")) {
+        const parts = piece.trim().split("=")[0].split(":");
+        const orig = parts[0].trim();
+        const local = (parts[1] || parts[0]).trim();
+        if (local === t)
+          return d[2] === "body"
+            ? ctx.bodyTypes[orig] || UNKNOWN
+            : { type: "string" };
+      }
+    }
+  }
+  return UNKNOWN;
+}
+
+// Which "return" statements belong to the handler itself (not to a callback inside it)
+function scanReturnDepths(masked) {
+  const stack = [];
+  const out = [];
+  for (let i = 0; i < masked.length; i++) {
+    const ch = masked[i];
+    if (ch === "{") {
+      const before = masked.slice(Math.max(0, i - 300), i).trimEnd();
+      let isFn = false;
+      if (/=>$/.test(before)) isFn = true;
+      else if (before.endsWith(")")) {
+        let d = 0;
+        let j = before.length - 1;
+        for (; j >= 0; j--) {
+          if (before[j] === ")") d++;
+          else if (before[j] === "(") {
+            d--;
+            if (d === 0) break;
+          }
+        }
+        const head = before.slice(0, Math.max(0, j)).trimEnd();
+        isFn = !/\b(?:if|for|while|switch|catch|with)$/.test(head);
+      }
+      stack.push(isFn);
+    } else if (ch === "}") stack.pop();
+    else if (
+      ch === "r" &&
+      masked.startsWith("return", i) &&
+      !/[\w$.]/.test(masked[i - 1] || " ") &&
+      !/[\w$]/.test(masked[i + 6] || " ")
+    )
+      out.push({ index: i, fnDepth: stack.filter(Boolean).length });
+  }
+  return out;
+}
+
+function usefulReply(s) {
+  if (!s) return false;
+  if (s.type === "array") return !!s.items && s.items.type !== "unknown";
+  if (s.type !== "object" || !s.properties) return false;
+  const keys = Object.keys(s.properties);
+  return keys.length > 0 && !(keys.length === 1 && keys[0] === "error"); // lone error = error reply
+}
+
+// First successful reply written in the handler: return {...}, reply.send({...}), or a variable behind them
+function responseFromCode(code, ctx) {
+  const masked = maskNonCode(code);
+  const cands = [];
+  for (const r of scanReturnDepths(masked)) {
+    if (r.fnDepth > 1) continue;
+    const after = /^return\s*(?:await\s+)?/.exec(code.slice(r.index));
+    const start = r.index + after[0].length;
+    if (/^(?:reply|res|response)\s*[.(]/.test(code.slice(start, start + 12)))
+      continue; // handled via .send()
+    cands.push({
+      index: r.index,
+      expr: code.slice(start, readExpr(code, start)),
+    });
+  }
+  const sendRe =
+    /\b(?:reply|res|response)\s*(?:\.\s*(?:code|status)\s*\(\s*(\d{3})\s*\))?\s*\.\s*send\s*\(/g;
+  let m;
+  while ((m = sendRe.exec(masked)) !== null) {
+    if (m[1] && parseInt(m[1], 10) >= 400) continue;
+    const call = sliceCallText(code, m.index + m[0].length - 1);
+    if (!call) continue;
+    const first = (splitStaticEntries(call.slice(1, -1)) || [])[0];
+    if (first) cands.push({ index: m.index, expr: first });
+  }
+  const arrow =
+    /^\s*(?:async\s+)?(?:\([^)]*\)|[\w$]+)\s*=>\s*(\(\s*\{[\s\S]*)$/.exec(code);
+  if (arrow) cands.push({ index: 0, expr: arrow[1] });
+  cands.sort(function (a, b) {
+    return a.index - b.index;
+  });
+  for (const c of cands) {
+    const s = valueType(c.expr, ctx, 0);
+    if (usefulReply(s)) return Object.assign({}, s, { _source: "static" });
+  }
+  return null;
+}
+
+// ── Reading declared schemas (schema: {...} and TypeScript generics) ─────────
+function jsonSchemaFromText(text, file, depth) {
+  depth = depth || 0;
+  if (depth > 6) return UNKNOWN;
+  const t = String(text || "").trim();
+  if (/^[A-Za-z_$][\w$]*$/.test(t)) {
+    const f = src.lookupConst(t, file);
+    return f ? jsonSchemaFromText(f.expr, f.file, depth + 1) : null;
+  }
+  const o = readObj(t);
+  if (!o) return null;
+  const type = o.type ? src.resolveStringExpr(o.type, file) : null;
+  if (o.properties) {
+    let po = readObj(o.properties);
+    if (!po && /^[A-Za-z_$][\w$]*$/.test(o.properties.trim())) {
+      const f = src.lookupConst(o.properties.trim(), file);
+      po = f ? readObj(f.expr) : null;
+    }
+    const properties = {};
+    Object.keys(po || {}).forEach(function (k) {
+      properties[k] = jsonSchemaFromText(po[k], file, depth + 1) || UNKNOWN;
+    });
+    return { type: "object", properties: properties };
+  }
+  if (type === "array") {
+    return {
+      type: "array",
+      items:
+        (o.items && jsonSchemaFromText(o.items, file, depth + 1)) || UNKNOWN,
+    };
+  }
+  if (type === "integer" || type === "number") return { type: "number" };
+  if (type === "string" || type === "boolean") return { type: type };
+  if (type === "object") return { type: "object" };
+  return UNKNOWN;
+}
+
+// <{ Body: X; Querystring: Y; Reply: Z }> written after the method name
+function readGenerics(genericText, file) {
+  const out = {};
+  if (!genericText) return out;
+  let inner = genericText.trim().replace(/^</, "").replace(/>$/, "").trim();
+  if (inner.charAt(0) === "{") inner = inner.slice(1, inner.lastIndexOf("}"));
+  for (const part of src.splitTopLevel(inner.replace(/;/g, ",")) || []) {
+    const m = /^(Body|Querystring|Reply)\s*:\s*([\s\S]+)$/.exec(part.trim());
+    if (!m || m[2].trim().charAt(0) === "{") continue;
+    const s = src.typeToSchema(m[2].trim(), file);
+    if (s && s.type !== "unknown") out[m[1]] = s;
+  }
+  return out;
+}
+
+function pickSuccessResponse(responseText, file) {
+  const ro = readObj(responseText);
+  if (!ro) return jsonSchemaFromText(responseText, file, 0);
+  const key = Object.keys(ro).find(function (k) {
+    return /^(2\d\d|2xx)$/i.test(k);
+  });
+  return key ? jsonSchemaFromText(ro[key], file, 0) : null;
+}
+
+// Declared fields win over guessed ones; fields only seen in code are kept
+function mergeFieldSchemas(fromCode, declared) {
+  if (!declared) return fromCode;
+  if (!fromCode) return declared;
+  const props = Object.assign({}, fromCode.properties);
+  Object.keys(declared.properties || {}).forEach(function (k) {
+    const d = declared.properties[k];
+    if (d && d.type === "unknown" && props[k]) return;
+    props[k] = d;
+  });
+  return { type: "object", properties: props };
+}
+
+function fastifyMultipartFields(code) {
+  if (
+    !/\b(?:req|request)\s*\.\s*(?:file|files|parts|saveRequestFiles|multipart)\s*\(/.test(
+      code,
+    )
+  )
+    return null;
+  const fields = {};
+  for (const m of code.matchAll(/\.fields\s*(?:\?\.|\.)\s*([A-Za-z_$][\w$]*)/g))
+    fields[m[1]] = true;
+  for (const m of code.matchAll(/\.fields\s*\[\s*['"`]([^'"`]+)['"`]\s*\]/g))
+    fields[m[1]] = true;
+  for (const m of code.matchAll(/\bfieldname\s*===?\s*['"`]([^'"`]+)['"`]/g))
+    fields[m[1]] = true;
+  const properties = {};
+  Object.keys(fields).forEach(function (k) {
+    properties[k] = { type: "string" };
+  });
+  // File field names are chosen by the caller at runtime, so none are invented here
+  return {
+    type: "object",
+    properties: properties,
+    "x-content-type": "multipart/form-data",
+  };
+}
+
+// ── Finding the handler's code ───────────────────────────────────────────────
+function firstParamName(code) {
+  let m = /\bfunction\b\s*\*?\s*[\w$]*\s*\(\s*([A-Za-z_$][\w$]*)/.exec(code);
+  if (m) return m[1];
+  m = /^\s*(?:async\s+)?\(\s*([A-Za-z_$][\w$]*)/.exec(code);
+  if (m && m[1] !== "async") return m[1];
+  m = /=\s*(?:async\s+)?\(\s*([A-Za-z_$][\w$]*)/.exec(code);
+  if (m) return m[1];
+  m = /^\s*(?:async\s+)?([A-Za-z_$][\w$]*)\s*=>/.exec(code);
+  return m ? m[1] : null;
+}
+
+// Rewrites "<requestParam>.body/query/params" to "req.body/query/params" so the shared
+// field readers (which know "req") work whatever the handler calls its request.
+function normalizeHandlerCode(code, param) {
+  const names = new Set(["request", "req"]);
+  if (param) names.add(param);
+  let out = code;
+  names.forEach(function (n) {
+    if (n === "req") return;
+    out = out.replace(
+      new RegExp(
+        "(?<![\\w$.])" + esc(n) + "\\s*\\.\\s*(body|query|params)\\b",
+        "g",
+      ),
+      "req.$1",
+    );
+  });
+  return out;
+}
+
+function requireBindings(content) {
+  const out = {};
+  for (const m of content.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ))
+    out[m[1]] = { spec: m[2], imported: "default" };
+  return out;
+}
+
+function bindingsOf(content) {
+  return Object.assign({}, requireBindings(content), src.parseImports(content));
+}
+
+function sliceFunctionFrom(text, start) {
+  const brace = text.indexOf("{", start);
+  const semi = text.indexOf(";", start);
+  if (semi !== -1 && (brace === -1 || semi < brace))
+    return text.slice(start, semi + 1);
+  if (brace === -1) return null;
+  const close = findStaticClosingBrace(text, brace);
+  return close === null ? null : text.slice(start, close + 1);
+}
+
+// A function declared by name in a file: function x / const x = ... / exports.x = ...
+function findInSource(text, name) {
+  const code = findNamedHandlerCode(text, name);
+  if (code) return code;
+  const m = new RegExp(
+    "(?:module\\.)?exports\\.(?:" + esc(name) + ")\\s*=\\s*",
+  ).exec(text);
+  return m ? sliceFunctionFrom(text, m.index + m[0].length) : null;
+}
+
+function findClassMethod(content, prop, nearIndex) {
+  const c = blankOutComments(content);
+  const classes = src.findClasses(c);
+  const ordered = classes
+    .filter(function (k) {
+      return nearIndex > k.open && nearIndex < k.close;
+    })
+    .concat(classes);
+  for (const cls of ordered) {
+    for (const mem of src.parseMembers(c, cls.open, cls.close)) {
+      if (mem.kind === "method" && mem.name === prop)
+        return (
+          "(" + (mem.paramsText || "") + ") {" + (mem.bodyText || "") + "}"
+        );
+    }
+  }
+  return null;
+}
+
+// Handler written in the route call: inline function, named function, class method, or imported
+function locateHandler(expr, file, content, callIndex) {
+  expr = String(expr || "").trim();
+  if (!expr) return { code: null, how: "none" };
+  if (
+    /^(?:async\b|function\b|\()/.test(expr) ||
+    /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(expr)
+  )
+    return { code: expr, how: "inline" };
+
+  const member =
+    /^([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)(?:\s*\.\s*bind\s*\([^)]*\))?$/.exec(
+      expr,
+    );
+  if (member) {
+    const own = findClassMethod(content, member[2], callIndex);
+    if (own) return { code: own, how: "class method" };
+    const b = bindingsOf(content)[member[1]];
+    const f = b && src.resolveModuleFile(file, b.spec);
+    const text = f && src.readSource(f);
+    const code = text && findInSource(text, member[2]);
+    if (code) return { code: code, how: "imported (" + path.basename(f) + ")" };
+    return { code: null, how: "member '" + expr + "' not found" };
+  }
+  if (/^[A-Za-z_$][\w$]*$/.test(expr)) return locateNamed(expr, file, content);
+
+  if (/=>|\bfunction\b/.test(expr))
+    return { code: expr, how: "inline (wrapped)" };
+  const names = (expr.match(/[A-Za-z_$][\w$]*/g) || []).slice(1);
+  for (const n of names) {
+    const r = locateNamed(n, file, content);
+    if (r.code) return r;
+  }
+  return { code: null, how: "not found in '" + expr.slice(0, 40) + "'" };
+}
+
+function locateNamed(name, file, content) {
+  let code = findNamedHandlerCode(content, name);
+  if (code) return { code: code, how: "named function" };
+  const b = bindingsOf(content)[name];
+  if (b) {
+    const f = src.resolveModuleFile(file, b.spec);
+    const text = f && src.readSource(f);
+    code =
+      text && findInSource(text, b.imported === "default" ? name : b.imported);
+    if (code) return { code: code, how: "imported (" + path.basename(f) + ")" };
+  }
+  return { code: null, how: "'" + name + "' not found" };
+}
+
+// ── Finding the Fastify instance names used in a file ────────────────────────
+function collectInstanceNames(code) {
+  const names = new Set(BASE_NAMES);
+  const pkg = new Set(["Fastify", "fastify"]);
+  for (const m of code.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\s*\(\s*['"]fastify['"]\s*\)\s*;?/g,
+  ))
+    pkg.add(m[1]);
+  for (const m of code.matchAll(
+    /import\s+([A-Za-z_$][\w$]*)\s*(?:,\s*\{[^}]*\})?\s*from\s*['"]fastify['"]/g,
+  ))
+    pkg.add(m[1]);
+  // const x = require("fastify")(...)  /  const x = Fastify(...)
+  for (const m of code.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:await\s+)?(?:require\s*\(\s*['"]fastify['"]\s*\)|([A-Za-z_$][\w$]*))\s*(?:<[^()]*>)?\(/g,
+  )) {
+    if (!m[2] || pkg.has(m[2])) names.add(m[1]);
+  }
+  // Plugin functions: first parameter of a function that looks like a Fastify plugin
+  const heads = [
+    /\bfunction\s*\*?\s*[\w$]*\s*\(\s*([A-Za-z_$][\w$]*)\s*(\??\s*:\s*[^,)=]+)?\s*(?:,\s*([A-Za-z_$][\w$]*)[^,)]*)?\)/g,
+    /\(\s*([A-Za-z_$][\w$]*)\s*(\??\s*:\s*[^,)=]+)?\s*(?:,\s*([A-Za-z_$][\w$]*)[^,)]*)?\)\s*(?::\s*[^=;{]+)?=>/g,
+  ];
+  heads.forEach(function (re) {
+    for (const m of code.matchAll(re)) {
+      const before = code.slice(Math.max(0, m.index - 60), m.index);
+      const typed = /Fastify/.test(m[2] || "");
+      const optsLike =
+        /^_?(opts|options|done|next|pluginOptions|pluginOpts)$/i.test(
+          m[3] || "",
+        );
+      const ctxOk =
+        /(?:module\.exports\s*=|exports\.[\w$]+\s*=|export\s+default|\.register\s*\(\s*)\s*(?:\w+\s*\(\s*)?(?:async\s+)?$/.test(
+          before,
+        );
+      if (typed || optsLike || ctxOk) names.add(m[1]);
+    }
+  });
+  // this.server = server  (instance stored on a class)
+  const members = new Set();
+  for (const m of code.matchAll(
+    /\bthis\s*\.\s*([A-Za-z_$][\w$]*)\s*=\s*([A-Za-z_$][\w$]*)\b/g,
+  )) {
+    if (names.has(m[2])) members.add("this." + m[1]);
+  }
+  BASE_NAMES.forEach(function (n) {
+    members.add("this." + n);
+  });
+  return { names: names, members: members };
+}
+
+// ── Plugin registration (prefixes) ───────────────────────────────────────────
+function prefixFromOptions(optText, file) {
+  if (!optText) return { prefix: "", ok: true };
+  let t = optText.trim();
+  if (/^[A-Za-z_$][\w$]*$/.test(t)) {
+    const f = src.lookupConst(t, file);
+    if (f) t = f.expr;
+  }
+  const o = readObj(t);
+  if (!o || o.prefix === undefined) return { prefix: "", ok: true, obj: o };
+  const v = src.resolveStringExpr(o.prefix, file);
+  return v === null
+    ? {
+        prefix: "",
+        ok: false,
+        why: "prefix value cannot be read statically: " + o.prefix,
+        obj: o,
+      }
+    : { prefix: v, ok: true, obj: o };
+}
+
+function resolveDirExpr(expr, file, cwd) {
+  const e = String(expr || "").trim();
+  const call = /^(?:path\s*\.\s*)?(?:join|resolve)\s*\(([\s\S]*)\)$/.exec(e);
+  if (call) {
+    let cur = null;
+    for (const p of splitStaticEntries(call[1]) || []) {
+      const t = p.trim();
+      const seg =
+        t === "__dirname"
+          ? path.dirname(file)
+          : t === "process.cwd()"
+            ? cwd
+            : src.resolveStringExpr(t, file);
+      if (seg === null) return null;
+      cur = cur === null ? seg : path.resolve(cur, seg);
+    }
+    return cur ? path.resolve(cur) : null;
+  }
+  if (e === "__dirname") return path.dirname(file);
+  const s = src.resolveStringExpr(e, file);
+  return s === null ? null : path.resolve(path.dirname(file), s);
+}
+
+function resolvePluginTarget(expr, file, content) {
+  let e = String(expr || "").trim();
+  if (
+    /^(?:async\b|function\b|\()/.test(e) ||
+    /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(e)
+  )
+    return { kind: "inline" };
+  // wrapper such as fp(require("./x")) or fp(plugin)
+  const wrap = /^[\w$.]+\s*\(\s*([\s\S]+?)\s*(?:,[\s\S]*)?\)$/.exec(e);
+  if (wrap && !/^require\s*\(/.test(e)) e = wrap[1].trim();
+  let spec = null;
+  const req = /^require\s*\(\s*['"]([^'"]+)['"]\s*\)(?:\s*\.\s*[\w$]+)?$/.exec(
+    e,
+  );
+  if (req) spec = req[1];
+  else {
+    const id = /^([A-Za-z_$][\w$]*)(?:\s*\.\s*[\w$]+)?$/.exec(e);
+    if (id) {
+      const b = bindingsOf(content)[id[1]];
+      if (b) spec = b.spec;
+    }
+  }
+  if (!spec) return { kind: "unknown" };
+  if (/autoload/i.test(spec)) return { kind: "autoload" };
+  const f = src.resolveModuleFile(file, spec);
+  return f ? { kind: "file", file: path.resolve(f) } : { kind: "external" };
+}
+
+function analyzeFile(file, content, cwd) {
+  const code = blankOutComments(content);
+  const masked = maskNonCode(content);
+  const inst = collectInstanceNames(code);
+  const info = {
+    file: file,
+    content: content,
+    masked: masked,
+    names: inst.names,
+    members: inst.members,
+    registers: [],
+    problems: [],
+  };
+  const re = /\.\s*register\s*(?:<[^()]*?>)?\s*\(/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    const parenAt = m.index + m[0].length - 1;
+    const call = sliceCallText(content, parenAt);
+    if (!call) continue;
+    const args = splitStaticEntries(call.slice(1, -1)) || [];
+    if (!args[0]) continue;
+    const plugin = resolvePluginTarget(args[0], file, content);
+    const opts = prefixFromOptions(args[1], file);
+    if (!opts.ok)
+      info.problems.push(
+        "register() at line " + lineAt(content, m.index) + ": " + opts.why,
+      );
+    const reg = {
+      index: m.index,
+      end: parenAt + call.length,
+      line: lineAt(content, m.index),
+      plugin: plugin,
+      prefix: opts.prefix,
+    };
+    if (plugin.kind === "autoload") {
+      const o = opts.obj || {};
+      const dir = o.dir ? resolveDirExpr(o.dir, file, cwd) : null;
+      const inner = o.options ? readObj(o.options) : null;
+      let optPrefix = "";
+      if (inner && inner.prefix !== undefined) {
+        const v = src.resolveStringExpr(inner.prefix, file);
+        optPrefix = v === null ? "" : v;
+      }
+      reg.auto = {
+        dir: dir,
+        prefix: optPrefix,
+        folderPrefix: !(
+          o.dirNameRoutePrefix && /^false$/.test(o.dirNameRoutePrefix.trim())
+        ),
+        routeParams: !!(o.routeParams && /^true$/.test(o.routeParams.trim())),
+      };
+      if (!dir)
+        info.problems.push(
+          "autoload at line " +
+            reg.line +
+            ": 'dir' cannot be read statically (" +
+            (o.dir || "missing") +
+            ")",
+        );
+    }
+    if (plugin.kind === "unknown")
+      info.problems.push(
+        "register() at line " +
+          reg.line +
+          ": plugin '" +
+          args[0].slice(0, 40) +
+          "' cannot be resolved to a file",
+      );
+    info.registers.push(reg);
+  }
+  return info;
+}
+
+// Prefix added by inline plugins ( register(async (i) => {...}, { prefix }) ) around a position
+function inlinePrefixAt(info, index) {
+  return info.registers
+    .filter(function (r) {
+      return r.plugin.kind === "inline" && r.index < index && index < r.end;
+    })
+    .sort(function (a, b) {
+      return a.index - b.index;
+    })
+    .reduce(function (acc, r) {
+      return joinMountPath(acc, r.prefix);
+    }, "");
+}
+
+function methodsFromExpr(expr, file) {
+  if (!expr) return [];
+  const t = expr.trim();
+  const items =
+    t.charAt(0) === "["
+      ? splitStaticEntries(
+          t.slice(
+            1,
+            src.matchClose(t, 0) === -1 ? t.length : src.matchClose(t, 0),
+          ),
+        ) || []
+      : [t];
+  const out = [];
+  items.forEach(function (it) {
+    const v = src.resolveStringExpr(it, file);
+    if (v && HTTP_METHODS.indexOf(v.toUpperCase()) !== -1)
+      out.push(v.toUpperCase());
+  });
+  return out;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+function scanFastifyRoutes(cwd) {
+  cwd = path.resolve(cwd);
+  src.setProjectRoot(cwd);
+
+  // 1. Read every source file (tests and type declarations are skipped)
+  const infos = {};
+  (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);
+        continue;
+      }
+      if (!/\.(?:[cm]?js|[cm]?ts)$/.test(entry)) continue;
+      const rel = path.relative(cwd, full);
+      if (isIgnoredFile(rel) || stat.size > 2 * 1024 * 1024) continue;
+      let content;
+      try {
+        content = fs.readFileSync(full, "utf8");
+      } catch (e) {
+        continue;
+      }
+      infos[path.resolve(full)] = analyzeFile(path.resolve(full), content, cwd);
+    }
+  })(cwd, 0);
+  const files = Object.keys(infos);
+
+  // 2. Who registers whom, and under which prefix
+  const incoming = {};
+  function addEdge(target, parent, prefix) {
+    (incoming[target] = incoming[target] || []).push({
+      parent: parent,
+      prefix: prefix,
+    });
+  }
+  files.forEach(function (f) {
+    const info = infos[f];
+    info.registers.forEach(function (reg) {
+      const local = joinMountPath(inlinePrefixAt(info, reg.index), reg.prefix);
+      if (reg.plugin.kind === "file" && infos[reg.plugin.file])
+        addEdge(reg.plugin.file, f, local);
+      if (reg.plugin.kind === "autoload" && reg.auto && reg.auto.dir) {
+        files.forEach(function (t) {
+          const relDir = path.relative(reg.auto.dir, path.dirname(t));
+          if (t === f || relDir.startsWith("..") || path.isAbsolute(relDir))
+            return;
+          let segs = relDir ? relDir.split(path.sep) : [];
+          if (!reg.auto.folderPrefix) segs = [];
+          segs = segs.map(function (s) {
+            return reg.auto.routeParams && s.charAt(0) === "_"
+              ? ":" + s.slice(1)
+              : s;
+          });
+          addEdge(
+            t,
+            f,
+            joinMountPath(
+              joinMountPath(local, reg.auto.prefix),
+              segs.join("/"),
+            ),
+          );
+        });
+      }
+    });
+  });
+  const memo = {};
+  function prefixesOf(file, stack) {
+    if (memo[file]) return memo[file];
+    const inc = incoming[file];
+    if (!inc || !inc.length || stack.has(file)) return [""];
+    stack.add(file);
+    const out = new Set();
+    inc.forEach(function (e) {
+      prefixesOf(e.parent, stack).forEach(function (pp) {
+        const j = joinMountPath(pp, e.prefix);
+        out.add(j === "/" ? "" : j);
+      });
+    });
+    stack.delete(file);
+    memo[file] = Array.from(out);
+    return memo[file];
+  }
+
+  // 3. Routes
+  const endpoints = [];
+  const seen = new Set();
+  const callRe =
+    /(?<![\w$.])((?:this\s*\.\s*)?[A-Za-z_$][\w$]*)\s*\.\s*(get|post|put|delete|patch|all|route)\s*(<[^()]*?>)?\s*\(/g;
+
+  files.forEach(function (file) {
+    const info = infos[file];
+    const rel = path.relative(cwd, file);
+    const found = [];
+    let m;
+    callRe.lastIndex = 0;
+    while ((m = callRe.exec(info.masked)) !== null) {
+      const recv = m[1].replace(/\s+/g, "");
+      const okRecv = recv.startsWith("this.")
+        ? info.members.has(recv)
+        : info.names.has(recv);
+      if (!okRecv) continue;
+      const parenAt = m.index + m[0].length - 1;
+      const call = sliceCallText(info.content, parenAt);
+      const args = call ? splitStaticEntries(call.slice(1, -1)) : null;
+      if (!args || !args.length) {
+        info.problems.push(
+          "line " +
+            lineAt(info.content, m.index) +
+            ": cannot read the arguments of ." +
+            m[2] +
+            "(...)",
+        );
+        continue;
+      }
+      let methods;
+      let pathExpr;
+      let handlerExpr;
+      let schemaText = null;
+      if (m[2] === "route") {
+        const o = readObj(args[0]);
+        if (!o) {
+          info.problems.push(
+            "line " +
+              lineAt(info.content, m.index) +
+              ": .route(...) argument is not an object written in code",
+          );
+          continue;
+        }
+        methods = methodsFromExpr(o.method, file);
+        pathExpr = o.url !== undefined ? o.url : o.path;
+        handlerExpr = o.handler;
+        schemaText = o.schema || null;
+      } else {
+        methods =
+          m[2] === "all" ? [ALL_METHOD_STORED_AS] : [m[2].toUpperCase()];
+        pathExpr = args[0];
+        const second = args[1] ? readObj(args[1]) : null;
+        handlerExpr = second
+          ? second.handler || args[2]
+          : args[args.length - 1];
+        schemaText = second && second.schema ? second.schema : null;
+        if (args.length === 1 && !second) handlerExpr = null;
+      }
+      if (!methods.length || pathExpr === undefined) {
+        info.problems.push(
+          "line " +
+            lineAt(info.content, m.index) +
+            ": method or path of ." +
+            m[2] +
+            "(...) cannot be read",
+        );
+        continue;
+      }
+      const routePath = src.resolveStringExpr(pathExpr, file);
+      if (routePath === null) {
+        info.problems.push(
+          "line " +
+            lineAt(info.content, m.index) +
+            ": path '" +
+            String(pathExpr).slice(0, 40) +
+            "' cannot be read statically",
+        );
+        continue;
+      }
+      found.push({
+        index: m.index,
+        line: lineAt(info.content, m.index),
+        methods: methods,
+        routePath: routePath,
+        handlerExpr: handlerExpr,
+        schemaText: schemaText,
+        generics: readGenerics(m[3], file),
+      });
+    }
+    if (!found.length && !info.problems.length) return;
+
+    const prefixes = prefixesOf(file, new Set());
+
+    found.forEach(function (r) {
+      const local = inlinePrefixAt(info, r.index);
+      const h = locateHandler(r.handlerExpr, file, info.content, r.index);
+      const param = h.code ? firstParamName(h.code) : null;
+      const handlerCode = h.code
+        ? blankOutComments(normalizeHandlerCode(h.code, param))
+        : "";
+      const so = r.schemaText ? readObj(r.schemaText) : null;
+      const bodyDeclared =
+        (so && so.body ? jsonSchemaFromText(so.body, file, 0) : null) ||
+        r.generics.Body ||
+        null;
+      const queryDeclared =
+        (so && (so.querystring || so.query)
+          ? jsonSchemaFromText(so.querystring || so.query, file, 0)
+          : null) ||
+        r.generics.Querystring ||
+        null;
+      let respDeclared =
+        (so && so.response ? pickSuccessResponse(so.response, file) : null) ||
+        r.generics.Reply ||
+        null;
+      if (respDeclared && !usefulReply(respDeclared)) respDeclared = null;
+
+      const sharedHandler = r.methods.length > 1;
+      r.methods.forEach(function (method) {
+        const needsBody = ["POST", "PUT", "PATCH"].indexOf(method) !== -1;
+        const bodyFromCode =
+          needsBody && handlerCode
+            ? extractBodyFieldsFromFile(handlerCode)
+            : null;
+        const bodyMerged = needsBody
+          ? mergeFieldSchemas(bodyFromCode, bodyDeclared)
+          : null;
+        let requestBody = null;
+        if (needsBody) {
+          const mp1 = handlerCode ? fastifyMultipartFields(handlerCode) : null;
+          const mp2 = handlerCode
+            ? extractMultipartFieldsFromFile(handlerCode)
+            : null;
+          requestBody = mergeBodyWithMultipart(
+            bodyMerged,
+            mergeBodyWithMultipart(mp1, mp2),
+          );
+        }
+        const queryCode = handlerCode
+          ? extractQueryFieldsFromFile(handlerCode)
+          : null;
+        const queryMerged = mergeFieldSchemas(queryCode, queryDeclared);
+
+        // Reply shape; a handler shared by several methods cannot be split safely, so none is guessed
+        let responseBody = null;
+        if (!sharedHandler) {
+          responseBody = respDeclared
+            ? Object.assign({}, respDeclared, { _source: "static" })
+            : null;
+          if (!responseBody && handlerCode) {
+            const bodyTypes = {};
+            const bp = (bodyMerged && bodyMerged.properties) || {};
+            Object.keys(bp).forEach(function (k) {
+              bodyTypes[k] = bp[k];
+            });
+            const aliases = new Set();
+            for (const a of handlerCode.matchAll(
+              /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*req\s*\.\s*body\s*(?:as\s+[^;]+)?;/g,
+            ))
+              aliases.add(a[1]);
+            responseBody = responseFromCode(handlerCode, {
+              code: handlerCode,
+              bodyTypes: bodyTypes,
+              aliases: aliases,
+            });
+          }
+        }
+
+        prefixes.forEach(function (prefix) {
+          const fullPath = joinMountPath(
+            joinMountPath(prefix, local),
+            r.routePath,
+          );
+          const key = method + ":" + fullPath;
+          if (seen.has(key)) {
+            return;
+          }
+          seen.add(key);
+          if (method === "GET" || method === "DELETE")
+            requestBody = removePathParamFields(queryMerged, fullPath);
+          endpoints.push({
+            method: method,
+            path: fullPath,
+            description: "",
+            requestBody: requestBody,
+            responseBody: responseBody,
+            routeParamMap: buildRouteParamMap(fullPath, []),
+            detectedBy: "static-scan-fastify",
+          });
+          const fl = function (s) {
+            return s && s.properties
+              ? JSON.stringify(Object.keys(s.properties))
+              : s && s.type === "array"
+                ? "[array]"
+                : "null";
+          };
+        });
+      });
+    });
+  });
+
+  return endpoints;
+}
+
+module.exports = {
+  scanFastifyRoutes,
+};