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}