Skip to main content

ask/store/
cache.rs

1//! Global store inspection + garbage collection for `ask cache`. Rust port of
2//! `store/cache.ts`.
3//!
4//! `cache_ls` enumerates every entry under `<askHome>` (npm/web/llms-txt kind
5//! dirs + the nested `github/<host>/<owner>/<repo>/<tag>/` layout, plus the
6//! legacy `github/checkouts` layout tagged `legacy`). `cache_gc` removes entries
7//! not referenced by any `.ask/resolved.json` under the scan roots, with an
8//! optional age gate. `cache_clean_legacy` drops the pre-v2 github dirs.
9
10use std::collections::BTreeSet;
11use std::path::{Path, PathBuf};
12use std::time::{SystemTime, UNIX_EPOCH};
13
14use serde::Serialize;
15
16use crate::store::assert_contained;
17
18/// One entry in the global store.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct CacheEntry {
21    pub kind: CacheKind,
22    pub key: String,
23    pub path: PathBuf,
24    pub size_bytes: u64,
25    /// True for the legacy `github/checkouts` layout — rendered with a
26    /// `(legacy)` tag and a `(legacy) ` key prefix.
27    pub legacy: bool,
28}
29
30/// Store entry kind. Serializes to the wire values `npm`/`github`/`web`/`llms-txt`.
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
32#[serde(rename_all = "kebab-case")]
33pub enum CacheKind {
34    Npm,
35    Github,
36    Web,
37    LlmsTxt,
38}
39
40impl CacheKind {
41    /// The on-disk kind directory / wire string.
42    pub fn as_str(self) -> &'static str {
43        match self {
44            CacheKind::Npm => "npm",
45            CacheKind::Github => "github",
46            CacheKind::Web => "web",
47            CacheKind::LlmsTxt => "llms-txt",
48        }
49    }
50
51    /// Parse a `--kind` filter value.
52    pub fn parse(s: &str) -> Option<CacheKind> {
53        match s {
54            "npm" => Some(CacheKind::Npm),
55            "github" => Some(CacheKind::Github),
56            "web" => Some(CacheKind::Web),
57            "llms-txt" => Some(CacheKind::LlmsTxt),
58            _ => None,
59        }
60    }
61}
62
63// ── JSON output models ─────────────────────────────────────────────
64
65/// A cache entry as serialized in `--json` output (matches `CacheLsEntrySchema`).
66#[derive(Debug, Serialize, PartialEq, Eq)]
67pub struct CacheLsEntry {
68    pub kind: CacheKind,
69    pub key: String,
70    pub path: String,
71    #[serde(rename = "sizeBytes")]
72    pub size_bytes: u64,
73    /// Emitted only when true (absent otherwise), matching the TS shape.
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub legacy: Option<bool>,
76}
77
78impl CacheLsEntry {
79    fn from_entry(e: &CacheEntry) -> Self {
80        CacheLsEntry {
81            kind: e.kind,
82            key: e.key.clone(),
83            path: e.path.to_string_lossy().into_owned(),
84            size_bytes: e.size_bytes,
85            legacy: if e.legacy { Some(true) } else { None },
86        }
87    }
88}
89
90/// `ask cache ls --json` model (matches `CacheLsModelSchema`).
91#[derive(Debug, Serialize, PartialEq, Eq)]
92pub struct CacheLsModel {
93    #[serde(rename = "askHome")]
94    pub ask_home: String,
95    #[serde(rename = "totalBytes")]
96    pub total_bytes: u64,
97    pub entries: Vec<CacheLsEntry>,
98}
99
100/// `ask cache gc --json` model (matches `CacheGcModelSchema`).
101#[derive(Debug, Serialize, PartialEq, Eq)]
102pub struct CacheGcModel {
103    #[serde(rename = "askHome")]
104    pub ask_home: String,
105    #[serde(rename = "dryRun")]
106    pub dry_run: bool,
107    #[serde(rename = "freedBytes")]
108    pub freed_bytes: u64,
109    pub removed: Vec<CacheLsEntry>,
110}
111
112pub fn build_cache_ls_model(ask_home: &Path, filter: Option<CacheKind>) -> CacheLsModel {
113    let entries = cache_ls(ask_home, filter);
114    let total_bytes = entries.iter().map(|e| e.size_bytes).sum();
115    CacheLsModel {
116        ask_home: ask_home.to_string_lossy().into_owned(),
117        total_bytes,
118        entries: entries.iter().map(CacheLsEntry::from_entry).collect(),
119    }
120}
121
122pub fn build_cache_gc_model(ask_home: &Path, options: &CacheGcOptions) -> CacheGcModel {
123    let mut opts = options.clone();
124    opts.silent = true;
125    let result = cache_gc(ask_home, &opts);
126    CacheGcModel {
127        ask_home: ask_home.to_string_lossy().into_owned(),
128        dry_run: options.dry_run,
129        freed_bytes: result.freed_bytes,
130        removed: result
131            .removed
132            .iter()
133            .map(CacheLsEntry::from_entry)
134            .collect(),
135    }
136}
137
138// ── cache_ls ───────────────────────────────────────────────────────
139
140/// List all entries in the store at `ask_home`, optionally filtered by kind.
141pub fn cache_ls(ask_home: &Path, filter: Option<CacheKind>) -> Vec<CacheEntry> {
142    let mut entries = Vec::new();
143    let kinds: Vec<CacheKind> = match filter {
144        Some(k) => vec![k],
145        None => vec![
146            CacheKind::Npm,
147            CacheKind::Github,
148            CacheKind::Web,
149            CacheKind::LlmsTxt,
150        ],
151    };
152
153    for kind in kinds {
154        if kind == CacheKind::Github {
155            collect_github(ask_home, &mut entries);
156        } else {
157            let kind_dir = ask_home.join(kind.as_str());
158            if !kind_dir.exists() {
159                continue;
160            }
161            for subdir in safe_readdir(&kind_dir) {
162                let entry_path = kind_dir.join(&subdir);
163                if !safe_is_directory(&entry_path) {
164                    continue;
165                }
166                let size = dir_size(&entry_path);
167                entries.push(CacheEntry {
168                    kind,
169                    key: subdir,
170                    path: entry_path,
171                    size_bytes: size,
172                    legacy: false,
173                });
174            }
175        }
176    }
177
178    entries
179}
180
181fn collect_github(ask_home: &Path, entries: &mut Vec<CacheEntry>) {
182    // New nested layout: github/<host>/<owner>/<repo>/<tag>/
183    let github_dir = ask_home.join("github");
184    if github_dir.exists() {
185        for host in safe_readdir(&github_dir) {
186            // Skip legacy subdirs — handled separately below.
187            if host == "db" || host == "checkouts" {
188                continue;
189            }
190            let host_path = github_dir.join(&host);
191            if !safe_is_directory(&host_path) {
192                continue;
193            }
194            for owner in safe_readdir(&host_path) {
195                let owner_path = host_path.join(&owner);
196                if !safe_is_directory(&owner_path) {
197                    continue;
198                }
199                for repo in safe_readdir(&owner_path) {
200                    let repo_path = owner_path.join(&repo);
201                    if !safe_is_directory(&repo_path) {
202                        continue;
203                    }
204                    for tag in safe_readdir(&repo_path) {
205                        let tag_path = repo_path.join(&tag);
206                        if !safe_is_directory(&tag_path) {
207                            continue;
208                        }
209                        let size = dir_size(&tag_path);
210                        entries.push(CacheEntry {
211                            kind: CacheKind::Github,
212                            key: format!("{host}/{owner}/{repo}/{tag}"),
213                            path: tag_path,
214                            size_bytes: size,
215                            legacy: false,
216                        });
217                    }
218                }
219            }
220        }
221    }
222
223    // Legacy layout: github/checkouts/<owner>__<repo>/<ref>/
224    let legacy_checkout_dir = ask_home.join("github").join("checkouts");
225    if legacy_checkout_dir.exists() {
226        for repo_dir in safe_readdir(&legacy_checkout_dir) {
227            let repo_path = legacy_checkout_dir.join(&repo_dir);
228            if !safe_is_directory(&repo_path) {
229                continue;
230            }
231            for reference in safe_readdir(&repo_path) {
232                let ref_path = repo_path.join(&reference);
233                if !safe_is_directory(&ref_path) {
234                    continue;
235                }
236                let size = dir_size(&ref_path);
237                entries.push(CacheEntry {
238                    kind: CacheKind::Github,
239                    key: format!("(legacy) {repo_dir}/{reference}"),
240                    path: ref_path,
241                    size_bytes: size,
242                    legacy: true,
243                });
244            }
245        }
246    }
247}
248
249// ── Legacy detection + cleanup ─────────────────────────────────────
250
251/// Pre-store-v2 github paths under `<askHome>`.
252pub fn legacy_layout_paths(ask_home: &Path) -> Vec<PathBuf> {
253    vec![
254        ask_home.join("github").join("db"),
255        ask_home.join("github").join("checkouts"),
256    ]
257}
258
259/// True iff any legacy github path exists under `<askHome>`.
260pub fn detect_legacy_layout(ask_home: &Path) -> bool {
261    legacy_layout_paths(ask_home).iter().any(|p| p.exists())
262}
263
264/// Remove all legacy github store paths under `<askHome>`. Idempotent.
265pub fn cache_clean_legacy(ask_home: &Path) -> Vec<PathBuf> {
266    let mut removed = Vec::new();
267    for p in legacy_layout_paths(ask_home) {
268        if p.exists() {
269            let _ = std::fs::remove_dir_all(&p);
270            removed.push(p);
271        }
272    }
273    removed
274}
275
276// ── parse_duration ─────────────────────────────────────────────────
277
278/// Parse `30d`/`12h`/`90m`/`60s` into milliseconds. `None` on invalid input.
279pub fn parse_duration(input: &str) -> Option<u64> {
280    let s = input.trim();
281    let idx = s.find(|c: char| !c.is_ascii_digit())?;
282    if idx == 0 {
283        return None; // no leading digits
284    }
285    let (num, rest) = s.split_at(idx);
286    let unit = rest.trim();
287    let n: u64 = num.parse().ok()?;
288    match unit {
289        "s" => Some(n * 1000),
290        "m" => Some(n * 60 * 1000),
291        "h" => Some(n * 60 * 60 * 1000),
292        "d" => Some(n * 24 * 60 * 60 * 1000),
293        _ => None,
294    }
295}
296
297// ── cache_gc ───────────────────────────────────────────────────────
298
299/// Options for [`cache_gc`].
300#[derive(Debug, Clone, Default)]
301pub struct CacheGcOptions {
302    pub dry_run: bool,
303    /// Roots to scan for `.ask/resolved.json`. `None` → `[$HOME]`.
304    pub scan_roots: Option<Vec<PathBuf>>,
305    /// Age gate in milliseconds; entries newer than `now - older_than` are kept.
306    pub older_than: Option<u64>,
307    /// Suppress per-entry progress (set by the `--json` path).
308    pub silent: bool,
309}
310
311/// Result of a [`cache_gc`] run.
312#[derive(Debug, Default)]
313pub struct CacheGcResult {
314    pub removed: Vec<CacheEntry>,
315    pub kept: Vec<CacheEntry>,
316    pub freed_bytes: u64,
317}
318
319/// Remove store entries not referenced by any `.ask/resolved.json` under the
320/// scan roots. With `older_than`, unreferenced entries newer than the cutoff are
321/// still kept.
322pub fn cache_gc(ask_home: &Path, options: &CacheGcOptions) -> CacheGcResult {
323    let scan_roots = options.scan_roots.clone().unwrap_or_else(|| {
324        // Platform-aware home (USERPROFILE on Windows, $HOME on unix), matching
325        // TS's os.homedir(). Defaulting to only $HOME leaves scan_roots EMPTY on
326        // native Windows → collect_referenced_store_paths returns an empty set →
327        // every entry looks unreferenced → a non-dry-run `ask cache gc` deletes
328        // the whole store, including in-use entries.
329        vec![super::paths::home_dir()]
330    });
331
332    let referenced = collect_referenced_store_paths(&scan_roots, ask_home);
333    let all_entries = cache_ls(ask_home, None);
334
335    let mut result = CacheGcResult::default();
336    let cutoff_ms = options.older_than.map(|ot| now_ms().saturating_sub(ot));
337
338    for entry in all_entries {
339        if referenced.contains(&entry.path) {
340            result.kept.push(entry);
341            continue;
342        }
343        if let Some(cutoff) = cutoff_ms {
344            match entry_mtime_ms(&entry.path) {
345                Some(mtime) if mtime > cutoff => {
346                    result.kept.push(entry);
347                    continue;
348                }
349                None => {
350                    // Stat failure → keep to avoid accidental removal.
351                    result.kept.push(entry);
352                    continue;
353                }
354                _ => {}
355            }
356        }
357        if !options.dry_run && std::fs::remove_dir_all(&entry.path).is_err() {
358            result.kept.push(entry);
359            continue;
360        }
361        result.freed_bytes += entry.size_bytes;
362        result.removed.push(entry);
363    }
364
365    result
366}
367
368fn collect_referenced_store_paths(scan_roots: &[PathBuf], ask_home: &Path) -> BTreeSet<PathBuf> {
369    let mut referenced = BTreeSet::new();
370    for root in scan_roots {
371        if root.as_os_str().is_empty() || !root.exists() {
372            continue;
373        }
374        find_resolved_json_files(root, &mut referenced, ask_home, 0, 8);
375    }
376    referenced
377}
378
379fn find_resolved_json_files(
380    dir: &Path,
381    referenced: &mut BTreeSet<PathBuf>,
382    ask_home: &Path,
383    depth: usize,
384    max_depth: usize,
385) {
386    if depth > max_depth {
387        return;
388    }
389
390    let resolved_path = dir.join(".ask").join("resolved.json");
391    if resolved_path.exists() {
392        if let Ok(text) = std::fs::read_to_string(&resolved_path) {
393            if let Ok(data) = serde_json::from_str::<serde_json::Value>(&text) {
394                if let Some(entries) = data.get("entries").and_then(|e| e.as_object()) {
395                    for entry in entries.values() {
396                        if let Some(sp) = entry.get("storePath").and_then(|v| v.as_str()) {
397                            // Only trust storePath values inside ask_home — a
398                            // stale/malicious resolved.json cannot pin entries
399                            // outside the store.
400                            let candidate = PathBuf::from(sp);
401                            if let Ok(abs) = assert_contained(ask_home, &candidate) {
402                                referenced.insert(abs);
403                            }
404                        }
405                    }
406                }
407            }
408        }
409    }
410
411    let Ok(read) = std::fs::read_dir(dir) else {
412        return;
413    };
414    for entry in read.flatten() {
415        // is_dir() is false for symlinks, so symlinked dirs are excluded —
416        // preventing cycle traps and scope escape.
417        let Ok(ft) = entry.file_type() else { continue };
418        if !ft.is_dir() {
419            continue;
420        }
421        let name = entry.file_name();
422        let name = name.to_string_lossy();
423        if name.starts_with('.') || name == "node_modules" {
424            continue;
425        }
426        find_resolved_json_files(
427            &dir.join(name.as_ref()),
428            referenced,
429            ask_home,
430            depth + 1,
431            max_depth,
432        );
433    }
434}
435
436// ── format_bytes ───────────────────────────────────────────────────
437
438/// Human-readable byte count. Matches the TS `toFixed(1)` rendering.
439pub fn format_bytes(bytes: u64) -> String {
440    const KB: f64 = 1024.0;
441    const MB: f64 = 1024.0 * 1024.0;
442    const GB: f64 = 1024.0 * 1024.0 * 1024.0;
443    let b = bytes as f64;
444    if bytes < 1024 {
445        format!("{bytes} B")
446    } else if b < MB {
447        format!("{:.1} KB", b / KB)
448    } else if b < GB {
449        format!("{:.1} MB", b / MB)
450    } else {
451        format!("{:.1} GB", b / GB)
452    }
453}
454
455// ── Helpers ────────────────────────────────────────────────────────
456
457fn now_ms() -> u64 {
458    SystemTime::now()
459        .duration_since(UNIX_EPOCH)
460        .map(|d| d.as_millis() as u64)
461        .unwrap_or(0)
462}
463
464fn entry_mtime_ms(p: &Path) -> Option<u64> {
465    let meta = std::fs::metadata(p).ok()?;
466    let mtime = meta.modified().ok()?;
467    mtime
468        .duration_since(UNIX_EPOCH)
469        .ok()
470        .map(|d| d.as_millis() as u64)
471}
472
473fn safe_is_directory(p: &Path) -> bool {
474    std::fs::metadata(p).map(|m| m.is_dir()).unwrap_or(false)
475}
476
477fn safe_readdir(dir: &Path) -> Vec<String> {
478    match std::fs::read_dir(dir) {
479        Ok(read) => read
480            .flatten()
481            .map(|e| e.file_name().to_string_lossy().into_owned())
482            .collect(),
483        Err(_) => Vec::new(),
484    }
485}
486
487fn dir_size(dir: &Path) -> u64 {
488    let mut size = 0;
489    let Ok(read) = std::fs::read_dir(dir) else {
490        return 0;
491    };
492    for entry in read.flatten() {
493        let full = entry.path();
494        match entry.file_type() {
495            Ok(ft) if ft.is_dir() => size += dir_size(&full),
496            Ok(_) => {
497                if let Ok(meta) = std::fs::metadata(&full) {
498                    size += meta.len();
499                }
500            }
501            Err(_) => {}
502        }
503    }
504    size
505}
506
507#[cfg(test)]
508mod tests {
509    use super::*;
510
511    #[test]
512    fn parse_duration_units() {
513        assert_eq!(parse_duration("60s"), Some(60_000));
514        assert_eq!(parse_duration("90m"), Some(90 * 60_000));
515        assert_eq!(parse_duration("12h"), Some(12 * 3_600_000));
516        assert_eq!(parse_duration("30d"), Some(30 * 86_400_000));
517        assert_eq!(parse_duration(" 5 d "), Some(5 * 86_400_000));
518        assert_eq!(parse_duration("d"), None);
519        assert_eq!(parse_duration("10w"), None);
520        assert_eq!(parse_duration("abc"), None);
521    }
522
523    #[test]
524    fn format_bytes_thresholds() {
525        assert_eq!(format_bytes(512), "512 B");
526        assert_eq!(format_bytes(1024), "1.0 KB");
527        assert_eq!(format_bytes(1536), "1.5 KB");
528        assert_eq!(format_bytes(1024 * 1024), "1.0 MB");
529        assert_eq!(format_bytes(1024 * 1024 * 1024), "1.0 GB");
530    }
531
532    fn touch(path: &Path, contents: &str) {
533        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
534        std::fs::write(path, contents).unwrap();
535    }
536
537    #[test]
538    fn cache_ls_walks_all_kinds_and_legacy() {
539        let home = tempfile::tempdir().unwrap();
540        let ah = home.path();
541        touch(&ah.join("npm/react@18.3.1/INDEX.md"), "x");
542        touch(
543            &ah.join("github/github.com/facebook/react/v18.2.0/README.md"),
544            "hello",
545        );
546        touch(&ah.join("web/abcd1234/page.md"), "web");
547        touch(&ah.join("llms-txt/efgh5678/llms.md"), "llms");
548        // Legacy layout.
549        touch(&ah.join("github/checkouts/owner__repo/v1.0.0/f.md"), "leg");
550
551        let entries = cache_ls(ah, None);
552        let keys: Vec<&str> = entries.iter().map(|e| e.key.as_str()).collect();
553        assert!(keys.contains(&"react@18.3.1"));
554        assert!(keys.contains(&"github.com/facebook/react/v18.2.0"));
555        assert!(keys.contains(&"abcd1234"));
556        assert!(keys.contains(&"efgh5678"));
557        assert!(keys
558            .iter()
559            .any(|k| k.starts_with("(legacy) owner__repo/v1.0.0")));
560        // Legacy entry flagged.
561        assert!(entries.iter().find(|e| e.legacy).is_some());
562        // Filter by kind.
563        let only_web = cache_ls(ah, Some(CacheKind::Web));
564        assert_eq!(only_web.len(), 1);
565        assert_eq!(only_web[0].kind, CacheKind::Web);
566    }
567
568    #[test]
569    fn detect_and_clean_legacy() {
570        let home = tempfile::tempdir().unwrap();
571        let ah = home.path();
572        assert!(!detect_legacy_layout(ah));
573        touch(&ah.join("github/db/some-clone/HEAD"), "x");
574        touch(&ah.join("github/checkouts/o__r/v1/f.md"), "y");
575        assert!(detect_legacy_layout(ah));
576        let removed = cache_clean_legacy(ah);
577        assert_eq!(removed.len(), 2);
578        assert!(!detect_legacy_layout(ah));
579        // Idempotent.
580        assert!(cache_clean_legacy(ah).is_empty());
581    }
582
583    #[test]
584    fn gc_removes_unreferenced_keeps_referenced() {
585        let home = tempfile::tempdir().unwrap();
586        let ah = home.path();
587        let used = ah.join("github/github.com/o/used/v1.0.0");
588        let unused = ah.join("github/github.com/o/unused/v1.0.0");
589        touch(&used.join("f.md"), "used");
590        touch(&unused.join("f.md"), "unused");
591
592        // A project whose resolved.json references the `used` entry.
593        let proj = tempfile::tempdir().unwrap();
594        let resolved = serde_json::json!({
595            "entries": { "used": { "storePath": used.to_string_lossy() } }
596        });
597        touch(
598            &proj.path().join(".ask/resolved.json"),
599            &resolved.to_string(),
600        );
601
602        let opts = CacheGcOptions {
603            dry_run: false,
604            scan_roots: Some(vec![proj.path().to_path_buf()]),
605            older_than: None,
606            silent: true,
607        };
608        let result = cache_gc(ah, &opts);
609        assert_eq!(result.removed.len(), 1);
610        assert!(result.removed[0].key.contains("unused"));
611        assert!(!unused.exists());
612        assert!(used.exists());
613    }
614
615    #[test]
616    fn gc_dry_run_does_not_delete() {
617        let home = tempfile::tempdir().unwrap();
618        let ah = home.path();
619        let unused = ah.join("web/abcd");
620        touch(&unused.join("f.md"), "x");
621        let proj = tempfile::tempdir().unwrap();
622        let opts = CacheGcOptions {
623            dry_run: true,
624            scan_roots: Some(vec![proj.path().to_path_buf()]),
625            older_than: None,
626            silent: true,
627        };
628        let result = cache_gc(ah, &opts);
629        assert_eq!(result.removed.len(), 1);
630        assert!(unused.exists()); // not actually deleted
631    }
632
633    #[test]
634    fn gc_age_gate_keeps_fresh_entries() {
635        let home = tempfile::tempdir().unwrap();
636        let ah = home.path();
637        let fresh = ah.join("web/fresh");
638        touch(&fresh.join("f.md"), "x");
639        let proj = tempfile::tempdir().unwrap();
640        // older_than very large → cutoff far in the past → fresh entry kept.
641        let opts = CacheGcOptions {
642            dry_run: false,
643            scan_roots: Some(vec![proj.path().to_path_buf()]),
644            older_than: Some(365 * 86_400_000),
645            silent: true,
646        };
647        let result = cache_gc(ah, &opts);
648        assert!(result.removed.is_empty());
649        assert!(fresh.exists());
650    }
651
652    #[test]
653    fn ls_json_model_omits_legacy_when_false() {
654        let home = tempfile::tempdir().unwrap();
655        let ah = home.path();
656        touch(&ah.join("web/abcd/f.md"), "hello");
657        let model = build_cache_ls_model(ah, None);
658        let json = serde_json::to_string(&model).unwrap();
659        assert!(json.contains(r#""kind":"web""#));
660        assert!(json.contains(r#""sizeBytes""#));
661        assert!(!json.contains("legacy"));
662    }
663}