Allow global language imports in REPL and snippet compiler (scala#25458)

Previously, `import language.experimental.captureChecking` (and related
global language imports) were rejected in the REPL and snippet compiler
because they appeared in nested scopes rather than at the toplevel.

This change takes a structural approach to fix both contexts:

- REPL: Forward `outermost` through `blockStatSeq` in Interactive mode
so the parser treats REPL-level imports as toplevel. After a successful
compile, propagate global language imports to `rootCtx` as `-language:`
settings so subsequent inputs can parse CC syntax (e.g. `^`).

- Snippet compiler: Extract global language imports from snippet body
and place them before the `object Snippet {}` wrapper, making them
genuine toplevel imports.

Fixes scala#16250

## How much have your relied on LLM-based tools in this contribution?

Used Claude extensively to analyze the problem and iterate on the
solution.

## How was the solution tested?

There are REPL and snippet compiler tests. I also verified manually
within the REPL that the top-level CC import works. 
Updated some snippets in the CC language ref to verify that the snippet
compilation
works as well.

Author: bracevac

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

@@ -248,10 +248,17 @@ object Feature:
   def isExperimentalEnabledByImport(using Context): Boolean =
     experimentalAutoEnableFeatures.exists(enabledByImport)
 
-  /** Handle language import `import language.<prefix>.<imported>` if it is one
-   *  of the global imports `pureFunctions` or `captureChecking`. In this case
-   *  make the compilation unit's and current run's fields accordingly.
-   *  @return true iff import that was handled
+  /** Global language imports that affect parsing and must be handled specially.
+   *  These need per-compilation-unit flags (set in `handleGlobalLanguageImport`)
+   *  and also require propagation to rootCtx in the REPL and hoisting in the
+   *  snippet compiler so they take effect across inputs (i16250).
+   */
+  val globalLanguageImports: Set[TermName] =
+    Set(pureFunctions, captureChecking, separationChecking, safe)
+
+  /** Handle a global language import `import language.<prefix>.<imported>`.
+   *  Sets the compilation unit's and current run's fields accordingly.
+   *  @return true iff the import was handled
    */
   def handleGlobalLanguageImport(prefix: TermName, imported: Name)(using Context): Boolean =
     QualifiedName(prefix, imported.asTermName) match

compiler/src/dotty/tools/dotc/parsing/Parsers.scala

@@ -3937,15 +3937,7 @@ object Parsers {
           in.languageImportContext = in.languageImportContext.importContext(imp, NoSymbol)
           for case ImportSelector(id @ Ident(imported), EmptyTree, _) <- selectors do
             if Feature.handleGlobalLanguageImport(prefix, imported) && !outermost then
-              val desc =
-                if ctx.mode.is(Mode.Interactive) then
-                  "not allowed in the REPL"
-                else "only allowed at the toplevel"
-              val hint =
-                if ctx.mode.is(Mode.Interactive) then
-                  f"\nTo use this language feature, include the flag `-language:$prefix.$imported` when starting the REPL"
-                else ""
-              syntaxError(em"this language import is $desc$hint", id.span)
+              syntaxError(em"this language import is only allowed at the toplevel", id.span)
             if allSourceVersionNames.contains(imported) && prefix.isEmpty then
               if !outermost then
                 syntaxError(em"source version import is only allowed at the toplevel", id.span)
@@ -5023,7 +5015,7 @@ object Parsers {
       while
         var empty = false
         if (in.token == IMPORT)
-          stats ++= importClause()
+          stats ++= importClause(outermost = outermost && ctx.mode.is(Mode.Interactive))
         else if (isExprIntro)
           stats += expr(Location.InBlock)
         else if in.token == IMPLICIT && !in.inModifierPosition() then

compiler/src/dotty/tools/dotc/printing/PlainPrinter.scala

@@ -329,7 +329,8 @@ class PlainPrinter(_ctx: Context) extends Printer {
               ~ Str("R").provided(printDebug)
             else toText(tpe)
           case annot: CaptureAnnotation =>
-            toTextLocal(tpe) ~ "^" ~ toText(annot)
+            val boxText: Text = Str("box ") `provided` annot.boxed && ccVerbose
+            toTextCapturing(tpe, annot.refs, boxText)
           case _ if defn.SilentAnnots.contains(annot.symbol) && !printDebug =>
             toText(tpe)
           case _ =>
@@ -567,6 +568,25 @@ class PlainPrinter(_ctx: Context) extends Printer {
         (tparamStr, bounds.derivedTypeBounds(loRhs, hiRhs))
   end decomposeLambdas
 
+  /** Is this a capture variable's bounds? i.e. lo and hi are both CapSet-based. */
+  private def isCaptureVarBounds(lo: Type, hi: Type): Boolean =
+    lo.derivesFrom(defn.Caps_CapSet) && (hi match
+      case CapturingType(parent, _) => parent.derivesFrom(defn.Caps_CapSet)
+      case hi => hi.derivesFrom(defn.Caps_CapSet))
+
+  /** Print capture variable bounds using `^` syntax.
+   *  Plain CapSet lower bound and universal upper bound are elided.
+   */
+  private def toTextCaptureVarBounds(lo: Type, hi: Type): Text =
+    val loText = lo match
+      case CapturingType(_, refs) => " >: " ~ toTextCaptureSet(refs)
+      case _ => Text() // plain CapSet = trivial lower bound
+    val hiText = hi match
+      case CapturingType(_, refs) if isElidableUniversal(refs) => Text() // trivial upper bound
+      case CapturingType(_, refs) => " <: " ~ toTextCaptureSet(refs)
+      case _ => Text()
+    Str("^") ~ loText ~ hiText
+
   /** String representation of a definition's type following its name */
   protected def toTextRHS(tp: Type, isParameter: Boolean = false): Text = controlled {
     homogenize(tp) match {
@@ -575,6 +595,8 @@ class PlainPrinter(_ctx: Context) extends Printer {
         val binder = rhs match
           case tp: AliasingBounds =>
             " = " ~ toText(tp.alias)
+          case TypeBounds(lo, hi) if !printDebug && Feature.ccEnabledSomewhere && isCaptureVarBounds(lo, hi) =>
+            toTextCaptureVarBounds(lo, hi)
           case TypeBounds(lo, hi) =>
             (if lo.isExactlyNothing then Text() else " >: " ~ toText(lo))
             ~ (if hi.isExactlyAny || (!printDebug && hi.isFromJavaObject) then Text() else " <: " ~ toText(hi))

compiler/src/dotty/tools/dotc/printing/RefinedPrinter.scala

@@ -1176,6 +1176,10 @@ class RefinedPrinter(_ctx: Context) extends PlainPrinter(_ctx) {
   protected override def annotText(sym: Symbol): Text =
     if sym == defn.ConsumeAnnot then "consume" else super.annotText(sym)
 
+  protected override def specialAnnotText(sym: ClassSymbol, tp: Type): Text =
+    if sym == defn.ConsumeAnnot then keywordText("consume ").provided(tp.hasAnnotation(sym))
+    else super.specialAnnotText(sym, tp)
+
   protected def modText(mods: untpd.Modifiers, sym: Symbol, kw: String, isType: Boolean): Text = { // DD
     val suppressKw = if (enclDefIsClass) mods.isAllOf(LocalParam) else mods.is(Param)
     var flagMask =

docs/_docs/reference/experimental/capture-checking/basics.md

@@ -7,6 +7,7 @@ nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/capture-che
 ## Introduction
 
 ```scala sc-hidden sc-name:cc-context
+import language.experimental.captureChecking
 import caps.*
 ```
 

docs/_docs/reference/experimental/capture-checking/mutability.md

@@ -4,6 +4,11 @@ title: "Stateful Capabilities"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/capture-checking/mutability.html
 ---
 
+```scala sc-hidden sc-name:mut-context
+import language.experimental.captureChecking
+import language.experimental.separationChecking
+```
+
 ## Introduction
 
 An important class of effects represents accesses to mutable variables and mutable data structures. This is intimately tied with the concept of _program state_. Stateful capabilities are capabilities that allow to consult and change the program state.
@@ -13,7 +18,7 @@ We distinguish two kinds of accesses: full access that allows state changes and
 A common kind of stateful capabilities represent mutable variables that can be read and written.
 These mutable data structures are expressed with the marker trait `caps.Mutable`.
 For instance, consider a simple reference cell:
-```scala
+```scala sc-compile-with:mut-context
 import caps.Mutable
 
 class Ref[T](init: T) extends Mutable:
@@ -46,7 +51,7 @@ These classes typically contain mutable variables and/or _update methods_.
 Update methods are declared using a new soft modifier `update`.
 
 **Example:**
-```scala
+```scala sc-compile-with:mut-context
 //{
 import caps.*
 //}

docs/_docs/reference/experimental/capture-checking/safe.md

@@ -12,7 +12,11 @@ Full Scala 3 has elements that are incompatible with capability safety, such as
 
 To distinguish between these two usage modes, there is a safe language subset that can be specified with a command-line option or a language import:
 ```scala sc:nocompile
-  import language.experimental.safe
+import language.experimental.safe
+```
+
+```scala sc-hidden sc-name:safe-context
+import language.experimental.safe
 ```
 
 It makes sense for agentic tooling to subject all compilations of agent-generated code to be compiled in _safe mode_ using this language import. Safe mode imposes the following restrictions:

project/Build.scala

@@ -2003,10 +2003,7 @@ object Build {
             .add(SnippetCompiler(List(
               s"${docs.getAbsolutePath}/_docs/reference/new-types=compile",
               s"${docs.getAbsolutePath}/_docs/reference/enums=compile",
-              s"$ccDocs=compile|-language:experimental.captureChecking",
-              s"$ccDocs/separation-checking=compile|-language:experimental.captureChecking|-language:experimental.separationChecking",
-              s"$ccDocs/mutability=compile|-language:experimental.captureChecking|-language:experimental.separationChecking",
-              s"$ccDocs/safe=compile|-language:experimental.safe",
+              s"$ccDocs=compile",
             )))
         }
 
@@ -2965,10 +2962,7 @@ object ScaladocConfigs {
         snippetCompilerTargets(s"$stdlib/src") ++ List(
         "docs/_docs/reference/new-types=compile",
         "docs/_docs/reference/enums=compile",
-        "docs/_docs/reference/experimental/capture-checking=compile|-language:experimental.captureChecking",
-        "docs/_docs/reference/experimental/capture-checking/separation-checking=compile|-language:experimental.captureChecking|-language:experimental.separationChecking",
-        "docs/_docs/reference/experimental/capture-checking/mutability=compile|-language:experimental.captureChecking|-language:experimental.separationChecking",
-        "docs/_docs/reference/experimental/capture-checking/safe=compile|-language:experimental.safe",
+        "docs/_docs/reference/experimental/capture-checking=compile",
       )))
       .add(SiteRoot("docs"))
       .add(ApiSubdirectory(true))

repl/src/dotty/tools/repl/ReplDriver.scala

@@ -13,7 +13,7 @@ import dotc.config.CommandLineParser.tokenize
 import dotc.config.Properties.{javaVersion, javaVmName, simpleVersionString}
 import dotc.core.Contexts.*
 import dotc.core.Decorators.*
-import dotc.core.Phases.{unfusedPhases, typerPhase}
+import dotc.core.Phases.{unfusedPhases, typerPhase, checkCapturesPhase}
 import dotc.core.Denotations.Denotation
 import dotc.core.Flags.*
 import dotc.core.Mode
@@ -32,7 +32,7 @@ import dotc.reporting.Diagnostic
 import dotc.util.Spans.Span
 import dotc.util.{SourceFile, SourcePosition}
 import dotc.{CompilationUnit, Driver}
-import dotc.config.CompilerCommand
+import dotc.config.{CompilerCommand, Feature}
 import dotty.tools.io.{AbstractFileClassLoader => _, *}
 import dotty.tools.repl.ScalaClassLoader.*
 
@@ -304,6 +304,25 @@ class ReplDriver(settings: Array[String],
     state.copy(context = run.runContext)
   }
 
+  /** Add a language feature to rootCtx so subsequent parses and compilations see it. */
+  private def enableLanguageFeature(feature: String): Unit =
+    val summary = rootCtx.settings.processArguments(List(s"-language:$feature"), true, rootCtx.settingsState)
+    rootCtx = rootCtx.fresh.setSettings(summary.sstate)
+
+  /** Detect global language imports in parsed trees and enable them in rootCtx
+   *  so subsequent parses and compilations see them (i16250).
+   */
+  private def propagateLanguageImports(trees: List[untpd.Tree]): Unit =
+    import dotc.core.NameKinds.QualifiedName
+    for case untpd.Import(expr, selectors) <- trees do
+      untpd.languageImport(expr) match
+        case Some(prefix) =>
+          for case untpd.ImportSelector(untpd.Ident(imported), untpd.EmptyTree, _) <- selectors do
+            val qual = QualifiedName(prefix, imported.asTermName)
+            if Feature.globalLanguageImports.contains(qual) then
+              enableLanguageFeature(qual.toString)
+        case _ =>
+
   private def stripBackTicks(label: String) =
     if label.startsWith("`") && label.endsWith("`") then
       label.drop(1).dropRight(1)
@@ -340,6 +359,7 @@ class ReplDriver(settings: Array[String],
         state
 
       case parsed: Parsed if parsed.trees.nonEmpty =>
+        propagateLanguageImports(parsed.trees)
         compile(parsed, state)
 
       case SyntaxErrors(_, errs, _) =>
@@ -422,7 +442,7 @@ class ReplDriver(settings: Array[String],
   private def renderDefinitions(tree: tpd.Tree, newestWrapper: Name)(using state: State): (State, Seq[Diagnostic]) = {
     given Context = state.context
 
-    def resAndUnit(denot: Denotation) = {
+    def resAndUnit(denot: Denotation)(using Context) = {
       import scala.util.{Success, Try}
       val sym = denot.symbol
       val name = sym.name.show
@@ -433,7 +453,7 @@ class ReplDriver(settings: Array[String],
       name.startsWith(str.REPL_RES_PREFIX) && hasValidNumber && sym.info == defn.UnitType
     }
 
-    def extractAndFormatMembers(symbol: Symbol): (State, Seq[Diagnostic]) = if (tree.symbol.info.exists) {
+    def extractAndFormatMembers(symbol: Symbol)(using Context): (State, Seq[Diagnostic]) = if (tree.symbol.info.exists) {
       val info = symbol.info
       val defs =
         info.bounds.hi.finalResultType
@@ -484,13 +504,17 @@ class ReplDriver(settings: Array[String],
     def isSyntheticCompanion(sym: Symbol) =
       sym.is(Module) && sym.is(Synthetic)
 
-    def typeDefs(sym: Symbol): Seq[Diagnostic] = sym.info.memberClasses
+    def typeDefs(sym: Symbol)(using Context): Seq[Diagnostic] = sym.info.memberClasses
       .collect {
         case x if !isSyntheticCompanion(x.symbol) && !x.symbol.name.isReplWrapperName =>
           rendering.renderTypeDef(x)
       }
 
-    atPhase(typerPhase.next) {
+    val renderPhase =
+      if Feature.ccEnabledSomewhere && checkCapturesPhase.exists
+      then checkCapturesPhase
+      else typerPhase.next
+    atPhase(renderPhase) {
       // Display members of wrapped module:
       tree.symbol.info.memberClasses
         .find(_.symbol.name == newestWrapper.moduleClassName)