/// No live path contains a binding.

Unbound,

/// Some live paths contain a binding and others leave the symbol unbound.

PossiblyBound,

/// Every live path contains a binding.

Bound,

/// An ordinary binding leaves previous imported qualifiers in place.

Preserve,

/// The imported member or wildcard binding may contribute a `Final` qualifier.

Record,

/// A module import removes previous imported qualifiers from its scope.

Clear,

fn bindings_id(self) -> InternedBindingsId {

self.0

}

fn declarations_id(self) -> InternedDeclarationsId {

self.1

}

interned_bindings: RetainedBindingsBuilder,

interned_ids_by_bindings: hashbrown::HashTable<InternedBindingsId>,

interned_declarations: RetainedDeclarationsBuilder,

interned_ids_by_declarations: FxHashMap<Declarations, InternedDeclarationsId>,

// Undeclared states are common and can be interned by their dense constraint IDs.

undeclared_declarations_by_constraint:

IndexVec<ScopedReachabilityConstraintId, Option<InternedDeclarationsId>>,

// These values are extremely common, so avoid repeatedly hashing their small vectors.

always_unbound_bindings: Option<InternedBindingsId>,

always_undeclared_declarations: Option<InternedDeclarationsId>,

fn with_capacity(bindings: usize, declaration_map: usize, declarations: usize) -> Self {

Self {

interned_bindings: RetainedBindingsBuilder::with_capacity(bindings),

interned_ids_by_bindings: hashbrown::HashTable::with_capacity(bindings),

interned_declarations: RetainedDeclarationsBuilder::with_capacity(declarations),

interned_ids_by_declarations: FxHashMap::with_capacity_and_hasher(

declaration_map,

FxBuildHasher,

),

undeclared_declarations_by_constraint: IndexVec::new(),

always_unbound_bindings: None,

always_undeclared_declarations: None,

}

}

fn intern_bindings(&mut self, bindings: &Bindings) -> InternedBindingsId {

if bindings.is_always_unbound() {

if let Some(interned_id) = self.always_unbound_bindings {

return interned_id;

}

let interned_id = self.interned_bindings.push(bindings);

self.always_unbound_bindings = Some(interned_id);

return interned_id;

}

// The retained representation discards the unbound narrowing constraint, so it isn't

// part of the interned identity.

let hash = Self::hash_bindings(bindings.as_slice());

let interned_bindings = &mut self.interned_bindings;

let entry = self.interned_ids_by_bindings.entry(

hash,

|id| interned_bindings.get(*id) == bindings.as_slice(),

|id| Self::hash_bindings(interned_bindings.get(*id)),

);

match entry {

hashbrown::hash_table::Entry::Occupied(entry) => *entry.get(),

hashbrown::hash_table::Entry::Vacant(entry) => {

let interned_id = interned_bindings.push(bindings);

entry.insert(interned_id);

interned_id

}

}

}

fn hash_bindings(live_bindings: &[LiveBinding]) -> u64 {

let mut hasher = FxHasher::default();

live_bindings.hash(&mut hasher);

hasher.finish()

}

fn intern_declarations(&mut self, declarations: Declarations) -> InternedDeclarationsId {

if declarations.is_always_undeclared() {

if let Some(interned_id) = self.always_undeclared_declarations {

return interned_id;

}

let interned_id = self.interned_declarations.push(&declarations);

self.always_undeclared_declarations = Some(interned_id);

return interned_id;

}

if let Some(reachability_constraint) = declarations.undeclared_reachability_constraint()

&& !reachability_constraint.is_terminal()

{

let index = reachability_constraint.index();

let len = self.undeclared_declarations_by_constraint.len();

if index >= len {

self.undeclared_declarations_by_constraint

.resize(index + 1, None);

} else if let Some(interned_id) =

self.undeclared_declarations_by_constraint[reachability_constraint]

{

return interned_id;

}

let interned_id = self.interned_declarations.push(&declarations);

self.undeclared_declarations_by_constraint[reachability_constraint] = Some(interned_id);

return interned_id;

}

match self.interned_ids_by_declarations.entry(declarations) {

Entry::Occupied(entry) => *entry.get(),

Entry::Vacant(entry) => {

let interned_id = self.interned_declarations.push(entry.key());

entry.insert(interned_id);

interned_id

}

}

}

fn intern_place_state(

&mut self,

bindings: &Bindings,

declarations: Declarations,

) -> InternedPlaceStateId {

InternedPlaceStateId(

self.intern_bindings(bindings),

self.intern_declarations(declarations),

)

}

fn retain_place_state(

&mut self,

bindings: &Bindings,

declarations: Declarations,

) -> InternedPlaceStateId {

// Other retained declarations rarely repeat. Keep the compact IDs without hashing every

// declaration vector to find the occasional duplicate.

let declarations_id = if declarations.undeclared_reachability_constraint().is_some() {

self.intern_declarations(declarations)

} else {

self.interned_declarations.push(&declarations)

};

InternedPlaceStateId(self.intern_bindings(bindings), declarations_id)

}

fn with_capacity(bindings: usize) -> Self {

Self {

ends: IndexVec::with_capacity(bindings),

live_bindings: Vec::with_capacity(bindings),

}

}

fn push(&mut self, bindings: &Bindings) -> InternedBindingsId {

// Definition IDs are also 32-bit and a single scope cannot practically approach this

// limit. Keeping one cumulative end offset per state halves the retained range metadata.

self.live_bindings.extend_from_slice(bindings.as_slice());

let end = u32::try_from(self.live_bindings.len())

.expect("Expected live-bindings length to fit into a u32");

self.ends.push(end)

}

fn get(&self, index: InternedBindingsId) -> &[LiveBinding] {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedBindingsId::new(index.index() - 1)]

};

&self.live_bindings[start as usize..end as usize]

}

fn finish(

self,

narrowing_constraints: &mut NarrowingConstraintsBuilder,

reachability_constraints: &mut ReachabilityConstraintsBuilder,

) -> RetainedBindings {

for binding in &self.live_bindings {

reachability_constraints.mark_used(binding.reachability_constraint());

narrowing_constraints.mark_used(binding.narrowing_constraint());

}

RetainedBindings {

ends: self.ends.into(),

live_bindings: self.live_bindings.into_boxed_slice(),

}

}

type Output = [LiveBinding];

fn index(&self, index: InternedBindingsId) -> &Self::Output {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedBindingsId::new(index.index() - 1)]

};

&self.live_bindings[start as usize..end as usize]

}

/// The exclusive end of each state in `live_declarations`; its start is the previous end.

ends: FrozenIndexVec<InternedDeclarationsId, u32>,

live_declarations: Box<[LiveDeclaration]>,

fn with_capacity(declarations: usize) -> Self {

Self {

ends: IndexVec::with_capacity(declarations),

live_declarations: Vec::with_capacity(declarations),

}

}

fn push(&mut self, declarations: &Declarations) -> InternedDeclarationsId {

self.live_declarations.extend(declarations.iter().cloned());

let end = u32::try_from(self.live_declarations.len())

.expect("Expected live-declarations length to fit into a u32");

self.ends.push(end)

}

fn get(&self, index: InternedDeclarationsId) -> &[LiveDeclaration] {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedDeclarationsId::new(index.index() - 1)]

};

&self.live_declarations[start as usize..end as usize]

}

fn finish(

self,

reachability_constraints: &mut ReachabilityConstraintsBuilder,

) -> RetainedDeclarations {

for declaration in &self.live_declarations {

reachability_constraints.mark_used(declaration.reachability_constraint);

}

RetainedDeclarations {

ends: self.ends.into(),

live_declarations: self.live_declarations.into_boxed_slice(),

}

}

type Output = [LiveDeclaration];

fn index(&self, index: InternedDeclarationsId) -> &Self::Output {

let end = self.ends[index];

let start = if index.index() == 0 {

0

} else {

self.ends[InternedDeclarationsId::new(index.index() - 1)]

};

&self.live_declarations[start as usize..end as usize]

}

end_of_scope: InternedPlaceStateId,

/// The reachable histories exclude their implicit initial unbound/undeclared entries.

reachable: InternedPlaceStateId,

/// Both initial entries have this reachability constraint and are reconstructed by iterators.

initial_reachability: ScopedReachabilityConstraintId,

predicates: Predicates<'db>,

predicate_narrowing_targets: PredicateNarrowingTargets,

reachability_constraints: ReachabilityConstraints,

narrowing_constraints: NarrowingConstraints,

fn from_entries(mut entries: Vec<(ScopedPredicateId, ScopedPlaceId)>) -> Self {

entries.sort_unstable_by_key(|&(predicate, place)| (place, predicate));

entries.dedup();

Self(entries.into_boxed_slice())

}

/// Returns whether `predicate` may narrow `place`.

pub fn contains(&self, predicate: ScopedPredicateId, place: ScopedPlaceId) -> bool {

self.0

.binary_search_by_key(&(place, predicate), |&(predicate, place)| {

(place, predicate)

})

.is_ok()

}

/// Returns whether any predicate may narrow `place`.

pub fn contains_place(&self, place: ScopedPlaceId) -> bool {

self.0

.binary_search_by_key(&place, |&(_, target)| target)

.is_ok()

}

/// [`Bindings`] reaching a [`ScopedUseId`].

bindings_by_use: PackedIds<InternedBindingsId>,

/// Bindings before an `if` chain, for uses in its final `elif` condition.

if_chain_start_by_use: FrozenMap<ScopedUseId, InternedBindingsId>,

/// [`Bindings`] for each member reaching a [`ScopedUseId`].

///

/// This is only used for kwargs expressions, whose corresponding `bindings_by_use` entry

/// is empty.

multi_bindings_by_use: MultiBindingsByUse,

/// Retained [`PlaceState`] values for each member.

member_states: FrozenIndexVec<ScopedMemberId, RetainedPlaceStates>,

/// Snapshots of bindings used to resolve references from nested scopes.

enclosing_snapshots: FrozenIndexVec<ScopedEnclosingSnapshotId, InternedEnclosingSnapshotId>,

/// Completed loop headers in this scope.

loop_headers: FrozenIndexVec<LoopHeaderId, LoopHeader>,

/// Node IDs of "boolean tests".

///

/// See [`super::SemanticIndexBuilder::visit_boolean_test`] for details on what a boolean

/// test is, and how this field is used during type inference.

///

/// The stored IDs exclude any entries that are nested inside another such test in this

/// scope. They are guaranteed to be in sorted order, so that they can be queried using a

/// binary search.

boolean_test_roots: Box<[NodeIndex]>,

/// The early declaration of a combined definition whose binding is recorded separately.

/// It participates in declaration lookup, but not in binding-usage analysis.

DeclarationPart(Definition<'db>),

/// A binding or standalone declaration with no recorded use.

Unused(Definition<'db>),

Used(Definition<'db>),

Undefined,

Deleted,

fn state(self) -> DefinitionState<'db> {

match self {

Self::DeclarationPart(definition)

| Self::Unused(definition)

| Self::Used(definition) => DefinitionState::Defined(definition),

Self::Undefined => DefinitionState::Undefined,

Self::Deleted => DefinitionState::Deleted,

}

}

fn new(states: IndexVec<ScopedDefinitionId, DefinitionEntry<'db>>) -> Self {

let mut states = states.into_iter();

let unbound_state = states.next();

debug_assert_eq!(unbound_state, Some(DefinitionEntry::Undefined));

Self {

states: states.collect(),

}

}

#[inline]

fn get(&self, id: ScopedDefinitionId) -> DefinitionEntry<'db> {

let index = id.index();

if index == 0 {

DefinitionEntry::Undefined

} else {

self.states[index - 1]

}

}

fn iter_enumerated(

&self,

) -> impl Iterator<Item = (ScopedDefinitionId, DefinitionEntry<'db>)> + '_ {

self.states

.iter()

.copied()

.enumerate()

.map(|(index, entry)| (ScopedDefinitionId::new(index + 1), entry))

}

/// Definition states in this scope, plus an implicit "unbound"/"undeclared" definition at

/// index zero.

all_definitions: RetainedDefinitions<'db>,

/// Constraint lookup tables, absent when all retained constraints are built-in terminal

/// values that require no table lookup.

constraint_tables: Option<Box<ConstraintTables<'db>>>,

/// Interned [`Bindings`] values.

interned_bindings: Arc<RetainedBindings>,

/// Interned [`Declarations`] values.

interned_declarations: Arc<RetainedDeclarations>,

/// Tracks the reachability constraint for statements and certain sub-expressions

/// (e.g. ternary branches, boolean operator operands), keyed by their text range.

/// Used to suppress diagnostics in unreachable code.

range_reachability: Box<[(TextRange, RangeInfo)]>,

/// If the definition is a binding (only) -- `x = 1` for example -- then we need

/// [`Declarations`] to know whether this binding is permitted by the live declarations and

/// imported qualifiers.

///

/// If the definition is both a declaration and a binding -- `x: int = 1` for example -- then

/// we don't actually need anything here, all we'll need to validate is that our own RHS is a

/// valid assignment to our own annotation.

///

/// If the definition is a declaration (only) -- `x: int` for example -- then we need

/// [`Bindings`] to know whether this declaration is consistent with the previously

/// inferred type.

///

/// If we see a binding to a `Final`-qualified symbol, we also need the bindings to find

/// previous bindings to that symbol. If there are any, the assignment is invalid.

///

/// Entries whose prior state is the start-of-scope default (always unbound and, if present,

/// always undeclared) are omitted. Lookups use [`ALWAYS_UNBOUND_BINDINGS`] and

/// [`ALWAYS_UNDECLARED_DECLARATIONS`], which are initialized lazily and shared by every map.

definitions_by_definition: FrozenMap<

Definition<'db>,

DefinitionsAtDefinition<InternedBindingsId, InternedDeclarationsId>,

>,

/// Retained [`PlaceState`] values for each symbol.

symbol_states: FrozenIndexVec<ScopedSymbolId, RetainedPlaceStates>,

/// Collection fields omitted when they would all be empty.

extra: Option<Box<UseDefMapExtra>>,

/// Whether or not the end of the scope is reachable.

///

/// This is used to check if the function can implicitly return `None`.

/// For example:

/// ```py

/// def f(cond: bool) -> int | None:

/// if cond:

/// return 1

///

/// def g() -> int:

/// if True:

/// return 1

/// ```

///

/// Function `f` may implicitly return `None`, but `g` cannot.

///

/// This is used by `is_end_of_scope_reachable` in the `ty_python_semantic` crate.

end_of_scope_reachability: ScopedReachabilityConstraintId,

bindings: FxHashSet<Arc<RetainedBindings>>,

declarations: FxHashSet<Arc<RetainedDeclarations>>,

stub_layouts: FxHashMap<SmallVec<[bool; 8]>, StubParameterLayout>,

bindings: Arc<RetainedBindings>,

declarations: Arc<RetainedDeclarations>,

symbols: FrozenIndexVec<ScopedSymbolId, RetainedPlaceStates>,

pub(super) symbol: ScopedSymbolId,

pub(super) definition: Definition<'db>,

pub(super) annotated: bool,

/// Returns the annotation pattern in definition order. A repeated symbol shadows an

/// earlier parameter, so the annotation pattern alone cannot describe that scope.

fn key(parameters: &[StubParameter<'_>]) -> Option<SmallVec<[bool; 8]>> {

let mut key = SmallVec::with_capacity(parameters.len());

for (index, parameter) in parameters.iter().enumerate() {

if parameter.symbol.index() != index {

return None;

}

key.push(parameter.annotated);

}

Some(key)

}

/// Pairs the shared tables with the definitions their indices refer to in this function.

/// The function also keeps its own reachability information for source ranges.

fn instantiate<'db>(

&self,

parameters: Vec<StubParameter<'db>>,

builder: &mut UseDefMapBuilder<'db>,

) -> UseDefMap<'db> {

UseDefMap {

all_definitions: RetainedDefinitions {

states: parameters

.into_iter()

.map(|p| DefinitionEntry::Unused(p.definition))

.collect(),

},

constraint_tables: None,

interned_bindings: Arc::clone(&self.bindings),

interned_declarations: Arc::clone(&self.declarations),

range_reachability: builder.finish_ranges(),

definitions_by_definition: FrozenMap::default(),

symbol_states: self.symbols.clone(),

extra: None,

end_of_scope_reachability: builder.reachability,

}

}

/// Reuses the layout of an earlier stub in this file when the same parameter positions

/// have annotations. The first occurrence and signatures with duplicate names build

/// their binding and declaration tables from the individual parameters.

pub(super) fn finish<'db>(

&mut self,

mut builder: Box<UseDefMapBuilder<'db>>,

) -> Arc<UseDefMap<'db>> {

let Some(parameters) = builder.stub_parameters.take() else {

return self.intern(builder.finish());

};

let shape = StubParameterLayout::key(&parameters);

if let Some(layout) = shape

.as_ref()

.and_then(|shape| self.stub_layouts.get(shape))

{

return Arc::new(layout.instantiate(parameters, &mut builder));

}

builder.record_stub_parameters(parameters);

let map = self.intern(builder.finish());

if let Some(shape) = shape {

self.stub_layouts.insert(

shape,

StubParameterLayout {

bindings: Arc::clone(&map.interned_bindings),

declarations: Arc::clone(&map.interned_declarations),

symbols: map.symbol_states.clone(),

},

);

}

map

}

fn intern<'db>(&mut self, mut map: UseDefMap<'db>) -> Arc<UseDefMap<'db>> {

map.interned_bindings = Self::intern_table(&mut self.bindings, map.interned_bindings);

map.interned_declarations =

Self::intern_table(&mut self.declarations, map.interned_declarations);

Arc::new(map)

}

fn intern_table<T: Eq + std::hash::Hash>(

values: &mut FxHashSet<Arc<T>>,