sweet-search 2.5.2 → 2.5.4

package/core/infrastructure/native-sparse-gram.js

@@ -4,37 +4,185 @@
  */
 
 import { existsSync } from 'fs';
-import { createRequire } from 'module';
-import { resolveNativeAddon } from './native-resolver.js';
+import { loadNativeAddon } from './native-resolver.js';
 import { SPARSE_SYMBOL_MASKS, resolveSparseSymbolMask } from './constants.js';
 
 // Re-export from constants.js — canonical source of symbol type vocabulary.
 export { SPARSE_SYMBOL_MASKS, resolveSparseSymbolMask };
 
-const require = createRequire(import.meta.url);
-
 let _addon = null;
 let _addonLoaded = false;
+let _fallbackWeights = null;
+
+const ASCII_DIM = 128;
+const WEIGHT_TABLE_LEN = ASCII_DIM * ASCII_DIM;
+const MIN_SPAN_LEN = 3;
+const MAX_GRAM_LEN = 12;
+const FALLBACK_WEIGHTS_ID = 'common-code-bigram-v1';
+const COMMON_CODE_BIGRAMS = [
+  ['th', 5000], ['he', 4800], ['in', 4700], ['er', 4500], ['re', 4300], ['fo', 4200], ['or', 4200], ['fu', 4100],
+  ['un', 4000], ['ct', 3900], ['cl', 3800], ['ss', 3700], ['co', 3600], ['de', 3500], ['nt', 3400], ['io', 3300],
+  ['on', 3200], ['st', 3100], ['te', 3000], ['ra', 2900], ['ri', 2800], ['al', 2700], ['se', 2600], ['it', 2500],
+  ['at', 2400], ['es', 2300], ['is', 2200], ['le', 2100], ['ar', 2000], ['ha', 1900], ['ng', 1800], ['js', 1700],
+  ['ts', 1600], ['py', 1500], ['rs', 1400], ['::', 1300], ['->', 1200], ['=>', 1100], ['__', 1000], ['./', 900],
+];
+
+function isSpanCode(code) {
+  return (code >= 97 && code <= 122) || (code >= 48 && code <= 57) ||
+    code === 95 || code === 46 || code === 47 || code === 58 || code === 45;
+}
+
+function normalizeAsciiCode(code) {
+  return code >= 65 && code <= 90 ? code + 32 : code;
+}
+
+function pairIndex(left, right) {
+  return (left << 7) | right;
+}
+
+function buildFallbackWeights() {
+  if (_fallbackWeights) return _fallbackWeights;
+  const counts = new Uint32Array(WEIGHT_TABLE_LEN);
+  counts.fill(1);
+  for (const [pair, count] of COMMON_CODE_BIGRAMS) {
+    counts[pairIndex(pair.charCodeAt(0), pair.charCodeAt(1))] = count;
+  }
+  let total = 0;
+  for (const count of counts) total += count;
+  const denominator = total + WEIGHT_TABLE_LEN;
+  _fallbackWeights = Array.from(counts, (count) => Math.log(denominator / (count + 1)));
+  return _fallbackWeights;
+}
+
+function collectNormalizedSpans(text) {
+  const spans = [];
+  let current = [];
+  for (const char of String(text || '')) {
+    const code = normalizeAsciiCode(char.charCodeAt(0));
+    if (isSpanCode(code)) current.push(code);
+    else if (current.length >= MIN_SPAN_LEN) {
+      spans.push(current);
+      current = [];
+    } else current = [];
+  }
+  if (current.length >= MIN_SPAN_LEN) spans.push(current);
+  return spans;
+}
+
+function bytesToString(bytes) {
+  return String.fromCharCode(...bytes);
+}
+
+function extractSparseGramsFromSpan(span, weights) {
+  if (span.length < MIN_SPAN_LEN) return [];
+  const pairWeights = [];
+  for (let i = 0; i < span.length - 1; i += 1) {
+    pairWeights.push(weights[pairIndex(span[i], span[i + 1])]);
+  }
+  const grams = [];
+  const seen = new Set();
+  for (let start = 0; start <= span.length - MIN_SPAN_LEN; start += 1) {
+    const maxEnd = Math.min(span.length, start + MAX_GRAM_LEN);
+    for (let end = start + MIN_SPAN_LEN; end <= maxEnd; end += 1) {
+      const first = pairWeights[start];
+      const last = pairWeights[end - 2];
+      let interiorMax = Number.NEGATIVE_INFINITY;
+      if (end - start > MIN_SPAN_LEN) {
+        for (let i = start + 1; i < end - 2; i += 1) {
+          interiorMax = Math.max(interiorMax, pairWeights[i]);
+        }
+      }
+      if (Math.min(first, last) > interiorMax) {
+        const gram = bytesToString(span.slice(start, end));
+        if (!seen.has(gram)) { seen.add(gram); grams.push(gram); }
+      }
+    }
+  }
+  if (grams.length === 0) {
+    for (let i = 0; i <= span.length - MIN_SPAN_LEN; i += 1) {
+      const gram = bytesToString(span.slice(i, i + MIN_SPAN_LEN));
+      if (!seen.has(gram)) { seen.add(gram); grams.push(gram); }
+    }
+  }
+  return grams;
+}
+
+function normalizeLiteral(literal) {
+  const bytes = [];
+  for (const char of String(literal || '')) {
+    const code = normalizeAsciiCode(char.charCodeAt(0));
+    if (!isSpanCode(code)) return null;
+    bytes.push(code);
+  }
+  return bytes.length >= MIN_SPAN_LEN ? bytes : null;
+}
+
+function extractCoveringGramsFromSpan(span, weights) {
+  if (span.length < MIN_SPAN_LEN) return [];
+  const pairWeights = [];
+  for (let i = 0; i < span.length - 1; i += 1) {
+    pairWeights.push(weights[pairIndex(span[i], span[i + 1])]);
+  }
+  const grams = [];
+  const seen = new Set();
+  const stack = [[0, span.length]];
+  while (stack.length > 0) {
+    const [start, end] = stack.pop();
+    const len = end - start;
+    if (len < MIN_SPAN_LEN) continue;
+    if (len === MIN_SPAN_LEN) {
+      const gram = bytesToString(span.slice(start, end));
+      if (!seen.has(gram)) { seen.add(gram); grams.push(gram); }
+      continue;
+    }
+    if (len <= MAX_GRAM_LEN) {
+      const first = pairWeights[start];
+      const last = pairWeights[end - 2];
+      let interiorMax = Number.NEGATIVE_INFINITY;
+      for (let i = start + 1; i < end - 2; i += 1) {
+        interiorMax = Math.max(interiorMax, pairWeights[i]);
+      }
+      if (Math.min(first, last) > interiorMax) {
+        const gram = bytesToString(span.slice(start, end));
+        if (!seen.has(gram)) { seen.add(gram); grams.push(gram); }
+        continue;
+      }
+    }
+    let maxWeight = Number.NEGATIVE_INFINITY;
+    let maxPos = start + 1;
+    for (let i = start + 1; i < end - 1; i += 1) {
+      if (pairWeights[i] > maxWeight) {
+        maxWeight = pairWeights[i];
+        maxPos = i;
+      }
+    }
+    const leftEnd = maxPos + 1;
+    const rightStart = maxPos;
+    if (end - rightStart >= MIN_SPAN_LEN) stack.push([rightStart, end]);
+    if (leftEnd - start >= MIN_SPAN_LEN) stack.push([start, leftEnd]);
+  }
+  if (grams.length === 0) {
+    for (let i = 0; i <= span.length - MIN_SPAN_LEN; i += 1) {
+      const gram = bytesToString(span.slice(i, i + MIN_SPAN_LEN));
+      if (!seen.has(gram)) { seen.add(gram); grams.push(gram); }
+    }
+  }
+  return grams;
+}
 
 function loadAddon() {
   if (_addonLoaded) return _addon;
   _addonLoaded = true;
 
-  try {
-    const addonPath = resolveNativeAddon();
-    if (!addonPath) return null;
-    const mod = require(addonPath);
-    if (
-      typeof mod.buildSparseGramIndex === 'function' &&
-      typeof mod.NativeSparseGramIndex?.load === 'function' &&
-      typeof mod.extractRegexLiterals === 'function'
-    ) {
-      _addon = mod;
-    }
-  } catch (err) {
-    // Native addon is optional; callers decide whether to warn or fall back.
-    if (process.env.SWEET_DEBUG) console.debug('[native-sparse-gram] addon load failed:', err.message);
-  }
+  // CUDA-preferred with CPU fallback (see loadNativeAddon): a CUDA addon that
+  // can't load on a no-GPU box falls back to the plain CPU addon.
+  const res = loadNativeAddon({
+    validate: (m) =>
+      typeof m.buildSparseGramIndex === 'function' &&
+      typeof m.NativeSparseGramIndex?.load === 'function' &&
+      typeof m.extractRegexLiterals === 'function',
+  });
+  if (res) _addon = res.mod;
 
   return _addon;
 }
@@ -43,6 +191,20 @@ export function hasNativeSparseGramSupport() {
   return !!loadAddon();
 }
 
+/**
+ * Whether the native addon exposes the in-process grep functions
+ * (native_grep_lines / native_grep_full). When true, ss-grep / ss-pattern can
+ * run regex matching in-process without spawning ripgrep.
+ */
+export function isNativeGrepAvailable() {
+  const addon = loadAddon();
+  return !!(
+    addon &&
+    typeof addon.nativeGrepLines === 'function' &&
+    typeof addon.nativeGrepFull === 'function'
+  );
+}
+
 export function buildSparseGramIndexArtifact({ projectRoot, files, fileSymbolMasks = [], outputPath }) {
   const addon = loadAddon();
   if (!addon) {
@@ -63,6 +225,86 @@ export function loadSparseGramIndex(indexPath) {
   return addon.NativeSparseGramIndex.load(indexPath);
 }
 
+function normalizeExtractionResult(result) {
+  if (!result || !Array.isArray(result.grams)) return null;
+  return {
+    weightsId: result.weightsId || result.weights_id || FALLBACK_WEIGHTS_ID,
+    grams: [...new Set(result.grams.map(String))].sort(),
+  };
+}
+
+function fallbackSparseGramExtraction(content) {
+  const weights = buildFallbackWeights();
+  const grams = new Set();
+  for (const span of collectNormalizedSpans(content)) {
+    for (const gram of extractSparseGramsFromSpan(span, weights)) grams.add(gram);
+  }
+  return { weightsId: FALLBACK_WEIGHTS_ID, grams: [...grams].sort() };
+}
+
+function fallbackRequiredGrams(literals) {
+  if (!Array.isArray(literals) || literals.length === 0) {
+    return { eligible: false, grams: [], weightsId: FALLBACK_WEIGHTS_ID };
+  }
+  const weights = buildFallbackWeights();
+  const grams = new Set();
+  for (const literal of literals) {
+    const span = normalizeLiteral(literal);
+    if (!span) return { eligible: false, grams: [], weightsId: FALLBACK_WEIGHTS_ID };
+    const required = extractCoveringGramsFromSpan(span, weights);
+    if (required.length === 0) return { eligible: false, grams: [], weightsId: FALLBACK_WEIGHTS_ID };
+    for (const gram of required) grams.add(gram);
+  }
+  return { eligible: true, grams: [...grams].sort(), weightsId: FALLBACK_WEIGHTS_ID };
+}
+
+export function extractSparseGramDeltaRecord({ indexPath, content }) {
+  const addon = loadAddon();
+  if (addon) {
+    try {
+      if (indexPath && existsSync(indexPath)) {
+        const index = addon.NativeSparseGramIndex.load(indexPath);
+        const extractor = index.extractIndexGrams || index.extract_index_grams;
+        if (typeof extractor === 'function') return normalizeExtractionResult(extractor.call(index, content));
+        const stats = typeof index.getStats === 'function' ? index.getStats() : null;
+        if (stats?.usedFallbackWeights || stats?.used_fallback_weights) {
+          return fallbackSparseGramExtraction(content);
+        }
+        if (typeof stats?.weightsId === 'string' || typeof stats?.weights_id === 'string') {
+          return { weightsId: stats.weightsId || stats.weights_id, grams: [] };
+        }
+      }
+      if (typeof addon.extractSparseGramDelta === 'function') {
+        return normalizeExtractionResult(addon.extractSparseGramDelta(content));
+      }
+      if (typeof addon.extract_sparse_gram_delta === 'function') {
+        return normalizeExtractionResult(addon.extract_sparse_gram_delta(content));
+      }
+    } catch (err) {
+      if (process.env.SWEET_DEBUG) console.debug('[native-sparse-gram] extractSparseGramDeltaRecord failed:', err.message);
+    }
+  }
+  return fallbackSparseGramExtraction(content);
+}
+
+export function extractSparseGramRequiredGrams(sparseGramIndex, literals) {
+  try {
+    const extractor = sparseGramIndex?.extractLiteralCoveringGrams || sparseGramIndex?.extract_literal_covering_grams;
+    if (typeof extractor === 'function') {
+      const result = extractor.call(sparseGramIndex, literals);
+      return {
+        eligible: !!result?.eligible,
+        grams: Array.isArray(result?.grams) ? [...new Set(result.grams.map(String))].sort() : [],
+        weightsId: result?.weightsId || result?.weights_id || null,
+      };
+    }
+  } catch (err) {
+    if (process.env.SWEET_DEBUG) console.debug('[native-sparse-gram] extractSparseGramRequiredGrams failed:', err.message);
+    return null;
+  }
+  return fallbackRequiredGrams(literals);
+}
+
 export function extractRegexLiteralClauses(regex) {
   const addon = loadAddon();
   if (!addon) return null;
@@ -254,4 +496,3 @@ export function searchFull(sparseGramIndex, clauses, regex, projectRoot, opts =
     return null;
   }
 }
-

package/core/infrastructure/native-tokenizer.js

@@ -11,10 +11,7 @@
  */
 
 import { existsSync } from 'fs';
-import { resolveNativeAddon } from './native-resolver.js';
-import { createRequire } from 'module';
-
-const require = createRequire(import.meta.url);
+import { loadNativeAddon } from './native-resolver.js';
 
 let _addon = null;
 let _addonLoaded = false;
@@ -22,17 +19,11 @@ let _addonLoaded = false;
 function loadAddon() {
   if (_addonLoaded) return _addon;
   _addonLoaded = true;
-  try {
-    const addonPath = resolveNativeAddon();
-    if (addonPath) {
-      const mod = require(addonPath);
-      if (typeof mod.NativeTokenizer?.fromFile === 'function') {
-        _addon = mod;
-      }
-    }
-  } catch {
-    // Native addon not available
-  }
+  // CUDA-preferred with CPU fallback (see loadNativeAddon): on a no-GPU box the
+  // CUDA addon throws on load (libcuda absent) and we fall back to the plain
+  // CPU addon so local tokenization (→ ORT-INT8 indexing) keeps working.
+  const res = loadNativeAddon({ validate: (m) => typeof m.NativeTokenizer?.fromFile === 'function' });
+  if (res) _addon = res.mod;
   return _addon;
 }
 

package/core/infrastructure/simd-distance.js

@@ -17,8 +17,7 @@
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { readFileSync, existsSync } from 'fs';
-import { createRequire } from 'module';
-import { resolveNativeAddon } from './native-resolver.js';
+import { loadNativeAddon } from './native-resolver.js';
 
 const DATA_OFFSET = 0; // SIMD popcount needs no LUT
 
@@ -46,17 +45,12 @@ async function initWasm() {
   initPromise = (async () => {
     try {
       const __dirname = dirname(fileURLToPath(import.meta.url));
-      const require = createRequire(import.meta.url);
-
-      // Tier 1: Try native Rust addon (rayon parallel + NEON/AVX2 SIMD)
-      try {
-        const addonPath = resolveNativeAddon();
-        if (addonPath) {
-          nativeMaxsim = require(addonPath);
-        }
-      } catch {
-        // Native not available — fall through to WASM
-      }
+
+      // Tier 1: native Rust addon (rayon + NEON/AVX2 SIMD). CUDA-preferred with
+      // CPU fallback (see loadNativeAddon) — a CUDA addon that can't load on a
+      // no-GPU box falls back to the plain CPU addon; otherwise WASM (Tier 2).
+      const nativeRes = loadNativeAddon();
+      if (nativeRes) nativeMaxsim = nativeRes.mod;
 
       // Tier 2a: Load hand-assembled SIMD distance WASM
       const wasmPath = join(__dirname, 'simd-distance.wasm');
@@ -79,11 +73,11 @@ async function initWasm() {
       initDone = true;
 
       if (nativeMaxsim) {
-        console.log('[MaxSim] Tier 1: Native Rust + Rayon (parallel SIMD)');
+        console.error('[MaxSim] Tier 1: Native Rust + Rayon (parallel SIMD)');
       } else if (maxsimExports || wasmExports?.maxsim_f32) {
-        console.log('[MaxSim] Tier 2: WASM SIMD f32x4');
+        console.error('[MaxSim] Tier 2: WASM SIMD f32x4');
       } else {
-        console.log('[MaxSim] Tier 3: JS fallback');
+        console.error('[MaxSim] Tier 3: JS fallback');
       }
 
       return true;

package/core/infrastructure/sparse-gram-delta-reader.js

@@ -0,0 +1,76 @@
+/**
+ * Read-only sparse-gram delta helpers for query-time overlay resolution.
+ *
+ * The reconcile writer lives under incremental-indexing. Search only needs to
+ * resolve the latest append-only delta record per file, so that read contract
+ * belongs in infrastructure instead of importing the writer bounded context.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SPARSE_DELTA_DIR_SUFFIX = '.deltas';
+export const SPARSE_DELTA_FILE_EXT = '.ssgrmdelta';
+
+function deltaDirFor(baseArtifactPath) {
+  return baseArtifactPath + SPARSE_DELTA_DIR_SUFFIX;
+}
+
+function parseDeltaSegment(baseArtifactPath, segmentPath, maxEpoch) {
+  if (typeof segmentPath !== 'string' || !segmentPath.endsWith(SPARSE_DELTA_FILE_EXT)) return null;
+  const deltaRoot = path.resolve(deltaDirFor(baseArtifactPath));
+  const resolved = path.isAbsolute(segmentPath)
+    ? segmentPath
+    : path.join(path.dirname(baseArtifactPath), segmentPath);
+  const normalized = path.resolve(resolved);
+  if (normalized !== deltaRoot && !normalized.startsWith(deltaRoot + path.sep)) return null;
+  const match = path.basename(normalized).match(/^(\d+)-(\d+)\.ssgrmdelta$/);
+  if (!match) return null;
+  const epoch = Number(match[1]);
+  if (epoch > maxEpoch) return null;
+  if (!fs.existsSync(normalized)) return null;
+  return {
+    path: normalized,
+    epoch,
+    seq: Number(match[2]),
+  };
+}
+
+export function listSparseGramDeltaSegments(baseArtifactPath, opts = {}) {
+  const maxEpoch = Number.isInteger(opts.maxEpoch) ? opts.maxEpoch : Infinity;
+  if (Array.isArray(opts.segments)) {
+    return opts.segments
+      .map((segmentPath) => parseDeltaSegment(baseArtifactPath, segmentPath, maxEpoch))
+      .filter(Boolean)
+      .sort((a, b) => (a.epoch - b.epoch) || (a.seq - b.seq));
+  }
+
+  const dir = deltaDirFor(baseArtifactPath);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const segment = parseDeltaSegment(baseArtifactPath, path.join(dir, name), maxEpoch);
+    if (segment) out.push(segment);
+  }
+  return out.sort((a, b) => (a.epoch - b.epoch) || (a.seq - b.seq));
+}
+
+export function resolveLatestSparseGramDeltaRecords(baseArtifactPath, opts = {}) {
+  const latest = new Map();
+  for (const seg of listSparseGramDeltaSegments(baseArtifactPath, opts)) {
+    const raw = fs.readFileSync(seg.path, 'utf-8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let record;
+      try {
+        record = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      if (!record.fileId) continue;
+      latest.set(record.fileId, { record, segmentPath: seg.path, epoch: seg.epoch });
+    }
+  }
+  return latest;
+}

package/core/infrastructure/structural-alias-resolver.js

@@ -0,0 +1,122 @@
+import path from 'path';
+
+const ACTIVE = 'stale_since IS NULL';
+
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function rowToEntity(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    type: row.type,
+    filePath: row.file_path,
+    startLine: row.start_line,
+    endLine: row.end_line,
+    signature: row.signature || '',
+    summary: row.summary || '',
+    parentClass: row.parent_class || null,
+    package: row.package || null,
+  };
+}
+
+function moduleStem(filePath) {
+  return path.basename(String(filePath || ''), path.extname(String(filePath || '')));
+}
+
+function moduleLooksRelated(moduleName, stem) {
+  const normalized = String(moduleName || '').replace(/\\/g, '/').replace(/\.[cm]?[jt]sx?$/, '');
+  return normalized === stem || normalized.endsWith(`/${stem}`);
+}
+
+function parseSpecifiers(specs, targetName, aliases) {
+  for (const rawPart of specs.split(',')) {
+    const part = rawPart.trim();
+    const colon = part.match(new RegExp(`^${escapeRegExp(targetName)}\\s*:\\s*([A-Za-z_$][\\w$]*)$`));
+    const asAlias = part.match(new RegExp(`^${escapeRegExp(targetName)}\\s+as\\s+([A-Za-z_$][\\w$]*)$`));
+    if (colon) aliases.add(colon[1]);
+    else if (asAlias) aliases.add(asAlias[1]);
+    else if (part === targetName) aliases.add(targetName);
+  }
+}
+
+function extractAliases(text, target) {
+  const aliases = new Set();
+  const stem = moduleStem(target.filePath);
+  for (const line of String(text || '').split('\n')) {
+    if (!line.includes(target.name) || !line.includes(stem)) continue;
+    const cjs = line.match(/\{([^}]+)\}\s*=\s*require\(['"]([^'"]+)['"]\)/);
+    if (cjs && moduleLooksRelated(cjs[2], stem)) parseSpecifiers(cjs[1], target.name, aliases);
+    const esm = line.match(/import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/);
+    if (esm && moduleLooksRelated(esm[2], stem)) parseSpecifiers(esm[1], target.name, aliases);
+    const prop = line.match(new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*require\\(['"]([^'"]+)['"]\\)\\.${escapeRegExp(target.name)}\\b`));
+    if (prop && moduleLooksRelated(prop[2], stem)) aliases.add(prop[1]);
+  }
+  return [...aliases];
+}
+
+function lineOfIndex(text, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) line++;
+  return line;
+}
+
+export function findAliasCallers({
+  db,
+  target,
+  readFileRange,
+  limit = 40,
+  entityVisibilitySql: entitySql = ACTIVE,
+  entityVisibilityParams: entityParams = [],
+  mapEntity = rowToEntity,
+}) {
+  if (!db || !target?.filePath || !target?.name) return [];
+  const files = db.prepare(`
+    SELECT DISTINCT file_path
+    FROM entities
+    WHERE ${entitySql} AND file_path IS NOT NULL
+    ORDER BY CASE WHEN file_path LIKE '%/test/%' OR file_path LIKE 'test/%' OR file_path LIKE 'tests/%' THEN 1 ELSE 0 END, file_path
+    LIMIT 1000
+  `).all(...entityParams);
+  const entityAtLine = db.prepare(`
+    SELECT id, name, type, file_path, start_line, end_line, signature, summary, parent_class, package
+    FROM entities
+    WHERE ${entitySql} AND file_path = ? AND start_line <= ? AND end_line >= ?
+    ORDER BY (end_line - start_line) ASC
+    LIMIT 1
+  `);
+  const out = [];
+  const seen = new Set();
+  for (const { file_path: filePath } of files) {
+    if (filePath === target.filePath) continue;
+    const text = readFileRange(filePath, 1, 20000);
+    const aliases = extractAliases(text, target);
+    const patterns = aliases.map(alias => ({
+      targetName: alias,
+      re: new RegExp(`(?<![\\w$])${escapeRegExp(alias)}\\s*\\(`, 'g'),
+    }));
+    if (/\.rs$/.test(target.filePath)) {
+      patterns.push({
+        targetName: `::${target.name}`,
+        re: new RegExp(`\\b[A-Za-z_][\\w]*::${escapeRegExp(target.name)}\\s*\\(`, 'g'),
+      });
+    }
+    if (!patterns.length) continue;
+    for (const pattern of patterns) {
+      const re = pattern.re;
+      for (const match of text.matchAll(re)) {
+        const line = lineOfIndex(text, match.index || 0);
+        const entity = entityAtLine.get(...entityParams, filePath, line, line);
+        if (!entity || entity.id === target.id) continue;
+        const targetName = match[0].replace(/\s*\($/, '') || pattern.targetName;
+        const key = `${entity.id}:${line}:${targetName}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push({ ...mapEntity(entity), relationship: 'calls', contextLine: line, targetName, weight: 0.82 });
+        if (out.length >= limit) return out;
+      }
+    }
+  }
+  return out;
+}

package/core/infrastructure/structural-candidate-ranker.js

@@ -0,0 +1,34 @@
+function tokens(text) {
+  return [...new Set(String(text || '').toLowerCase().match(/[a-z_][a-z0-9_]{2,}/g) || [])];
+}
+
+function wantsImplementation(hintTokens) {
+  if (hintTokens.includes('wrapper')) return false;
+  return hintTokens.some(t => ['callee', 'callees', 'downstream', 'helper', 'helpers', 'conversion', 'implementation'].includes(t));
+}
+
+function delegatesSameName(candidate, code) {
+  const name = String(candidate.name || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\.\\s*${name}\\s*\\(`).test(code);
+}
+
+function scoreCandidate(candidate, hintTokens, readFileRange) {
+  if (!hintTokens.length) return 0;
+  const code = readFileRange(candidate.filePath, candidate.startLine, candidate.endLine) || '';
+  const hay = `${candidate.name} ${candidate.type} ${candidate.filePath} ${candidate.signature} ${candidate.summary} ${code}`.toLowerCase();
+  let hits = 0;
+  for (const tok of hintTokens) if (hay.includes(tok)) hits++;
+  let score = hits / hintTokens.length;
+  if (wantsImplementation(hintTokens) && delegatesSameName(candidate, code)) score -= 0.35;
+  return score;
+}
+
+export function rankStructuralCandidates(candidates, { queryHint, readFileRange }) {
+  const hintTokens = tokens(queryHint);
+  if (!hintTokens.length || candidates.length < 2) return candidates;
+  return candidates.map((candidate, index) => ({
+    candidate,
+    index,
+    score: scoreCandidate(candidate, hintTokens, readFileRange),
+  })).sort((a, b) => (b.score - a.score) || (a.index - b.index)).map(x => x.candidate);
+}