lsp
- Repo stars 3,367
- License MIT
- Author repo atopile
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @atopile · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# LSP Module
The `lsp` module (located in `src/atopile/lsp/`) implements the Language Server Protocol for atopile. It provides IDE features like autocomplete, go-to-definition, and diagnostics (error reporting) for `ato` files.
## Quick Start
Run the server on stdio (what editors expect):
```bash
python -m atopile.lsp.lsp_server
```
## Relevant Files
- Server implementation: `src/atopile/lsp/lsp_server.py`
- owns global `LSP_SERVER` (pygls `LanguageServer`)
- maintains per-document `DocumentState` (graph/typegraph/build_result)
- implements completion/hover/definition/diagnostics handlers
- Utilities: `src/atopile/lsp/lsp_utils.py`
- Optional debugging helper: `src/atopile/lsp/_debug_server.py`
## Dependants (Call Sites)
- **VSCode Extension**: The designated client for this server.
- **Compiler**: The LSP invokes the compiler (often in a partial or fault-tolerant mode) to understand the code structure.
## How to Work With / Develop / Test
### Core Concepts
- **Partial Compilation**: Unlike the CLI build, the LSP must handle broken or incomplete code without crashing.
- **Latency**: Features must be fast (<50ms for typing, <200ms for completion).
- **Per-document graphs**: each open document has an isolated `GraphView` + `TypeGraph` stored in `DocumentState`.
- **Keep last good build**: the server keeps the last successful `BuildFileResult` to power completion/hover even when the current edit has errors.
### Development Workflow
1) Edit handlers/helpers in `src/atopile/lsp/lsp_server.py`.
2) Run completion tests (fast loop) and verify GraphView cleanup paths.
### Testing
- Integration-style tests: `ato dev test --llm test/test_lsp_completion.py -q`
## Best Practices
- **Robustness**: Never let the server crash. Catch all exceptions in handlers and log them.
- **Debouncing**: Don't trigger expensive operations on every keystroke.
## Core Invariants (easy to regress)
- Always destroy old graphs on rebuild/reset (`DocumentState.reset_graph` calls `GraphView.destroy()`).
- Do not assume builds succeed; most features must handle:
- syntax errors (ANTLR)
- partial typegraphs
- exceptions from linking/deferred execution
Sections and files
Listed in source order.
sections -> Quick Start → Relevant Files → Dependants (Call Sites) → How to Work With / Develop / Test → Core Concepts → Development Workflow
terms -> VSCode Extension · Compiler · Partial Compilation · Latency · Per-document graphs · Keep last good build · Robustness · Debouncing
files/cmd -> lsp · src/atopile/lsp/ · ato · src/atopile/lsp/lsp_server.py · LSP_SERVER · LanguageServer · DocumentState · src/atopile/lsp/lsp_utils.py
body sha256 -> 81d561a5f974
Quick Start
Run the server on stdio (what editors expect):
Relevant Files
Server implementation:
src/atopile/lsp/lsp_server.pyowns globalLSP_SERVER(pyglsLanguageServer) maintains per-documentDocumentState(graph/typegraph/build_result) implements completion/hover/definition/diagnostics handlers Utilities:src/atopile/lsp/lsp_utils.pyDependants (Call Sites)
VSCode Extension: The designated client for this server. Compiler: The LSP invokes the compiler (often in a partial or fault-tolerant mode) to understand the code structure.
Core Concepts
Partial Compilation: Unlike the CLI build, the LSP must handle broken or incomplete code without crashing. Latency: Features must be fast (<50ms for typing, <200ms for completion). Per-document graphs: each open document has an isolated
GraphView+TypeGraphstored inDocumentState. Keep last good build: the server keeps the last successfulBuildFileResultto power completion/hover even when the current edit has errors.Development Workflow
Edit handlers/helpers in
src/atopile/lsp/lsp_server.py. Run completion tests (fast loop) and verify GraphView cleanup paths.