Added support for Revapi (#3974)

Added [Revapi](https://revapi.org/revapi-site/main/index.html) support
for API analysis and change tracking to identify incompatibilities.

Resolves #3929.

docs/modules/ROOT/pages/javalib/publishing.adoc

@@ -9,4 +9,29 @@ This page will discuss common topics around publishing your Java projects for ot
 
 include::partial$example/javalib/publishing/2-publish-module.adoc[]
 
+== Checking API compatibility
+
+Mill provides the ability to check API changes with the https://revapi.org/revapi-site/main/index.html[Revapi] analysis and change tracking tool.
+
+include::partial$example/javalib/publishing/3-revapi.adoc[]
+
+CAUTION: The `revapi` task does not fail if incompatibilities are reported. You should fix these, and verify by re-running `revapi`, before a release.
+
+[TIP]
+====
+The `revapi` task returns the path to a directory that can be used to resolve the relative path to any extension configuration output.
+[source,json]
+----
+[
+  {
+    "extension": "revapi.reporter.text",
+    "configuration": {
+      "minSeverity": "BREAKING",
+      "output": "report.txt"
+    }
+  }
+]
+----
+====
+
 include::partial$Publishing_Footer.adoc[]

example/javalib/publishing/3-revapi/bar/conf/logback.xml

@@ -0,0 +1,31 @@
+<!--
+
+    Copyright 2014-2017 Lukas Krejci
+    and other contributors as indicated by the @author tags.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+<configuration>
+
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <!-- change to "trace" if AST debugging is needed -->
+    <root level="info">
+        <appender-ref ref="STDOUT"/>
+    </root>
+</configuration>

example/javalib/publishing/3-revapi/bar/conf/revapi.json

@@ -0,0 +1,8 @@
+[
+  {
+    "extension": "revapi.reporter.text",
+    "configuration": {
+      "minSeverity": "BREAKING"
+    }
+  }
+]

example/javalib/publishing/3-revapi/bar/src/Visibility.java

@@ -0,0 +1,11 @@
+public class Visibility {
+  public int f;
+
+  private class SuperClass {
+    public int f;
+  }
+
+  public class SubClass extends SuperClass {
+    private int f2;
+  }
+}

example/javalib/publishing/3-revapi/build.mill

@@ -0,0 +1,53 @@
+//// SNIPPET:BUILD
+package build
+import mill._, javalib._, publish._, revapi._
+
+object bar extends JavaModule with RevapiModule {
+  def publishVersion = "0.0.1"
+
+  def pomSettings = PomSettings(
+    description = "Hello",
+    organization = "com.lihaoyi",
+    url = "https://github.com/lihaoyi/example",
+    licenses = Seq(License.MIT),
+    versionControl = VersionControl.github("lihaoyi", "example"),
+    developers = Seq(Developer("lihaoyi", "Li Haoyi", "https://github.com/lihaoyi"))
+  )
+
+  override def revapiConfigFiles: T[Seq[PathRef]] =
+    // add Revapi config JSON file(s)
+    Task.Sources(millSourcePath / "conf/revapi.json")
+
+  override def revapiClasspath: T[Agg[PathRef]] = T {
+    // add folder containing logback.xml
+    super.revapiClasspath() ++ Seq(PathRef(millSourcePath / "conf"))
+  }
+}
+
+// This example uses the `revapi` task, provided by the `RevapiModule`, to run an
+// analysis on old and new archives of a module to identify incompatibilities.
+//
+// NOTE: For demonstration purposes, an archive, to compare against, is published locally.
+// In real usage, the old version would be downloaded from the publish repository.
+
+/** Usage
+
+> mill bar.publishLocal
+Publishing Artifact(com.lihaoyi,bar,0.0.1) to ivy repo...
+
+> cp dev/src/Visibility.java bar/src/Visibility.java
+
+> mill bar.revapi
+Starting analysis
+Analysis results
+----------------
+old: field Visibility.SuperClass.f @ Visibility.SubClass
+new: <none>
+java.field.removed: Field removed from class.
+... BREAKING
+old: field Visibility.f
+new: field Visibility.f
+java.field.visibilityReduced: Visibility was reduced from 'public' to 'protected'.
+... BREAKING
+Analysis took ...ms.
+*/

example/javalib/publishing/3-revapi/dev/src/Visibility.java

@@ -0,0 +1,11 @@
+public class Visibility {
+  protected int f;
+
+  private class SuperClass {
+    private int f;
+  }
+
+  public class SubClass extends SuperClass {
+    public int f2;
+  }
+}

scalalib/src/mill/javalib/revapi/RevapiModule.scala

@@ -0,0 +1,126 @@
+package mill.javalib.revapi
+
+import mill._
+import mill.javalib._
+import mill.javalib.revapi.RevapiModule.optional
+import mill.scalalib.publish.Artifact
+import mill.util.Jvm
+
+/**
+ * Adds support for [[https://revapi.org/revapi-site/main/index.html Revapi checker]] to enable API analysis and change tracking.
+ */
+@mill.api.experimental // until Revapi has a stable release
+trait RevapiModule extends PublishModule {
+
+  /**
+   * Runs [[revapiCliVersion Revapi CLI]] on this module's archives.
+   *
+   * @param args additional CLI options
+   * @return CLI working directory
+   */
+  def revapi(args: String*): Command[PathRef] = Task.Command {
+    val workingDir = T.dest
+
+    val oldFiles = revapiOldFiles()
+    val oldFile = oldFiles.head
+    val oldSupFiles = oldFiles.tail
+
+    val newFiles = revapiNewFiles()
+    val newFile = newFiles.head
+    val newSupFiles = newFiles.tail
+
+    val mainClass = "org.revapi.standalone.Main"
+    val mainArgs =
+      Seq.newBuilder[String]
+        // https://github.com/revapi/revapi/blob/69445626881347fbf7811a4a78ff230fe152a2dc/revapi-standalone/src/main/java/org/revapi/standalone/Main.java#L149
+        .++=(Seq(mainClass, workingDir.toString()))
+        // https://github.com/revapi/revapi/blob/69445626881347fbf7811a4a78ff230fe152a2dc/revapi-standalone/src/main/java/org/revapi/standalone/Main.java#L97
+        .++=(Seq("-e", revapiExtensions().mkString(",")))
+        .++=(Seq("-o", oldFile.path.toString()))
+        .++=(optional("-s", oldSupFiles.iterator.map(_.path)))
+        .++=(Seq("-n", newFile.path.toString()))
+        .++=(optional("-t", newSupFiles.iterator.map(_.path)))
+        .++=(optional("-c", revapiConfigFiles().iterator.map(_.path)))
+        .++=(Seq("-d", revapiCacheDir().path.toString()))
+        .++=(optional("-r", revapiRemoteRepositories()))
+        .++=(args)
+        .result()
+
+    T.log.info("running revapi cli")
+    Jvm.runSubprocess(
+      mainClass = mainClass,
+      classPath = revapiClasspath().map(_.path),
+      jvmArgs = revapiJvmArgs(),
+      mainArgs = mainArgs,
+      workingDir = workingDir
+    )
+
+    PathRef(workingDir)
+  }
+
+  /**
+   * List of Maven GAVs of Revapi extensions
+   *
+   * @note Must be non-empty.
+   */
+  def revapiExtensions: T[Seq[String]] = Seq(
+    "org.revapi:revapi-java:0.28.1",
+    "org.revapi:revapi-reporter-text:0.15.0"
+  )
+
+  /** API archive and supplement files (dependencies) to compare against */
+  def revapiOldFiles: T[Agg[PathRef]] = T {
+    val Artifact(group, id, version) = publishSelfDependency()
+    defaultResolver().resolveDeps(
+      Seq(ivy"$group:$id:$version"),
+      artifactTypes = Some(revapiArtifactTypes())
+    )
+  }
+
+  /** API archive and supplement files (dependencies) to compare */
+  def revapiNewFiles: T[Agg[PathRef]] = T {
+    Agg(jar()) ++
+      T.traverse(recursiveModuleDeps)(_.jar)() ++
+      defaultResolver().resolveDeps(
+        transitiveIvyDeps(),
+        artifactTypes = Some(revapiArtifactTypes())
+      )
+  }
+
+  /** List of configuration files */
+  def revapiConfigFiles: T[Seq[PathRef]] = Seq.empty[PathRef]
+
+  /** Location of local cache of extensions to use to locate artifacts */
+  def revapiCacheDir: T[PathRef] = T { PathRef(T.dest) }
+
+  /** URLs of remote Maven repositories to use for artifact resolution */
+  def revapiRemoteRepositories: T[Seq[String]] = T {
+    repositoriesTask()
+      .collect { case repo: coursier.MavenRepository => repo.root }
+  }
+
+  /** Classpath containing the Revapi [[revapiCliVersion CLI]] */
+  def revapiClasspath: T[Agg[PathRef]] = T {
+    defaultResolver().resolveDeps(
+      Agg(ivy"org.revapi:revapi-standalone:${revapiCliVersion()}")
+    )
+  }
+
+  /** [[https://revapi.org/revapi-standalone/0.12.0/index.html Revapi CLI]] version */
+  def revapiCliVersion: T[String] = "0.12.0"
+
+  /** JVM arguments for the Revapi [[revapiCliVersion CLI]] */
+  def revapiJvmArgs: T[Seq[String]] = Seq.empty[String]
+
+  /** Artifact types to resolve archives and supplement files (dependencies) */
+  def revapiArtifactTypes: T[Set[coursier.Type]] = Set(coursier.Type.jar)
+}
+@mill.api.experimental
+object RevapiModule {
+
+  private def optional[T](name: String, values: IterableOnce[T]): Seq[String] = {
+    val it = values.iterator
+    if (it.isEmpty) Seq.empty
+    else Seq(name, it.mkString(","))
+  }
+}

scalalib/test/resources/javalib/revapi/conf/logback.xml

@@ -0,0 +1,31 @@
+<!--
+
+    Copyright 2014-2017 Lukas Krejci
+    and other contributors as indicated by the @author tags.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+<configuration>
+
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <!-- change to "trace" if AST debugging is needed -->
+    <root level="info">
+        <appender-ref ref="STDOUT"/>
+    </root>
+</configuration>

scalalib/test/resources/javalib/revapi/conf/revapi.json

@@ -0,0 +1,9 @@
+[
+  {
+    "extension": "revapi.reporter.text",
+    "configuration": {
+      "minSeverity": "BREAKING",
+      "output": "report.txt"
+    }
+  }
+]

scalalib/test/resources/javalib/revapi/example/v1/src/annotations/InheritedAnnotation.java

@@ -0,0 +1,5 @@
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+@Target(ElementType.TYPE)
+public @interface InheritedAnnotation {}

scalalib/test/resources/javalib/revapi/example/v1/src/classes/TypeParams.java

@@ -0,0 +1,6 @@
+public class TypeParams {
+
+  public static class Base<T> {}
+
+  public static class Class<A, B extends String, T> extends Base<T> {}
+}

scalalib/test/resources/javalib/revapi/example/v1/src/fields/Visibility.java

@@ -0,0 +1,11 @@
+public class Visibility {
+  public int f;
+
+  private class SuperClass {
+    public int f;
+  }
+
+  public class SubClass extends SuperClass {
+    private int f2;
+  }
+}

scalalib/test/resources/javalib/revapi/example/v2/src/annotations/InheritedAnnotation.java

@@ -0,0 +1,7 @@
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Target;
+
+@Inherited
+@Target(ElementType.TYPE)
+public @interface InheritedAnnotation {}

scalalib/test/resources/javalib/revapi/example/v2/src/classes/TypeParams.java

@@ -0,0 +1,6 @@
+public class TypeParams {
+
+  public static class Base<T extends Number, E> {}
+
+  public static class Class<New, B extends Cloneable> extends Base<Double, New> {}
+}

scalalib/test/resources/javalib/revapi/example/v2/src/fields/Visibility.java

@@ -0,0 +1,11 @@
+public class Visibility {
+  protected int f;
+
+  private class SuperClass {
+    private int f;
+  }
+
+  public class SubClass extends SuperClass {
+    public int f2;
+  }
+}