feat(refs): Tree-sitter identifier-aware symbol references

[PatrickSys]

Improve refs --symbol precision by using Tree-sitter identifier occurrences when the file exists and a curated grammar is available; fall back to legacy chunk-regex otherwise. Adds coverage for excluding comment/string-only matches. No docs changes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2aa0831510

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

This PR enhances get_symbol_references precision by using Tree-sitter AST analysis to identify genuine code identifiers, automatically filtering out matches in comments and strings. When Tree-sitter is available and the file exists, it performs an identifier-aware scan; otherwise, it gracefully falls back to the legacy chunk-regex approach.

Major changes:

• Refactored findSymbolReferences to group chunks by file and prefer reading actual file content over chunk content for accuracy
• Added findIdentifierOccurrences in tree-sitter utils that traverses the AST and excludes non-code contexts (comments, strings, template strings, regex, jsx_text)
• Implemented proper deduplication, resource cleanup (tree.delete in finally), and error handling with fallback
• Added comprehensive test coverage validating comment/string exclusion

Code quality:

• Maintains backward compatibility and project constraints (zero-infra, language-agnostic, privacy-first)
• Proper type safety with minimal use of type assertions
• Good separation of concerns between core logic and tree-sitter utilities
• One minor style issue: test file uses as any to access private members

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Score reflects excellent code quality with proper error handling, graceful fallback mechanisms, good test coverage, and no breaking changes. The implementation is well-structured, maintains project constraints, and includes proper resource cleanup. Only one minor style issue found regarding any usage in tests.
• No files require special attention

Important Files Changed

Filename	Overview
src/core/symbol-references.ts	Refactored to use Tree-sitter for identifier matching when available, with proper fallback to regex. Clean implementation with good error handling.
src/utils/tree-sitter.ts	Added findIdentifierOccurrences function with proper AST traversal and comment/string filtering. Includes proper resource cleanup and error handling.
tests/get-symbol-references.test.ts	Added comprehensive test validating that comments and strings are excluded from symbol references when Tree-sitter is available.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start([findSymbolReferences called]) --> LoadIndex[Load keyword index]
    LoadIndex --> Prefilter[Prefilter chunks with regex]
    Prefilter --> GroupFiles[Group chunks by file path]
    GroupFiles --> IterateFiles{For each file}
    
    IterateFiles --> CheckFile{File exists<br/>on disk?}
    CheckFile -->|No| FallbackRegex[Use chunk-regex fallback]
    CheckFile -->|Yes| ReadFile[Read file content]
    
    ReadFile --> DetectLang[Detect language]
    DetectLang --> CheckTreeSitter{Tree-sitter<br/>supported?}
    
    CheckTreeSitter -->|No| FallbackRegex
    CheckTreeSitter -->|Yes| ParseAST[Parse with Tree-sitter]
    
    ParseAST --> CheckError{Parse<br/>error?}
    CheckError -->|Yes| FallbackRegex
    CheckError -->|No| TraverseAST[Traverse AST for identifiers]
    
    TraverseAST --> FilterContext[Filter out comments/strings]
    FilterContext --> Dedupe[Deduplicate occurrences]
    Dedupe --> CountMatches[Add to usageCount]
    CountMatches --> NextFile[Continue to next file]
    
    FallbackRegex --> RegexScan[Regex scan in chunks]
    RegexScan --> CountRegex[Add matches to usageCount]
    CountRegex --> NextFile
    
    NextFile --> IterateFiles
    IterateFiles -->|Done| Return[Return results with usages]
    Return --> End([End])

Loading

_{Last reviewed commit: 2aa0831}

[greptile-apps]

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Violates AGENTS.md guideline: "Avoid using any Type AT ALL COSTS." Consider using a typed interface or unknown with proper type guards to access the handler.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[PatrickSys]

Addressed review feedback:\n- Security: avoid reading index-provided paths outside CODEBASE_ROOT. We now only read files when the resolved path stays under root; otherwise we fall back to chunk-regex. (commit 1735e3c)\n- Tests: removed newly-introduced �s any access by adding a typed tools/call handler helper. (commit 1735e3c)