rustc_span/
source_map.rs

1//! Types for tracking pieces of source code within a crate.
2//!
3//! The [`SourceMap`] tracks all the source code used within a single crate, mapping
4//! from integer byte positions to the original source code location. Each bit
5//! of source parsed during crate parsing (typically files, in-memory strings,
6//! or various bits of macro expansion) cover a continuous range of bytes in the
7//! `SourceMap` and are represented by [`SourceFile`]s. Byte positions are stored in
8//! [`Span`] and used pervasively in the compiler. They are absolute positions
9//! within the `SourceMap`, which upon request can be converted to line and column
10//! information, source code snippets, etc.
11
12use std::io::{self, BorrowedBuf, Read};
13use std::{fs, path};
14
15use rustc_data_structures::sync::{IntoDynSyncSend, MappedReadGuard, ReadGuard, RwLock};
16use rustc_data_structures::unhash::UnhashMap;
17use rustc_macros::{Decodable, Encodable};
18use tracing::{debug, instrument, trace};
19
20use crate::*;
21
22#[cfg(test)]
23mod tests;
24
25/// Returns the span itself if it doesn't come from a macro expansion,
26/// otherwise return the call site span up to the `enclosing_sp` by
27/// following the `expn_data` chain.
28pub fn original_sp(sp: Span, enclosing_sp: Span) -> Span {
29    let ctxt = sp.ctxt();
30    if ctxt.is_root() {
31        return sp;
32    }
33
34    let enclosing_ctxt = enclosing_sp.ctxt();
35    let expn_data1 = ctxt.outer_expn_data();
36    if !enclosing_ctxt.is_root()
37        && expn_data1.call_site == enclosing_ctxt.outer_expn_data().call_site
38    {
39        sp
40    } else {
41        original_sp(expn_data1.call_site, enclosing_sp)
42    }
43}
44
45mod monotonic {
46    use std::ops::{Deref, DerefMut};
47
48    /// A `MonotonicVec` is a `Vec` which can only be grown.
49    /// Once inserted, an element can never be removed or swapped,
50    /// guaranteeing that any indices into a `MonotonicVec` are stable
51    // This is declared in its own module to ensure that the private
52    // field is inaccessible
53    pub struct MonotonicVec<T>(Vec<T>);
54    impl<T> MonotonicVec<T> {
55        pub(super) fn push(&mut self, val: T) {
56            self.0.push(val);
57        }
58    }
59
60    impl<T> Default for MonotonicVec<T> {
61        fn default() -> Self {
62            MonotonicVec(vec![])
63        }
64    }
65
66    impl<T> Deref for MonotonicVec<T> {
67        type Target = Vec<T>;
68        fn deref(&self) -> &Self::Target {
69            &self.0
70        }
71    }
72
73    impl<T> !DerefMut for MonotonicVec<T> {}
74}
75
76#[derive(Clone, Encodable, Decodable, Debug, Copy, PartialEq, Hash, HashStable_Generic)]
77pub struct Spanned<T> {
78    pub node: T,
79    pub span: Span,
80}
81
82pub fn respan<T>(sp: Span, t: T) -> Spanned<T> {
83    Spanned { node: t, span: sp }
84}
85
86pub fn dummy_spanned<T>(t: T) -> Spanned<T> {
87    respan(DUMMY_SP, t)
88}
89
90// _____________________________________________________________________________
91// SourceFile, MultiByteChar, FileName, FileLines
92//
93
94/// An abstraction over the fs operations used by the Parser.
95pub trait FileLoader {
96    /// Query the existence of a file.
97    fn file_exists(&self, path: &Path) -> bool;
98
99    /// Read the contents of a UTF-8 file into memory.
100    /// This function must return a String because we normalize
101    /// source files, which may require resizing.
102    fn read_file(&self, path: &Path) -> io::Result<String>;
103
104    /// Read the contents of a potentially non-UTF-8 file into memory.
105    /// We don't normalize binary files, so we can start in an Arc.
106    fn read_binary_file(&self, path: &Path) -> io::Result<Arc<[u8]>>;
107}
108
109/// A FileLoader that uses std::fs to load real files.
110pub struct RealFileLoader;
111
112impl FileLoader for RealFileLoader {
113    fn file_exists(&self, path: &Path) -> bool {
114        path.exists()
115    }
116
117    fn read_file(&self, path: &Path) -> io::Result<String> {
118        if path.metadata().is_ok_and(|metadata| metadata.len() > SourceFile::MAX_FILE_SIZE.into()) {
119            return Err(io::Error::other(format!(
120                "text files larger than {} bytes are unsupported",
121                SourceFile::MAX_FILE_SIZE
122            )));
123        }
124        fs::read_to_string(path)
125    }
126
127    fn read_binary_file(&self, path: &Path) -> io::Result<Arc<[u8]>> {
128        let mut file = fs::File::open(path)?;
129        let len = file.metadata()?.len();
130
131        let mut bytes = Arc::new_uninit_slice(len as usize);
132        let mut buf = BorrowedBuf::from(Arc::get_mut(&mut bytes).unwrap());
133        match file.read_buf_exact(buf.unfilled()) {
134            Ok(()) => {}
135            Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => {
136                drop(bytes);
137                return fs::read(path).map(Vec::into);
138            }
139            Err(e) => return Err(e),
140        }
141        // SAFETY: If the read_buf_exact call returns Ok(()), then we have
142        // read len bytes and initialized the buffer.
143        let bytes = unsafe { bytes.assume_init() };
144
145        // At this point, we've read all the bytes that filesystem metadata reported exist.
146        // But we are not guaranteed to be at the end of the file, because we did not attempt to do
147        // a read with a non-zero-sized buffer and get Ok(0).
148        // So we do small read to a fixed-size buffer. If the read returns no bytes then we're
149        // already done, and we just return the Arc we built above.
150        // If the read returns bytes however, we just fall back to reading into a Vec then turning
151        // that into an Arc, losing our nice peak memory behavior. This fallback code path should
152        // be rarely exercised.
153
154        let mut probe = [0u8; 32];
155        let n = loop {
156            match file.read(&mut probe) {
157                Ok(0) => return Ok(bytes),
158                Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
159                Err(e) => return Err(e),
160                Ok(n) => break n,
161            }
162        };
163        let mut bytes: Vec<u8> = bytes.iter().copied().chain(probe[..n].iter().copied()).collect();
164        file.read_to_end(&mut bytes)?;
165        Ok(bytes.into())
166    }
167}
168
169// _____________________________________________________________________________
170// SourceMap
171//
172
173#[derive(Default)]
174struct SourceMapFiles {
175    source_files: monotonic::MonotonicVec<Arc<SourceFile>>,
176    stable_id_to_source_file: UnhashMap<StableSourceFileId, Arc<SourceFile>>,
177}
178
179/// Used to construct a `SourceMap` with `SourceMap::with_inputs`.
180pub struct SourceMapInputs {
181    pub file_loader: Box<dyn FileLoader + Send + Sync>,
182    pub path_mapping: FilePathMapping,
183    pub hash_kind: SourceFileHashAlgorithm,
184    pub checksum_hash_kind: Option<SourceFileHashAlgorithm>,
185}
186
187pub struct SourceMap {
188    files: RwLock<SourceMapFiles>,
189    file_loader: IntoDynSyncSend<Box<dyn FileLoader + Sync + Send>>,
190
191    // This is used to apply the file path remapping as specified via
192    // `--remap-path-prefix` to all `SourceFile`s allocated within this `SourceMap`.
193    path_mapping: FilePathMapping,
194
195    /// The algorithm used for hashing the contents of each source file.
196    hash_kind: SourceFileHashAlgorithm,
197
198    /// Similar to `hash_kind`, however this algorithm is used for checksums to determine if a crate is fresh.
199    /// `cargo` is the primary user of these.
200    ///
201    /// If this is equal to `hash_kind` then the checksum won't be computed twice.
202    checksum_hash_kind: Option<SourceFileHashAlgorithm>,
203}
204
205impl SourceMap {
206    pub fn new(path_mapping: FilePathMapping) -> SourceMap {
207        Self::with_inputs(SourceMapInputs {
208            file_loader: Box::new(RealFileLoader),
209            path_mapping,
210            hash_kind: SourceFileHashAlgorithm::Md5,
211            checksum_hash_kind: None,
212        })
213    }
214
215    pub fn with_inputs(
216        SourceMapInputs { file_loader, path_mapping, hash_kind, checksum_hash_kind }: SourceMapInputs,
217    ) -> SourceMap {
218        SourceMap {
219            files: Default::default(),
220            file_loader: IntoDynSyncSend(file_loader),
221            path_mapping,
222            hash_kind,
223            checksum_hash_kind,
224        }
225    }
226
227    pub fn path_mapping(&self) -> &FilePathMapping {
228        &self.path_mapping
229    }
230
231    pub fn file_exists(&self, path: &Path) -> bool {
232        self.file_loader.file_exists(path)
233    }
234
235    pub fn load_file(&self, path: &Path) -> io::Result<Arc<SourceFile>> {
236        let src = self.file_loader.read_file(path)?;
237        let filename = path.to_owned().into();
238        Ok(self.new_source_file(filename, src))
239    }
240
241    /// Loads source file as a binary blob.
242    ///
243    /// Unlike `load_file`, guarantees that no normalization like BOM-removal
244    /// takes place.
245    pub fn load_binary_file(&self, path: &Path) -> io::Result<(Arc<[u8]>, Span)> {
246        let bytes = self.file_loader.read_binary_file(path)?;
247
248        // We need to add file to the `SourceMap`, so that it is present
249        // in dep-info. There's also an edge case that file might be both
250        // loaded as a binary via `include_bytes!` and as proper `SourceFile`
251        // via `mod`, so we try to use real file contents and not just an
252        // empty string.
253        let text = std::str::from_utf8(&bytes).unwrap_or("").to_string();
254        let file = self.new_source_file(path.to_owned().into(), text);
255        Ok((
256            bytes,
257            Span::new(
258                file.start_pos,
259                BytePos(file.start_pos.0 + file.source_len.0),
260                SyntaxContext::root(),
261                None,
262            ),
263        ))
264    }
265
266    // By returning a `MonotonicVec`, we ensure that consumers cannot invalidate
267    // any existing indices pointing into `files`.
268    pub fn files(&self) -> MappedReadGuard<'_, monotonic::MonotonicVec<Arc<SourceFile>>> {
269        ReadGuard::map(self.files.borrow(), |files| &files.source_files)
270    }
271
272    pub fn source_file_by_stable_id(
273        &self,
274        stable_id: StableSourceFileId,
275    ) -> Option<Arc<SourceFile>> {
276        self.files.borrow().stable_id_to_source_file.get(&stable_id).cloned()
277    }
278
279    fn register_source_file(
280        &self,
281        file_id: StableSourceFileId,
282        mut file: SourceFile,
283    ) -> Result<Arc<SourceFile>, OffsetOverflowError> {
284        let mut files = self.files.borrow_mut();
285
286        file.start_pos = BytePos(if let Some(last_file) = files.source_files.last() {
287            // Add one so there is some space between files. This lets us distinguish
288            // positions in the `SourceMap`, even in the presence of zero-length files.
289            last_file.end_position().0.checked_add(1).ok_or(OffsetOverflowError)?
290        } else {
291            0
292        });
293
294        let file = Arc::new(file);
295        files.source_files.push(Arc::clone(&file));
296        files.stable_id_to_source_file.insert(file_id, Arc::clone(&file));
297
298        Ok(file)
299    }
300
301    /// Creates a new `SourceFile`.
302    /// If a file already exists in the `SourceMap` with the same ID, that file is returned
303    /// unmodified.
304    pub fn new_source_file(&self, filename: FileName, src: String) -> Arc<SourceFile> {
305        self.try_new_source_file(filename, src).unwrap_or_else(|OffsetOverflowError| {
306            eprintln!(
307                "fatal error: rustc does not support text files larger than {} bytes",
308                SourceFile::MAX_FILE_SIZE
309            );
310            crate::fatal_error::FatalError.raise()
311        })
312    }
313
314    fn try_new_source_file(
315        &self,
316        filename: FileName,
317        src: String,
318    ) -> Result<Arc<SourceFile>, OffsetOverflowError> {
319        // Note that filename may not be a valid path, eg it may be `<anon>` etc,
320        // but this is okay because the directory determined by `path.pop()` will
321        // be empty, so the working directory will be used.
322        let (filename, _) = self.path_mapping.map_filename_prefix(&filename);
323
324        let stable_id = StableSourceFileId::from_filename_in_current_crate(&filename);
325        match self.source_file_by_stable_id(stable_id) {
326            Some(lrc_sf) => Ok(lrc_sf),
327            None => {
328                let source_file =
329                    SourceFile::new(filename, src, self.hash_kind, self.checksum_hash_kind)?;
330
331                // Let's make sure the file_id we generated above actually matches
332                // the ID we generate for the SourceFile we just created.
333                debug_assert_eq!(source_file.stable_id, stable_id);
334
335                self.register_source_file(stable_id, source_file)
336            }
337        }
338    }
339
340    /// Allocates a new `SourceFile` representing a source file from an external
341    /// crate. The source code of such an "imported `SourceFile`" is not available,
342    /// but we still know enough to generate accurate debuginfo location
343    /// information for things inlined from other crates.
344    pub fn new_imported_source_file(
345        &self,
346        filename: FileName,
347        src_hash: SourceFileHash,
348        checksum_hash: Option<SourceFileHash>,
349        stable_id: StableSourceFileId,
350        source_len: u32,
351        cnum: CrateNum,
352        file_local_lines: FreezeLock<SourceFileLines>,
353        multibyte_chars: Vec<MultiByteChar>,
354        normalized_pos: Vec<NormalizedPos>,
355        metadata_index: u32,
356    ) -> Arc<SourceFile> {
357        let source_len = RelativeBytePos::from_u32(source_len);
358
359        let source_file = SourceFile {
360            name: filename,
361            src: None,
362            src_hash,
363            checksum_hash,
364            external_src: FreezeLock::new(ExternalSource::Foreign {
365                kind: ExternalSourceKind::AbsentOk,
366                metadata_index,
367            }),
368            start_pos: BytePos(0),
369            source_len,
370            lines: file_local_lines,
371            multibyte_chars,
372            normalized_pos,
373            stable_id,
374            cnum,
375        };
376
377        self.register_source_file(stable_id, source_file)
378            .expect("not enough address space for imported source file")
379    }
380
381    /// If there is a doctest offset, applies it to the line.
382    pub fn doctest_offset_line(&self, file: &FileName, orig: usize) -> usize {
383        match file {
384            FileName::DocTest(_, offset) => {
385                if *offset < 0 {
386                    orig - (-(*offset)) as usize
387                } else {
388                    orig + *offset as usize
389                }
390            }
391            _ => orig,
392        }
393    }
394
395    /// Return the SourceFile that contains the given `BytePos`
396    pub fn lookup_source_file(&self, pos: BytePos) -> Arc<SourceFile> {
397        let idx = self.lookup_source_file_idx(pos);
398        Arc::clone(&(*self.files.borrow().source_files)[idx])
399    }
400
401    /// Looks up source information about a `BytePos`.
402    pub fn lookup_char_pos(&self, pos: BytePos) -> Loc {
403        let sf = self.lookup_source_file(pos);
404        let (line, col, col_display) = sf.lookup_file_pos_with_col_display(pos);
405        Loc { file: sf, line, col, col_display }
406    }
407
408    /// If the corresponding `SourceFile` is empty, does not return a line number.
409    pub fn lookup_line(&self, pos: BytePos) -> Result<SourceFileAndLine, Arc<SourceFile>> {
410        let f = self.lookup_source_file(pos);
411
412        let pos = f.relative_position(pos);
413        match f.lookup_line(pos) {
414            Some(line) => Ok(SourceFileAndLine { sf: f, line }),
415            None => Err(f),
416        }
417    }
418
419    pub fn span_to_string(
420        &self,
421        sp: Span,
422        filename_display_pref: FileNameDisplayPreference,
423    ) -> String {
424        let (source_file, lo_line, lo_col, hi_line, hi_col) = self.span_to_location_info(sp);
425
426        let file_name = match source_file {
427            Some(sf) => sf.name.display(filename_display_pref).to_string(),
428            None => return "no-location".to_string(),
429        };
430
431        format!(
432            "{file_name}:{lo_line}:{lo_col}{}",
433            if let FileNameDisplayPreference::Short = filename_display_pref {
434                String::new()
435            } else {
436                format!(": {hi_line}:{hi_col}")
437            }
438        )
439    }
440
441    pub fn span_to_location_info(
442        &self,
443        sp: Span,
444    ) -> (Option<Arc<SourceFile>>, usize, usize, usize, usize) {
445        if self.files.borrow().source_files.is_empty() || sp.is_dummy() {
446            return (None, 0, 0, 0, 0);
447        }
448
449        let lo = self.lookup_char_pos(sp.lo());
450        let hi = self.lookup_char_pos(sp.hi());
451        (Some(lo.file), lo.line, lo.col.to_usize() + 1, hi.line, hi.col.to_usize() + 1)
452    }
453
454    /// Format the span location suitable for embedding in build artifacts
455    pub fn span_to_embeddable_string(&self, sp: Span) -> String {
456        self.span_to_string(sp, FileNameDisplayPreference::Remapped)
457    }
458
459    /// Format the span location to be printed in diagnostics. Must not be emitted
460    /// to build artifacts as this may leak local file paths. Use span_to_embeddable_string
461    /// for string suitable for embedding.
462    pub fn span_to_diagnostic_string(&self, sp: Span) -> String {
463        self.span_to_string(sp, self.path_mapping.filename_display_for_diagnostics)
464    }
465
466    pub fn span_to_filename(&self, sp: Span) -> FileName {
467        self.lookup_char_pos(sp.lo()).file.name.clone()
468    }
469
470    pub fn filename_for_diagnostics<'a>(&self, filename: &'a FileName) -> FileNameDisplay<'a> {
471        filename.display(self.path_mapping.filename_display_for_diagnostics)
472    }
473
474    pub fn is_multiline(&self, sp: Span) -> bool {
475        let lo = self.lookup_source_file_idx(sp.lo());
476        let hi = self.lookup_source_file_idx(sp.hi());
477        if lo != hi {
478            return true;
479        }
480        let f = Arc::clone(&(*self.files.borrow().source_files)[lo]);
481        let lo = f.relative_position(sp.lo());
482        let hi = f.relative_position(sp.hi());
483        f.lookup_line(lo) != f.lookup_line(hi)
484    }
485
486    #[instrument(skip(self), level = "trace")]
487    pub fn is_valid_span(&self, sp: Span) -> Result<(Loc, Loc), SpanLinesError> {
488        let lo = self.lookup_char_pos(sp.lo());
489        trace!(?lo);
490        let hi = self.lookup_char_pos(sp.hi());
491        trace!(?hi);
492        if lo.file.start_pos != hi.file.start_pos {
493            return Err(SpanLinesError::DistinctSources(Box::new(DistinctSources {
494                begin: (lo.file.name.clone(), lo.file.start_pos),
495                end: (hi.file.name.clone(), hi.file.start_pos),
496            })));
497        }
498        Ok((lo, hi))
499    }
500
501    pub fn is_line_before_span_empty(&self, sp: Span) -> bool {
502        match self.span_to_prev_source(sp) {
503            Ok(s) => s.rsplit_once('\n').unwrap_or(("", &s)).1.trim_start().is_empty(),
504            Err(_) => false,
505        }
506    }
507
508    pub fn span_to_lines(&self, sp: Span) -> FileLinesResult {
509        debug!("span_to_lines(sp={:?})", sp);
510        let (lo, hi) = self.is_valid_span(sp)?;
511        assert!(hi.line >= lo.line);
512
513        if sp.is_dummy() {
514            return Ok(FileLines { file: lo.file, lines: Vec::new() });
515        }
516
517        let mut lines = Vec::with_capacity(hi.line - lo.line + 1);
518
519        // The span starts partway through the first line,
520        // but after that it starts from offset 0.
521        let mut start_col = lo.col;
522
523        // For every line but the last, it extends from `start_col`
524        // and to the end of the line. Be careful because the line
525        // numbers in Loc are 1-based, so we subtract 1 to get 0-based
526        // lines.
527        //
528        // FIXME: now that we handle DUMMY_SP up above, we should consider
529        // asserting that the line numbers here are all indeed 1-based.
530        let hi_line = hi.line.saturating_sub(1);
531        for line_index in lo.line.saturating_sub(1)..hi_line {
532            let line_len = lo.file.get_line(line_index).map_or(0, |s| s.chars().count());
533            lines.push(LineInfo { line_index, start_col, end_col: CharPos::from_usize(line_len) });
534            start_col = CharPos::from_usize(0);
535        }
536
537        // For the last line, it extends from `start_col` to `hi.col`:
538        lines.push(LineInfo { line_index: hi_line, start_col, end_col: hi.col });
539
540        Ok(FileLines { file: lo.file, lines })
541    }
542
543    /// Extracts the source surrounding the given `Span` using the `extract_source` function. The
544    /// extract function takes three arguments: a string slice containing the source, an index in
545    /// the slice for the beginning of the span and an index in the slice for the end of the span.
546    pub fn span_to_source<F, T>(&self, sp: Span, extract_source: F) -> Result<T, SpanSnippetError>
547    where
548        F: Fn(&str, usize, usize) -> Result<T, SpanSnippetError>,
549    {
550        let local_begin = self.lookup_byte_offset(sp.lo());
551        let local_end = self.lookup_byte_offset(sp.hi());
552
553        if local_begin.sf.start_pos != local_end.sf.start_pos {
554            Err(SpanSnippetError::DistinctSources(Box::new(DistinctSources {
555                begin: (local_begin.sf.name.clone(), local_begin.sf.start_pos),
556                end: (local_end.sf.name.clone(), local_end.sf.start_pos),
557            })))
558        } else {
559            self.ensure_source_file_source_present(&local_begin.sf);
560
561            let start_index = local_begin.pos.to_usize();
562            let end_index = local_end.pos.to_usize();
563            let source_len = local_begin.sf.source_len.to_usize();
564
565            if start_index > end_index || end_index > source_len {
566                return Err(SpanSnippetError::MalformedForSourcemap(MalformedSourceMapPositions {
567                    name: local_begin.sf.name.clone(),
568                    source_len,
569                    begin_pos: local_begin.pos,
570                    end_pos: local_end.pos,
571                }));
572            }
573
574            if let Some(ref src) = local_begin.sf.src {
575                extract_source(src, start_index, end_index)
576            } else if let Some(src) = local_begin.sf.external_src.read().get_source() {
577                extract_source(src, start_index, end_index)
578            } else {
579                Err(SpanSnippetError::SourceNotAvailable { filename: local_begin.sf.name.clone() })
580            }
581        }
582    }
583
584    pub fn is_span_accessible(&self, sp: Span) -> bool {
585        self.span_to_source(sp, |src, start_index, end_index| {
586            Ok(src.get(start_index..end_index).is_some())
587        })
588        .is_ok_and(|is_accessible| is_accessible)
589    }
590
591    /// Returns the source snippet as `String` corresponding to the given `Span`.
592    pub fn span_to_snippet(&self, sp: Span) -> Result<String, SpanSnippetError> {
593        self.span_to_source(sp, |src, start_index, end_index| {
594            src.get(start_index..end_index)
595                .map(|s| s.to_string())
596                .ok_or(SpanSnippetError::IllFormedSpan(sp))
597        })
598    }
599
600    pub fn span_to_margin(&self, sp: Span) -> Option<usize> {
601        Some(self.indentation_before(sp)?.len())
602    }
603
604    pub fn indentation_before(&self, sp: Span) -> Option<String> {
605        self.span_to_source(sp, |src, start_index, _| {
606            let before = &src[..start_index];
607            let last_line = before.rsplit_once('\n').map_or(before, |(_, last)| last);
608            Ok(last_line
609                .split_once(|c: char| !c.is_whitespace())
610                .map_or(last_line, |(indent, _)| indent)
611                .to_string())
612        })
613        .ok()
614    }
615
616    /// Returns the source snippet as `String` before the given `Span`.
617    pub fn span_to_prev_source(&self, sp: Span) -> Result<String, SpanSnippetError> {
618        self.span_to_source(sp, |src, start_index, _| {
619            src.get(..start_index).map(|s| s.to_string()).ok_or(SpanSnippetError::IllFormedSpan(sp))
620        })
621    }
622
623    /// Extends the given `Span` to just after the previous occurrence of `c`. Return the same span
624    /// if no character could be found or if an error occurred while retrieving the code snippet.
625    pub fn span_extend_to_prev_char(&self, sp: Span, c: char, accept_newlines: bool) -> Span {
626        if let Ok(prev_source) = self.span_to_prev_source(sp) {
627            let prev_source = prev_source.rsplit(c).next().unwrap_or("");
628            if !prev_source.is_empty() && (accept_newlines || !prev_source.contains('\n')) {
629                return sp.with_lo(BytePos(sp.lo().0 - prev_source.len() as u32));
630            }
631        }
632
633        sp
634    }
635
636    /// Extends the given `Span` to just before the previous occurrence of `c`. Return the same span
637    /// if an error occurred while retrieving the code snippet.
638    pub fn span_extend_to_prev_char_before(
639        &self,
640        sp: Span,
641        c: char,
642        accept_newlines: bool,
643    ) -> Span {
644        if let Ok(prev_source) = self.span_to_prev_source(sp) {
645            let prev_source = prev_source.rsplit(c).next().unwrap_or("");
646            if accept_newlines || !prev_source.contains('\n') {
647                return sp.with_lo(BytePos(sp.lo().0 - prev_source.len() as u32 - 1_u32));
648            }
649        }
650
651        sp
652    }
653
654    /// Extends the given `Span` to just after the previous occurrence of `pat` when surrounded by
655    /// whitespace. Returns None if the pattern could not be found or if an error occurred while
656    /// retrieving the code snippet.
657    pub fn span_extend_to_prev_str(
658        &self,
659        sp: Span,
660        pat: &str,
661        accept_newlines: bool,
662        include_whitespace: bool,
663    ) -> Option<Span> {
664        // assure that the pattern is delimited, to avoid the following
665        //     fn my_fn()
666        //           ^^^^ returned span without the check
667        //     ---------- correct span
668        let prev_source = self.span_to_prev_source(sp).ok()?;
669        for ws in &[" ", "\t", "\n"] {
670            let pat = pat.to_owned() + ws;
671            if let Some(pat_pos) = prev_source.rfind(&pat) {
672                let just_after_pat_pos = pat_pos + pat.len() - 1;
673                let just_after_pat_plus_ws = if include_whitespace {
674                    just_after_pat_pos
675                        + prev_source[just_after_pat_pos..]
676                            .find(|c: char| !c.is_whitespace())
677                            .unwrap_or(0)
678                } else {
679                    just_after_pat_pos
680                };
681                let len = prev_source.len() - just_after_pat_plus_ws;
682                let prev_source = &prev_source[just_after_pat_plus_ws..];
683                if accept_newlines || !prev_source.trim_start().contains('\n') {
684                    return Some(sp.with_lo(BytePos(sp.lo().0 - len as u32)));
685                }
686            }
687        }
688
689        None
690    }
691
692    /// Returns the source snippet as `String` after the given `Span`.
693    pub fn span_to_next_source(&self, sp: Span) -> Result<String, SpanSnippetError> {
694        self.span_to_source(sp, |src, _, end_index| {
695            src.get(end_index..).map(|s| s.to_string()).ok_or(SpanSnippetError::IllFormedSpan(sp))
696        })
697    }
698
699    /// Extends the given `Span` while the next character matches the predicate
700    pub fn span_extend_while(
701        &self,
702        span: Span,
703        f: impl Fn(char) -> bool,
704    ) -> Result<Span, SpanSnippetError> {
705        self.span_to_source(span, |s, _start, end| {
706            let n = s[end..].char_indices().find(|&(_, c)| !f(c)).map_or(s.len() - end, |(i, _)| i);
707            Ok(span.with_hi(span.hi() + BytePos(n as u32)))
708        })
709    }
710
711    /// Extends the span to include any trailing whitespace, or returns the original
712    /// span if a `SpanSnippetError` was encountered.
713    pub fn span_extend_while_whitespace(&self, span: Span) -> Span {
714        self.span_extend_while(span, char::is_whitespace).unwrap_or(span)
715    }
716
717    /// Extends the given `Span` to previous character while the previous character matches the predicate
718    pub fn span_extend_prev_while(
719        &self,
720        span: Span,
721        f: impl Fn(char) -> bool,
722    ) -> Result<Span, SpanSnippetError> {
723        self.span_to_source(span, |s, start, _end| {
724            let n = s[..start]
725                .char_indices()
726                .rfind(|&(_, c)| !f(c))
727                .map_or(start, |(i, _)| start - i - 1);
728            Ok(span.with_lo(span.lo() - BytePos(n as u32)))
729        })
730    }
731
732    /// Extends the given `Span` to just before the next occurrence of `c`.
733    pub fn span_extend_to_next_char(&self, sp: Span, c: char, accept_newlines: bool) -> Span {
734        if let Ok(next_source) = self.span_to_next_source(sp) {
735            let next_source = next_source.split(c).next().unwrap_or("");
736            if !next_source.is_empty() && (accept_newlines || !next_source.contains('\n')) {
737                return sp.with_hi(BytePos(sp.hi().0 + next_source.len() as u32));
738            }
739        }
740
741        sp
742    }
743
744    /// Extends the given `Span` to contain the entire line it is on.
745    pub fn span_extend_to_line(&self, sp: Span) -> Span {
746        self.span_extend_to_prev_char(self.span_extend_to_next_char(sp, '\n', true), '\n', true)
747    }
748
749    /// Given a `Span`, tries to get a shorter span ending before the first occurrence of `char`
750    /// `c`.
751    pub fn span_until_char(&self, sp: Span, c: char) -> Span {
752        match self.span_to_snippet(sp) {
753            Ok(snippet) => {
754                let snippet = snippet.split(c).next().unwrap_or("").trim_end();
755                if !snippet.is_empty() && !snippet.contains('\n') {
756                    sp.with_hi(BytePos(sp.lo().0 + snippet.len() as u32))
757                } else {
758                    sp
759                }
760            }
761            _ => sp,
762        }
763    }
764
765    /// Given a 'Span', tries to tell if it's wrapped by "<>" or "()"
766    /// the algorithm searches if the next character is '>' or ')' after skipping white space
767    /// then searches the previous character to match '<' or '(' after skipping white space
768    /// return true if wrapped by '<>' or '()'
769    pub fn span_wrapped_by_angle_or_parentheses(&self, span: Span) -> bool {
770        self.span_to_source(span, |src, start_index, end_index| {
771            if src.get(start_index..end_index).is_none() {
772                return Ok(false);
773            }
774            // test the right side to match '>' after skipping white space
775            let end_src = &src[end_index..];
776            let mut i = 0;
777            let mut found_right_parentheses = false;
778            let mut found_right_angle = false;
779            while let Some(cc) = end_src.chars().nth(i) {
780                if cc == ' ' {
781                    i = i + 1;
782                } else if cc == '>' {
783                    // found > in the right;
784                    found_right_angle = true;
785                    break;
786                } else if cc == ')' {
787                    found_right_parentheses = true;
788                    break;
789                } else {
790                    // failed to find '>' return false immediately
791                    return Ok(false);
792                }
793            }
794            // test the left side to match '<' after skipping white space
795            i = start_index;
796            let start_src = &src[0..start_index];
797            while let Some(cc) = start_src.chars().nth(i) {
798                if cc == ' ' {
799                    if i == 0 {
800                        return Ok(false);
801                    }
802                    i = i - 1;
803                } else if cc == '<' {
804                    // found < in the left
805                    if !found_right_angle {
806                        // skip something like "(< )>"
807                        return Ok(false);
808                    }
809                    break;
810                } else if cc == '(' {
811                    if !found_right_parentheses {
812                        // skip something like "<(>)"
813                        return Ok(false);
814                    }
815                    break;
816                } else {
817                    // failed to find '<' return false immediately
818                    return Ok(false);
819                }
820            }
821            Ok(true)
822        })
823        .is_ok_and(|is_accessible| is_accessible)
824    }
825
826    /// Given a `Span`, tries to get a shorter span ending just after the first occurrence of `char`
827    /// `c`.
828    pub fn span_through_char(&self, sp: Span, c: char) -> Span {
829        if let Ok(snippet) = self.span_to_snippet(sp) {
830            if let Some(offset) = snippet.find(c) {
831                return sp.with_hi(BytePos(sp.lo().0 + (offset + c.len_utf8()) as u32));
832            }
833        }
834        sp
835    }
836
837    /// Given a `Span`, gets a new `Span` covering the first token and all its trailing whitespace
838    /// or the original `Span`.
839    ///
840    /// If `sp` points to `"let mut x"`, then a span pointing at `"let "` will be returned.
841    pub fn span_until_non_whitespace(&self, sp: Span) -> Span {
842        let mut whitespace_found = false;
843
844        self.span_take_while(sp, |c| {
845            if !whitespace_found && c.is_whitespace() {
846                whitespace_found = true;
847            }
848
849            !whitespace_found || c.is_whitespace()
850        })
851    }
852
853    /// Given a `Span`, gets a new `Span` covering the first token without its trailing whitespace
854    /// or the original `Span` in case of error.
855    ///
856    /// If `sp` points to `"let mut x"`, then a span pointing at `"let"` will be returned.
857    pub fn span_until_whitespace(&self, sp: Span) -> Span {
858        self.span_take_while(sp, |c| !c.is_whitespace())
859    }
860
861    /// Given a `Span`, gets a shorter one until `predicate` yields `false`.
862    pub fn span_take_while<P>(&self, sp: Span, predicate: P) -> Span
863    where
864        P: for<'r> FnMut(&'r char) -> bool,
865    {
866        if let Ok(snippet) = self.span_to_snippet(sp) {
867            let offset = snippet.chars().take_while(predicate).map(|c| c.len_utf8()).sum::<usize>();
868
869            sp.with_hi(BytePos(sp.lo().0 + (offset as u32)))
870        } else {
871            sp
872        }
873    }
874
875    /// Given a `Span`, return a span ending in the closest `{`. This is useful when you have a
876    /// `Span` enclosing a whole item but we need to point at only the head (usually the first
877    /// line) of that item.
878    ///
879    /// *Only suitable for diagnostics.*
880    pub fn guess_head_span(&self, sp: Span) -> Span {
881        // FIXME: extend the AST items to have a head span, or replace callers with pointing at
882        // the item's ident when appropriate.
883        self.span_until_char(sp, '{')
884    }
885
886    /// Returns a new span representing just the first character of the given span.
887    pub fn start_point(&self, sp: Span) -> Span {
888        let width = {
889            let sp = sp.data();
890            let local_begin = self.lookup_byte_offset(sp.lo);
891            let start_index = local_begin.pos.to_usize();
892            let src = local_begin.sf.external_src.read();
893
894            let snippet = if let Some(ref src) = local_begin.sf.src {
895                Some(&src[start_index..])
896            } else {
897                src.get_source().map(|src| &src[start_index..])
898            };
899
900            match snippet {
901                None => 1,
902                Some(snippet) => match snippet.chars().next() {
903                    None => 1,
904                    Some(c) => c.len_utf8(),
905                },
906            }
907        };
908
909        sp.with_hi(BytePos(sp.lo().0 + width as u32))
910    }
911
912    /// Returns a new span representing just the last character of this span.
913    pub fn end_point(&self, sp: Span) -> Span {
914        let pos = sp.hi().0;
915
916        let width = self.find_width_of_character_at_span(sp, false);
917        let corrected_end_position = pos.checked_sub(width).unwrap_or(pos);
918
919        let end_point = BytePos(cmp::max(corrected_end_position, sp.lo().0));
920        sp.with_lo(end_point)
921    }
922
923    /// Returns a new span representing the next character after the end-point of this span.
924    /// Special cases:
925    /// - if span is a dummy one, returns the same span
926    /// - if next_point reached the end of source, return a span exceeding the end of source,
927    ///   which means sm.span_to_snippet(next_point) will get `Err`
928    /// - respect multi-byte characters
929    pub fn next_point(&self, sp: Span) -> Span {
930        if sp.is_dummy() {
931            return sp;
932        }
933        let start_of_next_point = sp.hi().0;
934
935        let width = self.find_width_of_character_at_span(sp, true);
936        // If the width is 1, then the next span should only contain the next char besides current ending.
937        // However, in the case of a multibyte character, where the width != 1, the next span should
938        // span multiple bytes to include the whole character.
939        let end_of_next_point =
940            start_of_next_point.checked_add(width).unwrap_or(start_of_next_point);
941
942        let end_of_next_point = BytePos(cmp::max(start_of_next_point + 1, end_of_next_point));
943        Span::new(BytePos(start_of_next_point), end_of_next_point, sp.ctxt(), None)
944    }
945
946    /// Check whether span is followed by some specified expected string in limit scope
947    pub fn span_look_ahead(&self, span: Span, expect: &str, limit: Option<usize>) -> Option<Span> {
948        let mut sp = span;
949        for _ in 0..limit.unwrap_or(100_usize) {
950            sp = self.next_point(sp);
951            if let Ok(ref snippet) = self.span_to_snippet(sp) {
952                if snippet == expect {
953                    return Some(sp);
954                }
955                if snippet.chars().any(|c| !c.is_whitespace()) {
956                    break;
957                }
958            }
959        }
960        None
961    }
962
963    /// Finds the width of the character, either before or after the end of provided span,
964    /// depending on the `forwards` parameter.
965    #[instrument(skip(self, sp))]
966    fn find_width_of_character_at_span(&self, sp: Span, forwards: bool) -> u32 {
967        let sp = sp.data();
968
969        if sp.lo == sp.hi && !forwards {
970            debug!("early return empty span");
971            return 1;
972        }
973
974        let local_begin = self.lookup_byte_offset(sp.lo);
975        let local_end = self.lookup_byte_offset(sp.hi);
976        debug!("local_begin=`{:?}`, local_end=`{:?}`", local_begin, local_end);
977
978        if local_begin.sf.start_pos != local_end.sf.start_pos {
979            debug!("begin and end are in different files");
980            return 1;
981        }
982
983        let start_index = local_begin.pos.to_usize();
984        let end_index = local_end.pos.to_usize();
985        debug!("start_index=`{:?}`, end_index=`{:?}`", start_index, end_index);
986
987        // Disregard indexes that are at the start or end of their spans, they can't fit bigger
988        // characters.
989        if (!forwards && end_index == usize::MIN) || (forwards && start_index == usize::MAX) {
990            debug!("start or end of span, cannot be multibyte");
991            return 1;
992        }
993
994        let source_len = local_begin.sf.source_len.to_usize();
995        debug!("source_len=`{:?}`", source_len);
996        // Ensure indexes are also not malformed.
997        if start_index > end_index || end_index > source_len - 1 {
998            debug!("source indexes are malformed");
999            return 1;
1000        }
1001
1002        let src = local_begin.sf.external_src.read();
1003
1004        let snippet = if let Some(src) = &local_begin.sf.src {
1005            src
1006        } else if let Some(src) = src.get_source() {
1007            src
1008        } else {
1009            return 1;
1010        };
1011
1012        if forwards {
1013            (snippet.ceil_char_boundary(end_index + 1) - end_index) as u32
1014        } else {
1015            (end_index - snippet.floor_char_boundary(end_index - 1)) as u32
1016        }
1017    }
1018
1019    pub fn get_source_file(&self, filename: &FileName) -> Option<Arc<SourceFile>> {
1020        // Remap filename before lookup
1021        let filename = self.path_mapping().map_filename_prefix(filename).0;
1022        for sf in self.files.borrow().source_files.iter() {
1023            if filename == sf.name {
1024                return Some(Arc::clone(&sf));
1025            }
1026        }
1027        None
1028    }
1029
1030    /// For a global `BytePos`, computes the local offset within the containing `SourceFile`.
1031    pub fn lookup_byte_offset(&self, bpos: BytePos) -> SourceFileAndBytePos {
1032        let idx = self.lookup_source_file_idx(bpos);
1033        let sf = Arc::clone(&(*self.files.borrow().source_files)[idx]);
1034        let offset = bpos - sf.start_pos;
1035        SourceFileAndBytePos { sf, pos: offset }
1036    }
1037
1038    /// Returns the index of the [`SourceFile`] (in `self.files`) that contains `pos`.
1039    /// This index is guaranteed to be valid for the lifetime of this `SourceMap`,
1040    /// since `source_files` is a `MonotonicVec`
1041    pub fn lookup_source_file_idx(&self, pos: BytePos) -> usize {
1042        self.files.borrow().source_files.partition_point(|x| x.start_pos <= pos) - 1
1043    }
1044
1045    pub fn count_lines(&self) -> usize {
1046        self.files().iter().fold(0, |a, f| a + f.count_lines())
1047    }
1048
1049    pub fn ensure_source_file_source_present(&self, source_file: &SourceFile) -> bool {
1050        source_file.add_external_src(|| {
1051            let FileName::Real(ref name) = source_file.name else {
1052                return None;
1053            };
1054
1055            let local_path: Cow<'_, Path> = match name {
1056                RealFileName::LocalPath(local_path) => local_path.into(),
1057                RealFileName::Remapped { local_path: Some(local_path), .. } => local_path.into(),
1058                RealFileName::Remapped { local_path: None, virtual_name } => {
1059                    // The compiler produces better error messages if the sources of dependencies
1060                    // are available. Attempt to undo any path mapping so we can find remapped
1061                    // dependencies.
1062                    // We can only use the heuristic because `add_external_src` checks the file
1063                    // content hash.
1064                    self.path_mapping.reverse_map_prefix_heuristically(virtual_name)?.into()
1065                }
1066            };
1067
1068            self.file_loader.read_file(&local_path).ok()
1069        })
1070    }
1071
1072    pub fn is_imported(&self, sp: Span) -> bool {
1073        let source_file_index = self.lookup_source_file_idx(sp.lo());
1074        let source_file = &self.files()[source_file_index];
1075        source_file.is_imported()
1076    }
1077
1078    /// Gets the span of a statement. If the statement is a macro expansion, the
1079    /// span in the context of the block span is found. The trailing semicolon is included
1080    /// on a best-effort basis.
1081    pub fn stmt_span(&self, stmt_span: Span, block_span: Span) -> Span {
1082        if !stmt_span.from_expansion() {
1083            return stmt_span;
1084        }
1085        let mac_call = original_sp(stmt_span, block_span);
1086        self.mac_call_stmt_semi_span(mac_call).map_or(mac_call, |s| mac_call.with_hi(s.hi()))
1087    }
1088
1089    /// Tries to find the span of the semicolon of a macro call statement.
1090    /// The input must be the *call site* span of a statement from macro expansion.
1091    /// ```ignore (illustrative)
1092    /// //       v output
1093    ///    mac!();
1094    /// // ^^^^^^ input
1095    /// ```
1096    pub fn mac_call_stmt_semi_span(&self, mac_call: Span) -> Option<Span> {
1097        let span = self.span_extend_while_whitespace(mac_call);
1098        let span = self.next_point(span);
1099        if self.span_to_snippet(span).as_deref() == Ok(";") { Some(span) } else { None }
1100    }
1101}
1102
1103pub fn get_source_map() -> Option<Arc<SourceMap>> {
1104    with_session_globals(|session_globals| session_globals.source_map.clone())
1105}
1106
1107#[derive(Clone)]
1108pub struct FilePathMapping {
1109    mapping: Vec<(PathBuf, PathBuf)>,
1110    filename_display_for_diagnostics: FileNameDisplayPreference,
1111    filename_embeddable_preference: FileNameEmbeddablePreference,
1112}
1113
1114impl FilePathMapping {
1115    pub fn empty() -> FilePathMapping {
1116        FilePathMapping::new(
1117            Vec::new(),
1118            FileNameDisplayPreference::Local,
1119            FileNameEmbeddablePreference::RemappedOnly,
1120        )
1121    }
1122
1123    pub fn new(
1124        mapping: Vec<(PathBuf, PathBuf)>,
1125        filename_display_for_diagnostics: FileNameDisplayPreference,
1126        filename_embeddable_preference: FileNameEmbeddablePreference,
1127    ) -> FilePathMapping {
1128        FilePathMapping {
1129            mapping,
1130            filename_display_for_diagnostics,
1131            filename_embeddable_preference,
1132        }
1133    }
1134
1135    /// Applies any path prefix substitution as defined by the mapping.
1136    /// The return value is the remapped path and a boolean indicating whether
1137    /// the path was affected by the mapping.
1138    pub fn map_prefix<'a>(&'a self, path: impl Into<Cow<'a, Path>>) -> (Cow<'a, Path>, bool) {
1139        let path = path.into();
1140        if path.as_os_str().is_empty() {
1141            // Exit early if the path is empty and therefore there's nothing to remap.
1142            // This is mostly to reduce spam for `RUSTC_LOG=[remap_path_prefix]`.
1143            return (path, false);
1144        }
1145
1146        return remap_path_prefix(&self.mapping, path);
1147
1148        #[instrument(level = "debug", skip(mapping), ret)]
1149        fn remap_path_prefix<'a>(
1150            mapping: &'a [(PathBuf, PathBuf)],
1151            path: Cow<'a, Path>,
1152        ) -> (Cow<'a, Path>, bool) {
1153            // NOTE: We are iterating over the mapping entries from last to first
1154            //       because entries specified later on the command line should
1155            //       take precedence.
1156            for (from, to) in mapping.iter().rev() {
1157                debug!("Trying to apply {from:?} => {to:?}");
1158
1159                if let Ok(rest) = path.strip_prefix(from) {
1160                    let remapped = if rest.as_os_str().is_empty() {
1161                        // This is subtle, joining an empty path onto e.g. `foo/bar` will
1162                        // result in `foo/bar/`, that is, there'll be an additional directory
1163                        // separator at the end. This can lead to duplicated directory separators
1164                        // in remapped paths down the line.
1165                        // So, if we have an exact match, we just return that without a call
1166                        // to `Path::join()`.
1167                        to.into()
1168                    } else {
1169                        to.join(rest).into()
1170                    };
1171                    debug!("Match - remapped");
1172
1173                    return (remapped, true);
1174                } else {
1175                    debug!("No match - prefix {from:?} does not match");
1176                }
1177            }
1178
1179            debug!("not remapped");
1180            (path, false)
1181        }
1182    }
1183
1184    fn map_filename_prefix(&self, file: &FileName) -> (FileName, bool) {
1185        match file {
1186            FileName::Real(realfile) if let RealFileName::LocalPath(local_path) = realfile => {
1187                let (mapped_path, mapped) = self.map_prefix(local_path);
1188                let realfile = if mapped {
1189                    RealFileName::Remapped {
1190                        local_path: Some(local_path.clone()),
1191                        virtual_name: mapped_path.into_owned(),
1192                    }
1193                } else {
1194                    realfile.clone()
1195                };
1196                (FileName::Real(realfile), mapped)
1197            }
1198            FileName::Real(_) => unreachable!("attempted to remap an already remapped filename"),
1199            other => (other.clone(), false),
1200        }
1201    }
1202
1203    /// Applies any path prefix substitution as defined by the mapping.
1204    /// The return value is the local path with a "virtual path" representing the remapped
1205    /// part if any remapping was performed.
1206    pub fn to_real_filename<'a>(&self, local_path: impl Into<Cow<'a, Path>>) -> RealFileName {
1207        let local_path = local_path.into();
1208        if let (remapped_path, true) = self.map_prefix(&*local_path) {
1209            RealFileName::Remapped {
1210                virtual_name: remapped_path.into_owned(),
1211                local_path: Some(local_path.into_owned()),
1212            }
1213        } else {
1214            RealFileName::LocalPath(local_path.into_owned())
1215        }
1216    }
1217
1218    /// Expand a relative path to an absolute path with remapping taken into account.
1219    /// Use this when absolute paths are required (e.g. debuginfo or crate metadata).
1220    ///
1221    /// The resulting `RealFileName` will have its `local_path` portion erased if
1222    /// possible (i.e. if there's also a remapped path).
1223    pub fn to_embeddable_absolute_path(
1224        &self,
1225        file_path: RealFileName,
1226        working_directory: &RealFileName,
1227    ) -> RealFileName {
1228        match file_path {
1229            // Anything that's already remapped we don't modify, except for erasing
1230            // the `local_path` portion (if desired).
1231            RealFileName::Remapped { local_path, virtual_name } => {
1232                RealFileName::Remapped {
1233                    local_path: match self.filename_embeddable_preference {
1234                        FileNameEmbeddablePreference::RemappedOnly => None,
1235                        FileNameEmbeddablePreference::LocalAndRemapped => local_path,
1236                    },
1237                    // We use the remapped name verbatim, even if it looks like a relative
1238                    // path. The assumption is that the user doesn't want us to further
1239                    // process paths that have gone through remapping.
1240                    virtual_name,
1241                }
1242            }
1243
1244            RealFileName::LocalPath(unmapped_file_path) => {
1245                // If no remapping has been applied yet, try to do so
1246                let (new_path, was_remapped) = self.map_prefix(&unmapped_file_path);
1247                if was_remapped {
1248                    // It was remapped, so don't modify further
1249                    return RealFileName::Remapped {
1250                        virtual_name: new_path.into_owned(),
1251                        // But still provide the local path if desired
1252                        local_path: match self.filename_embeddable_preference {
1253                            FileNameEmbeddablePreference::RemappedOnly => None,
1254                            FileNameEmbeddablePreference::LocalAndRemapped => {
1255                                Some(unmapped_file_path)
1256                            }
1257                        },
1258                    };
1259                }
1260
1261                if new_path.is_absolute() {
1262                    // No remapping has applied to this path and it is absolute,
1263                    // so the working directory cannot influence it either, so
1264                    // we are done.
1265                    return RealFileName::LocalPath(new_path.into_owned());
1266                }
1267
1268                debug_assert!(new_path.is_relative());
1269                let unmapped_file_path_rel = new_path;
1270
1271                match working_directory {
1272                    RealFileName::LocalPath(unmapped_working_dir_abs) => {
1273                        let unmapped_file_path_abs =
1274                            unmapped_working_dir_abs.join(unmapped_file_path_rel);
1275
1276                        // Although neither `working_directory` nor the file name were subject
1277                        // to path remapping, the concatenation between the two may be. Hence
1278                        // we need to do a remapping here.
1279                        let (file_path_abs, was_remapped) =
1280                            self.map_prefix(&unmapped_file_path_abs);
1281                        if was_remapped {
1282                            RealFileName::Remapped {
1283                                virtual_name: file_path_abs.into_owned(),
1284                                local_path: match self.filename_embeddable_preference {
1285                                    FileNameEmbeddablePreference::RemappedOnly => None,
1286                                    FileNameEmbeddablePreference::LocalAndRemapped => {
1287                                        Some(unmapped_file_path_abs)
1288                                    }
1289                                },
1290                            }
1291                        } else {
1292                            // No kind of remapping applied to this path, so
1293                            // we leave it as it is.
1294                            RealFileName::LocalPath(file_path_abs.into_owned())
1295                        }
1296                    }
1297                    RealFileName::Remapped {
1298                        local_path,
1299                        virtual_name: remapped_working_dir_abs,
1300                    } => {
1301                        // If working_directory has been remapped, then we emit
1302                        // Remapped variant as the expanded path won't be valid
1303                        RealFileName::Remapped {
1304                            virtual_name: Path::new(remapped_working_dir_abs)
1305                                .join(&unmapped_file_path_rel),
1306                            local_path: match self.filename_embeddable_preference {
1307                                FileNameEmbeddablePreference::RemappedOnly => None,
1308                                FileNameEmbeddablePreference::LocalAndRemapped => local_path
1309                                    .as_ref()
1310                                    .map(|local_path| local_path.join(unmapped_file_path_rel)),
1311                            },
1312                        }
1313                    }
1314                }
1315            }
1316        }
1317    }
1318
1319    /// Attempts to (heuristically) reverse a prefix mapping.
1320    ///
1321    /// Returns [`Some`] if there is exactly one mapping where the "to" part is
1322    /// a prefix of `path` and has at least one non-empty
1323    /// [`Normal`](path::Component::Normal) component. The component
1324    /// restriction exists to avoid reverse mapping overly generic paths like
1325    /// `/` or `.`).
1326    ///
1327    /// This is a heuristic and not guaranteed to return the actual original
1328    /// path! Do not rely on the result unless you have other means to verify
1329    /// that the mapping is correct (e.g. by checking the file content hash).
1330    #[instrument(level = "debug", skip(self), ret)]
1331    fn reverse_map_prefix_heuristically(&self, path: &Path) -> Option<PathBuf> {
1332        let mut found = None;
1333
1334        for (from, to) in self.mapping.iter() {
1335            let has_normal_component = to.components().any(|c| match c {
1336                path::Component::Normal(s) => !s.is_empty(),
1337                _ => false,
1338            });
1339
1340            if !has_normal_component {
1341                continue;
1342            }
1343
1344            let Ok(rest) = path.strip_prefix(to) else {
1345                continue;
1346            };
1347
1348            if found.is_some() {
1349                return None;
1350            }
1351
1352            found = Some(from.join(rest));
1353        }
1354
1355        found
1356    }
1357}