1use 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#[derive(Debug, Encode, Decode)]
34pub struct CacheStore {
35 version: u32,
36 config_hash: u64,
38 root: String,
43 entries: FxHashMap<String, CachedModule>,
45}
46
47impl CacheStore {
48 #[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 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 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 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 "Cache was built under different extraction config, rebuilding from cold"
163 );
164 return Err(CacheRejection::ConfigHashMismatch);
165 }
166 let current_root = normalise_root(root);
167 if store.root != current_root {
168 tracing::debug!(
169 cached_root = %store.root,
170 "Reusing a cache written under a different project root"
171 );
172 store.root = current_root;
173 }
174 Ok(store)
175 }
176
177 pub fn save(
181 &mut self,
182 target: CacheTarget<'_>,
183 config_hash: u64,
184 max_size_bytes: usize,
185 ) -> Result<(), String> {
186 target
187 .write_gitignore()
188 .map_err(|e| format!("Failed to write cache .gitignore: {e}"))?;
189
190 self.config_hash = config_hash;
191 let initial_entries = self.entries.len();
192 let mut encoded = self.encode();
193
194 let trigger = (max_size_bytes / 10_000).saturating_mul(EVICTION_TRIGGER_BPS);
195 if encoded.len().saturating_add(CACHE_HEADER_LEN) > trigger {
196 let target = (max_size_bytes / 10_000)
199 .saturating_mul(EVICTION_TARGET_BPS)
200 .saturating_sub(CACHE_HEADER_LEN);
201 let working_set = max_size_bytes.saturating_sub(CACHE_HEADER_LEN);
203 encoded = self.evict_lru_to_target(target, working_set, encoded);
204 let evicted = initial_entries.saturating_sub(self.entries.len());
205 let final_size = encoded.len();
206 let significant_evicted =
207 initial_entries.saturating_mul(EVICTION_SIGNIFICANT_BPS) / 10_000;
208 if evicted >= significant_evicted && initial_entries > 0 {
209 tracing::info!(
210 evicted_entries = evicted,
211 remaining_entries = self.entries.len(),
212 final_size_kb = final_size / 1024,
213 max_size_kb = max_size_bytes / 1024,
214 "Cache eviction: removed oldest entries to stay under cap"
215 );
216 } else {
217 tracing::debug!(
218 evicted_entries = evicted,
219 remaining_entries = self.entries.len(),
220 final_size_kb = final_size / 1024,
221 max_size_kb = max_size_bytes / 1024,
222 "Cache eviction"
223 );
224 }
225 }
226
227 target
228 .write_file("cache.bin", &framed(self.version, &encoded))
229 .map_err(|e| format!("Failed to write cache file: {e}"))
230 }
231
232 fn evict_lru_to_target(
245 &mut self,
246 target_bytes: usize,
247 working_set_bytes: usize,
248 encoded: Vec<u8>,
249 ) -> Vec<u8> {
250 let mut order: Vec<(u64, String, usize)> = self
251 .entries
252 .iter()
253 .map(|(key, entry)| {
254 (
255 entry.last_seen_secs,
256 key.clone(),
257 bitcode::encode(entry)
258 .len()
259 .saturating_add(key.len())
260 .max(1),
261 )
262 })
263 .collect();
264 order.sort();
265 let newest = order.last().map_or(0, |(seen, _, _)| *seen);
266 let working_set_from = order.partition_point(|(seen, _, _)| *seen < newest);
267
268 let mut cursor = EvictionCursor {
269 idx: 0,
270 estimated_remaining: order
271 .iter()
272 .map(|(_, _, estimated_bytes)| estimated_bytes)
273 .sum(),
274 };
275 let mut encoded = encoded;
276 if working_set_from > 0 {
277 encoded = self.evict_order_range(
278 &order,
279 &mut cursor,
280 working_set_from,
281 target_bytes,
282 encoded,
283 );
284 }
285 let working_set_target = target_bytes.max(working_set_bytes);
286 if encoded.len() > working_set_target {
287 let keep_newest_from = order.len().saturating_sub(1);
288 encoded = self.evict_order_range(
289 &order,
290 &mut cursor,
291 keep_newest_from,
292 working_set_target,
293 encoded,
294 );
295 }
296
297 if encoded.len() > working_set_target && self.entries.len() == 1 {
298 tracing::warn!(
299 encoded_kb = encoded.len() / 1024,
300 target_kb = working_set_target / 1024,
301 "Single cache entry exceeds configured max; cache will overshoot the cap"
302 );
303 }
304 encoded
305 }
306
307 fn evict_order_range(
310 &mut self,
311 order: &[(u64, String, usize)],
312 cursor: &mut EvictionCursor,
313 end: usize,
314 target_bytes: usize,
315 mut encoded: Vec<u8>,
316 ) -> Vec<u8> {
317 const MAX_REFINEMENT_PASSES: usize = 2;
318 const ESTIMATE_SAFETY_BPS: usize = 9_800;
319 for _ in 0..MAX_REFINEMENT_PASSES {
320 if encoded.len() <= target_bytes || cursor.idx >= end {
321 return encoded;
322 }
323
324 let estimated_budget = estimated_eviction_budget(
325 cursor.estimated_remaining,
326 target_bytes,
327 encoded.len(),
328 ESTIMATE_SAFETY_BPS,
329 );
330 let start_idx = cursor.idx;
331 while cursor.idx < end && cursor.estimated_remaining > estimated_budget {
332 self.evict_at(order, cursor);
333 }
334 if cursor.idx == start_idx {
335 self.evict_at(order, cursor);
336 }
337 encoded = self.encode();
338 }
339
340 if encoded.len() > target_bytes && cursor.idx < end {
341 let conservative_budget = target_bytes / 2;
342 while cursor.idx < end && cursor.estimated_remaining > conservative_budget {
343 self.evict_at(order, cursor);
344 }
345 encoded = self.encode();
346 }
347
348 if encoded.len() > target_bytes && cursor.idx < end {
353 while cursor.idx < end {
354 self.evict_at(order, cursor);
355 }
356 encoded = self.encode();
357 }
358 encoded
359 }
360
361 fn evict_at(&mut self, order: &[(u64, String, usize)], cursor: &mut EvictionCursor) {
362 let (_, key, estimated_bytes) = &order[cursor.idx];
363 self.entries.remove(key);
364 cursor.estimated_remaining = cursor.estimated_remaining.saturating_sub(*estimated_bytes);
365 cursor.idx += 1;
366 }
367
368 fn encode(&self) -> Vec<u8> {
369 #[cfg(test)]
370 FULL_STORE_ENCODE_COUNT.with(|count| count.set(count.get() + 1));
371 bitcode::encode(self)
372 }
373
374 #[cfg(test)]
375 pub(super) fn reset_full_store_encode_count() {
376 FULL_STORE_ENCODE_COUNT.with(|count| count.set(0));
377 }
378
379 #[cfg(test)]
380 pub(super) fn full_store_encode_count() -> usize {
381 FULL_STORE_ENCODE_COUNT.with(Cell::get)
382 }
383
384 fn key_for(&self, path: &Path) -> String {
391 let text = path.to_string_lossy().replace('\\', "/");
392 if self.root.is_empty() {
393 return text;
394 }
395 match text
396 .strip_prefix(&self.root)
397 .and_then(|rest| rest.strip_prefix('/'))
398 {
399 Some(relative) => relative.to_owned(),
400 None => text,
401 }
402 }
403
404 fn path_for_key(&self, key: &str) -> std::path::PathBuf {
406 if self.root.is_empty() {
407 return std::path::PathBuf::from(key);
408 }
409 let candidate = Path::new(key);
410 if candidate.is_absolute() {
411 return candidate.to_path_buf();
412 }
413 Path::new(&self.root).join(key)
414 }
415
416 #[must_use]
419 pub fn get(&self, path: &Path, content_hash: u64) -> Option<&CachedModule> {
420 let entry = self.entries.get(&self.key_for(path))?;
421 if entry.content_hash == content_hash {
422 Some(entry)
423 } else {
424 None
425 }
426 }
427
428 pub fn insert(&mut self, path: &Path, module: CachedModule) {
430 let key = self.key_for(path);
431 self.entries.insert(key, module);
432 }
433
434 pub fn refresh_fingerprint(
442 &mut self,
443 path: &Path,
444 fingerprint: fallow_types::source_fingerprint::SourceFingerprint,
445 ) -> bool {
446 let key = self.key_for(path);
447 let Some(entry) = self.entries.get_mut(&key) else {
448 return false;
449 };
450 entry.mtime_ns = fingerprint.mtime_ns;
451 entry.ctime_ns = fingerprint.ctime_ns;
452 entry.file_size = fingerprint.file_size;
453 true
454 }
455
456 pub fn record_module(
466 &mut self,
467 path: &Path,
468 module: &crate::ModuleInfo,
469 fingerprint: fallow_types::source_fingerprint::SourceFingerprint,
470 need_complexity: bool,
471 need_call_facts: bool,
472 ) -> bool {
473 let Some(cached) = self
474 .get_by_path_only(path)
475 .filter(|cached| cached.content_hash == module.content_hash)
476 else {
477 self.insert(
478 path,
479 module_to_cached(module, fingerprint, need_complexity, need_call_facts),
480 );
481 return true;
482 };
483 let adds_complexity = need_complexity && !cached.complexity_extracted;
484 let adds_call_facts = need_call_facts && cached.call_facts.is_none();
485 if !adds_complexity && !adds_call_facts {
486 return cached.source_fingerprint() != fingerprint
487 && self.refresh_fingerprint(path, fingerprint);
488 }
489 let mut refreshed = module_to_cached(module, fingerprint, need_complexity, need_call_facts);
490 if !need_complexity && cached.complexity_extracted {
491 refreshed.complexity.clone_from(&cached.complexity);
492 refreshed.complexity_extracted = true;
493 }
494 if !need_call_facts {
495 refreshed.call_facts.clone_from(&cached.call_facts);
496 }
497 self.insert(path, refreshed);
498 true
499 }
500
501 #[must_use]
503 pub fn get_by_path_only(&self, path: &Path) -> Option<&CachedModule> {
504 self.entries.get(&self.key_for(path))
505 }
506
507 pub fn retain_paths(&mut self, files: &[fallow_types::discover::DiscoveredFile]) -> bool {
532 use rustc_hash::FxHashSet;
533 let current_keys: FxHashSet<String> = files.iter().map(|f| self.key_for(&f.path)).collect();
534 let before = self.entries.len();
535 let retained: FxHashSet<String> = self
536 .entries
537 .keys()
538 .filter(|key| {
539 current_keys.contains(*key)
540 || std::fs::symlink_metadata(self.path_for_key(key)).is_ok()
541 })
542 .cloned()
543 .collect();
544 self.entries.retain(|key, _| retained.contains(key));
545 let now = super::conversion::current_unix_seconds();
546 for key in ¤t_keys {
547 if let Some(entry) = self.entries.get_mut(key) {
548 entry.last_seen_secs = now;
549 }
550 }
551 self.entries.len() != before
552 }
553
554 #[must_use]
556 pub fn len(&self) -> usize {
557 self.entries.len()
558 }
559
560 #[must_use]
562 pub fn is_empty(&self) -> bool {
563 self.entries.is_empty()
564 }
565}
566
567struct EvictionCursor {
570 idx: usize,
571 estimated_remaining: usize,
572}
573
574const CACHE_MAGIC: [u8; 4] = *b"FLWX";
581
582pub(super) const CACHE_HEADER_LEN: usize = CACHE_MAGIC.len() + 4;
585
586pub(super) fn framed(version: u32, payload: &[u8]) -> Vec<u8> {
591 let mut framed = Vec::with_capacity(CACHE_HEADER_LEN + payload.len());
592 framed.extend_from_slice(&CACHE_MAGIC);
593 framed.extend_from_slice(&version.to_le_bytes());
594 framed.extend_from_slice(payload);
595 framed
596}
597
598fn read_header(data: &[u8]) -> Result<&[u8], CacheRejection> {
611 let Some((header, payload)) = data.split_at_checked(CACHE_HEADER_LEN) else {
612 tracing::warn!("Cache file is too short to carry a format header, rebuilding");
613 return Err(CacheRejection::Undecodable);
614 };
615 let (declared_magic, declared_version) = header.split_at(CACHE_MAGIC.len());
616 if declared_magic != CACHE_MAGIC {
617 tracing::warn!("Cache file does not carry fallow's cache framing, rebuilding");
618 return Err(CacheRejection::Undecodable);
619 }
620 let declared = declared_version.try_into().map_or(0, u32::from_le_bytes);
624 if declared != CACHE_VERSION {
625 tracing::warn!(
626 cached_version = declared,
627 expected_version = CACHE_VERSION,
628 "Cache format upgraded, rebuilding (one-time cost after version bump)"
629 );
630 return Err(CacheRejection::VersionMismatch);
631 }
632 Ok(payload)
633}
634
635pub(super) fn estimated_eviction_budget(
636 estimated_remaining: usize,
637 target_bytes: usize,
638 encoded_bytes: usize,
639 safety_bps: usize,
640) -> usize {
641 if encoded_bytes == 0 {
642 return 0;
643 }
644
645 const BASIS_POINTS: u128 = 10_000;
646 let scaled = estimated_remaining as u128 * target_bytes as u128 / encoded_bytes as u128;
647 let safety = (safety_bps as u128).min(BASIS_POINTS);
648 let budget = scaled / BASIS_POINTS * safety + scaled % BASIS_POINTS * safety / BASIS_POINTS;
649 budget.min(usize::MAX as u128) as usize
650}
651
652fn normalise_root(root: &Path) -> String {
656 let text = root.to_string_lossy().replace('\\', "/");
657 match text.strip_suffix('/') {
658 Some(trimmed) => trimmed.to_owned(),
659 None => text,
660 }
661}
662
663impl Default for CacheStore {
664 fn default() -> Self {
665 Self::new(Path::new(""))
666 }
667}