Language Server Protocol (LSP)

The Zen Language Server Protocol (LSP) implementation is a powerful tool designed to significantly enhance the development experience for Zen programmers within various Integrated Development Environments (IDEs). By integrating directly with the Zen compiler's core functionalities, the LSP provides a rich set of code intelligence features, ensuring accuracy and consistency across the entire development workflow. This deep integration is particularly crucial for Zen, with its unique zero-keyword syntax and reliance on pattern matching and Uniform Function Call (UFC), as it helps developers navigate the language's expressive power.

The Zen LSP server is built in Rust and leverages a background analysis thread to perform computationally intensive tasks, such as full program validation and diagnostics. This architecture ensures that the editor's UI remains responsive while providing real-time, compiler-backed insights into the codebase.

Key LSP Features for Zen Development

The Zen LSP supports a comprehensive suite of features, transforming a basic text editor into a full-fledged Zen development environment:

Diagnostics

Purpose: Provides real-time feedback on syntax errors, type mismatches, and semantic issues directly in the editor.

Zen Context: Leveraging the Zen compiler, diagnostics are highly accurate, pinpointing issues specific to Zen's grammar and type system, including:

• Syntax Errors: Catches malformed expressions, declarations, or control flow constructs.
• Type Mismatches: Identifies incompatible types in assignments, function calls, and binary operations, crucial given Zen's strong static typing.
• Undeclared Symbols: Warns about undefined variables, functions, structs, or enum variants.
• Allocator Usage: Highlights calls to collection constructors (e.g., DynVec, HashMap) or string operations that require an explicit allocator, guiding developers toward correct memory management.
• Non-Exhaustive Pattern Matching: Detects when ? (pattern matching) expressions do not cover all possible cases of an enum, helping ensure robust code.
• Import Errors: Flags incorrect module paths or attempts to import modules inside comptime blocks, which is disallowed by Zen's spec.

Hover (Type Information)

Purpose: Displays contextual information, such as type definitions, function signatures, and documentation, when hovering over a symbol.

Zen Context: Hover is type-aware and deeply integrated with Zen's unique features:

• Inferred Types: Reveals the automatically inferred types for variables and expressions, a key aspect of Zen's concise syntax.
• Function/Method Signatures: Shows detailed parameter lists, return types, and potential generic parameters for both traditional functions and UFC (Uniform Function Call) methods (e.g., my_vec.push(item)).
• Struct/Enum Definitions: Displays the full structure of custom types, including fields and variants.
• Built-in Types: Provides explanations for primitive types (i32, f64, bool), string types (StaticString, String), and core constructs (Option, Result, Vec, DynVec, HashMap).
• Format String Interpolations: When hovering over an expression inside a ${...} block within a string literal, the LSP infers and displays the type of that embedded expression.

Go to Definition

Purpose: Navigates directly to the source code location where a symbol is defined.

Zen Context: Facilitates quick navigation across your codebase and the standard library:

• Functions and Variables: Jumps to their declarations.
• Structs and Enums: Directs to their definitions.
• Enum Variants: Points to the definition of the enum that contains the variant.
• Module Imports: When clicking on an imported symbol (e.g., io from { io } = @std), it navigates to the corresponding standard library file (e.g., stdlib/io/io.zen).
• UFC Methods: Resolves to the actual function definition that implements the method call, even with Zen's flexible UFC mechanism.

Code Completion

Purpose: Provides intelligent suggestions for code completion as you type.

Zen Context: Context-aware completion helps with Zen's expressive but terse syntax:

• Keywords: Suggests control flow constructs (loop, return, break), pub, comptime, etc.
• Built-in Types: Offers primitive types and common generic types like Option, Result, Vec, DynVec, HashMap.
• Local Symbols: Completes names of variables, functions, structs, and enums defined in the current file.
• Standard Library: Suggests modules (e.g., @std.io, @std.math), functions, and types from the Zen standard library.
• Workspace Symbols: Provides completion for symbols defined in other .zen files within your project.
• Contextual Completion:
  • UFC Methods: After typing object., it suggests methods applicable to object's type, including both inherent methods and functions callable via UFC.
  • Module Paths: After @std., it suggests available standard library modules (e.g., io, math, collections).

Signature Help

Purpose: Displays the signature of a function or method, along with parameter information, as you type arguments.

Zen Context: Essential for understanding complex function calls in Zen:

• Function Calls: Shows the full signature (parameters with names and types, and return type) of the function being called.
• Method Calls (UFC): Provides signatures for functions invoked via UFC (e.g., my_list.push(element)).
• Active Parameter Highlighting: Highlights the parameter currently being typed, aiding in correct argument placement.

Inlay Hints

Purpose: Displays additional inline information, such as inferred types for variables or parameter names in function calls, directly in the code without altering the source.

Zen Context: Enhances readability without verbosity:

• Inferred Variable Types: Shows the compiler-inferred type for variables where an explicit type annotation was omitted (e.g., x = 10 //: i32).
• Parameter Names: Displays parameter names at the call site for clarity (e.g., some_func(param1: 10, param2: "hello")).

Semantic Tokens

Purpose: Provides fine-grained, semantic-based highlighting that goes beyond basic syntax highlighting, distinguishing different types of symbols based on their meaning.

Zen Context: Offers richer visual cues for Zen's unique elements:

• Keywords, Types, Variables, Functions, Methods: Standard semantic highlighting.
• Allocator-Related Code: Special highlighting for types and functions related to memory allocators (e.g., Allocator, DynVec, get_default_allocator()).
• Error Propagation: Distinct highlighting for .raise() calls, emphasizing error handling points.
• String Interpolation: Differentiates literal parts of a string from interpolated expressions (${...}) within a string.

Call Hierarchy

Purpose: Helps navigate the call graph of a function or method, showing both incoming calls (who calls this function) and outgoing calls (what functions this function calls).

Zen Context: Provides insights into code flow, especially useful in modular Zen projects:

• Functions and Methods: Supports call hierarchy for all defined functions and methods, including those used via UFC.
• Cross-File Analysis: Analyzes calls across different .zen files within the workspace.

Document Symbols

Purpose: Generates a structured outline of all symbols (functions, structs, enums, variables) defined within the current document.

Zen Context: Provides a quick overview of the file's contents:

• Functions, Structs, Enums, Constants: Lists top-level declarations.
• Enum Variants: Includes enum variants as sub-symbols of their respective enum.

Workspace Symbols

Purpose: Allows searching for any symbol (functions, structs, enums, variables) across the entire workspace, including all project files and the standard library.

Zen Context: Facilitates discovery and navigation in large projects:

• Comprehensive Search: Indexes symbols from all .zen files in the project and the entire Zen standard library.
• Quick Access: Enables rapid lookup of any public symbol, regardless of where it's defined.

Code Actions

Purpose: Provides context-sensitive refactoring suggestions and automatic quick-fixes for diagnostics.

Zen Context: Streamlines common Zen development tasks:

• Quick-Fixes:
  • Missing Allocator: Suggests adding get_default_allocator() to constructors of dynamic collections or string operations that require an allocator.
  • String Conversions: Offers fixes for type mismatches involving StaticString and String.
  • Error Handling: Provides boilerplate for Result type error handling (e.g., value ? | Ok(x) { ... } | Err(e) { ... }).
• Refactorings:
  • Extract Variable: Refactors a selected expression into a new local variable.
  • Extract Function: Transforms a selected block of code into a new function.

Rename Symbol

Purpose: Safely renames a symbol (variable, function, struct, etc.) across all its occurrences in the codebase.

Zen Context: Ensures consistency and prevents errors during refactoring:

• Scope-Aware: Distinguishes between local and module-level symbols, applying renames only to the correct scope.
• Cross-File Renaming: Renames module-level symbols across all relevant .zen files in the workspace.

Code Lens

Purpose: Provides context-sensitive, actionable buttons or links directly within the code (e.g., "Run Test").

Zen Context: Offers convenience for common developer workflows:

• Run Tests: Automatically displays a "▶ Run Test" code lens above functions identified as test functions (e.g., test_my_feature, my_feature_test).

Document Formatting

Purpose: Automatically formats the code according to a predefined style guide.

Zen Context: Ensures consistent code style across the project:

• Zen Style Guide: Formats indentation, brace placement, and whitespace according to the Zen language's recommended style.

Conclusion

The Zen LSP implementation is a robust, compiler-backed system that provides comprehensive code intelligence. By understanding and adapting to Zen's unique design principles, it offers a seamless and highly productive development experience, enabling developers to write clean, correct, and efficient Zen code with confidence.