feat: add project comparison and benchmarking endpoints (#146)

[KingFRANKHOOD]

Summary

Add two new feature areas to the API: Project Comparison and Benchmarking against Industry Standards.
Closes #42
Closes #43
Closes #44
Closes #45

Project Comparison Endpoints

Method	Path	Description
GET	/v1/comparison?ids=1,2,3	Compare multiple projects side by side
GET	/v1/comparison/metrics	List available comparison metrics
GET	/v1/comparison/ranking?ids=1,2,3&criteria=green_impact	Generate ranking by criteria
GET	/v1/comparison/export?ids=1,2,3	Export comparison as CSV
GET	/v1/comparison/ranking/export?ids=1,2,3&criteria=combined_score	Export ranking as CSV

Acceptance criteria covered:

• Multi-project comparison — compare up to 20 projects simultaneously
• Side-by-side metrics — all 7 metrics displayed per project (credit_quality, green_impact, power_output_kw, efficiency_pct, forest_density_pct, ndvi_score, combined_score)
• Ranking generation — sortable by any metric with rank position
• Comparison export — CSV download for both comparison and ranking
• Custom comparison criteria — ranking supports any of the 7 available metrics as criteria

---

Benchmarking Endpoints

Method	Path	Description
GET	/v1/benchmarking/benchmarks	List all available benchmarks
GET	/v1/benchmarking/benchmarks/:id	Get specific benchmark definition
POST	/v1/benchmarking/benchmarks	Define a custom benchmark
GET	/v1/benchmarking/:id	Evaluate all benchmarks for a project
GET	/v1/benchmarking/:id/percentiles?metric=credit_quality	Get percentile ranking
GET	/v1/benchmarking/:id/alerts	Get benchmark alerts for a project
GET	/v1/benchmarking/:id/trend?metric=credit_quality&benchmark=credit_quality	Trend vs benchmark

Acceptance criteria covered:

• Industry standard data integration — 5 built-in benchmarks from NREL, Global Forest Watch, and Heliobond standards
• Percentile ranking — calculated against sampled project population
• Benchmark alerts — categorized as info/warning/critical based on performance tier
• Trend vs benchmark — compare historical trajectory against benchmark thresholds
• Custom benchmark definition — POST endpoint to define custom benchmarks with arbitrary thresholds

---

Files Changed

• src/index.ts — register new routes under /v1 and /api
• src/lib/comparison.ts — service layer for multi-project comparison, ranking, and CSV export
• src/routes/comparison.ts — route handlers for comparison endpoints
• src/lib/benchmarking.ts — service layer for benchmark evaluation, percentiles, alerts, and trend analysis
• src/routes/benchmarking.ts — route handlers for benchmarking endpoints
• src/__tests__/comparison.test.ts — 9 tests covering all comparison endpoints
• src/__tests__/benchmarking.test.ts — 10 tests covering all benchmarking endpoints

Testing

All 64 tests pass (45 pre-existing + 19 new).

[drips-wave]

@KingFRANKHOOD Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits