Skip to main content

raf_source/code/
aliases.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//! Bounded alias-member projection through the existing native symbol queries.
5
6use purrdf_lex::allocation::{Admission, Memory, StorageError};
7
8use super::{CodeResolveError, CodeResolver, Heads, ItemAdmission, Meter};
9use crate::facts::PathFact;
10use crate::meter::Steps;
11use crate::{
12    ItemId, Namespace, Resolution, ResolveError, SourceAuthorityId, SymbolKind, TestRole, Usage,
13};
14
15enum Failure {
16    Code(CodeResolveError),
17    Storage(StorageError),
18    Outside(CodeResolveError),
19}
20
21#[derive(Clone, Copy, PartialEq, Eq)]
22enum AliasPurpose {
23    Member,
24    Enum,
25    FirstParty,
26}
27
28enum Destination {
29    Alias,
30    Nominal(usize),
31    Outside(&'static str),
32}
33
34const ALIAS_SYNTAX: &str = "supply a zero-parameter plain alias with literal const arguments; general alias substitution is not modeled";
35const NOMINAL_ARITY: &str = "alias arguments do not establish the nominal const arity";
36
37fn alias_arity(item: &crate::Item) -> Option<usize> {
38    item.detail.as_ref()?.alias_const_arity
39}
40
41fn destination(item: &crate::Item, arguments: usize, purpose: AliasPurpose) -> Destination {
42    if purpose == AliasPurpose::FirstParty
43        && item.file.authority() != SourceAuthorityId::FIRST_PARTY
44    {
45        return Destination::Outside("target is outside the first-party source");
46    }
47    match item.kind {
48        SymbolKind::TypeAlias if arguments != 0 => Destination::Outside(
49            "generic arguments on an alias need explicit substitution evidence",
50        ),
51        SymbolKind::TypeAlias
52            if purpose == AliasPurpose::FirstParty && alias_arity(item).is_none() =>
53        {
54            Destination::Outside(ALIAS_SYNTAX)
55        }
56        SymbolKind::TypeAlias => Destination::Alias,
57        SymbolKind::Struct | SymbolKind::Enum | SymbolKind::Union => item
58            .detail
59            .as_ref()
60            .and_then(|detail| detail.nominal_const_arity)
61            .map_or(Destination::Outside(NOMINAL_ARITY), Destination::Nominal),
62        _ => Destination::Outside(NOMINAL_ARITY),
63    }
64}
65
66fn alias_path<S: Admission + ?Sized>(
67    rhs: &PathFact,
68    memory: &mut Memory<'_, S>,
69) -> Result<String, StorageError> {
70    let mut path = String::new();
71    if rhs.leading_colon {
72        memory.push_str(&mut path, "::")?;
73    }
74    for (index, segment) in rhs.segments.iter().enumerate() {
75        if index > 0 {
76            memory.push_str(&mut path, "::")?;
77        }
78        memory.push_str(&mut path, segment)?;
79    }
80    Ok(path)
81}
82
83impl From<CodeResolveError> for Failure {
84    fn from(error: CodeResolveError) -> Self {
85        Self::Code(error)
86    }
87}
88impl From<StorageError> for Failure {
89    fn from(error: StorageError) -> Self {
90        Self::Storage(error)
91    }
92}
93
94fn unsupported(alias: ItemId, member: &str, reason: &'static str) -> CodeResolveError {
95    CodeResolveError::AliasMember {
96        alias,
97        member: member.into(),
98        reason,
99    }
100}
101fn budget(error: crate::LoadError) -> CodeResolveError {
102    CodeResolveError::Query(Box::new(error))
103}
104
105impl CodeResolver<'_> {
106    /// Resolve a plain type alias to its enum through unconditional named paths.
107    /// The query admits the same bounded const argument forms as associated
108    /// member lookup. Other nominal types supply no enum identity.
109    ///
110    /// # Errors
111    /// Refuses an absent alias, an uncertain or unsupported alias chain and
112    /// exhausted query resources.
113    pub fn unconditional_enum_alias(
114        &self,
115        alias: ItemId,
116    ) -> Result<Option<ItemId>, CodeResolveError> {
117        self.unconditional_alias(alias, AliasPurpose::Enum)
118            .map(|(nominal, _)| {
119                nominal.filter(|id| self.index.items[id.index()].kind == SymbolKind::Enum)
120            })
121    }
122
123    /// Resolve a written first-party alias to its indexed struct, enum or union.
124    ///
125    /// Returns no identity for an unindexed target or a form outside the
126    /// zero-parameter named alias and literal const argument profile. The
127    /// returned usage includes the work of an unsuccessful supported probe.
128    ///
129    /// # Errors
130    /// Refuses absent items, ambiguous, cyclic or conditional indexed routes,
131    /// broken explicitly local paths and exhausted query resources.
132    pub fn unconditional_nominal_alias(
133        &self,
134        alias: ItemId,
135    ) -> Result<(Option<ItemId>, Usage), CodeResolveError> {
136        self.unconditional_alias(alias, AliasPurpose::FirstParty)
137    }
138
139    fn unconditional_alias(
140        &self,
141        alias: ItemId,
142        purpose: AliasPurpose,
143    ) -> Result<(Option<ItemId>, Usage), CodeResolveError> {
144        let item = self
145            .index
146            .items
147            .get(alias.index())
148            .ok_or(CodeResolveError::UnknownItem(alias))?;
149        if item.kind != SymbolKind::TypeAlias {
150            return Ok((None, Usage::default()));
151        }
152        let meter = Meter::resume_query(
153            self.options,
154            Usage {
155                item_bytes: self.usage.item_bytes,
156                ..Usage::default()
157            },
158        );
159        let steps = Steps::QueryItems {
160            meter: &meter,
161            file: &item.file,
162            line: Some(item.name_line),
163        };
164        let mut admission = ItemAdmission::new(&meter, &item.file);
165        let result = self.alias_nominal(
166            alias,
167            if purpose == AliasPurpose::Enum {
168                "enum"
169            } else {
170                "type"
171            },
172            &meter,
173            &mut Memory::new(&mut admission),
174            steps,
175            purpose,
176        );
177        match result {
178            Ok((id, _, _)) => Ok((Some(id), meter.usage())),
179            Err(Failure::Outside(_)) if purpose == AliasPurpose::FirstParty => {
180                Ok((None, meter.usage()))
181            }
182            Err(Failure::Code(error) | Failure::Outside(error)) => Err(error),
183            Err(Failure::Storage(error)) => Err(budget(admission.error(error))),
184        }
185    }
186
187    /// Require a method whose self type applies without generic inference.
188    ///
189    /// Admits direct nominal types with no parameters, or the exact forwarding
190    /// of all unconstrained nominal const parameters. General bounds, defaults,
191    /// type/lifetime substitution and aliased impl headers need more evidence.
192    /// Configuration and unexpanded declaration attributes remain caller audits.
193    ///
194    /// # Errors
195    /// Refuses absent items and every method outside that proven header subset.
196    pub fn require_unconditional_inherent_method(
197        &self,
198        site: ItemId,
199    ) -> Result<(), CodeResolveError> {
200        let meter = Meter::resume_query(
201            self.options,
202            Usage {
203                item_bytes: self.usage.item_bytes,
204                ..Usage::default()
205            },
206        );
207        let item = self
208            .index
209            .items
210            .get(site.index())
211            .ok_or(CodeResolveError::UnknownItem(site))?;
212        let steps = Steps::QueryItems {
213            meter: &meter,
214            file: &item.file,
215            line: Some(item.name_line),
216        };
217        self.require_unconditional_inherent_method_counted(site, steps)
218    }
219
220    fn require_unconditional_inherent_method_counted(
221        &self,
222        site: ItemId,
223        steps: Steps<'_>,
224    ) -> Result<(), CodeResolveError> {
225        let item = self
226            .index
227            .items
228            .get(site.index())
229            .ok_or(CodeResolveError::UnknownItem(site))?;
230        if item.kind != SymbolKind::InherentMethod
231            || !self
232                .index
233                .unconditional_method(site, steps)
234                .map_err(CodeResolveError::Resolve)?
235        {
236            return Err(CodeResolveError::MethodApplicability(site));
237        }
238        Ok(())
239    }
240
241    pub(super) fn resolve_code_at(
242        &self,
243        module: usize,
244        path: &str,
245        namespace: Namespace,
246        heads: Heads,
247    ) -> Result<(Resolution, Usage), CodeResolveError> {
248        let retained = Usage {
249            item_bytes: self.usage.item_bytes,
250            ..Usage::default()
251        };
252        self.resolve_code_after(module, path, namespace, heads, retained)
253    }
254
255    pub(super) fn resolve_code_after(
256        &self,
257        module: usize,
258        path: &str,
259        namespace: Namespace,
260        heads: Heads,
261        retained: Usage,
262    ) -> Result<(Resolution, Usage), CodeResolveError> {
263        let (site, line) = self.index.module_site(module);
264        let meter = Meter::resume_query(self.options, retained);
265        meter.work(0, &site, line).map_err(budget)?;
266        let steps = Steps::QueryItems {
267            meter: &meter,
268            file: &site,
269            line,
270        };
271        let missing = match self
272            .index
273            .resolve_at(module, path, Some(namespace), heads, steps)
274        {
275            Ok(resolution) => return Ok((resolution, meter.usage())),
276            Err(error @ ResolveError::NotFound(_)) => error,
277            Err(error) => return Err(CodeResolveError::Resolve(error)),
278        };
279        let Some((prefix, member)) = path
280            .rsplit_once("::")
281            .filter(|(prefix, _)| !prefix.is_empty() && namespace == Namespace::Value)
282        else {
283            return Err(CodeResolveError::Resolve(missing));
284        };
285        let prefix =
286            match self
287                .index
288                .resolve_at(module, prefix, Some(Namespace::Type), heads, steps)
289            {
290                Ok(resolution) => resolution,
291                Err(ResolveError::NotFound(_)) => return Err(CodeResolveError::Resolve(missing)),
292                Err(error) => return Err(CodeResolveError::Resolve(error)),
293            };
294        if !prefix
295            .sites
296            .iter()
297            .any(|id| self.index.items[id.index()].kind == SymbolKind::TypeAlias)
298        {
299            return Err(CodeResolveError::Resolve(missing));
300        }
301        if prefix.sites.len() != 1 {
302            return Err(CodeResolveError::Resolve(ResolveError::Ambiguous(
303                prefix.sites,
304            )));
305        }
306        let alias = prefix.sites[0];
307        let file = &self.index.items[alias.index()].file;
308        meter
309            .work(path.len().saturating_mul(2), file, None)
310            .map_err(budget)?;
311        let mut admission = ItemAdmission::new(&meter, file);
312        let result = {
313            let mut memory = Memory::new(&mut admission);
314            self.alias_member(alias, member, &meter, &mut memory, steps)
315        };
316        match result {
317            Ok(mut resolution) => {
318                resolution.via_glob |= prefix.via_glob;
319                Ok((resolution, meter.usage()))
320            }
321            Err(Failure::Code(error) | Failure::Outside(error)) => Err(error),
322            Err(Failure::Storage(error)) => Err(budget(admission.error(error))),
323        }
324    }
325
326    fn alias_member<S: Admission + ?Sized>(
327        &self,
328        first: ItemId,
329        member: &str,
330        meter: &Meter,
331        memory: &mut Memory<'_, S>,
332        steps: Steps<'_>,
333    ) -> Result<Resolution, Failure> {
334        let (nominal, aliases, carried) =
335            self.alias_nominal(first, member, meter, memory, steps, AliasPurpose::Member)?;
336        let item = &self.index.items[nominal.index()];
337        let home = self.homes[nominal.index()]
338            .module()
339            .ok_or(CodeResolveError::MissingContext(nominal))?;
340        let path = memory.format(&format_args!("{}::{member}", item.name))?;
341        meter.work(path.len(), &item.file, None).map_err(budget)?;
342        let mut resolution = self
343            .index
344            .resolve_at(
345                home,
346                &path,
347                Some(Namespace::Value),
348                Heads::Code {
349                    test: item.test != TestRole::None,
350                },
351                steps,
352            )
353            .map_err(CodeResolveError::Resolve)?;
354        for id in &resolution.sites {
355            match self.require_unconditional_inherent_method_counted(*id, steps) {
356                Ok(()) => {}
357                Err(CodeResolveError::MethodApplicability(_)) => {
358                    return Err(unsupported(
359                        first,
360                        member,
361                        "requires an unconditionally applicable inherent method on the exact nominal type",
362                    ).into());
363                }
364                Err(error) => return Err(error.into()),
365            }
366        }
367        resolution.via_glob |= carried;
368        resolution.type_aliases = aliases;
369        Ok(resolution)
370    }
371
372    fn alias_nominal<S: Admission + ?Sized>(
373        &self,
374        first: ItemId,
375        member: &str,
376        meter: &Meter,
377        memory: &mut Memory<'_, S>,
378        steps: Steps<'_>,
379        purpose: AliasPurpose,
380    ) -> Result<(ItemId, Vec<ItemId>, bool), Failure> {
381        let mut current = first;
382        let mut aliases = Vec::new();
383        let mut carried = false;
384        loop {
385            let item = &self.index.items[current.index()];
386            let declared = current;
387            meter
388                .work(aliases.len().saturating_add(1), &item.file, None)
389                .map_err(budget)?;
390            if purpose == AliasPurpose::FirstParty
391                && item.file.authority() != SourceAuthorityId::FIRST_PARTY
392            {
393                return Err(Failure::Outside(unsupported(
394                    current,
395                    member,
396                    "alias is outside the first-party source",
397                )));
398            }
399            if aliases.contains(&current) {
400                return Err(
401                    CodeResolveError::Resolve(ResolveError::Cyclic(item.path.to_string())).into(),
402                );
403            }
404            let arguments = alias_arity(item)
405                .ok_or_else(|| Failure::Outside(unsupported(current, member, ALIAS_SYNTAX)))?;
406            let (home, rhs, configuration) = self
407                .index
408                .aliases
409                .get(&current)
410                .ok_or_else(|| unsupported(current, member, "plain alias target is absent"))?;
411            memory.push(&mut aliases, current)?;
412            let path = alias_path(rhs, memory)?;
413            meter.work(path.len(), &item.file, None).map_err(budget)?;
414            let heads = Heads::Code {
415                test: item.test != TestRole::None,
416            };
417            let resolution = self.resolve_nominal_alias_target(
418                (*home, &path),
419                (current, member),
420                heads,
421                steps,
422                purpose,
423            )?;
424            if resolution.sites.len() != 1 {
425                return Err(
426                    CodeResolveError::Resolve(ResolveError::Ambiguous(resolution.sites)).into(),
427                );
428            }
429            carried |= resolution.via_glob;
430            current = resolution.sites[0];
431            let target = &self.index.items[current.index()];
432            let next = destination(target, arguments, purpose);
433            if purpose == AliasPurpose::FirstParty
434                && let Destination::Outside(reason) = next
435            {
436                return Err(Failure::Outside(unsupported(declared, member, reason)));
437            }
438            if purpose != AliasPurpose::Member
439                && (*configuration == crate::facts::ConfigurationDependence::Conditional
440                    || !self
441                        .index
442                        .module_is_unconditional(*home, steps)
443                        .map_err(CodeResolveError::Resolve)?
444                    || self
445                        .index
446                        .unconditional_type_path(*home, &path, heads, steps)
447                        .map_err(CodeResolveError::Resolve)?
448                        != Some(current))
449            {
450                return Err(unsupported(
451                    declared,
452                    member,
453                    "alias route is not unconditionally selected",
454                )
455                .into());
456            }
457            match next {
458                Destination::Alias => {}
459                Destination::Nominal(arity) if arity == arguments => {
460                    return Ok((current, aliases, carried));
461                }
462                Destination::Nominal(_) => {
463                    return Err(unsupported(declared, member, NOMINAL_ARITY).into());
464                }
465                Destination::Outside(reason) => {
466                    return Err(Failure::Outside(unsupported(declared, member, reason)));
467                }
468            }
469        }
470    }
471
472    fn resolve_nominal_alias_target(
473        &self,
474        (home, path): (usize, &str),
475        (alias, member): (ItemId, &str),
476        heads: Heads,
477        steps: Steps<'_>,
478        purpose: AliasPurpose,
479    ) -> Result<Resolution, Failure> {
480        if purpose != AliasPurpose::FirstParty {
481            return self
482                .index
483                .resolve_at(home, path, Some(Namespace::Type), heads, steps)
484                .map_err(|error| CodeResolveError::Resolve(error).into());
485        }
486        match self.index.resolve_alias_at(home, path, heads, steps) {
487            Ok(Some(resolution)) => Ok(resolution),
488            Ok(None) => Err(Failure::Outside(unsupported(
489                alias,
490                member,
491                "target is outside the indexed source",
492            ))),
493            Err(error @ ResolveError::NotFound(_))
494                if !self.indexed_alias_head(home, path, heads, steps)? =>
495            {
496                Err(Failure::Outside(CodeResolveError::Resolve(error)))
497            }
498            Err(error) => Err(CodeResolveError::Resolve(error).into()),
499        }
500    }
501
502    fn indexed_alias_head(
503        &self,
504        home: usize,
505        path: &str,
506        heads: Heads,
507        steps: Steps<'_>,
508    ) -> Result<bool, CodeResolveError> {
509        let written = path.strip_prefix("::").unwrap_or(path);
510        let Some((head, _)) = written.split_once("::") else {
511            return Ok(false);
512        };
513        if matches!(head, "crate" | "self" | "super") {
514            return Ok(true);
515        }
516        let head = &path[..path.len() - written.len() + head.len()];
517        match self
518            .index
519            .resolve_at(home, head, Some(Namespace::Type), heads, steps)
520        {
521            Ok(resolution) => Ok(resolution.sites.iter().any(|id| {
522                self.index.items[id.index()].file.authority() == SourceAuthorityId::FIRST_PARTY
523            })),
524            Err(ResolveError::NotFound(_)) => Ok(false),
525            Err(error) => Err(CodeResolveError::Resolve(error)),
526        }
527    }
528}