fallow_graph/cache/
mod.rs

1//! Persisted graph-cache identity contracts and on-disk store.
2//!
3//! The manifest types here define the invalidation surface a persisted graph
4//! cache must satisfy before a cached graph can be trusted. Exact manifest hits
5//! can reuse a previously-built `ModuleGraph`; stable-key resolver hits can
6//! reuse resolver output and rebuild the graph with current `FileId`s.
7
8use std::path::{Path, PathBuf};
9
10use fallow_types::discover::{DiscoveredFile, FileId, StableFileKey};
11use fallow_types::extract::{ImportInfo, ReExportInfo};
12use fallow_types::source_fingerprint::SourceFingerprint;
13use oxc_span::Span;
14
15use crate::resolve::{ResolveResult, ResolvedImport, ResolvedModule, ResolvedReExport};
16
17mod store;
18
19pub use store::GraphCacheStore;
20
21/// Persisted graph cache schema version.
22///
23/// Bump this whenever the serialized shape of the persisted graph (any of the
24/// graph types that derive serde for the cache, the manifest types, or the
25/// store envelope) changes, so a stale `graph-cache.bin` written by an older
26/// binary is rejected rather than deserialized into the wrong shape.
27pub const GRAPH_CACHE_VERSION: u32 = 3;
28
29/// Cached form of a resolved target.
30///
31/// Internal targets are stored by stable file key, not by `FileId`, so resolver
32/// output can be reused across a future FileId assignment shift. The persisted
33/// `ModuleGraph` itself is still `FileId`-keyed; callers may only trust the
34/// cached graph when the manifest's `file_id` assignments match, but they may
35/// remap this resolver payload and rebuild the graph.
36#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
37pub enum CachedResolveResult {
38    /// Resolved to a file within the project.
39    InternalModule(StableFileKey),
40    /// Resolved to a project file through a framework convention auto-import.
41    SyntheticAutoImport(StableFileKey),
42    /// Resolved to a workspace or self package source file.
43    InternalPackageModule {
44        /// Stable source file reached by the package map.
45        key: StableFileKey,
46        /// Package name that was used in the import specifier.
47        package_name: String,
48    },
49    /// Resolved to a file outside the project.
50    ExternalFile(PathBuf),
51    /// Bare specifier.
52    NpmPackage(String),
53    /// Could not resolve.
54    Unresolvable(String),
55}
56
57impl CachedResolveResult {
58    fn from_resolve_result(
59        target: &ResolveResult,
60        key_by_file_id: &rustc_hash::FxHashMap<FileId, StableFileKey>,
61    ) -> Option<Self> {
62        Some(match target {
63            ResolveResult::InternalModule(file_id) => {
64                Self::InternalModule(key_by_file_id.get(file_id)?.clone())
65            }
66            ResolveResult::SyntheticAutoImport(file_id) => {
67                Self::SyntheticAutoImport(key_by_file_id.get(file_id)?.clone())
68            }
69            ResolveResult::InternalPackageModule {
70                file_id,
71                package_name,
72            } => Self::InternalPackageModule {
73                key: key_by_file_id.get(file_id)?.clone(),
74                package_name: package_name.clone(),
75            },
76            ResolveResult::ExternalFile(path) => Self::ExternalFile(path.clone()),
77            ResolveResult::NpmPackage(package_name) => Self::NpmPackage(package_name.clone()),
78            ResolveResult::Unresolvable(specifier) => Self::Unresolvable(specifier.clone()),
79        })
80    }
81
82    fn into_resolve_result(
83        self,
84        id_by_key: &rustc_hash::FxHashMap<StableFileKey, FileId>,
85    ) -> Option<ResolveResult> {
86        Some(match self {
87            Self::InternalModule(key) => ResolveResult::InternalModule(*id_by_key.get(&key)?),
88            Self::SyntheticAutoImport(key) => {
89                ResolveResult::SyntheticAutoImport(*id_by_key.get(&key)?)
90            }
91            Self::InternalPackageModule { key, package_name } => {
92                ResolveResult::InternalPackageModule {
93                    file_id: *id_by_key.get(&key)?,
94                    package_name,
95                }
96            }
97            Self::ExternalFile(path) => ResolveResult::ExternalFile(path),
98            Self::NpmPackage(package_name) => ResolveResult::NpmPackage(package_name),
99            Self::Unresolvable(specifier) => ResolveResult::Unresolvable(specifier),
100        })
101    }
102}
103
104/// Cached import edge that can be restored without re-running resolution.
105#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
106pub struct CachedResolvedImport {
107    /// Import metadata mirrored from extraction or resolver synthesis.
108    pub info: CachedImportInfo,
109    /// Resolved target for this import edge.
110    pub target: CachedResolveResult,
111}
112
113impl CachedResolvedImport {
114    fn from_resolved(
115        import: &ResolvedImport,
116        key_by_file_id: &rustc_hash::FxHashMap<FileId, StableFileKey>,
117    ) -> Option<Self> {
118        Some(Self {
119            info: CachedImportInfo::from(&import.info),
120            target: CachedResolveResult::from_resolve_result(&import.target, key_by_file_id)?,
121        })
122    }
123
124    fn into_resolved(
125        self,
126        id_by_key: &rustc_hash::FxHashMap<StableFileKey, FileId>,
127    ) -> Option<ResolvedImport> {
128        Some(ResolvedImport {
129            info: self.info.into(),
130            target: self.target.into_resolve_result(id_by_key)?,
131        })
132    }
133}
134
135/// Cached re-export edge that can be restored without re-running resolution.
136#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
137pub struct CachedResolvedReExport {
138    /// Re-export metadata mirrored from extraction.
139    pub info: CachedReExportInfo,
140    /// Resolved target for this re-export source.
141    pub target: CachedResolveResult,
142}
143
144impl CachedResolvedReExport {
145    fn from_resolved(
146        re_export: &ResolvedReExport,
147        key_by_file_id: &rustc_hash::FxHashMap<FileId, StableFileKey>,
148    ) -> Option<Self> {
149        Some(Self {
150            info: CachedReExportInfo::from(&re_export.info),
151            target: CachedResolveResult::from_resolve_result(&re_export.target, key_by_file_id)?,
152        })
153    }
154
155    fn into_resolved(
156        self,
157        id_by_key: &rustc_hash::FxHashMap<StableFileKey, FileId>,
158    ) -> Option<ResolvedReExport> {
159        Some(ResolvedReExport {
160            info: self.info.into(),
161            target: self.target.into_resolve_result(id_by_key)?,
162        })
163    }
164}
165
166/// Cache-friendly mirror of [`ImportInfo`].
167#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
168pub struct CachedImportInfo {
169    /// Import source specifier.
170    pub source: String,
171    /// Imported binding shape.
172    pub imported_name: fallow_types::extract::ImportedName,
173    /// Local binding name.
174    pub local_name: String,
175    /// Whether this import is type-only.
176    pub is_type_only: bool,
177    /// Whether this import originated from a style context.
178    pub from_style: bool,
179    /// Span of the full import declaration.
180    pub span: [u32; 2],
181    /// Span of the import source literal.
182    pub source_span: [u32; 2],
183}
184
185impl From<&ImportInfo> for CachedImportInfo {
186    fn from(info: &ImportInfo) -> Self {
187        Self {
188            source: info.source.clone(),
189            imported_name: info.imported_name.clone(),
190            local_name: info.local_name.clone(),
191            is_type_only: info.is_type_only,
192            from_style: info.from_style,
193            span: span_to_pair(info.span),
194            source_span: span_to_pair(info.source_span),
195        }
196    }
197}
198
199impl From<CachedImportInfo> for ImportInfo {
200    fn from(info: CachedImportInfo) -> Self {
201        Self {
202            source: info.source,
203            imported_name: info.imported_name,
204            local_name: info.local_name,
205            is_type_only: info.is_type_only,
206            from_style: info.from_style,
207            span: pair_to_span(info.span),
208            source_span: pair_to_span(info.source_span),
209        }
210    }
211}
212
213/// Cache-friendly mirror of [`ReExportInfo`].
214#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
215pub struct CachedReExportInfo {
216    /// Re-export source specifier.
217    pub source: String,
218    /// Imported name from the source module.
219    pub imported_name: String,
220    /// Exported name from this module.
221    pub exported_name: String,
222    /// Whether this re-export is type-only.
223    pub is_type_only: bool,
224    /// Span of the re-export declaration.
225    pub span: [u32; 2],
226}
227
228impl From<&ReExportInfo> for CachedReExportInfo {
229    fn from(info: &ReExportInfo) -> Self {
230        Self {
231            source: info.source.clone(),
232            imported_name: info.imported_name.clone(),
233            exported_name: info.exported_name.clone(),
234            is_type_only: info.is_type_only,
235            span: span_to_pair(info.span),
236        }
237    }
238}
239
240impl From<CachedReExportInfo> for ReExportInfo {
241    fn from(info: CachedReExportInfo) -> Self {
242        Self {
243            source: info.source,
244            imported_name: info.imported_name,
245            exported_name: info.exported_name,
246            is_type_only: info.is_type_only,
247            span: pair_to_span(info.span),
248        }
249    }
250}
251
252/// Cached resolver output for one module.
253#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
254pub struct CachedResolvedModule {
255    /// Stable identity of the source module.
256    pub key: StableFileKey,
257    /// Static import and require edges after resolution.
258    pub resolved_imports: Vec<CachedResolvedImport>,
259    /// Literal dynamic import edges after resolution.
260    pub resolved_dynamic_imports: Vec<CachedResolvedImport>,
261    /// Re-export source edges after resolution.
262    pub re_exports: Vec<CachedResolvedReExport>,
263    /// Dynamic import pattern targets, aligned with current extracted patterns.
264    pub resolved_dynamic_pattern_targets: Vec<Vec<StableFileKey>>,
265}
266
267impl CachedResolvedModule {
268    fn from_resolved(
269        module: &ResolvedModule,
270        key_by_file_id: &rustc_hash::FxHashMap<FileId, StableFileKey>,
271    ) -> Option<Self> {
272        Some(Self {
273            key: key_by_file_id.get(&module.file_id)?.clone(),
274            resolved_imports: module
275                .resolved_imports
276                .iter()
277                .map(|import| CachedResolvedImport::from_resolved(import, key_by_file_id))
278                .collect::<Option<Vec<_>>>()?,
279            resolved_dynamic_imports: module
280                .resolved_dynamic_imports
281                .iter()
282                .map(|import| CachedResolvedImport::from_resolved(import, key_by_file_id))
283                .collect::<Option<Vec<_>>>()?,
284            re_exports: module
285                .re_exports
286                .iter()
287                .map(|re_export| CachedResolvedReExport::from_resolved(re_export, key_by_file_id))
288                .collect::<Option<Vec<_>>>()?,
289            resolved_dynamic_pattern_targets: module
290                .resolved_dynamic_patterns
291                .iter()
292                .map(|(_, targets)| {
293                    targets
294                        .iter()
295                        .map(|target| key_by_file_id.get(target).cloned())
296                        .collect::<Option<Vec<_>>>()
297                })
298                .collect::<Option<Vec<_>>>()?,
299        })
300    }
301}
302
303/// Convert resolved modules into the compact graph-cache resolver payload.
304#[must_use]
305pub fn cache_resolved_modules(
306    root: &Path,
307    files: &[DiscoveredFile],
308    resolved: &[ResolvedModule],
309) -> Option<Vec<CachedResolvedModule>> {
310    let key_by_file_id = stable_key_by_file_id(root, files);
311    resolved
312        .iter()
313        .map(|module| CachedResolvedModule::from_resolved(module, &key_by_file_id))
314        .collect()
315}
316
317/// Restore resolved modules from cached resolver payloads and current parsed modules.
318///
319/// Returns `None` if the payload no longer aligns with the current parse result.
320/// A normal graph-cache manifest hit should keep these aligned; this extra check
321/// keeps corrupt or hand-edited cache files on the safe miss path.
322#[must_use]
323pub fn restore_resolved_modules(
324    root: &Path,
325    modules: &[fallow_types::extract::ModuleInfo],
326    files: &[DiscoveredFile],
327    cached: &[CachedResolvedModule],
328) -> Option<Vec<ResolvedModule>> {
329    if modules.len() != cached.len() {
330        return None;
331    }
332
333    let key_by_file_id = stable_key_by_file_id(root, files);
334    let id_by_key: rustc_hash::FxHashMap<_, _> = key_by_file_id
335        .iter()
336        .map(|(file_id, key)| (key.clone(), *file_id))
337        .collect();
338    let mut by_key: rustc_hash::FxHashMap<_, _> = modules
339        .iter()
340        .filter_map(|module| {
341            key_by_file_id
342                .get(&module.file_id)
343                .map(|key| (key.clone(), module))
344        })
345        .collect();
346    let path_by_key: rustc_hash::FxHashMap<_, _> = files
347        .iter()
348        .map(|file| {
349            (
350                StableFileKey::from_root_relative(root, &file.path),
351                file.path.clone(),
352            )
353        })
354        .collect();
355
356    cached
357        .iter()
358        .map(|entry| {
359            let module = by_key.remove(&entry.key)?;
360            let path = path_by_key.get(&entry.key)?.clone();
361            if entry.resolved_dynamic_pattern_targets.len() != module.dynamic_import_patterns.len()
362            {
363                return None;
364            }
365            let resolved_dynamic_pattern_targets = entry
366                .resolved_dynamic_pattern_targets
367                .iter()
368                .map(|targets| {
369                    targets
370                        .iter()
371                        .map(|key| id_by_key.get(key).copied())
372                        .collect::<Option<Vec<_>>>()
373                })
374                .collect::<Option<Vec<_>>>()?;
375
376            Some(ResolvedModule {
377                file_id: module.file_id,
378                path,
379                exports: module.exports.clone(),
380                re_exports: entry
381                    .re_exports
382                    .iter()
383                    .cloned()
384                    .map(|re_export| re_export.into_resolved(&id_by_key))
385                    .collect::<Option<Vec<_>>>()?,
386                resolved_imports: entry
387                    .resolved_imports
388                    .iter()
389                    .cloned()
390                    .map(|import| import.into_resolved(&id_by_key))
391                    .collect::<Option<Vec<_>>>()?,
392                resolved_dynamic_imports: entry
393                    .resolved_dynamic_imports
394                    .iter()
395                    .cloned()
396                    .map(|import| import.into_resolved(&id_by_key))
397                    .collect::<Option<Vec<_>>>()?,
398                resolved_dynamic_patterns: module
399                    .dynamic_import_patterns
400                    .iter()
401                    .cloned()
402                    .zip(resolved_dynamic_pattern_targets)
403                    .collect(),
404                member_accesses: module.member_accesses.clone(),
405                semantic_facts: module.semantic_facts.clone(),
406                whole_object_uses: module.whole_object_uses.clone(),
407                has_cjs_exports: module.has_cjs_exports,
408                has_angular_component_template_url: module.has_angular_component_template_url,
409                unused_import_bindings: module.unused_import_bindings.iter().cloned().collect(),
410                type_referenced_import_bindings: module.type_referenced_import_bindings.clone(),
411                value_referenced_import_bindings: module.value_referenced_import_bindings.clone(),
412                namespace_object_aliases: module.namespace_object_aliases.clone(),
413                exported_factory_returns: module.exported_factory_returns.clone(),
414            })
415        })
416        .collect()
417}
418
419fn stable_key_by_file_id(
420    root: &Path,
421    files: &[DiscoveredFile],
422) -> rustc_hash::FxHashMap<FileId, StableFileKey> {
423    files
424        .iter()
425        .map(|file| (file.id, StableFileKey::from_root_relative(root, &file.path)))
426        .collect()
427}
428
429fn span_to_pair(span: Span) -> [u32; 2] {
430    [span.start, span.end]
431}
432
433fn pair_to_span(pair: [u32; 2]) -> Span {
434    Span::new(pair[0], pair[1])
435}
436
437/// Serialize an [`oxc_span::Span`] as a `[start, end]` `u32` pair.
438///
439/// `oxc_span::Span` does not enable its own serde feature in this workspace, so
440/// the graph types that carry spans route them through this module via
441/// `#[serde(with = "crate::cache::span_serde")]`. A 2-element array keeps the
442/// postcard encoding compact (two varints) and is trivially lossless: a `Span`
443/// is fully described by its `start` / `end` offsets.
444pub(crate) mod span_serde {
445    use oxc_span::Span;
446    use serde::{Deserialize, Deserializer, Serialize, Serializer};
447
448    #[expect(
449        clippy::trivially_copy_pass_by_ref,
450        reason = "serde `serialize_with` / `with` requires a `&T` signature"
451    )]
452    pub fn serialize<S: Serializer>(span: &Span, serializer: S) -> Result<S::Ok, S::Error> {
453        [span.start, span.end].serialize(serializer)
454    }
455
456    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Span, D::Error> {
457        let [start, end] = <[u32; 2]>::deserialize(deserializer)?;
458        Ok(Span::new(start, end))
459    }
460}
461
462/// Lossless cache (de)serialization for `Vec<MemberInfo>`.
463///
464/// `fallow_types::extract::MemberInfo` derives only `serde::Serialize`, and its
465/// `span` field uses `serialize_with` with no matching deserializer, so it
466/// cannot be deserialized through a plain derive. Rather than change the shared
467/// type's serde shape (which would ripple into JSON output), the cache mirrors
468/// it field-for-field into a dedicated `CachedMemberInfo` and converts both
469/// ways. Every `MemberInfo` field is carried, so the round-trip is lossless.
470pub(crate) mod member_serde {
471    use fallow_types::extract::{MemberInfo, MemberKind};
472    use oxc_span::Span;
473    use serde::{Deserialize, Deserializer, Serialize, Serializer};
474
475    #[derive(Serialize, Deserialize)]
476    struct CachedMemberInfo {
477        name: String,
478        kind: MemberKind,
479        span: [u32; 2],
480        has_decorator: bool,
481        decorator_names: Vec<String>,
482        is_instance_returning_static: bool,
483        is_self_returning: bool,
484    }
485
486    impl From<&MemberInfo> for CachedMemberInfo {
487        fn from(member: &MemberInfo) -> Self {
488            Self {
489                name: member.name.clone(),
490                kind: member.kind,
491                span: [member.span.start, member.span.end],
492                has_decorator: member.has_decorator,
493                decorator_names: member.decorator_names.clone(),
494                is_instance_returning_static: member.is_instance_returning_static,
495                is_self_returning: member.is_self_returning,
496            }
497        }
498    }
499
500    impl From<CachedMemberInfo> for MemberInfo {
501        fn from(cached: CachedMemberInfo) -> Self {
502            Self {
503                name: cached.name,
504                kind: cached.kind,
505                span: Span::new(cached.span[0], cached.span[1]),
506                has_decorator: cached.has_decorator,
507                decorator_names: cached.decorator_names,
508                is_instance_returning_static: cached.is_instance_returning_static,
509                is_self_returning: cached.is_self_returning,
510            }
511        }
512    }
513
514    pub fn serialize<S: Serializer>(
515        members: &[MemberInfo],
516        serializer: S,
517    ) -> Result<S::Ok, S::Error> {
518        let mirror: Vec<CachedMemberInfo> = members.iter().map(CachedMemberInfo::from).collect();
519        mirror.serialize(serializer)
520    }
521
522    pub fn deserialize<'de, D: Deserializer<'de>>(
523        deserializer: D,
524    ) -> Result<Vec<MemberInfo>, D::Error> {
525        let mirror = Vec::<CachedMemberInfo>::deserialize(deserializer)?;
526        Ok(mirror.into_iter().map(MemberInfo::from).collect())
527    }
528}
529
530/// Option dimensions that affect graph construction.
531///
532/// The hashes are intentionally opaque to this crate. Callers decide which
533/// resolver/plugin/entry-point inputs feed each hash, while this contract keeps
534/// graph-cache validation explicit and typed.
535#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
536pub struct GraphCacheMode {
537    /// Import resolver and tsconfig-relevant options.
538    pub resolver_options_hash: u64,
539    /// Entry point set and reachability root options.
540    pub entry_points_hash: u64,
541    /// Plugin-derived graph-affecting configuration.
542    pub plugin_config_hash: u64,
543}
544
545impl GraphCacheMode {
546    /// Build a mode from explicit hash dimensions.
547    #[must_use]
548    pub const fn new(
549        resolver_options_hash: u64,
550        entry_points_hash: u64,
551        plugin_config_hash: u64,
552    ) -> Self {
553        Self {
554            resolver_options_hash,
555            entry_points_hash,
556            plugin_config_hash,
557        }
558    }
559}
560
561/// Source freshness for one file in a graph-cache manifest.
562#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
563pub struct GraphCacheFile {
564    /// Persistable identity for the file.
565    pub key: StableFileKey,
566    /// Current in-memory identifier for the file.
567    ///
568    /// The stable key is the durable identity, but the persisted `ModuleGraph`
569    /// is still `FileId`-keyed. Until a future graph-cache format remaps graph
570    /// edges through stable keys, a changed assignment must miss rather than
571    /// trust a graph whose `modules[file_id]` indexes point at different files.
572    pub file_id: FileId,
573    /// Metadata fingerprint for cache invalidation.
574    pub fingerprint: SourceFingerprint,
575}
576
577impl GraphCacheFile {
578    /// Build a graph-cache file row from a discovered file and fingerprint.
579    #[must_use]
580    pub fn from_discovered_file(
581        root: &Path,
582        file: &DiscoveredFile,
583        fingerprint: SourceFingerprint,
584    ) -> Self {
585        Self {
586            key: StableFileKey::from_root_relative(root, &file.path),
587            file_id: file.id,
588            fingerprint,
589        }
590    }
591}
592
593/// Manifest inputs required to trust a persisted graph cache entry.
594#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
595pub struct GraphCacheManifest {
596    /// Schema version used by the persisted graph-cache entry.
597    pub version: u32,
598    /// Graph-affecting option dimensions.
599    pub mode: GraphCacheMode,
600    /// Stable file identities, current FileId assignments, and freshness metadata.
601    pub files: Vec<GraphCacheFile>,
602}
603
604impl GraphCacheManifest {
605    /// Build a manifest and sort files by stable key for deterministic compare.
606    #[must_use]
607    pub fn new(mode: GraphCacheMode, mut files: Vec<GraphCacheFile>) -> Self {
608        sort_files(&mut files);
609        Self {
610            version: GRAPH_CACHE_VERSION,
611            mode,
612            files,
613        }
614    }
615
616    /// Build a manifest from discovered files plus a fingerprint provider.
617    pub fn from_discovered_files(
618        root: &Path,
619        files: &[DiscoveredFile],
620        mode: GraphCacheMode,
621        mut fingerprint_for_path: impl FnMut(&Path) -> SourceFingerprint,
622    ) -> Self {
623        let rows = files
624            .iter()
625            .map(|file| {
626                GraphCacheFile::from_discovered_file(root, file, fingerprint_for_path(&file.path))
627            })
628            .collect();
629        Self::new(mode, rows)
630    }
631
632    /// True when a persisted manifest matches the current graph inputs.
633    #[must_use]
634    pub fn matches_inputs(&self, current: &Self) -> bool {
635        self.version == GRAPH_CACHE_VERSION
636            && current.version == GRAPH_CACHE_VERSION
637            && self.mode == current.mode
638            && self.files == current.files
639    }
640
641    /// True when a persisted resolver payload can be remapped to current FileIds.
642    ///
643    /// Unlike [`Self::matches_inputs`], this intentionally ignores each row's
644    /// `file_id`. It is not sufficient to trust the persisted `ModuleGraph`, but
645    /// it is sufficient to reuse stable-keyed resolver output and rebuild the
646    /// graph with current FileIds.
647    #[must_use]
648    pub fn matches_resolution_inputs(&self, current: &Self) -> bool {
649        self.version == GRAPH_CACHE_VERSION
650            && current.version == GRAPH_CACHE_VERSION
651            && self.mode == current.mode
652            && self.files.len() == current.files.len()
653            && self
654                .files
655                .iter()
656                .zip(current.files.iter())
657                .all(|(cached, current)| {
658                    cached.key == current.key && cached.fingerprint == current.fingerprint
659                })
660    }
661}
662
663fn sort_files(files: &mut [GraphCacheFile]) {
664    files.sort_unstable_by(|a, b| a.key.cmp(&b.key));
665}
666
667#[cfg(test)]
668mod tests {
669    use std::path::{Path, PathBuf};
670
671    use fallow_types::discover::FileId;
672    use rustc_hash::FxHashMap;
673
674    use super::*;
675
676    fn file(id: u32, path: &str) -> DiscoveredFile {
677        DiscoveredFile {
678            id: FileId(id),
679            path: PathBuf::from(path),
680            size_bytes: 1,
681        }
682    }
683
684    fn mode() -> GraphCacheMode {
685        GraphCacheMode::new(1, 2, 3)
686    }
687
688    fn fingerprints(pairs: &[(&str, SourceFingerprint)]) -> FxHashMap<PathBuf, SourceFingerprint> {
689        pairs
690            .iter()
691            .map(|(path, fingerprint)| (PathBuf::from(path), *fingerprint))
692            .collect()
693    }
694
695    fn manifest(
696        files: &[DiscoveredFile],
697        mode: GraphCacheMode,
698        map: &FxHashMap<PathBuf, SourceFingerprint>,
699    ) -> GraphCacheManifest {
700        GraphCacheManifest::from_discovered_files(Path::new("/project"), files, mode, |path| {
701            *map.get(path).unwrap()
702        })
703    }
704
705    fn import_info(source: &str) -> ImportInfo {
706        ImportInfo {
707            source: source.to_string(),
708            imported_name: fallow_types::extract::ImportedName::SideEffect,
709            local_name: String::new(),
710            is_type_only: false,
711            from_style: false,
712            span: Span::new(0, 0),
713            source_span: Span::new(0, 0),
714        }
715    }
716
717    #[test]
718    fn manifest_sorts_by_stable_file_key() {
719        let files = vec![file(0, "/project/src/z.ts"), file(1, "/project/src/a.ts")];
720        let map = fingerprints(&[
721            ("/project/src/z.ts", SourceFingerprint::new(10, 1)),
722            ("/project/src/a.ts", SourceFingerprint::new(20, 1)),
723        ]);
724
725        let manifest = manifest(&files, mode(), &map);
726
727        let keys: Vec<&str> = manifest
728            .files
729            .iter()
730            .map(|file| file.key.as_str())
731            .collect();
732        assert_eq!(keys, vec!["src/a.ts", "src/z.ts"]);
733    }
734
735    #[test]
736    fn manifest_misses_on_file_id_shift_until_graph_remap_exists() {
737        let before = vec![file(0, "/project/src/a.ts"), file(1, "/project/src/c.ts")];
738        let after = vec![file(9, "/project/src/c.ts"), file(2, "/project/src/a.ts")];
739        let map = fingerprints(&[
740            ("/project/src/a.ts", SourceFingerprint::new(10, 1)),
741            ("/project/src/c.ts", SourceFingerprint::new(20, 1)),
742        ]);
743
744        let cached = manifest(&before, mode(), &map);
745        let current = manifest(&after, mode(), &map);
746
747        assert!(
748            !cached.matches_inputs(&current),
749            "the persisted graph is still FileId-keyed, so FileId shifts cannot trust it"
750        );
751        assert!(
752            cached.matches_resolution_inputs(&current),
753            "stable-keyed resolver payloads may be remapped across FileId shifts"
754        );
755    }
756
757    #[test]
758    fn cached_resolve_result_remaps_internal_targets_by_stable_key() {
759        let key_a = StableFileKey::from_root_relative(
760            Path::new("/project"),
761            Path::new("/project/src/a.ts"),
762        );
763        let key_b = StableFileKey::from_root_relative(
764            Path::new("/project"),
765            Path::new("/project/src/b.ts"),
766        );
767        let key_by_file_id =
768            FxHashMap::from_iter([(FileId(0), key_a.clone()), (FileId(1), key_b.clone())]);
769        let id_by_key = FxHashMap::from_iter([(key_a, FileId(7)), (key_b, FileId(9))]);
770
771        let cached = CachedResolveResult::from_resolve_result(
772            &ResolveResult::InternalPackageModule {
773                file_id: FileId(1),
774                package_name: "@scope/pkg".to_string(),
775            },
776            &key_by_file_id,
777        )
778        .expect("target file id should map to a stable key");
779
780        let restored = cached
781            .into_resolve_result(&id_by_key)
782            .expect("stable key should map to current FileId");
783
784        assert!(matches!(
785            restored,
786            ResolveResult::InternalPackageModule {
787                file_id: FileId(9),
788                ref package_name,
789            } if package_name == "@scope/pkg"
790        ));
791    }
792
793    #[test]
794    fn cache_resolved_modules_rejects_unknown_internal_targets() {
795        let files = vec![file(0, "/project/src/a.ts")];
796        let module = ResolvedModule {
797            file_id: FileId(0),
798            path: PathBuf::from("/project/src/a.ts"),
799            resolved_imports: vec![ResolvedImport {
800                info: import_info("./missing"),
801                target: ResolveResult::InternalModule(FileId(1)),
802            }],
803            ..ResolvedModule::default()
804        };
805
806        let cached = cache_resolved_modules(Path::new("/project"), &files, &[module]);
807
808        assert!(cached.is_none());
809    }
810
811    #[test]
812    fn manifest_misses_on_fingerprint_change() {
813        let files = vec![file(0, "/project/src/a.ts")];
814        let cached_map = fingerprints(&[("/project/src/a.ts", SourceFingerprint::new(10, 1))]);
815        let current_map = fingerprints(&[("/project/src/a.ts", SourceFingerprint::new(11, 1))]);
816
817        let cached = manifest(&files, mode(), &cached_map);
818        let current = manifest(&files, mode(), &current_map);
819
820        assert!(!cached.matches_inputs(&current));
821    }
822
823    #[test]
824    fn manifest_misses_on_file_deletion() {
825        let before = vec![
826            file(0, "/project/src/a.ts"),
827            file(1, "/project/src/deleted.ts"),
828        ];
829        let after = vec![file(0, "/project/src/a.ts")];
830        let map = fingerprints(&[
831            ("/project/src/a.ts", SourceFingerprint::new(10, 1)),
832            ("/project/src/deleted.ts", SourceFingerprint::new(20, 1)),
833        ]);
834
835        let cached = manifest(&before, mode(), &map);
836        let current = manifest(&after, mode(), &map);
837
838        assert!(!cached.matches_inputs(&current));
839    }
840
841    #[test]
842    fn manifest_misses_on_file_rename_with_same_fingerprint() {
843        let before = vec![file(0, "/project/src/old.ts")];
844        let after = vec![file(0, "/project/src/new.ts")];
845        let map = fingerprints(&[
846            ("/project/src/old.ts", SourceFingerprint::new(10, 1)),
847            ("/project/src/new.ts", SourceFingerprint::new(10, 1)),
848        ]);
849
850        let cached = manifest(&before, mode(), &map);
851        let current = manifest(&after, mode(), &map);
852
853        assert!(!cached.matches_inputs(&current));
854    }
855
856    #[test]
857    fn manifest_misses_on_workspace_scoped_file_set() {
858        let full_project = vec![
859            file(0, "/project/packages/app/src/index.ts"),
860            file(1, "/project/packages/shared/src/index.ts"),
861        ];
862        let workspace_scoped = vec![file(0, "/project/packages/app/src/index.ts")];
863        let map = fingerprints(&[
864            (
865                "/project/packages/app/src/index.ts",
866                SourceFingerprint::new(10, 1),
867            ),
868            (
869                "/project/packages/shared/src/index.ts",
870                SourceFingerprint::new(20, 1),
871            ),
872        ]);
873
874        let cached = manifest(&full_project, mode(), &map);
875        let current = manifest(&workspace_scoped, mode(), &map);
876
877        assert!(!cached.matches_inputs(&current));
878        assert!(!cached.matches_resolution_inputs(&current));
879    }
880
881    #[test]
882    fn manifest_misses_on_mode_change() {
883        let files = vec![file(0, "/project/src/a.ts")];
884        let map = fingerprints(&[("/project/src/a.ts", SourceFingerprint::new(10, 1))]);
885
886        let cached = manifest(&files, mode(), &map);
887        let current = manifest(&files, GraphCacheMode::new(1, 99, 3), &map);
888
889        assert!(!cached.matches_inputs(&current));
890    }
891
892    #[test]
893    fn manifest_misses_on_version_change() {
894        let files = vec![file(0, "/project/src/a.ts")];
895        let map = fingerprints(&[("/project/src/a.ts", SourceFingerprint::new(10, 1))]);
896        let mut cached = manifest(&files, mode(), &map);
897        let current = manifest(&files, mode(), &map);
898
899        cached.version = GRAPH_CACHE_VERSION + 1;
900
901        assert!(!cached.matches_inputs(&current));
902    }
903}
fallow_graph/cache/mod.rs

fallow_graph/cache/
mod.rs
