voom 0.10.0

Fast, safe, parallel build-artifact pruning across every major language ecosystem
Documentation
//! Arguments and rendering for the maintenance subcommands: `git-prune`,
//! `claude-prune`. Split out of `cli/mod.rs` purely to stay under the module size cap — the
//! three share a shape (a subcommand takes its own paths, its own `--dry-run`, its own
//! `--format`) but nothing that would justify one being written in terms of another.

use std::io;
use std::path::PathBuf;

use clap::Args;

use super::{Format, PruneArgs};
use crate::error::Result;
use crate::policy::parse_duration;

/// `voom git-prune` arguments.
#[expect(
    clippy::struct_excessive_bools,
    reason = "these mirror command-line flags, which are bools by nature"
)]
#[derive(Debug, Args)]
pub struct GitPruneArgs {
    /// Trees to search for repositories.
    #[arg(value_name = "PATH", default_value = ".")]
    pub paths: Vec<PathBuf>,

    /// Report what git would prune, without letting it repack.
    #[arg(short = 'n', long)]
    pub dry_run: bool,

    /// Output format.
    ///
    /// Duplicated from the top-level flag rather than inherited: `args_conflicts_with_subcommands`
    /// makes `voom --format json git-prune .` a usage error, so without this the subcommand has
    /// no route to JSON at all.
    #[arg(long, value_enum, default_value_t = Format::Human)]
    pub format: Format,

    /// Also prune remote-tracking branches whose upstream is gone.
    ///
    /// Off by default, and deliberately not part of a sweep, because it contacts the remote: one
    /// network round trip per remote per repository, which hangs without connectivity and can
    /// block on a credential prompt.
    #[arg(long)]
    pub remotes: bool,

    /// How long one repository's housekeeping may take, e.g. `30s`.
    #[arg(long, value_name = "DURATION")]
    pub timeout: Option<String>,

    /// Also remove linked worktrees whose work is already merged into the default branch.
    ///
    /// The same rules as the top-level `--remove-merged-worktrees`: merged, not locked or the
    /// current directory, below a searched path, and clean apart from deleted tracked build
    /// output or ignored build-output trees. Reports only under `-n`.
    #[arg(long)]
    pub remove_merged_worktrees: bool,

    /// With `--remove-merged-worktrees`, also recognize squash and rebase merges on GitHub.
    ///
    /// Contacts github.com through `gh`. Only an exact HEAD match to a merged pull request
    /// in the origin repository counts; lookup failures keep the checkout. Working-tree and
    /// containment checks still apply. Commits proved only by GitHub are retained under
    /// `refs/voom/merged-worktrees/` before removal.
    #[arg(long, requires = "remove_merged_worktrees")]
    pub github_merged_worktrees: bool,

    /// How old a worktree's administration must be before git may prune it.
    ///
    /// Defaults to git's own `gc.worktreePruneExpire` policy, three months, rather than
    /// `git worktree prune`'s much more aggressive one — which removes the administration for
    /// every absent worktree at any age, an unmounted disk included, and with it the reflog that
    /// is the recovery path for anything committed there.
    #[arg(long, value_name = "TIME")]
    pub expire: Option<String>,
}

impl GitPruneArgs {
    /// The options for an explicit `voom git-prune`.
    ///
    /// # Errors
    ///
    /// [`Error::InvalidDuration`] for an unparseable timeout, or [`Error::CatalogPattern`] for
    /// an `--exclude` glob that will not compile.
    pub fn to_git_options(&self, prune: &PruneArgs) -> Result<crate::git::GitPruneOptions> {
        Ok(crate::git::GitPruneOptions {
            roots: self.paths.clone(),
            dry_run: self.dry_run,
            jobs: prune.jobs,
            one_file_system: prune.one_file_system,
            timeout: self
                .timeout
                .as_deref()
                .map(parse_duration)
                .transpose()?
                .unwrap_or(crate::git::DEFAULT_TIMEOUT),
            exclude: crate::scan::PatternSet::new(prune.exclude.clone())?,
            remotes: self.remotes,
            worktree_expire: self
                .expire
                .clone()
                .unwrap_or_else(|| crate::git::WORKTREE_PRUNE_EXPIRE.to_owned()),
            // The explicit surface says what a withheld repack would have had to work with; a
            // sweep does not, because the census is a question nobody asked it.
            count_objects: true,
        })
    }
}

/// Renders a finished `git-prune` in the requested format.
///
/// # Errors
///
/// Propagates write failures from `out`.
pub fn render_git(
    result: &crate::git::GitPruneResult,
    args: &GitPruneArgs,
    out: &mut impl io::Write,
) -> io::Result<()> {
    match args.format {
        Format::Human => crate::git::render_human(result, out),
        Format::Json => crate::git::render_json(result, out),
    }
}

/// `voom claude-prune` arguments.
#[expect(
    clippy::struct_excessive_bools,
    reason = "these mirror command-line flags, which are bools by nature"
)]
#[derive(Debug, Args)]
pub struct ClaudePruneArgs {
    /// `~/.claude/jobs`-shaped directories to search. Defaults to `~/.claude/jobs`.
    #[arg(value_name = "PATH")]
    pub roots: Vec<PathBuf>,

    /// Actually remove an eligible job's scratch, on top of the age gate and the liveness check
    /// both already having to hold. Without this, the command only ever reports.
    #[arg(long)]
    pub remove: bool,

    /// Report what would be removed, without removing it. Only meaningful with `--remove`.
    #[arg(short = 'n', long)]
    pub dry_run: bool,

    /// How long a job must have been quiet before it is even a candidate.
    #[arg(long, value_name = "DURATION")]
    pub min_age: Option<String>,

    /// Output format.
    #[arg(long, value_enum, default_value_t = Format::Human)]
    pub format: Format,

    /// Do not cross filesystem boundaries.
    #[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
    pub one_file_system: bool,

    /// Retry a failed removal, repairing permissions inside the scratch directory first.
    #[arg(long)]
    pub force: bool,
}

impl ClaudePruneArgs {
    /// The options for `voom claude-prune`.
    ///
    /// # Errors
    ///
    /// [`Error::InvalidDuration`] for an unparseable `--min-age`.
    pub fn to_claude_options(&self) -> Result<crate::claude::ClaudePruneOptions> {
        Ok(crate::claude::ClaudePruneOptions {
            roots: if self.roots.is_empty() {
                crate::claude::default_root()
            } else {
                self.roots.clone()
            },
            min_age: self
                .min_age
                .as_deref()
                .map(parse_duration)
                .transpose()?
                .unwrap_or(crate::claude::DEFAULT_MIN_AGE),
            remove: self.remove,
            dry_run: self.dry_run,
            force: self.force,
            one_file_system: self.one_file_system,
        })
    }
}

/// Renders a finished `claude-prune` in the requested format.
///
/// # Errors
///
/// Propagates write failures from `out`.
pub fn render_claude(
    result: &crate::claude::ClaudePruneResult,
    args: &ClaudePruneArgs,
    out: &mut impl io::Write,
) -> io::Result<()> {
    match args.format {
        Format::Human => crate::claude::render_human(result, out),
        Format::Json => crate::claude::render_json(result, out),
    }
}