# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
CppShift is a Rust library that parses C++20 source code into an AST for transpilation to native Rust. Unlike FFI tools like `cxx`, it converts C++ code snippets directly to Rust. The AST design is heavily inspired by the [syn](https://github.com/dtolnay/syn) crate.
## Build Commands
```bash
cargo build # Build the library
cargo test # Run all tests (76 unit + 3 doc tests)
cargo test --lib # Run library tests only
cargo test <test_name> # Run a single test by name
cargo clippy # Lint
cargo fmt # Format code
cargo run --example lexer -- <file> # Run lexer on a C++ file
cargo run --example ast -- <file> # Run AST parser on a C++ file
```
## Architecture
The processing pipeline flows: **C++ source → Lexer → Parser → AST → Visitor**
### Core Components (`src/`)
- **`lib.rs`** — Library root. Exports `lex` and `ast` modules. Defines `SourceSpan` for tracking source locations (integrates with `miette` for diagnostics).
- **`lex.rs`** — Lexer/tokenizer. Implements `Iterator<Item=Result<Token, LexError>>`. The lexer is **cloneable** to support parser backtracking without buffering tokens. `Token` contains a `TokenKind` enum with 100+ variants covering all C++ operators and keywords.
- **`ast/parse.rs`** — Recursive descent parser. Wraps the cloneable `Lexer` with peek/peek_nth lookahead. This is the largest file (~4500 lines) and contains the bulk of the parsing logic plus ~60 tests.
- **`ast/item.rs`** — Top-level declaration nodes: functions, classes, structs, enums, unions, namespaces, templates, using declarations, constructors, destructors, etc.
- **`ast/expr.rs`** — Expression nodes: literals, operators, function calls, casts (`static_cast`, `dynamic_cast`, etc.), lambdas, `new`/`delete`, `throw`.
- **`ast/stmt.rs`** — Statement nodes: declarations, control flow (`if`, `while`, `for`, range-for), `try`/`catch`, `goto`/labels.
- **`ast/ty.rs`** — Type system nodes: fundamental types, pointers, references, arrays, templates, CV-qualifiers, `auto`, `decltype`.
- **`ast/punct.rs`** — Generic `Punctuated<T, P>` container for separator-delimited sequences (inspired by syn's `Punctuated`).
- **`ast/visit.rs`** — Visitor trait for immutable AST traversal with default `walk_*` implementations for recursive descent.
- **`ast/error.rs`** — `AstError` enum with `miette` integration for rich error diagnostics with source highlighting.
### Key Design Patterns
- All AST nodes carry a `'de` lifetime, borrowing from the original source string.
- Error reporting uses `miette` + `thiserror` for source-annotated diagnostics.
- The `Punctuated<T, P>` type tracks whether trailing punctuation exists, mirroring syn's approach.
- Async dev-dependencies (`tokio`, `reqwest`) are used only for integration tests that fetch real C++ code from GitHub.