refactor(bench): replace benchmark tools with unified comprehensive solution

Replaced multiple benchmark scripts with a single integrated tool that
provides human-readable reports and optional historical performance graphs.

**Key Changes**:

Removed:
- scripts/bench-viz.py (replaced)
- scripts/bench-report.sh (replaced)
- scripts/bench-compare.sh (replaced)
- bench.txt, bench-report.txt, bench_results.json from .gitignore

Added:
- scripts/bench.py - Comprehensive benchmark tool with:
  - Human-readable reports grouped by category (API, Parsers, Format)
  - Multiple performance metrics per benchmark
  - Summary statistics (fastest/slowest, averages)
  - Optional historical performance graphs across git commits

**Metrics Reported**:
- **Ops/Sec** - Operations per second (throughput)
- **ns/op** - Nanoseconds per operation (latency)
- **MB/s** - Megabytes per second (data throughput)
- **B/op** - Bytes allocated per operation (memory usage)
- **allocs/op** - Number of allocations per operation

**Usage**:
```bash
make bench          # Run benchmarks with comprehensive report
make bench N=50     # Run benchmarks + generate graphs for last 50 commits
```

**Historical Graphs** (when N specified):
- out/ops_per_sec.png - Throughput trends over time
- out/ns_per_op.png - Latency trends over time
- out/throughput.png - Data throughput (MB/s) trends
- out/bytes_per_op.png - Memory allocation trends
- out/allocs_per_op.png - Allocation count trends

**Makefile Updates**:
- Simplified bench target to use new tool
- Removed bench-all, bench-report, bench-viz targets
- Single command for all benchmark needs

**Documentation Updates**:
- README.md: Updated with new benchmark usage and metrics
- CONTRIBUTING.md: Detailed explanation of benchmark tool and graphs
- All documentation now reflects unified approach

The tool automatically skips commits where benchmarks fail to compile,
making it robust for historical analysis across code structure changes.

Requirements: Python 3 + matplotlib (only for historical graphs)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: rpuneet

.gitignore

@@ -24,10 +24,6 @@ go.work.sum
 debug/
 
 # Benchmark outputs
-bench.txt
-bench-report.txt
-bench_output.txt
-bench_results.json
 *.prof
 *.test
 trace.out

CONTRIBUTING.md

@@ -293,41 +293,44 @@ The `Extractor` type clones configuration per call and is safe for concurrent us
 ### Running Benchmarks
 
 ```bash
-make bench              # Quick benchmark run
-make bench-all          # Detailed output (3s timing, saved to bench.txt)
-make bench-report       # Generate formatted report
-make bench-compare OLD=commit1 NEW=commit2  # Compare commits
-make bench-viz N=50     # Generate performance graphs across last N commits
-```
-
-### Performance Visualization
+# Run benchmarks with comprehensive report
+make bench
 
-Generate graphs showing how performance evolved over time:
-
-```bash
-# Generate graphs for last 50 commits
-make bench-viz N=50
-
-# Custom number of commits
-make bench-viz N=100
+# Run benchmarks + generate historical graphs
+make bench N=50         # Last 50 commits
+make bench N=100        # Last 100 commits
 ```
 
-**Requirements**: Python 3 with matplotlib
+**Benchmark Report Includes**:
+- Human-readable performance metrics grouped by category (API, Parsers, Format)
+- Multiple metrics per benchmark:
+  - **Ops/Sec** - Operations per second (throughput)
+  - **ns/op** - Nanoseconds per operation (latency)
+  - **MB/s** - Megabytes per second (data throughput)
+  - **B/op** - Bytes allocated per operation (memory usage)
+  - **allocs/op** - Number of allocations per operation
+- Summary statistics (fastest/slowest, averages)
+
+**Historical Performance Graphs**:
+
+When you specify `N=commits`, the tool will:
+1. Run benchmarks on current commit and show results
+2. Checkout each of the last N commits
+3. Run benchmarks (skip commits where benchmarks fail)
+4. Generate graphs in `out/` directory showing performance trends
+
+**Graph Files Generated**:
+- `out/ops_per_sec.png` - Throughput over time
+- `out/ns_per_op.png` - Latency over time
+- `out/throughput.png` - Data throughput (MB/s) over time
+- `out/bytes_per_op.png` - Memory allocations over time
+- `out/allocs_per_op.png` - Allocation count over time
+
+**Requirements**: Python 3 + matplotlib (only for historical graphs)
 ```bash
 pip3 install matplotlib
 ```
 
-The tool will:
-1. Checkout each commit in git history
-2. Run benchmarks (skip if they fail to compile)
-3. Collect performance metrics
-4. Generate graphs in `out/` directory showing trends over time
-
-Graphs are generated for each benchmark showing:
-- Nanoseconds per operation (ns/op)
-- Bytes allocated per operation (B/op)
-- Allocations per operation (allocs/op)
-
 ### Continuous Benchmarking
 
 Every commit to `main` and every PR automatically runs benchmarks via GitHub Actions:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test test-lib lint fmt clean install coverage coverage-html check help bench bench-all bench-report bench-compare bench-viz
+.PHONY: build test test-lib lint fmt clean install coverage coverage-html check help bench
 
 # Go settings
 GOCMD = go
@@ -90,35 +90,9 @@ example: build
 	@echo "Running example..."
 	./$(BIN_DIR)/imx testdata/goldens/jpeg/google_iptc.jpg
 
-# Run benchmarks
+# Run benchmarks with comprehensive report
 bench:
-	@echo "Running benchmarks..."
-	$(GOTEST) -bench=. -benchmem -run=^$$ . ./internal/meta/... ./internal/format/...
-	@echo "✓ Benchmarks complete"
-
-# Run benchmarks with detailed output
-bench-all:
-	@echo "Running all benchmarks with detailed output..."
-	$(GOTEST) -bench=. -benchmem -benchtime=3s -run=^$$ . ./internal/meta/... ./internal/format/... | tee bench.txt
-	@echo "✓ Benchmarks saved to bench.txt"
-
-# Generate detailed benchmark report
-bench-report:
-	@echo "Generating benchmark report..."
-	@./scripts/bench-report.sh
-	@echo "✓ Benchmark report generated"
-
-# Compare benchmarks between commits
-bench-compare:
-	@echo "Comparing benchmarks between commits..."
-	@./scripts/bench-compare.sh $(OLD) $(NEW)
-	@echo "Usage: make bench-compare OLD=commit1 NEW=commit2"
-
-# Generate benchmark visualizations across git history
-bench-viz:
-	@echo "Running benchmarks across git history and generating graphs..."
-	@./scripts/bench-viz.py --max-commits $(or $(N),50) --graphs --output out
-	@echo "✓ Benchmark visualization complete. Graphs saved to out/"
+	@./scripts/bench.py $(if $(N),-n $(N),)
 
 # Show help
 help:
@@ -138,10 +112,6 @@ help:
 	@echo "  install      - Install CLI to GOPATH/bin"
 	@echo "  coverage     - Show coverage report (100% target)"
 	@echo "  coverage-html- Generate HTML coverage report"
-	@echo "  bench        - Run all benchmarks"
-	@echo "  bench-all    - Run benchmarks with detailed output"
-	@echo "  bench-report - Generate detailed benchmark report"
-	@echo "  bench-compare- Compare benchmarks between commits"
-	@echo "  bench-viz    - Generate benchmark graphs across git history (N=commits)"
+	@echo "  bench        - Run benchmarks with report (use N=commits for graphs)"
 	@echo "  example      - Build and run example"
 	@echo "  help         - Show this help"

README.md

@@ -196,39 +196,44 @@ BenchmarkParser_JPEG-12           481448       2.5μs/op      48KB/op       24 a
 - Automatic regression detection with 120% threshold
 - Performance alerts on PRs
 
-**Run Benchmarks Locally**:
+**Run Benchmarks**:
 ```bash
-make bench              # Quick benchmark run
-make bench-all          # Detailed output with 3s timing
-make bench-report       # Generate formatted report
-make bench-compare OLD=commit1 NEW=commit2  # Compare commits
-make bench-viz N=50     # Generate performance graphs across last 50 commits
+# Run benchmarks with comprehensive human-readable report
+make bench
+
+# Run benchmarks + generate historical performance graphs
+make bench N=50         # Last 50 commits
 ```
 
-**Performance Visualization**:
+The benchmark tool provides:
+- **Human-readable report** with performance metrics grouped by category
+- **Summary statistics** showing fastest/slowest benchmarks
+- **Multiple metrics**:
+  - **Ops/Sec** - Operations per second (throughput)
+  - **ns/op** - Nanoseconds per operation (latency)
+  - **MB/s** - Megabytes per second (data throughput)
+  - **B/op** - Bytes allocated per operation (memory usage)
+  - **allocs/op** - Number of allocations per operation
+
+**Historical Performance Graphs**:
 
-Generate performance graphs showing how benchmarks evolved over time:
+Generate performance trend graphs across git history:
 
 ```bash
-# Generate graphs for last 50 commits
-make bench-viz N=50
+make bench N=50     # Creates graphs in out/ directory
 ```
 
-This creates visualizations in `out/` directory showing:
-- **ns/op** - Nanoseconds per operation over time
-- **B/op** - Bytes allocated per operation over time
-- **allocs/op** - Number of allocations per operation over time
-
-Example graphs (run `make bench-viz` to generate):
-
-![High-Level API Performance](out/summary_HighLevelAPI.png)
-![Parser Performance](out/summary_ParserEXIF.png)
+Generates graphs showing trends over time:
+- `out/ops_per_sec.png` - Operations per second across commits
+- `out/ns_per_op.png` - Latency across commits
+- `out/throughput.png` - MB/s throughput across commits
+- `out/bytes_per_op.png` - Memory allocations across commits
+- `out/allocs_per_op.png` - Allocation count across commits
 
-**Requirements**: Python 3 with matplotlib (`pip3 install matplotlib`)
+**Requirements**: Python 3 with matplotlib for graphs (`pip3 install matplotlib`)
 
 **Tools**:
 - Results tracked via [github-action-benchmark](https://github.com/benchmark-action/github-action-benchmark)
-- Statistical comparison using [benchstat](https://pkg.go.dev/golang.org/x/perf/cmd/benchstat)
 - Historical visualization using Python + matplotlib
 
 ## Contributing