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