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 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 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 let target = (max_size_bytes / 10_000)
200 .saturating_mul(EVICTION_TARGET_BPS)
201 .saturating_sub(CACHE_HEADER_LEN);
202 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 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 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 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 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 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 #[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 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 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 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 #[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 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 ¤t_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 #[must_use]
557 pub fn len(&self) -> usize {
558 self.entries.len()
559 }
560
561 #[must_use]
563 pub fn is_empty(&self) -> bool {
564 self.entries.is_empty()
565 }
566}
567
568struct EvictionCursor {
571 idx: usize,
572 estimated_remaining: usize,
573}
574
575const CACHE_MAGIC: [u8; 4] = *b"FLWX";
582
583pub(super) const CACHE_HEADER_LEN: usize = CACHE_MAGIC.len() + 4;
586
587pub(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
599fn 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 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
653fn 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}