Function build_walkthrough

atomic-cli/src/commands/triage/project.rs:847–979

Group the candidate modifications into ordered semantic layers. Pure and deterministic: clusters modified paths by [`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 that land in each l

(
    change_paths: &[(String, Vec<String>)],
    file_module: &BTreeMap<String, String>,
    file_deps: &BTreeSet<(String, String)>,
    task_facts: &[TaskFact],
)

/// prose rationale. No repo access; every input is already pinned by the
/// report.
pub(crate) fn build_walkthrough(
    change_paths: &[(String, Vec<String>)],
    file_module: &BTreeMap<String, String>,
    file_deps: &BTreeSet<(String, String)>,
    task_facts: &[TaskFact],
) -> Vec<WalkthroughLayer> {
    // 1. Cluster: layer key → sorted modified paths; path → layer key.
    let mut layer_files: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    let mut path_layer: BTreeMap<String, String> = BTreeMap::new();
    for (_, paths) in change_paths {
        for p in paths {
            let key = layer_key(p, file_module);
            layer_files
                .entry(key.clone())
                .or_default()
                .insert(p.clone());
            path_layer.insert(p.clone(), key);
        }
    }
    if layer_files.is_empty() {
        return Vec::new();
    }

    // 2. Order: project file → file dependencies onto layers. `a imports b`
    //    means b is more foundational, so the reading-order edge is b → a.
    //    Only edges where BOTH ends are modified files count — the walkthrough
    //    orders the change-set, not the whole codebase.
    let mut reads_after: BTreeMap<String, BTreeSet<String>> = BTreeMap::new(); // layer → layers it builds on
    for (from, to) in file_deps {
        let (Some(from_layer), Some(to_layer)) = (path_layer.get(from), path_layer.get(to)) else {
            continue;
        };
        if from_layer != to_layer {
            reads_after
                .entry(from_layer.clone())
                .or_default()
                .insert(to_layer.clone());
        }
    }

    // Kahn's algorithm over the layer set, always taking the lexicographically
    // smallest ready layer. A dependency cycle leaves layers with unresolved
    // in-edges; they are appended in lexicographic order (deterministic, and
    // their `depends_on` still names the relationship for the reader).
    let mut remaining: BTreeSet<String> = layer_files.keys().cloned().collect();
    let mut ordered: Vec<String> = Vec::new();
    while !remaining.is_empty() {
        let next = remaining
            .iter()
            .find(|l| {
                reads_after
                    .get(*l)
                    .map(|deps| deps.iter().all(|d| !remaining.contains(d)))
                    .unwrap_or(true)
            })
            .or_else(|| remaining.iter().next()) // cycle: break it lexicographically
            .cloned()
            .expect("remaining is non-empty");