refactor(day154-156): deepen pathfinding lessons with tests and study guide

Author: 0xBoji

src/day154_to_day156/README.md

@@ -0,0 +1,26 @@
+# Days 154-156: Pathfinding and Graph Distances (Deep Version)
+
+## Learning Goals
+- Day 154: Dijkstra with predecessor tracking, so learners see both distance and actual route.
+- Day 155: BFS on grid with full shortest-path reconstruction, not just distance.
+- Day 156: Floyd-Warshall with path rebuilding for all-pairs reasoning.
+
+## Why This Matters
+- Dijkstra appears in route planners, dependency optimization, and weighted workflow engines.
+- Grid BFS is the cleanest introduction to shortest path on unweighted graphs.
+- Floyd-Warshall is a great fit when node count is small but many pair queries are needed.
+
+## Common Mistakes
+- Forgetting to ignore stale entries in Dijkstra's heap.
+- Returning a BFS distance without preserving parent pointers.
+- Updating Floyd-Warshall distances without updating the `next` matrix for path replay.
+
+## Practice Exercises
+1. Easy: Add walls with different terrain costs and switch BFS to Dijkstra.
+2. Medium: Return every reachable cell and its parent from the grid search.
+3. Hard: Detect negative cycles in Floyd-Warshall and expose them in the API.
+
+## Suggested Homework
+- Build a tiny maze solver that prints the recovered path.
+- Compare BFS vs Dijkstra on weighted and unweighted maps.
+- Add a CLI that loads an adjacency matrix from JSON and prints shortest routes.

src/day154_to_day156/bfs_grid.rs

@@ -1,37 +1,109 @@
 use std::collections::VecDeque;
 
 pub fn run() {
-    println!("\nLesson: BFS on grid");
+    println!("\nDay 155 - BFS on grid: shortest route reconstruction");
 
     let grid = vec![
-        vec![0, 0, 1],
-        vec![1, 0, 0],
-        vec![1, 0, 0],
+        vec![0, 0, 1, 0],
+        vec![1, 0, 1, 0],
+        vec![1, 0, 0, 0],
+        vec![1, 1, 1, 0],
     ];
-    println!("distance={:?}", bfs((0, 0), (2, 2), &grid));
+
+    let route = shortest_path((0, 0), (3, 3), &grid);
+    println!("route={route:?}");
 }
 
-fn bfs(start: (usize, usize), target: (usize, usize), grid: &[Vec<i32>]) -> Option<i32> {
-    let n = grid.len();
-    let m = grid[0].len();
-    let mut dist = vec![vec![-1; m]; n];
-    let mut q = VecDeque::new();
+pub fn shortest_path(
+    start: (usize, usize),
+    target: (usize, usize),
+    grid: &[Vec<i32>],
+) -> Option<Vec<(usize, usize)>> {
+    if grid.is_empty() || grid[0].is_empty() {
+        return None;
+    }
+    if grid[start.0][start.1] == 1 || grid[target.0][target.1] == 1 {
+        return None;
+    }
+
+    let rows = grid.len();
+    let cols = grid[0].len();
+    let mut queue = VecDeque::new();
+    let mut visited = vec![vec![false; cols]; rows];
+    let mut prev = vec![vec![None; cols]; rows];
+
+    visited[start.0][start.1] = true;
+    queue.push_back(start);
+
+    let directions = [(1_i32, 0_i32), (-1, 0), (0, 1), (0, -1)];
 
-    q.push_back(start);
-    dist[start.0][start.1] = 0;
+    while let Some((x, y)) = queue.pop_front() {
+        if (x, y) == target {
+            return Some(reconstruct_path(start, target, &prev));
+        }
 
-    let dirs = [(1,0),(-1,0),(0,1),(0,-1)];
-    while let Some((x,y)) = q.pop_front() {
-        if (x,y) == target { return Some(dist[x][y]); }
-        for (dx,dy) in dirs {
+        for (dx, dy) in directions {
             let nx = x as i32 + dx;
             let ny = y as i32 + dy;
-            if nx < 0 || ny < 0 || nx >= n as i32 || ny >= m as i32 { continue; }
-            let (nx,ny) = (nx as usize, ny as usize);
-            if grid[nx][ny] == 1 || dist[nx][ny] != -1 { continue; }
-            dist[nx][ny] = dist[x][y] + 1;
-            q.push_back((nx,ny));
+            if nx < 0 || ny < 0 || nx >= rows as i32 || ny >= cols as i32 {
+                continue;
+            }
+
+            let (nx, ny) = (nx as usize, ny as usize);
+            if grid[nx][ny] == 1 || visited[nx][ny] {
+                continue;
+            }
+
+            visited[nx][ny] = true;
+            prev[nx][ny] = Some((x, y));
+            queue.push_back((nx, ny));
         }
     }
+
     None
 }
+
+fn reconstruct_path(
+    start: (usize, usize),
+    target: (usize, usize),
+    prev: &[Vec<Option<(usize, usize)>>],
+) -> Vec<(usize, usize)> {
+    let mut path = Vec::new();
+    let mut current = Some(target);
+
+    while let Some(node) = current {
+        path.push(node);
+        if node == start {
+            break;
+        }
+        current = prev[node.0][node.1];
+    }
+
+    path.reverse();
+    path
+}
+
+#[cfg(test)]
+mod tests {
+    use super::shortest_path;
+
+    #[test]
+    fn reconstructs_shortest_grid_path() {
+        let grid = vec![
+            vec![0, 0, 1],
+            vec![1, 0, 0],
+            vec![1, 0, 0],
+        ];
+
+        let path = shortest_path((0, 0), (2, 2), &grid).expect("path exists");
+        assert_eq!(path.first(), Some(&(0, 0)));
+        assert_eq!(path.last(), Some(&(2, 2)));
+        assert_eq!(path.len(), 5);
+    }
+
+    #[test]
+    fn returns_none_for_blocked_target() {
+        let grid = vec![vec![0, 1], vec![1, 1]];
+        assert_eq!(shortest_path((0, 0), (1, 1), &grid), None);
+    }
+}

src/day154_to_day156/dijkstra_basic.rs

@@ -1,37 +1,101 @@
 use std::cmp::Reverse;
 use std::collections::BinaryHeap;
 
+const INF: i64 = i64::MAX / 4;
+
 pub fn run() {
-    println!("\nLesson: Dijkstra shortest path");
+    println!("\nDay 154 - Dijkstra: shortest path + path reconstruction");
 
-    let g = vec![
+    let graph = vec![
         vec![(1usize, 2i64), (2, 5)],
         vec![(2, 1), (3, 4)],
-        vec![(3, 1)],
+        vec![(3, 1), (4, 7)],
+        vec![(4, 3)],
         vec![],
     ];
 
-    let d = dijkstra(0, &g);
-    println!("dist={:?}", d);
+    let result = dijkstra_with_prev(0, &graph);
+    println!("distances={:?}", result.distances);
+    println!("path 0 -> 4 = {:?}", result.path_to(4));
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DijkstraResult {
+    pub distances: Vec<i64>,
+    pub previous: Vec<Option<usize>>,
 }
 
-fn dijkstra(src: usize, g: &[Vec<(usize, i64)>]) -> Vec<i64> {
-    let n = g.len();
-    let mut dist = vec![i64::MAX / 4; n];
-    dist[src] = 0;
+impl DijkstraResult {
+    pub fn path_to(&self, target: usize) -> Option<Vec<usize>> {
+        if self.distances.get(target).copied()? >= INF {
+            return None;
+        }
+
+        let mut path = Vec::new();
+        let mut current = Some(target);
+        while let Some(node) = current {
+            path.push(node);
+            current = self.previous[node];
+        }
+        path.reverse();
+        Some(path)
+    }
+}
+
+pub fn dijkstra_with_prev(src: usize, graph: &[Vec<(usize, i64)>]) -> DijkstraResult {
+    let n = graph.len();
+    let mut distances = vec![INF; n];
+    let mut previous = vec![None; n];
     let mut pq = BinaryHeap::new();
-    pq.push((Reverse(0i64), src));
-
-    while let Some((Reverse(d), u)) = pq.pop() {
-        if d != dist[u] { continue; }
-        for &(v, w) in &g[u] {
-            let nd = d + w;
-            if nd < dist[v] {
-                dist[v] = nd;
-                pq.push((Reverse(nd), v));
+
+    distances[src] = 0;
+    pq.push((Reverse(0_i64), src));
+
+    while let Some((Reverse(current_dist), u)) = pq.pop() {
+        if current_dist != distances[u] {
+            continue;
+        }
+
+        for &(v, weight) in &graph[u] {
+            let next_dist = current_dist + weight;
+            if next_dist < distances[v] {
+                distances[v] = next_dist;
+                previous[v] = Some(u);
+                pq.push((Reverse(next_dist), v));
             }
         }
     }
 
-    dist
+    DijkstraResult {
+        distances,
+        previous,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{dijkstra_with_prev, INF};
+
+    #[test]
+    fn computes_shortest_distance_and_path() {
+        let graph = vec![
+            vec![(1usize, 2i64), (2, 5)],
+            vec![(2, 1), (3, 4)],
+            vec![(3, 1)],
+            vec![],
+        ];
+
+        let result = dijkstra_with_prev(0, &graph);
+        assert_eq!(result.distances, vec![0, 2, 3, 4]);
+        assert_eq!(result.path_to(3), Some(vec![0, 1, 2, 3]));
+    }
+
+    #[test]
+    fn unreachable_node_has_no_path() {
+        let graph = vec![vec![(1usize, 3i64)], vec![], vec![]];
+        let result = dijkstra_with_prev(0, &graph);
+
+        assert_eq!(result.distances[2], INF);
+        assert_eq!(result.path_to(2), None);
+    }
 }

src/day154_to_day156/floyd_warshall.rs

@@ -1,21 +1,101 @@
+const INF: i64 = 1_000_000_000;
+
 pub fn run() {
-    println!("\nLesson: Floyd-Warshall all-pairs shortest path");
+    println!("\nDay 156 - Floyd-Warshall: all-pairs shortest path");
 
-    let inf = 1_000_000;
-    let mut d = vec![
-        vec![0, 3, inf],
-        vec![2, 0, 4],
-        vec![inf, 1, 0],
+    let matrix = vec![
+        vec![0, 3, INF, 7],
+        vec![8, 0, 2, INF],
+        vec![5, INF, 0, 1],
+        vec![2, INF, INF, 0],
     ];
 
-    let n = d.len();
+    let result = floyd_warshall(matrix);
+    println!("dist matrix={:?}", result.distances);
+    println!("path 0 -> 3 = {:?}", result.path(0, 3));
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FloydWarshallResult {
+    pub distances: Vec<Vec<i64>>,
+    next: Vec<Vec<Option<usize>>>,
+}
+
+impl FloydWarshallResult {
+    pub fn path(&self, start: usize, end: usize) -> Option<Vec<usize>> {
+        self.next.get(start)?.get(end)?.as_ref()?;
+
+        let mut path = vec![start];
+        let mut current = start;
+
+        while current != end {
+            current = self.next[current][end]?;
+            path.push(current);
+        }
+
+        Some(path)
+    }
+}
+
+pub fn floyd_warshall(mut distances: Vec<Vec<i64>>) -> FloydWarshallResult {
+    let n = distances.len();
+    let mut next = vec![vec![None; n]; n];
+
+    for i in 0..n {
+        for j in 0..n {
+            if i != j && distances[i][j] < INF {
+                next[i][j] = Some(j);
+            }
+        }
+    }
+
     for k in 0..n {
         for i in 0..n {
             for j in 0..n {
-                d[i][j] = d[i][j].min(d[i][k] + d[k][j]);
+                if distances[i][k] >= INF || distances[k][j] >= INF {
+                    continue;
+                }
+
+                let through_k = distances[i][k] + distances[k][j];
+                if through_k < distances[i][j] {
+                    distances[i][j] = through_k;
+                    next[i][j] = next[i][k];
+                }
             }
         }
     }
 
-    println!("dist matrix={:?}", d);
+    FloydWarshallResult { distances, next }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{floyd_warshall, INF};
+
+    #[test]
+    fn computes_all_pairs_distances() {
+        let matrix = vec![
+            vec![0, 3, INF, 7],
+            vec![8, 0, 2, INF],
+            vec![5, INF, 0, 1],
+            vec![2, INF, INF, 0],
+        ];
+
+        let result = floyd_warshall(matrix);
+        assert_eq!(result.distances[0][3], 6);
+        assert_eq!(result.distances[3][1], 5);
+    }
+
+    #[test]
+    fn reconstructs_path() {
+        let matrix = vec![
+            vec![0, 3, INF, 7],
+            vec![8, 0, 2, INF],
+            vec![5, INF, 0, 1],
+            vec![2, INF, INF, 0],
+        ];
+
+        let result = floyd_warshall(matrix);
+        assert_eq!(result.path(0, 3), Some(vec![0, 1, 2, 3]));
+    }
 }