Rename Red Knot (#17820)

crates/ty_python_semantic/src/semantic_index/ast_ids.rs

@@ -0,0 +1,212 @@
+use rustc_hash::FxHashMap;
+
+use ruff_index::newtype_index;
+use ruff_python_ast as ast;
+use ruff_python_ast::ExprRef;
+
+use crate::semantic_index::ast_ids::node_key::ExpressionNodeKey;
+use crate::semantic_index::semantic_index;
+use crate::semantic_index::symbol::ScopeId;
+use crate::Db;
+
+/// AST ids for a single scope.
+///
+/// The motivation for building the AST ids per scope isn't about reducing invalidation because
+/// the struct changes whenever the parsed AST changes. Instead, it's mainly that we can
+/// build the AST ids struct when building the symbol table and also keep the property that
+/// IDs of outer scopes are unaffected by changes in inner scopes.
+///
+/// For example, we don't want that adding new statements to `foo` changes the statement id of `x = foo()` in:
+///
+/// ```python
+/// def foo():
+///     return 5
+///
+/// x = foo()
+/// ```
+#[derive(Debug, salsa::Update)]
+pub(crate) struct AstIds {
+    /// Maps expressions to their expression id.
+    expressions_map: FxHashMap<ExpressionNodeKey, ScopedExpressionId>,
+    /// Maps expressions which "use" a symbol (that is, [`ast::ExprName`]) to a use id.
+    uses_map: FxHashMap<ExpressionNodeKey, ScopedUseId>,
+}
+
+impl AstIds {
+    fn expression_id(&self, key: impl Into<ExpressionNodeKey>) -> ScopedExpressionId {
+        let key = &key.into();
+        *self.expressions_map.get(key).unwrap_or_else(|| {
+            panic!("Could not find expression ID for {key:?}");
+        })
+    }
+
+    fn use_id(&self, key: impl Into<ExpressionNodeKey>) -> ScopedUseId {
+        self.uses_map[&key.into()]
+    }
+}
+
+fn ast_ids<'db>(db: &'db dyn Db, scope: ScopeId) -> &'db AstIds {
+    semantic_index(db, scope.file(db)).ast_ids(scope.file_scope_id(db))
+}
+
+/// Uniquely identifies a use of a name in a [`crate::semantic_index::symbol::FileScopeId`].
+#[newtype_index]
+pub struct ScopedUseId;
+
+pub trait HasScopedUseId {
+    /// Returns the ID that uniquely identifies the use in `scope`.
+    fn scoped_use_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedUseId;
+}
+
+impl HasScopedUseId for ast::Identifier {
+    fn scoped_use_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedUseId {
+        let ast_ids = ast_ids(db, scope);
+        ast_ids.use_id(self)
+    }
+}
+
+impl HasScopedUseId for ast::ExprName {
+    fn scoped_use_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedUseId {
+        let expression_ref = ExprRef::from(self);
+        expression_ref.scoped_use_id(db, scope)
+    }
+}
+
+impl HasScopedUseId for ast::ExprRef<'_> {
+    fn scoped_use_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedUseId {
+        let ast_ids = ast_ids(db, scope);
+        ast_ids.use_id(*self)
+    }
+}
+
+/// Uniquely identifies an [`ast::Expr`] in a [`crate::semantic_index::symbol::FileScopeId`].
+#[newtype_index]
+#[derive(salsa::Update)]
+pub struct ScopedExpressionId;
+
+pub trait HasScopedExpressionId {
+    /// Returns the ID that uniquely identifies the node in `scope`.
+    fn scoped_expression_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedExpressionId;
+}
+
+impl<T: HasScopedExpressionId> HasScopedExpressionId for Box<T> {
+    fn scoped_expression_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedExpressionId {
+        self.as_ref().scoped_expression_id(db, scope)
+    }
+}
+
+macro_rules! impl_has_scoped_expression_id {
+    ($ty: ty) => {
+        impl HasScopedExpressionId for $ty {
+            fn scoped_expression_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedExpressionId {
+                let expression_ref = ExprRef::from(self);
+                expression_ref.scoped_expression_id(db, scope)
+            }
+        }
+    };
+}
+
+impl_has_scoped_expression_id!(ast::ExprBoolOp);
+impl_has_scoped_expression_id!(ast::ExprName);
+impl_has_scoped_expression_id!(ast::ExprBinOp);
+impl_has_scoped_expression_id!(ast::ExprUnaryOp);
+impl_has_scoped_expression_id!(ast::ExprLambda);
+impl_has_scoped_expression_id!(ast::ExprIf);
+impl_has_scoped_expression_id!(ast::ExprDict);
+impl_has_scoped_expression_id!(ast::ExprSet);
+impl_has_scoped_expression_id!(ast::ExprListComp);
+impl_has_scoped_expression_id!(ast::ExprSetComp);
+impl_has_scoped_expression_id!(ast::ExprDictComp);
+impl_has_scoped_expression_id!(ast::ExprGenerator);
+impl_has_scoped_expression_id!(ast::ExprAwait);
+impl_has_scoped_expression_id!(ast::ExprYield);
+impl_has_scoped_expression_id!(ast::ExprYieldFrom);
+impl_has_scoped_expression_id!(ast::ExprCompare);
+impl_has_scoped_expression_id!(ast::ExprCall);
+impl_has_scoped_expression_id!(ast::ExprFString);
+impl_has_scoped_expression_id!(ast::ExprStringLiteral);
+impl_has_scoped_expression_id!(ast::ExprBytesLiteral);
+impl_has_scoped_expression_id!(ast::ExprNumberLiteral);
+impl_has_scoped_expression_id!(ast::ExprBooleanLiteral);
+impl_has_scoped_expression_id!(ast::ExprNoneLiteral);
+impl_has_scoped_expression_id!(ast::ExprEllipsisLiteral);
+impl_has_scoped_expression_id!(ast::ExprAttribute);
+impl_has_scoped_expression_id!(ast::ExprSubscript);
+impl_has_scoped_expression_id!(ast::ExprStarred);
+impl_has_scoped_expression_id!(ast::ExprNamed);
+impl_has_scoped_expression_id!(ast::ExprList);
+impl_has_scoped_expression_id!(ast::ExprTuple);
+impl_has_scoped_expression_id!(ast::ExprSlice);
+impl_has_scoped_expression_id!(ast::ExprIpyEscapeCommand);
+impl_has_scoped_expression_id!(ast::Expr);
+
+impl HasScopedExpressionId for ast::ExprRef<'_> {
+    fn scoped_expression_id(&self, db: &dyn Db, scope: ScopeId) -> ScopedExpressionId {
+        let ast_ids = ast_ids(db, scope);
+        ast_ids.expression_id(*self)
+    }
+}
+
+#[derive(Debug, Default)]
+pub(super) struct AstIdsBuilder {
+    expressions_map: FxHashMap<ExpressionNodeKey, ScopedExpressionId>,
+    uses_map: FxHashMap<ExpressionNodeKey, ScopedUseId>,
+}
+
+impl AstIdsBuilder {
+    /// Adds `expr` to the expression ids map and returns its id.
+    pub(super) fn record_expression(&mut self, expr: &ast::Expr) -> ScopedExpressionId {
+        let expression_id = self.expressions_map.len().into();
+
+        self.expressions_map.insert(expr.into(), expression_id);
+
+        expression_id
+    }
+
+    /// Adds `expr` to the use ids map and returns its id.
+    pub(super) fn record_use(&mut self, expr: impl Into<ExpressionNodeKey>) -> ScopedUseId {
+        let use_id = self.uses_map.len().into();
+
+        self.uses_map.insert(expr.into(), use_id);
+
+        use_id
+    }
+
+    pub(super) fn finish(mut self) -> AstIds {
+        self.expressions_map.shrink_to_fit();
+        self.uses_map.shrink_to_fit();
+
+        AstIds {
+            expressions_map: self.expressions_map,
+            uses_map: self.uses_map,
+        }
+    }
+}
+
+/// Node key that can only be constructed for expressions.
+pub(crate) mod node_key {
+    use ruff_python_ast as ast;
+
+    use crate::node_key::NodeKey;
+
+    #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, salsa::Update)]
+    pub(crate) struct ExpressionNodeKey(NodeKey);
+
+    impl From<ast::ExprRef<'_>> for ExpressionNodeKey {
+        fn from(value: ast::ExprRef<'_>) -> Self {
+            Self(NodeKey::from_node(value))
+        }
+    }
+
+    impl From<&ast::Expr> for ExpressionNodeKey {
+        fn from(value: &ast::Expr) -> Self {
+            Self(NodeKey::from_node(value))
+        }
+    }
+
+    impl From<&ast::Identifier> for ExpressionNodeKey {
+        fn from(value: &ast::Identifier) -> Self {
+            Self(NodeKey::from_node(value))
+        }
+    }
+}

crates/ty_python_semantic/src/semantic_index/builder/except_handlers.rs

@@ -0,0 +1,102 @@
+use crate::semantic_index::use_def::FlowSnapshot;
+
+use super::SemanticIndexBuilder;
+
+/// An abstraction over the fact that each scope should have its own [`TryNodeContextStack`]
+#[derive(Debug, Default)]
+pub(super) struct TryNodeContextStackManager(Vec<TryNodeContextStack>);
+
+impl TryNodeContextStackManager {
+    /// Push a new [`TryNodeContextStack`] onto the stack of stacks.
+    ///
+    /// Each [`TryNodeContextStack`] is only valid for a single scope
+    pub(super) fn enter_nested_scope(&mut self) {
+        self.0.push(TryNodeContextStack::default());
+    }
+
+    /// Pop a new [`TryNodeContextStack`] off the stack of stacks.
+    ///
+    /// Each [`TryNodeContextStack`] is only valid for a single scope
+    pub(super) fn exit_scope(&mut self) {
+        let popped_context = self.0.pop();
+        debug_assert!(
+            popped_context.is_some(),
+            "exit_scope() should never be called on an empty stack \
+(this indicates an unbalanced `enter_nested_scope()`/`exit_scope()` pair of calls)"
+        );
+    }
+
+    /// Push a [`TryNodeContext`] onto the [`TryNodeContextStack`]
+    /// at the top of our stack of stacks
+    pub(super) fn push_context(&mut self) {
+        self.current_try_context_stack().push_context();
+    }
+
+    /// Pop a [`TryNodeContext`] off the [`TryNodeContextStack`]
+    /// at the top of our stack of stacks. Return the Vec of [`FlowSnapshot`]s
+    /// recorded while we were visiting the `try` suite.
+    pub(super) fn pop_context(&mut self) -> Vec<FlowSnapshot> {
+        self.current_try_context_stack().pop_context()
+    }
+
+    /// Retrieve the stack that is at the top of our stack of stacks.
+    /// For each `try` block on that stack, push the snapshot onto the `try` block
+    pub(super) fn record_definition(&mut self, builder: &SemanticIndexBuilder) {
+        self.current_try_context_stack().record_definition(builder);
+    }
+
+    /// Retrieve the [`TryNodeContextStack`] that is relevant for the current scope.
+    fn current_try_context_stack(&mut self) -> &mut TryNodeContextStack {
+        self.0
+            .last_mut()
+            .expect("There should always be at least one `TryBlockContexts` on the stack")
+    }
+}
+
+/// The contexts of nested `try`/`except` blocks for a single scope
+#[derive(Debug, Default)]
+struct TryNodeContextStack(Vec<TryNodeContext>);
+
+impl TryNodeContextStack {
+    /// Push a new [`TryNodeContext`] for recording intermediate states
+    /// while visiting a [`ruff_python_ast::StmtTry`] node that has a `finally` branch.
+    fn push_context(&mut self) {
+        self.0.push(TryNodeContext::default());
+    }
+
+    /// Pop a [`TryNodeContext`] off the stack. Return the Vec of [`FlowSnapshot`]s
+    /// recorded while we were visiting the `try` suite.
+    fn pop_context(&mut self) -> Vec<FlowSnapshot> {
+        let TryNodeContext {
+            try_suite_snapshots,
+        } = self
+            .0
+            .pop()
+            .expect("Cannot pop a `try` block off an empty `TryBlockContexts` stack");
+        try_suite_snapshots
+    }
+
+    /// For each `try` block on the stack, push the snapshot onto the `try` block
+    fn record_definition(&mut self, builder: &SemanticIndexBuilder) {
+        for context in &mut self.0 {
+            context.record_definition(builder.flow_snapshot());
+        }
+    }
+}
+
+/// Context for tracking definitions over the course of a single
+/// [`ruff_python_ast::StmtTry`] node
+///
+/// It will likely be necessary to add more fields to this struct in the future
+/// when we add more advanced handling of `finally` branches.
+#[derive(Debug, Default)]
+struct TryNodeContext {
+    try_suite_snapshots: Vec<FlowSnapshot>,
+}
+
+impl TryNodeContext {
+    /// Take a record of what the internal state looked like after a definition
+    fn record_definition(&mut self, snapshot: FlowSnapshot) {
+        self.try_suite_snapshots.push(snapshot);
+    }
+}

crates/ty_python_semantic/src/semantic_index/expression.rs

@@ -0,0 +1,68 @@
+use crate::ast_node_ref::AstNodeRef;
+use crate::db::Db;
+use crate::semantic_index::symbol::{FileScopeId, ScopeId};
+use ruff_db::files::File;
+use ruff_python_ast as ast;
+use salsa;
+
+/// Whether or not this expression should be inferred as a normal expression or
+/// a type expression. For example, in `self.x: <annotation> = <value>`, the
+/// `<annotation>` is inferred as a type expression, while `<value>` is inferred
+/// as a normal expression.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) enum ExpressionKind {
+    Normal,
+    TypeExpression,
+}
+
+/// An independently type-inferable expression.
+///
+/// Includes constraint expressions (e.g. if tests) and the RHS of an unpacking assignment.
+///
+/// ## Module-local type
+/// This type should not be used as part of any cross-module API because
+/// it holds a reference to the AST node. Range-offset changes
+/// then propagate through all usages, and deserialization requires
+/// reparsing the entire module.
+///
+/// E.g. don't use this type in:
+///
+/// * a return type of a cross-module query
+/// * a field of a type that is a return type of a cross-module query
+/// * an argument of a cross-module query
+#[salsa::tracked(debug)]
+pub(crate) struct Expression<'db> {
+    /// The file in which the expression occurs.
+    pub(crate) file: File,
+
+    /// The scope in which the expression occurs.
+    pub(crate) file_scope: FileScopeId,
+
+    /// The expression node.
+    #[no_eq]
+    #[tracked]
+    #[return_ref]
+    pub(crate) node_ref: AstNodeRef<ast::Expr>,
+
+    /// An assignment statement, if this expression is immediately used as the rhs of that
+    /// assignment.
+    ///
+    /// (Note that this is the _immediately_ containing assignment — if a complex expression is
+    /// assigned to some target, only the outermost expression node has this set. The inner
+    /// expressions are used to build up the assignment result, and are not "immediately assigned"
+    /// to the target, and so have `None` for this field.)
+    #[no_eq]
+    #[tracked]
+    pub(crate) assigned_to: Option<AstNodeRef<ast::StmtAssign>>,
+
+    /// Should this expression be inferred as a normal expression or a type expression?
+    pub(crate) kind: ExpressionKind,
+
+    count: countme::Count<Expression<'static>>,
+}
+
+impl<'db> Expression<'db> {
+    pub(crate) fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {
+        self.file_scope(db).to_scope_id(db, self.file(db))
+    }
+}

crates/ty_python_semantic/src/semantic_index/narrowing_constraints.rs

@@ -0,0 +1,144 @@
+//! # Narrowing constraints
+//!
+//! When building a semantic index for a file, we associate each binding with a _narrowing
+//! constraint_, which constrains the type of the binding's symbol. Note that a binding can be
+//! associated with a different narrowing constraint at different points in a file. See the
+//! [`use_def`][crate::semantic_index::use_def] module for more details.
+//!
+//! This module defines how narrowing constraints are stored internally.
+//!
+//! A _narrowing constraint_ consists of a list of _predicates_, each of which corresponds with an
+//! expression in the source file (represented by a [`Predicate`]). We need to support the
+//! following operations on narrowing constraints:
+//!
+//! - Adding a new predicate to an existing constraint
+//! - Merging two constraints together, which produces the _intersection_ of their predicates
+//! - Iterating through the predicates in a constraint
+//!
+//! In particular, note that we do not need random access to the predicates in a constraint. That
+//! means that we can use a simple [_sorted association list_][crate::list] as our data structure.
+//! That lets us use a single 32-bit integer to store each narrowing constraint, no matter how many
+//! predicates it contains. It also makes merging two narrowing constraints fast, since alists
+//! support fast intersection.
+//!
+//! Because we visit the contents of each scope in source-file order, and assign scoped IDs in
+//! source-file order, that means that we will tend to visit narrowing constraints in order by
+//! their predicate IDs. This is exactly how to get the best performance from our alist
+//! implementation.
+//!
+//! [`Predicate`]: crate::semantic_index::predicate::Predicate
+
+use crate::list::{List, ListBuilder, ListSetReverseIterator, ListStorage};
+use crate::semantic_index::predicate::ScopedPredicateId;
+
+/// A narrowing constraint associated with a live binding.
+///
+/// A constraint is a list of [`Predicate`]s that each constrain the type of the binding's symbol.
+///
+/// [`Predicate`]: crate::semantic_index::predicate::Predicate
+pub(crate) type ScopedNarrowingConstraint = List<ScopedNarrowingConstraintPredicate>;
+
+/// One of the [`Predicate`]s in a narrowing constraint, which constraints the type of the
+/// binding's symbol.
+///
+/// Note that those [`Predicate`]s are stored in [their own per-scope
+/// arena][crate::semantic_index::predicate::Predicates], so internally we use a
+/// [`ScopedPredicateId`] to refer to the underlying predicate.
+///
+/// [`Predicate`]: crate::semantic_index::predicate::Predicate
+#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
+pub(crate) struct ScopedNarrowingConstraintPredicate(ScopedPredicateId);
+
+impl ScopedNarrowingConstraintPredicate {
+    /// Returns (the ID of) the `Predicate`
+    pub(crate) fn predicate(self) -> ScopedPredicateId {
+        self.0
+    }
+}
+
+impl From<ScopedPredicateId> for ScopedNarrowingConstraintPredicate {
+    fn from(predicate: ScopedPredicateId) -> ScopedNarrowingConstraintPredicate {
+        ScopedNarrowingConstraintPredicate(predicate)
+    }
+}
+
+/// A collection of narrowing constraints for a given scope.
+#[derive(Debug, Eq, PartialEq)]
+pub(crate) struct NarrowingConstraints {
+    lists: ListStorage<ScopedNarrowingConstraintPredicate>,
+}
+
+// Building constraints
+// --------------------
+
+/// A builder for creating narrowing constraints.
+#[derive(Debug, Default, Eq, PartialEq)]
+pub(crate) struct NarrowingConstraintsBuilder {
+    lists: ListBuilder<ScopedNarrowingConstraintPredicate>,
+}
+
+impl NarrowingConstraintsBuilder {
+    pub(crate) fn build(self) -> NarrowingConstraints {
+        NarrowingConstraints {
+            lists: self.lists.build(),
+        }
+    }
+
+    /// Adds a predicate to an existing narrowing constraint.
+    pub(crate) fn add_predicate_to_constraint(
+        &mut self,
+        constraint: ScopedNarrowingConstraint,
+        predicate: ScopedNarrowingConstraintPredicate,
+    ) -> ScopedNarrowingConstraint {
+        self.lists.insert(constraint, predicate)
+    }
+
+    /// Returns the intersection of two narrowing constraints. The result contains the predicates
+    /// that appear in both inputs.
+    pub(crate) fn intersect_constraints(
+        &mut self,
+        a: ScopedNarrowingConstraint,
+        b: ScopedNarrowingConstraint,
+    ) -> ScopedNarrowingConstraint {
+        self.lists.intersect(a, b)
+    }
+}
+
+// Iteration
+// ---------
+
+pub(crate) type NarrowingConstraintsIterator<'a> =
+    std::iter::Copied<ListSetReverseIterator<'a, ScopedNarrowingConstraintPredicate>>;
+
+impl NarrowingConstraints {
+    /// Iterates over the predicates in a narrowing constraint.
+    pub(crate) fn iter_predicates(
+        &self,
+        set: ScopedNarrowingConstraint,
+    ) -> NarrowingConstraintsIterator<'_> {
+        self.lists.iter_set_reverse(set).copied()
+    }
+}
+
+// Test support
+// ------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    impl ScopedNarrowingConstraintPredicate {
+        pub(crate) fn as_u32(self) -> u32 {
+            self.0.as_u32()
+        }
+    }
+
+    impl NarrowingConstraintsBuilder {
+        pub(crate) fn iter_predicates(
+            &self,
+            set: ScopedNarrowingConstraint,
+        ) -> NarrowingConstraintsIterator<'_> {
+            self.lists.iter_set_reverse(set).copied()
+        }
+    }
+}

crates/ty_python_semantic/src/semantic_index/predicate.rs

@@ -0,0 +1,173 @@
+//! _Predicates_ are Python expressions whose runtime values can affect type inference.
+//!
+//! We currently use predicates in two places:
+//!
+//! - [_Narrowing constraints_][crate::semantic_index::narrowing_constraints] constrain the type of
+//!   a binding that is visible at a particular use.
+//! - [_Visibility constraints_][crate::semantic_index::visibility_constraints] determine the
+//!   static visibility of a binding, and the reachability of a statement.
+
+use ruff_db::files::File;
+use ruff_index::{newtype_index, IndexVec};
+use ruff_python_ast::Singleton;
+
+use crate::db::Db;
+use crate::semantic_index::expression::Expression;
+use crate::semantic_index::global_scope;
+use crate::semantic_index::symbol::{FileScopeId, ScopeId, ScopedSymbolId};
+
+// A scoped identifier for each `Predicate` in a scope.
+#[newtype_index]
+#[derive(Ord, PartialOrd)]
+pub(crate) struct ScopedPredicateId;
+
+// A collection of predicates for a given scope.
+pub(crate) type Predicates<'db> = IndexVec<ScopedPredicateId, Predicate<'db>>;
+
+#[derive(Debug, Default)]
+pub(crate) struct PredicatesBuilder<'db> {
+    predicates: IndexVec<ScopedPredicateId, Predicate<'db>>,
+}
+
+impl<'db> PredicatesBuilder<'db> {
+    /// Adds a predicate. Note that we do not deduplicate predicates. If you add a `Predicate`
+    /// more than once, you will get distinct `ScopedPredicateId`s for each one. (This lets you
+    /// model predicates that might evaluate to different values at different points of execution.)
+    pub(crate) fn add_predicate(&mut self, predicate: Predicate<'db>) -> ScopedPredicateId {
+        self.predicates.push(predicate)
+    }
+
+    pub(crate) fn build(mut self) -> Predicates<'db> {
+        self.predicates.shrink_to_fit();
+        self.predicates
+    }
+}
+
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, salsa::Update)]
+pub(crate) struct Predicate<'db> {
+    pub(crate) node: PredicateNode<'db>,
+    pub(crate) is_positive: bool,
+}
+
+impl Predicate<'_> {
+    pub(crate) fn negated(self) -> Self {
+        Self {
+            node: self.node,
+            is_positive: !self.is_positive,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, salsa::Update)]
+pub(crate) enum PredicateNode<'db> {
+    Expression(Expression<'db>),
+    Pattern(PatternPredicate<'db>),
+    StarImportPlaceholder(StarImportPlaceholderPredicate<'db>),
+}
+
+/// Pattern kinds for which we support type narrowing and/or static visibility analysis.
+#[derive(Debug, Clone, Hash, PartialEq, salsa::Update)]
+pub(crate) enum PatternPredicateKind<'db> {
+    Singleton(Singleton),
+    Value(Expression<'db>),
+    Or(Vec<PatternPredicateKind<'db>>),
+    Class(Expression<'db>),
+    Unsupported,
+}
+
+#[salsa::tracked(debug)]
+pub(crate) struct PatternPredicate<'db> {
+    pub(crate) file: File,
+
+    pub(crate) file_scope: FileScopeId,
+
+    pub(crate) subject: Expression<'db>,
+
+    #[return_ref]
+    pub(crate) kind: PatternPredicateKind<'db>,
+
+    pub(crate) guard: Option<Expression<'db>>,
+
+    count: countme::Count<PatternPredicate<'static>>,
+}
+
+impl<'db> PatternPredicate<'db> {
+    pub(crate) fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {
+        self.file_scope(db).to_scope_id(db, self.file(db))
+    }
+}
+
+/// A "placeholder predicate" that is used to model the fact that the boundness of a
+/// (possible) definition or declaration caused by a `*` import cannot be fully determined
+/// until type-inference time. This is essentially the same as a standard visibility constraint,
+/// so we reuse the [`Predicate`] infrastructure to model it.
+///
+/// To illustrate, say we have a module `exporter.py` like so:
+///
+/// ```py
+/// if <condition>:
+///     class A: ...
+/// ```
+///
+/// and we have a module `importer.py` like so:
+///
+/// ```py
+/// A = 1
+///
+/// from importer import *
+/// ```
+///
+/// Since we cannot know whether or not <condition> is true at semantic-index time,
+/// we record a definition for `A` in `b.py` as a result of the `from a import *`
+/// statement, but place a predicate on it to record the fact that we don't yet
+/// know whether this definition will be visible from all control-flow paths or not.
+/// Essentially, we model `b.py` as something similar to this:
+///
+/// ```py
+/// A = 1
+///
+/// if <star_import_placeholder_predicate>:
+///     from a import A
+/// ```
+///
+/// At type-check time, the placeholder predicate for the `A` definition is evaluated by
+/// attempting to resolve the `A` symbol in `a.py`'s global namespace:
+/// - If it resolves to a definitely bound symbol, then the predicate resolves to [`Truthiness::AlwaysTrue`]
+/// - If it resolves to an unbound symbol, then the predicate resolves to [`Truthiness::AlwaysFalse`]
+/// - If it resolves to a possibly bound symbol, then the predicate resolves to [`Truthiness::Ambiguous`]
+///
+/// [Truthiness]: [crate::types::Truthiness]
+#[salsa::tracked(debug)]
+pub(crate) struct StarImportPlaceholderPredicate<'db> {
+    pub(crate) importing_file: File,
+
+    /// Each symbol imported by a `*` import has a separate predicate associated with it:
+    /// this field identifies which symbol that is.
+    ///
+    /// Note that a [`ScopedSymbolId`] is only meaningful if you also know the scope
+    /// it is relative to. For this specific struct, however, there's no need to store a
+    /// separate field to hold the ID of the scope. `StarImportPredicate`s are only created
+    /// for valid `*`-import definitions, and valid `*`-import definitions can only ever
+    /// exist in the global scope; thus, we know that the `symbol_id` here will be relative
+    /// to the global scope of the importing file.
+    pub(crate) symbol_id: ScopedSymbolId,
+
+    pub(crate) referenced_file: File,
+}
+
+impl<'db> StarImportPlaceholderPredicate<'db> {
+    pub(crate) fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {
+        // See doc-comment above [`StarImportPlaceholderPredicate::symbol_id`]:
+        // valid `*`-import definitions can only take place in the global scope.
+        global_scope(db, self.importing_file(db))
+    }
+}
+
+impl<'db> From<StarImportPlaceholderPredicate<'db>> for Predicate<'db> {
+    fn from(predicate: StarImportPlaceholderPredicate<'db>) -> Self {
+        Predicate {
+            node: PredicateNode::StarImportPlaceholder(predicate),
+            is_positive: true,
+        }
+    }
+}

crates/ty_python_semantic/src/semantic_index/re_exports.rs

@@ -0,0 +1,408 @@
+//! A visitor and query to find all global-scope symbols that are exported from a module
+//! when a wildcard import is used.
+//!
+//! For example, if a module `foo` contains `from bar import *`, which symbols from the global
+//! scope of `bar` are imported into the global namespace of `foo`?
+//!
+//! ## Why is this a separate query rather than a part of semantic indexing?
+//!
+//! This query is called by the [`super::SemanticIndexBuilder`] in order to add the correct
+//! [`super::Definition`]s to the semantic index of a module `foo` if `foo` has a
+//! `from bar import *` statement in its global namespace. Adding the correct `Definition`s to
+//! `foo`'s [`super::SemanticIndex`] requires knowing which symbols are exported from `bar`.
+//!
+//! If we determined the set of exported names during semantic indexing rather than as a
+//! separate query, we would need to complete semantic indexing on `bar` in order to
+//! complete analysis of the global namespace of `foo`. Since semantic indexing is somewhat
+//! expensive, this would be undesirable. A separate query allows us to avoid this issue.
+//!
+//! An additional concern is that the recursive nature of this query means that it must be able
+//! to handle cycles. We do this using fixpoint iteration; adding fixpoint iteration to the
+//! whole [`super::semantic_index()`] query would probably be prohibitively expensive.
+
+use ruff_db::{files::File, parsed::parsed_module};
+use ruff_python_ast::{
+    self as ast,
+    name::Name,
+    visitor::{walk_expr, walk_pattern, walk_stmt, Visitor},
+};
+use rustc_hash::FxHashMap;
+
+use crate::{module_name::ModuleName, resolve_module, Db};
+
+fn exports_cycle_recover(
+    _db: &dyn Db,
+    _value: &[Name],
+    _count: u32,
+    _file: File,
+) -> salsa::CycleRecoveryAction<Box<[Name]>> {
+    salsa::CycleRecoveryAction::Iterate
+}
+
+fn exports_cycle_initial(_db: &dyn Db, _file: File) -> Box<[Name]> {
+    Box::default()
+}
+
+#[salsa::tracked(return_ref, cycle_fn=exports_cycle_recover, cycle_initial=exports_cycle_initial)]
+pub(super) fn exported_names(db: &dyn Db, file: File) -> Box<[Name]> {
+    let module = parsed_module(db.upcast(), file);
+    let mut finder = ExportFinder::new(db, file);
+    finder.visit_body(module.suite());
+    finder.resolve_exports()
+}
+
+struct ExportFinder<'db> {
+    db: &'db dyn Db,
+    file: File,
+    visiting_stub_file: bool,
+    exports: FxHashMap<&'db Name, PossibleExportKind>,
+    dunder_all: DunderAll,
+}
+
+impl<'db> ExportFinder<'db> {
+    fn new(db: &'db dyn Db, file: File) -> Self {
+        Self {
+            db,
+            file,
+            visiting_stub_file: file.is_stub(db.upcast()),
+            exports: FxHashMap::default(),
+            dunder_all: DunderAll::NotPresent,
+        }
+    }
+
+    fn possibly_add_export(&mut self, export: &'db Name, kind: PossibleExportKind) {
+        self.exports.insert(export, kind);
+
+        if export == "__all__" {
+            self.dunder_all = DunderAll::Present;
+        }
+    }
+
+    fn resolve_exports(self) -> Box<[Name]> {
+        match self.dunder_all {
+            DunderAll::NotPresent => self
+                .exports
+                .into_iter()
+                .filter_map(|(name, kind)| {
+                    if kind == PossibleExportKind::StubImportWithoutRedundantAlias {
+                        return None;
+                    }
+                    if name.starts_with('_') {
+                        return None;
+                    }
+                    Some(name.clone())
+                })
+                .collect(),
+            DunderAll::Present => self.exports.into_keys().cloned().collect(),
+        }
+    }
+}
+
+impl<'db> Visitor<'db> for ExportFinder<'db> {
+    fn visit_alias(&mut self, alias: &'db ast::Alias) {
+        let ast::Alias {
+            name,
+            asname,
+            range: _,
+        } = alias;
+
+        let name = &name.id;
+        let asname = asname.as_ref().map(|asname| &asname.id);
+
+        // If the source is a stub, names defined by imports are only exported
+        // if they use the explicit `foo as foo` syntax:
+        let kind = if self.visiting_stub_file && asname.is_none_or(|asname| asname != name) {
+            PossibleExportKind::StubImportWithoutRedundantAlias
+        } else {
+            PossibleExportKind::Normal
+        };
+
+        self.possibly_add_export(asname.unwrap_or(name), kind);
+    }
+
+    fn visit_pattern(&mut self, pattern: &'db ast::Pattern) {
+        match pattern {
+            ast::Pattern::MatchAs(ast::PatternMatchAs {
+                pattern,
+                name,
+                range: _,
+            }) => {
+                if let Some(pattern) = pattern {
+                    self.visit_pattern(pattern);
+                }
+                if let Some(name) = name {
+                    // Wildcard patterns (`case _:`) do not bind names.
+                    // Currently `self.possibly_add_export()` just ignores
+                    // all names with leading underscores, but this will not always be the case
+                    // (in the future we will want to support modules with `__all__ = ['_']`).
+                    if name != "_" {
+                        self.possibly_add_export(&name.id, PossibleExportKind::Normal);
+                    }
+                }
+            }
+            ast::Pattern::MatchMapping(ast::PatternMatchMapping {
+                patterns,
+                rest,
+                keys: _,
+                range: _,
+            }) => {
+                for pattern in patterns {
+                    self.visit_pattern(pattern);
+                }
+                if let Some(rest) = rest {
+                    self.possibly_add_export(&rest.id, PossibleExportKind::Normal);
+                }
+            }
+            ast::Pattern::MatchStar(ast::PatternMatchStar { name, range: _ }) => {
+                if let Some(name) = name {
+                    self.possibly_add_export(&name.id, PossibleExportKind::Normal);
+                }
+            }
+            ast::Pattern::MatchSequence(_)
+            | ast::Pattern::MatchOr(_)
+            | ast::Pattern::MatchClass(_) => {
+                walk_pattern(self, pattern);
+            }
+            ast::Pattern::MatchSingleton(_) | ast::Pattern::MatchValue(_) => {}
+        }
+    }
+
+    fn visit_stmt(&mut self, stmt: &'db ast::Stmt) {
+        match stmt {
+            ast::Stmt::ClassDef(ast::StmtClassDef {
+                name,
+                decorator_list,
+                arguments,
+                type_params: _, // We don't want to visit the type params of the class
+                body: _,        // We don't want to visit the body of the class
+                range: _,
+            }) => {
+                self.possibly_add_export(&name.id, PossibleExportKind::Normal);
+                for decorator in decorator_list {
+                    self.visit_decorator(decorator);
+                }
+                if let Some(arguments) = arguments {
+                    self.visit_arguments(arguments);
+                }
+            }
+
+            ast::Stmt::FunctionDef(ast::StmtFunctionDef {
+                name,
+                decorator_list,
+                parameters,
+                returns,
+                type_params: _, // We don't want to visit the type params of the function
+                body: _,        // We don't want to visit the body of the function
+                range: _,
+                is_async: _,
+            }) => {
+                self.possibly_add_export(&name.id, PossibleExportKind::Normal);
+                for decorator in decorator_list {
+                    self.visit_decorator(decorator);
+                }
+                self.visit_parameters(parameters);
+                if let Some(returns) = returns {
+                    self.visit_expr(returns);
+                }
+            }
+
+            ast::Stmt::AnnAssign(ast::StmtAnnAssign {
+                target,
+                value,
+                annotation,
+                simple: _,
+                range: _,
+            }) => {
+                if value.is_some() || self.visiting_stub_file {
+                    self.visit_expr(target);
+                }
+                self.visit_expr(annotation);
+                if let Some(value) = value {
+                    self.visit_expr(value);
+                }
+            }
+
+            ast::Stmt::TypeAlias(ast::StmtTypeAlias {
+                name,
+                type_params: _,
+                value: _,
+                range: _,
+            }) => {
+                self.visit_expr(name);
+                // Neither walrus expressions nor statements cannot appear in type aliases;
+                // no need to recursively visit the `value` or `type_params`
+            }
+
+            ast::Stmt::ImportFrom(node) => {
+                let mut found_star = false;
+                for name in &node.names {
+                    if &name.name.id == "*" {
+                        if !found_star {
+                            found_star = true;
+                            for export in
+                                ModuleName::from_import_statement(self.db, self.file, node)
+                                    .ok()
+                                    .and_then(|module_name| resolve_module(self.db, &module_name))
+                                    .iter()
+                                    .flat_map(|module| exported_names(self.db, module.file()))
+                            {
+                                self.possibly_add_export(export, PossibleExportKind::Normal);
+                            }
+                        }
+                    } else {
+                        self.visit_alias(name);
+                    }
+                }
+            }
+
+            ast::Stmt::Import(_)
+            | ast::Stmt::AugAssign(_)
+            | ast::Stmt::While(_)
+            | ast::Stmt::If(_)
+            | ast::Stmt::With(_)
+            | ast::Stmt::Assert(_)
+            | ast::Stmt::Try(_)
+            | ast::Stmt::Expr(_)
+            | ast::Stmt::For(_)
+            | ast::Stmt::Assign(_)
+            | ast::Stmt::Match(_) => walk_stmt(self, stmt),
+
+            ast::Stmt::Global(_)
+            | ast::Stmt::Raise(_)
+            | ast::Stmt::Return(_)
+            | ast::Stmt::Break(_)
+            | ast::Stmt::Continue(_)
+            | ast::Stmt::IpyEscapeCommand(_)
+            | ast::Stmt::Delete(_)
+            | ast::Stmt::Nonlocal(_)
+            | ast::Stmt::Pass(_) => {}
+        }
+    }
+
+    fn visit_expr(&mut self, expr: &'db ast::Expr) {
+        match expr {
+            ast::Expr::Name(ast::ExprName { id, ctx, range: _ }) => {
+                if ctx.is_store() {
+                    self.possibly_add_export(id, PossibleExportKind::Normal);
+                }
+            }
+
+            ast::Expr::Lambda(_)
+            | ast::Expr::BooleanLiteral(_)
+            | ast::Expr::NoneLiteral(_)
+            | ast::Expr::NumberLiteral(_)
+            | ast::Expr::BytesLiteral(_)
+            | ast::Expr::EllipsisLiteral(_)
+            | ast::Expr::StringLiteral(_) => {}
+
+            // Walrus definitions "leak" from comprehension scopes into the comprehension's
+            // enclosing scope; they thus need special handling
+            ast::Expr::SetComp(_)
+            | ast::Expr::ListComp(_)
+            | ast::Expr::Generator(_)
+            | ast::Expr::DictComp(_) => {
+                let mut walrus_finder = WalrusFinder {
+                    export_finder: self,
+                };
+                walk_expr(&mut walrus_finder, expr);
+            }
+
+            ast::Expr::BoolOp(_)
+            | ast::Expr::Named(_)
+            | ast::Expr::BinOp(_)
+            | ast::Expr::UnaryOp(_)
+            | ast::Expr::If(_)
+            | ast::Expr::Attribute(_)
+            | ast::Expr::Subscript(_)
+            | ast::Expr::Starred(_)
+            | ast::Expr::Call(_)
+            | ast::Expr::Compare(_)
+            | ast::Expr::Yield(_)
+            | ast::Expr::YieldFrom(_)
+            | ast::Expr::FString(_)
+            | ast::Expr::Tuple(_)
+            | ast::Expr::List(_)
+            | ast::Expr::Slice(_)
+            | ast::Expr::IpyEscapeCommand(_)
+            | ast::Expr::Dict(_)
+            | ast::Expr::Set(_)
+            | ast::Expr::Await(_) => walk_expr(self, expr),
+        }
+    }
+}
+
+struct WalrusFinder<'a, 'db> {
+    export_finder: &'a mut ExportFinder<'db>,
+}
+
+impl<'db> Visitor<'db> for WalrusFinder<'_, 'db> {
+    fn visit_expr(&mut self, expr: &'db ast::Expr) {
+        match expr {
+            // It's important for us to short-circuit here for lambdas specifically,
+            // as walruses cannot leak out of the body of a lambda function.
+            ast::Expr::Lambda(_)
+            | ast::Expr::BooleanLiteral(_)
+            | ast::Expr::NoneLiteral(_)
+            | ast::Expr::NumberLiteral(_)
+            | ast::Expr::BytesLiteral(_)
+            | ast::Expr::EllipsisLiteral(_)
+            | ast::Expr::StringLiteral(_)
+            | ast::Expr::Name(_) => {}
+
+            ast::Expr::Named(ast::ExprNamed {
+                target,
+                value: _,
+                range: _,
+            }) => {
+                if let ast::Expr::Name(ast::ExprName {
+                    id,
+                    ctx: ast::ExprContext::Store,
+                    range: _,
+                }) = &**target
+                {
+                    self.export_finder
+                        .possibly_add_export(id, PossibleExportKind::Normal);
+                }
+            }
+
+            // We must recurse inside nested comprehensions,
+            // as even a walrus inside a comprehension inside a comprehension in the global scope
+            // will leak out into the global scope
+            ast::Expr::DictComp(_)
+            | ast::Expr::SetComp(_)
+            | ast::Expr::ListComp(_)
+            | ast::Expr::Generator(_)
+            | ast::Expr::BoolOp(_)
+            | ast::Expr::BinOp(_)
+            | ast::Expr::UnaryOp(_)
+            | ast::Expr::If(_)
+            | ast::Expr::Attribute(_)
+            | ast::Expr::Subscript(_)
+            | ast::Expr::Starred(_)
+            | ast::Expr::Call(_)
+            | ast::Expr::Compare(_)
+            | ast::Expr::Yield(_)
+            | ast::Expr::YieldFrom(_)
+            | ast::Expr::FString(_)
+            | ast::Expr::Tuple(_)
+            | ast::Expr::List(_)
+            | ast::Expr::Slice(_)
+            | ast::Expr::IpyEscapeCommand(_)
+            | ast::Expr::Dict(_)
+            | ast::Expr::Set(_)
+            | ast::Expr::Await(_) => walk_expr(self, expr),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PossibleExportKind {
+    Normal,
+    StubImportWithoutRedundantAlias,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum DunderAll {
+    NotPresent,
+    Present,
+}

crates/ty_python_semantic/src/semantic_index/symbol.rs

@@ -0,0 +1,576 @@
+use std::hash::{Hash, Hasher};
+use std::ops::Range;
+
+use bitflags::bitflags;
+use hashbrown::hash_map::RawEntryMut;
+use ruff_db::files::File;
+use ruff_db::parsed::ParsedModule;
+use ruff_index::{newtype_index, IndexVec};
+use ruff_python_ast as ast;
+use ruff_python_ast::name::Name;
+use rustc_hash::FxHasher;
+
+use crate::ast_node_ref::AstNodeRef;
+use crate::node_key::NodeKey;
+use crate::semantic_index::visibility_constraints::ScopedVisibilityConstraintId;
+use crate::semantic_index::{semantic_index, SymbolMap};
+use crate::Db;
+
+#[derive(Eq, PartialEq, Debug)]
+pub struct Symbol {
+    name: Name,
+    flags: SymbolFlags,
+}
+
+impl Symbol {
+    fn new(name: Name) -> Self {
+        Self {
+            name,
+            flags: SymbolFlags::empty(),
+        }
+    }
+
+    fn insert_flags(&mut self, flags: SymbolFlags) {
+        self.flags.insert(flags);
+    }
+
+    /// The symbol's name.
+    pub fn name(&self) -> &Name {
+        &self.name
+    }
+
+    /// Is the symbol used in its containing scope?
+    pub fn is_used(&self) -> bool {
+        self.flags.contains(SymbolFlags::IS_USED)
+    }
+
+    /// Is the symbol defined in its containing scope?
+    pub fn is_bound(&self) -> bool {
+        self.flags.contains(SymbolFlags::IS_BOUND)
+    }
+
+    /// Is the symbol declared in its containing scope?
+    pub fn is_declared(&self) -> bool {
+        self.flags.contains(SymbolFlags::IS_DECLARED)
+    }
+}
+
+bitflags! {
+    /// Flags that can be queried to obtain information about a symbol in a given scope.
+    ///
+    /// See the doc-comment at the top of [`super::use_def`] for explanations of what it
+    /// means for a symbol to be *bound* as opposed to *declared*.
+    #[derive(Copy, Clone, Debug, Eq, PartialEq)]
+    struct SymbolFlags: u8 {
+        const IS_USED         = 1 << 0;
+        const IS_BOUND        = 1 << 1;
+        const IS_DECLARED     = 1 << 2;
+        /// TODO: This flag is not yet set by anything
+        const MARKED_GLOBAL   = 1 << 3;
+        /// TODO: This flag is not yet set by anything
+        const MARKED_NONLOCAL = 1 << 4;
+    }
+}
+
+/// ID that uniquely identifies a symbol in a file.
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
+pub struct FileSymbolId {
+    scope: FileScopeId,
+    scoped_symbol_id: ScopedSymbolId,
+}
+
+impl FileSymbolId {
+    pub fn scope(self) -> FileScopeId {
+        self.scope
+    }
+
+    pub(crate) fn scoped_symbol_id(self) -> ScopedSymbolId {
+        self.scoped_symbol_id
+    }
+}
+
+impl From<FileSymbolId> for ScopedSymbolId {
+    fn from(val: FileSymbolId) -> Self {
+        val.scoped_symbol_id()
+    }
+}
+
+/// Symbol ID that uniquely identifies a symbol inside a [`Scope`].
+#[newtype_index]
+#[derive(salsa::Update)]
+pub struct ScopedSymbolId;
+
+/// A cross-module identifier of a scope that can be used as a salsa query parameter.
+#[salsa::tracked(debug)]
+pub struct ScopeId<'db> {
+    pub file: File,
+
+    pub file_scope_id: FileScopeId,
+
+    count: countme::Count<ScopeId<'static>>,
+}
+
+impl<'db> ScopeId<'db> {
+    pub(crate) fn is_function_like(self, db: &'db dyn Db) -> bool {
+        self.node(db).scope_kind().is_function_like()
+    }
+
+    pub(crate) fn is_type_parameter(self, db: &'db dyn Db) -> bool {
+        self.node(db).scope_kind().is_type_parameter()
+    }
+
+    pub(crate) fn node(self, db: &dyn Db) -> &NodeWithScopeKind {
+        self.scope(db).node()
+    }
+
+    pub(crate) fn scope(self, db: &dyn Db) -> &Scope {
+        semantic_index(db, self.file(db)).scope(self.file_scope_id(db))
+    }
+
+    #[cfg(test)]
+    pub(crate) fn name(self, db: &'db dyn Db) -> &'db str {
+        match self.node(db) {
+            NodeWithScopeKind::Module => "<module>",
+            NodeWithScopeKind::Class(class) | NodeWithScopeKind::ClassTypeParameters(class) => {
+                class.name.as_str()
+            }
+            NodeWithScopeKind::Function(function)
+            | NodeWithScopeKind::FunctionTypeParameters(function) => function.name.as_str(),
+            NodeWithScopeKind::TypeAlias(type_alias)
+            | NodeWithScopeKind::TypeAliasTypeParameters(type_alias) => type_alias
+                .name
+                .as_name_expr()
+                .map(|name| name.id.as_str())
+                .unwrap_or("<type alias>"),
+            NodeWithScopeKind::Lambda(_) => "<lambda>",
+            NodeWithScopeKind::ListComprehension(_) => "<listcomp>",
+            NodeWithScopeKind::SetComprehension(_) => "<setcomp>",
+            NodeWithScopeKind::DictComprehension(_) => "<dictcomp>",
+            NodeWithScopeKind::GeneratorExpression(_) => "<generator>",
+        }
+    }
+}
+
+/// ID that uniquely identifies a scope inside of a module.
+#[newtype_index]
+#[derive(salsa::Update)]
+pub struct FileScopeId;
+
+impl FileScopeId {
+    /// Returns the scope id of the module-global scope.
+    pub fn global() -> Self {
+        FileScopeId::from_u32(0)
+    }
+
+    pub fn is_global(self) -> bool {
+        self == FileScopeId::global()
+    }
+
+    pub fn to_scope_id(self, db: &dyn Db, file: File) -> ScopeId<'_> {
+        let index = semantic_index(db, file);
+        index.scope_ids_by_scope[self]
+    }
+}
+
+#[derive(Debug, salsa::Update)]
+pub struct Scope {
+    parent: Option<FileScopeId>,
+    node: NodeWithScopeKind,
+    descendants: Range<FileScopeId>,
+    reachability: ScopedVisibilityConstraintId,
+}
+
+impl Scope {
+    pub(super) fn new(
+        parent: Option<FileScopeId>,
+        node: NodeWithScopeKind,
+        descendants: Range<FileScopeId>,
+        reachability: ScopedVisibilityConstraintId,
+    ) -> Self {
+        Scope {
+            parent,
+            node,
+            descendants,
+            reachability,
+        }
+    }
+
+    pub fn parent(&self) -> Option<FileScopeId> {
+        self.parent
+    }
+
+    pub fn node(&self) -> &NodeWithScopeKind {
+        &self.node
+    }
+
+    pub fn kind(&self) -> ScopeKind {
+        self.node().scope_kind()
+    }
+
+    pub fn descendants(&self) -> Range<FileScopeId> {
+        self.descendants.clone()
+    }
+
+    pub(super) fn extend_descendants(&mut self, children_end: FileScopeId) {
+        self.descendants = self.descendants.start..children_end;
+    }
+
+    pub(crate) fn is_eager(&self) -> bool {
+        self.kind().is_eager()
+    }
+
+    pub(crate) fn reachability(&self) -> ScopedVisibilityConstraintId {
+        self.reachability
+    }
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum ScopeKind {
+    Module,
+    Annotation,
+    Class,
+    Function,
+    Lambda,
+    Comprehension,
+    TypeAlias,
+}
+
+impl ScopeKind {
+    pub(crate) fn is_eager(self) -> bool {
+        match self {
+            ScopeKind::Module | ScopeKind::Class | ScopeKind::Comprehension => true,
+            ScopeKind::Annotation
+            | ScopeKind::Function
+            | ScopeKind::Lambda
+            | ScopeKind::TypeAlias => false,
+        }
+    }
+
+    pub(crate) fn is_function_like(self) -> bool {
+        // Type parameter scopes behave like function scopes in terms of name resolution; CPython
+        // symbol table also uses the term "function-like" for these scopes.
+        matches!(
+            self,
+            ScopeKind::Annotation
+                | ScopeKind::Function
+                | ScopeKind::Lambda
+                | ScopeKind::TypeAlias
+                | ScopeKind::Comprehension
+        )
+    }
+
+    pub(crate) fn is_class(self) -> bool {
+        matches!(self, ScopeKind::Class)
+    }
+
+    pub(crate) fn is_type_parameter(self) -> bool {
+        matches!(self, ScopeKind::Annotation | ScopeKind::TypeAlias)
+    }
+}
+
+/// Symbol table for a specific [`Scope`].
+#[derive(Default, salsa::Update)]
+pub struct SymbolTable {
+    /// The symbols in this scope.
+    symbols: IndexVec<ScopedSymbolId, Symbol>,
+
+    /// The symbols indexed by name.
+    symbols_by_name: SymbolMap,
+}
+
+impl SymbolTable {
+    fn shrink_to_fit(&mut self) {
+        self.symbols.shrink_to_fit();
+    }
+
+    pub(crate) fn symbol(&self, symbol_id: impl Into<ScopedSymbolId>) -> &Symbol {
+        &self.symbols[symbol_id.into()]
+    }
+
+    #[allow(unused)]
+    pub(crate) fn symbol_ids(&self) -> impl Iterator<Item = ScopedSymbolId> {
+        self.symbols.indices()
+    }
+
+    pub fn symbols(&self) -> impl Iterator<Item = &Symbol> {
+        self.symbols.iter()
+    }
+
+    /// Returns the symbol named `name`.
+    pub(crate) fn symbol_by_name(&self, name: &str) -> Option<&Symbol> {
+        let id = self.symbol_id_by_name(name)?;
+        Some(self.symbol(id))
+    }
+
+    /// Returns the [`ScopedSymbolId`] of the symbol named `name`.
+    pub(crate) fn symbol_id_by_name(&self, name: &str) -> Option<ScopedSymbolId> {
+        let (id, ()) = self
+            .symbols_by_name
+            .raw_entry()
+            .from_hash(Self::hash_name(name), |id| {
+                self.symbol(*id).name().as_str() == name
+            })?;
+
+        Some(*id)
+    }
+
+    fn hash_name(name: &str) -> u64 {
+        let mut hasher = FxHasher::default();
+        name.hash(&mut hasher);
+        hasher.finish()
+    }
+}
+
+impl PartialEq for SymbolTable {
+    fn eq(&self, other: &Self) -> bool {
+        // We don't need to compare the symbols_by_name because the name is already captured in `Symbol`.
+        self.symbols == other.symbols
+    }
+}
+
+impl Eq for SymbolTable {}
+
+impl std::fmt::Debug for SymbolTable {
+    /// Exclude the `symbols_by_name` field from the debug output.
+    /// It's very noisy and not useful for debugging.
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_tuple("SymbolTable")
+            .field(&self.symbols)
+            .finish_non_exhaustive()
+    }
+}
+
+#[derive(Debug, Default)]
+pub(super) struct SymbolTableBuilder {
+    table: SymbolTable,
+}
+
+impl SymbolTableBuilder {
+    pub(super) fn add_symbol(&mut self, name: Name) -> (ScopedSymbolId, bool) {
+        let hash = SymbolTable::hash_name(&name);
+        let entry = self
+            .table
+            .symbols_by_name
+            .raw_entry_mut()
+            .from_hash(hash, |id| self.table.symbols[*id].name() == &name);
+
+        match entry {
+            RawEntryMut::Occupied(entry) => (*entry.key(), false),
+            RawEntryMut::Vacant(entry) => {
+                let symbol = Symbol::new(name);
+
+                let id = self.table.symbols.push(symbol);
+                entry.insert_with_hasher(hash, id, (), |id| {
+                    SymbolTable::hash_name(self.table.symbols[*id].name().as_str())
+                });
+                (id, true)
+            }
+        }
+    }
+
+    pub(super) fn mark_symbol_bound(&mut self, id: ScopedSymbolId) {
+        self.table.symbols[id].insert_flags(SymbolFlags::IS_BOUND);
+    }
+
+    pub(super) fn mark_symbol_declared(&mut self, id: ScopedSymbolId) {
+        self.table.symbols[id].insert_flags(SymbolFlags::IS_DECLARED);
+    }
+
+    pub(super) fn mark_symbol_used(&mut self, id: ScopedSymbolId) {
+        self.table.symbols[id].insert_flags(SymbolFlags::IS_USED);
+    }
+
+    pub(super) fn symbols(&self) -> impl Iterator<Item = &Symbol> {
+        self.table.symbols()
+    }
+
+    pub(super) fn symbol_id_by_name(&self, name: &str) -> Option<ScopedSymbolId> {
+        self.table.symbol_id_by_name(name)
+    }
+
+    pub(super) fn symbol(&self, symbol_id: impl Into<ScopedSymbolId>) -> &Symbol {
+        self.table.symbol(symbol_id)
+    }
+
+    pub(super) fn finish(mut self) -> SymbolTable {
+        self.table.shrink_to_fit();
+        self.table
+    }
+}
+
+/// Reference to a node that introduces a new scope.
+#[derive(Copy, Clone, Debug)]
+pub(crate) enum NodeWithScopeRef<'a> {
+    Module,
+    Class(&'a ast::StmtClassDef),
+    Function(&'a ast::StmtFunctionDef),
+    Lambda(&'a ast::ExprLambda),
+    FunctionTypeParameters(&'a ast::StmtFunctionDef),
+    ClassTypeParameters(&'a ast::StmtClassDef),
+    TypeAlias(&'a ast::StmtTypeAlias),
+    TypeAliasTypeParameters(&'a ast::StmtTypeAlias),
+    ListComprehension(&'a ast::ExprListComp),
+    SetComprehension(&'a ast::ExprSetComp),
+    DictComprehension(&'a ast::ExprDictComp),
+    GeneratorExpression(&'a ast::ExprGenerator),
+}
+
+impl NodeWithScopeRef<'_> {
+    /// Converts the unowned reference to an owned [`NodeWithScopeKind`].
+    ///
+    /// # Safety
+    /// The node wrapped by `self` must be a child of `module`.
+    #[allow(unsafe_code)]
+    pub(super) unsafe fn to_kind(self, module: ParsedModule) -> NodeWithScopeKind {
+        match self {
+            NodeWithScopeRef::Module => NodeWithScopeKind::Module,
+            NodeWithScopeRef::Class(class) => {
+                NodeWithScopeKind::Class(AstNodeRef::new(module, class))
+            }
+            NodeWithScopeRef::Function(function) => {
+                NodeWithScopeKind::Function(AstNodeRef::new(module, function))
+            }
+            NodeWithScopeRef::TypeAlias(type_alias) => {
+                NodeWithScopeKind::TypeAlias(AstNodeRef::new(module, type_alias))
+            }
+            NodeWithScopeRef::TypeAliasTypeParameters(type_alias) => {
+                NodeWithScopeKind::TypeAliasTypeParameters(AstNodeRef::new(module, type_alias))
+            }
+            NodeWithScopeRef::Lambda(lambda) => {
+                NodeWithScopeKind::Lambda(AstNodeRef::new(module, lambda))
+            }
+            NodeWithScopeRef::FunctionTypeParameters(function) => {
+                NodeWithScopeKind::FunctionTypeParameters(AstNodeRef::new(module, function))
+            }
+            NodeWithScopeRef::ClassTypeParameters(class) => {
+                NodeWithScopeKind::ClassTypeParameters(AstNodeRef::new(module, class))
+            }
+            NodeWithScopeRef::ListComprehension(comprehension) => {
+                NodeWithScopeKind::ListComprehension(AstNodeRef::new(module, comprehension))
+            }
+            NodeWithScopeRef::SetComprehension(comprehension) => {
+                NodeWithScopeKind::SetComprehension(AstNodeRef::new(module, comprehension))
+            }
+            NodeWithScopeRef::DictComprehension(comprehension) => {
+                NodeWithScopeKind::DictComprehension(AstNodeRef::new(module, comprehension))
+            }
+            NodeWithScopeRef::GeneratorExpression(generator) => {
+                NodeWithScopeKind::GeneratorExpression(AstNodeRef::new(module, generator))
+            }
+        }
+    }
+
+    pub(crate) fn node_key(self) -> NodeWithScopeKey {
+        match self {
+            NodeWithScopeRef::Module => NodeWithScopeKey::Module,
+            NodeWithScopeRef::Class(class) => NodeWithScopeKey::Class(NodeKey::from_node(class)),
+            NodeWithScopeRef::Function(function) => {
+                NodeWithScopeKey::Function(NodeKey::from_node(function))
+            }
+            NodeWithScopeRef::Lambda(lambda) => {
+                NodeWithScopeKey::Lambda(NodeKey::from_node(lambda))
+            }
+            NodeWithScopeRef::FunctionTypeParameters(function) => {
+                NodeWithScopeKey::FunctionTypeParameters(NodeKey::from_node(function))
+            }
+            NodeWithScopeRef::ClassTypeParameters(class) => {
+                NodeWithScopeKey::ClassTypeParameters(NodeKey::from_node(class))
+            }
+            NodeWithScopeRef::TypeAlias(type_alias) => {
+                NodeWithScopeKey::TypeAlias(NodeKey::from_node(type_alias))
+            }
+            NodeWithScopeRef::TypeAliasTypeParameters(type_alias) => {
+                NodeWithScopeKey::TypeAliasTypeParameters(NodeKey::from_node(type_alias))
+            }
+            NodeWithScopeRef::ListComprehension(comprehension) => {
+                NodeWithScopeKey::ListComprehension(NodeKey::from_node(comprehension))
+            }
+            NodeWithScopeRef::SetComprehension(comprehension) => {
+                NodeWithScopeKey::SetComprehension(NodeKey::from_node(comprehension))
+            }
+            NodeWithScopeRef::DictComprehension(comprehension) => {
+                NodeWithScopeKey::DictComprehension(NodeKey::from_node(comprehension))
+            }
+            NodeWithScopeRef::GeneratorExpression(generator) => {
+                NodeWithScopeKey::GeneratorExpression(NodeKey::from_node(generator))
+            }
+        }
+    }
+}
+
+/// Node that introduces a new scope.
+#[derive(Clone, Debug, salsa::Update)]
+pub enum NodeWithScopeKind {
+    Module,
+    Class(AstNodeRef<ast::StmtClassDef>),
+    ClassTypeParameters(AstNodeRef<ast::StmtClassDef>),
+    Function(AstNodeRef<ast::StmtFunctionDef>),
+    FunctionTypeParameters(AstNodeRef<ast::StmtFunctionDef>),
+    TypeAliasTypeParameters(AstNodeRef<ast::StmtTypeAlias>),
+    TypeAlias(AstNodeRef<ast::StmtTypeAlias>),
+    Lambda(AstNodeRef<ast::ExprLambda>),
+    ListComprehension(AstNodeRef<ast::ExprListComp>),
+    SetComprehension(AstNodeRef<ast::ExprSetComp>),
+    DictComprehension(AstNodeRef<ast::ExprDictComp>),
+    GeneratorExpression(AstNodeRef<ast::ExprGenerator>),
+}
+
+impl NodeWithScopeKind {
+    pub(crate) const fn scope_kind(&self) -> ScopeKind {
+        match self {
+            Self::Module => ScopeKind::Module,
+            Self::Class(_) => ScopeKind::Class,
+            Self::Function(_) => ScopeKind::Function,
+            Self::Lambda(_) => ScopeKind::Lambda,
+            Self::FunctionTypeParameters(_)
+            | Self::ClassTypeParameters(_)
+            | Self::TypeAliasTypeParameters(_) => ScopeKind::Annotation,
+            Self::TypeAlias(_) => ScopeKind::TypeAlias,
+            Self::ListComprehension(_)
+            | Self::SetComprehension(_)
+            | Self::DictComprehension(_)
+            | Self::GeneratorExpression(_) => ScopeKind::Comprehension,
+        }
+    }
+
+    pub fn expect_class(&self) -> &ast::StmtClassDef {
+        match self {
+            Self::Class(class) => class.node(),
+            _ => panic!("expected class"),
+        }
+    }
+
+    pub fn expect_function(&self) -> &ast::StmtFunctionDef {
+        self.as_function().expect("expected function")
+    }
+
+    pub fn expect_type_alias(&self) -> &ast::StmtTypeAlias {
+        match self {
+            Self::TypeAlias(type_alias) => type_alias.node(),
+            _ => panic!("expected type alias"),
+        }
+    }
+
+    pub const fn as_function(&self) -> Option<&ast::StmtFunctionDef> {
+        match self {
+            Self::Function(function) => Some(function.node()),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
+pub(crate) enum NodeWithScopeKey {
+    Module,
+    Class(NodeKey),
+    ClassTypeParameters(NodeKey),
+    Function(NodeKey),
+    FunctionTypeParameters(NodeKey),
+    TypeAlias(NodeKey),
+    TypeAliasTypeParameters(NodeKey),
+    Lambda(NodeKey),
+    ListComprehension(NodeKey),
+    SetComprehension(NodeKey),
+    DictComprehension(NodeKey),
+    GeneratorExpression(NodeKey),
+}

crates/ty_python_semantic/src/semantic_index/use_def/symbol_state.rs

@@ -0,0 +1,633 @@
+//! Track live bindings per symbol, applicable constraints per binding, and live declarations.
+//!
+//! These data structures operate entirely on scope-local newtype-indices for definitions and
+//! constraints, referring to their location in the `all_definitions` and `all_constraints`
+//! indexvecs in [`super::UseDefMapBuilder`].
+//!
+//! We need to track arbitrary associations between bindings and constraints, not just a single set
+//! of currently dominating constraints (where "dominating" means "control flow must have passed
+//! through it to reach this point"), because we can have dominating constraints that apply to some
+//! bindings but not others, as in this code:
+//!
+//! ```python
+//! x = 1 if flag else None
+//! if x is not None:
+//!     if flag2:
+//!         x = 2 if flag else None
+//!     x
+//! ```
+//!
+//! The `x is not None` constraint dominates the final use of `x`, but it applies only to the first
+//! binding of `x`, not the second, so `None` is a possible value for `x`.
+//!
+//! And we can't just track, for each binding, an index into a list of dominating constraints,
+//! either, because we can have bindings which are still visible, but subject to constraints that
+//! are no longer dominating, as in this code:
+//!
+//! ```python
+//! x = 0
+//! if flag1:
+//!     x = 1 if flag2 else None
+//!     assert x is not None
+//! x
+//! ```
+//!
+//! From the point of view of the final use of `x`, the `x is not None` constraint no longer
+//! dominates, but it does dominate the `x = 1 if flag2 else None` binding, so we have to keep
+//! track of that.
+//!
+//! The data structures use `IndexVec` arenas to store all data compactly and contiguously, while
+//! supporting very cheap clones.
+//!
+//! Tracking live declarations is simpler, since constraints are not involved, but otherwise very
+//! similar to tracking live bindings.
+
+use itertools::{EitherOrBoth, Itertools};
+use ruff_index::newtype_index;
+use smallvec::{smallvec, SmallVec};
+
+use crate::semantic_index::narrowing_constraints::{
+    NarrowingConstraintsBuilder, ScopedNarrowingConstraint, ScopedNarrowingConstraintPredicate,
+};
+use crate::semantic_index::visibility_constraints::{
+    ScopedVisibilityConstraintId, VisibilityConstraintsBuilder,
+};
+
+/// A newtype-index for a definition in a particular scope.
+#[newtype_index]
+#[derive(Ord, PartialOrd)]
+pub(super) struct ScopedDefinitionId;
+
+impl ScopedDefinitionId {
+    /// A special ID that is used to describe an implicit start-of-scope state. When
+    /// we see that this definition is live, we know that the symbol is (possibly)
+    /// unbound or undeclared at a given usage site.
+    /// When creating a use-def-map builder, we always add an empty `None` definition
+    /// at index 0, so this ID is always present.
+    pub(super) const UNBOUND: ScopedDefinitionId = ScopedDefinitionId::from_u32(0);
+}
+
+/// Can keep inline this many live bindings or declarations per symbol at a given time; more will
+/// go to heap.
+const INLINE_DEFINITIONS_PER_SYMBOL: usize = 4;
+
+/// Live declarations for a single symbol at some point in control flow, with their
+/// corresponding visibility constraints.
+#[derive(Clone, Debug, Default, PartialEq, Eq, salsa::Update)]
+pub(super) struct SymbolDeclarations {
+    /// A list of live declarations for this symbol, sorted by their `ScopedDefinitionId`
+    live_declarations: SmallVec<[LiveDeclaration; INLINE_DEFINITIONS_PER_SYMBOL]>,
+}
+
+/// One of the live declarations for a single symbol at some point in control flow.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct LiveDeclaration {
+    pub(super) declaration: ScopedDefinitionId,
+    pub(super) visibility_constraint: ScopedVisibilityConstraintId,
+}
+
+pub(super) type LiveDeclarationsIterator<'a> = std::slice::Iter<'a, LiveDeclaration>;
+
+impl SymbolDeclarations {
+    fn undeclared(scope_start_visibility: ScopedVisibilityConstraintId) -> Self {
+        let initial_declaration = LiveDeclaration {
+            declaration: ScopedDefinitionId::UNBOUND,
+            visibility_constraint: scope_start_visibility,
+        };
+        Self {
+            live_declarations: smallvec![initial_declaration],
+        }
+    }
+
+    /// Record a newly-encountered declaration for this symbol.
+    fn record_declaration(&mut self, declaration: ScopedDefinitionId) {
+        // The new declaration replaces all previous live declaration in this path.
+        self.live_declarations.clear();
+        self.live_declarations.push(LiveDeclaration {
+            declaration,
+            visibility_constraint: ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        });
+    }
+
+    /// Add given visibility constraint to all live declarations.
+    pub(super) fn record_visibility_constraint(
+        &mut self,
+        visibility_constraints: &mut VisibilityConstraintsBuilder,
+        constraint: ScopedVisibilityConstraintId,
+    ) {
+        for declaration in &mut self.live_declarations {
+            declaration.visibility_constraint = visibility_constraints
+                .add_and_constraint(declaration.visibility_constraint, constraint);
+        }
+    }
+
+    /// Return an iterator over live declarations for this symbol.
+    pub(super) fn iter(&self) -> LiveDeclarationsIterator<'_> {
+        self.live_declarations.iter()
+    }
+
+    /// Iterate over the IDs of each currently live declaration for this symbol
+    fn iter_declarations(&self) -> impl Iterator<Item = ScopedDefinitionId> + '_ {
+        self.iter().map(|lb| lb.declaration)
+    }
+
+    fn simplify_visibility_constraints(&mut self, other: SymbolDeclarations) {
+        // If the set of live declarations hasn't changed, don't simplify.
+        if self.live_declarations.len() != other.live_declarations.len()
+            || !self.iter_declarations().eq(other.iter_declarations())
+        {
+            return;
+        }
+
+        for (declaration, other_declaration) in self
+            .live_declarations
+            .iter_mut()
+            .zip(other.live_declarations)
+        {
+            declaration.visibility_constraint = other_declaration.visibility_constraint;
+        }
+    }
+
+    fn merge(&mut self, b: Self, visibility_constraints: &mut VisibilityConstraintsBuilder) {
+        let a = std::mem::take(self);
+
+        // Invariant: merge_join_by consumes the two iterators in sorted order, which ensures that
+        // the merged `live_declarations` vec remains sorted. If a definition is found in both `a`
+        // and `b`, we compose the constraints from the two paths in an appropriate way
+        // (intersection for narrowing constraints; ternary OR for visibility constraints). If a
+        // definition is found in only one path, it is used as-is.
+        let a = a.live_declarations.into_iter();
+        let b = b.live_declarations.into_iter();
+        for zipped in a.merge_join_by(b, |a, b| a.declaration.cmp(&b.declaration)) {
+            match zipped {
+                EitherOrBoth::Both(a, b) => {
+                    let visibility_constraint = visibility_constraints
+                        .add_or_constraint(a.visibility_constraint, b.visibility_constraint);
+                    self.live_declarations.push(LiveDeclaration {
+                        declaration: a.declaration,
+                        visibility_constraint,
+                    });
+                }
+
+                EitherOrBoth::Left(declaration) | EitherOrBoth::Right(declaration) => {
+                    self.live_declarations.push(declaration);
+                }
+            }
+        }
+    }
+}
+
+/// Live bindings for a single symbol at some point in control flow. Each live binding comes
+/// with a set of narrowing constraints and a visibility constraint.
+#[derive(Clone, Debug, Default, PartialEq, Eq, salsa::Update)]
+pub(super) struct SymbolBindings {
+    /// A list of live bindings for this symbol, sorted by their `ScopedDefinitionId`
+    live_bindings: SmallVec<[LiveBinding; INLINE_DEFINITIONS_PER_SYMBOL]>,
+}
+
+/// One of the live bindings for a single symbol at some point in control flow.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct LiveBinding {
+    pub(super) binding: ScopedDefinitionId,
+    pub(super) narrowing_constraint: ScopedNarrowingConstraint,
+    pub(super) visibility_constraint: ScopedVisibilityConstraintId,
+}
+
+pub(super) type LiveBindingsIterator<'a> = std::slice::Iter<'a, LiveBinding>;
+
+impl SymbolBindings {
+    fn unbound(scope_start_visibility: ScopedVisibilityConstraintId) -> Self {
+        let initial_binding = LiveBinding {
+            binding: ScopedDefinitionId::UNBOUND,
+            narrowing_constraint: ScopedNarrowingConstraint::empty(),
+            visibility_constraint: scope_start_visibility,
+        };
+        Self {
+            live_bindings: smallvec![initial_binding],
+        }
+    }
+
+    /// Record a newly-encountered binding for this symbol.
+    pub(super) fn record_binding(
+        &mut self,
+        binding: ScopedDefinitionId,
+        visibility_constraint: ScopedVisibilityConstraintId,
+    ) {
+        // The new binding replaces all previous live bindings in this path, and has no
+        // constraints.
+        self.live_bindings.clear();
+        self.live_bindings.push(LiveBinding {
+            binding,
+            narrowing_constraint: ScopedNarrowingConstraint::empty(),
+            visibility_constraint,
+        });
+    }
+
+    /// Add given constraint to all live bindings.
+    pub(super) fn record_narrowing_constraint(
+        &mut self,
+        narrowing_constraints: &mut NarrowingConstraintsBuilder,
+        predicate: ScopedNarrowingConstraintPredicate,
+    ) {
+        for binding in &mut self.live_bindings {
+            binding.narrowing_constraint = narrowing_constraints
+                .add_predicate_to_constraint(binding.narrowing_constraint, predicate);
+        }
+    }
+
+    /// Add given visibility constraint to all live bindings.
+    pub(super) fn record_visibility_constraint(
+        &mut self,
+        visibility_constraints: &mut VisibilityConstraintsBuilder,
+        constraint: ScopedVisibilityConstraintId,
+    ) {
+        for binding in &mut self.live_bindings {
+            binding.visibility_constraint = visibility_constraints
+                .add_and_constraint(binding.visibility_constraint, constraint);
+        }
+    }
+
+    /// Iterate over currently live bindings for this symbol
+    pub(super) fn iter(&self) -> LiveBindingsIterator<'_> {
+        self.live_bindings.iter()
+    }
+
+    /// Iterate over the IDs of each currently live binding for this symbol
+    fn iter_bindings(&self) -> impl Iterator<Item = ScopedDefinitionId> + '_ {
+        self.iter().map(|lb| lb.binding)
+    }
+
+    fn simplify_visibility_constraints(&mut self, other: SymbolBindings) {
+        // If the set of live bindings hasn't changed, don't simplify.
+        if self.live_bindings.len() != other.live_bindings.len()
+            || !self.iter_bindings().eq(other.iter_bindings())
+        {
+            return;
+        }
+
+        for (binding, other_binding) in self.live_bindings.iter_mut().zip(other.live_bindings) {
+            binding.visibility_constraint = other_binding.visibility_constraint;
+        }
+    }
+
+    fn merge(
+        &mut self,
+        b: Self,
+        narrowing_constraints: &mut NarrowingConstraintsBuilder,
+        visibility_constraints: &mut VisibilityConstraintsBuilder,
+    ) {
+        let a = std::mem::take(self);
+
+        // Invariant: merge_join_by consumes the two iterators in sorted order, which ensures that
+        // the merged `live_bindings` vec remains sorted. If a definition is found in both `a` and
+        // `b`, we compose the constraints from the two paths in an appropriate way (intersection
+        // for narrowing constraints; ternary OR for visibility constraints). If a definition is
+        // found in only one path, it is used as-is.
+        let a = a.live_bindings.into_iter();
+        let b = b.live_bindings.into_iter();
+        for zipped in a.merge_join_by(b, |a, b| a.binding.cmp(&b.binding)) {
+            match zipped {
+                EitherOrBoth::Both(a, b) => {
+                    // If the same definition is visible through both paths, any constraint
+                    // that applies on only one path is irrelevant to the resulting type from
+                    // unioning the two paths, so we intersect the constraints.
+                    let narrowing_constraint = narrowing_constraints
+                        .intersect_constraints(a.narrowing_constraint, b.narrowing_constraint);
+
+                    // For visibility constraints, we merge them using a ternary OR operation:
+                    let visibility_constraint = visibility_constraints
+                        .add_or_constraint(a.visibility_constraint, b.visibility_constraint);
+
+                    self.live_bindings.push(LiveBinding {
+                        binding: a.binding,
+                        narrowing_constraint,
+                        visibility_constraint,
+                    });
+                }
+
+                EitherOrBoth::Left(binding) | EitherOrBoth::Right(binding) => {
+                    self.live_bindings.push(binding);
+                }
+            }
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(in crate::semantic_index) struct SymbolState {
+    declarations: SymbolDeclarations,
+    bindings: SymbolBindings,
+}
+
+impl SymbolState {
+    /// Return a new [`SymbolState`] representing an unbound, undeclared symbol.
+    pub(super) fn undefined(scope_start_visibility: ScopedVisibilityConstraintId) -> Self {
+        Self {
+            declarations: SymbolDeclarations::undeclared(scope_start_visibility),
+            bindings: SymbolBindings::unbound(scope_start_visibility),
+        }
+    }
+
+    /// Record a newly-encountered binding for this symbol.
+    pub(super) fn record_binding(
+        &mut self,
+        binding_id: ScopedDefinitionId,
+        visibility_constraint: ScopedVisibilityConstraintId,
+    ) {
+        debug_assert_ne!(binding_id, ScopedDefinitionId::UNBOUND);
+        self.bindings
+            .record_binding(binding_id, visibility_constraint);
+    }
+
+    /// Add given constraint to all live bindings.
+    pub(super) fn record_narrowing_constraint(
+        &mut self,
+        narrowing_constraints: &mut NarrowingConstraintsBuilder,
+        constraint: ScopedNarrowingConstraintPredicate,
+    ) {
+        self.bindings
+            .record_narrowing_constraint(narrowing_constraints, constraint);
+    }
+
+    /// Add given visibility constraint to all live bindings.
+    pub(super) fn record_visibility_constraint(
+        &mut self,
+        visibility_constraints: &mut VisibilityConstraintsBuilder,
+        constraint: ScopedVisibilityConstraintId,
+    ) {
+        self.bindings
+            .record_visibility_constraint(visibility_constraints, constraint);
+        self.declarations
+            .record_visibility_constraint(visibility_constraints, constraint);
+    }
+
+    /// Simplifies this snapshot to have the same visibility constraints as a previous point in the
+    /// control flow, but only if the set of live bindings or declarations for this symbol hasn't
+    /// changed.
+    pub(super) fn simplify_visibility_constraints(&mut self, snapshot_state: SymbolState) {
+        self.bindings
+            .simplify_visibility_constraints(snapshot_state.bindings);
+        self.declarations
+            .simplify_visibility_constraints(snapshot_state.declarations);
+    }
+
+    /// Record a newly-encountered declaration of this symbol.
+    pub(super) fn record_declaration(&mut self, declaration_id: ScopedDefinitionId) {
+        self.declarations.record_declaration(declaration_id);
+    }
+
+    /// Merge another [`SymbolState`] into this one.
+    pub(super) fn merge(
+        &mut self,
+        b: SymbolState,
+        narrowing_constraints: &mut NarrowingConstraintsBuilder,
+        visibility_constraints: &mut VisibilityConstraintsBuilder,
+    ) {
+        self.bindings
+            .merge(b.bindings, narrowing_constraints, visibility_constraints);
+        self.declarations
+            .merge(b.declarations, visibility_constraints);
+    }
+
+    pub(super) fn bindings(&self) -> &SymbolBindings {
+        &self.bindings
+    }
+
+    pub(super) fn declarations(&self) -> &SymbolDeclarations {
+        &self.declarations
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::semantic_index::predicate::ScopedPredicateId;
+
+    #[track_caller]
+    fn assert_bindings(
+        narrowing_constraints: &NarrowingConstraintsBuilder,
+        symbol: &SymbolState,
+        expected: &[&str],
+    ) {
+        let actual = symbol
+            .bindings()
+            .iter()
+            .map(|live_binding| {
+                let def_id = live_binding.binding;
+                let def = if def_id == ScopedDefinitionId::UNBOUND {
+                    "unbound".into()
+                } else {
+                    def_id.as_u32().to_string()
+                };
+                let predicates = narrowing_constraints
+                    .iter_predicates(live_binding.narrowing_constraint)
+                    .map(|idx| idx.as_u32().to_string())
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                format!("{def}<{predicates}>")
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(actual, expected);
+    }
+
+    #[track_caller]
+    pub(crate) fn assert_declarations(symbol: &SymbolState, expected: &[&str]) {
+        let actual = symbol
+            .declarations()
+            .iter()
+            .map(
+                |LiveDeclaration {
+                     declaration,
+                     visibility_constraint: _,
+                 }| {
+                    if *declaration == ScopedDefinitionId::UNBOUND {
+                        "undeclared".into()
+                    } else {
+                        declaration.as_u32().to_string()
+                    }
+                },
+            )
+            .collect::<Vec<_>>();
+        assert_eq!(actual, expected);
+    }
+
+    #[test]
+    fn unbound() {
+        let narrowing_constraints = NarrowingConstraintsBuilder::default();
+        let sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+
+        assert_bindings(&narrowing_constraints, &sym, &["unbound<>"]);
+    }
+
+    #[test]
+    fn with() {
+        let narrowing_constraints = NarrowingConstraintsBuilder::default();
+        let mut sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym.record_binding(
+            ScopedDefinitionId::from_u32(1),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+
+        assert_bindings(&narrowing_constraints, &sym, &["1<>"]);
+    }
+
+    #[test]
+    fn record_constraint() {
+        let mut narrowing_constraints = NarrowingConstraintsBuilder::default();
+        let mut sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym.record_binding(
+            ScopedDefinitionId::from_u32(1),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+        let predicate = ScopedPredicateId::from_u32(0).into();
+        sym.record_narrowing_constraint(&mut narrowing_constraints, predicate);
+
+        assert_bindings(&narrowing_constraints, &sym, &["1<0>"]);
+    }
+
+    #[test]
+    fn merge() {
+        let mut narrowing_constraints = NarrowingConstraintsBuilder::default();
+        let mut visibility_constraints = VisibilityConstraintsBuilder::default();
+
+        // merging the same definition with the same constraint keeps the constraint
+        let mut sym1a = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym1a.record_binding(
+            ScopedDefinitionId::from_u32(1),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+        let predicate = ScopedPredicateId::from_u32(0).into();
+        sym1a.record_narrowing_constraint(&mut narrowing_constraints, predicate);
+
+        let mut sym1b = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym1b.record_binding(
+            ScopedDefinitionId::from_u32(1),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+        let predicate = ScopedPredicateId::from_u32(0).into();
+        sym1b.record_narrowing_constraint(&mut narrowing_constraints, predicate);
+
+        sym1a.merge(
+            sym1b,
+            &mut narrowing_constraints,
+            &mut visibility_constraints,
+        );
+        let mut sym1 = sym1a;
+        assert_bindings(&narrowing_constraints, &sym1, &["1<0>"]);
+
+        // merging the same definition with differing constraints drops all constraints
+        let mut sym2a = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym2a.record_binding(
+            ScopedDefinitionId::from_u32(2),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+        let predicate = ScopedPredicateId::from_u32(1).into();
+        sym2a.record_narrowing_constraint(&mut narrowing_constraints, predicate);
+
+        let mut sym1b = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym1b.record_binding(
+            ScopedDefinitionId::from_u32(2),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+        let predicate = ScopedPredicateId::from_u32(2).into();
+        sym1b.record_narrowing_constraint(&mut narrowing_constraints, predicate);
+
+        sym2a.merge(
+            sym1b,
+            &mut narrowing_constraints,
+            &mut visibility_constraints,
+        );
+        let sym2 = sym2a;
+        assert_bindings(&narrowing_constraints, &sym2, &["2<>"]);
+
+        // merging a constrained definition with unbound keeps both
+        let mut sym3a = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym3a.record_binding(
+            ScopedDefinitionId::from_u32(3),
+            ScopedVisibilityConstraintId::ALWAYS_TRUE,
+        );
+        let predicate = ScopedPredicateId::from_u32(3).into();
+        sym3a.record_narrowing_constraint(&mut narrowing_constraints, predicate);
+
+        let sym2b = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+
+        sym3a.merge(
+            sym2b,
+            &mut narrowing_constraints,
+            &mut visibility_constraints,
+        );
+        let sym3 = sym3a;
+        assert_bindings(&narrowing_constraints, &sym3, &["unbound<>", "3<3>"]);
+
+        // merging different definitions keeps them each with their existing constraints
+        sym1.merge(
+            sym3,
+            &mut narrowing_constraints,
+            &mut visibility_constraints,
+        );
+        let sym = sym1;
+        assert_bindings(&narrowing_constraints, &sym, &["unbound<>", "1<0>", "3<3>"]);
+    }
+
+    #[test]
+    fn no_declaration() {
+        let sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+
+        assert_declarations(&sym, &["undeclared"]);
+    }
+
+    #[test]
+    fn record_declaration() {
+        let mut sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+
+        assert_declarations(&sym, &["1"]);
+    }
+
+    #[test]
+    fn record_declaration_override() {
+        let mut sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+        sym.record_declaration(ScopedDefinitionId::from_u32(2));
+
+        assert_declarations(&sym, &["2"]);
+    }
+
+    #[test]
+    fn record_declaration_merge() {
+        let mut narrowing_constraints = NarrowingConstraintsBuilder::default();
+        let mut visibility_constraints = VisibilityConstraintsBuilder::default();
+        let mut sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+
+        let mut sym2 = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym2.record_declaration(ScopedDefinitionId::from_u32(2));
+
+        sym.merge(
+            sym2,
+            &mut narrowing_constraints,
+            &mut visibility_constraints,
+        );
+
+        assert_declarations(&sym, &["1", "2"]);
+    }
+
+    #[test]
+    fn record_declaration_merge_partial_undeclared() {
+        let mut narrowing_constraints = NarrowingConstraintsBuilder::default();
+        let mut visibility_constraints = VisibilityConstraintsBuilder::default();
+        let mut sym = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+        sym.record_declaration(ScopedDefinitionId::from_u32(1));
+
+        let sym2 = SymbolState::undefined(ScopedVisibilityConstraintId::ALWAYS_TRUE);
+
+        sym.merge(
+            sym2,
+            &mut narrowing_constraints,
+            &mut visibility_constraints,
+        );
+
+        assert_declarations(&sym, &["undeclared", "1"]);
+    }
+}

crates/ty_python_semantic/src/semantic_index/visibility_constraints.rs

@@ -0,0 +1,670 @@
+//! # Visibility constraints
+//!
+//! During semantic index building, we collect visibility constraints for each binding and
+//! declaration. These constraints are then used during type-checking to determine the static
+//! visibility of a certain definition. This allows us to re-analyze control flow during type
+//! checking, potentially "hiding" some branches that we can statically determine to never be
+//! taken. Consider the following example first. We added implicit "unbound" definitions at the
+//! start of the scope. Note how visibility constraints can apply to bindings outside of the
+//! if-statement:
+//! ```py
+//! x = <unbound>  # not a live binding for the use of x below, shadowed by `x = 1`
+//! y = <unbound>  # visibility constraint: ~test
+//!
+//! x = 1  # visibility constraint: ~test
+//! if test:
+//!     x = 2  # visibility constraint: test
+//!
+//!     y = 2  # visibility constraint: test
+//!
+//! use(x)
+//! use(y)
+//! ```
+//! The static truthiness of the `test` condition can either be always-false, ambiguous, or
+//! always-true. Similarly, we have the same three options when evaluating a visibility constraint.
+//! This outcome determines the visibility of a definition: always-true means that the definition
+//! is definitely visible for a given use, always-false means that the definition is definitely
+//! not visible, and ambiguous means that we might see this definition or not. In the latter case,
+//! we need to consider both options during type inference and boundness analysis. For the example
+//! above, these are the possible type inference / boundness results for the uses of `x` and `y`:
+//!
+//! ```text
+//!       | `test` truthiness | `~test` truthiness | type of `x`     | boundness of `y` |
+//!       |-------------------|--------------------|-----------------|------------------|
+//!       | always false      | always true        | `Literal[1]`    | unbound          |
+//!       | ambiguous         | ambiguous          | `Literal[1, 2]` | possibly unbound |
+//!       | always true       | always false       | `Literal[2]`    | bound            |
+//! ```
+//!
+//! ### Sequential constraints (ternary AND)
+//!
+//! As we have seen above, visibility constraints can apply outside of a control flow element.
+//! So we need to consider the possibility that multiple constraints apply to the same binding.
+//! Here, we consider what happens if multiple `if`-statements lead to a sequence of constraints.
+//! Consider the following example:
+//! ```py
+//! x = 0
+//!
+//! if test1:
+//!     x = 1
+//!
+//! if test2:
+//!     x = 2
+//! ```
+//! The binding `x = 2` is easy to analyze. Its visibility corresponds to the truthiness of `test2`.
+//! For the `x = 1` binding, things are a bit more interesting. It is always visible if `test1` is
+//! always-true *and* `test2` is always-false. It is never visible if `test1` is always-false *or*
+//! `test2` is always-true. And it is ambiguous otherwise. This corresponds to a ternary *test1 AND
+//! ~test2* operation in three-valued Kleene logic [Kleene]:
+//!
+//! ```text
+//!       | AND          | always-false | ambiguous    | always-true  |
+//!       |--------------|--------------|--------------|--------------|
+//!       | always false | always-false | always-false | always-false |
+//!       | ambiguous    | always-false | ambiguous    | ambiguous    |
+//!       | always true  | always-false | ambiguous    | always-true  |
+//! ```
+//!
+//! The `x = 0` binding can be handled similarly, with the difference that both `test1` and `test2`
+//! are negated:
+//! ```py
+//! x = 0  # ~test1 AND ~test2
+//!
+//! if test1:
+//!     x = 1  # test1 AND ~test2
+//!
+//! if test2:
+//!     x = 2  # test2
+//! ```
+//!
+//! ### Merged constraints (ternary OR)
+//!
+//! Finally, we consider what happens in "parallel" control flow. Consider the following example
+//! where we have omitted the test condition for the outer `if` for clarity:
+//! ```py
+//! x = 0
+//!
+//! if <…>:
+//!     if test1:
+//!         x = 1
+//! else:
+//!     if test2:
+//!         x = 2
+//!
+//! use(x)
+//! ```
+//! At the usage of `x`, i.e. after control flow has been merged again, the visibility of the `x =
+//! 0` binding behaves as follows: the binding is always visible if `test1` is always-false *or*
+//! `test2` is always-false; and it is never visible if `test1` is always-true *and* `test2` is
+//! always-true. This corresponds to a ternary *OR* operation in Kleene logic:
+//!
+//! ```text
+//!       | OR           | always-false | ambiguous    | always-true  |
+//!       |--------------|--------------|--------------|--------------|
+//!       | always false | always-false | ambiguous    | always-true  |
+//!       | ambiguous    | ambiguous    | ambiguous    | always-true  |
+//!       | always true  | always-true  | always-true  | always-true  |
+//! ```
+//!
+//! Using this, we can annotate the visibility constraints for the example above:
+//! ```py
+//! x = 0  # ~test1 OR ~test2
+//!
+//! if <…>:
+//!     if test1:
+//!         x = 1  # test1
+//! else:
+//!     if test2:
+//!         x = 2  # test2
+//!
+//! use(x)
+//! ```
+//!
+//! ### Explicit ambiguity
+//!
+//! In some cases, we explicitly add an “ambiguous” constraint to all bindings
+//! in a certain control flow path. We do this when branching on something that we can not (or
+//! intentionally do not want to) analyze statically. `for` loops are one example:
+//! ```py
+//! x = <unbound>
+//!
+//! for _ in range(2):
+//!    x = 1
+//! ```
+//! Here, we report an ambiguous visibility constraint before branching off. If we don't do this,
+//! the `x = <unbound>` binding would be considered unconditionally visible in the no-loop case.
+//! And since the other branch does not have the live `x = <unbound>` binding, we would incorrectly
+//! create a state where the `x = <unbound>` binding is always visible.
+//!
+//!
+//! ### Representing formulas
+//!
+//! Given everything above, we can represent a visibility constraint as a _ternary formula_. This
+//! is like a boolean formula (which maps several true/false variables to a single true/false
+//! result), but which allows the third "ambiguous" value in addition to "true" and "false".
+//!
+//! [_Binary decision diagrams_][bdd] (BDDs) are a common way to represent boolean formulas when
+//! doing program analysis. We extend this to a _ternary decision diagram_ (TDD) to support
+//! ambiguous values.
+//!
+//! A TDD is a graph, and a ternary formula is represented by a node in this graph. There are three
+//! possible leaf nodes representing the "true", "false", and "ambiguous" constant functions.
+//! Interior nodes consist of a ternary variable to evaluate, and outgoing edges for whether the
+//! variable evaluates to true, false, or ambiguous.
+//!
+//! Our TDDs are _reduced_ and _ordered_ (as is typical for BDDs).
+//!
+//! An ordered TDD means that variables appear in the same order in all paths within the graph.
+//!
+//! A reduced TDD means two things: First, we intern the graph nodes, so that we only keep a single
+//! copy of interior nodes with the same contents. Second, we eliminate any nodes that are "noops",
+//! where the "true" and "false" outgoing edges lead to the same node. (This implies that it
+//! doesn't matter what value that variable has when evaluating the formula, and we can leave it
+//! out of the evaluation chain completely.)
+//!
+//! Reduced and ordered decision diagrams are _normal forms_, which means that two equivalent
+//! formulas (which have the same outputs for every combination of inputs) are represented by
+//! exactly the same graph node. (Because of interning, this is not _equal_ nodes, but _identical_
+//! ones.) That means that we can compare formulas for equivalence in constant time, and in
+//! particular, can check whether a visibility constraint is statically always true or false,
+//! regardless of any Python program state, by seeing if the constraint's formula is the "true" or
+//! "false" leaf node.
+//!
+//! [Kleene]: <https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics>
+//! [bdd]: https://en.wikipedia.org/wiki/Binary_decision_diagram
+
+use std::cmp::Ordering;
+
+use ruff_index::{Idx, IndexVec};
+use rustc_hash::FxHashMap;
+
+use crate::semantic_index::expression::Expression;
+use crate::semantic_index::predicate::{
+    PatternPredicate, PatternPredicateKind, Predicate, PredicateNode, Predicates, ScopedPredicateId,
+};
+use crate::semantic_index::symbol_table;
+use crate::symbol::imported_symbol;
+use crate::types::{infer_expression_type, Truthiness, Type};
+use crate::Db;
+
+/// A ternary formula that defines under what conditions a binding is visible. (A ternary formula
+/// is just like a boolean formula, but with `Ambiguous` as a third potential result. See the
+/// module documentation for more details.)
+///
+/// The primitive atoms of the formula are [`Predicate`]s, which express some property of the
+/// runtime state of the code that we are analyzing.
+///
+/// We assume that each atom has a stable value each time that the formula is evaluated. An atom
+/// that resolves to `Ambiguous` might be true or false, and we can't tell which — but within that
+/// evaluation, we assume that the atom has the _same_ unknown value each time it appears. That
+/// allows us to perform simplifications like `A ∨ !A → true` and `A ∧ !A → false`.
+///
+/// That means that when you are constructing a formula, you might need to create distinct atoms
+/// for a particular [`Predicate`], if your formula needs to consider how a particular runtime
+/// property might be different at different points in the execution of the program.
+///
+/// Visibility constraints are normalized, so equivalent constraints are guaranteed to have equal
+/// IDs.
+#[derive(Clone, Copy, Eq, Hash, PartialEq)]
+pub(crate) struct ScopedVisibilityConstraintId(u32);
+
+impl std::fmt::Debug for ScopedVisibilityConstraintId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let mut f = f.debug_tuple("ScopedVisibilityConstraintId");
+        match *self {
+            // We use format_args instead of rendering the strings directly so that we don't get
+            // any quotes in the output: ScopedVisibilityConstraintId(AlwaysTrue) instead of
+            // ScopedVisibilityConstraintId("AlwaysTrue").
+            ALWAYS_TRUE => f.field(&format_args!("AlwaysTrue")),
+            AMBIGUOUS => f.field(&format_args!("Ambiguous")),
+            ALWAYS_FALSE => f.field(&format_args!("AlwaysFalse")),
+            _ => f.field(&self.0),
+        };
+        f.finish()
+    }
+}
+
+// Internal details:
+//
+// There are 3 terminals, with hard-coded constraint IDs: true, ambiguous, and false.
+//
+// _Atoms_ are the underlying Predicates, which are the variables that are evaluated by the
+// ternary function.
+//
+// _Interior nodes_ provide the TDD structure for the formula. Interior nodes are stored in an
+// arena Vec, with the constraint ID providing an index into the arena.
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+struct InteriorNode {
+    /// A "variable" that is evaluated as part of a TDD ternary function. For visibility
+    /// constraints, this is a `Predicate` that represents some runtime property of the Python
+    /// code that we are evaluating.
+    atom: ScopedPredicateId,
+    if_true: ScopedVisibilityConstraintId,
+    if_ambiguous: ScopedVisibilityConstraintId,
+    if_false: ScopedVisibilityConstraintId,
+}
+
+impl ScopedVisibilityConstraintId {
+    /// A special ID that is used for an "always true" / "always visible" constraint.
+    pub(crate) const ALWAYS_TRUE: ScopedVisibilityConstraintId =
+        ScopedVisibilityConstraintId(0xffff_ffff);
+
+    /// A special ID that is used for an ambiguous constraint.
+    pub(crate) const AMBIGUOUS: ScopedVisibilityConstraintId =
+        ScopedVisibilityConstraintId(0xffff_fffe);
+
+    /// A special ID that is used for an "always false" / "never visible" constraint.
+    pub(crate) const ALWAYS_FALSE: ScopedVisibilityConstraintId =
+        ScopedVisibilityConstraintId(0xffff_fffd);
+
+    fn is_terminal(self) -> bool {
+        self.0 >= SMALLEST_TERMINAL.0
+    }
+}
+
+impl Idx for ScopedVisibilityConstraintId {
+    #[inline]
+    fn new(value: usize) -> Self {
+        assert!(value <= (SMALLEST_TERMINAL.0 as usize));
+        #[allow(clippy::cast_possible_truncation)]
+        Self(value as u32)
+    }
+
+    #[inline]
+    fn index(self) -> usize {
+        debug_assert!(!self.is_terminal());
+        self.0 as usize
+    }
+}
+
+// Rebind some constants locally so that we don't need as many qualifiers below.
+const ALWAYS_TRUE: ScopedVisibilityConstraintId = ScopedVisibilityConstraintId::ALWAYS_TRUE;
+const AMBIGUOUS: ScopedVisibilityConstraintId = ScopedVisibilityConstraintId::AMBIGUOUS;
+const ALWAYS_FALSE: ScopedVisibilityConstraintId = ScopedVisibilityConstraintId::ALWAYS_FALSE;
+const SMALLEST_TERMINAL: ScopedVisibilityConstraintId = ALWAYS_FALSE;
+
+/// A collection of visibility constraints for a given scope.
+#[derive(Debug, PartialEq, Eq, salsa::Update)]
+pub(crate) struct VisibilityConstraints {
+    interiors: IndexVec<ScopedVisibilityConstraintId, InteriorNode>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+pub(crate) struct VisibilityConstraintsBuilder {
+    interiors: IndexVec<ScopedVisibilityConstraintId, InteriorNode>,
+    interior_cache: FxHashMap<InteriorNode, ScopedVisibilityConstraintId>,
+    not_cache: FxHashMap<ScopedVisibilityConstraintId, ScopedVisibilityConstraintId>,
+    and_cache: FxHashMap<
+        (ScopedVisibilityConstraintId, ScopedVisibilityConstraintId),
+        ScopedVisibilityConstraintId,
+    >,
+    or_cache: FxHashMap<
+        (ScopedVisibilityConstraintId, ScopedVisibilityConstraintId),
+        ScopedVisibilityConstraintId,
+    >,
+}
+
+impl VisibilityConstraintsBuilder {
+    pub(crate) fn build(self) -> VisibilityConstraints {
+        VisibilityConstraints {
+            interiors: self.interiors,
+        }
+    }
+
+    /// Returns whether `a` or `b` has a "larger" atom. TDDs are ordered such that interior nodes
+    /// can only have edges to "larger" nodes. Terminals are considered to have a larger atom than
+    /// any internal node, since they are leaf nodes.
+    fn cmp_atoms(
+        &self,
+        a: ScopedVisibilityConstraintId,
+        b: ScopedVisibilityConstraintId,
+    ) -> Ordering {
+        if a == b || (a.is_terminal() && b.is_terminal()) {
+            Ordering::Equal
+        } else if a.is_terminal() {
+            Ordering::Greater
+        } else if b.is_terminal() {
+            Ordering::Less
+        } else {
+            self.interiors[a].atom.cmp(&self.interiors[b].atom)
+        }
+    }
+
+    /// Adds an interior node, ensuring that we always use the same visibility constraint ID for
+    /// equal nodes.
+    fn add_interior(&mut self, node: InteriorNode) -> ScopedVisibilityConstraintId {
+        // If the true and false branches lead to the same node, we can override the ambiguous
+        // branch to go there too. And this node is then redundant and can be reduced.
+        if node.if_true == node.if_false {
+            return node.if_true;
+        }
+
+        *self
+            .interior_cache
+            .entry(node)
+            .or_insert_with(|| self.interiors.push(node))
+    }
+
+    /// Adds a new visibility constraint that checks a single [`Predicate`].
+    ///
+    /// [`ScopedPredicateId`]s are the “variables” that are evaluated by a TDD. A TDD variable has
+    /// the same value no matter how many times it appears in the ternary formula that the TDD
+    /// represents.
+    ///
+    /// However, we sometimes have to model how a `Predicate` can have a different runtime
+    /// value at different points in the execution of the program. To handle this, you can take
+    /// advantage of the fact that the [`Predicates`] arena does not deduplicate `Predicate`s.
+    /// You can add a `Predicate` multiple times, yielding different `ScopedPredicateId`s, which
+    /// you can then create separate TDD atoms for.
+    pub(crate) fn add_atom(
+        &mut self,
+        predicate: ScopedPredicateId,
+    ) -> ScopedVisibilityConstraintId {
+        self.add_interior(InteriorNode {
+            atom: predicate,
+            if_true: ALWAYS_TRUE,
+            if_ambiguous: AMBIGUOUS,
+            if_false: ALWAYS_FALSE,
+        })
+    }
+
+    /// Adds a new visibility constraint that is the ternary NOT of an existing one.
+    pub(crate) fn add_not_constraint(
+        &mut self,
+        a: ScopedVisibilityConstraintId,
+    ) -> ScopedVisibilityConstraintId {
+        if a == ALWAYS_TRUE {
+            return ALWAYS_FALSE;
+        } else if a == AMBIGUOUS {
+            return AMBIGUOUS;
+        } else if a == ALWAYS_FALSE {
+            return ALWAYS_TRUE;
+        }
+
+        if let Some(cached) = self.not_cache.get(&a) {
+            return *cached;
+        }
+        let a_node = self.interiors[a];
+        let if_true = self.add_not_constraint(a_node.if_true);
+        let if_ambiguous = self.add_not_constraint(a_node.if_ambiguous);
+        let if_false = self.add_not_constraint(a_node.if_false);
+        let result = self.add_interior(InteriorNode {
+            atom: a_node.atom,
+            if_true,
+            if_ambiguous,
+            if_false,
+        });
+        self.not_cache.insert(a, result);
+        result
+    }
+
+    /// Adds a new visibility constraint that is the ternary OR of two existing ones.
+    pub(crate) fn add_or_constraint(
+        &mut self,
+        a: ScopedVisibilityConstraintId,
+        b: ScopedVisibilityConstraintId,
+    ) -> ScopedVisibilityConstraintId {
+        match (a, b) {
+            (ALWAYS_TRUE, _) | (_, ALWAYS_TRUE) => return ALWAYS_TRUE,
+            (ALWAYS_FALSE, other) | (other, ALWAYS_FALSE) => return other,
+            (AMBIGUOUS, AMBIGUOUS) => return AMBIGUOUS,
+            _ => {}
+        }
+
+        // OR is commutative, which lets us halve the cache requirements
+        let (a, b) = if b.0 < a.0 { (b, a) } else { (a, b) };
+        if let Some(cached) = self.or_cache.get(&(a, b)) {
+            return *cached;
+        }
+
+        let (atom, if_true, if_ambiguous, if_false) = match self.cmp_atoms(a, b) {
+            Ordering::Equal => {
+                let a_node = self.interiors[a];
+                let b_node = self.interiors[b];
+                let if_true = self.add_or_constraint(a_node.if_true, b_node.if_true);
+                let if_false = self.add_or_constraint(a_node.if_false, b_node.if_false);
+                let if_ambiguous = if if_true == if_false {
+                    if_true
+                } else {
+                    self.add_or_constraint(a_node.if_ambiguous, b_node.if_ambiguous)
+                };
+                (a_node.atom, if_true, if_ambiguous, if_false)
+            }
+            Ordering::Less => {
+                let a_node = self.interiors[a];
+                let if_true = self.add_or_constraint(a_node.if_true, b);
+                let if_false = self.add_or_constraint(a_node.if_false, b);
+                let if_ambiguous = if if_true == if_false {
+                    if_true
+                } else {
+                    self.add_or_constraint(a_node.if_ambiguous, b)
+                };
+                (a_node.atom, if_true, if_ambiguous, if_false)
+            }
+            Ordering::Greater => {
+                let b_node = self.interiors[b];
+                let if_true = self.add_or_constraint(a, b_node.if_true);
+                let if_false = self.add_or_constraint(a, b_node.if_false);
+                let if_ambiguous = if if_true == if_false {
+                    if_true
+                } else {
+                    self.add_or_constraint(a, b_node.if_ambiguous)
+                };
+                (b_node.atom, if_true, if_ambiguous, if_false)
+            }
+        };
+
+        let result = self.add_interior(InteriorNode {
+            atom,
+            if_true,
+            if_ambiguous,
+            if_false,
+        });
+        self.or_cache.insert((a, b), result);
+        result
+    }
+
+    /// Adds a new visibility constraint that is the ternary AND of two existing ones.
+    pub(crate) fn add_and_constraint(
+        &mut self,
+        a: ScopedVisibilityConstraintId,
+        b: ScopedVisibilityConstraintId,
+    ) -> ScopedVisibilityConstraintId {
+        match (a, b) {
+            (ALWAYS_FALSE, _) | (_, ALWAYS_FALSE) => return ALWAYS_FALSE,
+            (ALWAYS_TRUE, other) | (other, ALWAYS_TRUE) => return other,
+            (AMBIGUOUS, AMBIGUOUS) => return AMBIGUOUS,
+            _ => {}
+        }
+
+        // AND is commutative, which lets us halve the cache requirements
+        let (a, b) = if b.0 < a.0 { (b, a) } else { (a, b) };
+        if let Some(cached) = self.and_cache.get(&(a, b)) {
+            return *cached;
+        }
+
+        let (atom, if_true, if_ambiguous, if_false) = match self.cmp_atoms(a, b) {
+            Ordering::Equal => {
+                let a_node = self.interiors[a];
+                let b_node = self.interiors[b];
+                let if_true = self.add_and_constraint(a_node.if_true, b_node.if_true);
+                let if_false = self.add_and_constraint(a_node.if_false, b_node.if_false);
+                let if_ambiguous = if if_true == if_false {
+                    if_true
+                } else {
+                    self.add_and_constraint(a_node.if_ambiguous, b_node.if_ambiguous)
+                };
+                (a_node.atom, if_true, if_ambiguous, if_false)
+            }
+            Ordering::Less => {
+                let a_node = self.interiors[a];
+                let if_true = self.add_and_constraint(a_node.if_true, b);
+                let if_false = self.add_and_constraint(a_node.if_false, b);
+                let if_ambiguous = if if_true == if_false {
+                    if_true
+                } else {
+                    self.add_and_constraint(a_node.if_ambiguous, b)
+                };
+                (a_node.atom, if_true, if_ambiguous, if_false)
+            }
+            Ordering::Greater => {
+                let b_node = self.interiors[b];
+                let if_true = self.add_and_constraint(a, b_node.if_true);
+                let if_false = self.add_and_constraint(a, b_node.if_false);
+                let if_ambiguous = if if_true == if_false {
+                    if_true
+                } else {
+                    self.add_and_constraint(a, b_node.if_ambiguous)
+                };
+                (b_node.atom, if_true, if_ambiguous, if_false)
+            }
+        };
+
+        let result = self.add_interior(InteriorNode {
+            atom,
+            if_true,
+            if_ambiguous,
+            if_false,
+        });
+        self.and_cache.insert((a, b), result);
+        result
+    }
+}
+
+impl VisibilityConstraints {
+    /// Analyze the statically known visibility for a given visibility constraint.
+    pub(crate) fn evaluate<'db>(
+        &self,
+        db: &'db dyn Db,
+        predicates: &Predicates<'db>,
+        mut id: ScopedVisibilityConstraintId,
+    ) -> Truthiness {
+        loop {
+            let node = match id {
+                ALWAYS_TRUE => return Truthiness::AlwaysTrue,
+                AMBIGUOUS => return Truthiness::Ambiguous,
+                ALWAYS_FALSE => return Truthiness::AlwaysFalse,
+                _ => self.interiors[id],
+            };
+            let predicate = &predicates[node.atom];
+            match Self::analyze_single(db, predicate) {
+                Truthiness::AlwaysTrue => id = node.if_true,
+                Truthiness::Ambiguous => id = node.if_ambiguous,
+                Truthiness::AlwaysFalse => id = node.if_false,
+            }
+        }
+    }
+
+    fn analyze_single_pattern_predicate_kind<'db>(
+        db: &'db dyn Db,
+        predicate_kind: &PatternPredicateKind<'db>,
+        subject: Expression<'db>,
+    ) -> Truthiness {
+        match predicate_kind {
+            PatternPredicateKind::Value(value) => {
+                let subject_ty = infer_expression_type(db, subject);
+                let value_ty = infer_expression_type(db, *value);
+
+                if subject_ty.is_single_valued(db) {
+                    Truthiness::from(subject_ty.is_equivalent_to(db, value_ty))
+                } else {
+                    Truthiness::Ambiguous
+                }
+            }
+            PatternPredicateKind::Singleton(singleton) => {
+                let subject_ty = infer_expression_type(db, subject);
+
+                let singleton_ty = match singleton {
+                    ruff_python_ast::Singleton::None => Type::none(db),
+                    ruff_python_ast::Singleton::True => Type::BooleanLiteral(true),
+                    ruff_python_ast::Singleton::False => Type::BooleanLiteral(false),
+                };
+
+                debug_assert!(singleton_ty.is_singleton(db));
+
+                if subject_ty.is_equivalent_to(db, singleton_ty) {
+                    Truthiness::AlwaysTrue
+                } else if subject_ty.is_disjoint_from(db, singleton_ty) {
+                    Truthiness::AlwaysFalse
+                } else {
+                    Truthiness::Ambiguous
+                }
+            }
+            PatternPredicateKind::Or(predicates) => {
+                use std::ops::ControlFlow;
+                let (ControlFlow::Break(truthiness) | ControlFlow::Continue(truthiness)) =
+                    predicates
+                        .iter()
+                        .map(|p| Self::analyze_single_pattern_predicate_kind(db, p, subject))
+                        // this is just a "max", but with a slight optimization: `AlwaysTrue` is the "greatest" possible element, so we short-circuit if we get there
+                        .try_fold(Truthiness::AlwaysFalse, |acc, next| match (acc, next) {
+                            (Truthiness::AlwaysTrue, _) | (_, Truthiness::AlwaysTrue) => {
+                                ControlFlow::Break(Truthiness::AlwaysTrue)
+                            }
+                            (Truthiness::Ambiguous, _) | (_, Truthiness::Ambiguous) => {
+                                ControlFlow::Continue(Truthiness::Ambiguous)
+                            }
+                            (Truthiness::AlwaysFalse, Truthiness::AlwaysFalse) => {
+                                ControlFlow::Continue(Truthiness::AlwaysFalse)
+                            }
+                        });
+                truthiness
+            }
+            PatternPredicateKind::Class(class_expr) => {
+                let subject_ty = infer_expression_type(db, subject);
+                let class_ty = infer_expression_type(db, *class_expr).to_instance(db);
+
+                class_ty.map_or(Truthiness::Ambiguous, |class_ty| {
+                    if subject_ty.is_subtype_of(db, class_ty) {
+                        Truthiness::AlwaysTrue
+                    } else if subject_ty.is_disjoint_from(db, class_ty) {
+                        Truthiness::AlwaysFalse
+                    } else {
+                        Truthiness::Ambiguous
+                    }
+                })
+            }
+            PatternPredicateKind::Unsupported => Truthiness::Ambiguous,
+        }
+    }
+
+    fn analyze_single_pattern_predicate(db: &dyn Db, predicate: PatternPredicate) -> Truthiness {
+        let truthiness = Self::analyze_single_pattern_predicate_kind(
+            db,
+            predicate.kind(db),
+            predicate.subject(db),
+        );
+
+        if truthiness == Truthiness::AlwaysTrue && predicate.guard(db).is_some() {
+            // Fall back to ambiguous, the guard might change the result.
+            // TODO: actually analyze guard truthiness
+            Truthiness::Ambiguous
+        } else {
+            truthiness
+        }
+    }
+
+    fn analyze_single(db: &dyn Db, predicate: &Predicate) -> Truthiness {
+        match predicate.node {
+            PredicateNode::Expression(test_expr) => {
+                let ty = infer_expression_type(db, test_expr);
+                ty.bool(db).negate_if(!predicate.is_positive)
+            }
+            PredicateNode::Pattern(inner) => Self::analyze_single_pattern_predicate(db, inner),
+            PredicateNode::StarImportPlaceholder(star_import) => {
+                let symbol_table = symbol_table(db, star_import.scope(db));
+                let symbol_name = symbol_table.symbol(star_import.symbol_id(db)).name();
+                match imported_symbol(db, star_import.referenced_file(db), symbol_name).symbol {
+                    crate::symbol::Symbol::Type(_, crate::symbol::Boundness::Bound) => {
+                        Truthiness::AlwaysTrue
+                    }
+                    crate::symbol::Symbol::Type(_, crate::symbol::Boundness::PossiblyUnbound) => {
+                        Truthiness::Ambiguous
+                    }
+                    crate::symbol::Symbol::Unbound => Truthiness::AlwaysFalse,
+                }
+            }
+        }
+    }
+}