nomiscript/compiler/
mod.rs

1mod context;
2mod emit;
3pub(crate) mod expr;
4mod layout;
5mod native;
6pub mod special;
7
8use tracing::debug;
9
10use crate::ast::{Expr, Program, WasmType};
11use crate::error::{Error, Result};
12use crate::host_fn::HostFnSpec;
13use crate::runtime::SymbolTable;
14
15use context::CompileContext;
16use emit::FunctionEmitter;
17
18/// Selects which export shape the compiler emits.
19///
20/// `Script` keeps the entity-script surface (`should_apply` + `process`
21/// exports, env.* imports) the script executor consumes. `Eval` emits a
22/// `nomi-eval` export that runs the program and returns the final value
23/// via the function's `(ref null any)` return slot; the host decodes it
24/// with `scripting::runtime::decode_eval_result`.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum CompileMode {
27    Script,
28    Eval,
29}
30
31pub struct Compiler {
32    host_fns: Vec<HostFnSpec>,
33}
34
35impl Compiler {
36    #[must_use]
37    pub fn new() -> Self {
38        Self {
39            host_fns: Vec::new(),
40        }
41    }
42
43    /// Builds a compiler that recognises the given host fn names in eval-mode
44    /// programs. Each spec gets a wasm import declared in the module and an
45    /// entry the native dispatcher consults when emitting calls. Has no effect
46    /// in `Script` mode (entity-script bytecode imports `env.*`, not `nomi.*`).
47    #[must_use]
48    pub fn with_host_fns(host_fns: Vec<HostFnSpec>) -> Self {
49        Self { host_fns }
50    }
51
52    pub fn compile(&mut self, program: &Program, symbols: &mut SymbolTable) -> Result<Vec<u8>> {
53        self.compile_with_mode(program, symbols, CompileMode::Script)
54    }
55
56    pub fn compile_with_mode(
57        &mut self,
58        program: &Program,
59        symbols: &mut SymbolTable,
60        mode: CompileMode,
61    ) -> Result<Vec<u8>> {
62        debug!(expr_count = program.exprs.len(), ?mode, "compilation start");
63        match mode {
64            CompileMode::Script => self.compile_script(program, symbols),
65            CompileMode::Eval => self.compile_eval(program, symbols),
66        }
67    }
68
69    fn compile_script(&mut self, program: &Program, symbols: &mut SymbolTable) -> Result<Vec<u8>> {
70        let mut ctx = CompileContext::new()?;
71
72        // Snapshot how many helpers (gcd / ratio_* / commodity_* / pair_*)
73        // were queued during context bootstrap; these correspond to the
74        // function-section slots between `should_apply` and `process`,
75        // so their bodies must drain *with* `should_apply`'s emit. User
76        // code inside `process` may queue more helpers (e.g. a real
77        // wasm fn for a `(lambda ...)` value); those slots land *after*
78        // `process` and have to drain *with* `process`'s emit so the
79        // code-section ordering matches the function-section.
80        let bootstrap_helper_count = ctx.pending_helper_count();
81
82        let mut process = FunctionEmitter::new();
83
84        // Wrap the body in the Tier 3 boundary `try_table` so an uncaught
85        // `(error)` throw bridges to `__nomi_raise` (ADR-0026). `process`
86        // returns void.
87        ctx.emit_boundary_wrapper(&mut process, None, |ctx, emit| {
88            // output_base = get_output_offset()
89            emit.call(ctx.ids.get_output_offset()?);
90            emit.local_set(expr::LOCAL_OUTPUT_BASE);
91            expr::compile_program(ctx, emit, symbols, program)
92        })?;
93        process.end();
94
95        let process_locals = ctx.build_locals_declaration();
96        ctx.reset_locals();
97
98        let should_apply = self.build_should_apply(&mut ctx, symbols)?;
99        ctx.add_should_apply(should_apply, bootstrap_helper_count);
100        ctx.add_process(process.finish(&process_locals));
101
102        let wasm = ctx.finish();
103        debug!(wasm_size = wasm.len(), "compilation complete");
104        Ok(wasm)
105    }
106
107    fn compile_eval(&mut self, program: &Program, symbols: &mut SymbolTable) -> Result<Vec<u8>> {
108        let (wasm, _ty) = self.compile_eval_with_type(program, symbols)?;
109        Ok(wasm)
110    }
111
112    /// Compiles `program` in eval mode and returns the wasm bytes paired
113    /// with the form's final result type. `None` for empty programs /
114    /// definition-only forms (nomi-eval returns `ref.null any`); `Some(ty)`
115    /// for any other terminator. Hosts decode the returned anyref via the
116    /// type hint — see `scripting::runtime::decode_eval_result`.
117    pub fn compile_eval_with_type(
118        &mut self,
119        program: &Program,
120        symbols: &mut SymbolTable,
121    ) -> Result<(Vec<u8>, Option<WasmType>)> {
122        let mut ctx = CompileContext::new_eval_with_host_fns(&self.host_fns)?;
123        let mut emit = FunctionEmitter::new();
124
125        // `nomi-eval` returns anyref. The boundary wrapper bridges an
126        // uncaught `(error)` to `__nomi_raise` (ADR-0026). The body's
127        // final result type is computed inside the closure and surfaced
128        // out for the host's `decode_eval_result` hint.
129        let mut result_ty: Option<WasmType> = None;
130        ctx.emit_boundary_wrapper(&mut emit, Some(WasmType::AnyRef), |ctx, emit| {
131            if program.exprs.is_empty() {
132                emit.ref_null_any();
133                return Ok(());
134            }
135            let last_idx = program.exprs.len() - 1;
136            for expr in &program.exprs[..last_idx] {
137                expr::compile_for_effect(ctx, emit, symbols, expr)?;
138            }
139            let last = &program.exprs[last_idx];
140            if is_definition_form(last) {
141                expr::compile_for_effect(ctx, emit, symbols, last)?;
142                emit.ref_null_any();
143            } else {
144                let ty = expr::compile_for_stack(ctx, emit, symbols, last)?;
145                emit_to_anyref(emit, ty);
146                result_ty = Some(ty);
147            }
148            Ok(())
149        })?;
150        emit.end();
151
152        let locals = ctx.build_locals_declaration();
153        ctx.reset_locals();
154        ctx.add_nomi_eval(emit.finish(&locals));
155
156        let wasm = ctx.finish();
157        debug!(wasm_size = wasm.len(), "eval compilation complete");
158        Ok((wasm, result_ty))
159    }
160
161    fn build_should_apply(
162        &self,
163        ctx: &mut CompileContext,
164        symbols: &mut SymbolTable,
165    ) -> Result<wasm_encoder::Function> {
166        let body = symbols
167            .lookup("SHOULD-APPLY")
168            .and_then(|s| s.function().cloned());
169
170        let Some(Expr::Lambda(params, body)) = body else {
171            return Ok(CompileContext::default_should_apply());
172        };
173
174        if !params.required.is_empty() {
175            return Err(Error::Compile(
176                "SHOULD-APPLY must take no parameters".to_string(),
177            ));
178        }
179
180        debug!("compiling custom should-apply");
181        let mut emit = FunctionEmitter::new();
182
183        // Boundary wrapper bridges an uncaught `(error)` in the body to
184        // `__nomi_raise` (ADR-0026). `should_apply` returns i32.
185        ctx.emit_boundary_wrapper(&mut emit, Some(WasmType::I32), |ctx, emit| {
186            let ty = expr::compile_for_stack(ctx, emit, symbols, &body)?;
187            match ty {
188                // Bool is the natural should-apply result (a predicate); I32
189                // (a raw count used as truthy) is also accepted. Both are
190                // i32-repr, so the i32 return passes through unchanged.
191                WasmType::I32 | WasmType::Bool => Ok(()),
192                WasmType::Ratio => {
193                    emit.struct_get(ctx.ids.ty_ratio, 0);
194                    emit.i64_const(0);
195                    emit.i64_ne();
196                    Ok(())
197                }
198                _ => Err(Error::Compile(
199                    "SHOULD-APPLY must return a boolean or numeric value".to_string(),
200                )),
201            }
202        })?;
203        emit.end();
204
205        let locals = ctx.build_locals_declaration();
206        ctx.reset_locals();
207        Ok(emit.finish(&locals))
208    }
209}
210
211/// Promotes the form's final value (already on the wasm stack as its
212/// declared `WasmType`) to an anyref-subtype so it satisfies nomi-eval's
213/// `(ref null any)` return slot. Reference-typed values (ratio_ref,
214/// commodity_ref, i8_array, pair_ref, entity_ref) are anyref subtypes
215/// already; primitive `i32` needs `ref.i31` boxing.
216fn emit_to_anyref(emit: &mut FunctionEmitter, ty: WasmType) {
217    match ty {
218        // Both i32-repr value types box into an `(ref i31)`.
219        WasmType::I32 | WasmType::Bool => emit.ref_i31(),
220        WasmType::Ratio
221        | WasmType::Commodity
222        | WasmType::StringRef
223        | WasmType::PairRef(_)
224        | WasmType::EntityRef(_)
225        | WasmType::Closure(_)
226        | WasmType::AnyRef => {}
227    }
228}
229
230fn is_definition_form(expr: &Expr) -> bool {
231    let Expr::List(elems) = expr else {
232        return false;
233    };
234    let Some(Expr::Symbol(name)) = elems.first() else {
235        return false;
236    };
237    matches!(
238        name.as_str(),
239        "DEFUN" | "DEFVAR" | "DEFMACRO" | "DEFPARAMETER" | "DEFSTRUCT"
240    )
241}
242
243impl Default for Compiler {
244    fn default() -> Self {
245        Self::new()
246    }
247}
248
249#[cfg(test)]
250mod tests {
251    use super::*;
252    use crate::ast::Expr;
253    use crate::runtime::{Symbol, SymbolKind};
254
255    #[test]
256    fn test_compile_empty_program() {
257        let program = Program::default();
258        let mut compiler = Compiler::new();
259        let wasm = compiler.compile(&program, &mut SymbolTable::new()).unwrap();
260        assert!(!wasm.is_empty());
261        assert_eq!(&wasm[0..4], b"\0asm");
262    }
263
264    #[test]
265    fn test_compile_eval_empty_program_emits_capture_nil() {
266        let program = Program::default();
267        let mut compiler = Compiler::new();
268        let wasm = compiler
269            .compile_with_mode(&program, &mut SymbolTable::new(), CompileMode::Eval)
270            .unwrap();
271        assert!(!wasm.is_empty());
272        assert_eq!(&wasm[0..4], b"\0asm");
273    }
274
275    #[test]
276    fn test_compile_eval_integer_literal() {
277        let program = Program::new(vec![Expr::Number(num_rational::Ratio::from_integer(7))]);
278        let mut compiler = Compiler::new();
279        let wasm = compiler
280            .compile_with_mode(&program, &mut SymbolTable::new(), CompileMode::Eval)
281            .unwrap();
282        assert!(!wasm.is_empty());
283    }
284
285    #[test]
286    fn test_compile_eval_arithmetic() {
287        let program = Program::new(vec![Expr::List(vec![
288            Expr::Symbol("+".into()),
289            Expr::Number(num_rational::Ratio::from_integer(1)),
290            Expr::Number(num_rational::Ratio::from_integer(2)),
291        ])]);
292        let mut compiler = Compiler::new();
293        let mut symbols = SymbolTable::with_builtins();
294        let wasm = compiler
295            .compile_with_mode(&program, &mut symbols, CompileMode::Eval)
296            .unwrap();
297        assert!(!wasm.is_empty());
298    }
299
300    #[test]
301    fn test_compile_default_uses_script_mode() {
302        let program = Program::new(vec![Expr::Bool(true)]);
303        let mut compiler = Compiler::new();
304        let mut symbols = SymbolTable::new();
305        let default_bytes = compiler.compile(&program, &mut symbols).unwrap();
306        let mut symbols = SymbolTable::new();
307        let explicit_bytes = compiler
308            .compile_with_mode(&program, &mut symbols, CompileMode::Script)
309            .unwrap();
310        assert_eq!(default_bytes, explicit_bytes);
311    }
312
313    #[test]
314    fn test_compile_eval_and_script_produce_distinct_bytes() {
315        let program = Program::new(vec![Expr::Number(num_rational::Ratio::from_integer(1))]);
316        let mut compiler = Compiler::new();
317        let mut s1 = SymbolTable::new();
318        let mut s2 = SymbolTable::new();
319        let script_bytes = compiler
320            .compile_with_mode(&program, &mut s1, CompileMode::Script)
321            .unwrap();
322        let eval_bytes = compiler
323            .compile_with_mode(&program, &mut s2, CompileMode::Eval)
324            .unwrap();
325        assert_ne!(script_bytes, eval_bytes);
326    }
327
328    #[test]
329    fn test_compile_nil() {
330        let program = Program::new(vec![Expr::Nil]);
331        let mut compiler = Compiler::new();
332        let wasm = compiler.compile(&program, &mut SymbolTable::new()).unwrap();
333        assert!(!wasm.is_empty());
334        assert_eq!(&wasm[0..4], b"\0asm");
335    }
336
337    #[test]
338    fn test_compile_bool() {
339        let program = Program::new(vec![Expr::Bool(true)]);
340        let mut compiler = Compiler::new();
341        let wasm = compiler.compile(&program, &mut SymbolTable::new()).unwrap();
342        assert!(!wasm.is_empty());
343    }
344
345    #[test]
346    fn test_compile_number() {
347        use num_rational::Ratio;
348        let program = Program::new(vec![Expr::Number(Ratio::new(1, 2))]);
349        let mut compiler = Compiler::new();
350        let wasm = compiler.compile(&program, &mut SymbolTable::new()).unwrap();
351        assert!(!wasm.is_empty());
352    }
353
354    #[test]
355    fn test_compile_string() {
356        let program = Program::new(vec![Expr::String("hello".into())]);
357        let mut compiler = Compiler::new();
358        let wasm = compiler.compile(&program, &mut SymbolTable::new()).unwrap();
359        assert!(!wasm.is_empty());
360        assert_eq!(&wasm[0..4], b"\0asm");
361    }
362
363    #[test]
364    fn test_compile_symbol_with_value() {
365        let mut symbols = SymbolTable::new();
366        symbols.define(Symbol::new("REVISION", SymbolKind::Variable).with_value(Expr::Bool(true)));
367        let program = Program::new(vec![Expr::Symbol("REVISION".into())]);
368        let mut compiler = Compiler::new();
369        let wasm = compiler.compile(&program, &mut symbols).unwrap();
370        assert!(!wasm.is_empty());
371    }
372
373    #[test]
374    fn test_compile_undefined_symbol() {
375        let program = Program::new(vec![Expr::Symbol("UNKNOWN".into())]);
376        let mut compiler = Compiler::new();
377        let result = compiler.compile(&program, &mut SymbolTable::new());
378        assert!(result.is_err());
379        let err = result.unwrap_err();
380        assert!(matches!(err, crate::error::Error::UndefinedSymbol(_)));
381    }
382
383    #[test]
384    fn test_defun_populates_function_cell() {
385        let program = Program::new(vec![Expr::List(vec![
386            Expr::Symbol("DEFUN".into()),
387            Expr::Symbol("SUM".into()),
388            Expr::List(vec![
389                Expr::Symbol("A".into()),
390                Expr::Symbol("B".into()),
391                Expr::Symbol("C".into()),
392            ]),
393            Expr::String("Sums A, B, C".into()),
394            Expr::List(vec![
395                Expr::Symbol("+".into()),
396                Expr::Symbol("A".into()),
397                Expr::Symbol("B".into()),
398                Expr::Symbol("C".into()),
399            ]),
400        ])]);
401        let mut compiler = Compiler::new();
402        let mut symbols = SymbolTable::with_builtins();
403        compiler.compile(&program, &mut symbols).unwrap();
404
405        let sym = symbols.lookup("SUM").expect("SUM should be defined");
406        assert!(sym.function().is_some());
407        assert!(matches!(sym.function(), Some(Expr::Lambda(_, _))));
408        assert_eq!(sym.doc(), Some("Sums A, B, C"));
409    }
410
411    #[test]
412    fn test_defun_no_doc_populates_function_cell() {
413        let program = Program::new(vec![Expr::List(vec![
414            Expr::Symbol("DEFUN".into()),
415            Expr::Symbol("ADD".into()),
416            Expr::List(vec![Expr::Symbol("A".into()), Expr::Symbol("B".into())]),
417            Expr::List(vec![
418                Expr::Symbol("+".into()),
419                Expr::Symbol("A".into()),
420                Expr::Symbol("B".into()),
421            ]),
422        ])]);
423        let mut compiler = Compiler::new();
424        let mut symbols = SymbolTable::with_builtins();
425        compiler.compile(&program, &mut symbols).unwrap();
426
427        let sym = symbols.lookup("ADD").expect("ADD should be defined");
428        assert!(sym.function().is_some());
429        assert!(sym.doc().is_none());
430    }
431}
nomiscript/compiler/mod.rs

nomiscript/compiler/
mod.rs
