ReefVM/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ReefVM is a stack-based bytecode virtual machine for the Shrimp programming language. It implements a complete VM with closures, tail call optimization, exception handling, variadic functions, named parameters, and Ruby-style iterators with break/continue.

**Essential reading**: Before making changes, read README.md, SPEC.md, and GUIDE.md to understand the VM architecture, instruction set, and compiler patterns.

## Development Commands

### Running Files
```bash
bun <file.ts>              # Run TypeScript files directly
bun examples/native.ts     # Run example
```

### Testing
```bash
bun test                   # Run all tests
bun test <file>            # Run specific test file
bun test --watch           # Watch mode
```

### Building
No build step required - Bun runs TypeScript directly.

## Architecture

### Core Components

**VM Execution Model** (src/vm.ts):
- Stack-based execution with program counter (PC)
- Call stack for function frames
- Exception handler stack for try/catch/finally
- Lexical scope chain with parent references
- Native function registry for TypeScript interop

**Key subsystems**:
- **bytecode.ts**: Parser that converts human-readable bytecode strings to executable bytecode. Handles label resolution, constant pool management, and function definition parsing.
- **value.ts**: Tagged union Value type system with type coercion functions (toNumber, toString, isTrue, isEqual)
- **scope.ts**: Linked scope chain for variable resolution with lexical scoping
- **frame.ts**: Call frame tracking for function calls and break targets
- **exception.ts**: Exception handler records for try/catch/finally blocks
- **validator.ts**: Bytecode validation to catch common errors before execution
- **opcode.ts**: OpCode enum defining all VM instructions

### Critical Design Decisions

**Relative jumps**: All JUMP instructions use PC-relative offsets (not absolute addresses), making bytecode position-independent. PUSH_TRY/PUSH_FINALLY use absolute addresses.

**Truthiness semantics**: Only `null` and `false` are falsy. Unlike JavaScript, `0`, `""`, empty arrays, and empty dicts are truthy.

**No AND/OR opcodes**: Short-circuit logical operations are implemented at the compiler level using JUMP patterns with DUP.

**Tail call optimization**: TAIL_CALL reuses the current call frame instead of pushing a new one, enabling unbounded recursion.

**Break semantics**: CALL marks frames as break targets. BREAK unwinds the call stack to the most recent break target, enabling Ruby-style iterator patterns.

**Exception handling**: THROW jumps to finally (if present) or catch. The VM does NOT auto-jump to finally on successful try completion - compilers must explicitly generate JUMPs to finally blocks.

**Parameter binding priority**: Named args bind to fixed params first. Unmatched named args go to `@named` dict parameter. Fixed params bind in order: named arg > positional arg > default > null.

**Native function calling**: CALL_NATIVE consumes the entire stack as arguments (different from CALL which pops specific argument counts).

## Testing Strategy

Tests are organized by feature area:
- **basic.test.ts**: Stack ops, arithmetic, comparisons, variables, control flow
- **functions.test.ts**: Function creation, calls, closures, defaults, variadic, named args
- **tail-call.test.ts**: Tail call optimization and unbounded recursion
- **exceptions.test.ts**: Try/catch/finally, exception unwinding, nested handlers
- **native.test.ts**: Native function interop (sync and async)
- **bytecode.test.ts**: Bytecode parser, label resolution, constants
- **validator.test.ts**: Bytecode validation rules
- **examples.test.ts**: Integration tests for example programs

When adding features:
1. Add unit tests for the specific opcode/feature
2. Add integration tests showing real-world usage
3. Update SPEC.md with formal specification
4. Update GUIDE.md with compiler patterns
5. Consider adding an example to examples/

## Common Patterns

### Writing Bytecode Tests
```typescript
import { toBytecode, run } from "#reef"

const bytecode = toBytecode(`
  PUSH 42
  STORE x
  LOAD x
  HALT
`)

const result = await run(bytecode)
// result is { type: 'number', value: 42 }
```

### Native Function Registration
```typescript
const vm = new VM(bytecode)
vm.registerFunction('functionName', (...args: Value[]): Value => {
  // Implementation
  return toValue(result)
})
await vm.run()
```

### Label Usage (Preferred)
Use labels instead of numeric offsets for readability:
```
JUMP .skip
PUSH 42
HALT
.skip:
  PUSH 99
  HALT
```

## TypeScript Configuration

- Import alias: `#reef` maps to `./src/index.ts`
- Module system: ES modules (`"type": "module"` in package.json)
- Bun automatically handles TypeScript compilation

## Bun-Specific Notes

- Use `bun` instead of `node`, `npm`, `pnpm`, or `vite`
- No need for dotenv - Bun loads .env automatically
- Prefer Bun APIs over Node.js equivalents when available
- See .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc for detailed Bun usage

## Common Gotchas

**Jump offsets**: JUMP/JUMP_IF_FALSE/JUMP_IF_TRUE use relative offsets from the next instruction (PC + 1). PUSH_TRY/PUSH_FINALLY use absolute instruction indices.

**Stack operations**: Most binary operations pop in reverse order (second operand is popped first, then first operand).

**MAKE_ARRAY operand**: Specifies count, not a stack index. `MAKE_ARRAY #3` pops 3 items.

**CALL_NATIVE stack behavior**: Unlike CALL, it consumes all stack values as arguments and clears the stack.

**Finally blocks**: The compiler must generate explicit JUMPs to finally blocks for successful try/catch completion. The VM only auto-jumps to finally on THROW.

**Variable scoping**: STORE updates existing variables in parent scopes or creates in current scope. It does NOT shadow by default.