haz-cli 0.2.0

//! Parser for the `haz cache` subcommand family.
//!
//! Owns [`CacheCleanArgs`], the [`cache_command`] dispatcher over
//! the three `clear` / `clean` / `info` branches, and the
//! [`clean_command`] mode-flag parser. The `clear` and `info`
//! branches carry no arguments and map straight to their [`Cmd`]
//! variants; `clean` collects the composable mode flags.

use bpaf::{Parser, construct, long, pure};
use haz_domain::settings::cache_clean::max_age::MaxAge;
use haz_domain::settings::cache_clean::max_size::MaxSize;

use crate::cli::Cmd;

/// Arguments parsed for the `haz cache clean` subcommand.
///
/// Three composable mode flags (`--soft`, `--max-age`,
/// `--max-size`) plus the `--dry-run` modifier per
/// `AUX-022`..`AUX-024`. The CLI parser eagerly validates
/// `--max-age` / `--max-size` value strings against the
/// `CFG-034` / `CFG-035` grammars so a syntactically bad value
/// is rejected before workspace load. The `AUX-022` "at least
/// one mode" requirement is enforced at the executor layer
/// because workspace `cache.clean.*` defaults (`AUX-025`) MAY
/// supply a mode when the CLI is silent.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct CacheCleanArgs {
    /// `--soft`: reclaim objectively-stale state (`CACHE-022`).
    pub soft: bool,
    /// `--max-age <DURATION>`: evict entries strictly older than
    /// `now - DURATION` (`AUX-022`).
    pub max_age: Option<MaxAge>,
    /// `--max-size <BYTES>`: evict oldest-first until the
    /// well-formed footprint is at or below `BYTES`
    /// (`AUX-022`).
    pub max_size: Option<MaxSize>,
    /// `--dry-run`: compute the eviction set per `AUX-024`
    /// without removing anything.
    pub dry_run: bool,
}

pub(super) fn cache_command() -> impl Parser<Cmd> {
    // Three branches under `haz cache`: `clear` (remove every
    // entry, `CACHE-021`), `clean --soft` (remove only objectively
    // stale entries, `CACHE-022`), and `info` (read-only report,
    // `AUX-017`..`AUX-021`). Bindings named by their semantic
    // role rather than `cache_<verb>_subcommand` to keep clippy's
    // `similar_names` lint at bay (the spec verbs `clear` and
    // `clean` are too close on their own).
    let remove_all = pure(Cmd::CacheClear)
        .to_options()
        .command("clear")
        .help("Remove every cache entry (CACHE-021)");
    let prune_stale = clean_command()
        .to_options()
        .command("clean")
        .help("Selectively reclaim cache entries (CACHE-022, AUX-022..AUX-027)");
    let report_info = pure(Cmd::CacheInfo)
        .to_options()
        .command("info")
        .help("Report cache-state statistics (AUX-017..AUX-021)");
    construct!([remove_all, prune_stale, report_info])
}

fn clean_command() -> impl Parser<Cmd> {
    // Three composable mode flags + `--dry-run`. The `AUX-022`
    // "at least one mode" rule MAY be satisfied by workspace
    // `cache.clean.*` defaults (`AUX-025`), so enforcement
    // lives at the executor layer after the workspace loads.
    let soft = long("soft")
        .help("Reclaim objectively-stale state (CACHE-022)")
        .switch();
    let max_age = long("max-age")
        .help("Evict entries strictly older than DURATION (AUX-022)")
        .argument::<String>("DURATION")
        .parse(|s| MaxAge::parse(&s).map_err(|e| e.to_string()))
        .optional();
    let max_size = long("max-size")
        .help("Cap on-disk footprint at BYTES, evicting oldest first (AUX-022)")
        .argument::<String>("BYTES")
        .parse(|s| MaxSize::parse(&s).map_err(|e| e.to_string()))
        .optional();
    let dry_run = long("dry-run")
        .help("Compute the eviction set without removing anything (AUX-024)")
        .switch();
    construct!(CacheCleanArgs {
        soft,
        max_age,
        max_size,
        dry_run,
    })
    .map(Cmd::CacheClean)
}

#[cfg(test)]
mod tests {
    use super::{CacheCleanArgs, MaxAge, MaxSize};
    use crate::cli::{Cmd, parse};

    #[test]
    fn cache_clear_parses() {
        assert_eq!(parse(&["cache", "clear"]).unwrap(), Cmd::CacheClear);
    }

    #[test]
    fn cache_info_parses() {
        assert_eq!(parse(&["cache", "info"]).unwrap(), Cmd::CacheInfo);
    }

    #[test]
    fn aux_017_cache_info_rejects_positional() {
        // AUX-017 form contract: bare `cache info` only; any extra
        // positional is a CLI error.
        let err = parse(&["cache", "info", "extra"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "extra positional must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn aux_017_cache_info_rejects_unknown_flag() {
        // AUX-017 form contract: no flags defined for v1.
        let err = parse(&["cache", "info", "--soft"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "unknown flag must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn cache_clean_soft_parses() {
        assert_eq!(
            parse(&["cache", "clean", "--soft"]).unwrap(),
            Cmd::CacheClean(CacheCleanArgs {
                soft: true,
                ..CacheCleanArgs::default()
            }),
        );
    }

    #[test]
    fn cache_clean_bare_parses_with_no_modes() {
        // AUX-025 lets workspace `cache.clean.*` defaults supply
        // a mode, so the parser MUST accept a bare invocation.
        // The "at least one mode" rule (AUX-022) is enforced at
        // the executor layer after workspace load.
        assert_eq!(
            parse(&["cache", "clean"]).unwrap(),
            Cmd::CacheClean(CacheCleanArgs::default()),
        );
    }

    #[test]
    fn cache_clean_max_age_parses_valid_duration() {
        let want = MaxAge::parse("90d").unwrap();
        assert_eq!(
            parse(&["cache", "clean", "--max-age", "90d"]).unwrap(),
            Cmd::CacheClean(CacheCleanArgs {
                max_age: Some(want),
                ..CacheCleanArgs::default()
            }),
        );
    }

    #[test]
    fn cache_clean_max_age_rejects_bare_integer() {
        // CFG-034 / AUX-022: the bare-integer form is ambiguous
        // and MUST be rejected by the duration grammar.
        let err = parse(&["cache", "clean", "--max-age", "90"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "malformed --max-age must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn cache_clean_max_size_parses_si_suffix() {
        let want = MaxSize::parse("1GB").unwrap();
        assert_eq!(
            parse(&["cache", "clean", "--max-size", "1GB"]).unwrap(),
            Cmd::CacheClean(CacheCleanArgs {
                max_size: Some(want),
                ..CacheCleanArgs::default()
            }),
        );
    }

    #[test]
    fn cache_clean_max_size_rejects_unknown_suffix() {
        let err = parse(&["cache", "clean", "--max-size", "1ZB"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "malformed --max-size must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn cache_clean_dry_run_composes_with_other_flags() {
        let want_age = MaxAge::parse("30d").unwrap();
        assert_eq!(
            parse(&["cache", "clean", "--soft", "--max-age", "30d", "--dry-run"]).unwrap(),
            Cmd::CacheClean(CacheCleanArgs {
                soft: true,
                max_age: Some(want_age),
                max_size: None,
                dry_run: true,
            }),
        );
    }
}