botversion-sdk 2.2.2 → 2.3.0

package/scanner-sdk/scan/nuxt-value-types.js

@@ -0,0 +1,521 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/nuxt-value-types.js
+// PURPOSE: Nuxt: works out value types by tracing names back to the code that defines them (h3 helpers like readBody/getQuery), and reads TypeScript types.
+// CONTAINS: inferExprType, arrayOfObjectsType, inferReturnedShape, typeMembersOf
+// USED BY: scan/response-shape.js, scan/nuxt.js
+// DEPENDS ON: ./text-utils, ./response-shape (loaded lazily)
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const {
+  findStaticClosingBrace,
+  sliceCallText,
+  skipStaticString,
+} = require("./text-utils");
+
+// loaded on use, because response-shape also loads this file
+function getRs() {
+  return require("./response-shape");
+}
+
+const STRING_METHODS = new Set([
+  "toISOString",
+  "toUTCString",
+  "toLocaleString",
+  "toLocaleDateString",
+  "toLocaleTimeString",
+  "toLowerCase",
+  "toUpperCase",
+  "trim",
+  "trimStart",
+  "trimEnd",
+  "padStart",
+  "padEnd",
+  "toFixed",
+  "join",
+  "replace",
+  "replaceAll",
+  "substring",
+  "substr",
+  "charAt",
+  "toString",
+  "normalize",
+  "repeat",
+]);
+const BOOL_METHODS = new Set([
+  "includes",
+  "startsWith",
+  "endsWith",
+  "some",
+  "every",
+  "has",
+  "test",
+]);
+const NUMBER_METHODS = new Set([
+  "indexOf",
+  "lastIndexOf",
+  "getTime",
+  "findIndex",
+  "charCodeAt",
+  "push",
+]);
+const ARRAY_METHODS = new Set([
+  "map",
+  "filter",
+  "sort",
+  "reverse",
+  "flat",
+  "flatMap",
+  "split",
+]);
+const STRING_CALLS =
+  /^(?:getRouterParam|getHeader|getRequestHeader|getMethod|getCookie|getRequestHost|getRequestIP|randomUUID)\s*\(/;
+
+// Reads the expression that starts at "start" (up to the end of the statement)
+function readExpr(code, start) {
+  let depth = 0;
+  for (let i = start; i < code.length && i < start + 3000; i++) {
+    const ch = code[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipStaticString(code, i, code.length);
+      if (end === -1) break;
+      i = end;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      if (depth === 0) return code.slice(start, i).trim();
+      depth--;
+    } else if (depth === 0 && ch === ";") {
+      return code.slice(start, i).trim();
+    } else if (depth === 0 && ch === "\n") {
+      const before = code.slice(start, i).trim();
+      const after = /^\s*(\S{1,2})/.exec(code.slice(i + 1));
+      const nextTok = after ? after[1] : "";
+      // the statement goes on when the line ends or the next line starts with an operator
+      if (
+        /[+\-*/&|?:,=<>]$/.test(before) ||
+        /^(\.|\?|:|&&|\|\||\+)/.test(nextTok)
+      )
+        continue;
+      return before;
+    }
+  }
+  return code.slice(start, start + 500).trim();
+}
+
+// The value a variable is set to: const name = <this>
+function declInit(code, name) {
+  const safe = String(name).replace(/\$/g, "\\$");
+  const m = new RegExp(
+    "(?:const|let|var)\\s+" + safe + "\\s*(?::[^=;\\n]+)?=(?!=)\\s*",
+  ).exec(code);
+  return m ? readExpr(code, m.index + m[0].length) : null;
+}
+
+// const { a, b: c } = getQuery(event)  ->  where a name comes from (body, query or params) and its key
+function destructuredSource(code, name) {
+  for (const m of code.matchAll(
+    /(?:const|let|var)\s*\{([^}]*)\}\s*(?::[^=]+)?=\s*(?:await\s+)?([^\n;]+)/g,
+  )) {
+    const rhs = m[2];
+    let kind = null;
+    if (/\b(?:readBody|readValidatedBody|readRawBody)\b/.test(rhs))
+      kind = "body";
+    else if (/\b(?:getQuery|getValidatedQuery)\b/.test(rhs)) kind = "query";
+    else if (/\bgetRouterParams\b|context\.params/.test(rhs)) kind = "params";
+    if (!kind) continue;
+    for (const piece of m[1].split(",")) {
+      const parts = piece.split("=")[0].split(":");
+      const key = parts[0].trim();
+      const local = (parts[1] || parts[0]).trim();
+      if (local === name) return { kind: kind, key: key };
+    }
+  }
+  return null;
+}
+
+// First operator found outside brackets and strings (null if none, or if the text is an arrow function)
+function findTop(e, tokens, accept) {
+  let depth = 0;
+  for (let i = 0; i < e.length; i++) {
+    const ch = e[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipStaticString(e, i, e.length);
+      if (end === -1) return null;
+      i = end;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") depth--;
+    else if (depth === 0) {
+      if (ch === "=" && e[i + 1] === ">") return null;
+      for (const t of tokens) {
+        if (e.startsWith(t, i) && (!accept || accept(e, i, t)))
+          return { i: i, token: t };
+      }
+    }
+  }
+  return null;
+}
+
+// "a.b(x).c(y)" -> { name: "c", recv: "a.b(x)" } (the call that ends the expression)
+function tailCall(e) {
+  const re = /(\?\.|\.)\s*([A-Za-z_$][\w$]*)\s*(?:<[^>()]*>)?\s*\(/g;
+  let m;
+  while ((m = re.exec(e)) !== null) {
+    const open = m.index + m[0].length - 1;
+    const call = sliceCallText(e, open);
+    if (call && open + call.length === e.length)
+      return { name: m[2], recv: e.slice(0, m.index).trim() };
+  }
+  return null;
+}
+
+function cloneType(t) {
+  return t ? Object.assign({}, t) : null;
+}
+
+function fromSource(kind, key, ctx) {
+  if (kind === "params") return { type: "string" };
+  const map = kind === "body" ? ctx.body : ctx.query;
+  return map && map[key] ? cloneType(map[key]) : null;
+}
+
+function helperCtx(ctx, helperCode) {
+  return Object.assign({}, ctx, { code: helperCode, body: null, query: null });
+}
+
+// Which request part a variable's value is read from (body, query, params) or null
+function sourceKindOfInit(init, ctx) {
+  if (
+    /^\{\s*\.\.\.\s*\(?\s*(?:await\s+)?(?:readBody|readValidatedBody)\b/.test(
+      init,
+    )
+  )
+    return "body";
+  if (/^(?:await\s+)?(?:readBody|readValidatedBody)\b/.test(init))
+    return "body";
+  if (
+    /\.\s*(?:parse|safeParse|parseAsync)\s*\(\s*(?:await\s+)?(?:readBody|readValidatedBody)\b/.test(
+      init,
+    )
+  )
+    return "body";
+  if (/^(?:await\s+)?(?:getQuery|getValidatedQuery)\b/.test(init))
+    return "query";
+  if (/^(?:await\s+)?getRouterParams\b|context\.params/.test(init))
+    return "params";
+  if (/^JSON\s*\.\s*parse\s*\(\s*(?:await\s+)?readRawBody\b/.test(init))
+    return "body";
+  const m = /^JSON\s*\.\s*parse\s*\(\s*([A-Za-z_$][\w$]*)\s*\)$/.exec(init);
+  if (m) {
+    const inner = declInit(ctx.code, m[1]);
+    if (inner && /^(?:await\s+)?readRawBody\b/.test(inner)) return "body";
+  }
+  return null;
+}
+
+// "variable.prop": the type of one field of a variable
+function memberType(v, prop, ctx) {
+  const init = declInit(ctx.code, v);
+  if (init) {
+    const kind = sourceKindOfInit(init, ctx);
+    if (kind) return fromSource(kind, prop, ctx);
+    // a helper function's result: read the object the helper returns
+    const call = /^(?:await\s+)?([A-Za-z_$][\w$]*)\s*\(/.exec(init);
+    if (call && ctx.findHelper) {
+      const h = ctx.findHelper(call[1]);
+      if (h) {
+        const f = getRs().returnedObjectFields(h, helperCtx(ctx, h));
+        if (f && f.properties[prop]) return f.properties[prop];
+      }
+    }
+  }
+  // an uploaded part has a text name, file name and content type
+  if (
+    /readMultipartFormData|readFormData/.test(ctx.code) &&
+    /^(filename|type|name)$/.test(prop)
+  )
+    return { type: "string" };
+  return null;
+}
+
+// Best-effort type of an expression written in code; null when it cannot be told
+function inferExprType(expr, ctx, depth) {
+  depth = depth || 0;
+  if (!expr || !ctx || depth > 6) return null;
+  let e = String(expr)
+    .trim()
+    .replace(/^await\s+/, "");
+  e = e
+    .replace(/\s+as\s+[\w$.<>\[\]| ]+$/, "")
+    .replace(/!$/, "")
+    .trim();
+  if (!e) return null;
+  if (e[0] === "(") {
+    const c = sliceCallText(e, 0);
+    if (c && c.length === e.length)
+      return inferExprType(e.slice(1, -1), ctx, depth + 1);
+  }
+  if (/^\[\s*\{/.test(e)) return arrayOfObjectsType(e, ctx);
+  const lit = getRs().guessStaticValueType(e);
+  if (lit.type !== "unknown") return lit;
+
+  // a ternary has two possible results: not guessed
+  if (
+    findTop(e, ["?"], function (s, i) {
+      return s[i + 1] !== "?" && s[i + 1] !== "." && s[i - 1] !== "?";
+    })
+  )
+    return null;
+  // a ?? b  /  a || b: the type of a, or of b when a is not known
+  const nul = findTop(e, ["??", "||"]);
+  if (nul) {
+    const left = inferExprType(e.slice(0, nul.i), ctx, depth + 1);
+    if (left && left.type !== "unknown") return left;
+    return inferExprType(e.slice(nul.i + 2), ctx, depth + 1);
+  }
+  if (findTop(e, ["&&"])) return null;
+  // comparisons are always true/false
+  if (
+    findTop(
+      e,
+      ["===", "!==", "==", "!=", ">=", "<=", "<", ">"],
+      function (s, i, t) {
+        return (
+          (t !== "<" && t !== ">") || (s[i - 1] === " " && s[i + 1] === " ")
+        );
+      },
+    )
+  )
+    return { type: "boolean" };
+  if (e[0] !== "/") {
+    const plus = findTop(e, ["+"], function (s, i) {
+      return i > 0 && s[i + 1] !== "+" && s[i - 1] !== "+" && s[i + 1] !== "=";
+    });
+    if (plus) {
+      const l = inferExprType(e.slice(0, plus.i), ctx, depth + 1);
+      const r = inferExprType(e.slice(plus.i + 1), ctx, depth + 1);
+      if ((l && l.type === "string") || (r && r.type === "string"))
+        return { type: "string" };
+      if (l && r && l.type === "number" && r.type === "number")
+        return { type: "number" };
+      return null;
+    }
+    if (
+      findTop(e, ["-", "*", "/", "%"], function (s, i, t) {
+        return (
+          i > 0 &&
+          s[i - 1] !== t &&
+          s[i + 1] !== t &&
+          s[i + 1] !== "=" &&
+          !(t === "/" && s[i + 1] === "*")
+        );
+      })
+    )
+      return { type: "number" };
+  }
+  if (/\.\s*length$/.test(e)) return { type: "number" };
+
+  const tc = tailCall(e);
+  if (tc) {
+    const n = tc.name;
+    const r = tc.recv;
+    if (r === "Math") return { type: "number" };
+    if (r === "Date" && n === "now") return { type: "number" };
+    if (r === "JSON" && n === "stringify") return { type: "string" };
+    if (r === "Array" && (n === "from" || n === "of"))
+      return { type: "array", items: { type: "unknown" } };
+    if (r === "Object" && (n === "keys" || n === "values" || n === "entries"))
+      return { type: "array", items: { type: "unknown" } };
+    if (n === "slice" || n === "concat") {
+      const rt = inferExprType(r, ctx, depth + 1);
+      if (rt && rt.type === "array")
+        return { type: "array", items: rt.items || { type: "unknown" } };
+      if (rt && rt.type === "string") return { type: "string" };
+      return null;
+    }
+    if (STRING_METHODS.has(n)) return { type: "string" };
+    if (BOOL_METHODS.has(n)) return { type: "boolean" };
+    if (NUMBER_METHODS.has(n)) return { type: "number" };
+    if (ARRAY_METHODS.has(n))
+      return { type: "array", items: { type: "unknown" } };
+  }
+
+  // h3 helper calls that always give text
+  if (STRING_CALLS.test(e)) {
+    const open = e.indexOf("(");
+    const c = sliceCallText(e, open);
+    if (c && open + c.length === e.length) return { type: "string" };
+  }
+
+  // getQuery(event).q  /  (await readBody(event)).x
+  let m =
+    /^\(?\s*(?:await\s+)?(readBody|readValidatedBody|getQuery|getValidatedQuery|getRouterParams)\s*(?:<[^>]*>)?\s*\(([^()]*)\)\s*\)?\s*\??\.\s*([A-Za-z_$][\w$]*)$/.exec(
+      e,
+    );
+  if (m) {
+    const kind = /Body/.test(m[1])
+      ? "body"
+      : /Query/.test(m[1])
+        ? "query"
+        : "params";
+    return fromSource(kind, m[3], ctx);
+  }
+  // variable.prop
+  m = /^([A-Za-z_$][\w$]*)\s*\??\.\s*([A-Za-z_$][\w$]*)$/.exec(e);
+  if (m) return memberType(m[1], m[2], ctx);
+  // a plain name: destructured from the request, or set by a line above
+  m = /^[A-Za-z_$][\w$]*$/.exec(e);
+  if (m) {
+    const ds = destructuredSource(ctx.code, e);
+    if (ds) return fromSource(ds.kind, ds.key, ctx);
+    const init = declInit(ctx.code, e);
+    if (init && init !== e) return inferExprType(init, ctx, depth + 1);
+  }
+  return null;
+}
+
+// "[ { a: 1 }, ... ]" -> list type with the fields of the first item
+function arrayOfObjectsType(v, ctx) {
+  const open = v.indexOf("{");
+  if (open === -1) return null;
+  const close = findStaticClosingBrace(v, open);
+  if (close === null) return null;
+  const f = getRs().parseStaticObjectFields(v.slice(open + 1, close), ctx);
+  if (!f) return null;
+  return { type: "array", items: { type: "object", properties: f.properties } };
+}
+
+// Reply that is a variable ("return result", "return list.filter(...)") or a helper call ("return buildX(...)")
+function inferReturnedShape(code, ctx) {
+  const rs = getRs();
+  const re = /\breturn\s+(?:await\s+)?([A-Za-z_$][\w$]*)\s*([(.;\n}]|$)/g;
+  for (const m of code.matchAll(re)) {
+    const name = m[1];
+    const next = m[2];
+    if (
+      ["new", "null", "true", "false", "undefined", "void", "typeof"].indexOf(
+        name,
+      ) !== -1
+    )
+      continue;
+    if (next === "(") {
+      const h = ctx.findHelper ? ctx.findHelper(name) : null;
+      if (h) {
+        const f = rs.returnedObjectFields(h, helperCtx(ctx, h));
+        if (f) return f;
+      }
+      continue;
+    }
+    if (next === ".") {
+      const rest = code.slice(m.index + m[0].length - 1);
+      if (!/^\.\s*(filter|slice|sort|reverse|concat)\s*\(/.test(rest)) continue;
+    }
+    const init = declInit(code, name);
+    if (!init) continue;
+    if (/^\[\s*\{/.test(init)) {
+      const arr = arrayOfObjectsType(init, ctx);
+      if (arr) return { type: "array", items: arr.items, _source: "static" };
+    }
+    if (init[0] === "{") {
+      const close = findStaticClosingBrace(init, 0);
+      if (close !== null) {
+        const f = rs.parseStaticObjectFields(init.slice(1, close), ctx);
+        if (f) return f;
+      }
+    }
+  }
+  return null;
+}
+
+// ── TypeScript types ──────────────────────────────────────────
+function tsTypeToSchema(raw) {
+  const t = String(raw)
+    .trim()
+    .replace(/\s*\|\s*(?:null|undefined)\b/g, "")
+    .replace(/\b(?:null|undefined)\s*\|\s*/g, "")
+    .trim();
+  if (/^string$/.test(t) || /^Date$/.test(t) || /^['"`]/.test(t))
+    return { type: "string" };
+  if (/^(?:number|bigint)$/.test(t) || /^-?\d/.test(t))
+    return { type: "number" };
+  if (/^boolean$/.test(t) || /^(?:true|false)$/.test(t))
+    return { type: "boolean" };
+  if (/\[\]$/.test(t) || /^(?:Readonly)?Array\s*</.test(t))
+    return { type: "array", items: { type: "object" } };
+  if (/^\{/.test(t) || /^Record\s*</.test(t) || /^[Oo]bject$/.test(t))
+    return { type: "object" };
+  return { type: "unknown" };
+}
+
+// "name: string" lines of an interface or type body (members nested inside other members are skipped)
+function parseTypeMembers(inner) {
+  const props = {};
+  let depth = 0;
+  inner.split("\n").forEach(function (line) {
+    if (depth === 0) {
+      const m =
+        /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:\s*([^;,]+?)\s*[;,]?\s*$/.exec(
+          line,
+        );
+      if (m) props[m[1]] = tsTypeToSchema(m[2]);
+    }
+    depth +=
+      (line.match(/[{(\[]/g) || []).length -
+      (line.match(/[})\]]/g) || []).length;
+  });
+  return Object.keys(props).length ? props : null;
+}
+
+// Fields of "interface Name { ... }" / "type Name = { ... }" in this file or in a file it imports from
+function typeMembersOf(name, code, file, resolveImport, readSource, depth) {
+  depth = depth || 0;
+  if (!name || depth > 3) return null;
+  const safe = String(name).replace(/\$/g, "\\$");
+  const decl = new RegExp(
+    "(?:\\binterface\\s+" +
+      safe +
+      "(?:\\s*<[^>]*>)?(?:\\s+extends\\s+[^{]+)?\\s*\\{|\\btype\\s+" +
+      safe +
+      "(?:\\s*<[^>]*>)?\\s*=\\s*\\{)",
+  ).exec(code);
+  if (decl) {
+    const open = decl.index + decl[0].length - 1;
+    const close = findStaticClosingBrace(code, open);
+    if (close !== null) return parseTypeMembers(code.slice(open + 1, close));
+  }
+  for (const m of code.matchAll(
+    /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g,
+  )) {
+    for (const piece of m[1].split(",")) {
+      const parts = piece
+        .trim()
+        .replace(/^type\s+/, "")
+        .split(/\s+as\s+/);
+      if ((parts[1] || parts[0]).trim() !== name) continue;
+      const f = resolveImport(m[2], file);
+      const c = f && readSource(f);
+      if (c) {
+        const r = typeMembersOf(
+          parts[0].trim(),
+          c,
+          f,
+          resolveImport,
+          readSource,
+          depth + 1,
+        );
+        if (r) return r;
+      }
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  inferExprType,
+  arrayOfObjectsType,
+  inferReturnedShape,
+  typeMembersOf,
+};