Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elfrask/cls/llms.txt

Use this file to discover all available pages before exploring further.

The CLS LSP server (clx lsp) implements the Language Server Protocol over standard JSON-RPC, providing real-time feedback as you write .clsx files. On every document open or change it runs the full Lexer → Parser → NameResolver → TypeChecker pipeline and publishes syntax errors and type diagnostics as underlined squiggles in the editor. Beyond diagnostics it offers completions for keywords, core intrinsics, standard library modules, and every symbol in scope, plus hover documentation drawn from type maps, go-to-definition for functions and variables, and a document symbol list for quick navigation.

​
Starting the Server

clx lsp
  • stdin/stdout mode is the only transport currently implemented. The server reads JSON-RPC messages from stdin and writes responses to stdout. This is the standard transport used by VS Code and most LSP clients.
  • --silent / -s suppresses the startup message ([clx lsp] ready) so that the log output does not interfere with clients that parse stdout.
The server is implemented with tower-lsp and runs on a Tokio async runtime. It is started by the lsp subcommand in nodos/clx/src/subcommands/lsp.rs, which calls crate::lsp::run_server(silent).

​
LSP Capabilities

The server announces the following capabilities during the initialize handshake: 
ServerCapabilities {
  text_document_sync: FULL,
  completion_provider: { trigger_characters: [".", "\"", "/"] },
  hover_provider: true,
}
In addition to the announced capabilities, the server also implements textDocument/definition and textDocument/documentSymbol request handlers. LSP clients that send these requests will receive valid responses, even though the capabilities are not explicitly advertised in the initialize result.

​
Diagnostics

On every textDocument/didOpen and textDocument/didChange event the server runs:
  1. Lexer — tokenizes the document; a lex error produces an immediate error diagnostic.
  2. Parser — builds the AST; a parse error produces an error diagnostic with the source location.
  3. NameResolver — verifies that every identifier is declared before use; name errors become error diagnostics.
  4. TypeChecker — validates type assignments, resolves generics, and checks function call arities; type errors and warnings are published with ERROR or WARNING severity.
The type checker configuration is read from the workspace cls.json (if present). When no manifest exists, the server defaults to check: true, strict: false.

​
Completions

Triggered by any character or explicitly by the ., ", and / trigger characters. General completions (no trigger character):
SourceKind
Functions and variables in the current documentFunction / Variable
Symbols from other open documentsFunction / Variable
CLS keywords (var, function, if, for, return, …)Keyword
Core intrinsics from core.clsi (print, input, len, …)Function
Standard library module names (math, json, fs, http, Lib, async)Module
.clsx filenames found in the workspaceFile
Member completions (triggered by .): When you type math. or obj., the server inspects the identifier before the dot, resolves it through the import map of the current file, and returns the members of the matching type module or struct. Member sources in priority order:
  1. Type definitions loaded from .clsi / .type.json files (matched by import alias)
  2. Runtime module exports (math, json, fs, http)
  3. Struct fields declared in the current document

​
Hover Documentation

On textDocument/hover the server extracts the word under the cursor, searches the loaded type definitions, and renders a Markdown snippet: 
**print**  `print(val: Any)`
_core_

Imprime valores en consola
For functions with annotations the hover content expands to include parameter docs (- \name type — description`), return documentation (→ …`), and deprecation notices (strikethrough).

​
Go-to-Definition

On textDocument/definition the server parses the current document, finds the symbol under the cursor in the built symbol table (functions, variables, and parameters at the top-level scope), and returns the source location as a Location pointing to the declaration span.

​
Document Symbols

On textDocument/documentSymbol (bound to Ctrl+Shift+O in VS Code) the server returns a flat list of all top-level functions, variables, and parameters with their kind and source range. This powers the Go to Symbol quick picker.

​
VS Code Integration

The extension connects to clx lsp automatically when lspServer is enabled in .vscode/settings.json: 
{
  "cls.options.unnestableFeatures": {
    "lspServer": true,
    "useStaticTypes": true,
    "useMapClsi": true
  }
}
The extension client (client/extension.js) launches clx lsp as a child process using the stdin/stdout transport provided by vscode-languageclient ^10.1.0.
The LSP server loads type definitions from the embedded builtin .clsi files (always available) and optionally from a clsi/ directory at the workspace root (workspace override). Run clx maptype . --watch alongside the LSP server so that .type.json files for your own source files stay up to date. The server reads these via type_defs::load_all_type_definitions during the initialize handshake.

​
Type Definitions

On startup the server calls type_defs::load_all_type_definitions(workspace_root), which:
  1. Loads the seven builtin .clsi definitions embedded in the clx binary:
    • core — intrinsics (print, input, len, type, now, exit, sleep, throw, …)
    • math — math module
    • json — JSON module
    • fs — filesystem module
    • http — HTTP module
    • Lib — compiled library loader
    • async — async module
  2. Scans <workspace_root>/clsi/*.clsi and merges any workspace-provided definitions, allowing projects to override or extend the builtins.
The resulting HashMap<String, TypeModule> is shared across all document handlers for the lifetime of the server session.

​
Error Reporting

Diagnostics carry precise source locations derived from the Span type (start_line, start_col, end_line, end_col, all 1-indexed). The server converts these to 0-indexed LSP Position values before publishing. When a raw error string contains a line:col pattern (from ClsError::extract_line_col), the server parses it to produce a point-range diagnostic even for errors that do not carry a structured span.

Build docs developers (and LLMs) love

Get started for freeTalk to us