Skip to main content

fallow_graph/
read_trace.rs

1//! Trace of the paths that import resolution reads.
2//!
3//! The persisted graph cache stores import resolutions. A warm run can only
4//! reuse them when the cache key covers each path that the resolution read.
5//! With the `read-trace` feature, the file system calls of `oxc_resolver` and
6//! the direct path checks of the resolution fallbacks report their paths
7//! here, and `ReadRecorder` collects the paths below a scope directory.
8//! Tests use the recorded read set to check that the cache key covers each
9//! path.
10//!
11//! The trace does not see the manifest loads in `fallow_config` (the
12//! `package.json` and Deno configs of the project and workspace roots, and
13//! the `tsconfig.json` chains), or the read of `.pnp.cjs` in the `pnp` crate.
14//! The resolver input hash reads each of these files by name.
15//!
16//! Without the feature, the trace records nothing, so a release build pays
17//! no cost for it. The helpers report missed paths and read package
18//! manifests to [`crate::missed_probes`] in every build.
19
20use std::io;
21use std::path::{Path, PathBuf};
22
23use oxc_resolver::{FileMetadata, FileSystem, FileSystemOs, ResolveError};
24
25use crate::missed_probes;
26
27/// What a resolution step learned from a path.
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
29pub enum ReadKind {
30    /// The step read the content of the path.
31    Content,
32    /// The step checked if the path exists, or if it is a file.
33    File,
34    /// The step checked if the path is a directory.
35    Dir,
36}
37
38/// The file system of the `oxc_resolver` instances that resolution builds.
39/// It reports each missed path to [`crate::missed_probes`], and with the
40/// `read-trace` feature each call to the read trace.
41pub(crate) type ResolverFs = ProbeFs;
42
43/// The resolver type of the resolution stage.
44pub(crate) type Resolver = oxc_resolver::ResolverGeneric<ResolverFs>;
45
46#[cfg(feature = "read-trace")]
47pub use recording::{ReadEvent, ReadRecorder};
48
49#[cfg(feature = "read-trace")]
50use recording::note;
51
52#[cfg(not(feature = "read-trace"))]
53#[inline(always)]
54const fn note(_path: &Path, _kind: ReadKind) {}
55
56/// Path checks that report the path to the read trace.
57pub(crate) trait TracedPath {
58    /// [`Path::is_file`], recorded as a [`ReadKind::File`] read.
59    fn traced_is_file(&self) -> bool;
60    /// [`Path::is_dir`], recorded as a [`ReadKind::Dir`] read.
61    fn traced_is_dir(&self) -> bool;
62    /// [`Path::exists`], recorded as a [`ReadKind::File`] read.
63    fn traced_exists(&self) -> bool;
64}
65
66impl TracedPath for Path {
67    fn traced_is_file(&self) -> bool {
68        note(self, ReadKind::File);
69        checked_metadata(self).is_ok_and(|metadata| metadata.is_file())
70    }
71
72    fn traced_is_dir(&self) -> bool {
73        note(self, ReadKind::Dir);
74        checked_metadata(self).is_ok_and(|metadata| metadata.is_dir())
75    }
76
77    fn traced_exists(&self) -> bool {
78        note(self, ReadKind::File);
79        checked_metadata(self).is_ok()
80    }
81}
82
83/// [`std::fs::metadata`], with a missing path reported as a missed probe.
84fn checked_metadata(path: &Path) -> io::Result<std::fs::Metadata> {
85    let result = std::fs::metadata(path);
86    missed_probes::note_if_missing(path, &result);
87    result
88}
89
90/// [`std::fs::read_to_string`], recorded as a content read.
91pub(crate) fn read_to_string(path: impl AsRef<Path>) -> io::Result<String> {
92    let path = path.as_ref();
93    let result = std::fs::read_to_string(path);
94    missed_probes::note_read(path, &result);
95    note(path, content_kind(result.is_ok()));
96    result
97}
98
99/// [`dunce::canonicalize`], recorded as a [`ReadKind::File`] read.
100pub(crate) fn canonicalize(path: impl AsRef<Path>) -> io::Result<PathBuf> {
101    let path = path.as_ref();
102    note(path, ReadKind::File);
103    let result = dunce::canonicalize(path);
104    missed_probes::note_if_missing(path, &result);
105    result
106}
107
108/// The operating system file system of the resolver. Each call that finds
109/// no path reports it as a missed probe, and each call goes to the read
110/// trace.
111pub(crate) struct ProbeFs(FileSystemOs);
112
113impl FileSystem for ProbeFs {
114    fn new(yarn_pnp: bool) -> Self {
115        Self(FileSystemOs::new(yarn_pnp))
116    }
117
118    fn read(&self, path: &Path) -> io::Result<Vec<u8>> {
119        let result = self.0.read(path);
120        missed_probes::note_read(path, &result);
121        note(path, content_kind(result.is_ok()));
122        result
123    }
124
125    fn read_to_string(&self, path: &Path) -> io::Result<String> {
126        let result = self.0.read_to_string(path);
127        missed_probes::note_read(path, &result);
128        note(path, content_kind(result.is_ok()));
129        result
130    }
131
132    fn metadata(&self, path: &Path) -> io::Result<FileMetadata> {
133        note(path, ReadKind::File);
134        let result = self.0.metadata(path);
135        missed_probes::note_if_missing(path, &result);
136        result
137    }
138
139    fn symlink_metadata(&self, path: &Path) -> io::Result<FileMetadata> {
140        note(path, ReadKind::File);
141        let result = self.0.symlink_metadata(path);
142        missed_probes::note_if_missing(path, &result);
143        result
144    }
145
146    fn read_link(&self, path: &Path) -> Result<PathBuf, ResolveError> {
147        note(path, ReadKind::File);
148        self.0.read_link(path)
149    }
150
151    fn canonicalize(&self, path: &Path) -> io::Result<PathBuf> {
152        note(path, ReadKind::File);
153        let result = self.0.canonicalize(path);
154        missed_probes::note_if_missing(path, &result);
155        result
156    }
157}
158
159/// A content read of a missing file only learned that the file is absent.
160const fn content_kind(found: bool) -> ReadKind {
161    if found {
162        ReadKind::Content
163    } else {
164        ReadKind::File
165    }
166}
167
168#[cfg(feature = "read-trace")]
169mod recording {
170    use std::path::{Path, PathBuf};
171    use std::sync::Mutex;
172    use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
173
174    use rustc_hash::FxHashSet;
175
176    use super::ReadKind;
177
178    /// One recorded read.
179    #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
180    pub struct ReadEvent {
181        /// The absolute path, as the resolution step spelled it.
182        pub path: PathBuf,
183        /// What the step learned from the path.
184        pub kind: ReadKind,
185    }
186
187    struct Active {
188        id: u64,
189        scopes: Vec<PathBuf>,
190        events: FxHashSet<ReadEvent>,
191    }
192
193    /// The number of open recorders. A zero count keeps [`note`] at one
194    /// atomic load, so tests that do not record pay almost nothing.
195    static OPEN: AtomicUsize = AtomicUsize::new(0);
196    static NEXT_ID: AtomicU64 = AtomicU64::new(0);
197    static RECORDERS: Mutex<Vec<Active>> = Mutex::new(Vec::new());
198
199    /// Collects the reads below one scope directory until [`Self::finish`].
200    ///
201    /// Recorders are process-wide, because resolution runs on rayon workers.
202    /// Tests that run at the same time stay apart when each one uses its own
203    /// temporary directory as the scope.
204    #[derive(Debug)]
205    pub struct ReadRecorder {
206        id: u64,
207    }
208
209    impl ReadRecorder {
210        /// Start to record the reads of paths below `scope`. The recorder
211        /// also matches the canonical spelling of `scope`.
212        #[must_use]
213        pub fn start(scope: &Path) -> Self {
214            let mut scopes = vec![scope.to_path_buf()];
215            if let Ok(canonical) = dunce::canonicalize(scope)
216                && canonical != scope
217            {
218                scopes.push(canonical);
219            }
220            let id = NEXT_ID.fetch_add(1, Ordering::Relaxed);
221            RECORDERS
222                .lock()
223                .unwrap_or_else(|e| e.into_inner())
224                .push(Active {
225                    id,
226                    scopes,
227                    events: FxHashSet::default(),
228                });
229            OPEN.fetch_add(1, Ordering::SeqCst);
230            Self { id }
231        }
232
233        /// Stop the recorder and return its reads, sorted by path and kind.
234        #[must_use]
235        pub fn finish(self) -> Vec<ReadEvent> {
236            let Some(active) = remove(self.id) else {
237                return Vec::new();
238            };
239            let mut events: Vec<ReadEvent> = active.events.into_iter().collect();
240            events.sort_unstable();
241            events
242        }
243    }
244
245    /// A test that panics before [`ReadRecorder::finish`] must not leave the
246    /// recorder open, or each later file system call takes the lock.
247    impl Drop for ReadRecorder {
248        fn drop(&mut self) {
249            let _ = remove(self.id);
250        }
251    }
252
253    fn remove(id: u64) -> Option<Active> {
254        let active = {
255            let mut recorders = RECORDERS.lock().unwrap_or_else(|e| e.into_inner());
256            let index = recorders.iter().position(|active| active.id == id)?;
257            recorders.swap_remove(index)
258        };
259        OPEN.fetch_sub(1, Ordering::SeqCst);
260        Some(active)
261    }
262
263    pub fn note(path: &Path, kind: ReadKind) {
264        if OPEN.load(Ordering::Relaxed) == 0 || !path.is_absolute() {
265            return;
266        }
267        let mut recorders = RECORDERS.lock().unwrap_or_else(|e| e.into_inner());
268        for active in recorders.iter_mut() {
269            if active.scopes.iter().any(|scope| path.starts_with(scope)) {
270                active.events.insert(ReadEvent {
271                    path: path.to_path_buf(),
272                    kind,
273                });
274            }
275        }
276    }
277}