haz-dag 0.1.0

//! Overlay merging: combine each project's own tasks with the
//! tasks contributed by every overlay file that attaches to it,
//! producing an *effective task set* for every project per
//! `DAG-001`..`DAG-006` of `docs/spec/07-dag-semantics.md`.
//!
//! This module is the orchestrator for the overlay-merging layer:
//!
//! - `DAG-001` (overlay attachment) is consumed via the
//!   pre-computed [`haz_domain::overlay::Overlay::matched_projects`]
//!   set: discovery has already projected each overlay's
//!   `tagsFilter` against project tags per `CFG-026`, so this layer
//!   reads the relation directly.
//! - `DAG-002` (definition sources): for each `(project P, task
//!   name n)` pair, the set of definition sources is the union of
//!   `P`'s own task body for `n` (if present) and every overlay
//!   attaching a task named `n` to `P`.
//! - `DAG-003` (specialisation order): the standard partial order
//!   induced by set inclusion on matched-projects sets. A
//!   project-level source's conceptual matched-projects set is
//!   `{P}` and is therefore maximally specific.
//! - `DAG-004` (single source): a singleton definition-source set
//!   has a trivial winner.
//! - `DAG-005` (specialisation override): when more than one
//!   source exists, the unique source whose matched-projects set
//!   is a strict subset of every other source's set wins. A
//!   project-level source, when present, always wins per the spec.
//! - `DAG-006` (specialisation collision): when no unique winner
//!   exists, the workspace is rejected with a typed error
//!   identifying every contributing source for that
//!   `(project, task)` pair. Errors are accumulated across the
//!   workspace.
//!
//! After [`compute_effective_tasks`] succeeds, every project has
//! exactly one body per attached task name, and the result feeds
//! the rest of the DAG-construction pipeline
//! ([`crate::construction::build_task_graph`]).

use std::collections::{BTreeMap, BTreeSet};
use std::fmt;

use haz_domain::name::{OverlayName, ProjectName, TaskName};
use haz_domain::overlay::Overlay;
use haz_domain::task::Task;
use haz_domain::workspace::Workspace;
use snafu::Snafu;

/// Effective task set per project, after overlay merging.
///
/// Keyed by [`ProjectName`]. Every project in the input workspace
/// appears as a key; the inner map is the project's effective
/// tasks keyed by [`TaskName`].
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct EffectiveTasksByProject(BTreeMap<ProjectName, BTreeMap<TaskName, Task>>);

impl EffectiveTasksByProject {
    /// View the effective task map for one project, if known.
    #[must_use]
    pub fn get(&self, project: &ProjectName) -> Option<&BTreeMap<TaskName, Task>> {
        self.0.get(project)
    }

    /// Iterate over `(project, effective tasks)` pairs in
    /// [`ProjectName`] order.
    pub fn iter(&self) -> impl Iterator<Item = (&ProjectName, &BTreeMap<TaskName, Task>)> {
        self.0.iter()
    }

    /// Number of projects covered (always equals the number of
    /// projects in the source workspace).
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// `true` if no projects are covered (i.e., the source
    /// workspace had no projects).
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Consume and return the underlying map.
    #[must_use]
    pub fn into_inner(self) -> BTreeMap<ProjectName, BTreeMap<TaskName, Task>> {
        self.0
    }
}

/// Identity of a single definition source for a `(project, task)`
/// pair per `DAG-002`.
///
/// Variant ordering ([`ProjectLevel`] before [`Overlay`]) reflects
/// the specialisation order: a project-level source is maximally
/// specific by construction (`DAG-003`).
///
/// [`ProjectLevel`]: DefinitionSource::ProjectLevel
/// [`Overlay`]: DefinitionSource::Overlay
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum DefinitionSource {
    /// The project's own `haz.yml`.
    ProjectLevel {
        /// Identity of the project whose `haz.yml` contributes.
        project: ProjectName,
    },
    /// An overlay file `.haz/tasks/<name>.yml`.
    Overlay {
        /// Identity of the contributing overlay.
        name: OverlayName,
    },
}

impl fmt::Display for DefinitionSource {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            DefinitionSource::ProjectLevel { project } => {
                write!(f, "project-level `{project}/haz.yml`")
            }
            DefinitionSource::Overlay { name } => write!(f, "overlay `{name}.yml`"),
        }
    }
}

/// A single error encountered during overlay merging.
///
/// Multiple instances are accumulated into [`OverlayMergeErrors`]:
/// every `(project, task)` collision in the workspace surfaces in
/// one run.
#[derive(Debug, Clone, PartialEq, Eq, Snafu)]
pub enum OverlayMergeError {
    /// More than one definition source exists for the
    /// `(project, task)` pair AND no unique winner under the
    /// specialisation order (`DAG-006`). The body cannot be
    /// resolved; the workspace MUST be rejected.
    #[snafu(display(
        "task `{project}:{task}`: overlay-merge collision among {n} sources (DAG-006)",
        n = sources.len()
    ))]
    Collision {
        /// The project the collision applies to.
        project: ProjectName,
        /// The task name the collision applies to.
        task: TaskName,
        /// Every contributing definition source for the pair.
        /// Per `DAG-005` a project-level source, when present,
        /// always wins; therefore in practice this set contains
        /// only [`DefinitionSource::Overlay`] variants.
        sources: BTreeSet<DefinitionSource>,
    },
}

/// All overlay-merge errors accumulated by [`compute_effective_tasks`].
///
/// Ordered by project then task name; the printed diagnostic is
/// stable across runs.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OverlayMergeErrors(Vec<OverlayMergeError>);

impl OverlayMergeErrors {
    /// View the underlying slice without consuming.
    #[must_use]
    pub fn as_slice(&self) -> &[OverlayMergeError] {
        &self.0
    }

    /// Consume and return the underlying vector.
    #[must_use]
    pub fn into_inner(self) -> Vec<OverlayMergeError> {
        self.0
    }

    /// Number of accumulated errors. Always `>= 1` for a value
    /// that escapes [`compute_effective_tasks`] as `Err(_)`.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// `true` if there are no errors (defensive; the constructor
    /// only emits a value when there is at least one).
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

impl fmt::Display for OverlayMergeErrors {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let n = self.0.len();
        writeln!(f, "{n} error(s) during overlay merging:")?;
        for (i, err) in self.0.iter().enumerate() {
            writeln!(f, "  {}. {err}", i + 1)?;
        }
        Ok(())
    }
}

impl std::error::Error for OverlayMergeErrors {}

/// Compute the effective task set of every project in `workspace`
/// per `DAG-001`..`DAG-006`.
///
/// The function does NOT short-circuit on the first collision:
/// every `(project, task)` collision in the workspace surfaces in
/// the returned [`OverlayMergeErrors`].
///
/// # Errors
///
/// Returns [`OverlayMergeErrors`] when any `(project, task)`
/// definition-source set has more than one member AND no unique
/// winner under the specialisation order (`DAG-006`).
pub fn compute_effective_tasks(
    workspace: &Workspace,
) -> Result<EffectiveTasksByProject, OverlayMergeErrors> {
    let mut result: BTreeMap<ProjectName, BTreeMap<TaskName, Task>> = BTreeMap::new();
    let mut errors: Vec<OverlayMergeError> = Vec::new();

    for (project_name, project) in &workspace.projects {
        let attached_overlays: Vec<&Overlay> = workspace
            .overlays
            .values()
            .filter(|o| o.matched_projects.contains(project_name))
            .collect();

        let mut task_names: BTreeSet<&TaskName> = project.tasks.keys().collect();
        for overlay in &attached_overlays {
            for n in overlay.tasks.keys() {
                task_names.insert(n);
            }
        }

        let mut effective: BTreeMap<TaskName, Task> = BTreeMap::new();

        for task_name in task_names {
            let project_level_body = project.tasks.get(task_name);
            let overlay_sources: Vec<&Overlay> = attached_overlays
                .iter()
                .copied()
                .filter(|o| o.tasks.contains_key(task_name))
                .collect();

            if let Some(body) = pick_winner(project_level_body, &overlay_sources, task_name) {
                effective.insert(task_name.clone(), body.clone());
            } else {
                let mut sources: BTreeSet<DefinitionSource> = overlay_sources
                    .iter()
                    .map(|o| DefinitionSource::Overlay {
                        name: o.name.clone(),
                    })
                    .collect();
                if project_level_body.is_some() {
                    sources.insert(DefinitionSource::ProjectLevel {
                        project: project_name.clone(),
                    });
                }
                errors.push(OverlayMergeError::Collision {
                    project: project_name.clone(),
                    task: task_name.clone(),
                    sources,
                });
            }
        }

        result.insert(project_name.clone(), effective);
    }

    if errors.is_empty() {
        Ok(EffectiveTasksByProject(result))
    } else {
        Err(OverlayMergeErrors(errors))
    }
}

/// Pick the winning task body for one `(project, task)` pair, or
/// `None` if the definition-source set is empty or no unique
/// winner exists.
///
/// Per `DAG-005`: when a project-level source is present, it
/// always wins (it is maximally specific by construction). When
/// only overlay sources exist, the unique overlay whose
/// `matched_projects` is a strict subset of every other
/// candidate's `matched_projects` wins.
fn pick_winner<'a>(
    project_level: Option<&'a Task>,
    overlays: &[&'a Overlay],
    task_name: &TaskName,
) -> Option<&'a Task> {
    // DAG-005: project-level always wins when present.
    if let Some(body) = project_level {
        return Some(body);
    }

    match overlays.len() {
        0 => None,
        // DAG-004: single overlay is the trivial winner.
        1 => overlays[0].tasks.get(task_name),
        _ => {
            // DAG-005 (overlay-only path): an overlay X wins iff,
            // for every OTHER overlay Y in the candidate set,
            // X.matched_projects is a STRICT subset of
            // Y.matched_projects. If exactly one such X exists,
            // it wins; otherwise we report DAG-006.
            let winners: Vec<&Overlay> = overlays
                .iter()
                .copied()
                .filter(|x| {
                    overlays.iter().copied().all(|y| {
                        x.name == y.name
                            || (x.matched_projects.is_subset(&y.matched_projects)
                                && x.matched_projects != y.matched_projects)
                    })
                })
                .collect();
            if winners.len() == 1 {
                winners[0].tasks.get(task_name)
            } else {
                None
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use std::collections::BTreeSet;
    use std::path::PathBuf;
    use std::str::FromStr;

    use haz_domain::action::TaskAction;
    use haz_domain::env::EnvSettings;
    use haz_domain::name::{OverlayName, ProjectName, TaskName};
    use haz_domain::overlay::Overlay;
    use haz_domain::path::{CanonicalPath, HazPath, ProjectRoot, WorkspaceRootPath};
    use haz_domain::project::Project;
    use haz_domain::settings::WorkspaceSettings;
    use haz_domain::task::Task;
    use haz_domain::workspace::Workspace;
    use nonempty::NonEmpty;

    use super::{DefinitionSource, OverlayMergeError, compute_effective_tasks, pick_winner};

    fn project_name(s: &str) -> ProjectName {
        ProjectName::from_str(s).unwrap()
    }

    fn task_name(s: &str) -> TaskName {
        TaskName::from_str(s).unwrap()
    }

    fn overlay_name(s: &str) -> OverlayName {
        OverlayName::from_str(s).unwrap()
    }

    fn task_with_marker(name: &str, marker: &str) -> Task {
        Task {
            name: task_name(name),
            action: TaskAction::Command(
                NonEmpty::from_vec(vec!["echo".to_owned(), marker.to_owned()]).unwrap(),
            ),
            inputs: vec![],
            outputs: vec![],
            deps: vec![],
            weak_deps: vec![],
            mutex: None,
            env: EnvSettings::default(),
        }
    }

    fn project_with(name: &str, root: &str, tasks: Vec<Task>) -> Project {
        Project {
            name: project_name(name),
            root: ProjectRoot::Nested(
                CanonicalPath::from_absolute(&HazPath::parse(root).unwrap()).unwrap(),
            ),
            tags: BTreeSet::new(),
            tasks: tasks.into_iter().map(|t| (t.name.clone(), t)).collect(),
        }
    }

    fn overlay_with(name: &str, matched_projects: &[&str], tasks: Vec<Task>) -> Overlay {
        Overlay {
            name: overlay_name(name),
            matched_projects: matched_projects.iter().map(|p| project_name(p)).collect(),
            tasks: tasks.into_iter().map(|t| (t.name.clone(), t)).collect(),
        }
    }

    fn workspace_with(projects: Vec<Project>, overlays: Vec<Overlay>) -> Workspace {
        Workspace {
            root: WorkspaceRootPath::try_new(PathBuf::from("/abs/ws")).unwrap(),
            projects: projects.into_iter().map(|p| (p.name.clone(), p)).collect(),
            overlays: overlays.into_iter().map(|o| (o.name.clone(), o)).collect(),
            settings: WorkspaceSettings::default(),
        }
    }

    fn marker_of(task: &Task) -> &str {
        match &task.action {
            TaskAction::Command(parts) => parts[1].as_str(),
            TaskAction::Shell { .. } => panic!("expected Command action with two parts"),
        }
    }

    // DAG-002 + DAG-004 baseline: workspace with no overlays
    // returns project tasks verbatim.

    #[test]
    fn dag_002_no_overlays_returns_project_tasks_unchanged() {
        let p = project_with("p", "/p", vec![task_with_marker("build", "p-build")]);
        let q = project_with(
            "q",
            "/q",
            vec![
                task_with_marker("build", "q-build"),
                task_with_marker("test", "q-test"),
            ],
        );
        let workspace = workspace_with(vec![p, q], vec![]);
        let effective = compute_effective_tasks(&workspace).unwrap();

        assert_eq!(effective.len(), 2);
        let p_tasks = effective.get(&project_name("p")).unwrap();
        let q_tasks = effective.get(&project_name("q")).unwrap();
        assert_eq!(p_tasks.len(), 1);
        assert_eq!(q_tasks.len(), 2);
        assert_eq!(marker_of(&p_tasks[&task_name("build")]), "p-build");
        assert_eq!(marker_of(&q_tasks[&task_name("test")]), "q-test");
    }

    #[test]
    fn empty_workspace_returns_empty_effective_tasks() {
        let workspace = workspace_with(vec![], vec![]);
        let effective = compute_effective_tasks(&workspace).unwrap();
        assert!(effective.is_empty());
    }

    // DAG-001 + DAG-002: an overlay attaches its tasks to every
    // project in its matched-projects set, and only those.

    #[test]
    fn dag_002_overlay_attaches_task_only_to_matched_projects() {
        let p = project_with("p", "/p", vec![]);
        let q = project_with("q", "/q", vec![]);
        let r = project_with("r", "/r", vec![]);
        let lint = overlay_with(
            "lint",
            &["p", "r"],
            vec![task_with_marker("lint", "lint-body")],
        );
        let workspace = workspace_with(vec![p, q, r], vec![lint]);

        let effective = compute_effective_tasks(&workspace).unwrap();

        assert!(
            effective
                .get(&project_name("p"))
                .unwrap()
                .contains_key(&task_name("lint"))
        );
        assert!(
            effective
                .get(&project_name("r"))
                .unwrap()
                .contains_key(&task_name("lint"))
        );
        assert!(
            effective.get(&project_name("q")).unwrap().is_empty(),
            "overlay must NOT attach to unmatched project q"
        );
    }

    #[test]
    fn dag_002_overlay_only_task_appears_in_effective_set_for_matched_project() {
        let p = project_with("p", "/p", vec![task_with_marker("build", "p-build")]);
        let lint = overlay_with("lint", &["p"], vec![task_with_marker("lint", "lint-body")]);
        let workspace = workspace_with(vec![p], vec![lint]);

        let effective = compute_effective_tasks(&workspace).unwrap();
        let p_tasks = effective.get(&project_name("p")).unwrap();
        assert_eq!(p_tasks.len(), 2);
        assert_eq!(marker_of(&p_tasks[&task_name("build")]), "p-build");
        assert_eq!(marker_of(&p_tasks[&task_name("lint")]), "lint-body");
    }

    // DAG-004: single overlay source for a task is the trivial
    // winner.

    #[test]
    fn dag_004_single_overlay_source_is_trivial_winner() {
        let p = project_with("p", "/p", vec![]);
        let lint = overlay_with(
            "lint",
            &["p"],
            vec![task_with_marker("lint", "overlay-body")],
        );
        let workspace = workspace_with(vec![p], vec![lint]);

        let effective = compute_effective_tasks(&workspace).unwrap();
        let body = &effective.get(&project_name("p")).unwrap()[&task_name("lint")];
        assert_eq!(marker_of(body), "overlay-body");
    }

    // DAG-005: project-level source always wins over any overlay.

    #[test]
    fn dag_005_project_level_always_wins_over_overlay() {
        let p = project_with("p", "/p", vec![task_with_marker("build", "project-body")]);
        let universal = overlay_with(
            "universal",
            &["p"],
            vec![task_with_marker("build", "overlay-body")],
        );
        let workspace = workspace_with(vec![p], vec![universal]);

        let effective = compute_effective_tasks(&workspace).unwrap();
        let body = &effective.get(&project_name("p")).unwrap()[&task_name("build")];
        assert_eq!(marker_of(body), "project-body");
    }

    #[test]
    fn dag_005_project_level_wins_even_against_singleton_overlay() {
        // Overlay's matched_projects is {p}, equal to project-level's
        // conceptual {p}. Per DAG-005 project-level still wins.
        let p = project_with("p", "/p", vec![task_with_marker("build", "project-body")]);
        let singleton = overlay_with(
            "singleton",
            &["p"],
            vec![task_with_marker("build", "overlay-body")],
        );
        let workspace = workspace_with(vec![p], vec![singleton]);

        let effective = compute_effective_tasks(&workspace).unwrap();
        let body = &effective.get(&project_name("p")).unwrap()[&task_name("build")];
        assert_eq!(marker_of(body), "project-body");
    }

    // DAG-005 (overlay-only path): a strictly more specific
    // overlay wins over a less specific one.

    #[test]
    fn dag_005_more_specific_overlay_wins_over_less_specific() {
        let p = project_with("p", "/p", vec![]);
        let q = project_with("q", "/q", vec![]);
        let universal = overlay_with(
            "universal",
            &["p", "q"],
            vec![task_with_marker("lint", "universal-body")],
        );
        let specific = overlay_with(
            "specific",
            &["p"],
            vec![task_with_marker("lint", "specific-body")],
        );
        let workspace = workspace_with(vec![p, q], vec![universal, specific]);

        let effective = compute_effective_tasks(&workspace).unwrap();
        let p_body = &effective.get(&project_name("p")).unwrap()[&task_name("lint")];
        let q_body = &effective.get(&project_name("q")).unwrap()[&task_name("lint")];
        // For p: specific {p} ⊂ universal {p,q} → specific wins.
        assert_eq!(marker_of(p_body), "specific-body");
        // For q: only universal attaches → universal is trivially the source.
        assert_eq!(marker_of(q_body), "universal-body");
    }

    #[test]
    fn dag_005_three_overlay_chain_smallest_wins() {
        let p = project_with("p", "/p", vec![]);
        let q = project_with("q", "/q", vec![]);
        let r = project_with("r", "/r", vec![]);
        let pqr = overlay_with(
            "pqr",
            &["p", "q", "r"],
            vec![task_with_marker("compile", "pqr-body")],
        );
        let pq = overlay_with(
            "pq",
            &["p", "q"],
            vec![task_with_marker("compile", "pq-body")],
        );
        let p_only = overlay_with(
            "p_only",
            &["p"],
            vec![task_with_marker("compile", "p-only-body")],
        );
        let workspace = workspace_with(vec![p, q, r], vec![pqr, pq, p_only]);

        let effective = compute_effective_tasks(&workspace).unwrap();
        let body = &effective.get(&project_name("p")).unwrap()[&task_name("compile")];
        assert_eq!(
            marker_of(body),
            "p-only-body",
            "{{p}} ⊂ {{p,q}} ⊂ {{p,q,r}}: smallest wins"
        );
    }

    // DAG-006: incomparable matched-projects sets emit a collision.

    #[test]
    fn dag_006_incomparable_overlays_emit_collision() {
        let p = project_with("p", "/p", vec![]);
        let q = project_with("q", "/q", vec![]);
        let r = project_with("r", "/r", vec![]);
        let pq = overlay_with("pq", &["p", "q"], vec![task_with_marker("lint", "pq-body")]);
        let pr = overlay_with("pr", &["p", "r"], vec![task_with_marker("lint", "pr-body")]);
        let workspace = workspace_with(vec![p, q, r], vec![pq, pr]);

        let errors = compute_effective_tasks(&workspace).unwrap_err();
        let collision_for_p = errors.as_slice().iter().any(|e| {
            matches!(
                e,
                OverlayMergeError::Collision { project, task, sources }
                    if project == &project_name("p")
                        && task == &task_name("lint")
                        && sources.contains(&DefinitionSource::Overlay { name: overlay_name("pq") })
                        && sources.contains(&DefinitionSource::Overlay { name: overlay_name("pr") })
            )
        });
        assert!(collision_for_p, "expected DAG-006 collision for (p, lint)");
    }

    #[test]
    fn dag_006_equal_matched_projects_overlays_emit_collision() {
        // Two distinct overlay files with identical
        // matched-projects sets are treated as incomparable per
        // DAG-003 and therefore collide per DAG-006.
        let p = project_with("p", "/p", vec![]);
        let a = overlay_with("a", &["p"], vec![task_with_marker("lint", "a-body")]);
        let b = overlay_with("b", &["p"], vec![task_with_marker("lint", "b-body")]);
        let workspace = workspace_with(vec![p], vec![a, b]);

        let errors = compute_effective_tasks(&workspace).unwrap_err();
        assert_eq!(errors.len(), 1);
        let OverlayMergeError::Collision { sources, .. } = &errors.as_slice()[0];
        assert_eq!(sources.len(), 2);
        assert!(sources.contains(&DefinitionSource::Overlay {
            name: overlay_name("a")
        }));
        assert!(sources.contains(&DefinitionSource::Overlay {
            name: overlay_name("b")
        }));
    }

    #[test]
    fn dag_006_collision_does_not_block_other_tasks_or_projects() {
        // (p, collide) collides; (p, good) and (q, *) succeed.
        let p = project_with("p", "/p", vec![]);
        let q = project_with("q", "/q", vec![task_with_marker("build", "q-build")]);
        let a = overlay_with(
            "a",
            &["p"],
            vec![
                task_with_marker("collide", "a-body"),
                task_with_marker("good", "a-good"),
            ],
        );
        let b = overlay_with("b", &["p"], vec![task_with_marker("collide", "b-body")]);
        let workspace = workspace_with(vec![p, q], vec![a, b]);

        let errors = compute_effective_tasks(&workspace).unwrap_err();
        assert!(
            errors
                .as_slice()
                .iter()
                .all(|e| matches!(e, OverlayMergeError::Collision { task, .. } if task == &task_name("collide"))),
            "only `collide` should fail"
        );
    }

    #[test]
    fn errors_accumulate_across_projects_and_tasks() {
        // Two separate collisions, one for each project.
        let p = project_with("p", "/p", vec![]);
        let q = project_with("q", "/q", vec![]);
        let a = overlay_with(
            "a",
            &["p", "q"],
            vec![task_with_marker("collide", "a-body")],
        );
        let b = overlay_with(
            "b",
            &["p", "q"],
            vec![task_with_marker("collide", "b-body")],
        );
        let workspace = workspace_with(vec![p, q], vec![a, b]);

        let errors = compute_effective_tasks(&workspace).unwrap_err();
        assert_eq!(
            errors.len(),
            2,
            "expected one collision per affected project"
        );
    }

    // DefinitionSource ordering: ProjectLevel comes before Overlay
    // in the derived Ord, reflecting the specialisation hierarchy.

    #[test]
    fn dag_003_definition_source_ordering_puts_project_level_first() {
        let pl = DefinitionSource::ProjectLevel {
            project: project_name("z"),
        };
        let ov = DefinitionSource::Overlay {
            name: overlay_name("a"),
        };
        assert!(pl < ov);
    }

    // Display rendering: error text mentions count and one line
    // per error.

    #[test]
    fn display_overlay_merge_errors_renders_count_and_list() {
        let p = project_with("p", "/p", vec![]);
        let a = overlay_with("a", &["p"], vec![task_with_marker("lint", "a")]);
        let b = overlay_with("b", &["p"], vec![task_with_marker("lint", "b")]);
        let workspace = workspace_with(vec![p], vec![a, b]);

        let errors = compute_effective_tasks(&workspace).unwrap_err();
        let rendered = errors.to_string();
        assert!(rendered.starts_with("1 error(s) during overlay merging:"));
        assert!(rendered.contains("overlay-merge collision"));
        assert!(rendered.contains("DAG-006"));
    }

    // Helper-level: pick_winner edge cases that are awkward to
    // express via compute_effective_tasks alone.

    #[test]
    fn pick_winner_returns_none_for_empty_sources() {
        let result = pick_winner(None, &[], &task_name("anything"));
        assert!(result.is_none());
    }

    #[test]
    fn pick_winner_returns_project_level_over_overlays() {
        let project_body = task_with_marker("x", "pl");
        let overlay = overlay_with("a", &["p"], vec![task_with_marker("x", "ov")]);
        let body = pick_winner(Some(&project_body), &[&overlay], &task_name("x")).unwrap();
        assert_eq!(marker_of(body), "pl");
    }
}