scaladoc: support diagnostic expectations in snippets

Author: bracevac

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

@@ -94,4 +94,4 @@ By leveraging capability polymorphism, capability members, and path-dependent ca
 * `Label`s store the free capabilities `C` of the `block` passed to `boundary` in their capability member `Fv`.
 * When suspending on a given label, the suspension handler can capture at most the capabilities that occur freely at the `boundary` that introduced the label. That prevents mentioning nested bound labels.
 
-[Back to Capability Polymorphism](polymorphism.md)
+[Back to Capability Polymorphism](polymorphism.md)

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

@@ -85,7 +85,7 @@ trait LzyList[+A]:
 object LzyList:
   def apply[T](xs: T*): LzyList[T] = ???
 //}
-val xs = usingLogFile { f =>
+val xs = usingLogFile { f => // error // error
   LzyList(1, 2, 3).map { x => f.write(x); x * x }
 }
 ```
@@ -372,7 +372,7 @@ like this:
 ```scala sc:fail sc-compile-with:logfile-checked
 var loophole: () => Unit = () => ()
 usingLogFile { f =>
-  loophole = () => f.write(0)
+  loophole = () => f.write(0) // error
 }
 loophole()
 ```

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

@@ -4,4 +4,4 @@ title: "Capture Checking"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/capture-checking/index.html
 ---
 
-Capture checking is a research project that modifies the Scala type system to track references to capabilities in values.
+Capture checking is a research project that modifies the Scala type system to track references to capabilities in values.

docs/_docs/reference/experimental/capture-checking/checked-exceptions.md

@@ -73,9 +73,9 @@ As with other capability based schemes, one needs to guard against capabilities
 that are captured in results. For instance, here is a problematic use case:
 ```scala sc:fail sc-compile-with:checked-exceptions-base
 def escaped(xs: Double*): (() => Double) throws LimitExceeded =
-  try () => xs.map(f).sum // error: CanThrow escapes into returned closure
+  try () => xs.map(f).sum
   catch case ex: LimitExceeded => () => -1
-val crasher = escaped(1, 2, 10e+11)
+val crasher = escaped(1, 2, 10e+11) // error: CanThrow escapes into returned closure
 crasher()
 ```
 This code needs to be rejected since otherwise the call to `crasher()` would cause

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

@@ -80,5 +80,3 @@ This section lists all variables that appeared in previous diagnostics and their
  - variable `31` has a constant fixed superset `{xs, f}`
  - variable `32` has no dependencies.
 
-
-

docs/_docs/reference/experimental/capture-checking/scoped-capabilities.md

@@ -142,7 +142,7 @@ If any scope refuses to absorb the capability, capture checking fails:
 
 ```scala sc:fail sc-compile-with:scoped-fs-context
 def process(fs: FileSystem^): Unit =
-  val f: () -> Unit = () => fs.read()  // Error: fs cannot flow into {}
+  val f: () -> Unit = () => fs.read()  // error: fs cannot flow into {}
 ```
 
 The closure is declared pure (`() -> Unit`), meaning its local `any` is the empty set. The
@@ -312,14 +312,14 @@ determines the binding structure automatically from where `fresh` appears in the
 
 The rules above establish a key practical distinction when writing function types. Consider:
 
-```scala sc:fail
+```scala sc:fail sc-compile-with:scoped-cc-context
 import caps.fresh
 class A
 class B
 
 def test(): Unit =
-  val f: (x: A^) -> B^{fresh} = ???   // B^{fresh}: existentially bound
-  val g: A^ -> B^             = ???   // B^{any}: enclosing scope's local any
+  val f: (x: A^) -> B^{fresh} = ???  // B^{fresh}: existentially bound
+  val g: A^ -> B^             = ???  // B^{any}: enclosing scope's local any
 
   val _: A^ -> B^        = f   // error: fresh is not in {any}
   val _: A^ -> B^{fresh} = f   // ok
@@ -390,7 +390,7 @@ directly returning a closure that captures it:
 ```scala sc:fail sc-compile-with:scoped-withfile-context
 withFile[() => File^]("test.txt"): f =>
 //       ^^^^^^^^^^^ T = () => File^, i.e., () ->{any} File^{any} for some outer any
-  () => f  // error: We want to return this as () => File^
+  () => f  // error // error // error: We want to return this as () => File^
 ```
 
 The lambda `(f: File^) => () => f` has inferred type:
@@ -414,7 +414,7 @@ into this outer `any`, so the assignment fails.
 Otherwise, allowing widening `∃fresh. () ->{fresh} File^{fresh}` to `() => File^` would let the scoped file escape:
 
 ```scala sc:fail sc-compile-with:scoped-withfile-context
-val escaped: () => File^ = withFile[() => File^]("test.txt")(f => () => f)
+val escaped: () => File^ = withFile[() => File^]("test.txt")(f => () => f) // error // error
 //           ^^^^^^^^^^^ any here is in the outer scope
 escaped().read()  // Use-after-close!
 ```

project/Build.scala

@@ -2137,9 +2137,7 @@ object Build {
               .add(NoLinkWarnings(true))
               .add(NoLinkAssetWarnings(true))
               .add(GenerateAPI(false))
-              .add(SnippetCompiler(List(
-                s"${tempDocsRoot.getAbsolutePath}=compile"
-              )))
+              .add(SnippetCompiler(referenceSnippetCompilerTargets(tempRoot.getAbsolutePath)))
           }
 
           generateDocumentation(config)
@@ -3071,8 +3069,14 @@ object ScaladocConfigs {
     "enums",
     "experimental/capture-checking",
   )
+  def captureCheckingSnippetTestTargets(docsRoot: String) = List(
+    s"$docsRoot/_docs/reference/experimental/capture-checking/basics.md=compile+test",
+    s"$docsRoot/_docs/reference/experimental/capture-checking/checked-exceptions.md=compile+test",
+    s"$docsRoot/_docs/reference/experimental/capture-checking/scoped-capabilities.md=compile+test"
+  )
   def referenceSnippetCompilerTargets(docsRoot: String) =
-    referenceSnippetRelativeRoots.map(path => s"$docsRoot/_docs/reference/$path=compile")
+    referenceSnippetRelativeRoots.map(path => s"$docsRoot/_docs/reference/$path=compile") ++
+      captureCheckingSnippetTestTargets(docsRoot)
 
   lazy val Scala3 = Def.task {
     val stdlib = { // relative path to the stdlib directory ('library/')

scaladoc/src/dotty/tools/scaladoc/site/templates.scala

@@ -76,24 +76,24 @@ case class TemplateFile(
   def isIndexPage() = file.isFile && (file.getName == "index.md" || file.getName == "index.html")
 
   private[site] def resolveInner(ctx: RenderingContext)(using ssctx: StaticSiteContext): ResolvedPage =
-
     lazy val snippetCheckingFunc: SnippetChecker.SnippetCheckingFunc =
       val path = Some(Paths.get(file.getAbsolutePath))
       val pathBasedArg = ssctx.snippetCompilerArgs.get(path)
       val sourceFile = dotty.tools.dotc.util.SourceFile(dotty.tools.io.AbstractFile.getFile(path.get), scala.io.Codec.UTF8)
-      (snippet: SnippetSource, argOverride: Option[SnippetCompilerArg]) => {
-          val arg = argOverride.fold(pathBasedArg)(pathBasedArg.merge(_))
-          val compilerData = SnippetCompilerData(
-            "staticsitesnippet",
-            SnippetCompilerData.Position(configOffset - 1, 0)
-          )
-          ssctx.snippetChecker.checkSnippet(snippet, Some(compilerData), arg, sourceFile, 0).collect {
-              case r: SnippetCompilationResult if !r.isSuccessful =>
-                ssctx.bufferSnippetMessages(r.messages)
-                r
-              case r => r
-          }
-      }
+      (snippet: SnippetSource, argOverride: Option[SnippetCompilerArg]) =>
+        val arg = argOverride.fold(pathBasedArg)(pathBasedArg.merge(_))
+        val compilerData = SnippetCompilerData("staticsitesnippet", SnippetCompilerData.Position(configOffset - 1, 0))
+        val result = ssctx.snippetChecker.checkSnippet(
+          snippet,
+          Some(compilerData),
+          arg,
+          sourceFile,
+          0
+        )
+        result.foreach: r =>
+          if !r.isSuccessful then
+            ssctx.bufferSnippetMessages(r.messages)
+        result
 
     if (ctx.resolving.contains(file.getAbsolutePath))
       throw new RuntimeException(s"Cycle in templates involving $file: ${ctx.resolving}")

scaladoc/src/dotty/tools/scaladoc/snippets/FlexmarkSnippetProcessor.scala

@@ -3,7 +3,6 @@ package snippets
 
 import com.vladsch.flexmark.util.{ast => mdu, sequence}
 import com.vladsch.flexmark.{ast => mda}
-import com.vladsch.flexmark.formatter.Formatter
 import scala.jdk.CollectionConverters._
 
 import dotty.tools.scaladoc.tasty.comments.markdown.ExtendedFencedCodeBlock
@@ -20,7 +19,7 @@ object FlexmarkSnippetProcessor:
     nodes.foldLeft[Map[String, SnippetSource]](Map()) { (snippetMap, node) =>
       val lineOffset = node.getStartLineNumber + preparsed.fold(0)(_.strippedLinesBeforeNo)
       val codeStartLine = lineOffset + SnippetChecker.codeFenceContentLineOffset
-      val info = node.getInfo.toString.split(" ")
+      val info = node.getInfo.toString.split(" ").filter(_.nonEmpty)
       if info.contains("scala") then {
         val flagOverride = info
           .find(_.startsWith("sc:"))

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetChecker.scala

@@ -1,15 +1,10 @@
 package dotty.tools.scaladoc
 package snippets
 
-import dotty.tools.scaladoc.DocContext
-import java.nio.file.Paths
-import java.io.File
-
+import dotty.tools.dotc.config.Settings._
+import dotty.tools.dotc.fromtasty.TastyFileUtil
 import dotty.tools.dotc.util.SourceFile
 import dotty.tools.io.AbstractFile
-import dotty.tools.dotc.fromtasty.TastyFileUtil
-import dotty.tools.dotc.config.Settings._
-import dotty.tools.dotc.config.ScalaSettings
 
 class SnippetChecker(val args: Scaladoc.Args)(using cctx: CompilerContext):
   private val sep = System.getProperty("path.separator")
@@ -18,15 +13,19 @@ class SnippetChecker(val args: Scaladoc.Args)(using cctx: CompilerContext):
     args.tastyFiles
       .map(_.getAbsolutePath())
       .map(AbstractFile.getFile(_))
-      .flatMap(t => try { TastyFileUtil.getClassPath(t) } catch { case e: AssertionError => Seq() })
-      .distinct.mkString(sep),
+      .flatMap(t => try TastyFileUtil.getClassPath(t) catch case _: AssertionError => Seq.empty)
+      .distinct
+      .mkString(sep),
     args.classpath
   ).mkString(sep)
 
-  private val snippetCompilerSettings: Seq[SnippetCompilerSetting[?]] = cctx.settings.userSetSettings(cctx.settingsState).filter(_ != cctx.settings.classpath)
-  .map[SnippetCompilerSetting[?]]( s =>
-    SnippetCompilerSetting(s, s.valueIn(cctx.settingsState))
-  ) :+ SnippetCompilerSetting(cctx.settings.classpath, fullClasspath)
+  private val snippetCompilerSettings: Seq[SnippetCompilerSetting[?]] =
+    val userSetSettings =
+      cctx.settings.userSetSettings(cctx.settingsState)
+        .filter(_ != cctx.settings.classpath)
+        .map[SnippetCompilerSetting[?]]: setting =>
+          SnippetCompilerSetting(setting, setting.valueIn(cctx.settingsState))
+    userSetSettings :+ SnippetCompilerSetting(cctx.settings.classpath, fullClasspath)
 
   private val compiler: SnippetCompiler = SnippetCompiler(snippetCompilerSettings = snippetCompilerSettings)
 
@@ -36,23 +35,31 @@ class SnippetChecker(val args: Scaladoc.Args)(using cctx: CompilerContext):
     arg: SnippetCompilerArg,
     sourceFile: SourceFile,
     sourceColumnOffset: Int
-  ): Option[SnippetCompilationResult] = {
+  ): Option[SnippetCompilationResult] =
     if arg.flag != SCFlags.NoCompile then
       val baseLineOffset = data.fold(0)(_.position.line)
       val baseColumnOffset = data.fold(0)(_.position.column) + sourceColumnOffset
+      val sourceLines = snippet.sourceLines.map(_.map(_ + baseLineOffset))
+      val adjustedSnippet = snippet.copy(
+        sourceLines = sourceLines,
+        outerLineOffset = snippet.outerLineOffset + baseLineOffset
+      )
       val wrapped = WrappedSnippet(
         snippet.snippet,
         data.map(_.packageName),
         snippet.outerLineOffset + baseLineOffset,
         baseColumnOffset,
-        snippet.sourceLines.map(_.map(_ + baseLineOffset))
+        sourceLines
       )
-      Some(compiler.compile(wrapped, arg, sourceFile))
+      Some(compiler.compile(
+        adjustedSnippet,
+        wrapped,
+        arg,
+        sourceFile
+      ))
     else
       None
 
-  }
-
 object SnippetChecker:
   // The first line of snippet content is two lines below the opening code fence.
   val codeFenceContentLineOffset = 2