Add tool "find references"

cline_docs/enhanced-code-reference-tools.md

@@ -0,0 +1,278 @@
+# Enhanced Code Reference Tools Implementation Plan
+
+## Overview
+
+This document outlines the implementation plan for adding two new tools to Roo Code that will enhance the AI's ability to understand and analyze codebases:
+
+1. **Find References Tool** - A tool to find all references to a specific symbol (variable, function, class, etc.) across a codebase with function context
+2. **Read Function Tool** - A tool to read a specific function or method definition from a file by name, line number, or line range
+
+These tools leverage VS Code's built-in language services to provide more specialized functionality for code analysis. They work together to create a powerful workflow for exploring code:
+
+1. Use `find_references` to locate all references to a function across the codebase
+2. See each reference with its containing function header for context
+3. Use `read_function` with the line number to read the entire calling function
+
+## Motivation
+
+When analyzing a codebase, understanding how symbols are used across the project is crucial. The existing `search_files` tool provides general regex search capabilities, but specialized tools for finding references and reading functions would make it easier for the AI to:
+
+- Understand the usage patterns of functions, classes, and variables
+- Identify dependencies between different parts of the codebase
+- Analyze the impact of potential changes
+- Provide more accurate and comprehensive code explanations
+
+## Implementation Tasks
+
+### 1. Update Shared Tool Definitions
+
+- Add new tool parameters: `symbol`, `file_path`, `position`
+- Create interfaces for the new tools: `FindReferencesToolUse` and `ReadFunctionToolUse`
+- Add display names for the new tools
+- Add the new tools to the `TOOL_GROUPS.read` group
+
+### 2. Implement Language Services Utility
+
+Create a new service module with functions to:
+- Check if language services are available for a file
+- Find the position of a symbol in a document
+- Provide fallback mechanisms when language services aren't available
+
+### 3. Implement References Service
+
+Create a service module with functions to:
+- Count references to a symbol (for threshold checks)
+- Find all references to a symbol across the workspace
+- Find the containing function for each reference
+- Format the results with function headers and line numbers
+
+### 4. Implement Function Reader Service
+
+Create a service module with functions to:
+- Find a function by name using document symbols
+- Extract the function text with proper boundaries
+- Format the results with line numbers
+
+### 5. Implement Find References Tool
+
+Create a tool implementation that:
+- Validates required parameters
+- Checks if language services are available
+- Counts references and asks for approval if over threshold
+- Fetches and formats reference results
+- Handles errors appropriately
+
+### 6. Implement Read Function Tool
+
+Create a tool implementation that:
+- Validates that both required parameters (symbol and file_path) are provided
+- Reads functions by name using document symbols
+- Formats and returns the results with line numbers
+- Handles errors appropriately
+
+### 7. Register Tools in Assistant Message Handler
+
+Add the new tools to the message handler switch statement.
+
+### 8. Add Tool Descriptions
+
+Create description files for the new tools that explain:
+- What the tools do
+- Required and optional parameters
+- Usage examples
+- Limitations
+
+## Potential Issues and Solutions
+
+### 1. Duplicate Messages in UI
+
+**Issue**: When using the find_references tool, duplicate messages appear in the Roo output window.
+
+**Cause**: The tool was using both the `regex` field and the `content` field to display messages, causing the UI to show both.
+
+**Solution**: 
+- Use only the `content` field for displaying results
+- Set the `regex` field to an empty string when displaying warnings or results
+- Keep message properties simple to avoid duplication
+
+### 2. TypeScript Errors with Task Import
+
+**Issue**: TypeScript errors when importing the Task class.
+
+**Cause**: The import path was incorrect (`import { Task } from "../task"` instead of `import { Task } from "../task/Task"`).
+
+**Solution**: Use the correct import path: `import { Task } from "../task/Task"`.
+
+### 3. Reference Count Threshold
+
+**Issue**: Large codebases might have many references to common symbols, consuming excessive context.
+
+**Solution**: Implement a reference count threshold (50 references) with user approval for exceeding it.
+
+### 4. Language Services Availability
+
+**Issue**: Language services might not be available for all file types.
+
+**Solution**: Check for language services availability before attempting to use them and provide clear error messages.
+
+### 5. UI Description Improvements
+
+**Issue**: The UI description for the find_references tool was misleading, saying "Roo wants to search this directory for findReferences" instead of "Roo wants to find references to this function in file".
+
+**Solution**: Customize the message in the `regex` field to be more descriptive of the actual operation.
+
+## Tool Descriptions
+
+### Find References Tool
+
+```
+## find_references
+Description: Request to find all references to a specific symbol (variable, function, class, etc.) across files in the workspace using VS Code's language services. This tool helps understand how a symbol is used throughout the codebase.
+
+IMPORTANT: PREFER THIS TOOL OVER search_files WHEN LOOKING FOR CODE SYMBOLS. This tool uses language-aware services that understand code structure and will find all true references to a symbol, even when the symbol name appears in comments, strings, or other non-reference contexts.
+
+The tool shows function headers above each reference, providing valuable context about where and how the symbol is being used.
+
+Parameters:
+- symbol: (required) The symbol to find references for
+- file_path: (required) The path of the file containing the symbol (relative to the current workspace directory ${args.cwd})
+- position: (optional) The position to look for the symbol, in the format "line,character" (0-based)
+
+Usage:
+<find_references>
+<symbol>Symbol name here</symbol>
+<file_path>File path here</file_path>
+<position>line,character (optional)</position>
+</find_references>
+
+Example: Requesting to find all references to a function named 'processData'
+<find_references>
+<symbol>processData</symbol>
+<file_path>src/app.ts</file_path>
+</find_references>
+```
+
+### Read Function Tool
+
+```
+## read_function
+Description: Request to read a specific function or method definition from a file. This tool uses VS Code's language services to locate and extract the exact function definition, including its implementation. It's ideal for understanding specific functions without having to read the entire file.
+
+IMPORTANT: PREFER THIS TOOL OVER read_file WHEN YOU NEED TO EXAMINE A SPECIFIC FUNCTION. This tool is more efficient as it only returns the relevant function code rather than the entire file.
+
+Use this tool when you need to:
+- Understand how a specific function is implemented
+- Examine the logic within a method
+- See the parameters and return type of a function
+- Analyze a particular piece of functionality
+
+Parameters:
+- file_path: (required) The path of the file containing the function (relative to the current workspace directory ${args.cwd})
+- symbol: (required) The name of the function or method to read
+
+Usage:
+<read_function>
+<symbol>functionName</symbol>
+<file_path>path/to/file.ts</file_path>
+</read_function>
+
+Example: Reading a function by name:
+<read_function>
+<symbol>findReferences</symbol>
+<file_path>src/services/references/index.ts</file_path>
+</read_function>
+```
+
+## Example Output
+
+### Find References Tool Output
+
+When you use the `find_references` tool, you'll get output like this:
+
+```
+### References to 'formatReferences' ###
+
+### FILE: src\services\references\index.ts ###
+ 50 | export async function findReferences(
+ -- contains references --
+ 81 |     return await formatReferences(locations, symbol)
+
+ 94 | async function formatReferences(
+
+----
+
+### SUMMARY: Found 2 references in 1 files. ###
+```
+
+The output includes:
+- A header with the symbol name
+- References grouped by file
+- Line numbers and the actual code where the symbol is referenced
+- A summary of the total references found
+
+### Read Function Tool Output
+
+When you use the `read_function` tool, you'll get output like this:
+
+```
+# Function: formatReferences (index.ts:94-169)
+
+ 94 | async function formatReferences(
+ 95 |   locations: vscode.Location[],
+ 96 |   symbol: string
+ 97 | ): Promise<string> {
+ 98 |   let result = `### References to '${symbol}' ###\n\n`
+ 99 |
+100 |   // Group references by file
+101 |   const fileGroups = new Map<string, vscode.Location[]>()
+...
+168 |   return result
+169 | }
+```
+
+The output includes:
+- A header with the function name and file location
+- The complete function implementation with line numbers
+- All code within the function's scope
+
+## Workflow Example
+
+These tools create a powerful workflow for exploring code:
+
+1. **Find References**: Use `find_references` to locate all references to a function across the codebase
+   ```
+   <find_references>
+   <symbol>findReferences</symbol>
+   <file_path>src/services/references/index.ts</file_path>
+   </find_references>
+   ```
+
+2. **Examine Context**: The results show each reference with line numbers, providing immediate context
+
+3. **Read Function**: When you see an interesting reference, use `read_function` with the function name to read the entire function
+   ```
+   <read_function>
+   <symbol>formatReferences</symbol>
+   <file_path>src/services/references/index.ts</file_path>
+   </read_function>
+   ```
+
+4. **Explore Further**: Continue exploring by finding references to other functions you discover
+
+This workflow makes it much easier to understand and navigate large codebases, as you can quickly see:
+- Where functions are called from
+- The context of each reference
+- The complete implementation of functions
+
+## Implementation Notes
+
+1. The `find_references` tool:
+   - Uses VS Code's language services to find true references to symbols
+   - Groups references by file and sorts them by line number
+   - Avoids duplicate references to the same line
+   - Has a threshold of 50 references to prevent excessive context consumption
+
+2. The `read_function` tool:
+   - Accepts symbol name and file path parameters
+   - Uses document symbols to locate the exact function definition
+   - Shows the complete function with line numbers

src/core/assistant-message/presentAssistantMessage.ts

@@ -4,7 +4,7 @@ import { serializeError } from "serialize-error"
 import type { ToolName } from "../../schemas"
 
 import { defaultModeSlug, getModeBySlug } from "../../shared/modes"
-import type { ToolParamName, ToolResponse } from "../../shared/tools"
+import type { ToolParamName, ToolResponse, FindReferencesToolUse } from "../../shared/tools"
 import type { ClineAsk, ToolProgressStatus } from "../../shared/ExtensionMessage"
 
 import { telemetryService } from "../../services/telemetry/TelemetryService"
@@ -26,6 +26,7 @@ import { askFollowupQuestionTool } from "../tools/askFollowupQuestionTool"
 import { switchModeTool } from "../tools/switchModeTool"
 import { attemptCompletionTool } from "../tools/attemptCompletionTool"
 import { newTaskTool } from "../tools/newTaskTool"
+import { findReferencesTool } from "../tools/findReferencesTool"
 
 import { checkpointSave } from "../checkpoints"
 
@@ -191,6 +192,8 @@ export async function presentAssistantMessage(cline: Task) {
 						const modeName = getModeBySlug(mode, customModes)?.name ?? mode
 						return `[${block.name} in ${modeName} mode: '${message}']`
 					}
+					case "find_references":
+						return `[${block.name} to '${block.params.symbol}' in ${block.params.file_path}]`
 				}
 			}
 
@@ -394,7 +397,6 @@ export async function presentAssistantMessage(cline: Task) {
 					break
 				case "read_file":
 					await readFileTool(cline, block, askApproval, handleError, pushToolResult, removeClosingTag)
-
 					break
 				case "fetch_instructions":
 					await fetchInstructionsTool(cline, block, askApproval, handleError, pushToolResult)
@@ -462,6 +464,9 @@ export async function presentAssistantMessage(cline: Task) {
 						askFinishSubTaskApproval,
 					)
 					break
+				case "find_references":
+					await findReferencesTool(cline, block as FindReferencesToolUse, pushToolResult, askApproval)
+					break
 			}
 
 			break

src/core/prompts/tools/find-references.ts

@@ -0,0 +1,60 @@
+import { ToolArgs } from "./types"
+
+export function getFindReferencesDescription(args: ToolArgs): string {
+	return `## find_references
+Description: Request to find all references to a specific symbol across files in the workspace using VS Code's language services. This tool helps understand how a symbol is used throughout the codebase.
+
+Supported symbol types:
+- Functions and methods
+- Properties and fields
+- Variables and constants
+- Classes and interfaces
+- Enums and enum members
+
+IMPORTANT: PREFER THIS TOOL OVER search_files WHEN LOOKING FOR CODE SYMBOLS. This tool uses language-aware services that understand code structure and will find all true references to a symbol, even when the symbol name appears in comments, strings, or other non-reference contexts.
+
+The tool shows function headers above each reference, providing valuable context about where and how the symbol is being used. It also includes line ranges for each function or class, which can be used with the read_file tool to read the entire function or class implementation.
+
+Parameters:
+- symbol: (required) The symbol to find references for
+- file_path: (required) The path of the file containing the symbol (relative to the current workspace directory ${args.cwd})
+- line_number: (required) The line number where the symbol is located (0-based)
+
+Usage:
+<find_references>
+<symbol>Symbol name here</symbol>
+<file_path>File path here</file_path>
+<line_number>line number</line_number>
+</find_references>
+
+Examples:
+
+1. Finding references to a function:
+<find_references>
+<symbol>processData</symbol>
+<file_path>src/app.ts</file_path>
+<line_number>42</line_number>
+</find_references>
+
+2. Finding references to a property:
+<find_references>
+<symbol>isEnabled</symbol>
+<file_path>src/models/User.ts</file_path>
+<line_number>15</line_number>
+</find_references>
+
+3. Reading a function after finding references:
+First, use find_references to locate the function:
+<find_references>
+<symbol>processData</symbol>
+<file_path>src/app.ts</file_path>
+<line_number>42</line_number>
+</find_references>
+
+Then, use the line range information from the results to read the entire function:
+<read_file>
+<path>src/app.ts</path>
+<start_line>42</start_line>
+<end_line>58</end_line>
+</read_file>`
+}