magector 1.2.14 → 1.2.15

package/README.md

@@ -1,20 +1,21 @@
 # Magector
 
-**Semantic code search engine for Magento 2, powered by ONNX embeddings and HNSW vector search.**
+**Semantic code search engine for Magento 2 and Adobe Commerce, powered by ONNX embeddings and HNSW vector search.**
 
-Magector indexes an entire Magento 2 codebase and lets you search it with natural language. Instead of grepping for keywords, ask questions like *"how are checkout totals calculated?"* or *"where is the product price determined?"* and get ranked, relevant results in under 50ms.
+Magector indexes an entire Magento 2 or Adobe Commerce codebase and lets you search it with natural language. Instead of grepping for keywords, ask questions like *"how are checkout totals calculated?"* or *"where is the product price determined?"* and get ranked, relevant results in under 50ms.
 
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)
 [![Node.js](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org)
 [![Magento](https://img.shields.io/badge/magento-2.4.x-blue.svg)](https://magento.com)
-[![Accuracy](https://img.shields.io/badge/accuracy-94.9%25-brightgreen.svg)](#validation)
+[![Adobe Commerce](https://img.shields.io/badge/adobe%20commerce-supported-blue.svg)](https://business.adobe.com/products/magento/magento-commerce.html)
+[![Accuracy](https://img.shields.io/badge/accuracy-99.2%25-brightgreen.svg)](#validation)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
 ---
 
 ## Why Magector
 
-Magento 2 has **18,000+ source files** across hundreds of modules. Finding the right code is slow:
+Magento 2 and Adobe Commerce have **18,000+ source files** across hundreds of modules. Finding the right code is slow:
 
 | Approach | Finds semantic matches | Understands Magento patterns | Speed (18K files) |
 |----------|:---------------------:|:---------------------------:|:-----------------:|
@@ -29,7 +30,7 @@ Magector understands that a query about *"payment capture"* should return `Sales
 
 ## Magector vs Built-in AI Search
 
-Claude Code and Cursor both have built-in code search -- but they rely on keyword matching (`grep`/`ripgrep`) and file-tree heuristics. On a Magento 2 codebase with 18,000+ files, that approach breaks down fast.
+Claude Code and Cursor both have built-in code search -- but they rely on keyword matching (`grep`/`ripgrep`) and file-tree heuristics. On a Magento 2 / Adobe Commerce codebase with 18,000+ files, that approach breaks down fast.
 
 | Capability | Claude Code / Cursor (built-in) | Magector |
 |---|---|---|
@@ -52,13 +53,14 @@ Without Magector, asking Claude Code or Cursor *"how are checkout totals calcula
 ## Features
 
 - **Semantic search** -- find code by meaning, not exact keywords
-- **94.9% accuracy** -- validated with 101 E2E test queries across 16 tool categories, plus 557 Rust-level test cases
+- **99.2% accuracy** -- validated with 101 E2E test queries across 16 tool categories, plus 557 Rust-level test cases
 - **Hybrid search** -- combines semantic vector similarity with keyword re-ranking for best-of-both-worlds results
 - **Structured JSON output** -- results include file path, class name, methods list, role badges, and content snippets for minimal round-trips
 - **Persistent serve mode** -- keeps ONNX model and HNSW index resident in memory, eliminating cold-start latency
 - **ONNX embeddings** -- native 384-dim transformer embeddings via ONNX Runtime
-- **36K+ vectors** -- indexes the complete Magento 2 codebase including framework internals
+- **36K+ vectors** -- indexes the complete Magento 2 / Adobe Commerce codebase including framework internals
 - **Magento-aware** -- understands controllers, plugins, observers, blocks, resolvers, repositories, and 20+ Magento patterns
+- **Adobe Commerce compatible** -- works with both Magento Open Source and Adobe Commerce (B2B, Staging, and all Commerce-specific modules)
 - **AST-powered** -- tree-sitter parsing for PHP and JavaScript extracts classes, methods, namespaces, and inheritance
 - **Cross-tool discovery** -- tool descriptions include keywords and "See also" references so AI clients find the right tool on the first try
 - **Diff analysis** -- risk scoring and change classification for git commits and staged changes
@@ -137,10 +139,10 @@ flowchart TD
 
 - [Node.js 18+](https://nodejs.org)
 
-### 1. Initialize in Your Magento Project
+### 1. Initialize in Your Project
 
 ```bash
-cd /path/to/your/magento2
+cd /path/to/your/magento2  # or Adobe Commerce project
 npx magector init
 ```
 
@@ -267,7 +269,7 @@ npx magector help               # Show help
 
 ## MCP Server Tools
 
-The MCP server exposes 19 tools for AI-assisted Magento 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 19 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
 
@@ -436,11 +438,11 @@ pie title Test Pass Rate (101 queries)
 
 | Metric | Value |
 |--------|-------|
-| **Grade** | **A (94.9/100)** |
+| **Grade** | **A+ (99.2/100)** |
 | **Pass rate** | 101/101 (100%) |
-| **Precision** | 93.2% |
-| **MRR** | 99.2% |
-| **NDCG@10** | 85.5% |
+| **Precision** | 98.7% |
+| **MRR** | 99.3% |
+| **NDCG@10** | 98.7% |
 | **Index size** | 35,795 vectors |
 | **Query time** | 10-45ms |
 
@@ -449,19 +451,20 @@ pie title Test Pass Rate (101 queries)
 | Tool | Pass | Precision | MRR | NDCG |
 |------|------|-----------|-----|------|
 | find_class | 100% | 100% | 100% | 100% |
-| find_method | 100% | 89% | 100% | 87% |
-| find_controller | 100% | 100% | 100% | -- |
+| find_method | 100% | 98% | 92% | 97% |
+| find_controller | 100% | 100% | 100% | 100% |
 | find_observer | 100% | 100% | 100% | 100% |
-| find_plugin | 100% | 96% | 100% | 100% |
+| find_plugin | 100% | 100% | 100% | 100% |
 | find_preference | 100% | 100% | 100% | 100% |
 | find_api | 100% | 100% | 100% | 100% |
 | find_cron | 100% | 100% | 100% | 100% |
 | find_db_schema | 100% | 100% | 100% | 100% |
 | find_graphql | 100% | 100% | 100% | 100% |
 | find_block | 100% | 100% | 100% | 100% |
-| find_config | 100% | 89% | 89% | 93% |
-| find_template | 100% | 84% | 100% | 100% |
-| search | 100% | 99% | 100% | 100% |
+| find_config | 100% | 100% | 100% | 100% |
+| find_template | 100% | 100% | 100% | 100% |
+| search | 100% | 100% | 100% | 100% |
+| module_structure | 100% | 100% | 100% | 100% |
 
 ### Integration Tests
 
@@ -546,7 +549,7 @@ magector/
 
 ### 1. Indexing
 
-Magector scans every `.php`, `.js`, `.xml`, `.phtml`, and `.graphqls` file in a Magento codebase:
+Magector scans every `.php`, `.js`, `.xml`, `.phtml`, and `.graphqls` file in a Magento 2 or Adobe Commerce codebase:
 
 1. **AST parsing** -- Tree-sitter extracts class names, namespaces, methods, inheritance, and interface implementations from PHP and JavaScript files
 2. **Pattern detection** -- Identifies Magento-specific patterns: controllers, models, repositories, plugins, observers, blocks, GraphQL resolvers, admin grids, cron jobs, and more
@@ -851,6 +854,7 @@ gantt
     JSON output         :done, 2025-03, 15d
     Cross-tool hints    :done, 2025-03, 15d
     E2E tests           :done, 2025-03, 15d
+    Adobe Commerce      :done, 2025-03, 15d
   section Next
     Method chunking     :active, 2025-04, 30d
     Intent detection    :2025-05, 30d
@@ -859,7 +863,6 @@ gantt
   section Future
     VSCode extension    :2025-08, 60d
     Web UI              :2025-10, 60d
-    Commerce support    :2026-01, 60d
 ```
 
 - [x] Hybrid search (semantic + keyword re-ranking)
@@ -867,13 +870,13 @@ gantt
 - [x] Structured JSON output (methods, badges, snippets)
 - [x] Cross-tool discovery hints for AI clients
 - [x] E2E accuracy test suite (101 queries)
+- [x] Adobe Commerce support (B2B, Staging, and all Commerce-specific modules)
 - [ ] Method-level chunking (per-method vectors for direct method search)
 - [ ] Query intent classification (auto-detect "give me XML" vs "give me PHP")
 - [ ] Filtered search by file type at the vector level
 - [ ] Incremental indexing (only re-index changed files)
 - [ ] VSCode extension
 - [ ] Web UI for browsing results
-- [ ] Support for Magento 2 Commerce (B2B, Staging modules)
 
 ---
 
@@ -895,4 +898,4 @@ Contributions are welcome. Please:
 
 ---
 
-Built with Rust and Node.js for the Magento community.
+Built with Rust and Node.js for the Magento and Adobe Commerce community.

package/package.json

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

package/src/mcp-server.js

@@ -697,19 +697,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'magento_find_method': {
         const query = `method ${args.methodName} function ${args.className || ''}`.trim();
-        const raw = await rustSearchAsync(query, 30);
+        const raw = await rustSearchAsync(query, 50);
         const methodLower = args.methodName.toLowerCase();
+        // Hard-filter: only results that actually define/contain this method
         let results = raw.map(normalizeResult).filter(r =>
           r.methodName?.toLowerCase() === methodLower ||
-          r.methodName?.toLowerCase().includes(methodLower) ||
-          r.methods?.some(m => m.toLowerCase() === methodLower || m.toLowerCase().includes(methodLower)) ||
-          r.path?.toLowerCase().includes(methodLower)
+          r.methods?.some(m => m.toLowerCase() === methodLower || m.toLowerCase().includes(methodLower))
         );
+        // If not enough results from methods[], fall back to path-based matching
+        if (results.length < 3) {
+          const pathFallback = raw.map(normalizeResult).filter(r =>
+            r.path?.toLowerCase().includes(methodLower) &&
+            !results.some(existing => existing.path === r.path)
+          );
+          results = results.concat(pathFallback);
+        }
         // Boost exact method matches to top
         results = results.map(r => {
-          const exact = r.methodName?.toLowerCase() === methodLower ||
-            r.methods?.some(m => m.toLowerCase() === methodLower);
-          return { ...r, score: (r.score || 0) + (exact ? 0.5 : 0) };
+          let bonus = 0;
+          if (r.methods?.some(m => m.toLowerCase() === methodLower)) bonus += 0.5;
+          if (r.methodName?.toLowerCase() === methodLower) bonus += 0.3;
+          return { ...r, score: (r.score || 0) + bonus };
         }).sort((a, b) => b.score - a.score);
         return {
           content: [{
@@ -722,18 +730,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'magento_find_config': {
         let query = args.query;
         if (args.configType && args.configType !== 'other') {
-          query = `${args.configType}.xml ${args.query}`;
+          query = `${args.configType}.xml xml config ${args.query}`;
         }
-        const raw = await rustSearchAsync(query, 30);
-        const pathBoost = args.configType ? [`${args.configType}.xml`] : ['.xml'];
+        const raw = await rustSearchAsync(query, 100);
         let normalized = raw.map(normalizeResult);
-        // Prefer XML results when configType is specified, but don't hard-exclude
-        if (args.configType) {
-          const xmlOnly = normalized.filter(r =>
-            r.type === 'xml' || r.path?.endsWith('.xml') || r.path?.includes('.xml')
+        // Hard-filter to XML results
+        const xmlOnly = normalized.filter(r =>
+          r.type === 'xml' || r.path?.endsWith('.xml') || r.path?.includes('.xml')
+        );
+        if (xmlOnly.length > 0) normalized = xmlOnly;
+        // Hard-filter to specific config type when specified
+        if (args.configType && args.configType !== 'other') {
+          const configTypeFile = `${args.configType}.xml`;
+          const typeSpecific = normalized.filter(r =>
+            r.path?.includes(configTypeFile)
           );
-          if (xmlOnly.length > 0) normalized = xmlOnly;
+          if (typeSpecific.length >= 3) normalized = typeSpecific;
         }
+        const pathBoost = args.configType ? [`${args.configType}.xml`] : ['.xml'];
         const results = rerank(normalized, { fileType: 'xml', pathContains: pathBoost });
         return {
           content: [{
@@ -747,8 +761,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         let query = args.query;
         if (args.area) query = `${args.area} ${query}`;
         query += ' template phtml';
-        const raw = await rustSearchAsync(query, 15);
-        const results = rerank(raw.map(normalizeResult), { pathContains: ['.phtml'] });
+        const raw = await rustSearchAsync(query, 50);
+        // Hard-filter to .phtml template files only
+        let results = raw.map(normalizeResult).filter(r =>
+          r.path?.includes('.phtml') || r.type === 'template'
+        );
+        results = rerank(results, { pathContains: ['.phtml'] });
         return {
           content: [{
             type: 'text',
@@ -850,10 +868,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const namespaceParts = parts.map(p => p.charAt(0).toUpperCase() + p.slice(1));
         const query = `${namespaceParts.join(' ')} controller execute action`;
 
-        const raw = await rustSearchAsync(query, 30);
+        const raw = await rustSearchAsync(query, 50);
+        // Prefer path-based controller detection, fall back to isController flag
         let results = raw.map(normalizeResult).filter(r =>
-          r.isController || r.path?.includes('/Controller/')
+          r.path?.includes('/Controller/')
         );
+        if (results.length < 5) {
+          // Add isController-flagged results not already included
+          const extra = raw.map(normalizeResult).filter(r =>
+            r.isController && !results.some(e => e.path === r.path)
+          );
+          results = results.concat(extra);
+        }
 
         // Boost results whose path matches the route segments
         if (parts.length >= 2) {
@@ -947,11 +973,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'magento_module_structure': {
-        const raw = await rustSearchAsync(args.moduleName, 100);
-        const moduleName = args.moduleName.replace('_', '/');
-        const results = raw.map(normalizeResult).filter(r =>
-          r.path?.includes(moduleName) || r.module?.includes(args.moduleName)
-        );
+        const raw = await rustSearchAsync(args.moduleName, 200);
+        // Support both app/code (Magento/Catalog/) and vendor (module-catalog/) paths
+        const modulePath = args.moduleName.replace('_', '/') + '/';
+        const parts = args.moduleName.split('_');
+        const vendorPath = parts.length === 2
+          ? `module-${parts[1].toLowerCase()}/`
+          : '';
+        const results = raw.map(normalizeResult).filter(r => {
+          const path = r.path || '';
+          const mod = r.module || '';
+          // Exact module match or directory-level path match (trailing slash prevents Catalog matching CatalogRule)
+          return mod === args.moduleName ||
+            path.includes(modulePath) ||
+            (vendorPath && path.toLowerCase().includes(vendorPath));
+        });
 
         const structure = {
           controllers: results.filter(r => r.isController || r.path?.includes('/Controller/')),
@@ -970,24 +1006,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           )
         };
 
-        let text = `## Module Structure: ${args.moduleName}\n\n`;
-
+        // Build structured JSON output for module structure
+        const structureOutput = {
+          module: args.moduleName,
+          totalFiles: results.length,
+          categories: {}
+        };
         for (const [category, items] of Object.entries(structure)) {
           if (items.length > 0) {
-            text += `### ${category.charAt(0).toUpperCase() + category.slice(1)} (${items.length})\n`;
-            items.slice(0, 10).forEach(item => {
-              text += `- ${item.className || item.path} (${item.path})\n`;
-            });
-            if (items.length > 10) text += `  ... and ${items.length - 10} more\n`;
-            text += '\n';
+            structureOutput.categories[category] = {
+              count: items.length,
+              files: items.slice(0, 10).map(item => ({
+                path: item.path,
+                className: item.className || null,
+                methods: item.methods?.length > 0 ? item.methods : undefined
+              }))
+            };
           }
         }
 
-        if (results.length === 0) {
-          text += 'No code found for this module. Try re-indexing or check the module name.';
-        }
+        // Return both JSON and formatted summary
+        const jsonOutput = JSON.stringify({
+          results: results.slice(0, 50).map((r, i) => ({
+            rank: i + 1,
+            path: r.path,
+            className: r.className || undefined,
+            magentoType: r.magentoType || undefined,
+            module: r.module || undefined
+          })),
+          count: results.length,
+          structure: structureOutput.categories
+        });
 
-        return { content: [{ type: 'text', text }] };
+        return { content: [{ type: 'text', text: jsonOutput }] };
       }
 
       case 'magento_analyze_diff': {