# CLAUDE.md -- Rust Project Conventions

## Philosophy

Functional, type-driven, domain-driven.

## Architecture

- Modules by domain context.
- Each parsing concern (expression, statement, pattern, declaration, class, module) gets its own module.
- Thin lib.rs that wires contexts together.

## 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.
- No naked `as` casts.
- Exhaustive matches; no `_` wildcard arm on enums.
- Iterators over indexed access.

## Traits

- No dyn Trait.
- 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 concern.

## Dependencies

- `ecma-syntax-cat = "0.1"` for AST types.
- `ecma-lex-cat = "0.1"` for tokens.
- `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 **parser** in the boa-cat stack:

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

## Parsing strategy

- Recursive descent for statements and declarations.
- Precedence climbing for expressions.
- Cover-grammar refinement: parenthesised expressions get reinterpreted as arrow parameters when `=>` follows.
- ASI: a `;` is optional immediately before `}` or EOF; required elsewhere.  Full newline-based ASI is a v0.2 TODO (the lexer would need to expose line-terminator hints).
