Skip to main content

raf_source/workspace/
module_paths.rs

1// SPDX-FileCopyrightText: 2026 Blackcat InformaticsĀ® Inc. <paudley@blackcatinformatics.ca>
2// SPDX-License-Identifier: MIT OR Apache-2.0 OR MulanPSL-2.0
3
4//! Module `path` attributes that lead a target outside its own package.
5
6use crate::modtree::{PathSite, Reach};
7use crate::path::RelPath;
8use crate::target::PackageId;
9
10use super::Workspace;
11
12/// An arrival through a module `path` attribute at a file that the package of
13/// the arriving target does not own.
14///
15/// The struct is `#[non_exhaustive]`: adding a field is not a breaking change,
16/// so a pattern names the fields it reads and ends in `..`.
17///
18/// ```compile_fail,E0638
19/// # fn names(found: &raf_source::ForeignModulePath<'_>) {
20/// let raf_source::ForeignModulePath { file, reach, site, package, owner } = found;
21/// # }
22/// ```
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24#[non_exhaustive]
25pub struct ForeignModulePath<'a> {
26    /// The reached file's path, as the workspace keeps it.
27    pub file: &'a RelPath,
28    /// The arrival, whose target followed the attribute.
29    pub reach: &'a Reach,
30    /// The attribute of that arrival.
31    pub site: &'a PathSite,
32    /// The package of the target that followed the attribute.
33    pub package: PackageId,
34    /// The package whose directory holds the resolved spelling, the deepest
35    /// one when directories nest; `None` when no loaded package holds it.
36    pub owner: Option<PackageId>,
37}
38
39impl Workspace {
40    /// Every arrival through a module `path` attribute, plain or inside
41    /// `cfg_attr`, whose resolved spelling the arriving target's package does
42    /// not own, in the order of [`Workspace::files`] and then of each file's
43    /// reaches.
44    ///
45    /// A package owns a spelling when its directory is the deepest package
46    /// directory that lexically holds it in the same source, so a package
47    /// nested inside another one owns its own directory. A spelling that
48    /// keeps a `..` below the package directory, which the walk keeps only
49    /// after a symlink or other non-directory entry, is not owned by that
50    /// package. Every target kind is covered, since each target's module
51    /// tree is walked from its root. Structural loads follow every `cfg_attr`
52    /// alternative; configured loads follow only the active ones.
53    ///
54    /// A module declared inside a function body or another block is followed,
55    /// so a `path` there that leaves its package is listed too.
56    #[must_use]
57    pub fn foreign_module_paths(&self) -> Vec<ForeignModulePath<'_>> {
58        let mut found = Vec::new();
59        for file in self.files.values() {
60            for reach in &file.reached {
61                let Some(site) = &reach.path_attribute else {
62                    continue;
63                };
64                // INVARIANT: every reach names a target of the same load.
65                let target = &self.targets[reach.target.index()];
66                let owner = self.owning_package(&site.resolved);
67                if owner != Some(target.package_id) {
68                    found.push(ForeignModulePath {
69                        file: &file.path,
70                        reach,
71                        site,
72                        package: target.package_id,
73                        owner,
74                    });
75                }
76            }
77        }
78        found
79    }
80
81    /// The package with the deepest directory that lexically holds `path`.
82    fn owning_package(&self, path: &RelPath) -> Option<PackageId> {
83        self.package_ids()
84            .filter(|id| holds(&self.packages[id.index()].dir, path))
85            .max_by_key(|id| self.packages[id.index()].dir.segments().count())
86    }
87}
88
89/// True when `path` lies below `dir` in the same source, without a `..`
90/// segment after the directory's own segments.
91fn holds(dir: &RelPath, path: &RelPath) -> bool {
92    if dir.authority() != path.authority() {
93        return false;
94    }
95    let mut rest = path.segments();
96    dir.segments().all(|segment| rest.next() == Some(segment))
97        && rest.all(|segment| segment != "..")
98}