# CLAUDE.md -- Rust Project Conventions

## Philosophy

Functional, type-driven, domain-driven.

## Architecture

- Modules by domain context.
- One module per evaluation concern (value, heap, env, completion, expression, statement).
- Thin lib.rs that wires contexts together and exposes the Io entry point.

## Types

- Newtypes for domain primitives.
- Sum types for variants.
- No public struct fields; enum variants with named fields are permitted.
- `#[must_use]` on getters and constructors.

## Error Handling

- Single project-wide `Error` enum.
- Display + std::error::Error impls by hand; no thiserror, no anyhow.
- Never panic in library code.

## Style

- Prefer match over if/else, except on bool.
- No `return` keyword.
- No `mut`.
- Combinators over loops.
- Never match on Option<_>; use combinators.
- Prefer combinators on Result<_, _>; match only when arms are complex.
- No unwrap()/expect() anywhere.
- No loop or for.
- No scan.
- No Rc/Arc (exception: comp-cat-rs Stream API requires `Arc<dyn Fn(...)>`).
- No naked `as` casts.
- Exhaustive matches; no `_` wildcard arm on enums.
- Iterators over indexed access.

## Traits

- No dyn Trait (exception: comp-cat-rs effect types use dyn internally).
- Implement standard traits over ad-hoc methods.

## Linting

```toml
[lints.clippy]
all = { level = "deny", priority = -1 }
pedantic = { level = "warn", priority = -1 }
needless_pass_by_value = "warn"
manual_map = "warn"
```

## Verification

- Always run `RUSTFLAGS="-D warnings" cargo clippy --all-targets`.
- Always run `cargo fmt`.

## Testing

- Tests return `Result<(), Error>` and propagate failures with `?`.
- No assert!, assert_eq!, panic!, unreachable!, unwrap, expect.
- Integration tests in tests/ organized by language concern.

## Dependencies

- `comp-cat-rs` foundation.  Use Io at the entry point; manual `(Value, Heap)` threading inside.
- `ecma-syntax-cat` for AST types.
- `ecma-lex-cat` for lexer.
- `ecma-parse-cat` for parser.
- `proptest` dev-dep.
- No path dependencies.

## Documentation

- `///` doc comments on every public item.
- `# Examples` with runnable code blocks.
- Doctests must not use unwrap/expect/unreachable.

## Layer context

This crate is the **engine** in the boa-cat stack:

1. `ecma-syntax-cat` -- AST types.
2. `ecma-lex-cat` -- tokenizer.
3. `ecma-parse-cat` -- parser; consumes tokens, produces Program.
4. **`boa-cat`** -- engine; consumes Program, produces Value.
5. `ecma-runtime-cat` -- built-ins.
6. `tauri-runtime-servocat` -- Tauri bridge.

## Evaluation strategy

- Tree-walking interpreter.
- Persistent heap (`BTreeMap<ObjectId, Object>`) cloned on every "mutation".
- Persistent env (cons list of `(name, Value)`).
- Statements return `(Completion, Heap, Env)`; expressions return `(Value, Heap)`.
- `Completion = Normal(Value) | Break | Continue | Return(Value) | Throw(Value)` -- the spec's abrupt-completion mechanism.
- Functions close over their definition-time env; calls extend it with parameter bindings.
- Arrow functions inherit `this` from the surrounding lexical scope.
- `Fuel` budget bounds evaluation; running out of fuel raises `Error::FuelExhausted`.

## v0 scope

In v0 the engine supports the core surface of ECMAScript:

- All literals (number, string, boolean, null, regex, template, BigInt-as-string).
- Variable resolution + var/let/const declarations (identifier patterns only, no destructuring in v0).
- All binary/unary/logical/conditional/assignment/sequence operators with spec semantics.
- Functions: declarations, expressions, arrow forms; closures; call + return.
- Member access (dot, computed), call, new, optional chaining (treated as plain access).
- Array and object literals (including spread and shorthand properties).
- Statements: block, expression, if, while, do-while, for-classic, for-in, for-of, switch, throw, try/catch/finally, return.

Deferred to v0.2+:

- Class declarations and expressions (require prototype chain).
- Destructuring patterns in declarations and parameters.
- Modules and import/export.
- async/await/yield and generators (require scheduler integration via the lambda-async-cat queue model).
- Tagged templates.
- Labeled break/continue.
- PrivateIdentifier, MetaProperty, ImportExpression, Super.
