@webassemblyjs/wasm-parser 1.14.1: decode WebAssembly binary into AST using wasm-parser decode

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: decode WebAssembly binary into AST using wasm-parser decode
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40webassemblyjs/wasm-parser@1.14.1
Demonstrate these symbols/APIs:
  - decode

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:fa3b8f42ee144b273cd2289ca1b5fb8304b52bf630f45f2c85f1117c14ed55db","contract":["decode parses minimal WebAssembly binary into Program AST with empty Module","decode parses WebAssembly module containing type, func, export, and code sections","decode parses instruction details such as i32.const with NumberLiteral argument","decode respects ignoreCodeSection option to skip parsing function body instructions","decode throws unexpected end error when binary buffer is truncated","decode throws magic header not detected error when wasm magic bytes are invalid","parseWasmBinary helper decodes Uint8Array and Buffer inputs into AST"],"goal":"decode WebAssembly binary into AST using wasm-parser decode","kind":"HOW","packages":["pkg:npm/%40webassemblyjs/wasm-parser@1.14.1"],"schemaVersion":1,"symbols":["decode"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40webassemblyjs/wasm-parser@1.14.1"],"schemaVersion":1,"subject":"pkg:npm/%40webassemblyjs/wasm-parser@1.14.1","symbols":["decode"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-wasm-parser",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-wasm-parser",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@webassemblyjs/wasm-parser": "1.14.1"
      }
    },
    "node_modules/@webassemblyjs/ast": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/ast/-/ast-1.14.1.tgz",
      "integrity": "sha512-nuBEDgQfm1ccRp/8bCQrx1frohyufl4JlbMMZ4P1wpeOfDhF6FQkxZJ1b/e+PLwr6X1Nhw6OLme5usuBWYBvuQ==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/helper-numbers": "1.13.2",
        "@webassemblyjs/helper-wasm-bytecode": "1.13.2"
      }
    },
    "node_modules/@webassemblyjs/floating-point-hex-parser": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/floating-point-hex-parser/-/floating-point-hex-parser-1.13.2.tgz",
      "integrity": "sha512-6oXyTOzbKxGH4steLbLNOu71Oj+C8Lg34n6CqRvqfS2O71BxY6ByfMDRhBytzknj9yGUPVJ1qIKhRlAwO1AovA==",
      "license": "MIT"
    },
    "node_modules/@webassemblyjs/helper-api-error": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/helper-api-error/-/helper-api-error-1.13.2.tgz",
      "integrity": "sha512-U56GMYxy4ZQCbDZd6JuvvNV/WFildOjsaWD3Tzzvmw/mas3cXzRJPMjP83JqEsgSbyrmaGjBfDtV7KDXV9UzFQ==",
      "license": "MIT"
    },
    "node_modules/@webassemblyjs/helper-numbers": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/helper-numbers/-/helper-numbers-1.13.2.tgz",
      "integrity": "sha512-FE8aCmS5Q6eQYcV3gI35O4J789wlQA+7JrqTTpJqn5emA4U2hvwJmvFRC0HODS+3Ye6WioDklgd6scJ3+PLnEA==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/floating-point-hex-parser": "1.13.2",
        "@webassemblyjs/helper-api-error": "1.13.2",
        "@xtuc/long": "4.2.2"
      }
    },
    "node_modules/@webassemblyjs/helper-wasm-bytecode": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/helper-wasm-bytecode/-/helper-wasm-bytecode-1.13.2.tgz",
      "integrity": "sha512-3QbLKy93F0EAIXLh0ogEVR6rOubA9AoZ+WRYhNbFyuB70j3dRdwH9g+qXhLAO0kiYGlg3TxDV+I4rQTr/YNXkA==",
      "license": "MIT"
    },
    "node_modules/@webassemblyjs/ieee754": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/ieee754/-/ieee754-1.13.2.tgz",
      "integrity": "sha512-4LtOzh58S/5lX4ITKxnAK2USuNEvpdVV9AlgGQb8rJDHaLeHciwG4zlGr0j/SNWlr7x3vO1lDEsuePvtcDNCkw==",
      "license": "MIT",
      "dependencies": {
        "@xtuc/ieee754": "^1.2.0"
      }
    },
    "node_modules/@webassemblyjs/leb128": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/leb128/-/leb128-1.13.2.tgz",
      "integrity": "sha512-Lde1oNoIdzVzdkNEAWZ1dZ5orIbff80YPdHx20mrHwHrVNNTjNr8E3xz9BdpcGqRQbAEa+fkrCb+fRFTl/6sQw==",
      "license": "Apache-2.0",
      "dependencies": {
        "@xtuc/long": "4.2.2"
      }
    },
    "node_modules/@webassemblyjs/utf8": {
      "version": "1.13.2",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/utf8/-/utf8-1.13.2.tgz",
      "integrity": "sha512-3NQWGjKTASY1xV5m7Hr0iPeXD9+RDobLll3T9d2AO+g3my8xy5peVyjSag4I50mR1bBSN/Ct12lo+R9tJk0NZQ==",
      "license": "MIT"
    },
    "node_modules/@webassemblyjs/wasm-parser": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/wasm-parser/-/wasm-parser-1.14.1.tgz",
      "integrity": "sha512-JLBl+KZ0R5qB7mCnud/yyX08jWFw5MsoalJ1pQ4EdFlgj9VdXKGuENGsiCIjegI1W7p91rUlcB/LB5yRJKNTcQ==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@webassemblyjs/helper-api-error": "1.13.2",
        "@webassemblyjs/helper-wasm-bytecode": "1.13.2",
        "@webassemblyjs/ieee754": "1.13.2",
        "@webassemblyjs/leb128": "1.13.2",
        "@webassemblyjs/utf8": "1.13.2"
      }
    },
    "node_modules/@xtuc/ieee754": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/@xtuc/ieee754/-/ieee754-1.2.0.tgz",
      "integrity": "sha512-DX8nKgqcGwsc0eJSqYt5lwP4DH5FlHnmuWWBRy7X0NcaGR0ZtuyeESgMwTYVEtxmsNGY+qit4QYT/MIYTOTPeA==",
      "license": "BSD-3-Clause"
    },
    "node_modules/@xtuc/long": {
      "version": "4.2.2",
      "resolved": "https://registry.npmjs.org/@xtuc/long/-/long-4.2.2.tgz",
      "integrity": "sha512-NuHqBY1PB/D8xU6s/thBgOAiAP7HOYDQ32+BFZILJ8ivkUkAHQnWfn6WhL79Owj1qmUnoN/YPhktdIoucipkAQ==",
      "license": "Apache-2.0"
    }
  }
}

{
  "name": "sample-wasm-parser",
  "version": "1.0.0",
  "description": "decode WebAssembly binary into AST using wasm-parser decode",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "@webassemblyjs/wasm-parser": "1.14.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "decode WebAssembly binary into AST using wasm-parser decode",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40webassemblyjs/wasm-parser@1.14.1"
  ],
  "symbols": [
    "decode"
  ]
}

'use strict';

const { decode } = require('@webassemblyjs/wasm-parser');

/**
 * Decodes a WebAssembly binary into an AST.
 * Accepts ArrayBuffer, Buffer, or Uint8Array.
 *
 * @param {ArrayBuffer|Uint8Array|Buffer} buffer
 * @param {Object} [options]
 * @returns {Object} AST Program node
 */
function parseWasmBinary(buffer, options) {
  let arrayBuffer;
  if (buffer instanceof ArrayBuffer) {
    arrayBuffer = buffer;
  } else if (ArrayBuffer.isView(buffer)) {
    arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
  } else if (Array.isArray(buffer)) {
    arrayBuffer = new Uint8Array(buffer).buffer;
  } else {
    throw new TypeError('Expected an ArrayBuffer, Uint8Array, Buffer, or byte array');
  }

  return decode(arrayBuffer, options);
}

module.exports = {
  decode,
  parseWasmBinary
};

'use strict';

const assert = require('assert');
const { decode, parseWasmBinary } = require('../src/index');

// 1. Export verification
{
  assert.strictEqual(typeof decode, 'function');
  assert.strictEqual(typeof parseWasmBinary, 'function');
}

// 2. Decode minimal WebAssembly binary into Program AST with empty Module
{
  const minimalWasm = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
  const ast = decode(minimalWasm.buffer);

  assert.strictEqual(ast.type, 'Program');
  assert.strictEqual(Array.isArray(ast.body), true);
  assert.strictEqual(ast.body.length, 1);
  assert.strictEqual(ast.body[0].type, 'Module');
  assert.strictEqual(ast.body[0].id, null);
  assert.deepStrictEqual(ast.body[0].fields, []);
  assert.strictEqual(ast.body[0].metadata.type, 'ModuleMetadata');
  assert.deepStrictEqual(ast.body[0].metadata.sections, []);
}

// 3. Decode WebAssembly module containing type, func, export, and code sections
{
  const wasmWithFunc = new Uint8Array([
    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, // header
    0x01, 0x05, 0x01, 0x60, 0x00, 0x01, 0x7f,       // type section: () -> i32
    0x03, 0x02, 0x01, 0x00,                         // func section: func 0 uses type 0
    0x07, 0x08, 0x01, 0x04, 0x6d, 0x61, 0x69, 0x6e, 0x00, 0x00, // export 'main' -> func 0
    0x0a, 0x06, 0x01, 0x04, 0x00, 0x41, 0x2a, 0x0b // code section: i32.const 42, end
  ]);

  const ast = decode(wasmWithFunc.buffer);
  assert.strictEqual(ast.type, 'Program');
  const moduleNode = ast.body[0];
  assert.strictEqual(moduleNode.type, 'Module');
  assert.strictEqual(moduleNode.fields.length, 3);

  const typeInst = moduleNode.fields[0];
  assert.strictEqual(typeInst.type, 'TypeInstruction');
  assert.strictEqual(typeInst.functype.type, 'Signature');
  assert.deepStrictEqual(typeInst.functype.params, []);
  assert.deepStrictEqual(typeInst.functype.results, ['i32']);

  const funcNode = moduleNode.fields[1];
  assert.strictEqual(funcNode.type, 'Func');
  assert.strictEqual(funcNode.name.value, 'func_0');
  assert.strictEqual(funcNode.body.length, 2);

  const exportNode = moduleNode.fields[2];
  assert.strictEqual(exportNode.type, 'ModuleExport');
  assert.strictEqual(exportNode.name, 'main');
  assert.strictEqual(exportNode.descr.exportType, 'Func');
}

// 4. Decode instruction details such as i32.const with NumberLiteral argument
{
  const wasmWithConst = new Uint8Array([
    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
    0x01, 0x05, 0x01, 0x60, 0x00, 0x01, 0x7f,
    0x03, 0x02, 0x01, 0x00,
    0x07, 0x08, 0x01, 0x04, 0x6d, 0x61, 0x69, 0x6e, 0x00, 0x00,
    0x0a, 0x06, 0x01, 0x04, 0x00, 0x41, 0x2a, 0x0b
  ]);

  const ast = decode(wasmWithConst.buffer);
  const funcNode = ast.body[0].fields.find(f => f.type === 'Func');
  const constInstr = funcNode.body[0];

  assert.strictEqual(constInstr.type, 'Instr');
  assert.strictEqual(constInstr.id, 'const');
  assert.strictEqual(constInstr.object, 'i32');
  assert.strictEqual(constInstr.args.length, 1);
  assert.strictEqual(constInstr.args[0].type, 'NumberLiteral');
  assert.strictEqual(constInstr.args[0].value, 42);

  const endInstr = funcNode.body[1];
  assert.strictEqual(endInstr.type, 'Instr');
  assert.strictEqual(endInstr.id, 'end');
}

// 5. Decode respects ignoreCodeSection option to skip parsing function body instructions
{
  const wasmWithFunc = new Uint8Array([
    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
    0x01, 0x05, 0x01, 0x60, 0x00, 0x01, 0x7f,
    0x03, 0x02, 0x01, 0x00,
    0x07, 0x08, 0x01, 0x04, 0x6d, 0x61, 0x69, 0x6e, 0x00, 0x00,
    0x0a, 0x06, 0x01, 0x04, 0x00, 0x41, 0x2a, 0x0b
  ]);

  const ast = decode(wasmWithFunc.buffer, { ignoreCodeSection: true });
  const funcNode = ast.body[0].fields.find(f => f.type === 'Func');
  assert.strictEqual(funcNode.type, 'Func');
  assert.deepStrictEqual(funcNode.body, []);
}

// 6. Decode throws unexpected end error when binary buffer is truncated
{
  const truncatedWasm = new Uint8Array([0x00, 0x61, 0x73]);
  assert.throws(
    () => decode(truncatedWasm.buffer),
    /unexpected end/
  );
}

// 7. Decode throws magic header not detected error when wasm magic bytes are invalid
{
  const invalidMagic = new Uint8Array([0x01, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
  assert.throws(
    () => decode(invalidMagic.buffer),
    /magic header not detected/
  );
}

// 8. parseWasmBinary helper decodes Uint8Array and Buffer inputs into AST
{
  const wasmBytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
  const astFromUint8 = parseWasmBinary(wasmBytes);
  assert.strictEqual(astFromUint8.type, 'Program');

  const astFromBuffer = parseWasmBinary(Buffer.from(wasmBytes));
  assert.strictEqual(astFromBuffer.type, 'Program');

  const astFromArray = parseWasmBinary([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
  assert.strictEqual(astFromArray.type, 'Program');
}

console.log('All wasm-parser decode contract tests passed.');