Fuzzy Symbol Search
Relevant source files
The following files were used as context for generating this wiki page:
Fuzzy Symbol Search is a core feature of the Arbor ecosystem designed to provide typo tolerance and relevant suggestions when developers query code entities. Introduced in version 1.5.0, this system utilizes Jaro-Winkler distance matching to resolve symbol names even when the input is imprecise. It integrates across the CLI, GUI, and MCP bridge to improve user experience in impact analysis and refactoring workflows.
The primary objective is to assist users in locating functions, classes, and methods within a semantic dependency graph, ensuring that "structural certainty" is maintained even if the initial search query contains minor errors.
Sources: README.md:14-16, README.md:31-35, CHANGELOG.md:8-9
Search Logic and Scoring
The fuzzy search mechanism operates by calculating a relevance score for potential matches within the ArborGraph. This scoring system prioritizes exact matches and structural relevance while falling back to fuzzy string similarity for typo correction.
Relevance Weighting
Relevance is calculated based on the following hierarchy:
- Exact Name (100): The symbol name matches the query exactly (case-insensitive).
- Exact Suffix (80): The query matches the end of a fully qualified name (e.g., matching
authinmodule::auth). - Starts With (60): The symbol name begins with the query string.
- Contains (40): The symbol name contains the query string anywhere within it.
- Fuzzy (30): Jaro-Winkler similarity is greater than 0.75.
Sources: crates/arbor-cli/src/commands.rs:729-762
The Jaro-Winkler Algorithm
When structural matches fail, the system employs the Jaro-Winkler similarity algorithm. This is particularly effective for correcting typos (e.g., matching autth to auth). Only matches with a similarity score above 0.75 are considered relevant.
Sources: README.md:15, crates/arbor-cli/src/commands.rs:756-760
Architecture and Component Interaction
The fuzzy search functionality is distributed across the codebase, with the CLI serving as the primary driver for suggestion logic.
The diagram above illustrates the fallback logic used when a direct symbol lookup fails.
Component Roles
| Component | Responsibility | Relevant Files |
|---|---|---|
| CLI Command Layer | Implements the suggest_similar_symbols function and manages CLI output. | crates/arbor-cli/src/commands.rs |
| ArborGraph | Provides access to all nodes and their upstream impact counts for ranking. | crates/arbor-graph/src/lib.rs |
| GUI (ArborApp) | Provides symbol search and history tracking for interactive analysis. | crates/arbor-gui/src/app.rs |
| MCP Bridge | Resolves node IDs or names provided by AI agents to support graph tools. | crates/arbor-mcp/src/lib.rs |
Sources: crates/arbor-cli/src/commands.rs:722-800, crates/arbor-gui/src/app.rs:77-105, crates/arbor-mcp/src/lib.rs:188-196
Refactoring Workflow Integration
Fuzzy search is tightly integrated into the arbor refactor command. When a developer attempts to analyze the impact of a symbol that does not exist exactly as typed, the system triggers the suggestion engine.
Sequence of a Fuzzy Refactor Request
This sequence ensures that even failed lookups provide actionable intelligence to the developer.
Sources: crates/arbor-cli/src/commands.rs:624-633, crates/arbor-cli/src/commands.rs:764-770
Implementation Details
The CLI implementation uses the strsim crate for Jaro-Winkler calculations and combines relevance scores with node metadata (like caller counts) to rank suggestions.
// crates/arbor-cli/src/commands.rs:722-725
fn suggest_similar_symbols(graph: &arbor_graph::ArborGraph, target: &str) -> Result<()> {
println!();
println!("{} Couldn't find \"{}\"", "š".yellow(), target.cyan());
// ...
GUI Search History
The GUI (ArborApp) complements fuzzy search by maintaining a search_history vector, allowing users to quickly return to previously analyzed symbols without re-typing.
Sources: crates/arbor-gui/src/app.rs:60, crates/arbor-gui/src/app.rs:141-147
Conclusion
Fuzzy Symbol Search elevates Arbor from a simple static analysis tool to an intelligent code navigation engine. By leveraging string similarity and graph-based impact metadata, it ensures that developers can find and analyze code symbols efficiently, even in large, complex codebases where exact names may be difficult to remember.