jz 0.1.0 → 0.2.0

package/index.js

@@ -38,11 +38,12 @@
  * @module jz
  */
 
-import { parse } from 'subscript/jessie'
+import { parse } from 'subscript/feature/jessie'
 import { compile as watrCompile, print as watrPrint, optimize as watrOptimize } from "watr";
-import { ctx, reset } from './src/ctx.js'
+import { ctx, reset, err } from './src/ctx.js'
 import prepare, { GLOBALS } from './src/prepare.js'
-import compile, { emitter } from './src/compile.js'
+import compile from './src/compile.js'
+import { emitter } from './src/emit.js'
 import { optimizeFunc, resolveOptimize } from './src/optimize.js'
 import jzify from './src/jzify.js'
 import {
@@ -62,6 +63,83 @@ const importsMayReturnExternal = (imports) => {
   return false
 }
 
+const nowMs = () => globalThis.performance?.now ? globalThis.performance.now() : Date.now()
+
+const compileProfiler = (profile) => {
+  if (profile == null) return null
+  if (typeof profile !== 'object') throw new TypeError('opts.profile must be an object sink; use { profile: { names: true } } to emit a wasm name section')
+  profile.entries ||= []
+  profile.totals ||= {}
+  return {
+    time(name, fn) {
+      const start = nowMs()
+      try { return fn() }
+      finally {
+        const ms = nowMs() - start
+        profile.entries.push({ name, ms })
+        profile.totals[name] = (profile.totals[name] || 0) + ms
+      }
+    },
+  }
+}
+
+const uleb = (n) => {
+  const out = []
+  do {
+    let b = n & 0x7f
+    n >>>= 7
+    if (n) b |= 0x80
+    out.push(b)
+  } while (n)
+  return out
+}
+
+const utf8Bytes = (s) => [...new TextEncoder().encode(s)]
+const nameBytes = (s) => {
+  const bytes = utf8Bytes(s)
+  return [...uleb(bytes.length), ...bytes]
+}
+
+const watName = (s) => typeof s === 'string' && s.startsWith('$') ? s.slice(1) : null
+const quotedName = (s) => typeof s === 'string' && /^".*"$/.test(s) ? s.slice(1, -1) : null
+
+const importFuncName = (node) => {
+  if (!Array.isArray(node) || node[0] !== 'import') return null
+  const desc = node[3]
+  if (!Array.isArray(desc) || desc[0] !== 'func') return null
+  return watName(desc[1]) || quotedName(node[2])
+}
+
+const functionNameSection = (module) => {
+  const entries = []
+  let funcIdx = 0
+  for (const node of module) {
+    if (!Array.isArray(node)) continue
+    if (node[0] === 'import') {
+      const name = importFuncName(node)
+      if (name != null) entries.push([funcIdx++, name])
+    } else if (node[0] === 'func') {
+      const name = watName(node[1])
+      if (name != null) entries.push([funcIdx, name])
+      funcIdx++
+    }
+  }
+  if (!entries.length) return null
+  const map = [...uleb(entries.length)]
+  for (const [idx, name] of entries) map.push(...uleb(idx), ...nameBytes(name))
+  const payload = [...nameBytes('name'), 1, ...uleb(map.length), ...map]
+  return Uint8Array.from([0, ...uleb(payload.length), ...payload])
+}
+
+const appendFunctionNames = (wasm, module) => {
+  const section = functionNameSection(module)
+  if (!section) return wasm
+  const out = new Uint8Array(wasm.length + section.length)
+  out.set(wasm)
+  out.set(section, wasm.length)
+  return out
+}
+
 /**
  * jz — JS subset → WASM compiler.
  *
@@ -84,8 +162,12 @@ jz.memory = enhanceMemory
  * @param {boolean} [opts.strict] - Reject dynamic features (obj[k], for-in, unknown
  *   receiver method calls) at compile time. Avoids pulling dynamic-dispatch stdlib
  *   into output; large size win for static programs.
- * @param {boolean} [opts.runtimeExports=true] - Export runtime allocator helpers
- *   (`_alloc`, `_reset`) for JS memory wrapping. Set false for standalone host-run
+ * @param {WebAssembly.Memory|number} [opts.memory] - Shared memory import, or
+ *   initial page count for owned memory when a number is passed.
+ * @param {number} [opts.memoryPages] - Legacy alias for owned/imported memory
+ *   initial page count. Prefer `memory: N` for owned memory.
+ * @param {boolean} [opts.alloc=true] - Export raw allocator helpers
+ *   (`_alloc`, `_clear`) for JS memory wrapping. Set false for standalone host-run
  *   modules that only call exported wasm functions.
  * @param {boolean|number|object} [opts.optimize] - Optimization level/config.
  *   - `false` / `0`: nothing. Fastest compile, largest output (live coding).
@@ -94,13 +176,24 @@ jz.memory = enhanceMemory
  *   - `3`: reserved for future aggressive passes (currently == 2).
  *   - `{ level?: 0|1|2|3, watr?: bool, hoistAddrBase?: bool, ... }`: per-pass
  *     overrides on top of the chosen level. See PASS_NAMES in src/optimize.js.
+ * @param {object} [opts.profile] - Optional mutable profile sink populated with
+ *   `entries` and `totals` for parse / jzify / prepare / compile / plan / watr phases.
+ *   Set `profile.names = true` to also emit a standard wasm `name` custom section
+ *   for profiler/debugger symbolication.
+ * @param {boolean} [opts.profileNames] - Legacy alias for `profile.names`.
+ * @param {string} [opts.importMetaUrl] - Module URL used to lower `import.meta.url`
+ *   and static `import.meta.resolve("...")` expressions.
  * @returns {Uint8Array|string}
  */
 jz.compile = (code, opts = {}) => {
+  const profiler = compileProfiler(opts.profile)
+  const time = (name, fn) => profiler ? profiler.time(name, fn) : fn()
+
   reset(emitter, GLOBALS)
   ctx.error.src = code
 
-  if (opts.memory) ctx.memory.shared = true
+  if (typeof opts.memory === 'number') ctx.memory.pages = opts.memory
+  else if (opts.memory) ctx.memory.shared = true
   if (opts.memoryPages) ctx.memory.pages = opts.memoryPages
   if (opts.modules) ctx.module.importSources = opts.modules
   if (opts.imports) {
@@ -112,34 +205,60 @@ jz.compile = (code, opts = {}) => {
   if (opts.jzify) ctx.transform.jzify = jzify
   if (opts.noTailCall) ctx.transform.noTailCall = true
   if (opts.strict) ctx.transform.strict = true
-  if (opts.runtimeExports === false) ctx.transform.runtimeExports = false
+  if (opts.host) {
+    if (opts.host !== 'js' && opts.host !== 'wasi') err(`Invalid host '${opts.host}'. Expected 'js' or 'wasi'.`)
+    ctx.transform.host = opts.host
+  }
+  if (opts.alloc === false) ctx.transform.alloc = false
+  if (opts.importMetaUrl) ctx.transform.importMetaUrl = String(opts.importMetaUrl)
   if (opts.nativeTimers) ctx.features.blockingTimers = true  // wasmtime CLI: include __timer_loop in _start
   ctx.transform.optimize = resolveOptimize(opts.optimize)
 
   if (opts._interp) {
     for (const [name, fn] of Object.entries(opts._interp)) {
       if (name.startsWith('__ext_')) continue;
+      if (ctx.transform.host === 'wasi') throw new Error(`host:'wasi' does not support _interp['${name}']: env imports are unavailable in WASI. Implement it natively.`)
       ctx.features.external = true
       const params = Array(fn.length).fill(['param', 'f64'])
       ctx.module.imports.push(['import', '"env"', `"${name}"`, ['func', `$${name}`, ...params, ['result', 'f64']]])
     }
   }
 
-  let parsed = parse(code)
-  if (opts.jzify) parsed = jzify(parsed)
-  const ast = prepare(parsed)
-  const module = compile(ast)
+  let parsed = time('parse', () => parse(code))
+  if (opts.jzify) parsed = time('jzify', () => jzify(parsed))
+  const ast = time('prepare', () => prepare(parsed))
+  const module = time('compile', () => compile(ast, profiler))
+
+  // host: 'wasi' — error if the wasm would import any env.__ext_* helper. Those exist
+  // only to defer to a JS host's value-aware semantics; in a wasmtime/wasmer/deno
+  // sandbox the imports either go unsatisfied or are stubbed out and silently produce
+  // wrong output. Surface the gap at compile so the caller can pick a comparator,
+  // type-annotate the receiver, or wait for native lowering. Read `extImports`
+  // (populated in pullStdlib) — `core.includes` has had these removed by then.
+  if (ctx.transform.host === 'wasi' && ctx.core.extImports?.size) {
+    const ext = [...ctx.core.extImports].sort()
+    err(
+      `host: 'wasi' — compiled wasm would require JS-host imports that wasmtime/wasmer/deno cannot satisfy:\n  ` +
+      ext.map(n => `env.${n}`).join('\n  ') +
+      `\nThis happens when jz falls through to dynamic dispatch for a method or property without a native lowering. ` +
+      `Either annotate the receiver type, switch to a natively-supported method, or compile with the default host.`)
+  }
 
   const cfg = ctx.transform.optimize
-  const optimized = cfg.watr ? watrOptimize(module) : module
+  const optimized = cfg.watr ? time('watrOptimize', () => watrOptimize(module)) : module
   // Final peephole pass: watrOptimize's inliner can re-introduce rebox/unbox at boundaries
   // (e.g. inlined closure body's `i32.wrap_i64 (i64.reinterpret_f64 __env)` next to caller's
   // `boxPtrIR(g)` rebox). Our fusedRewrite folds these, watr's peephole doesn't.
   // Only valuable to re-run when watr ran (watr is what re-introduces the boundaries).
   if (cfg.watr) {
-    for (const node of optimized) if (Array.isArray(node) && node[0] === 'func') optimizeFunc(node, cfg)
+    const postCfg = { ...cfg, __phase: 'post' }
+    time('watrReopt', () => {
+      for (const node of optimized) if (Array.isArray(node) && node[0] === 'func') optimizeFunc(node, postCfg)
+    })
   }
-  return opts.wat ? watrPrint(optimized) : watrCompile(optimized)
+  if (opts.wat) return time('watrPrint', () => watrPrint(optimized))
+  const wasm = time('watrCompile', () => watrCompile(optimized))
+  return (opts.profileNames || opts.profile?.names) ? appendFunctionNames(wasm, optimized) : wasm
 }
 
 /**