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
//! 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};
/// 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,
}
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 path = match &error {
ignore::Error::WithPath { path, .. } => Some(path.clone()),
_ => None,
};
// `EINTR` means the read was interrupted by a signal, not that the directory
// could not be read. The walker's callback gives no way to resume the entry, so
// it cannot be retried from here — but it can be told apart from a real failure
// instead of being reported as one.
let transient = error
.io_error()
.is_some_and(|io| io.kind() == std::io::ErrorKind::Interrupted);
let failure = WalkFailure {
path,
message: error.to_string(),
transient,
};
// 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());
if let Some(pattern) = self.options.exclude.matched(path) {
self.note_skip(
sender,
path,
SkipReason::Excluded {
pattern: pattern.to_owned(),
},
);
return 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 WalkState::Skip;
}
// A named cache is checked before the blanket skip below, so `--clean-caches uv`
// reaches `~/.cache/uv` without `--caches` having to open 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, 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 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, sender);
}
self.note_skip(sender, path, SkipReason::ToolCache);
return WalkState::Skip;
}
// 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(entry.file_name(), path, is_symlink)
{
let _ = sender.send(Message::Repository(work_tree.to_path_buf()));
}
if is_dir && is_never_descended(entry.file_name()) {
return WalkState::Skip;
}
if is_dir && is_dependency_dir(entry.file_name()) {
self.visit_dependency_dir(entry.file_name(), path, sender);
return WalkState::Skip;
}
// 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 WalkState::Skip;
}
}
Verdict::Skip(reason) => self.note_skip(sender, path, reason),
Verdict::NotACandidate => {}
}
WalkState::Continue
}
/// 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, sender: &mpsc::Sender<Message>) {
if !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 one voom neither enters nor classifies.
fn is_never_descended(name: &OsStr) -> bool {
NEVER_DESCEND.iter().any(|never| name == OsStr::new(never))
}