monkey-rust-compiler

A compatibility-focused Monkey compiler + VM implementation in Rust.

Behavior is locked against:

• COMPATIBILITY.md
• PROTOCOL.md

Build

cargo build

CLI usage

Usage: monkey [run <path> | bench <path> | --tokens <path> | --ast <path>]

Examples:

cargo run -- run examples/hello.monkey
cargo run -- --tokens examples/control_flow.monkey
cargo run -- --ast examples/closures.monkey
cargo run --release -- bench bench/b1.monkey

REPL

Start REPL:

cargo run --
# or
cargo run -- repl

REPL meta commands:

• :help
• :tokens [input]
• :ast [input]
• :env
• :quit
• :exit

The REPL session is stateful across inputs.

Tests and quality gates

cargo test
make check
make compat

Golden updates are explicit only:

make goldens-update
# or
UPDATE_GOLDENS=1 cargo test compat_

Java parity conformance

Step 21 adds Java↔Rust parity checks:

make conformance
# or
MONKEY_JAVA_REF_CMD="java -jar path/to/ref.jar" cargo test conformance_ -- --nocapture

See docs/conformance.md for command contract, fixture layout, and mismatch triage.

Release readiness

make release-check

Benchmarks

make bench
# or pass a compiled monkey binary path:
./scripts/bench.sh ./target/release/monkey

Windows (cmd) benchmark runner:

cargo build --release
scripts\bench.cmd

Rust vs Java comparison on Windows:

set MONKEY_JAVA_REF_CMD=java -jar C:\path\to\monkey-java.jar
scripts\bench.cmd

Optional benchmark environment variables:

set MONKEY_RUST_BIN=C:\path\to\monkey.exe
set BENCH_ROUNDS=5
set BENCH_FILTER=b4
scripts\bench.cmd

Repository layout

• src/ runtime/compiler/parser/CLI implementation
• tests/ unit, integration, compatibility goldens, and conformance parity harness
• examples/ runnable Monkey programs
• bench/ benchmark programs
• scripts/ developer and CI helper scripts

Compatibility note

Do not change protocol-visible behavior without validating against COMPATIBILITY.md, PROTOCOL.md, compatibility goldens, and conformance parity checks.