lsp

Other Community

Skill notes

Quick Start

Run the server on stdio (what editors expect):

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

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.

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.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
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.

Author source file SKILL.md

# 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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.