@webassemblyjs/wasm-edit 1.14.1: edit WebAssembly binary AST nodes using wasm-edit

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: edit WebAssembly binary AST nodes using wasm-edit
Kind: HOW

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

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:c6e9ad394cf1c9cf3c13d8f11f8ef68bc8e4f5a1fce75bb86f2a53a645f2ffc4","contract":["assert add inserts AST nodes into a WebAssembly binary ArrayBuffer","assert edit modifies AST nodes in-place within a WebAssembly binary ArrayBuffer","assert edit removes AST nodes when path.remove() is called in visitor","assert addWithAST inserts AST nodes using a pre-decoded Program AST","assert editWithAST updates AST nodes using a pre-decoded Program AST"],"goal":"edit WebAssembly binary AST nodes using wasm-edit","kind":"HOW","packages":["pkg:npm/%40webassemblyjs/wasm-edit@1.14.1"],"schemaVersion":1,"symbols":["add","edit"]},"contractCommand":["node","test/contract.mjs"],"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-edit@1.14.1"],"schemaVersion":1,"subject":"pkg:npm/%40webassemblyjs/wasm-edit@1.14.1","symbols":["add","edit"],"verifierAdapter":"node-typescript@1"}

const { edit, add, editWithAST, addWithAST } = require('@webassemblyjs/wasm-edit');
const { decode } = require('@webassemblyjs/wasm-parser');
const t = require('@webassemblyjs/ast');

/**
 * Adds a memory import node to a WebAssembly binary.
 *
 * @param {ArrayBuffer} binary - The WebAssembly binary buffer.
 * @param {string} moduleName - The imported module name.
 * @param {string} fieldName - The imported field name.
 * @param {number} [initialMemory=1] - Initial memory page limit.
 * @returns {ArrayBuffer} The updated WebAssembly binary buffer.
 */
function addMemoryImport(binary, moduleName, fieldName, initialMemory = 1) {
  const importNode = t.moduleImport(
    moduleName,
    fieldName,
    t.memory(t.limit(initialMemory))
  );
  return add(binary, [importNode]);
}

/**
 * Renames module imports in a WebAssembly binary.
 *
 * @param {ArrayBuffer} binary - The WebAssembly binary buffer.
 * @param {string} fromModule - The original module name to match.
 * @param {string} toModule - The new module name.
 * @param {string} [toName] - Optional new field name.
 * @returns {ArrayBuffer} The updated WebAssembly binary buffer.
 */
function renameImport(binary, fromModule, toModule, toName) {
  return edit(binary, {
    ModuleImport({ node }) {
      if (node.module === fromModule) {
        node.module = toModule;
        if (toName) {
          node.name = toName;
        }
      }
    }
  });
}

/**
 * Removes an export node from a WebAssembly binary by name.
 *
 * @param {ArrayBuffer} binary - The WebAssembly binary buffer.
 * @param {string} exportName - Name of the export to remove.
 * @returns {ArrayBuffer} The updated WebAssembly binary buffer.
 */
function removeExportByName(binary, exportName) {
  return edit(binary, {
    ModuleExport(path) {
      if (path.node.name === exportName) {
        path.remove();
      }
    }
  });
}

module.exports = {
  edit,
  add,
  editWithAST,
  addWithAST,
  addMemoryImport,
  renameImport,
  removeExportByName
};

{
  "name": "sample-wasm-edit",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-wasm-edit",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@webassemblyjs/wasm-edit": "1.14.1",
        "@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-buffer": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/helper-buffer/-/helper-buffer-1.14.1.tgz",
      "integrity": "sha512-jyH7wtcHiKssDtFPRB+iQdxlDf96m0E39yb0k5uJVhFGleZFoNw1c4aeIcVUPPbXUVJ94wwnMOAqUHyzoEPVMA==",
      "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/helper-wasm-section": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/helper-wasm-section/-/helper-wasm-section-1.14.1.tgz",
      "integrity": "sha512-ds5mXEqTJ6oxRoqjhWDU83OgzAYjwsCV8Lo/N+oRsNDmx/ZDpqalmrtgOMkHwxsG0iI//3BwWAErYRHtgn0dZw==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@webassemblyjs/helper-buffer": "1.14.1",
        "@webassemblyjs/helper-wasm-bytecode": "1.13.2",
        "@webassemblyjs/wasm-gen": "1.14.1"
      }
    },
    "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-edit": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/wasm-edit/-/wasm-edit-1.14.1.tgz",
      "integrity": "sha512-RNJUIQH/J8iA/1NzlE4N7KtyZNHi3w7at7hDjvRNm5rcUXa00z1vRz3glZoULfJ5mpvYhLybmVcwcjGrC1pRrQ==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@webassemblyjs/helper-buffer": "1.14.1",
        "@webassemblyjs/helper-wasm-bytecode": "1.13.2",
        "@webassemblyjs/helper-wasm-section": "1.14.1",
        "@webassemblyjs/wasm-gen": "1.14.1",
        "@webassemblyjs/wasm-opt": "1.14.1",
        "@webassemblyjs/wasm-parser": "1.14.1",
        "@webassemblyjs/wast-printer": "1.14.1"
      }
    },
    "node_modules/@webassemblyjs/wasm-gen": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/wasm-gen/-/wasm-gen-1.14.1.tgz",
      "integrity": "sha512-AmomSIjP8ZbfGQhumkNvgC33AY7qtMCXnN6bL2u2Js4gVCg8fp735aEiMSBbDR7UQIj90n4wKAFUSEd0QN2Ukg==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@webassemblyjs/helper-wasm-bytecode": "1.13.2",
        "@webassemblyjs/ieee754": "1.13.2",
        "@webassemblyjs/leb128": "1.13.2",
        "@webassemblyjs/utf8": "1.13.2"
      }
    },
    "node_modules/@webassemblyjs/wasm-opt": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/wasm-opt/-/wasm-opt-1.14.1.tgz",
      "integrity": "sha512-PTcKLUNvBqnY2U6E5bdOQcSM+oVP/PmrDY9NzowJjislEjwP/C4an2303MCVS2Mg9d3AJpIGdUFIQQWbPds0Sw==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@webassemblyjs/helper-buffer": "1.14.1",
        "@webassemblyjs/wasm-gen": "1.14.1",
        "@webassemblyjs/wasm-parser": "1.14.1"
      }
    },
    "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/@webassemblyjs/wast-printer": {
      "version": "1.14.1",
      "resolved": "https://registry.npmjs.org/@webassemblyjs/wast-printer/-/wast-printer-1.14.1.tgz",
      "integrity": "sha512-kPSSXE6De1XOR820C90RIo2ogvZG+c3KiHzqUoO/F34Y2shGzesfqv7o57xrxovZJH/MetF5UjroJ/R/3isoiw==",
      "license": "MIT",
      "dependencies": {
        "@webassemblyjs/ast": "1.14.1",
        "@xtuc/long": "4.2.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-edit",
  "version": "1.0.0",
  "description": "Clean-room sample verifying @webassemblyjs/wasm-edit AST editing and addition",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "@webassemblyjs/ast": "1.14.1",
    "@webassemblyjs/wasm-edit": "1.14.1",
    "@webassemblyjs/wasm-parser": "1.14.1"
  }
}

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

import assert from 'node:assert';
import { decode } from '@webassemblyjs/wasm-parser';
import * as t from '@webassemblyjs/ast';
import {
  edit,
  add,
  editWithAST,
  addWithAST,
  addMemoryImport,
  renameImport,
  removeExportByName
} from '../index.js';

// Minimal valid WASM binary header (\0asm \1\0\0\0)
const createEmptyWasmBinary = () =>
  new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]).buffer;

// 1. Assert add inserts AST nodes into a WebAssembly binary ArrayBuffer
{
  const initialBinary = createEmptyWasmBinary();
  const importNode = t.moduleImport('env', 'memory', t.memory(t.limit(1)));
  const updatedBinary = add(initialBinary, [importNode]);

  assert(updatedBinary instanceof ArrayBuffer, 'add must return an ArrayBuffer');
  assert(updatedBinary.byteLength > initialBinary.byteLength, 'updated binary must be larger');

  const ast = decode(updatedBinary);
  const imports = ast.body[0].fields.filter(f => f.type === 'ModuleImport');
  assert.strictEqual(imports.length, 1, 'must contain exactly 1 import');
  assert.strictEqual(imports[0].module, 'env', 'import module must match');
  assert.strictEqual(imports[0].name, 'memory', 'import name must match');
}

// 2. Assert edit modifies AST nodes in-place within a WebAssembly binary ArrayBuffer
{
  const initialBinary = createEmptyWasmBinary();
  const withImport = addMemoryImport(initialBinary, 'env', 'memory', 1);
  const editedBinary = renameImport(withImport, 'env', 'custom_env', 'custom_memory');

  assert(editedBinary instanceof ArrayBuffer, 'edit must return an ArrayBuffer');
  const ast = decode(editedBinary);
  const imports = ast.body[0].fields.filter(f => f.type === 'ModuleImport');
  assert.strictEqual(imports.length, 1, 'must contain 1 import');
  assert.strictEqual(imports[0].module, 'custom_env', 'module name must be updated');
  assert.strictEqual(imports[0].name, 'custom_memory', 'field name must be updated');
}

// 3. Assert edit removes AST nodes when path.remove() is called in visitor
{
  const initialBinary = createEmptyWasmBinary();
  const withImport = addMemoryImport(initialBinary, 'env', 'memory', 1);
  const exportNode = t.moduleExport('myMemExport', t.moduleExportDescr('Memory', t.indexLiteral(0)));
  const withExport = add(withImport, [exportNode]);

  const astBefore = decode(withExport);
  const exportsBefore = astBefore.body[0].fields.filter(f => f.type === 'ModuleExport');
  assert.strictEqual(exportsBefore.length, 1, 'export must exist before removal');

  const withoutExport = removeExportByName(withExport, 'myMemExport');
  const astAfter = decode(withoutExport);
  const exportsAfter = astAfter.body[0].fields.filter(f => f.type === 'ModuleExport');
  assert.strictEqual(exportsAfter.length, 0, 'export must be removed');
  const importsAfter = astAfter.body[0].fields.filter(f => f.type === 'ModuleImport');
  assert.strictEqual(importsAfter.length, 1, 'import must remain intact');
}

// 4. Assert addWithAST inserts AST nodes using a pre-decoded Program AST
{
  const initialBinary = createEmptyWasmBinary();
  const baseAST = decode(initialBinary);
  const importNode = t.moduleImport('host', 'memory', t.memory(t.limit(2)));
  const resultBinary = addWithAST(baseAST, initialBinary, [importNode]);

  assert(resultBinary instanceof ArrayBuffer, 'addWithAST must return an ArrayBuffer');
  const ast = decode(resultBinary);
  const imports = ast.body[0].fields.filter(f => f.type === 'ModuleImport');
  assert.strictEqual(imports.length, 1, 'must contain 1 import');
  assert.strictEqual(imports[0].module, 'host');
}

// 5. Assert editWithAST updates AST nodes using a pre-decoded Program AST
{
  const initialBinary = createEmptyWasmBinary();
  const withImport = addMemoryImport(initialBinary, 'orig_mod', 'orig_fn', 1);
  const baseAST = decode(withImport);

  const editedBinary = editWithAST(baseAST, withImport, {
    ModuleImport({ node }) {
      if (node.module === 'orig_mod') {
        node.module = 'updated_mod';
      }
    }
  });

  assert(editedBinary instanceof ArrayBuffer, 'editWithAST must return an ArrayBuffer');
  const ast = decode(editedBinary);
  const imports = ast.body[0].fields.filter(f => f.type === 'ModuleImport');
  assert.strictEqual(imports.length, 1, 'must contain 1 import');
  assert.strictEqual(imports[0].module, 'updated_mod');
}

console.log('All contract assertions passed.');