# escalier-lang/escalier architecture

> Architecture diagram of the GitHub repository escalier-lang/escalier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/escalier-lang/escalier
- Repository: https://github.com/escalier-lang/escalier

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Points
    subgraph "Entry Points"
        CLI["CLI (cmd/escalier)"]:::entry
        LSP["LSP Server (cmd/lsp-server)"]:::entry
        VSCode["VSCode Extension"]:::frontend
    end

    %% Playground Components
    subgraph "Playground"
        PlaygroundUI["Playground UI"]:::frontend
        LSPClient["LSP Client Library"]:::frontend
        PlaygroundWorker["Playground Worker (WASM)"]:::entry
    end

    %% Transports
    subgraph "Transports"
        Stdio["stdio/TCP"]:::transport
        PostMsg["postMessage"]:::transport
    end

    %% Compiler Core Modules
    subgraph "Compiler Core"
        Parser["Parser (internal/parser)"]:::core
        AST["AST (internal/ast)"]:::core
        Checker["Checker (internal/checker)"]:::core
        Codegen["Codegen (internal/codegen)"]:::core
        CompilerLib["Compiler Driver (internal/compiler)"]:::core
        TypeSys["Type System (internal/type_system)"]:::core
        Provenance["Provenance (internal/provenance)"]:::core
    end

    %% Outputs
    FS[".js/.map/.d.ts files"]:::storage

    %% Connections: CLI
    CLI -->|invokes| CompilerLib
    CLI -->|builds via| Parser

    %% Connections: LSP Server
    VSCode -->|launches| Stdio
    Stdio -->|connects to| LSP
    LSP -->|invokes| CompilerLib
    LSP -->|parses via| Parser

    %% Playground Flow
    PlaygroundUI -->|uses| LSPClient
    PlaygroundUI -->|sends messages via| PostMsg
    LSPClient -->|communicates via| PostMsg
    PostMsg -->|to worker| PlaygroundWorker
    PlaygroundWorker -->|invokes| CompilerLib
    PlaygroundWorker -->|parses via| Parser

    %% Core pipeline
    Parser -->|produces AST| AST
    AST -->|type checks| Checker
    Checker -->|generates code| Codegen
    Codegen -->|writes files| FS

    %% Click Events
    click CLI "https://github.com/escalier-lang/escalier/blob/main/cmd/escalier/main.go"
    click LSP "https://github.com/escalier-lang/escalier/blob/main/cmd/lsp-server/main.go"
    click VSCode "https://github.com/escalier-lang/escalier/tree/main/packages/vscode-escalier/"
    click PlaygroundUI "https://github.com/escalier-lang/escalier/tree/main/playground/src/"
    click PlaygroundWorker "https://github.com/escalier-lang/escalier/blob/main/playground/src/user-worker.ts"
    click LSPClient "https://github.com/escalier-lang/escalier/tree/main/playground/src/lsp-client/"
    click Parser "https://github.com/escalier-lang/escalier/tree/main/internal/parser/"
    click AST "https://github.com/escalier-lang/escalier/tree/main/internal/ast/"
    click Checker "https://github.com/escalier-lang/escalier/tree/main/internal/checker/"
    click Codegen "https://github.com/escalier-lang/escalier/tree/main/internal/codegen/"
    click CompilerLib "https://github.com/escalier-lang/escalier/tree/main/internal/compiler/"
    click TypeSys "https://github.com/escalier-lang/escalier/tree/main/internal/type_system/"
    click Provenance "https://github.com/escalier-lang/escalier/tree/main/internal/provenance/"

    %% Styles
    classDef entry fill:#D0E8FF,stroke:#0366D6;
    classDef core fill:#E0F8E0,stroke:#228B22;
    classDef frontend fill:#FFF4C1,stroke:#DAA520;
    classDef transport stroke-dasharray: 5 5,stroke:#888;
    classDef storage fill:#F0F0F0,stroke:#999,stroke-width:2px;
```
