About this skill

LSP Module

Name: lsp
Rating: 5 (3381 reviews)
Author: atopile/atopile

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):

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

Edit handlers/helpers in src/atopile/lsp/lsp_server.py.
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