magector 1.7.1 → 2.1.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 21 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 28 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-18+-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** -- 21 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
+- **MCP server** -- 28 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/>21 tools · LRU cache"]
+    E["MCP Server<br/>28 tools · LRU cache"]
     F["Persistent Serve Process"]
     G --> F
     E --> F
@@ -347,11 +347,29 @@ For very large or CPU-constrained runs, you may also need to extend the wall-clo
 MAGECTOR_INDEX_TIMEOUT=28800000 npx magector index --threads 2   # 8 h timeout, 2 threads
 ```
 
+### Resume after timeout or interrupt
+
+Indexing writes a crash-safe checkpoint to disk every 50 batches (~12,800 files). If the process is killed or times out mid-run, **just re-run `npx magector index`** — it auto-resumes from the last checkpoint:
+
+```bash
+npx magector index
+# ♻️  Resuming from previous run: 38400 vectors across 12200 files already indexed
+# ✓ Found 79771 total files; 12200 already indexed, 67571 remaining to process
+```
+
+The indexer collects already-embedded file paths from the existing DB, filters them out of file discovery, preserves the existing HNSW state, and only parses/embeds the files that aren't in the DB yet. Partial resume also picks up new files added to the tree since the previous run.
+
+To force a full rebuild (e.g. after a schema change or if you want to discard stale vectors), pass `--force`:
+
+```bash
+npx magector index --force
+```
+
 ---
 
 ## MCP Server Tools
 
-The MCP server exposes 21 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 28 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
 
@@ -407,14 +425,31 @@ All search tools return structured JSON:
 | `magento_find_cron` | Find cron job definitions in crontab.xml |
 | `magento_find_db_schema` | Find database table definitions in db_schema.xml (declarative schema) |
 
-### Flow Tracing
+### Flow & Dependency Tracing
 
 | Tool | Description |
 |------|-------------|
 | `magento_trace_flow` | Trace execution flow from an entry point (route, API, GraphQL, event, cron) -- maps controller → plugins → observers → templates in one call |
+| `magento_trace_dependency` | Trace DI graph for a class/interface -- preferences, plugins, virtualTypes, argument overrides (parses all di.xml, no index needed) |
+| `magento_find_event_flow` | Trace complete event chain: dispatchers → observers → handler PHP classes (parses events.xml + vector search) |
+| `magento_find_layout` | Find layout XML files by handle or content -- lists blocks, containers, and referenceBlock declarations |
 
 Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event, `camelCase` → GraphQL, `path/segments` → route), or override with `entryType`. Use `depth: "shallow"` (entry + config + plugins) or `depth: "deep"` (adds observers, layout, templates, DI preferences).
 
+### Impact & Testing
+
+| Tool | Description |
+|------|-------------|
+| `magento_impact_analysis` | Analyze impact of changing a class -- finds use statements, DI references, direct instantiations, and type hints across the codebase |
+| `magento_find_test` | Find PHPUnit tests for a given class/method -- searches Test/ directories for coverage, mocks, and assertions |
+
+### Diagnostics
+
+| Tool | Description |
+|------|-------------|
+| `magento_error_parser` | Parse Magento error messages and map to root cause, affected files, and fix suggestions (10 known patterns) |
+| `magento_performance_profile` | Profile a Magento subsystem (checkout_totals, order_place, product_save, etc.) for performance bottlenecks -- plugins, observers, and complexity hotspots |
+
 ### Analysis Tools
 
 | Tool | Description |
@@ -431,6 +466,13 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 | `magento_describe` | Generate LLM descriptions for di.xml files (requires `ANTHROPIC_API_KEY`), stored in SQLite, auto-reindexes affected files |
 | `magento_stats` | View index statistics |
 
+### Search Enhancements (v2.1)
+
+- **Hybrid BM25+vector search** -- combines text frequency scoring with semantic vector similarity for better exact class name matches
+- **Query expansion** -- automatically expands queries with Magento domain synonyms (plugin → interceptor, checkout → cart/quote/totals, etc.)
+- **Module filtering** -- `moduleFilter` parameter on `magento_search` to limit results by vendor/module pattern (supports wildcards, e.g., `"Vendor_*"`)
+- **Non-blocking reindex** -- old index stays usable during background rebuild; new index is built to a temp path and swapped in atomically on completion
+
 ### Tool Cross-References
 
 Each tool description includes "See also" hints to help AI clients chain tools effectively:
@@ -458,6 +500,14 @@ graph LR
   trc -.-> tpl
   trc -.-> api
   trc -.-> gql
+  dep["trace_dependency"] --> prf
+  dep --> plg
+  evf["find_event_flow"] --> obs
+  imp["impact_analysis"] --> dep
+  imp --> cls
+  tst["find_test"] --> cls
+  err["error_parser"] --> dep
+  lay["find_layout"] --> blk
 
   style cls fill:#4a90d9,color:#fff
   style mtd fill:#4a90d9,color:#fff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "1.7.1",
+  "version": "2.1.0",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -20,7 +20,9 @@
     "validate:verbose": "node src/cli.js validate --verbose",
     "validate:keep": "node src/cli.js validate --verbose --keep",
     "benchmark": "node src/cli.js benchmark",
-    "test": "node tests/mcp-server.test.js",
+    "test": "node tests/unit.test.js && node tests/mcp-server.test.js",
+    "test:unit": "node tests/unit.test.js",
+    "test:integration": "node tests/mcp-server.test.js",
     "test:no-index": "node tests/mcp-server.test.js --no-index",
     "test:accuracy": "node tests/mcp-accuracy.test.js",
     "test:accuracy:verbose": "node tests/mcp-accuracy.test.js --verbose",
@@ -32,15 +34,15 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chalk": "^5.3.0",
-    "glob": "^10.3.10",
+    "glob": "^13.0.0",
     "ora": "^8.0.1",
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "1.7.1",
-    "@magector/cli-linux-x64": "1.7.1",
-    "@magector/cli-linux-arm64": "1.7.1",
-    "@magector/cli-win32-x64": "1.7.1"
+    "@magector/cli-darwin-arm64": "2.1.0",
+    "@magector/cli-linux-x64": "2.1.0",
+    "@magector/cli-linux-arm64": "2.1.0",
+    "@magector/cli-win32-x64": "2.1.0"
   },
   "keywords": [
     "magento",

package/src/cli.js

@@ -40,7 +40,9 @@ Index options:
                        system responsive during indexing.
   --batch-size <n>     Embedding batch size (default: 256). Higher = faster
                        but more RAM.
-  --force              Force re-index even if index exists
+  --force              Discard any existing index and rebuild from scratch.
+                       Without --force, indexing auto-resumes from the last
+                       incremental save (written every ~50 batches).
 
 Environment Variables:
   MAGENTO_ROOT             Path to Magento installation (default: cwd)
@@ -122,6 +124,12 @@ async function runIndex(targetPath, opts = {}) {
     if (opts.batchSize != null) {
       indexArgs.push('--batch-size', String(opts.batchSize));
     }
+    // --force discards any existing partial index and rebuilds from scratch.
+    // Without it, the Rust indexer auto-resumes from the last incremental
+    // save on disk and only re-embeds files that aren't in the DB yet.
+    if (opts.force) {
+      indexArgs.push('--force');
+    }
     // Pass descriptions DB if it exists
     const descDbPath = path.resolve(root, '.magector', 'sqlite.db');
     if (existsSync(descDbPath)) {
@@ -137,10 +145,12 @@ async function runIndex(targetPath, opts = {}) {
     if (err.message && err.message.includes('ETIMEDOUT')) {
       console.error(
         `Indexing timed out after ${indexTimeout / 1000}s.\n` +
-        `For large codebases or CPU-constrained environments, increase the timeout:\n` +
+        `Partial progress was saved to disk every ~50 batches — re-run\n` +
+        `'npx magector index' to auto-resume from the last checkpoint.\n` +
+        `\n` +
+        `For large codebases or CPU-constrained environments, also consider:\n` +
         `  MAGECTOR_INDEX_TIMEOUT=28800000 npx magector index    # 8 hours\n` +
-        `Or reduce CPU usage with fewer threads:\n` +
-        `  npx magector index --threads 2`
+        `  npx magector index --threads 2                        # lower CPU usage`
       );
     } else {
       console.error(`Indexing error: ${err.message}`);
@@ -247,20 +257,44 @@ async function main() {
 
     case 'index': {
       // First non-flag arg after `index` is the path; everything else is options.
+      // Must skip values belonging to flags (e.g., "4" in "--threads 4").
       const indexArgv = args.slice(1);
-      const targetPath = indexArgv.find(a => !a.startsWith('-'));
       const indexOpts = parseArgs(indexArgv);
+      let targetPath = undefined;
+      for (let i = 0; i < indexArgv.length; i++) {
+        if (indexArgv[i] === '--threads' || indexArgv[i] === '--batch-size') {
+          i++; // skip the flag's value
+        } else if (indexArgv[i].startsWith('-')) {
+          // skip boolean flags like --force, --verbose
+        } else {
+          targetPath = indexArgv[i];
+          break; // first non-flag, non-value arg is the path
+        }
+      }
       await runIndex(targetPath, indexOpts);
       break;
     }
 
     case 'search': {
-      const query = args.slice(1).filter(a => !a.startsWith('-')).join(' ');
+      // Build query from non-flag arguments, skipping values that belong to flags
+      const searchArgv = args.slice(1);
+      const queryParts = [];
+      for (let i = 0; i < searchArgv.length; i++) {
+        if (searchArgv[i] === '-l' || searchArgv[i] === '--limit' ||
+            searchArgv[i] === '-f' || searchArgv[i] === '--format') {
+          i++; // skip the flag's value
+        } else if (searchArgv[i].startsWith('-')) {
+          // skip boolean flags like -v, --verbose
+        } else {
+          queryParts.push(searchArgv[i]);
+        }
+      }
+      const query = queryParts.join(' ');
       if (!query) {
         console.error('Usage: npx magector search <query>');
         process.exit(1);
       }
-      const opts = parseArgs(args.slice(1));
+      const opts = parseArgs(searchArgv);
       runSearch(query, opts);
       break;
     }

package/src/init.js

@@ -265,6 +265,9 @@ export async function init(projectPath, opts = {}) {
     if (opts.batchSize != null) {
       indexArgs.push('--batch-size', String(opts.batchSize));
     }
+    if (opts.force) {
+      indexArgs.push('--force');
+    }
     execFileSync(binary, indexArgs, { timeout: initTimeout, stdio: 'inherit' });
   } catch (err) {
     if (err.status) {