search_files

The search_files tool enables VJSP to perform regex-based searches across multiple files within a project, facilitating the identification of specific code patterns, text, and other content throughout the entire codebase, and returns search results with contextual information.

Parameter Specifications

This tool accepts the following parameters:

• path (required): The directory path to search, relative to the current working directory
• regex (required): The regex pattern for matching (following Rust regex syntax specifications)
• file_pattern (optional): Wildcard pattern for file filtering (e.g., *.ts matches all TypeScript files)

Feature Overview

This tool performs comprehensive searches across files in the specified directory using regular expressions, displaying surrounding contextual context for each match. It is equivalent to a high-performance "find in files" functionality capable of operating across the entire project structure.

Use Cases

• When locating all invocation sites of specific functions or variables
• During code refactoring, when analyzing code usage patterns
• When finding all instances of a specific code pattern
• When filtering files by rules and searching for specified text across multiple files

Core Features

• Powered by the high-performance Ripgrep engine, enabling comprehensive multi-file searches in a single operation
• Displays context for each match (default: 1 line before and after)
• Supports wildcard pattern filtering by file type (e.g., search only TypeScript files)
• Returns line numbers for matches, enabling quick location
• Supports powerful regular expressions for precise searches
• Automatically limits output to 300 results, with a prompt when exceeded
• Truncates lines exceeding 500 characters and adds "[truncated...]" marker
• Intelligently merges adjacent matches into single display blocks for improved readability

Limitations

• Works best with plain text files; ineffective for binary files such as images
• Search performance may degrade with extremely large codebases
• Follows Rust regex syntax, which has subtle differences from other regex implementations
• Does not support searching within compressed or archived files
• Context display lines are fixed at default values (1 line before and after)
• Due to result merging rules, the actual number of context lines displayed may vary when match results are adjacent

Execution Flow

After invoking the search_files tool, the following process is executed:

1. Parameter Validation: Validates the required parameters path and regex

2. Path Resolution: Resolves relative paths to absolute paths

3. Search Execution:

   • Executes high-performance text search based on Ripgrep (rg) engine
   • Filters files according to rules if file_pattern is specified
   • Collects all matches with context

4. Result Formatting:

   • Formats results with file paths, line numbers, and context
   • Displays 1 line before and after context for each match
   • Optimizes result structure for improved readability
   • Limits result count to 300, with a prompt when exceeded
   • Truncates lines longer than 500 characters
   • Merges adjacent matches into continuous display blocks

Search Result Format

Search results include the following information:

• Relative path of each matched file (prefixed with #)
• Context lines before and after each match (default: 1 line each)
• Line numbers zero-padded to 3 digits, followed by | and line content
• Separator line (----) after each match block

Example output:

# rel/path/to/app.ts
 11 |   // Data processing logic
 12 |   // TODO: Implement exception handling mechanism
 13 |   return processedData;
----

# Total of 300+ matches found, displaying first 300 results only. For precise searches, please optimize your matching criteria.

When match results are adjacent, they will be merged into a single display block rather than shown separately:

# rel/path/to/auth.ts
 13 | // Business logic code
 14 | // TODO: Add parameter validation
 15 | function validateUser(credentials) {
 16 |   // TODO: Implement rate limiting strategy
 17 |   return checkDatabase(credentials);
----

Practical Application Examples

• Upon receiving a code refactoring request, VJSP first searches for all invocation sites of the target function to ensure the completeness of the refactoring operation
• When debugging program issues, VJSP searches for similar code patterns to locate related problems across the entire codebase
• When addressing technical debt, VJSP searches for all TODO comments in the project to identify optimization points
• When analyzing project dependencies, VJSP searches for all import statements of a specific module to clarify dependency relationships

Tool Usage Examples

Search for TODO comments in all JavaScript files:

<search_files>
<path>src</path>
<regex>TODO|FIXME</regex>
<file_pattern>*.js</file_pattern>
</search_files>

Find all definitions and invocation sites of a specific function:

<search_files>
<path>.</path>
<regex>function\s+calculateTotal</regex>
<file_pattern>*.{js,ts}</file_pattern>
</search_files>

Search for specific import patterns throughout the entire project:

<search_files>
<path>.</path>
<regex>import\s+.*\s+from\s+['"]@components/</regex>
</search_files>