Impact Radius Simulator
Relevant source files
The following files were used as context for generating this wiki page:
The Impact Radius Simulator is a core analysis engine within Arbor designed to predict the "blast radius" of code changes. By performing bidirectional Breadth-First Search (BFS) traversals on the project's semantic dependency graph, the simulator identifies all code nodes—such as functions, classes, and modules—that are affected when a target symbol is modified. This allows developers to understand both upstream callers that might break and downstream dependencies that the target relies upon.
The simulator integrates across multiple Arbor interfaces, including the CLI for refactoring previews, the Model Context Protocol (MCP) for AI agent integration, and the native GUI for interactive visualization. It provides structured data including severity classifications (Direct, Transitive, or Distant) and explainable confidence levels based on the structural connectivity of the graph.
Sources: crates/arbor-graph/src/impact.rs:1-12, CHANGELOG.md:7-15, crates/arbor-cli/src/commands.rs:434-450
Core Architecture and Analysis Logic
The simulation logic resides primarily within the arbor-graph crate. It utilizes a petgraph based structure to perform traversals. The simulation is triggered via the analyze_impact function, which executes a bidirectional BFS to identify affected nodes in two specific directions: Upstream and Downstream.
Bidirectional BFS Traversal
The engine tracks the "hop distance" from the target node to every discovered node. This distance is used to categorize the impact severity and direction.
The diagram shows how the simulator traverses incoming edges to find upstream impact and outgoing edges to find downstream impact.
Sources: crates/arbor-graph/src/impact.rs:136-155, crates/arbor-graph/src/impact.rs:182-195
Severity and Direction Classification
The simulator classifies every AffectedNode based on its relationship to the target.
| Classification | Logic / Threshold | Description |
|---|---|---|
| Upstream | Incoming Edges | Nodes that depend on the target (e.g., callers). |
| Downstream | Outgoing Edges | Nodes the target depends on (e.g., callees). |
| Direct Impact | 0 or 1 Hops | Immediate neighbors that break if interfaces change. |
| Transitive Impact | 2 to 3 Hops | Indirectly connected nodes in the dependency chain. |
| Distant Impact | 4+ Hops | Nodes connected via long execution paths. |
Sources: crates/arbor-graph/src/impact.rs:19-45, crates/arbor-graph/src/impact.rs:58-71
Confidence Scoring and Node Roles
Arbor provides an explainable confidence score for each simulation, helping developers assess the reliability of the blast radius prediction. This scoring is based on the connectivity density and the size of the impact set.
Confidence Levels
- High: Node is well-integrated with clear, statically verifiable edges.
- Medium: Moderate connectivity or a large blast radius (>20 nodes) that might require modular refactoring.
- Low: Isolated nodes or very large blast radii (>50 nodes) where static analysis might miss dynamic dispatch or reflection.
Automatic Role Identification
The simulator identifies the architectural role of a node by analyzing its upstream/downstream ratios:
- Entry Point: No internal callers, but has downstream dependencies.
- Utility: Multiple upstream callers, but no outgoing dependencies.
- Core Logic: Significant connectivity in both directions.
- Adapter: Boundary node with high asymmetry (e.g., 1 caller but many dependencies).
Sources: crates/arbor-graph/src/confidence.rs:13-30, crates/arbor-graph/src/confidence.rs:43-85, crates/arbor-graph/src/confidence.rs:125-150
User Interface and API Integration
The Impact Radius Simulator is exposed through several Arbor components to support different development workflows.
CLI Implementation (arbor refactor)
The CLI provides a human-readable summary of the blast radius, including immediate "breaking" warnings and a --why flag for detailed traversal reasoning.
$ arbor refactor <symbol> --depth 5
🔍 Analyzing symbol...
🟢 Confidence: High | Role: Utility
• 15 callers, 3 dependencies
• Well-connected with manageable impact
⚠️ 18 nodes affected (4 direct, 14 transitive)
Will break immediately:
• parse_file (Function)
• get_parser (Function)
Sources: crates/arbor-cli/src/commands.rs:434-450, crates/arbor-cli/src/commands.rs:475-495, CHANGELOG.md:18-22
AI Bridge (MCP)
The simulator implements the Model Context Protocol, allowing AI tools to request structured JSON impact data.
| Tool Name | Parameter | Description |
|---|---|---|
analyze_impact | node_id | ID/Name of the node to simulate. |
analyze_impact | max_depth | Max hop distance (default 5). |
Sources: crates/arbor-mcp/src/lib.rs:163-174, crates/arbor-mcp/src/lib.rs:218-240
GUI Visualizer
The native GUI provides a "Spoiler Mode" for privacy-safe impact analysis, allowing developers to reveal file paths only when necessary while exploring direct and indirect callers.
Sources: crates/arbor-gui/src/app.rs:35-60, crates/arbor-gui/src/app.rs:215-235
Data Structures
AffectedNode
Represents a single node caught in the blast radius.
pub struct AffectedNode {
pub node_id: NodeId,
pub node_info: NodeInfo,
pub severity: ImpactSeverity,
pub hop_distance: usize,
pub entry_edge: EdgeKind, // Explains why this node is included
pub direction: ImpactDirection,
}
Sources: crates/arbor-graph/src/impact.rs:82-95
ImpactAnalysis
The result object containing the full simulation state.
pub struct ImpactAnalysis {
pub target: NodeInfo,
pub upstream: Vec<AffectedNode>,
pub downstream: Vec<AffectedNode>,
pub total_affected: usize,
pub max_depth: usize,
pub query_time_ms: u64,
}
Sources: crates/arbor-graph/src/impact.rs:98-111
The Impact Radius Simulator ensures deterministic and explainable analysis by following the physical execution paths of the code rather than relying on probabilistic keyword searches.
Sources: README.md:105-115