LSP Support & Refactoring Tools
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The LSP (Language Server Protocol) Support & Refactoring Tools provide the project with a high-precision mechanism for codebase analysis, structural transformation, and safe refactoring. By leveraging LSP servers, the system can perform deterministic operations such as symbol renaming, reference tracking, and hierarchical code mapping. These tools are primarily utilized by autonomous agents to maintain codebase integrity during complex modifications.
This system integrates specialized tools like ast-grep for pattern-based transformations alongside standard LSP features to ensure that refactoring is not merely a text-based search-and-replace but a semantically aware architectural update. The suite is designed to function within an autonomous "Execution Loop" that emphasizes exploration, planning, and continuous verification.
Sources: src/features/builtin-commands/templates/refactor.ts:25-36, src/agents/hephaestus.ts:160-170
Core LSP Capabilities
The project implements a comprehensive set of LSP tools for precise analysis and manipulation of the source code. These tools are critical for building "Codemaps" that identify dependency chains and impact zones before any changes are applied.
Analysis Tools
| Tool Name | Function | Use Case |
|---|---|---|
LspGotoDefinition | Locates the primary definition of a symbol. | Understanding code context before modification. |
LspFindReferences | Finds all usages of a symbol across the workspace. | Mapping dependency chains and impact zones. |
LspDocumentSymbols | Retrieves the hierarchical outline of a specific file. | Understanding internal file structure. |
LspWorkspaceSymbols | Searches for symbols by name across the project. | Locating target symbols for refactoring. |
lsp_diagnostics | Returns errors and warnings for specific files. | Continuous verification and post-edit quality gates. |
Sources: src/features/builtin-commands/templates/refactor.ts:110-120, src/features/builtin-commands/templates/init-deep.ts:117-128
Transformation Tools
For actual code modification, the system utilizes high-precision tools to prevent regressions:
lsp_prepare_rename: Validates if a rename operation is possible at a specific location.lsp_rename: Executes a symbol rename across the entire workspace, ensuring all references are updated.ast_grep_replace: Performs structural transformations using pattern matching, supporting adryRunmode for safety previews.
Sources: src/features/builtin-commands/templates/refactor.ts:241-255, sisyphus-prompt.md:280-285
Refactoring Workflow
The refactoring process follows a strict six-phase deterministic execution protocol to ensure safety and coverage.
Phase Flow Diagram
The following diagram illustrates the lifecycle of a refactoring request from intent parsing to final verification.
Implementation Strategy
Refactoring is categorized by risk and strategy:
- Safe Strategy: Conservative approach requiring maximum test coverage.
- Aggressive Strategy: Allows broader changes provided adequate test coverage is detected.
- Verification Protocol: After every atomic change, the system must run
lsp_diagnostics, the project build command, and the relevant test suite. A "zero errors" policy is enforced for all modified files.
Sources: src/features/builtin-commands/templates/refactor.ts:14-23, src/agents/hephaestus.ts:410-425
Dependency Mapping & Impact Analysis
Before execution, the system builds a definitive "Codemap" to visualize the dependency graph. This mapping identifies:
- Core Files: Direct definition sites (High Impact).
- Consumers: Files importing the target (Medium Impact).
- Edge Cases: Indirect dependencies (Low Impact).
Example Codemap Structure
[TARGET_SYMBOL]
├── Imports from: module-a, utils.ts
├── Imported by: consumer-1.ts, consumer-2.ts
└── Used by: handler.ts (direct call), service.ts (DI)
Sources: src/features/builtin-commands/templates/refactor.ts:145-160, src/features/builtin-commands/templates/init-deep.ts:145-155
Verification Standards
The system employs a "Universal Rule: Zero Human Intervention" for verification. All refactoring tasks must be verifiable via automated tools.
| Verification Type | Tool Used | Success Criteria |
|---|---|---|
| Syntax/Types | lsp_diagnostics | Zero errors/warnings introduced. |
| Logic/Behavior | bun test / pytest | Exit code 0, all tests pass. |
| Build Integrity | bun run build | Exit code 0. |
| Pattern Match | ast_grep_search | Code matches project conventions. |
Sources: src/features/builtin-commands/templates/refactor.ts:285-310, src/agents/hephaestus.ts:415-430
Conclusion
LSP Support & Refactoring Tools form the backbone of the project's autonomous code maintenance capability. By combining semantic understanding from LSP servers with the flexibility of AST-based searching, the system allows agents to execute complex refactors with the precision of a senior engineer. The mandatory multi-phase verification loop ensures that architectural changes remain safe, documented, and fully integrated with existing tests.