Cross-build for sbt 1.x and sbt 2.x (#209)

* Cross-build for sbt 1.x and sbt 2.x

sbt 2.0.0 introduces several breaking API changes for plugins (built with
Scala 3): apiMappings is now Map[HashedVirtualFileRef, URI] instead of
Map[File, URL], the dependency classpath holds Attributed[HashedVirtualFileRef],
the ModuleID is stored as a JSON string under a StringAttributeKey, inTask was
removed, and task results are cached by default.

This change makes the plugin cross-build for both sbt 1.x (Scala 2.12) and
sbt 2.x (Scala 3):

- build.sbt: crossScalaVersions = [2.12.20, 3.8.4] with pluginCrossBuild /
  sbtVersion selecting sbt 1.12.11 / 2.0.0 per Scala binary version.
- Most of the sbt 2.x divergence is absorbed by sbt2-compat (PluginCompat:
  FileRef, moduleIDStr, parseModuleIDStrAttribute, Def.uncached), keeping the
  rule sources shared.
- A small version-specific Compat object (src/main/scala-2.12, src/main/scala-3)
  holds only what sbt2-compat cannot unify: the api doc URL type (URL vs URI),
  the synthetic bootstrap classpath key (which cannot go through fileConverter),
  and the `.extract` adapter (an implicit Extractor on Scala 2.12; a
  PartialFunction-returning extension on Scala 3, where a PartialFunction is
  already a valid pattern).
- breakOut / inTask removed in favour of cross-version-friendly equivalents.
- CI matrix and scripted test assertions updated for both sbt versions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Scope all task-body reads to config / doc after dropping inConfig/inTask

Replacing `inConfig(config) { inTask(doc) { ... } }` with explicit
`config / doc / key` settings also changed the scope in which the `.value`
reads inside the task bodies resolve. Only `apiMappings` and
`dependencyClasspath` had been re-scoped; `apiMappingRules`,
`bootstrapJavadocURL` and `streams` were left unscoped and resolved in the
default/global scope instead of `config / doc`, so a user override such as
`Compile / doc / apiMappingRules += ...` would no longer be picked up.

Re-scope every read in both task bodies to `config / doc`, matching the
original inConfig/inTask behavior.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Reuse the extractor library via a private Compat.Extractor

Make `.extract` opt-in and keep it out of `com.thoughtworks`:

- `Compat` is now `private[sbtApiMappings]` and exposes a nested `Extractor`
  member, imported with `import Compat.Extractor._`. This avoids leaking the
  `.extract` implicit onto every function via `import Compat._`.
- On Scala 2.12, `Compat.Extractor` is `val Extractor = com.thoughtworks.Extractor`,
  i.e. a re-export of the `com.thoughtworks.extractor` library (added back as a
  Scala-2.12-only dependency). The library is reused as-is; its `sealed`
  `private[thoughtworks]` traits cannot be wrapped, but a plain `val` alias
  re-exports the object so its implicits come in through `import Compat.Extractor._`.
- On Scala 3 `Compat.Extractor` is an `object` whose `extension` turns a
  function/partial function into a `PartialFunction` (already a valid pattern on
  Scala 3). No `com.thoughtworks.Extractor` shim, so the package is not polluted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix scripted test fixtures for sbt 2.x

CI on sbt 2.0.0 surfaced two sbt-1-isms in the test fixtures (keep-api-url
already passed; only all-libraries and jdk failed):

- all-libraries/test used the sbt 0.13 colon command syntax
  `+compile:doc::apiMappings`, which sbt 2.x rejects ("Expected ';'"). Switch to
  slash syntax `+Compile / doc / apiMappings`.
- jdk/build.sbt read `sLog.value` in its check/fgrep/jgrep tasks. On sbt 2.x a
  Logger has no `HashWriter`, so reading it as a task input breaks the default
  task caching ("given evidence sjsonnew.HashWriter[...Logger...] is not found").
  Use `println` for the diagnostic output instead — no task input needed. (The
  `Map[HashedVirtualFileRef, URI]` from apiMappings does have a HashWriter, as
  the passing keep-api-url test shows, so only the Logger was the problem.)

Both changes are also valid on sbt 1.x.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Run only keep-api-url scripted test under sbt 2.x

The all-libraries and jdk scripted fixtures use very old Scala versions
(2.12.10 / 2.13.1 / 2.13.8) whose sbt 2.x Zinc compiler bridges fail to build,
and they assert sbt 1.x-specific behaviour (the scaladoc `target/api` output
path and the autoAPIMappings scala-library URL), which differs on sbt 2.x.

Until those fixtures are modernised, gate them to sbt 1.x: under sbt 2.x run
only keep-api-url (which exercises the full rule pipeline end-to-end), while
sbt 1.x keeps running all three. The sbt 2.x code path is also covered by
`+compile` / `+Test/compile`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Make all-libraries and jdk scripted tests pass on both sbt versions

Modernise the two fixtures so they run under both sbt 1.x and sbt 2.x, and
remove the temporary sbt-2.x gating:

- Bump their Scala versions (2.12.10 / 2.13.1 / 2.13.8 -> 2.12.20 / 2.13.16) so
  the sbt 2.x Zinc compiler bridge builds, and scalacheck to 1.18.1.
- all-libraries: the scala-library and scalacheck api doc URLs differ by sbt
  version (autoAPIMappings reads the POM `apiURL` on sbt 1.x — e.g.
  https://www.scala-lang.org/api/<v>/ and https://www.javadoc.io/doc/<...> — while
  on sbt 2.x this plugin's own rules provide http://scala-lang.org/files/archive/
  api/<v>/ and https://javadoc.io/page/<...>). Assert leniently (host + version)
  so one test covers both.
- jdk: the scaladoc output directory is `target/api` on sbt 1.x but
  `target/out/jvm/<...>/api` on sbt 2.x, so the hard-coded `$ exists` / `jgrep`
  path no longer works. Move the file checks into a `checkDoc` task that locates
  the directory via `Compile / doc / target`.

Verified locally (JDK 17): `++2.12.20 test` and `++3.8.4 test` both run all three
scripted tests plus the unit test green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Rename Compat to Compatibility

Use the full word `Compatibility` instead of the abbreviation `Compat` for the
plugin's internal version-specific object. (sbt2-compat's `PluginCompat` /
`sbtcompat` are unchanged.)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Rename Compatibility.DocUrl to Compatibility.URL

`URL` reads better than `DocUrl` for the api-doc value type of the `apiMappings`
map. The alias resolves to `java.net.URL` on sbt 1.x and `java.net.URI` on
sbt 2.x.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: Atry

.github/workflows/scala.yml

@@ -15,24 +15,31 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        scala:
-          - 2.12.20
-        distribution:
-          - temurin
-        java:
-          - 8
-          - 11
-          - 17
+        # Scala 2.12 builds the sbt 1.x plugin, Scala 3 builds the sbt 2.x plugin.
+        # sbt 2.x requires JDK 17 or later, so Scala 3 is not tested on Java 8/11.
+        include:
+          - scala: 2.12.20
+            java: 8
+            publish: true
+          - scala: 2.12.20
+            java: 11
+          - scala: 2.12.20
+            java: 17
+          - scala: 3.8.4
+            java: 17
+            publish: true
+          - scala: 3.8.4
+            java: 21
 
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0 # Need the git history for sbt-dynver to determine the version
-      - name: Set up JDK 11
+      - name: Set up JDK
         uses: actions/setup-java@v3
         with:
           java-version: ${{ matrix.java }}
-          distribution: ${{ matrix.distribution }}
+          distribution: temurin
       - uses: sbt/setup-sbt@v1
       - name: Cache SBT
         uses: actions/cache@v3
@@ -51,5 +58,5 @@ jobs:
       - name: Publish to Maven Central Repository
         env:
           GITHUB_PERSONAL_ACCESS_TOKEN: ${{secrets.PERSONAL_ACCESS_TOKEN}}
-        if: ${{ env.GITHUB_PERSONAL_ACCESS_TOKEN != '' && github.event_name != 'pull_request' && matrix.java == 8 }}
+        if: ${{ env.GITHUB_PERSONAL_ACCESS_TOKEN != '' && github.event_name != 'pull_request' && matrix.publish }}
         run: sbt ${{matrix.sbt-args}} ++${{ matrix.scala }} publishSigned sonaRelease

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
     "files.watcherExclude": {
-        "**/target": true
+        "**/target/**": true
     }
 }

README.md

@@ -35,7 +35,7 @@ This plugin resolves the problem.
 addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "latest.release")
 ```
 
-Note that sbt-api-mappings 1.x requires sbt 0.13.x, sbt-api-mappings 2.x requires sbt 1.x.
+Note that sbt-api-mappings 1.x requires sbt 0.13.x, sbt-api-mappings 2.x requires sbt 1.x, and sbt-api-mappings 3.x is cross-built for both sbt 1.x and sbt 2.x.
 
 ### Step 2: Reload the Sbt configuration:
 

build.sbt

@@ -14,7 +14,35 @@ startYear := Some(2015)
 
 scalacOptions += "-deprecation"
 
-libraryDependencies += "com.thoughtworks.extractor" %% "extractor" % "2.1.3"
+val scala212 = "2.12.20"
+
+val scala3 = "3.8.4"
+
+// Cross-build for both sbt 1.x (Scala 2.12) and sbt 2.x (Scala 3).
+crossScalaVersions := Seq(scala212, scala3)
+
+scalaVersion := scala212
+
+pluginCrossBuild / sbtVersion := {
+  scalaBinaryVersion.value match {
+    case "2.12" => "1.12.11" // sbt 1.x
+    case _      => "2.0.0" // sbt 2.x
+  }
+}
+
+// Compatibility layer that exposes a subset of the sbt 2 API using sbt 1 API,
+// so most of the plugin sources can be shared across both sbt versions.
+addSbtPlugin("com.github.sbt" % "sbt2-compat" % "0.1.0")
+
+// `.extract` pattern support, reused via `Compat.Extractor`. Only published for
+// Scala 2.12; on Scala 3 a PartialFunction is already a valid pattern, so the
+// Scala 3 `Compat.Extractor` provides an equivalent extension instead.
+libraryDependencies ++= {
+  if (scalaBinaryVersion.value == "2.12")
+    Seq("com.thoughtworks.extractor" %% "extractor" % "2.1.3")
+  else
+    Seq.empty
+}
 
 libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.20" % "test"
 

src/main/scala-2.12/com/thoughtworks/sbtApiMappings/Compatibility.scala

@@ -0,0 +1,27 @@
+package com.thoughtworks.sbtApiMappings
+
+import java.io.File
+
+import sbt._
+import sbtcompat.PluginCompat
+
+/** sbt 1.x specific bindings: only the pieces that genuinely differ from sbt
+  * 2.x. Everything that sbt2-compat can express uniformly is plain shared code.
+  */
+private[sbtApiMappings] object Compatibility {
+
+  /** The value type of the `apiMappings` map. */
+  type URL = java.net.URL
+
+  /** Convert a real [[java.io.File]] (e.g. a JDK bootstrap classpath jar) to an
+    * `apiMappings` key. On sbt 1.x the key is already a `File`.
+    */
+  def fileToDocKey: Def.Initialize[Task[File => PluginCompat.FileRef]] =
+    Def.task { (file: File) => file }
+
+  /** The `.extract` pattern support, opted into with
+    * `import Compatibility.Extractor._`. On Scala 2.12 it simply re-exports the
+    * `com.thoughtworks.extractor` library.
+    */
+  val Extractor = com.thoughtworks.Extractor
+}

src/main/scala-3/com/thoughtworks/sbtApiMappings/Compatibility.scala

@@ -0,0 +1,38 @@
+package com.thoughtworks.sbtApiMappings
+
+import java.io.File
+
+import sbt._
+import sbtcompat.PluginCompat
+import xsbti.HashedVirtualFileRef
+
+/** sbt 2.x specific bindings: only the pieces that genuinely differ from sbt
+  * 1.x. Everything that sbt2-compat can express uniformly is plain shared code.
+  */
+private[sbtApiMappings] object Compatibility:
+
+  /** The value type of the `apiMappings` map (a `java.net.URI` on sbt 2.x). */
+  type URL = java.net.URI
+
+  /** Convert a real [[java.io.File]] (e.g. a JDK bootstrap classpath jar) to an
+    * `apiMappings` key.
+    *
+    * The bootstrap class loader entries (e.g. the synthetic `/modules/java.base`
+    * on Java 9+) are not real files, so they cannot go through `fileConverter`
+    * (which validates that the file exists). Build the reference directly.
+    */
+  def fileToDocKey: Def.Initialize[Task[File => PluginCompat.FileRef]] =
+    Def.task { (file: File) =>
+      HashedVirtualFileRef.of(file.toPath.toString, ""): PluginCompat.FileRef
+    }
+
+  /** The `.extract` pattern support, opted into with `import Compatibility.Extractor._`.
+    * The `com.thoughtworks.extractor` library has no Scala 3 build, but on Scala
+    * 3 a [[scala.PartialFunction]] is already a valid pattern, so a function (or
+    * partial function) only needs to be turned into one.
+    */
+  object Extractor:
+    extension [A, B](f: A => Option[B])
+      def extract: PartialFunction[A, B] = Function.unlift(f)
+    extension [A, B](pf: PartialFunction[A, B])
+      def extract: PartialFunction[A, B] = pf

src/main/scala/com/thoughtworks/sbtApiMappings/ApiMappings.scala

@@ -18,14 +18,19 @@ package com.thoughtworks.sbtApiMappings
 
 import sbt._
 import Keys._
-import com.thoughtworks.Extractor._
+import Compatibility.Extractor._
 import sbt.plugins.JvmPlugin
+import sbtcompat.PluginCompat
+// Brings `Def.uncached`, which sbt2-compat backfills on sbt 1.x (native on 2.x).
+import sbtcompat.PluginCompat._
 
 object ApiMappings extends AutoPlugin {
 
   object autoImport {
     val apiMappingRules =
-      SettingKey[PartialFunction[Attributed[File], URL]](
+      SettingKey[
+        PartialFunction[Attributed[PluginCompat.FileRef], Compatibility.URL]
+      ](
         "api-mapping-rules",
         "Rules to create api-mappings"
       )
@@ -41,21 +46,18 @@ object ApiMappings extends AutoPlugin {
   }
 
   override def projectSettings = Seq(Compile, Test).flatMap { config =>
-    inConfig(config) {
-      inTask(doc) {
-        Seq(
-          autoAPIMappings := true,
-          apiMappings ++= {
-            val rules = apiMappingRules.value
-            dependencyClasspath.value.collect {
-              case jar @ rules.extract(url)
-                  if !apiMappings.value.exists(_._1 == jar.data) =>
-                jar.data -> url
-            }(collection.breakOut(Map.canBuildFrom))
-          }
-        )
+    Seq(
+      config / doc / autoAPIMappings := true,
+      config / doc / apiMappings ++= Def.uncached {
+        val rules = (config / doc / apiMappingRules).value
+        val existingMappings = (config / doc / apiMappings).value
+        (config / doc / dependencyClasspath).value.view.collect {
+          case jar @ rules.extract(url)
+              if !existingMappings.exists(_._1 == jar.data) =>
+            jar.data -> url
+        }.toMap
       }
-    }
+    )
   }
 
 }

src/main/scala/com/thoughtworks/sbtApiMappings/BootstrapApiMappings.scala

@@ -2,11 +2,12 @@ package com.thoughtworks.sbtApiMappings
 
 import java.io.File
 import java.lang.management.ManagementFactory
-import java.net.URL
 
 import sbt._
 import sbt.Keys._
 import sbt.plugins.JvmPlugin
+// Brings `Def.uncached`, which sbt2-compat backfills on sbt 1.x (native on 2.x).
+import sbtcompat.PluginCompat._
 
 /** API mappings for classpath used by the bootstrap class loader.
   * @author
@@ -19,7 +20,7 @@ object BootstrapApiMappings extends AutoPlugin {
 
   object autoImport {
     val bootstrapJavadocURL =
-      SettingKey[URL](
+      SettingKey[Compatibility.URL](
         "bootstrap-javadoc-url",
         "Javadoc URL for classpath used by bootstrap class loader"
       )
@@ -43,32 +44,31 @@ object BootstrapApiMappings extends AutoPlugin {
     }
   }
 
-  override def globalSettings: Seq[Def.Setting[_]] = Seq(
+  override def globalSettings = Seq(
     bootstrapJavadocURL := defaultBootstrapJavadocUrl
   )
 
   override def projectSettings = Seq(Compile, Test).flatMap { config =>
-    inConfig(config) {
-      inTask(doc) {
-        Seq(
-          apiMappings ++= {
-            val url = bootstrapJavadocURL.value
-            val log = streams.value.log
+    Seq(
+      config / doc / apiMappings ++= Def.uncached {
+        val javadocUrl = (config / doc / bootstrapJavadocURL).value
+        val toDocKey = Compatibility.fileToDocKey.value
+        val log = (config / doc / streams).value.log
 
-            if (!ManagementFactory.getRuntimeMXBean.isBootClassPathSupported) {
-              // Copied from scala-js/project/Build.scala for Java 9 or later
-              Map(file("/modules/java.base") -> url)
-            } else {
-              ManagementFactory.getRuntimeMXBean.getBootClassPath
-                .split(File.pathSeparatorChar)
-                .map { jar =>
-                  new File(jar) -> url
-                }(collection.breakOut(Map.canBuildFrom))
+        if (!ManagementFactory.getRuntimeMXBean.isBootClassPathSupported) {
+          // Copied from scala-js/project/Build.scala for Java 9 or later
+          Map(toDocKey(file("/modules/java.base")) -> javadocUrl)
+        } else {
+          ManagementFactory.getRuntimeMXBean.getBootClassPath
+            .split(File.pathSeparatorChar)
+            .view
+            .map { jar =>
+              toDocKey(new File(jar)) -> javadocUrl
             }
-          }
-        )
+            .toMap
+        }
       }
-    }
+    )
   }
 
 }

src/main/scala/com/thoughtworks/sbtApiMappings/JavadocIoApiMappingRule.scala

@@ -1,7 +1,8 @@
 package com.thoughtworks.sbtApiMappings
 
 import sbt._
-import com.thoughtworks.Extractor._
+import Compatibility.Extractor._
+import sbtcompat.PluginCompat
 import sbt.internal.librarymanagement.mavenint.PomExtraDependencyAttributes
 
 object JavadocIoApiMappingRule extends AutoPlugin {
@@ -13,19 +14,24 @@ object JavadocIoApiMappingRule extends AutoPlugin {
   override def trigger = allRequirements
 
   private def nonSbtModuleID
-      : Attributed[File] => Option[(String, String, String)] = { jar =>
-    for {
-      moduleID <- jar.get(Keys.moduleID.key)
-      if !moduleID.extraAttributes.contains(
-        PomExtraDependencyAttributes.SbtVersionKey
-      )
-    } yield (moduleID.organization, moduleID.name, moduleID.revision)
+      : Attributed[PluginCompat.FileRef] => Option[(String, String, String)] = {
+    jar =>
+      for {
+        moduleID <- jar
+          .get(PluginCompat.moduleIDStr)
+          .map(PluginCompat.parseModuleIDStrAttribute)
+        if !moduleID.extraAttributes.contains(
+          PomExtraDependencyAttributes.SbtVersionKey
+        )
+      } yield (moduleID.organization, moduleID.name, moduleID.revision)
   }
 
-  private def javadocIoRule: PartialFunction[Attributed[File], URL] = {
+  private def javadocIoRule
+      : PartialFunction[Attributed[PluginCompat.FileRef], Compatibility.URL] = {
     case nonSbtModuleID.extract(organization, libraryName, revision) =>
-      val organizationPath = organization.replace('.', '/')
-      url(s"https://javadoc.io/page/$organization/$libraryName/$revision/")
+      url(
+        s"https://javadoc.io/page/$organization/$libraryName/$revision/"
+      )
   }
 
   override def projectSettings = {

src/main/scala/com/thoughtworks/sbtApiMappings/PlayApiMappingRule.scala

@@ -1,7 +1,8 @@
 package com.thoughtworks.sbtApiMappings
 
-import com.thoughtworks.Extractor._
 import sbt._
+import Compatibility.Extractor._
+import sbtcompat.PluginCompat
 
 /** @author
   *   杨博 (Yang Bo) <pop.atry@gmail.com>
@@ -14,12 +15,16 @@ object PlayApiMappingRule extends AutoPlugin {
 
   override def trigger = allRequirements
 
-  private def moduleID: Attributed[File] => Option[(String, String, String)] =
-    _.get(Keys.moduleID.key).map { moduleID =>
-      (moduleID.organization, moduleID.name, moduleID.revision)
-    }
+  private def moduleID
+      : Attributed[PluginCompat.FileRef] => Option[(String, String, String)] =
+    _.get(PluginCompat.moduleIDStr)
+      .map(PluginCompat.parseModuleIDStrAttribute)
+      .map { moduleID =>
+        (moduleID.organization, moduleID.name, moduleID.revision)
+      }
 
-  private def playRule: PartialFunction[Attributed[File], URL] = {
+  private def playRule
+      : PartialFunction[Attributed[PluginCompat.FileRef], Compatibility.URL] = {
     case moduleID.extract(
           "com.typesafe.play",
           libraryName,