Function semanticIdentifierSearch

src/tools/semantic-identifiers.ts:347–423

(options: SemanticIdentifierSearchOptions)

}

export async function semanticIdentifierSearch(options: SemanticIdentifierSearchOptions): Promise<string> {
  const topK = Math.max(1, Math.floor(options.topK ?? 5));
  const topCalls = Math.max(1, Math.floor(options.topCallsPerIdentifier ?? 10));
  const semanticWeight = normalizeWeight(options.semanticWeight, 0.78);
  const keywordWeight = normalizeWeight(options.keywordWeight, 0.22);
  const includeKinds = normalizeKinds(options.includeKinds);

  const index = await buildIdentifierIndex(options.rootDir);
  if (index.docs.length === 0) {
    return "No supported identifiers found for semantic identifier search.";
  }

  const [queryVec] = await fetchEmbedding(options.query);
  const queryTerms = new Set(splitTerms(options.query));

  const scored: RankedIdentifier[] = [];
  for (let i = 0; i < index.docs.length; i++) {
    const doc = index.docs[i];
    if (includeKinds && !includeKinds.has(doc.kind.toLowerCase())) continue;

    const semanticScore = Math.max(cosine(queryVec, index.vectors[i]), 0);
    const keywordScore = getKeywordCoverage(queryTerms, `${doc.name} ${doc.signature} ${doc.path} ${doc.header}`);
    const totalWeight = semanticWeight + keywordWeight;
    const score = totalWeight > 0
      ? clamp01((semanticWeight * semanticScore + keywordWeight * keywordScore) / totalWeight)
      : semanticScore;

    scored.push({ doc, semanticScore, keywordScore, score });
  }

  if (scored.length === 0) {
    return "No identifiers matched the requested kind filters.";
  }

  const top = scored.sort((a, b) => b.score - a.score).slice(0, topK);
  const cache = await loadEmbeddingCache(options.rootDir, IDENTIFIER_CACHE_FILE);

  const lines: string[] = [
    `Top ${top.length} identifier matches for: "${options.query}"`,
    "",
  ];

  for (let i = 0; i < top.length; i++) {
    const item = top[i];
    const range = formatLineRange(item.doc.line, item.doc.endLine);
    lines.push(`${i + 1}. ${item.doc.kind} ${item.doc.name} - ${item.doc.path} (${range})`);
    lines.push(`   Score: ${Math.round(item.score * 1000) / 10}% | Semantic: ${Math.round(item.semanticScore * 1000) / 10}% | Keyword: ${Math.round(item.keywordScore * 1000) / 10}%`);
    lines.push(`   Signature: ${item.doc.signature}`);
    if (item.doc.parentName) lines.push(`   Parent: ${item.doc.parentName}`);

    const calls = await rankCallSites(
      options.rootDir,
      cache,
      queryTerms,
      queryVec,
      item.doc,
      index.fileLines,
      topCalls,