/// Flow states at each `break` in the current loop.

break_states: Vec<FlowSnapshot>,

/// Flow states at each `continue` in the current loop.

continue_states: Vec<FlowSnapshot>,

/// The RHS expression (e.g., `x is None`).

expression: &'ast ast::Expr,

/// The scope whose place table should be used to resolve the aliased expression.

expression_scope: FileScopeId,

/// Places that, if reassigned, should invalidate this alias.

narrowed_places: PossiblyNarrowedPlaces,

/// The first definition ID allocated after the alias assignment.

first_definition_after_alias: ScopedDefinitionId,

file_scope_id: FileScopeId,

/// Current loop state; None if we are not currently visiting a loop

current_loop: Option<Loop>,

/// Saved narrowing aliases from the enclosing scope, restored on `pop_scope`.

narrowing_aliases: FxHashMap<Name, NarrowingAlias<'ast>>,

/// `global` and `nonlocal` declarations from scopes nested under this one. This is used for:

///

/// 1. Visibility of nested writes. A nested function that binds a variable might affect the

/// inferred type of that variable in an outer scope. After each nested scope is closed, we

/// install synthetic definitions to refer to visible nested writes, which we read from this

/// map. (Note that *which kind* of nested writes is visible isn't necessarily known at that

/// point; we stash both kinds and decide which one to use at inference time.)

/// 2. Semantic syntax errors for invalid `nonlocal` declarations. A `nonlocal` declaration is

/// required to resolve to a local variable, and that variable must not be declared `global`

/// or defined in the global scope. (This is why we track all `nonlocal` declarations, even

/// if there's no binding in their scope.)

///

/// When we're trying to figure out what scope a `nonlocal` declaration resolves to, we have to

/// remember that the definition of a local variable can come after a nested function that

/// mentions it. Similarly, when we're trying to figure out whether `global` bindings from a

/// nested scopes are visible in the current scope, we have to remember that a `global`

/// declaration can also come after nested function definitions. We build up these maps as we

/// encounter each `global` and `nonlocal` keyword, but we generally need to wait until scopes

/// are popped (or later, at inference time) to analyze them.

nested_global_or_nonlocal_declarations: NestedGlobalOrNonlocalDeclarations,

/// Text ranges for `global` and `nonlocal` declarations in this scope, which we use to

/// populate `nested_global_or_nonlocal_declarations` when we reach end of scope.

this_scope_global_or_nonlocal_declarations: FxHashMap<Name, TextRange>,

/// Free symbol uses from nested scopes that may resolve to this scope.

pending_captures: PendingCaptures,

nested_scope: FileScopeId,

laziness: ScopeLaziness,

binding_definition_ids: SmallVec<[ScopedDefinitionId; 2]>,

/// The scope containing the free symbol use. Retaining this lets final resolution apply class

/// scope visibility rules correctly as the capture is propagated outward.

nested_scope: FileScopeId,

name: Name,

laziness: ScopeLaziness,

fn through_scope(mut self, scope_laziness: ScopeLaziness) -> Self {

if scope_laziness.is_lazy() {

self.laziness = ScopeLaziness::Lazy;

}

self

}

pub kind: GlobalOrNonlocal,

pub file_scope_id: FileScopeId,

pub range: TextRange,

pub is_bound: bool,

pub fn is_global(&self) -> bool {

matches!(self.kind, GlobalOrNonlocal::Global)

}

fn into_short_circuit_and_continuation(self, op: ast::BoolOp) -> (FlowSnapshot, FlowSnapshot) {

match op {

ast::BoolOp::And => (self.falsy, self.truthy),

ast::BoolOp::Or => (self.truthy, self.falsy),

}

}

fn into_truthy(self) -> Option<FlowSnapshot> {

match self {

Self::Fallback => None,

Self::Branches(snapshots) => Some(snapshots.truthy),

}

}

fn into_branches(self) -> Option<ConditionFlowSnapshots> {

match self {

Self::Fallback => None,

Self::Branches(snapshots) => Some(snapshots),

}

}

// Builder state

db: &'db dyn Db,

file: ProgramFile<'db>,

source_type: PySourceType,

module: &'ast ParsedModuleRef,

scope_stack: Vec<ScopeInfo<'ast>>,

/// The assignments we're currently visiting, with

/// the most recent visit at the end of the Vec.

current_assignments: Vec<CurrentAssignment<'ast, 'db>>,

/// The statements we're currently visiting, with

/// the most recent visit at the end of the Vec.

current_statements: Vec<CurrentStatement<'ast, 'db>>,

/// The match case we're currently visiting.

current_match_case: Option<CurrentMatchCase<'ast, 'db>>,

/// The name of the first function parameter of the innermost function that we're currently visiting.

current_first_parameter_name: Option<&'ast str>,

/// The scope of a boolean test whose subexpressions we are currently visiting.

///

/// See [`Self::visit_boolean_test`] for details on how this field is used.

active_boolean_test_scope: Option<FileScopeId>,

/// Per-scope exception contexts for nested `try` and `with` statements.

exception_context_stack_manager: ExceptionContextStackManager,

/// Flags about the file's global scope

has_future_annotations: bool,

/// Whether we are currently visiting an `if TYPE_CHECKING` block.

in_type_checking_block: bool,

// Used for checking semantic syntax errors

resolver_environment: ResolverEnvironment<'db>,

python_version: PythonVersion,

source_text: OnceCell<SourceText>,

semantic_checker: SemanticSyntaxChecker,

/// Whether the current statement is inside a `try` statement, including its `except`, `else`,

/// and `finally` suites. Used for semantic syntax checks independently of handler activity.

in_try_statement: bool,

// Semantic Index fields

scopes: IndexVec<FileScopeId, Scope>,

scope_ids_by_scope: IndexVec<FileScopeId, ScopeId<'db>>,

place_tables: IndexVec<FileScopeId, PlaceTableBuilder>,

ast_ids: AstIdsBuilder,

// Box to avoid copying large builders when this index grows.

use_def_maps: IndexVec<FileScopeId, Box<UseDefMapBuilder<'db>>>,

scopes_by_node: FxHashMap<NodeWithScopeKey, FileScopeId>,

definitions_by_node: FxHashMap<DefinitionNodeKey, Definitions<'db>>,

expressions_by_node: FxHashMap<ExpressionNodeKey, Expression<'db>>,

unpacks_by_target: FxHashMap<ExpressionNodeKey, Unpack<'db>>,

condition_flow_snapshots_by_node: FxHashMap<ExpressionNodeKey, ConditionFlowSnapshots>,

statements_by_node: FxHashMap<StatementNodeKey, Statement<'db>>,

imported_modules: FxHashSet<ModuleName>,

seen_submodule_imports: FxHashSet<String>,

// A map from a lambda expression to its enclosing statement.

enclosing_lambda_statements: FxHashMap<ExpressionNodeKey, Statement<'db>>,

// A map from a constraining use of a collection initializer to its definition.

collections_by_use: FxHashMap<ExpressionNodeKey, Definition<'db>>,

// A map from a collection initializer definition to statements containing a constraining use.

uses_by_collection: FxHashMap<Definition<'db>, Vec<(Statement<'db>, ExpressionNodeKey)>>,

/// Hashset of all [`FileScopeId`]s that correspond to [generator functions].

///

/// [generator functions]: https://docs.python.org/3/glossary.html#term-generator

generator_functions: FxHashSet<FileScopeId>,

/// Hashset of all [`FileScopeId`]s that correspond to asynchronous comprehensions.

async_comprehensions: FxHashSet<FileScopeId>,

/// Node indices of syntactic annotation roots.

annotations: Vec<NodeIndex>,

/// Snapshots taken when an eager scope finishes. These never need to be updated.

eager_snapshots: Vec<(EnclosingSnapshotKey, ScopedEnclosingSnapshotId)>,

/// A reassignment can update lazy snapshots of the same name in several nested scopes.

lazy_snapshots: FxHashMap<Name, Vec<(EnclosingSnapshotKey, ScopedEnclosingSnapshotId)>>,

/// Errors collected by the `semantic_checker`.

semantic_syntax_errors: RefCell<Vec<SemanticSyntaxError>>,

/// Maps alias variable names to their narrowing expressions (same-scope only).

/// TODO: cross-scope alias narrowing support

narrowing_aliases: FxHashMap<Name, NarrowingAlias<'ast>>,

/// Alias metadata for predicate leaf names in the current file.

alias_predicates: FxHashMap<ExpressionNodeKey, NarrowingAliasPredicate<'db>>,

pub(super) fn new(

db: &'db dyn Db,

file: ProgramFile<'db>,

module_ref: &'ast ParsedModuleRef,

) -> Self {

let mut builder = Self {

db,

file,

source_type: file.file(db).source_type(db),

module: module_ref,

scope_stack: Vec::new(),

current_assignments: Vec::new(),

current_statements: Vec::new(),

current_match_case: None,

current_first_parameter_name: None,

active_boolean_test_scope: None,

exception_context_stack_manager: ExceptionContextStackManager::default(),

has_future_annotations: false,

in_type_checking_block: false,

scopes: IndexVec::new(),

place_tables: IndexVec::new(),

ast_ids: AstIdsBuilder::with_node_count(module_ref.node_count()),

scope_ids_by_scope: IndexVec::new(),

use_def_maps: IndexVec::new(),

scopes_by_node: FxHashMap::default(),

definitions_by_node: FxHashMap::default(),

expressions_by_node: FxHashMap::default(),

unpacks_by_target: FxHashMap::default(),

condition_flow_snapshots_by_node: FxHashMap::default(),

statements_by_node: FxHashMap::default(),

enclosing_lambda_statements: FxHashMap::default(),

collections_by_use: FxHashMap::default(),

uses_by_collection: FxHashMap::default(),

seen_submodule_imports: FxHashSet::default(),

imported_modules: FxHashSet::default(),

generator_functions: FxHashSet::default(),

async_comprehensions: FxHashSet::default(),

annotations: Vec::new(),

eager_snapshots: Vec::new(),

lazy_snapshots: FxHashMap::default(),

resolver_environment: file.resolver_environment(db),

python_version: file.python_version(db),

source_text: OnceCell::new(),

semantic_checker: SemanticSyntaxChecker::default(),

in_try_statement: false,

semantic_syntax_errors: RefCell::default(),

narrowing_aliases: FxHashMap::default(),

alias_predicates: FxHashMap::default(),

};

builder.push_scope_with_parent(NodeWithScopeRef::Module, None);

builder

}

fn current_scope_info(&self) -> &ScopeInfo<'ast> {

self.scope_stack

.last()

.expect("SemanticIndexBuilder should have created a root scope")

}

fn current_scope_info_mut(&mut self) -> &mut ScopeInfo<'ast> {

self.scope_stack

.last_mut()

.expect("SemanticIndexBuilder should have created a root scope")

}

fn current_scope(&self) -> FileScopeId {

self.current_scope_info().file_scope_id

}

fn current_scope_id(&self) -> ScopeId<'db> {

self.scope_ids_by_scope[self.current_scope()]

}

fn mark_current_comprehension_async(&mut self) {

let scope = self.current_scope();

if self.scopes[scope].kind() == ScopeKind::Comprehension {

self.async_comprehensions.insert(scope);

}

}

fn expect_single_definition(

&self,

definition_key: impl Into<DefinitionNodeKey> + std::fmt::Debug + Copy,

) -> Definition<'db> {

let definitions = &self.definitions_by_node[&definition_key.into()];

debug_assert_eq!(

definitions.len(),

1,

"Expected exactly one definition to be associated with AST node {definition_key:?} but found {}",

definitions.len()

);

definitions[0]

}

/// See [`SemanticIndex::visible_ancestor_scopes`].

fn visible_ancestor_scopes(

&self,

scope: FileScopeId,

) -> impl Iterator<Item = (FileScopeId, &Scope)> {

AncestorsIter::new(&self.scopes, scope).visible()

}

/// Returns the scope ID of the current scope if the current scope

/// is a method inside a class body or an eagerly executed scope inside a method.

/// Returns `None` otherwise, e.g. if the current scope is a function body outside of a class, or if the current scope is not a

/// function body.

fn is_method_or_eagerly_executed_in_method(&self) -> Option<FileScopeId> {

let mut scopes_rev = self

.scope_stack

.iter()

.rev()

.skip_while(|scope| self.scopes[scope.file_scope_id].is_eager());

let current = scopes_rev.next()?;

if self.scopes[current.file_scope_id].kind() != ScopeKind::Function {

return None;

}

let maybe_method = current.file_scope_id;

let parent = scopes_rev.next()?;

match self.scopes[parent.file_scope_id].kind() {

ScopeKind::Class => Some(maybe_method),

ScopeKind::TypeParams => {

// If the function is generic, the parent scope is an annotation scope.

// In this case, we need to go up one level higher to find the class scope.

let grandparent = scopes_rev.next()?;

if self.scopes[grandparent.file_scope_id].kind() == ScopeKind::Class {

Some(maybe_method)

} else {

None

}

}

_ => None,

}

}

/// Checks if a symbol name is bound in any intermediate eager scopes

/// between the current scope and the specified method scope.

///

fn is_symbol_bound_in_intermediate_eager_scopes(

&self,

symbol_name: &str,

method_scope_id: FileScopeId,

) -> bool {

for scope_info in self.scope_stack.iter().rev() {

let scope_id = scope_info.file_scope_id;

if scope_id == method_scope_id {

break;

}

if let Some(symbol_id) = self.place_tables[scope_id].symbol_id(symbol_name) {

let symbol = self.place_tables[scope_id].symbol(symbol_id);

if symbol.is_bound() {

return true;

}

}

}

false

}

/// Push a new loop, returning the outer loop, if any.

fn push_loop(&mut self) -> Option<Loop> {

self.current_scope_info_mut()

.current_loop

.replace(Loop::default())

}

/// Pop a loop, replacing with the previous saved outer loop, if any.

fn pop_loop(&mut self, outer_loop: Option<Loop>) -> Loop {

std::mem::replace(&mut self.current_scope_info_mut().current_loop, outer_loop)

.expect("pop_loop() should not be called without a prior push_loop()")

}

fn current_loop_mut(&mut self) -> Option<&mut Loop> {

self.current_scope_info_mut().current_loop.as_mut()

}

fn push_scope(&mut self, node: NodeWithScopeRef) {

self.push_scope_with_parent(node, Some(self.current_scope()));

}

fn push_scope_with_parent(&mut self, node: NodeWithScopeRef, parent: Option<FileScopeId>) {

let children_start = self.scopes.next_index() + 1;

// Note `node` is guaranteed to be a child of `self.module`

let node_with_kind = node.to_kind(self.module);

let scope = Scope::new(parent, node_with_kind, children_start..children_start);

let scope_kind = scope.kind();

self.exception_context_stack_manager.enter_nested_scope();

let file_scope_id = self.scopes.push(scope);

self.place_tables.push(PlaceTableBuilder::default());

self.use_def_maps

.push(Box::new(UseDefMapBuilder::new(scope_kind)));

let scope_id = ScopeId::new(self.db, self.file, file_scope_id);

self.scope_ids_by_scope.push(scope_id);

let previous = self.scopes_by_node.insert(node.node_key(), file_scope_id);

debug_assert_eq!(previous, None);

// Save narrowing aliases. They will be restored with `pop_scope` after returning from inspecting the inner scope.

// TODO: Cross-scope alias narrowing is not supported yet.

let saved_aliases = std::mem::take(&mut self.narrowing_aliases);

self.scope_stack.push(ScopeInfo {

file_scope_id,

current_loop: None,

narrowing_aliases: saved_aliases,

nested_global_or_nonlocal_declarations: FxHashMap::default(),

this_scope_global_or_nonlocal_declarations: FxHashMap::default(),

pending_captures: FxHashMap::default(),

});

}

// Records snapshots of the place states visible from the current eager scope.

fn record_eager_snapshots(&mut self, popped_scope_id: FileScopeId) {

// If the scope that we just popped off is an eager scope, we need to "lock" our view of

// which bindings reach each of the uses in the scope. Loop through each enclosing scope,

// looking for any that bind each place.

// TODO: Bindings in eager nested scopes also need to be recorded. For example:

// ```python

// class C:

// x: int | None = None

// c = C()

// class _:

// c.x = 1

// reveal_type(c.x) # revealed: Literal[1]

// ```

for ancestor in AncestorsIter::new(&self.scopes, popped_scope_id)

.with_lexical_visibility()

.skip(1)

{

let enclosing_place_table = &self.place_tables[ancestor.id];

for nested_place in self.place_tables[popped_scope_id].iter() {

// Skip this place if this enclosing scope doesn't contain any bindings for it.

// Note that even if this place is bound in the popped scope,

// it may refer to the enclosing scope bindings

// so we also need to snapshot the bindings of the enclosing scope.

let Some(enclosing_place_id) = enclosing_place_table.place_id(nested_place) else {

continue;

};

let enclosing_place = enclosing_place_table.place(enclosing_place_id);

// Snapshot the state of this place that are visible at this point in this

// enclosing scope.

let key = EnclosingSnapshotKey {

enclosing_scope: ancestor.id,

enclosing_place: enclosing_place_id,

nested_scope: popped_scope_id,

nested_laziness: ScopeLaziness::Eager,

};

let eager_snapshot = self.use_def_maps[ancestor.id].snapshot_enclosing_state(

enclosing_place_id,

enclosing_place,

ancestor.is_lexically_visible,

);

self.eager_snapshots.push((key, eager_snapshot));

}

// Lazy scopes are "sticky": once we see a lazy scope we stop doing lookups

// eagerly, even if we would encounter another eager enclosing scope later on.

if !ancestor.scope.is_eager() {

break;

}

}

}

fn bound_scope(&self, enclosing_scope: FileScopeId, symbol: &Symbol) -> Option<FileScopeId> {

self.scope_stack

.iter()

.rev()

.skip_while(|scope| scope.file_scope_id != enclosing_scope)

.find_map(|scope_info| {

let scope_id = scope_info.file_scope_id;

let place_table = &self.place_tables[scope_id];

let place_id = place_table.symbol_id(symbol.name())?;

place_table.place(place_id).is_bound().then_some(scope_id)

})

}

fn register_pending_capture(&mut self, capture: UnresolvedCapture) {

let current_scope = self.current_scope();

let binding_definition_ids = self.place_tables[current_scope]

.symbol_id(&capture.name)

.into_iter()

.flat_map(|symbol| {

self.use_def_maps[current_scope].symbol_binding_definition_ids(symbol)

})

.collect();

let captures = self

.current_scope_info_mut()

.pending_captures

.entry(capture.name)

.or_default();

if let Some(pending) = captures

.iter_mut()

.find(|pending| pending.nested_scope == capture.nested_scope)

{

pending

.binding_definition_ids

.extend(binding_definition_ids);

if capture.laziness.is_lazy() {

pending.laziness = ScopeLaziness::Lazy;

}

} else {

captures.push(PendingCapture {

nested_scope: capture.nested_scope,

laziness: capture.laziness,

binding_definition_ids,

});

}

}

fn record_pending_capture_binding(

&mut self,

symbol: ScopedSymbolId,

definition_id: ScopedDefinitionId,

) {

let current_scope = self.current_scope();

let name = self.place_tables[current_scope]

.symbol(symbol)

.name()

.clone();

let Some(captures) = self

.current_scope_info_mut()

.pending_captures

.get_mut(&name)

else {

return;

};

for capture in captures {

if capture.laziness.is_lazy() {

capture.binding_definition_ids.push(definition_id);

}

}

}

fn finish_pending_captures(

&mut self,

popped_scope_id: FileScopeId,

popped_scope_laziness: ScopeLaziness,

pending_captures: PendingCaptures,

) -> Vec<UnresolvedCapture> {

let mut unresolved = Vec::new();

#[expect(

for (name, captures) in pending_captures {

for capture in captures {

if self.resolve_nested_reference_scope(capture.nested_scope, &name)

== Some(popped_scope_id)

{

self.use_def_maps[popped_scope_id]

.mark_binding_definitions_used(capture.binding_definition_ids);

} else {

unresolved.push(

UnresolvedCapture {

nested_scope: capture.nested_scope,

name: name.clone(),

laziness: capture.laziness,

}

.through_scope(popped_scope_laziness),

);

}

}

}

for symbol in self.place_tables[popped_scope_id].symbols() {

if symbol.is_used() && !symbol.is_local() && !symbol.is_global() {

unresolved.push(UnresolvedCapture {

nested_scope: popped_scope_id,

name: symbol.name().clone(),

laziness: popped_scope_laziness,

});

}

}

unresolved

}

// Records snapshots of the place states visible from the current lazy scope.

fn record_lazy_snapshots(&mut self, popped_scope_id: FileScopeId) {

for enclosing_scope_info in self.scope_stack.iter().rev() {

let enclosing_scope_id = enclosing_scope_info.file_scope_id;

let enclosing_scope_kind = self.scopes[enclosing_scope_id].kind();

let enclosing_place_table = &self.place_tables[enclosing_scope_id];

// We don't record lazy snapshots of attributes or subscripts, because these are difficult to track as they modify.

for nested_symbol in self.place_tables[popped_scope_id].symbols() {

// For the same reason, we don't snapshot bindings owned by `global`/`nonlocal`

// forwarding declarations here; `snapshot_enclosing_state` stores only a

// constraint for those symbols. Also, if the enclosing scope allows its members to

// be modified from elsewhere, the snapshot will not be recorded.

// Lazy annotation scopes that can see class names look up their bindings when evaluated.

if self.scopes[enclosing_scope_id].kind().is_module() {

continue;

}

// Skip this place if this enclosing scope doesn't contain any bindings for it.

// Note that even if this place is bound in the popped scope,

// it may refer to the enclosing scope bindings

// so we also need to snapshot the bindings of the enclosing scope.

let Some(enclosed_symbol_id) =

enclosing_place_table.symbol_id(nested_symbol.name())

else {

continue;

};

let enclosing_place = enclosing_place_table.symbol(enclosed_symbol_id);

if !enclosing_place.is_bound() {

// If the bound scope of a place can be modified from elsewhere, the snapshot will not be recorded.

if self

.bound_scope(enclosing_scope_id, nested_symbol)

.is_none_or(|scope| self.scopes[scope].visibility().is_public())

{

continue;

}

}

// Snapshot the state of this place that are visible at this point in this

// enclosing scope (this may later be invalidated and swept away).

let key = EnclosingSnapshotKey {

enclosing_scope: enclosing_scope_id,

enclosing_place: enclosed_symbol_id.into(),

nested_scope: popped_scope_id,

nested_laziness: ScopeLaziness::Lazy,

};

let lazy_snapshot = self.use_def_maps[enclosing_scope_id].snapshot_enclosing_state(

enclosed_symbol_id.into(),

enclosing_place.into(),

!enclosing_scope_kind.is_class(),

);

self.lazy_snapshots

.entry(nested_symbol.name().clone())

.or_default()

.push((key, lazy_snapshot));

}

}

}

/// Any lazy snapshots of the place that have been reassigned are obsolete, so update them.

/// ```py

/// def outer() -> None:

/// x = None

///

/// def inner2() -> None:

/// # `inner` can be referenced before its definition,

/// # but `inner2` must still be called after the definition of `inner` for this call to be valid.

/// inner()

///

/// # In this scope, `x` may refer to `x = None` or `x = 1`.

/// reveal_type(x) # revealed: None | Literal[1]

///

/// # Reassignment of `x` after the definition of `inner2`.

/// # Update lazy snapshots of `x` for `inner2`.

/// x = 1

///

/// def inner() -> None:

/// # In this scope, `x = None` appears as being shadowed by `x = 1`.

/// reveal_type(x) # revealed: Literal[1]

///

/// # No reassignment of `x` after the definition of `inner`, so we can safely use a lazy snapshot for `inner` as is.

/// inner()

/// inner2()

/// ```

fn update_lazy_snapshots(&mut self, symbol: ScopedSymbolId) {

let current_scope = self.current_scope();

let current_place_table = &self.place_tables[current_scope];

let symbol = current_place_table.symbol(symbol);

// Optimization: if this is the first binding of the symbol we've seen, there can't be any

// lazy snapshots of it to update.

if !symbol.is_reassigned() {

return;

}

let name = symbol.name();

let Some(snapshots) = self.lazy_snapshots.get(name) else {

return;

};

for &(key, snapshot_id) in snapshots {

// A binding between the snapshot and this scope shadows the reassignment.

let first_binding =

self.visible_ancestor_scopes(key.enclosing_scope)

.find(|(ancestor, _)| {

let table = &self.place_tables[*ancestor];

*ancestor == current_scope

|| table

.symbol_id(name)

.is_some_and(|id| table.symbol(id).is_bound())

});

if first_binding.is_some_and(|(ancestor, _)| ancestor == current_scope) {

self.use_def_maps[key.enclosing_scope]

.update_enclosing_snapshot(snapshot_id, key.enclosing_place.expect_symbol());

}

}

}

fn finish_enclosing_snapshots(

&mut self,

) -> FrozenMap<EnclosingSnapshotKey, ScopedEnclosingSnapshotId> {

let mut snapshots = std::mem::take(&mut self.eager_snapshots);

if self.lazy_snapshots.is_empty() {

return FrozenMap::from_entries(snapshots);

}

// Only the last scope containing a bound nonlocal matters: a lazy snapshot must be

// discarded if such a scope occurs at or after its enclosing scope. Build this index once

// instead of searching all later scopes separately for every snapshot.

let mut last_nonlocal_binding = FxHashMap::default();

for (scope_id, place_table) in self.place_tables.iter_enumerated() {

for symbol in place_table.symbols() {

if symbol.is_nonlocal() && symbol.is_bound() {

last_nonlocal_binding.insert(symbol.name(), scope_id);

}

}

}

#[expect(

for (name, lazy) in self.lazy_snapshots.drain() {

let last_nonlocal = last_nonlocal_binding.get(&name);

snapshots.extend(lazy.into_iter().filter(|(key, _)| {

last_nonlocal.is_none_or(|scope| scope.index() < key.enclosing_scope.index())

}));

}

FrozenMap::from_entries(snapshots)

}

/// Finds the nearest visible ancestor scope that actually owns a local binding for `name`.

fn resolve_nested_reference_scope(

&self,

nested_scope: FileScopeId,

name: &str,

) -> Option<FileScopeId> {

self.visible_ancestor_scopes(nested_scope)

.skip(1)

.find_map(|(scope_id, _)| {

let place_table = &self.place_tables[scope_id];

let symbol_id = place_table.symbol_id(name)?;

let symbol = place_table.symbol(symbol_id);

// Only a true local binding in an ancestor scope can be the resolution target.

// `global`/`nonlocal` here are forwarding declarations, not owning bindings.

symbol.is_local().then_some(scope_id)

})

}

/// Returns the `NestedGlobalOrNonlocalDeclarations` that are still visible to the enclosing

/// scope, including those contributed by `global` and `nonlocal` keywords in the popped scope,

/// but excluding nested `nonlocal`s that resolved to the popped scope.

fn pop_scope(&mut self) -> NestedGlobalOrNonlocalDeclarations {

self.exception_context_stack_manager.exit_scope();

let ScopeInfo {

file_scope_id: popped_scope_id,

narrowing_aliases,

mut nested_global_or_nonlocal_declarations,

this_scope_global_or_nonlocal_declarations,

pending_captures,

..

} = self

.scope_stack

.pop()

.expect("Root scope should be present");

self.narrowing_aliases = narrowing_aliases;