Ban Guava's immutable collections outside the SPI

forbidden-apis 3.11 checks the bytecode of every module but the SPI
against config/forbidden-apis/guava-immutables.txt, which names
ImmutableList, ImmutableMap and ImmutableSet, and fails the build on a
use of one. Error Prone has no check that bans a class, and Picnic's
error-prone-support pushes towards Guava's immutables rather than away.
The check sees what a source-level ban would miss: a var whose type is
one of them, a subclass such as ImmutableSortedSet, and a call on what
a Guava method like ClassPath.getResources() returns.

The SPI is left out because FormatterService.getFormatReplacements
returns ImmutableList for compatibility. The methods that implement it
in open-java-format and open-java-format-jdk-bootstrap carry
@SuppressForbidden, an annotation of each module's own: the default
one would put forbidden-apis on their compile classpath. Code that
calls the method and keeps the result as a List passes the check.

ignoreSignaturesOfMissingClasses, because the benchmarks have no Guava
on their classpath and would otherwise fail to parse the signatures.

Author: abashev

CLAUDE.md

@@ -6,8 +6,10 @@ Building and testing: the README's "Building and testing locally" section. Gradl
 ## Conventions for new code
 
 - **Collections.** Plain `java.util` types. `List.of`, `List.copyOf`, `Map.of` and `Stream.toList()` give
-  unmodifiable collections, so new code does not need Guava's `ImmutableList` or `ImmutableMap`; use them only
-  where an existing API already hands one over.
+  unmodifiable collections; unlike Guava's, `Set.of` and `Map.of` do not keep insertion order, and `contains(null)`
+  on them throws. Guava's `ImmutableList`, `ImmutableMap` and `ImmutableSet` are banned by forbidden-apis
+  (`config/forbidden-apis`), which fails the build, in every module but the SPI: `FormatterService` keeps returning
+  `ImmutableList` for compatibility, and the methods that implement it carry their module's `@SuppressForbidden`.
 - **Nullability.** One annotation, JSpecify's `org.jspecify.annotations.Nullable`; do not add another `Nullable`,
   nor a `NotNull` or `NonNull`: what is not `@Nullable` is non-null, and NullAway checks it. It is a type-use
   annotation, so on a nested type it goes before the simple name (`Input.@Nullable Token`), and on an array before

build.gradle

@@ -83,6 +83,11 @@ subprojects {
     // Java toolchains, javac and test settings; Error Prone. Both in buildSrc/src/main/groovy.
     apply plugin: 'open-java-format.java-conventions'
     apply plugin: 'open-java-format.error-prone-conventions'
+    // Bans Guava's immutable collections, but not in the SPI: FormatterService.getFormatReplacements keeps
+    // returning ImmutableList, so that code compiled against an older SPI still links.
+    if (path != ':open-java-format-spi') {
+        apply plugin: 'open-java-format.forbidden-apis-conventions'
+    }
 
     dependencies {
         // Gives a version to the JUnit artifacts that useJUnitJupiter() adds without one.

buildSrc/build.gradle

@@ -13,5 +13,6 @@ repositories {
 dependencies {
     implementation 'net.ltgt.gradle:gradle-errorprone-plugin:5.2.0'
     implementation 'net.ltgt.gradle:gradle-nullaway-plugin:3.3.0'
+    implementation 'de.thetaphi:forbiddenapis:3.11'
     implementation 'org.jreleaser:org.jreleaser.gradle.plugin:1.26.0'
 }

buildSrc/src/main/groovy/open-java-format.forbidden-apis-conventions.gradle

@@ -0,0 +1,13 @@
+// Bans Guava's immutable collections in favour of java.util ones; the list is config/forbidden-apis.
+plugins {
+    id 'java'
+    id 'de.thetaphi.forbiddenapis'
+}
+
+forbiddenApis {
+    signaturesFiles = files(rootProject.file('config/forbidden-apis/guava-immutables.txt'))
+    // A module without Guava on its classpath cannot use the classes anyway.
+    ignoreSignaturesOfMissingClasses = true
+    // A module's own package-private SuppressForbidden, so the code does not depend on forbidden-apis.
+    suppressAnnotations = ['**.SuppressForbidden']
+}

config/forbidden-apis/guava-immutables.txt

@@ -0,0 +1,4 @@
+@defaultMessage Use java.util collections: List.of, List.copyOf, Map.of, Stream.toList()
+com.google.common.collect.ImmutableList
+com.google.common.collect.ImmutableMap
+com.google.common.collect.ImmutableSet

open-java-format-jdk-bootstrap/src/main/java/com/palantir/javaformat/bootstrap/BootstrappingFormatterService.java

@@ -52,6 +52,7 @@ public BootstrappingFormatterService(Path jdkPath, Integer jdkMajorVersion, List
     }
 
     @Override
+    @SuppressForbidden(reason = "FormatterService, kept in the SPI for compatibility, returns ImmutableList")
     public ImmutableList<Replacement> getFormatReplacements(String input, Collection<Range<Integer>> ranges) {
         try {
             return getFormatReplacementsInternal(input, ranges);
@@ -78,6 +79,7 @@ public String fixImports(String input) throws FormatterException {
         }
     }
 
+    @SuppressForbidden(reason = "FormatterService, kept in the SPI for compatibility, returns ImmutableList")
     private ImmutableList<Replacement> getFormatReplacementsInternal(String input, Collection<Range<Integer>> ranges)
             throws IOException {
         FormatterCliArgs command = new FormatterCliArgs(

open-java-format-jdk-bootstrap/src/main/java/com/palantir/javaformat/bootstrap/NativeImageFormatterService.java

@@ -43,6 +43,7 @@ public NativeImageFormatterService(Path nativeImagePath) {
     }
 
     @Override
+    @SuppressForbidden(reason = "FormatterService, kept in the SPI for compatibility, returns ImmutableList")
     public ImmutableList<Replacement> getFormatReplacements(String input, Collection<Range<Integer>> ranges) {
         Optional<String> output = Optional.empty();
         try {

open-java-format-jdk-bootstrap/src/main/java/com/palantir/javaformat/bootstrap/SuppressForbidden.java

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+package com.palantir.javaformat.bootstrap;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Lets forbidden-apis accept a use of an API that config/forbidden-apis bans, for the reason given. */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
+@interface SuppressForbidden {
+    String reason();
+}

open-java-format/src/main/java/com/palantir/javaformat/java/FormatterServiceImpl.java

@@ -33,6 +33,7 @@ public FormatterServiceImpl() {
     }
 
     @Override
+    @SuppressForbidden(reason = "FormatterService, kept in the SPI for compatibility, returns ImmutableList")
     public ImmutableList<Replacement> getFormatReplacements(String text, Collection<Range<Integer>> toRanges)
             throws FormatterException {
         return ImmutableList.copyOf(formatter.getFormatReplacements(text, toRanges));

open-java-format/src/main/java/com/palantir/javaformat/java/SuppressForbidden.java

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+package com.palantir.javaformat.java;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Lets forbidden-apis accept a use of an API that config/forbidden-apis bans, for the reason given. */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
+@interface SuppressForbidden {
+    String reason();
+}