Add capture checking annotation to Scala 3 Standard Library (#23688)

<!--
- **Add capture checking to boundary and NonLocalReturns**
- **Add capture-checking test for boundary**
- **Patch DropBreaks to correctly detect boundary blocks**
- **Add capture checking to CommandLineParser**
- **Add capture checking to scala.util**
- **Add capture checking to scala.runtime**
- **Add capture checking to rest of scala.runtime (except
TupledFunctions)**
- **Add capture checking to IArray**
- **[TODO INVESTIGATE] IArray: `Array[AnyRef^{xs*}]` not working, revert
cast**
- **Add capture checking to various scala.* base package files**
- **[TODO FIX] Temporarily drop upper bound of higher-kinded type `F` in
tuple match types**
- **Add capture checking to scala.reflect**
- **[TODO REMOVE] Add TODO list**
- **[TODO EXPLAIN] Add capture checking to Mirror and TupleMirror**
- **Add capture checking to scala.caps**
- **Add capture checking to compiletime.Ops**
- **Add capture checking to stdLibPatches**
- **Add capture checking to annotations**
- **Attempt to capture-check quotes**
- **Track sun.misc.Unsafe in LazyVal implementation**
- **Require Conversion to be pure**
-->

## List of changes

- Capture checking enabled for all files except listed in the next
section
- `boundary` is now capture-checked, preventing `Label` from being
leaked outside of its corresponding `boundary`. Requires #23507.
- `

## Files missing capture checking 

- [ ] `Tuple.scala`, waiting for #23695 to reach the next base version
- [ ] `Mirror.scala`, which requires auto-generated Mirrors to be
compatible with extending one of the `caps.Capability` subtraits.
Currently the plan is to simply ban case classes.

---------

Co-authored-by: Hamza Remmal <[email protected]>

Author: natsukagami

compiler/src/dotty/tools/dotc/cc/Synthetics.scala

@@ -168,4 +168,4 @@ object Synthetics:
         transformCompareCaptures)
   end transform
 
-end Synthetics
+end Synthetics

compiler/src/dotty/tools/dotc/core/StdNames.scala

@@ -531,6 +531,7 @@ object StdNames {
     val isEmpty: N              = "isEmpty"
     val isInstanceOf_ : N       = "isInstanceOf"
     val isInstanceOfPM: N       = "$isInstanceOf$"
+    val isSameLabelAs : N       = "isSameLabelAs"
     val java: N                 = "java"
     val key: N                  = "key"
     val label: N                = "label"

compiler/src/dotty/tools/dotc/transform/DropBreaks.scala

@@ -27,6 +27,8 @@ object DropBreaks:
     /** The number of other references to associated label */
     var otherRefs: Int = 0
 
+    override def toString() = s"LabelUsage($goto, $enclMeth, returnRefs = $returnRefs, otherRefs = $otherRefs)"
+
   private val LabelUsages = new Property.Key[Map[Symbol, LabelUsage]]
   private val ShadowedLabels = new Property.Key[Set[Symbol]]
 
@@ -63,13 +65,22 @@ class DropBreaks extends MiniPhase:
        */
       def unapply(expr: Tree)(using Context): Option[(Symbol, Symbol)] = stripTyped(expr) match
         case If(
-          Apply(Select(Select(ex: Ident, label), eq), (lbl @ Ident(local)) :: Nil),
+          Apply(Select(ex: Ident, isSameLabelAs), (lbl @ Ident(local)) :: Nil),
           Select(ex2: Ident, value),
           Apply(throww, (ex3: Ident) :: Nil))
-        if label == nme.label && eq == nme.eq && local == nme.local && value == nme.value
+        if isSameLabelAs == nme.isSameLabelAs && local == nme.local && value == nme.value
             && throww.symbol == defn.throwMethod
             && ex.symbol == ex2.symbol && ex.symbol == ex3.symbol =>
           Some((ex.symbol, lbl.symbol))
+        case If(
+          Apply(Select(ex: Ident, isSameLabelAs), (lbl @ Ident(local)) :: Nil),
+          Literal(_), // in the case where the value is constant folded
+          Apply(throww, (ex3: Ident) :: Nil))
+        if isSameLabelAs == nme.isSameLabelAs && local == nme.local
+            && throww.symbol == defn.throwMethod
+            && ex.symbol == ex3.symbol
+            && expr.tpe.isSingleton =>
+          Some((ex.symbol, lbl.symbol))
         case _ =>
           None
     end GuardedThrow

compiler/test/dotty/tools/backend/jvm/LabelBytecodeTests.scala

@@ -21,7 +21,7 @@ class LabelBytecodeTests extends DottyBytecodeTest {
       """val local = boundary.Label[Long]()
         |try break(5L)(using local)
         |catch case ex: boundary.Break[Long] @unchecked =>
-        |  if ex.label eq local then ex.value
+        |  if ex.isSameLabelAs(local) then ex.value
         |  else throw ex
       """.stripMargin,
       "Long",

library/src/scala/CanEqual.scala

@@ -1,5 +1,7 @@
 package scala
 
+import language.experimental.captureChecking
+
 import annotation.implicitNotFound
 import scala.collection.{Seq, Set, Map}
 

library/src/scala/CanThrow.scala

@@ -2,6 +2,8 @@ package scala
 import language.experimental.erasedDefinitions
 import annotation.{implicitNotFound, experimental, capability}
 
+import language.experimental.captureChecking
+
 /** A capability class that allows to throw exception `E`. When used with the
  *  experimental.saferExceptions feature, a `throw Ex()` expression will require
  *  a given of class `CanThrow[Ex]` to be available.

library/src/scala/Conversion.scala

@@ -1,5 +1,7 @@
 package scala
 
+import language.experimental.captureChecking
+
 /** A class for implicit values that can serve as implicit conversions.
 *  The implicit resolution algorithm will act as if there existed
 *  the additional implicit definition:
@@ -23,12 +25,13 @@ package scala
 */
 @java.lang.FunctionalInterface
 abstract class Conversion[-T, +U] extends Function1[T, U]:
-  /** Convert value `x` of type `T` to type `U` */
-  def apply(x: T): U
+  self =>
+    /** Convert value `x` of type `T` to type `U` */
+    def apply(x: T): U
 
-  extension (x: T)
-    /** `x.convert` converts a value `x` of type `T` to type `U` */
-    def convert = this(x)
+    extension (x: T)
+      /** `x.convert` converts a value `x` of type `T` to type `U` */
+      def convert = this(x)
 
 object Conversion:
   import annotation.experimental
@@ -44,5 +47,4 @@ object Conversion:
   /** Unwrap an `into` */
   extension [T](x: into[T])
     @experimental def underlying: T = x
-
-end Conversion
+end Conversion

library/src/scala/IArray.scala

@@ -1,6 +1,8 @@
 package scala
 import reflect.ClassTag
 
+import language.experimental.captureChecking
+
 import scala.collection.{LazyZip2, SeqView, Searching, Stepper, StepperShape}
 import scala.collection.immutable.ArraySeq
 import scala.collection.mutable.{ArrayBuilder, Builder}
@@ -92,12 +94,12 @@ object IArray:
 
   /** Builds a new array by applying a function to all elements of this array
     * and using the elements of the resulting collections. */
-  extension [T](arr: IArray[T]) def flatMap[U: ClassTag](f: T => IterableOnce[U]): IArray[U] =
+  extension [T](arr: IArray[T]) def flatMap[U: ClassTag](f: T => IterableOnce[U]^): IArray[U] =
     genericArrayOps(arr).flatMap(f)
 
   /** Flattens a two-dimensional array by concatenating all its rows
     * into a single array. */
-  extension [T](arr: IArray[T]) def flatten[U](using asIterable: T => Iterable[U], ct: ClassTag[U]): IArray[U] =
+  extension [T](arr: IArray[T]) def flatten[U](using asIterable: T => Iterable[U]^, ct: ClassTag[U]): IArray[U] =
     genericArrayOps(arr).flatten
 
   /** Folds the elements of this array using the specified associative binary operator. */
@@ -222,7 +224,7 @@ object IArray:
     genericArrayOps(arr).sortWith(f)
 
   /** Sorts this array according to an Ordering. */
-  extension [T](arr: IArray[T]) def sorted(using math.Ordering[T]): IArray[T] =
+  extension [T](arr: IArray[T]) def sorted(using math.Ordering[T]^): IArray[T] =
     genericArrayOps(arr).sorted
 
   /** Splits this array into a prefix/suffix pair according to a predicate. */
@@ -260,42 +262,42 @@ object IArray:
     def ++[U >: T: ClassTag](suffix: IterableOnce[U]): IArray[U] = genericArrayOps(arr) ++ suffix
     def :+ [U >: T: ClassTag](x: U): IArray[U] = genericArrayOps(arr) :+ x
     def :++ [U >: T: ClassTag](suffix: IArray[U]): IArray[U] = genericArrayOps(arr) :++ suffix
-    def :++ [U >: T: ClassTag](suffix: IterableOnce[U]): IArray[U] = genericArrayOps(arr) :++ suffix
+    def :++ [U >: T: ClassTag](suffix: IterableOnce[U]^): IArray[U] = genericArrayOps(arr) :++ suffix
     def appended[U >: T: ClassTag](x: U): IArray[U] = genericArrayOps(arr).appended(x)
     def appendedAll[U >: T: ClassTag](suffix: IArray[U]): IArray[U] = genericArrayOps(arr).appendedAll(suffix)
-    def appendedAll[U >: T: ClassTag](suffix: IterableOnce[U]): IArray[U] = genericArrayOps(arr).appendedAll(suffix)
-    def collect[U: ClassTag](pf: PartialFunction[T, U]): IArray[U] = genericArrayOps(arr).collect(pf)
-    def collectFirst[U](f: PartialFunction[T, U]): Option[U] = genericArrayOps(arr).collectFirst(f)
+    def appendedAll[U >: T: ClassTag](suffix: IterableOnce[U]^): IArray[U] = genericArrayOps(arr).appendedAll(suffix)
+    def collect[U: ClassTag](pf: PartialFunction[T, U]^): IArray[U] = genericArrayOps(arr).collect(pf)
+    def collectFirst[U](f: PartialFunction[T, U]^): Option[U] = genericArrayOps(arr).collectFirst(f)
     def combinations(n: Int): Iterator[IArray[T]] = genericArrayOps(arr).combinations(n)
     def concat[U >: T: ClassTag](suffix: IArray[U]): IArray[U] = genericArrayOps(arr).concat(suffix)
-    def concat[U >: T: ClassTag](suffix: IterableOnce[U]): IArray[U] = genericArrayOps(arr).concat(suffix)
+    def concat[U >: T: ClassTag](suffix: IterableOnce[U]^): IArray[U] = genericArrayOps(arr).concat(suffix)
     def diff[U >: T](that: IArray[U]): IArray[T] = genericArrayOps(arr).diff(that.toSeq)
-    def diff[U >: T](that: Seq[U]): IArray[T] = genericArrayOps(arr).diff(that)
+    def diff[U >: T](that: Seq[U]^): IArray[T] = genericArrayOps(arr).diff(that)
     def distinct: IArray[T] = genericArrayOps(arr).distinct
     def distinctBy[U](f: T => U): IArray[T] = genericArrayOps(arr).distinctBy(f)
     def startsWith[U >: T](that: IArray[U]): Boolean = genericArrayOps(arr).startsWith(that, 0)
     def startsWith[U >: T](that: IArray[U], offset: Int): Boolean = genericArrayOps(arr).startsWith(that, offset)
-    def startsWith[U >: T](that: IterableOnce[U]): Boolean = genericArrayOps(arr).startsWith(that, 0)
-    def startsWith[U >: T](that: IterableOnce[U], offset: Int): Boolean = genericArrayOps(arr).startsWith(that, offset)
+    def startsWith[U >: T](that: IterableOnce[U]^): Boolean = genericArrayOps(arr).startsWith(that, 0)
+    def startsWith[U >: T](that: IterableOnce[U]^, offset: Int): Boolean = genericArrayOps(arr).startsWith(that, offset)
     def endsWith[U >: T](that: IArray[U]): Boolean = genericArrayOps(arr).endsWith(that)
-    def endsWith[U >: T](that: Iterable[U]): Boolean = genericArrayOps(arr).endsWith(that)
+    def endsWith[U >: T](that: Iterable[U]^): Boolean = genericArrayOps(arr).endsWith(that)
     def groupBy[K](f: T => K): Map[K, IArray[T]] = genericArrayOps(arr).groupBy(f)
     def groupMap[K, U: ClassTag](key: T => K)(f: T => U): Map[K, IArray[U]] = genericArrayOps(arr).groupMap(key)(f)
     def grouped(size: Int): Iterator[IArray[T]] = genericArrayOps(arr).grouped(size)
     def inits: Iterator[IArray[T]] = genericArrayOps(arr).inits
     def intersect[U >: T](that: IArray[U]): IArray[T] = genericArrayOps(arr).intersect(that)
-    def intersect[U >: T](that: Seq[U]): IArray[T] = genericArrayOps(arr).intersect(that)
+    def intersect[U >: T](that: Seq[U]^): IArray[T] = genericArrayOps(arr).intersect(that)
     def lazyZip[U](that: IArray[U]): LazyZip2[T, U, IArray[T]] = genericArrayOps(arr).lazyZip[U](that).asInstanceOf[LazyZip2[T, U, IArray[T]]]
-    def lazyZip[U](that: Iterable[U]): LazyZip2[T, U, IArray[T]] = genericArrayOps(arr).lazyZip[U](that).asInstanceOf[LazyZip2[T, U, IArray[T]]]
+    def lazyZip[U](that: Iterable[U]^): LazyZip2[T, U, IArray[T]] = genericArrayOps(arr).lazyZip[U](that).asInstanceOf[LazyZip2[T, U, IArray[T]]]
     def lengthCompare(len: Int): Int = genericArrayOps(arr).lengthCompare(len)
     def padTo[U >: T: ClassTag](len: Int, elem: U): IArray[U] = genericArrayOps(arr).padTo(len, elem)
     def partitionMap[T1: ClassTag, T2: ClassTag](f: T => Either[T1, T2]): (IArray[T1], IArray[T2]) = genericArrayOps(arr).partitionMap(f)
     def patch[U >: T: ClassTag](from: Int, other: IterableOnce[U], replaced: Int): IArray[U] = genericArrayOps(arr).patch(from, other, replaced)
     def permutations: Iterator[IArray[T]] = genericArrayOps(arr).permutations
     def prepended[U >: T: ClassTag](x: U): IArray[U] = genericArrayOps(arr).prepended(x)
-    def prependedAll[U >: T: ClassTag](prefix: IterableOnce[U]): IArray[U] = genericArrayOps(arr).prependedAll(prefix)
+    def prependedAll[U >: T: ClassTag](prefix: IterableOnce[U]^): IArray[U] = genericArrayOps(arr).prependedAll(prefix)
     def reverseIterator: Iterator[T] = genericArrayOps(arr).reverseIterator
-    def search[U >: T](elem: U)(using Ordering[U]): Searching.SearchResult = arr.toSeq.search(elem)
+    def search[U >: T](elem: U)(using Ordering[U]^): Searching.SearchResult = arr.toSeq.search(elem)
     def search[U >: T](elem: U, from: Int, to: Int)(using Ordering[U]): Searching.SearchResult = arr.toSeq.search(elem, from, to)
     def sizeCompare(that: IArray[Any]): Int = arr.toSeq.sizeCompare(that)
     def sizeCompare(that: Iterable[?]): Int = arr.toSeq.sizeCompare(that)
@@ -312,14 +314,14 @@ object IArray:
     def unzip3[T1, T2, T3](using asTriple: T => (T1, T2, T3), ct1: ClassTag[T1], ct2: ClassTag[T2], ct3: ClassTag[T3]): (IArray[T1], IArray[T2], IArray[T3]) = genericArrayOps(arr).unzip3
     def updated[U >: T: ClassTag](index: Int, elem: U): IArray[U] = genericArrayOps(arr).updated(index, elem)
     def view: SeqView[T] = genericArrayOps(arr).view
-    def withFilter(p: T => Boolean): WithFilter[T] = new WithFilter(p, arr)
+    def withFilter(p: T => Boolean): WithFilter[T]^{p} = new WithFilter(p, arr)
     def zip[U](that: IArray[U]): IArray[(T, U)] = genericArrayOps(arr).zip(that)
-    def zip[U](that: IterableOnce[U]): IArray[(T, U)] = genericArrayOps(arr).zip(that)
+    def zip[U](that: IterableOnce[U]^): IArray[(T, U)] = genericArrayOps(arr).zip(that)
     def zipAll[T1 >: T, U](that: IArray[U], thisElem: T1, thatElem: U): IArray[(T1, U)] = genericArrayOps(arr).zipAll(that, thisElem, thatElem)
-    def zipAll[T1 >: T, U](that: Iterable[U], thisElem: T1, thatElem: U): IArray[(T1, U)] = genericArrayOps(arr).zipAll(that, thisElem, thatElem)
+    def zipAll[T1 >: T, U](that: Iterable[U]^, thisElem: T1, thatElem: U): IArray[(T1, U)] = genericArrayOps(arr).zipAll(that, thisElem, thatElem)
     def zipWithIndex: IArray[(T, Int)] = genericArrayOps(arr).zipWithIndex
 
-  extension [T, U >: T: ClassTag](prefix: IterableOnce[T])
+  extension [T, U >: T: ClassTag](prefix: IterableOnce[T]^)
     def ++:(arr: IArray[U]): IArray[U] = genericArrayOps(arr).prependedAll(prefix)
 
   extension [T, U >: T: ClassTag](prefix: IArray[T])
@@ -444,7 +446,7 @@ object IArray:
    *  @param  it the iterable collection
    *  @return    an array consisting of elements of the iterable collection
    */
-  def from[A : ClassTag](it: IterableOnce[A]): IArray[A] =
+  def from[A : ClassTag](it: IterableOnce[A]^): IArray[A] =
     unsafeFromArray(Array.from(it))
 
   def newBuilder[T](using t: ClassTag[T]): Builder[T, IArray[T]] =
@@ -606,8 +608,8 @@ object IArray:
    *  @param ys an array of AnyRef
    *  @return true if corresponding elements are equal
    */
-   def equals(xs: IArray[AnyRef], ys: IArray[AnyRef]): Boolean =
-    Array.equals(xs.asInstanceOf[Array[AnyRef]], ys.asInstanceOf[Array[AnyRef]])
+   def equals(xs: IArray[AnyRef^], ys: IArray[AnyRef^]): Boolean =
+    Array.equals(xs.asInstanceOf[Array[AnyRef^{xs}]], ys.asInstanceOf[Array[AnyRef^{ys}]])
 
   /** Returns a decomposition of the array into a sequence. This supports
    *  a pattern match like `{ case IArray(x,y,z) => println('3 elements')}`.
@@ -660,7 +662,7 @@ object IArray:
       *  @return       a new array resulting from applying the given collection-valued function
       *                `f` to each element of this array and concatenating the results.
       */
-    def flatMap[U: ClassTag](f: T => IterableOnce[U]): IArray[U] = {
+    def flatMap[U: ClassTag](f: T => IterableOnce[U]^): IArray[U] = {
       val b = IArray.newBuilder[U]
       var i = 0
       while(i < xs.length) {
@@ -671,11 +673,11 @@ object IArray:
       b.result()
     }
 
-    def flatMap[BS, U](f: T => BS)(using asIterable: BS => Iterable[U], m: ClassTag[U]): IArray[U] =
+    def flatMap[BS, U](f: T => BS)(using asIterable: BS => Iterable[U]^, m: ClassTag[U]): IArray[U] =
       flatMap[U](x => asIterable(f(x)))
 
     /** Creates a new non-strict filter which combines this filter with the given predicate. */
-    def withFilter(q: T => Boolean): WithFilter[T] = new WithFilter[T](a => p(a) && q(a), xs)
+    def withFilter(q: T => Boolean): WithFilter[T]^{p, q} = new WithFilter[T](a => p(a) && q(a), xs)
 
   end WithFilter
 

library/src/scala/NamedTuple.scala

@@ -1,6 +1,8 @@
 package scala
 import compiletime.ops.boolean.*
 
+import language.experimental.captureChecking
+
 object NamedTuple:
 
   /** The type to which named tuples get mapped to. For instance,

library/src/scala/PolyFunction.scala

@@ -1,5 +1,7 @@
 package scala
 
+import language.experimental.captureChecking
+
 /* (EXPERIMENTAL) NEW DOCUMENTATION: This should be used when we stabilize erased definitions or other generalize other function types.
  *
  * Marker trait for many (poly) function types.