@gasm-compiler/core 0.1.0

package/README.md

@@ -0,0 +1,720 @@
+# Gasm Compiler Core Compiler
+
+**Compile WebAssembly to WGSL for GPU Execution**
+
+This package implements the core compiler that transforms WebAssembly binaries into WGSL (WebGPU Shading Language) code for execution on GPUs. It implements the [Gasm v0.1 specification](../../spec/gasm-v0.1.md), a GPU-executable subset of WebAssembly.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Compilation Pipeline](#compilation-pipeline)
+- [IR Types](#ir-types)
+- [Instruction Mapping](#instruction-mapping)
+- [Gasm Conformance](#gasm-conformance)
+- [Usage](#usage)
+- [Testing](#testing)
+- [API Reference](#api-reference)
+
+---
+
+## Overview
+
+**Gasm Compiler Core** is a TypeScript/Deno compiler that:
+
+1. **Parses** WebAssembly binaries (Wasm Core 1.0)
+2. **Validates** GPU execution constraints (Gasm spec)
+3. **Transforms** stack-based Wasm to structured WGSL
+4. **Generates** WGSL compute shaders ready for WebGPU
+
+### Key Features
+
+- ✅ Full L0 conformance (scalar operations)
+- ✅ 120+ WebAssembly instructions supported
+- ✅ Control flow restructuring (Relooper algorithm)
+- ✅ Memory operation lowering (sub-word access)
+- ✅ Global imports and Gasm built-ins
+- ✅ Type-safe SSA intermediate representation
+- 🚧 L1/L2 conformance (SIMD, atomics) — planned
+
+---
+
+## Architecture
+
+The compiler uses a **5-phase pipeline** to transform WebAssembly into WGSL:
+
+```
+┌─────────────┐
+│  Wasm Binary │  Input: .wasm file (Uint8Array)
+└──────┬──────┘
+       │
+       v
+┌─────────────┐
+│  Phase 1:   │  Parse & Validate
+│  Parser     │  • Binary format parsing
+│             │  • Gasm restriction validation (Section 10)
+└──────┬──────┘  • Output: WasmModule (stack-based IR)
+       │
+       v
+┌─────────────┐
+│  Phase 2:   │  Stack → SSA Conversion
+│  SSA IR     │  • Convert stack operations to SSA form
+│             │  • Type inference for locals
+└──────┬──────┘  • Output: SSAModule (SSA IR)
+       │
+       v
+┌─────────────┐
+│  Phase 3:   │  Control Flow Restructuring
+│  Relooper   │  • Transform unstructured jumps (br, br_if, br_table)
+│             │  • Generate structured blocks/loops
+└──────┬──────┘  • Output: StructuredModule
+       │
+       v
+┌─────────────┐
+│  Phase 4:   │  Memory Lowering
+│  MemLower   │  • Lower i8/i16 loads/stores to i32 word access
+│             │  • Generate bit-masking and shifting
+└──────┬──────┘  • Output: StructuredModule (memory-lowered)
+       │
+       v
+┌─────────────┐
+│  Phase 5:   │  WGSL Code Generation
+│  Codegen    │  • Emit WGSL functions, variables, structs
+│             │  • Map Wasm instructions to WGSL expressions
+└──────┬──────┘  • Output: WGSL string
+       │
+       v
+┌─────────────┐
+│  WGSL Code  │  Output: Valid WebGPU shader
+└─────────────┘
+```
+
+---
+
+## Compilation Pipeline
+
+### Phase 1: Parse & Validate
+
+**File:** `src/parser.ts`  
+**Input:** WebAssembly binary (`Uint8Array`)  
+**Output:** `WasmModule` (stack-based IR)
+
+**Responsibilities:**
+- Parse Wasm binary format (magic, version, sections)
+- Extract types, imports, functions, tables, memories, globals, exports, code
+- Validate Gasm restrictions:
+  - Max 1 memory (no multi-memory)
+  - Max 1 table (no multi-table)
+  - No imports except globals (built-ins)
+  - Memory must be exported as `"memory"`
+- Decode instruction bytecode to IR
+
+**Key Functions:**
+```typescript
+export function parseWasm(binary: Uint8Array): WasmModule
+```
+
+**Error Handling:**
+Throws `CompileError` with descriptive message for invalid binaries or Gasm violations.
+
+---
+
+### Phase 2: Stack → SSA Conversion
+
+**File:** `src/phases.ts` → `phaseStackToSSA()`  
+**Input:** `WasmModule`  
+**Output:** `SSAModule`
+
+**Responsibilities:**
+- Convert stack-based operations to Static Single Assignment (SSA) form
+- Infer types for local variables (from usage patterns)
+- Preserve global definitions and imports
+- Generate unique SSA variable names (`%0`, `%1`, `%2`, ...)
+
+**Example:**
+```wasm
+;; WebAssembly (stack-based)
+local.get 0
+i32.const 1
+i32.add
+local.set 0
+```
+
+↓
+
+```
+// SSA IR
+%0 = local.get 0: i32
+%1 = i32.const 1
+%2 = i32.add %0, %1
+local.set 0, %2
+```
+
+**Key Functions:**
+```typescript
+export function phaseStackToSSA(module: WasmModule): SSAModule
+```
+
+---
+
+### Phase 3: Control Flow Restructuring
+
+**File:** `src/relooper.ts`  
+**Input:** `SSAModule`  
+**Output:** `StructuredModule`
+
+**Responsibilities:**
+- Apply the **Relooper algorithm** to restructure control flow
+- Transform unstructured jumps (`br`, `br_if`, `br_table`) into structured loops/blocks
+- Generate WGSL-compatible control structures (`if`, `loop`, `break`, `continue`)
+
+**Example:**
+```wasm
+;; WebAssembly (unstructured)
+block $exit
+  loop $loop
+    local.get 0
+    i32.const 10
+    i32.lt_s
+    br_if $exit
+    ;; loop body
+    br $loop
+  end
+end
+```
+
+↓
+
+```wgsl
+// WGSL (structured)
+loop {
+  if (var_0 < 10i) { break; }
+  // loop body
+}
+```
+
+**Key Functions:**
+```typescript
+export function reloop(module: SSAModule): StructuredModule
+```
+
+---
+
+### Phase 4: Memory Lowering
+
+**File:** `src/phases.ts` → `phaseMemoryLowering()`  
+**Input:** `StructuredModule`  
+**Output:** `StructuredModule` (memory-lowered)
+
+**Responsibilities:**
+- Lower sub-word memory operations (i8/i16) to word-aligned access (i32)
+- Generate bit-masking and shifting for unaligned access
+- Preserve i32/i64/f32/f64 memory operations
+
+**Example:**
+```wasm
+;; i32.load8_u offset=0 align=1
+i32.load8_u offset=0 align=1
+```
+
+↓
+
+```wgsl
+// WGSL (lowered to word access)
+let word_addr = offset / 4u;
+let byte_offset = offset % 4u;
+let word = memory[word_addr];
+let byte = (word >> (byte_offset * 8u)) & 0xFFu;
+```
+
+**Key Functions:**
+```typescript
+export function phaseMemoryLowering(module: StructuredModule): StructuredModule
+```
+
+---
+
+### Phase 5: WGSL Code Generation
+
+**File:** `src/phases.ts` → `phaseWgslCodegen()`  
+**Input:** `StructuredModule`  
+**Output:** WGSL string
+
+**Responsibilities:**
+- Emit WGSL variable declarations (globals, locals)
+- Emit function definitions with signatures
+- Emit main entry point with Gasm built-in parameters:
+  - `@builtin(global_invocation_id)` → `global_invocation_id_{x,y,z}`
+  - `@builtin(local_invocation_id)` → `local_invocation_id_{x,y,z}`
+  - `@builtin(workgroup_id)` → `workgroup_id_{x,y,z}`
+  - `@builtin(num_workgroups)` → `num_workgroups_{x,y,z}`
+- Map Wasm instructions to WGSL expressions
+- Generate structured control flow (blocks, loops, conditionals)
+
+**Example:**
+```wasm
+(func $add (param i32 i32) (result i32)
+  local.get 0
+  local.get 1
+  i32.add)
+```
+
+↓
+
+```wgsl
+fn func_0(param_0: i32, param_1: i32) -> i32 {
+  return param_0 + param_1;
+}
+```
+
+**Key Functions:**
+```typescript
+export function phaseWgslCodegen(
+  module: StructuredModule,
+  options?: CompileOptions
+): string
+```
+
+---
+
+## IR Types
+
+The compiler uses three IR representations:
+
+### 1. WasmModule (Stack-Based IR)
+
+**File:** `src/types.ts`  
+**Purpose:** Direct representation of WebAssembly binary
+
+```typescript
+export interface WasmModule {
+  types: WasmType[];
+  imports: Import[];
+  functions: WasmFunction[];
+  tables: Table[];
+  memories: Memory[];
+  globals: Global[];  // ImportedGlobal | DefinedGlobal
+  exports: Export[];
+  start?: number;
+  elements: Element[];
+  dataSegments: DataSegment[];
+  customSections: CustomSection[];
+}
+```
+
+**Key Properties:**
+- `types`: Function signatures (param/result types)
+- `functions`: Function bodies with stack-based instructions
+- `globals`: Global variables (imported built-ins or definitions)
+- `memories`: Linear memory configuration (initial/max pages)
+- `exports`: Exported functions and memory
+
+---
+
+### 2. SSAModule (SSA IR)
+
+**File:** `src/types.ts`  
+**Purpose:** Static Single Assignment form for analysis
+
+```typescript
+export interface SSAModule {
+  types: WasmType[];
+  imports: Import[];
+  functions: SSAFunction[];
+  tables: Table[];
+  memories: Memory[];
+  globals: Global[];
+  exports: Export[];
+  start?: number;
+  elements: Element[];
+  dataSegments: DataSegment[];
+  customSections: CustomSection[];
+}
+
+export interface SSAFunction {
+  typeIndex: number;
+  locals: Local[];
+  body: SSAInstruction[];
+}
+
+export interface SSAInstruction {
+  opcode: number;
+  name: string;
+  type?: string;
+  operands?: string[];
+  result?: string;
+  immediates?: unknown[];
+}
+```
+
+**Key Properties:**
+- `SSAFunction.body`: Instructions with explicit SSA operands/results
+- `SSAInstruction.result`: SSA variable name (e.g., `%0`, `%1`)
+- `SSAInstruction.operands`: SSA variable dependencies (e.g., `["%0", "%1"]`)
+
+---
+
+### 3. StructuredModule (Structured IR)
+
+**File:** `src/types.ts`  
+**Purpose:** Structured control flow for WGSL generation
+
+```typescript
+export interface StructuredModule {
+  types: WasmType[];
+  imports: Import[];
+  functions: StructuredFunction[];
+  tables: Table[];
+  memories: Memory[];
+  globals: Global[];
+  exports: Export[];
+  start?: number;
+  elements: Element[];
+  dataSegments: DataSegment[];
+  customSections: CustomSection[];
+}
+
+export interface StructuredFunction {
+  typeIndex: number;
+  locals: Local[];
+  body: StructuredInstruction[];
+}
+
+export interface StructuredInstruction {
+  opcode: number;
+  name: string;
+  type?: string;
+  operands?: string[];
+  result?: string;
+  immediates?: unknown[];
+}
+```
+
+**Key Properties:**
+- Control flow is fully structured (no `br`, `br_if`, `br_table`)
+- Instructions use WGSL-compatible constructs (`if`, `loop`, `break`)
+- Memory operations are word-aligned (i32/i64/f32/f64 only)
+
+---
+
+## Instruction Mapping
+
+The compiler maps 120+ WebAssembly instructions to WGSL equivalents. See the full table in the [Instruction Set Reference](../../docs/instruction-set.md).
+
+### Quick Reference
+
+| Category | Example Instructions | WGSL Equivalent |
+|----------|---------------------|-----------------|
+| **Arithmetic** | `i32.add`, `f32.mul` | `a + b`, `a * b` |
+| **Bitwise** | `i32.and`, `i32.shl` | `a & b`, `a << (b & 31u)` |
+| **Comparisons** | `i32.lt_s`, `f32.eq` | `a < b`, `a == b` |
+| **Memory** | `i32.load`, `i32.store8` | `memory[addr/4u]`, bit-masking |
+| **Conversions** | `i32.trunc_f32_s`, `f32.convert_i32_u` | `i32(trunc(a))`, `f32(u32(a))` |
+| **Control Flow** | `block`, `loop`, `br_if` | `{ ... }`, `loop { ... }`, `if (c) { break; }` |
+| **Variables** | `local.get`, `global.set` | `var_N`, `global_N = val` |
+| **Special** | `select`, `memory.size` | `select(a, b, c)`, `arrayLength(&memory)` |
+
+---
+
+## Gasm Conformance
+
+The compiler implements **Gasm v0.1 L0 (Core)** conformance:
+
+### Conformance Levels
+
+| Level | Features | Status |
+|-------|----------|--------|
+| **L0 (Core)** | Scalar operations (i32, i64, f32, f64) | ✅ Implemented |
+| **L1 (SIMD)** | 128-bit SIMD operations (v128) | 🚧 Planned |
+| **L2 (Extended)** | Atomics + Relaxed SIMD | 🚧 Planned |
+
+### Gasm Restrictions (Section 10)
+
+The compiler enforces these restrictions during Phase 1 validation:
+
+1. **Single Memory**: Max 1 memory, must be exported as `"memory"`
+2. **Single Table**: Max 1 table (for indirect calls)
+3. **No Imports** (except globals): Only global imports allowed (Gasm built-ins)
+4. **Deterministic Execution**: No `unreachable` or trapping operations in production code
+5. **Structured Control Flow**: All `br`, `br_if`, `br_table` must be restructurable (Phase 3)
+
+### Gasm Built-in Globals
+
+The compiler automatically maps WGSL built-ins to global imports:
+
+| Global Name | WGSL Built-in | Type |
+|-------------|---------------|------|
+| `global_invocation_id_x` | `@builtin(global_invocation_id).x` | `u32` |
+| `global_invocation_id_y` | `@builtin(global_invocation_id).y` | `u32` |
+| `global_invocation_id_z` | `@builtin(global_invocation_id).z` | `u32` |
+| `local_invocation_id_x` | `@builtin(local_invocation_id).x` | `u32` |
+| `local_invocation_id_y` | `@builtin(local_invocation_id).y` | `u32` |
+| `local_invocation_id_z` | `@builtin(local_invocation_id).z` | `u32` |
+| `workgroup_id_x` | `@builtin(workgroup_id).x` | `u32` |
+| `workgroup_id_y` | `@builtin(workgroup_id).y` | `u32` |
+| `workgroup_id_z` | `@builtin(workgroup_id).z` | `u32` |
+| `num_workgroups_x` | `@builtin(num_workgroups).x` | `u32` |
+| `num_workgroups_y` | `@builtin(num_workgroups).y` | `u32` |
+| `num_workgroups_z` | `@builtin(num_workgroups).z` | `u32` |
+
+**Example:**
+```wasm
+(import "gasm" "global_invocation_id_x" (global $gid_x i32))
+```
+
+↓
+
+```wgsl
+@compute @workgroup_size(64)
+fn main(
+  @builtin(global_invocation_id) global_invocation_id: vec3<u32>,
+  // ... other built-ins
+) {
+  var global_invocation_id_x: u32 = global_invocation_id.x;
+  // ... use in function body
+}
+```
+
+---
+
+## Usage
+
+### Basic Compilation
+
+```typescript
+import { compile } from "@gasm-compiler/core";
+
+// Load WebAssembly binary
+const wasmBytes = await Deno.readFile("shader.wasm");
+
+// Compile to WGSL
+const wgslCode = compile(wasmBytes);
+
+// Use with WebGPU
+const shaderModule = device.createShaderModule({ code: wgslCode });
+```
+
+### With Options
+
+```typescript
+import { compile, CompileOptions } from "@gasm-compiler/core";
+
+const options: CompileOptions = {
+  workgroupSize: [128, 1, 1],  // Default: [64, 1, 1]
+  debug: true,                  // Emit debug comments
+  mathExtension: true,          // Enable gasm:math built-ins
+};
+
+const wgslCode = compile(wasmBytes, options);
+```
+
+### Math Extension (gasm:math)
+
+The `mathExtension` option enables WGSL built-in math functions to be called directly from WebAssembly via imports from the `"gasm"` module:
+
+```typescript
+import { compile } from "@gasm-compiler/core";
+
+const wgslCode = compile(wasmBytes, {
+  mathExtension: true,   // Enable all levels (M0, M1, M2)
+  // or: mathExtension: "M0"  // Core scalar functions only
+  // or: mathExtension: "M1"  // Core + vector functions
+  // or: mathExtension: "M2"  // All functions
+});
+```
+
+When enabled, imports like `(import "gasm" "sin" (func ...))` are compiled to direct WGSL built-in calls like `sin(...)` instead of function calls.
+
+**Math Levels:**
+- **M0 (Core)**: Scalar functions (sin, cos, sqrt, abs, min, max, clamp, etc.)
+- **M1 (Vector)**: Geometric functions (length, dot, cross, normalize, reflect, etc.)
+- **M2 (Advanced)**: modf, frexp, ldexp, degrees, radians, bit manipulation
+
+### Error Handling
+
+```typescript
+import { compile, isCompileError } from "@gasm-compiler/core";
+
+try {
+  const wgslCode = compile(wasmBytes);
+  console.log("Compilation successful!");
+} catch (error) {
+  if (isCompileError(error)) {
+    console.error("Compile Error:", error.message);
+    if (error.location) {
+      console.error(`  at line ${error.location.line}, column ${error.location.column}`);
+    }
+  } else {
+    throw error;  // Unexpected error
+  }
+}
+```
+
+---
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test:core
+
+# Or directly with Deno
+cd packages/core
+deno test --allow-all
+
+# Run specific test file
+deno test tests/compiler_test.ts --allow-all
+```
+
+### Test Organization
+
+Tests are organized by phase:
+
+```
+packages/core/tests/
+├── compiler_test.ts      # Integration tests (full pipeline)
+└── fixtures/             # Test data files (future)
+```
+
+**Current Test Coverage (Session 3):**
+- ✅ **Phase 1: Parser validation** (26 tests)
+- ✅ **Phase 2-5: Integration tests** (12 tests)
+- ✅ **i32 Arithmetic** (18 tests)
+- ✅ **i32 Bitwise** (32 tests)
+- ✅ **i32 Comparison** (20 tests)
+- ✅ **i64 Arithmetic** (19 tests)
+- ✅ **i64 Bitwise** (32 tests)
+- ✅ **i64 Comparison** (20 tests)
+- ✅ **f32 Arithmetic** (48 tests)
+- ✅ **f64 Arithmetic** (48 tests)
+- ✅ **Float Comparison** (17 tests)
+- ✅ **Float Edge Cases** (18 tests)
+- ✅ **Type Conversions** (53 tests: 16 original + 37 new comprehensive tests)
+- ✅ **Control Flow** (9 tests)
+- ✅ **Memory Operations** (14 tests)
+- ✅ **Functions, Stack, Constants** (19 tests)
+- ✅ **Error Handling** (19 tests)
+- ✅ **WGSL Output Validation** (40 tests)
+- ✅ **Global & Options** (2 tests)
+
+**Total:** 471 tests passing (414ms execution time)
+**Test Files:** 23 organized by instruction category
+
+### Adding New Tests
+
+```typescript
+import { assertEquals } from "jsr:@std/assert";
+import { compile } from "../src/mod.ts";
+
+Deno.test("Compiler - Feature Name", () => {
+  // Create WebAssembly binary (WAT → Wasm)
+  const wat = `
+    (module
+      (func (export "add") (param i32 i32) (result i32)
+        local.get 0
+        local.get 1
+        i32.add))
+  `;
+  const wasmBytes = wat2wasm(wat);  // Use wat2wasm utility
+
+  // Compile to WGSL
+  const wgslCode = compile(wasmBytes);
+
+  // Verify output
+  assertEquals(wgslCode.includes("param_0 + param_1"), true);
+});
+```
+
+---
+
+## API Reference
+
+### Main API
+
+#### `compile(source: Uint8Array, options?: CompileOptions): string`
+
+Compiles a WebAssembly binary to WGSL.
+
+**Parameters:**
+- `source`: WebAssembly binary (Uint8Array)
+- `options`: Optional compilation options
+
+**Returns:** WGSL shader code (string)
+
+**Throws:** `CompileError` if validation or transformation fails
+
+---
+
+### Types
+
+#### `CompileOptions`
+
+```typescript
+export interface CompileOptions {
+  workgroupSize?: [number, number, number];  // Default: [64, 1, 1]
+  debug?: boolean;                           // Emit debug comments (default: false)
+}
+```
+
+#### `CompileError`
+
+```typescript
+export interface CompileError {
+  type: "CompileError";
+  message: string;
+  location?: { line: number; column: number };
+  context?: string;
+}
+```
+
+#### `isCompileError(error: unknown): error is CompileError`
+
+Type guard to check if an error is a `CompileError`.
+
+---
+
+### Internal APIs
+
+These are exported for testing but not intended for public use:
+
+- `parseWasm(binary: Uint8Array): WasmModule` — Parse Wasm binary
+- `phaseStackToSSA(module: WasmModule): SSAModule` — Convert to SSA
+- `reloop(module: SSAModule): StructuredModule` — Restructure control flow
+- `phaseMemoryLowering(module: StructuredModule): StructuredModule` — Lower memory ops
+- `phaseWgslCodegen(module: StructuredModule, options?: CompileOptions): string` — Generate WGSL
+
+---
+
+## Contributing
+
+See [AGENTS.md](../../AGENTS.md) for guidelines on working with the core compiler.
+
+### Development Workflow
+
+1. **Write tests first** for new features
+2. **Run tests** with `pnpm test:core`
+3. **Keep platform-agnostic** — no Deno-specific APIs in core logic
+4. **Follow TypeScript strict mode** — all types must be explicit
+5. **Document public APIs** — JSDoc for all exported functions
+
+---
+
+## License
+
+MIT License — See [LICENSE](../../LICENSE) for details.
+
+---
+
+## Related Documentation
+
+- [Gasm Specification v0.1](../../spec/gasm-v0.1.md) — GPU-executable WebAssembly spec
+- [Instruction Set Reference](../../docs/instruction-set.md) — Detailed instruction mappings
+- [AGENTS.md](../../AGENTS.md) — Development guidelines for agents
+
+---
+
+**Last Updated:** December 2025