#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Cache {
pub id: &'static str,
pub name: &'static str,
pub locations: &'static [&'static str],
pub markers: &'static [&'static str],
pub note: &'static str,
pub in_all: bool,
pub read_only: bool,
}
impl Cache {
#[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)),
})
}
}
fn exists(path: &std::path::Path) -> bool {
std::fs::symlink_metadata(path).is_ok()
}
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"],
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",
],
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"],
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",
],
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"],
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::*;
#[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);
}
}
#[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);
}
}
#[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
);
}
}
#[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"
);
}
}
#[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
);
}
}
}
#[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
);
}
}
}
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");
}
#[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
);
}
}
#[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
);
}
}
}
#[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()));
}
#[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");
}
}
}