LSP Refactoring Tools
Relevant source files
The following files were used as context for generating this wiki page:
LSP Refactoring Tools within the OhMyOpenCode ecosystem provide a deterministic and intelligent framework for performing complex code transformations. Unlike standard search-and-replace operations, these tools leverage Language Server Protocol (LSP) capabilities to maintain codebase awareness, ensure type safety, and verify structural integrity throughout the refactoring lifecycle.
The system integrates LSP primitives—such as symbol renaming, definition tracking, and diagnostics—with advanced AI orchestration. This ensures that refactoring tasks are meticulously planned, executed in verifiable steps, and constantly validated against the project's existing patterns and test infrastructure.
Refactoring Command Architecture
The refactoring process is governed by a multi-phase execution loop that prioritizes intent validation and risk assessment before any code modification occurs.
Phase 0: Intent Gate
Every refactoring request must pass through an "Intent Gate." This stage classifies the request type (Explicit, Clear, Open-ended, or Ambiguous) and validates that the success criteria are well-defined. If the scope is uncertain, the system is mandated to ask clarifying questions before proceeding.
Sources: src/features/builtin-commands/templates/refactor.ts:25-70, src/agents/sisyphus.ts:79-115
The Refactoring Lifecycle
The following diagram illustrates the standard workflow for a high-intelligence refactoring task:
The lifecycle ensures that exploration and planning are completed before execution, with continuous verification at every step.
Sources: src/features/builtin-commands/templates/refactor.ts:75-400
Core LSP Primitives
The system utilizes several key LSP functions to perform precise analysis and surgical edits.
LSP Toolset for Analysis
| Tool | Purpose | Implementation Detail |
|---|---|---|
LspGotoDefinition | Context Discovery | Identifies where a symbol is defined to grasp architectural context. |
LspFindReferences | Impact Analysis | Maps all usages across the workspace before modification. |
LspDocumentSymbols | Structural Mapping | Provides a hierarchical outline of file structures. |
lsp_diagnostics | Continuous Verification | Checks for errors/warnings after every single change. |
Sources: src/features/builtin-commands/templates/refactor.ts:114-135, src/agents/hephaestus/gpt.ts:210-220
Deterministic Transformation Tools
For actual code changes, the system prefers deterministic LSP tools over generic text editing when possible:
lsp_prepare_rename: Validates if a symbol rename is valid at the current cursor position.lsp_rename: Executes workspace-wide symbol renaming with type awareness.- AST-Grep: Used for structural pattern transformations (e.g.,
ast_grep_searchandast_grep_replace) with mandatorydryRunpreviews.
Sources: src/features/builtin-commands/templates/refactor.ts:333-355, src/agents/sisyphus.ts:310-315
Codebase Analysis and Codemapping
Before refactoring, the system constructs a "Definitive Codemap" to identify impact zones and established patterns.
Parallel Exploration
The system launches multiple background agents (e.g., explore, librarian) in parallel to find definitions, usage patterns, dependency chains, and related test files.
Sources: src/features/builtin-commands/templates/refactor.ts:84-110, src/agents/atlas/gpt-prompt-sections.ts:153-162
Parallel execution reduces latency during the discovery phase of the refactoring process.
Sources: src/agents/hephaestus/gpt.ts:127-145, src/features/builtin-commands/templates/refactor.ts:84-110
Impact Zone Classification
Based on the codemap, code is categorized by risk level:
- Core (High Risk): Primary definitions and direct implementations.
- Consumers (Medium Risk): Direct callers and modules importing the target.
- Edge (Low Risk): Indirect dependencies or isolated zones.
Sources: src/features/builtin-commands/templates/refactor.ts:167-185
Verification and Safety Protocols
Refactoring tools enforce a strict "No Evidence = Not Complete" policy.
Test Assessment Matrix
The system evaluates test coverage to determine the refactoring strategy:
| Coverage Level | Strategy | Action |
|---|---|---|
| High (>80%) | Standard | Run existing tests after each atomic step. |
| Medium (50-80%) | Caution | Run tests and add safety assertions. |
| Low (<50%) | Pause | Propose adding tests before refactoring. |
| None | Block | Refuse aggressive refactoring. |
Sources: src/features/builtin-commands/templates/refactor.ts:223-235
Post-Step Execution Protocol
For every atomic refactoring step, the following verification sequence is mandatory:
- Read current file state.
- Execute surgical change (LSP Rename or Edit).
- Validate via
lsp_diagnostics(must be clean or match baseline). - Verify via test command (e.g.,
bun testorpytest). - Type Check (e.g.,
tsc --noEmit).
Sources: src/features/builtin-commands/templates/refactor.ts:330-365, src/agents/hephaestus/gpt.ts:245-255
Failure Recovery
If verification fails, the system triggers a recovery protocol:
- Stop immediately.
- Revert the failed change to the last known working state.
- Diagnose the root cause (potentially consulting the
Oracleagent). - Re-verify after every fix attempt.
Sources: src/features/builtin-commands/templates/refactor.ts:367-378, src/agents/sisyphus.ts:346-358
Technical Summary
LSP Refactoring Tools provide a high-integrity environment for code modification by combining the precision of Language Server Protocol with the strategic planning of AI agents. By enforcing mandatory intent gates, codemapping, and post-step verification, the system minimizes regressions and ensures that refactored code remains consistent with established project patterns. Key components like the refactor template and agents like Sisyphus or Hephaestus work in concert to manage the complexity of workspace-wide changes.