elly_wasm/

lib.rs

//! A `wasm32-unknown-unknown` wrapper exposing the [`elly`] parse + eval
//! pipeline to JavaScript, with `IO` and imports through [`elly_host`].
//!
//! The `elly` and `muon` crates are `no_std`; this thin shim links `std` only
//! for the allocator that `wasm32-unknown-unknown` provides, so no
//! `wasm-bindgen` (or any post-processing tool) is needed — the `.wasm` is
//! loaded directly.
//!
//! ## Session
//!
//! The module keeps one realm — an [`elly::Ctx`] and the `IO` built over it —
//! for as long as the instance lives. Every `elly_run` evaluates in it, so the
//! builtin modules keep their identity across runs and an imported module loads
//! once. `IO.Proc.exit` ends the session: the host is expected to drop the
//! instance and make a new one (see `elly_host_exit` below).
//!
//! ## ABI
//!
//! Strings cross the boundary as `(ptr, len)` into wasm linear memory:
//!
//! - `elly_alloc(len) -> ptr` — reserve `len` bytes for JS to write UTF-8 into.
//! - `elly_run(ptr, len) -> out` — parse and evaluate those bytes;
//!   returns a pointer to a length-prefixed result: a little-endian `u32` byte
//!   length followed by that many bytes of UTF-8 JSON (see below).
//! - `elly_free(ptr, len)` — release a block obtained from `elly_alloc`.
//!
//! The module imports its system surface from `elly_host` (the [`Sys`] shim):
//!
//! - `elly_host_write(stream, ptr, len)` — `IO.print`/`write` (stream 1) and
//!   `IO.error` (stream 2).
//! - `elly_host_read(ptr, len, out_len) -> ptr` — the source of the module file
//!   at the path `(ptr, len)`, or `0` if there is none. The host allocates the
//!   block with `elly_alloc`, writes its length as a `u32` at `out_len`, and
//!   hands ownership over.
//! - `elly_host_exit(code)` — `IO.Proc.exit`. It must not return: the host
//!   throws, which abandons the run and the instance with it.
//!
//! The source is one of two things:
//!
//! - an **expression**, resolved with `IO` in scope;
//! - a **module** declaring `__main`, run the way the `elly` binary runs a
//!   program, with its imports resolved below `/lib` through
//!   [`elly_host::FsResolver`]. A source is taken as a module when it does not
//!   parse as an expression but does compile as a module.
//!
//! The JSON result is one of:
//!
//! - `{"ast":<expr>,"value":"<display>"}` — an expression, evaluated. `<expr>`
//!   is the tagged AST dump (`elly::Ctx::to_json`).
//! - `{"ast":<expr>,"exit":N}` — the expression ran `IO.Proc.return N`.
//! - `{"ast":<expr>,"error":{"stage":"eval","raised":"<display>","report":"…"}}`
//!   — parsed, but evaluation raised a value that unwound to the top level (an
//!   explicit `__Err.raise` or a host failure like `.div_by_zero`); the AST is
//!   still shown. `report` lists the calls it unwound through, and for a
//!   `.no_match` what refuted which value, each at its line
//!   (`elly::Ctx::report_raised`).
//! - `{"module":true,…}` — the same `value` / `exit` / `error` shapes for a
//!   module's `__main`, without an AST, plus `"error":{"stage":"load","kind":"…"}`
//!   when the module or one of its imports would not load, or it has no `__main`.
//!   A module that would not compile is reported in `kind` as `report` is below.
//! - `{"error":{"stage":"parse","offset":N,"length":L,"kind":"…","report":"…"}}`
//!   — a valid Muon tree but not a valid Elly program in this subset, at the
//!   `L` bytes from byte offset `N`. `report` is the error with the source
//!   line it is on, the span underlined (`elly::Error::report`).
//! - `{"error":{"stage":"syntax","offset":N,"kind":"…","report":"…"}}` — the
//!   syntax layer (Muon) rejected the input at byte offset `N`.

use std::cell::OnceCell;
use std::path::{Component, Path, PathBuf};
use std::rc::Rc;

use elly_core as elly;
use elly_core::{Ctx, DocSource, Error, LoadError, ReportStyle, Text};
use elly_host::{FsResolver, Io, Run, Stream, Sys};

/// Reserve `len` bytes of linear memory and hand ownership to the caller.
#[no_mangle]
pub extern "C" fn elly_alloc(len: usize) -> *mut u8 {
    let mut buf = Vec::<u8>::with_capacity(len);
    let ptr = buf.as_mut_ptr();
    core::mem::forget(buf);
    ptr
}

/// Release a block previously returned by [`elly_alloc`] (same `len`).
///
/// # Safety
/// `ptr`/`len` must come from a prior `elly_alloc(len)` and not be freed twice.
#[no_mangle]
pub unsafe extern "C" fn elly_free(ptr: *mut u8, len: usize) {
    drop(Vec::from_raw_parts(ptr, 0, len));
}

/// Run `len` UTF-8 bytes at `ptr` through the pipeline; return length-prefixed
/// JSON.
///
/// # Safety
/// `ptr`/`len` must describe a valid, initialized block of linear memory (e.g.
/// one from [`elly_alloc`] that JS has filled). The returned block is owned by
/// the caller and must be released with [`elly_free`].
#[no_mangle]
pub unsafe extern "C" fn elly_run(ptr: *const u8, len: usize) -> *mut u8 {
    let input = core::slice::from_raw_parts(ptr, len);
    let json = match core::str::from_utf8(input) {
        Ok(src) => run(src),
        Err(_) => r#"{"error":{"stage":"parse","offset":0,"kind":"NotUtf8"}}"#.to_string(),
    };

    // Frame as: [u32 little-endian length][UTF-8 bytes].
    let bytes = json.into_bytes();
    let mut out = Vec::with_capacity(4 + bytes.len());
    out.extend_from_slice(&(bytes.len() as u32).to_le_bytes());
    out.extend_from_slice(&bytes);
    let p = out.as_mut_ptr();
    core::mem::forget(out);
    p
}

/// The directory a module's imports are searched in. The host serves files
/// below it through `elly_host_read`.
const LIB: &str = "/lib";

/// The name a module typed into the playground is loaded under, which names its
/// chunk too. `__` keeps it apart from a library module `main.ly`, and it has
/// no number since only one run is alive at a time.
const EVAL: &str = "__eval";

/// The name a report gives the source being run.
const INPUT: &str = "<input>";

thread_local! {
    /// The realm every run evaluates in, made on first use.
    static SESSION: OnceCell<Session> = const { OnceCell::new() };
}

fn run(src: &str) -> String {
    SESSION.with(|session| {
        let session = session.get_or_init(Session::new);
        session.run(src).to_json(session.ctx(), src)
    })
}

/// One realm and the `IO` capability built over it. `elly_run` keeps one per
/// instance; a native test makes its own.
pub struct Session {
    ctx: Ctx,
    io: Io,
}

/// How one run of a source ended. Each kind maps to one shape of the JSON
/// described in the module docs. The `stage` there mirrors the pipeline
/// vocabulary: `syntax` (the Muon layer), `parse` (Muon tree → Elly AST),
/// `load` (a module graph), `eval` (a raise that unwound to the top level).
pub enum Outcome {
    /// The syntax layer (Muon) rejected the source. `report` shows it at its
    /// line.
    Syntax {
        offset: usize,
        kind: String,
        report: String,
    },
    /// Neither an expression nor a module.
    Parse {
        offset: u32,
        length: u32,
        kind: String,
        report: String,
    },
    /// An expression ran. `ast` is its tagged JSON dump, and `chunk` the
    /// name of the chunk it was parsed into.
    Expr {
        ast: String,
        chunk: String,
        run: Run,
    },
    /// A module's `__main` ran, or the module would not load, which includes
    /// having no `__main`. A library is reported as the latter, so it never
    /// appears as [`Run::Library`] here.
    Module(Result<Run, String>),
}

impl Default for Session {
    fn default() -> Self {
        Session::new()
    }
}

impl Session {
    pub fn new() -> Session {
        let sys: Rc<dyn Sys> = Rc::new(JsSys);
        let resolver = FsResolver::new(sys.clone(), None, vec![PathBuf::from(LIB)]);
        let ctx = Ctx::with_resolver(Box::new(resolver));
        let io = elly_host::io(sys, &[], &ctx);
        Session { ctx, io }
    }

    /// The realm the session runs in, which renders what its runs return.
    pub fn ctx(&self) -> &Ctx {
        &self.ctx
    }

    /// Run `src` as an expression with `IO` in scope or, failing that, as a
    /// module.
    pub fn run(&self, src: &str) -> Outcome {
        let expr = match self.ctx.parse_preluded(src, &[Text::from("IO")]) {
            Ok(expr) => expr,
            Err(Error::Parse(..)) if self.ctx.compile_module(src).is_ok() => {
                return Outcome::Module(self.run_module(src));
            }
            Err(error @ Error::Syntax(_)) => {
                let Error::Syntax(e) = &error else {
                    unreachable!()
                };
                return Outcome::Syntax {
                    offset: e.offset,
                    kind: format!("{:?}", e.kind),
                    report: error.report(INPUT, src),
                };
            }
            Err(error @ Error::Parse(..)) => {
                let Error::Parse(e, span) = &error else {
                    unreachable!()
                };
                return Outcome::Parse {
                    offset: span.offset,
                    length: span.length,
                    kind: format!("{e:?}"),
                    report: error.report(INPUT, src),
                };
            }
        };
        let env = elly::Env::EMPTY.bind(self.io.value.clone());
        let run = self
            .io
            .finish(elly::eval_env(expr, &env, &self.ctx), &self.ctx);
        Outcome::Expr {
            ast: self.ctx.to_json(expr),
            chunk: self.ctx.chunk(expr).name().to_string(),
            run,
        }
    }

    /// Load `src` as the module `__eval` — replacing the previous run's — and run
    /// its `__main` against `IO`.
    fn run_module(&self, src: &str) -> Result<Run, String> {
        let instance = self
            .ctx
            .load_source(EVAL, src)
            .map_err(|e| describe_load(&e))?;
        match self.io.run(&instance, &self.ctx) {
            Run::Library => Err("no `__main`: a library, not a program".to_string()),
            run => Ok(run),
        }
    }
}

impl Outcome {
    /// The JSON `elly_run` hands the page, rendering values in `ctx`, the
    /// session's realm, and reporting a raise in `src`, the source run.
    pub fn to_json(&self, ctx: &Ctx, src: &str) -> String {
        match self {
            Outcome::Syntax {
                offset,
                kind,
                report,
            } => format!(
                r#"{{"error":{{"stage":"syntax","offset":{offset},"kind":{},"report":{}}}}}"#,
                json_string(kind),
                json_string(report)
            ),
            // The `{:?}` of a `ParseError` may embed a quoted payload (e.g.
            // `UnboundName("__List_")`), so escape it as a JSON string rather than
            // splicing the raw debug text — otherwise the inner quotes break the JSON.
            Outcome::Parse {
                offset,
                length,
                kind,
                report,
            } => format!(
                r#"{{"error":{{"stage":"parse","offset":{offset},"length":{length},"kind":{},"report":{}}}}}"#,
                json_string(kind),
                json_string(report)
            ),
            Outcome::Expr { ast, chunk, run } => {
                format!(r#"{{"ast":{ast},{}}}"#, run_json(run, ctx, src, chunk))
            }
            Outcome::Module(Ok(run)) => {
                format!(r#"{{"module":true,{}}}"#, run_json(run, ctx, src, EVAL))
            }
            Outcome::Module(Err(kind)) => format!(
                r#"{{"module":true,"error":{{"stage":"load","kind":{}}}}}"#,
                json_string(kind)
            ),
        }
    }
}

/// The JSON members for how a run ended (everything but a library). `src`
/// is the source run, parsed into the chunk named `input`.
fn run_json(run: &Run, ctx: &Ctx, src: &str, input: &str) -> String {
    match run {
        Run::Returned(value) => format!(r#""value":{}"#, json_string(&value.to_display(ctx))),
        Run::Exit(code) => format!(r#""exit":{code}"#),
        // A raise unwound to the top level: the raised value's display, and
        // the report of what it unwound through. Only the input's text is at
        // hand; a library module is named by its path.
        Run::Raised(r, trace) => {
            let doc = |source: &DocSource, chunk: &str| match source {
                _ if chunk == input => (INPUT.to_string(), Some(src.to_string())),
                DocSource::Path(path) => (path.to_string(), None),
                _ => (chunk.to_string(), None),
            };
            format!(
                r#""error":{{"stage":"eval","raised":{},"report":{}}}"#,
                json_string(&r.value().to_display(ctx)),
                json_string(&ctx.report_raised(r, trace, &doc, ReportStyle::Snippets))
            )
        }
        Run::Library => unreachable!("a library is reported as a load error"),
    }
}

/// Why a module graph would not load, in one line.
fn describe_load(e: &LoadError) -> String {
    match e {
        LoadError::NotFound { spec } => format!("cannot resolve import {spec:?} (searched {LIB})"),
        LoadError::Cycle { path } => {
            let names: Vec<&str> = path.iter().map(|n| n.as_str()).collect();
            format!("import cycle: {}", names.join(" → "))
        }
        LoadError::Compile {
            name,
            error,
            path,
            source,
        } => error.report(path.as_deref().unwrap_or(name.as_str()), source),
    }
}

/// [`Sys`] over the functions the page imports. There is no environment and no
/// real file system: a path is normalized lexically, and whether a file exists
/// is the host's to say when it is read.
struct JsSys;

impl Sys for JsSys {
    fn write(&self, stream: Stream, s: &str) -> std::io::Result<()> {
        let stream = match stream {
            Stream::Out => 1,
            Stream::Err => 2,
        };
        host::write(stream, s);
        Ok(())
    }

    fn real_path(&self, path: &Path) -> Option<PathBuf> {
        let mut real = PathBuf::from("/");
        for c in path.components() {
            match c {
                Component::ParentDir => {
                    real.pop();
                }
                Component::Normal(part) => real.push(part),
                Component::RootDir | Component::CurDir | Component::Prefix(_) => {}
            }
        }
        Some(real)
    }

    fn read_source(&self, path: &Path) -> Option<String> {
        host::read(path.to_str()?)
    }

    fn var(&self, _name: &str) -> Option<String> {
        None
    }

    fn vars(&self) -> Vec<(String, String)> {
        Vec::new()
    }

    fn exit(&self, code: i32) -> ! {
        host::exit(code)
    }
}

/// The page's side of [`JsSys`].
#[cfg(target_arch = "wasm32")]
mod host {
    #[link(wasm_import_module = "elly_host")]
    extern "C" {
        fn elly_host_write(stream: u32, ptr: *const u8, len: usize);
        fn elly_host_read(ptr: *const u8, len: usize, out_len: *mut usize) -> *mut u8;
        fn elly_host_exit(code: i32);
    }

    pub fn write(stream: u32, s: &str) {
        unsafe { elly_host_write(stream, s.as_ptr(), s.len()) }
    }

    pub fn read(path: &str) -> Option<String> {
        let mut len = 0usize;
        let ptr = unsafe { elly_host_read(path.as_ptr(), path.len(), &mut len) };
        if ptr.is_null() {
            return None;
        }
        // The host filled a block from `elly_alloc(len)` and handed it over.
        let bytes = unsafe { Vec::from_raw_parts(ptr, len, len) };
        String::from_utf8(bytes).ok()
    }

    pub fn exit(code: i32) -> ! {
        unsafe { elly_host_exit(code) };
        // The host throws instead of returning; if it did return, stop here.
        core::arch::wasm32::unreachable()
    }
}

/// Native builds have no page to import from. This side stands in for it, so
/// a test can run the playground's examples (`tests/examples.rs`, which
/// compiles this file in as a module): files come
/// from a table the test sets, writes are recorded, and an exit unwinds with an
/// [`Exit`](native::Exit) payload.
#[cfg(not(target_arch = "wasm32"))]
pub mod native {
    use std::cell::RefCell;

    use elly_host::Stream;

    thread_local! {
        static FILES: RefCell<Vec<(String, String)>> = const { RefCell::new(Vec::new()) };
        static OUTPUT: RefCell<Vec<(Stream, String)>> = const { RefCell::new(Vec::new()) };
    }

    /// The panic payload `IO.Proc.exit` unwinds with.
    #[derive(Debug)]
    pub struct Exit(pub i32);

    /// Serve `(path, source)` files to imports, as the page's `FILES` table does.
    pub fn set_files(files: Vec<(String, String)>) {
        FILES.with(|f| *f.borrow_mut() = files);
    }

    /// What was written since the last call, in order.
    pub fn take_output() -> Vec<(Stream, String)> {
        OUTPUT.with(|o| std::mem::take(&mut *o.borrow_mut()))
    }

    pub(crate) fn write(stream: u32, s: &str) {
        let stream = if stream == 2 {
            Stream::Err
        } else {
            Stream::Out
        };
        OUTPUT.with(|o| o.borrow_mut().push((stream, s.to_string())));
    }

    pub(crate) fn read(path: &str) -> Option<String> {
        FILES.with(|f| {
            f.borrow()
                .iter()
                .find(|(p, _)| p == path)
                .map(|(_, src)| src.clone())
        })
    }

    pub(crate) fn exit(code: i32) -> ! {
        std::panic::panic_any(Exit(code))
    }
}

#[cfg(not(target_arch = "wasm32"))]
use native as host;

/// Quote and escape `s` as a JSON string literal.
fn json_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 2);
    out.push('"');
    for ch in s.chars() {
        match ch {
            '"' => out.push_str("\\\""),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
            c => out.push(c),
        }
    }
    out.push('"');
    out
}