jade — a Language Server for Crystal

jade is Language Server Protocol support for the Crystal programming language: a thin VS Code client plus a native Crystal LSP server, shippable as a Docker container.

The server engine is a fork of skuznetsov/adamas-lang — the "Crystal V2" compiler project — vendored as a git subtree under server/. Its LSP server is the most mature part of that project and gives jade a full feature set out of the box:

hover · go-to-definition · find references · completion · signature help · rename · document symbols · workspace symbols · formatting (token-based, faster than crystal tool format) · diagnostics · semantic tokens · inlay hints · folding ranges · call hierarchy · code actions

Repository layout

jade/
├── package.json                 # VS Code extension manifest
├── client/src/extension.ts     # client entry — launches the server (docker|binary)
├── server/                      # ← adamas-lang fork (git subtree, squashed)
│   ├── src/lsp_main.cr          # LSP server entry point
│   ├── src/compiler/lsp/        # LSP implementation
│   ├── spec/lsp/                # LSP regression suite
│   ├── build_lsp.sh             # builds server/bin/adamas_lsp
│   └── Dockerfile               # multi-stage image build (jade:latest)
└── ROADMAP.md                   # project history + roadmap

Prerequisites

Build & test

# Server binary (fast dev loop)
cd server && ./build_lsp.sh            # → server/bin/adamas_lsp

# LSP regression suite
cd server && crystal spec spec/lsp

# Docker image (used by the default "docker" runtime)
npm run docker:build                   # → jade:latest + jade:<version>
# Slim runtime (~150 MB vs ~1.1 GB full Crystal base): Ubuntu + libyaml/libpcre2
# + the vanilla Crystal stdlib on CRYSTAL_PATH for prelude resolution.

# VS Code client
npm install && npm run compile

Smoke-test the server without an editor by piping a framed initialize request to server/bin/adamas_lsp (or docker run --rm -i jade:latest) — it responds with its capabilities and exits cleanly on shutdown/exit.

Running in VS Code

Open this repo in VS Code, npm install && npm run compile, then F5 to launch an Extension Development Host and open any .cr file.

Settings (jade.*):

• jade.runtime — "docker" (default, runs jade.docker.image) or "binary" (runs jade.server.path, default server/bin/adamas_lsp, resolved against the workspace root).
• jade.docker.mountWorkspace — bind-mount the workspace into the container at the same absolute path so file:// URIs resolve inside the container; needed for whole-project features (cross-file navigation, project-wide diagnostics) in docker mode.
• jade.trace.server — set to "verbose" to watch LSP traffic.
• jade.server.debugLogPath — write the server's structured debug log to a file (never to the stdio JSON-RPC stream).
• jade.server.env — extra env vars for the server process (e.g. LSP_DEBOUNCE_MS, LSP_COMPILER_FLAGS, LSP_BACKGROUND_INDEXING); applied in both runtimes.

See docs/RELEASING.md for the release/publishing process.

Upstream

Pull upstream engine updates with:

git subtree pull --prefix=server https://github.com/skuznetsov/adamas-lang.git main --squash

Upstream docs live inside server/: README.md (project vision & bootstrap status), ARCHITECTURE.md, LSP_COVERAGE.md, CLAUDE.md (dev conventions). The adamas compiler pipeline is beta; jade only relies on its LSP server.

License

MIT — matching both the original jade scaffolding and adamas-lang.