feat(lsp): Phase 1 - LSP server scaffolding complete

Implements foundational LSP infrastructure for WokeLang:

## Architecture
- tower-lsp 0.20 (async LSP framework)
- tokio async runtime
- DashMap for concurrent document cache
- OnceCell for lazy parsing

## Files Added (2,600+ LOC planned, ~1,200 LOC Phase 1)
- src/bin/woke-lsp.rs - LSP server binary entry point
- src/lsp/mod.rs - Module exports
- src/lsp/backend.rs - LanguageServer trait implementation
- src/lsp/document.rs - Document state with lazy caching
- src/lsp/utils.rs - Span↔Range conversion utilities
- src/lsp/handlers/* - Handler stubs (completion, hover, definition, diagnostics)
- src/lsp/symbols.rs - Symbol resolution (stub)
- src/lsp/stdlib_metadata.rs - Stdlib metadata (stub)

## Integration
- Added public API to TypeChecker: env(), take_env(), get_all_symbols(), get_symbol_type()
- Uses existing Lexer, Parser, TypeChecker, Linter

## Features Implemented
✅ LSP server lifecycle (initialize, initialized, shutdown)
✅ Document synchronization (didOpen, didChange, didClose)
✅ Basic diagnostics pipeline (lexer + parser errors)
✅ Server capabilities declaration
✅ Document caching with lazy evaluation

## Features Stubbed (Phase 2)
- Auto-completion (keywords, stdlib, symbols)
- Hover (type information)
- Go-to-definition
- Enhanced diagnostics (linter integration)

## Build Status
✅ Compiles successfully
✅ cargo build --bin woke-lsp --release passes
✅ Dependencies resolved (tower-lsp, tokio, lsp-types, dashmap, once_cell)

## Testing
Manual test: cargo run --bin woke-lsp starts server

## Next Steps (Phase 2)
- Implement completion handler
- Implement hover handler
- Implement go-to-definition
- Add stdlib metadata
- Full diagnostics integration

Estimated Phase 1 completion: 100%
Overall LSP implementation: ~40% (Phase 1 of 3)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Jonathan D.A. Jewell

Cargo.lock

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+
 [package]
 name = "wokelang"
 version = "0.1.0"
@@ -15,6 +17,10 @@ path = "src/lib.rs"
 name = "woke"
 path = "src/main.rs"
 
+[[bin]]
+name = "woke-lsp"
+path = "src/bin/woke-lsp.rs"
+
 [dependencies]
 logos = "0.14"
 thiserror = "1.0"
@@ -23,6 +29,15 @@ rustyline = { version = "14.0", features = ["derive"] }
 dirs = "5.0"
 clap = { version = "4.5", features = ["derive"] }
 
+# LSP dependencies
+tower-lsp = "0.20"
+tokio = { version = "1", features = ["full"] }
+lsp-types = "0.95"
+dashmap = "6.0"
+once_cell = "1.19"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
 [dev-dependencies]
 pretty_assertions = "1.4"
 

Cargo.toml

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//! WokeLang Language Server Protocol (LSP) Server
+//!
+//! This binary provides IDE integration for WokeLang through the Language Server Protocol.
+
+use tower_lsp::{LspService, Server};
+use wokelang::lsp::Backend;
+
+#[tokio::main]
+async fn main() {
+    // Initialize logging (stderr for LSP)
+    eprintln!("WokeLang LSP Server starting...");
+
+    // Create LSP service
+    let stdin = tokio::io::stdin();
+    let stdout = tokio::io::stdout();
+
+    let (service, socket) = LspService::new(|client| Backend::new(client));
+
+    eprintln!("WokeLang LSP Server initialized");
+
+    // Run the server
+    Server::new(stdin, stdout, socket).serve(service).await;
+
+    eprintln!("WokeLang LSP Server shutdown");
+}

src/bin/woke-lsp.rs

@@ -3,6 +3,7 @@ pub mod ast;
 pub mod interpreter;
 pub mod lexer;
 pub mod linter;
+pub mod lsp;
 pub mod parser;
 pub mod repl;
 pub mod security;

src/lib.rs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//! LSP Backend - LanguageServer trait implementation
+
+use dashmap::DashMap;
+use std::sync::Arc;
+use tower_lsp::jsonrpc::Result;
+use tower_lsp::lsp_types::*;
+use tower_lsp::{Client, LanguageServer};
+
+use super::document::DocumentState;
+use super::handlers;
+
+/// LSP Backend for WokeLang
+pub struct Backend {
+    /// LSP client for sending notifications
+    pub client: Client,
+    /// Map of document URIs to document state
+    pub document_map: Arc<DashMap<Url, DocumentState>>,
+}
+
+impl Backend {
+    /// Create a new LSP backend
+    pub fn new(client: Client) -> Self {
+        Self {
+            client,
+            document_map: Arc::new(DashMap::new()),
+        }
+    }
+}
+
+#[tower_lsp::async_trait]
+impl LanguageServer for Backend {
+    async fn initialize(&self, _params: InitializeParams) -> Result<InitializeResult> {
+        Ok(InitializeResult {
+            capabilities: ServerCapabilities {
+                text_document_sync: Some(TextDocumentSyncCapability::Kind(
+                    TextDocumentSyncKind::FULL,
+                )),
+                completion_provider: Some(CompletionOptions {
+                    trigger_characters: Some(vec![".".to_string(), ":".to_string()]),
+                    resolve_provider: Some(false),
+                    ..Default::default()
+                }),
+                hover_provider: Some(HoverProviderCapability::Simple(true)),
+                definition_provider: Some(OneOf::Left(true)),
+                diagnostic_provider: Some(DiagnosticServerCapabilities::Options(
+                    DiagnosticOptions {
+                        identifier: Some("wokelang".to_string()),
+                        inter_file_dependencies: false,
+                        workspace_diagnostics: false,
+                        ..Default::default()
+                    },
+                )),
+                ..Default::default()
+            },
+            server_info: Some(ServerInfo {
+                name: "woke-lsp".to_string(),
+                version: Some("0.1.0".to_string()),
+            }),
+        })
+    }
+
+    async fn initialized(&self, _params: InitializedParams) {
+        self.client
+            .log_message(MessageType::INFO, "WokeLang LSP server initialized")
+            .await;
+    }
+
+    async fn shutdown(&self) -> Result<()> {
+        Ok(())
+    }
+
+    async fn did_open(&self, params: DidOpenTextDocumentParams) {
+        let uri = params.text_document.uri;
+        let text = params.text_document.text;
+        let version = params.text_document.version;
+
+        // Store document
+        let doc = DocumentState::new(uri.clone(), text, version);
+        self.document_map.insert(uri.clone(), doc);
+
+        // Publish diagnostics
+        handlers::diagnostics::publish_diagnostics(self, &uri).await;
+    }
+
+    async fn did_change(&self, params: DidChangeTextDocumentParams) {
+        let uri = params.text_document.uri;
+        let version = params.text_document.version;
+
+        // Get new text (full sync mode)
+        if let Some(change) = params.content_changes.first() {
+            let new_text = change.text.clone();
+
+            // Replace document state (invalidates all caches)
+            let doc = DocumentState::new(uri.clone(), new_text, version);
+            self.document_map.insert(uri.clone(), doc);
+
+            // Publish diagnostics
+            handlers::diagnostics::publish_diagnostics(self, &uri).await;
+        }
+    }
+
+    async fn did_close(&self, params: DidCloseTextDocumentParams) {
+        let uri = params.text_document.uri;
+        // Remove from cache
+        self.document_map.remove(&uri);
+    }
+
+    async fn completion(&self, params: CompletionParams) -> Result<Option<CompletionResponse>> {
+        handlers::completion::completion(self, params).await
+    }
+
+    async fn hover(&self, params: HoverParams) -> Result<Option<Hover>> {
+        handlers::hover::hover(self, params).await
+    }
+
+    async fn goto_definition(
+        &self,
+        params: GotoDefinitionParams,
+    ) -> Result<Option<GotoDefinitionResponse>> {
+        handlers::definition::goto_definition(self, params).await
+    }
+}

src/lsp/backend.rs

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//! Document state management and caching
+
+use once_cell::sync::OnceCell;
+use std::ops::Range;
+use tower_lsp::lsp_types::Url;
+
+use crate::ast::Program;
+use crate::lexer::{Lexer, Spanned as LexerSpanned, Token};
+use crate::parser::Parser;
+use crate::typechecker::{TypeChecker, TypeEnv};
+
+use super::utils::LineIndex;
+
+/// Document state with lazy-evaluated caches
+pub struct DocumentState {
+    pub uri: Url,
+    pub version: i32,
+    pub source: String,
+    pub line_index: LineIndex,
+
+    // Lazy-evaluated caches
+    tokens: OnceCell<Result<Vec<LexerSpanned<Token>>, String>>,
+    ast: OnceCell<Result<Program, String>>,
+    type_env: OnceCell<Option<TypeEnv>>,
+}
+
+impl DocumentState {
+    /// Create a new document state
+    pub fn new(uri: Url, source: String, version: i32) -> Self {
+        let line_index = LineIndex::new(&source);
+
+        Self {
+            uri,
+            version,
+            source,
+            line_index,
+            tokens: OnceCell::new(),
+            ast: OnceCell::new(),
+            type_env: OnceCell::new(),
+        }
+    }
+
+    /// Get tokens (lazy evaluation)
+    pub fn tokens(&self) -> &Result<Vec<LexerSpanned<Token>>, String> {
+        self.tokens.get_or_init(|| {
+            let lexer = Lexer::new(&self.source);
+            lexer.tokenize().map_err(|e| format!("{}", e))
+        })
+    }
+
+    /// Get AST (lazy evaluation)
+    pub fn ast(&self) -> &Result<Program, String> {
+        self.ast.get_or_init(|| {
+            let tokens = match self.tokens() {
+                Ok(t) => t,
+                Err(e) => return Err(e.clone()),
+            };
+
+            let mut parser = Parser::new(tokens.clone(), &self.source);
+            parser.parse().map_err(|e| format!("{}", e))
+        })
+    }
+
+    /// Get type environment (lazy evaluation, returns reference)
+    pub fn type_env(&self) -> Option<&TypeEnv> {
+        self.type_env
+            .get_or_init(|| {
+                let ast = match self.ast() {
+                    Ok(a) => a,
+                    Err(_) => return None,
+                };
+
+                let mut typechecker = TypeChecker::new();
+                match typechecker.check_program(ast) {
+                    Ok(_) => Some(typechecker.take_env()),
+                    Err(_) => None,
+                }
+            })
+            .as_ref()
+    }
+
+    /// Get word at position (for completion/hover)
+    pub fn word_at_position(&self, line: u32, character: u32) -> Option<String> {
+        let offset = self.line_index.position_to_offset(line, character)?;
+
+        // Find word boundaries
+        let start = self.source[..offset]
+            .rfind(|c: char| !c.is_alphanumeric() && c != '_' && c != '.')
+            .map(|i| i + 1)
+            .unwrap_or(0);
+
+        let end = self.source[offset..]
+            .find(|c: char| !c.is_alphanumeric() && c != '_' && c != '.')
+            .map(|i| offset + i)
+            .unwrap_or(self.source.len());
+
+        if start < end {
+            Some(self.source[start..end].to_string())
+        } else {
+            None
+        }
+    }
+}

src/lsp/document.rs

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//! Completion handler
+
+use tower_lsp::jsonrpc::Result;
+use tower_lsp::lsp_types::*;
+
+use crate::lsp::Backend;
+
+/// Handle completion request
+pub async fn completion(
+    _backend: &Backend,
+    _params: CompletionParams,
+) -> Result<Option<CompletionResponse>> {
+    // TODO: Implement completion
+    Ok(None)
+}

src/lsp/handlers/completion.rs

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
+//! Definition handler
+
+use tower_lsp::jsonrpc::Result;
+use tower_lsp::lsp_types::*;
+
+use crate::lsp::Backend;
+
+/// Handle go-to-definition request
+pub async fn goto_definition(
+    _backend: &Backend,
+    _params: GotoDefinitionParams,
+) -> Result<Option<GotoDefinitionResponse>> {
+    // TODO: Implement go-to-definition
+    Ok(None)
+}