Promote implicit literals for module-level variables

Summary:
Module-level assignments like `timeout = 100` infer `Literal[100]`, but
protocols expect `timeout: int`. This caused the `protocols_modules.py`
conformance test to fail.

We fix this by promoting implicit literals at two use sites where
module-level variables are read from outside their defining scope:

1. Cross-barrier function reads: when a function reads a module-level
   variable (across a flow barrier), we use `Binding::PromoteForward`
   instead of `Binding::Forward`. This widens implicit literals to their
   base types, so `def foo(): reveal_type(x)` gives `int` for `x = 42`.
   The `is_module_scope` flag on `NameReadInfo::Anywhere` ensures we only
   promote reads from module scope, not from enclosing functions.

2. Module exports: unannotated exports promote implicit literals so that
   cross-module access like `import mod; mod.x` gives `int`.

Flow-sensitive reads at the same level are unchanged — `x = 42;
reveal_type(x)` still gives `Literal[42]`. ALL_CAPS names are excluded
from promotion as conventional constants. Annotated exports (including
`Final`) are unchanged since the annotation determines the type.

Reviewed By: rchen152

Differential Revision: D98803805

fbshipit-source-id: e7784ad9be3b7a8a32bfd280b31f6e1e2f273069

Author: migeed-z

conformance/third_party/conformance.exp

@@ -9655,22 +9655,11 @@
     }
   ],
   "protocols_modules.py": [
-    {
-      "code": -2,
-      "column": 17,
-      "concise_description": "`Module[_protocols_modules1]` is not assignable to `Options1`",
-      "description": "`Module[_protocols_modules1]` is not assignable to `Options1`\n  `Module[_protocols_modules1].timeout` has type `Literal[100]`, which is not consistent with `int` in `Options1.timeout` (the type of read-write attributes cannot be changed)",
-      "line": 25,
-      "name": "bad-assignment",
-      "severity": "error",
-      "stop_column": 36,
-      "stop_line": 25
-    },
     {
       "code": -2,
       "column": 17,
       "concise_description": "`Module[_protocols_modules1]` is not assignable to `Options2`",
-      "description": "`Module[_protocols_modules1]` is not assignable to `Options2`\n  `Module[_protocols_modules1].timeout` has type `Literal[100]`, which is not consistent with `str` in `Options2.timeout` (the type of read-write attributes cannot be changed)",
+      "description": "`Module[_protocols_modules1]` is not assignable to `Options2`\n  `Module[_protocols_modules1].timeout` has type `int`, which is not consistent with `str` in `Options2.timeout` (the type of read-write attributes cannot be changed)",
       "line": 26,
       "name": "bad-assignment",
       "severity": "error",

conformance/third_party/conformance.result

@@ -147,9 +147,7 @@
   "protocols_explicit.py": [],
   "protocols_generic.py": [],
   "protocols_merging.py": [],
-  "protocols_modules.py": [
-    "Line 25: Unexpected errors ['`Module[_protocols_modules1]` is not assignable to `Options1`\\n  `Module[_protocols_modules1].timeout` has type `Literal[100]`, which is not consistent with `int` in `Options1.timeout` (the type of read-write attributes cannot be changed)']"
-  ],
+  "protocols_modules.py": [],
   "protocols_recursive.py": [],
   "protocols_runtime_checkable.py": [],
   "protocols_self.py": [],

conformance/third_party/results.json

@@ -1,9 +1,9 @@
 {
   "total": 139,
-  "pass": 126,
-  "fail": 13,
+  "pass": 127,
+  "fail": 12,
   "pass_rate": 0.91,
-  "differences": 32,
+  "differences": 31,
   "passing": [
     "aliases_explicit.py",
     "aliases_newtype.py",
@@ -101,6 +101,7 @@
     "protocols_explicit.py",
     "protocols_generic.py",
     "protocols_merging.py",
+    "protocols_modules.py",
     "protocols_recursive.py",
     "protocols_runtime_checkable.py",
     "protocols_self.py",
@@ -144,7 +145,6 @@
     "generics_self_basic.py": 2,
     "generics_self_usage.py": 1,
     "generics_typevartuple_basic.py": 1,
-    "protocols_modules.py": 1,
     "typeforms_typeform.py": 2
   },
   "comment": "@generated"

crates/pyrefly_types/src/types.rs

@@ -1701,6 +1701,29 @@ impl Type {
         sigs
     }
 
+    fn widen_one_implicit_literal(ty: &mut Type, stdlib: &Stdlib) {
+        match &*ty {
+            Type::Literal(lit) if lit.style == LitStyle::Implicit => {
+                *ty = lit.value.general_class_type(stdlib).clone().to_type()
+            }
+            Type::LiteralString(LitStyle::Implicit) => *ty = stdlib.str().clone().to_type(),
+            _ => {}
+        }
+    }
+
+    /// Like `promote_implicit_literals` but only recurses into unions.
+    pub fn promote_shallow_implicit_literals(mut self, stdlib: &Stdlib) -> Type {
+        match &mut self {
+            Type::Union(union) => {
+                for member in &mut union.members {
+                    Self::widen_one_implicit_literal(member, stdlib);
+                }
+            }
+            _ => Self::widen_one_implicit_literal(&mut self, stdlib),
+        }
+        self
+    }
+
     pub fn promote_implicit_literals(mut self, stdlib: &Stdlib) -> Type {
         fn g(ty: &mut Type, f: &mut dyn FnMut(&mut Type)) {
             // Don't recurse into NNModule fields — they carry captured constructor
@@ -1712,12 +1735,8 @@ impl Type {
             ty.recurse_mut(&mut |ty| g(ty, f));
             f(ty);
         }
-        g(&mut self, &mut |ty| match &ty {
-            Type::Literal(lit) if lit.style == LitStyle::Implicit => {
-                *ty = lit.value.general_class_type(stdlib).clone().to_type()
-            }
-            Type::LiteralString(LitStyle::Implicit) => *ty = stdlib.str().clone().to_type(),
-            _ => {}
+        g(&mut self, &mut |ty| {
+            Self::widen_one_implicit_literal(ty, stdlib)
         });
         self
     }

pyrefly/lib/alt/expr.rs

@@ -286,8 +286,15 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
                 if Ast::is_synthesized_empty_name(x) {
                     TypeInfo::of_ty(self.heap.mk_any_error())
                 } else {
-                    self.get(&Key::BoundName(ShortIdentifier::expr_name(x)))
-                        .arc_clone()
+                    let result = self
+                        .get(&Key::BoundName(ShortIdentifier::expr_name(x)))
+                        .arc_clone();
+                    // Complements PromoteForward for seeded captures.
+                    if self.bindings().should_promote_at_range(x.range) {
+                        result.map_ty(|ty| ty.promote_shallow_implicit_literals(self.stdlib))
+                    } else {
+                        result
+                    }
                 }
             }
             Expr::Attribute(x) => {

pyrefly/lib/alt/function.rs

@@ -1592,7 +1592,9 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
     fn step_pred(&self, pred: &mut Option<Idx<Key>>) -> Option<DecoratedFunction> {
         let pred_idx = (*pred)?;
         let mut b = self.bindings().get(pred_idx);
-        while let Binding::Forward(k) | Binding::ForwardToFirstUse(k) = b {
+        while let Binding::Forward(k) | Binding::PromoteForward(k) | Binding::ForwardToFirstUse(k) =
+            b
+        {
             b = self.bindings().get(*k);
         }
         if let Binding::Function(idx, pred_, _) = b {

pyrefly/lib/alt/solve.rs

@@ -1948,6 +1948,9 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
         if let Binding::Forward(fwd) | Binding::ForwardToFirstUse(fwd) = binding {
             return self.get_idx(*fwd);
         }
+        if let Binding::PromoteForward(fwd) = binding {
+            return Arc::new(self.resolve_promote_forward(*fwd));
+        }
         // Inline first-use pinning for NameAssign.
         let mut type_info = if let Binding::NameAssign(na) = binding
             && self.solver().infer_with_first_use
@@ -4266,9 +4269,16 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
         type_info
     }
 
+    fn resolve_promote_forward(&self, fwd: Idx<Key>) -> TypeInfo {
+        self.get_idx(fwd)
+            .arc_clone()
+            .map_ty(|ty| ty.promote_shallow_implicit_literals(self.stdlib))
+    }
+
     fn binding_to_type_info(&self, binding: &Binding, errors: &ErrorCollector) -> TypeInfo {
         match binding {
             Binding::Forward(k) => self.get_idx(*k).arc_clone(),
+            Binding::PromoteForward(k) => self.resolve_promote_forward(*k),
             Binding::ForwardToFirstUse(k) => {
                 if let Some(def_idx) = self.def_idx_for_forward_to_first_use(*k)
                     && let Some(type_info) = self.check_partial_answer(def_idx)
@@ -4691,6 +4701,7 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
     fn binding_to_type(&self, binding: &Binding, errors: &ErrorCollector) -> Type {
         match binding {
             Binding::Forward(..)
+            | Binding::PromoteForward(..)
             | Binding::ForwardToFirstUse(..)
             | Binding::Phi(..)
             | Binding::LoopPhi(..)

pyrefly/lib/alt/traits.rs

@@ -237,6 +237,7 @@ impl<Ans: LookupAnswer> Solve<Ans> for KeyExport {
     ) -> Arc<Type> {
         let inner = match binding {
             BindingExport::Forward(idx) => Binding::Forward(*idx),
+            BindingExport::PromoteForward(idx) => Binding::PromoteForward(*idx),
             BindingExport::AnnotatedForward(ann, idx) => {
                 Binding::AnnotatedType(*ann, Box::new(Binding::Forward(*idx)))
             }

pyrefly/lib/binding/binding.rs

@@ -70,6 +70,7 @@ use crate::binding::django::DjangoFieldInfo;
 use crate::binding::narrow::NarrowOp;
 use crate::binding::narrow::NarrowingSubject;
 use crate::binding::pydantic::PydanticConfigDict;
+use crate::binding::scope::is_constant_name;
 use crate::binding::table::TableKeyed;
 use crate::export::special::SpecialExport;
 use crate::module::module_info::ModuleInfo;
@@ -2089,6 +2090,8 @@ pub enum Binding {
     ClassDef(Idx<KeyClass>, Box<[Idx<KeyDecorator>]>),
     /// A forward reference to another binding.
     Forward(Idx<Key>),
+    /// Like Forward, but widens implicit literals.
+    PromoteForward(Idx<Key>),
     /// A forward reference produced during first-use resolution of a partial type.
     /// Behaves identically to `Forward` but marks that this indirection came from
     /// the partial-type / first-use machinery.
@@ -2259,6 +2262,7 @@ impl DisplayWith<Bindings> for Binding {
             }
             Self::ClassDef(x, _) => write!(f, "ClassDef({})", ctx.display(*x)),
             Self::Forward(k) => write!(f, "Forward({})", ctx.display(*k)),
+            Self::PromoteForward(k) => write!(f, "PromoteForward({})", ctx.display(*k)),
             Self::ForwardToFirstUse(k) => {
                 write!(f, "ForwardToFirstUse({})", ctx.display(*k))
             }
@@ -2513,6 +2517,7 @@ impl Binding {
             | Binding::None
             | Binding::Any(_)
             | Binding::Forward(_)
+            | Binding::PromoteForward(_)
             | Binding::ForwardToFirstUse(_)
             | Binding::Phi(_, _)
             | Binding::LoopPhi(_, _)
@@ -2538,14 +2543,23 @@ impl Binding {
 #[derive(Clone, Debug)]
 pub enum BindingExport {
     Forward(Idx<Key>),
+    PromoteForward(Idx<Key>),
     AnnotatedForward(Idx<KeyAnnotation>, Idx<Key>),
 }
 
 impl BindingExport {
+    pub fn forward_maybe_promote(idx: Idx<Key>, name: &Name) -> Self {
+        if is_constant_name(name) {
+            Self::Forward(idx)
+        } else {
+            Self::PromoteForward(idx)
+        }
+    }
+
     /// The forwarded key index that this export points to.
     pub fn key_idx(&self) -> Idx<Key> {
         match self {
-            Self::Forward(idx) | Self::AnnotatedForward(_, idx) => *idx,
+            Self::Forward(idx) | Self::PromoteForward(idx) | Self::AnnotatedForward(_, idx) => *idx,
         }
     }
 }
@@ -2554,6 +2568,9 @@ impl DisplayWith<Bindings> for BindingExport {
     fn fmt(&self, f: &mut fmt::Formatter<'_>, ctx: &Bindings) -> fmt::Result {
         match self {
             Self::Forward(idx) => write!(f, "BindingExport::Forward({})", ctx.display(*idx)),
+            Self::PromoteForward(idx) => {
+                write!(f, "BindingExport::PromoteForward({})", ctx.display(*idx))
+            }
             Self::AnnotatedForward(ann, idx) => {
                 write!(
                     f,