WebAssembly Modules skill for Claude Code

#!/usr/bin/env python3
"""Report what is inside a .wasm core module: section sizes, imports, exports,
custom sections, gzip size, and the largest functions (when a name section exists).

Usage:
    python3 wasm_sections.py <module.wasm> [--top N] [--max-kb KB]

--top N     number of largest functions to list (default 15)
--max-kb KB exit 1 if the gzip-compressed size exceeds KB kilobytes (size budget gate)

Exit codes: 0 ok, 1 budget exceeded, 2 unreadable or invalid file.
Standard library only.
"""
from __future__ import annotations

import gzip
import sys
from collections import Counter
from pathlib import Path

SECTION_NAMES = {
    0: "custom", 1: "type", 2: "import", 3: "function", 4: "table", 5: "memory",
    6: "global", 7: "export", 8: "start", 9: "element", 10: "code", 11: "data",
    12: "datacount", 13: "tag",
}
KINDS = {0: "func", 1: "table", 2: "memory", 3: "global", 4: "tag"}


class Reader:
    def __init__(self, data: bytes, pos: int = 0, end: int | None = None):
        self.d, self.p = data, pos
        self.end = len(data) if end is None else end

    def byte(self) -> int:
        if self.p >= self.end:
            raise ValueError("unexpected end of data")
        b = self.d[self.p]
        self.p += 1
        return b

    def u32(self) -> int:
        result = shift = 0
        while True:
            b = self.byte()
            result |= (b & 0x7F) << shift
            if not b & 0x80:
                return result
            shift += 7
            if shift > 63:
                raise ValueError("LEB128 too long")

    def s33(self) -> int:
        result = shift = 0
        while True:
            b = self.byte()
            result |= (b & 0x7F) << shift
            shift += 7
            if not b & 0x80:
                if b & 0x40:
                    result -= 1 << shift
                return result

    def name(self) -> str:
        n = self.u32()
        s = self.d[self.p:self.p + n]
        self.p += n
        return s.decode("utf-8", errors="replace")

    def limits(self) -> None:
        flags = self.byte()
        self.u32()
        if flags & 0x01:
            self.u32()

    def reftype(self) -> None:
        b = self.byte()
        if b in (0x63, 0x64):  # (ref null ht) / (ref ht) from the GC proposal
            self.s33()

    valtype = reftype  # numeric types are single bytes; ref types handled above


def human(n: int) -> str:
    return f"{n / 1024:.1f} KiB" if n >= 1024 else f"{n} B"


def analyze(path: Path, top: int) -> tuple[int, int]:
    data = path.read_bytes()
    if len(data) < 8 or data[:4] != b"\x00asm":
        raise ValueError("not a WebAssembly binary (missing \\0asm magic)")
    version = data[4:8]
    total = len(data)
    gz = len(gzip.compress(data, compresslevel=9))
    print(f"{path}: {human(total)} raw, {human(gz)} gzip -9")
    if version != b"\x01\x00\x00\x00":
        print(f"Header version {version.hex()} is not a core module (likely a component). "
              "Inspect components with `wasm-tools component wit` or `wasm-tools print`.")
        return total, gz

    r = Reader(data, 8)
    sizes: Counter[str] = Counter()
    customs: list[tuple[str, int]] = []
    imports: list[tuple[str, str, str]] = []
    exports: list[tuple[str, str]] = []
    imported_funcs = 0
    body_sizes: list[int] = []
    func_names: dict[int, str] = {}

    while r.p < len(data):
        sid = r.byte()
        size = r.u32()
        start, end = r.p, r.p + size
        label = SECTION_NAMES.get(sid, f"unknown({sid})")
        sub = Reader(data, start, end)
        if sid == 0:
            cname = sub.name()
            customs.append((cname, size))
            label = f"custom:{cname}"
            if cname == "name":
                try:
                    while sub.p < end:
                        sub_id = sub.byte()
                        sub_size = sub.u32()
                        sub_end = sub.p + sub_size
                        if sub_id == 1:
                            for _ in range(sub.u32()):
                                idx = sub.u32()
                                func_names[idx] = sub.name()
                        sub.p = sub_end
                except ValueError:
                    pass  # malformed name section: sizes are still valid
        elif sid == 2:
            for _ in range(sub.u32()):
                mod, field, kind = sub.name(), sub.name(), sub.byte()
                imports.append((mod, field, KINDS.get(kind, str(kind))))
                if kind == 0:
                    sub.u32(); imported_funcs += 1
                elif kind == 1:
                    sub.reftype(); sub.limits()
                elif kind == 2:
                    sub.limits()
                elif kind == 3:
                    sub.valtype(); sub.byte()
                elif kind == 4:
                    sub.byte(); sub.u32()
        elif sid == 7:
            for _ in range(sub.u32()):
                ename, kind = sub.name(), sub.byte()
                sub.u32()
                exports.append((ename, KINDS.get(kind, str(kind))))
        elif sid == 10:
            for _ in range(sub.u32()):
                bsize = sub.u32()
                body_sizes.append(bsize)
                sub.p += bsize
        sizes[label] += size
        r.p = end

    print("\nSections (largest first):")
    for label, size in sizes.most_common():
        print(f"  {label:<28} {human(size):>12}  {100 * size / total:5.1f}%")

    debug = [(n, s) for n, s in customs if n.startswith(".debug") or n in ("sourceMappingURL", "external_debug_info")]
    if debug:
        dsize = sum(s for _, s in debug)
        print(f"\nDebug info: {human(dsize)} in {len(debug)} section(s). Strip for release "
              "(wasm-opt --strip-debug, wasm-tools strip, or build profile settings).")
    if "name" in dict(customs):
        print("Name section present: useful for profiling, strippable for release (wasm-opt --strip-debug removes it).")

    by_module = Counter(m for m, _, _ in imports)
    print(f"\nImports: {len(imports)} ({imported_funcs} functions)")
    for mod, count in by_module.most_common():
        print(f"  {mod:<40} {count}")
    hints = []
    if any(m.startswith("wasi_snapshot_preview1") for m in by_module):
        hints.append("WASI preview 1 module (wasip1): runs on wasmtime/wasmer/Node WASI, not directly in browsers")
    if any(m.startswith("wasi:") for m in by_module):
        hints.append("imports WASI 0.2+ interfaces: should be a component, not a core module")
    if any("wbindgen" in m or "wbg" == m for m in by_module):
        hints.append("wasm-bindgen glue module: load through the generated JS, not raw WebAssembly.instantiate")
    if any(m == "go" or m == "gojs" for m in by_module):
        hints.append("Go js/wasm module: needs wasm_exec.js from the same Go version")
    if "env" in by_module:
        hints.append("imports from 'env': host must supply these (Emscripten/C toolchains)")
    for h in hints:
        print(f"  note: {h}")

    print(f"\nExports: {len(exports)}")
    for ename, kind in exports[:40]:
        print(f"  {kind:<7} {ename}")
    if len(exports) > 40:
        print(f"  ... {len(exports) - 40} more")

    if body_sizes:
        ranked = sorted(enumerate(body_sizes), key=lambda t: t[1], reverse=True)[:top]
        code_total = sum(body_sizes)
        print(f"\nLargest functions ({len(body_sizes)} defined, code total {human(code_total)}):")
        for local_idx, bsize in ranked:
            fidx = imported_funcs + local_idx
            name = func_names.get(fidx, f"func[{fidx}]")
            if len(name) > 90:
                name = name[:87] + "..."
            print(f"  {human(bsize):>10}  {100 * bsize / code_total:5.1f}%  {name}")
        if not func_names:
            print("  (no name section: build with debug names or use twiggy/wasm-tools for attribution)")
    return total, gz


def main() -> int:
    args = sys.argv[1:]
    if not args or args[0] in ("-h", "--help"):
        print(__doc__.strip())
        return 2
    top, max_kb, path = 15, None, None
    i = 0
    while i < len(args):
        if args[i] == "--top":
            top = int(args[i + 1]); i += 2
        elif args[i] == "--max-kb":
            max_kb = float(args[i + 1]); i += 2
        else:
            path = Path(args[i]); i += 1
    if path is None or not path.is_file():
        print(f"wasm_sections: file not found: {path}", file=sys.stderr)
        return 2
    try:
        _, gz = analyze(path, top)
    except (ValueError, IndexError) as exc:
        print(f"wasm_sections: invalid module: {exc}", file=sys.stderr)
        return 2
    if max_kb is not None:
        limit = max_kb * 1024
        status = "OK" if gz <= limit else "OVER BUDGET"
        print(f"\nBudget: gzip {human(gz)} vs limit {max_kb:g} KiB -> {status}")
        if gz > limit:
            return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())