cellang 0.7.0

Interpreter for the CEL expression language
Documentation
# Cellang

Cellang is an implementation of the [CEL](https://cel.dev/) language interpreter in Rust.

## Motivation

Motivation behind this project is to provide a way to evaluate CEL expressions in Rust, while allowing
easier way to provide custom functions. This project is built for [BountyHub](https://bountyhub.org) project,
but is open-source and can be used by anyone.

There is a great rust project called [CEL Interpreter](https://crates.io/crates/cel-interpreter) which I initially used.

However, I found that the project is not flexible enough for my needs. I needed to be able to:
- Inspect the syntax tree during parsing for IDE/LSP support
- Add slightly more complex functions on types
- Robust error recovery for incomplete expressions

Therefore, the library exposes lower-level primitives that would allow you to do that.

## Parser Architecture

Cellang uses a **Rowan-based parser** with a clean semantic boundary:

1. **Lexer** (`lexer`) - Tokenizes source text into a stream of tokens
2. **Rowan Parser** (`parser::parse`) - Builds a lossless concrete syntax tree (CST)
   - Preserves whitespace, comments, error tokens
   - Supports error recovery for IDE/LSP workflows
3. **HIR Lowering** (`parser::lower`) - Converts CST to high-level intermediate representation
   - Strips away syntax noise (grouping parens, etc.)
   - Owned data structure suitable for semantic analysis
4. **Type Checking** (`parser::type_check`) - Validates types and builds typed expression graph
5. **Interpreter** (`parser::eval`) - Evaluates expressions against a runtime

Use only the canonical parser facade paths (`cellang::parser::*`) for parse/lower/type-check/eval pipeline access.

The separation between CST (syntax layer) and HIR (semantic layer) provides:
- **CST**: Perfect for IDE tooling (preserves all source details, supports incremental parsing)
- **HIR**: Perfect for semantic analysis (clean structure, no parser lifetimes)

## Getting started

This library aims to be ergonomic without hiding the lower-level building blocks that make CEL powerful. The typical workflow is:

1. Build a `Runtime` with variables, declared types, and native functions.
2. Evaluate expressions against that runtime (or child runtimes that inherit the same environment).

```rust
use cellang::types::{FunctionDecl, OverloadDecl, Type};
use cellang::{Runtime, Value};

fn main() -> miette::Result<()> {
    let mut builder = Runtime::builder();
    builder.set_variable("first_name", "Ada")?;
    builder.set_variable("last_name", "Lovelace")?;
    builder.set_variable("roles", vec!["admin", "analyst"])?;

    let mut decl = FunctionDecl::new("full_name");
    decl.add_overload(OverloadDecl::new(
        "full_name_string_string",
        vec![Type::String, Type::String],
        Type::String,
    ))?;
    builder.add_function_decl(decl)?;
    builder.register_function("full_name", |first: String, last: String| {
        format!("{first} {last}")
    })?;

    let runtime = builder.build();
    let value = runtime.eval("full_name(first_name, last_name)")?;
    assert_eq!(value, Value::String("Ada Lovelace".into()));

    let is_admin = runtime.eval("'admin' in roles")?;
    assert_eq!(is_admin, Value::Bool(true));
    Ok(())
}
```

## Runnable Examples

The examples in [examples](examples) are written as user documentation and are also executed by `cargo test`, so they stay in sync with the public API.

Run all default-feature examples with:

```bash
cargo test -p cellang --examples
```

Run the derive-backed example with:

```bash
cargo test -p cellang --features derive --example user_role_derive
```

Good starting points:

- [examples/getting_started.rs]examples/getting_started.rs shows variables, scoped child runtimes, function declarations, native function registration, and error handling.
- [examples/policy_rules.rs]examples/policy_rules.rs shows map-backed request/resource data and policy expressions that can be owned outside Rust code.
- [examples/typed_environment.rs]examples/typed_environment.rs shows typed environment metadata, compile-time validation, typed AST serialization, and runtime evaluation.
- [examples/create_function.rs]examples/create_function.rs focuses on registering custom functions as both functions and receiver-style methods.
- [examples/env_snapshot.rs]examples/env_snapshot.rs shows serializing an `Env` so rule metadata can be cached and reused.
- [examples/user_role_derive.rs]examples/user_role_derive.rs shows the optional `derive` feature for structured data.

### Advanced Examples

For larger flows, prefer the checked examples over copying README snippets. [examples/typed_environment.rs](examples/typed_environment.rs) demonstrates explicit type metadata and compile-time rule validation, while [examples/user_role_derive.rs](examples/user_role_derive.rs) demonstrates the optional `derive` feature for strongly typed Rust structs.

## WebAssembly

Cellang can be compiled to `wasm32-unknown-unknown` behind the optional `wasm` feature. The bindings in [src/wasm.rs](crates/cellang/src/wasm.rs) expose an `evaluateExpression` helper and a reusable `WasmRuntime` class. Build the WebAssembly artifact with:

```bash
cargo build -p cellang --features wasm --target wasm32-unknown-unknown
```

For projects that expect JavaScript glue code, run `wasm-pack build crates/cellang --features wasm --target web` to generate the `.wasm` binary plus the corresponding JS module. JavaScript callers can then evaluate expressions provided that the environment is a JSON-serializable object:

```javascript
import { evaluateExpression, WasmRuntime } from "cellang";

const result = await evaluateExpression("users.exists(u, u == name)", {
    users: ["alice", "bob"],
    name: "alice",
});

const runtime = new WasmRuntime({ greeting: "hello" });
const jsValue = runtime.evaluate("greeting.upperAscii() == 'HELLO'");
```

Both exports accept any value that `serde_wasm_bindgen` can convert (objects, arrays, scalars). Additional per-evaluation variables can be merged via `runtime.withVariables({...})`, which builds a scoped child runtime without mutating the original instance.