haz-cli 0.2.0

//! Load a haz workspace from a starting directory.
//!
//! Wires the three crates that turn an on-disk workspace into
//! the value objects every downstream subcommand consumes:
//!
//! 1. `haz-discovery` walks upward from the starting directory
//!    to find the workspace root, loads `.haz/workspace.yml`,
//!    expands the project list, loads each project's `haz.yml`,
//!    and loads any `.haz/tasks/*.yml` overlays.
//! 2. The discovery-produced [`DiscoveredWorkspace`] is
//!    converted to a pure-domain
//!    [`haz_domain::workspace::Workspace`] (drops the
//!    filesystem-coupled `F::CanonicalPath` type info; keeps the
//!    validated projects, overlays, and settings).
//! 3. `haz-dag` validates the workspace as a directed task graph
//!    (overlay merging, reference resolution, cycle and output-
//!    uniqueness checks) and produces the
//!    [`haz_dag::graph::TaskGraph`] the scheduler consumes.
//!
//! The single public entry point [`load_workspace`] returns a
//! [`miette::Result`] so the binary can render diagnostics with
//! source-span snippets where the underlying crates provide
//! them.

use std::collections::BTreeMap;
use std::path::Path;

use haz_dag::construction::build_task_graph;
use haz_dag::graph::TaskGraph;
use haz_discovery::discover::{DiscoveredWorkspace, DiscoveryError};
use haz_discovery::discovery::Discovery;
use haz_discovery::overlays::load::{LoadOverlayError, LoadOverlayErrors, overlays_map};
use haz_discovery::projects::load::{LoadError, LoadErrors};
use haz_discovery::workspace::load::WorkspaceLoadError;
use haz_domain::name::ProjectName;
use haz_domain::project::Project;
use haz_domain::workspace::Workspace;
use haz_vfs::{Filesystem, StdFilesystem};
use miette::{IntoDiagnostic, NamedSource, Report, Result, WrapErr};

/// Load a workspace rooted somewhere at or above `starting_dir`.
///
/// Returns the pair `(Workspace, TaskGraph)` on success. The
/// returned `Workspace` is the *effective* workspace per
/// `DAG-001`..`DAG-006`: each project's `tasks` map is the
/// post-overlay-merge effective task set, not the un-merged
/// `haz.yml` declaration. Downstream phases (target resolution,
/// cache-key derivation, `haz why`, `haz query`) MUST consult
/// this view; reading from a project's pre-merge `tasks` map
/// misses every overlay-attached task.
///
/// # Errors
///
/// Returns a [`miette::Report`] on any failure. The underlying
/// failure modes:
///
/// - Discovery: no workspace marker found, symlink cycle, etc.
///   (`DISC-*`).
/// - YAML parse: invalid UTF-8 or YAML grammar in any of the
///   loaded files (`CFG-*`).
/// - Graph validation: cycle (`DAG-014`), output collision
///   (`DAG-015`), unresolved reference (`DAG-011`), overlay
///   collision (`DAG-006`).
pub fn load_workspace(starting_dir: &Path) -> Result<(Workspace, TaskGraph)> {
    load_with(starting_dir, discovery_error_to_report)
}

/// Like [`load_workspace`], but surfaces *every* per-file load
/// diagnostic at once instead of promoting only the first parse
/// error.
///
/// `haz check` uses this variant to satisfy `AUX-010` ("surface
/// every error encountered without short-circuiting at the first
/// one") and `AUX-011` ("the diagnostics MUST NOT be truncated or
/// summarised away"). The other subcommands keep calling
/// [`load_workspace`], whose first-error short-circuit is
/// spec-compliant for them: `AUX-010` binds only `haz check`.
///
/// When discovery fails with two or more project or overlay
/// errors, the returned [`Report`] carries each as a miette
/// `related` diagnostic, so every offending file is rendered with
/// its own source span. A single failure renders identically to
/// [`load_workspace`]. Graph-construction (`DAG-*`) errors already
/// accumulate inside [`build_task_graph`]'s `BuildErrors`, so both
/// loaders surface all of them.
///
/// # Errors
///
/// Returns a [`miette::Report`] on any discovery, parse, or
/// graph-construction failure, as [`load_workspace`].
pub fn load_workspace_accumulating(starting_dir: &Path) -> Result<(Workspace, TaskGraph)> {
    load_with(starting_dir, discovery_error_to_aggregated_report)
}

/// Shared load pipeline for both [`load_workspace`] and
/// [`load_workspace_accumulating`]. The only difference is how a
/// [`DiscoveryError`] is turned into a [`Report`]: short-circuit
/// to the first parse, or aggregate every per-file error.
fn load_with(
    starting_dir: &Path,
    discovery_to_report: impl FnOnce(DiscoveryError, &Path) -> Report,
) -> Result<(Workspace, TaskGraph)> {
    let fs = StdFilesystem::new();
    let discovered = Discovery::new(&fs)
        .discover_workspace(starting_dir)
        .map_err(|e| discovery_to_report(e, starting_dir))?;
    let workspace = assemble_domain_workspace(discovered);
    let (graph, effective_workspace) = build_task_graph(&workspace)
        .into_diagnostic()
        .wrap_err("task-graph construction failed")?;
    Ok((effective_workspace, graph))
}

/// Build a [`miette::Report`] from a [`DiscoveryError`].
///
/// When the chain contains a parse-family error (a
/// [`LoadError::Parse`] for project files, a
/// [`WorkspaceLoadError::Parse`] for `.haz/workspace.yml`, or a
/// [`LoadOverlayError::Parse`] for `.haz/tasks/*.yml`), the
/// inner mapper error (and its rich [`miette::Diagnostic`] info:
/// `code`, `labels`, `help`) is promoted to the Report's primary
/// error, with the offending file attached as a [`NamedSource`]
/// so miette can render the source snippet. Without this
/// promotion, the renderer only surfaces `Display` strings from
/// each chain level and the rich Diagnostic info is silently
/// dropped.
///
/// For non-parse failures (workspace-root walk, filesystem
/// errors, etc.) the function falls back to the chain rendering
/// with a `workspace discovery failed starting from <dir>`
/// wrap.
fn discovery_error_to_report(err: DiscoveryError, starting_dir: &Path) -> Report {
    let wrap = || {
        format!(
            "workspace discovery failed starting from {}",
            starting_dir.display(),
        )
    };
    match err {
        DiscoveryError::LoadProjects { source } => match take_first_parse(source) {
            Ok((path, text, inner)) => rich_parse_report(&path, text, *inner),
            Err(load_err) => Report::new(load_err).wrap_err(wrap()),
        },
        DiscoveryError::LoadImplicitProject { source } => match source {
            LoadError::Parse {
                path,
                source_text,
                source,
                ..
            } => rich_parse_report(&path, source_text, *source),
            other => Report::new(other).wrap_err(wrap()),
        },
        DiscoveryError::LoadWorkspaceConfig { source } => match source {
            WorkspaceLoadError::Parse {
                path,
                source_text,
                source,
            } => rich_parse_report(&path, source_text, *source),
            other => Report::new(other).wrap_err(wrap()),
        },
        DiscoveryError::LoadOverlays { source } => match take_first_overlay_parse(source) {
            Ok((path, text, inner)) => rich_parse_report(&path, text, *inner),
            Err(load_err) => Report::new(load_err).wrap_err(wrap()),
        },
        other => Report::new(other).wrap_err(wrap()),
    }
}

/// Walk a [`LoadErrors`] container looking for the first
/// [`LoadError::Parse`] (suitable for rich rendering). Returns
/// `Ok((path, source_text, inner))` if found; otherwise returns
/// `Err(first_non_parse)` so the caller can fall back to chain
/// rendering on a representative error.
///
/// [`LoadErrors`] is non-empty by construction (the type's
/// own documented invariant); the post-loop `None` branch is
/// therefore statically impossible.
type ParseTriple = (
    std::path::PathBuf,
    String,
    Box<haz_config::mapper::project::ProjectMapError>,
);

fn take_first_parse(errors: LoadErrors) -> Result<ParseTriple, LoadError> {
    let mut other: Option<LoadError> = None;
    for e in errors {
        match e {
            LoadError::Parse {
                path,
                source_text,
                source,
                ..
            } => return Ok((path, source_text, source)),
            non_parse => {
                if other.is_none() {
                    other = Some(non_parse);
                }
            }
        }
    }
    match other {
        Some(e) => Err(e),
        None => unreachable!("LoadErrors is non-empty by construction"),
    }
}

/// Walk a [`LoadOverlayErrors`] container looking for the first
/// [`LoadOverlayError::Parse`] (suitable for rich rendering).
/// Returns `Ok((path, source_text, inner))` if found; otherwise
/// returns `Err(first_non_parse)` so the caller can fall back to
/// chain rendering on a representative error.
///
/// [`LoadOverlayErrors`] is non-empty by construction; the
/// post-loop `None` branch is therefore statically impossible.
type OverlayParseTriple = (
    std::path::PathBuf,
    String,
    Box<haz_config::mapper::overlay::OverlayMapError>,
);

fn take_first_overlay_parse(
    errors: LoadOverlayErrors,
) -> Result<OverlayParseTriple, LoadOverlayError> {
    let mut other: Option<LoadOverlayError> = None;
    for e in errors {
        match e {
            LoadOverlayError::Parse {
                path,
                source_text,
                source,
                ..
            } => return Ok((path, source_text, source)),
            non_parse => {
                if other.is_none() {
                    other = Some(non_parse);
                }
            }
        }
    }
    match other {
        Some(e) => Err(e),
        None => unreachable!("LoadOverlayErrors is non-empty by construction"),
    }
}

/// Build a [`Report`] whose primary error is the inner mapper
/// diagnostic and whose source code is the parsed file. Used
/// for both project (`haz.yml`) and workspace (`workspace.yml`)
/// parse failures; both inner error types implement
/// [`miette::Diagnostic`] with the same shape (`code`, `labels`,
/// `help`).
fn rich_parse_report<D>(path: &Path, source_text: String, inner: D) -> Report
where
    D: miette::Diagnostic + Send + Sync + 'static,
{
    Report::new(inner).with_source_code(NamedSource::new(path.display().to_string(), source_text))
}

/// `haz check` counterpart to [`discovery_error_to_report`]: for
/// the multi-error discovery variants (`LoadProjects`,
/// `LoadOverlays`) it promotes *every* contained error to a
/// [`Report`] and aggregates them; for the single-error variants
/// (and the one-error multi-variant case) it delegates to
/// [`discovery_error_to_report`] so the one-failure rendering is
/// byte-for-byte identical to the short-circuit path.
fn discovery_error_to_aggregated_report(err: DiscoveryError, starting_dir: &Path) -> Report {
    match err {
        DiscoveryError::LoadProjects { source } if source.len() >= 2 => aggregate_reports(
            source
                .into_iter()
                .map(project_load_error_to_report)
                .collect(),
        ),
        DiscoveryError::LoadOverlays { source } if source.errors.len() >= 2 => aggregate_reports(
            source
                .errors
                .into_iter()
                .map(overlay_load_error_to_report)
                .collect(),
        ),
        single => discovery_error_to_report(single, starting_dir),
    }
}

/// Promote one project-load error to a [`Report`]: rich-rendered
/// (inner mapper diagnostic plus source snippet) when it is a
/// [`LoadError::Parse`], plain chain otherwise.
fn project_load_error_to_report(e: LoadError) -> Report {
    match e {
        LoadError::Parse {
            path,
            source_text,
            source,
            ..
        } => rich_parse_report(&path, source_text, *source),
        other => Report::new(other),
    }
}

/// Overlay counterpart of [`project_load_error_to_report`].
fn overlay_load_error_to_report(e: LoadOverlayError) -> Report {
    match e {
        LoadOverlayError::Parse {
            path,
            source_text,
            source,
            ..
        } => rich_parse_report(&path, source_text, *source),
        other => Report::new(other),
    }
}

/// Fold two or more per-file [`Report`]s into one whose miette
/// `related` chain renders every member, each with its own source
/// span. The caller guarantees `reports.len() >= 2`.
fn aggregate_reports(reports: Vec<Report>) -> Report {
    Report::new(AggregatedLoadErrors {
        count: reports.len(),
        reports,
    })
}

/// Carrier for [`aggregate_reports`]. Its `related` chain yields
/// each member diagnostic so the miette renderer surfaces all of
/// them with their own source spans, satisfying `AUX-010` /
/// `AUX-011` for `haz check`.
#[derive(Debug)]
struct AggregatedLoadErrors {
    count: usize,
    reports: Vec<Report>,
}

impl std::fmt::Display for AggregatedLoadErrors {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} configuration error(s) found", self.count)
    }
}

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

impl miette::Diagnostic for AggregatedLoadErrors {
    fn related<'a>(&'a self) -> Option<Box<dyn Iterator<Item = &'a dyn miette::Diagnostic> + 'a>> {
        Some(Box::new(
            self.reports
                .iter()
                .map(AsRef::<dyn miette::Diagnostic>::as_ref),
        ))
    }
}

/// Convert a [`DiscoveredWorkspace`] (which carries
/// filesystem-coupled `F::CanonicalPath` type info) into a
/// pure-domain [`Workspace`].
///
/// The conversion drops the host-canonical project roots
/// (haz-cli does not need them after the cache root has been
/// established) and keeps the validated projects, overlays, and
/// settings.
fn assemble_domain_workspace<F: Filesystem>(dw: DiscoveredWorkspace<F>) -> Workspace {
    let root = dw.workspace.lexical().clone();
    let projects: BTreeMap<ProjectName, Project> = dw
        .projects
        .iter()
        .map(|lp| (lp.project().name.clone(), lp.project().clone()))
        .collect();
    let overlays = overlays_map(&dw.overlays);
    // Implicit-mode workspaces have no `.haz/workspace.yml`, so
    // every workspace-wide setting defaults per `CFG-027`..`CFG-031`.
    let settings = dw
        .workspace_config
        .map(|c| c.config.settings)
        .unwrap_or_default();
    Workspace {
        root,
        projects,
        overlays,
        settings,
    }
}

#[cfg(test)]
mod tests {
    use super::{load_workspace, load_workspace_accumulating};
    use std::fs;
    use std::path::Path;

    fn write_file(path: &Path, contents: &str) {
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent).unwrap();
        }
        fs::write(path, contents).unwrap();
    }

    #[test]
    fn explicit_mode_two_projects_load_cleanly() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        write_file(
            &root.join(".haz/workspace.yml"),
            "projects:\n  - /lib_core\n  - /apps/web\n",
        );
        write_file(
            &root.join("lib_core/haz.yml"),
            "name: lib_core\ntasks:\n  build:\n    command: [\"true\"]\n",
        );
        write_file(
            &root.join("apps/web/haz.yml"),
            "name: web\ntasks:\n  bundle:\n    command: [\"true\"]\n    deps:\n      - lib_core:build\n",
        );

        let (workspace, graph) = load_workspace(root).unwrap();
        assert_eq!(workspace.projects.len(), 2);
        // Two task nodes; one hard edge (lib_core:build -> web:bundle).
        assert_eq!(graph.nodes.len(), 2);
        assert_eq!(graph.edges.len(), 1);
    }

    #[test]
    fn implicit_mode_single_project_loads_cleanly() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        // `.git` directory makes this an implicit-mode workspace
        // per `DISC-001`; `haz.yml` at the root defines the
        // singleton project per `DISC-003`.
        fs::create_dir_all(root.join(".git")).unwrap();
        write_file(
            &root.join("haz.yml"),
            "name: only_proj\ntasks:\n  build:\n    command: [\"true\"]\n",
        );

        let (workspace, graph) = load_workspace(root).unwrap();
        assert_eq!(workspace.projects.len(), 1);
        assert_eq!(graph.nodes.len(), 1);
        assert!(graph.edges.is_empty());
    }

    #[test]
    fn no_workspace_marker_surfaces_discovery_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        // No `.haz/` and no `.git/`; the walk reaches the
        // filesystem root without finding a marker (`DISC-002`).
        let err = load_workspace(tempdir.path()).unwrap_err();
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("discovery failed"),
            "diagnostic should mention discovery failure: {rendered}",
        );
    }

    #[test]
    fn malformed_workspace_yml_surfaces_load_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();
        // `:` at column 0 makes this invalid YAML.
        write_file(&root.join(".haz/workspace.yml"), ":\n");
        let err = load_workspace(root).unwrap_err();
        let rendered = format!("{err:?}");
        // The rich rendering promotes the inner WorkspaceMapError
        // to the Report's primary error, so the wrap string is
        // absent. The header carries the haz::cfg::yaml family
        // code instead.
        assert!(
            rendered.contains("haz::cfg::"),
            "rendered report must include a CFG-family code; got: {rendered}",
        );
    }

    #[test]
    fn malformed_overlay_yml_surfaces_rich_load_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        write_file(&root.join(".haz/workspace.yml"), "projects:\n  - /lib\n");
        write_file(
            &root.join("lib/haz.yml"),
            "name: lib\ntasks:\n  build:\n    command: [\"true\"]\n",
        );
        // A scalar `command:` instead of a sequence: CFG-021.
        write_file(
            &root.join(".haz/tasks/lint.yml"),
            "tasks:\n  lint:\n    command: \"eslint .\"\n",
        );

        let err = load_workspace(root).unwrap_err();
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("haz::cfg::021"),
            "rendered report must promote the inner overlay-mapper code; got: {rendered}",
        );
        assert!(
            rendered.contains("tasks.lint.command"),
            "rendered report must include the resolved overlay key path; got: {rendered}",
        );
        assert!(
            rendered.contains("eslint ."),
            "rendered report must include the offending overlay snippet; got: {rendered}",
        );
    }

    #[test]
    fn unresolved_task_ref_surfaces_graph_build_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        write_file(&root.join(".haz/workspace.yml"), "projects:\n  - /lib\n");
        // `lib:build` deps on a non-existent task; `DAG-011`
        // surfaces the unresolved reference at build_task_graph
        // time, not at discovery time.
        write_file(
            &root.join("lib/haz.yml"),
            "name: lib\ntasks:\n  build:\n    command: [\"true\"]\n    deps:\n      - lib:nonexistent\n",
        );
        let err = load_workspace(root).unwrap_err();
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("task-graph construction failed"),
            "diagnostic should mention graph construction failure: {rendered}",
        );
    }

    /// AUX-010 / AUX-011: the accumulating loader (used by
    /// `haz check`) surfaces every broken project `haz.yml` in one
    /// pass, each with its own source snippet, rather than dropping
    /// all but the first.
    #[test]
    fn accumulating_load_surfaces_every_project_parse_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        write_file(
            &root.join(".haz/workspace.yml"),
            "projects:\n  - /alpha\n  - /beta\n",
        );
        // Both projects: `command` is a scalar, not a sequence, so
        // each `haz.yml` fails to map (CFG-021 family). The distinct
        // scalar values mark which file's snippet was rendered.
        write_file(
            &root.join("alpha/haz.yml"),
            "name: alpha\ntasks:\n  build:\n    command: \"AAA\"\n",
        );
        write_file(
            &root.join("beta/haz.yml"),
            "name: beta\ntasks:\n  build:\n    command: \"BBB\"\n",
        );

        let err = load_workspace_accumulating(root).unwrap_err();
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("AAA") && rendered.contains("BBB"),
            "both files' snippets must appear (no truncation per AUX-011): {rendered}",
        );
        assert!(
            rendered.contains("configuration error(s) found"),
            "the aggregate header must report the count: {rendered}",
        );
        assert!(
            rendered.contains("haz::cfg::"),
            "each member must carry its rich CFG-family diagnostic code: {rendered}",
        );
    }

    /// AUX-010 / AUX-011: the accumulating loader also surfaces every
    /// broken overlay `.haz/tasks/*.yml`, not just the first.
    #[test]
    fn accumulating_load_surfaces_every_overlay_parse_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        write_file(&root.join(".haz/workspace.yml"), "projects:\n  - /lib\n");
        write_file(
            &root.join("lib/haz.yml"),
            "name: lib\ntasks:\n  build:\n    command: [\"true\"]\n",
        );
        // Two overlays, each with a scalar `command` (CFG-021).
        write_file(
            &root.join(".haz/tasks/one.yml"),
            "tasks:\n  one:\n    command: \"AAA\"\n",
        );
        write_file(
            &root.join(".haz/tasks/two.yml"),
            "tasks:\n  two:\n    command: \"BBB\"\n",
        );

        let err = load_workspace_accumulating(root).unwrap_err();
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("AAA") && rendered.contains("BBB"),
            "both overlays' snippets must appear: {rendered}",
        );
        assert!(
            rendered.contains("configuration error(s) found"),
            "the aggregate header must report the count: {rendered}",
        );
    }

    /// The short-circuit loader (`run` / `why` / `cache` / `query`)
    /// keeps promoting only the first parse error. AUX-010 binds only
    /// `haz check`, so this asymmetry is deliberate; the test locks it
    /// so a future change does not silently broaden accumulation.
    #[test]
    fn nonaccumulating_load_still_promotes_only_first_parse_error() {
        let tempdir = tempfile::TempDir::new().unwrap();
        let root = tempdir.path();

        write_file(
            &root.join(".haz/workspace.yml"),
            "projects:\n  - /alpha\n  - /beta\n",
        );
        write_file(
            &root.join("alpha/haz.yml"),
            "name: alpha\ntasks:\n  build:\n    command: \"AAA\"\n",
        );
        write_file(
            &root.join("beta/haz.yml"),
            "name: beta\ntasks:\n  build:\n    command: \"BBB\"\n",
        );

        let err = load_workspace(root).unwrap_err();
        let rendered = format!("{err:?}");
        assert!(
            rendered.contains("AAA") ^ rendered.contains("BBB"),
            "exactly one file's snippet must appear (short-circuit): {rendered}",
        );
        assert!(
            !rendered.contains("configuration error(s) found"),
            "the short-circuit path must not build an aggregate: {rendered}",
        );
    }
}