feat(bench): add performance visualization tool across git history

Added comprehensive Python tool to visualize benchmark performance over time:

**New Tool**: scripts/bench-viz.py
- Runs benchmarks across git commit history
- Parses Go benchmark output and extracts metrics
- Generates performance graphs using matplotlib
- Supports parallel execution planning (sequential for now)
- Handles compilation failures gracefully (skips commits)
- Saves results as JSON for reuse

**Features**:
- Individual graphs per benchmark showing all metrics
- Summary graphs grouping benchmarks by category
- CLI with options for commit count, output dir, JSON export
- Automatic date-based x-axis formatting
- Latest value annotations on graphs

**Metrics Visualized**:
- ns/op: Nanoseconds per operation over time
- B/op: Bytes allocated per operation over time
- allocs/op: Allocations per operation over time

**Usage**:
```bash
make bench-viz N=50              # Last 50 commits
./scripts/bench-viz.py --help    # Full options
```

**Requirements**: Python 3 + matplotlib

**Documentation Updates**:
- README.md: Added Performance Visualization section with examples
- CONTRIBUTING.md: Added detailed visualization usage guide
- Makefile: Added bench-viz target
- .gitignore: Added out/ and bench_results.json

Graphs are saved to out/ directory and can be embedded in README
to show performance trends across project history.

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

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

Author: rpuneet

.gitignore

@@ -27,6 +27,8 @@ debug/
 bench.txt
 bench-report.txt
 bench_output.txt
+bench_results.json
 *.prof
 *.test
 trace.out
+out/

CONTRIBUTING.md

@@ -297,8 +297,37 @@ 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
+
+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
+```
+
+**Requirements**: Python 3 with matplotlib
+```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:
@@ -355,6 +384,7 @@ make bench         # Run benchmarks
 make bench-all     # Run benchmarks with detailed output
 make bench-report  # Generate benchmark report
 make bench-compare # Compare benchmarks between commits
+make bench-viz     # Generate performance graphs across git history
 make example       # Build and run example
 ```
 

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
+.PHONY: build test test-lib lint fmt clean install coverage coverage-html check help bench bench-all bench-report bench-compare bench-viz
 
 # Go settings
 GOCMD = go
@@ -114,6 +114,12 @@ bench-compare:
 	@./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/"
+
 # Show help
 help:
 	@echo "imx - Image Metadata Extraction Library"
@@ -136,5 +142,6 @@ help:
 	@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 "  example      - Build and run example"
 	@echo "  help         - Show this help"

README.md

@@ -202,11 +202,34 @@ 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
 ```
 
+**Performance Visualization**:
+
+Generate performance graphs showing how benchmarks evolved over time:
+
+```bash
+# Generate graphs for last 50 commits
+make bench-viz N=50
+```
+
+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)
+
+**Requirements**: Python 3 with matplotlib (`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