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
//! The per-entry decision, made on whichever worker thread produced the entry.
//!
//! Every branch here either prunes a subtree or emits one message; nothing accumulates, and
//! nothing allocates on the path that rejects an ordinary entry. The order of the checks is the
//! order of authority — `exclude` outranks `include`, which outranks every prune — and it is
//! load-bearing, not incidental.

use std::ffi::OsStr;
use std::path::{Path, PathBuf};
use std::sync::mpsc;

use ignore::WalkState;

use super::{Message, NEVER_DESCEND, ScanOptions, Skipped, WalkFailure};
use crate::classify::{Classifier, Finding, Provenance, SkipReason, Verdict, is_dependency_dir};

/// The path a walk error is about, however deeply the walker wrapped it.
///
/// The walker nests a path inside a depth marker, so matching only the outermost variant
/// returns nothing for exactly the read failures that carry one — and the report then had the
/// path only inside the message text.
fn failing_path(error: &ignore::Error) -> Option<PathBuf> {
    match error {
        ignore::Error::WithPath { path, .. } => Some(path.clone()),
        ignore::Error::WithDepth { err, .. } | ignore::Error::WithLineNumber { err, .. } => failing_path(err),
        ignore::Error::Loop { child, .. } => Some(child.clone()),
        ignore::Error::Partial(errors) => errors.iter().find_map(failing_path),
        _ => None,
    }
}

/// Classifies one entry per call, from whichever worker thread produced it.
#[derive(Clone, Copy)]
pub(super) struct Visitor<'a> {
    pub(super) root: &'a Path,
    pub(super) classifier: &'a Classifier,
    pub(super) options: &'a ScanOptions,
    /// Whether work trees under this root are walked from their index (`super::guided`).
    pub(super) guide: bool,
}

impl Visitor<'_> {
    pub(super) fn visit(
        &self,
        result: std::result::Result<ignore::DirEntry, ignore::Error>,
        sender: &mpsc::Sender<Message>,
    ) -> WalkState {
        let entry = match result {
            Ok(entry) => entry,
            Err(error) => {
                let kind = error.io_error().map(std::io::Error::kind);
                // `EINTR` means the read was interrupted by a signal, not that the directory
                // could not be read; `scan_root` walks such a directory again before it is
                // reported at all. `EPERM` and `EACCES` both surface as `PermissionDenied`.
                let failure = WalkFailure {
                    path: failing_path(&error),
                    message: error.to_string(),
                    transient: kind == Some(std::io::ErrorKind::Interrupted),
                    inaccessible: kind == Some(std::io::ErrorKind::PermissionDenied),
                };
                // Sends cannot fail here: `scan_root` owns the `Receiver` and holds it until
                // `WalkBuilder::run` returns, which is after every worker has finished. The
                // same is true of the other sends in this file.
                let _ = sender.send(Message::Failure(Box::new(failure)));
                return WalkState::Continue;
            }
        };

        // Depth 0 is the scan root itself, which is never a candidate for its own removal.
        if entry.depth() == 0 {
            return WalkState::Continue;
        }

        let path = entry.path();
        // `file_type()` is what the walker already knows; a `metadata()` call here would cost
        // an extra syscall on every entry in the tree.
        let file_type = entry.file_type();
        let is_dir = file_type.is_some_and(|file_type| file_type.is_dir());
        let is_symlink = file_type.is_some_and(|file_type| file_type.is_symlink());
        self.decide(path, entry.file_name(), is_dir, is_symlink, true, sender)
    }

    /// Decides one entry: prune it, descend it, or hand it to the index-guided walk.
    ///
    /// Shared by the directory walk and by [`super::guided`], which offers it the entries a
    /// repository's index cannot vouch for and the tracked directories it descends, so both
    /// walks answer every entry identically. `may_guide` is false for a tracked directory, which
    /// is never a work tree of its own and is not worth the `lstat` that would ask.
    pub(super) fn decide(
        &self,
        path: &Path,
        name: &OsStr,
        is_dir: bool,
        is_symlink: bool,
        may_guide: bool,
        sender: &mpsc::Sender<Message>,
    ) -> WalkState {
        // voom's own trash holds artifacts that have already passed every rail and are being freed
        // by the reaper; walking it would only find them again. Compared by name first, so the
        // path comparison runs on a handful of directories rather than on every one.
        if is_dir && is_trash(name, path) {
            return WalkState::Skip;
        }

        if let Some(state) = self.decide_by_configuration(path, sender) {
            return state;
        }

        if let Some(state) = self.decide_by_cache(path, is_dir, sender) {
            return state;
        }

        // Git housekeeping discovers repositories here, at the moment the walker meets `.git`
        // and is about to prune it: one name comparison, no syscall (ADR 0011). A second walk
        // over `$HOME` to find the same directories would roughly double the run, which is the
        // whole reason this is a line in the artifact walk rather than a pass of its own.
        //
        // It does not return: the prune below still refuses to descend into a `.git` directory,
        // and a `.git` *file* — a linked worktree or a submodule — falls through to the
        // classifier, which has nothing to say about it.
        if self.options.collect_repositories
            && let Some(work_tree) = crate::git::repository_at(name, path, is_symlink)
        {
            let _ = sender.send(Message::Repository(work_tree.to_path_buf()));
        }

        if let Some(state) = self.decide_by_name(name, path, is_dir, sender) {
            return state;
        }

        if let Some(state) = self.decide_by_verdict(path, is_dir, is_symlink, sender) {
            return state;
        }

        // A work tree is walked from its index instead (`super::guided`): one `lstat` here, so
        // that its tracked directories cost one more each rather than an `open` and a listing.
        if may_guide && self.guide && is_dir && super::guided::is_work_tree(path) {
            let _ = sender.send(Message::Guide(path.to_path_buf()));
            return WalkState::Skip;
        }

        WalkState::Continue
    }

    /// The user's own `exclude` and `include` patterns, which outrank every other rule here.
    ///
    /// `exclude` first, because ADR 0004 makes it absolute. `None` means neither pattern matched.
    fn decide_by_configuration(&self, path: &Path, sender: &mpsc::Sender<Message>) -> Option<WalkState> {
        if let Some(pattern) = self.options.exclude.matched(path) {
            self.note_skip(
                sender,
                path,
                SkipReason::Excluded {
                    pattern: pattern.to_owned(),
                },
            );
            return Some(WalkState::Skip);
        }

        // `include` outranks every prune below but never `exclude`, which ADR 0004 makes
        // absolute. That ordering lets an explicit include *name* a directory the walk would
        // otherwise prune — a dependency directory or a tool cache, both of which ADR 0001
        // keeps out of the catalog and says configuration is the one way to reach.
        //
        // It does not let one reach *inside* such a directory: pruning is what makes the walk
        // fast, and once the walk declines to descend nothing below is offered to any matcher.
        // `.git` stays unreachable either way — the deletion guard refuses a VCS directory by
        // name whatever produced it.
        if let Some(pattern) = self.options.include.matched(path) {
            let finding = Finding {
                path: path.to_path_buf(),
                provenance: Provenance::Included {
                    pattern: pattern.to_owned(),
                },
            };
            let _ = sender.send(Message::Found(Box::new(finding)));
            return Some(WalkState::Skip);
        }

        None
    }

    /// The tool-cache rules: a named cache the run asked for, then the blanket skip of cache roots.
    ///
    /// `None` means `path` is not a cache location and the decision continues.
    fn decide_by_cache(&self, path: &Path, is_dir: bool, sender: &mpsc::Sender<Message>) -> Option<WalkState> {
        // A named cache is checked before the blanket skip below, so `--clean-caches=uv`
        // reaches `~/.cache/uv` without opening every cache location at once. The marker still
        // has to prove it (ADR 0012): the id says which directory to look at, never that it may
        // go.
        if is_dir && let Some(cache) = self.options.caches.removable(path) {
            self.visit_named_cache(path, cache, true, sender);
            // Skipped either way: a cache is an indivisible unit like any other artifact, and
            // one that failed its marker check is still somewhere a walk must not wander.
            return Some(WalkState::Skip);
        }

        // After `exclude`, which ADR 0004 makes absolute, and before anything that could
        // classify: an installed toolchain is shaped exactly like a project, so the classifier
        // would prove it correctly and take it (ADR 0001).
        if is_dir && self.options.caches.contains(path) {
            // A named cache underneath is still reached, by naming rather than by walking.
            // The prune below is unchanged, so nothing else in here is enumerated or
            // classified — see `CacheRoots::removable_inside`.
            for (cache_path, cache) in self.options.caches.removable_inside(path) {
                self.visit_named_cache(cache_path, cache, false, sender);
            }
            self.note_skip(sender, path, SkipReason::ToolCache);
            return Some(WalkState::Skip);
        }

        None
    }

    /// Directories pruned by name alone: never-descended ones, then dependency directories.
    ///
    /// `None` means the name carries no prune and the decision continues.
    fn decide_by_name(
        &self,
        name: &OsStr,
        path: &Path,
        is_dir: bool,
        sender: &mpsc::Sender<Message>,
    ) -> Option<WalkState> {
        if is_dir && is_never_descended(name) {
            return Some(WalkState::Skip);
        }

        if is_dir && is_dependency_dir(name) {
            self.visit_dependency_dir(name, path, sender);
            return Some(WalkState::Skip);
        }

        None
    }

    /// Classifies `path` and reports what the classifier found.
    ///
    /// `Some(Skip)` when the entry is pruned, `None` when the walk goes on past it.
    fn decide_by_verdict(
        &self,
        path: &Path,
        is_dir: bool,
        is_symlink: bool,
        sender: &mpsc::Sender<Message>,
    ) -> Option<WalkState> {
        // A symlink is classified as though it were a directory so a symlinked `target/` is
        // *seen* rather than silently invisible. It can never become a deletion — the deletion
        // guard refuses to remove through a link (ADR 0006) — but it is reported as a finding
        // the guard then refuses, not folded into the anonymous skip count. A refusal names the
        // path in the artifacts block; a skip is a number unless `-v` was passed, and a
        // symlinked `target/` beside a real `Cargo.toml` is exactly the thing a reader wants
        // told about.
        match self.classifier.classify(self.root, path, is_dir || is_symlink) {
            Verdict::Artifact(finding) => {
                let _ = sender.send(Message::Found(Box::new(finding)));
                // A matched artifact is an indivisible unit: it is sized and removed wholesale,
                // so walking inside it is wasted work and would produce nested findings that
                // make the report unreadable. A symlink is not descended for the older reason:
                // the walker does not follow links at all.
                if is_dir || is_symlink {
                    return Some(WalkState::Skip);
                }
            }
            // An `Inside` anchor that found no marker is the one skip worth pruning on. The
            // directory carries the name of a self-declaring cache and does not carry the
            // declaration — so it is either an older cache of that tool or somebody else's
            // directory, and in both cases voom has already decided not to remove it. Walking
            // it can only turn up *other* projects, and measured over one home directory it
            // turned up none at all while generating 181 of 2305 skips and taking the scan from
            // 1.3 s to 7.7 s. Pruning is a recall trade, never a safety one, and this one was
            // measured before it was made.
            Verdict::Skip(reason) => {
                // The tagged check runs only where the catalog declined. An anchored verdict is
                // more specific — it names an ecosystem and an artifact a reader can act on —
                // so `target/` beside a `Cargo.toml` stays Rust's even though Cargo also tags it.
                if self.take_if_tagged(path, is_dir, sender) {
                    return Some(WalkState::Skip);
                }
                // ~keep The `NoInnerMarker` prune above is a measured 6x win, and `--clean-tagged`
                // has to give it up. The prune's premise is that an unproven self-declaring cache
                // holds nothing worth looking for; a run that asked for tagged directories has
                // said the opposite, and the directory one level down is exactly where the field
                // case lived — alef tagged `.alef/snippets/` and not `.alef/`, so pruning at
                // `.alef/` hid 18.86 GB (see the correction to ADR 0012). The cost is bounded: it
                // applies only to directories named like an `Inside`-anchored entry, of which a
                // real tree has a handful.
                let prune = is_dir && !self.options.clean_tagged && matches!(reason, SkipReason::NoInnerMarker { .. });
                self.note_skip(sender, path, reason);
                if prune {
                    return Some(WalkState::Skip);
                }
            }
            Verdict::NotACandidate => {
                self.note_if_tagged_skipped(path, is_dir, sender);
                if self.take_if_tagged(path, is_dir, sender) {
                    return Some(WalkState::Skip);
                }
            }
        }

        None
    }

    /// Reports a self-declaring directory the run did not ask to remove.
    ///
    /// Only where skips are collected: the probe is one `symlink_metadata` and a short read per
    /// directory, which is affordable in a verbose run and not in the default one. Nothing is
    /// pruned on this path — a tagged directory may still hold a catalog artifact, and pruning
    /// it would make `--verbose` change what the run finds.
    fn note_if_tagged_skipped(&self, path: &Path, is_dir: bool, sender: &mpsc::Sender<Message>) {
        if self.options.clean_tagged || !self.options.collect_skips || !is_dir || !crate::tagged::is_tagged(path) {
            return;
        }
        self.note_skip(sender, path, SkipReason::TaggedNotEnabled);
    }

    /// Claims `path` when the run asked for tagged directories and this one declares itself.
    ///
    /// Returns whether the caller must prune. Pruning is the whole point: a tagged directory is
    /// an indivisible unit like every other artifact, and descending one is how voom currently
    /// spends the traversal of a 19 GB relocated `CARGO_TARGET_DIR` to report nothing at all.
    ///
    /// ~keep A symlink is never probed. Reading `link/CACHEDIR.TAG` would resolve through the
    /// link, which is the one thing voom does not do anywhere — and a symlinked artifact could
    /// not be removed afterwards regardless (ADR 0006). So unlike a named artifact, a symlinked
    /// tagged directory is not reported-then-refused: there is no way to learn it was tagged
    /// without doing the thing the rail forbids. `is_dir` is already false for a symlink, since
    /// the walker does not follow links; the check is named here so nobody later "fixes" it by
    /// widening the condition.
    fn take_if_tagged(&self, path: &Path, is_dir: bool, sender: &mpsc::Sender<Message>) -> bool {
        if !self.options.clean_tagged || !is_dir || !crate::tagged::is_tagged(path) {
            return false;
        }
        // uv tags every virtualenv it creates, its tool installs included, so the tag alone
        // would take `~/.local/share/uv/tools/<tool>` — an installed command, not a cache. A
        // tagged directory holding `pyvenv.cfg` is left to the catalog, where a project's
        // `.venv` is the opt-in `python.venv` and an installed tool is nobody's to remove.
        if crate::tagged::is_virtualenv(path) {
            return false;
        }
        let finding = Finding {
            path: path.to_path_buf(),
            provenance: Provenance::Tagged,
        };
        let _ = sender.send(Message::Found(Box::new(finding)));
        true
    }

    /// Decides what a dependency directory is, without ever entering it.
    ///
    /// ~keep The caller prunes unconditionally on return, and that is not negotiable: declining
    /// to enumerate `node_modules/` is where essentially all of the walk's wall-clock saving
    /// comes from. What this adds is one classification of the *directory itself*, which costs
    /// at most a single memoized `read_dir` of its anchor — a directory the classifier has
    /// almost always listed already for the artifacts beside it — and never touches an entry
    /// below. `should_not_enumerate_inside_an_enabled_dependency_directory` pins both halves.
    ///
    /// Classification runs whether or not the artifact is enabled, because the enable decision
    /// belongs to the classifier and to the configuration resolved at the artifact's own
    /// directory (ADR 0004) — the walker does not get a second opinion on it. With the opt-in
    /// off, the verdict is a `NotEnabled` skip that says which spec would turn it on.
    fn visit_dependency_dir(&self, name: &OsStr, path: &Path, sender: &mpsc::Sender<Message>) {
        // The inside-check runs on every verdict, including `Artifact`. The classifier here is
        // permissive (`run.rs` builds it that way so a deeper `voom.toml` can still turn an
        // artifact on), so an `Artifact` verdict means "this could be taken", not "this will
        // be" — and skipping the check on it lost Ruby's `vendor/bundle/` on any tree that also
        // had a `composer.json` beside the same `vendor/`. Whether the outer directory is
        // actually taken is decided in `run.rs`, which also drops a finding the outer one
        // covers, so nothing is counted twice.
        self.check_inside_dependency(name, path, sender);
        match self.classifier.classify(self.root, path, true) {
            Verdict::Artifact(finding) => {
                let _ = sender.send(Message::Found(Box::new(finding)));
            }
            Verdict::Skip(reason) => self.note_skip(sender, path, reason),
            Verdict::NotACandidate => {}
        }
    }

    /// Classifies the specific paths the catalog declares inside a dependency directory.
    ///
    /// Nothing else below is walked: this constructs the declared paths directly and then the
    /// caller prunes, so a `node_modules/` with a hundred thousand entries still costs nothing.
    fn check_inside_dependency(&self, name: &OsStr, dir: &Path, sender: &mpsc::Sender<Message>) {
        for id in self.classifier.artifacts_inside(name) {
            let artifact = id.artifact();
            // The first segment is the dependency directory itself, which is `dir`.
            let relative: PathBuf = artifact.segments().skip(1).collect();
            let candidate = dir.join(relative);
            let Ok(metadata) = std::fs::symlink_metadata(&candidate) else {
                continue;
            };
            // Same rule as the walk above: a symlinked artifact is reported and then refused,
            // never quietly counted.
            let is_dir = metadata.is_dir() || metadata.file_type().is_symlink();
            match self.classifier.classify(self.root, &candidate, is_dir) {
                Verdict::Artifact(finding) => {
                    let _ = sender.send(Message::Found(Box::new(finding)));
                }
                Verdict::Skip(reason) => self.note_skip(sender, &candidate, reason),
                Verdict::NotACandidate => {}
            }
        }
    }

    /// Records a passed-over candidate, keeping only the count unless detail was asked for.
    /// Emits one named cache as a finding, or as the reason it was not one.
    ///
    /// The id says which directory to look at; the marker says whether it may go (ADR 0012). A
    /// location that does not exist on this machine says nothing at all — the table is written
    /// for every machine, and most entries are absent on any given one.
    fn visit_named_cache(
        &self,
        path: &Path,
        cache: &'static crate::caches::Cache,
        known_dir: bool,
        sender: &mpsc::Sender<Message>,
    ) {
        // The walk has already typed the entry at the call site that walked it; only the path
        // constructed inside a pruned cache root has to be stat'ed.
        if !known_dir && !path.is_dir() {
            return;
        }
        if cache.proven_in(path) {
            let finding = Finding {
                path: path.to_path_buf(),
                provenance: Provenance::Cache { cache },
            };
            let _ = sender.send(Message::Found(Box::new(finding)));
        } else {
            self.note_skip(
                sender,
                path,
                SkipReason::NoInnerMarker {
                    ecosystem: cache.id,
                    markers: cache.markers,
                },
            );
        }
    }

    fn note_skip(&self, sender: &mpsc::Sender<Message>, path: &Path, reason: SkipReason) {
        let message = if self.options.collect_skips {
            Message::Skipped(Box::new(Skipped {
                path: path.to_path_buf(),
                reason,
            }))
        } else {
            Message::SkippedCount
        };
        let _ = sender.send(message);
    }
}

/// Whether a directory is voom's own trash.
fn is_trash(name: &OsStr, path: &Path) -> bool {
    name == OsStr::new("trash")
        && crate::delete::trash_location()
            .is_some_and(|trash| path == trash || path.canonicalize().is_ok_and(|resolved| resolved == trash))
}

/// Whether a directory is one voom neither enters nor classifies.
fn is_never_descended(name: &OsStr) -> bool {
    NEVER_DESCEND.iter().any(|never| name == OsStr::new(never))
}