mmz 0.7.0

//! Per-rule cache records under a gitignored cache directory (`.mmz/cache` by
//! default; see `cache_dir` in the manifest).
//!
//! Each command rule owns one record, keyed by the rule name (the cache
//! identity). A record is trusted only when its format, algorithm, command,
//! status, and input digest all match — anything else is a miss, so the command
//! re-runs. Records are derived, throwaway state and belong in `.gitignore`.

use std::collections::{BTreeMap, BTreeSet};
use std::fs;
use std::io::ErrorKind;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::clock::Clock;
use crate::error::{Error, Result};
use crate::hashing::ALGORITHM;

/// On-disk record format version. A mismatch invalidates the record.
const FORMAT: u32 = 1;

/// Maximum length of a slug's readable stem, before the disambiguating hash.
/// Caps the filename so a very long rule name cannot overrun the OS limit.
const SLUG_MAX: usize = 64;

/// Outcome of the last run, recorded so a failed run never counts as fresh.
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
enum Status {
    Ok,
    Failed,
}

/// A single command rule's memoization state.
///
/// `outputs` is the artifact list the rule declared when the run was recorded,
/// so `mmz --status` can report a missing artifact against the run that
/// promised it. `probes` is the same idea for command-driven inputs: the digest
/// each named probe produced at that moment, so a later stale verdict can name
/// the probe that moved instead of sending a reader to diff files that did not.
/// Both default to empty, which is exactly what a record written before the
/// field existed (or by a rule declaring neither) means, so neither needs a
/// [`FORMAT`] bump: freshness is decided against the manifest's current
/// declaration, never against the stored lists.
#[derive(Debug, Serialize, Deserialize)]
struct Record {
    format: u32,
    algorithm: String,
    command: String,
    input_digest: String,
    status: Status,
    ran_at: u64,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    outputs: Vec<String>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    probes: BTreeMap<String, String>,
}

/// What a completed run records: the digest it was measured against, whether it
/// succeeded, the artifacts its rule declared, and the probe digests that fed
/// the input digest.
///
/// A struct rather than five positional arguments so a new recorded fact costs
/// a field, not another parameter at every call site.
#[derive(Default)]
pub struct Outcome<'a> {
    /// The input digest the run was measured against.
    pub digest: &'a str,
    /// Whether the run exited 0.
    pub ok: bool,
    /// Artifact paths the rule declared when the run was recorded.
    pub outputs: &'a [PathBuf],
    /// Digest of each probe the rule names, by probe name.
    pub probes: BTreeMap<String, String>,
}

/// A trusted view of a stored record, for inspection by `mmz --status`.
pub struct Cached {
    /// Whether the recorded run succeeded.
    pub ok: bool,
    /// The recorded input digest.
    pub digest: String,
    /// Unix seconds when the run was recorded.
    pub ran_at: u64,
    /// The outputs the rule declared when this run was recorded, as written.
    /// Empty for a rule that declares none.
    pub outputs: Vec<String>,
    /// The digest each named probe produced when this run was recorded. Empty
    /// for a rule that names none.
    pub probes: BTreeMap<String, String>,
    /// Every stored record field as a string, keyed by field name, for cache-hit
    /// notice macros (`{cache:<field>}`). Driven off serialization, so a new
    /// record field becomes a macro automatically.
    pub fields: BTreeMap<String, String>,
}

/// Reads the record for `command` from `dir`, returning a [`Cached`] view only
/// when it is present, parseable, and compatible (format, algorithm, and
/// command match).
///
/// Any read, parse, or compatibility mismatch returns `None` (a miss), so the
/// worst case is an unnecessary re-run, never a wrongful skip.
#[must_use]
pub fn read(dir: &Path, command: &str) -> Option<Cached> {
    let text = fs::read_to_string(record_path(dir, command)).ok()?;
    let record = serde_yaml_ng::from_str::<Record>(&text).ok()?;
    if record.format != FORMAT || record.algorithm != ALGORITHM || record.command != command {
        return None;
    }
    let fields = record_fields(&record);
    Some(Cached {
        ok: record.status == Status::Ok,
        digest: record.input_digest,
        ran_at: record.ran_at,
        outputs: record.outputs,
        probes: record.probes,
        fields,
    })
}

/// Flattens a record into a `field -> string` map for notice macro expansion.
/// Built from serialization, so every record field is exposed as a
/// `{cache:<field>}` macro without per-field wiring; non-scalar shapes are
/// skipped.
fn record_fields(record: &Record) -> BTreeMap<String, String> {
    use serde_yaml_ng::Value;
    let mut fields = BTreeMap::new();
    let Ok(Value::Mapping(map)) = serde_yaml_ng::to_value(record) else {
        return fields;
    };
    for (key, value) in map {
        let Some(name) = key.as_str() else { continue };
        let text = match value {
            Value::String(text) => text,
            Value::Bool(flag) => flag.to_string(),
            Value::Number(number) => number.to_string(),
            Value::Null => String::new(),
            _ => continue,
        };
        fields.insert(name.to_owned(), text);
    }
    fields
}

/// True when a trusted, successful record for `command` in `dir` matches `digest`.
#[must_use]
pub fn is_fresh(dir: &Path, command: &str, digest: &str) -> bool {
    read(dir, command).is_some_and(|cached| cached.ok && cached.digest == digest)
}

/// Records the outcome of a run under `dir`, along with the artifact paths and
/// probe digests the rule carried at that moment. Best-effort: a write failure
/// is logged, never propagated, because the command has already run and its exit
/// code stands.
///
/// `clock` stamps `ran_at`. It is passed in rather than read here so the whole
/// process agrees on one instant (see [`crate::clock`]) — which is also what
/// makes a captured record reproducible under `MMZ_NOW`.
pub fn write(dir: &Path, command: &str, clock: Clock, outcome: &Outcome) {
    let record = Record {
        format: FORMAT,
        algorithm: ALGORITHM.to_owned(),
        command: command.to_owned(),
        input_digest: outcome.digest.to_owned(),
        status: if outcome.ok {
            Status::Ok
        } else {
            Status::Failed
        },
        ran_at: clock.now_secs(),
        outputs: outcome
            .outputs
            .iter()
            .map(|output| output.display().to_string())
            .collect(),
        probes: outcome.probes.clone(),
    };
    if let Err(err) = try_write(dir, command, &record) {
        log::warn!("mmz: could not write cache for `{command}`: {err}");
    }
}

/// Removes records in `dir` whose stored command is not in `live`, returning the
/// pruned command names sorted. Leftover `.tmp` files from interrupted writes
/// are swept too. A record that cannot be read or parsed is left untouched, so
/// only confidently orphaned records are deleted. A missing directory is empty.
///
/// # Errors
///
/// Returns [`Error::Io`] if the directory cannot be listed or a record cannot
/// be deleted.
pub fn prune(dir: &Path, live: &BTreeSet<String>) -> Result<Vec<String>> {
    let entries = match fs::read_dir(dir) {
        Ok(entries) => entries,
        Err(err) if err.kind() == ErrorKind::NotFound => return Ok(Vec::new()),
        Err(err) => return Err(err.into()),
    };
    let mut pruned = Vec::new();
    for entry in entries {
        let path = entry?.path();
        match path.extension().and_then(|ext| ext.to_str()) {
            Some("tmp") => {
                let _ = fs::remove_file(&path);
            }
            Some("yaml") => {
                if let Some(command) = record_command(&path) {
                    if !live.contains(command.as_str()) {
                        fs::remove_file(&path)?;
                        pruned.push(command);
                    }
                }
            }
            _ => {}
        }
    }
    pruned.sort();
    Ok(pruned)
}

/// Reads just the stored command name from a record file, or `None` when the
/// file is unreadable or not a parseable record.
fn record_command(path: &Path) -> Option<String> {
    let text = fs::read_to_string(path).ok()?;
    Some(serde_yaml_ng::from_str::<Record>(&text).ok()?.command)
}

/// Writes the record atomically: serialize to a per-process temp file in the
/// cache directory, then rename it over the final path. A reader therefore sees
/// either the old record or the complete new one, never a half-written file —
/// so a crash mid-write or a concurrent writer can never produce a truncated
/// record that would parse wrong. A failed rename cleans up its temp file.
fn try_write(dir: &Path, command: &str, record: &Record) -> Result<()> {
    fs::create_dir_all(dir)?;
    let text = serde_yaml_ng::to_string(record).map_err(|err| Error::Serialize(Box::new(err)))?;
    let tmp = dir.join(format!("{}.{}.tmp", slug(command), std::process::id()));
    fs::write(&tmp, text)?;
    if let Err(err) = fs::rename(&tmp, record_path(dir, command)) {
        let _ = fs::remove_file(&tmp);
        return Err(err.into());
    }
    Ok(())
}

fn record_path(dir: &Path, command: &str) -> PathBuf {
    dir.join(format!("{}.yaml", slug(command)))
}

/// Builds a readable, collision-resistant filename stem from a command name: a
/// lowercased ascii-alphanumeric slug (capped, never empty) plus a short hash of
/// the full name. The hash disambiguates names that share a slug, so a slug
/// collision is at worst a harmless re-run, never a wrongful skip.
fn slug(command: &str) -> String {
    let mut readable = String::new();
    let mut last_dash = false;
    for ch in command.chars() {
        if ch.is_ascii_alphanumeric() {
            readable.push(ch.to_ascii_lowercase());
            last_dash = false;
        } else if !last_dash {
            readable.push('-');
            last_dash = true;
        }
    }
    let capped: String = readable.trim_matches('-').chars().take(SLUG_MAX).collect();
    let stem = match capped.trim_matches('-') {
        "" => "cmd",
        trimmed => trimmed,
    };
    let digest = blake3::hash(command.as_bytes()).to_hex();
    let short = digest.as_str().get(..16).unwrap_or(digest.as_str());
    format!("{stem}-{short}")
}

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

    use super::{Outcome, is_fresh, prune, read, slug, write as write_record};
    use crate::clock::Clock;

    /// Every record below is stamped from a pinned clock, so `ran_at` is a fact
    /// the test states rather than whatever second the suite happened to run in.
    const RAN_AT: u64 = 1_700_000_000;

    /// Records a run declaring no outputs and naming no probes — every case
    /// here but the two that check those lists.
    fn write(dir: &Path, command: &str, digest: &str, ok: bool) {
        write_record(
            dir,
            command,
            Clock::pinned(RAN_AT),
            &Outcome {
                digest,
                ok,
                ..Outcome::default()
            },
        );
    }

    #[test]
    fn fresh_only_for_matching_successful_record() {
        let dir = tempfile::tempdir().expect("tempdir");
        let base = dir.path();
        assert!(!is_fresh(base, "sh", "digest-a"), "no record yet");

        write(base, "sh", "digest-a", true);
        assert!(
            is_fresh(base, "sh", "digest-a"),
            "matching ok record is fresh"
        );
        assert!(!is_fresh(base, "sh", "digest-b"), "different digest misses");

        write(base, "sh", "digest-a", false);
        assert!(
            !is_fresh(base, "sh", "digest-a"),
            "failed record is never fresh"
        );
    }

    #[test]
    fn read_exposes_record_fields_for_macros() {
        let dir = tempfile::tempdir().expect("tempdir");
        write(dir.path(), "cargo test", "d1", true);
        let cached = read(dir.path(), "cargo test").expect("record");
        assert_eq!(
            cached.fields.get("command").map(String::as_str),
            Some("cargo test"),
            "string field exposed"
        );
        assert_eq!(
            cached.fields.get("status").map(String::as_str),
            Some("ok"),
            "enum field exposed in its serialized spelling"
        );
        assert_eq!(
            cached.fields.get("input_digest").map(String::as_str),
            Some("d1")
        );
        assert!(
            cached.fields.contains_key("ran_at"),
            "numeric field exposed for macros"
        );
    }

    #[test]
    fn declared_outputs_are_stored_with_the_record() {
        let dir = tempfile::tempdir().expect("tempdir");
        write_record(
            dir.path(),
            "just cover",
            Clock::pinned(RAN_AT),
            &Outcome {
                digest: "d1",
                ok: true,
                outputs: &[PathBuf::from("target/coverage/lcov.info")],
                ..Outcome::default()
            },
        );
        let cached = read(dir.path(), "just cover").expect("record");
        assert_eq!(
            cached.outputs,
            vec!["target/coverage/lcov.info".to_owned()],
            "the record remembers what the run promised to produce"
        );

        write(dir.path(), "cargo test", "d2", true);
        let bare = read(dir.path(), "cargo test").expect("record");
        assert!(
            bare.outputs.is_empty(),
            "a rule declaring no outputs records none"
        );
    }

    #[test]
    fn probe_digests_are_stored_with_the_record() {
        let dir = tempfile::tempdir().expect("tempdir");
        let probes: BTreeMap<String, String> = [("fmt-recipe".to_owned(), "abc".to_owned())]
            .into_iter()
            .collect();
        write_record(
            dir.path(),
            "just fmt-check",
            Clock::pinned(RAN_AT),
            &Outcome {
                digest: "d1",
                ok: true,
                probes: probes.clone(),
                ..Outcome::default()
            },
        );
        let cached = read(dir.path(), "just fmt-check").expect("record");
        assert_eq!(
            cached.probes, probes,
            "the record remembers what each probe printed, so a later stale verdict can name the one that moved"
        );

        write(dir.path(), "cargo test", "d2", true);
        let bare = read(dir.path(), "cargo test").expect("record");
        assert!(
            bare.probes.is_empty(),
            "a rule naming no probes records none"
        );
    }

    #[test]
    fn distinct_commands_get_distinct_records() {
        let dir = tempfile::tempdir().expect("tempdir");
        let base = dir.path();
        write(base, "cargo test", "d1", true);
        write(base, "cargo build", "d2", true);
        assert!(is_fresh(base, "cargo test", "d1"));
        assert!(is_fresh(base, "cargo build", "d2"));
    }

    #[test]
    fn read_surfaces_the_clock_it_was_stamped_from() {
        let dir = tempfile::tempdir().expect("tempdir");
        write(dir.path(), "sh", "d", true);
        let cached = read(dir.path(), "sh").expect("record");
        assert_eq!(
            cached.ran_at, RAN_AT,
            "ran_at is the clock the writer was handed, not one read here"
        );
    }

    #[test]
    fn slug_is_readable_distinct_capped_and_never_empty() {
        assert!(slug("cargo test").starts_with("cargo-test-"));
        assert_ne!(slug("cargo test"), slug("cargo build"));
        assert!(
            slug("+++").starts_with("cmd-"),
            "all-symbol name gets a stem"
        );
        let long = "x".repeat(500);
        let stem = slug(&long);
        // 64-char stem + '-' + 16-char hash.
        assert_eq!(stem.len(), super::SLUG_MAX + 1 + 16, "stem is capped");
    }

    #[test]
    fn write_is_atomic_and_leaves_no_temp_file() {
        let dir = tempfile::tempdir().expect("tempdir");
        let base = dir.path();
        write(base, "cargo test", "digest-a", true);

        let temps: Vec<_> = std::fs::read_dir(base)
            .expect("cache dir")
            .filter_map(Result::ok)
            .filter(|entry| entry.path().extension().is_some_and(|ext| ext == "tmp"))
            .collect();
        assert!(temps.is_empty(), "rename leaves no .tmp behind");
        assert!(
            is_fresh(base, "cargo test", "digest-a"),
            "record is readable"
        );
    }

    #[test]
    fn prune_drops_only_orphan_records() {
        let dir = tempfile::tempdir().expect("tempdir");
        let base = dir.path();
        write(base, "cargo test", "d1", true);
        write(base, "cargo build", "d2", true);

        let live: BTreeSet<String> = ["cargo test".to_owned()].into_iter().collect();
        let pruned = prune(base, &live).expect("prune");
        assert_eq!(pruned, vec!["cargo build".to_owned()], "orphan removed");
        assert!(is_fresh(base, "cargo test", "d1"), "live record kept");
        assert!(read(base, "cargo build").is_none(), "orphan record gone");
    }

    #[test]
    fn prune_on_missing_dir_is_empty() {
        let dir = tempfile::tempdir().expect("tempdir");
        let pruned = prune(&dir.path().join("absent"), &BTreeSet::new()).expect("prune");
        assert!(pruned.is_empty(), "missing cache dir prunes nothing");
    }
}