haz-cli 0.1.0

//! Command-line argument parser for the `haz` binary.
//!
//! Built on `bpaf` 0.9 using the combinator API; the derive
//! macro is deliberately not used so the parser type tree stays
//! decoupled from bpaf's macros. The parser produces a [`Cmd`]
//! sum: one variant per command shape that the spec names
//! normatively (`haz run`, `haz check`, `haz cache clear`,
//! `haz cache clean --soft`).
//!
//! `--help` and `--version` are provided by bpaf automatically;
//! the version string is sourced from `CARGO_PKG_VERSION` at
//! compile time.

use bpaf::{OptionParser, Parser, construct, long, positional, pure};
use haz_domain::settings::cache_clean::max_age::MaxAge;
use haz_domain::settings::cache_clean::max_size::MaxSize;
pub use haz_domain::settings::output::OutputMode;
pub use haz_vcs::GitFilter;

/// Top-level command parsed from `argv`.
///
/// Each variant carries the per-command arguments needed to
/// dispatch. The parser layer does not load the workspace, run
/// the scheduler, or touch the filesystem; downstream modules
/// take a [`Cmd`] value and act on it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Cmd {
    /// `haz run [--all | --workspace] [--dry-run] [--output-mode <mode>]
    /// [<TASK_REF>...]` -- run (or, with `--dry-run`, enumerate)
    /// the selected tasks plus their transitive hard predecessors
    /// in the discovered workspace.
    Run(RunArgs),
    /// `haz check [--all | --workspace]` -- validate the discovered
    /// workspace without running any task (`AUX-009`..`AUX-012`).
    Check(CheckArgs),
    /// `haz why <TASK>` -- read-only introspection of one task per
    /// `AUX-013`..`AUX-016`.
    Why(WhyArgs),
    /// `haz cache clear` -- remove every cache entry (`CACHE-021`).
    CacheClear,
    /// `haz cache clean [--soft] [--max-age <DURATION>]
    /// [--max-size <BYTES>] [--dry-run]` -- selective cache
    /// reclamation (`CACHE-022`, `AUX-022`..`AUX-027`). The
    /// executor enforces the "at least one mode" rule
    /// (`AUX-022`) after merging CLI flags with workspace
    /// `cache.clean.*` defaults (`AUX-025`).
    CacheClean(CacheCleanArgs),
    /// `haz cache info` -- read-only cache-state report
    /// (`AUX-017`..`AUX-021`).
    CacheInfo,
    /// `haz query [filter flags]... [--format <fmt>]` -- enumerate
    /// the tasks in the workspace matching every supplied filter
    /// (`QRY-001`..`QRY-009`).
    Query(QueryArgs),
    /// `haz init [--yes]` -- scaffold a workspace
    /// (`AUX-001`..`AUX-008`). The bare form runs the interactive
    /// flow (`AUX-003`..`AUX-005`); `--yes` writes the minimal
    /// `projects: []` workspace per `AUX-007`.
    Init(InitArgs),
}

/// Arguments parsed for the `haz run` subcommand.
///
/// The three scope-mutex rules (`--all` vs `--workspace`,
/// `--all` vs positional refs, `--workspace` vs positional refs)
/// are enforced by the parser itself, so any [`RunArgs`] value
/// produced by [`cli`] is already known to satisfy them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RunArgs {
    /// Positional task references the user named on the command
    /// line. Each entry is a raw string; reference resolution
    /// (`REF-001`..`REF-008`) happens after the workspace loads.
    pub targets: Vec<String>,
    /// `--all`: widen the target set to every task in the current
    /// bearing scope (`EXEC-024`). Mutex with [`Self::workspace`]
    /// and with non-empty [`Self::targets`]; enforced at parse
    /// time.
    pub all: bool,
    /// `--workspace`: widen the target set to every task in every
    /// project, regardless of cwd (`EXEC-025`). Mutex with
    /// [`Self::all`] and with non-empty [`Self::targets`];
    /// enforced at parse time.
    pub workspace: bool,
    /// `--git-changed` / `--git-staged` / `--git-changed-since
    /// <REV>`: which git changeset to restrict the candidate set
    /// to (`EXEC-026`..`EXEC-029`). At most one filter; intra-
    /// family mutex enforced at parse time. Mutex with non-empty
    /// [`Self::targets`] also enforced at parse time. MAY combine
    /// with [`Self::all`] or [`Self::workspace`].
    pub git_filter: Option<GitFilter>,
    /// `--dry-run`: enumerate the target set without spawning any
    /// task (`EXEC-030`). Composable with every other flag.
    pub dry_run: bool,
    /// `--output-mode` flag value, if the user provided one.
    /// `None` means "fall back to the workspace's `output.mode`
    /// setting" per `EXEC-016`.
    pub output_mode: Option<OutputMode>,
}

/// Arguments parsed for the `haz check` subcommand.
///
/// `haz check` accepts only the scope flags (`--all`,
/// `--workspace`) per `AUX-009`. Like `haz run`, the two scope
/// flags are mutually exclusive; the parser enforces the mutex
/// so any [`CheckArgs`] value reaching the executor is in a
/// well-formed shape.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct CheckArgs {
    /// `--all`: widen the validated set to every task in the
    /// current bearing scope (`AUX-009`, mirroring `EXEC-024`).
    /// Mutex with [`Self::workspace`]; enforced at parse time.
    pub all: bool,
    /// `--workspace`: widen the validated set to every task in
    /// every project, regardless of cwd (`AUX-009`, mirroring
    /// `EXEC-025`). Mutex with [`Self::all`]; enforced at parse
    /// time.
    pub workspace: bool,
}

/// Arguments parsed for the `haz why` subcommand.
///
/// `haz why` takes exactly one positional task reference per
/// `AUX-013` and no flags for v1. Reference resolution
/// (`REF-001`..`REF-008`) and the "exactly one node" check
/// happen at the executor, after workspace load.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WhyArgs {
    /// The task reference the user named on the command line.
    /// Stored as the raw string; resolution happens after the
    /// workspace and graph have loaded.
    pub target: String,
}

/// 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,
}

/// Arguments parsed for the `haz query` subcommand.
///
/// Each filter slot stores the user's raw expression string; the
/// executor parses it through `haz_query_lang::parser` and lifts
/// each atom to its typed form via the appropriate
/// `haz_query::expr::*` helper. Storing strings here keeps the CLI
/// layer agnostic to the query language's typed-atom surface and
/// matches the convention already used for `targets` on
/// [`RunArgs`].
///
/// The boolean shortcuts each carry their own field; the parser
/// enforces the intra-pair mutex (`--has-X` vs `--no-X`) at parse
/// time so the executor sees at most one of each pair set.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct QueryArgs {
    /// `--tags <EXPR>` per `QRY-003`.
    pub tags: Option<String>,
    /// `--projects <EXPR>` per `QRY-003`.
    pub projects: Option<String>,
    /// `--tasks <EXPR>` per `QRY-003`.
    pub tasks: Option<String>,
    /// `--inputs <EXPR>` per `QRY-003`.
    pub inputs: Option<String>,
    /// `--outputs <EXPR>` per `QRY-003`.
    pub outputs: Option<String>,
    /// `--child-of <EXPR>` per `QRY-004`.
    pub child_of: Option<String>,
    /// `--parent-of <EXPR>` per `QRY-004`.
    pub parent_of: Option<String>,
    /// `--depends-on <EXPR>` per `QRY-004`.
    pub depends_on: Option<String>,
    /// `--ancestor-of <EXPR>` per `QRY-004`.
    pub ancestor_of: Option<String>,
    /// `--has-deps` / `--no-deps` per `QRY-005`.
    pub deps_presence: FieldPresence,
    /// `--has-inputs` / `--no-inputs` per `QRY-005`.
    pub inputs_presence: FieldPresence,
    /// `--has-outputs` / `--no-outputs` per `QRY-005`.
    pub outputs_presence: FieldPresence,
    /// `--mutex` per `QRY-005`.
    pub mutex: bool,
    /// `--format <FMT>` per `QRY-008`; defaults to `plain`.
    pub format: OutputFormat,
}

/// Arguments parsed for the `haz init` subcommand.
///
/// `AUX-001` admits exactly two invocation shapes: the bare form
/// (which would run the interactive scaffold flow,
/// `AUX-003`..`AUX-005`) and `--yes` (which writes the minimal
/// `projects: []` workspace per `AUX-007`). Both forms parse;
/// the executor selects the branch.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct InitArgs {
    /// `--yes`: skip the interactive flow per `AUX-007`.
    pub yes: bool,
}

/// Per-field presence selector for the `--has-X` / `--no-X` flag
/// pairs of `QRY-005`. Encoding the pair as a single tri-state
/// value lifts the spec's intra-pair mutex (within a pair, the
/// two flags are mutually exclusive) into the type system, so the
/// invariant cannot be violated at any layer.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum FieldPresence {
    /// Neither `--has-X` nor `--no-X` was supplied; the field
    /// contributes no constraint.
    #[default]
    Any,
    /// `--has-X`: the field MUST be non-empty.
    NonEmpty,
    /// `--no-X`: the field MUST be empty.
    Empty,
}

/// Output presentation for `haz query` per `QRY-008`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum OutputFormat {
    /// One line per task, formatted as `<project>:<task>`. The
    /// default per `QRY-001`.
    #[default]
    Plain,
    /// A single JSON array of objects with `project`, `task`, and
    /// `tags` fields per `QRY-008`.
    Json,
}

/// Build the top-level argument parser.
///
/// Returns an [`OptionParser`] that callers consume via
/// `.run()` (for `argv` parsing) or `.run_inner(...)` (for
/// programmatic / test parsing).
pub fn cli() -> OptionParser<Cmd> {
    let run = run_command().map(Cmd::Run).to_options();
    let check = check_command().map(Cmd::Check).to_options();
    let why = why_command().map(Cmd::Why).to_options();
    let cache = cache_command().to_options();
    let query = query_command().map(Cmd::Query).to_options();
    let init = init_command().map(Cmd::Init).to_options();

    let run_subcommand = run.command("run").help("Run one or more tasks");
    let check_subcommand = check
        .command("check")
        .help("Validate the workspace without running (AUX-009..AUX-012)");
    let why_subcommand = why
        .command("why")
        .help("Introspect a single task (AUX-013..AUX-016)");
    let cache_subcommand = cache
        .command("cache")
        .help("Cache management commands (CACHE-021, CACHE-022)");
    let query_subcommand = query
        .command("query")
        .help("Enumerate tasks under a filter expression (QRY-001..QRY-009)");
    let init_subcommand = init
        .command("init")
        .help("Scaffold a workspace (AUX-001..AUX-008)");

    construct!([
        run_subcommand,
        check_subcommand,
        why_subcommand,
        cache_subcommand,
        query_subcommand,
        init_subcommand,
    ])
    .to_options()
    .version(env!("CARGO_PKG_VERSION"))
    .descr("haz: task dependency graph runner")
}

fn run_command() -> impl Parser<RunArgs> {
    let all = long("all")
        .help("Run every task in the bearing scope (EXEC-024)")
        .switch();
    let workspace = long("workspace")
        .help("Run every task in every project, regardless of cwd (EXEC-025)")
        .switch();
    let dry_run = long("dry-run")
        .help("Enumerate the target set without spawning any task (EXEC-030)")
        .switch();
    let git_filter = git_filter_parser();
    let output_mode = long("output-mode")
        .help("Output presentation mode (live | buffered)")
        .argument::<String>("MODE")
        .parse(|s| match s.as_ref() {
            "live" => Ok(OutputMode::Live),
            "buffered" => Ok(OutputMode::Buffered),
            other => Err(format!(
                "unknown output mode `{other}` (expected `live` or `buffered`)"
            )),
        })
        .optional();
    let targets = positional::<String>("TASK")
        .help("Task reference (e.g. `proj:task`, `^:task`)")
        .many();
    // Named options before positionals: bpaf's parser-combinator
    // matching follows construct! order. Putting the named flags
    // first lets `--output-mode <value>` consume its argument
    // before `targets.many()` becomes greedy on the same value.
    construct!(RunArgs {
        all,
        workspace,
        git_filter,
        dry_run,
        output_mode,
        targets,
    })
    // EXEC-024 / EXEC-025 scope mutexes and the EXEC-026 git-
    // filter / positional mutex. Caught at parse time so a
    // downstream resolver can assume every received RunArgs is
    // already in a well-formed shape (at most one scope flag, and
    // either a positional list OR a git filter OR neither, but
    // never both).
    .parse(|args: RunArgs| {
        let has_positionals = !args.targets.is_empty();
        let has_git_filter = args.git_filter.is_some();
        match (args.all, args.workspace, has_git_filter, has_positionals) {
            (true, true, _, _) => {
                Err("`--all` and `--workspace` are mutually exclusive".to_owned())
            }
            (true, _, _, true) => {
                Err("`--all` cannot be combined with positional task references".to_owned())
            }
            (_, true, _, true) => {
                Err("`--workspace` cannot be combined with positional task references".to_owned())
            }
            (_, _, true, true) => Err(
                "git-changeset filters cannot be combined with positional task references"
                    .to_owned(),
            ),
            _ => Ok(args),
        }
    })
}

/// Build the optional git-changeset filter parser.
///
/// Three independent sub-flags are gathered (`--git-changed`,
/// `--git-staged`, `--git-changed-since <REV>`) and reduced to an
/// `Option<GitFilter>`. The reduction is the EXEC-026 intra-family
/// mutex: two or more flags are rejected at parse time, so callers
/// never see an ambiguous filter value.
fn git_filter_parser() -> impl Parser<Option<GitFilter>> {
    let changed = long("git-changed")
        .help("Restrict targets to tasks affected by working-tree changes vs HEAD (EXEC-027)")
        .switch();
    let staged = long("git-staged")
        .help("Restrict targets to tasks affected by staged changes vs HEAD (EXEC-028)")
        .switch();
    let changed_since = long("git-changed-since")
        .help("Restrict targets to tasks affected by changes since <REV> (EXEC-029)")
        .argument::<String>("REV")
        .optional();
    construct!(changed, staged, changed_since).parse(|(changed, staged, changed_since)| {
        match (changed, staged, changed_since) {
            (false, false, None) => Ok(None),
            (true, false, None) => Ok(Some(GitFilter::Changed)),
            (false, true, None) => Ok(Some(GitFilter::Staged)),
            (false, false, Some(rev)) => Ok(Some(GitFilter::ChangedSince(rev))),
            _ => Err("git-changeset filters are mutually exclusive".to_owned()),
        }
    })
}

fn check_command() -> impl Parser<CheckArgs> {
    let all = long("all")
        .help("Validate every task in the bearing scope (AUX-009, mirrors EXEC-024)")
        .switch();
    let workspace = long("workspace")
        .help("Validate every task in every project, regardless of cwd (AUX-009, mirrors EXEC-025)")
        .switch();
    construct!(CheckArgs { all, workspace })
        // AUX-009 scope mutex. Caught at parse time so the
        // executor never sees both flags set.
        .parse(|args: CheckArgs| {
            if args.all && args.workspace {
                Err("`--all` and `--workspace` are mutually exclusive".to_owned())
            } else {
                Ok(args)
            }
        })
}

fn why_command() -> impl Parser<WhyArgs> {
    // AUX-013 form contract: exactly one positional task
    // reference and no flags defined for v1. Reference resolution
    // and the "exactly one node" check happen at the executor.
    let target = positional::<String>("TASK").help("Task reference (REF-001..REF-008)");
    construct!(WhyArgs { target })
}

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)
}

fn query_command() -> impl Parser<QueryArgs> {
    let tags = long("tags")
        .help("Filter by owning-project tag expression (QRY-003)")
        .argument::<String>("EXPR")
        .optional();
    let projects = long("projects")
        .help("Filter by project-name expression (QRY-003)")
        .argument::<String>("EXPR")
        .optional();
    let tasks = long("tasks")
        .help("Filter by task-name expression (QRY-003)")
        .argument::<String>("EXPR")
        .optional();
    let inputs = long("inputs")
        .help("Filter by inputs path-pattern expression (QRY-003)")
        .argument::<String>("EXPR")
        .optional();
    let outputs = long("outputs")
        .help("Filter by outputs path-pattern expression (QRY-003)")
        .argument::<String>("EXPR")
        .optional();
    let child_of = long("child-of")
        .help("Direct hard-edge predecessor must satisfy EXPR (QRY-004)")
        .argument::<String>("EXPR")
        .optional();
    let parent_of = long("parent-of")
        .help("Direct hard-edge successor must satisfy EXPR (QRY-004)")
        .argument::<String>("EXPR")
        .optional();
    let depends_on = long("depends-on")
        .help("Transitive hard-edge predecessor must satisfy EXPR (QRY-004)")
        .argument::<String>("EXPR")
        .optional();
    let ancestor_of = long("ancestor-of")
        .help("Transitive hard-edge successor must satisfy EXPR (QRY-004)")
        .argument::<String>("EXPR")
        .optional();

    let deps_presence = presence_parser(
        "has-deps",
        "no-deps",
        "Select tasks whose `deps:` is non-empty (QRY-005)",
        "Select tasks whose `deps:` is empty (QRY-005)",
    );
    let inputs_presence = presence_parser(
        "has-inputs",
        "no-inputs",
        "Select tasks whose `inputs:` is non-empty (QRY-005)",
        "Select tasks whose `inputs:` is empty (QRY-005)",
    );
    let outputs_presence = presence_parser(
        "has-outputs",
        "no-outputs",
        "Select tasks whose `outputs:` is non-empty (QRY-005)",
        "Select tasks whose `outputs:` is empty (QRY-005)",
    );
    let mutex = long("mutex")
        .help("Select tasks that declare a `mutex:` field (QRY-005)")
        .switch();

    let format = long("format")
        .help("Output format (plain | json) per QRY-008")
        .argument::<String>("FMT")
        .parse(|s| match s.as_ref() {
            "plain" => Ok(OutputFormat::Plain),
            "json" => Ok(OutputFormat::Json),
            other => Err(format!(
                "unknown output format `{other}` (expected `plain` or `json`)"
            )),
        })
        .fallback(OutputFormat::Plain);

    construct!(QueryArgs {
        tags,
        projects,
        tasks,
        inputs,
        outputs,
        child_of,
        parent_of,
        depends_on,
        ancestor_of,
        deps_presence,
        inputs_presence,
        outputs_presence,
        mutex,
        format,
    })
}

fn init_command() -> impl Parser<InitArgs> {
    let yes = long("yes")
        .help("Skip the interactive flow and write a minimal workspace (AUX-007)")
        .switch();
    construct!(InitArgs { yes })
}

/// Build the `--<has_flag>` / `--<no_flag>` pair parser. The
/// reduction to [`FieldPresence`] is the `QRY-005` intra-pair
/// mutex: two switches yield three valid states; the impossible
/// "both" state is rejected at parse time.
fn presence_parser(
    has_flag: &'static str,
    no_flag: &'static str,
    has_help: &'static str,
    no_help: &'static str,
) -> impl Parser<FieldPresence> {
    let has = long(has_flag).help(has_help).switch();
    let no = long(no_flag).help(no_help).switch();
    construct!(has, no).parse(move |(has, no)| match (has, no) {
        (false, false) => Ok(FieldPresence::Any),
        (true, false) => Ok(FieldPresence::NonEmpty),
        (false, true) => Ok(FieldPresence::Empty),
        (true, true) => Err(format!(
            "`--{has_flag}` and `--{no_flag}` are mutually exclusive"
        )),
    })
}

#[cfg(test)]
mod tests {
    use super::{
        CacheCleanArgs, CheckArgs, Cmd, FieldPresence, GitFilter, InitArgs, MaxAge, MaxSize,
        OutputFormat, OutputMode, QueryArgs, RunArgs, WhyArgs, cli,
    };

    fn parse(args: &[&str]) -> Result<Cmd, String> {
        cli().run_inner(args).map_err(|err| err.unwrap_stderr())
    }

    fn bare_run_args() -> RunArgs {
        RunArgs {
            targets: Vec::new(),
            all: false,
            workspace: false,
            git_filter: None,
            dry_run: false,
            output_mode: None,
        }
    }

    #[test]
    fn run_with_no_targets_parses() {
        let parsed = parse(&["run"]).unwrap();
        assert_eq!(parsed, Cmd::Run(bare_run_args()));
    }

    #[test]
    fn run_with_one_target_parses() {
        let parsed = parse(&["run", "lib:build"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                targets: vec!["lib:build".to_owned()],
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_multiple_targets_parses_in_order() {
        let parsed = parse(&["run", "lib:build", "app:test", "^:lint"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                targets: vec![
                    "lib:build".to_owned(),
                    "app:test".to_owned(),
                    "^:lint".to_owned(),
                ],
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_output_mode_live() {
        let parsed = parse(&["run", "--output-mode", "live", "lib:build"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                targets: vec!["lib:build".to_owned()],
                output_mode: Some(OutputMode::Live),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_output_mode_buffered() {
        let parsed = parse(&["run", "--output-mode", "buffered", "lib:build"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                targets: vec!["lib:build".to_owned()],
                output_mode: Some(OutputMode::Buffered),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_all_flag_parses() {
        let parsed = parse(&["run", "--all"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                all: true,
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_workspace_flag_parses() {
        let parsed = parse(&["run", "--workspace"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                workspace: true,
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_dry_run_flag_parses() {
        let parsed = parse(&["run", "--dry-run"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                dry_run: true,
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_dry_run_composes_with_positional() {
        let parsed = parse(&["run", "--dry-run", "lib:build"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                targets: vec!["lib:build".to_owned()],
                dry_run: true,
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_dry_run_composes_with_all() {
        let parsed = parse(&["run", "--dry-run", "--all"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                all: true,
                dry_run: true,
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_dry_run_composes_with_workspace() {
        let parsed = parse(&["run", "--dry-run", "--workspace"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                workspace: true,
                dry_run: true,
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_all_plus_workspace_rejects() {
        // EXEC-024 / EXEC-025 mutex.
        let err = parse(&["run", "--all", "--workspace"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the mutex: {err}",
        );
    }

    #[test]
    fn run_all_plus_positional_rejects() {
        // EXEC-024 mutex with positional targets.
        let err = parse(&["run", "--all", "lib:build"]).unwrap_err();
        assert!(
            err.contains("`--all`") && err.contains("positional"),
            "diagnostic should mention --all and positional refs: {err}",
        );
    }

    #[test]
    fn run_workspace_plus_positional_rejects() {
        // EXEC-025 mutex with positional targets.
        let err = parse(&["run", "--workspace", "lib:build"]).unwrap_err();
        assert!(
            err.contains("`--workspace`") && err.contains("positional"),
            "diagnostic should mention --workspace and positional refs: {err}",
        );
    }

    #[test]
    fn run_with_git_changed_parses() {
        let parsed = parse(&["run", "--git-changed"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                git_filter: Some(GitFilter::Changed),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_git_staged_parses() {
        let parsed = parse(&["run", "--git-staged"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                git_filter: Some(GitFilter::Staged),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_with_git_changed_since_parses() {
        let parsed = parse(&["run", "--git-changed-since", "main"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                git_filter: Some(GitFilter::ChangedSince("main".to_owned())),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_git_changed_plus_all_composes() {
        // EXEC-026 explicitly permits filter + single scope flag.
        let parsed = parse(&["run", "--git-changed", "--all"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                all: true,
                git_filter: Some(GitFilter::Changed),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_git_changed_plus_workspace_composes() {
        let parsed = parse(&["run", "--git-changed", "--workspace"]).unwrap();
        assert_eq!(
            parsed,
            Cmd::Run(RunArgs {
                workspace: true,
                git_filter: Some(GitFilter::Changed),
                ..bare_run_args()
            }),
        );
    }

    #[test]
    fn run_git_changed_plus_staged_rejects() {
        // EXEC-026 intra-family mutex.
        let err = parse(&["run", "--git-changed", "--git-staged"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the intra-family mutex: {err}",
        );
    }

    #[test]
    fn run_git_changed_plus_changed_since_rejects() {
        let err = parse(&["run", "--git-changed", "--git-changed-since", "main"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the intra-family mutex: {err}",
        );
    }

    #[test]
    fn run_git_staged_plus_changed_since_rejects() {
        let err = parse(&["run", "--git-staged", "--git-changed-since", "main"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the intra-family mutex: {err}",
        );
    }

    #[test]
    fn run_git_changed_plus_positional_rejects() {
        // EXEC-026 filter-vs-positional mutex.
        let err = parse(&["run", "--git-changed", "lib:build"]).unwrap_err();
        assert!(
            err.contains("git-changeset") && err.contains("positional"),
            "diagnostic should mention the filter-vs-positional mutex: {err}",
        );
    }

    #[test]
    fn run_git_staged_plus_positional_rejects() {
        let err = parse(&["run", "--git-staged", "lib:build"]).unwrap_err();
        assert!(
            err.contains("git-changeset") && err.contains("positional"),
            "diagnostic should mention the filter-vs-positional mutex: {err}",
        );
    }

    #[test]
    fn run_git_changed_since_plus_positional_rejects() {
        let err = parse(&["run", "--git-changed-since", "main", "lib:build"]).unwrap_err();
        assert!(
            err.contains("git-changeset") && err.contains("positional"),
            "diagnostic should mention the filter-vs-positional mutex: {err}",
        );
    }

    #[test]
    fn run_with_unknown_output_mode_rejects() {
        let err = parse(&["run", "--output-mode", "noisy", "lib:build"]).unwrap_err();
        assert!(
            err.contains("unknown output mode"),
            "diagnostic should name the offending value: {err}",
        );
    }

    #[test]
    fn aux_009_check_with_no_args_parses() {
        assert_eq!(parse(&["check"]).unwrap(), Cmd::Check(CheckArgs::default()),);
    }

    #[test]
    fn aux_009_check_with_all_flag_parses() {
        assert_eq!(
            parse(&["check", "--all"]).unwrap(),
            Cmd::Check(CheckArgs {
                all: true,
                workspace: false,
            }),
        );
    }

    #[test]
    fn aux_009_check_with_workspace_flag_parses() {
        assert_eq!(
            parse(&["check", "--workspace"]).unwrap(),
            Cmd::Check(CheckArgs {
                all: false,
                workspace: true,
            }),
        );
    }

    #[test]
    fn aux_009_check_all_plus_workspace_rejects() {
        // AUX-009 scope mutex (mirrors EXEC-024 / EXEC-025).
        let err = parse(&["check", "--all", "--workspace"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the mutex: {err}",
        );
    }

    #[test]
    fn aux_009_check_rejects_unknown_flag() {
        // AUX-009 form contract: no positional or extra flags
        // beyond --all / --workspace.
        let err = parse(&["check", "--dry-run"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "unknown flag must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn aux_009_check_rejects_positional() {
        // AUX-009 form contract: haz check takes no positional
        // arguments.
        let err = parse(&["check", "lib:build"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "positional argument must produce a diagnostic: {err}",
        );
    }

    // ---- why ----

    #[test]
    fn aux_013_why_parses_a_single_positional_target() {
        assert_eq!(
            parse(&["why", "lib:build"]).unwrap(),
            Cmd::Why(WhyArgs {
                target: "lib:build".to_owned(),
            }),
        );
    }

    #[test]
    fn aux_013_why_accepts_fan_out_reference_form_at_parse_time() {
        // REF-001..REF-008 admits forms like `^:test` (fan-out by
        // task name across projects). The parser accepts any
        // non-empty string verbatim; reference parsing and
        // resolution happen at the executor per AUX-013.
        assert_eq!(
            parse(&["why", "^:test"]).unwrap(),
            Cmd::Why(WhyArgs {
                target: "^:test".to_owned(),
            }),
        );
    }

    #[test]
    fn aux_013_why_rejects_missing_positional() {
        // AUX-013 form contract: exactly one positional argument.
        let err = parse(&["why"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "missing positional must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn aux_013_why_rejects_extra_positional() {
        // AUX-013 form contract: at most one positional argument.
        let err = parse(&["why", "lib:build", "other:task"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "extra positional must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn aux_013_why_rejects_unknown_flag() {
        // AUX-013 form contract: no flags defined for v1.
        let err = parse(&["why", "--all", "lib:build"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "unknown flag must produce a diagnostic: {err}",
        );
    }

    // ---- cache ----

    #[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,
            }),
        );
    }

    #[test]
    fn no_subcommand_rejects() {
        let err = parse(&[]).unwrap_err();
        assert!(
            !err.is_empty(),
            "missing subcommand must produce a diagnostic",
        );
    }

    // ---- query ----

    #[test]
    fn qry_001_query_with_no_flags_parses_to_default() {
        assert_eq!(parse(&["query"]).unwrap(), Cmd::Query(QueryArgs::default()),);
    }

    #[test]
    fn qry_003_tags_filter_captures_expression_verbatim() {
        assert_eq!(
            parse(&["query", "--tags", "backend & !legacy"]).unwrap(),
            Cmd::Query(QueryArgs {
                tags: Some("backend & !legacy".to_owned()),
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_003_projects_filter_captures_expression_verbatim() {
        assert_eq!(
            parse(&["query", "--projects", "lib | web"]).unwrap(),
            Cmd::Query(QueryArgs {
                projects: Some("lib | web".to_owned()),
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_003_tasks_filter_captures_expression_verbatim() {
        assert_eq!(
            parse(&["query", "--tasks", "build"]).unwrap(),
            Cmd::Query(QueryArgs {
                tasks: Some("build".to_owned()),
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_003_inputs_and_outputs_filters_capture_expressions_verbatim() {
        assert_eq!(
            parse(&[
                "query",
                "--inputs",
                "src/**/*.rs",
                "--outputs",
                "/lib/dist/*.so",
            ])
            .unwrap(),
            Cmd::Query(QueryArgs {
                inputs: Some("src/**/*.rs".to_owned()),
                outputs: Some("/lib/dist/*.so".to_owned()),
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_004_relational_filters_capture_expressions_verbatim() {
        assert_eq!(
            parse(&[
                "query",
                "--child-of",
                "name:build",
                "--parent-of",
                "tag:backend",
                "--depends-on",
                "project:lib",
                "--ancestor-of",
                "name:lint",
            ])
            .unwrap(),
            Cmd::Query(QueryArgs {
                child_of: Some("name:build".to_owned()),
                parent_of: Some("tag:backend".to_owned()),
                depends_on: Some("project:lib".to_owned()),
                ancestor_of: Some("name:lint".to_owned()),
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_005_individual_shortcut_flags_parse() {
        let parsed = parse(&[
            "query",
            "--has-deps",
            "--has-inputs",
            "--no-outputs",
            "--mutex",
        ])
        .unwrap();
        assert_eq!(
            parsed,
            Cmd::Query(QueryArgs {
                deps_presence: FieldPresence::NonEmpty,
                inputs_presence: FieldPresence::NonEmpty,
                outputs_presence: FieldPresence::Empty,
                mutex: true,
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_005_has_deps_plus_no_deps_rejects() {
        let err = parse(&["query", "--has-deps", "--no-deps"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the intra-pair mutex: {err}",
        );
    }

    #[test]
    fn qry_005_has_inputs_plus_no_inputs_rejects() {
        let err = parse(&["query", "--has-inputs", "--no-inputs"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the intra-pair mutex: {err}",
        );
    }

    #[test]
    fn qry_005_has_outputs_plus_no_outputs_rejects() {
        let err = parse(&["query", "--has-outputs", "--no-outputs"]).unwrap_err();
        assert!(
            err.contains("mutually exclusive"),
            "diagnostic should name the intra-pair mutex: {err}",
        );
    }

    #[test]
    fn qry_008_format_plain_parses() {
        assert_eq!(
            parse(&["query", "--format", "plain"]).unwrap(),
            Cmd::Query(QueryArgs {
                format: OutputFormat::Plain,
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_008_format_json_parses() {
        assert_eq!(
            parse(&["query", "--format", "json"]).unwrap(),
            Cmd::Query(QueryArgs {
                format: OutputFormat::Json,
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_008_format_default_is_plain() {
        let Cmd::Query(args) = parse(&["query"]).unwrap() else {
            panic!("expected Cmd::Query");
        };
        assert_eq!(args.format, OutputFormat::Plain);
    }

    #[test]
    fn qry_008_unknown_format_rejects() {
        let err = parse(&["query", "--format", "yaml"]).unwrap_err();
        assert!(
            err.contains("unknown output format"),
            "diagnostic should name the offending value: {err}",
        );
    }

    #[test]
    fn qry_006_multiple_filter_families_combine_into_one_args() {
        let parsed = parse(&[
            "query",
            "--tags",
            "backend",
            "--tasks",
            "test",
            "--has-deps",
            "--format",
            "json",
        ])
        .unwrap();
        assert_eq!(
            parsed,
            Cmd::Query(QueryArgs {
                tags: Some("backend".to_owned()),
                tasks: Some("test".to_owned()),
                deps_presence: FieldPresence::NonEmpty,
                format: OutputFormat::Json,
                ..QueryArgs::default()
            }),
        );
    }

    #[test]
    fn qry_001_query_rejects_positional_arguments() {
        let err = parse(&["query", "lib:build"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "positional argument must produce a diagnostic: {err}",
        );
    }

    // ---- init ----

    #[test]
    fn aux_001_init_bare_parses_with_yes_false() {
        assert_eq!(
            parse(&["init"]).unwrap(),
            Cmd::Init(InitArgs { yes: false }),
        );
    }

    #[test]
    fn aux_001_init_with_yes_flag_parses() {
        assert_eq!(
            parse(&["init", "--yes"]).unwrap(),
            Cmd::Init(InitArgs { yes: true }),
        );
    }

    #[test]
    fn aux_001_init_rejects_positional_argument() {
        let err = parse(&["init", "extra"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "positional argument must produce a diagnostic: {err}",
        );
    }

    #[test]
    fn aux_001_init_rejects_unknown_flag() {
        let err = parse(&["init", "--no-such-flag"]).unwrap_err();
        assert!(
            !err.is_empty(),
            "unknown flag must produce a diagnostic: {err}",
        );
    }
}