Skip to main content

raf_source/code/
library.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//! Borrowed exact library candidates from the already settled external-name tables.
5
6use super::{CodeResolveError, CodeResolver, Heads};
7use crate::meter::{ItemAdmission, Meter};
8use crate::{
9    ExportOptions, ItemId, LoadError, LoadErrorKind, Namespace, PackageId, RelPath, Resolution,
10    ResolveError, SymbolKind, TargetId, TargetKind, TestRole, Usage,
11};
12use purrdf_lex::allocation::Memory;
13use purrdf_lex::walk::{try_dedup_by, try_sort_unstable_by};
14
15#[derive(Clone, Copy)]
16enum Group<'a> {
17    Prelude(&'a crate::index::ExternName, bool),
18    Explicit(&'a [usize]),
19}
20
21/// The access route preserved by an admitted library receipt.
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub enum ExternRouteKind {
24    /// An absolute external name, with its complete native candidate group.
25    Prelude,
26    /// A genuine lexical `extern crate` declaration, which can shadow a prelude name.
27    Explicit,
28}
29
30impl Group<'_> {
31    fn scan_len(&self) -> usize {
32        match self {
33            Self::Prelude(entry, _) => entry.roots.len(),
34            Self::Explicit(roots) => roots.len(),
35        }
36    }
37    fn roots(&self) -> impl Iterator<Item = usize> + '_ {
38        let (prelude, explicit, test) = match self {
39            Self::Prelude(entry, test) => (Some(*entry), None, *test),
40            Self::Explicit(roots) => (None, Some(*roots), false),
41        };
42        prelude
43            .into_iter()
44            .flat_map(move |entry| entry.roots(test))
45            .chain(explicit.into_iter().flat_map(|roots| roots.iter().copied()))
46    }
47}
48
49/// One actual admitted external library under a Rust name visible in the source model.
50///
51/// The receipt borrows one code query and keeps its complete original-name candidate
52/// group. It is not durable identity or configuration proof. Same-package injected
53/// libraries and `extern crate self` roots are excluded.
54pub struct ExternLibrary<'a> {
55    code: &'a CodeResolver<'a>,
56    name: &'a str,
57    module: usize,
58    group: Group<'a>,
59    from: usize,
60    test: bool,
61}
62
63impl ExternLibrary<'_> {
64    /// Whether the receipt represents an absolute name or a lexical declaration.
65    #[must_use]
66    pub const fn route_kind(&self) -> ExternRouteKind {
67        match self.group {
68            Group::Prelude(..) => ExternRouteKind::Prelude,
69            Group::Explicit(..) => ExternRouteKind::Explicit,
70        }
71    }
72    /// The actual Rust external name, including a custom library or explicit alias.
73    #[must_use]
74    pub const fn rust_name(&self) -> &str {
75        self.name
76    }
77    /// The actual indexed crate-root definition.
78    #[must_use]
79    pub fn root(&self) -> ItemId {
80        self.code.index.root_items[&self.module]
81    }
82    /// The actual library target.
83    #[must_use]
84    pub fn target(&self) -> TargetId {
85        self.code.index.modules[self.module].target
86    }
87    /// The exact load-local package owning that target.
88    #[must_use]
89    pub fn package(&self) -> PackageId {
90        self.code.index.targets[self.target().index()].package_id
91    }
92
93    /// Resolve a relative definition that this library actually exports.
94    ///
95    /// Public reexports retain their actual defining sites. Canonical definition
96    /// paths are admitted only when those definitions appear on this library's
97    /// public surface. This does not replace lexical classification of a consumer
98    /// occurrence. Resolution, surface construction and membership share one query
99    /// work grant and retain the reading table's original item-byte allowance,
100    /// including hidden but public definitions.
101    ///
102    /// # Errors
103    /// Preserves original external-name ambiguity, native resolution/surface causes,
104    /// and an explicit refusal for definitions that are not exported.
105    pub fn resolve(
106        &self,
107        relative: &str,
108        namespace: Namespace,
109    ) -> Result<Resolution, CodeResolveError> {
110        let meter = Meter::resume_query(
111            self.code.options,
112            Usage {
113                item_bytes: self.code.usage.item_bytes,
114                ..Usage::default()
115            },
116        );
117        let roots = self.candidate_roots(&meter)?;
118        if roots.len() != 1 {
119            return Err(CodeResolveError::Resolve(ResolveError::Ambiguous(roots)));
120        }
121        let (resolved, retained) = self.code.resolve_code_after(
122            self.module,
123            relative,
124            namespace,
125            Heads::Local,
126            meter.usage(),
127        )?;
128        let options = ExportOptions {
129            include_hidden: true,
130        };
131        let (surface, usage) = self
132            .code
133            .workspace
134            .exports_after(self.target(), &options, retained)
135            .map_err(|error| CodeResolveError::Exports(Box::new(error)))?;
136        let meter = Meter::resume_query(self.code.options, usage);
137        let target = &self.code.index.targets[self.target().index()];
138        for site in resolved.sites.iter().chain(resolved.type_aliases.first()) {
139            let mut exported = false;
140            for item in &surface.items {
141                meter.work(1, &target.root, None).map_err(|error| {
142                    CodeResolveError::Exports(Box::new(crate::ExportError::Budget(error)))
143                })?;
144                if item.item == *site {
145                    exported = true;
146                    break;
147                }
148            }
149            if !exported {
150                for item in &surface.reexports {
151                    meter.work(1, &target.root, None).map_err(|error| {
152                        CodeResolveError::Exports(Box::new(crate::ExportError::Budget(error)))
153                    })?;
154                    if item.item == Some(*site) {
155                        exported = true;
156                        break;
157                    }
158                }
159            }
160            if !exported {
161                return Err(CodeResolveError::NotExported {
162                    root: self.root(),
163                    path: relative.into(),
164                });
165            }
166        }
167        Ok(resolved)
168    }
169
170    fn candidate_roots(&self, meter: &Meter) -> Result<Vec<ItemId>, CodeResolveError> {
171        let path = &self.code.index.targets[self.target().index()].root;
172        let mut admission = ItemAdmission::new(meter, path);
173        let result = (|| {
174            self.charge_candidate_scan(meter, path)?;
175            let mut memory = Memory::new(&mut admission);
176            let mut roots = Vec::new();
177            let inherited = (self.route_kind() == ExternRouteKind::Prelude).then(|| {
178                self.code.index.extern_root_candidates(
179                    self.from,
180                    self.name,
181                    Heads::Code { test: self.test },
182                )
183            });
184            for root in self.group.roots().chain(inherited.into_iter().flatten()) {
185                meter.work(1, path, None)?;
186                memory
187                    .push(&mut roots, self.code.index.root_items[&root])
188                    .map_err(|error| LoadError::new(path, None, LoadErrorKind::Storage(error)))?;
189            }
190            try_sort_unstable_by(&mut roots, |left, right| {
191                let left = self.code.index.sort_key(*left);
192                let right = self.code.index.sort_key(*right);
193                meter.work(
194                    left.0
195                        .len()
196                        .saturating_add(right.0.len())
197                        .saturating_add(left.2.as_str().len())
198                        .saturating_add(right.2.as_str().len())
199                        .saturating_add(1),
200                    path,
201                    None,
202                )?;
203                Ok::<_, LoadError>(left.cmp(&right))
204            })?;
205            try_dedup_by(&mut roots, |left, right| {
206                meter.work(1, path, None)?;
207                Ok::<_, LoadError>(left == right)
208            })?;
209            Ok(roots)
210        })();
211        result.map_err(|error| CodeResolveError::Query(Box::new(admission.recover(error))))
212    }
213
214    fn charge_candidate_scan(&self, meter: &Meter, path: &RelPath) -> Result<(), LoadError> {
215        meter.work(self.group.scan_len().saturating_add(1), path, None)?;
216        if self.route_kind() == ExternRouteKind::Prelude {
217            meter.work(self.name.len().saturating_add(1), path, None)?;
218            if let Some(entry) = self.code.index.extern_name(self.from, self.name, self.test) {
219                meter.work(entry.roots.len(), path, None)?;
220            }
221            let root = self.code.index.modules[self.from].root;
222            if let Some(entry) = self.code.index.scopes[root].get(self.name) {
223                meter.work(
224                    entry.defs[crate::settle::slot(Namespace::Type)].len(),
225                    path,
226                    None,
227                )?;
228            }
229        }
230        Ok(())
231    }
232}
233
234impl CodeResolver<'_> {
235    /// Borrow every actual external library candidate from the owner's admitted tables.
236    ///
237    /// Uses existing target/dev/test filtering and settled Cargo names; custom library
238    /// names, renames and explicit `extern crate` aliases are retained. Unindexed
239    /// external names yield no library receipt. Every original-name candidate is
240    /// preserved; choosing a receipt does not remove its group's ambiguity.
241    ///
242    /// # Errors
243    /// Refuses absent/outside owners, missing context and macro definition bodies.
244    pub fn extern_libraries_at(
245        &self,
246        owner: ItemId,
247        byte: usize,
248    ) -> Result<impl Iterator<Item = ExternLibrary<'_>> + '_, CodeResolveError> {
249        let module = self.module(owner, byte)?;
250        let reading = module;
251        let item = &self.index.items[owner.index()];
252        if item.kind == SymbolKind::MacroRules
253            && item
254                .body
255                .as_ref()
256                .is_some_and(|body| (body.start_byte..body.end_byte).contains(&byte))
257        {
258            return Err(CodeResolveError::MacroDefinition(owner));
259        }
260        let test = item.test != TestRole::None;
261        let target = self.index.modules[module].target;
262        let own_package = self.index.targets[target.index()].package_id;
263        let root = self.index.modules[module].root;
264        let preludes = self.index.preludes[target.index()]
265            .iter()
266            .filter(move |(_, entry)| entry.everywhere || test)
267            .flat_map(move |(name, entry)| {
268                entry.roots(test).map(move |module| ExternLibrary {
269                    code: self,
270                    name,
271                    module,
272                    group: Group::Prelude(entry, test),
273                    from: reading,
274                    test,
275                })
276            });
277        let explicit = self
278            .index
279            .crate_of
280            .iter()
281            .filter(move |(id, _)| {
282                let declaration = &self.index.items[id.index()];
283                let home = self.homes[id.index()].module();
284                declaration.target == target
285                    && (test || declaration.test == TestRole::None)
286                    && (home == Some(module) || home == Some(root))
287            })
288            .flat_map(move |(id, roots)| {
289                roots.iter().copied().map(move |module| ExternLibrary {
290                    code: self,
291                    name: self.index.items[id.index()].name.as_str(),
292                    module,
293                    group: Group::Explicit(roots),
294                    from: reading,
295                    test,
296                })
297            });
298        Ok(preludes.chain(explicit).filter(move |library| {
299            library.package() != own_package
300                && self.index.targets[library.target().index()].kind == TargetKind::Lib
301        }))
302    }
303}