Language Server (LSP)
Relevant source files
The following files were used as context for generating this wiki page:
The Language Server Protocol (LSP) implementation for Pop Lang, organized under the Pop.Lsp package, provides IDE-like features through structured semantic APIs rather than simple text scraping. It is designed to expose the compiler's internal semantic model—including diagnostics, symbols, metadata, and documentation—to editors and build tools via stable, versioned structured formats.
Sources: README.md:243-250, AGENTS.md:520-523, architecture/22.6-standard-library-implementation-plan.md:38
Architecture and Integration
The Language Server is built as an official extension package (Pop.Lsp) that operates independently of the fixed language prelude. It consumes data from the compiler's semantic pipeline, specifically leveraging the resolved AST and typed analysis to provide accurate code intelligence.
The diagram shows how the LSP functions as a consumer of the core compiler's semantic analysis stages.
Sources: AGENTS.md:512-517, architecture/07-implementation-roadmap.md:16-18, architecture/22.6-standard-library-implementation-plan.md:38
Key Responsibilities
The Language Server is responsible for several critical developer experience features:
- Hover Support: Displays
<summary>, parameters, returns, errors, effects, and selected remarks from XML documentation. - Completion: Provides concise summaries during code entry.
- Signature Help: Shows matching
<param>and<typeparam>documentation. - Navigation: Implements Go-to-Definition and Rename functionality, specifically resolving
creflinks within documentation. - Diagnostics: Integrates with the compiler's structured diagnostic pipeline to provide real-time feedback and incremental updates.
Sources: architecture/20-xml-documentation-comments.md:186-193, AGENTS.md:659-661
Structured Diagnostics and Fixes
Diagnostics in the Pop Lang LSP are not simple strings but structured semantic APIs. These diagnostics include stable POP#### codes, typed arguments, and semantic quick fixes. The LSP renders the same diagnostic objects used by the CLI and other tooling.
| Feature | Description |
|---|---|
| Stable Codes | Unique identifiers (e.g., POP64xx for docs) for reliable suppression and lookup. |
| Quick Fixes | Semantic actions like inserting XML skeletons or renaming parameters. |
| Incremental Updates | Real-time diagnostic refreshing as the user edits code. |
| Safe Fix-All | Atomic, version-checked, and composable fixes that verify postconditions. |
Sources: AGENTS.md:659-666, architecture/20-xml-documentation-comments.md:195-212
Documentation and Semantic Hover
A primary function of the LSP is rendering XML Documentation Comments. Documentation edits trigger invalidation of hover queries but do not necessitate a full rebuild of the implementation (MIR/Native code), ensuring high performance for editor interactions.
The sequence diagram illustrates the flow from a user action in the editor to the retrieval and rendering of semantic information by the LSP.
Sources: architecture/20-xml-documentation-comments.md:175-179, architecture/20-xml-documentation-comments.md:186-188
Implementation Roadmap
The LSP development is staged following the project's vertical slice roadmap. While Milestone 2 introduced basic JSON output and diagnostic rendering, full LSP integration is targeted in later phases.
- Milestone 2: Initial JSON output for diagnostics and basic compiler fixtures.
- Milestone 4: Full stack traces and debug locations for native execution.
- Phase 6 (StdLib Plan): Finalization of
Pop.Lspextension builds, incorporatingPop.Syntaxfacades andPop.Rpcfor communication.
Sources: architecture/07-implementation-roadmap.md:46-47, architecture/07-implementation-roadmap.md:92, architecture/22.6-standard-library-implementation-plan.md:38-40
Conclusion
The Language Server serves as the bridge between the high-fidelity semantic analysis of the Pop Lang compiler and the developer's environment. By treating diagnostics and documentation as checked, structured data rather than trivia, it ensures that editor features remain technically accurate and synchronized with the language's static typing and architecture invariants.