Alya for Visual Studio Code

Official Visual Studio Code extension providing full Language Server Protocol (LSP) intelligence, formatting, CodeLens, snippets, and official brand file icons for the Alya programming language.

🌟 Key Features

1. 🧠 Language Server Protocol (LSP)

Powered by the native alya lsp engine:

• Instant Diagnostics: Real-time syntax and type error reporting as you type.
• Smart Autocompletion: Context-aware completion for keywords, variables, struct fields, and functions (Ctrl+Space).
• Hover Tooltips: Signature inspection and Markdown docstrings (##).
• Go to Definition: Jump directly to function, struct, and symbol definitions (F12).

2. ⚡ CodeLens (One-Click Execution & Testing)

• ▶ Run: Appears automatically above function main(). Click to run the program in an integrated Alya terminal.
• 🧪 Run Test: Appears above each test "..." block to execute individual test suites directly.

3. 🎨 Official Brand File Icons & Theme

• Embedded vector SVGs with automatic Dark and Light mode switching for .alya files.
• Includes the standalone Alya File Icons theme (Preferences: File Icon Theme ➔ Alya File Icons).
• Includes the Alya Dark and Alya Light color themes (Preferences: Color Theme): navy/light workspaces matching the brand icons, sky/violet/emerald bracket-pair palettes, say/test/assert highlighted apart from other keywords, subtle inlay-hint colors, and semantic colors aligned with the Alya language server.

4. 🧹 In-Place Code Formatter (alya fmt)

• Native integration with the Alya compiler's formatter:
  • Format Document: Shift+Alt+F
  • Format on Save: Automatic formatting upon saving ("editor.formatOnSave": true).

5. ✂️ Rich Code Snippets

Tab-triggered templates for all major language idioms:

• fn / pubfn ➔ Function definitions
• main / mainargs ➔ Program entry point functions
• struct / pubstruct ➔ Struct definitions
• enum ➔ Enumerations
• test ➔ Unit and integration test blocks
• when ➔ Pattern matching cascades
• if / ifelse ➔ Conditional branching
• while / for ➔ Loop constructs
• try ➔ Exception handling (try ... catch ... finally ... end)
• extern ➔ Foreign Function Interface (extern "C")
• spawn ➔ Colorless concurrency fiber dispatch
• defer ➔ Scope-exit deferred cleanup
• cfg ➔ Feature gate (@cfg(feature = "...") for alya.toml [features])

6. 📝 Smart Docstring & Summary Generator

• Automatic Specification Alignment: Generates canonical ## docstrings adhering to Src/spec (Section 1.2).
• Context-Aware Inference: Analyzes function verbs (calculate, get, is, parse...), parameters, and returns.
• Throws Detection: Automatically inspects function bodies for throw statements and populates ### Throws.
• Struct & Enum Introspection: Generates ### Fields and ### Variants based on declared members.
• Instant Activation:
  • Keyboard shortcut: Ctrl+Alt+D
  • Lightbulb / CodeAction: Click the 💡 icon on any function or struct declaration.
  • Right-click editor context menu: Generate Alya Docstring.

7. 🧪 Official VS Code Test Explorer

• Dedicated sidebar tree view via the VS Code Test Controller API.
• Automatically discovers and organizes all test "..." blocks across your workspace.
• One-click execution with real-time pass/fail indicators and test run durations.

8. 🔬 Native Assembly & AST Inspectors

• Assembly Inspector (Alya: View Assembly Output): Compile directly to native GNU/Mach-O assembly (-S) and inspect side-by-side.
• AST & Token Inspector: Side-by-side visualization of parsed Abstract Syntax Trees (--ast) and lexical tokens (--tokens).

9. 🛠️ Interactive Commands & Menus

• Status Bar: Real-time compiler version and LSP status (Ready, Error) with a 1-click quick actions menu.
• Title Bar Buttons: Instant ▶ Run, 🐞 Debug, and 🧪 Test buttons on every .alya file.
• Context Menu: Right-click anywhere in an .alya file to run, debug, test, format, or generate docs.
• Command Palette (Ctrl+Shift+P):
  • Alya: Run Current File
  • Alya: Debug Current File
  • Alya: Run Tests
  • Alya: Open REPL
  • Alya: Format Document
  • Alya: Generate Documentation
  • Alya: Generate Docstring (Summary)
  • Alya: View Assembly Output (-S)
  • Alya: View Abstract Syntax Tree (AST)
  • Alya: Restart Language Server
  • Alya: Show Environment Info
  • Alya: Register System File Icons (Windows and Linux — system file icons for .alya)

10. 🐞 Debug Adapter Protocol (DAP)

Powered by the native alya dap engine:

• Interactive Breakpoints & Stepping: Set line breakpoints (F9), step over (F10), step into (F11), and step out (Shift+F11).
• Stack & Variable Inspection: Inspect call stack frames, local variables, constants, and concurrency states in the Run & Debug pane.
• Expression Evaluation: Evaluate variables and expressions on hover, in the Watch window, or via the Debug Console.
• Predefined Launch Configurations:
  • Alya: Launch Current File: Instant F5 debugging for active scripts.
  • Alya: Run Tests: Step through test suites with full variable inspection.
  • Alya: Run with Memory Leak Trace: Debug programs with live allocation profiling and memory leak tracing.

11. ✅ Built-in Task Definitions & Problem Matching

• Terminal ➔ Run Task offers Alya: Run Current File, Test/Build/Check/Format Project out of the box (usable as preLaunchTask, customizable via tasks.json with file/args, e.g. "args": ["--features", "simd", "--no-default-features"] to select package features).
• alya lint analyzes each file under its package's default features (matching alya build/test); pass --features/--no-default-features explicitly to gate another view.
• alya check diagnostics land in the Problems panel through the $alya problem matcher.
• a::b chains count as one word (double-click, find, rename support).

12. 👋 Get Started Walkthrough

• Five guided steps with hand-drawn dark/light illustrations: compiler check, first file, first run, theme + tests, docs.
• Fully localized in 20 languages; steps auto-complete as you work.

13. 🌈 Bracket Pair Colorization

Powered by VSCode's native bracket engine (no dependencies, theme-aware):

• Rainbow (), [], {}: matching pairs colored per nesting level, enabled for Alya out of the box with active-pair guides.
• Toggle: alya.rainbowBrackets setting (default true) mirrors into Alya files; or use the standard editor.bracketPairColorization.enabled globally / per [alya].
• Quote punctuation: "...", '...', raw/backtick strings get distinct punctuation.definition.string scopes via the grammar.

🚀 Prerequisites

No manual install needed: if no alya compiler is found on your system PATH, the extension downloads a prebuilt release (alya + alya-lsp) from alya-lang/alya on activation, verifies its SHA-256 checksum, and caches it in global storage. Prefer a system install? It is used first when present:

alya --version

Auto-download can be pinned or disabled via alya.compiler.version ("latest" default) and alya.compiler.autoDownload, or bypassed with an explicit alya.lsp.path.

⚙️ Configuration

Configure the extension in your user or workspace settings.json:

{
  "alya.lsp.path": "alya",
  "alya.lsp.arguments": ["lsp"],
  "editor.formatOnSave": true
}

📦 Building from Source

This extension uses Bun for ultra-fast bundling and dependency management:

# Clone repository
git clone https://github.com/alya-lang/vscode-alya.git
cd vscode-alya

# Install dependencies
bun install

# Bundle extension
bun run build

# Package .vsix
bun run package

To install the built .vsix into VS Code:

code --install-extension alya-lsp-0.13.0.vsix

📄 License

This extension is licensed under the MIT License. Copyright (c) 2026 Taiizor and the Alya Project Authors.