fix(plugin): fall back to module mode when a binary cannot be parsed - #112

Problem

When the WebAssembly reader cannot decode a binary, the build emits an ESM binding that cannot possibly instantiate — and the failure surfaces at module scope in production, not at build time.

parse() catches the decoder error, console.warns it, and then caches and returns the empty accumulators:

} catch (error) {
  console.warn(`[unwasm] Failed to parse WASM module ${name}:`, error);
}
_parseCache[name] = { imports, exports };  // both empty on failure

An empty result is indistinguishable from a module that genuinely has no imports, so both existing fallbacks are bypassed:

• The try/catch around parse() in transform only fires if parse throws, which it never does. Its isModule = true branch is unreachable for a parse failure.
• getWasmImports sees importNames.length === 0 and returns { code: "const _imports = { /* no imports */ }", resolved: true } — a successful resolution — so the getWasmESMBinding(...).catch(...) fallback does not fire either.

The eager binding is emitted, and for a module that does declare imports, WebAssembly.instantiate throws under a top-level await at module scope:

WebAssembly.instantiate(): Import #0 "env": module is not an object or function

On a Workers/Cloudflare build that means the worker fails at boot and never serves a request.

Reported in #111 against @oxc-parser/binding-wasm32-wasi. The reproduction there predates the in-tree reader, but the defect is in the plugin's error handling, not the decoder, so it survived the rewrite: any binary the reader declines still takes this path today.

Fix

Let the parse failure propagate. transform already has the correct handler for it one frame up — the catch that sets isModule = true and warns through this.warn — it just never received anything.

-    try {
-      const parsed = parseWasm(source, { name });
-      ...
-    } catch (error) {
-      console.warn(...);
-    }
+    const parsed = parseWasm(source, { name });
+    ...

Three things follow from this, all of which were already implemented and simply unreachable:

• Module mode is used, handing the binary to the engine, which understands the sections and proposals the reader does not. getWasmModuleBinding needs no interface information at all, so it is correct for exactly the binaries the reader cannot describe.
• The warning goes through this.warn instead of console.warn, so it carries the module id, is attributed to the plugin, and respects the existing silent option (which console.warn ignored).
• Nothing is cached on failure, since the assignment to _parseCache is now after the throwing call. A second transform of the same asset re-parses and fails again rather than reading a cache entry that looks like a successful parse — relevant to watch mode and to multi-entry builds sharing an asset.

Behaviour for parsable modules is unchanged; ?module imports and modules that genuinely declare no imports are untouched.

Tests

test/parse-fallback.test.ts drives the transform hook over a hand-assembled binary whose import section declares kind 0x09. Import kinds are open ended and each descriptor is kind specific, so an unknown kind leaves the reader no way to locate the next import — it is the smallest honest stand-in for the oxc binary in #111, without vendoring a 30 MB fixture.

• The emitted code is a WebAssembly.Module binding, and contains neither no imports nor _instantiate — i.e. the build is not wired to an interface derived from a parse that never succeeded. On main this assertion fails with the eager, unsatisfiable binding.
• A second transform of the same asset still falls back (pins the cache behaviour).
• silent: true suppresses the warning, which console.warn did not.

Validation

• vitest run — 54 passed (3 files), including the rollup/rolldown/vite build matrix
• oxlint . && oxfmt --check src test — clean
• Both new assertions verified to fail on main before the fix

Fixes #111.

Summary by CodeRabbit

• Bug Fixes

  • Improved handling of unsupported WebAssembly binaries by issuing a warning and falling back to module mode instead of producing invalid results.
  • Parsing failures now propagate correctly to the transformation process, ensuring consistent fallback behavior.

• Tests

  • Expanded coverage for parser and engine validation, generated module compilation, exports, instantiation failures, and unsupported WebAssembly imports.