magector 2.11.1 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.11.1",
+  "version": "2.13.0",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -33,10 +33,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "2.11.1",
-    "@magector/cli-linux-x64": "2.11.1",
-    "@magector/cli-linux-arm64": "2.11.1",
-    "@magector/cli-win32-x64": "2.11.1"
+    "@magector/cli-darwin-arm64": "2.13.0",
+    "@magector/cli-linux-x64": "2.13.0",
+    "@magector/cli-linux-arm64": "2.13.0",
+    "@magector/cli-win32-x64": "2.13.0"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -3425,6 +3425,206 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
   return result;
 }
 
+// ─── Method Chain Enrichment ────────────────────────────────────
+// Scans PHP files for two-step method chains (->first()->second()) and detects
+// null guards in surrounding code. Results stored in SQLite enrichment.db for
+// instant O(1) queries — eliminates 20+ grep calls for null-risk analyses.
+
+const ENRICHMENT_DB_PATH = (root) => path.join(root, '.magector', 'enrichment.db');
+
+/**
+ * Detect null guard for a chained call in surrounding lines.
+ * Checks ±guardRadius lines for: null checks, ?->, ??, isset()
+ */
+function hasNullGuard(lines, matchLineIdx, receiverExpr, guardRadius = 6) {
+  const start = Math.max(0, matchLineIdx - guardRadius);
+  const end = Math.min(lines.length - 1, matchLineIdx + guardRadius);
+  const window = lines.slice(start, end + 1).join('\n');
+
+  if (window.includes('?->')) return true;
+  if (/\?\?|\?:/.test(window)) return true;
+
+  if (receiverExpr) {
+    const esc = receiverExpr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (new RegExp(`(?:is_null\\s*\\(\\s*${esc}|${esc}\\s*(?:===|!==)\\s*null|!\\s*${esc}\\s*[,)]|isset\\s*\\(\\s*${esc})`, 'i').test(window)) return true;
+  }
+  return false;
+}
+
+/**
+ * Scan vendor/ PHP files for ->first()->second() chains and store null-safety
+ * analysis in enrichment.db. Called by magento_enrich and after magento_index.
+ */
+async function enrichMethodChains(root, options = {}) {
+  const dbPath = ENRICHMENT_DB_PATH(root);
+
+  // Use node:sqlite (built-in, no deps)
+  let DatabaseSync;
+  try {
+    ({ DatabaseSync } = await import('node:sqlite'));
+  } catch {
+    throw new Error('node:sqlite not available — requires Node.js 22.5+');
+  }
+
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS method_chains (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file TEXT NOT NULL,
+      line INTEGER NOT NULL,
+      chain TEXT NOT NULL,
+      first_method TEXT NOT NULL,
+      second_method TEXT NOT NULL,
+      has_null_guard INTEGER NOT NULL DEFAULT 0,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_first_method ON method_chains (first_method);
+    CREATE INDEX IF NOT EXISTS idx_null_guard ON method_chains (has_null_guard, first_method);
+  `);
+
+  // Two-step chain: $var->firstMethod(...)->secondMethod(
+  // Captures: receiver ($var), firstMethod, secondMethod
+  const chainRegex = /(\$\w+)\s*->\s*(\w+)\s*\([^)]{0,60}\)\s*->\s*(\w+)\s*\(/g;
+  const now = Date.now();
+
+  const phpFiles = await glob('vendor/**/*.php', { cwd: root, absolute: true, nodir: true });
+  let scanned = 0;
+  let chains = 0;
+
+  const insertStmt = db.prepare(
+    'INSERT INTO method_chains (file, line, chain, first_method, second_method, has_null_guard, updated_at) VALUES (?,?,?,?,?,?,?)'
+  );
+  const deleteFile = db.prepare('DELETE FROM method_chains WHERE file = ?');
+
+  // Process files in batches for memory efficiency
+  for (const phpFile of phpFiles) {
+    let content;
+    try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+    if (!content.includes('->')) continue;
+
+    const relPath = phpFile.replace(root + '/', '');
+    const lines = content.split('\n');
+    const rows = [];
+
+    chainRegex.lastIndex = 0;
+    let m;
+    while ((m = chainRegex.exec(content)) !== null) {
+      const lineNum = content.slice(0, m.index).split('\n').length;
+      rows.push({
+        file: relPath, line: lineNum,
+        chain: `->${m[2]}()->${m[3]}()`,
+        firstMethod: m[2], secondMethod: m[3],
+        hasNullGuard: hasNullGuard(lines, lineNum - 1, m[1]) ? 1 : 0
+      });
+      chains++;
+    }
+
+    if (rows.length > 0) {
+      deleteFile.run(relPath);
+      for (const r of rows) {
+        insertStmt.run(r.file, r.line, r.chain, r.firstMethod, r.secondMethod, r.hasNullGuard, now);
+      }
+    }
+    scanned++;
+  }
+
+  db.close();
+  return { scanned, chains };
+}
+
+/**
+ * Query enrichment.db for unsafe method chains (no null guard).
+ */
+async function queryNullRisks(root, firstMethod, limit = 100) {
+  const dbPath = ENRICHMENT_DB_PATH(root);
+  if (!existsSync(dbPath)) return null;
+
+  let DatabaseSync;
+  try {
+    ({ DatabaseSync } = await import('node:sqlite'));
+  } catch {
+    return null;
+  }
+
+  const db = new DatabaseSync(dbPath, { open: true });
+  let rows;
+  try {
+    if (firstMethod) {
+      rows = db.prepare(
+        'SELECT file, line, chain, second_method FROM method_chains WHERE has_null_guard = 0 AND first_method = ? ORDER BY file, line LIMIT ?'
+      ).all(firstMethod, limit);
+    } else {
+      rows = db.prepare(
+        'SELECT file, line, chain, first_method, second_method FROM method_chains WHERE has_null_guard = 0 ORDER BY first_method, file, line LIMIT ?'
+      ).all(limit);
+    }
+  } finally {
+    db.close();
+  }
+  return rows;
+}
+
+// ─── AST Search (semgrep) ───────────────────────────────────────
+
+async function astSearch(pattern, searchPath, lang, maxResults) {
+  const root = config.magentoRoot;
+  if (!root) throw new Error('MAGENTO_ROOT not set');
+
+  const targetPath = searchPath ? path.join(root, searchPath) : root;
+  const semgrepLang = lang || 'php';
+  const limit = Math.min(maxResults || 50, 200);
+
+  // Create a temporary empty .semgrepignore in the target directory if none exists.
+  // Semgrep's default ignore list includes "vendor/" which is exactly what we need to scan.
+  // An empty .semgrepignore overrides the defaults: https://semgrep.dev/docs/ignoring-files-folders-code/
+  const semgrepIgnorePath = path.join(targetPath, '.semgrepignore');
+  let createdSemgrepIgnore = false;
+  if (!existsSync(semgrepIgnorePath)) {
+    try { writeFileSync(semgrepIgnorePath, '# Magector: scan vendor/ and all project files\n'); createdSemgrepIgnore = true; } catch { /* best effort */ }
+  }
+
+  const semgrepArgs = [
+    '--pattern', pattern,
+    '--lang', semgrepLang,
+    '--json',
+    '--no-git-ignore',
+    targetPath
+  ];
+
+  let rawOutput;
+  try {
+    rawOutput = execFileSync('semgrep', semgrepArgs, {
+      encoding: 'utf-8',
+      timeout: 60000,
+      maxBuffer: 20 * 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, PATH: process.env.PATH + ':/home/swed/.local/bin' }
+    });
+  } catch (err) {
+    // semgrep exits non-zero when it has findings — stdout still contains valid JSON
+    rawOutput = err.stdout || '';
+    if (!rawOutput) throw new Error(`semgrep failed: ${(err.stderr || err.message || '').slice(0, 500)}`);
+  } finally {
+    if (createdSemgrepIgnore) { try { unlinkSync(semgrepIgnorePath); } catch { /* best effort */ } }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawOutput);
+  } catch {
+    throw new Error(`Failed to parse semgrep output. First 300 chars: ${rawOutput.slice(0, 300)}`);
+  }
+
+  const findings = (parsed.results || []).slice(0, limit);
+  return findings.map(r => ({
+    file: r.path.replace(root + '/', ''),
+    line: r.start.line,
+    endLine: r.end.line,
+    snippet: (r.extra?.lines || '').trim()
+  }));
+}
+
 // ─── MCP Server ─────────────────────────────────────────────────
 
 const server = new Server(
@@ -4143,13 +4343,69 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           context: {
             type: 'number',
-            description: 'Lines of context around each match (default: 2). Like grep -C.',
-            default: 2
+            description: 'Lines of context around each match (default: 4). Like grep -C. Use 0 for broad scans with many matches, then batch-read specific files.',
+            default: 4
+          },
+          filesOnly: {
+            type: 'boolean',
+            description: 'Return only file paths (like grep -l). No content, no context. Use for discovery: first find which files match, then batch-read them with magento_read. Dramatically reduces tokens when pattern matches many files.',
+            default: false
           }
         },
         required: ['pattern']
       }
     },
+    {
+      name: 'magento_ast_search',
+      description: 'Structural PHP code search using semgrep patterns. Unlike magento_grep (text-based), this understands PHP AST — matches code structure regardless of variable names, ignores comments/strings, understands operator precedence. Use when grep gives false positives or you need structural awareness. Pattern syntax: $X = any expression/variable, $Y = any identifier, ... = any arguments. Examples: "$ORDER->getPayment()->$M(...)" finds all method calls on payment regardless of variable name; "$X->getPayment()->$Y(...)" finds all two-step chains involving getPayment. ⚡ For multi-query workflows use magento_batch.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: {
+            type: 'string',
+            description: 'Semgrep PHP pattern. $X = any expr, $Y = any identifier, ... = any args. Examples: "$X->getPayment()->$Y(...)", "if ($X !== null) { ... $X->$Y(...) }", "$X = $Y->getPayment(); ... $X->$Z(...)"'
+          },
+          path: {
+            type: 'string',
+            description: 'Subdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"'
+          },
+          lang: {
+            type: 'string',
+            description: 'Language to search (default: php). Options: php, xml, js.',
+            default: 'php'
+          },
+          maxResults: {
+            type: 'number',
+            description: 'Maximum matches to return (default: 50, max: 200)',
+            default: 50
+          }
+        },
+        required: ['pattern']
+      }
+    },
+    {
+      name: 'magento_enrich',
+      description: 'Build the method-chain enrichment index. Scans all vendor/ PHP files for two-step method chains (->firstMethod()->secondMethod()) and analyses whether each call has a null guard in surrounding code. Results stored in .magector/enrichment.db. Run this once after magento_index, then use magento_find_null_risks for instant O(1) null-safety queries instead of 20+ grep calls. Also runs automatically after magento_index completes.',
+      inputSchema: { type: 'object', properties: {} }
+    },
+    {
+      name: 'magento_find_null_risks',
+      description: 'Find method chains without null guards using the pre-built enrichment index. Returns all ->firstMethod()->secondMethod() calls where no null check (=== null, !== null, ?->, ??, isset, is_null) was detected in surrounding code. Requires magento_enrich to have been run first. 100× faster than grep — O(1) SQLite query vs O(n) file scan. Use firstMethod to filter (e.g., "getPayment" finds all ->getPayment()->anything() without null guard). ⚡ For multi-query workflows use magento_batch.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          firstMethod: {
+            type: 'string',
+            description: 'Filter by first method name. Example: "getPayment" returns all ->getPayment()->$X() without null guard. Omit to get all unsafe chains.'
+          },
+          limit: {
+            type: 'number',
+            description: 'Maximum results (default: 100, max: 500)',
+            default: 100
+          }
+        }
+      }
+    },
     {
       name: 'magento_trace_api',
       description: 'Trace a REST or GraphQL API endpoint from URL to implementation. Parses webapi.xml to find the service interface, resolves the DI preference to the concrete class, reads the execute/method body, and checks di.xml for constructor arguments. Returns the complete chain in one call.',
@@ -4216,7 +4472,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // These tools have filesystem/di.xml fallbacks — work without serve process
     'magento_find_class', 'magento_find_method', 'magento_find_plugin',
     'magento_find_observer', 'magento_find_di_wiring', 'magento_module_structure',
-    'magento_batch', 'magento_find_config', 'magento_find_callers', 'magento_grep', 'magento_read', 'magento_trace_api'];
+    'magento_batch', 'magento_find_config', 'magento_find_callers', 'magento_grep', 'magento_read', 'magento_trace_api', 'magento_ast_search', 'magento_find_null_risks'];
   if (warmupInProgress && !indexFreeTools.includes(name)) {
     logToFile('REQ', `${name} → blocked (warmup: loading index)`);
     return {
@@ -4479,10 +4735,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'magento_index': {
         const root = args.path || config.magentoRoot;
         const output = rustIndex(root);
+        // Auto-enrich after indexing: runs in background, doesn't block response
+        enrichMethodChains(root, { verbose: true }).then(({ scanned, chains }) => {
+          logToFile('INFO', `Auto-enrich complete: ${scanned} files, ${chains} chains`);
+        }).catch(err => {
+          logToFile('WARN', `Auto-enrich failed: ${err.message}`);
+        });
         return {
           content: [{
             type: 'text',
-            text: `Indexing complete (Rust core).\n\n${output}`
+            text: `Indexing complete (Rust core).\n\n${output}\n\n_Method-chain enrichment index is being built in the background. Use \`magento_enrich\` to run it manually or wait ~30-60s._`
           }]
         };
       }
@@ -6078,10 +6340,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const searchPath = a.path || '.';
                 const include = a.include || '*.php';
                 const maxRes = Math.min(a.maxResults || 30, 100);
-                const batchCtx = a.context !== undefined ? a.context : 2;
+                const batchCtx = a.context !== undefined ? a.context : 4;
+                const batchFilesOnly = a.filesOnly || false;
                 const gArgs = ['-rn', '-E'];
+                if (batchFilesOnly) { gArgs[0] = '-rl'; gArgs.splice(1, 1); } // -rl = recursive + files-only, drop -n
                 if (a.ignoreCase) gArgs.push('-i');
-                if (batchCtx > 0) gArgs.push('-C', String(batchCtx));
+                if (!batchFilesOnly && batchCtx > 0) gArgs.push('-C', String(batchCtx));
                 for (const pat of include.split(',').map(p => p.trim())) gArgs.push('--include=' + pat);
                 gArgs.push('--', a.pattern, searchPath);
                 let out;
@@ -6089,8 +6353,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   out = execFileSync('grep', gArgs, { cwd: config.magentoRoot, encoding: 'utf-8', timeout: 15000, maxBuffer: 5 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
                 } catch (err) { out = err.stdout || ''; }
                 const gLines = out.trim().split('\n').filter(Boolean);
-                text = `Found ${gLines.length} matches${gLines.length > maxRes ? ` (showing ${maxRes})` : ''}:\n`;
-                for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
+                if (batchFilesOnly) {
+                  text = `Files matching \`${a.pattern}\` (${gLines.length}):\n`;
+                  for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
+                } else {
+                  text = `Found ${gLines.length} matches${gLines.length > maxRes ? ` (showing ${maxRes})` : ''}:\n`;
+                  for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
+                }
+                break;
+              }
+              case 'magento_ast_search': {
+                const astResults = await astSearch(a.pattern, a.path, a.lang, a.maxResults);
+                if (astResults.length === 0) {
+                  text = `No matches for pattern: \`${a.pattern}\``;
+                } else {
+                  text = `Found ${astResults.length} match(es) for \`${a.pattern}\`:\n\n`;
+                  for (const r of astResults) text += `${r.file}:${r.line}: ${r.snippet}\n`;
+                }
+                break;
+              }
+              case 'magento_find_null_risks': {
+                const bRoot = config.magentoRoot;
+                const bLimit = Math.min(a.limit || 100, 500);
+                const bRows = bRoot ? await queryNullRisks(bRoot, a.firstMethod || null, bLimit) : null;
+                if (!bRows) { text = '⚠️ Run magento_enrich first.'; break; }
+                if (bRows.length === 0) { text = 'No unsafe chains found.'; break; }
+                text = `Found ${bRows.length} unsafe chain(s):\n`;
+                for (const r of bRows.slice(0, 50)) {
+                  const chain = r.chain || `->${r.first_method}()->${r.second_method}()`;
+                  text += `${r.file}:${r.line}: ${chain}\n`;
+                }
                 break;
               }
               default:
@@ -6115,10 +6407,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const searchPath = args.path || '.';
         const include = args.include || '*.php';
         const maxResults = Math.min(args.maxResults || 50, 200);
-        const ctxLines = args.context !== undefined ? args.context : 2;
-        const grepArgs = ['-rn', '-E'];
+        const ctxLines = args.context !== undefined ? args.context : 4;
+        const filesOnly = args.filesOnly || false;
+        const grepArgs = filesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
         if (args.ignoreCase) grepArgs.push('-i');
-        if (ctxLines > 0) grepArgs.push('-C', String(ctxLines));
+        if (!filesOnly && ctxLines > 0) grepArgs.push('-C', String(ctxLines));
         // Support multiple include patterns (e.g., "*.{php,xml}")
         for (const pat of include.split(',').map(p => p.trim())) {
           grepArgs.push('--include=' + pat);
@@ -6138,8 +6431,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const lines = output.trim().split('\n').filter(Boolean);
         const total = lines.length;
         const truncated = lines.slice(0, maxResults);
-        let text = `## grep: \`${args.pattern}\`\n`;
-        text += `Found **${total}** matches${total > maxResults ? ` (showing first ${maxResults})` : ''}\n\n`;
+        let text = filesOnly
+          ? `## grep (files only): \`${args.pattern}\`\nFound **${total}** file(s)${total > maxResults ? ` (showing first ${maxResults})` : ''}. Use magento_read with methodName to read specific methods.\n\n`
+          : `## grep: \`${args.pattern}\`\nFound **${total}** matches${total > maxResults ? ` (showing first ${maxResults})` : ''}\n\n`;
         for (const line of truncated) {
           text += line + '\n';
         }
@@ -6324,10 +6618,75 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const numbered = sliced.map((line, i) => `${start + i + 1}\t${line}`).join('\n');
         let text = `## ${args.path}`;
         if (args.startLine || args.endLine) text += ` (lines ${start + 1}-${end})`;
+        // Hint: large file read without method extraction wastes tokens
+        if (!args.startLine && !args.endLine && allLines.length > 100) {
+          const methodMatches = content.match(/(?:public|protected|private)\s+(?:static\s+)?function\s+(\w+)/g) || [];
+          const methodNames = methodMatches.slice(0, 8).map(m => m.replace(/.*function\s+/, '')).join(', ');
+          text += `\n> 💡 **${allLines.length} lines** — add \`methodName\` to extract a single method (~10× fewer tokens). Methods: ${methodNames}${methodMatches.length > 8 ? ', ...' : ''}`;
+        }
         text += `\n\n${numbered}`;
         return { content: [{ type: 'text', text }] };
       }
 
+      case 'magento_ast_search': {
+        const astResults = await astSearch(args.pattern, args.path, args.lang, args.maxResults);
+        if (astResults.length === 0) {
+          return { content: [{ type: 'text', text: `## magento_ast_search: \`${args.pattern}\`\n\nNo matches found.` }] };
+        }
+        let text = `## magento_ast_search: \`${args.pattern}\`\n`;
+        text += `Found **${astResults.length}** match(es)\n\n`;
+        for (const r of astResults) {
+          const lineInfo = r.endLine && r.endLine !== r.line ? `${r.line}-${r.endLine}` : String(r.line);
+          text += `**${r.file}:${lineInfo}**\n\`\`\`php\n${r.snippet}\n\`\`\`\n\n`;
+        }
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_enrich': {
+        const root = config.magentoRoot;
+        if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };
+        let text = `## magento_enrich\n\nScanning vendor/ PHP files for method chains...\n`;
+        try {
+          const { scanned, chains } = await enrichMethodChains(root, { verbose: true });
+          text += `\n✅ **Done**\n- Files scanned: ${scanned}\n- Method chains indexed: ${chains}\n- Null-risk index saved to: \`.magector/enrichment.db\`\n\nUse \`magento_find_null_risks\` to query unsafe chains.`;
+        } catch (err) {
+          text += `\n❌ Error: ${err.message}`;
+        }
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_null_risks': {
+        const root = config.magentoRoot;
+        if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };
+        const limit = Math.min(args.limit || 100, 500);
+        const rows = await queryNullRisks(root, args.firstMethod || null, limit);
+        if (rows === null) {
+          return { content: [{ type: 'text', text: `## magento_find_null_risks\n\n⚠️ Enrichment index not found. Run \`magento_enrich\` first to build the method-chain index.` }] };
+        }
+        if (rows.length === 0) {
+          const filter = args.firstMethod ? ` for \`->${args.firstMethod}()\`` : '';
+          return { content: [{ type: 'text', text: `## magento_find_null_risks${filter}\n\nNo unsafe chains found. All detected chains have null guards.` }] };
+        }
+        const filter = args.firstMethod ? ` for \`->${args.firstMethod}()\`` : '';
+        let text = `## magento_find_null_risks${filter}\n\nFound **${rows.length}** chain(s) without null guard:\n\n`;
+        // Group by chain type for readability
+        const byChain = {};
+        for (const r of rows) {
+          const key = r.chain || `->${r.first_method}()->${r.second_method}()`;
+          if (!byChain[key]) byChain[key] = [];
+          byChain[key].push(r);
+        }
+        for (const [chain, sites] of Object.entries(byChain)) {
+          text += `### \`${chain}\` (${sites.length} site${sites.length > 1 ? 's' : ''})\n`;
+          for (const s of sites.slice(0, 20)) {
+            text += `- \`${s.file}:${s.line}\`\n`;
+          }
+          if (sites.length > 20) text += `- ... and ${sites.length - 20} more\n`;
+          text += '\n';
+        }
+        return { content: [{ type: 'text', text }] };
+      }
+
       default:
         return {
           content: [{