use std::io::IsTerminal;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use indicatif::{ProgressBar, ProgressDrawTarget};
use rayon::prelude::*;
use crate::caches::CacheRoots;
use crate::classify::{ArtifactId, Classifier, Finding, Selection, SkipReason};
use crate::config::resolve::Flags;
use crate::config::{Resolved, Resolver, discover};
use crate::delete::{Guard, Outcome, Removal};
use crate::error::{Error, Result};
use crate::report::{Entry, RunResult, Timings};
use crate::scan::{PatternSet, ScanOptions, Skipped, scan};
use crate::size::Measured;
mod select;
mod tracked;
use select::select;
use tracked::without_tracked;
#[expect(
clippy::struct_excessive_bools,
reason = "these mirror command-line flags, which are bools by nature"
)]
#[derive(Debug, Clone)]
pub struct RunOptions {
pub roots: Vec<PathBuf>,
pub dry_run: bool,
pub jobs: Option<usize>,
pub one_file_system: bool,
pub force: bool,
pub verbose: bool,
pub config: Option<PathBuf>,
pub flags: Flags,
pub progress: bool,
}
#[derive(Default)]
struct Collected {
entries: Vec<Entry>,
skips: Vec<Skipped>,
skipped_count: usize,
failures: Vec<crate::scan::WalkFailure>,
git: Option<crate::git::GitPruneResult>,
repositories: Vec<PathBuf>,
scan: Duration,
policy: Duration,
size: Duration,
delete: Duration,
git_elapsed: Duration,
}
pub fn run(options: &RunOptions) -> Result<RunResult> {
let started = Instant::now();
let mut collected = Collected::default();
let roots = normalize_roots(&options.roots)?;
let pool = build_pool(options.jobs)?;
crate::delete::limit_removal_workers(options.jobs);
pool.install(|| -> Result<()> {
for root in &roots {
sweep(root, options, &mut collected)?;
}
Ok(())
})?;
let mut result = RunResult {
roots,
entries: collected.entries,
skips: collected.skips,
skipped_count: collected.skipped_count,
failures: collected.failures,
dry_run: options.dry_run,
git: collected.git,
repositories: collected.repositories,
timings: Timings {
total: started.elapsed(),
scan: collected.scan,
policy: collected.policy,
size: collected.size,
delete: collected.delete,
git: collected.git_elapsed,
},
};
result.sort();
Ok(result)
}
pub(crate) fn build_pool(jobs: Option<usize>) -> Result<rayon::ThreadPool> {
let jobs = jobs.map_or_else(io_threads, |jobs| jobs.max(1));
rayon::ThreadPoolBuilder::new()
.num_threads(jobs)
.build()
.map_err(|source| Error::ThreadPool { jobs, source })
}
fn io_threads() -> usize {
crate::limits::default_width()
}
fn normalize_roots(roots: &[PathBuf]) -> Result<Vec<PathBuf>> {
let mut resolved: Vec<(PathBuf, usize)> = Vec::with_capacity(roots.len());
for (index, root) in roots.iter().enumerate() {
let canonical = root.canonicalize().map_err(|source| Error::ReadDir {
path: root.clone(),
source,
})?;
resolved.push((canonical, index));
}
resolved.sort();
let mut kept: Vec<(PathBuf, usize)> = Vec::with_capacity(resolved.len());
for (canonical, index) in resolved {
if kept.iter().any(|(existing, _)| canonical.starts_with(existing)) {
continue;
}
kept.push((canonical, index));
}
Ok(kept.into_iter().map(|(_, index)| roots[index].clone()).collect())
}
pub fn resolver_for(root: &Path, options: &RunOptions) -> Result<Resolver> {
let sources = discover(root, options.config.as_deref())?;
Resolver::new(root, &sources, options.flags.clone())
}
fn sweep(root: &Path, options: &RunOptions, collected: &mut Collected) -> Result<()> {
let resolver = resolver_for(root, options)?;
let at_root = resolver.root_config()?;
let classifier = Classifier::new(selection_for(options)?)?;
let roots = std::slice::from_ref(&root.to_path_buf()).to_vec();
let guard = Guard::new(&roots, options.one_file_system)?;
let scan_options = scan_options_for(root, options, &at_root)?;
let spinner = start_progress(options.progress, root);
let started = Instant::now();
let scanned = scan(&roots, &classifier, &scan_options);
collected.scan += started.elapsed();
if let Some(spinner) = spinner {
spinner.finish_and_clear();
}
collected.failures.extend(scanned.failures);
collected.skips.extend(scanned.skips);
collected.skipped_count += scanned.skipped_count;
collected.repositories.extend(scanned.repositories.iter().cloned());
let (git, removed) = rayon::join(
|| prune_repositories(root, &scanned.repositories, &at_root, options),
|| -> Result<(Vec<Entry>, Vec<Entry>)> {
let mut selected = select(root, &resolver, scanned.findings, options, collected)?;
let tracked = without_tracked(&mut selected.to_remove, &scanned.repositories);
let removal = Removal {
dry_run: options.dry_run,
force: options.force,
};
let started = Instant::now();
let progress = (!options.dry_run).then(|| removal_progress(options.progress)).flatten();
let entries = remove_all(selected.to_remove, &guard, removal);
let uncovered = settle_covered(selected.covered, &entries, options, collected);
let retried = remove_all(uncovered, &guard, removal);
if let Some(progress) = progress {
progress.finish_and_clear();
}
collected.delete += started.elapsed();
Ok((entries.into_iter().chain(tracked).collect(), retried))
},
);
if let Some((pruned, elapsed)) = git? {
match &mut collected.git {
Some(existing) => existing.merge(pruned),
None => collected.git = Some(pruned),
}
collected.git_elapsed += elapsed;
}
let (entries, retried) = removed?;
collected.entries.extend(entries);
collected.entries.extend(retried);
Ok(())
}
fn scan_options_for(root: &Path, options: &RunOptions, at_root: &Resolved) -> Result<ScanOptions> {
Ok(ScanOptions {
jobs: options.jobs,
one_file_system: options.one_file_system,
collect_skips: options.verbose,
exclude: PatternSet::new(at_root.exclude.clone())?,
include: PatternSet::new(at_root.include.clone())?,
caches: CacheRoots::for_root(root, &at_root.clean_caches),
collect_repositories: true,
clean_tagged: at_root.clean_tagged,
guide_repositories: true,
})
}
fn settle_covered(
covered: Vec<(Finding, Option<Measured>, PathBuf)>,
entries: &[Entry],
options: &RunOptions,
collected: &mut Collected,
) -> Vec<(Finding, Option<Measured>)> {
let ran: std::collections::HashSet<&Path> = entries
.iter()
.filter(|entry| entry.outcome.is_reclaimed() || matches!(entry.outcome, Outcome::PartiallyRemoved { .. }))
.map(|entry| entry.path.as_path())
.collect();
let mut uncovered = Vec::new();
for (finding, measured, by) in covered {
if ran.contains(by.as_path()) {
note(collected, options.verbose, finding.path, SkipReason::Covered { by });
} else {
uncovered.push((finding, measured));
}
}
uncovered
}
fn prune_repositories(
root: &Path,
work_trees: &[PathBuf],
at_root: &Resolved,
options: &RunOptions,
) -> Result<Option<(crate::git::GitPruneResult, Duration)>> {
if !at_root.git || work_trees.is_empty() {
return Ok(None);
}
let started = Instant::now();
let git_options = crate::git::GitPruneOptions {
roots: vec![root.to_path_buf()],
dry_run: options.dry_run,
one_file_system: options.one_file_system,
exclude: PatternSet::new(at_root.exclude.clone())?,
..crate::git::GitPruneOptions::default()
};
Ok(crate::git::prune_during_sweep(work_trees, &git_options).map(|pruned| (pruned, started.elapsed())))
}
fn selection_for(options: &RunOptions) -> Result<Selection> {
let Some(ids) = &options.flags.ecosystems else {
return Ok(Selection::all().permissive());
};
let (selection, unknown) = Selection::only(ids.iter().map(String::as_str));
if let Some(name) = unknown.first() {
return Err(Error::UnknownEcosystem { name: name.clone() });
}
Ok(selection.permissive())
}
fn remove_all(mut to_remove: Vec<(Finding, Option<Measured>)>, guard: &Guard, removal: Removal) -> Vec<Entry> {
to_remove.sort_by_key(|(_, measured)| std::cmp::Reverse(measured.map_or(0, |size| size.bytes)));
crate::delete::install_removal(|| {
to_remove
.into_par_iter()
.map(|(finding, measured)| {
let removal = removal_for(&finding, removal);
let (outcome, measured) = if let Some(measured) = measured {
(guard.remove(&finding.path, measured.bytes, removal), measured)
} else {
guard.reclaim_fully(&finding.path, removal)
};
Entry {
path: finding.path.clone(),
finding,
bytes: measured.bytes,
unreadable: measured.unreadable,
outcome,
}
})
.collect()
})
}
fn removal_for(finding: &Finding, removal: Removal) -> Removal {
match finding.provenance {
crate::classify::Provenance::Cache { cache } if cache.read_only => Removal { force: true, ..removal },
_ => removal,
}
}
#[must_use]
pub fn removal_progress(enabled: bool) -> Option<ProgressBar> {
if !enabled || !std::io::stderr().is_terminal() {
return None;
}
let spinner = ProgressBar::new_spinner();
spinner.set_draw_target(ProgressDrawTarget::stderr());
spinner.enable_steady_tick(Duration::from_millis(120));
let ticker = spinner.clone();
let started = Instant::now();
let initial_freed = crate::delete::freed_so_far();
std::thread::spawn(move || {
while !ticker.is_finished() {
let freed = crate::delete::freed_so_far().saturating_sub(initial_freed);
let seconds = started.elapsed().as_secs_f64().max(1.0);
#[expect(
clippy::cast_precision_loss,
clippy::cast_possible_truncation,
clippy::cast_sign_loss,
reason = "a display rate, not a figure anything is decided by"
)]
let rate = (freed as f64 / seconds) as u64;
ticker.set_message(format!(
"removing — {} freed ({}/s)",
humansize::format_size(freed, humansize::DECIMAL),
humansize::format_size(rate, humansize::DECIMAL)
));
std::thread::sleep(Duration::from_millis(250));
}
});
Some(spinner)
}
fn start_progress(enabled: bool, root: &Path) -> Option<ProgressBar> {
if !enabled || !std::io::stderr().is_terminal() {
return None;
}
let spinner = ProgressBar::new_spinner();
spinner.set_draw_target(ProgressDrawTarget::stderr());
spinner.enable_steady_tick(Duration::from_millis(120));
spinner.set_message(format!("scanning {}", root.display()));
Some(spinner)
}
fn not_enabled(artifact: ArtifactId) -> SkipReason {
SkipReason::NotEnabled {
spec: artifact.spec(),
note: artifact.artifact().note,
}
}
fn note(collected: &mut Collected, verbose: bool, path: PathBuf, reason: SkipReason) {
collected.skipped_count += 1;
if verbose {
collected.skips.push(Skipped { path, reason });
}
}
#[cfg(test)]
mod tests_support {
use std::path::Path;
use super::*;
pub(super) fn options(root: &Path) -> RunOptions {
RunOptions {
roots: vec![root.to_path_buf()],
dry_run: false,
jobs: Some(2),
one_file_system: true,
force: false,
verbose: true,
config: None,
flags: Flags::default(),
progress: false,
}
}
pub(super) fn with_keep(root: &Path, keep: crate::policy::KeepPolicy) -> RunOptions {
RunOptions {
flags: Flags {
keep,
..Flags::default()
},
..options(root)
}
}
}
#[cfg(test)]
mod tests {
use super::tests_support::*;
use std::time::Duration;
use super::*;
use crate::delete::Outcome;
use crate::policy::KeepPolicy;
use crate::testing::{snapshot, tree};
#[test]
fn should_count_during_removal_unless_a_size_policy_needs_measurement() {
let fixture = tree(&["Cargo.toml", "target/debug/app"]);
let expected = crate::size::measure(&fixture.path().join("target"));
let result = run(&options(fixture.path())).expect("the run completes");
assert_eq!(
result.timings.size,
Duration::ZERO,
"no recursive sizing before removal"
);
assert_eq!(result.entries[0].bytes, expected, "removal counts all allocated bytes");
assert_eq!(result.entries[0].outcome, Outcome::Removed);
}
#[cfg(unix)]
#[test]
fn should_preserve_unreadable_counts_when_counting_during_removal() {
use std::os::unix::fs::PermissionsExt;
let fixture = tree(&["Cargo.toml", "target/locked/precious"]);
let locked = fixture.path().join("target/locked");
std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o000)).unwrap();
let result = run(&options(fixture.path())).expect("the run completes");
std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o700)).unwrap();
assert_eq!(
result.entries[0].unreadable, 1,
"failed removal retains unreadable evidence"
);
assert!(locked.join("precious").exists(), "unreadable content survives");
}
#[test]
fn should_remove_a_proven_artifact_and_leave_the_source() {
let fixture = tree(&["Cargo.toml", "src/main.rs", "target/debug/app"]);
let result = run(&options(fixture.path())).expect("the run completes");
assert_eq!(result.entries.len(), 1);
assert_eq!(result.entries[0].outcome, Outcome::Removed);
assert_eq!(snapshot(fixture.path()), vec!["Cargo.toml", "src/", "src/main.rs"]);
}
#[test]
fn should_leave_an_unproven_artifact_alone() {
let fixture = tree(&["target/important.txt"]);
let before = snapshot(fixture.path());
let result = run(&options(fixture.path())).expect("the run completes");
assert!(result.entries.is_empty());
assert_eq!(snapshot(fixture.path()), before);
assert_eq!(result.skipped_count, 1);
}
#[test]
fn should_leave_the_tree_byte_identical_during_a_dry_run() {
let fixture = tree(&["Cargo.toml", "target/debug/app", "package.json", "dist/bundle.js"]);
let before = snapshot(fixture.path());
let dry = run(&RunOptions {
dry_run: true,
..options(fixture.path())
})
.expect("the dry run completes");
assert_eq!(snapshot(fixture.path()), before, "a dry run must not touch the tree");
assert_eq!(dry.entries.len(), 2);
assert!(dry.entries.iter().all(|entry| entry.outcome == Outcome::WouldRemove));
let real = run(&options(fixture.path())).expect("the real run completes");
let dry_paths: Vec<_> = dry.entries.iter().map(|entry| entry.path.clone()).collect();
let real_paths: Vec<_> = real.entries.iter().map(|entry| entry.path.clone()).collect();
assert_eq!(
dry_paths, real_paths,
"a dry run reports exactly what a real run removes"
);
}
#[test]
fn should_hold_a_freshly_modified_artifact_when_min_age_is_set() {
let fixture = tree(&["Cargo.toml", "target/debug/app"]);
let keep = KeepPolicy {
min_age: Some(Duration::from_secs(86_400)),
..KeepPolicy::default()
};
let result = run(&with_keep(fixture.path(), keep)).expect("the run completes");
assert!(result.entries.is_empty(), "a build from a moment ago is not swept");
assert!(fixture.path().join("target").exists());
assert!(matches!(
result.skips[0].reason,
SkipReason::KeptByPolicy { rule: "min_age", .. }
));
}
#[test]
fn should_hold_an_artifact_whose_root_is_old_but_which_is_being_written_inside() {
let fixture = tree(&["Cargo.toml", "target/debug/app"]);
let root = fixture.path().join("target");
let old = std::time::SystemTime::now() - Duration::from_secs(86_400 * 30);
std::fs::File::open(&root)
.expect("the artifact root opens")
.set_modified(old)
.expect("the fixture root can be dated");
let keep = KeepPolicy {
min_age: Some(Duration::from_secs(86_400)),
..KeepPolicy::default()
};
let result = run(&with_keep(fixture.path(), keep)).expect("the run completes");
assert!(
result.entries.is_empty(),
"a build writing below an old target root is not swept: {:?}",
result.entries
);
assert!(fixture.path().join("target/debug/app").exists());
assert!(matches!(
result.skips[0].reason,
SkipReason::KeptByPolicy { rule: "min_age", .. }
));
}
#[test]
fn should_hold_an_artifact_below_min_size() {
let fixture = tree(&["Cargo.toml", "target/debug/app"]);
let keep = KeepPolicy {
min_size: Some(1_000_000_000),
..KeepPolicy::default()
};
let result = run(&with_keep(fixture.path(), keep)).expect("the run completes");
assert!(result.entries.is_empty());
assert!(fixture.path().join("target").exists());
assert!(matches!(
result.skips[0].reason,
SkipReason::KeptByPolicy { rule: "min_size", .. }
));
}
#[test]
fn should_measure_what_it_removes() {
let fixture = tree(&["Cargo.toml", "target/debug/app"]);
let result = run(&options(fixture.path())).expect("the run completes");
assert!(
result.entries[0].bytes > 0,
"a removed artifact reports the space it reclaimed"
);
assert_eq!(result.totals().bytes, result.entries[0].bytes);
}
#[test]
fn should_fail_before_scanning_when_a_root_does_not_exist() {
let mut options = options(std::path::Path::new("/"));
options.roots = vec![PathBuf::from("/no/such/tree")];
assert!(run(&options).is_err());
}
#[test]
#[cfg(unix)]
fn should_not_count_one_tree_twice_when_two_roots_resolve_to_it() {
let fixture = tree(&["real/Cargo.toml", "real/target/app"]);
std::os::unix::fs::symlink(fixture.path().join("real"), fixture.path().join("link")).expect("a symlink");
let mut options = options(fixture.path());
options.dry_run = true;
options.roots = vec![fixture.path().join("real"), fixture.path().join("link")];
let result = run(&options).expect("the run completes");
assert_eq!(result.entries.len(), 1, "one artifact, however many names its root has");
assert_eq!(
result.roots,
vec![fixture.path().join("real")],
"the spelling typed first is the one kept"
);
}
#[test]
#[cfg(unix)]
fn should_keep_the_spelling_typed_first_when_two_roots_alias_one_tree() {
let fixture = tree(&["real/Cargo.toml", "real/target/app"]);
let real = fixture.path().join("real");
let link = fixture.path().join("link");
std::os::unix::fs::symlink(&real, &link).expect("a symlink");
for typed in [vec![link.clone(), real.clone()], vec![real.clone(), link.clone()]] {
let first = typed[0].clone();
let mut options = options(fixture.path());
options.dry_run = true;
options.roots = typed;
let result = run(&options).expect("the run completes");
assert_eq!(
result.roots,
vec![first],
"the order the user typed decides, not the spelling"
);
}
}
#[test]
fn should_collapse_a_chain_of_nested_roots_in_any_order() {
let fixture = tree(&["a/b/c/Cargo.toml"]);
let a = fixture.path().join("a");
let b = fixture.path().join("a/b");
let c = fixture.path().join("a/b/c");
for typed in [
vec![a.clone(), b.clone(), c.clone()],
vec![c.clone(), b.clone(), a.clone()],
vec![b.clone(), c.clone(), a.clone()],
] {
assert_eq!(normalize_roots(&typed).expect("the roots resolve"), vec![a.clone()]);
}
}
#[test]
fn should_keep_sibling_roots_that_share_a_name_prefix() {
let fixture = tree(&["b/Cargo.toml", "bc/Cargo.toml"]);
let roots = vec![fixture.path().join("b"), fixture.path().join("bc")];
assert_eq!(normalize_roots(&roots).expect("the roots resolve"), roots);
}
#[test]
fn should_drop_a_root_nested_inside_another_root() {
let fixture = tree(&["outer/inner/Cargo.toml", "outer/inner/target/app"]);
let mut options = options(fixture.path());
options.dry_run = true;
options.roots = vec![fixture.path().join("outer"), fixture.path().join("outer/inner")];
let result = run(&options).expect("the run completes");
assert_eq!(result.entries.len(), 1);
assert_eq!(
result.roots,
vec![fixture.path().join("outer")],
"the path as typed is kept"
);
}
#[test]
fn should_bound_the_worker_pool_to_the_requested_jobs() {
assert_eq!(build_pool(Some(1)).expect("a pool").current_num_threads(), 1);
assert_eq!(build_pool(Some(3)).expect("a pool").current_num_threads(), 3);
assert!(
build_pool(None).expect("a pool").current_num_threads() > 0,
"no request means available parallelism, not zero threads"
);
}
#[test]
fn should_treat_a_request_for_no_threads_as_a_request_for_one() {
assert_eq!(build_pool(Some(0)).expect("a pool").current_num_threads(), 1);
}
#[test]
fn should_hold_parallel_work_to_the_width_of_the_pool() {
use std::sync::atomic::{AtomicUsize, Ordering};
let pool = build_pool(Some(2)).expect("a pool");
let in_flight = AtomicUsize::new(0);
let peak = AtomicUsize::new(0);
pool.install(|| {
(0..64).into_par_iter().for_each(|_| {
let now = in_flight.fetch_add(1, Ordering::SeqCst) + 1;
peak.fetch_max(now, Ordering::SeqCst);
std::thread::sleep(Duration::from_millis(2));
in_flight.fetch_sub(1, Ordering::SeqCst);
});
});
assert!(peak.load(Ordering::SeqCst) <= 2, "the pool did not bound the work");
}
#[test]
fn should_sweep_identically_however_many_workers_it_is_given() {
let paths = &["a/Cargo.toml", "a/target/app", "b/package.json", "b/dist/app.js"];
let unbounded = tree(paths);
let throttled = tree(paths);
let mut throttled_options = options(throttled.path());
throttled_options.jobs = Some(1);
let wide = run(&options(unbounded.path())).expect("the run completes");
let narrow = run(&throttled_options).expect("the run completes");
assert_eq!(wide.entries.len(), narrow.entries.len());
assert_eq!(snapshot(unbounded.path()), snapshot(throttled.path()));
}
#[test]
#[cfg(unix)]
fn should_drop_a_root_that_symlinks_into_another_root() {
let fixture = tree(&["outer/inner/Cargo.toml", "outer/inner/target/app"]);
let link = fixture.path().join("link");
std::os::unix::fs::symlink(fixture.path().join("outer/inner"), &link).expect("a symlink");
let mut options = options(fixture.path());
options.dry_run = true;
options.roots = vec![fixture.path().join("outer"), link];
let result = run(&options).expect("the run completes");
assert_eq!(result.entries.len(), 1, "one artifact, reached two ways");
assert_eq!(result.roots, vec![fixture.path().join("outer")]);
}
#[test]
fn should_not_sweep_a_valid_root_when_another_root_does_not_exist() {
let fixture = tree(&["Cargo.toml", "target/debug/app"]);
let before = snapshot(fixture.path());
let mut options = options(fixture.path());
options.roots = vec![fixture.path().to_path_buf(), PathBuf::from("/no/such/tree")];
assert!(run(&options).is_err());
assert_eq!(snapshot(fixture.path()), before, "the good root is left untouched");
}
#[test]
fn should_sweep_several_ecosystems_in_one_pass() {
let fixture = tree(&[
"rust/Cargo.toml",
"rust/target/x",
"web/package.json",
"web/dist/x",
"py/pyproject.toml",
"py/.mypy_cache/x",
]);
let result = run(&options(fixture.path())).expect("the run completes");
let mut ecosystems: Vec<_> = result.entries.iter().filter_map(Entry::ecosystem).collect();
ecosystems.sort_unstable();
assert_eq!(ecosystems, vec!["node", "python", "rust"]);
}
}