# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Overview
This is a Rust workspace implementing the [oshash algorithm](https://pypi.org/project/oshash/) — a fast file hashing method that reads only the first 64KB and last 64KB of a file plus its size, returning a 16-character hex string. It's optimized for media files.
Two crates:
- `oshash` — library crate (root)
- `oshash-cli` — CLI binary in `cli/`
MSRV: 1.60
## Common Commands
```bash
# Build
cargo build --all --all-features
# Test
cargo test --locked --all-features --all-targets
cargo test --all-features --doc
# Lint & format
cargo fmt --check
cargo clippy
# Feature powerset check (like CI)
cargo hack --feature-powerset check
# Semver validation
cargo semver-checks
```
To run a single test:
```bash
cargo test --all-features test_name
```
## Architecture
### Library (`src/`)
- `lib.rs` — Defines `HashError` (FileTooSmall, IoError), constants (`CHUNK_SIZE=65536`, `MIN_FILE_SIZE=131072`), and feature-gated re-exports
- `sync.rs` — `oshash(path)` and `oshash_buf(&mut file, len)` — synchronous implementations
- `async_impl.rs` — `oshash_async(path)` and `oshash_buf_async(&mut file, len)` — tokio-based async implementations (behind `tokio` feature flag)
The hash algorithm: read first 64KB and last 64KB of file as little-endian u64 chunks, sum them with the file size, format as hex. Minimum file size is 128KB; smaller files return `HashError::FileTooSmall`. Both sync and async implementations preserve the seek position of the file handle after hashing.
### CLI (`cli/src/main.rs`)
Uses `clap` with derive macros. Accepts file paths as positional args, prints `hash path` per file. Supports `--bench` flag for 1000-iteration performance measurement.
### Tests
- `tests/integration_tests.rs` — sync API (7 tests)
- `tests/async_integration_tests.rs` — async API mirror tests (feature-gated)
- `test-resources/testdata` — 128KB+ file (expected hash: `40d354daf3acce9c`)
- `test-resources/too_small` — sub-128KB file for error-path testing
### Features
- `tokio` (optional) — enables async implementations; the crate is usable without it