Skip to content
nixptPublic

About

Crush CAST IR + tree-sitter grammar + polyglot language walkers (standalone, zero runtime deps)

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

1,568 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Crush AST Banner

Crush Logo Crush AST

Polyglot Intermediate Representation & Toolchain

License Rust Version

crushlang.org ยท Language Guide


CI Crush is a capability-based, polyglot programming language and virtual runtime. This repository hosts the standalone Crush implementation: providing the CAST intermediate representation, tree-sitter grammar, polyglot walkers, compiler frontend, VM runtime, package manager, and installer.

๐Ÿ‘‰ crushlang.org for the landing page and a live example, or docs.crushlang.org for the full language guide (syntax, capability system, polyglot programming, stdlib, CAST/CASM, worked examples).

๐Ÿ“ฆ Install

cargo install crush-lang-sdk    # crush, crushc, crush-run, crush-repl, crush-compile, crush-diff, crush-debug

Not cargo install crush โ€” the crush crate on crates.io is an unrelated project. The toolchain is published as crush-lang-sdk (plus crush-pkg, crush-installer, and the library crates). There is no crush-ast crate; that's this repository's name.

Prebuilt binaries. Starting with v0.9.0, every vX.Y.Z tag has a GitHub pre-release with a Linux x86_64 tarball (crush, crushc, crush-run, crush-compile, crush-repl, crush-debug, crush-pkg, crush-gui), the browser runtime (crush-web-<ver>-pkg.tar.gz) and SHA256SUMS, so cargo binstall crush-lang-sdk downloads instead of compiling. (Pre-releases until 1.0: see docs/planning/RELEASE-1.0-CRITERIA.md.)

Updating. crush update (= crush-installer update; needs cargo install crush-installer) replaces the binaries of a tarball/crush-installer install with the newest release: it checks the download against the release's SHA256SUMS before extracting and swaps every binary in with an atomic rename (a failure leaves the old set), so it can replace the running crush. Linux x86_64 only; a cargo install is refused โ€” update that with cargo install crush-lang-sdk.

crush update --check            # exit 0 = up to date, 10 = update available; writes nothing
crush update                    # newest release; never downgrades
crush update --version 0.9.0    # pin (the only way to downgrade)
crush update --dir ~/opt/crush  # default: crush's own dir if crush-installer manages it, else ~/.crush/bin

File types and editors. So file managers, file(1) and editors recognise .crush, .cast.json, .casm, .cvm1, capsule.toml and the rest: crush-installer install --desktop-integration (opt-in) registers the MIME types and magic(5) rules, and contrib/ has Vim/Neovim, Helix, Emacs and Zed support plus the tree-sitter queries.

All crates are released together at the workspace version in Cargo.toml.

Command What it does
crush / crush repl interactive REPL
crush run FILE run a program: .crush, CAST (.cast.json/.castb), CASM (.casm), .cvms, .cvm1
crush build FILE compile to .cvm1 (--emit casm|cvms|cast|ast for the other forms)
crush cast CMD FILE CAST tools: validate, pack, unpack, format, diff
crush debug FILE --step --inspect breakpoints by source line, step, watch, print (grant-gated)
crush gui run FILE --ui run a program that draws a window with ui.* (needs crush-gui)
crush doctor check the host runtimes polyglot blocks need
crush update [--check] update to the newest GitHub release (needs crush-installer)

๐Ÿ—๏ธ Repository Structure

crates/
โ”œโ”€โ”€ crush-errors/         # Unified error types (leaf crate)
โ”œโ”€โ”€ crush-cast/           # CAST โ€” Crush Abstract Syntax Tree IR
โ”œโ”€โ”€ crush-cosm/           # COSM โ€” Crush Object Semantic Model: Kind declarations, C3, validation (structs/impl/trait/@kind)
โ”œโ”€โ”€ crush-caison/         # CAISON (formerly CSON) format + `caison.parse` VM capability
โ”œโ”€โ”€ crush-cson-shim/      # retired `crush-cson` name: re-exports crush-caison
โ”œโ”€โ”€ casm/                 # CASM โ€” Crush Assembly bytecode format
โ”œโ”€โ”€ tree-sitter-crush/    # Tree-sitter grammar for the Crush language
โ”œโ”€โ”€ crush-diagnostics/    # Shared diagnostics/wire-format types
โ”œโ”€โ”€ crush-index/          # Cross-crate symbol/reference index
โ”‚
โ”œโ”€โ”€ crush-walker-core/    # LanguageAdapter trait + shared walker utilities (renamed from walker-core)
โ”œโ”€โ”€ cli/                  # crush-walker โ€” CLI that auto-detects source language and dispatches a walker
โ”œโ”€โ”€ crush-lang-python/    # Python โ†’ CAST (bin: python_walker)
โ”œโ”€โ”€ crush-lang-rust/      # Rust โ†’ CAST (syn-based; refuses what it can't prove exact)
โ”œโ”€โ”€ crush-lang-js/        # JavaScript โ†’ CAST
โ”œโ”€โ”€ crush-lang-go/        # Go โ†’ CAST
โ”œโ”€โ”€ crush-lang-c/         # C โ†’ CAST
โ”œโ”€โ”€ crush-lang-zig/       # Zig โ†’ CAST
โ”œโ”€โ”€ crush-lang-bash/      # Bash โ†’ CAST
โ”œโ”€โ”€ crush-lang-zsh/       # Zsh โ†’ CAST
โ”œโ”€โ”€ crush-lang-wasm/      # WebAssembly walker โ€” parses Wasm modules into CAST IR
โ”œโ”€โ”€ crush-lang-dart/      # Dart โ†’ CAST
โ”œโ”€โ”€ crush-lang-nepali/    # Nepali (Sona) โ†’ CAST
โ”œโ”€โ”€ crush-lang-java/      # Java โ†’ CAST (skeleton)
โ”œโ”€โ”€ crush-lang-custom/    # Custom/user-defined language adapter scaffold
โ”‚
โ”œโ”€โ”€ crush-frontend/       # Crush language parser, semantic analyzer, optimizer, and CASM compiler
โ”œโ”€โ”€ crush-lang-sdk/       # Rust SDK for hosting the CVM1 runtime (bins: crush, crushc, crush-run, crush-compile, crush-repl, crush-diff, crush-debug)
โ”œโ”€โ”€ crush-vm/             # CVM1 bytecode assembler, disassembler, and sandboxed interpreter (incl. polyglot exec + capability gates)
โ”œโ”€โ”€ crush-vm-capi/        # C API shared library for embedding CrushVM in C/C++ programs
โ”œโ”€โ”€ crush-vm-py/          # Python extension module (PyO3) exposing the canonical CVM1 VM (outside the workspace)
โ”œโ”€โ”€ crush-jit/            # Cranelift-based JIT backend (native execution tier)
โ”œโ”€โ”€ crush-aot/            # AOT: CASM โ†’ Rust (rustc) or C (gcc/clang) โ†’ native .so (bins: crush-aotc, crush-walk-run)
โ”œโ”€โ”€ crush-aotc/           # Typed AOT compiler library: CASM โ†’ C source โ†’ shared library (.so)
โ”œโ”€โ”€ crush-ptx/            # CASM โ†’ PTX (NVIDIA GPU assembly) emission backend
โ”œโ”€โ”€ crush-web/            # Browser WebAssembly runtime (outside the workspace; its pkg ships with each tag's pre-release)
โ”œโ”€โ”€ crush-ffi/            # C-ABI plugin interface
โ”œโ”€โ”€ crush-plugin-example/ # Example native plugin built on crush-ffi
โ”œโ”€โ”€ crush-python/         # PyO3 bindings exposing crush-cast to Python
โ”œโ”€โ”€ crush-debugger/       # Debugger engine over crush-vm (breakpoints, step, watch, grant-gated inspection); `crush debug` / `crush-debug`
โ”œโ”€โ”€ crush-lint/           # Static lint pass over CAST/CASM
โ”œโ”€โ”€ crush-macros/         # Proc-macros shared across the workspace
โ”œโ”€โ”€ crush-net/            # Raw TCP/TLS sockets as `tcp.*` capabilities (`--tcp`, `--tcp-listen`)
โ”œโ”€โ”€ crush-tui/            # Terminal UI front-end
โ”œโ”€โ”€ crush-gui/            # Desktop GUI: `ui.*` capabilities on arniko/bliss (`crush gui run`, `--ui`; not a default member, needs fontconfig)
โ”œโ”€โ”€ crush-pkg/            # Package manager โ€” cargo-like build tool for Crush (uses buckets for sandboxed script runtimes)
โ””โ”€โ”€ crush-installer/      # Toolchain installer and uninstaller

๐Ÿš€ Quick Start

Building from Source

You need Rust 1.95 or newer (the MSRV that CI checks; rust-toolchain.toml selects stable). crush-pkg and crush-vm path-depend on nixpt/buckets, so clone it next to this repo first (CI does the same):

git clone https://github.com/nixpt/buckets ../buckets
# Build the core SDK and package manager (`cargo build` alone builds every
# default member; `crush-gui` is left out because it needs `libfontconfig1-dev`)
cargo build -p crush-lang-sdk -p crush-pkg

# Install to ~/.crush using the included installer
cargo run --bin crush-installer -- install --bin-dir target/debug

Running Directly

# Check compiler options
cargo run --bin crushc -- --help

# Run a Crush script directly
cargo run --bin crush-run -- run my-program.crush

A first program, with what it prints (verified against faeb86e8, 2026-10-31):

fn make_counter() {
    let c = 0
    return || {
        c = c + 1
        return c
    }
}
let next = make_counter()
next()
print(next())
2

Capabilities are opt-in per run. The standard library (str.*, math.*, json.*, โ€ฆ) is on by default; everything that touches the host needs a flag (--fs, --net, --tcp, --env, --time, --process, --polyglot, โ€ฆ), and a program that needs an ungranted capability is refused before it runs. crush-run caps FILE shows what a program needs without running it. Raw sockets (tcp.*, crate crush-net) have their own grants: --tcp for outbound client sockets and a separate, stronger --tcp-listen for being a server; --net is HTTP-client only and grants neither.

โš™๏ธ Compilation Pipeline

The Crush pipeline seamlessly converts polyglot source code down to execution-ready bytecode through an interconnected set of stages.

graph TD
    A[Source File<br/>.crush, .py, .rs, .go, .c, .js, .sh, .zig, .wasm] --> B
    B(Walker<br/>Language-specific tree-sitter โ†’ CAST) --> C
    C[CAST<br/>Crush AST โ€” .cast.json / CBOR .castb] --> D
    D(Crush Compiler<br/>crates/crush-frontend) --> E
    E[CASM<br/>Crush Assembly IR โ€” JSON .casm / MessagePack .casmb] --> G
    G[CVM1 bytecode<br/>.cvm1 โ€” assembly text .cvms] --> F
    F((CVM1 VM<br/>Execution))
    
    classDef file fill:#2d3436,stroke:#74b9ff,stroke-width:2px,color:#fff
    classDef process fill:#0984e3,stroke:#74b9ff,stroke-width:2px,color:#fff
    
    class A,C,E,G file
    class B,D,F process
Loading

Every extension, its encoding, version constant and who reads/writes it: docs/FILE-FORMATS.md.

๐ŸŽฎ Examples

examples/crush/ holds 50+ .crush programs, from language-feature smoke tests (arithmetic.crush, control_flow.crush, exception_test.crush, ...) to full self-playing programs written by several different LLMs given the same "learn this language" prompt โ€” two hosted-language interpreters (forth.crush, brainfuck.crush), self-playing games (tictactoe.crush, lights_out.crush, pong.crush, breakout.crush), an IDA*-based 15-puzzle solver (fifteen_puzzle.crush), and Conway's Game of Life. The story behind that particular set โ€” which model wrote what, and the real language constraints/bugs each one hit โ€” is documented in nixpt/awesome-crush.

๐Ÿ“š Documentation

  • The Crush Language Guide (docs.crushlang.org) โ€” language reference, examples, CAST/CASM specifications. Every example in it is run against a pinned crush-ast commit, and its examples/verified/ corpus keeps one small program per language behaviour with its exact output.
  • Comprehensive crate-level documentation is available in the respective crates/*/README.md files.

โš–๏ธ License

Licensed under either of MIT or Apache License 2.0 at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work shall be dual-licensed as above, without any additional terms or conditions.

About

Crush CAST IR + tree-sitter grammar + polyglot language walkers (standalone, zero runtime deps)

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages