voom 0.14.1

Fast, safe, parallel build-artifact pruning across every major language ecosystem
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
//! The pipeline: `scan -> classify -> policy -> size -> delete -> report`.
//!
//! Each stage is a function of the previous one's output. `--dry-run` is this same pipeline
//! with the deleter's final step withheld (ADR 0006) — there is no second code path, so a dry
//! run cannot disagree with a real one.
//!
//! Roots are swept one at a time because configuration, containment and the marker-climb bound
//! are all evaluated relative to the root an entry came from. Within a root everything is
//! parallel.

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;

/// Everything one invocation needs.
#[expect(
    clippy::struct_excessive_bools,
    reason = "these mirror command-line flags, which are bools by nature"
)]
#[derive(Debug, Clone)]
pub struct RunOptions {
    /// Trees to sweep.
    pub roots: Vec<PathBuf>,
    /// Withhold the removal and report what would happen.
    pub dry_run: bool,
    /// Worker threads; `None` means available parallelism.
    pub jobs: Option<usize>,
    /// Stay on the scan root's filesystem.
    pub one_file_system: bool,
    /// Retry a failed removal, repairing permissions inside the artifact first.
    pub force: bool,
    /// Record why candidates were passed over.
    pub verbose: bool,
    /// `--config`, which replaces the discovered hierarchy.
    pub config: Option<PathBuf>,
    /// Command-line overrides, which sit above every configuration layer.
    pub flags: Flags,
    /// Show a scan spinner. Suppressed automatically when stderr is not a terminal, so a
    /// piped or redirected run is never contaminated by it (ADR 0007).
    pub progress: bool,
}

/// Accumulates one root's results into the run's.
#[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>,
    // Accumulated across roots: each root runs the whole pipeline, so a two-root run has two
    // scan phases and the user wants the time the stage cost them, not the time one of them did.
    scan: Duration,
    policy: Duration,
    size: Duration,
    delete: Duration,
    git_elapsed: Duration,
}

/// Runs the whole pipeline.
///
/// # Errors
///
/// [`Error::ReadDir`] if a scan root cannot be resolved — a root that does not exist is a usage
/// error and must stop the run before anything is removed — [`Error::Config`] for a broken
/// configuration file, [`Error::CatalogPattern`] for an exclusion glob that will not compile, or
/// [`Error::ThreadPool`] if `-j` asks for a pool that cannot be built.
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);

    // Sizing and removal fan out over rayon, which otherwise runs on a process-wide pool sized
    // to every logical core. `-j` is the escape hatch for spinning disks and network
    // filesystems (ADR 0005), so it has to bound the removal storm and not just the walk.
    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)
}

/// Builds the worker pool that sizes and removes artifacts.
///
/// Scoped rather than [`rayon::ThreadPoolBuilder::build_global`], which is process-wide and
/// one-shot: a second call fails, so a global pool would break both the test suite and any
/// program that uses voom as a library and has its own pool.
///
/// # Errors
///
/// [`Error::ThreadPool`] if the pool cannot be built.
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 })
}

/// How many workers size and remove when `-j` is not given.
///
/// Sizing and removal are a `getattrlistbulk` or `unlinkat` per directory and spend their time
/// waiting on the filesystem, so a worker per core leaves it idle between requests — the same
/// argument the walk makes for oversubscribing (`scan::walker_threads`). Measured over twenty
/// Bazel output bases under two endpoint-security agents: 334 s on eighteen workers, 162 s on
/// sixty-four, 143 s on a hundred and twenty-eight.
///
/// That measurement is a Bazel stage on a filesystem that answers in parallel. On a spinning disk
/// or a network filesystem oversubscription is the wrong default, which is exactly what `-j`
/// exists to set; this is the width only when the flag is absent — and it is additionally held
/// under the descriptor limit, because a worker that cannot open a file is not a worker
/// (`crate::limits`).
fn io_threads() -> usize {
    crate::limits::default_width()
}

/// Resolves the roots to their real locations, drops duplicates, and drops any root that sits
/// inside another.
///
/// On macOS `/tmp` is a symlink to `/private/tmp`, so `voom /tmp /private/tmp` walks one tree
/// twice and reports every artifact — and every byte — twice over. The same happens for
/// `voom ~ ~/projects`. voom deletes without asking and the report is the only record of what
/// it did, so a doubled total is a correctness bug rather than a cosmetic one.
///
/// # Errors
///
/// [`Error::ReadDir`] if a root cannot be resolved. A root that does not exist is a usage error
/// and must stop the run before anything is removed.
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));
    }

    // Sorting on the canonical path puts an ancestor before everything nested inside it
    // whatever order they were typed in, which is what makes one pass over `kept` sufficient.
    // The index breaks ties, so when two spellings name the same tree the one the user typed
    // first is the one that survives — see the note below on why the choice is visible.
    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));
    }

    // The *original* spelling is what gets walked. Deduplication has to reason about where a
    // root really is, but the walk must not: a user's `exclude = ["/tmp/build/**"]` is written
    // against the path they typed, and silently rewriting it to `/private/tmp/...` would stop
    // the glob matching — an exclusion that quietly stops working is the exact failure ADR 0004
    // exists to prevent.
    //
    // Which is also why the tie-break above is not arbitrary. Exclusion globs are matched
    // textually against the walked path, so of two spellings of one tree only the surviving
    // one's globs keep working. Taking the first the user typed makes that choice predictable
    // instead of alphabetical.
    Ok(kept.into_iter().map(|(_, index)| roots[index].clone()).collect())
}

/// Resolves the configuration that governs one scan root.
///
/// # Errors
///
/// [`Error::Config`] if a configuration file is missing, unreadable, or invalid.
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)?;
    // Progress goes to stderr so it never contaminates piped stdout, and only when stderr is a
    // terminal — a redirected run gets nothing.
    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;

    // Git's own local housekeeping over the repositories the walk already passed (ADR 0011).
    // It runs on this pool, never fails the sweep — a machine without git simply has nothing to
    // do here — and says nothing in the report when it did nothing.
    collected.repositories.extend(scanned.repositories.iter().cloned());

    // Git's housekeeping is a process per repository and the slowest stage once the walk is
    // wide; sizing and removal touch artifacts and never a repository's administration. Neither
    // needs the other's result, so they overlap on the same pool.
    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);

            // Removal is independent per artifact and embarrassingly parallel; a failure on one is
            // recorded and never aborts the run.
            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(())
}

/// The walk's options for one scan root, from the run's flags and the configuration at the root.
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),
        // Always: the walk passes them anyway, and merged-worktree removal (opt-in) needs them
        // whether or not git housekeeping is on.
        collect_repositories: true,
        clean_tagged: at_root.clean_tagged,
        guide_repositories: true,
    })
}

/// Splits the artifacts an outer removal was expected to take into those it did take, which are
/// reported as covered, and those that must be removed after all, which are returned.
fn settle_covered(
    covered: Vec<(Finding, Option<Measured>, PathBuf)>,
    entries: &[Entry],
    options: &RunOptions,
    collected: &mut Collected,
) -> Vec<(Finding, Option<Measured>)> {
    // A covered artifact is only *covered* if the removal that was supposed to take it actually
    // happened. Deciding that before the rails run would let a refused `vendor/` leave its
    // `vendor/bundle/` neither removed nor reported as removable, on every subsequent run —
    // a skip line asserting something that never took place. Nesting is rare, so this second
    // pass is almost always empty.
    //
    // `PartiallyRemoved` counts as covered even though it is not `is_reclaimed`: the outer
    // removal *ran*, its `freed` already counts whatever it took out of the inner artifact, and
    // retrying on the pre-removal size would report those bytes a second time. Only a removal
    // that never happened at all sends the inner one back.
    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
}

/// Runs git's own housekeeping over the repositories the walk passed.
///
/// Never fails the sweep. A machine with no git, or a tree with no repositories, simply produces
/// nothing — this is not the command the user asked for, and failing their artifact sweep over
/// it would be the wrong trade. Per-repository failures are carried in the result and reported.
///
/// # Errors
///
/// [`Error::CatalogPattern`] if the configured `exclude` will not compile, which is the same
/// error the scan would already have raised for it.
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);
    }

    // Timed from here rather than around the call, so a run that never asked for housekeeping
    // reports no git stage at all instead of a few hundred nanoseconds of deciding not to.
    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())?,
        // Deliberately not `jobs`: this runs on the ambient pool, which `run` already built to
        // honour `-j`. Setting it here would nest a second pool inside that one.
        ..crate::git::GitPruneOptions::default()
    };
    Ok(crate::git::prune_during_sweep(work_trees, &git_options).map(|pruned| (pruned, started.elapsed())))
}

/// Which ecosystems the classifier will consider, always permissively.
///
/// An off-by-default artifact must still be *found*, because a `voom.toml` deeper in the tree
/// may turn it on. The real decision is made in [`select`], against the configuration resolved
/// at each artifact's own location.
///
/// # Errors
///
/// [`Error::UnknownEcosystem`] if `--ecosystems` names one the catalog does not ship.
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())
}

/// Removes each artifact, in parallel, recording an outcome per artifact.
fn remove_all(mut to_remove: Vec<(Finding, Option<Measured>)>, guard: &Guard, removal: Removal) -> Vec<Entry> {
    // Prefer larger artifacts when a policy or dry run already measured them. Other artifacts
    // are counted during removal instead of walking them first merely to choose their order.
    to_remove.sort_by_key(|(_, measured)| std::cmp::Reverse(measured.map_or(0, |size| size.bytes)));
    // The whole fan-out runs inside the removal pool, so every artifact's task is a removal worker
    // and none parks a sizing worker to install into the pool it is already using.
    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()
    })
}

/// The removal settings for one finding: a cache its tool writes read-only is removed with its
/// owner bits restored, as the tool's own clean command does, whether or not `--force` was given.
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,
    }
}

/// A live count of the bytes removal has freed, across every stage of the process, or nothing
/// when it would be noise.
///
/// Removal is the long stage of a real run — on a machine whose endpoint-security agents vet
/// every unlink, tens of millions of files take hours — and a spinner alone says only that
/// something is still happening.
#[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)
}

/// A spinner for the scan phase, or nothing when it would be noise.
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,
    }
}

/// Records a skip, keeping only the count unless detail was asked for.
fn note(collected: &mut Collected, verbose: bool, path: PathBuf, reason: SkipReason) {
    collected.skipped_count += 1;
    if verbose {
        collected.skips.push(Skipped { path, reason });
    }
}

/// Helpers shared by this module's test suites.
#[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"]);
    }

    /// The whole point, end to end: an unproven `target/` is left exactly where it is.
    #[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());
    }

    /// `/tmp` is a symlink to `/private/tmp` on macOS, so naming both walked one tree twice and
    /// reported every byte twice. Found by running voom against a real machine.
    #[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"
        );
    }

    /// Which spelling survives is not cosmetic: exclusion globs are matched textually against
    /// the walked path, so only the surviving spelling's globs keep working.
    #[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"
            );
        }
    }

    /// Sorting is what lets a single pass over the survivors collapse a chain, so the order the
    /// roots arrive in must not matter.
    #[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()]);
        }
    }

    /// Two roots that share a name prefix but not a parent are not duplicates. `Path::starts_with`
    /// is component-wise, so `a/bc` is not inside `a/b` — this pins that it stays that way.
    #[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);
    }

    /// `voom ~ ~/projects` is the same problem without a symlink.
    #[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"
        );
    }

    /// `-j` bounded the walk but not the rayon fan-out that sizes and removes, so `-j 2` on a
    /// network filesystem meant a throttled walk followed by a full-core removal storm.
    #[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"
        );
    }

    /// `-j 0` is a plausible typo for "no limit"; it must not mean "no workers".
    #[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);
    }

    /// The thread count alone would be satisfied by a pool nothing runs in, so this checks that
    /// work sent through it is actually held to that width.
    #[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");
    }

    /// Throttling changes how fast the work happens, never what it does.
    #[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()));
    }

    /// The reviewer's case: one root reached through a symlink that lands *inside* another.
    /// It is a duplicate, not a sibling, and the sort has to see that before the prefix filter
    /// can drop it.
    #[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")]);
    }

    /// The doc comment promises a bad root stops the run before anything is removed. With one
    /// root that is vacuous; with two it is the property that matters.
    #[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"]);
    }
}