@webassemblyjs/ast 1.14.1: parse raw numeric literals and look up instruction signatures with @webassemblyjs/ast

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: parse raw numeric literals and look up instruction signatures with @webassemblyjs/ast
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40webassemblyjs/ast@1.14.1
Demonstrate these symbols/APIs:
  - instruction
  - numberLiteralFromRaw
  - signatureForOpcode
  - signatures
  - withLoc

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:7465098ef6bb9dc06c5c7fc7032e6fc3029b2d4ac79d65ac51875b328ded4876","contract":["numberLiteralFromRaw parses integer and floating-point literals with type coercion and raw string preservation","signatures provides instruction signatures mapping WebAssembly opcodes to parameter and result types","signatureForOpcode looks up parameter types for standard and object-prefixed WebAssembly opcodes","instruction and objectInstruction build instruction AST nodes with arguments and locations","withLoc attaches source location metadata to AST nodes"],"goal":"parse raw numeric literals and look up instruction signatures with @webassemblyjs/ast","kind":"HOW","packages":["pkg:npm/%40webassemblyjs/ast@1.14.1"],"schemaVersion":1,"symbols":["instruction","numberLiteralFromRaw","signatureForOpcode","signatures","withLoc"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40webassemblyjs/ast@1.14.1"],"schemaVersion":1,"subject":"pkg:npm/%40webassemblyjs/ast@1.14.1","symbols":["instruction","numberLiteralFromRaw","signatureForOpcode","signatures","withLoc"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-webassemblyjs-ast-literals-signatures",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-webassemblyjs-ast-literals-signatures",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@webassemblyjs/ast": "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/@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-webassemblyjs-ast-literals-signatures",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for @webassemblyjs/ast@1.14.1 numeric literals and signatures",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@webassemblyjs/ast": "1.14.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "parse raw numeric literals and look up instruction signatures with @webassemblyjs/ast",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40webassemblyjs/ast@1.14.1"
  ],
  "symbols": [
    "instruction",
    "numberLiteralFromRaw",
    "signatureForOpcode",
    "signatures",
    "withLoc"
  ]
}

'use strict';

const ast = require('@webassemblyjs/ast');

/**
 * Parses raw numeric literals into appropriate WebAssembly AST literal nodes.
 *
 * @param {string|number} rawValue - Raw numeric value or string (supports underscores and special values like nan/inf)
 * @param {'i32'|'u32'|'i64'|'f32'|'f64'} [instructionType='i32'] - Target WebAssembly numeric type
 * @returns {object} NumberLiteral, LongNumberLiteral, or FloatLiteral AST node
 */
function parseLiteral(rawValue, instructionType = 'i32') {
  return ast.numberLiteralFromRaw(rawValue, instructionType);
}

/**
 * Looks up parameter and result signatures for a given WebAssembly opcode.
 *
 * @param {string} opcode - WebAssembly opcode name (e.g. 'i32.add', 'br', 'call')
 * @returns {Array<Array<string>>|undefined} Tuple of [paramTypes, resultTypes] or undefined
 */
function getInstructionSignature(opcode) {
  return ast.signatures[opcode];
}

/**
 * Resolves argument parameter types for an opcode or object-scoped instruction.
 *
 * @param {string} object - Object prefix or empty string (e.g. 'i32', 'f64', '')
 * @param {string} name - Opcode base name (e.g. 'add', 'const', 'br')
 * @returns {Array<string>} Parameter types expected by opcode
 */
function getOpcodeParamTypes(object, name) {
  return ast.signatureForOpcode(object, name);
}

/**
 * Builds a WebAssembly instruction AST node.
 *
 * @param {string} id - Instruction mnemonic/opcode
 * @param {Array<object>} [args=[]] - Instruction argument AST nodes
 * @param {object} [namedArgs={}] - Named instruction arguments
 * @returns {object} Instr AST node
 */
function createInstruction(id, args = [], namedArgs = {}) {
  return ast.instruction(id, args, namedArgs);
}

/**
 * Builds an object-scoped WebAssembly instruction AST node.
 *
 * @param {string} id - Instruction name (e.g. 'add', 'sub')
 * @param {string} object - Type/object prefix (e.g. 'i32', 'i64')
 * @param {Array<object>} [args=[]] - Instruction argument AST nodes
 * @param {object} [namedArgs={}] - Named arguments
 * @returns {object} Instr AST node with object property
 */
function createObjectInstruction(id, object, args = [], namedArgs = {}) {
  return ast.objectInstruction(id, object, args, namedArgs);
}

/**
 * Attaches source position location information to an AST node.
 *
 * @param {object} node - AST node to decorate
 * @param {object} start - Start location { line: number, column: number }
 * @param {object} end - End location { line: number, column: number }
 * @returns {object} Decorated AST node with loc property
 */
function attachLocation(node, start, end) {
  return ast.withLoc(node, end, start);
}

module.exports = {
  ast,
  parseLiteral,
  getInstructionSignature,
  getOpcodeParamTypes,
  createInstruction,
  createObjectInstruction,
  attachLocation
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  ast,
  parseLiteral,
  getInstructionSignature,
  getOpcodeParamTypes,
  createInstruction,
  createObjectInstruction,
  attachLocation
} = require('../src/index.js');

async function testAll() {
  // 1. numberLiteralFromRaw parses integer and floating-point literals with type coercion and raw string preservation
  const i32Node = parseLiteral('1_000', 'i32');
  assert.equal(i32Node.type, 'NumberLiteral');
  assert.equal(i32Node.value, 1000);
  assert.equal(i32Node.raw, '1_000');

  const u32Node = parseLiteral('42', 'u32');
  assert.equal(u32Node.type, 'NumberLiteral');
  assert.equal(u32Node.value, 42);
  assert.equal(u32Node.raw, '42');

  const i64Node = parseLiteral('9007199254740993', 'i64');
  assert.equal(i64Node.type, 'LongNumberLiteral');
  assert.equal(typeof i64Node.value, 'object');
  assert.equal(i64Node.value.low, 1);
  assert.equal(i64Node.value.high, 2097152);
  assert.equal(i64Node.raw, '9007199254740993');

  const f32Nan = parseLiteral('nan', 'f32');
  assert.equal(f32Nan.type, 'FloatLiteral');
  assert.equal(f32Nan.nan, true);
  assert.equal(f32Nan.raw, 'nan');

  const f64Node = parseLiteral('3.14159', 'f64');
  assert.equal(f64Node.type, 'FloatLiteral');
  assert.equal(f64Node.value, 3.14159);
  assert.equal(f64Node.raw, '3.14159');

  // Direct export check
  const directNum = ast.numberLiteralFromRaw(100);
  assert.equal(directNum.type, 'NumberLiteral');
  assert.equal(directNum.value, 100);

  // 2. signatures provides instruction signatures mapping WebAssembly opcodes to parameter and result types
  assert.ok(typeof ast.signatures === 'object' && ast.signatures !== null);

  const addSig = getInstructionSignature('i32.add');
  assert.deepEqual(addSig, [['i32', 'i32'], ['i32']]);

  const brSig = getInstructionSignature('br');
  assert.deepEqual(brSig, [['u32'], []]);

  const dropSig = getInstructionSignature('drop');
  assert.deepEqual(dropSig, [[], []]);

  const loadSig = getInstructionSignature('i64.load8_s');
  assert.deepEqual(loadSig, [['u32', 'u32'], ['i64']]);

  const constSig = getInstructionSignature('f64.const');
  assert.deepEqual(constSig, [['f64'], ['f64']]);

  // 3. signatureForOpcode looks up parameter types for standard and object-prefixed WebAssembly opcodes
  const i32AddParams = getOpcodeParamTypes('i32', 'add');
  assert.deepEqual(i32AddParams, ['i32', 'i32']);

  const brParams = getOpcodeParamTypes('', 'br');
  assert.deepEqual(brParams, ['u32']);

  const directSig = ast.signatureForOpcode('f32', 'mul');
  assert.deepEqual(directSig, ['f32', 'f32']);

  // 4. instruction and objectInstruction build instruction AST nodes with arguments and locations
  const constArg = parseLiteral(42, 'i32');
  const constInstr = createInstruction('i32.const', [constArg]);
  assert.equal(constInstr.type, 'Instr');
  assert.equal(constInstr.id, 'i32.const');
  assert.equal(constInstr.args.length, 1);
  assert.equal(constInstr.args[0].value, 42);

  const objInstr = createObjectInstruction('add', 'i32');
  assert.equal(objInstr.type, 'Instr');
  assert.equal(objInstr.id, 'add');
  assert.equal(objInstr.object, 'i32');
  assert.deepEqual(objInstr.args, []);

  const directInstr = ast.instruction('nop');
  assert.equal(directInstr.type, 'Instr');
  assert.equal(directInstr.id, 'nop');

  // 5. withLoc attaches source location metadata to AST nodes
  const startLoc = { line: 1, column: 0 };
  const endLoc = { line: 1, column: 15 };
  const locatedInstr = attachLocation(constInstr, startLoc, endLoc);
  assert.equal(locatedInstr.loc.start.line, 1);
  assert.equal(locatedInstr.loc.start.column, 0);
  assert.equal(locatedInstr.loc.end.line, 1);
  assert.equal(locatedInstr.loc.end.column, 15);

  const ident = ast.identifier('my_var');
  const locatedIdent = ast.withLoc(ident, { line: 2, column: 10 }, { line: 2, column: 4 });
  assert.equal(locatedIdent.loc.start.line, 2);
  assert.equal(locatedIdent.loc.start.column, 4);
  assert.equal(locatedIdent.loc.end.line, 2,);
  assert.equal(locatedIdent.loc.end.column, 10);

  console.log('All 5 contract assertions PASSED successfully.');
}

testAll();