Files

T

Oleksandr Kozachuk 380250a641 feat(core): SEE, SEE-IR, HELP introspection trio (WS-010)

Implements plans/01-see-introspection.md, all phases.

- see.rs: feature-free IR pretty-printer (format_ir/format_ir_with),
  exhaustive over IrOp -- a new variant fails the build, not the output.
- SEE-IR <name>: post-optimization IR view with resolved callee names,
  immediate/does> annotations; host-word and interpreter-token stubs.
- SEE <name>: verbatim source capture for colon words (multi-line,
  comments preserved, EVALUATE-nesting safe, error-path wiped, MARKER/
  REMEMBER/EMPTY roll word sources back too). Data definers (VARIABLE/
  CONSTANT/CREATE/BUFFER:/2*/F*/SYNONYM) record synthesized one-liners
  at definition time; VALUE/2VALUE/FVALUE/DEFER synthesize at SEE time
  so current values and IS targets show. Fallback chain ends at IR dump
  or host-word stub -- SEE never dead-ends on a defined word.
- HELP [<name>]: wordhelp.rs doc table with stack effect + one-line
  description for EVERY word in a fresh VM (300+ dictionary words plus
  all outer-interpreter tokens); a coverage test fails the build if a
  word is ever added undocumented. User words echo their leading
  ( ... -- ... ) comment. SEE/SEE-IR prepend the HELP line as a
  \ comment. Bare HELP prints usage.
- boot.fth colon definitions get real sources for free (they flow
  through evaluate); INTERPRETER_TOKENS gained the missing ?DO.

524 unit + 11 compliance + 9 comparison + 5 crypto + 1 bench green;
fmt/clippy clean; core still builds --no-default-features; web
wasm-pack build unchanged.

2026-08-06 11:18:03 +02:00

5.0 KiB

Raw Blame History

WAFER Project Conventions

What is WAFER?

WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler targeting WebAssembly. Currently a working Forth system with 200+ words, JIT compilation, 12 word sets at 100% compliance, and a full optimization pipeline (peephole, constant folding, inlining, strength reduction, DCE, tail calls, stack-to-local promotion with loop/IF support, self-recursive direct calls, consolidation). Beats gforth on all benchmarks in release mode. Includes a browser-based REPL via wasm-pack.

Architecture

Each Forth word compiles to its own WASM module via wasm-encoder
Modules share memory, globals (dsp/rsp/fsp), and a function table via runtime imports
IR-based compilation: Forth -> Vec<IrOp> -> WASM codegen -> runtime instantiation
Dictionary: linked-list in a Vec<u8> buffer simulating WASM linear memory
Primitives: either IR-based (compiled to WASM) or host functions (closures via HostFn)
Runtime trait: ForthVM<R: Runtime> is generic over the execution backend
- NativeRuntime (wasmtime) -- CLI, tests, AOT compilation
- WebRuntime (js-sys) -- browser REPL via wasm-pack

Crate Structure

crates/core -- compiler, optimizer, codegen, dictionary, runtime traits, outer interpreter
crates/cli -- CLI REPL with rustyline, wafer build/wafer run commands
crates/web -- browser REPL (wasm-bindgen entry point, WebRuntime, HTML/CSS/JS frontend)

Key Files

crates/core/src/outer.rs -- ForthVM<R: Runtime>: outer interpreter, compiler, all primitives
crates/core/src/runtime.rs -- Runtime + HostAccess traits (execution backend abstraction)
crates/core/src/runtime_native.rs -- NativeRuntime: wasmtime implementation (behind native feature)
crates/core/src/codegen.rs -- IR-to-WASM translation, module generation
crates/core/src/dictionary.rs -- Dictionary data structure with create/find/reveal
crates/core/src/ir.rs -- IrOp enum (the intermediate representation)
crates/core/src/memory.rs -- Memory layout constants (stack regions, dictionary base, etc.)
crates/core/src/optimizer.rs -- IR optimization passes (peephole, fold, inline, DCE, etc.)
crates/core/src/config.rs -- WaferConfig: unified optimization configuration
crates/core/src/consolidate.rs -- Consolidation recompiler (single-module direct calls)
crates/core/boot.fth -- Bootstrap Forth definitions loaded at startup
crates/cli/src/main.rs -- CLI REPL with rustyline
crates/web/src/lib.rs -- WaferRepl wasm-bindgen entry point
crates/web/src/runtime_web.rs -- WebRuntime: browser WebAssembly API via js-sys
crates/web/www/ -- Frontend (index.html, style.css, app.js)

Feature Flags (wafer-core)

default = ["native"] -- includes wasmtime, NativeRuntime, runner, export, etc.
native -- enables dep:wasmtime and all native-only modules
No features -- pure Rust only (dictionary, IR, optimizer, codegen, outer interpreter). Used by wafer-web.

Adding a New Word

IR primitive (simple stack/arithmetic/logic -- preferred when possible):

self.register_primitive("WORD_NAME", false, vec![IrOp::Dup, IrOp::Mul])?;

Host function (needs Rust logic -- I/O, dictionary manipulation, complex stack access):

let shared_state = Arc::clone(&self.some_field);
let func: HostFn = Box::new(move |ctx: &mut dyn HostAccess| {
    let sp = ctx.get_dsp();
    let val = ctx.mem_read_i32(sp);
    // ... logic using ctx for memory/global access ...
    ctx.set_dsp(sp + CELL_SIZE);
    Ok(())
});
self.register_host_primitive("WORD_NAME", false, func)?;

Special interpreter token (defining words like VARIABLE, CONSTANT, CREATE): Handle in interpret_token_immediate() or compile_token() as a special case.

Code Style

cargo fmt --all and cargo clippy --workspace must pass with no warnings
Every public function needs a doc comment
Use thiserror for error types in core crate, anyhow for CLI
Prefer returning Result over panicking

Testing

Run cargo test --workspace before committing (currently 524 unit + 1 benchmark + 11 compliance + 9 comparison + 5 crypto)
Forth 2012 compliance: cargo test -p wafer-core --test compliance
Cross-engine comparison (vs gforth): cargo test -p wafer-core --test comparison
Performance benchmarks (release mode): cargo test -p wafer-core --test comparison -- --nocapture --ignored
Test helper in outer.rs: eval_output("forth code") returns printed output as String
Test helper: eval_stack("forth code") returns data stack as Vec

Web REPL

Build: cd crates/web && wasm-pack build --target web --out-dir www/pkg
Serve: python3 -m http.server -d crates/web/www 8080
Open: http://localhost:8080/
Dev build (faster, unoptimized): wasm-pack build --target web --dev --out-dir www/pkg

Key Principles

Correctness first, performance second
Maximize Forth, minimize Rust (self-hosting goal -- not yet started)
Test-driven: if it's not tested, it doesn't work
Every word set at 100% compliance before moving to the next
Never break existing tests

5.0 KiB Raw Blame History