How elfrask/cls works
Purpose and Entrypoints
CLS 2.0 is a Rust workspace implementing a modular CLS language toolchain: parse/type-check source, interpret it, package applications, and provide editor integration. User-facing binaries are clx (development CLI, including LSP) and clxr (runtime executor): nodos/clx/src/main.rs, nodos/clxr/src/main.rs.
Language Core: Frontend and AST
cls-core is the pure language layer, deliberately separated from host filesystem/I/O. Source text is tokenized, parsed, and represented as an AST by cls-core/src/frontend/lexer.rs, cls-core/src/frontend/parser.rs, and cls-core/src/frontend/ast.rs. Shared diagnostics and source-span reporting are defined under cls-core/src/error/diagnostic.rs.
Semantic Middleware Pipeline
Parsed ASTs pass through name resolution, static type checking, and optimization before execution or output generation. These stages are cls-core/src/middleware/resolver.rs, cls-core/src/middleware/typeck.rs, and cls-core/src/middleware/optimizer.rs. This establishes the central control flow: .clsx source → frontend AST → semantic passes → runtime interpreter or backend.
Backends and Build Outputs
The core exposes alternate AST consumers: JSON serialization/dumps and a planned WASM compilation target, rooted at cls-core/src/backend/json.rs and cls-core/src/backend/wasm.rs. CLI build behavior is hosted in nodos/clx/src/subcommands/build.rs; WASM/.clbin generation is explicitly future-facing rather than the primary current execution path.
Runtime Execution Model
cls-runtime executes ASTs with a tree-walking interpreter. Runtime values, lexical/scoped bindings, garbage collection, intrinsics, and error reporting are separated into cls-runtime/src/interpreter.rs, cls-runtime/src/value.rs, and cls-runtime/src/environment.rs. The runtime does not own direct host I/O; host capabilities are supplied through its API/FFI boundary in cls-runtime/src/host_api.rs and cls-runtime/src/ffi.rs.
Modules, Standard Library, and Security
Imports resolve through runtime module resolution and bundled CLS interface definitions: cls-runtime/src/resolver.rs, cls-runtime/src/modules.rs, and cls-runtime/clsi/. Built-in math, JSON, async, and primitive functionality live under cls-runtime/src/stdlib/. Sandbox policy and protocol-based virtual filesystem access are runtime boundaries in cls-runtime/src/sandbox.rs, cls-runtime/src/vfs/resolver.rs, and cls-runtime/src/vfs/security.rs.
Host Nodes and External Services
clx supplies desktop integrations that core/runtime intentionally exclude: command dispatch, filesystem and HTTP modules, package actions, and LSP. Key boundaries are nodos/clx/src/subcommands/run.rs, nodos/clx/src/modules/fs.rs, nodos/clx/src/modules/http.rs, and nodos/clx/src/lsp.rs. The LSP communicates over stdio or TCP; filesystem and network access are mediated by these node-provided modules and runtime sandbox permissions. Project manifests/configuration are parsed by cls-core/src/config/manifest.rs, with cls.json serving as the project entry/configuration contract.
Main entry points: interpreter.rs Tree-walking interpreter · resolver.rs Semantic pipeline · main.rs clx development CLI · parser.rs Lexer, parser & AST
Components 19
Language Core
Pure parsing, diagnostics, and semantic processing.
- Project manifest · Parses the cls.json project contract.
cls-core/src/config/manifest.rs - Lexer, parser & AST · Converts source text into an AST.
cls-core/src/frontend/parser.rs - Diagnostics · Shared source spans and diagnostics.
cls-core/src/error/diagnostic.rs - Semantic pipeline · Resolves names, checks types, and optimizes ASTs.
cls-core/src/middleware/resolver.rs - JSON backend
cls-core/src/backend/json.rs - WASM backend · Future-facing WASM and .clbin output path.
cls-core/src/backend/wasm.rs
Runtime
AST execution and controlled host capabilities.
- Tree-walking interpreter
cls-runtime/src/interpreter.rs - Values & environments · Runtime values and lexical scoped bindings.
cls-runtime/src/environment.rs - Host API & FFI · Supplies host capabilities without direct runtime I/O.
cls-runtime/src/host_api.rs - Modules & CLS interfaces · Resolves imports and bundled interface definitions.
cls-runtime/src/resolver.rs - Standard library · Math, JSON, async, and primitive functionality.
- Sandboxed VFS · Enforces policy for protocol-based filesystem access.
cls-runtime/src/sandbox.rs
Host Nodes
User-facing CLI, runtime launcher, and editor integration.
- clx development CLI · Dispatches development commands, packages, and host modules.
nodos/clx/src/main.rs - Run command
nodos/clx/src/subcommands/run.rs - Build command · Drives alternate build outputs.
nodos/clx/src/subcommands/build.rs - Filesystem & HTTP modules · Host-provided filesystem and network capabilities.
nodos/clx/src/modules/fs.rs - Language server · Serves LSP over stdio or TCP.
nodos/clx/src/lsp.rs - clxr runtime executor
nodos/clxr/src/main.rs
Other components
- .clsx source
Connections 23
- .clsx source → Lexer, parser & AST: tokenize / parse
- Lexer, parser & AST → Diagnostics: source errors
- Lexer, parser & AST → Semantic pipeline: AST
- Semantic pipeline → Diagnostics: semantic errors
- Semantic pipeline → Tree-walking interpreter: checked AST
- Semantic pipeline → JSON backend: serialize
- Semantic pipeline → WASM backend: compile target
- Tree-walking interpreter → Values & environments: evaluates with
- Tree-walking interpreter → Modules & CLS interfaces: resolves imports
- Modules & CLS interfaces → Standard library: loads built-ins
- Tree-walking interpreter → Host API & FFI: requests capabilities
- Host API & FFI → Sandboxed VFS: permission-controlled access
- clx development CLI → Run command: dispatches
- clx development CLI → Build command: dispatches
- clx development CLI → Language server: serves
- Run command → Lexer, parser & AST: loads source
- Run command → Tree-walking interpreter: runs
- Build command → JSON backend: emits
- Build command → WASM backend: future output
- Filesystem & HTTP modules → Host API & FFI: implements host API
- clx development CLI → Filesystem & HTTP modules: provides
- clxr runtime executor → Tree-walking interpreter: executes
- Project manifest → clx development CLI: project configuration