Group the candidate modifications into ordered semantic layers. Pure and deterministic: clusters modified paths by their layer key (`layer_key`), orders clusters foundations-first by a Kahn toposort over the module-level projection of `file_deps` (a layer that is imported reads before its importer), breaking ties — and cycles — lexicographically, then attaches the tasks, criteria, and changes tha
(
change_paths: &[(String, Vec<String>)],
file_module: &BTreeMap<String, String>,
file_deps: &BTreeSet<(String, String)>,
task_facts: &[TaskFact],
)
| 886 | /// prose rationale. No repo access; every input is already pinned by the |
| 887 | /// report. |
| 888 | pub fn build_walkthrough( |
| 889 | change_paths: &[(String, Vec<String>)], |
| 890 | file_module: &BTreeMap<String, String>, |
| 891 | file_deps: &BTreeSet<(String, String)>, |
| 892 | task_facts: &[TaskFact], |
| 893 | ) -> Vec<WalkthroughLayer> { |
| 894 | // 1. Cluster: layer key → sorted modified paths; path → layer key. |
| 895 | let mut layer_files: BTreeMap<String, BTreeSet<String>> = BTreeMap::new(); |
| 896 | let mut path_layer: BTreeMap<String, String> = BTreeMap::new(); |
| 897 | for (_, paths) in change_paths { |
| 898 | for p in paths { |
| 899 | let key = layer_key(p, file_module); |
| 900 | layer_files |
| 901 | .entry(key.clone()) |
| 902 | .or_default() |
| 903 | .insert(p.clone()); |
| 904 | path_layer.insert(p.clone(), key); |
| 905 | } |
| 906 | } |
| 907 | if layer_files.is_empty() { |
| 908 | return Vec::new(); |
| 909 | } |
| 910 | |
| 911 | // 2. Order: project file → file dependencies onto layers. `a imports b` |
| 912 | // means b is more foundational, so the reading-order edge is b → a. |
| 913 | // Only edges where BOTH ends are modified files count — the walkthrough |
| 914 | // orders the change-set, not the whole codebase. |
| 915 | let mut reads_after: BTreeMap<String, BTreeSet<String>> = BTreeMap::new(); // layer → layers it builds on |
| 916 | for (from, to) in file_deps { |
| 917 | let (Some(from_layer), Some(to_layer)) = (path_layer.get(from), path_layer.get(to)) else { |
| 918 | continue; |
| 919 | }; |
| 920 | if from_layer != to_layer { |
| 921 | reads_after |
| 922 | .entry(from_layer.clone()) |
| 923 | .or_default() |
| 924 | .insert(to_layer.clone()); |
| 925 | } |
| 926 | } |
| 927 | |
| 928 | // Kahn's algorithm over the layer set, always taking the lexicographically |
| 929 | // smallest ready layer. A dependency cycle leaves layers with unresolved |
| 930 | // in-edges; they are appended in lexicographic order (deterministic, and |
| 931 | // their `depends_on` still names the relationship for the reader). |
| 932 | let mut remaining: BTreeSet<String> = layer_files.keys().cloned().collect(); |
| 933 | let mut ordered: Vec<String> = Vec::new(); |
| 934 | while !remaining.is_empty() { |
| 935 | let next = remaining |
| 936 | .iter() |
| 937 | .find(|l| { |
| 938 | reads_after |
| 939 | .get(*l) |
| 940 | .map(|deps| deps.iter().all(|d| !remaining.contains(d))) |
| 941 | .unwrap_or(true) |
| 942 | }) |
| 943 | .or_else(|| remaining.iter().next()) // cycle: break it lexicographically |
| 944 | .cloned() |
| 945 | .expect("remaining is non-empty"); |