ide/
moniker.rs

1//! This module generates [moniker](https://microsoft.github.io/language-server-protocol/specifications/lsif/0.6.0/specification/#exportsImports)
2//! for LSIF and LSP.
3
4use core::fmt;
5
6use hir::{Adt, AsAssocItem, Crate, HirDisplay, MacroKind, Semantics};
7use ide_db::{
8    FilePosition, RootDatabase,
9    base_db::{CrateOrigin, LangCrateOrigin},
10    defs::{Definition, IdentClass},
11    helpers::pick_best_token,
12};
13use itertools::Itertools;
14use syntax::{AstNode, SyntaxKind::*, T};
15
16use crate::{RangeInfo, doc_links::token_as_doc_comment, parent_module::crates_for};
17
18#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
19pub enum MonikerDescriptorKind {
20    Namespace,
21    Type,
22    Term,
23    Method,
24    TypeParameter,
25    Parameter,
26    Macro,
27    Meta,
28}
29
30// Subset of scip_types::SymbolInformation::Kind
31#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
32pub enum SymbolInformationKind {
33    AssociatedType,
34    Attribute,
35    Constant,
36    Enum,
37    EnumMember,
38    Field,
39    Function,
40    Macro,
41    Method,
42    Module,
43    Parameter,
44    SelfParameter,
45    StaticMethod,
46    StaticVariable,
47    Struct,
48    Trait,
49    TraitMethod,
50    Type,
51    TypeAlias,
52    TypeParameter,
53    Union,
54    Variable,
55}
56
57impl From<SymbolInformationKind> for MonikerDescriptorKind {
58    fn from(value: SymbolInformationKind) -> Self {
59        match value {
60            SymbolInformationKind::AssociatedType => Self::Type,
61            SymbolInformationKind::Attribute => Self::Meta,
62            SymbolInformationKind::Constant => Self::Term,
63            SymbolInformationKind::Enum => Self::Type,
64            SymbolInformationKind::EnumMember => Self::Type,
65            SymbolInformationKind::Field => Self::Term,
66            SymbolInformationKind::Function => Self::Method,
67            SymbolInformationKind::Macro => Self::Macro,
68            SymbolInformationKind::Method => Self::Method,
69            SymbolInformationKind::Module => Self::Namespace,
70            SymbolInformationKind::Parameter => Self::Parameter,
71            SymbolInformationKind::SelfParameter => Self::Parameter,
72            SymbolInformationKind::StaticMethod => Self::Method,
73            SymbolInformationKind::StaticVariable => Self::Term,
74            SymbolInformationKind::Struct => Self::Type,
75            SymbolInformationKind::Trait => Self::Type,
76            SymbolInformationKind::TraitMethod => Self::Method,
77            SymbolInformationKind::Type => Self::Type,
78            SymbolInformationKind::TypeAlias => Self::Type,
79            SymbolInformationKind::TypeParameter => Self::TypeParameter,
80            SymbolInformationKind::Union => Self::Type,
81            SymbolInformationKind::Variable => Self::Term,
82        }
83    }
84}
85
86#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
87pub struct MonikerDescriptor {
88    pub name: String,
89    pub desc: MonikerDescriptorKind,
90}
91
92#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
93pub struct MonikerIdentifier {
94    pub crate_name: String,
95    pub description: Vec<MonikerDescriptor>,
96}
97
98impl fmt::Display for MonikerIdentifier {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        f.write_str(&self.crate_name)?;
101        f.write_fmt(format_args!("::{}", self.description.iter().map(|x| &x.name).join("::")))
102    }
103}
104
105#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
106pub enum MonikerKind {
107    Import,
108    Export,
109}
110
111#[derive(Debug, Clone, PartialEq, Eq, Hash)]
112pub enum MonikerResult {
113    /// Uniquely identifies a definition.
114    Moniker(Moniker),
115    /// Specifies that the definition is a local, and so does not have a unique identifier. Provides
116    /// a unique identifier for the container.
117    Local { enclosing_moniker: Option<Moniker> },
118}
119
120impl MonikerResult {
121    pub fn from_def(db: &RootDatabase, def: Definition<'_>, from_crate: Crate) -> Option<Self> {
122        def_to_moniker(db, def, from_crate)
123    }
124}
125
126/// Information which uniquely identifies a definition which might be referenceable outside of the
127/// source file. Visibility declarations do not affect presence.
128#[derive(Debug, Clone, PartialEq, Eq, Hash)]
129pub struct Moniker {
130    pub identifier: MonikerIdentifier,
131    pub kind: MonikerKind,
132    pub package_information: PackageInformation,
133}
134
135#[derive(Debug, Clone, PartialEq, Eq, Hash)]
136pub struct PackageInformation {
137    pub name: String,
138    pub repo: Option<String>,
139    pub version: Option<String>,
140}
141
142pub(crate) fn moniker(
143    db: &RootDatabase,
144    FilePosition { file_id, offset }: FilePosition,
145) -> Option<RangeInfo<Vec<MonikerResult>>> {
146    let sema = &Semantics::new(db);
147    let file = sema.parse_guess_edition(file_id).syntax().clone();
148    let current_crate: hir::Crate = crates_for(db, file_id).pop()?.into();
149    let original_token = pick_best_token(file.token_at_offset(offset), |kind| match kind {
150        IDENT
151        | INT_NUMBER
152        | LIFETIME_IDENT
153        | T![self]
154        | T![super]
155        | T![crate]
156        | T![Self]
157        | COMMENT
158        | INNER_DOC_COMMENT
159        | OUTER_DOC_COMMENT => 2,
160        kind if kind.is_trivia() => 0,
161        _ => 1,
162    })?;
163    if let Some(doc_comment) = token_as_doc_comment(&original_token) {
164        return doc_comment.get_definition_with_descend_at(sema, offset, |def, _, _| {
165            let m = def_to_moniker(db, def, current_crate)?;
166            Some(RangeInfo::new(original_token.text_range(), vec![m]))
167        });
168    }
169    let navs = sema
170        .descend_into_macros_exact(original_token.clone())
171        .into_iter()
172        .filter_map(|token| {
173            IdentClass::classify_token(sema, &token).map(IdentClass::definitions_no_ops).map(|it| {
174                it.into_iter().flat_map(|def| def_to_moniker(sema.db, def, current_crate))
175            })
176        })
177        .flatten()
178        .unique()
179        .collect::<Vec<_>>();
180    Some(RangeInfo::new(original_token.text_range(), navs))
181}
182
183pub(crate) fn def_to_kind(db: &RootDatabase, def: Definition<'_>) -> SymbolInformationKind {
184    use SymbolInformationKind::*;
185
186    match def {
187        Definition::Macro(it) => match it.kind(db) {
188            MacroKind::Derive
189            | MacroKind::DeriveBuiltIn
190            | MacroKind::AttrBuiltIn
191            | MacroKind::Attr => Attribute,
192            MacroKind::Declarative | MacroKind::DeclarativeBuiltIn | MacroKind::ProcMacro => Macro,
193        },
194        Definition::Field(..) | Definition::TupleField(..) => Field,
195        Definition::Module(..) | Definition::Crate(..) => Module,
196        Definition::Function(it) => {
197            if it.as_assoc_item(db).is_some() {
198                if it.has_self_param(db) {
199                    if it.has_body(db) { Method } else { TraitMethod }
200                } else {
201                    StaticMethod
202                }
203            } else {
204                Function
205            }
206        }
207        Definition::Adt(Adt::Struct(..)) => Struct,
208        Definition::Adt(Adt::Union(..)) => Union,
209        Definition::Adt(Adt::Enum(..)) => Enum,
210        Definition::EnumVariant(..) => EnumMember,
211        Definition::Const(..) => Constant,
212        Definition::Static(..) => StaticVariable,
213        Definition::Trait(..) => Trait,
214        Definition::TypeAlias(it) => {
215            if it.as_assoc_item(db).is_some() {
216                AssociatedType
217            } else {
218                TypeAlias
219            }
220        }
221        Definition::BuiltinType(..) => Type,
222        Definition::BuiltinLifetime(_) => TypeParameter,
223        Definition::SelfType(..) => TypeAlias,
224        Definition::GenericParam(..) => TypeParameter,
225        Definition::Local(it) => {
226            if it.is_self(db) {
227                SelfParameter
228            } else if it.is_param(db) {
229                Parameter
230            } else {
231                Variable
232            }
233        }
234        Definition::Label(..) | Definition::InlineAsmOperand(_) => Variable, // For lack of a better variant
235        Definition::DeriveHelper(..) => Attribute,
236        Definition::BuiltinAttr(..) => Attribute,
237        Definition::ToolModule(..) => Module,
238        Definition::ExternCrateDecl(..) => Module,
239        Definition::InlineAsmRegOrRegClass(..) => Module,
240    }
241}
242
243/// Computes a `MonikerResult` for a definition. Result cases:
244///
245/// * `Some(MonikerResult::Moniker(_))` provides a unique `Moniker` which refers to a definition.
246///
247/// * `Some(MonikerResult::Local { .. })` provides a `Moniker` for the definition enclosing a local.
248///
249/// * `None` is returned for definitions which are not in a module: `BuiltinAttr`, `BuiltinType`,
250///   `BuiltinLifetime`, `TupleField`, `ToolModule`, and `InlineAsmRegOrRegClass`. TODO: it might be
251///   sensible to provide monikers that refer to some non-existent crate of compiler builtin
252///   definitions.
253pub(crate) fn def_to_moniker(
254    db: &RootDatabase,
255    definition: Definition<'_>,
256    from_crate: Crate,
257) -> Option<MonikerResult> {
258    match definition {
259        Definition::Local(_) | Definition::Label(_) | Definition::GenericParam(_) => {
260            return Some(MonikerResult::Local {
261                enclosing_moniker: enclosing_def_to_moniker(db, definition, from_crate),
262            });
263        }
264        _ => {}
265    }
266    Some(MonikerResult::Moniker(def_to_non_local_moniker(db, definition, from_crate)?))
267}
268
269fn enclosing_def_to_moniker(
270    db: &RootDatabase,
271    mut def: Definition<'_>,
272    from_crate: Crate,
273) -> Option<Moniker> {
274    loop {
275        let enclosing_def = def.enclosing_definition(db)?;
276        if let Some(enclosing_moniker) = def_to_non_local_moniker(db, enclosing_def, from_crate) {
277            return Some(enclosing_moniker);
278        }
279        def = enclosing_def;
280    }
281}
282
283fn def_to_non_local_moniker(
284    db: &RootDatabase,
285    definition: Definition<'_>,
286    from_crate: Crate,
287) -> Option<Moniker> {
288    let module = match definition {
289        Definition::Module(module) if module.is_crate_root(db) => module,
290        _ => definition.module(db)?,
291    };
292    let krate = module.krate(db);
293    let edition = krate.edition(db);
294
295    // Add descriptors for this definition and every enclosing definition.
296    let mut reverse_description = vec![];
297    let mut def = definition;
298    loop {
299        match def {
300            Definition::SelfType(impl_) => {
301                if let Some(trait_ref) = impl_.trait_ref(db) {
302                    // Trait impls use the trait type for the 2nd parameter.
303                    reverse_description.push(MonikerDescriptor {
304                        name: display(db, module, trait_ref),
305                        desc: MonikerDescriptorKind::TypeParameter,
306                    });
307                }
308                // Both inherent and trait impls use the self type for the first parameter.
309                reverse_description.push(MonikerDescriptor {
310                    name: display(db, module, impl_.self_ty(db)),
311                    desc: MonikerDescriptorKind::TypeParameter,
312                });
313                reverse_description.push(MonikerDescriptor {
314                    name: "impl".to_owned(),
315                    desc: MonikerDescriptorKind::Type,
316                });
317            }
318            _ => {
319                if let Some(name) = def.name(db) {
320                    reverse_description.push(MonikerDescriptor {
321                        name: name.display(db, edition).to_string(),
322                        desc: def_to_kind(db, def).into(),
323                    });
324                } else {
325                    match def {
326                        Definition::Module(module) if module.is_crate_root(db) => {
327                            // only include `crate` namespace by itself because we prefer
328                            // `rust-analyzer cargo foo . bar/` over `rust-analyzer cargo foo . crate/bar/`
329                            if reverse_description.is_empty() {
330                                reverse_description.push(MonikerDescriptor {
331                                    name: "crate".to_owned(),
332                                    desc: MonikerDescriptorKind::Namespace,
333                                });
334                            }
335                        }
336                        _ => {
337                            tracing::error!(?def, "Encountered enclosing definition with no name");
338                        }
339                    }
340                }
341            }
342        }
343        let Some(next_def) = def.enclosing_definition(db) else {
344            break;
345        };
346        def = next_def;
347    }
348    if reverse_description.is_empty() {
349        return None;
350    }
351    reverse_description.reverse();
352    let description = reverse_description;
353
354    Some(Moniker {
355        identifier: MonikerIdentifier {
356            crate_name: krate.display_name(db)?.crate_name().to_string(),
357            description,
358        },
359        kind: if krate == from_crate { MonikerKind::Export } else { MonikerKind::Import },
360        package_information: {
361            let (name, repo, version) = match krate.origin(db) {
362                CrateOrigin::Library { repo, name } => (name, repo, krate.version(db)),
363                CrateOrigin::Local { repo, name } => (
364                    name.unwrap_or(krate.display_name(db)?.canonical_name().to_owned()),
365                    repo,
366                    krate.version(db),
367                ),
368                CrateOrigin::Rustc { name } => (
369                    name.clone(),
370                    Some("https://github.com/rust-lang/rust/".to_owned()),
371                    Some(format!("https://github.com/rust-lang/rust/compiler/{name}",)),
372                ),
373                CrateOrigin::Lang(lang) => (
374                    krate.display_name(db)?.canonical_name().to_owned(),
375                    Some("https://github.com/rust-lang/rust/".to_owned()),
376                    Some(match lang {
377                        LangCrateOrigin::Other => {
378                            "https://github.com/rust-lang/rust/library/".into()
379                        }
380                        lang => format!("https://github.com/rust-lang/rust/library/{lang}",),
381                    }),
382                ),
383            };
384            PackageInformation { name: name.as_str().to_owned(), repo, version }
385        },
386    })
387}
388
389fn display<'db, T: HirDisplay<'db>>(db: &'db RootDatabase, module: hir::Module, it: T) -> String {
390    match it.display_source_code(db, module.into(), true) {
391        Ok(result) => result,
392        // Fallback on display variant that always succeeds
393        Err(_) => {
394            let fallback_result =
395                it.display(db, module.krate(db).to_display_target(db)).to_string();
396            tracing::error!(
397                display = %fallback_result, "`display_source_code` failed; falling back to using display"
398            );
399            fallback_result
400        }
401    }
402}
403
404#[cfg(test)]
405mod tests {
406    use crate::{MonikerResult, fixture};
407
408    use super::MonikerKind;
409
410    #[allow(dead_code)]
411    #[track_caller]
412    fn no_moniker(#[rust_analyzer::rust_fixture] ra_fixture: &str) {
413        let (analysis, position) = fixture::position(ra_fixture);
414        if let Some(x) = analysis.moniker(position).unwrap() {
415            assert_eq!(x.info.len(), 0, "Moniker found but no moniker expected: {x:?}");
416        }
417    }
418
419    #[track_caller]
420    fn check_local_moniker(
421        #[rust_analyzer::rust_fixture] ra_fixture: &str,
422        identifier: &str,
423        package: &str,
424        kind: MonikerKind,
425    ) {
426        let (analysis, position) = fixture::position(ra_fixture);
427        let x = analysis.moniker(position).unwrap().expect("no moniker found").info;
428        assert_eq!(x.len(), 1);
429        match x.into_iter().next().unwrap() {
430            MonikerResult::Local { enclosing_moniker: Some(x) } => {
431                assert_eq!(identifier, x.identifier.to_string());
432                assert_eq!(package, format!("{:?}", x.package_information));
433                assert_eq!(kind, x.kind);
434            }
435            MonikerResult::Local { enclosing_moniker: None } => {
436                panic!("Unexpected local with no enclosing moniker");
437            }
438            MonikerResult::Moniker(_) => {
439                panic!("Unexpected non-local moniker");
440            }
441        }
442    }
443
444    #[track_caller]
445    fn check_moniker(
446        #[rust_analyzer::rust_fixture] ra_fixture: &str,
447        identifier: &str,
448        package: &str,
449        kind: MonikerKind,
450    ) {
451        let (analysis, position) = fixture::position(ra_fixture);
452        let x = analysis.moniker(position).unwrap().expect("no moniker found").info;
453        assert_eq!(x.len(), 1);
454        match x.into_iter().next().unwrap() {
455            MonikerResult::Local { enclosing_moniker } => {
456                panic!("Unexpected local enclosed in {enclosing_moniker:?}");
457            }
458            MonikerResult::Moniker(x) => {
459                assert_eq!(identifier, x.identifier.to_string());
460                assert_eq!(package, format!("{:?}", x.package_information));
461                assert_eq!(kind, x.kind);
462            }
463        }
464    }
465
466    #[test]
467    fn basic() {
468        check_moniker(
469            r#"
470//- /lib.rs crate:main deps:foo
471use foo::module::func;
472fn main() {
473    func$0();
474}
475//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
476pub mod module {
477    pub fn func() {}
478}
479"#,
480            "foo::module::func",
481            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
482            MonikerKind::Import,
483        );
484        check_moniker(
485            r#"
486//- /lib.rs crate:main deps:foo
487use foo::module::func;
488fn main() {
489    func();
490}
491//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
492pub mod module {
493    pub fn func$0() {}
494}
495"#,
496            "foo::module::func",
497            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
498            MonikerKind::Export,
499        );
500    }
501
502    #[test]
503    fn moniker_for_trait() {
504        check_moniker(
505            r#"
506//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
507pub mod module {
508    pub trait MyTrait {
509        pub fn func$0() {}
510    }
511}
512"#,
513            "foo::module::MyTrait::func",
514            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
515            MonikerKind::Export,
516        );
517    }
518
519    #[test]
520    fn moniker_for_trait_constant() {
521        check_moniker(
522            r#"
523//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
524pub mod module {
525    pub trait MyTrait {
526        const MY_CONST$0: u8;
527    }
528}
529"#,
530            "foo::module::MyTrait::MY_CONST",
531            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
532            MonikerKind::Export,
533        );
534    }
535
536    #[test]
537    fn moniker_for_trait_type() {
538        check_moniker(
539            r#"
540//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
541pub mod module {
542    pub trait MyTrait {
543        type MyType$0;
544    }
545}
546"#,
547            "foo::module::MyTrait::MyType",
548            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
549            MonikerKind::Export,
550        );
551    }
552
553    #[test]
554    fn moniker_for_trait_impl_function() {
555        check_moniker(
556            r#"
557//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
558pub mod module {
559    pub trait MyTrait {
560        pub fn func() {}
561    }
562    struct MyStruct {}
563    impl MyTrait for MyStruct {
564        pub fn func$0() {}
565    }
566}
567"#,
568            "foo::module::impl::MyStruct::MyTrait::func",
569            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
570            MonikerKind::Export,
571        );
572    }
573
574    #[test]
575    fn moniker_for_field() {
576        check_moniker(
577            r#"
578//- /lib.rs crate:main deps:foo
579use foo::St;
580fn main() {
581    let x = St { a$0: 2 };
582}
583//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
584pub struct St {
585    pub a: i32,
586}
587"#,
588            "foo::St::a",
589            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
590            MonikerKind::Import,
591        );
592    }
593
594    #[test]
595    fn local() {
596        check_local_moniker(
597            r#"
598//- /lib.rs crate:main deps:foo
599use foo::module::func;
600fn main() {
601    func();
602}
603//- /foo/lib.rs crate:foo@0.1.0,https://a.b/foo.git library
604pub mod module {
605    pub fn func() {
606        let x$0 = 2;
607    }
608}
609"#,
610            "foo::module::func",
611            r#"PackageInformation { name: "foo", repo: Some("https://a.b/foo.git"), version: Some("0.1.0") }"#,
612            MonikerKind::Export,
613        );
614    }
615}
ide/moniker.rs

ide/
moniker.rs
