magector 1.0.0

package/src/model.js

@@ -0,0 +1,127 @@
+/**
+ * Resolve and download ONNX model files for magector-core.
+ *
+ * Resolution order:
+ * 1. MAGECTOR_MODELS env var
+ * 2. ~/.magector/models/ (global cache)
+ * 3. rust-core/models/ (dev fallback)
+ *
+ * Downloads from HuggingFace if not found.
+ */
+import { existsSync, mkdirSync, createWriteStream } from 'fs';
+import { get as httpsGet } from 'https';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const MODEL_FILES = [
+  {
+    name: 'all-MiniLM-L6-v2.onnx',
+    url: 'https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx',
+    description: 'ONNX embedding model (~86MB)'
+  },
+  {
+    name: 'tokenizer.json',
+    url: 'https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json',
+    description: 'Tokenizer vocabulary (~700KB)'
+  }
+];
+
+function getGlobalCacheDir() {
+  return path.join(os.homedir(), '.magector', 'models');
+}
+
+/**
+ * Find the model directory. Does NOT download — returns null if not found.
+ */
+export function resolveModels() {
+  // 1. Explicit env var
+  if (process.env.MAGECTOR_MODELS) {
+    if (hasModels(process.env.MAGECTOR_MODELS)) {
+      return process.env.MAGECTOR_MODELS;
+    }
+  }
+
+  // 2. Global cache
+  const globalDir = getGlobalCacheDir();
+  if (hasModels(globalDir)) {
+    return globalDir;
+  }
+
+  // 3. Dev fallback
+  const devDir = path.join(__dirname, '..', 'rust-core', 'models');
+  if (hasModels(devDir)) {
+    return devDir;
+  }
+
+  return null;
+}
+
+function hasModels(dir) {
+  return MODEL_FILES.every(f => existsSync(path.join(dir, f.name)));
+}
+
+/**
+ * Ensure models exist, downloading if needed. Returns the model directory path.
+ */
+export async function ensureModels({ silent = false } = {}) {
+  const existing = resolveModels();
+  if (existing) return existing;
+
+  const targetDir = getGlobalCacheDir();
+  mkdirSync(targetDir, { recursive: true });
+
+  if (!silent) {
+    console.log(`Downloading ONNX model to ${targetDir} ...`);
+  }
+
+  for (const file of MODEL_FILES) {
+    const dest = path.join(targetDir, file.name);
+    if (existsSync(dest)) continue;
+
+    if (!silent) {
+      process.stdout.write(`  ${file.description} ... `);
+    }
+    await downloadFile(file.url, dest);
+    if (!silent) {
+      console.log('done');
+    }
+  }
+
+  if (!hasModels(targetDir)) {
+    throw new Error('Model download failed — files missing after download');
+  }
+
+  return targetDir;
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+
+    function follow(url) {
+      httpsGet(url, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          follow(res.headers.location);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          file.close();
+          reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+          return;
+        }
+        res.pipe(file);
+        file.on('finish', () => {
+          file.close(resolve);
+        });
+      }).on('error', (err) => {
+        file.close();
+        reject(err);
+      });
+    }
+
+    follow(url);
+  });
+}

package/src/templates/claude-md.js

@@ -0,0 +1,47 @@
+/**
+ * CLAUDE.md section content for Magento projects using Magector.
+ */
+export const CLAUDE_MD = `# Magector — Magento Semantic Search
+
+This project is indexed with Magector. Use the MCP tools below to search the codebase semantically instead of reading files manually.
+
+## MCP Tools Available
+
+### Search
+- \`magento_search\` — Natural language search ("checkout totals calculation", "product price with tier pricing")
+- \`magento_find_class\` — Find PHP class/interface/trait by name
+- \`magento_find_method\` — Find method implementations across the codebase
+
+### Magento-Specific
+- \`magento_find_config\` — Find XML config files (di.xml, events.xml, system.xml)
+- \`magento_find_template\` — Find PHTML templates
+- \`magento_find_plugin\` — Find interceptor plugins (before/after/around)
+- \`magento_find_observer\` — Find event observers
+- \`magento_find_preference\` — Find DI preference overrides
+- \`magento_find_api\` — Find REST/SOAP API endpoints
+- \`magento_find_controller\` — Find controllers by route
+- \`magento_find_block\` — Find Block classes
+- \`magento_find_cron\` — Find cron job definitions
+- \`magento_find_graphql\` — Find GraphQL resolvers and schema
+- \`magento_find_db_schema\` — Find database table definitions
+- \`magento_module_structure\` — Get full module structure
+
+### Analysis & Utility
+- \`magento_index\` — Re-index the codebase after changes
+- \`magento_stats\` — View index statistics
+- \`magento_analyze_diff\` — Analyze git diffs for risk scoring
+- \`magento_complexity\` — Analyze code complexity
+
+## Query Tips
+
+- Describe what code DOES: "calculate product price" not "price file"
+- Include Magento terms: "plugin for save", "observer for order place"
+- Be specific: "customer address validation before checkout" not just "validation"
+
+## Re-indexing
+
+After significant code changes, re-index:
+\`\`\`bash
+npx magector index
+\`\`\`
+`;

package/src/templates/cursorrules.js

@@ -0,0 +1,45 @@
+/**
+ * .cursorrules content for Magento projects using Magector.
+ */
+export const CURSORRULES = `# Magento 2 Development Rules (Magector)
+
+## Semantic Search First
+
+Before reading files manually, ALWAYS use Magector MCP tools to find relevant code:
+
+1. \`magento_search\` — Natural language search across the entire codebase
+2. \`magento_find_class\` — Find a PHP class, interface, or trait
+3. \`magento_find_method\` — Find method implementations
+4. \`magento_find_config\` — Find XML configuration (di.xml, events.xml, etc.)
+5. \`magento_find_template\` — Find PHTML templates
+6. \`magento_find_plugin\` — Find interceptor plugins
+7. \`magento_find_observer\` — Find event observers
+8. \`magento_find_preference\` — Find DI preference overrides
+9. \`magento_find_api\` — Find REST/SOAP API endpoints
+10. \`magento_find_controller\` — Find controllers by route
+11. \`magento_find_block\` — Find Block classes
+12. \`magento_find_cron\` — Find cron job definitions
+13. \`magento_find_graphql\` — Find GraphQL resolvers and schema
+14. \`magento_find_db_schema\` — Find database table definitions
+15. \`magento_module_structure\` — Get full module structure
+16. \`magento_index\` — Re-index the codebase
+17. \`magento_stats\` — View index statistics
+18. \`magento_analyze_diff\` — Analyze git diffs for risk
+19. \`magento_complexity\` — Analyze code complexity
+
+## Writing Effective Queries
+
+- Describe what the code DOES, not what it IS: "calculate product price" not "price file"
+- Include Magento terms: "plugin for save", "observer for order place", "checkout totals collector"
+- Be specific: "customer address validation before checkout" not just "validation"
+
+## Magento Development Patterns
+
+- Always check for existing plugins before modifying core behavior
+- Use dependency injection — never instantiate classes with \`new\`
+- Prefer interfaces over concrete classes
+- Check events.xml for observer hooks before adding plugins
+- Use repositories for entity CRUD, not direct model save
+- Follow PSR-4 autoloading: Vendor\\\\Module\\\\Path\\\\ClassName
+- Use db_schema.xml for database changes, not setup scripts
+`;

package/src/validation/accuracy-calculator.js

@@ -0,0 +1,397 @@
+/**
+ * Accuracy calculation and metrics for validation
+ */
+
+/**
+ * Calculate precision: relevant results / total results
+ */
+export function calculatePrecision(results, expectedConditions) {
+  if (results.length === 0) return 0;
+
+  const relevant = results.filter(r => isResultRelevant(r, expectedConditions));
+  return relevant.length / results.length;
+}
+
+/**
+ * Calculate recall: found relevant / total expected relevant
+ */
+export function calculateRecall(results, expectedConditions, totalExpected) {
+  if (totalExpected === 0) return 1;
+
+  const relevant = results.filter(r => isResultRelevant(r, expectedConditions));
+  return Math.min(relevant.length / totalExpected, 1);
+}
+
+/**
+ * Calculate F1 score: harmonic mean of precision and recall
+ */
+export function calculateF1(precision, recall) {
+  if (precision + recall === 0) return 0;
+  return 2 * (precision * recall) / (precision + recall);
+}
+
+/**
+ * Calculate Mean Reciprocal Rank (MRR)
+ */
+export function calculateMRR(results, expectedConditions) {
+  for (let i = 0; i < results.length; i++) {
+    if (isResultRelevant(results[i], expectedConditions)) {
+      return 1 / (i + 1);
+    }
+  }
+  return 0;
+}
+
+/**
+ * Calculate Normalized Discounted Cumulative Gain (NDCG)
+ */
+export function calculateNDCG(results, expectedConditions, k = 10) {
+  const dcg = results.slice(0, k).reduce((sum, r, i) => {
+    const relevance = isResultRelevant(r, expectedConditions) ? 1 : 0;
+    return sum + relevance / Math.log2(i + 2);
+  }, 0);
+
+  // Ideal DCG (all relevant results at top)
+  const relevantCount = results.filter(r => isResultRelevant(r, expectedConditions)).length;
+  const idcg = Array(Math.min(relevantCount, k)).fill(1).reduce((sum, _, i) => {
+    return sum + 1 / Math.log2(i + 2);
+  }, 0);
+
+  return idcg === 0 ? 0 : dcg / idcg;
+}
+
+/**
+ * Check if a result matches expected conditions
+ */
+export function isResultRelevant(result, conditions) {
+  // Check expected Magento types
+  if (conditions.expectedTypes && conditions.expectedTypes.length > 0) {
+    const hasType = conditions.expectedTypes.some(t =>
+      result.magentoType === t ||
+      result.type === t.toLowerCase() ||
+      result.path?.includes(`/${t}/`)
+    );
+    if (hasType) return true;
+  }
+
+  // Check expected patterns
+  if (conditions.expectedPatterns && conditions.expectedPatterns.length > 0) {
+    const hasPattern = conditions.expectedPatterns.some(p =>
+      result.patterns?.includes(p) ||
+      result.isPlugin && p === 'plugin' ||
+      result.isController && p === 'controller' ||
+      result.isObserver && p === 'observer' ||
+      result.isRepository && p === 'repository' ||
+      result.isResolver && p === 'graphql_resolver' ||
+      result.isModel && p === 'model' ||
+      result.isBlock && p === 'block'
+    );
+    if (hasPattern) return true;
+  }
+
+  // Check expected classes
+  if (conditions.expectedClasses && conditions.expectedClasses.length > 0) {
+    const hasClass = conditions.expectedClasses.some(c =>
+      result.className === c ||
+      result.className?.includes(c) ||
+      result.content?.includes(`class ${c}`)
+    );
+    if (hasClass) return true;
+  }
+
+  // Check expected methods
+  if (conditions.expectedMethods && conditions.expectedMethods.length > 0) {
+    const hasMethod = conditions.expectedMethods.some(m =>
+      result.methodName === m ||
+      result.content?.includes(`function ${m}`)
+    );
+    if (hasMethod) return true;
+  }
+
+  // Check expected file types
+  if (conditions.expectedFileTypes && conditions.expectedFileTypes.length > 0) {
+    const hasFileType = conditions.expectedFileTypes.includes(result.type);
+    if (hasFileType) return true;
+  }
+
+  // Check expected content
+  if (conditions.expectedInContent && conditions.expectedInContent.length > 0) {
+    const contentLower = (result.content || '').toLowerCase();
+    const hasContent = conditions.expectedInContent.every(c =>
+      contentLower.includes(c.toLowerCase())
+    );
+    if (hasContent) return true;
+  }
+
+  // Check expected module
+  if (conditions.expectedModule) {
+    if (result.module === conditions.expectedModule ||
+        result.path?.includes(conditions.expectedModule.replace('_', '/'))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Calculate relevance score for a result (0-1)
+ */
+export function calculateRelevanceScore(result, conditions) {
+  let score = 0;
+  let factors = 0;
+
+  // Type match
+  if (conditions.expectedTypes) {
+    factors++;
+    if (conditions.expectedTypes.some(t => result.magentoType === t)) {
+      score += 1;
+    } else if (conditions.expectedTypes.some(t => result.path?.includes(`/${t}/`))) {
+      score += 0.7;
+    }
+  }
+
+  // Pattern match
+  if (conditions.expectedPatterns) {
+    factors++;
+    const patternMatch = conditions.expectedPatterns.filter(p =>
+      result.patterns?.includes(p) || result[`is${p.charAt(0).toUpperCase() + p.slice(1)}`]
+    ).length;
+    score += patternMatch / conditions.expectedPatterns.length;
+  }
+
+  // Class match
+  if (conditions.expectedClasses) {
+    factors++;
+    if (conditions.expectedClasses.some(c => result.className === c)) {
+      score += 1;
+    } else if (conditions.expectedClasses.some(c => result.className?.includes(c))) {
+      score += 0.5;
+    }
+  }
+
+  // Content match
+  if (conditions.expectedInContent) {
+    factors++;
+    const contentLower = (result.content || '').toLowerCase();
+    const contentMatch = conditions.expectedInContent.filter(c =>
+      contentLower.includes(c.toLowerCase())
+    ).length;
+    score += contentMatch / conditions.expectedInContent.length;
+  }
+
+  // Module match
+  if (conditions.expectedModule) {
+    factors++;
+    if (result.module === conditions.expectedModule) {
+      score += 1;
+    }
+  }
+
+  return factors === 0 ? 0 : score / factors;
+}
+
+/**
+ * Aggregate metrics across multiple queries
+ */
+export function aggregateMetrics(queryResults) {
+  const metrics = {
+    totalQueries: queryResults.length,
+    passedQueries: 0,
+    avgPrecision: 0,
+    avgRecall: 0,
+    avgF1: 0,
+    avgMRR: 0,
+    avgNDCG: 0,
+    byCategory: {},
+    failed: []
+  };
+
+  let sumPrecision = 0;
+  let sumRecall = 0;
+  let sumF1 = 0;
+  let sumMRR = 0;
+  let sumNDCG = 0;
+
+  for (const qr of queryResults) {
+    sumPrecision += qr.precision;
+    sumRecall += qr.recall;
+    sumF1 += qr.f1;
+    sumMRR += qr.mrr;
+    sumNDCG += qr.ndcg;
+
+    if (qr.passed) {
+      metrics.passedQueries++;
+    } else {
+      metrics.failed.push({
+        id: qr.queryId,
+        query: qr.query,
+        reason: qr.failReason
+      });
+    }
+
+    // Aggregate by category
+    if (!metrics.byCategory[qr.category]) {
+      metrics.byCategory[qr.category] = {
+        count: 0,
+        passed: 0,
+        avgPrecision: 0,
+        avgRecall: 0,
+        avgF1: 0
+      };
+    }
+    const cat = metrics.byCategory[qr.category];
+    cat.count++;
+    if (qr.passed) cat.passed++;
+    cat.avgPrecision += qr.precision;
+    cat.avgRecall += qr.recall;
+    cat.avgF1 += qr.f1;
+  }
+
+  // Calculate averages
+  const n = queryResults.length;
+  metrics.avgPrecision = sumPrecision / n;
+  metrics.avgRecall = sumRecall / n;
+  metrics.avgF1 = sumF1 / n;
+  metrics.avgMRR = sumMRR / n;
+  metrics.avgNDCG = sumNDCG / n;
+  metrics.passRate = metrics.passedQueries / n;
+
+  // Category averages
+  for (const cat of Object.values(metrics.byCategory)) {
+    cat.avgPrecision /= cat.count;
+    cat.avgRecall /= cat.count;
+    cat.avgF1 /= cat.count;
+    cat.passRate = cat.passed / cat.count;
+  }
+
+  return metrics;
+}
+
+/**
+ * Grade the overall accuracy
+ */
+export function gradeAccuracy(metrics) {
+  const f1 = metrics.avgF1;
+  const passRate = metrics.passRate;
+
+  // Weighted score
+  const score = (f1 * 0.6 + passRate * 0.4) * 100;
+
+  let grade, description;
+  if (score >= 95) {
+    grade = 'A+';
+    description = 'Excellent - Production ready';
+  } else if (score >= 90) {
+    grade = 'A';
+    description = 'Very Good - Minor improvements possible';
+  } else if (score >= 85) {
+    grade = 'B+';
+    description = 'Good - Some edge cases need work';
+  } else if (score >= 80) {
+    grade = 'B';
+    description = 'Above Average - Noticeable gaps';
+  } else if (score >= 75) {
+    grade = 'C+';
+    description = 'Average - Significant improvements needed';
+  } else if (score >= 70) {
+    grade = 'C';
+    description = 'Below Average - Major issues';
+  } else if (score >= 60) {
+    grade = 'D';
+    description = 'Poor - Fundamental problems';
+  } else {
+    grade = 'F';
+    description = 'Failing - Requires complete rework';
+  }
+
+  return {
+    score: Math.round(score * 10) / 10,
+    grade,
+    description,
+    breakdown: {
+      f1Contribution: Math.round(f1 * 60 * 10) / 10,
+      passRateContribution: Math.round(passRate * 40 * 10) / 10
+    }
+  };
+}
+
+/**
+ * Generate detailed report
+ */
+export function generateReport(metrics, grade) {
+  let report = `
+================================================================================
+                    MAGECTOR ACCURACY VALIDATION REPORT
+================================================================================
+
+OVERALL GRADE: ${grade.grade} (${grade.score}/100)
+${grade.description}
+
+--------------------------------------------------------------------------------
+AGGREGATE METRICS
+--------------------------------------------------------------------------------
+  Total Queries:     ${metrics.totalQueries}
+  Passed:            ${metrics.passedQueries} (${(metrics.passRate * 100).toFixed(1)}%)
+  Failed:            ${metrics.failed.length}
+
+  Precision:         ${(metrics.avgPrecision * 100).toFixed(2)}%
+  Recall:            ${(metrics.avgRecall * 100).toFixed(2)}%
+  F1 Score:          ${(metrics.avgF1 * 100).toFixed(2)}%
+  MRR:               ${(metrics.avgMRR * 100).toFixed(2)}%
+  NDCG@10:           ${(metrics.avgNDCG * 100).toFixed(2)}%
+
+--------------------------------------------------------------------------------
+PERFORMANCE BY CATEGORY
+--------------------------------------------------------------------------------
+`;
+
+  const categories = Object.entries(metrics.byCategory).sort((a, b) => b[1].avgF1 - a[1].avgF1);
+  for (const [name, cat] of categories) {
+    const status = cat.passRate >= 0.8 ? '✓' : cat.passRate >= 0.5 ? '~' : '✗';
+    report += `  ${status} ${name.padEnd(20)} F1: ${(cat.avgF1 * 100).toFixed(1).padStart(5)}%  Pass: ${cat.passed}/${cat.count}\n`;
+  }
+
+  if (metrics.failed.length > 0) {
+    report += `
+--------------------------------------------------------------------------------
+FAILED QUERIES
+--------------------------------------------------------------------------------
+`;
+    for (const fail of metrics.failed.slice(0, 10)) {
+      report += `  [${fail.id}] "${fail.query.substring(0, 40)}${fail.query.length > 40 ? '...' : ''}"\n`;
+      report += `         Reason: ${fail.reason}\n`;
+    }
+    if (metrics.failed.length > 10) {
+      report += `  ... and ${metrics.failed.length - 10} more\n`;
+    }
+  }
+
+  report += `
+--------------------------------------------------------------------------------
+RECOMMENDATIONS
+--------------------------------------------------------------------------------
+`;
+
+  // Generate recommendations based on weak categories
+  const weakCategories = categories.filter(([_, cat]) => cat.avgF1 < 0.7);
+  if (weakCategories.length > 0) {
+    report += `  Improve indexing for: ${weakCategories.map(([name]) => name).join(', ')}\n`;
+  }
+
+  if (metrics.avgPrecision < 0.7) {
+    report += `  - Precision is low: Consider stricter filtering and better chunking\n`;
+  }
+  if (metrics.avgRecall < 0.7) {
+    report += `  - Recall is low: Consider broader search terms and synonym expansion\n`;
+  }
+  if (metrics.avgMRR < 0.5) {
+    report += `  - MRR is low: Top results are not relevant, review ranking algorithm\n`;
+  }
+
+  report += `
+================================================================================
+`;
+
+  return report;
+}