lsp

The atopile LSP module facilitates real-time language support within IDEs like VS Code and Cursor, enabling hardware engineers to design circuit boards using code. It acts as a bridge between the atopile compiler and the editor, ensuring that design intent expressed in .ato files is validated and surfaced through standard LSP interfaces. By leveraging the pygls framework, the server provides responsive feedback, including autocomplete, go-to-definition, and diagnostic error reporting, significantly reducing the iteration loop for hardware development.

• Real-time IDE integration providing autocomplete, hover documentation, and jump-to-definition capabilities for .ato files.

• Fault-tolerant partial compilation architecture that handles broken or incomplete code during active editing sessions without crashing the server.

• Per-document DocumentState management using GraphView and TypeGraph, allowing the server to maintain project context even when editing isolated modules.

• Efficient caching mechanism that preserves the last successful BuildFileResult to ensure responsive UI behavior during ongoing edits.

• Robust error reporting and diagnostics powered by the integration with the core atopile compiler and ANTLR-based parser.

• Operates on standard input/output (stdio) for seamless editor compatibility.

• Performance requirements dictate response times of under 50ms for typing and 200ms for completion to maintain a fluid user experience.

• Implements strict robustness patterns, including debouncing of expensive operations and systematic cleanup of GraphView resources upon rebuilds or resets.

• Developers should utilize integration tests via the ato dev test command specifically targeting lsp_completion.py for rapid feedback loops.

• Primary entry point for development is located at src/atopile/lsp/lsp_server.py, with supplemental utilities found in lsp_utils.py.

• Ensure all LSP handlers implement comprehensive exception catching to guarantee that the server never crashes, even when encountering syntax errors or deferred execution failures.