Function findSymbolReferences

src/core/symbol-references.ts:104–255

(
  rootPath: string,
  symbol: string,
  limit = 10
)

}

export async function findSymbolReferences(
  rootPath: string,
  symbol: string,
  limit = 10
): Promise<SymbolReferencesResult> {
  const normalizedSymbol = symbol.trim();
  const normalizedLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 10;

  if (!normalizedSymbol) {
    return {
      status: 'error',
      message: 'Symbol is required'
    };
  }

  const indexPath = path.join(rootPath, CODEBASE_CONTEXT_DIRNAME, KEYWORD_INDEX_FILENAME);

  let chunksRaw: unknown;
  try {
    const content = await fs.readFile(indexPath, 'utf-8');
    chunksRaw = JSON.parse(content);
  } catch (error) {
    throw new IndexCorruptedError(
      `Keyword index missing or unreadable (rebuild required): ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }

  if (Array.isArray(chunksRaw)) {
    throw new IndexCorruptedError(
      'Legacy keyword index format detected (missing header). Rebuild required.'
    );
  }

  const chunks =
    chunksRaw !== null &&
    typeof chunksRaw === 'object' &&
    'chunks' in chunksRaw &&
    Array.isArray(chunksRaw.chunks)
      ? (chunksRaw.chunks as unknown[])
      : null;

  if (!chunks) {
    throw new IndexCorruptedError('Keyword index corrupted: expected { header, chunks }');
  }

  const usages: SymbolUsage[] = [];
  let usageCount = 0;

  const escapedSymbol = escapeRegex(normalizedSymbol);
  const prefilter = new RegExp(`\\b${escapedSymbol}\\b`);
  const matcher = new RegExp(`\\b${escapedSymbol}\\b`, 'g');

  // Prefilter candidate files from the keyword index. We do not trust chunk contents for
  // exact reference counting when Tree-sitter is available; chunks only guide which files to scan.
  const chunksByFile = new Map<
    string,