[red-knot] Symbol API improvements, part 2 (#14276)

## Summary

Apart from one small functional change, this is mostly a refactoring of
the `Symbol` API:

- Rename `as_type` to the more explicit `ignore_possibly_unbound`, no
functional change
- Remove `unwrap_or_unknown` in favor of the more explicit
`.ignore_possibly_unbound().unwrap_or(Type::Unknown)`, no functional
change
- Consistently call it "possibly unbound" (not "may be unbound")
- Rename `replace_unbound_with` to `or_fall_back_to` and properly handle
boundness of the fall back. This is the only functional change (did not
have any impact on existing tests).

relates to: #14022

## Test Plan

New unit tests for `Symbol::or_fall_back_to`

---------

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

crates/red_knot_python_semantic/src/symbol.rs

@@ -6,7 +6,16 @@ use crate::{
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum Boundness {
     Bound,
-    MayBeUnbound,
+    PossiblyUnbound,
+}
+
+impl Boundness {
+    pub(crate) fn or(self, other: Boundness) -> Boundness {
+        match (self, other) {
+            (Boundness::Bound, _) | (_, Boundness::Bound) => Boundness::Bound,
+            (Boundness::PossiblyUnbound, Boundness::PossiblyUnbound) => Boundness::PossiblyUnbound,
+        }
+    }
 }
 
 /// The result of a symbol lookup, which can either be a (possibly unbound) type
@@ -17,14 +26,14 @@ pub(crate) enum Boundness {
 /// bound = 1
 ///
 /// if flag:
-///     maybe_unbound = 2
+///     possibly_unbound = 2
 /// ```
 ///
 /// If we look up symbols in this scope, we would get the following results:
 /// ```rs
-/// bound:          Symbol::Type(Type::IntLiteral(1), Boundness::Bound),
-/// maybe_unbound:  Symbol::Type(Type::IntLiteral(2), Boundness::MayBeUnbound),
-/// non_existent:   Symbol::Unbound,
+/// bound:             Symbol::Type(Type::IntLiteral(1), Boundness::Bound),
+/// possibly_unbound:  Symbol::Type(Type::IntLiteral(2), Boundness::PossiblyUnbound),
+/// non_existent:      Symbol::Unbound,
 /// ```
 #[derive(Debug, Clone, PartialEq)]
 pub(crate) enum Symbol<'db> {
@@ -37,21 +46,18 @@ impl<'db> Symbol<'db> {
         matches!(self, Symbol::Unbound)
     }
 
-    pub(crate) fn may_be_unbound(&self) -> bool {
+    pub(crate) fn possibly_unbound(&self) -> bool {
         match self {
-            Symbol::Type(_, Boundness::MayBeUnbound) | Symbol::Unbound => true,
+            Symbol::Type(_, Boundness::PossiblyUnbound) | Symbol::Unbound => true,
             Symbol::Type(_, Boundness::Bound) => false,
         }
     }
 
-    pub(crate) fn unwrap_or_unknown(&self) -> Type<'db> {
-        match self {
-            Symbol::Type(ty, _) => *ty,
-            Symbol::Unbound => Type::Unknown,
-        }
-    }
-
-    pub(crate) fn as_type(&self) -> Option<Type<'db>> {
+    /// Returns the type of the symbol, ignoring possible unboundness.
+    ///
+    /// If the symbol is *definitely* unbound, this function will return `None`. Otherwise,
+    /// if there is at least one control-flow path where the symbol is bound, return the type.
+    pub(crate) fn ignore_possibly_unbound(&self) -> Option<Type<'db>> {
         match self {
             Symbol::Type(ty, _) => Some(*ty),
             Symbol::Unbound => None,
@@ -61,28 +67,80 @@ impl<'db> Symbol<'db> {
     #[cfg(test)]
     #[track_caller]
     pub(crate) fn expect_type(self) -> Type<'db> {
-        self.as_type()
+        self.ignore_possibly_unbound()
             .expect("Expected a (possibly unbound) type, not an unbound symbol")
     }
 
     #[must_use]
-    pub(crate) fn replace_unbound_with(
-        self,
-        db: &'db dyn Db,
-        replacement: &Symbol<'db>,
-    ) -> Symbol<'db> {
-        match replacement {
-            Symbol::Type(replacement, _) => Symbol::Type(
-                match self {
-                    Symbol::Type(ty, Boundness::Bound) => ty,
-                    Symbol::Type(ty, Boundness::MayBeUnbound) => {
-                        UnionType::from_elements(db, [*replacement, ty])
-                    }
-                    Symbol::Unbound => *replacement,
-                },
-                Boundness::Bound,
-            ),
+    pub(crate) fn or_fall_back_to(self, db: &'db dyn Db, fallback: &Symbol<'db>) -> Symbol<'db> {
+        match fallback {
+            Symbol::Type(fallback_ty, fallback_boundness) => match self {
+                Symbol::Type(_, Boundness::Bound) => self,
+                Symbol::Type(ty, boundness @ Boundness::PossiblyUnbound) => Symbol::Type(
+                    UnionType::from_elements(db, [*fallback_ty, ty]),
+                    fallback_boundness.or(boundness),
+                ),
+                Symbol::Unbound => fallback.clone(),
+            },
             Symbol::Unbound => self,
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::tests::setup_db;
+
+    #[test]
+    fn test_symbol_or_fall_back_to() {
+        use Boundness::{Bound, PossiblyUnbound};
+
+        let db = setup_db();
+        let ty1 = Type::IntLiteral(1);
+        let ty2 = Type::IntLiteral(2);
+
+        // Start from an unbound symbol
+        assert_eq!(
+            Symbol::Unbound.or_fall_back_to(&db, &Symbol::Unbound),
+            Symbol::Unbound
+        );
+        assert_eq!(
+            Symbol::Unbound.or_fall_back_to(&db, &Symbol::Type(ty1, PossiblyUnbound)),
+            Symbol::Type(ty1, PossiblyUnbound)
+        );
+        assert_eq!(
+            Symbol::Unbound.or_fall_back_to(&db, &Symbol::Type(ty1, Bound)),
+            Symbol::Type(ty1, Bound)
+        );
+
+        // Start from a possibly unbound symbol
+        assert_eq!(
+            Symbol::Type(ty1, PossiblyUnbound).or_fall_back_to(&db, &Symbol::Unbound),
+            Symbol::Type(ty1, PossiblyUnbound)
+        );
+        assert_eq!(
+            Symbol::Type(ty1, PossiblyUnbound)
+                .or_fall_back_to(&db, &Symbol::Type(ty2, PossiblyUnbound)),
+            Symbol::Type(UnionType::from_elements(&db, [ty2, ty1]), PossiblyUnbound)
+        );
+        assert_eq!(
+            Symbol::Type(ty1, PossiblyUnbound).or_fall_back_to(&db, &Symbol::Type(ty2, Bound)),
+            Symbol::Type(UnionType::from_elements(&db, [ty2, ty1]), Bound)
+        );
+
+        // Start from a definitely bound symbol
+        assert_eq!(
+            Symbol::Type(ty1, Bound).or_fall_back_to(&db, &Symbol::Unbound),
+            Symbol::Type(ty1, Bound)
+        );
+        assert_eq!(
+            Symbol::Type(ty1, Bound).or_fall_back_to(&db, &Symbol::Type(ty2, PossiblyUnbound)),
+            Symbol::Type(ty1, Bound)
+        );
+        assert_eq!(
+            Symbol::Type(ty1, Bound).or_fall_back_to(&db, &Symbol::Type(ty2, Bound)),
+            Symbol::Type(ty1, Bound)
+        );
+    }
+}