hullproof 0.0.0-stage → 0.5.0

package/src/map/go.ts

@@ -0,0 +1,271 @@
+// Go entry points: net/http (ServeMux, including the Go 1.22 "METHOD /path" patterns), chi, gin, echo, fiber and gorilla/mux.
+// Router variables are followed in order inside a function (Group, Route, With, Use, PathPrefix), routers handed in as
+// parameters are read at the prefix the file can see, and a Mount or a router returned by a function is followed to its
+// definition. Pattern based, like the other extractors; every fact carries a confidence.
+import type { EntryPoint, Scope } from '../types/index.ts';
+import type { FileView } from './analyze.ts';
+import { empty, joinPath, makeEntry, type Extracted } from './entry.ts';
+import { goFunc, type FnIndex } from './light-index.ts';
+import { analyzeLight, type LightDeco } from './light.ts';
+import { closeOf, splitArgs } from './lex.ts';
+import type { LocalVocab } from './local-vocab.ts';
+import type { Repo } from './repo.ts';
+
+interface Mw { view: FileView; start: number; end: number; scope: Scope; only: string | null }
+interface Env { prefix: string; mws: Mw[]; fw: string; param: boolean }
+interface FnRef { file: string; view: FileView; start: number; end: number; bodyStart: number; params: string; name: string }
+interface MountCall { prefix: string; mws: Mw[]; fw: string; targets: string[]; from: string }
+
+const ROUTER_TYPE = /\*?(?:gin\.(?:Engine|RouterGroup|IRouter|IRoutes)|chi\.(?:Router|Mux)|echo\.(?:Echo|Group)|fiber\.(?:App|Router)|mux\.Router|http\.ServeMux)\b/;
+const FW_BY_IMPORT: [RegExp, string][] = [[/gin-gonic\/gin/, 'gin'], [/go-chi\/chi/, 'chi'], [/labstack\/echo/, 'echo'], [/gofiber\/fiber/, 'fiber'], [/gorilla\/mux/, 'gorilla-mux']];
+const METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', 'TRACE']);
+const CREATE = /(?<![\w.])([A-Za-z_]\w*)\s*(?::=|=)\s*(?:chi\.NewRouter|chi\.NewMux|gin\.Default|gin\.New|echo\.New|fiber\.New|mux\.NewRouter|http\.NewServeMux|NewRouter|NewServeMux)\s*\(/g;
+const ROUTE_CALLS = new Set(['Get', 'Post', 'Put', 'Patch', 'Delete', 'Head', 'Options', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'Any', 'All', 'Handle', 'HandleFunc', 'Method', 'MethodFunc', 'Match', 'Add', 'Connect', 'Trace', 'Mount', 'Use', 'Group', 'Route', 'With', 'PathPrefix', 'Subrouter', 'Static']);
+
+const unq = (s: string): string | null => /^\s*(?:"((?:\\.|[^"\\])*)"|`([^`]*)`)\s*$/.exec(s)?.slice(1).find((x) => x !== undefined) ?? null;
+
+export function goFiles(repo: Repo): string[] {
+  return repo.filesOf('go').filter((f) => { const v = repo.view(f); return !!v && /net\/http|gin-gonic|go-chi|labstack\/echo|gofiber|gorilla\/mux/.test(v.imports); });
+}
+
+export function extractGoAll(repo: Repo, fn: FnIndex, local: LocalVocab | null): Extracted {
+  const out = empty();
+  const keyOf = (f: FnRef): string => `${f.file}#${f.start}`;
+  const funcs: FnRef[] = [];
+  for (const file of goFiles(repo)) {
+    const v = repo.view(file)!;
+    for (const x of v.masked.matchAll(/^func\s+(?:\(\s*\w*\s*\*?\s*[\w.[\]]+\s*\)\s*)?(\w+)\s*[([]/gm)) {
+      const f = goFunc(v.masked, x.index!);
+      if (f) funcs.push({ file, view: v, start: f.start, end: f.end, bodyStart: f.bodyStart, params: f.params, name: x[1] });
+    }
+    // Package level routing, outside any function: var mux = http.NewServeMux(); func init() is a function and is covered above.
+  }
+  const scanned = new Map<string, { entries: EntryPoint[]; mounts: MountCall[] }>();
+  const mounted = new Map<string, Env>();
+  const scan = (f: FnRef, base: Env | null): { entries: EntryPoint[]; mounts: MountCall[] } => {
+    const r = scanFunction(repo, fn, local, f, base);
+    return r;
+  };
+  for (const f of funcs) scanned.set(keyOf(f), scan(f, null));
+  // Mounted routers: scan the function that builds them again at the mount prefix, and drop its standalone result.
+  const queue: MountCall[] = [...scanned.values()].flatMap((s) => s.mounts);
+  for (let depth = 0; depth < 4 && queue.length; depth++) {
+    const next: MountCall[] = [];
+    for (const m of queue.splice(0)) {
+      for (const name of m.targets) {
+        const t = fn.defs(name).filter((d) => d.view.lang === 'go' && funcs.some((f) => f.file === d.view.file && f.start === d.start))[0];
+        if (!t) continue;
+        const ref = funcs.find((f) => f.file === t.view.file && f.start === t.start)!;
+        const key = keyOf(ref);
+        if (mounted.has(key)) continue;
+        const env: Env = { prefix: m.prefix, mws: m.mws, fw: m.fw, param: true };
+        mounted.set(key, env);
+        const res = scan(ref, env);
+        scanned.set(key, res);
+        next.push(...res.mounts);
+      }
+    }
+    queue.push(...next);
+  }
+  for (const [, s] of [...scanned.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) out.entries.push(...s.entries);
+  return out;
+}
+
+function scanFunction(repo: Repo, fn: FnIndex, local: LocalVocab | null, f: FnRef, base: Env | null): { entries: EntryPoint[]; mounts: MountCall[] } {
+  const v = f.view;
+  const fw0 = FW_BY_IMPORT.find(([re]) => re.test(v.imports))?.[1] ?? 'net-http';
+  const entries: EntryPoint[] = [];
+  const mounts: MountCall[] = [];
+  const env = new Map<string, Env>();
+  let baseUsed = false;
+  const fresh = (): Env => { if (base && !baseUsed) { baseUsed = true; return { ...base, mws: base.mws.slice() }; } return { prefix: '', mws: [], fw: fw0, param: false }; };
+  // Routers handed in as parameters.
+  for (const part of f.params.split(',')) {
+    const m = /^\s*(\w+)\s+(.+)$/.exec(part);
+    if (m && ROUTER_TYPE.test(m[2])) env.set(m[1], base ? { ...base, mws: base.mws.slice() } : { prefix: '', mws: [], fw: fw0, param: true });
+  }
+  if (base && env.size) baseUsed = true;
+  if (/"net\/http"/.test(v.imports)) env.set('http', { prefix: '', mws: [], fw: 'net-http', param: false });
+
+  const text = v.text;
+  const masked = v.masked;
+  const mwOf = (a: { start: number; end: number }, scope: Scope, only: string | null = null): Mw => ({ view: v, start: a.start, end: a.end, scope, only });
+
+  const route = (e: Env, recv: string, method: string, open: number, chained: Mw[], at: number, forced: string | null): void => {
+    const args = splitArgs(masked, open);
+    if (!args.length) return;
+    let verb: string | null = forced;
+    let pathIdx = 0;
+    if (method === 'Handle' && args.length >= 3 && unq(text.slice(args[0].start, args[0].end)) && METHODS.has(unq(text.slice(args[0].start, args[0].end))!)) { verb = unq(text.slice(args[0].start, args[0].end))!; pathIdx = 1; }
+    if (method === 'Add' && args.length >= 3) { verb = unq(text.slice(args[0].start, args[0].end)); pathIdx = 1; }
+    if ((method === 'Method' || method === 'MethodFunc') && args.length >= 3) { verb = unq(text.slice(args[0].start, args[0].end))?.toUpperCase() ?? null; pathIdx = 1; }
+    if (method === 'Match' && args.length >= 3) { verb = 'ANY'; pathIdx = 1; }
+    if (!verb) verb = ROUTE_CALLS.has(method) && METHODS.has(method.toUpperCase()) ? method.toUpperCase() : 'ANY';
+    let path = unq(text.slice(args[pathIdx].start, args[pathIdx].end));
+    if (path === null) return;
+    // Go 1.22 patterns: "GET /notes/{id}", and gorilla/chi style braces.
+    const pm = /^([A-Z]+)\s+(\S.*)$/.exec(path);
+    if (pm && METHODS.has(pm[1])) { verb = pm[1]; path = pm[2]; }
+    path = path.replace(/\{(\w+)(?::[^}]*)?\}/g, ':$1').replace(/:(\w+)(?=\/|$)/g, ':$1').replace(/\*(\w*)/g, (_m, n) => `*${n || 'rest'}`).replace(/\{(\w+)\.\.\.\}/g, '*$1');
+    const rest = args.slice(pathIdx + 1);
+    if (!rest.length) return;
+    const echo = e.fw === 'echo';
+    const handlerArg = echo ? rest[0] : rest[rest.length - 1];
+    const perRoute = (echo ? rest.slice(1) : rest.slice(0, -1)).map((a) => mwOf(a, 'wrapper'));
+    const full = joinPath(e.prefix, path);
+    const handlerText = text.slice(handlerArg.start, handlerArg.end);
+    if (/\bFileServer\b|\bStripPrefix\b|\bStatic\b/.test(handlerText) && !/func\s*\(/.test(handlerText)) return;
+    const resolved = resolveHandler(repo, fn, v, handlerArg);
+    const decorators: LightDeco[] = [
+      ...e.mws.filter((m) => m.only === null || full.startsWith(m.only)).map((m) => ({ view: m.view, start: m.start, end: m.end, scope: m.scope })),
+      ...chained.map((m) => ({ view: m.view, start: m.start, end: m.end, scope: m.scope })),
+      ...perRoute.map((m) => ({ view: m.view, start: m.start, end: m.end, scope: m.scope })),
+      ...resolved.wrappers.map((w) => ({ view: v, start: w.start, end: w.end, scope: 'wrapper' as Scope })),
+    ];
+    const hv = resolved.view;
+    const a = analyzeLight(hv, { start: resolved.start, end: resolved.end, seeds: [], decorators, lookup: fn.find, local });
+    const line = v.lines.at(at);
+    entries.push(makeEntry(repo, {
+      kind: 'http_route', framework: e.fw, file: v.file, line, method: verb, path: full, name: resolved.name,
+      confidence: e.param || !resolved.found ? 'medium' : 'high', handlerView: hv, spec: { start: resolved.start, end: resolved.end, seeds: [] }, analysis: a,
+    }));
+  };
+
+  // Events in order: router creation, groups, middleware, routes, mounts.
+  type Ev = { at: number; kind: 'create' | 'call'; m: RegExpExecArray };
+  const evs: Ev[] = [];
+  const body = [f.bodyStart, f.end] as const;
+  CREATE.lastIndex = 0;
+  for (const m of masked.slice(body[0], body[1]).matchAll(CREATE)) evs.push({ at: body[0] + m.index!, kind: 'create', m: m as RegExpExecArray });
+  const callRe = /(?<![\w.])([A-Za-z_]\w*)\s*\.\s*([A-Za-z_]\w*)\s*\(/g;
+  for (const m of masked.slice(body[0], body[1]).matchAll(callRe)) evs.push({ at: body[0] + m.index!, kind: 'call', m: m as RegExpExecArray });
+  evs.sort((a, b) => a.at - b.at || (a.kind === 'create' ? -1 : 1));
+  let skipTo = -1;
+  const handleCall = (recv: string, method: string, at: number, open: number, e: Env, assignTo: string | null, within: Map<string, Env>): number => {
+    const args = splitArgs(masked, open);
+    const closeAt = closeOf(masked, open);
+    if (method === 'Use') {
+      let only: string | null = null;
+      let list = args;
+      if (e.fw === 'fiber' && args.length > 1 && unq(text.slice(args[0].start, args[0].end)) !== null) { only = unq(text.slice(args[0].start, args[0].end)); list = args.slice(1); }
+      for (const a of list) e.mws.push(mwOf(a, 'router', only === null ? null : joinPath(e.prefix, only)));
+      return closeAt;
+    }
+    if ((method === 'Group' || method === 'Route') && args.length) {
+      // chi: r.Route("/p", func(r chi.Router) { ... }) and r.Group(func(r chi.Router) { ... })
+      const lit = args.find((a) => /^func\s*\(/.test(masked.slice(a.start, a.end)));
+      if (lit && /\bchi\b|Router/.test(masked.slice(lit.start, lit.start + 80))) {
+        const g = goFunc(masked, lit.start);
+        const pm = /^func\s*\(\s*(\w+)/.exec(masked.slice(lit.start));
+        if (g && pm) {
+          const p = method === 'Route' ? unq(text.slice(args[0].start, args[0].end)) ?? '' : '';
+          const child: Env = { prefix: joinPath(e.prefix, p || '/'), mws: e.mws.slice(), fw: e.fw, param: e.param };
+          const inner = new Map(within);
+          inner.set(pm[1], child);
+          walkRange(g.bodyStart + 1, g.end - 1, inner);
+          return g.end;
+        }
+      }
+      if (assignTo) {
+        const p = unq(text.slice(args[0].start, args[0].end)) ?? '';
+        const child: Env = { prefix: joinPath(e.prefix, p || '/'), mws: [...e.mws, ...args.slice(1).map((a) => mwOf(a, 'router'))], fw: e.fw, param: e.param };
+        within.set(assignTo, child);
+        return closeAt;
+      }
+      return closeAt;
+    }
+    if (method === 'PathPrefix' && assignTo) {
+      const p = unq(text.slice(args[0]?.start ?? 0, args[0]?.end ?? 0)) ?? '';
+      within.set(assignTo, { prefix: joinPath(e.prefix, p || '/'), mws: e.mws.slice(), fw: e.fw, param: e.param });
+      return closeAt;
+    }
+    if (method === 'With') {
+      const tail = /^\s*\.\s*([A-Za-z_]\w*)\s*\(/.exec(masked.slice(closeAt, closeAt + 60));
+      if (tail) {
+        const chained = args.map((a) => mwOf(a, 'wrapper'));
+        const open2 = closeAt + tail[0].length - 1;
+        route(e, recv, tail[1], open2, chained, at, null);
+        return closeOf(masked, open2);
+      }
+      return closeAt;
+    }
+    if (method === 'Mount') {
+      const p = unq(text.slice(args[0]?.start ?? 0, args[0]?.end ?? 0));
+      const target = args[1] ? text.slice(args[1].start, args[1].end) : '';
+      if (p !== null) {
+        const names = [...target.matchAll(/(?<![\w.])(\w+)\s*\(/g)].map((x) => x[1]).concat(/^\s*\w+\s*$/.test(target) ? [target.trim()] : []);
+        mounts.push({ prefix: joinPath(e.prefix, p), mws: e.mws.slice(), fw: e.fw, targets: names, from: v.file });
+      }
+      return closeAt;
+    }
+    if (method === 'Subrouter' || method === 'Static') return closeAt;
+    if (ROUTE_CALLS.has(method) || METHODS.has(method.toUpperCase())) {
+      // gorilla/mux: r.HandleFunc("/x", h).Methods("POST")
+      let forced: string | null = null;
+      const meth = /^\s*\.\s*Methods\s*\(([^)]*)\)/.exec(masked.slice(closeAt, closeAt + 80));
+      if (meth) forced = [...text.slice(closeAt, closeAt + 120).matchAll(/"(\w+)"/g)].map((x) => x[1].toUpperCase())[0] ?? null;
+      route(e, recv, method, open, [], at, forced);
+      return meth ? closeAt + meth[0].length : closeAt;
+    }
+    return closeAt;
+  };
+  const walkRange = (from: number, to: number, scope: Map<string, Env>): void => {
+    for (const ev of evs) {
+      if (ev.at < from || ev.at >= to || ev.at < skipTo) continue;
+      if (ev.kind === 'create') {
+        scope.set(ev.m[1], fresh());
+        continue;
+      }
+      const recv = ev.m[1];
+      const method = ev.m[2];
+      const e = scope.get(recv);
+      if (!e) continue;
+      const open = ev.at + ev.m[0].length - 1;
+      const pre = masked.slice(Math.max(0, ev.at - 80), ev.at);
+      const assign = /(?:^|\n)\s*(\w+)\s*:?=\s*$/.exec(pre)?.[1] ?? null;
+      const end = handleCall(recv, method, ev.at, open, e, assign, scope);
+      if (end > skipTo) skipTo = end;
+    }
+  };
+  walkRange(body[0], body[1], env);
+  return { entries, mounts };
+}
+
+interface Resolved { view: FileView; start: number; end: number; name: string | null; found: boolean; wrappers: { start: number; end: number }[] }
+
+// A handler argument: a function literal, a name, a method value (h.CreateNote), or a call that wraps or builds a handler.
+function resolveHandler(repo: Repo, fn: FnIndex, v: FileView, a: { start: number; end: number }, depth = 0): Resolved {
+  const m = v.masked;
+  const t = m.slice(a.start, a.end).trim();
+  const miss: Resolved = { view: v, start: a.start, end: a.end, name: /^(?:\w+\.)*(\w+)$/.exec(t)?.[1] ?? null, found: false, wrappers: [] };
+  if (depth > 4) return miss;
+  if (/^func\s*\(/.test(t)) {
+    const g = goFunc(m, a.start + (m.slice(a.start, a.end).length - m.slice(a.start, a.end).trimStart().length));
+    if (g) return { view: v, start: g.start, end: g.end, name: null, found: true, wrappers: [] };
+  }
+  const call = /^((?:\w+\.)*\w+)\s*\(/.exec(t);
+  if (call) {
+    const at = a.start + (m.slice(a.start, a.end).length - m.slice(a.start, a.end).trimStart().length);
+    const open = at + call[0].length - 1;
+    const args = splitArgs(m, open);
+    const head = call[1];
+    const last = head.split('.').pop()!;
+    if (/^HandlerFunc$/.test(last) && args.length === 1) return resolveHandler(repo, fn, v, args[0], depth + 1);
+    for (const x of args) {
+      const r = resolveHandler(repo, fn, v, x, depth + 1);
+      if (r.found) return { ...r, wrappers: [{ start: at, end: x.start }, ...r.wrappers] };
+    }
+    // A handler factory: s.handleCreate() returns the handler, so read its body.
+    const def = fn.find(last, v.file) ?? fn.defs(last)[0];
+    if (def) return { view: def.view, start: def.start, end: def.end, name: last, found: true, wrappers: [] };
+    return miss;
+  }
+  const nm = /^(?:\w+\.)*(\w+)$/.exec(t)?.[1];
+  if (nm) {
+    const defs = fn.defs(nm);
+    const def = fn.find(nm, v.file) ?? defs.find((d) => d.view.file === v.file) ?? defs[0];
+    if (def) return { view: def.view, start: def.start, end: def.end, name: nm, found: true, wrappers: [] };
+  }
+  return miss;
+}
+

package/src/map/js-express.ts

@@ -0,0 +1,135 @@
+// Entry points registered with a call, in the Express family: Express, Koa router, Fastify, Hono, restify and similar
+// (app.get('/path', ...middleware, handler)), plus the app.use gates and router mounts around them.
+import type { Confidence, Gate, Protection } from '../types/index.ts';
+import { analyze, type FileView, type Spec } from './analyze.ts';
+import { empty, joinPath, makeEntry, type Extracted } from './entry.ts';
+import { closeOf, jsFunction, splitArgs } from './lex.ts';
+import { paramsOf, resolveFunction } from './js-next.ts';
+import type { Repo } from './repo.ts';
+
+const FRAMEWORK = /\b(?:express|fastify|koa|hono|restify|polka|@hapi\/hapi|itty-router|elysia|@koa\/router|koa-router|connect|h3|@fastify\/\w+)\b/;
+const CREATORS = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*(?:await\s+)?(?:new\s+)?(?:express\s*\.\s*Router|express|Router|fastify|Fastify|Hono|Koa|Elysia|polka|createRouter|KoaRouter|restify\s*\.\s*createServer|\w*[rR]outer)\s*[(<]/g;
+const VERBS = new Set(['get', 'post', 'put', 'patch', 'delete', 'all', 'options', 'head']);
+
+const confMin = (cs: Confidence[]): Confidence => (cs.includes('low') ? 'low' : cs.includes('medium') ? 'medium' : 'high');
+
+function literalPaths(v: FileView, a: { start: number; end: number } | undefined): string[] | null {
+  if (!a) return null;
+  const c = v.masked[a.start];
+  if (c === '"' || c === "'" || c === '`') {
+    const p = v.text.slice(a.start + 1, a.end - 1);
+    return p.startsWith('/') || p === '*' || p === '' ? [p] : null;
+  }
+  if (c === '[') {
+    const ps = [...v.text.slice(a.start, a.end).matchAll(/['"`]([^'"`]*)['"`]/g)].map((x) => x[1]).filter((p) => p.startsWith('/') || p === '*');
+    return ps.length ? ps : null;
+  }
+  return null;
+}
+
+export function extractExpress(repo: Repo, v: FileView): Extracted {
+  const out = empty();
+  if (!FRAMEWORK.test(v.imports) && !/\bexpress\s*\(\s*\)|\bRouter\s*\(\s*\)/.test(v.masked)) return out;
+  const names = new Set(['app', 'router', 'server', 'api', 'route', 'routes', 'fastify', 'instance']);
+  for (const m of v.masked.matchAll(CREATORS)) names.add(m[1]);
+  const recv = [...names].map((n) => n.replace(/\$/g, '\\$')).join('|');
+  const call = new RegExp(`(?<![.\\w$])(?:${recv})\\s*\\.\\s*(get|post|put|patch|delete|all|options|head|use|route)\\s*\\(`, 'g');
+  const imports = repo.importMap(v);
+  const helpers = repo.helpers('js');
+
+  const middlewareDeco = (args: { start: number; end: number }[]): NonNullable<Spec['decorators']> =>
+    args.map((a) => ({ view: v, start: a.start, end: a.end, scope: 'wrapper' as const }));
+  const calledNames = (args: { start: number; end: number }[]): string[] => {
+    const set = new Set<string>();
+    for (const a of args) for (const m of v.masked.slice(a.start, a.end).matchAll(/(?<![\w$])([A-Za-z_$][\w$]*)\s*(?:\(|,|$)/g)) set.add(m[1]);
+    for (const a of args) { const t = v.masked.slice(a.start, a.end); const id = /^[A-Za-z_$][\w$.]*$/.exec(t); if (id) set.add(id[0].split('.').pop()!); }
+    return [...set].sort();
+  };
+
+  const register = (verb: string, paths: string[], args: { start: number; end: number }[], at: number): void => {
+    if (!args.length) return;
+    const last = args[args.length - 1];
+    const mws = args.slice(0, -1);
+    const r = resolveFunction(repo, v, last.start, last.end);
+    const line = v.lines.at(at);
+    for (const p of paths) {
+      const method = verb === 'all' ? 'ANY' : verb.toUpperCase();
+      const handlerView = r?.view ?? v;
+      const start = r?.start ?? last.start;
+      const end = r?.end ?? last.end;
+      const seeds = r ? (r.params.length ? [r.params[0]] : ['req']) : [];
+      const deco = middlewareDeco(mws);
+      if (r?.wrapper) deco.push({ view: v, start: r.wrapper.from, end: r.wrapper.to, scope: 'wrapper' });
+      const extra = calledNames(mws).concat(r?.wrapper ? [r.wrapper.name.split('.').pop()!] : []);
+      const e = makeEntry(repo, {
+        kind: 'http_route', framework: 'express', file: v.file, line, method, path: joinPath('', p === '' ? '/' : p), name: r?.defName ?? nameOf(v, last),
+        confidence: 'high', handlerView, spec: { start, end, seeds, decorators: deco, extraCalls: extra, returnsJson: true },
+      });
+      out.entries.push(e);
+    }
+  };
+
+  for (const m of v.masked.matchAll(call)) {
+    const verb = m[1];
+    const open = m.index! + m[0].length - 1;
+    const args = splitArgs(v.masked, open);
+    if (verb === 'route') {
+      const paths = literalPaths(v, args[0]);
+      if (!paths) continue;
+      // .route('/x').get(h).post(h): read the chain after the call.
+      let i = closeOf(v.masked, open);
+      if (i < 0) continue;
+      for (let g = 0; g < 8; g++) {
+        const nxt = /^\s*\.\s*(get|post|put|patch|delete|all|options|head)\s*\(/.exec(v.masked.slice(i, i + 60));
+        if (!nxt) break;
+        const o = i + nxt[0].length - 1;
+        register(nxt[1], paths, splitArgs(v.masked, o), i + nxt[0].indexOf(nxt[1]));
+        i = closeOf(v.masked, o);
+        if (i < 0) break;
+      }
+      continue;
+    }
+    if (VERBS.has(verb)) {
+      const paths = literalPaths(v, args[0]);
+      if (!paths || args.length < 2) continue;
+      register(verb, paths, args.slice(1), m.index!);
+      continue;
+    }
+    // use(): a gate on a path, or a router mount.
+    const paths = literalPaths(v, args[0]);
+    const rest = paths ? args.slice(1) : args;
+    const prefix = paths?.[0] ?? '*';
+    const line = v.lines.at(m.index!);
+    let target: string | null = null;
+    for (const a of rest) {
+      const id = /^[A-Za-z_$][\w$]*$/.exec(v.masked.slice(a.start, a.end));
+      const spec = id ? imports.get(id[0]) : undefined;
+      const file = spec ? repo.resolveImport(v.file, spec) : null;
+      if (file && /\bRouter\s*\(|\bexpress\.Router\b|\bnew\s+Hono\b|\bfastify\b/.test(repo.ctx.text(file))) target = file;
+    }
+    const gateArgs = rest.filter((a) => { const id = /^[A-Za-z_$][\w$]*$/.exec(v.masked.slice(a.start, a.end)); return !(id && target && imports.get(id[0]) && repo.resolveImport(v.file, imports.get(id[0])!) === target); });
+    const protections: Protection[] = [];
+    for (const a of gateArgs) {
+      const spec: Spec = { start: a.start, end: a.end, seeds: [], decorators: [], extraCalls: calledNames([a]), returnsJson: false, gate: true };
+      const an = analyze(v, spec, helpers);
+      for (const p of an.protections) if (p.kind !== 'owner_filter' && p.kind !== 'audit_log') protections.push({ ...p, scope: 'middleware' });
+    }
+    const joined = protections.length ? protections : [];
+    if (target) out.mounts.push({ from: v.file, line, prefix: joinPath('', prefix === '*' ? '/' : prefix), target, protections: joined });
+    else if (joined.length) {
+      const gate: Gate = { id: `${v.file}:${line}:use:${prefix}`, kind: 'middleware', framework: 'express', file: v.file, line, paths: [prefix === '*' ? '*' : joinPath('', prefix)], methods: [], protections: joined, confidence: confMin(joined.map((p) => p.confidence)) === 'high' ? 'medium' : confMin(joined.map((p) => p.confidence)) };
+      out.gates.push(gate);
+    }
+  }
+  return out;
+}
+
+// A readable name for the handler argument: the function name, or the called factory, or null for an inline function.
+function nameOf(v: FileView, a: { start: number; end: number }): string | null {
+  const t = v.masked.slice(a.start, a.end);
+  if (/^(?:async\b|function\b|\(|[A-Za-z_$][\w$]*\s*=>)/.test(t)) return null;
+  const m = /^([A-Za-z_$][\w$.]*)/.exec(t);
+  return m ? m[1] : null;
+}
+
+export { paramsOf };

package/src/map/js-misc.ts

@@ -0,0 +1,221 @@
+// NestJS controllers, resolvers and consumers; scheduled and queued jobs; functions handed to a model as tools.
+import type { Gate, InputSource, Protection } from '../types/index.ts';
+import type { FileView, Spec } from './analyze.ts';
+import { empty, joinPath, makeEntry, paramNames, type Extracted } from './entry.ts';
+import { closeOf, jsFunction, splitArgs } from './lex.ts';
+import { paramsOf, resolveFunction } from './js-next.ts';
+import type { Repo } from './repo.ts';
+
+const NEST_VERBS = /@(Get|Post|Put|Patch|Delete|All|Options|Head)\s*\(/g;
+const NEST_OTHER = /@(Query|Mutation|Subscription|ResolveField|MessagePattern|EventPattern|SubscribeMessage|Cron|Interval|Timeout|Process)\s*\(/g;
+const PUBLIC_MARK = /@(?:Public|AllowAnonymous|SkipAuth|IsPublic|NoAuth|AllowUnauthenticated)\s*\(/;
+
+const dtoCache = new WeakMap<Repo, Map<string, boolean>>();
+// Whether a class of this name in the repository carries class-validator decorators.
+function dtoValidated(repo: Repo, name: string): boolean {
+  let cache = dtoCache.get(repo);
+  if (!cache) { cache = new Map(); dtoCache.set(repo, cache); }
+  const hit = cache.get(name);
+  if (hit !== undefined) return hit;
+  let ok = false;
+  for (const f of repo.filesOf('js')) {
+    const t = repo.ctx.text(f);
+    const m = new RegExp(`class\\s+${name}\\b[^{]*\\{`).exec(t);
+    if (!m) continue;
+    const body = t.slice(m.index, m.index + 4000);
+    if (/@(?:Is[A-Z]\w*|Min|Max|Length|MinLength|MaxLength|Matches|Validate\w*|Allow|ArrayMaxSize|ArrayMinSize|Contains|NotEquals|Equals|IsOptional)\s*\(/.test(body)) { ok = true; break; }
+  }
+  cache.set(name, ok);
+  return ok;
+}
+
+export function extractNest(repo: Repo, v: FileView): Extracted {
+  const out = empty();
+  if (!/@(?:Controller|Resolver|Cron|Interval|Timeout|MessagePattern|EventPattern|SubscribeMessage|Process|Processor)\s*\(|APP_GUARD|useGlobalPipes|consumer\s*\.\s*apply\s*\(/.test(v.text)) return out;
+  const { masked, text } = v;
+
+  // Global guards and pipes become gates.
+  for (const m of masked.matchAll(/provide\s*:\s*APP_GUARD/g)) {
+    const seg = text.slice(m.index!, m.index! + 160);
+    const cls = /useClass\s*:\s*([A-Za-z_$][\w$]*)/.exec(seg)?.[1] ?? 'APP_GUARD';
+    const protections: Protection[] = [];
+    const line = v.lines.at(m.index!);
+    if (/auth|jwt|session|firebase|supabase/i.test(cls)) protections.push({ kind: 'session_read', scope: 'global', file: v.file, line, via: `APP_GUARD ${cls}`, enforced: true, confidence: 'medium' });
+    if (/role|permission|admin|abac|casl/i.test(cls)) protections.push({ kind: 'role_check', scope: 'global', file: v.file, line, via: `APP_GUARD ${cls}`, enforced: true, confidence: 'medium' });
+    if (/throttl|rate/i.test(cls)) protections.push({ kind: 'rate_limit', scope: 'global', file: v.file, line, via: `APP_GUARD ${cls}`, enforced: true, confidence: 'high' });
+    if (protections.length) out.gates.push({ id: `${v.file}:${line}:APP_GUARD:${cls}`, kind: 'guard', framework: 'nest', file: v.file, line, paths: ['*'], methods: [], protections, confidence: 'medium' });
+  }
+  // Module middleware: consumer.apply(AuthMiddleware).forRoutes('path', { path: 'x', method: RequestMethod.GET }). One gate per route spec.
+  for (const m of masked.matchAll(/\.\s*apply\s*\(([^)]*)\)/g)) {
+    const statementEnd = masked.indexOf(';', m.index!);
+    const chain = text.slice(m.index!, statementEnd < 0 ? m.index! + 600 : statementEnd);
+    const fr = /\.\s*forRoutes\s*\(/.exec(chain);
+    if (!fr) continue;
+    const names = [...m[1].matchAll(/[A-Za-z_$][\w$]*/g)].map((x) => x[0]).filter((x) => !/^(?:new|function|req|res|next)$/.test(x));
+    const line = v.lines.at(m.index!);
+    const protections: Protection[] = [];
+    for (const n of names) {
+      if (/auth|jwt|session|firebase|supabase|login|token/i.test(n)) protections.push({ kind: 'session_read', scope: 'middleware', file: v.file, line, via: `module middleware ${n}`, enforced: null, confidence: 'medium' });
+      if (/role|permission|admin|abac|casl/i.test(n)) protections.push({ kind: 'role_check', scope: 'middleware', file: v.file, line, via: `module middleware ${n}`, enforced: null, confidence: 'medium' });
+      if (/throttl|rate/i.test(n)) protections.push({ kind: 'rate_limit', scope: 'middleware', file: v.file, line, via: `module middleware ${n}`, enforced: null, confidence: 'medium' });
+    }
+    if (!protections.length) continue;
+    const open = m.index! + chain.indexOf('forRoutes') + 'forRoutes'.length;
+    const args = text.slice(text.indexOf('(', open - 1) + 1, text.indexOf(')', open - 1 + chain.slice(chain.indexOf('forRoutes')).length)).trim();
+    const specs: { path: string; methods: string[] }[] = [];
+    for (const o of args.matchAll(/\{\s*path\s*:\s*['"`]([^'"`]*)['"`]\s*,\s*method\s*:\s*RequestMethod\.(\w+)\s*\}/g)) specs.push({ path: o[1], methods: o[2] === 'ALL' ? [] : [o[2]] });
+    const rest = args.replace(/\{[^}]*\}/g, ' ');
+    for (const sx of rest.matchAll(/['"`]([^'"`]*)['"`]/g)) specs.push({ path: sx[1], methods: [] });
+    if (!specs.length && /^\s*\*\s*$|['"`]\*['"`]/.test(args)) specs.push({ path: '*', methods: [] });
+    specs.forEach((sp, i) => {
+      const star = sp.path.replace(/\/?\*.*$/, '');
+      const gp = sp.path === '*' ? '*' : joinPath('/', star);
+      out.gates.push({ id: `${v.file}:${line}:forRoutes:${i}`, kind: 'middleware', framework: 'nest', file: v.file, line, paths: [gp], methods: sp.methods, protections, confidence: 'medium' });
+    });
+  }
+  for (const m of masked.matchAll(/useGlobalPipes\s*\(\s*new\s+ValidationPipe/g)) {
+    const line = v.lines.at(m.index!);
+    const g: Gate = { id: `${v.file}:${line}:ValidationPipe`, kind: 'global_pipe', framework: 'nest', file: v.file, line, paths: ['*'], methods: [], protections: [{ kind: 'input_validation', scope: 'global', file: v.file, line, via: 'global ValidationPipe', enforced: true, confidence: 'medium' }], confidence: 'medium' };
+    out.gates.push(g);
+  }
+
+  for (const cm of masked.matchAll(/(?<![\w$])class\s+([A-Za-z_$][\w$]*)\b/g)) {
+    const classKw = cm.index!;
+    let ds = classKw;
+    for (let k = classKw - 1; k >= 0 && classKw - k < 900; k--) { const c = masked[k]; if (c === '}' || c === ';') break; ds = k; }
+    const classDeco = text.slice(ds, classKw);
+    const bodyOpen = masked.indexOf('{', classKw);
+    if (bodyOpen < 0) continue;
+    const bodyClose = closeOf(masked, bodyOpen);
+    if (bodyClose < 0) continue;
+    const isController = /@Controller\s*\(/.test(classDeco);
+    const isResolver = /@Resolver\s*\(/.test(classDeco);
+    const prefix = isController ? (/@Controller\s*\(\s*(?:['"`]([^'"`]*)['"`]|\{[^}]*?path\s*:\s*['"`]([^'"`]*)['"`])/.exec(classDeco)?.slice(1).find((x) => x !== undefined) ?? '') : '';
+    const body = masked.slice(bodyOpen, bodyClose);
+    const verbRe = isController ? NEST_VERBS : NEST_OTHER;
+    verbRe.lastIndex = 0;
+    const hits = [...body.matchAll(isController ? NEST_VERBS : new RegExp(NEST_OTHER.source, 'g'))];
+    if (!hits.length) continue;
+    for (const h of hits) {
+      const at = bodyOpen + h.index!;
+      const decoOpen = at + h[0].length - 1;
+      const decoClose = closeOf(masked, decoOpen);
+      if (decoClose < 0) continue;
+      // Skip further decorators, then read the method name and signature.
+      let i = decoClose;
+      for (;;) {
+        const nxt = /^\s*@[\w$.]+\s*(?:\()?/.exec(masked.slice(i, i + 80));
+        if (!nxt) break;
+        const o = i + nxt[0].length - 1;
+        if (masked[o] === '(') { const c = closeOf(masked, o); if (c < 0) break; i = c; } else i += nxt[0].length;
+      }
+      const sig = /^\s*(?:(?:public|private|protected|async|static|override)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>(]*>)?\s*\(/.exec(masked.slice(i, i + 200));
+      if (!sig) continue;
+      const parenIdx = i + sig[0].length - 1;
+      const f = jsFunction(masked, parenIdx, true);
+      if (!f) continue;
+      let ms = at;
+      for (let k = at - 1; k > bodyOpen && at - k < 700; k--) { const c = masked[k]; if (c === '}' || c === ';' || c === '{') break; ms = k; }
+      const methodDeco = text.slice(ms, at + (decoClose - at));
+      const argText = text.slice(decoOpen + 1, decoClose - 1);
+      const litPath = /^\s*['"`]([^'"`]*)['"`]/.exec(argText)?.[1] ?? '';
+      const deco: NonNullable<Spec['decorators']> = [{ view: v, start: ds, end: classKw, scope: 'router' }, { view: v, start: ms, end: i, scope: 'handler' }];
+      const name = sig[1];
+      const params = paramNames(masked, parenIdx);
+      let kind: 'http_route' | 'graphql_resolver' | 'message_consumer' | 'websocket' | 'job' = 'http_route';
+      let method: string | null = h[1].toUpperCase();
+      let path: string | null = null;
+      if (isController) { method = h[1] === 'All' ? 'ANY' : h[1].toUpperCase(); path = joinPath('/' + prefix, litPath); if (path === '') path = '/'; }
+      else if (/^(?:Query|Mutation|Subscription|ResolveField)$/.test(h[1])) { kind = 'graphql_resolver'; method = h[1] === 'ResolveField' ? 'FIELD' : h[1].toUpperCase(); path = name; }
+      else if (/^(?:MessagePattern|EventPattern)$/.test(h[1])) { kind = 'message_consumer'; method = null; path = litPath || argText.trim().slice(0, 60) || name; }
+      else if (h[1] === 'SubscribeMessage') { kind = 'websocket'; method = null; path = litPath || name; }
+      else { kind = 'job'; method = null; path = litPath || (argText.trim().slice(0, 40) || name); }
+      if (!isController && !isResolver && kind === 'graphql_resolver') continue;
+      const e = makeEntry(repo, { kind, framework: 'nest', file: v.file, line: v.lines.at(at), method, path, name, confidence: 'high', handlerView: v, spec: { start: f.start, end: f.end, seeds: params, decorators: deco, extraCalls: [], returnsJson: true }, tags: PUBLIC_MARK.test(classDeco) || PUBLIC_MARK.test(methodDeco) ? ['public'] : [] });
+      // Parameter decorators are request reads; a typed @Body() is checked against class-validator decorators on the DTO.
+      const sigText = text.slice(parenIdx, f.bodyStart);
+      const reads: [InputSource, RegExp][] = [['body', /@Body\s*\(/], ['query', /@Query\s*\(/], ['params', /@Param\s*\(/], ['headers', /@Headers?\s*\(/], ['file', /@(?:UploadedFiles?|UploadedFile)\s*\(/]];
+      for (const [source, re] of reads) { const rm = re.exec(sigText); if (rm && !e.reads.some((r) => r.source === source)) e.reads.push({ source, line: v.lines.at(parenIdx + rm.index) }); }
+      if (e.reads.some((r) => r.source === 'file') && !e.tags.includes('upload')) e.tags = [...e.tags, 'upload'].sort();
+      if (/@(?:UseInterceptors\s*\(\s*(?:FileInterceptor|FilesInterceptor))/.test(methodDeco) && !e.reads.some((r) => r.source === 'file')) e.reads.push({ source: 'file', line: e.line });
+      for (const dm of sigText.matchAll(/@Body\s*\([^)]*\)\s*[A-Za-z_$][\w$]*\s*:\s*([A-Z][\w$]*)/g)) {
+        if (dtoValidated(repo, dm[1])) e.protections.push({ kind: 'input_validation', scope: 'handler', file: v.file, line: v.lines.at(parenIdx + dm.index!), via: `DTO ${dm[1]}`, enforced: null, confidence: 'medium' });
+      }
+      e.protections.sort((a, b) => a.line - b.line || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0) || (a.via < b.via ? -1 : a.via > b.via ? 1 : 0));
+      e.reads.sort((a, b) => (a.source < b.source ? -1 : 1));
+      out.entries.push(e);
+    }
+  }
+  return out;
+}
+
+const JOB_CALL = /(?<![\w$])(cron\.schedule|schedule\.scheduleJob|scheduleJob|new\s+CronJob|agenda\.define|new\s+Worker|\w*[qQ]ueue\w*\.process|boss\.work|inngest\.createFunction|\w+\.addRepeatableJob|setInterval)\s*\(/g;
+
+export function extractJobs(repo: Repo, v: FileView): Extracted {
+  const out = empty();
+  if (!/cron|schedule|agenda|Worker|[qQ]ueue|boss|inngest/.test(v.text)) return out;
+  for (const m of v.masked.matchAll(JOB_CALL)) {
+    if (m[1] === 'setInterval') continue;
+    const open = m.index! + m[0].length - 1;
+    const args = splitArgs(v.masked, open);
+    const first = args[0];
+    const lit = first && /^['"`]/.test(v.masked[first.start]) ? v.text.slice(first.start + 1, first.end - 1) : null;
+    const fa = args.map((a) => ({ a, r: resolveFunction(repo, v, a.start, a.end) })).find((x) => x.r);
+    if (!fa?.r) continue;
+    const framework = /cron|schedule/i.test(m[1]) ? 'node-cron' : /Worker|process|work/.test(m[1]) ? 'queue' : m[1];
+    out.entries.push(makeEntry(repo, { kind: 'job', framework, file: v.file, line: v.lines.at(m.index!), method: null, path: lit, name: lit && !/[\s*]/.test(lit) ? lit : null, confidence: 'high', handlerView: fa.r.view, spec: { start: fa.r.start, end: fa.r.end, seeds: fa.r.params, decorators: [], returnsJson: false } }));
+  }
+  return out;
+}
+
+const TOOL_OBJECT = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*\{/g;
+const TOOLISH = /tool|function|handler|action|capabilit/i;
+
+export function extractAiTools(repo: Repo, v: FileView): Extracted {
+  const out = empty();
+  if (!/tool|function_call|mcp|[aA]gent|llm|openai|anthropic|generateText|assistant/.test(v.text)) return out;
+  const seen = new Set<number>();
+  const push = (name: string | null, f: { start: number; end: number; bodyStart: number }, line: number, framework: string): void => {
+    if (seen.has(f.start)) return;
+    seen.add(f.start);
+    out.entries.push(makeEntry(repo, { kind: 'ai_tool', framework, file: v.file, line, method: null, path: null, name, confidence: 'medium', handlerView: v, spec: { start: f.start, end: f.end, seeds: paramsOf(v.masked, f).slice(0, 1), decorators: [], returnsJson: false } }));
+  };
+  // 1. An object of functions named like tools: { read_note: (args) => ..., send: async (args) => ... }
+  for (const m of v.masked.matchAll(TOOL_OBJECT)) {
+    if (!TOOLISH.test(m[1]) || !/\b(?:tool|function|openai|anthropic|llm|assistant|agent|model)/i.test(v.text)) continue;
+    const open = m.index! + m[0].length - 1;
+    const close = closeOf(v.masked, open);
+    if (close < 0) continue;
+    for (const seg of splitArgs(v.masked, open)) {
+      const head = /^(?:async\s+)?\[?['"]?([\w$-]+)['"]?\]?\s*(:|\()/.exec(v.text.slice(seg.start, seg.end).replace(/^async\s+/, 'async '));
+      if (!head) continue;
+      const name = head[1];
+      let at = seg.start + head[0].length - 1;
+      if (head[2] === ':') at = seg.start + head[0].length;
+      const f = jsFunction(v.masked, head[2] === '(' ? at : at);
+      if (f && f.end <= seg.end + 1) push(name, f, v.lines.at(seg.start), 'ai-tools');
+    }
+  }
+  // 2. tool({ description, parameters, execute })
+  for (const m of v.masked.matchAll(/(?<![\w$])tool\s*\(\s*\{/g)) {
+    const open = v.masked.indexOf('{', m.index!);
+    for (const seg of splitArgs(v.masked, open)) {
+      const ex = /^execute\s*(:|\()/.exec(v.masked.slice(seg.start, seg.end));
+      if (!ex) continue;
+      const f = jsFunction(v.masked, seg.start + (ex[1] === ':' ? ex[0].length : ex[0].length - 1));
+      if (!f) continue;
+      const before = v.text.slice(Math.max(0, m.index! - 80), m.index!);
+      const nm = /([A-Za-z_$][\w$]*)\s*(?::|=)\s*$/.exec(before)?.[1] ?? null;
+      push(nm, f, v.lines.at(m.index!), 'ai-sdk');
+    }
+  }
+  // 3. MCP: server.tool('name', schema, handler)
+  for (const m of v.masked.matchAll(/\.\s*(?:tool|registerTool)\s*\(\s*(['"])/g)) {
+    const open = v.masked.indexOf('(', m.index!);
+    const args = splitArgs(v.masked, open);
+    const nm = v.text.slice(args[0].start + 1, args[0].end - 1);
+    const fa = args.map((a) => jsFunction(v.masked, a.start)).filter((x) => x).pop();
+    if (fa) push(nm, fa, v.lines.at(m.index!), 'mcp');
+  }
+  return out;
+}