[2.x] fix: Resolve virtual file refs in scaladoc options (#8768)

When `semanticdbEnabled := true` is set on Scala 2.x projects, the
`doc` task fails because `${CSR_CACHE}` placeholders in scalacOptions
(specifically the `-Xplugin:` path for the semanticdb compiler plugin)
are not resolved before being passed to Scaladoc.

This fix resolves virtual file references (containing $) in
scalacOptions before passing them to the Scaladoc bridge, matching
what zinc's MixedAnalyzingCompiler already does for compilation
(see sbt/zinc#1545).

Fixes sbt/sbt#8740

Generated-by: GitHub Copilot (Claude Opus 4.6)

main/src/main/scala/sbt/Defaults.scala

@@ -2064,6 +2064,13 @@ object Defaults extends BuildCommon {
                 if (ScalaArtifacts.isScala3(sv)) Opts.doc.externalAPIScala3(xapisFiles)
                 else Opts.doc.externalAPI(xapisFiles)
               val options = sOpts ++ externalApiOpts
+              def convertVfRef(value: String): String =
+                if !value.contains("$") then value
+                else converter.toPath(VirtualFileRef.of(value)).toString
+              val resolvedOptions = options.map { x =>
+                if !x.contains("$") then x
+                else x.split(":").map(_.split(",").map(convertVfRef).mkString(",")).mkString(":")
+              }
               val scalac = cs.scalac match
                 case ac: AnalyzingCompiler => ac.onArgs(Compiler.exported(s, "scaladoc"))
               val docSrcFiles = if ScalaArtifacts.isScala3(sv) then tFiles else srcs
@@ -2077,7 +2084,7 @@ object Defaults extends BuildCommon {
                   cp.map(converter.toPath).map(new sbt.internal.inc.PlainVirtualFile(_)),
                   converter,
                   out.toPath(),
-                  options,
+                  resolvedOptions,
                   maxErrors.value,
                   s.log,
                 )

sbt-app/src/sbt-test/project/semanticdb-doc/build.sbt

@@ -0,0 +1,2 @@
+semanticdbEnabled := true
+scalaVersion := "2.12.21"

sbt-app/src/sbt-test/project/semanticdb-doc/src/main/scala/A.scala

@@ -0,0 +1 @@
+object A

sbt-app/src/sbt-test/project/semanticdb-doc/test

@@ -0,0 +1,2 @@
+# scaladoc should succeed when semanticdbEnabled is true
+> doc