NAME

Nimala::Raku-LSP - Complete Raku Language Server Protocol (LSP 3.18) & Debug Adapter Protocol (DAP)

DESCRIPTION

Nimala is a full-featured Language Server Protocol (LSP 3.18) and Debug Adapter Protocol (DAP) implementation for the Raku programming language, written entirely in Raku. It provides advanced IDE intelligence, refactoring capabilities, and integrated debugging to any LSP-compatible editor (such as VS Code, Neovim, Helix, or Emacs).

Key Highlights

• 100% Coverage of All Useful LSP 3.18 Features: 72 LSP methods and 20 DAP methods fully implemented and tested.

• Multi-Tiered AST & Deep Type Inference: Combines native NQP compiler AST parsing, resilient fallback grammars, and dynamic MRO / generic type tracking.

• Multi-Root Workspace & Reactive Progress Engine: Dynamic folder indexing, pruning, and bidirectional $/progress reporting with RAII scopes.

• High Performance & Low Latency: Persistent SQLite index caching (.nimala/symbols.db), prefix-based symbol search, and non-blocking asynchronous event streams (Supply, Proc::Async, Lock).

LSP 3.18 Implementation Matrix

Programmatic Usage

The server binary dispatches JSON-RPC through its own Nimala::Raku-LSP::Dispatcher (method whitelist, cancellation, concurrent requests). For embedding, the handler can also be driven by JSON::RPC::Server, as the test suite does, to analyze Raku code or build custom clients:

use Nimala::Raku-LSP::Handler;
use JSON::RPC::Server;

# Initialize the LSP Handler
my $handler = Nimala::Raku-LSP::Handler.new;

# Wrap it in a JSON-RPC Server
my $server = JSON::RPC::Server.new(application => $handler);

# Simulate a JSON-RPC Request (e.g., from a client)
my $request = q:to/END/;
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "processId": null,
    "rootUri": null,
    "capabilities": {}
  }
}
END

# Process the request and get the JSON-RPC response
my $response = $server.handler($request);
say $response;

Debug Adapter Protocol (DAP) Architecture

Nimala includes a Debug Adapter Protocol (DAP) server (bin/nimala-raku-dap). The debugger is built directly on MoarVM's native remote debugging protocol, communicating with the debuggee over loopback TCP using MessagePack framing.

• Native VM-Level Execution: The debuggee runs as standard raku --debug-port=<port> --debug-suspend <program>, executing standard precompiled bytecode. This eliminates the precompilation slot mismatches, slow first launches, and compiler when statement crashes of earlier statement-hook implementations.

• Pure-Raku MessagePack Framing: Communication uses a fast, dependency-free MessagePack codec and protocol client with monotonic request/response correlation and event dispatch.

• Monotonic Handle Management: Context and object handles allocated during stops are tracked in a lifecycle registry and cleanly released in batches upon resume or disconnect.

• Bounded Expressions & Safe Inspection: Expression evaluation, conditional breakpoints, and logpoints use a bounded expression grammar (variables, attribute/key/index access, comparisons against literals). Arbitrary method calls and mutations are refused; only the whitelisted helpers .gist, .Str, .raku and .elems run in the debuggee, at most one per stop.

• Smart Stepping: Configurable smart stepping (into, over, disable) automatically filters out internal compiler, runtime, and NQP frames so stepping stays focused on user code.

For full architectural details, see docs/DEBUG.md and docs/DEBUG-MOARVM.md.

Installation & Dependencies

Nimala requires a working Raku installation (Rakudo 2026.09 recommended) and the sqlite3 shared library for index persistence. Only Rakudo 2026.09 is tested. Rakudo 2024.07 runs with limitations: the debugger can abort with a MoarVM panic, and the RakuAST-based analysis ignores signature parameters and fails on files with BEGIN blocks, so the built-in parser fills in.

Dependencies

• DBIish & DBDish::SQLite: Database independent interface and SQLite driver for persistent, transactional symbol indexing (.nimala/symbols.db).

• JSON::Fast: High-performance JSON parser and serializer.

Install via Zef

# Install all dependencies and Nimala LSP/DAP binaries
zef install Nimala::Raku-LSP

zef puts the nimala-raku-lsp and nimala-raku-dap scripts into the bin/ directory of the repository it installs to. Without root rights that is usually ~/.raku/bin, which must be in PATH (for example export PATH="$HOME/.raku/bin:$PATH" in ~/.bashrc). Otherwise editors cannot find the server.

Security Considerations

Like standard Raku tooling, the language server executes compile-time code when inspecting documents:

• Compile-Time Execution: Background syntax checking (raku -c) and native AST parsing execute BEGIN, CHECK, and INIT blocks as well as compile-time side effects of imported modules (use).

• Doc Preview Evaluation: Rendering RakuDoc to HTML (raku --doc=HTML) also evaluates compile-time blocks in opened files.

• Untrusted Code: Never open untrusted Raku files or untrusted workspaces without inspecting them first. Always use isolated environments (containers or sandboxes) when reviewing unknown code.

License Artistic-2.0

sub run-tcp-server

sub run-tcp-server(
    Str :$host = "127.0.0.1",
    Int :$port = 5007,
    Bool :$single-session = Bool::False,
    Promise :$stop-promise = Code.new
) returns Nil

Re-export run-tcp-server from Transport::Socket

sub run-server

sub run-server(
    IO::Handle :$in = Code.new,
    IO::Handle :$out = Code.new,
    Nimala::Raku-LSP::Handler :$handler = Code.new,
    :$supply = Code.new
) returns Int

Start the LSP server loop.