waq 0.1.0

Add your description here

QBEWA - WebAssembly to QBE Compiler

QBEWA is an ahead-of-time (AOT) compiler that translates WebAssembly binary modules into native machine code using QBE as the backend.

Features

• WASM Binary Parsing: Parse WebAssembly binary modules
• Stack-to-SSA Translation: Convert WebAssembly's stack-based model to QBE's SSA form
• Control Flow Conversion: Transform structured control flow (blocks, loops, ifs) to basic blocks and jumps
• Type Mapping: Map WASM types (i32, i64, f32, f64) to QBE types (w, l, s, d)
• QBE Backend: Generate QBE intermediate language code

Installation

# Clone the repository
git clone https://github.com/yourusername/qbewa.git
cd qbewa

# Install dependencies using uv
uv sync

Usage

Basic Compilation

# Compile a WASM file to QBE IL
qbewa input.wasm -o output.qbe

# Run tests
make test

# Run specific test types
uv run pytest -m unit              # Unit tests only
uv run pytest -m integration       # Integration tests only
uv run pytest -m e2e               # End-to-end tests only

Development Commands

# Format code
make format

# Lint and type check
make lint

# Run with coverage
make test-cov

# Multi-version testing via nox
nox -s tests              # Run tests on all Python versions
nox -s check              # Run linting/type checking

Project Structure

qbewa/
├── src/
│   └── waq/              # Main source code
│       ├── compiler/     # Compilation logic
│       ├── parser/       # WASM binary parsing
│       ├── runtime/      # Runtime support
│       └── cli.py        # Command-line interface
├── tests/                # Test suite
│   ├── a_unit/           # Unit tests
│   ├── b_integration/    # Integration tests
│   └── c_e2e/            # End-to-end tests
├── local-notes/          # Project documentation
└── runtime/              # Runtime components

Documentation

Comprehensive documentation is available in the local-notes/ directory:

• Project Documentation: Vision, specifications, design decisions
• Python Development Guidelines: Coding standards, testing strategies, design patterns
• WASM-to-QBE Transformation: Detailed compiler specifications

Testing

The project follows a pyramid testing structure:

• Unit Tests: Fast, isolated tests in tests/a_unit/
• Integration Tests: Component interaction tests in tests/b_integration/
• End-to-end Tests: Full workflow tests in tests/c_e2e/

Code Style

• Targets Python 3.12+
• Uses Ruff with ALL rules enabled
• Multiple type checkers: ty, pyrefly, mypy
• All files must have from __future__ import annotations

License

[Specify your license here - e.g., MIT, Apache 2.0, etc.]

Contributing

See CONTRIBUTING.md for contribution guidelines.