haz-domain 0.2.0

//! Reference resolution: turn a parsed [`TaskRef`] into the set of
//! [`TaskId`]s it points at.
//!
//! The function in this module is the bridge between the textual
//! reference forms defined by `REF-002`..`REF-005` and `REF-008`
//! and the workspace-level task identity. It is pure: no IO, no
//! async, no logging. A successful resolution returns a non-empty
//! `BTreeSet<TaskId>`; an empty result is reported as a specific
//! [`ResolutionError`] variant per the rules in
//! `docs/spec/05-task-references.md`.
//!
//! Cross-reference accumulation (one error per task, all errors
//! reported) belongs to a layer above this module per `DAG-011`.

use std::collections::BTreeSet;

use snafu::Snafu;

use crate::name::{ProjectName, TagName, TaskName};
use crate::project::Project;
use crate::task_id::TaskId;
use crate::task_ref::TaskRef;
use crate::workspace::Workspace;

/// Error produced when a [`TaskRef`] cannot be resolved against a
/// [`Workspace`].
///
/// Each variant corresponds to one specific failure mode so the
/// caller can render targeted diagnostics. The accumulation of
/// multiple unresolved references across a workspace is the
/// caller's responsibility per `DAG-011`.
#[derive(Debug, Clone, PartialEq, Eq, Snafu)]
pub enum ResolutionError {
    /// Same-project reference (`~:<task>`) where the bearing project
    /// does not define a task with the given name (`REF-002`).
    #[snafu(display("bearing project does not define task `{task}`"))]
    BearingTaskNotFound {
        /// The task name that was not found.
        task: TaskName,
    },

    /// Project reference (`<project>:<task>`) where the named
    /// project is not in the workspace (`REF-003`).
    #[snafu(display("project `{project}` not found in workspace"))]
    ProjectNotFound {
        /// The project name that was not found.
        project: ProjectName,
    },

    /// Project reference (`<project>:<task>`) where the named
    /// project exists but does not define the given task
    /// (`REF-003`).
    #[snafu(display("project `{project}` does not define task `{task}`"))]
    TaskNotInProject {
        /// The project that was found.
        project: ProjectName,
        /// The task name that was not found in that project.
        task: TaskName,
    },

    /// Fan-out reference (`^:<task>`) whose resolved set is empty:
    /// no project in the workspace defines the named task
    /// (`REF-004`).
    #[snafu(display("no project defines task `{task}`"))]
    FanOutEmpty {
        /// The task name fanned out over.
        task: TaskName,
    },

    /// Sibling-fan-out reference (`^~:<task>`) whose resolved set is
    /// empty: no project *other than the bearing project* defines
    /// the named task (`REF-008`).
    #[snafu(display("no sibling project defines task `{task}` (bearing project excluded)"))]
    SiblingFanOutEmpty {
        /// The task name fanned out over.
        task: TaskName,
    },

    /// Tag reference (`[<tag>]:<task>` or `[<tag>]~:<task>`) where
    /// no project in the workspace carries the named tag. The same
    /// variant covers both the plain-tag and sibling-tag forms
    /// because the underlying condition is identical
    /// (`REF-005`, `REF-008`).
    #[snafu(display("no project carries tag `{tag}`"))]
    TagNotInWorkspace {
        /// The tag name that no project carries.
        tag: TagName,
    },

    /// Tag reference (`[<tag>]:<task>`) where projects carrying the
    /// tag exist but none of them define the named task
    /// (`REF-005`).
    #[snafu(display("no project with tag `{tag}` defines task `{task}`"))]
    TagEmpty {
        /// The tag name.
        tag: TagName,
        /// The task name.
        task: TaskName,
    },

    /// Sibling-tag reference (`[<tag>]~:<task>`) whose resolved set
    /// is empty: no project *other than the bearing project*
    /// carries the tag and defines the named task (`REF-008`).
    #[snafu(display(
        "no sibling project with tag `{tag}` defines task `{task}` (bearing project excluded)"
    ))]
    SiblingTagEmpty {
        /// The tag name.
        tag: TagName,
        /// The task name.
        task: TaskName,
    },
}

/// Resolve `reference` to the set of [`TaskId`]s it points at,
/// given the bearing project (the project that owns the task
/// where the reference appears) and the surrounding workspace.
///
/// On success, the returned set is always non-empty. An empty
/// result is reported as one of the [`ResolutionError`] variants
/// rather than `Ok(BTreeSet::new())`.
///
/// The bearing project is taken by reference rather than by name
/// so that the function does not need to look it up in
/// `workspace`. This keeps the precondition "bearing is a real
/// project" out of the error space: the caller is responsible for
/// passing a valid `Project`.
///
/// # Errors
///
/// Returns the [`ResolutionError`] variant matching the failure
/// mode. See the variant docs for the full mapping. Cycle
/// detection is *not* performed here; it is a graph-layer
/// concern per `DAG-014`.
///
/// # Examples
///
/// ```
/// use std::collections::{BTreeMap, BTreeSet};
/// use std::str::FromStr;
/// use nonempty::NonEmpty;
/// use haz_domain::action::TaskAction;
/// use haz_domain::env::EnvSettings;
/// use haz_domain::name::{ProjectName, TaskName};
/// use haz_domain::path::{CanonicalPath, HazPath, ProjectRoot, WorkspaceRootPath};
/// use haz_domain::project::Project;
/// use haz_domain::resolution::resolve_task_ref;
/// use haz_domain::settings::WorkspaceSettings;
/// use haz_domain::task::Task;
/// use haz_domain::task_id::TaskId;
/// use haz_domain::task_ref::TaskRef;
/// use haz_domain::workspace::Workspace;
///
/// let bearing = Project {
///     name: ProjectName::from_str("lib_core").unwrap(),
///     root: ProjectRoot::Nested(
///         CanonicalPath::from_absolute(&HazPath::parse("/lib_core").unwrap()).unwrap(),
///     ),
///     tags: BTreeSet::new(),
///     tasks: BTreeMap::from([(
///         TaskName::from_str("build").unwrap(),
///         Task {
///             name: TaskName::from_str("build").unwrap(),
///             action: TaskAction::Command(NonEmpty::from_vec(vec!["true".to_owned()]).unwrap()),
///             inputs: vec![],
///             outputs: vec![],
///             deps: vec![],
///             weak_deps: vec![],
///             mutex: None,
///             env: EnvSettings::default(),
///         },
///     )]),
/// };
/// let mut projects = BTreeMap::new();
/// projects.insert(bearing.name.clone(), bearing.clone());
///
/// let workspace = Workspace {
///     root: WorkspaceRootPath::try_new(std::path::PathBuf::from("/abs/ws")).unwrap(),
///     projects,
///     overlays: BTreeMap::new(),
///     settings: WorkspaceSettings::default(),
/// };
///
/// let reference = TaskRef::parse("~:build").unwrap();
/// let resolved = resolve_task_ref(&reference, &bearing, &workspace).unwrap();
/// assert_eq!(resolved.len(), 1);
/// assert!(resolved.contains(&TaskId {
///     project: ProjectName::from_str("lib_core").unwrap(),
///     task: TaskName::from_str("build").unwrap(),
/// }));
/// ```
pub fn resolve_task_ref(
    reference: &TaskRef,
    bearing: &Project,
    workspace: &Workspace,
) -> Result<BTreeSet<TaskId>, ResolutionError> {
    match reference {
        TaskRef::SameProject(task) => resolve_same_project(task, bearing),
        TaskRef::Project(project, task) => resolve_project(project, task, workspace),
        TaskRef::FanOut(task) => resolve_fan_out(task, workspace, None),
        TaskRef::SiblingFanOut(task) => resolve_fan_out(task, workspace, Some(&bearing.name)),
        TaskRef::Tag(tag, task) => resolve_tag(tag, task, workspace, None),
        TaskRef::SiblingTag(tag, task) => resolve_tag(tag, task, workspace, Some(&bearing.name)),
    }
}

fn resolve_same_project(
    task: &TaskName,
    bearing: &Project,
) -> Result<BTreeSet<TaskId>, ResolutionError> {
    if bearing.tasks.contains_key(task) {
        Ok(BTreeSet::from([TaskId {
            project: bearing.name.clone(),
            task: task.clone(),
        }]))
    } else {
        Err(ResolutionError::BearingTaskNotFound { task: task.clone() })
    }
}

fn resolve_project(
    project: &ProjectName,
    task: &TaskName,
    workspace: &Workspace,
) -> Result<BTreeSet<TaskId>, ResolutionError> {
    let Some(found) = workspace.projects.get(project) else {
        return Err(ResolutionError::ProjectNotFound {
            project: project.clone(),
        });
    };
    if found.tasks.contains_key(task) {
        Ok(BTreeSet::from([TaskId {
            project: project.clone(),
            task: task.clone(),
        }]))
    } else {
        Err(ResolutionError::TaskNotInProject {
            project: project.clone(),
            task: task.clone(),
        })
    }
}

fn resolve_fan_out(
    task: &TaskName,
    workspace: &Workspace,
    exclude_bearing: Option<&ProjectName>,
) -> Result<BTreeSet<TaskId>, ResolutionError> {
    let mut result = BTreeSet::new();
    for (project_name, project) in &workspace.projects {
        if exclude_bearing == Some(project_name) {
            continue;
        }
        if project.tasks.contains_key(task) {
            result.insert(TaskId {
                project: project_name.clone(),
                task: task.clone(),
            });
        }
    }
    if result.is_empty() {
        Err(if exclude_bearing.is_some() {
            ResolutionError::SiblingFanOutEmpty { task: task.clone() }
        } else {
            ResolutionError::FanOutEmpty { task: task.clone() }
        })
    } else {
        Ok(result)
    }
}

fn resolve_tag(
    tag: &TagName,
    task: &TaskName,
    workspace: &Workspace,
    exclude_bearing: Option<&ProjectName>,
) -> Result<BTreeSet<TaskId>, ResolutionError> {
    // "No project carries this tag" is reported as its own variant
    // independent of the sibling modifier: the underlying condition
    // is identical and the diagnostic distinguishes it from
    // "matching project(s) exist but none define the task".
    let tag_in_use = workspace
        .projects
        .values()
        .any(|project| project.tags.contains(tag));
    if !tag_in_use {
        return Err(ResolutionError::TagNotInWorkspace { tag: tag.clone() });
    }

    let mut result = BTreeSet::new();
    for (project_name, project) in &workspace.projects {
        if exclude_bearing == Some(project_name) {
            continue;
        }
        if project.tags.contains(tag) && project.tasks.contains_key(task) {
            result.insert(TaskId {
                project: project_name.clone(),
                task: task.clone(),
            });
        }
    }
    if result.is_empty() {
        Err(if exclude_bearing.is_some() {
            ResolutionError::SiblingTagEmpty {
                tag: tag.clone(),
                task: task.clone(),
            }
        } else {
            ResolutionError::TagEmpty {
                tag: tag.clone(),
                task: task.clone(),
            }
        })
    } else {
        Ok(result)
    }
}

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

    use nonempty::NonEmpty;

    use crate::action::TaskAction;
    use crate::env::EnvSettings;
    use crate::name::{ProjectName, TagName, TaskName};
    use crate::path::{CanonicalPath, HazPath, ProjectRoot, WorkspaceRootPath};
    use crate::project::Project;
    use crate::resolution::{ResolutionError, resolve_task_ref};
    use crate::settings::WorkspaceSettings;
    use crate::task::Task;
    use crate::task_id::TaskId;
    use crate::task_ref::TaskRef;
    use crate::workspace::Workspace;

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

    fn tag_name(s: &str) -> TagName {
        TagName::from_str(s).unwrap()
    }

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

    fn project_root_at(s: &str) -> ProjectRoot {
        ProjectRoot::Nested(CanonicalPath::from_absolute(&HazPath::parse(s).unwrap()).unwrap())
    }

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

    fn make_project(name: &str, root: &str, tags: &[&str], tasks: &[&str]) -> Project {
        Project {
            name: project_name(name),
            root: project_root_at(root),
            tags: tags.iter().map(|t| tag_name(t)).collect(),
            tasks: tasks
                .iter()
                .map(|t| (task_name(t), empty_task(t)))
                .collect(),
        }
    }

    fn make_workspace(projects: Vec<Project>) -> Workspace {
        let mut map = BTreeMap::new();
        for project in projects {
            map.insert(project.name.clone(), project);
        }
        Workspace {
            root: WorkspaceRootPath::try_new(PathBuf::from("/abs/ws")).unwrap(),
            projects: map,
            overlays: BTreeMap::new(),
            settings: WorkspaceSettings::default(),
        }
    }

    fn id(project: &str, task: &str) -> TaskId {
        TaskId {
            project: project_name(project),
            task: task_name(task),
        }
    }

    fn parse(s: &str) -> TaskRef {
        TaskRef::parse(s).unwrap()
    }

    // REF-002: same-project reference.

    #[test]
    fn ref_002_same_project_resolves_to_bearing_task() {
        let bearing = make_project("lib_core", "/lib_core", &[], &["build", "test"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let resolved = resolve_task_ref(&parse("~:build"), &bearing, &workspace).unwrap();
        assert_eq!(resolved, BTreeSet::from([id("lib_core", "build")]));
    }

    #[test]
    fn ref_002_same_project_unresolved_when_task_missing() {
        let bearing = make_project("lib_core", "/lib_core", &[], &["build"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let err = resolve_task_ref(&parse("~:test"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::BearingTaskNotFound { ref task }
                if task == &task_name("test")
        ));
    }

    // REF-003: project reference.

    #[test]
    fn ref_003_project_resolves() {
        let bearing = make_project("a", "/a", &[], &["build"]);
        let other = make_project("b", "/b", &[], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), other]);

        let resolved = resolve_task_ref(&parse("b:compile"), &bearing, &workspace).unwrap();
        assert_eq!(resolved, BTreeSet::from([id("b", "compile")]));
    }

    #[test]
    fn ref_003_project_unresolved_project_missing() {
        let bearing = make_project("a", "/a", &[], &["build"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let err = resolve_task_ref(&parse("ghost:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::ProjectNotFound { ref project }
                if project == &project_name("ghost")
        ));
    }

    #[test]
    fn ref_003_project_unresolved_task_missing() {
        let bearing = make_project("a", "/a", &[], &["build"]);
        let other = make_project("b", "/b", &[], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), other]);

        let err = resolve_task_ref(&parse("b:bundle"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::TaskNotInProject { ref project, ref task }
                if project == &project_name("b") && task == &task_name("bundle")
        ));
    }

    // REF-004: fan-out reference.

    #[test]
    fn ref_004_fan_out_resolves_across_all_matching_projects() {
        let bearing = make_project("a", "/a", &[], &["compile"]);
        let b = make_project("b", "/b", &[], &["compile", "build"]);
        let c = make_project("c", "/c", &[], &["compile"]);
        let d = make_project("d", "/d", &[], &["test"]);
        let workspace = make_workspace(vec![bearing.clone(), b, c, d]);

        let resolved = resolve_task_ref(&parse("^:compile"), &bearing, &workspace).unwrap();
        assert_eq!(
            resolved,
            BTreeSet::from([id("a", "compile"), id("b", "compile"), id("c", "compile"),])
        );
    }

    #[test]
    fn ref_004_fan_out_includes_bearing() {
        let bearing = make_project("a", "/a", &[], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let resolved = resolve_task_ref(&parse("^:compile"), &bearing, &workspace).unwrap();
        assert_eq!(resolved, BTreeSet::from([id("a", "compile")]));
    }

    #[test]
    fn ref_004_fan_out_unresolved_when_no_match() {
        let bearing = make_project("a", "/a", &[], &["build"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let err = resolve_task_ref(&parse("^:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::FanOutEmpty { ref task }
                if task == &task_name("compile")
        ));
    }

    // REF-008: sibling-fan-out reference.

    #[test]
    fn ref_008_sibling_fan_out_excludes_bearing() {
        let bearing = make_project("a", "/a", &[], &["compile"]);
        let b = make_project("b", "/b", &[], &["compile"]);
        let c = make_project("c", "/c", &[], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), b, c]);

        let resolved = resolve_task_ref(&parse("^~:compile"), &bearing, &workspace).unwrap();
        assert_eq!(
            resolved,
            BTreeSet::from([id("b", "compile"), id("c", "compile")])
        );
    }

    #[test]
    fn ref_008_sibling_fan_out_unresolved_when_only_bearing_matches() {
        let bearing = make_project("a", "/a", &[], &["compile"]);
        let b = make_project("b", "/b", &[], &["build"]);
        let workspace = make_workspace(vec![bearing.clone(), b]);

        let err = resolve_task_ref(&parse("^~:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::SiblingFanOutEmpty { ref task }
                if task == &task_name("compile")
        ));
    }

    #[test]
    fn ref_008_sibling_fan_out_unresolved_when_no_one_matches() {
        let bearing = make_project("a", "/a", &[], &["build"]);
        let b = make_project("b", "/b", &[], &["test"]);
        let workspace = make_workspace(vec![bearing.clone(), b]);

        let err = resolve_task_ref(&parse("^~:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::SiblingFanOutEmpty { ref task }
                if task == &task_name("compile")
        ));
    }

    // REF-005: tag reference.

    #[test]
    fn ref_005_tag_resolves_across_tagged_projects() {
        let bearing = make_project("a", "/a", &["typescript"], &["compile"]);
        let b = make_project("b", "/b", &["typescript"], &["compile"]);
        let c = make_project("c", "/c", &["rust"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), b, c]);

        let resolved =
            resolve_task_ref(&parse("[typescript]:compile"), &bearing, &workspace).unwrap();
        assert_eq!(
            resolved,
            BTreeSet::from([id("a", "compile"), id("b", "compile")])
        );
    }

    #[test]
    fn ref_005_tag_includes_bearing_when_bearing_carries_tag() {
        let bearing = make_project("a", "/a", &["typescript"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let resolved =
            resolve_task_ref(&parse("[typescript]:compile"), &bearing, &workspace).unwrap();
        assert_eq!(resolved, BTreeSet::from([id("a", "compile")]));
    }

    #[test]
    fn ref_005_tag_unresolved_tag_not_in_workspace() {
        let bearing = make_project("a", "/a", &["rust"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let err = resolve_task_ref(&parse("[ghost]:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::TagNotInWorkspace { ref tag }
                if tag == &tag_name("ghost")
        ));
    }

    #[test]
    fn ref_005_tag_unresolved_when_tagged_projects_lack_task() {
        let bearing = make_project("a", "/a", &["typescript"], &["bundle"]);
        let b = make_project("b", "/b", &["typescript"], &["build"]);
        let workspace = make_workspace(vec![bearing.clone(), b]);

        let err =
            resolve_task_ref(&parse("[typescript]:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::TagEmpty { ref tag, ref task }
                if tag == &tag_name("typescript") && task == &task_name("compile")
        ));
    }

    // REF-008: sibling-tag reference.

    #[test]
    fn ref_008_sibling_tag_excludes_bearing() {
        let bearing = make_project("a", "/a", &["typescript"], &["compile"]);
        let b = make_project("b", "/b", &["typescript"], &["compile"]);
        let c = make_project("c", "/c", &["typescript"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), b, c]);

        let resolved =
            resolve_task_ref(&parse("[typescript]~:compile"), &bearing, &workspace).unwrap();
        assert_eq!(
            resolved,
            BTreeSet::from([id("b", "compile"), id("c", "compile")])
        );
    }

    #[test]
    fn ref_008_sibling_tag_unresolved_when_only_bearing_carries_tag_and_task() {
        let bearing = make_project("a", "/a", &["typescript"], &["compile"]);
        let b = make_project("b", "/b", &["rust"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), b]);

        let err =
            resolve_task_ref(&parse("[typescript]~:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::SiblingTagEmpty { ref tag, ref task }
                if tag == &tag_name("typescript") && task == &task_name("compile")
        ));
    }

    #[test]
    fn ref_008_sibling_tag_unresolved_when_tag_not_in_workspace() {
        // Tag absence is reported by `TagNotInWorkspace` even for
        // the sibling form: the absence of the tag is independent
        // of the sibling modifier.
        let bearing = make_project("a", "/a", &["rust"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone()]);

        let err = resolve_task_ref(&parse("[ghost]~:compile"), &bearing, &workspace).unwrap_err();
        assert!(matches!(
            err,
            ResolutionError::TagNotInWorkspace { ref tag }
                if tag == &tag_name("ghost")
        ));
    }

    // Postcondition: a successful resolution is always non-empty
    // and every member exists in the workspace.

    #[test]
    fn postcondition_successful_resolution_is_non_empty_and_internally_consistent() {
        let bearing = make_project("a", "/a", &["typescript"], &["compile", "test"]);
        let b = make_project("b", "/b", &["typescript"], &["compile"]);
        let c = make_project("c", "/c", &["rust"], &["compile"]);
        let workspace = make_workspace(vec![bearing.clone(), b, c]);

        let references = [
            "~:compile",
            "b:compile",
            "^:compile",
            "^~:compile",
            "[typescript]:compile",
            "[typescript]~:compile",
            "[rust]:compile",
        ];

        for raw in &references {
            let reference = parse(raw);
            let resolved = resolve_task_ref(&reference, &bearing, &workspace)
                .unwrap_or_else(|e| panic!("{raw}: expected Ok, got {e:?}"));
            assert!(
                !resolved.is_empty(),
                "{raw}: resolved set must be non-empty"
            );
            for resolved_id in &resolved {
                let p = workspace
                    .projects
                    .get(&resolved_id.project)
                    .unwrap_or_else(|| panic!("{raw}: project missing"));
                assert!(
                    p.tasks.contains_key(&resolved_id.task),
                    "{raw}: task missing in project",
                );
            }
        }
    }
}