# CLAUDE.md

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

## Project Overview

dshash is a simple SHA256 hashing library and command-line utility with no external dependencies. It consists of:
- **Library** (`src/`): Pure C++ SHA256 implementation that can hash strings, files, and directory trees
- **Utility** (`dshash/`): Command-line tool for hashing files and directories
- **Tests** (`tests/`): Comprehensive test suite including NIST vectors and system comparisons

## Build Commands

```bash
# Build the utility (from project root)
cd dshash && make clean && make

# Alternative: Use the build script
./build.sh  # Creates output/dshash

# Build just the library for testing
cd tests
g++ -std=c++17 -o test_lib test_lib.cpp ../src/dshash.cpp -I../src
```

## Test Commands

```bash
# Run all tests (recommended)
./test.sh  # or ./tests/test.sh

# The test suite includes:
# - Library unit tests
# - Utility tests  
# - System sha256sum comparisons
# - NIST test vectors
# - Stress tests
# - Edge cases
# - Performance benchmarks

# Build and run a specific test
cd tests
g++ -std=c++17 -o test_lib test_lib.cpp ../src/dshash.cpp -I../src && ./test_lib
g++ -std=c++17 -O2 -o test_stress test_stress.cpp ../src/dshash.cpp -I../src && ./test_stress
```

## Architecture

### SHA256 Implementation
The DSHash class (`src/dshash.hpp`) implements SHA256 from scratch:
- Uses standard SHA256 constants and operations (Ch, Maj, Σ0, Σ1, etc.)
- Processes data in 64-byte blocks
- Returns hash as `std::array<uint8_t, 32>` or hex string
- No external crypto library dependencies

### Key Design Decisions
1. **Single responsibility**: Library handles hashing only, utility handles CLI
2. **Directory hashing**: Recursively hashes all files in sorted order for deterministic results
3. **Static linking**: Utility is statically linked for portability (`-static` flag in Makefile)
4. **C++17**: Uses `std::filesystem` for cross-platform file operations

### Testing Strategy
The test suite (`tests/test.sh`) validates correctness by:
- Comparing output with system `sha256sum` for various inputs
- Verifying against official NIST test vectors
- Testing edge cases (empty files, special characters, padding boundaries)
- Stress testing with large files and many operations

## Development Guidelines

When modifying the SHA256 implementation:
- Ensure all NIST test vectors still pass
- Verify against system sha256sum for any new test cases
- The implementation follows FIPS 180-4 specification

When adding features to the utility:
- Maintain backward compatibility with existing command-line interface
- Keep the utility simple and focused on hashing
- Preserve static linking for distribution