lsp

Name: lsp
Author: atopile

Other Community

Repo stars 3,367
License MIT
Author repo atopile

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: How the atopile Language Server works (pygls), how it builds per-document graphs for completion/hover/defs, and the invariants f…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Quick Start”, “Relevant Files”, “Dependants (Call Sites)”, “How to Work With / Develop / Test”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name lsp directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Quick Start / Relevant Files / Dependants (Call Sites)” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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

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

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: 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
Author / version / license: @atopile · MIT
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Python
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview lsp.preview

The current SKILL.md does not define a fixed output example.

SKILL.md 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

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

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/lspserver.py · LSPSERVER · LanguageServer · DocumentState · src/atopile/lsp/lsputils.py
body sha256 -> 81d561a5f974