nornir 0.4.33

//! Loader for the consumer's `nornir.toml`.
//!
//! Discovery rule (used by the CLI when no explicit path is given):
//! walk up from `cwd` looking for `workspace_holger/release/nornir.toml`.
//! The discovered file's *grandparent of the grandparent* is the
//! **workspace root** — the dir containing `workspace_holger/`,
//! `holger/`, `znippy/`, etc. All relative paths inside `nornir.toml`
//! (including `[guard].forbidden`) are interpreted against that root.

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use anyhow::{anyhow, Context, Result};
use serde::{Deserialize, Serialize};

// ── The nornir data root: derived from the running user's home ──────────────
//
// ONE rule for everyone, NO path env-vars. The nornir data root is
// `<home>/.nornir`, where `<home>` is the RUNNING USER's home directory:
//   - a login user `rickard` (HOME=/home/rickard) → `/home/rickard/.nornir`
//   - the server (system user `nornir`, HOME=/home/nornir) → `/home/nornir/.nornir`
// Containers get the right path by setting the user's `$HOME` (the standard
// way) — never a nornir-specific env var. Home is resolved with the `home`
// crate, which reads `$HOME` then falls back to getpwuid, so it's correct for
// the systemd service user AND for `sudo -H -u nornir`.

/// Pure, testable: the nornir data root for a given home directory.
/// `nornir_home_from(Path::new("/home/alice")) == "/home/alice/.nornir"`.
pub fn nornir_home_from(home: &Path) -> PathBuf {
    home.join(".nornir")
}

/// The nornir data root for the **running user** (`<home>/.nornir`).
/// Panics only if the OS can resolve no home at all (no `$HOME`, no passwd
/// entry) — a misconfigured environment we can't sensibly proceed in.
pub fn nornir_home() -> PathBuf {
    nornir_home_from(&home::home_dir().expect("resolve running user's HOME"))
}

/// The workspace **registry root** — `<home>/.nornir/workspaces`. Holds
/// `registry.redb` and the per-workspace `<name>/{git,builds}/` trees.
pub fn registry_root() -> PathBuf {
    nornir_home().join("workspaces")
}

/// The default embedded/fat **warehouse** — `<home>/.nornir/warehouse`.
pub fn warehouse_default_root() -> PathBuf {
    nornir_home().join("warehouse")
}

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct Nornir {
    #[serde(default)]
    pub guard: Guard,
    #[serde(default)]
    pub storage: Storage,
    #[serde(default)]
    pub repo: BTreeMap<String, Repo>,
}

// NB (config seam): `nornir.toml` owns release *recipes* (gates/bench/
// publish_order) keyed by member name. It does **not** own where source comes
// from or whether a workspace is monitored:
//   - member *source* (path | git + branch/ref) lives in the workspace
//     descriptor `nornir-workspace.toml` (`crate::workspace::descriptor`);
//   - *monitored-ness* + poll interval + per-member sync state live in the
//     server's registry record (`crate::registry`);
//   - the server *root* (`<root>/<ws>/{git,builds}`) is server-global —
//     the home-derived `registry_root()` (`<home>/.nornir/workspaces`).
// `[repo].remote` below is kept only as doc-link metadata (README/CHANGELOG
// "repository" links); for monitored source the descriptor's `git` is
// authoritative.

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct Guard {
    #[serde(default)]
    pub forbidden: Vec<String>,
}

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct Storage {
    /// `"local"` (default) or `"remote"`. Empty string also = local.
    #[serde(default)]
    pub kind: String,
    /// Workspace-root-relative dir holding `warehouse/` and `cache/`.
    /// Defaults to `<home>/.nornir/workspaces/<name>/builds` (see `warehouse_root`)
    /// when empty.
    #[serde(default)]
    pub local_path: String,
    /// Flight endpoint URL when `kind = "remote"`.
    #[serde(default)]
    pub remote_url: String,
}

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct Repo {
    /// On-disk directory of this repo's checkout, **relative to the workspace
    /// root** (or absolute). Overrides the default `<workspace_root>/<name>`
    /// convention — needed when the `[repo.<name>]` key and the directory
    /// differ, e.g. a temp config that renders nornir's own book from a
    /// `nornir-orch` worktree (`[repo.nornir] path = "nornir-orch"`). Empty =
    /// fall back to the by-name convention (case-insensitive). Honored by
    /// [`Nornir::repo_dir_for`].
    #[serde(default)] pub path: String,
    /// Doc-link metadata only (README/CHANGELOG "repository" links). NOT the
    /// source-of-truth for monitored fetch — that's the descriptor's `git`.
    #[serde(default)] pub remote: String,
    #[serde(default)] pub history: String,
    #[serde(default)] pub readme: String,
    #[serde(default)] pub publish_order: Vec<Vec<String>>,
    #[serde(default)] pub gates: Gates,
    #[serde(default)] pub bench: BenchSpec,
}

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct Gates {
    #[serde(default)] pub no_path_patches: bool,
    #[serde(default)] pub nexus_floor: bool,
    #[serde(default)] pub no_regression: bool,
    #[serde(default)] pub max_regression_pct: f64,
    #[serde(default)] pub integration_roundtrip: Vec<String>,
    #[serde(default)] pub docs_fresh: bool,
    /// Fail the release if any `[guard].forbidden` path drifted from the
    /// recorded manifest (perm re-grant or out-of-band content change).
    #[serde(default)] pub guard_intact: bool,
}

/// Per-repo bench contract.
///
/// **Corpus shape (decided 2026-05-31):**
///
/// 1. A *corpus* is identified by a flat string name (e.g. `text_500mb`,
///    `rust_crate_mt32`) listed in [`Self::required_results`]. The list
///    is **the schema** — every release-time `BenchRun` must produce at
///    least one [`crate::bench::BenchResult`] with each of these names.
///    Missing names → release gate fails *before* regression checks run.
/// 2. Result name format: `<corpus>[_<variant>]`, snake_case, ASCII.
///    Variants are free-form and meaningful only to the repo (e.g.
///    `_st` / `_mt32` for single- vs 32-thread variants in holger).
/// 3. Per-result `metrics` is a free-form JSON map — but cross-repo
///    rollups (Time-Travel viz, regression gate) only auto-discover
///    numeric metrics. Recommended (not enforced) suffix convention:
///      - throughput  → `*_mbs` (MiB/s)
///      - latency     → `*_ms`  or `*_us`
///      - ratios      → `*_pct`
///      - counts      → plain noun (`files`, `chunks`)
/// 4. Stability requirement: once a name lands in `required_results`,
///    it MUST keep producing comparable numbers across releases. Renames
///    are schema breaks and require a workspace.toml update.
///
/// **Environmental requirements:**
///
/// - [`Self::network_required`] — set `true` if the corpus pulls real
///   artifacts at test-time (e.g. ljar's maven_artifacts suite hits
///   Maven Central). When true the upcoming funnel `network_probe`
///   node must pass before `cargo_test` / `cargo_bench` run for this
///   repo; in offline mode the pipeline records `status=skipped_offline`
///   for these stages rather than failing them.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct BenchSpec {
    #[serde(default)]
    pub required_results: Vec<String>,
    #[serde(default)]
    pub network_required: bool,
}

impl BenchSpec {
    /// Verify a `BenchRun` produces every required result name. Returns
    /// the sorted list of missing names (empty == ok).
    pub fn missing_in<'a>(&'a self, run: &crate::bench::BenchRun) -> Vec<&'a str> {
        let produced: std::collections::HashSet<&str> =
            run.results.iter().map(|r| r.name.as_str()).collect();
        let mut missing: Vec<&str> = self
            .required_results
            .iter()
            .map(|s| s.as_str())
            .filter(|n| !produced.contains(n))
            .collect();
        missing.sort();
        missing
    }

    /// Fail with a clear error if any required result is missing.
    pub fn validate(&self, run: &crate::bench::BenchRun) -> anyhow::Result<()> {
        let missing = self.missing_in(run);
        if !missing.is_empty() {
            anyhow::bail!(
                "bench corpus is missing {} required result(s): [{}]",
                missing.len(),
                missing.join(", ")
            );
        }
        Ok(())
    }
}

/// A loaded config plus the paths it was discovered through.
pub struct Loaded {
    pub nornir: Nornir,
    pub config_path: PathBuf,
    pub workspace_root: PathBuf,
}

impl Loaded {
    /// Canonical Iceberg warehouse directory for this workspace.
    ///
    /// Resolution order:
    ///   1. an **absolute** `[storage].local_path` — honored verbatim (a config
    ///      may still pin an explicit fast path).
    ///   2. a **relative** `[storage].local_path` — joined under `workspace_root`
    ///      (legacy; only fast if the workspace itself is on fast disk).
    ///   3. empty — the home-derived default `<home>/.nornir/warehouse`
    ///      ([`warehouse_default_root`]).
    /// In all cases the final segment is `warehouse/`.
    /// The canonical workspace name — the `<name>` from the `workspace_<name>`
    /// component of the config path (the same derivation the viz picker uses),
    /// e.g. `…/workspace_matrix/release/nornir.toml` → `matrix`. Falls back to
    /// `default` when no `workspace_<name>` is present (a bare/ad-hoc config).
    pub fn workspace_name(&self) -> String {
        self.config_path
            .components()
            .filter_map(|c| c.as_os_str().to_str())
            .find_map(|s| s.strip_prefix("workspace_").map(str::to_string))
            .filter(|s| !s.is_empty())
            .unwrap_or_else(|| "default".to_string())
    }

    /// Per-workspace Iceberg warehouse root. PER-WORKSPACE layout (decided
    /// 2026-06-12): the default is `<home>/.nornir/workspaces/<name>/builds` —
    /// **byte-for-byte the path the server opens** (`nornir-server` serves, and
    /// `monitor::republish` builds, `<root>/<name>/builds`; `catalog.redb` lives
    /// right there, with Iceberg's own `warehouse/` data dir nested inside). So
    /// fat and server read the *same* warehouse. An explicit `[storage].local_path`
    /// still overrides (absolute path honored verbatim; relative joined under
    /// `workspace_root`).
    pub fn warehouse_root(&self) -> PathBuf {
        let storage = &self.nornir.storage;
        if storage.local_path.is_empty() {
            registry_root().join(self.workspace_name()).join("builds")
        } else {
            // `join` with an absolute `local_path` discards `workspace_root`, so
            // an absolute fast path (e.g. `/home/rickard/.nornir`) wins as intended.
            self.workspace_root.join(&storage.local_path).join("warehouse")
        }
    }

    /// Per-workspace funnel store — `<home>/.nornir/workspaces/<name>/funnel`
    /// (a workspace's planning DAG belongs to the workspace, not a global dir).
    pub fn funnel_root(&self) -> PathBuf {
        registry_root().join(self.workspace_name()).join("funnel")
    }
}

impl Nornir {
    pub fn load(path: &Path) -> Result<Self> {
        let text = std::fs::read_to_string(path)
            .with_context(|| format!("read {}", path.display()))?;
        toml::from_str(&text).with_context(|| format!("parse {}", path.display()))
    }

    /// Resolve the repo's filesystem path inside `workspace_root`
    /// (convention: `<workspace_root>/<repo_name>/`).
    pub fn repo_dir(workspace_root: &Path, name: &str) -> PathBuf {
        workspace_root.join(name)
    }

    /// Resolve `name`'s on-disk checkout, honoring an explicit
    /// `[repo.<name>].path` override before falling back to the by-name
    /// convention ([`repo_dir_resolved`]).
    ///
    /// The override is the only way a config can point a repo at a directory
    /// whose name differs from the `[repo.<name>]` key — e.g. rendering
    /// nornir's *own* book from a sibling `nornir-orch` worktree via
    /// `[repo.nornir] path = "nornir-orch"`. Without it, `docs book nornir`
    /// silently resolved to the by-name `<workspace_root>/nornir` checkout (or,
    /// when that was absent, fell through to a bogus path) instead of the
    /// configured one. An **absolute** override is honored verbatim; a
    /// **relative** one is joined under `workspace_root`. Empty (the default)
    /// preserves the prior behavior exactly, so other repos are unaffected.
    pub fn repo_dir_for(&self, workspace_root: &Path, name: &str) -> PathBuf {
        if let Some(repo) = self.repo.get(name) {
            if !repo.path.trim().is_empty() {
                let p = Path::new(repo.path.trim());
                return if p.is_absolute() {
                    p.to_path_buf()
                } else {
                    workspace_root.join(p)
                };
            }
        }
        repo_dir_resolved(workspace_root, name)
    }
}

/// Resolve a repo's on-disk directory inside `workspace_root`, tolerating a
/// case mismatch between the configured `[repo.<name>]` key and the actual
/// directory name (e.g. `[repo.njord]` ↔ a `Njord/` checkout). Tries the exact
/// `<workspace_root>/<name>` first; if that doesn't exist, falls back to a
/// case-insensitive match among the workspace's sub-directories. Returns the
/// exact join when nothing matches, so callers still get a sensible path to
/// report in errors.
pub fn repo_dir_resolved(workspace_root: &Path, name: &str) -> PathBuf {
    let exact = Nornir::repo_dir(workspace_root, name);
    if exact.exists() {
        return exact;
    }
    // An empty `workspace_root` means "relative to the current directory";
    // `read_dir("")` errors, which would silently skip the case-insensitive
    // fallback — scan "." instead so e.g. `[repo.njord]` still resolves to a
    // `Njord/` checkout in the cwd.
    let scan_root: &Path = if workspace_root.as_os_str().is_empty() {
        Path::new(".")
    } else {
        workspace_root
    };
    if let Ok(entries) = std::fs::read_dir(scan_root) {
        for entry in entries.flatten() {
            if entry.file_name().to_string_lossy().eq_ignore_ascii_case(name)
                && entry.path().is_dir()
            {
                // When workspace_root is empty the caller expects a bare
                // relative name (not "./Njord"); otherwise the full join.
                return if workspace_root.as_os_str().is_empty() {
                    PathBuf::from(entry.file_name())
                } else {
                    entry.path()
                };
            }
        }
    }
    exact
}

/// Discover `nornir.toml` by walking up from `start` (cargo-style): the first
/// ancestor containing a `nornir.toml` wins, and the workspace root is that
/// directory. Fallback for the dev mono-repo: any `workspace_*/release/nornir.toml`
/// under an ancestor (any `workspace_*`, NOT a hardcoded personal name) — there
/// the workspace root is the dir holding `workspace_*`.
pub fn discover(start: &Path) -> Result<Loaded> {
    let mut cur = start
        .canonicalize()
        .unwrap_or_else(|_| start.to_path_buf());
    loop {
        // Standard: a `nornir.toml` right here.
        let plain = cur.join("nornir.toml");
        if plain.is_file() {
            return Ok(Loaded { nornir: Nornir::load(&plain)?, config_path: plain, workspace_root: cur });
        }
        // Mono-repo fallback: the first `workspace_*/release/nornir.toml` here.
        if let Ok(rd) = std::fs::read_dir(&cur) {
            let mut hits: Vec<PathBuf> = rd
                .flatten()
                .map(|e| e.path())
                .filter(|p| {
                    p.file_name()
                        .and_then(|n| n.to_str())
                        .is_some_and(|n| n.starts_with("workspace_"))
                        && p.join("release/nornir.toml").is_file()
                })
                .map(|p| p.join("release/nornir.toml"))
                .collect();
            hits.sort();
            if let Some(candidate) = hits.into_iter().next() {
                let nornir = Nornir::load(&candidate)?;
                return Ok(Loaded { nornir, config_path: candidate, workspace_root: cur });
            }
        }
        if !cur.pop() {
            return Err(anyhow!(
                "no nornir.toml found walking up from {}. Put a nornir.toml at your project \
                 root, pass --config / set NORNIR_CONFIG, or (MCP/CLI client mode) set \
                 NORNIR_SERVER + NORNIR_SERVER_TOKEN to relay to a remote nornir-server with \
                 no local config.",
                start.display()
            ));
        }
    }
}

/// Load from an explicit config path; workspace root = the two-up
/// ancestor (so `…/workspace_holger/release/nornir.toml` → `…/`).
pub fn load_explicit(config_path: &Path) -> Result<Loaded> {
    let nornir = Nornir::load(config_path)?;
    let workspace_root = config_path
        .parent()
        .and_then(Path::parent)
        .and_then(Path::parent)
        .ok_or_else(|| anyhow!("config path lacks grandparent dirs: {}", config_path.display()))?
        .to_path_buf();
    Ok(Loaded {
        nornir,
        config_path: config_path.to_path_buf(),
        workspace_root,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::{Path, PathBuf};
    use std::sync::Mutex;

    /// `$HOME` is process-global; serialize the HOME-mutating tests so they
    /// can't observe each other's value under the parallel test runner.
    static HOME_LOCK: Mutex<()> = Mutex::new(());

    /// The pure home→root rule: `<home>/.nornir`, identical for ANY user.
    #[test]
    fn home_root_is_home_dot_nornir_for_any_user() {
        // A login user.
        assert_eq!(
            nornir_home_from(Path::new("/home/alice")),
            PathBuf::from("/home/alice/.nornir"),
        );
        // The server's system user — same code, same shape.
        assert_eq!(
            nornir_home_from(Path::new("/home/nornir")),
            PathBuf::from("/home/nornir/.nornir"),
        );
    }

    /// The composed roots (registry + default warehouse) hang off the home root
    /// exactly as documented — assert the full path, not just "didn't panic".
    #[test]
    fn registry_and_warehouse_compose_under_home() {
        let _g = HOME_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        // Drive the running-user resolver through a known HOME so the assertion
        // is deterministic on any host.
        std::env::set_var("HOME", "/home/bob");
        assert_eq!(nornir_home(), PathBuf::from("/home/bob/.nornir"));
        assert_eq!(registry_root(), PathBuf::from("/home/bob/.nornir/workspaces"));
        assert_eq!(
            warehouse_default_root(),
            PathBuf::from("/home/bob/.nornir/warehouse"),
        );
    }

    /// An empty `[storage].local_path` falls back to the home-derived warehouse
    /// (NOT the old `workspace_holger/.nornir/warehouse`), while an absolute
    /// `local_path` is still honored verbatim.
    #[test]
    fn warehouse_root_default_is_home_derived() {
        let _g = HOME_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        std::env::set_var("HOME", "/home/carol");
        let empty = Loaded {
            nornir: Nornir::default(),
            config_path: PathBuf::from("/ws/workspace_holger/release/nornir.toml"),
            workspace_root: PathBuf::from("/ws"),
        };
        // PER-WORKSPACE default = <home>/.nornir/workspaces/<name>/builds (the exact
        // path the server opens), where <name> is the `workspace_<name>` component.
        assert_eq!(
            empty.warehouse_root(),
            PathBuf::from("/home/carol/.nornir/workspaces/holger/builds"),
        );
        assert_eq!(empty.workspace_name(), "holger");
        assert_eq!(
            empty.funnel_root(),
            PathBuf::from("/home/carol/.nornir/workspaces/holger/funnel"),
        );

        // Absolute pin still wins, joined with `warehouse/`.
        let mut pinned = Loaded {
            nornir: Nornir::default(),
            config_path: PathBuf::from("/ws/workspace_holger/release/nornir.toml"),
            workspace_root: PathBuf::from("/ws"),
        };
        pinned.nornir.storage.local_path = "/fast/disk".into();
        assert_eq!(
            pinned.warehouse_root(),
            PathBuf::from("/fast/disk/warehouse"),
        );
    }

    /// `[repo.<name>].path` redirects a repo to a directory whose name differs
    /// from the key — the seam that lets `docs book nornir` render nornir's own
    /// book from a configured `nornir-orch` worktree. A relative override joins
    /// the workspace root; an absolute override is honored verbatim; an empty
    /// override falls back to the by-name convention (so other repos are
    /// untouched). Inject distinct paths, assert the exact resolved dir.
    #[test]
    fn repo_dir_for_honors_path_override_relative_and_absolute() {
        let ws = Path::new("/ws");
        let mut nornir = Nornir::default();
        // Self-repo override: the `nornir` key points at a `nornir-orch` dir.
        nornir.repo.insert(
            "nornir".into(),
            Repo { path: "nornir-orch".into(), ..Default::default() },
        );
        // Absolute override wins over the join.
        nornir.repo.insert(
            "skade".into(),
            Repo { path: "/abs/skade-checkout".into(), ..Default::default() },
        );
        // No override → by-name convention.
        nornir.repo.insert("znippy".into(), Repo::default());

        assert_eq!(
            nornir.repo_dir_for(ws, "nornir"),
            PathBuf::from("/ws/nornir-orch"),
            "relative override must join the workspace root, not the by-name dir",
        );
        assert_eq!(
            nornir.repo_dir_for(ws, "skade"),
            PathBuf::from("/abs/skade-checkout"),
            "absolute override must be honored verbatim",
        );
        assert_eq!(
            nornir.repo_dir_for(ws, "znippy"),
            PathBuf::from("/ws/znippy"),
            "empty override must fall back to the by-name convention",
        );
        // A repo absent from the table still resolves by-name (no panic).
        assert_eq!(
            nornir.repo_dir_for(ws, "ghost"),
            PathBuf::from("/ws/ghost"),
        );
    }
}