Fix sequence pattern matching type narrowing (#2049)

Summary:
Adds proper type narrowing for sequence patterns in match/case statements. Previously, sequence patterns like [*values] did not narrow union types correctly, and captured variables were not properly typed.

This PR:
- Adds Sequence type to the stdlib for type checking
- Introduces IsSequence/IsNotSequence narrowing operations
- Emits IsSequence narrowing for sequence patterns to properly filter union types
- Correctly types captured variables (e.g., [*values] gives values: list[T] when matching Sequence[T])
- Excludes str, bytes, and bytearray from sequence pattern matching per PEP 634

Fixes #1806.

Pull Request resolved: #2049

Test Plan:
Added 9 new test cases covering:
    - Basic star capture patterns ([*values])
    - Union type narrowing (int | Sequence[int])
    - Fixed-length patterns ([a, b])
    - Mixed patterns ([first, *middle, last])
    - String exclusion per PEP 634
    - List and tuple patterns

Reviewed By: yangdanny97

Differential Revision: D90423128

Pulled By: stroxler

fbshipit-source-id: 359a6441285870de71157476e6562eb50dcd39dc

Author: Adist319

crates/pyrefly_types/src/stdlib.rs

@@ -62,6 +62,7 @@ pub struct Stdlib {
     async_iterable: StdlibResult<(Class, Arc<TParams>)>,
     async_iterator: StdlibResult<(Class, Arc<TParams>)>,
     mutable_sequence: StdlibResult<(Class, Arc<TParams>)>,
+    sequence: StdlibResult<(Class, Arc<TParams>)>,
     generator: StdlibResult<(Class, Arc<TParams>)>,
     async_generator: StdlibResult<(Class, Arc<TParams>)>,
     awaitable: StdlibResult<(Class, Arc<TParams>)>,
@@ -202,6 +203,7 @@ impl Stdlib {
             async_iterable: lookup_generic(typing, "AsyncIterable", 1),
             async_iterator: lookup_generic(typing, "AsyncIterator", 1),
             mutable_sequence: lookup_generic(typing, "MutableSequence", 1),
+            sequence: lookup_generic(typing, "Sequence", 1),
             generator: lookup_generic(typing, "Generator", 3),
             async_generator: lookup_generic(typing, "AsyncGenerator", 2),
             awaitable: lookup_generic(typing, "Awaitable", 1),
@@ -460,6 +462,10 @@ impl Stdlib {
         Self::apply(&self.mutable_sequence, vec![x])
     }
 
+    pub fn sequence(&self, x: Type) -> ClassType {
+        Self::apply(&self.sequence, vec![x])
+    }
+
     pub fn generator(&self, yield_ty: Type, send_ty: Type, return_ty: Type) -> ClassType {
         Self::apply(&self.generator, vec![yield_ty, send_ty, return_ty])
     }

pyrefly/lib/alt/narrow.rs

@@ -624,6 +624,30 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
                 };
                 self.narrow_length_less_than(ty, len + 1)
             }
+            AtomicNarrowOp::IsSequence => {
+                // Narrow to only sequence types (for sequence pattern matching)
+                self.distribute_over_union(ty, |t| {
+                    if self.is_sequence_for_pattern(t) {
+                        t.clone()
+                    } else {
+                        Type::never()
+                    }
+                })
+            }
+            AtomicNarrowOp::IsNotSequence => {
+                // Narrow to exclude sequence types (negation of sequence pattern)
+                // Note: Any and classes that extend Any must be preserved (not narrowed to Never)
+                // since we can't know at static analysis time whether they're sequences or not
+                self.distribute_over_union(ty, |t| {
+                    if self.behaves_like_any(t) {
+                        t.clone()
+                    } else if self.is_sequence_for_pattern(t) {
+                        Type::never()
+                    } else {
+                        t.clone()
+                    }
+                })
+            }
             AtomicNarrowOp::In(v) => {
                 let exprs = match v {
                     Expr::List(list) => Some(list.elts.clone()),

pyrefly/lib/alt/unwrap.rs

@@ -161,6 +161,41 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
         self.is_subset_eq(ty, &coroutine_ty)
     }
 
+    /// Check if a type is a sequence type for pattern matching purposes (PEP 634).
+    ///
+    /// Per PEP 634, sequence patterns match:
+    /// - Builtins with Py_TPFLAGS_SEQUENCE: list, tuple, range, memoryview,
+    ///   collections.deque, array.array
+    /// - Classes that inherit from collections.abc.Sequence
+    /// - Classes registered as collections.abc.Sequence (cannot detect statically)
+    ///
+    /// Explicitly excluded (even though they're sequences in other contexts):
+    /// - str, bytes, bytearray
+    ///
+    /// Warning: this returns `true` if the type is `Any` or a class that extends `Any`
+    pub fn is_sequence_for_pattern(&self, ty: &Type) -> bool {
+        // Handle special exclusions first - str, bytes, bytearray are NOT sequences
+        // for pattern matching per PEP 634
+        match ty {
+            Type::ClassType(cls)
+                if cls.is_builtin("str")
+                    || cls.is_builtin("bytes")
+                    || cls.is_builtin("bytearray") =>
+            {
+                return false;
+            }
+            Type::LiteralString(_) => return false,
+            // Tuples are always sequences for pattern matching
+            Type::Tuple(_) => return true,
+            _ => {}
+        }
+
+        // Check if the type is a subtype of Sequence[T] for some T
+        let var = self.fresh_var();
+        let sequence_ty = self.stdlib.sequence(var.to_type()).to_type();
+        self.is_subset_eq(ty, &sequence_ty)
+    }
+
     /// Warning: this returns `Some` if the type is `Any` or a class that extends `Any`
     pub fn unwrap_coroutine(&self, ty: &Type) -> Option<(Type, Type, Type)> {
         let yield_ty = self.fresh_var();

pyrefly/lib/binding/narrow.rs

@@ -86,6 +86,10 @@ pub enum AtomicNarrowOp {
     LenGte(Expr),
     LenLt(Expr),
     LenLte(Expr),
+    /// Narrowing for sequence pattern matching - confirms the subject is a sequence type
+    IsSequence,
+    /// Negation of IsSequence - confirms the subject is NOT a sequence type
+    IsNotSequence,
     /// (func, args) for a function call that may narrow the type of its first argument.
     Call(Box<Expr>, Arguments),
     NotCall(Box<Expr>, Arguments),
@@ -164,6 +168,8 @@ impl DisplayWith<ModuleInfo> for AtomicNarrowOp {
             AtomicNarrowOp::LenGte(expr) => write!(f, "LenGte({})", expr.display_with(ctx)),
             AtomicNarrowOp::LenLt(expr) => write!(f, "LenLt({})", expr.display_with(ctx)),
             AtomicNarrowOp::LenLte(expr) => write!(f, "LenLte({})", expr.display_with(ctx)),
+            AtomicNarrowOp::IsSequence => write!(f, "IsSequence"),
+            AtomicNarrowOp::IsNotSequence => write!(f, "IsNotSequence"),
             AtomicNarrowOp::Call(expr, arguments) => write!(
                 f,
                 "Call({}, {})",
@@ -233,6 +239,8 @@ impl AtomicNarrowOp {
             Self::LenLte(v) => Self::LenGt(v.clone()),
             Self::LenLt(v) => Self::LenGte(v.clone()),
             Self::LenNotEq(v) => Self::LenEq(v.clone()),
+            Self::IsSequence => Self::IsNotSequence,
+            Self::IsNotSequence => Self::IsSequence,
             Self::TypeGuard(ty, args) => Self::NotTypeGuard(ty.clone(), args.clone()),
             Self::NotTypeGuard(ty, args) => Self::TypeGuard(ty.clone(), args.clone()),
             Self::TypeIs(ty, args) => Self::NotTypeIs(ty.clone(), args.clone()),
@@ -419,7 +427,8 @@ impl NarrowOps {
             seen.insert(name.clone());
             self.and(name, op, range);
         }
-        // For names present in `self` but not `other`, `And` their narrows with a placeholder
+        // For names present in `self` but not `other`, `And` their narrows with a placeholder.
+        // This ensures that if a sub-pattern can't prove something, we don't claim we proved it.
         let unmerged_names: Vec<_> = self
             .0
             .keys()

pyrefly/lib/binding/pattern.rs

@@ -119,25 +119,38 @@ impl<'a> BindingsBuilder<'a> {
                     value: Number::Int(Int::from(num_non_star_patterns as u64)),
                 });
                 if let Some(subject) = &match_subject {
-                    // Narrow the match subject by length
-                    let narrow_op = if num_patterns == num_non_star_patterns {
+                    // Narrow the match subject by:
+                    // 1. IsSequence - confirms the subject is a sequence type
+                    // 2. Length - confirms the sequence has the right length
+                    let len_narrow_op = if num_patterns == num_non_star_patterns {
                         AtomicNarrowOp::LenEq(synthesized_len)
                     } else {
                         AtomicNarrowOp::LenGte(synthesized_len)
                     };
+
+                    // Create a combined narrowing: IsSequence AND LenXxx
+                    let combined_narrow_op = NarrowOp::And(vec![
+                        NarrowOp::Atomic(None, AtomicNarrowOp::IsSequence),
+                        NarrowOp::Atomic(None, len_narrow_op.clone()),
+                    ]);
+
                     subject_idx = self.insert_binding(
                         Key::PatternNarrow(x.range()),
                         Binding::Narrow(
                             subject_idx,
-                            Box::new(NarrowOp::Atomic(None, narrow_op.clone())),
+                            Box::new(combined_narrow_op.clone()),
                             NarrowUseLocation::Span(x.range()),
                         ),
                     );
-                    narrow_ops.and_all(NarrowOps::from_single_narrow_op_for_subject(
-                        subject.clone(),
-                        narrow_op,
-                        x.range,
-                    ));
+
+                    // Add the combined narrow op to the returned narrow_ops.
+                    // We insert directly instead of using and_all twice to avoid
+                    // Placeholder issues when starting from an empty NarrowOps.
+                    let name = match subject {
+                        NarrowingSubject::Name(name) => name.clone(),
+                        NarrowingSubject::Facets(name, _) => name.clone(),
+                    };
+                    narrow_ops.0.insert(name, (combined_narrow_op, x.range));
                 }
                 let mut seen_star = false;
                 for (i, x) in x.patterns.into_iter().enumerate() {
@@ -240,6 +253,24 @@ impl<'a> BindingsBuilder<'a> {
                         NarrowUseLocation::Span(x.cls.range()),
                     ),
                 );
+
+                // Check if this is a single-positional-slot builtin type
+                // These types (bool, bytearray, bytes, dict, float, frozenset, int, list, set, str, tuple)
+                // bind the entire narrowed value when used with a single positional pattern
+                let is_single_slot_builtin = if let Expr::Name(name) = x.cls.as_ref() {
+                    SpecialExport::new(&name.id)
+                        .map(|se| se.is_single_positional_slot_builtin())
+                        .unwrap_or(false)
+                } else {
+                    false
+                };
+
+                // For single-slot builtins with exactly one positional arg, the pattern matches
+                // all instances of the type, so we don't need a placeholder
+                let is_exhaustive_single_slot = is_single_slot_builtin
+                    && x.arguments.patterns.len() == 1
+                    && x.arguments.keywords.is_empty();
+
                 let mut narrow_ops = if let Some(ref subject) = match_subject {
                     let mut narrow_for_subject = NarrowOps::from_single_narrow_op_for_subject(
                         subject.clone(),
@@ -249,8 +280,10 @@ impl<'a> BindingsBuilder<'a> {
                     // We're not sure whether the pattern matches all possible instances of a class, and
                     // the placeholder prevents negative narrowing from removing the class in later branches.
                     // However, if there are no arguments, it's just an isinstance check, so we don't need
-                    // the placeholder.
-                    if !x.arguments.patterns.is_empty() || !x.arguments.keywords.is_empty() {
+                    // the placeholder. Similarly, single-slot builtins with one positional arg are exhaustive.
+                    if (!x.arguments.patterns.is_empty() || !x.arguments.keywords.is_empty())
+                        && !is_exhaustive_single_slot
+                    {
                         let placeholder = NarrowOps::from_single_narrow_op_for_subject(
                             subject.clone(),
                             AtomicNarrowOp::Placeholder,
@@ -263,30 +296,19 @@ impl<'a> BindingsBuilder<'a> {
                     NarrowOps::new()
                 };
 
-                // Check if this is a single-positional-slot builtin type
-                // These types (bool, bytearray, bytes, dict, float, frozenset, int, list, set, str, tuple)
-                // bind the entire narrowed value when used with a single positional pattern
-                let is_single_slot_builtin = if let Expr::Name(name) = x.cls.as_ref() {
-                    SpecialExport::new(&name.id)
-                        .map(|se| se.is_single_positional_slot_builtin())
-                        .unwrap_or(false)
-                } else {
-                    false
-                };
-
                 // Handle positional patterns
-                if is_single_slot_builtin
-                    && x.arguments.patterns.len() == 1
-                    && x.arguments.keywords.is_empty()
-                {
+                if is_exhaustive_single_slot {
                     // For single-positional-slot builtins with exactly one positional pattern,
                     // bind the pattern directly to the narrowed subject (like MatchAs)
                     let pattern = x.arguments.patterns.into_iter().next().unwrap();
-                    narrow_ops.and_all(self.bind_pattern(
-                        match_subject.clone(),
-                        pattern,
-                        subject_idx,
-                    ));
+                    let inner_narrow_ops =
+                        self.bind_pattern(match_subject.clone(), pattern, subject_idx);
+                    // Only combine if the inner pattern produced narrow ops.
+                    // If it's empty (e.g., a simple MatchAs like `value`), we don't want
+                    // and_all to add Placeholders that would invalidate our outer narrow.
+                    if !inner_narrow_ops.0.is_empty() {
+                        narrow_ops.and_all(inner_narrow_ops);
+                    }
                     return narrow_ops;
                 }
                 // Normal MatchClass handling