wasm_map_lookup

A CLI tool for looking up AssemblyScript source positions from WebAssembly binary offsets using AssemblyScript source maps.

Features

• Multiple Offset Support: Query multiple WebAssembly offsets in a single run
• Flexible Input Format: Accepts offsets in both decimal and hexadecimal (0x) notation
• Fallback Reporting: Provides closest source locations when exact matches aren't found

Building

All done by cargo:

cargo build --release

Usage

Basic Command Line Interface

wasm-map-lookup <MAP_FILE> <OFFSET>...

Arguments

• <MAP_FILE>: Path to the .wasm.map JSON file generated by AssemblyScript compiler
• <OFFSET>...: One or more WebAssembly offsets to lookup (decimal or 0x hex format)

Examples

1. Single offset lookup:

   wasm-map-lookup program.wasm.map 12345

2. Multiple offsets:

   wasm-map-lookup program.wasm.map 12345 0x3040 67890

3. Hexadecimal offsets:

   wasm-map-lookup program.wasm.map 0x1234 0x5678 0xABCD

4. Mixed decimal and hex:

   wasm-map-lookup program.wasm.map 4660 0x1234 12345

Output Format

The tool provides detailed mapping information for each queried offset:

Query offset: 0x3040(12336), Best match offset: 0x3030(12320)
Source: src/main.ts:42:15

For runtime-generated code without direct source mapping:

Query offset: 0x5000(20480), Best match offset: 0x4ff8(20472)
Segment: (internal / runtime generated)
Closest TS source before this: src/memory.ts:128:8

Source Map Structure

AssemblyScript source maps contain:

{
  "version": 3,
  "sources": ["src/main.ts", "src/utils.ts"],
  "names": ["calculate", "process"],
  "mappings": "AAAA,SAAS,KAAK,CAAC,CAAC"
}

AssemblyScript Integration

To use this tool effectively with AssemblyScript projects:

1. Enable Source Maps: Compile with source map generation enabled

   asc program.ts --sourceMap

2. Generate WASM Map: This creates program.wasm and program.wasm.map files

3. Capture Offsets: Obtain WebAssembly offsets from:

   • Stack traces
   • Profiling data
   • Memory dumps
   • Debug information

4. Lookup Sources: Use this tool to map offsets back to source locations

Dependencies

• serde: JSON serialization/deserialization for source map parsing
• serde_json: JSON parsing functionality
• clap: Command line argument parsing
• anyhow: Error handling and context management