lumen-wasm 0.1.1

package/README.md

@@ -0,0 +1,214 @@
+# lumen-wasm
+
+WebAssembly bindings for the Lumen compiler and VM.
+
+This crate provides a WASM-compatible interface for compiling and executing Lumen programs in browser and WASI environments.
+
+## Prerequisites
+
+Install wasm-pack:
+
+```bash
+cargo install wasm-pack
+```
+
+## Building
+
+### Browser Target
+
+```bash
+wasm-pack build --target web
+```
+
+Or use the CLI:
+
+```bash
+lumen build wasm --target web
+```
+
+Output in `pkg/`:
+- `lumen_wasm.js` - JavaScript glue code
+- `lumen_wasm_bg.wasm` - WASM binary
+- `lumen_wasm.d.ts` - TypeScript definitions
+
+### Node.js Target
+
+```bash
+wasm-pack build --target nodejs
+```
+
+Or:
+
+```bash
+lumen build wasm --target nodejs
+```
+
+### WASI Target
+
+```bash
+cargo build --target wasm32-wasi
+```
+
+(Requires `wasm32-wasi` target installed: `rustup target add wasm32-wasi`)
+
+## Usage
+
+### Browser
+
+```html
+<script type="module">
+import init, { run, compile, check, version } from './pkg/lumen_wasm.js';
+
+await init();
+
+const source = `
+cell main() -> Int
+    42
+end
+`;
+
+// Type-check
+const checkResult = check(source);
+console.log(checkResult.to_json());
+
+// Compile to LIR
+const lirResult = compile(source);
+console.log(lirResult.to_json());
+
+// Execute
+const runResult = run(source, "main");
+console.log(runResult.to_json());
+
+// Get version
+console.log("Lumen version:", version());
+</script>
+```
+
+### Node.js
+
+```javascript
+const { run, check, compile, version } = require('./pkg/lumen_wasm.js');
+
+const source = `
+cell factorial(n: Int) -> Int
+    if n <= 1
+        1
+    else
+        n * factorial(n - 1)
+    end
+end
+
+cell main() -> Int
+    factorial(5)
+end
+`;
+
+const result = run(source, "main");
+const parsed = JSON.parse(result.to_json());
+
+if (parsed.ok) {
+    console.log("Result:", parsed.ok);
+} else {
+    console.error("Error:", parsed.error);
+}
+```
+
+### Wasmtime (WASI)
+
+```bash
+cargo build --target wasm32-wasi --release
+wasmtime target/wasm32-wasi/release/lumen_wasm.wasm
+```
+
+## API
+
+### `check(source: &str) -> LumenResult`
+
+Type-check Lumen source code.
+
+Returns:
+- Success: `{"ok": "Type-checked successfully"}`
+- Error: `{"error": "error message with diagnostics"}`
+
+### `compile(source: &str) -> LumenResult`
+
+Compile Lumen source to LIR JSON.
+
+Returns:
+- Success: `{"ok": "<LIR JSON>"}`
+- Error: `{"error": "error message with diagnostics"}`
+
+### `run(source: &str, cell_name: Option<String>) -> LumenResult`
+
+Compile and execute Lumen source.
+
+Parameters:
+- `source` - Lumen source code
+- `cell_name` - Cell to execute (default: "main")
+
+Returns:
+- Success: `{"ok": "<output>"}`
+- Error: `{"error": "error message"}`
+
+### `version() -> String`
+
+Get the Lumen compiler version.
+
+### `LumenResult`
+
+Result wrapper with helper methods:
+
+- `is_ok() -> bool` - Returns true if successful
+- `is_err() -> bool` - Returns true if failed
+- `to_json() -> String` - Get result as JSON string
+
+## Examples
+
+See `examples/wasm_hello.lm.md` for Lumen code examples.
+
+See `examples/wasm_browser.html` for a complete browser demo.
+
+## Current Limitations
+
+- No filesystem access in browser (WASI supports filesystem)
+- No tool providers yet (coming in Phase 3)
+- No trace recording (requires file I/O)
+- No multi-file imports yet
+
+## Size Optimization
+
+The release profile is optimized for small binary size:
+
+```toml
+[profile.release]
+opt-level = "z"       # Optimize for size
+lto = true            # Link-time optimization
+codegen-units = 1     # Single codegen unit
+panic = "abort"       # Smaller panic handler
+```
+
+Further optimize with `wasm-opt`:
+
+```bash
+wasm-opt -Oz -o optimized.wasm pkg/lumen_wasm_bg.wasm
+```
+
+## Development
+
+Run tests:
+
+```bash
+cargo test
+```
+
+Run WASM tests:
+
+```bash
+wasm-pack test --headless --firefox
+```
+
+## See Also
+
+- `docs/WASM_STRATEGY.md` - Overall WASM compilation strategy
+- `examples/wasm_hello.lm.md` - Example Lumen programs for WASM
+- `examples/wasm_browser.html` - Interactive browser demo

package/lumen_wasm.d.ts

@@ -0,0 +1,61 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Result of a compilation or execution operation.
+ *
+ * JSON format:
+ * - Success: `{"ok": "result_value"}`
+ * - Error: `{"error": "error_message"}`
+ */
+export class LumenResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Returns true if the operation failed.
+     */
+    is_err(): boolean;
+    /**
+     * Returns true if the operation succeeded.
+     */
+    is_ok(): boolean;
+    /**
+     * Returns the result as a JSON string.
+     */
+    to_json(): string;
+}
+
+/**
+ * Type-check a Lumen source file.
+ *
+ * Returns a LumenResult:
+ * - On success: `{"ok": "Type-checked successfully"}`
+ * - On error: `{"error": "error message with diagnostics"}`
+ */
+export function check(source: string): LumenResult;
+
+/**
+ * Compile Lumen source to LIR JSON.
+ *
+ * Returns a LumenResult:
+ * - On success: `{"ok": "<LIR JSON>"}`
+ * - On error: `{"error": "error message with diagnostics"}`
+ */
+export function compile(source: string): LumenResult;
+
+/**
+ * Compile and execute Lumen source.
+ *
+ * Returns a LumenResult:
+ * - On success: `{"ok": "<output>"}`
+ * - On error: `{"error": "error message"}`
+ *
+ * The `cell_name` parameter specifies which cell to execute (default: "main").
+ */
+export function run(source: string, cell_name?: string | null): LumenResult;
+
+/**
+ * Get the version of the Lumen compiler.
+ */
+export function version(): string;

package/lumen_wasm.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./lumen_wasm.d.ts" */
+
+import * as wasm from "./lumen_wasm_bg.wasm";
+import { __wbg_set_wasm } from "./lumen_wasm_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    LumenResult, check, compile, run, version
+} from "./lumen_wasm_bg.js";

package/lumen_wasm_bg.js

@@ -0,0 +1,264 @@
+/**
+ * Result of a compilation or execution operation.
+ *
+ * JSON format:
+ * - Success: `{"ok": "result_value"}`
+ * - Error: `{"error": "error_message"}`
+ */
+export class LumenResult {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(LumenResult.prototype);
+        obj.__wbg_ptr = ptr;
+        LumenResultFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        LumenResultFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_lumenresult_free(ptr, 0);
+    }
+    /**
+     * Returns true if the operation failed.
+     * @returns {boolean}
+     */
+    is_err() {
+        const ret = wasm.lumenresult_is_err(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Returns true if the operation succeeded.
+     * @returns {boolean}
+     */
+    is_ok() {
+        const ret = wasm.lumenresult_is_ok(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Returns the result as a JSON string.
+     * @returns {string}
+     */
+    to_json() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.lumenresult_to_json(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) LumenResult.prototype[Symbol.dispose] = LumenResult.prototype.free;
+
+/**
+ * Type-check a Lumen source file.
+ *
+ * Returns a LumenResult:
+ * - On success: `{"ok": "Type-checked successfully"}`
+ * - On error: `{"error": "error message with diagnostics"}`
+ * @param {string} source
+ * @returns {LumenResult}
+ */
+export function check(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.check(ptr0, len0);
+    return LumenResult.__wrap(ret);
+}
+
+/**
+ * Compile Lumen source to LIR JSON.
+ *
+ * Returns a LumenResult:
+ * - On success: `{"ok": "<LIR JSON>"}`
+ * - On error: `{"error": "error message with diagnostics"}`
+ * @param {string} source
+ * @returns {LumenResult}
+ */
+export function compile(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.compile(ptr0, len0);
+    return LumenResult.__wrap(ret);
+}
+
+/**
+ * Compile and execute Lumen source.
+ *
+ * Returns a LumenResult:
+ * - On success: `{"ok": "<output>"}`
+ * - On error: `{"error": "error message"}`
+ *
+ * The `cell_name` parameter specifies which cell to execute (default: "main").
+ * @param {string} source
+ * @param {string | null} [cell_name]
+ * @returns {LumenResult}
+ */
+export function run(source, cell_name) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    var ptr1 = isLikeNone(cell_name) ? 0 : passStringToWasm0(cell_name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    const ret = wasm.run(ptr0, len0, ptr1, len1);
+    return LumenResult.__wrap(ret);
+}
+
+/**
+ * Get the version of the Lumen compiler.
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.version();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+export function __wbg___wbindgen_throw_be289d5034ed271b(arg0, arg1) {
+    throw new Error(getStringFromWasm0(arg0, arg1));
+}
+export function __wbg_getRandomValues_71d446877d8b0ad4() { return handleError(function (arg0, arg1) {
+    globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+}, arguments); }
+export function __wbg_getTime_1e3cd1391c5c3995(arg0) {
+    const ret = arg0.getTime();
+    return ret;
+}
+export function __wbg_new_0_73afc35eb544e539() {
+    const ret = new Date();
+    return ret;
+}
+export function __wbindgen_init_externref_table() {
+    const table = wasm.__wbindgen_externrefs;
+    const offset = table.grow(4);
+    table.set(0, undefined);
+    table.set(offset + 0, undefined);
+    table.set(offset + 1, null);
+    table.set(offset + 2, true);
+    table.set(offset + 3, false);
+}
+const LumenResultFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_lumenresult_free(ptr >>> 0, 1));
+
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+
+let wasm;
+export function __wbg_set_wasm(val) {
+    wasm = val;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "lumen-wasm",
+  "type": "module",
+  "collaborators": [
+    "Lumen Contributors"
+  ],
+  "description": "WebAssembly bindings for the Lumen compiler and VM",
+  "version": "0.1.1",
+  "license": "MIT OR Apache-2.0",
+  "files": [
+    "lumen_wasm_bg.wasm",
+    "lumen_wasm.js",
+    "lumen_wasm_bg.js",
+    "lumen_wasm.d.ts"
+  ],
+  "main": "lumen_wasm.js",
+  "types": "lumen_wasm.d.ts",
+  "sideEffects": [
+    "./lumen_wasm.js",
+    "./snippets/*"
+  ]
+}