sparda-mcp 0.5.2 → 0.5.4

package/src/parser/express.js

@@ -6,7 +6,15 @@ import traverseModule from '@babel/traverse';
 const traverse = traverseModule.default ?? traverseModule;
 
 const HTTP = new Set(['get', 'post', 'put', 'patch', 'delete']);
-const EXCLUDE = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.sparda']);
+const EXCLUDE = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  '.sparda',
+]);
 
 export function parseExpressProject(cwd, entryFile) {
   const routes = [];
@@ -29,7 +37,11 @@ export function parseExpressProject(cwd, entryFile) {
     if (depth > 2 || visited.has(absFile + '::' + prefix)) return;
     visited.add(absFile + '::' + prefix);
     let src;
-    try { src = fs.readFileSync(absFile, 'utf8'); } catch { return; }
+    try {
+      src = fs.readFileSync(absFile, 'utf8');
+    } catch {
+      return;
+    }
     let ast;
     try {
       ast = parse(src, {
@@ -38,13 +50,16 @@ export function parseExpressProject(cwd, entryFile) {
         attachComment: true,
       });
     } catch (e) {
-      skipped.push({ reason: `parse error in ${rel(absFile)}: ${e.message.slice(0, 80)}`, file: rel(absFile) });
+      skipped.push({
+        reason: `parse error in ${rel(absFile)}: ${e.message.slice(0, 80)}`,
+        file: rel(absFile),
+      });
       return;
     }
 
-    const appVars = new Set();    // vars = express()
+    const appVars = new Set(); // vars = express()
     const routerVars = new Set(); // vars = express.Router() / Router()
-    const importMap = new Map();  // localName -> absolute file path (relative imports only)
+    const importMap = new Map(); // localName -> absolute file path (relative imports only)
     const exprStarts = new Set(); // line numbers where express() assigned (for injector)
 
     traverse(ast, {
@@ -53,7 +68,11 @@ export function parseExpressProject(cwd, entryFile) {
         if (!init) return;
         if (init.type === 'CallExpression') {
           const callee = init.callee;
-          if (callee.type === 'Identifier' && callee.name === 'require' && init.arguments[0]?.type === 'StringLiteral') {
+          if (
+            callee.type === 'Identifier' &&
+            callee.name === 'require' &&
+            init.arguments[0]?.type === 'StringLiteral'
+          ) {
             const resolved = resolveRel(absFile, init.arguments[0].value);
             if (resolved) {
               const id = p.node.id;
@@ -61,7 +80,10 @@ export function parseExpressProject(cwd, entryFile) {
                 importMap.set(id.name, resolved);
               } else if (id.type === 'ObjectPattern') {
                 for (const prop of id.properties) {
-                  if (prop.type === 'ObjectProperty' && prop.value.type === 'Identifier') {
+                  if (
+                    prop.type === 'ObjectProperty' &&
+                    prop.value.type === 'Identifier'
+                  ) {
                     importMap.set(prop.value.name, resolved);
                   }
                 }
@@ -70,9 +92,14 @@ export function parseExpressProject(cwd, entryFile) {
           }
           const name = p.node.id?.name;
           if (name) {
-            if (callee.type === 'Identifier' && callee.name === 'express') { appVars.add(name); exprStarts.add(p.node.loc.end.line); }
-            if (callee.type === 'Identifier' && callee.name === 'Router') routerVars.add(name);
-            if (callee.type === 'MemberExpression' && callee.property?.name === 'Router') routerVars.add(name);
+            if (callee.type === 'Identifier' && callee.name === 'express') {
+              appVars.add(name);
+              exprStarts.add(p.node.loc.end.line);
+            }
+            if (callee.type === 'Identifier' && callee.name === 'Router')
+              routerVars.add(name);
+            if (callee.type === 'MemberExpression' && callee.property?.name === 'Router')
+              routerVars.add(name);
           }
         }
       },
@@ -83,7 +110,8 @@ export function parseExpressProject(cwd, entryFile) {
       },
       CallExpression(p) {
         const callee = p.node.callee;
-        if (callee.type !== 'MemberExpression' || callee.property.type !== 'Identifier') return;
+        if (callee.type !== 'MemberExpression' || callee.property.type !== 'Identifier')
+          return;
         const objName = callee.object.type === 'Identifier' ? callee.object.name : null;
         const method = callee.property.name;
         const args = p.node.arguments;
@@ -92,8 +120,17 @@ export function parseExpressProject(cwd, entryFile) {
         if (method === 'use' && objName && appVars.has(objName) && args.length >= 2) {
           const [a0, a1] = args;
           if (a0.type === 'StringLiteral' && a1.type === 'Identifier') {
-            mounts.push({ prefix: joinPath(prefix, a0.value), file: importMap.get(a1.name) ?? null, ident: a1.name });
-            if (!importMap.get(a1.name)) skipped.push({ reason: `router "${a1.name}" mounted at ${a0.value} — source file not resolved`, file: rel(absFile), line: p.node.loc.start.line });
+            mounts.push({
+              prefix: joinPath(prefix, a0.value),
+              file: importMap.get(a1.name) ?? null,
+              ident: a1.name,
+            });
+            if (!importMap.get(a1.name))
+              skipped.push({
+                reason: `router "${a1.name}" mounted at ${a0.value} — source file not resolved`,
+                file: rel(absFile),
+                line: p.node.loc.start.line,
+              });
           }
           return;
         }
@@ -105,26 +142,50 @@ export function parseExpressProject(cwd, entryFile) {
 
         const pathArg = args[0];
         if (!pathArg || pathArg.type !== 'StringLiteral') {
-          skipped.push({ reason: `dynamic path on ${method.toUpperCase()} (non-literal first arg)`, file: rel(absFile), line: p.node.loc?.start.line });
+          skipped.push({
+            reason: `dynamic path on ${method.toUpperCase()} (non-literal first arg)`,
+            file: rel(absFile),
+            line: p.node.loc?.start.line,
+          });
           return;
         }
 
         const fullPath = joinPath(prefix, pathArg.value);
         if (fullPath === '/mcp' || fullPath.startsWith('/mcp/')) {
-          skipped.push({ reason: `self-referential path ${fullPath} blocked`, file: rel(absFile), line: p.node.loc?.start.line });
+          skipped.push({
+            reason: `self-referential path ${fullPath} blocked`,
+            file: rel(absFile),
+            line: p.node.loc?.start.line,
+          });
           return;
         }
 
         const handler = args[args.length - 1];
-        const handlerName = handler?.type === 'Identifier' ? handler.name
-          : handler?.id?.name ?? `anonymous_${routes.length + 1}`;
+        const handlerName =
+          handler?.type === 'Identifier'
+            ? handler.name
+            : (handler?.id?.name ?? `anonymous_${routes.length + 1}`);
 
-        const leading = (p.parentPath.node.leadingComments ?? p.node.leadingComments ?? [])
-          .map((c) => c.value.replace(/^\*+/gm, '').replace(/^\s*\*\s?/gm, '').trim())
-          .filter(Boolean).join(' ');
+        const leading = (
+          p.parentPath.node.leadingComments ??
+          p.node.leadingComments ??
+          []
+        )
+          .map((c) =>
+            c.value
+              .replace(/^\*+/gm, '')
+              .replace(/^\s*\*\s?/gm, '')
+              .trim(),
+          )
+          .filter(Boolean)
+          .join(' ');
 
         const pathParams = [...fullPath.matchAll(/:(\w+)/g)].map((mm) => ({
-          name: mm[1], in: 'path', type: 'string', required: true, description: 'path parameter',
+          name: mm[1],
+          in: 'path',
+          type: 'string',
+          required: true,
+          description: 'path parameter',
         }));
 
         const mutating = method !== 'get';
@@ -135,18 +196,36 @@ export function parseExpressProject(cwd, entryFile) {
         for (const q of queryParamsOf(p)) {
           if (taken.has(q)) continue;
           taken.add(q);
-          params.push({ name: q, in: 'query', type: 'string', required: false, description: 'query parameter' });
+          params.push({
+            name: q,
+            in: 'query',
+            type: 'string',
+            required: false,
+            description: 'query parameter',
+          });
         }
         let confidence = 'high';
         if (mutating) {
-          params.push({ name: 'body', in: 'body', type: 'object', required: false, description: 'JSON body — schema not statically detected' });
+          params.push({
+            name: 'body',
+            in: 'body',
+            type: 'object',
+            required: false,
+            description: 'JSON body — schema not statically detected',
+          });
           confidence = 'low';
         }
 
         routes.push({
-          method, path: fullPath, handlerName,
-          sourceFile: rel(absFile), sourceLine: p.node.loc?.start.line ?? 0,
-          params, description: leading.slice(0, 400), mutating, confidence,
+          method,
+          path: fullPath,
+          handlerName,
+          sourceFile: rel(absFile),
+          sourceLine: p.node.loc?.start.line ?? 0,
+          params,
+          description: leading.slice(0, 400),
+          mutating,
+          confidence,
         });
       },
     });
@@ -163,16 +242,26 @@ export function parseExpressProject(cwd, entryFile) {
     }
   }
 
-  function rel(abs) { return path.relative(cwd, abs).split(path.sep).join('/'); }
+  function rel(abs) {
+    return path.relative(cwd, abs).split(path.sep).join('/');
+  }
 
   function resolveRel(fromFile, spec) {
     if (!spec.startsWith('.')) return null;
     const cleanSpec = spec.replace(/\.(m?[jt]s|cjs)$/, '');
     const base = path.resolve(path.dirname(fromFile), cleanSpec);
-    for (const cand of [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, `${base}.cjs`,
-      path.join(base, 'index.ts'), path.join(base, 'index.js')]) {
+    for (const cand of [
+      base,
+      `${base}.ts`,
+      `${base}.js`,
+      `${base}.mjs`,
+      `${base}.cjs`,
+      path.join(base, 'index.ts'),
+      path.join(base, 'index.js'),
+    ]) {
       if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
-        if ([...EXCLUDE].some((x) => cand.includes(`${path.sep}${x}${path.sep}`))) return null;
+        if ([...EXCLUDE].some((x) => cand.includes(`${path.sep}${x}${path.sep}`)))
+          return null;
         return cand;
       }
     }
@@ -187,27 +276,36 @@ export function parseExpressProject(cwd, entryFile) {
 function queryParamsOf(callPath) {
   const reqNames = new Set();
   for (const a of callPath.node.arguments) {
-    if ((a.type === 'ArrowFunctionExpression' || a.type === 'FunctionExpression') && a.params[0]?.type === 'Identifier') {
+    if (
+      (a.type === 'ArrowFunctionExpression' || a.type === 'FunctionExpression') &&
+      a.params[0]?.type === 'Identifier'
+    ) {
       reqNames.add(a.params[0].name);
     }
   }
   const found = [];
   if (!reqNames.size) return found;
-  const isReqQuery = (n) => n?.type === 'MemberExpression' && !n.computed &&
-    n.object?.type === 'Identifier' && reqNames.has(n.object.name) &&
-    n.property?.type === 'Identifier' && n.property.name === 'query';
+  const isReqQuery = (n) =>
+    n?.type === 'MemberExpression' &&
+    !n.computed &&
+    n.object?.type === 'Identifier' &&
+    reqNames.has(n.object.name) &&
+    n.property?.type === 'Identifier' &&
+    n.property.name === 'query';
   callPath.traverse({
     MemberExpression(q) {
       const n = q.node;
       if (!isReqQuery(n.object) || found.length >= 15) return;
       if (!n.computed && n.property.type === 'Identifier') found.push(n.property.name);
-      else if (n.computed && n.property.type === 'StringLiteral') found.push(n.property.value);
+      else if (n.computed && n.property.type === 'StringLiteral')
+        found.push(n.property.value);
     },
     VariableDeclarator(q) {
       if (q.node.id.type !== 'ObjectPattern' || !isReqQuery(q.node.init)) return;
       for (const prop of q.node.id.properties) {
         if (found.length >= 15) break;
-        if (prop.type === 'ObjectProperty' && prop.key.type === 'Identifier') found.push(prop.key.name);
+        if (prop.type === 'ObjectProperty' && prop.key.type === 'Identifier')
+          found.push(prop.key.name);
       }
     },
   });
@@ -230,14 +328,16 @@ function dedupe(routes) {
 }
 
 export function toolNameFor(route, taken) {
-  let name = `${route.method}_${route.path}`
-    .toLowerCase()
-    .replace(/:(\w+)/g, 'by_$1')
-    .replace(/\{(\w+)\}/g, 'by_$1')
-    .replace(/[^a-z0-9]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-    .slice(0, 60) || 'tool';
-  let final = name; let i = 2;
+  let name =
+    `${route.method}_${route.path}`
+      .toLowerCase()
+      .replace(/:(\w+)/g, 'by_$1')
+      .replace(/\{(\w+)\}/g, 'by_$1')
+      .replace(/[^a-z0-9]+/g, '_')
+      .replace(/^_+|_+$/g, '')
+      .slice(0, 60) || 'tool';
+  let final = name;
+  let i = 2;
   while (taken.has(final)) final = `${name}_${i++}`;
   taken.add(final);
   return final;

package/src/parser/fastapi.js

@@ -7,8 +7,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export function parseFastAPIProject(cwd, entryFile, pythonCmd = 'python') {
   const extractorScript = path.resolve(__dirname, 'fastapi_extract.py');
-  const res = spawnSync(pythonCmd, [extractorScript, entryFile, cwd], { cwd, encoding: 'utf8' });
-  
+  const res = spawnSync(pythonCmd, [extractorScript, entryFile, cwd], {
+    cwd,
+    encoding: 'utf8',
+  });
+
   if (res.status !== 0) {
     const errorMsg = (res.stderr || res.stdout || '').trim();
     throw new Error(`FastAPI extraction process failed: ${errorMsg}`);
@@ -19,8 +22,14 @@ export function parseFastAPIProject(cwd, entryFile, pythonCmd = 'python') {
     if (payload.error) {
       throw new Error(payload.error);
     }
-    return { routes: payload.routes || [], skipped: payload.skipped || [], entryAppVars: payload.entryAppVars || [] };
+    return {
+      routes: payload.routes || [],
+      skipped: payload.skipped || [],
+      entryAppVars: payload.entryAppVars || [],
+    };
   } catch (err) {
-    throw new Error(`Failed to parse Python extractor output: ${err.message}. Raw output: ${res.stdout}`);
+    throw new Error(
+      `Failed to parse Python extractor output: ${err.message}. Raw output: ${res.stdout}`,
+    );
   }
 }

package/src/probe/express-shim-esm.mjs

@@ -18,10 +18,10 @@
 
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
-import { dirname, resolve }  from 'node:path';
+import { dirname, resolve } from 'node:path';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const require   = createRequire(import.meta.url);
+const require = createRequire(import.meta.url);
 
 // Load the CJS shim — patches Module._load globally in the CJS loader
 require(resolve(__dirname, 'express-shim.cjs'));

package/src/probe/express-shim.cjs

@@ -31,16 +31,16 @@ if (!process.env.SPARDA_PROBE) {
 }
 
 function installShim() {
-  const net    = require('net');
+  const net = require('net');
   const Module = require('module');
 
   const IPC_PORT = parseInt(process.env.SPARDA_IPC_PORT, 10) || 0;
 
   // ── Transport: fork IPC or TCP fallback ────────────────────────────────────
 
-  let socket      = null;
+  let socket = null;
   let socketReady = false;
-  const pending   = [];
+  const pending = [];
 
   function connectTcp() {
     if (socket || !IPC_PORT) return;
@@ -50,23 +50,33 @@ function installShim() {
       for (const line of pending) socket.write(line);
       pending.length = 0;
     });
-    socket.on('error', () => { socket = null; socketReady = false; });
+    socket.on('error', () => {
+      socket = null;
+      socketReady = false;
+    });
   }
 
   function sendLine(line) {
     if (typeof process.send === 'function') {
-      try { process.send(JSON.parse(line.trimEnd())); return; } catch {}
+      try {
+        process.send(JSON.parse(line.trimEnd()));
+        return;
+      } catch {}
     }
     connectTcp();
     if (socketReady && socket) socket.write(line);
     else pending.push(line);
   }
 
-  function sendMsg(obj)  { sendLine(JSON.stringify(obj) + '\n'); }
+  function sendMsg(obj) {
+    sendLine(JSON.stringify(obj) + '\n');
+  }
 
   function sendDone() {
     if (typeof process.send === 'function') {
-      try { process.send({ type: '__done__' }); } catch {}
+      try {
+        process.send({ type: '__done__' });
+      } catch {}
       return;
     }
     const finish = () => {
@@ -93,7 +103,17 @@ function installShim() {
 
   // ── HTTP method list ───────────────────────────────────────────────────────
 
-  const HTTP_METHODS = ['get','post','put','patch','delete','del','head','options','all'];
+  const HTTP_METHODS = [
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'del',
+    'head',
+    'options',
+    'all',
+  ];
 
   // ── Core wrapper — works on any target object ──────────────────────────────
   //
@@ -117,7 +137,10 @@ function installShim() {
       };
     }
     try {
-      Object.defineProperty(target, '__sparda_wrapped__', { value: true, configurable: true });
+      Object.defineProperty(target, '__sparda_wrapped__', {
+        value: true,
+        configurable: true,
+      });
     } catch {}
   }
 
@@ -133,20 +156,30 @@ function installShim() {
     if (!appProto || appProto.__sparda_listen_patched__) return;
     if (typeof appProto.listen !== 'function') return;
     try {
-      Object.defineProperty(appProto, '__sparda_listen_patched__', { value: true, configurable: true });
+      Object.defineProperty(appProto, '__sparda_listen_patched__', {
+        value: true,
+        configurable: true,
+      });
     } catch {}
-    const origListen = appProto.listen;
     appProto.listen = function spardaListen(...args) {
       clearTimeout(idleTimer);
       // §ANALYSE §2: call the listen callback so routes registered inside it are captured
-      const cb = args.find(a => typeof a === 'function');
-      if (cb) { try { cb(); } catch {} }
+      const cb = args.find((a) => typeof a === 'function');
+      if (cb) {
+        try {
+          cb();
+        } catch {}
+      }
       sendDone();
       // Do NOT call origListen — no real socket in probe mode
       return {
-        on()      { return this; },
-        close()   {},
-        address() { return { port: 0, address: '127.0.0.1', family: 'IPv4' }; },
+        on() {
+          return this;
+        },
+        close() {},
+        address() {
+          return { port: 0, address: '127.0.0.1', family: 'IPv4' };
+        },
       };
     };
   }
@@ -156,7 +189,10 @@ function installShim() {
   function patchExpress(exp) {
     if (!exp || exp.__sparda_factory_patched__) return;
     try {
-      Object.defineProperty(exp, '__sparda_factory_patched__', { value: true, configurable: true });
+      Object.defineProperty(exp, '__sparda_factory_patched__', {
+        value: true,
+        configurable: true,
+      });
     } catch {}
 
     // Surface 1: express.application — catches app.get/post/... (Express 4 & 5)
@@ -179,7 +215,7 @@ function installShim() {
   // ── Intercept require('express') via Module._load ─────────────────────────
 
   const originalLoad = Module._load;
-  Module._load = function spardaLoad(request, parent, isMain) {
+  Module._load = function spardaLoad(request) {
     const result = originalLoad.apply(this, arguments);
     if (request === 'express') patchExpress(result);
     return result;
@@ -190,8 +226,8 @@ function installShim() {
   // this shim loaded, Module._load hook fires too late. Patch the cached export.
 
   try {
-    const expressPaths = Object.keys(require.cache).filter(
-      k => /[/\\]express[/\\]index\.js$/.test(k)
+    const expressPaths = Object.keys(require.cache).filter((k) =>
+      /[/\\]express[/\\]index\.js$/.test(k),
     );
     for (const p of expressPaths) {
       const cached = require.cache[p];
@@ -201,8 +237,15 @@ function installShim() {
 
   // ── Safety nets ────────────────────────────────────────────────────────────
 
-  process.on('exit',    () => { try { sendDone(); } catch {} });
-  process.on('SIGTERM', () => { sendDone(); setTimeout(() => process.exit(0), 200); });
+  process.on('exit', () => {
+    try {
+      sendDone();
+    } catch {}
+  });
+  process.on('SIGTERM', () => {
+    sendDone();
+    setTimeout(() => process.exit(0), 200);
+  });
 
   module.exports = { record, sendDone };
 }

package/src/probe/integrate.js

@@ -17,7 +17,7 @@
  */
 
 import { probeRoutes } from './probe.js';
-import { reconcile }   from './reconcile.js';
+import { reconcile } from './reconcile.js';
 
 const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 
@@ -40,21 +40,31 @@ const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
  */
 export function gapToStaticRoute(gap, framework) {
   const method = (gap.method ?? 'GET').toUpperCase();
-  const lower  = method.toLowerCase();
-  const mutating = gap.writeClass ? gap.writeClass === 'write' : WRITE_METHODS.has(method);
+  const lower = method.toLowerCase();
+  const mutating = gap.writeClass
+    ? gap.writeClass === 'write'
+    : WRITE_METHODS.has(method);
 
-  const path = framework === 'fastapi'
-    ? (gap.path ?? '/').replace(/:([a-zA-Z_]\w*)/g, '{$1}')
-    : (gap.path ?? '/');
+  const path =
+    framework === 'fastapi'
+      ? (gap.path ?? '/').replace(/:([a-zA-Z_]\w*)/g, '{$1}')
+      : (gap.path ?? '/');
 
   // Path params, in the exact param object the static parser uses.
   const params = (gap.pathParams ?? []).map((name) => ({
-    name, in: 'path', type: 'string', required: true, description: 'path parameter',
+    name,
+    in: 'path',
+    type: 'string',
+    required: true,
+    description: 'path parameter',
   }));
   // Mirror the static parser: mutating routes get a body param (schema unknown).
   if (mutating) {
     params.push({
-      name: 'body', in: 'body', type: 'object', required: false,
+      name: 'body',
+      in: 'body',
+      type: 'object',
+      required: false,
       description: 'JSON body — schema not statically detected',
     });
   }
@@ -68,7 +78,7 @@ export function gapToStaticRoute(gap, framework) {
     params,
     description: 'Discovered at runtime via --probe; not found by static analysis.',
     mutating,
-    confidence: 'low',   // never statically verified → always low
+    confidence: 'low', // never statically verified → always low
     source: 'dynamic',
   };
 }
@@ -84,9 +94,15 @@ export function gapToStaticRoute(gap, framework) {
  *   gaps        — the raw minimal gaps (stored in the scan-report for provenance)
  *   probedCount — how many routes the probe observed (0 ⇒ probe degraded / nothing seen)
  */
-export async function discoverDynamicRoutes({ framework, entryFile, projectRoot, staticRoutes, timeoutMs = 8000 }) {
+export async function discoverDynamicRoutes({
+  framework,
+  entryFile,
+  projectRoot,
+  staticRoutes,
+  timeoutMs = 8000,
+}) {
   const probed = await probeRoutes({ framework, entryFile, projectRoot, timeoutMs });
-  const { gaps, staticCount, dynamicCount } = reconcile(staticRoutes, probed);
+  const { gaps, staticCount } = reconcile(staticRoutes, probed);
 
   // Defensive: the probe should not emit duplicate (method, path) pairs, but
   // reconcile does not dedup gaps among themselves. Collapse here so we never
@@ -100,5 +116,11 @@ export async function discoverDynamicRoutes({ framework, entryFile, projectRoot,
   });
 
   const added = uniqueGaps.map((g) => gapToStaticRoute(g, framework));
-  return { added, gaps: uniqueGaps, staticCount, dynamicCount: added.length, probedCount: probed.length };
+  return {
+    added,
+    gaps: uniqueGaps,
+    staticCount,
+    dynamicCount: added.length,
+    probedCount: probed.length,
+  };
 }