Skip to main content

fallow_extract/cache/
store.rs

1//! Cache store: load, save, and query cached module data.
2
3use std::path::Path;
4
5#[cfg(test)]
6use std::cell::Cell;
7
8use fallow_types::cache_rejection::CacheRejection;
9use fallow_types::path_guard::CacheTarget;
10use rustc_hash::FxHashMap;
11
12use bitcode::{Decode, Encode};
13
14use super::conversion::module_to_cached;
15use super::types::{
16    CACHE_VERSION, CachedModule, DEFAULT_CACHE_MAX_SIZE, EVICTION_SIGNIFICANT_BPS,
17    EVICTION_TARGET_BPS, EVICTION_TRIGGER_BPS,
18};
19
20#[cfg(test)]
21thread_local! {
22    static FULL_STORE_ENCODE_COUNT: Cell<usize> = const { Cell::new(0) };
23}
24
25/// Cached module information stored on disk.
26///
27/// Entries are keyed on the ROOT-RELATIVE, forward-slash-normalised path, and
28/// the root is recorded once in the header. Absolute keys made the blob
29/// unusable anywhere but the directory that wrote it: a container job, a
30/// matrix over roots, a GitLab shell executor, or a plain `cp -Rp` to a
31/// sibling path paid the full decode of a multi-megabyte file and then missed
32/// every single lookup, with nothing on stderr to say so.
33#[derive(Debug, Encode, Decode)]
34pub struct CacheStore {
35    version: u32,
36    /// Stable hash of extraction-affecting config fields.
37    config_hash: u64,
38    /// Project root the entries are relative to, forward-slash normalised and
39    /// without a trailing separator. Informational after load: the loader
40    /// re-anchors to the CURRENT root, because a blob restored under another
41    /// path is exactly the case root-relative keys exist to serve.
42    root: String,
43    /// Map from root-relative file path to cached module data.
44    entries: FxHashMap<String, CachedModule>,
45}
46
47impl CacheStore {
48    /// Create a new empty cache anchored at `root`.
49    #[must_use]
50    pub fn new(root: &Path) -> Self {
51        Self {
52            version: CACHE_VERSION,
53            config_hash: 0,
54            root: normalise_root(root),
55            entries: FxHashMap::default(),
56        }
57    }
58
59    /// Load cache from disk.
60    ///
61    /// # Errors
62    ///
63    /// Returns the [`CacheRejection`] that decided against reuse. Every branch
64    /// names itself instead of collapsing into a bare miss: a run that read a
65    /// multi-megabyte blob and then refused it costs the same as a cold run,
66    /// and without a named reason it is indistinguishable from having no cache
67    /// at all. Callers carry
68    /// the reason into the perf table and `fallow doctor`.
69    ///
70    /// The version is read from the file header BEFORE the payload is
71    /// decoded, because the two are decided by different things. A format bump
72    /// changes the encoded shape, so decoding a blob from the previous release
73    /// fails outright and never reaches a version comparison made afterwards:
74    /// the most ordinary event there is (upgrading fallow) then reported
75    /// "cache file could not be decoded", which reads as corruption and sent
76    /// people looking for a damaged disk. With the version in front, an upgrade
77    /// says the format changed. The framing is checked separately from the
78    /// version it carries, so an unframed or unreadable payload reports `Undecodable`
79    /// rather than borrowing the upgrade message.
80    ///
81    /// Every branch that refuses a file that DID exist logs at warn, because
82    /// the user paid the read and got nothing back. Only the missing-file case
83    /// stays quiet.
84    pub fn load(
85        cache_dir: &Path,
86        root: &Path,
87        expected_config_hash: u64,
88        max_size_bytes: usize,
89    ) -> Result<Self, CacheRejection> {
90        Self::load_counting_bytes(cache_dir, root, expected_config_hash, max_size_bytes).0
91    }
92
93    /// [`Self::load`], plus the number of cache bytes read from disk.
94    ///
95    /// The count is returned also when the cache is refused, because the run
96    /// paid for the read either way. It is zero when no file was read.
97    pub fn load_counting_bytes(
98        cache_dir: &Path,
99        root: &Path,
100        expected_config_hash: u64,
101        max_size_bytes: usize,
102    ) -> (Result<Self, CacheRejection>, u64) {
103        let cache_file = cache_dir.join("cache.bin");
104        let data = match std::fs::read(&cache_file) {
105            Ok(data) => data,
106            Err(error) => {
107                if error.kind() != std::io::ErrorKind::NotFound {
108                    tracing::warn!("Cache file could not be read; check the path and permissions");
109                    return (Err(CacheRejection::Unreadable), 0);
110                }
111                return (Err(CacheRejection::Absent), 0);
112            }
113        };
114        let bytes_read = data.len() as u64;
115        (
116            Self::decode_loaded(&data, root, expected_config_hash, max_size_bytes),
117            bytes_read,
118        )
119    }
120
121    fn decode_loaded(
122        data: &[u8],
123        root: &Path,
124        expected_config_hash: u64,
125        max_size_bytes: usize,
126    ) -> Result<Self, CacheRejection> {
127        let safety_ceiling = max_size_bytes.max(DEFAULT_CACHE_MAX_SIZE);
128        if data.len() > safety_ceiling {
129            tracing::warn!(
130                size_mb = data.len() / (1024 * 1024),
131                ceiling_mb = safety_ceiling / (1024 * 1024),
132                "Cache file exceeds safety ceiling, ignoring"
133            );
134            return Err(CacheRejection::Oversize {
135                size_bytes: data.len() as u64,
136                ceiling_bytes: safety_ceiling as u64,
137            });
138        }
139        let payload = read_header(data)?;
140        let mut store: Self = match bitcode::decode(payload) {
141            Ok(s) => s,
142            Err(_) => {
143                tracing::warn!(
144                    "Cache file carries the current format version but its payload could not be \
145                     decoded, rebuilding"
146                );
147                return Err(CacheRejection::Undecodable);
148            }
149        };
150        // The header already agreed with `CACHE_VERSION`, so this catches only a
151        // file whose header and payload disagree: a spliced or hand-edited blob.
152        if store.version != CACHE_VERSION {
153            tracing::warn!(
154                cached_version = store.version,
155                expected_version = CACHE_VERSION,
156                "Cache header and payload declare different format versions, rebuilding"
157            );
158            return Err(CacheRejection::VersionMismatch);
159        }
160        if store.config_hash != expected_config_hash {
161            tracing::warn!(
162                target: fallow_types::ANALYSIS_DIAGNOSTIC_LOG_TARGET,
163                "Cache was built under different extraction config, rebuilding from cold"
164            );
165            return Err(CacheRejection::ConfigHashMismatch);
166        }
167        let current_root = normalise_root(root);
168        if store.root != current_root {
169            tracing::debug!(
170                cached_root = %store.root,
171                "Reusing a cache written under a different project root"
172            );
173            store.root = current_root;
174        }
175        Ok(store)
176    }
177
178    /// Save cache to disk with write-time size enforcement and atomic rename.
179    /// A symlink that leaves the base of `target` stops the save before any
180    /// write.
181    pub fn save(
182        &mut self,
183        target: CacheTarget<'_>,
184        config_hash: u64,
185        max_size_bytes: usize,
186    ) -> Result<(), String> {
187        target
188            .write_gitignore()
189            .map_err(|e| format!("Failed to write cache .gitignore: {e}"))?;
190
191        self.config_hash = config_hash;
192        let initial_entries = self.entries.len();
193        let mut encoded = self.encode();
194
195        let trigger = (max_size_bytes / 10_000).saturating_mul(EVICTION_TRIGGER_BPS);
196        if encoded.len().saturating_add(CACHE_HEADER_LEN) > trigger {
197            // The cap is a promise about the file, and the file carries the
198            // header as well as the payload, so eviction aims below both.
199            let target = (max_size_bytes / 10_000)
200                .saturating_mul(EVICTION_TARGET_BPS)
201                .saturating_sub(CACHE_HEADER_LEN);
202            // The working set of the latest run may fill the whole cap.
203            let working_set = max_size_bytes.saturating_sub(CACHE_HEADER_LEN);
204            encoded = self.evict_lru_to_target(target, working_set, encoded);
205            let evicted = initial_entries.saturating_sub(self.entries.len());
206            let final_size = encoded.len();
207            let significant_evicted =
208                initial_entries.saturating_mul(EVICTION_SIGNIFICANT_BPS) / 10_000;
209            if evicted >= significant_evicted && initial_entries > 0 {
210                tracing::info!(
211                    evicted_entries = evicted,
212                    remaining_entries = self.entries.len(),
213                    final_size_kb = final_size / 1024,
214                    max_size_kb = max_size_bytes / 1024,
215                    "Cache eviction: removed oldest entries to stay under cap"
216                );
217            } else {
218                tracing::debug!(
219                    evicted_entries = evicted,
220                    remaining_entries = self.entries.len(),
221                    final_size_kb = final_size / 1024,
222                    max_size_kb = max_size_bytes / 1024,
223                    "Cache eviction"
224                );
225            }
226        }
227
228        target
229            .write_file("cache.bin", &framed(self.version, &encoded))
230            .map_err(|e| format!("Failed to write cache file: {e}"))
231    }
232
233    /// Evict the entries that runs saw least recently until the re-encoded
234    /// size is under `target_bytes` or only one entry remains.
235    ///
236    /// The entries with the newest seen stamp are the working set of the
237    /// latest run, and they all share that one stamp. Eviction removes older
238    /// entries down to `target_bytes` first. It removes working-set entries
239    /// only down to `working_set_bytes`, which is the cap itself. The low
240    /// target gives headroom for entries that other scopes add. The working
241    /// set must not go down to the low target: a working set a little over
242    /// the trigger then loses about 40 percent of its entries on every save,
243    /// and the next run parses those files again. The tie order of the keys
244    /// is stable, so the same entries go on each save and the rest stay hits.
245    fn evict_lru_to_target(
246        &mut self,
247        target_bytes: usize,
248        working_set_bytes: usize,
249        encoded: Vec<u8>,
250    ) -> Vec<u8> {
251        let mut order: Vec<(u64, String, usize)> = self
252            .entries
253            .iter()
254            .map(|(key, entry)| {
255                (
256                    entry.last_seen_secs,
257                    key.clone(),
258                    bitcode::encode(entry)
259                        .len()
260                        .saturating_add(key.len())
261                        .max(1),
262                )
263            })
264            .collect();
265        order.sort();
266        let newest = order.last().map_or(0, |(seen, _, _)| *seen);
267        let working_set_from = order.partition_point(|(seen, _, _)| *seen < newest);
268
269        let mut cursor = EvictionCursor {
270            idx: 0,
271            estimated_remaining: order
272                .iter()
273                .map(|(_, _, estimated_bytes)| estimated_bytes)
274                .sum(),
275        };
276        let mut encoded = encoded;
277        if working_set_from > 0 {
278            encoded = self.evict_order_range(
279                &order,
280                &mut cursor,
281                working_set_from,
282                target_bytes,
283                encoded,
284            );
285        }
286        let working_set_target = target_bytes.max(working_set_bytes);
287        if encoded.len() > working_set_target {
288            let keep_newest_from = order.len().saturating_sub(1);
289            encoded = self.evict_order_range(
290                &order,
291                &mut cursor,
292                keep_newest_from,
293                working_set_target,
294                encoded,
295            );
296        }
297
298        if encoded.len() > working_set_target && self.entries.len() == 1 {
299            tracing::warn!(
300                encoded_kb = encoded.len() / 1024,
301                target_kb = working_set_target / 1024,
302                "Single cache entry exceeds configured max; cache will overshoot the cap"
303            );
304        }
305        encoded
306    }
307
308    /// Remove entries in `order` from `cursor.idx` up to (not including)
309    /// `end` until the re-encoded size is under `target_bytes`.
310    fn evict_order_range(
311        &mut self,
312        order: &[(u64, String, usize)],
313        cursor: &mut EvictionCursor,
314        end: usize,
315        target_bytes: usize,
316        mut encoded: Vec<u8>,
317    ) -> Vec<u8> {
318        const MAX_REFINEMENT_PASSES: usize = 2;
319        const ESTIMATE_SAFETY_BPS: usize = 9_800;
320        for _ in 0..MAX_REFINEMENT_PASSES {
321            if encoded.len() <= target_bytes || cursor.idx >= end {
322                return encoded;
323            }
324
325            let estimated_budget = estimated_eviction_budget(
326                cursor.estimated_remaining,
327                target_bytes,
328                encoded.len(),
329                ESTIMATE_SAFETY_BPS,
330            );
331            let start_idx = cursor.idx;
332            while cursor.idx < end && cursor.estimated_remaining > estimated_budget {
333                self.evict_at(order, cursor);
334            }
335            if cursor.idx == start_idx {
336                self.evict_at(order, cursor);
337            }
338            encoded = self.encode();
339        }
340
341        if encoded.len() > target_bytes && cursor.idx < end {
342            let conservative_budget = target_bytes / 2;
343            while cursor.idx < end && cursor.estimated_remaining > conservative_budget {
344                self.evict_at(order, cursor);
345            }
346            encoded = self.encode();
347        }
348
349        // Per-entry encodings are deliberately conservative, but keep the
350        // configured cap exact if a future bitcode layout violates that
351        // estimate. This safety path runs only after byte-aware retention had
352        // three opportunities to preserve a recent suffix.
353        if encoded.len() > target_bytes && cursor.idx < end {
354            while cursor.idx < end {
355                self.evict_at(order, cursor);
356            }
357            encoded = self.encode();
358        }
359        encoded
360    }
361
362    fn evict_at(&mut self, order: &[(u64, String, usize)], cursor: &mut EvictionCursor) {
363        let (_, key, estimated_bytes) = &order[cursor.idx];
364        self.entries.remove(key);
365        cursor.estimated_remaining = cursor.estimated_remaining.saturating_sub(*estimated_bytes);
366        cursor.idx += 1;
367    }
368
369    fn encode(&self) -> Vec<u8> {
370        #[cfg(test)]
371        FULL_STORE_ENCODE_COUNT.with(|count| count.set(count.get() + 1));
372        bitcode::encode(self)
373    }
374
375    #[cfg(test)]
376    pub(super) fn reset_full_store_encode_count() {
377        FULL_STORE_ENCODE_COUNT.with(|count| count.set(0));
378    }
379
380    #[cfg(test)]
381    pub(super) fn full_store_encode_count() -> usize {
382        FULL_STORE_ENCODE_COUNT.with(Cell::get)
383    }
384
385    /// Key `path` the way entries are stored: root-relative where possible,
386    /// forward-slash normalised.
387    ///
388    /// A path outside the root keeps its own normalised spelling. It is still
389    /// stable within one root, which is all a lookup needs, and no root-
390    /// relative spelling of it exists to prefer.
391    fn key_for(&self, path: &Path) -> String {
392        let text = path.to_string_lossy().replace('\\', "/");
393        if self.root.is_empty() {
394            return text;
395        }
396        match text
397            .strip_prefix(&self.root)
398            .and_then(|rest| rest.strip_prefix('/'))
399        {
400            Some(relative) => relative.to_owned(),
401            None => text,
402        }
403    }
404
405    /// Rebuild the absolute path an entry key refers to under the current root.
406    fn path_for_key(&self, key: &str) -> std::path::PathBuf {
407        if self.root.is_empty() {
408            return std::path::PathBuf::from(key);
409        }
410        let candidate = Path::new(key);
411        if candidate.is_absolute() {
412            return candidate.to_path_buf();
413        }
414        Path::new(&self.root).join(key)
415    }
416
417    /// Look up a cached module by path and content hash.
418    /// Returns None if not cached or hash mismatch.
419    #[must_use]
420    pub fn get(&self, path: &Path, content_hash: u64) -> Option<&CachedModule> {
421        let entry = self.entries.get(&self.key_for(path))?;
422        if entry.content_hash == content_hash {
423            Some(entry)
424        } else {
425            None
426        }
427    }
428
429    /// Insert or update a cached module.
430    pub fn insert(&mut self, path: &Path, module: CachedModule) {
431        let key = self.key_for(path);
432        self.entries.insert(key, module);
433    }
434
435    /// Replace the source fingerprint of the entry for `path`, and keep the
436    /// rest of the entry.
437    ///
438    /// A fresh checkout or a restored cache moves the file timestamps but not
439    /// the content. Rebuilding such an entry from the module copies every
440    /// extracted fact again, so a caller whose content hash still matches
441    /// refreshes only the metadata. Returns `false` when no entry exists.
442    pub fn refresh_fingerprint(
443        &mut self,
444        path: &Path,
445        fingerprint: fallow_types::source_fingerprint::SourceFingerprint,
446    ) -> bool {
447        let key = self.key_for(path);
448        let Some(entry) = self.entries.get_mut(&key) else {
449            return false;
450        };
451        entry.mtime_ns = fingerprint.mtime_ns;
452        entry.ctime_ns = fingerprint.ctime_ns;
453        entry.file_size = fingerprint.file_size;
454        true
455    }
456
457    /// Store the module of this run for `path`. Returns `true` when the store
458    /// changed.
459    ///
460    /// An entry whose content hash still matches is rewritten only when its
461    /// metadata fingerprint moved or when this run adds complexity or call
462    /// facts that the entry lacks. A rewrite keeps the complexity and the call
463    /// facts that an earlier run stored and this run did not extract: a
464    /// module of such a run has none of them by design, so a copy would strip
465    /// the entry and make each later run that reads them parse the file again.
466    pub fn record_module(
467        &mut self,
468        path: &Path,
469        module: &crate::ModuleInfo,
470        fingerprint: fallow_types::source_fingerprint::SourceFingerprint,
471        need_complexity: bool,
472        need_call_facts: bool,
473    ) -> bool {
474        let Some(cached) = self
475            .get_by_path_only(path)
476            .filter(|cached| cached.content_hash == module.content_hash)
477        else {
478            self.insert(
479                path,
480                module_to_cached(module, fingerprint, need_complexity, need_call_facts),
481            );
482            return true;
483        };
484        let adds_complexity = need_complexity && !cached.complexity_extracted;
485        let adds_call_facts = need_call_facts && cached.call_facts.is_none();
486        if !adds_complexity && !adds_call_facts {
487            return cached.source_fingerprint() != fingerprint
488                && self.refresh_fingerprint(path, fingerprint);
489        }
490        let mut refreshed = module_to_cached(module, fingerprint, need_complexity, need_call_facts);
491        if !need_complexity && cached.complexity_extracted {
492            refreshed.complexity.clone_from(&cached.complexity);
493            refreshed.complexity_extracted = true;
494        }
495        if !need_call_facts {
496            refreshed.call_facts.clone_from(&cached.call_facts);
497        }
498        self.insert(path, refreshed);
499        true
500    }
501
502    /// Look up a cached module by path only (ignoring hash).
503    #[must_use]
504    pub fn get_by_path_only(&self, path: &Path) -> Option<&CachedModule> {
505        self.entries.get(&self.key_for(path))
506    }
507
508    /// Remove cache entries for files that no longer exist on disk, and mark
509    /// the entries for every discovered file as seen by this run.
510    ///
511    /// Returns `true` when any entry was removed. The seen stamp alone does
512    /// not make the store dirty: a run that saves nothing else does not
513    /// rewrite the whole blob to persist it, and the next run that saves
514    /// stamps the same files again.
515    ///
516    /// The seen stamp orders eviction. A file that every run discovers keeps a
517    /// current stamp even when it never changes, so `evict_lru_to_target`
518    /// removes the entries that only another scope reads before it removes
519    /// the files that this scope reads on every run.
520    ///
521    /// The predicate is deliberately "still exists", not "was discovered by
522    /// this run". Discovery is scoped: `--production` drops test and story
523    /// files, `--root` narrows to a subtree, and `ignorePatterns` differs per
524    /// command. Evicting whatever the current scope did not walk meant one
525    /// `--production` run threw away the entries for every test file, and the
526    /// next full run reparsed them from cold. Entries are keyed by absolute
527    /// path, so the check is one `symlink_metadata` per undiscovered entry
528    /// (`symlink_metadata`, not `metadata`, so a broken symlink still counts as
529    /// present rather than being evicted as missing). Size is not this
530    /// method's concern: `evict_lru_to_target` remains the only guard on how
531    /// large the blob may grow.
532    pub fn retain_paths(&mut self, files: &[fallow_types::discover::DiscoveredFile]) -> bool {
533        use rustc_hash::FxHashSet;
534        let current_keys: FxHashSet<String> = files.iter().map(|f| self.key_for(&f.path)).collect();
535        let before = self.entries.len();
536        let retained: FxHashSet<String> = self
537            .entries
538            .keys()
539            .filter(|key| {
540                current_keys.contains(*key)
541                    || std::fs::symlink_metadata(self.path_for_key(key)).is_ok()
542            })
543            .cloned()
544            .collect();
545        self.entries.retain(|key, _| retained.contains(key));
546        let now = super::conversion::current_unix_seconds();
547        for key in &current_keys {
548            if let Some(entry) = self.entries.get_mut(key) {
549                entry.last_seen_secs = now;
550            }
551        }
552        self.entries.len() != before
553    }
554
555    /// Number of cached entries.
556    #[must_use]
557    pub fn len(&self) -> usize {
558        self.entries.len()
559    }
560
561    /// Whether the cache is empty.
562    #[must_use]
563    pub fn is_empty(&self) -> bool {
564        self.entries.is_empty()
565    }
566}
567
568/// Position in the sorted eviction order, and the estimated size of the
569/// entries that remain.
570struct EvictionCursor {
571    idx: usize,
572    estimated_remaining: usize,
573}
574
575/// Marker written ahead of every cache payload so the format version can be
576/// read without decoding the payload it describes.
577///
578/// Constant across format bumps: only the version field beside it moves. That
579/// lets future upgrades report an explicit version mismatch; older unframed
580/// caches still report an ambiguous decode failure.
581const CACHE_MAGIC: [u8; 4] = *b"FLWX";
582
583/// Bytes the framing adds ahead of the payload: the magic plus a little-endian
584/// `u32` format version.
585pub(super) const CACHE_HEADER_LEN: usize = CACHE_MAGIC.len() + 4;
586
587/// Prepend the format header to an encoded payload.
588///
589/// The version comes from the store being written rather than from the
590/// constant, so the header always describes the payload behind it.
591pub(super) fn framed(version: u32, payload: &[u8]) -> Vec<u8> {
592    let mut framed = Vec::with_capacity(CACHE_HEADER_LEN + payload.len());
593    framed.extend_from_slice(&CACHE_MAGIC);
594    framed.extend_from_slice(&version.to_le_bytes());
595    framed.extend_from_slice(payload);
596    framed
597}
598
599/// Split a cache file into its declared version and its payload, refusing
600/// anything this binary cannot read WITHOUT decoding it first.
601///
602/// The version check has to come first: a format bump changes the encoded
603/// shape, so a blob from the previous release fails to decode and a version
604/// comparison made after the decode is unreachable on the one event that
605/// triggers it most, an upgrade.
606///
607/// A recognized header exposes a version mismatch without decoding. Releases
608/// before framing wrote raw payloads, so a missing header cannot distinguish
609/// an older cache from foreign or damaged data. `Undecodable` keeps that
610/// uncertainty explicit and the next successful run replaces the blob.
611fn read_header(data: &[u8]) -> Result<&[u8], CacheRejection> {
612    let Some((header, payload)) = data.split_at_checked(CACHE_HEADER_LEN) else {
613        tracing::warn!("Cache file is too short to carry a format header, rebuilding");
614        return Err(CacheRejection::Undecodable);
615    };
616    let (declared_magic, declared_version) = header.split_at(CACHE_MAGIC.len());
617    if declared_magic != CACHE_MAGIC {
618        tracing::warn!("Cache file does not carry fallow's cache framing, rebuilding");
619        return Err(CacheRejection::Undecodable);
620    }
621    // The slice is exactly four bytes; the fallback only has to be a version
622    // this binary never writes, so an impossible header is refused rather than
623    // trusted.
624    let declared = declared_version.try_into().map_or(0, u32::from_le_bytes);
625    if declared != CACHE_VERSION {
626        tracing::warn!(
627            cached_version = declared,
628            expected_version = CACHE_VERSION,
629            "Cache format upgraded, rebuilding (one-time cost after version bump)"
630        );
631        return Err(CacheRejection::VersionMismatch);
632    }
633    Ok(payload)
634}
635
636pub(super) fn estimated_eviction_budget(
637    estimated_remaining: usize,
638    target_bytes: usize,
639    encoded_bytes: usize,
640    safety_bps: usize,
641) -> usize {
642    if encoded_bytes == 0 {
643        return 0;
644    }
645
646    const BASIS_POINTS: u128 = 10_000;
647    let scaled = estimated_remaining as u128 * target_bytes as u128 / encoded_bytes as u128;
648    let safety = (safety_bps as u128).min(BASIS_POINTS);
649    let budget = scaled / BASIS_POINTS * safety + scaled % BASIS_POINTS * safety / BASIS_POINTS;
650    budget.min(usize::MAX as u128) as usize
651}
652
653/// Normalise a project root for storage and prefix stripping: forward slashes,
654/// no trailing separator. An empty root disables stripping, which is what a
655/// default-constructed store gets.
656fn normalise_root(root: &Path) -> String {
657    let text = root.to_string_lossy().replace('\\', "/");
658    match text.strip_suffix('/') {
659        Some(trimmed) => trimmed.to_owned(),
660        None => text,
661    }
662}
663
664impl Default for CacheStore {
665    fn default() -> Self {
666        Self::new(Path::new(""))
667    }
668}