# Cleave Benchmarks

Performance benchmark suite for cleave core operations.

## Running Benchmarks

Run all benchmarks:
```bash
pytest benchmarks/ -v -m benchmark
```

Run specific benchmark:
```bash
pytest benchmarks/test_assessment_speed.py -v
```

Generate benchmark report:
```bash
pytest benchmarks/ -v -m benchmark --tb=short > benchmark_results.txt
```

## CI Integration

Benchmarks run automatically in CI on main branch commits via `.github/workflows/benchmarks.yml`.

Performance regression detection:
- Baseline metrics tracked in `benchmarks/baseline.json`
- CI fails if operations are >2x slower than baseline
- Baseline updated when approved by maintainers

## Benchmark Categories

### Assessment Speed (`test_assessment_speed.py`)
Tests complexity assessment with small/medium/large directives.

**Baseline targets:**
- Small directive: <100ms
- Medium directive: <500ms
- Large directive: <1000ms
- Repeated (100x): <1s total

### File Operations (`test_file_operations.py`)
Tests atomic file write throughput.

**Baseline targets:**
- 100 small files (1KB): <5s
- 50 medium files (100KB): <5s
- 10 large files (1MB): <5s
- 100 file reads (10KB): <2s

## Adding New Benchmarks

1. Create test file in `benchmarks/`
2. Mark tests with `@pytest.mark.benchmark`
3. Use `time.perf_counter()` for precise timing
4. Print results for CI visibility
5. Set reasonable assertions (not too strict)
6. Update this README with baseline targets
