forward compatibility for cli full Scala version lookups

An old scalafix-interfaces client should be able to get the full Scala version
for a recent scalafix-cli version. This is achieved by encapsulating property
file lookup behind a Java interface, for which an implementation can easily
be retrieved via ServiceLoader, as long as the recent scalafix-versions JAR
has been fetched.

Author: bjaglin

CONTRIBUTING.md

@@ -6,12 +6,22 @@ hesitate to ask in the [Discord channel](https://discord.gg/8AHaqGx3Qj).
 
 ## Modules
 
-- `scalafix-interfaces` Java facade to run rules within an existing JVM instance.
+### For rule writing
+
 - `scalafix-core/` data structures for rewriting and linting Scala source code.
-- `scalafix-reflect/` utilities to compile and classload rules from
-  configuration.
 - `scalafix-rules/` built-in rules such as `RemoveUnused`.
+
+### For rule execution
+
 - `scalafix-cli/` command-line interface.
+- `scalafix-interfaces` Java facade to run rules within an existing JVM instance.
+- `scalafix-reflect/` utilities to compile and classload rules from
+  configuration.
+- `scalafix-versions` Java implementation to advertize which Scala versions
+  `scalafix-cli` is published with.
+
+### Others
+
 - `scalafix-tests/` projects for unit and integration tests.
 - `scalafix-docs/` documentation code for the Scalafix website.
 

build.sbt

@@ -15,35 +15,41 @@ noPublishAndNoMima
 lazy val interfaces = project
   .in(file("scalafix-interfaces"))
   .settings(
+    moduleName := "scalafix-interfaces",
+    javaSettings,
+    libraryDependencies += coursierInterfaces,
     Compile / resourceGenerators += Def.task {
-      val props = new java.util.Properties()
+      val props = cliVersionsProperties()
       props.put("scalafixVersion", version.value)
       props.put("scalafixStableVersion", stableVersion.value)
       props.put("scalametaVersion", scalametaV)
-      props.put("scala212", scala212)
-      props.put("scala213", scala213)
-      props.put("scala33", scala33)
-      props.put("scala35", scala35)
-      props.put("scala36", scala36)
-      props.put("scala3LTS", scala3LTS)
-      props.put("scala3Next", scala3Next)
       val out =
         (Compile / managedResourceDirectories).value.head /
           "scalafix-interfaces.properties"
       IO.write(props, "Scalafix version constants", out)
       List(out)
-    },
-    (Compile / javacOptions) ++= List(
-      "-Xlint:all",
-      "-Werror"
-    ),
-    (Compile / doc / javacOptions) := List("-Xdoclint:none"),
-    libraryDependencies += coursierInterfaces,
-    moduleName := "scalafix-interfaces",
-    crossPaths := false,
-    autoScalaLibrary := false
+    }
+  )
+  .disablePlugins(ScalafixPlugin)
+
+lazy val versions = project
+  .in(file("scalafix-versions"))
+  .settings(
+    moduleName := "scalafix-versions",
+    javaSettings,
+    mimaPreviousArtifacts := Set.empty, // TODO: remove after 0.14.3
+    Compile / resourceGenerators += Def.task {
+      val props = cliVersionsProperties()
+      props.put("scalafix", version.value)
+      val out =
+        (Compile / managedResourceDirectories).value.head /
+          "scalafix-versions.properties"
+      IO.write(props, "Scala versions for ch.epfl.scala:::scalafix-cli", out)
+      List(out)
+    }
   )
   .disablePlugins(ScalafixPlugin)
+  .dependsOn(interfaces)
 
 // Scala 3 macros vendored separately (i.e. without runtime classes), to
 // shadow Scala 2.13 macros in the Scala 3 compiler classpath, while producing
@@ -340,22 +346,37 @@ lazy val integration = projectMatrix
       "inputSourceroot" ->
         resolve(input, Compile / sourceDirectory).value,
       "outputSourceroot" ->
-        resolve(output, Compile / sourceDirectory).value
+        resolve(output, Compile / sourceDirectory).value,
+      "versionsJars" ->
+        Seq(
+          (interfaces / Compile / packageBin / artifactPath).value,
+          (versions / Compile / packageBin / artifactPath).value
+        )
     ),
     Test / test := (Test / test)
       .dependsOn(
-        (resolve(cli, publishLocalTransitive) +: cli.projectRefs
+        interfaces / Compile / packageBin,
+        versions / Compile / packageBin
+      )
+      .dependsOn(resolve(cli, publishLocalTransitive))
+      .dependsOn(
+        cli.projectRefs
           // always publish Scala 3 artifacts to test Scala 3 minor version fallbacks
           .collect { case p @ LocalProject(n) if n.startsWith("cli3") => p }
-          .map(_ / publishLocalTransitive)): _*
+          .map(_ / publishLocalTransitive): _*
       )
       .value,
     Test / testWindows := (Test / testWindows)
       .dependsOn(
-        (resolve(cli, publishLocalTransitive) +: cli.projectRefs
+        interfaces / Compile / packageBin,
+        versions / Compile / packageBin
+      )
+      .dependsOn(resolve(cli, publishLocalTransitive))
+      .dependsOn(
+        cli.projectRefs
           // always publish Scala 3 artifacts to test Scala 3 minor version fallbacks
           .collect { case p @ LocalProject(n) if n.startsWith("cli3") => p }
-          .map(_ / publishLocalTransitive)): _*
+          .map(_ / publishLocalTransitive): _*
       )
       .value
   )

project/ScalafixBuild.scala

@@ -31,6 +31,16 @@ object ScalafixBuild extends AutoPlugin with GhpagesKeys {
       publish / skip := true
     )
 
+    lazy val javaSettings = Seq(
+      (Compile / javacOptions) ++= List(
+        "-Xlint:all",
+        "-Werror"
+      ),
+      (Compile / doc / javacOptions) := List("-Xdoclint:none"),
+      crossPaths := false,
+      autoScalaLibrary := false
+    )
+
     // https://github.com/scalameta/scalameta/issues/2485
     lazy val coreScalaVersions = Seq(scala212, scala213)
     lazy val cliScalaVersions = {
@@ -156,6 +166,19 @@ object ScalafixBuild extends AutoPlugin with GhpagesKeys {
       buildInfoObject := "RulesBuildInfo"
     )
 
+    // must match ScalafixProperties logic
+    def cliVersionsProperties() = {
+      val props = new java.util.Properties()
+      props.put("scala212", scala212)
+      props.put("scala213", scala213)
+      props.put("scala33", scala33)
+      props.put("scala35", scala35)
+      props.put("scala36", scala36)
+      props.put("scala3LTS", scala3LTS)
+      props.put("scala3Next", scala3Next)
+      props
+    }
+
     lazy val testWindows =
       taskKey[Unit]("run tests, excluding those incompatible with Windows")
 

scalafix-interfaces/src/main/java/scalafix/interfaces/Scalafix.java

@@ -3,6 +3,7 @@
 import coursierapi.Repository;
 import scalafix.internal.interfaces.ScalafixCoursier;
 import scalafix.internal.interfaces.ScalafixInterfacesClassloader;
+import scalafix.internal.interfaces.ScalafixProperties;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -137,30 +138,6 @@ static Scalafix fetchAndClassloadInstance(String requestedScalaVersion) throws S
     static Scalafix fetchAndClassloadInstance(String requestedScalaVersion, List<Repository> repositories)
             throws ScalafixException {
 
-        String requestedScalaMajorMinorOrMajorVersion =
-            requestedScalaVersion.replaceAll("^(\\d+\\.\\d+).*", "$1");
-
-        String scalaVersionKey;
-        if (requestedScalaMajorMinorOrMajorVersion.equals("2.12")) {
-            scalaVersionKey = "scala212";
-        } else if (requestedScalaMajorMinorOrMajorVersion.equals("2.13") ||
-            requestedScalaMajorMinorOrMajorVersion.equals("2")) {
-            scalaVersionKey = "scala213";
-        } else if (requestedScalaMajorMinorOrMajorVersion.equals("3.0") ||
-            requestedScalaMajorMinorOrMajorVersion.equals("3.1") ||
-            requestedScalaMajorMinorOrMajorVersion.equals("3.2") ||
-            requestedScalaMajorMinorOrMajorVersion.equals("3.3")) {
-            scalaVersionKey = "scala33";
-        } else if (requestedScalaMajorMinorOrMajorVersion.equals("3.5")) {
-            scalaVersionKey = "scala35";
-        } else if (requestedScalaMajorMinorOrMajorVersion.equals("3.6")) {
-            scalaVersionKey = "scala36";
-        } else if (requestedScalaMajorMinorOrMajorVersion.startsWith("3")) {
-            scalaVersionKey = "scala3Next";
-        } else {
-            throw new IllegalArgumentException("Unsupported scala version " + requestedScalaVersion);
-        }
-
         Properties properties = new Properties();
         String propertiesPath = "scalafix-interfaces.properties";
         InputStream stream = Scalafix.class.getClassLoader().getResourceAsStream(propertiesPath);
@@ -171,6 +148,7 @@ static Scalafix fetchAndClassloadInstance(String requestedScalaVersion, List<Rep
         }
 
         String scalafixVersion = properties.getProperty("scalafixVersion");
+        String scalaVersionKey = ScalafixProperties.getScalaVersionKey(requestedScalaVersion);
         String scalaVersion = properties.getProperty(scalaVersionKey);
         if (scalafixVersion == null || scalaVersion == null)
             throw new ScalafixException("Failed to lookup versions from '" + propertiesPath + "'");

scalafix-interfaces/src/main/java/scalafix/interfaces/ScalafixVersions.java

@@ -0,0 +1,61 @@
+package scalafix.interfaces;
+
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.Iterator;
+import java.util.List;
+import java.util.ServiceLoader;
+
+import scalafix.internal.interfaces.ScalafixInterfacesClassloader;
+
+/**
+ * Public API for looking up which one of the
+ * <code>ch.epfl.scala:::scalafix-cli</code> artifacts of a Scalafix release is
+ * the most appropriate, given the Scala version used to compile Scalafix target
+ * sources.
+ * <p>
+ * To obtain an instance of ScalafixVersions, fetch the corresponding
+ * <code>ch.epfl.scala:scalafix-versions</code> and use {@link #get}.
+ *
+ * @implNote This interface is not intended to be extended, the only
+ *           implementation of this interface should live in the Scalafix
+ *           repository.
+ */
+public interface ScalafixVersions {
+
+    /**
+     * @return the Scalafix release described.
+     */
+    String scalafixVersion();
+
+    /**
+     * Returns the most appropriate full Scala version to resolve
+     * <code>ch.epfl.scala:::scalafix-cli:scalafixVersion</code> with.
+     * 
+     * @param sourcesScalaVersion The Scala version (i.e. "3.3.4") used to compile
+     *                            Scalafix target sources.
+     * @return a full Scala version to resolve the artifact with.
+     */
+    String cliScalaVersion(String sourcesScalaVersion);
+
+    /**
+     * Obtains an implementation of ScalafixVersions using the provided
+     * classpath URLs.
+     * 
+     * @param classpathUrls URLs to be used in the classloader for loading
+     *                      a ScalafixVersions implementation
+     * @return the first available implementation of ScalafixVersions, as declared
+     *         via ServiceLoader
+     */
+    static ScalafixVersions get(List<URL> classpathUrls) {
+        ClassLoader parent = new ScalafixInterfacesClassloader(ScalafixVersions.class.getClassLoader());
+        ClassLoader classLoader = new URLClassLoader(classpathUrls.stream().toArray(URL[]::new), parent);
+        ServiceLoader<ScalafixVersions> loader = ServiceLoader.load(ScalafixVersions.class, classLoader);
+        Iterator<ScalafixVersions> iterator = loader.iterator();
+        if (iterator.hasNext()) {
+            return iterator.next();
+        } else {
+            throw new IllegalStateException("No implementation found");
+        }
+    }
+}

scalafix-interfaces/src/main/java/scalafix/internal/interfaces/ScalafixProperties.java

@@ -0,0 +1,30 @@
+package scalafix.internal.interfaces;
+
+//TODO: inline in scalafix.internal.versions.ScalafixVersions when scalafix.interfaces.Scalafix is removed
+public class ScalafixProperties {
+
+    public static String getScalaVersionKey(String requestedScalaVersion) {
+        String requestedScalaMajorMinorOrMajorVersion =
+            requestedScalaVersion.replaceAll("^(\\d+\\.\\d+).*", "$1");
+
+        if (requestedScalaMajorMinorOrMajorVersion.equals("2.12")) {
+            return "scala212";
+        } else if (requestedScalaMajorMinorOrMajorVersion.equals("2.13") ||
+            requestedScalaMajorMinorOrMajorVersion.equals("2")) {
+            return "scala213";
+        } else if (requestedScalaMajorMinorOrMajorVersion.equals("3.0") ||
+            requestedScalaMajorMinorOrMajorVersion.equals("3.1") ||
+            requestedScalaMajorMinorOrMajorVersion.equals("3.2") ||
+            requestedScalaMajorMinorOrMajorVersion.equals("3.3")) {
+            return "scala33";
+        } else if (requestedScalaMajorMinorOrMajorVersion.equals("3.5")) {
+            return "scala35";
+        } else if (requestedScalaMajorMinorOrMajorVersion.equals("3.6")) {
+            return "scala36";
+        } else if (requestedScalaMajorMinorOrMajorVersion.startsWith("3")) {
+            return "scala3Next";
+        } else {
+            throw new IllegalArgumentException("Unsupported scala version " + requestedScalaVersion);
+        }
+    }
+}

scalafix-tests/integration/src/test/scala/scalafix/tests/versions/ScalafixVersionsImplSuite.scala

@@ -0,0 +1,92 @@
+package scalafix.tests.versions
+
+import scala.jdk.CollectionConverters._
+
+import org.scalatest.funsuite.AnyFunSuite
+import scalafix.Versions
+import scalafix.interfaces.ScalafixVersions
+import scalafix.tests.BuildInfo
+
+/**
+ * This test require interfaces & versions to be packaged. `packageBin` is done
+ * automatically as part of `sbt integrationX / test`, so make sure to run that
+ * once if you want to run the test with testOnly or through BSP.
+ */
+class ScalafixVersionsImplSuite extends AnyFunSuite {
+
+  lazy val versions: ScalafixVersions =
+    ScalafixVersions.get(BuildInfo.versionsJars.map(_.toURL).asJava)
+
+  test("scalafixVersion") {
+    assert(versions.scalafixVersion() == Versions.version)
+  }
+
+  test("fail to get 2.11 with full version") {
+    assertThrows[IllegalArgumentException](
+      versions.cliScalaVersion("2.11.0")
+    )
+  }
+
+  test("fail to get 2.11 with minor version") {
+    assertThrows[IllegalArgumentException](
+      versions.cliScalaVersion("2.11")
+    )
+  }
+
+  test("get 2.12 with full version") {
+    assert(versions.cliScalaVersion("2.12.20") == Versions.scala212)
+  }
+
+  test("get 2.12 with major.minor version") {
+    assert(versions.cliScalaVersion("2.12") == Versions.scala212)
+  }
+
+  test("get 2.13 with full version") {
+    assert(versions.cliScalaVersion("2.13.15") == Versions.scala213)
+  }
+
+  test("get 2.13 with major.minor version") {
+    assert(versions.cliScalaVersion("2.13") == Versions.scala213)
+  }
+
+  test("get 2.13 with major version") {
+    assert(versions.cliScalaVersion("2") == Versions.scala213)
+  }
+
+  test("get 3LTS with full pre-LTS version") {
+    assert(versions.cliScalaVersion("3.0.0") == Versions.scala3LTS)
+  }
+
+  test("get 3LTS with major.minor pre-LTS version") {
+    assert(versions.cliScalaVersion("3.2") == Versions.scala3LTS)
+  }
+
+  test("get 3LTS with full LTS version") {
+    assert(versions.cliScalaVersion("3.3.4") == Versions.scala3LTS)
+  }
+
+  test("get 3LTS with major.minor LTS version") {
+    assert(versions.cliScalaVersion("3.3") == Versions.scala3LTS)
+  }
+
+  test("get 3.5 with full version") {
+    assert(versions.cliScalaVersion("3.5.2") == Versions.scala35)
+  }
+
+  test("get 3.5 with major.minor version") {
+    assert(versions.cliScalaVersion("3.5") == Versions.scala35)
+  }
+
+  test("get 3Next with full version") {
+    assert(versions.cliScalaVersion("3.6.2") == Versions.scala3Next)
+  }
+
+  test("get 3Next with major.minor version") {
+    assert(versions.cliScalaVersion("3.6") == Versions.scala3Next)
+  }
+
+  test("get 3Next with major version") {
+    assert(versions.cliScalaVersion("3") == Versions.scala3Next)
+  }
+
+}