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).

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

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

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.

🚀 Prerequisites

Ensure the alya compiler is installed and available in your system PATH:

alya --version

If not installed, install or build Alya from the official repository.

⚙️ 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.2.1.vsix

📄 License

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