How escalier-lang/escalier works
Project Type and Purpose
• Escalier is a compiler toolchain written in Go.
• It exposes:
– A CLI (cmd/escalier) for building and formatting .esc files.
– An LSP server (cmd/lsp-server) implementing the Language Server Protocol for editor integrations.
– A VSCode extension (packages/vscode-escalier) that leverages the LSP server.
– A browser-based playground (playground/…) that runs the compiler/LSP in WebAssembly and provides an interactive UI.
File Structure
Top-level directories:
• cmd/ — entry-points:
– escalier (CLI)
– lsp-server (Language Server)
• internal/ — core compiler libraries, organized by responsibility:
– parser/lexer → builds AST
– ast/visitor → AST manipulation
– checker/ → type checking & error reporting
– codegen/ → JavaScript output + source maps
– compiler/ → high-level driver/tests/examples
– type_system/ & provenance/ → auxiliary
• packages/vscode-escalier/ — VSCode plugin
• playground/ — React + Vite playground with LSP client + Go→WASM
• fixtures/ — test inputs/expected outputs
README
• Confirms it’s “Next version of the Escalier compiler written in Go.”
• Mentions tests, snapshots, coverage.
Main Components & Their Interactions
a. CLI (escalier)
– Input: .esc source files
– Pipeline: lexer → parser → AST → checker → codegen → .js + .map
– Output: JavaScript + source maps, .d.ts definitions
b. LSP Server
– Embeds the same pipeline for on-the-fly parsing/analysis
– Exposes LSP methods: hover, diagnostics, completions
c. VSCode Extension
– Activates on .esc files
– Spawns or connects to local LSP server over stdio/tcp
– Displays diagnostics, code actions
d. Web Playground
– UI: React/Vite app in browser
– Starts a WebWorker embedding the LSP server compiled to WASM via wasm_exec.js
– Uses a custom LSP client library (playground/src/lsp-client)
– Two-way messaging between UI and WebWorker for live feedback
e. Internal Libraries
– Shared by CLI, LSP, Playground WASM, compiler tests/examples
Architectural Patterns & Design Principles
• Modular layering: clear separation between parsing, checking, codegen.
• Re-use via internal libraries—no code duplication between CLI, LSP, WASM.
• LSP abstraction isolates transport (stdio vs WebWorker) from language logic.
• Test fixtures validate each stage (parser snapshots, codegen snapshots).
Detailed Component List
• Entry-Points:
– cmd/escalier (Go CLI)
– cmd/lsp-server (Go LSP)
– packages/vscode-escalier (TS VSCode extension)
– playground/src (TS React App)
• Compiler Core Modules (internal/*):
– parser/lexer
– internal/ast
– internal/checker
– internal/codegen
– internal/compiler
• Transports:
– stdio/TCP (LSP)
– postMessage (WebWorker)
• Outputs:
– .js, .map, .d.ts files (file system)
– Diagnostics & features in editors