Special handling of experimental.captureChecking import (#17427)

The question is, how do we introduce capture checking safely. There are
two conflicting requirements:

 - Capture checking should not leak into standard Scala. It should be 
   meaningful only in code that has capture checking explicitly enabled.
- We need to be able to build up libraries that express capture
information
   and that can be consumed from other code. This needs to start with
   the standard library itself.

So far, everything related to capture checking was marked experimental.
This means
all code that refers to a capture checking abstraction in any way
whatsoever needs
to be declared experimental. That clearly does not work for the new use
cases.

But fortunately, capture checking has some properties that enable a
different scheme.
Specifically, a file compiled under capture checking looks like a
completely normal
component (both Tasty and binary) to any other file that uses it and
that is not compiled
with captureChecking. Only when the consumer is also compiled with
capture checking,
the capturing types of the original file will be revealed. The same
holds for binaries.
Capture checking has no effect at all on the binaries that get generated
and all types
and annotations needed for capture checking are erased.

This allows the following more flexible scheme:

- We can turn capture checking on with a setting or language import in
any source file.
   The sources do not have to be @experimental.
- If capture checking is turned on, a number of annotations and other
symbols that
are needed for capture checking and are normally experimental are also
made available.

The important property is that capture checking in one component cannot
poison other normal components. Like
@experimental itself, the whole scheme is transitive. 

With the new scheme we do not need a special exemption for the dotty
package anymore, so the code
implementing the exception is dropped.

Author: odersky

compiler/src/dotty/tools/dotc/config/Feature.scala

@@ -136,16 +136,21 @@ object Feature:
     if !isExperimentalEnabled then
       report.error(em"Experimental $which may only be used with a nightly or snapshot version of the compiler$note", srcPos)
 
+  private def ccException(sym: Symbol)(using Context): Boolean =
+    ccEnabled && defn.ccExperimental.contains(sym)
+
   def checkExperimentalDef(sym: Symbol, srcPos: SrcPos)(using Context) =
     if !isExperimentalEnabled then
-      val symMsg =
-        if sym.hasAnnotation(defn.ExperimentalAnnot) then
-          i"$sym is marked @experimental"
-        else if sym.owner.hasAnnotation(defn.ExperimentalAnnot) then
-          i"${sym.owner} is marked @experimental"
-        else
-          i"$sym inherits @experimental"
-      report.error(em"$symMsg and therefore may only be used in an experimental scope.", srcPos)
+      val experimentalSym =
+        if sym.hasAnnotation(defn.ExperimentalAnnot) then sym
+        else if sym.owner.hasAnnotation(defn.ExperimentalAnnot) then sym.owner
+        else NoSymbol
+      if !ccException(experimentalSym) then
+        val symMsg =
+          if experimentalSym.exists
+          then i"$experimentalSym is marked @experimental"
+          else i"$sym inherits @experimental"
+        report.error(em"$symMsg and therefore may only be used in an experimental scope.", srcPos)
 
   /** Check that experimental compiler options are only set for snapshot or nightly compiler versions. */
   def checkExperimentalSettings(using Context): Unit =

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

@@ -976,6 +976,8 @@ class Definitions {
     @tu lazy val Caps_unsafeBoxFunArg: Symbol = CapsUnsafeModule.requiredMethod("unsafeBoxFunArg")
     @tu lazy val Caps_SealedAnnot: ClassSymbol = requiredClass("scala.caps.Sealed")
 
+  @tu lazy val PureClass: Symbol = requiredClass("scala.Pure")
+
   // Annotation base classes
   @tu lazy val AnnotationClass: ClassSymbol = requiredClass("scala.annotation.Annotation")
   @tu lazy val StaticAnnotationClass: ClassSymbol = requiredClass("scala.annotation.StaticAnnotation")
@@ -1944,6 +1946,14 @@ class Definitions {
       case Some(pkgs) => pkgs.contains(sym.owner)
       case none => false
 
+  /** Experimental definitions that can nevertheless be accessed from a stable
+   *  compiler if capture checking is enabled.
+   */
+  @tu lazy val ccExperimental: Set[Symbol] = Set(
+    CapsModule, CapsModule.moduleClass, PureClass,
+    CapabilityAnnot, RequiresCapabilityAnnot,
+    RetainsAnnot, RetainsByNameAnnot, WithPureFunsAnnot)
+
   // ----- primitive value class machinery ------------------------------------------
 
   class PerRun[T](generate: Context ?=> T) {
@@ -2041,15 +2051,17 @@ class Definitions {
   def isValueSubClass(sym1: Symbol, sym2: Symbol): Boolean =
     valueTypeEnc(sym2.asClass.name) % valueTypeEnc(sym1.asClass.name) == 0
 
-  @tu lazy val specialErasure: SimpleIdentityMap[Symbol, ClassSymbol] =
-    SimpleIdentityMap.empty[Symbol]
-      .updated(AnyClass, ObjectClass)
-      .updated(MatchableClass, ObjectClass)
-      .updated(AnyValClass, ObjectClass)
-      .updated(SingletonClass, ObjectClass)
-      .updated(TupleClass, ProductClass)
-      .updated(NonEmptyTupleClass, ProductClass)
-      .updated(PairClass, ObjectClass)
+  @tu lazy val specialErasure: collection.Map[Symbol, ClassSymbol] =
+    val m = mutable.Map[Symbol, ClassSymbol]()
+    m(AnyClass) = ObjectClass
+    m(MatchableClass) = ObjectClass
+    m(PureClass) = ObjectClass
+    m(AnyValClass) = ObjectClass
+    m(SingletonClass) = ObjectClass
+    m(TupleClass) = ProductClass
+    m(NonEmptyTupleClass) = ProductClass
+    m(PairClass) = ObjectClass
+    m
 
   // ----- Initialization ---------------------------------------------------
 

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

@@ -410,7 +410,7 @@ object TypeErasure {
             val candidates = takeUntil(tp2superclasses)(!_.is(Trait))
 
             // Candidates st "no other common superclass or trait derives from S"
-            // Also, drop `PairClass` since it is not valid after erasue
+            // Also, drop `PairClass` since it is not valid after erasure
             val minimums = candidates.filter { cand =>
               cand != defn.PairClass
               && candidates.forall(x => !x.derivesFrom(cand) || x.eq(cand))

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

@@ -190,12 +190,14 @@ class Erasure extends Phase with DenotTransformer {
   def assertErased(tp: Type, tree: tpd.Tree = tpd.EmptyTree)(using Context): Unit = {
     def isAllowed(cls: Symbol, sourceName: String) =
       tp.typeSymbol == cls && ctx.compilationUnit.source.file.name == sourceName
-    assert(isErasedType(tp) ||
-           isAllowed(defn.ArrayClass, "Array.scala") ||
-           isAllowed(defn.TupleClass, "Tuple.scala") ||
-           isAllowed(defn.NonEmptyTupleClass, "Tuple.scala") ||
-           isAllowed(defn.PairClass, "Tuple.scala"),
-        i"The type $tp - ${tp.toString} of class ${tp.getClass} of tree $tree : ${tree.tpe} / ${tree.getClass} is illegal after erasure, phase = ${ctx.phase.prev}")
+    assert(
+      isErasedType(tp)
+      || isAllowed(defn.ArrayClass, "Array.scala")
+      || isAllowed(defn.TupleClass, "Tuple.scala")
+      || isAllowed(defn.NonEmptyTupleClass, "Tuple.scala")
+      || isAllowed(defn.PairClass, "Tuple.scala")
+      || isAllowed(defn.PureClass, "Pure.scala"),
+      i"The type $tp - ${tp.toString} of class ${tp.getClass} of tree $tree : ${tree.tpe} / ${tree.getClass} is illegal after erasure, phase = ${ctx.phase.prev}")
   }
 }
 

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

@@ -370,8 +370,6 @@ object SymUtils:
       self.hasAnnotation(defn.ExperimentalAnnot)
       || isDefaultArgumentOfExperimentalMethod
       || (!self.is(Package) && self.owner.isInExperimentalScope)
-      || self.topLevelClass.ownersIterator.exists(p =>
-          p.is(Package) && p.owner.isRoot && p.name == tpnme.dotty)
 
     /** The declared self type of this class, as seen from `site`, stripping
     *  all refinements for opaque types.

compiler/src/dotty/tools/dotc/typer/Checking.scala

@@ -784,7 +784,9 @@ object Checking {
     for case imp @ Import(qual, selectors) <- trees do
       def isAllowedImport(sel: untpd.ImportSelector) =
         val name = Feature.experimental(sel.name)
-        name == Feature.scala2macros || name == Feature.erasedDefinitions
+        name == Feature.scala2macros
+        || name == Feature.erasedDefinitions
+        || name == Feature.captureChecking
 
       languageImport(qual) match
         case Some(nme.experimental)

library/src/scala/Pure.scala

@@ -0,0 +1,9 @@
+package scala
+import annotation.experimental
+
+/** A marker trait that declares that all inheriting classes are "pure" in the
+ *  sense that their values retain no capabilities including capabilities needed
+ *  to perform effects. This has formal meaning only under capture checking.
+ */
+@experimental trait Pure:
+  this: Pure =>

library/src/scala/caps.scala

@@ -40,9 +40,3 @@ import annotation.experimental
    */
   @deprecated("The Sealed annotation should not be directly used in source code.\nUse the `sealed` modifier on type parameters instead.")
   class Sealed extends annotation.Annotation
-
-  /** Mixing in this trait forces a trait or class to be pure, i.e.
-   *  have no capabilities retained in its self type.
-   */
-  trait Pure:
-    this: Pure =>

tests/neg-custom-args/captures/selftype.scala

@@ -1,4 +1,4 @@
-@annotation.experimental class C(x: () => Unit) extends caps.Pure // error
+@annotation.experimental class C(x: () => Unit) extends Pure // error
 
-@annotation.experimental class D(@annotation.constructorOnly x: () => Unit) extends caps.Pure // ok
+@annotation.experimental class D(@annotation.constructorOnly x: () => Unit) extends Pure // ok
 

tests/pos-custom-args/no-experimental/cc-experimental.scala

@@ -0,0 +1,11 @@
+package scala.runtime
+
+import language.experimental.captureChecking
+
+object test:
+  type T = Pure
+
+class Foo extends Object, Pure:
+  val x: Pure = ???
+  def foo() = ()
+