cel-rs

Documentation

Component	Documentation
Languages	CEL language guide · Adam language guide
Live presentation	Adam slides · Authoring and preview
CEL libraries	cel-rs · Runtime · Parser · Macros · Standard library
Adam libraries	Property-model runtime · Language · Web UI
Adam tools	Formatter · Language server · VS Code extension
Applications	Begin architecture · EZ Adam design

The Docs workflow builds and checks the guides, component APIs, and live slides on pull requests, then publishes the site on pushes to main. Newly added pages become available after their changes reach main and the Pages deployment finishes.

A stack-based runtime for developing domain specific languages, paired with a recursive-descent parser for CEL (Common Expression Language) and a proc-macro crate for compile-time CEL validation. See docs/VISION.md for the long-term direction behind each crate in this workspace.

Status: this project has not been released and has no clients yet. It is in active development and the API may change at any time.

Workspace layout

Crate	Role
cel-rs	Root façade crate — re-exports the crates below
cel-runtime	Core stack-based runtime; all evaluation and stack machinery
cel-parser	Recursive-descent CEL parser, lexer, and error types
cel-rs-macros	Proc-macro crate for compile-time CEL expression validation
cel-euclid	Opt-in f64 Euclid records and affine geometry; optional Adam cell types
adam-rs	Multi-way constraint system for property models
adam-lang	DSL that expresses adam-rs constraint systems as source text
adam-lsp	Language server for adam-lang
begin	Dioxus-based UI application for developing property models
editors/vscode-adam-lang	VS Code extension: syntax highlighting and live diagnostics for adam-lang, via adam-lsp
xtask	Repository automation and maintenance tasks

Getting started

Prerequisites

• Rust (stable), installed via rustup

VS Code worktree tasks

The repository does not define worktree: tasks. Worktree creation, removal, and branch pruning live in each contributor's VS Code user tasks (Tasks: Open User Tasks) with their scripts under ~/.vscode/scripts, so they work across repositories. Whatever tooling you use, create worktrees under .claude/worktrees/ on a worktree-<name> branch.

Clone and build

git clone https://github.com/stlab/cel-rs.git
cd cel-rs
git config core.hooksPath .githooks   # activate the shared git hooks (one-time)
cargo build --workspace
cargo test --workspace

Add cel-rs to your project

cargo add cel-rs

A first expression

use cel_rs::runtime::Segment;

// Build a segment that takes a u32 and a &str as arguments.
let segment = Segment::<(u32, &str)>::new()
    .op1r(|s| {
        let r = s.parse::<u32>()?;
        Ok(r)
    })
    .op2(|a, b| a + b)
    .op1(|r| r.to_string());
assert_eq!(segment.call((1u32, "2")).unwrap(), "3");

This builds a small pipeline over cel-runtime's typed stack: parse the &str into a u32 (fallibly, via op1r), add it to the u32 argument, then format the result. cel-parser and cel-rs-macros cover the other two ways to produce a segment: parsing CEL source at runtime, and validating/compiling CEL expressions at compile time. See src/lib.rs for one example of each.

Development

Optional geometry

Install cel_euclid::install(&mut lookup) alongside cel_std::install to use the complete geometry signature table. For Adam, enable cel-euclid/adam and register cell types with cel_euclid::register_adam_types(&mut types). The web UI, LSP, and runnable book support configure equivalent environments; adam-lang itself remains geometry-independent.

cargo run -p cel-euclid --features adam --example adam_geometry
cargo test -p cel-euclid --all-features

The actual crop/straighten sheet fits arbitrary affine geometry with general operations and typed IIFEs, preserves source aspiration through Adam self-reference, and derives a fixed-overlay presentation. Its numerical policy lives in CEL, not a Rust fitting helper. The pan/zoom sheet demonstrates graph policy. The live graph uses an Adam-owned model and a shared Dioxus proposal/approval bridge in Begin and the book; see graph view ownership and verification.

See CLAUDE.md for the full command reference (build, test, lint, sanitizers) and repository conventions, including the requirement to work in a separate git worktree for any change.

begin: Spectrum Web Components bundle

begin/assets/swc.js is a single bundle (elements + Spectrum 2 theme tokens + the zoom-control icons) produced by esbuild from real npm packages. It's committed like every other vendored asset, so cloning and building begin needs no Node/npm setup.

Node.js + npm are only needed if you're updating the Spectrum version or otherwise need to regenerate begin/assets/swc.js:

cargo xtask build-js

or directly:

cd begin
npm ci
npm run build

Commit the regenerated begin/assets/swc.js along with any begin/package.json/ begin/package-lock.json changes. See docs/superpowers/specs/2026-07-11-begin-spectrum2-theme-tokens-design.md for why this needs to be one compiled bundle rather than separate vendored/live files.

adam-lang: VS Code extension

editors/vscode-adam-lang is a VS Code extension providing syntax highlighting and live diagnostics for .adm2 (adam-lang) files, backed by the adam-lsp language server.

To install it locally:

cargo install --path adam-lsp
cd editors/vscode-adam-lang
npm ci
npm run package
npm run install-extension

Both the cargo install and the three npm steps are also available as a single VS Code task, Install adam-lsp + Extension (Local), runnable from the Command Palette's "Tasks: Run Task" with either the repository root or editors/vscode-adam-lang open. On Windows, this task builds/packages from a copy of the workspace staged outside any git worktree (under %LOCALAPPDATA%\cel-rs\adam-lsp-install), since installing directly from a worktree leaves the running LSP binary/extension referencing files inside it, which blocks git worktree remove until the extension is uninstalled — a Windows-only file-locking issue. On macOS/Linux, where that lock doesn't occur, use Install adam-lsp + Extension (Local, in-worktree, macOS/Linux) instead, which runs the four steps above directly. See editors/vscode-adam-lang/README.md for the full Extension Development Host walkthrough and troubleshooting notes.