#wasm-tools

#安装与运行

# 无需安装，直接运行
moonx Nanaloveyuki/wasm-tools contract snapshot app.wasm -o app.abi.json
moonx Nanaloveyuki/wasm-tools contract check --baseline app.abi.json app-next.wasm --direction both

# 想要短命令，可以自己包一层
alias wsm='moonx Nanaloveyuki/wasm-tools'
wsm contract snapshot app.wasm -o app.abi.json
wsm contract check --baseline app.abi.json app-next.wasm --direction both

#快速体验：检查 MoonBit 发布产物

./tests/contract-demo.sh

provided: compatible
required: compatible
provided: breaking
  breaking  export add (function): export type changed

#契约命令

wsm contract snapshot app.wasm -o app.abi.json
wsm contract check --baseline app.abi.json app-next.wasm --direction both
wsm contract wit snapshot --world cli app.wit -o app.wit.json
wsm contract wit check --world cli --baseline app.wit.json app-next.wit

#辅助 WASM 命令

• 输入缺省为 stdin，- 也表示 stdin；-o FILE 指定输出文件。
• 二进制输出默认写 stdout，重定向由调用方负责（当前没有可移植的 isatty）。
• 退出码：0 兼容/成功，1 内容非法、breaking 或 unknown，2 用法、IO 或快照 schema 错误。

wsm parse app.wat -o app.wasm
wsm validate app.wasm
wsm print app.wasm -o app.wat
wsm dump --instructions app.wasm | head
wsm strip app.wasm --keep producers -o app.stripped.wasm
wsm metadata --json app.wasm
wsm size app.wasm --top 20
wsm size app.wasm --diff old.wasm
wsm size app.wasm --budget 200KB
wsm opt app.wasm -Oz -o app.opt.wasm
wsm symbolize app.wasm 'wasm-function[34]:0xd8d'
wsm symbolize --json app.wasm 0xd8d
cat app.wasm | wsm validate -

#范围

• contract snapshot FILE 输出带 format_version 的稳定 JSON；接口按名称、种类及结构化类型表示，不用 WASM 类型索引作为身份。
• contract check --baseline BASELINE FILE 输出逐项变化。provided 检查候选产物能否继续满足旧调用方；required 检查旧宿主能否满足候选产物的新导入需求；默认 both 分开报告两个方向。
• breaking 与 unknown 均默认返回退出码 1。带类型化引用等当前无法安全比较的接口会报告 unknown，不会静默判兼容。
• Core ABI MVP 支持 wasm 与 wasm-gc 产物。WIT MVP 直接处理 WIT 源文件并要求显式选择 world；它不从任意 Component 二进制推断 package/world，也不覆盖 Component 二进制中的 WIT 抽取。未能安全规范化的 WIT 结构返回 unknown。
• WIT world 比较忽略 package 版本与源码声明顺序；候选 world 增加 imports、移除 exports 可兼容，移除 imports、增加 exports 或改变同名项类型为 breaking。首版不推导同名项内部的方差子类型；未能规范化或受 @unstable gate 影响的 item 返回 unknown，带 gate 的 world 无法快照。
• contract 包提供与 CLI/解析器类型无关的快照和比较 API；wasm 包负责把二进制解析结果规范化为该模型。

let old_snapshot = @contract.parse_snapshot(baseline_json)
let new_snapshot = @wasm.contract_snapshot(candidate_bytes)
let report = @contract.compare_snapshots(
  old_snapshot,
  new_snapshot,
  @contract.Both,
)

#实现边界与独立贡献

• contract 包定义独立于 CLI 和上游 AST 的契约模型、版本化快照、稳定身份与兼容报告。
• wasm 适配层把解析出的外部类型规范化为项目模型；类型段索引和无关 section 顺序不作为 ABI 身份。
• 本项目实现 provided / required 方向规则、变化分类和 breaking / unknown 判定。未 建模的结构明确报告 unknown，不会因解析成功就默认兼容。
• Core WASM 的真实 wasm / wasm-gc 产物以及 WIT 源文件均有快照和兼容检查路径；演示脚本 与单元测试覆盖这些结果。

• core module 走 Milky2018/wasm_core（解析、验证、WAT 双向、编码）
• component 走 Milky2018/wasm_component（解析、验证、WIT）
• component → WAT 走 moonrockz/wit/decompiler
• WIT/WAC 通用 parse/format/verify 交给 moonx moonrockz/wasm-devkit；WIT 契约命令复用 moonrockz/wit parser/verifier API 并使用项目自有的快照与比较模型
• 优化交给工具链自带的 moon-wasm-opt；opt 只做参数映射与产物校验，不实现 pass

#状态

#路线

#开发

moon build --target wasm       # 生成 _build/wasm/debug/build/wasm-tools.wasm
moon check --target all        # 检查所有支持的编译后端
moon test                      # 单元测试
./tests/contract-demo.sh       # 真实 wasm / wasm-gc 契约兼容演示
./tests/smoke.sh               # CLI 行为检查（Linux）
tests/win-smoke.sh             # Windows 侧检查（WSL interop，需 WIN_MOONRUN/WIN_WASM_OPT）

#结构

main.mbt          argv 转发与退出码
cli/              参数、IO、帮助、错误（不依赖 wasm 包）
cmd/              每个子命令一个文件
contract/         契约领域模型、稳定快照、方向性比较器
wasm/             raw 扫描与上游解析器适配，包括契约提取
tests/            fixtures、cli.md 场景、smoke.sh
examples/         导出 add ABI 的 MoonBit foreign library 样例与 breaking 变体
docs/adr/         范围、依赖与发布决策