Early Name Resolution: Imports

[yaahc]

tracking my progress on researching this part of name resolution and how it works. Including a copy of the daily personal notes I take on the subject

Outline

I'm going to keep this section up to date with the draft outline in my notes

• Outline

  • names.resolution
    • .early
      • .intro
        • early name resolution is part of macro expansion and is necessary to fully generate the AST of a rust crate
          • should I even mention ASTs? explaining why it exists seems to necessarily go into implementation details
          • the AST is mentioned in other parts of the reference, including the macros section, so possibly this is fine
        • imports are resolved to assist in macro resolution
        • macros are resolved so they can be expanded
        • this process is iterative and repeats until no progress can be made (fixed point algorithm)
          • I think I might be able to include this but not mention how this means it's a fixed point algorithm
            - Post expansion these resolutions are checked again to ensure no new ambiguities were introduced by the expansion process
        • Note: This section seems to be largely related to implementation details, will probably need to trim it down to just the bits that are relevant to language, possibly just noting the relationship to macro expansion
      • .imports
        • .shadowing
          • names bindings resolved through non-glob imports shadow names bindings resolved through glob imports
            • https://doc.rust-lang.org/nightly/reference/items/use-declarations.html#r-items.use.glob.shadowing
          • .macro-textual-scope
            • textual scope name bindings for macros may shadow path-based scope bindings to macros (the later may be unresolved, in which case it doesn't matter if it's a macro)
        • .errors
          • .reserved-names
            id:: 68acc38b-20bd-4f49-99ad-92e98d136e7b
            • the names cfg and cfg_attr are reserved in the macro attribute sub-namespace
          • .ambiguity
            id:: 68acc63c-c157-4f82-9bf6-8f439017b1ed
            • BuiltinAttr
              • it is an error to have a user defined attribute or derive macro with the same name as a builtin attribute (e.g. inline)
            • DeriveHelper
              • derive helpers used before their associated derive may not shadow other attributes or other derive helpers that are otherwise in scope after their derive
            • MacroRulesVsModularized
              • path-based scope bindings for macros may not shadow textual scope bindings to macros
            • GlobVsOuter
              • it is an error to shadow an outer name binding with a glob import
            • GlobVsGlob
              • it is an error to name an item through ambiguous use declarations
                id:: 68b0a2d7-52ce-462a-a166-f8e796a13aca
                • two globs imports which both have an item matching that name where the items are different
                  id:: 68b0a2d7-e8c3-420a-87ee-b875f54e6e15
                  • this is still an error even if there is a third non glob binding resolution to an item with the same name
              • it is not an error to have two glob imports which include items which would be ambiguous so long as you do not name one of those items through the ambiguous glob imports
            • GlobVsExpanded
              • Grey Area
            • MoreExpandedVsOuter
              • it is an error for name bindings from macro expansions to shadow name bindings from outside of those expansions
        • shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
      • .macros
    • .late

[yaahc]

From 2025-08-18:

note, apparently my notes are indented too deeply so github is flattening some of the deeper bullets to seem like they're at the same level, apologies.

• DOING how does it resolve imports?
  id:: 68a4b0a8-0513-457f-ba29-29af33a44b12
  • Resolver::resolve_imports() in rustc_resolve/src/imports.rs
    • implements fixed point algorithm, attempts to resolve imports until it cannot make forward progress
    • further meat in resolve_import
      • if the module hasn't been resolved already
      • try maybe_resolve_path on the module path in the parent scope of the import
        • this calls resolve_path_with_ribs
        • enters function with opt_ns, finalize, ribs, and ignore_bindings all set to None
          • ns for later calls defaults to TypeNS
          • since ribs are none it calls early_resolve_ident_in_lexical_scope with ScopeSet::All(ns) meaning searching all scopes within the type namespace this was incorrect for the simple case I tested, from tests/ui/imports/global-path-resolution-drop.rs which actually never hit this path because module is set to Some earlier in the function
            • gives the resolution from the scope closest to the resolved identifier
            • resolutions are weak when they come from glob imports which cannot shadow names
              • resolver must continue to search outer scopes to report potential ambiguities
            • calls visit_scopes
              • uses parent_scope.module.nearest_item_scope() as the module
                • needed to jump out of trait or enum modules(wait what!?), which do not act as scopes, if we're not in an enum or trait module kind then this just returns self
                  • apparently blocks are considered an anonymous module!?!?!?! I am shook
                  • structs are also treated as modules but don't jump into their parent scopes, so I guess structs have scopes but enums don't, odd.
              • starts visitor at Scope::Module(module, None)
              • call visitor closure to attempt to resolve the item in this module
                • return if we found a conclusive result
              • call self.hygenic_lexical_parent
                • if checks if the outer expression is a decendent of the current syntax context
                  • self is module.expansion
                  • ctxt is syntax context of the name being resolved (macro definition heirarchy chain repr)
                  • syntax context is retrieved from the span of the original ident being resolved
                  • we check if the module.expansion is a child of the syntax context's outer expression
                  • DONE what is outer_expn?
                  • its the outer_expn of the syntax context in the hygiene data
                  • its the id of the expansion (section of macro invocation generated code) that an ident exists within
                  • DONE what is module.expansion?
                  • its the id of the macro expansion that a module is defined within, if the module is defined within a macro's expansion
              • if result is some, construct module from the parent result and set scope to it
              • if none, set scope to Scope::ExternPrelude
                • -> Scope::ToolPrelude
                • -> Scope::StdLibPrelude
                • -> Scope::BuiltinTypes
                • break
              • continue to next iteration of loop

Associated Discussion: #t-compiler/help > understanding SyntaxContextData.outer_expn @ 💬

[yaahc]

From 2025-08-19:

• early name resolution: imports
  • continuing how does it resolve imports?
  • resolve_import actually ends up calling resolve_ident_in_module at least for the case triggered by tests/ui/imports/global-path-resolution-drop.rs
  • this calls normalize_to_macros_2_0_and_adjust which does some similar logic to hygenic_lexical_parent with the whole checking decendent of, remove mark, and get expn_def_scope logic
    • this call does nothing in the case of resolving use ::std::mem
  • DONE run simple test that uses imports with tracing enabled at debug to see precise content of (resolving import for module) resolving import ...
  • taking a step back and describing the high level bits in more detail
    • early name resolution first resolves all imports so that it will be able to resolve most imported macros immediately
      collapsed:: true
      • it does so with a fixed point algorithm
      • it iterates over the list of unresolved imports and attempts to resolve them
        • each resolution attempt returns a count of how many indeterminant imports are left
          • by default you start at 3 count per import, one for each namespace (imports bring items matching the name given in from all 3 namespaces, so a use statement name can resolve to multiple elements)
          • returns 0 to indicate that the import has been determined resolved or not
          • so long as there are any namespaces where the import is still considered indeterminate, add back to the list of unresolved imports
        • ends iteration once the number of unresolved imports remains unchanged between two iterations
    • loop through the list of unexpanded macro invocations

Associated Discussion: #t-compiler/help > understanding SyntaxContextData.outer_expn @ 💬

[yaahc]

From 2025-08-20

• find the module of the first segment of the use declaration
  • use early_resolve_ident_in_lexical_scope to resolve the first path segment
    • walks through the set of lexical scopes with visit_scopes to attempt to resolve the name
      • ScopeSet::All
      • starts with the nearest item scope (trait and enum modules do not act as scopes)
      • modules are walked through by progressively visiting the hygenic_lexical_parent of the current module
        • when the expansion that produced the name did not also produce the current module we treat the module containing the definition of the macro whose invocation produced name as the hygienic lexical parent
          • DOING does this ever even matter for imports?
            • DONE attempt 1: https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=679b03e8b26c233bf9bc9f0b5d3eae14, not valid
              collapsed:: true
              • do these imports get resolved prior to macro expansion?
                • My assumption up until now has been no, but maybe yes?? Do the macros need to be in different crates?

              •  rustc_resolve::imports::resolve_import import=ImportData { kind: Single { source: f1#8, target: f1#8, source_bindings: PerNS { value_ns: Err(Undetermined), type_ns: Err(Undetermined), macro_ns: Err(Undetermined) }, target_bindings: PerNS { value_ns: None, type_ns: None, macro_ns: None }, type_ns_only: false, nested: false, id: NodeId(33) }, root_id: NodeId(33), use_span: src/main.rs:17:21: 17:33 (#8), use_span_with_attributes: src/main.rs:17:21: 17:33 (#8), has_attributes: false, span: src/main.rs:17:25: 17:32 (#8), root_span: src/main.rs:17:25: 17:32 (#8), parent_scope: ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, module_path: [Segment { ident: bar#8, id: Some(NodeId(34)), has_generic_args: false, has_lifetime_args: false, args_span: no-location (#0) }], imported_module: Cell { value: None }, vis: Restricted(DefId(0:0 ~ early_resolution_probe[7a21])) }
                   0ms DEBUG rustc_resolve::imports (resolving import for module) resolving import `bar::...` in `<opaque>`
                   rustc_resolve::ident::maybe_resolve_path path=[Segment { ident: bar#8, id: Some(NodeId(34)), has_generic_args: false, has_lifetime_args: false, args_span: no-location (#0) }], opt_ns=None, parent_scope=ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, ignore_import=Some(ImportData { kind: Single { source: f1#8, target: f1#8, source_bindings: PerNS { value_ns: Err(Undetermined), type_ns: Err(Undetermined), macro_ns: Err(Undetermined) }, target_bindings: PerNS { value_ns: None, type_ns: None, macro_ns: None }, type_ns_only: false, nested: false, id: NodeId(33) }, root_id: NodeId(33), use_span: src/main.rs:17:21: 17:33 (#8), use_span_with_attributes: src/main.rs:17:21: 17:33 (#8), has_attributes: false, span: src/main.rs:17:25: 17:32 (#8), root_span: src/main.rs:17:25: 17:32 (#8), parent_scope: ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, module_path: [Segment { ident: bar#8, id: Some(NodeId(34)), has_generic_args: false, has_lifetime_args: false, args_span: no-location (#0) }], imported_module: Cell { value: None }, vis: Restricted(DefId(0:0 ~ early_resolution_probe[7a21])) })
                     0ms DEBUG rustc_resolve::ident resolve_path ident 0 bar#8 Some(NodeId(34))
                     rustc_resolve::ident::early_resolve_ident_in_lexical_scope orig_ident=bar#8, scope_set=All(TypeNS), parent_scope=ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, finalize=None, force=false, ignore_binding=None, ignore_import=Some(ImportData { kind: Single { source: f1#8, target: f1#8, source_bindings: PerNS { value_ns: Err(Undetermined), type_ns: Err(Undetermined), macro_ns: Err(Undetermined) }, target_bindings: PerNS { value_ns: None, type_ns: None, macro_ns: None }, type_ns_only: false, nested: false, id: NodeId(33) }, root_id: NodeId(33), use_span: src/main.rs:17:21: 17:33 (#8), use_span_with_attributes: src/main.rs:17:21: 17:33 (#8), has_attributes: false, span: src/main.rs:17:25: 17:32 (#8), root_span: src/main.rs:17:25: 17:32 (#8), parent_scope: ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, module_path: [Segment { ident: bar#8, id: Some(NodeId(34)), has_generic_args: false, has_lifetime_args: false, args_span: no-location (#0) }], imported_module: Cell { value: None }, vis: Restricted(DefId(0:0 ~ early_resolution_probe[7a21])) })
                       rustc_resolve::ident::resolve_ident_in_module_unadjusted module=Module(None), ident=bar#0, ns=TypeNS, parent_scope=ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, shadowing=Restricted, finalize=None, ignore_binding=None, ignore_import=Some(ImportData { kind: Single { source: f1#8, target: f1#8, source_bindings: PerNS { value_ns: Err(Undetermined), type_ns: Err(Undetermined), macro_ns: Err(Undetermined) }, target_bindings: PerNS { value_ns: None, type_ns: None, macro_ns: None }, type_ns_only: false, nested: false, id: NodeId(33) }, root_id: NodeId(33), use_span: src/main.rs:17:21: 17:33 (#8), use_span_with_attributes: src/main.rs:17:21: 17:33 (#8), has_attributes: false, span: src/main.rs:17:25: 17:32 (#8), root_span: src/main.rs:17:25: 17:32 (#8), parent_scope: ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, module_path: [Segment { ident: bar#8, id: Some(NodeId(34)), has_generic_args: false, has_lifetime_args: false, args_span: no-location (#0) }], imported_module: Cell { value: None }, vis: Restricted(DefId(0:0 ~ early_resolution_probe[7a21])) })
                       0ms DEBUG rustc_resolve::ident module.expansion: crate0::{{expn0}}, name SyntaxContext: #0
                       0ms DEBUG rustc_resolve::ident block module hygienic parent
                       rustc_resolve::ident::resolve_ident_in_module_unadjusted module=Module(Some(Def(Mod, DefId(0:0 ~ early_resolution_probe[7a21])))), ident=bar#0, ns=TypeNS, parent_scope=ParentScope { module: Some(Def(Mod, DefId(0:0 ~ early_resolution_probe[7a21]))), expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, shadowing=Restricted, finalize=None, ignore_binding=None, ignore_import=Some(ImportData { kind: Single { source: f1#8, target: f1#8, source_bindings: PerNS { value_ns: Err(Undetermined), type_ns: Err(Undetermined), macro_ns: Err(Undetermined) }, target_bindings: PerNS { value_ns: None, type_ns: None, macro_ns: None }, type_ns_only: false, nested: false, id: NodeId(33) }, root_id: NodeId(33), use_span: src/main.rs:17:21: 17:33 (#8), use_span_with_attributes: src/main.rs:17:21: 17:33 (#8), has_attributes: false, span: src/main.rs:17:25: 17:32 (#8), root_span: src/main.rs:17:25: 17:32 (#8), parent_scope: ParentScope { module: None, expansion: expn4, macro_rules: Cell { value: Empty }, derives: [] }, module_path: [Segment { ident: bar#8, id: Some(NodeId(34)), has_generic_args: false, has_lifetime_args: false, args_span: no-location (#0) }], imported_module: Cell { value: None }, vis: Restricted(DefId(0:0 ~ early_resolution_probe[7a21])) })
                       0ms DEBUG rustc_resolve::ident module.expansion: crate0::{{expn0}}, name SyntaxContext: #0
                       0ms DEBUG rustc_resolve::ident no hygienic parent
                

                • so it looks like its not triggering because both imports are seen as within expansion 0? tho the parent scope is expansion 4
            • DONE attempt 2: gonna try ensuring that the macro being called is itself generated by a macro so that we have to do some macro expansion in order to finish resolving the import
              • does the expansion producing the name mean it produced the definition or the for lack of a better term reference to it that we're resolving
                • I'm assuming the latter
              • https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=4b18026f664ae0ebd355e2a260bf78c8
                • also failed, its valid code but doesn't come close to triggering the code paths I care about and resolves thru different means
                • pretty sure this just isn't right and doesn't come close to triggering def-site hygiene
            • TODO attempt 3: try to write what I would expect to trigger def site hygiene, ignoring the whole syntaxcontext expansion id stuff
            • TODO attempt 4: try approaching attempt 2 again maybe
        • else, if the current module is not a named module (e.g. mod foo {}, the crate root, or a trait or enum) the the parent of the current module (or the parent's parent, if the parent is a trait or enum (??? cant they not be??)) is treated as the hygenic lexical parent
        • not included: details on derive fallback lint deprecation thingy, should be none during early name res for imports
        • otherwise return none as the hygenic lexical parent
          • default to the externprelude as the subsequent scope to visit for import resolution
  • use resolve_ident_in_module to resolve subsequent path segments

Associated Discussion: #t-compiler/help > understanding SyntaxContextData.outer_expn @ 💬

[yaahc]

From 2025-08-21

• [[rust reference project goal]] early name resolution: imports
  • does this ever even matter for imports?
    • Answer: No
    • This is all related to macro 2.0 which is unstable and therefore outside of the scope of the reference
  • Going through the extra info vadim gave me that I didn't fully dig into when I first woke up
    • fresh binding should shadow the def in expand rust#143141 (comment)
      • local def site resolution for macro_rules is in the process of being fixed
      • this is not part of early name resolution, so not immediately relevant, but eventually relevant for sure
    • https://github.com/rust-lang/rust/pull/145108/files
      • the resolve_imports algorithm is currently being updated
        • definitely relevant to early name resolution
        • TODO review this when they manage to get it working and land it
      • DONE what does self.assert_speculative control in resolve_imports?
        • its part of the new CmResolver logic which adds a conditional mutability mutability wrapper to the resolver to ensure that the resolver cannot be mutated during speculative resolution
          • Does this also imply that resolve_imports is speculative resolution?
  • TODO What is speculative resolution?
    • based on usage of assert_speculative it seems to be "resolving imports" during early resolution
    • I guess these resolutions are subject to change?
    • how?

      • I'm guessing finalize imports is relevant here

        ```rust
            // Miscellaneous post-processing, including recording re-exports,
            // reporting conflicts, and reporting unresolved imports.
            fn finalize_resolutions_in(&mut self, module: Module<'ra>) {
        ```
        

        • might just be a full answer right there
          • cant find where it reports unresolved imports
          • also what is "miscellaneous post-processing"? is this the stuff like simplifying the importdata into a reexport for reexport chains?
      • oh god how is finalize_import almost 500 lines
        • PLEASEEEE
        • its okay, I'll stay away from this right now because I know it comes after early name resolution, and hopefully I can get some sort of explanation from vadim or find some old conversation in zulip or github that summarizes the logic by the time I get here
  • TODO how are imports resolved through globs during early name resolution?
    • create an example and trace it

Associated Discussion: #t-compiler/help > understanding early name resolution of imports @ 💬

[yaahc]

From 2025-08-22

• [[rust reference project goal]] early name resolution
  • imports
    collapsed:: true
    • DONE Identify all code "pushing something to ambiguity_errors or creating AmbiguityKind before that" since such code represents logic relevant to the language and reference
      id:: 68a8c7c6-98cd-4cd7-b7ca-6b873dcdd8fc
      • DONE try_define
        • AmbiguityKind::GlobVsGlob
        • AmbiguityKind::GlobVsExpanded
        • AmbiguityKind::GlobVsGlob

        • logic from try_define

          id:: 68a8e082-a27a-4b4b-83f1-9f096adc552f
          • if we found a resolution, and when we went to save it there was already an older resolution for that name
            • if the new is an error and the old one is not
              • keep old
            • if both resolutions are from glob imports
              • if they came from the same import
                • keep new
                • TODO when does this happen?
                  • Guess: if you have two different use statements that resolve a path segment through a shared glob import the resolution for the second one may also go thru this logic (tho I would expect it to bail out earlier when the module )
                  • if this is true, I'm also assuming this isn't reference relevant
              • if the resolutions are not equal
                • report glob vs glob ambiguity error
                • TODO what does resolution equality mean and how does it differ from import equality?
                  • Guess: if they resolved to different elements
              • if the old binding is less visible than the new binding
                • keep new
                • TODO when can glob resolutions be less visible than other glob resolutions?
                  • guess: imports are different, the items are the same, but the globs come from different scopes, I think this means that we pick the resolution that comes from the most visible glob import (e.g. if you had a few nested modules that all use super::* and you resolve an item from the top level module you'd want to prefer that resolution resolving directly from the top level import rather than through a long chain of imports)
                  • if this is true, I'm also assuming this isn't reference relevant
            • if only one resolution is a glob
              • if the resolution is of a macro, the non-glob resolution's expansion (invocation that produced the item whose name we're resolving (e.g. the use statement)) is not from, and the resolutions are not the same
                • report a glob vs expanded ambiguity error
                • Okay so the logic as I understand it doesn't match the ambiguity error
                  • the error seems to be about the resolutions being from a glob and a macro expansion respectively
                  • but the key.ns seems to imply that the element the names resolved to is itself a macro
                  • TODO is this logic saying it's only an ambiguity error if we resolve a macro that has a use statement within a macro expansion that is colliding with a different identically named macro from a glob import? That's what it looks like to me
              • conversely, if the resolution is not of a macro, if the non glob is from the root, or the bindings are equal
                • keep non-glob
              • Next: if there was already a shadowed_glob in the old resolution
                • if the glob resolution and the old shadowed glob resolution are not equal
                  • report globvsglob ambiguity error
                • else if the old shadowed glob is less visible than the new one
                  • set save the glob import as a shadowed_glob in the resolution
              • else
                • set save the glob import as a shadowed_glob in the resolution
          • else
            • save new binding in resolution
        • we can ignore all warn_ambiguity logic, it's an old heuristic-based deprecation lint covering some bugs, slated for removal in the not too distant future
        • attaches ambiguity to primary name binding
          • in the case of globs, primary is the old glob
          • in the case of glob and non glob, primary is the non-glob
      • DONE [[rustc_resolve/ident/early_resolve_ident_in_lexical_scope]]
        • AmbiguityKind::BuiltinAttr
        • AmbiguityKind::DeriveHelper
        • AmbiguityKind::MacroRulesVsModularized
        • AmbiguityKind::GlobVsOuter
        • AmbiguityKind::MoreExpandedVsOuter
        • directly pushes into ambiguity_errors

        • logic description

          • in visit_scopes
          • if after matching on the scope we find a candidate binding
            • if we're searching for a macro and found a macro, also check that they're both in the same sub-namespace
            • if we're not finalizing or the scope set we're seaching is ScopeSet::Late
              • return the binding as a break result to visit_scopes
              • I'm assuming this means that all these ambiguity kinds are not part of early resolution, since afaik finalize isn't ever set during early res for imports and all of these, and ScopeSet::Late is also only part of late resolution
              • TODO do as part of [[rust reference project goal/resolution/late]]
                id:: 68a8e5d6-8b84-435b-b3ec-8f9eb30e78aa
      • resolve_ident_in_module_unadjusted
        • do as part of [[rust reference project goal/resolution/late]]
        • AmbiguityKind::GlobVsExpanded
        • directly pushes into ambiguity_errors

        • logic description

          • also seems to be dependent upon finalize being set, assuming this is late res related
      • record_use_inner
        • do as part of [[rust reference project goal/resolution/late]]
        • doesn't seem to directly produce ambiguity kinds
        • pushes ambiguity errors from bindings (presumably the ones produced by try_define) into ambiguity_errors
        • I'm assuming this is functionally part of try_define and not independently important
  • macros
    collapsed:: true
    • starting exploration from resolve_macro_invocation
      • going backwards to focus on where the return value comes from
      • returns Ok(ext) at the end
      • no early returns
      • ext comes from smart_resolve_macro_path
        • some glob delegation stuff I can ignore
        • early return on indeterminate result from resolve_macro_or_delegation_path
        • returns Ok((ext, res)) at the end (the macro definition and the name resolution)
        • ext and res are obtained from resolve_macro_or_delegation_path
          • similarly returns Ok((ext, res)) at the end
          • ignoring delegation impl stuff
          • ext comes from self.get_macro(res) near the end of the body of the function
          • res comes from the beginning of the function
          • it finds a binding with [[rustc_resolve/ident/early_resolve_ident_in_lexical_scope]]
            • depends heavily upon [[visit_scopes]]
          • this will often end up calling [[resolve_ident_in_module_unadjusted]]
        • the rest of the function seems to be error handling
          • TODO document
    • TODO are macros brought into scope via #[macro_use] on a module instead of on an external crate considered part of the macro_use prelude?
      • the reference seems to imply the answer is no, and that they're "imported textually (into the outer scope presumably)"
      • https://github.com/yaahc/rust/blob/29483883eed69d5fb4db01964cdf2af4d86e9cb2/compiler/rustc_resolve/src/ident.rs#L92
        • seems to imply that such macro_use statements may create a "user-defined prelude"
    • TODO document [[visit_scopes]] (or at least more thoroughly organize notes I've gathered so far)
      • https://github.com/yaahc/rust/blob/29483883eed69d5fb4db01964cdf2af4d86e9cb2/compiler/rustc_resolve/src/ident.rs#L57-L96 gives great detail about search order aka scope visitation order
        • notes about the comment without reproducing the content of the comment
        • Type NS
          • in early resolution there are no ribs
          • [[hygienic_lexical_parent]] means the direct parent module, stopping at the first named module boundary, and skipping any enum or trait modules
            • hygienic parts should be irrelevant to the reference until macros 2.0 stabilize
        • Value NS
          • no ribs
          • module logic is the same
        • Macro NS
          • nothing to add
  • [[rust reference project goal/resolution/early/draft]] outline
    • names.resolution
      • .early
        • .intro
          • early name resolution is part of macro expansion and is necessary to fully generate the AST of a rust crate
            • should I even mention ASTs? explaining why it exists seems to necessarily go into implementation details
            • the AST is mentioned in other parts of the reference, including the macros section, so possibly this is fine
          • imports are resolved to assist in macro resolution
          • macros are resolved so they can be expanded
          • this process is iterative and repeats until no progress can be made (fixed point algorithm)
            • I think I might be able to include this but not mention how this means it's a fixed point algorithm
          • Note: This section seems to be largely related to implementation details, will probably need to trim it down to just the bits that are relevant to language, possibly just noting the relationship to macro expansion
        • .imports
          • .shadowing
            • DONE much of the logic implementing the specifics of shadowing can be found in try_define, extract that into prose
              id:: 68a8caa3-3026-4d86-9a7c-f77a9241c881
              • logic from try_define
              • names to elements that resolve through non-glob imports shadow names to elements resolved through glob imports
                • https://doc.rust-lang.org/nightly/reference/items/use-declarations.html#r-items.use.glob.shadowing
          • .errors
            • .reserved-names
              • the names cfg and cfg_attr are reserved in the macro attribute sub-namespace
            • .ambiguity
              • Identify all code "pushing something to ambiguity_errors or creating AmbiguityKind before that" since such code represents logic relevant to the language and reference
          • shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
        • .macros
      • .late

Associated Discussion

[yaahc]

From 2025-08-25:

• [[rust reference project goal]] early name resolution
  • working remote from SoCal today
  • DONE switch to analyzing code on master branch instead of on 1.89 tag
  • DONE moving outline of [[rust reference project goal/resolution/early/draft]] from last friday into a separate page and keeping it up to date as a master copy
  • DONE fix rust analyser errors when viewing rustc code annotated with #[tracing::instrument]
  • DOING Redocumenting ambiguity related code in master, should go faster this time
  • Ambiguity Logic
    • [[AmbiguityKind]]::*(...)
      • [[try_define_local]]
        • changes from last review
          • renamed function from try_define
          • now we always keep non-glob and glob-bindings separate
          • keep only the most visible glob binding
          • can have a glob_binding set but no non_glob_binding
        • AmbiguityKind::GlobVsGlob
          • documented in .ambiguity
        • AmbiguityKind::GlobVsExpanded Grey Area
      • [[rustc_resolve/ident/resolve_ident_in_scope_set]]
        • AmbiguityKind::BuiltinAttr
        • AmbiguityKind::DeriveHelper
        • AmbiguityKind::MacroRulesVsModularized
        • AmbiguityKind::GlobVsOuter
        • AmbiguityKind::MoreExpandedVsOuter``
      • [[finalize_module_binding]]
    • ambiguity_errors.push(...)
      • [[finalize_module_binding]]
      • [[rustc_resolve/ident/resolve_ident_in_scope_set]]
  • Moved from outline
    • Identify all code "pushing something to ambiguity_errors or creating AmbiguityKind before that" since such code represents logic relevant to the language and reference

Associated Discussion: #t-compiler/help > understanding early name resolution of imports @ 💬

[yaahc]

2025-08-26 and 2025-08-27 PTO

[yaahc]

From 2025-08-28

• [[rust reference project goal]] early name resolution
  • DONE Continuing redocumentation of ambiguity related code in master, should go faster this time
  • Ambiguity Logic
    • [[AmbiguityKind]]::*(...)
      • [[rustc_resolve/ident/resolve_ident_in_scope_set]]
        • TODO When does this fn get called with finalize set?
        • all of these require that the two candidates resolve to different entities
        • AmbiguityKind::BuiltinAttr
          • Related Tests
            • tests/ui/proc-macro/ambiguous-builtin-attrs.stderr
          • it is an error to have a user defined attribute or derive macro with the same name as a builtin attribute (e.g. inline)
        • AmbiguityKind::DeriveHelper
          • Related Tests
            • tests/ui/proc-macro/derive-helper-shadowing.stderr
            • tests/ui/proc-macro/proc-macro-attributes.stderr
            • tests/ui/proc-macro/helper-attr-blocked-by-import-ambig.stderr
          • if a derive helper which is used before it's derive has the same name as an outer item
          • or if a derive helper has the same name as an outer derive helper which is used before it's derive
        • AmbiguityKind::MacroRulesVsModularized
          • Related Tests
            • tests/ui/macros/ambiguity-legacy-vs-modern.stderr
            • tests/ui/imports/issue-53269.stderr
          • path-based scope bindings may not shadow textual scope bindings to macros
          • textual scope bindings may shadow path-based scope bindings to macros (later may be unresolved, in which case it doesn't really matter if it's a macro)
        • AmbiguityKind::GlobVsOuter
          • Related Tests
            • tests/ui/macros/macro-path-prelude-shadowing.stderr
            • tests/ui/imports/issue-57539.stderr
            • tests/ui/imports/issue-56125.stderr
            • tests/ui/imports/shadow_builtin_macros.stderr
            • tests/ui/imports/glob-shadowing.stderr
            • tests/ui/rust-2018/uniform-paths/issue-56596.stderr
            • continued in Ambiguity Logic
        • AmbiguityKind::MoreExpandedVsOuter

        • logic description

          • setup a couple mutable bindings, innermost_result (default None) and determinancy (default Determined) which gets mutated by closure passed to visit_scopes
          • visit the scopes to search for a binding and return the best candidate as break_result
            • closure is called on each scope in the scope set from innermost to outermost until the closure returns Some
            • match the current scope being visited, depending on the type of scope attempt to find a candidate for the given name and return as Result
              • TODO document what innermost_result represents
            • match on result of previous step
              • if result is Ok((binding, flags))
                • and they're both macros with that aren't in the same subnamespace
                  • return None
                • if we're doing speculative resolution or late resolution, return Some(Ok(binding)) as break result
                • if innermost_result is None
                  • save current result in innermost_result
                • if innermost_result is Some((innermost_binding, ..)) and innermost_binding and binding resolve to different entities
                  • if either of those resolutions is a builtin nonmacroattr
                  • AmbiguityKind::BuiltinAttr
                  • both candidates need to be in non-bang macro subnamespace (aka the derive+attribute subnamespace)
                  • else if the innermost resolution is a derive_helper used before it was registered (derive_helper_compat), or the second resolution is a derive_helper_compat and the innermost res is a derive_helper
                  • AmbiguityKind::DeriveHelper
                  • if one resolution is a macro using textual scope, and the other is a macro (possibly unresolved, or non-existent) using path-based scope
                  • and their bindings parent modules aren't the same, or the module item is not an ancestor of the macro rules item
                  • AmbiguityKind::MacroRulesVsModularized
                  • "a conflict between a macro_rules name and a non-macro_rules name from another module"
                  • TODO: restate this more clearly
                  • else if the innermost_binding is a glob import
                  • AmbiguityKind::GlobVsOuter
                  • else if the innermost_binding may emerge from a macro again after the resolution of binding showed up
                    id:: 68b0b872-15c2-49be-9cae-26ba784dfade
                  • AmbiguityKind::MoreExpandedVsOuter
                  • a conflict between a macro-expanded name and a less macro-expanded name from outer scope during import or macro resolution
                  • [[is_descendent_of]]
                  • self == ancestor || self.parent == ancestor || self.parent.parent == ancestor || ...
                  • de morgans: self != ancestor && self.parent != ancestor && ...
                  • maybe_after_other = binding expansion is not a descendent of innermost binding expansion (expansion order hierarchy)
                  • maybe_after_invoc = macro expansion of invocation of name is not a decendent of innermost binding expansion (expansion order hierarchy)
                  • maybe_after_other && maybe_after_invoc
                  • binding expansion and the macro expansion of the invocation of name are both not equal to innermost binding expansion or any of its parent expansions
                  • report ambiguity error
                  • return Some(Ok(innermost_binding))
              • if result is Err(Determined) return None
              • if result is Err(Undetermined) set determinacy to Undetermined
          • if break result is Some we return that as the result (either Ok(namebinding) or Err(Determinancy)) for the function
          • otherwise, if innermost_result is Some(binding), return Ok(binding)
          • otherwise we return an error, either based on the determinancy from visit_scopes or Determined if we are finalizing resolutions

Related discussion: #t-compiler/help > understanding early name resolution of imports @ 💬

[yaahc]

From 2025-08-29

• [[rust reference project goal]] early name resolution
  • DONE Continuing redocumentation of ambiguity related code in master, should go faster this time
  • DONE setup new laptop
    • ran into issues, gave to IT
  • DONE revisit [[visit_scopes]] to better understand macro scope iteration order and how it may impact ambiguity logic
  • [[visit_scopes]] macro scope iteration order
    collapsed:: true
    • if namespace is MacroNS, scope iteration order is

    ---

    • Scope::DeriveHelpers
    • Scope::DeriveHelpersCompat
    • Scope::MacroRules(parent_scope.macro_rules)
      • if Binding(binding) => Scope::MacroRules(binding.parent_macro_rules_scope)
      • if Invocation(invoc_id) => Scope::MacroRules(self.invocation_parent_scopes[&invoc_id].macro_rules)
      • Empty => Scope::Module (continues normally from here)

    ---

    • what is binding.parent_macro_rules_scope?
      • its the previous textual macro rules scope that existed before the binding in question introduced the current scope
    • same question for invocation
      • invocation_parent_scopes stores "parent scopes in which macros were invoked"
      • so this is grabbing the textual parent scope of the invocation
    • so macro rules scopes can be introduced two ways, either by defining or macro_using a macro into a scope, which produces binding scopes, or by invoking a macro, which produces invocation scopes. Invocation scopes can further introduce either kind of scope.
    • ultimately the closure in [[rustc_resolve/ident/resolve_ident_in_scope_set]] just jumps thru Invocation scopes, they're just links in the chain that help you find all of the relevant textual binding scopes that may actually serve as a candidate for the name being resolved
  • Ambiguity Logic
    id:: 68b1db2e-923a-4cde-90ed-99a2dc6bb8d7
    collapsed:: true
    • [[AmbiguityKind]]::*(...)
      • [[rustc_resolve/ident/resolve_ident_in_scope_set]]
        id:: 5bf006e3-d4dc-4058-8bd9-a44090c6fe04
        • TODO When does this fn get called with finalize set?
        • AmbiguityKind::GlobVsOuter
          • Related Tests
            • tests/ui/macros/macro-path-prelude-shadowing.stderr
            • tests/ui/imports/issue-57539.stderr
            • tests/ui/imports/issue-56125.stderr
              • during early resolution we resolve the glob import to the extern crate, but then we record that resolution and all of the items in the glob import which includes an item named issue_56125
              • then during finalization we resolve that import again and now we end up finding the glob import we speculatively resolved as a candidate as well as the extern crate, at which point we report the ambiguity
            • tests/ui/imports/shadow_builtin_macros.stderr
            • tests/ui/imports/glob-shadowing.stderr
            • tests/ui/rust-2018/uniform-paths/issue-56596.stderr
          • There are some special cases but I don't think they need to be documented, they're more artifacts of rustc's approach to implementing name res than an intentional restriction within the language
          • it is an error to shadow an outer name binding with a glob import
        • AmbiguityKind::MoreExpandedVsOuter
          • Related Tests
            • tests/ui/rust-2018/uniform-paths/ambiguity-macros-nested.stderr
              • ambiguous item is std
              • candidate 1 is std library
              • candidate 2 is std module from within macro_rules m! invocation
            • tests/ui/rust-2018/uniform-paths/ambiguity-macros.stderr
              • identical to previous example but ambiguity occurs in virtual root module of crate rather than submodule foo
              • not sure how submodule impacts things, the stderr output is essentially identical ignoring differences in filenames and indentation of code in diagnostics
            • tests/ui/macros/issue-78325-inconsistent-resolution.stderr
              • ambiguous item is core
              • candidate 1 is core library
              • candidate 2 is extern crate std as core from within a macro expansion
              • notably, both core and ::core are found to be ambiguous
                • in the previous examples the diagnostic recommends using ::std to refer unambiguously to the builtin crate
                • relevant rules in reference
                  • https://doc.rust-lang.org/nightly/reference/items/extern-crates.html#r-items.extern-crate.extern-prelude
                  • https://doc.rust-lang.org/nightly/reference/paths.html#r-paths.qualifiers.global-root
                • extern crate in the crate root adds it to the extern prelude, and in 2018 edition and onward the global root path qualifier resolves directly to the extern prelude
            • tests/ui/macros/restricted-shadowing-modern.stderr
            • tests/ui/macros/restricted-shadowing-legacy.stderr
            • tests/ui/macros/macro-shadowing.stderr
            • tests/ui/macros/out-of-order-shadowing.stderr
            • tests/ui/imports/shadow_builtin_macros.stderr
            • tests/ui/imports/local-modularized-tricky-fail-1.stderr
            • tests/ui/imports/macro-paths.stderr
              • deeply cursed
              • is ambiguous with an item from within it's own macro invocation's args?
              • how could this item possibly be a candidate when we haven't even resolved the macro invocation and actually expanded the macro?
            • tests/ui/imports/extern-prelude-extern-crate-restricted-shadowing.stderr
            • tests/ui/imports/macros.stderr
            • tests/ui/imports/issue-109148.stderr
          • Related Logic Description: else if the innermost_binding may emerge from a macro again after the resolution of binding showed up
          • it is an error for items from macro expansions to shadow names from outside of those expansions
            • DONE low confidence, could be much more to this
              • okay actually im pretty sure I understand this now, and that it's all because of macro finalization and how we resolve macros and imports multiple times during early resolution, the failures are all in that last step of early resolution where we've already speculatively resolved and expanded everything and now we end up finding extra and often confusing candidates
      • [[finalize_module_binding]]
        • AmbiguityKind::GlobVsExpanded Grey Area
          • Related Tests
            • Identifying Error:
              • a conflict between a name from a glob import and a macro-expanded name in the same module during import or macro resolution
            • tests/ui/imports/local-modularized-tricky-fail-1.stderr
              • exported macro is ambiguous with glob import
              • exported macro is defined in a module below the invocation, but it is generated with a #[macro_export] which ends up defining it at the top level of the crate root, giving it path based scope over the entire module, thus letting it resolve at the point of use during finalization
            • tests/ui/imports/macro-paths.stderr
              • same cursed style of error as in MoreExpandedVsOuter
              • ambiguity is between a glob import and an item from the macro expansion that we're ACTIVELY RESOLVING
              • just gonna look at other test cases and hope this error comes up in simpler cases
              • Okay I think I understand this
              • During finalization we try to ensure that the macro invocation's resolution is unambiguous, at this point we've already speculatively resolved baz::m! to the mod above and the pub use two_macros::m; and expanded it.
              • after expansion we also now have a mod baz in scope within fn g() { ... } and so we end up finding two candidates during finalization, at which point we report the ambiguity
            • tests/ui/imports/macros.stderr
            • tests/ui/imports/issue-114682-1.stderr
          • it is an error to shadow a glob with a name binding from a macro expansion in the same module
    • ambiguity_errors.push(...)
      • [[finalize_module_binding]]
        • nothing new, pushes above error
      • [[rustc_resolve/ident/resolve_ident_in_scope_set]]
        • nothing new, pushes above errors
      • [[record_use_inner]]
        • pushes(reports) ambiguity errors attached to bindings by [[try_define_local]] when those bindings are used
  • DONE update [[rust reference project goal/resolution/early/draft]] outline with info from Ambiguity Logic analysis
  • TODO continue digging into early name resolution of macros
    • tbh im not sure how much more there is to look into here that I haven't already covered, many of the ambiguity errors seem related to macro resolution

Related discussion: #t-compiler/help > understanding early name resolution of imports @ 💬