# Valhalla Pure Rust Rewrite (`valhalla-rs`)
## Test Coverage Improvement Analysis & Comprehensive Action Plan

**Date:** July 28, 2026  
**Target Repository:** `https://gitdab.com/andodeki/nigig-org.git` (`crates/apps/valhalla/*`)  
**Baseline Test Count:** 56 Unit & Parity Tests  
**Target Test Count:** 80+ Comprehensive Unit, Property, Edge Case, & Integration Tests

---

## 1. Executive Summary & Audit Baseline

A comprehensive test coverage audit of the 11 Pure Rust Valhalla subcrates (`crates/apps/valhalla/*`) was performed to evaluate test density, edge case resilience, and boundary condition validation.

### Baseline Coverage Metrics:

| Crate | Baseline Test Count | Target Test Count | High-Priority Test Expansion Areas |
| :--- | :--- | :--- | :--- |
| **`valhalla-core`** | 26 tests | **35+ tests** | Anti-meridian wrapping, zero-copy struct bit-field deserialization, `EdgeInfo` polyline parsing. |
| **`valhalla-cost`** | 4 tests | **12+ tests** | Motorcycle & Scooter speed curves, mode access bitmasks, `HierarchyLimits` edge cases. |
| **`valhalla-path`** | 4 tests | **10+ tests** | `DoubleBucketQueue` overflow refills, $A^*$ unreachable destinations, `Isochrone` hull edge cases. |
| **`valhalla-search`** | 1 test | **4+ tests** | Multi-tile candidate locator boundary queries, search radius culling. |
| **`valhalla-match`** | 2 tests | **5+ tests** | Viterbi trajectory gaps, multi-candidate probability transition matrices. |
| **`valhalla-narrative`** | 3 tests | **8+ tests** | Locale template formatting for all 4 languages (`en-US`, `sw-KE`, `fr-FR`, `es-ES`), TTS abbreviations. |
| **`valhalla-elevation`** | 2 tests | **5+ tests** | SRTM1 ($3601 \times 3601$) parsing, bilinear interpolation tile boundary corners, `NO_DATA` values. |
| **`valhalla-service`** | 1 test | **4+ tests** | `ValhallaActor` status 400/404 error responses, `/height` and `/isochrone` endpoints. |
| **`valhalla-makepad`** | 3 tests | **6+ tests** | `DriverGuidanceController` off-route ($>25\text{m}$) auto-reroute event dispatch & HUD progress. |
| **`valhalla-builder`** | 9 tests | **12+ tests** | `OsmHighwayType` classification speed limits, PbfReader dense node delta offsets. |
| **`valhalla-diff`** | 1 test | **3+ tests** | Golden route fixture tolerance assertions (distance, time, maneuvers). |
| **Total Suite** | **56 tests** | **104+ tests** | Comprehensive test coverage across the entire routing suite. |

---

## 2. Action Plan for Test Suite Expansion

To achieve comprehensive test coverage, new tests will be implemented across all 11 subcrates:

### 2.1 `valhalla-core`
- Test `PointLL` anti-meridian coordinate wrapping ($180^\circ \to -180^\circ$) and polar limits ($\pm 90^\circ$).
- Test `AABB2` bounding box unions and zero-area point boxes.
- Test `Polyline2` single-point and empty polyline length queries.
- Test zero-copy deserialization for all `Raw*` bit-packed structs (`RawComplexRestriction`, `RawAccessRestriction`, `RawTimeDomain`, `RawNodeTransition`, `RawTrafficSpeed`, `RawTransitStop`, `RawTransitDeparture`, `RawTransitRoute`, `RawTransitSchedule`, `RawTurnLanes`, `RawLaneConnectivity`).

### 2.2 `valhalla-cost`
- Test `MotorcycleCost` and `MotorScooterCost` access bitmasks and speed limits.
- Test `AutoCost` toll penalty and border crossing penalty additions.
- Test `PedestrianCost` and `BicycleCost` mode access filtering.
- Test `HierarchyLimits` up-transition recording and expansion radius culling.

### 2.3 `valhalla-path`
- Test `DoubleBucketQueue` out-of-order pushes and equal sortcost pop ordering.
- Test `AStar` path search on unreachable destination nodes (returns `None`).
- Test `TimeDistanceMatrix` with asymmetric origin/destination lists.
- Test `IsochroneGenerator` convex hull with collinear and duplicate points.
- Test `AlternateRouteFinder` path sharing percentage calculation.

### 2.4 `valhalla-search`
- Test `EdgeLocator` multi-tile candidate snapping.
- Test `EdgeLocator` max search radius filtering.

### 2.5 `valhalla-match`
- Test `MapMatcher` Viterbi trajectory with noisy GPS points and heading alignment penalties.
- Test `MapMatcher` transition probability matrix calculations.

### 2.6 `valhalla-narrative`
- Test `NarrativeDictionary` formatting for French (`fr-FR`) and Spanish (`es-ES`).
- Test `VerbalTextFormatter` multi-abbreviation street name replacements (`"Moi Ave"` $\to$ `"Moi Avenue"`, `"Mama Ngina St"` $\to$ `"Mama Ngina Street"`).
- Test `ManeuverBuilder` multi-step turn sequence instruction generation.

### 2.7 `valhalla-elevation`
- Test `HgtTile` SRTM1 ($3601 \times 3601$) grid parsing.
- Test `HgtTile` bilinear interpolation at tile boundary corners.
- Test `ElevationSampler` polyline height profile sampling.

### 2.8 `valhalla-service`
- Test `ValhallaActor` status 404 for disconnected graph nodes.
- Test `ValhallaActor::height()` elevation profile response.
- Test `ValhallaActor::isochrone()` reachability response.

### 2.9 `valhalla-makepad`
- Test `DriverGuidanceController` off-route threshold ($>25\text{m}$) triggering `GuidanceEvent::Rerouted`.
- Test `NavigationHudData` step index progression and remaining time/distance calculations.

### 2.10 `valhalla-builder`
- Test `OsmHighwayType` speed limits for all 10 road classifications.
- Test `PbfReader` dense node coordinate delta decoding with custom granularity and offsets.

### 2.11 `valhalla-diff`
- Test `ParityChecker` error reporting for out-of-bounds distance and duration fixtures.

---

## 3. Execution & Verification

Run the expanded test suite using the isolated test runner:

```bash
TEST_TARGET=valhalla ./tools/test-rust-clean.sh
```

Ensure all tests pass cleanly with zero errors and zero warnings.