Initial commit: WAFER (WebAssembly Forth Engine in Rust)

Optimizing Forth 2012 compiler targeting WebAssembly with IR-based compilation pipeline, multi-typed stack inference, subroutine threading, and JIT/consolidation modes. Rust kernel with ~35 primitives and Forth standard library for core/core-ext word sets.
2026-03-29 22:14:53 +02:00
commit 683281363d
33 changed files with 5084 additions and 0 deletions
@@ -0,0 +1,92 @@
+# WAFER
+
+**WebAssembly Forth Engine in Rust**
+
+An optimizing Forth 2012 compiler targeting WebAssembly.
+
+## Goals
+
+- **Full Forth 2012 compliance** -- all word sets, 100% test suite pass rate
+- **Optimizing compiler** -- constant folding, inlining, peephole optimization, stack-to-local promotion
+- **Multi-typed stack** -- type inference uses WASM's native typed stack when possible, memory fallback for dynamic cases
+- **Self-hosting** -- minimal Rust kernel (~35 primitives), everything else written in WAFER Forth
+- **Dual mode** -- JIT for interactive development, consolidation recompilation into a single optimized WASM module
+
+## Architecture
+
+```
+Forth Source -> Outer Interpreter -> IR (with type inference) -> Optimization -> WASM Codegen
+```
+
+- **Subroutine threading** via WASM function tables
+- **JIT mode**: each new word compiles to a separate WASM module
+- **Consolidation mode**: recompile all words into a single module with direct calls
+- **IR-based pipeline** enables optimization passes before WASM emission
+
+## Building
+
+```bash
+cargo build --workspace
+```
+
+## Running
+
+```bash
+# Interactive REPL
+cargo run -p wafer
+
+# Run a Forth file
+cargo run -p wafer -- file.fth
+
+# Compile to optimized WASM
+cargo run -p wafer -- --consolidate file.fth -o output.wasm
+```
+
+## Testing
+
+```bash
+# All tests
+cargo test --workspace
+
+# Forth 2012 compliance dashboard
+cargo test --test compliance
+
+# Benchmarks
+cargo bench --workspace
+```
+
+## Project Structure
+
+```
+crates/
+  core/       wafer-core: compiler, IR, optimizer, codegen
+  cli/        wafer: CLI REPL and AOT compiler
+  web/        wafer-web: browser bindings (planned)
+forth/        Standard library written in WAFER Forth
+tests/        Integration tests and Forth 2012 compliance suite
+```
+
+## Compliance Status
+
+Targeting 100% Forth 2012 compliance, tested with [Gerry Jackson's forth2012-test-suite](https://github.com/gerryjackson/forth2012-test-suite).
+
+| Word Set | Status |
+|----------|--------|
+| Core | Pending |
+| Core Extensions | Pending |
+| Block | N/A |
+| Double-Number | Pending |
+| Exception | Pending |
+| Facility | Pending |
+| File-Access | Pending |
+| Floating-Point | Pending |
+| Locals | Pending |
+| Memory-Allocation | Pending |
+| Programming-Tools | Pending |
+| Search-Order | Pending |
+| String | Pending |
+| Extended-Character | Pending |
+
+## License
+
+MIT OR Apache-2.0