magector 2.13.3 → 2.14.1

package/README.md

@@ -1204,6 +1204,67 @@ gantt
 
 ---
 
+## Troubleshooting
+
+All MCP server activity is logged to `.magector/magector.log` in the Magento project root. The log persists across MCP restarts and uses the format:
+
+```
+[2026-04-12T18:30:00.000Z] [LEVEL] message
+```
+
+### Log Levels
+
+| Level | Meaning |
+|-------|---------|
+| `INFO` | Normal operations: startup config, tool completion, search fallbacks, enrichment progress |
+| `WARN` | Recoverable issues: slow grep queries (>5s), missing enrichment.db, file read errors, serve process disconnects |
+| `ERR` | Failures: semgrep crashes, transaction rollbacks, serve process errors, tool execution errors |
+| `REQ` | Every tool call with full input parameters (JSON) |
+| `RES` | Tool completion with elapsed time in milliseconds |
+| `QUERY` | Rust serve process queries (search, feedback) |
+| `CACHE` | Search cache hits |
+| `INDEX` | Background reindex progress |
+| `SERVE` | Rust serve process stderr (watcher events, model loading) |
+| `FATAL` | Server startup failures |
+
+### Common Diagnostic Commands
+
+```bash
+# Recent errors
+grep '\[ERR\]\|\[FATAL\]' .magector/magector.log | tail -20
+
+# Tool timing (find slow tools)
+grep '\[RES\]' .magector/magector.log | tail -20
+
+# Enrichment/null-risk analysis
+grep 'enrich:\|null_risks:' .magector/magector.log | tail -20
+
+# AST search (semgrep) issues
+grep 'ast_search:' .magector/magector.log | tail -20
+
+# Batch query breakdown (per-tool timing)
+grep 'batch\[' .magector/magector.log | tail -20
+
+# Slow grep queries
+grep 'grep: slow\|grep: timed' .magector/magento.log | tail -20
+
+# Full startup sequence
+grep 'server starting\|Config:\|primary\|Serve process' .magector/magector.log | tail -30
+```
+
+### What Gets Logged (v2.14+)
+
+Every tool call logs `[REQ]` with input parameters and `[RES]` with elapsed time. Additionally:
+
+- **`magento_ast_search`** — semgrep pattern, target path, execution time, result count, semgrep errors
+- **`magento_enrich`** — file count, progress every 10k files, read errors, transaction failures, final summary
+- **`magento_find_null_risks`** — query parameters, result count, query timing, missing DB warnings
+- **`magento_batch`** — query list on entry, per-sub-tool timing and errors
+- **`magento_grep`** — slow query warnings (>5s), timeout detection
+- **`magento_read`** — file-not-found with error codes, failed method extractions
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.13.3",
+  "version": "2.14.1",
   "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.13.3",
-    "@magector/cli-linux-x64": "2.13.3",
-    "@magector/cli-linux-arm64": "2.13.3",
-    "@magector/cli-win32-x64": "2.13.3"
+    "@magector/cli-darwin-arm64": "2.14.1",
+    "@magector/cli-linux-x64": "2.14.1",
+    "@magector/cli-linux-arm64": "2.14.1",
+    "@magector/cli-win32-x64": "2.14.1"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -149,6 +149,44 @@ const SOCK_PATH = path.join(config.magentoRoot, '.magector', 'serve.sock');
 const FORMAT_CACHE_PATH = path.join(config.magentoRoot, '.magector', 'format-ok.json');
 const PRIMARY_LOCK_PATH = path.join(config.magentoRoot, '.magector', 'primary.lock');
 
+/**
+ * Expand brace patterns in include globs for GNU grep compatibility.
+ * GNU grep --include does NOT support brace expansion (that's a shell feature).
+ * Transforms "*.{php,xml,graphqls}" → ["*.php", "*.xml", "*.graphqls"]
+ * Also handles comma-separated patterns: "*.php, *.xml" → ["*.php", "*.xml"]
+ * And mixed: "*.{php,xml}, *.phtml" → ["*.php", "*.xml", "*.phtml"]
+ */
+function expandIncludePattern(include) {
+  // Split on commas NOT inside braces
+  const parts = [];
+  let depth = 0, current = '';
+  for (const ch of include) {
+    if (ch === '{') depth++;
+    if (ch === '}') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  // Expand brace patterns in each part
+  const patterns = [];
+  const braceRegex = /^(.*?)\{([^}]+)\}(.*)$/;
+  for (const part of parts) {
+    const m = part.match(braceRegex);
+    if (m) {
+      for (const alt of m[2].split(',').map(a => a.trim())) {
+        patterns.push(m[1] + alt + m[3]);
+      }
+    } else {
+      patterns.push(part);
+    }
+  }
+  return patterns;
+}
+
 /**
  * Try to acquire the primary lock (O_EXCL = atomic create-or-fail).
  * Returns true if we are the primary instance, false if another instance holds the lock.
@@ -3459,12 +3497,15 @@ function hasNullGuard(lines, matchLineIdx, receiverExpr, guardRadius = 6) {
  */
 async function enrichMethodChains(root) {
   const dbPath = ENRICHMENT_DB_PATH(root);
+  logToFile('INFO', `enrich: starting method-chain scan, db=${dbPath}`);
+  const enrichStart = Date.now();
 
   // Use node:sqlite (built-in, no deps)
   let DatabaseSync;
   try {
     ({ DatabaseSync } = await import('node:sqlite'));
   } catch {
+    logToFile('ERR', 'enrich: node:sqlite not available — requires Node.js 22.5+');
     throw new Error('node:sqlite not available — requires Node.js 22.5+');
   }
 
@@ -3491,8 +3532,10 @@ async function enrichMethodChains(root) {
   const now = Date.now();
 
   const phpFiles = await glob('vendor/**/*.php', { cwd: root, absolute: true, nodir: true });
+  logToFile('INFO', `enrich: found ${phpFiles.length} PHP files in vendor/`);
   let scanned = 0;
   let chains = 0;
+  let readErrors = 0;
 
   const insertStmt = db.prepare(
     'INSERT INTO method_chains (file, line, chain, first_method, second_method, has_null_guard, updated_at) VALUES (?,?,?,?,?,?,?)'
@@ -3519,11 +3562,18 @@ async function enrichMethodChains(root) {
     return lo + 1; // 1-based
   }
 
+  // Progress logging every 10k files
+  const progressInterval = 10000;
+
   db.exec('BEGIN');
   try {
     for (const phpFile of phpFiles) {
       let content;
-      try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+      try { content = readFileSync(phpFile, 'utf-8'); } catch (err) {
+        readErrors++;
+        if (readErrors <= 5) logToFile('WARN', `enrich: cannot read ${phpFile}: ${err.code || err.message}`);
+        continue;
+      }
       if (!content.includes('->')) continue;
 
       const relPath = phpFile.replace(root + '/', '');
@@ -3551,14 +3601,20 @@ async function enrichMethodChains(root) {
         }
       }
       scanned++;
+      if (scanned % progressInterval === 0) {
+        logToFile('INFO', `enrich: progress ${scanned}/${phpFiles.length} files, ${chains} chains so far (${Date.now() - enrichStart}ms)`);
+      }
     }
     db.exec('COMMIT');
   } catch (err) {
+    logToFile('ERR', `enrich: transaction failed at file ${scanned}/${phpFiles.length}: ${err.message}`);
     db.exec('ROLLBACK');
     throw err;
   }
 
   db.close();
+  const enrichElapsed = Date.now() - enrichStart;
+  logToFile('INFO', `enrich: complete — ${scanned} files scanned, ${chains} chains indexed, ${readErrors} read errors, ${enrichElapsed}ms`);
   return { scanned, chains };
 }
 
@@ -3567,15 +3623,21 @@ async function enrichMethodChains(root) {
  */
 async function queryNullRisks(root, firstMethod, limit = 100) {
   const dbPath = ENRICHMENT_DB_PATH(root);
-  if (!existsSync(dbPath)) return null;
+  if (!existsSync(dbPath)) {
+    logToFile('WARN', `null_risks: enrichment.db not found at ${dbPath} — run magento_enrich first`);
+    return null;
+  }
 
   let DatabaseSync;
   try {
     ({ DatabaseSync } = await import('node:sqlite'));
-  } catch {
+  } catch (err) {
+    logToFile('ERR', `null_risks: node:sqlite not available: ${err.message}`);
     return null;
   }
 
+  const queryStart = Date.now();
+  logToFile('INFO', `null_risks: querying firstMethod=${firstMethod || '(all)'} limit=${limit}`);
   const db = new DatabaseSync(dbPath, { open: true });
   let rows;
   try {
@@ -3591,6 +3653,7 @@ async function queryNullRisks(root, firstMethod, limit = 100) {
   } finally {
     db.close();
   }
+  logToFile('INFO', `null_risks: ${rows.length} unsafe chain(s) found in ${Date.now() - queryStart}ms`);
   return rows;
 }
 
@@ -3604,13 +3667,22 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   const semgrepLang = lang || 'php';
   const limit = Math.min(maxResults || 50, 200);
 
+  logToFile('INFO', `ast_search: pattern="${pattern}" path="${searchPath || '.'}" lang=${semgrepLang} limit=${limit}`);
+  const astStart = Date.now();
+
   // 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 */ }
+    try {
+      writeFileSync(semgrepIgnorePath, '# Magector: scan vendor/ and all project files\n');
+      createdSemgrepIgnore = true;
+      logToFile('INFO', `ast_search: created temporary .semgrepignore at ${targetPath}`);
+    } catch (err) {
+      logToFile('WARN', `ast_search: failed to create .semgrepignore: ${err.message}`);
+    }
   }
 
   const semgrepArgs = [
@@ -3633,7 +3705,11 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   } 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)}`);
+    if (!rawOutput) {
+      const errMsg = (err.stderr || err.message || '').slice(0, 500);
+      logToFile('ERR', `ast_search: semgrep failed after ${Date.now() - astStart}ms: ${errMsg}`);
+      throw new Error(`semgrep failed: ${errMsg}`);
+    }
   } finally {
     if (createdSemgrepIgnore) { try { unlinkSync(semgrepIgnorePath); } catch { /* best effort */ } }
   }
@@ -3642,10 +3718,16 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   try {
     parsed = JSON.parse(rawOutput);
   } catch {
+    logToFile('ERR', `ast_search: failed to parse semgrep JSON output (${rawOutput.length} bytes)`);
     throw new Error(`Failed to parse semgrep output. First 300 chars: ${rawOutput.slice(0, 300)}`);
   }
 
   const findings = (parsed.results || []).slice(0, limit);
+  const astElapsed = Date.now() - astStart;
+  logToFile('INFO', `ast_search: ${findings.length} match(es) in ${astElapsed}ms (semgrep returned ${(parsed.results || []).length} total)`);
+  if (parsed.errors && parsed.errors.length > 0) {
+    logToFile('WARN', `ast_search: semgrep reported ${parsed.errors.length} error(s): ${parsed.errors.slice(0, 3).map(e => e.message || e.type || JSON.stringify(e)).join('; ')}`);
+  }
   return findings.map(r => ({
     file: r.path.replace(root + '/', ''),
     line: r.start.line,
@@ -4765,6 +4847,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const root = args.path || config.magentoRoot;
         const output = rustIndex(root);
         // Auto-enrich after indexing: runs in background, doesn't block response
+        logToFile('INFO', 'Auto-enrich: starting in background after index');
         enrichMethodChains(root).then(({ scanned, chains }) => {
           logToFile('INFO', `Auto-enrich complete: ${scanned} files, ${chains} chains`);
         }).catch(err => {
@@ -6112,8 +6195,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (queries.length > 10) {
           return { content: [{ type: 'text', text: 'Maximum 10 queries per batch.' }], isError: true };
         }
+        logToFile('INFO', `batch: ${queries.length} queries: ${queries.map(q => q.tool).join(', ')}`);
         // Run batch queries in parallel using existing standalone functions
         const batchResults = await Promise.all(queries.map(async (q, idx) => {
+          const batchItemStart = Date.now();
           try {
             const a = q.args || {};
             let text = '';
@@ -6374,7 +6459,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const gArgs = batchFilesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
                 if (a.ignoreCase) gArgs.push('-i');
                 if (!batchFilesOnly && batchCtx > 0) gArgs.push('-C', String(batchCtx));
-                for (const pat of include.split(',').map(p => p.trim())) gArgs.push('--include=' + pat);
+                for (const pat of expandIncludePattern(include)) gArgs.push('--include=' + pat);
                 gArgs.push('--', a.pattern, searchPath);
                 let out;
                 try {
@@ -6416,8 +6501,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               default:
                 text = `Unsupported batch tool: ${q.tool}`;
             }
+            logToFile('INFO', `batch[${idx}]: ${q.tool} completed (${Date.now() - batchItemStart}ms)`);
             return { idx, tool: q.tool, text };
           } catch (err) {
+            logToFile('ERR', `batch[${idx}]: ${q.tool} failed (${Date.now() - batchItemStart}ms): ${err.message}`);
             return { idx, tool: q.tool, text: `Error: ${err.message}` };
           }
         }));
@@ -6440,12 +6527,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const grepArgs = filesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
         if (args.ignoreCase) grepArgs.push('-i');
         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())) {
+        for (const pat of expandIncludePattern(include)) {
           grepArgs.push('--include=' + pat);
         }
         grepArgs.push('--', args.pattern, searchPath);
         let output;
+        const grepStart = Date.now();
         try {
           output = execFileSync('grep', grepArgs, {
             cwd: root, encoding: 'utf-8', timeout: 30000,
@@ -6455,9 +6542,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         } catch (err) {
           // grep returns exit code 1 when no matches found
           output = err.stdout || '';
+          if (err.killed) logToFile('WARN', `grep: timed out after 30s for pattern "${args.pattern}"`);
         }
+        const grepElapsed = Date.now() - grepStart;
         const lines = output.trim().split('\n').filter(Boolean);
         const total = lines.length;
+        if (grepElapsed > 5000) logToFile('WARN', `grep: slow query "${args.pattern}" — ${total} matches in ${grepElapsed}ms`);
         const truncated = lines.slice(0, maxResults);
         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`
@@ -6619,6 +6709,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const filePath = path.join(root, args.path);
         let content;
         try { content = readFileSync(filePath, 'utf-8'); } catch (err) {
+          logToFile('WARN', `read: file not found: ${args.path} (${err.code || err.message})`);
           return { content: [{ type: 'text', text: `File not found: ${args.path}` }], isError: true };
         }
 
@@ -6626,6 +6717,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (args.methodName) {
           const body = readFullMethodBody(filePath, args.methodName);
           if (!body) {
+            logToFile('WARN', `read: method "${args.methodName}" not found in ${args.path}`);
             return { content: [{ type: 'text', text: `## ${args.path}\n\nMethod \`${args.methodName}\` not found in file.` }] };
           }
           // Find line number of the method