Project Title

Extend sub-command of WasmEdge CLI tool

Motivation

WasmEdge command line tool currently supports only the sub-command about run and compile the WASM files. As a WebAssembly runtime tool, it's welcome to have more functions about verifying the WASM files. In this mentorship, we will plan and implement the functionality of WasmEdge command line tool about parsing, validating, and instantiating WASM files, which developers can do with WasmEdge C API.

Expected Outcome

1. Extend the sub-commands for WasmEdge CLI tool to include parse, validate and instantiate commands.
2. Provide the test cases to verify the implementation.
3. Use WasmEdge C API to trigger the WasmEdge CLI tools for further test cases.

Details

This project extends the unified WasmEdge CLI by ensuring strict state isolation across pipeline phases. The implementation focuses on four core areas:

• Architecture & Routing: Register three new sub-commands (parse, validate, instantiate) in lib/driver/uniTool.cpp and route them to dedicated handler files (e.g., validateTool.cpp, parseTool.cpp).

• Stateful Option Parsing: Refactor include/driver/tool.h using a "Partial Registration" strategy. Flag scopes will be strictly isolated so each phase only accepts its required arguments (e.g., parse only accepts input files and WASM proposals, while instantiate safely adds host configs like --dir and --env).

• Pipeline Workflows:

  • wasmedge parse: Extract and print the module's AST sections (Type, Import, Function, Memory, Global, Export) to match the industry-standard wasm-objdump -x format.

Output format

Type[N]:
- type[index] (param_types) -> return_type
Import[N]:
- kind[index] sig=type_idx <- module.name
Function[N]:
- func[index] sig=type_idx <name>
Export[N]:
- kind[index] <name> -> "export_name"

• wasmedge validate: Generate the AST from the binary and pass it through the validation engine to strictly enforce WebAssembly specification compliance.

• wasmedge instantiate: Initialize the runtime with WASI host modules, perform the full loading/validation/instantiation pipeline, and exit successfully without executing code to confirm all import dependencies and links are satisfied.

• Integration Testing: Programmatically verify the new sub-commands via the public WasmEdge C API. Add comprehensive test coverage for scenarios including malformed binaries, validation logic failures, successful parsing, and instantiation linker errors.

Milestones

• Week 1: Option Struct Refactoring & Analysis

• Re-architect argument parsing in include/driver/tool.h to map existing flags strictly to the appropriate new sub-commands.

• Week 2: CLI Routing & Setup

• Modify lib/driver/uniTool.cpp to register the new parse, validate, and instantiate sub-commands and create their corresponding routing stubs.

• Week 3: Implement validate Command

• Build the pipeline to generate the AST and pass it through the validation engine to strictly enforce WebAssembly specification compliance, handling success and specific error outputs.

• Weeks 4-5: Implement parse Command

• Extract the module's AST sections (Type, Import, Function, Memory, Global, Export, Code, Custom) and implement full inspection output matching the industry-standard wasm-objdump -x format.

• Week 6: Implement instantiate Command & Mid-Term PR

• Initialize the runtime with WASI host modules, execute the loading and validation phases, and instantiate the module to confirm all import dependencies link correctly without actually executing the code.
• Deadline (April 7, 2026): Demonstrate PR progress containing the core implementations for parse, validate, and instantiate commands.

• Week 7: Mid-Term Evaluation

• Milestone (April 14, 2026): Successfully complete the Mid-term Evaluation.
• Transition into the testing phase for the newly implemented sub-commands.

• Weeks 8-9: Comprehensive Testing

• Programmatically verify all new sub-commands via the public WasmEdge C API.
• Implement tests for edge cases including compliant binaries, logic failures, corrupt inputs, missing arguments, and instantiation linker errors.

• Week 10: Code Polish & Testing Cleanup

• Address edge cases and bugs discovered during testing.
• Update description strings in uniTool.cpp to ensure wasmedge --help prints a clean, consistent summary matching existing commands.

• Week 11: Official Documentation

• Create comprehensive user guides (validate.md, parse.md etc) in https://github.com/WasmEdge/docs.
• Deadline (May 19, 2026): Ensure the final PR is fully polished and ready for merging.

• Week 12: Review Cycle, Final PR, & Final Evaluation

• Address maintainer feedback, finalize code style fixes, and complete documentation.
• Milestone (May 26, 2026): Complete the Final Evaluation and submit the final LFX mentorship report detailing the architectural changes.

Appendix

Original Issue: #4513