ruvector 0.2.19 → 0.2.20

package/src/decompiler/name-predictor.js

@@ -0,0 +1,400 @@
+/**
+ * name-predictor.js - Pattern-based name prediction for minified identifiers.
+ *
+ * Uses the 210+ training patterns from claude-code-patterns.json to infer
+ * meaningful names based on context strings, property accesses, and
+ * structural patterns found near each identifier.
+ *
+ * Falls back to structural heuristics when no pattern matches.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** Cached patterns array — loaded once. */
+let _cachedPatterns = null;
+
+/**
+ * Load patterns from the JSON training data.
+ * @param {string} [patternPath] - override path to patterns JSON
+ * @returns {Array<{context_strings: string[], property_names: string[], inferred_name: string, module_hint: string, confidence: number}>}
+ */
+function loadPatterns(patternPath) {
+  if (_cachedPatterns && !patternPath) return _cachedPatterns;
+
+  const defaultPath = path.resolve(
+    __dirname,
+    '../../../../../crates/ruvector-decompiler/data/claude-code-patterns.json',
+  );
+  const resolved = patternPath || defaultPath;
+
+  try {
+    const raw = fs.readFileSync(resolved, 'utf-8');
+    _cachedPatterns = JSON.parse(raw);
+    return _cachedPatterns;
+  } catch {
+    // Pattern file not found — return empty, rely on structural rules
+    _cachedPatterns = [];
+    return _cachedPatterns;
+  }
+}
+
+/**
+ * Structural rename rules — deterministic, no model needed.
+ * Ordered by specificity (most specific first).
+ */
+const STRUCTURAL_RULES = [
+  // Async generators
+  {
+    test: (decl) => /async\s+function\s*\*/.test(decl),
+    nameFrom: (decl, ctx) => {
+      if (ctx.some((s) => s.includes('agent')) && ctx.some((s) => s.includes('loop'))) return 'agentLoop';
+      if (ctx.some((s) => s.includes('stream'))) return 'streamGenerator';
+      return 'asyncGenerator';
+    },
+    confidence: 0.7,
+  },
+  // Error subclasses
+  {
+    test: (decl) => /class\s+\w+\s+extends\s+Error/.test(decl),
+    nameFrom: (decl) => {
+      const match = decl.match(/class\s+(\w+)\s+extends\s+(\w*Error)/);
+      if (match && !isMinifiedLike(match[1])) return match[1];
+      return 'CustomError';
+    },
+    confidence: 0.85,
+  },
+  // Class extending another class
+  {
+    test: (decl) => /class\s+\w+\s+extends\s+\w+/.test(decl),
+    nameFrom: (decl) => {
+      const match = decl.match(/class\s+(\w+)\s+extends\s+(\w+)/);
+      if (match && !isMinifiedLike(match[1])) return match[1];
+      if (match) return `${match[2]}Subclass`;
+      return null;
+    },
+    confidence: 0.75,
+  },
+  // Regular class
+  {
+    test: (decl) => /class\s+\w+/.test(decl),
+    nameFrom: (decl) => {
+      const match = decl.match(/class\s+(\w+)/);
+      if (match && !isMinifiedLike(match[1])) return match[1];
+      return null;
+    },
+    confidence: 0.7,
+  },
+  // Export default function
+  {
+    test: (decl) => /export\s+default\s+function/.test(decl),
+    nameFrom: () => 'defaultExport',
+    confidence: 0.5,
+  },
+  // Named function
+  {
+    test: (decl) => /function\s+([a-zA-Z_$]\w+)/.test(decl),
+    nameFrom: (decl) => {
+      const match = decl.match(/function\s+([a-zA-Z_$]\w+)/);
+      if (match && !isMinifiedLike(match[1])) return match[1];
+      return null;
+    },
+    confidence: 0.8,
+  },
+];
+
+/**
+ * Parameter naming rules based on usage context.
+ */
+const PARAM_RULES = [
+  { context: ['.messages', 'systemPrompt', 'canUseTool'], name: 'params', type: 'AgentLoopParams' },
+  { context: ['.method', '.url', '.headers'], name: 'request', type: 'Request' },
+  { context: ['.status', '.json', '.send'], name: 'response', type: 'Response' },
+  { context: ['.next', '.done', '.value'], name: 'iterator', type: 'Iterator' },
+  { context: ['.emit', '.on', '.removeListener'], name: 'emitter', type: 'EventEmitter' },
+  { context: ['.pipe', '.write', '.end'], name: 'stream', type: 'Stream' },
+  { context: ['.query', '.params', '.body'], name: 'req', type: 'Request' },
+  { context: ['.resolve', '.reject'], name: 'promise', type: 'Promise' },
+  { context: ['.name', '.version', '.description'], name: 'packageInfo', type: 'PackageInfo' },
+  { context: ['.key', '.value', '.ttl'], name: 'cacheEntry', type: 'CacheEntry' },
+  { context: ['.token', '.user', '.role'], name: 'session', type: 'Session' },
+  { context: ['.width', '.height', '.x', '.y'], name: 'rect', type: 'Rect' },
+  { context: ['.type', '.data', '.target'], name: 'event', type: 'Event' },
+  { context: ['.path', '.content', '.encoding'], name: 'file', type: 'FileInfo' },
+  { context: ['.host', '.port', '.protocol'], name: 'connectionInfo', type: 'ConnectionInfo' },
+];
+
+/**
+ * Check if a name looks minified (short, no semantic meaning).
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isMinifiedLike(name) {
+  if (!name) return true;
+  return /^[a-zA-Z][a-zA-Z0-9$]{0,2}$/.test(name);
+}
+
+/**
+ * Score how well a pattern matches the given context.
+ *
+ * @param {object} pattern - from claude-code-patterns.json
+ * @param {string[]} contextStrings - strings found near the identifier
+ * @param {string[]} propertyNames - property accesses found near the identifier
+ * @returns {number} 0-1 match score
+ */
+function scorePatternMatch(pattern, contextStrings, propertyNames) {
+  let score = 0;
+  let totalChecks = 0;
+
+  // Check context string matches
+  if (pattern.context_strings && pattern.context_strings.length > 0) {
+    for (const ctx of pattern.context_strings) {
+      totalChecks++;
+      if (contextStrings.some((s) => s.includes(ctx) || ctx.includes(s))) {
+        score++;
+      }
+    }
+  }
+
+  // Check property name matches
+  if (pattern.property_names && pattern.property_names.length > 0) {
+    for (const prop of pattern.property_names) {
+      totalChecks++;
+      const propAccess = `.${prop}`;
+      if (propertyNames.some((p) => p === propAccess || p === prop)) {
+        score++;
+      }
+    }
+  }
+
+  if (totalChecks === 0) return 0;
+  return score / totalChecks;
+}
+
+/**
+ * Predict a meaningful name for a minified identifier.
+ *
+ * @param {string} minifiedName - the original short name (e.g. "s$")
+ * @param {string[]} contextStrings - strings/properties near the identifier
+ * @param {object} [options]
+ * @param {string} [options.declaration] - the declaration statement
+ * @param {string} [options.patternPath] - path to patterns JSON
+ * @param {number} [options.minConfidence=0.3] - minimum confidence to accept
+ * @returns {{name: string, confidence: number, source: string}|null}
+ */
+function predictName(minifiedName, contextStrings, options = {}) {
+  const { declaration = '', patternPath, minConfidence = 0.3 } = options;
+
+  // Separate context strings from property accesses
+  const props = contextStrings.filter((s) => s.startsWith('.'));
+  const strings = contextStrings.filter((s) => !s.startsWith('.'));
+
+  // 1. Try direct-assignment analysis (highest precision)
+  // If X = Y.propertyName, then X should be named "propertyName"
+  const directName = inferFromDirectAssignment(minifiedName, declaration);
+  if (directName) {
+    return { name: directName.name, confidence: directName.confidence, source: 'direct-assign' };
+  }
+
+  // 2. Try structural rules (high specificity)
+  for (const rule of STRUCTURAL_RULES) {
+    if (rule.test(declaration)) {
+      const name = rule.nameFrom(declaration, contextStrings);
+      if (name && rule.confidence >= minConfidence) {
+        return { name, confidence: rule.confidence, source: 'structural' };
+      }
+    }
+  }
+
+  // 3. Try pattern matching against training data
+  const patterns = loadPatterns(patternPath);
+  let bestMatch = null;
+  let bestScore = 0;
+
+  for (const pattern of patterns) {
+    const matchScore = scorePatternMatch(pattern, strings, props);
+    const adjustedScore = matchScore * pattern.confidence;
+
+    if (adjustedScore > bestScore && adjustedScore >= minConfidence) {
+      bestScore = adjustedScore;
+      bestMatch = pattern;
+    }
+  }
+
+  if (bestMatch) {
+    return {
+      name: toCamelCase(bestMatch.inferred_name),
+      confidence: bestScore,
+      source: 'pattern',
+    };
+  }
+
+  // 3. Try parameter naming rules
+  for (const rule of PARAM_RULES) {
+    const matches = rule.context.filter((c) =>
+      contextStrings.some((s) => s.includes(c)),
+    );
+    if (matches.length >= 2) {
+      return {
+        name: rule.name,
+        confidence: 0.6,
+        source: 'param-rule',
+        type: rule.type,
+      };
+    }
+  }
+
+  // 4. Heuristic fallbacks based on usage patterns
+  const heuristic = heuristicName(minifiedName, contextStrings, declaration);
+  if (heuristic && heuristic.confidence >= minConfidence) {
+    return heuristic;
+  }
+
+  return null;
+}
+
+/**
+ * Infer a name from direct assignment patterns.
+ *   let B = A.messages  -> B should be "messages"
+ *   let Z = await Y2(B, G, ...) -> Z might be "result" or inferred from Y2
+ *   var s$ = async function*(...) -> handled by structural rules
+ *
+ * @param {string} minifiedName
+ * @param {string} declaration
+ * @returns {{name: string, confidence: number}|null}
+ */
+function inferFromDirectAssignment(minifiedName, declaration) {
+  if (!declaration) return null;
+  const escaped = minifiedName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  // Pattern: X = Y.propertyName  (property extraction)
+  const propMatch = declaration.match(
+    new RegExp(`${escaped}\\s*=\\s*\\w+\\.(\\w{2,30})`)
+  );
+  if (propMatch && propMatch[1].length > 2) {
+    return { name: propMatch[1], confidence: 0.85 };
+  }
+
+  // Pattern: X = await Y(...)  (function call result)
+  const awaitCallMatch = declaration.match(
+    new RegExp(`${escaped}\\s*=\\s*await\\s+(\\w+)\\(`)
+  );
+  if (awaitCallMatch) {
+    const fnName = awaitCallMatch[1];
+    if (!isMinifiedLike(fnName)) {
+      // Infer from function name: createApiRequest -> apiRequest
+      const resultName = fnName.replace(/^(create|get|fetch|make|build|load)/, '').replace(/^./, (c) => c.toLowerCase());
+      return { name: resultName || 'result', confidence: 0.7 };
+    }
+    return { name: 'result', confidence: 0.5 };
+  }
+
+  // Pattern: for await (let J of Z)  -> J is an item from the iterable
+  const forOfMatch = declaration.match(
+    new RegExp(`for\\s+await\\s*\\(\\s*(?:let|const|var)\\s+${escaped}\\s+of\\s+(\\w+)`)
+  );
+  if (forOfMatch) {
+    return { name: 'item', confidence: 0.5 };
+  }
+
+  // Pattern: function parameter  (first param of function*)
+  const funcParamMatch = declaration.match(
+    new RegExp(`function\\s*\\*?\\s*\\w*\\s*\\(\\s*${escaped}(?:\\s*,|\\s*\\))`)
+  );
+  if (funcParamMatch) {
+    // First parameter of a function -> "params" or "options"
+    return { name: 'params', confidence: 0.5 };
+  }
+
+  return null;
+}
+
+/**
+ * Heuristic name inference from usage patterns.
+ *
+ * @param {string} minifiedName
+ * @param {string[]} contextStrings
+ * @param {string} declaration
+ * @returns {{name: string, confidence: number, source: string}|null}
+ */
+function heuristicName(minifiedName, contextStrings, declaration) {
+  const ctx = contextStrings.join(' ').toLowerCase();
+
+  // Callback / handler patterns
+  if (ctx.includes('callback') || ctx.includes('handler') || ctx.includes('listener')) {
+    return { name: 'handler', confidence: 0.4, source: 'heuristic' };
+  }
+  // Error variable
+  if (/catch\s*\(\s*$/.test(declaration) || ctx.includes('error') && ctx.includes('catch')) {
+    return { name: 'error', confidence: 0.5, source: 'heuristic' };
+  }
+  // Iterator / loop variable used with .length or [i]
+  if (ctx.includes('.length') && ctx.includes('for')) {
+    return { name: 'items', confidence: 0.4, source: 'heuristic' };
+  }
+  // Result of await
+  if (declaration.includes('await')) {
+    if (ctx.includes('fetch') || ctx.includes('request')) {
+      return { name: 'response', confidence: 0.5, source: 'heuristic' };
+    }
+    return { name: 'result', confidence: 0.35, source: 'heuristic' };
+  }
+  // Boolean-looking (used in conditions)
+  if (ctx.includes('if') && (ctx.includes('===true') || ctx.includes('===false') || ctx.includes('!!'))) {
+    return { name: 'isEnabled', confidence: 0.35, source: 'heuristic' };
+  }
+
+  return null;
+}
+
+/**
+ * Convert a PascalCase or kebab-case name to camelCase.
+ * @param {string} name
+ * @returns {string}
+ */
+function toCamelCase(name) {
+  if (!name) return name;
+  // If already camelCase, return as-is
+  if (/^[a-z]/.test(name) && !name.includes('-') && !name.includes('_')) return name;
+  // PascalCase -> camelCase
+  if (/^[A-Z]/.test(name) && !name.includes('-') && !name.includes('_')) {
+    return name[0].toLowerCase() + name.slice(1);
+  }
+  // kebab-case or snake_case -> camelCase
+  return name.replace(/[-_](.)/g, (_, c) => c.toUpperCase()).replace(/^./, (c) => c.toLowerCase());
+}
+
+/**
+ * Infer a parameter name from its position and usage.
+ * @param {number} index - parameter position (0-based)
+ * @param {string[]} contextStrings
+ * @returns {string}
+ */
+function inferParamName(index, contextStrings) {
+  // Try param rules
+  for (const rule of PARAM_RULES) {
+    const matches = rule.context.filter((c) =>
+      contextStrings.some((s) => s.includes(c)),
+    );
+    if (matches.length >= 1) {
+      return rule.name;
+    }
+  }
+
+  // Generic fallback
+  const fallbacks = ['param', 'value', 'data', 'input', 'arg', 'item'];
+  return fallbacks[index] || `param${index}`;
+}
+
+module.exports = {
+  predictName,
+  loadPatterns,
+  scorePatternMatch,
+  inferParamName,
+  toCamelCase,
+  isMinifiedLike,
+  STRUCTURAL_RULES,
+  PARAM_RULES,
+};

package/src/decompiler/npm-fetch.js

@@ -0,0 +1,176 @@
+/**
+ * npm-fetch.js - Fetch package info and files from the npm registry.
+ *
+ * Uses the built-in Node 18+ fetch API. Retrieves package metadata from
+ * registry.npmjs.org and file contents from unpkg.com / jsdelivr.
+ */
+
+'use strict';
+
+const REGISTRY_BASE = 'https://registry.npmjs.org';
+const JSDELIVR_BASE = 'https://data.jsdelivr.com/v1/package/npm';
+const UNPKG_BASE = 'https://unpkg.com';
+
+/**
+ * Fetch package metadata from the npm registry.
+ * @param {string} packageName - npm package name (e.g. 'express', '@anthropic-ai/claude-code')
+ * @returns {Promise<{name: string, description: string, versions: string[], latest: string, distTags: object, packageJson: object}>}
+ */
+async function fetchPackageInfo(packageName) {
+  const url = `${REGISTRY_BASE}/${encodeURIComponent(packageName).replace('%40', '@')}`;
+  const resp = await fetch(url, {
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!resp.ok) {
+    throw new Error(`Package "${packageName}" not found (HTTP ${resp.status})`);
+  }
+
+  const data = await resp.json();
+  const versions = Object.keys(data.versions || {}).reverse();
+  const distTags = data['dist-tags'] || {};
+  const latest = distTags.latest || versions[0] || '';
+
+  return {
+    name: data.name,
+    description: data.description || '',
+    versions,
+    latest,
+    distTags,
+    packageJson: data.versions?.[latest] || {},
+  };
+}
+
+/**
+ * Fetch the file list for a specific package version via jsDelivr.
+ * @param {string} packageName
+ * @param {string} version
+ * @returns {Promise<Array<{name: string, hash: string, size: number}>>}
+ */
+async function fetchPackageFileList(packageName, version) {
+  const encodedName = encodeURIComponent(packageName).replace('%40', '@');
+  const url = `${JSDELIVR_BASE}/${encodedName}@${version}/flat`;
+  const resp = await fetch(url);
+  if (!resp.ok) {
+    throw new Error(`Could not list files for ${packageName}@${version}`);
+  }
+  const data = await resp.json();
+  return (data.files || []);
+}
+
+/**
+ * Fetch the content of a single file from unpkg.
+ * @param {string} packageName
+ * @param {string} version
+ * @param {string} filePath - e.g. '/dist/index.js'
+ * @returns {Promise<string>}
+ */
+async function fetchFileContent(packageName, version, filePath) {
+  const cleanPath = filePath.startsWith('/') ? filePath.slice(1) : filePath;
+  const url = `${UNPKG_BASE}/${packageName}@${version}/${cleanPath}`;
+  const resp = await fetch(url, { redirect: 'follow' });
+  if (!resp.ok) {
+    throw new Error(`Could not fetch ${cleanPath} from ${packageName}@${version} (HTTP ${resp.status})`);
+  }
+  return resp.text();
+}
+
+/**
+ * Find the main JS bundle file from a file list.
+ * Checks common locations and falls back to the largest .js file.
+ * @param {Array<{name: string, size: number}>} files
+ * @param {object} [packageJson] - optional package.json to check main/module/browser fields
+ * @returns {string|null}
+ */
+function findMainBundle(files, packageJson) {
+  // Check package.json fields first
+  if (packageJson) {
+    const fields = ['browser', 'module', 'main'];
+    for (const field of fields) {
+      if (typeof packageJson[field] === 'string') {
+        const normalized = packageJson[field].startsWith('/')
+          ? packageJson[field]
+          : '/' + packageJson[field];
+        if (files.some((f) => f.name === normalized)) {
+          return normalized;
+        }
+      }
+    }
+  }
+
+  // Well-known candidate paths
+  const candidates = [
+    '/dist/cli.js',
+    '/dist/index.js',
+    '/dist/main.js',
+    '/dist/bundle.js',
+    '/lib/index.js',
+    '/lib/cli.js',
+    '/index.js',
+    '/cli.js',
+  ];
+
+  for (const candidate of candidates) {
+    if (files.some((f) => f.name === candidate)) {
+      return candidate;
+    }
+  }
+
+  // Fallback: largest JS file (prefer non-minified)
+  const jsFiles = files
+    .filter((f) => f.name.endsWith('.js') && !f.name.endsWith('.min.js'))
+    .sort((a, b) => b.size - a.size);
+
+  return jsFiles.length > 0 ? jsFiles[0].name : null;
+}
+
+/**
+ * Parse a target string into its components.
+ * Handles: 'express', 'express@4.18.2', '@scope/pkg@1.0.0',
+ * './local.js', 'https://...'.
+ * @param {string} target
+ * @returns {{type: 'npm'|'file'|'url', name?: string, version?: string, path?: string, url?: string}}
+ */
+function parseTarget(target) {
+  if (target.startsWith('http://') || target.startsWith('https://')) {
+    return { type: 'url', url: target };
+  }
+
+  if (target.startsWith('.') || target.startsWith('/')) {
+    return { type: 'file', path: target };
+  }
+
+  // npm package: @scope/name@version or name@version
+  let name = target;
+  let version = undefined;
+  if (target.startsWith('@')) {
+    // scoped: @scope/name@version
+    const afterScope = target.indexOf('/', 1);
+    if (afterScope > 0) {
+      const atIdx = target.indexOf('@', afterScope + 1);
+      if (atIdx > 0) {
+        name = target.slice(0, atIdx);
+        version = target.slice(atIdx + 1);
+      }
+    }
+  } else {
+    const atIdx = target.indexOf('@');
+    if (atIdx > 0) {
+      name = target.slice(0, atIdx);
+      version = target.slice(atIdx + 1);
+    }
+  }
+
+  return { type: 'npm', name, version };
+}
+
+module.exports = {
+  fetchPackageInfo,
+  fetchPackageFileList,
+  fetchFileContent,
+  findMainBundle,
+  parseTarget,
+  REGISTRY_BASE,
+  UNPKG_BASE,
+  JSDELIVR_BASE,
+};