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
//! Named tool caches that `--clean-caches` can remove.
//!
//! [`CACHE_DIRS`](super::CACHE_DIRS) says where a walk must not go. This table says which of
//! those places can be *emptied*, and on what evidence. The two are deliberately separate: the
//! first is a rule about wandering, the second is a rule about proof.
//!
//! # Why a second table rather than catalog entries
//!
//! A cache cannot be classified the way `target/` is. Nothing beside `~/.cargo/registry` says
//! what it is — its siblings under `~/.cargo` are unrelated — and `~/.cache/uv` sits next to
//! `zig`, `huggingface` and whatever else the machine has. There is no marker to anchor on and
//! there never will be. The name is no help either: `registry`, `caches`, `mod` and `_cacache`
//! are not names voom could match anywhere on a disk without matching a great deal it must not
//! touch.
//!
//! What identifies a cache is the pair: a **location** that names the tool, and a **marker the
//! tool wrote inside it**. `CACHEDIR.TAG`, whose
//! [specification](https://bford.info/cachedir/) says the directory holds data the application
//! can regenerate, is the cross-tool spelling of exactly this and is already present in four of
//! the entries below. The rest use a file or directory that only that tool creates.
//!
//! # The bar for an entry
//!
//! Both halves must be unambiguous, and the marker must carry weight the location does not. A
//! cache whose only contents are shard directories named `0`–`f` or `a`–`z` fails that: the
//! marker proves nothing the path did not already say, so there is no evidence to weigh and the
//! entry is not shipped. See ADR 0012 for the ones this excludes and how much they hold.
//!
//! Nothing here is ever on by default, and nothing here is reachable without naming it.

/// One removable tool cache: where it lives, and what proves it is one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Cache {
    /// The id `--clean-caches` and `voom.toml` name it by.
    pub id: &'static str,
    /// Human label for `--list-caches`.
    pub name: &'static str,
    /// Locations relative to the user's home directory. Several when a tool's cache moved or
    /// differs by platform; every one of them must satisfy `markers` on its own.
    pub locations: &'static [&'static str],
    /// Paths that must appear *inside* the directory for it to be one, each relative to it and
    /// optionally behind a `*/` for "in any immediate subdirectory". Any one is enough, and an
    /// empty list is rejected at construction time.
    pub markers: &'static [&'static str],
    /// What removing it costs, printed by `--list-caches`. Always a re-download or a rebuild,
    /// never lost work — an entry that cannot say so does not belong here.
    pub note: &'static str,
    /// Whether a bare `--clean-caches` (or `all`) includes it. Off for a cache whose loss is
    /// expensive rather than merely slow — gigabytes that a metered or absent network cannot
    /// replace — so it is removed only by naming it.
    pub in_all: bool,
    /// Whether the tool writes the cache read-only by design, as Go does its module cache.
    /// Removal then restores the owner's bits inside it first — what the tool's own clean
    /// command does (`go clean -modcache`) — instead of failing part-way unless `--force`.
    pub read_only: bool,
}

impl Cache {
    /// Whether the directory holds one of this entry's markers.
    ///
    /// A marker is a plain relative path, checked with one `lstat`; a leading `*/` means "in any
    /// immediate subdirectory", for tools that write their bookkeeping into a version directory
    /// whose name they choose (`node-gyp/<node-version>/installVersion`). The wildcard costs one
    /// `read_dir` of the candidate and is affordable for the same reason [`Anchor::Inside`]
    /// resolution is: a cache location is reached at most once in a walk, and the walker prunes
    /// it rather than enumerating it. Nothing is allocated per entry and a non-UTF-8 name cannot
    /// be mistaken for a match.
    ///
    /// An unreadable directory answers `false`: nothing proved it, which is the safe direction.
    ///
    /// [`Anchor::Inside`]: crate::catalog::Anchor::Inside
    #[must_use]
    pub fn proven_in(&self, dir: &std::path::Path) -> bool {
        self.markers.iter().any(|marker| match marker.strip_prefix("*/") {
            Some(inner) => std::fs::read_dir(dir).is_ok_and(|entries| {
                entries
                    .flatten()
                    .any(|entry| entry.file_type().is_ok_and(|kind| kind.is_dir()) && exists(&entry.path().join(inner)))
            }),
            None => exists(&dir.join(marker)),
        })
    }
}

/// Whether anything, a dangling link included, is named by `path`.
fn exists(path: &std::path::Path) -> bool {
    std::fs::symlink_metadata(path).is_ok()
}

/// Every cache `--clean-caches` knows about.
///
/// Ids are stable: they appear in `voom.toml` and in `--clean-caches`, so one may be added but
/// not renamed. Sizes in the comments are what one workstation held on 2026-08-29, recorded so
/// a later reader can tell a big entry from a rounding error.
pub static CACHES: &[Cache] = &[
    Cache {
        id: "cargo-registry",
        name: "Cargo registry",
        locations: &[".cargo/registry"],
        markers: &["CACHEDIR.TAG"],
        note: "Crate sources and their index. Re-downloaded on the next build; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "cargo-git",
        name: "Cargo git checkouts",
        locations: &[".cargo/git"],
        markers: &["CACHEDIR.TAG"],
        note: "Checkouts of git dependencies. Re-cloned on the next build; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "uv",
        name: "uv",
        locations: &[".cache/uv"],
        markers: &["CACHEDIR.TAG"],
        note: "Wheels and built distributions. `uv cache prune` removes only the stale part.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "gradle-caches",
        name: "Gradle caches",
        locations: &[".gradle/caches"],
        markers: &["CACHEDIR.TAG"],
        note: "Downloaded dependencies and build caches. The next build refetches them.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "go-build",
        name: "Go build cache",
        locations: &["Library/Caches/go-build", ".cache/go-build"],
        // `trim.txt` is go's own bookkeeping file, and the README beside it says outright to
        // run `go clean -cache` when the directory gets large.
        markers: &["trim.txt"],
        note: "Compiled package objects. Rebuilt locally, no network needed.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "go-mod",
        name: "Go module cache",
        locations: &["go/pkg/mod"],
        markers: &["cache"],
        note: "Downloaded modules. `go clean -modcache` is the same thing; needs network after.",
        in_all: true,
        read_only: true,
    },
    Cache {
        id: "npm",
        name: "npm cache",
        locations: &[".npm/_cacache"],
        markers: &["content-v2", "index-v5"],
        note: "Content-addressed package tarballs. Refetched on the next install.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "pnpm",
        name: "pnpm metadata cache",
        locations: &["Library/Caches/pnpm", ".cache/pnpm"],
        markers: &["lockfile-verified.jsonl"],
        note: "Registry metadata. The content-addressable store is `pnpm-store`.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "pub",
        name: "Dart pub cache",
        locations: &[".pub-cache"],
        markers: &["hosted-hashes"],
        note: "Downloaded packages. `dart pub get` refetches them; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "deno",
        name: "Deno cache",
        locations: &["Library/Caches/deno", ".cache/deno", ".deno"],
        markers: &["dep_analysis_cache_v2", "node_analysis_cache_v2"],
        note: "Fetched modules and analysis caches. Refetched on the next run; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "poly",
        name: "poly cache",
        locations: &[".cache/poly", "Library/Caches/poly", "AppData/Local/poly"],
        markers: &["CACHEDIR.TAG"],
        note: "Lint and format results, hook staged snapshots and fetched remote sources. \
               Rebuilt on the next run.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "alef-global",
        name: "alef global cache",
        locations: &[".cache/alef"],
        markers: &["zig-hashes.json"],
        note: "Shared snippet build output and toolchain hashes. Rebuilt on the next run.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "codex-cache",
        name: "Codex app cache",
        locations: &[".codex/cache"],
        markers: &["codex_app_directory"],
        note: "Plugin and app metadata Codex rebuilds on the next launch.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "codex-scratch",
        name: "Codex scratch directories",
        locations: &[".codex/.tmp"],
        markers: &["marketplaces"],
        note: "Marketplace bundles and scratch checkouts. Refetched when a plugin is installed.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "pnpm-store",
        name: "pnpm content-addressable store",
        locations: &[
            "Library/pnpm/store",
            ".local/share/pnpm/store",
            ".pnpm-store",
            "AppData/Local/pnpm/store",
        ],
        // The store keeps one directory per layout version, and each has a file only pnpm
        // writes: v10's `index`, v11's SQLite `index.db`, v3's `files`. The version directory
        // alone is not enough, which is why these are two segments deep.
        markers: &["v11/index.db", "v10/index", "v3/files"],
        note: "Every package pnpm has installed. Projects hold hard links into it, so their \
               `node_modules` survive; the next install of anything not already linked refetches \
               it, and needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "pip",
        name: "pip cache",
        locations: &["Library/Caches/pip", ".cache/pip", "AppData/Local/pip/Cache"],
        markers: &["http-v2", "wheels", "selfcheck"],
        note: "Downloaded and locally built wheels. The next install refetches or rebuilds them.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "homebrew",
        name: "Homebrew downloads",
        locations: &["Library/Caches/Homebrew", ".cache/Homebrew"],
        // `.cleaned` is the stamp `brew cleanup` leaves; the command list is brew's own too.
        markers: &[".cleaned", "all_commands_list.txt"],
        note: "Bottles and API metadata already downloaded. `brew cleanup` removes only the \
               stale part; a reinstall or upgrade refetches the rest.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "prek",
        name: "prek cache",
        locations: &[".cache/prek"],
        markers: &["config-tracking.json", "prek.log"],
        note: "Cloned hook repositories and their environments. Rebuilt on the next run; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "pre-commit",
        name: "pre-commit cache",
        locations: &[".cache/pre-commit"],
        markers: &["db.db"],
        note: "Cloned hook repositories and their environments. Rebuilt on the next run; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "ms-playwright",
        name: "Playwright browsers",
        locations: &[
            "Library/Caches/ms-playwright",
            ".cache/ms-playwright",
            "AppData/Local/ms-playwright",
        ],
        markers: &[".links"],
        note: "Downloaded browser builds. Playwright tests fail until `playwright install` fetches \
               them again; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "node-gyp",
        name: "node-gyp headers",
        locations: &[
            "Library/Caches/node-gyp",
            ".cache/node-gyp",
            "AppData/Local/node-gyp/Cache",
        ],
        markers: &["*/installVersion"],
        note: "Node headers for native addon builds. Refetched by the next `node-gyp rebuild`; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "golangci-lint",
        name: "golangci-lint cache",
        locations: &[
            "Library/Caches/golangci-lint",
            ".cache/golangci-lint",
            "AppData/Local/golangci-lint",
        ],
        // The Go build cache's own bookkeeping file, which golangci-lint's cache shares.
        markers: &["trim.txt"],
        note: "Analysis results. The next lint run is slow once, then warm again; no network needed.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "tree-sitter-language-pack",
        name: "tree-sitter language pack",
        locations: &[
            "Library/Caches/tree-sitter-language-pack",
            ".cache/tree-sitter-language-pack",
        ],
        markers: &["*/.download.lock", "*/manifest.json"],
        note: "Downloaded parser bundles, one directory per release. Refetched on first use; needs network.",
        in_all: true,
        read_only: false,
    },
    Cache {
        id: "huggingface",
        name: "Hugging Face hub",
        locations: &[".cache/huggingface/hub"],
        // The lock directory `huggingface_hub` creates on its first download. Only `hub/` is
        // named: its parent also holds the login token, which is not regenerable.
        markers: &[".locks"],
        note: "Downloaded models and datasets, often gigabytes each, some gated or withdrawn. \
               Only removed when named; refetching needs network and may need a login.",
        in_all: false,
        read_only: false,
    },
];

#[cfg(test)]
mod tests {
    use std::collections::HashSet;

    use super::*;

    /// The same rule the ecosystem catalog enforces: a location alone never justifies removal.
    #[test]
    fn every_cache_declares_a_marker() {
        for cache in CACHES {
            assert!(!cache.markers.is_empty(), "`{}` has no marker to prove it", cache.id);
            for marker in cache.markers {
                assert!(!marker.is_empty(), "`{}` has an empty marker", cache.id);
            }
        }
    }

    #[test]
    fn every_cache_declares_a_location_and_a_note() {
        for cache in CACHES {
            assert!(!cache.locations.is_empty(), "`{}` has no location", cache.id);
            assert!(!cache.note.is_empty(), "`{}` has no note", cache.id);
        }
    }

    /// Ids reach users through `--clean-caches` and `voom.toml`, so a duplicate would make one
    /// of the two unreachable and a rename would break a committed config.
    #[test]
    fn cache_ids_are_unique() {
        let mut seen = HashSet::new();
        for cache in CACHES {
            assert!(seen.insert(cache.id), "`{}` is declared twice", cache.id);
        }
    }

    /// The two tables share one column in the report and one word in conversation, so an id in
    /// both would leave a reader unable to tell which thing a line is about — `alef` names both
    /// an in-project cache and a machine-global one, and the second is `alef-global` for
    /// exactly this reason.
    #[test]
    fn no_cache_id_collides_with_an_ecosystem_id() {
        for cache in CACHES {
            assert!(
                crate::catalog::find(cache.id).is_none(),
                "`{}` is both a cache id and an ecosystem id, so the report cannot say which",
                cache.id
            );
        }
    }

    /// The third set sharing that one column (ADR 0013). `tagged` must not be an ecosystem id or
    /// a cache id either, or a reader cannot tell which table produced the line.
    #[test]
    fn no_id_collides_with_tagged() {
        let tagged = crate::classify::TAGGED_ID;
        assert!(
            crate::catalog::find(tagged).is_none(),
            "`{tagged}` is also an ecosystem id, so the report cannot say which"
        );
        for cache in CACHES {
            assert_ne!(
                cache.id, tagged,
                "`{tagged}` is also a cache id, so the report cannot say which"
            );
        }
    }

    /// A location is joined onto the home directory, so an absolute or climbing one would
    /// escape it — the cache equivalent of the catalog's own containment invariant.
    #[test]
    fn no_cache_location_escapes_the_home_directory() {
        for cache in CACHES {
            for location in cache.locations {
                let path = std::path::Path::new(location);
                assert!(path.is_relative(), "`{}`: `{location}` is absolute", cache.id);
                assert!(
                    path.components()
                        .all(|component| matches!(component, std::path::Component::Normal(_))),
                    "`{}`: `{location}` has a `.` or `..` segment",
                    cache.id
                );
            }
        }
    }

    /// Every location must also be somewhere the walker already refuses to wander into, or
    /// enabling a cache would be the only thing standing between an ordinary sweep and it.
    #[test]
    fn every_cache_location_is_also_skipped_by_location() {
        for cache in CACHES {
            for location in cache.locations {
                assert!(
                    super::super::CACHE_DIRS
                        .iter()
                        .any(|skipped| location == skipped || location.starts_with(&format!("{skipped}/"))),
                    "`{}`: `{location}` is not under any CACHE_DIRS entry, so a default sweep \
                     would walk into it",
                    cache.id
                );
            }
        }
    }

    /// Builds the marker as the tool would leave it: a `*/` marker goes one directory down,
    /// under a name standing in for the version or profile the tool chose.
    fn plant(dir: &std::path::Path, marker: &str) {
        let target = dir.join(marker.replace('*', "any-version"));
        std::fs::create_dir_all(target.parent().expect("a marker has a parent")).expect("a marker dir");
        std::fs::write(target, b"x").expect("a marker file");
    }

    /// The generated counterpart of the ecosystem harness: every marker of every entry proves
    /// its cache, and a directory holding something else does not.
    #[test]
    fn every_marker_proves_its_cache_and_nothing_else_does() {
        for cache in CACHES {
            for marker in cache.markers {
                let proven = tempfile::TempDir::new().expect("a temp dir");
                plant(proven.path(), marker);
                assert!(
                    cache.proven_in(proven.path()),
                    "`{}`: `{marker}` does not prove it",
                    cache.id
                );
            }
            let unproven = tempfile::TempDir::new().expect("a temp dir");
            std::fs::write(unproven.path().join("notes.txt"), b"x").expect("a file");
            assert!(
                !cache.proven_in(unproven.path()),
                "`{}` is proven by an unrelated file",
                cache.id
            );
        }
    }

    /// A marker is a relative path: an absolute or climbing one would let a cache be proven by
    /// something outside it.
    #[test]
    fn no_marker_escapes_the_cache_directory() {
        for cache in CACHES {
            for marker in cache.markers {
                let rest = marker.strip_prefix("*/").unwrap_or(marker);
                assert!(
                    std::path::Path::new(rest)
                        .components()
                        .all(|component| matches!(component, std::path::Component::Normal(_)))
                        && !rest.contains('*'),
                    "`{}`: `{marker}` is not a plain relative path, optionally behind `*/`",
                    cache.id
                );
            }
        }
    }

    /// A version directory alone proves nothing: `node-gyp` is proven by what node-gyp wrote
    /// inside one, not by there being a directory named `20.1.0`.
    #[test]
    fn should_not_prove_a_wildcard_marker_from_an_empty_subdirectory() {
        let node_gyp = CACHES
            .iter()
            .find(|cache| cache.id == "node-gyp")
            .expect("node-gyp is a cache");
        let dir = tempfile::TempDir::new().expect("a temp dir");
        std::fs::create_dir_all(dir.path().join("20.1.0")).expect("a version dir");

        assert!(!node_gyp.proven_in(dir.path()));
    }

    /// Gigabytes of models are not "a re-download" in the sense the others are, so a bare
    /// `--clean-caches` leaves them alone and only the id removes them.
    #[test]
    fn should_keep_expensive_caches_out_of_the_bare_flag() {
        let out: Vec<&str> = CACHES
            .iter()
            .filter(|cache| !cache.in_all)
            .map(|cache| cache.id)
            .collect();
        assert_eq!(out, vec!["huggingface"]);
    }

    #[test]
    fn should_know_the_machine_wide_stores_the_audit_found() {
        for id in [
            "pnpm-store",
            "pip",
            "homebrew",
            "prek",
            "pre-commit",
            "ms-playwright",
            "node-gyp",
            "golangci-lint",
            "huggingface",
            "tree-sitter-language-pack",
        ] {
            assert!(CACHES.iter().any(|cache| cache.id == id), "`{id}` is not in the table");
        }
    }

    #[test]
    fn should_name_the_agent_caches_it_can_reclaim() {
        for id in ["codex-cache", "codex-scratch"] {
            let cache = CACHES
                .iter()
                .find(|cache| cache.id == id)
                .unwrap_or_else(|| panic!("`{id}` is not in the table"));
            assert!(!cache.markers.is_empty(), "`{id}` has no marker, so nothing proves it");
            assert!(cache.in_all, "`{id}` is a cache a bare --clean-caches should reach");
        }
    }
}