magector 2.14.1 → 2.15.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Technology-aware MCP server for Magento 2 and Adobe Commerce with intelligent indexing and search.**
 
-Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 45 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
+Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 46 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
 
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)
 [![Node.js](https://img.shields.io/badge/node-22.5+-green.svg)](https://nodejs.org)
@@ -58,7 +58,7 @@ The result: your AI assistant calls one MCP tool and gets ranked, pattern-enrich
 - **Complexity analysis** -- cyclomatic complexity, function count, and hotspot detection across modules
 - **Fast** -- 10-45ms queries via persistent serve process, batched ONNX embedding with adaptive thread scaling
 - **LLM description enrichment** -- generate natural-language descriptions of di.xml files using Claude, stored in SQLite, and prepend them to embedding text so descriptions influence vector search ranking (not just post-retrieval display)
-- **MCP server** -- 45 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
+- **MCP server** -- 46 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
 - **Clean architecture** -- Rust core handles all indexing/search, Node.js MCP server delegates to it
 
 ---
@@ -70,7 +70,7 @@ flowchart LR
   subgraph node ["Node.js Layer"]
     direction TB
     G["CLI<br/>init · index · search · describe"]
-    E["MCP Server<br/>45 tools · LRU cache"]
+    E["MCP Server<br/>46 tools · LRU cache"]
     F["Persistent Serve Process"]
     G --> F
     E --> F
@@ -371,7 +371,7 @@ npx magector index --force
 
 ## MCP Server Tools
 
-The MCP server exposes 45 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
+The MCP server exposes 46 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
 
 ### Output Format
 
@@ -482,13 +482,14 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 | `magento_find_trigger` | Find database triggers across the codebase |
 | `magento_find_table_usage` | Find all PHP code referencing a specific database table |
 
-### Null-Safety Analysis (v2.12–v2.13)
+### Null-Safety Analysis (v2.12–v2.15)
 
 | Tool | Description |
 |------|-------------|
 | `magento_ast_search` | Structural PHP code search using [semgrep](https://semgrep.dev). Understands PHP AST — matches by structure regardless of variable names, ignores comments/strings. Pattern syntax: `$X` = any expression, `$Y` = any identifier, `...` = any args. Example: `$X->getPayment()->$Y(...)`. Requires `semgrep`. **(v2.12)** |
 | `magento_enrich` | Build the method-chain enrichment index. Scans all `vendor/` PHP files for `->firstMethod()->secondMethod()` chains and detects null guards in surrounding code. Stores results in `.magector/enrichment.db` (SQLite, `node:sqlite`). Runs automatically after `magento_index`. **(v2.13)** |
 | `magento_find_null_risks` | Query the enrichment index for method chains without null guards. O(1) SQLite query instead of file scanning. Pass `firstMethod` to filter (e.g., `"getPayment"` → all `->getPayment()->anything()` without null guard). Requires `magento_enrich`. **(v2.13)** |
+| `magento_find_dataobject_issues` | Detect `setX(null)` anti-pattern on Magento `DataObject` subclasses. `setX(null)` stores `['x' => null]` in `_data` — `hasX()` (via `array_key_exists`) returns `true` even when the value is `null`, creating false-positive guard conditions. Use during field-lifecycle audits or when debugging "value persists but shouldn't" bugs. Requires `semgrep`. **(v2.15)** |
 
 ### Search Enhancements (v2.1)
 
@@ -672,7 +673,7 @@ cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index
 magector/
 ├── src/                          # Node.js source
 │   ├── cli.js                    # CLI entry point (npx magector <command>)
-│   ├── mcp-server.js             # MCP server (45 tools, structured JSON output)
+│   ├── mcp-server.js             # MCP server (46 tools, structured JSON output)
 │   ├── binary.js                 # Platform binary resolver
 │   ├── model.js                  # ONNX model resolver/downloader
 │   ├── init.js                   # Full init command (index + IDE config)

package/package.json

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

package/src/mcp-server.js

@@ -3670,16 +3670,16 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   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');
+  // Semgrep resolves .semgrepignore from the git repo root, NOT the scan directory.
+  // An empty .semgrepignore at root overrides the defaults: https://semgrep.dev/docs/ignoring-files-folders-code/
+  const semgrepIgnorePath = path.join(root, '.semgrepignore');
   let createdSemgrepIgnore = false;
   if (!existsSync(semgrepIgnorePath)) {
     try {
       writeFileSync(semgrepIgnorePath, '# Magector: scan vendor/ and all project files\n');
       createdSemgrepIgnore = true;
-      logToFile('INFO', `ast_search: created temporary .semgrepignore at ${targetPath}`);
+      logToFile('INFO', `ast_search: created temporary .semgrepignore at ${root}`);
     } catch (err) {
       logToFile('WARN', `ast_search: failed to create .semgrepignore: ${err.message}`);
     }
@@ -3728,12 +3728,34 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   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,
-    endLine: r.end.line,
-    snippet: (r.extra?.lines || '').trim()
-  }));
+  return findings.map(r => {
+    // semgrep >=1.100 may return "requires login" in r.extra.lines for unlicensed installs.
+    // Fall back to r.extra.message which contains the matched expression (always available).
+    const rawLines = r.extra?.lines || '';
+    const snippet = (rawLines && rawLines !== 'requires login')
+      ? rawLines.trim()
+      : (r.extra?.message || '').trim();
+    return {
+      file: r.path.replace(root + '/', ''),
+      line: r.start.line,
+      endLine: r.end.line,
+      snippet
+    };
+  });
+}
+
+// ─── DataObject set-null Anti-pattern Detection ─────────────────
+
+async function findDataObjectIssues(searchPath, maxResults) {
+  // Detects DataObject::setX(null) anti-pattern:
+  //   setX(null) stores ['x' => null] in _data — key EXISTS with null value.
+  //   hasX() / hasData('x') calls array_key_exists() → returns true even for null.
+  //   This causes false-positive guard conditions: hasX() passes, getX() returns null.
+  //   Correct way to fully clear: unsetData('x') removes the key entirely.
+  const allResults = await astSearch('$X->$SETTER(null)', searchPath, 'php', 500);
+  const setterNullRegex = /->set[A-Z]\w+\s*\(\s*null\s*\)/;
+  const limit = Math.min(maxResults || 100, 500);
+  return allResults.filter(r => setterNullRegex.test(r.snippet)).slice(0, limit);
 }
 
 // ─── MCP Server ─────────────────────────────────────────────────
@@ -4494,6 +4516,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['pattern']
       }
     },
+    {
+      name: 'magento_find_dataobject_issues',
+      description: 'Detect DataObject::setX(null) anti-pattern calls. In Magento, classes extending DataObject store values in a _data array. Calling setX(null) stores the key with a null value — so hasX()/hasData(\'x\') (which use array_key_exists) return true even though the value is null. Downstream guard conditions silently pass, but getX() returns null. The correct way to clear is unsetData(\'x\'). Use this during field-lifecycle audits or when debugging "value persists but shouldn\'t" bugs. ⚡ For multi-query workflows use magento_batch.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Subdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"'
+          },
+          maxResults: {
+            type: 'number',
+            description: 'Maximum matches to return (default: 100, max: 500)',
+            default: 100
+          }
+        }
+      }
+    },
     {
       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.',
@@ -4583,7 +4623,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_ast_search', 'magento_find_null_risks'];
+    'magento_batch', 'magento_find_config', 'magento_find_callers', 'magento_grep', 'magento_read', 'magento_trace_api', 'magento_ast_search', 'magento_find_null_risks', 'magento_find_dataobject_issues'];
   if (warmupInProgress && !indexFreeTools.includes(name)) {
     logToFile('REQ', `${name} → blocked (warmup: loading index)`);
     return {
@@ -6485,6 +6525,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 break;
               }
+              case 'magento_find_dataobject_issues': {
+                const doResults = await findDataObjectIssues(a.path, a.maxResults);
+                if (doResults.length === 0) {
+                  text = 'No DataObject setX(null) anti-pattern calls found.';
+                } else {
+                  text = `Found ${doResults.length} setX(null) call(s) — review for DataObject anti-pattern:\n\n`;
+                  for (const r of doResults) 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);
@@ -6762,6 +6812,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text }] };
       }
 
+      case 'magento_find_dataobject_issues': {
+        const doResults = await findDataObjectIssues(args.path, args.maxResults);
+        if (doResults.length === 0) {
+          return { content: [{ type: 'text', text: '## magento_find_dataobject_issues\n\nNo `setX(null)` calls found.' }] };
+        }
+        let doText = `## magento_find_dataobject_issues\n`;
+        doText += `Found **${doResults.length}** \`setX(null)\` call(s)\n\n`;
+        doText += `> ⚠️ **DataObject anti-pattern**: \`setX(null)\` stores \`['x' => null]\` in \`_data\` — \`hasX()\` returns \`true\` via \`array_key_exists\` even for \`null\`. `;
+        doText += `Downstream \`hasX()\` guards silently pass while \`getX()\` returns \`null\`. `;
+        doText += `**Fix**: use \`unsetData('x')\` to remove the key entirely.\n\n`;
+        for (const r of doResults) {
+          const lineInfo = r.endLine && r.endLine !== r.line ? `${r.line}-${r.endLine}` : String(r.line);
+          doText += `**${r.file}:${lineInfo}**\n\`\`\`php\n${r.snippet}\n\`\`\`\n\n`;
+        }
+        return { content: [{ type: 'text', text: doText }] };
+      }
+
       case 'magento_enrich': {
         const root = config.magentoRoot;
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };