Context+

Instructions

Implementation Reference

• src/tools/semantic-identifiers.ts:347-423 (handler)

  The main handler function for the `semantic_identifier_search` tool. It performs identifier indexing, calculates semantic and keyword scores, and ranks call sites.

  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,
      );
  
      if (calls.sites.length === 0) {
        lines.push("   Calls: none found");
        lines.push("");
        continue;
      }
  
      lines.push(`   Calls (${calls.sites.length}/${calls.total}):`);
      for (let j = 0; j < calls.sites.length; j++) {
        const site = calls.sites[j];
        lines.push(`     ${j + 1}. ${site.file}:L${site.line} (${Math.round(site.score * 1000) / 10}%) ${site.context}`);
      }
      lines.push("");
    }
  
    await saveEmbeddingCache(options.rootDir, cache, IDENTIFIER_CACHE_FILE);
    return lines.join("\n");
  }

• src/tools/semantic-identifiers.ts:16-24 (schema)

  Type definition for the input options of the `semantic_identifier_search` tool.

  export interface SemanticIdentifierSearchOptions {
    rootDir: string;
    query: string;
    topK?: number;
    topCallsPerIdentifier?: number;
    includeKinds?: string[];
    semanticWeight?: number;
    keywordWeight?: number;
  }