CLAUDE.md · diff
git:20260129.0d6f278 to git:20260129.19426b4
27 added, 127 removed. Audit A to A.
- <!-- OPENSPEC:START -->
- # OpenSpec Instructions
-
- These instructions are for AI assistants working in this project.
-
- Always open `@/openspec/AGENTS.md` when the request:
- - Mentions planning or proposals (words like proposal, spec, change, plan)
- - Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- - Sounds ambiguous and you need the authoritative spec before coding
-
- Use `@/openspec/AGENTS.md` to learn:
- - How to create and apply change proposals
- - Spec format and conventions
- - Project structure and guidelines
-
- Keep this managed block so 'openspec update' can refresh the instructions.
+ # CLAUDE.md
- <!-- OPENSPEC:END -->
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
- # CLAUDE.md
+ ## Project Overview
- This file provides guidance to Claude Code (claude.ai/code) when working
- with code in this repository.
+ Soleur is a Rust project using Edition 2024. The project is in early development with a basic Hello World entry point.
- ## Build and Test Commands
+ ## Build and Development Commands
```bash
- # Build the project
+ # Build
cargo build
- # Run all tests
+ # Run
+ cargo run
+
+ # Run tests
cargo test
- # Run a specific test
+ # Run a single test
cargo test test_name
- # Watch mode (requires cargo-watch: cargo install cargo-watch)
- cargo watch -x check -x test
-
- # Code coverage (requires cargo-llvm-cov: cargo install cargo-llvm-cov)
- cargo llvm-cov
- ```
-
- ## Architecture Overview
-
- This is a Merkle tree implementation in Rust, used for learning the
- language through implementing a data structure widely used in blockchains
- like Bitcoin and Ethereum.
-
- ### Core Design Patterns
-
- #### Strategy Pattern for Hashing
-
- - The `Hasher` trait (in `src/hasher/mod.rs`) allows pluggable hash
- algorithms
- - Two implementations: `Sha256Hasher` (production) and `SimpleHasher`
- (testing)
- - Hashers return `[u8; 32]` arrays for performance (raw bytes, not hex
- strings)
-
- #### Domain Separation for Security
-
- - Leaf nodes: H(0x00 || leaf_bytes)
- - Internal nodes: H(0x01 || left_hash || right_hash)
- - This prevents collision attacks where different tree structures could
- produce the same root
-
- #### Arc-based Tree Structure for Performance
-
- - Nodes use `Arc<Node>` to avoid deep copying during tree construction
- - `InternalNode` stores left/right children as `Arc<Node>`
- - The `Hash` trait returns `&[u8]` (not owned `String`) to eliminate
- cloning
-
- ### Module Organization
-
- ```text
- src/
- ├── hasher/ - Pluggable hash algorithms
- │ ├── mod.rs - Hasher trait definition
- │ ├── sha256.rs - Production hasher
- │ └── simple.rs - Test hasher
- ├── merkle/ - Tree structure
- │ ├── mod.rs - Public API and MerkleTree trait
- │ ├── hash.rs - Hash trait (for types that have a hash)
- │ ├── node.rs - Node enum (Leaf or Internal)
- │ ├── leaf_node.rs - Leaf node (contains raw data)
- │ ├── internal_node.rs - Internal node (has two children)
- │ └── simple_tree.rs - SimpleMerkleTree implementation
- └── lib.rs - Public API exports
- ```
-
- ### Tree Construction Algorithm
-
- The `SimpleMerkleTree` rebuilds the entire tree on each `add_leaf()` call:
-
- 1. Wrap all leaves in `Arc<Node>`
- 2. For each level:
- - Process nodes in pairs (chunks of 2)
- - If odd number of nodes, duplicate the last node (clone the Arc
- pointer)
- - Create internal nodes from pairs
- - Store in next level
- 3. Continue until one node remains (the root)
-
- ### Performance Considerations
-
- The codebase has been optimized for:
-
- - **Memory efficiency**: Using raw byte arrays `[u8; 32]` instead of hex
- strings
- - **Zero-copy hash access**: `Hash` trait returns `&[u8]` references
- - **Minimal cloning**: Arc pointers are cloned, not the underlying data
- - **Pre-allocated vectors**: `Vec::with_capacity()` used where sizes are
- known
-
- ### Invariants
+ # Format code
+ cargo fmt --all
- 1. Empty data is rejected (returns `MerkleTreeError::EmptyInput`)
- 2. Odd number of nodes at a level: duplicate the last node
- 3. A hash is always 32 bytes (`[u8; 32]`)
- 4. Domain separation prefixes (0x00 for leaves, 0x01 for internal nodes)
- are mandatory
+ # Lint (with auto-fix)
+ cargo clippy --fix --allow-dirty --allow-staged -- -D warnings
- ### Build Configuration
+ # Lint (check only)
+ cargo clippy -- -D warnings
- The project uses the `mold` linker for faster linking times (configured
- in `.cargo/config.toml`). Install with:
+ # Security audit
+ cargo audit
- ```bash
- sudo apt-get install clang mold
+ # Run tests with coverage
+ cargo llvm-cov --lcov --output-path lcov.info
```
- ## Claude Code Agents
-
- This project includes specialized agents:
-
- - `blockchain-developer`: Expert in Merkle tree blockchain applications
- - `rust-pro`: Advanced Rust programming assistance
-
- And reusable commands:
+ ## Code Quality
- - `/audit`: Dependency security and update checks
- - `/write_tests <target>`: Generate comprehensive test suites
+ - Pre-commit hooks are managed via lefthook (see `lefthook.yml`)
+ - Clippy warnings are treated as errors (`-D warnings`)
+ - Coverage target: 95% for project, 90% for patches
+ - Test files (`*tests.rs`, `tests/**`) are excluded from coverage metrics
## Browser Automation
- Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
+ Use `agent-browser` for web automation:
- Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes