Nimala Raku LSP & Debugger

The Nimala Visual Studio Code extension providing full Language Server Protocol (LSP 3.18) and Debug Adapter Protocol (DAP) support for the Raku programming language, powered by the Nimala backend.

Features

Code Intelligence (LSP 3.18)

• Syntax Highlighting: Comprehensive and accurate TextMate grammars for Raku code, embedded regexes, and quoting constructs.
• Asynchronous Compiler Diagnostics: Live syntax checking (raku -c) in the background with customizable timeouts and include paths.
• Auto-Completion: Fast, context-aware completions for variables, routines, methods, packages, and named arguments.
• Navigation & References:
  • Go to Definition, Declaration, Type Definition, and Implementation.
  • Find References and Document Highlight.
• Hover & Documentation: Rich hover information with signatures, inferred types, and core Raku documentation.
• Outlines & Symbols:
  • Document Symbols for quick file navigation (Outline view & breadcrumbs).
  • Workspace Symbol search across the entire project.
• Formatting: Full Document Formatting, Range Formatting, and On-Type Formatting.
• Refactoring & Code Actions:
  • QuickFix diagnostics.
  • Extract Method, Inline Variable, and Move Symbol refactorings.
• Hierarchies: Call Hierarchy (incoming/outgoing calls) and Type Hierarchy (supertypes/subtypes).
• Advanced UI Intelligence:
  • Semantic Tokens (full, range, and delta highlighting).
  • Inlay Hints for parameter names and inferred types.
  • Inline Values and CodeLens support.
  • Linked Editing Ranges and Document Links.
• Multi-Root Workspace & File Watching: Dynamic file event watching and progress notifications ($/progress).

Integrated Debugger (DAP)

• Zero-Config Debugging: Press F5 or click the Debug Raku File title button on any active Raku file without needing a launch.json.
• Native VM-Level Execution: Runs standard precompiled bytecode using MoarVM's native debug protocol (raku --debug-port=... --debug-suspend).
• Interactive Stepping: Breakpoints, Step Over (F10), Step Into (F11), and Step Out (Shift+F11).
• Smart Stepping Modes: Configure stepping through Raku core and runtime dispatchers (into, over, or disable).
• Inspection & Evaluation:
  • Inspect call stacks, scopes, lexical variables, object attributes, and nested data structures.
  • Watch expressions and safe expression evaluation in the Debug Console.

Testing & Test Explorer

• Native VS Code Test Explorer:
  • Automatic test discovery for .rakutest, .t, and .t6 files under t/ and xt/ (and workspace folders).
  • Hierarchy discovery down to individual subtest blocks.
  • Test execution via raku / prove6 with live TAP output parsing (ok / not ok) and inline failure messages.
  • Dedicated Run and Debug test profiles directly in the Test view.
• Interactive CodeLens Testing:
  • ▶ Run All Tests and ▶ Debug All Tests at line 0 of every test file.
  • ▶ Run Subtest and ▶ Debug Subtest above each subtest block with automatic breakpoint targeting.

RakuDoc & Pod6 Live Preview

• Live Side-by-Side Preview: Press Ctrl+K V (Cmd+K V on macOS) or click the Open RakuDoc Preview to the Side ($(open-preview)) button on the editor title bar to open a live HTML preview of .rakudoc or embedded Pod6 files.
• Native HTML Generation: Streams document buffers to Rakudo's native raku --doc=HTML - engine via stdin, ensuring 100% spec-accurate rendering of headings, formatting codes (B<...>, C<...>, E<...>), tables, code blocks, and Table of Contents (TOC).
• Theme-Adaptive Styling: Injects VS Code theme variables (--vscode-editor-background, --vscode-editor-foreground, --vscode-textCodeBlock-background) so previews look native in light, dark, and high-contrast editor themes.
• Live Debounced Rendering: Automatically updates the webview preview 300 ms after typing stops, avoiding excessive child process spawning.
• Graceful Error Handling: Displays formatted diagnostic compiler banners inside the webview when Pod syntax errors occur during editing.

Editor Convenience & UI Controls

• Language Status Item:
  • Scoped status indicator in the status bar for active Raku files.
  • Displays Raku compiler version (raku --version) and LSP server state (Starting, Ready, Error).
  • One-click server restart via Raku: Restart Language Server.
• Editor Title Bar Actions:
  • Run Raku File ($(play)): Execute the current Raku file via shell-free ProcessExecution.
  • Debug Raku File ($(debug-alt)): Launch an interactive debugging session for the current file with zero setup.
  • Open RakuDoc Preview to the Side ($(open-preview)): Open a live side-by-side RakuDoc preview for the active document.
• Raku Tasks & Problem Matcher:
  • Auto-detected workspace tasks (vscode.tasks): prove6 -l t/, zef test, and zef install --deps-only ..
  • $raku problem matcher captures Raku compiler and test errors (at <file>:<line>) into VS Code Problems view.
• Built-in Code Snippets:
  • Instant snippets for core constructs: use v6.d;, sub, method, class, role, grammar, token, rule, subtest, given/when, CATCH, and Pod6 blocks.
• Workspace Trust:
  • Full support for VS Code Workspace Trust; restricts executable and include paths in untrusted folders.
  • In Restricted Mode the language server, Test Explorer and RakuDoc preview stay off, because they execute Raku compile-time code; they start automatically once the workspace is trusted.
• Command Palette Actions:
  • Raku: Restart Language Server (nimala.restartServer): Cleanly restarts the LSP server instance without reloading the editor window.
  • Raku: Run Raku File (nimala.runFile): Run the active Raku file.
  • Raku: Debug Raku File (nimala.debugFile): Debug the active Raku file.
  • Raku: Debug Test (nimala.debugTest): Debug a targeted test file or subtest.
  • Raku: Open RakuDoc Preview (nimala.showDocPreview): Open RakuDoc preview in active column.
  • Raku: Open RakuDoc Preview to the Side (nimala.showDocPreviewToSide): Open live RakuDoc preview to the side (Ctrl+K V / Cmd+K V).

Requirements

1. Raku: Ensure Raku is installed on your system (raku.org).

2. Nimala Raku LSP: Install the backend LSP & DAP server globally using zef:

   zef install Nimala::Raku-LSP
   

   This puts the nimala-raku-lsp and nimala-raku-dap executables into the bin/ directory of the repository zef installs to. Without root rights that is usually ~/.raku/bin, which must be in your PATH (for example export PATH="$HOME/.raku/bin:$PATH" in ~/.bashrc; restart VS Code afterwards). Alternatively set raku.lsp.serverPath to the full path of nimala-raku-lsp.

3. Pod::To::HTML (for RakuDoc Live Preview): If not already included with your Rakudo distribution:

   zef install Pod::To::HTML
   

Security Considerations

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

• Compile-Time Code Execution: Live syntax diagnostics (raku -c) and native AST parsing evaluate BEGIN, CHECK, and INIT blocks, as well as compile-time side effects of imported modules (use).
• RakuDoc Live Preview: Rendering documentation (raku --doc=HTML -) also evaluates compile-time code in opened documents.
• Untrusted Workspaces: Do not open untrusted Raku files or repositories without inspecting them first. Exercise caution when granting Workspace Trust in unfamiliar folders.

Extension Settings

Configure the extension via VS Code Settings (Ctrl+, or Cmd+,) or in .vscode/settings.json:

Example launch.json (Optional)

Zero-config debugging works out of the box, but you can create a custom .vscode/launch.json configuration for advanced needs:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "raku",
      "request": "launch",
      "name": "Launch Raku Program",
      "program": "${file}",
      "cwd": "${workspaceFolder}",
      "args": [],
      "stopOnEntry": false,
      "smartStepMode": "into"
    }
  ]
}

Release Notes

1.0.0

• Added live RakuDoc & Pod6 Preview webview panel (Ctrl+K V / Cmd+K V, $(open-preview)).
• Streaming native Rakudo HTML generation (raku --doc=HTML -) with 300 ms debounced live updates and theme variable styling.
• Restricted Mode: Language server, Test Explorer and RakuDoc preview start only in trusted workspaces.
• RakuDoc preview hints at zef install Pod::To::HTML when the module is missing.
• Test Explorer: Discovers tests under both t/ and xt/.

0.14.1

• Updated devDependencies (typescript-eslint, eslint, mocha, @types/node, glob) and runtime dependency (vscode-languageclient 10.1.2).
• Improved build & packaging compatibility for prepublish scripts.

0.14.0

• Synchronized with Nimala Raku LSP 0.14.0.
• Complete implementation of the remediation roadmap (Waves 1–4):
  • Modern LanguageStatusItem showing runtime version and server status.
  • Native VS Code Test Explorer (vscode.TestController) with TAP parsing and subtest discovery.
  • ▶ Debug All Tests / ▶ Debug Subtest CodeLenses.
  • Built-in Raku code snippets and Raku task provider.
  • Interactive refactoring input prompts (Move Symbol).
  • Workspace Trust declarations and configuration synchronization.
  • Modular architecture with single-file esbuild bundling (~325 KB VSIX).

0.1.0

• Feature Release:
  • Full LSP 3.18 implementation with code completion, definition jumping, references, formatting, refactorings, semantic tokens, and hierarchies.
  • Full Debug Adapter Protocol (DAP) implementation with breakpoints, variable inspection, call stack navigation, and expression evaluation.
  • Editor title bar buttons for quick Run Raku File and Debug Raku File.
  • Added Raku: Restart Language Server command.
  • Added comprehensive configuration settings for runtime paths, include directories, syntax check timeouts, and smart stepping modes.

0.0.x

• Early beta preview releases.

Acknowledgements

• TextMate syntax grammars (syntaxes/*.json) are derived from the Raku/atom-language project.
• Camelia logo © Larry Wall, Artistic License 2.0.

License: Artistic-2.0