Keep the Spotless step's jars through the configuration cache

The step kept its jars and the loaded formatter in transient fields.
The configuration cache serializes the step, and the one it read back
had neither: every file got a lint error, a NullPointerException
because "this.jarsSupplier" is null (#193).

The step now uses Spotless' round-trip API, as Spotless' own steps
do: the cache keeps the jar files, the up-to-date check compares
their signature, and the formatter is loaded from the jars on first
use. create(Configuration, Supplier) stays, deprecated.

The cache entry was not reused either: "an input to unknown location
has changed". That came from targetExclude with patterns, which
Spotless matches against a file tree of the whole project directory,
and every build changes that tree; Spotless alone does the same with
those patterns. The excludes are now the source sets' Java files in a
generated directory, by the same patterns, which is what Spotless
formats by default. A target set by hand to files outside the source
sets no longer has those directories left out.

Author: abashev

gradle-open-java-format/src/main/java/com/palantir/javaformat/gradle/PalantirJavaFormatSpotlessPlugin.java

@@ -17,10 +17,9 @@
 
 import com.diffplug.gradle.spotless.SpotlessExtension;
 import com.google.common.collect.ImmutableList;
-import com.palantir.javaformat.java.FormatterService;
-import java.util.function.Supplier;
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
+import org.gradle.api.plugins.JavaPluginExtension;
 
 public abstract class PalantirJavaFormatSpotlessPlugin implements Plugin<Project> {
     // The spotless gradle plugin got renamed to 'com.diffplug.spotless' at version 5.0.0
@@ -32,16 +31,19 @@ public void apply(Project project) {
         Project rootProject = project.getRootProject();
         rootProject.getPluginManager().apply(PalantirJavaFormatProviderPlugin.class);
 
-        Supplier<FormatterService> memoizedService =
-                rootProject.getExtensions().getByType(JavaFormatExtension.class)::serviceLoad;
-
         project.getPluginManager().withPlugin("java", _javaPlugin -> {
             SPOTLESS_PLUGINS.forEach(spotlessPluginId -> project.getPluginManager()
                     .withPlugin(spotlessPluginId, _spotlessPlugin -> {
                         // Not before this point: Gradle's decoration of SpotlessInterop loads Spotless classes, which
                         // are missing from a project that never applies Spotless.
-                        SpotlessInterop spotlessInterop =
-                                rootProject.getObjects().newInstance(SpotlessInterop.class, memoizedService);
+                        SpotlessInterop spotlessInterop = rootProject
+                                .getObjects()
+                                .newInstance(
+                                        SpotlessInterop.class,
+                                        project.getProjectDir(),
+                                        project.getExtensions()
+                                                .getByType(JavaPluginExtension.class)
+                                                .getSourceSets());
                         SpotlessExtension spotlessExtension =
                                 project.getExtensions().getByType(SpotlessExtension.class);
                         spotlessExtension.java(spotlessInterop);

gradle-open-java-format/src/main/java/com/palantir/javaformat/gradle/SpotlessInterop.java

@@ -19,15 +19,21 @@
 import com.diffplug.spotless.FormatterStep;
 import com.palantir.javaformat.gradle.spotless.NativePalantirJavaFormatStep;
 import com.palantir.javaformat.gradle.spotless.PalantirJavaFormatStep;
-import com.palantir.javaformat.java.FormatterService;
-import java.util.function.Supplier;
+import java.io.File;
+import java.util.List;
+import java.util.concurrent.Callable;
+import java.util.regex.Pattern;
 import javax.inject.Inject;
 import org.gradle.api.Action;
 import org.gradle.api.JavaVersion;
 import org.gradle.api.artifacts.ConfigurationContainer;
+import org.gradle.api.file.FileCollection;
 import org.gradle.api.logging.Logger;
 import org.gradle.api.logging.Logging;
+import org.gradle.api.model.ObjectFactory;
+import org.gradle.api.specs.Spec;
 import org.gradle.api.tasks.Nested;
+import org.gradle.api.tasks.SourceSetContainer;
 
 /**
  * Class that exists only to encapsulate accessing spotless classes, so that Gradle can generate a decorated class for
@@ -36,7 +42,19 @@
 public abstract class SpotlessInterop implements Action<JavaExtension> {
     private static final Logger logger = Logging.getLogger(SpotlessInterop.class);
 
-    private final Supplier<FormatterService> formatterService;
+    // Generated source directories, which are not formatted: a file is in one when its path in the project directory
+    // matches **/build/generated*/**, **/src/generated*/**, **/generated_*src/**, **/generated_*Src/** or
+    // **/groovy-dsl-plugins/**.
+    // Note: We cannot simply exclude **/build/**/* because some repos might contain a build directory
+    // within the src sourceset that should be formatted.
+    // build/groovy-dsl-plugins contains Java wrapper classes for
+    // https://docs.gradle.org/9.3.1/userguide/implementing_gradle_plugins_convention.html
+    // and don't need to be formatted.
+    private static final Pattern GENERATED = Pattern.compile(
+            "(.*/)?(build/generated[^/]*|src/generated[^/]*|generated_[^/]*src|generated_[^/]*Src|groovy-dsl-plugins)/.+");
+
+    private final File projectDir;
+    private final SourceSetContainer sourceSets;
 
     @Nested
     protected abstract NativeImageSupport getNativeImageSupport();
@@ -45,28 +63,33 @@ public abstract class SpotlessInterop implements Action<JavaExtension> {
     protected abstract ConfigurationContainer getConfigurations();
 
     @Inject
-    public SpotlessInterop(Supplier<FormatterService> formatterService) {
-        this.formatterService = formatterService;
+    protected abstract ObjectFactory getObjects();
+
+    @Inject
+    public SpotlessInterop(File projectDir, SourceSetContainer sourceSets) {
+        this.projectDir = projectDir;
+        this.sourceSets = sourceSets;
     }
 
     @Override
     public void execute(JavaExtension java) {
-        // Exclude generated source directories
-        java.targetExclude(
-                // Note: We cannot simply exclude **/build/**/* because some repos might contain a build directory
-                // within the src sourceset that should be formatted.
-                "**/build/generated*/**",
-                "**/src/generated*/**",
-                "**/generated_*src/**",
-                "**/generated_*Src/**",
-                // build/groovy-dsl-plugins contains Java wrapper classes for
-                // https://docs.gradle.org/9.3.1/userguide/implementing_gradle_plugins_convention.html
-                // and don't need to be formatted.
-                "**/groovy-dsl-plugins/**");
+        java.targetExclude(generatedSources());
         // This is configuration cache safe as happening afterEvaluate
         java.addStep(spotlessJavaFormatStep());
     }
 
+    /**
+     * The Java files of the source sets that are in a generated directory. Not the patterns themselves: Spotless
+     * matches a pattern against a file tree of the whole project directory, which every build changes, and the
+     * configuration cache entry is then never reused (#193). The source sets' files are what Spotless formats by
+     * default; a callable, so that source sets added after the plugin count too.
+     */
+    private FileCollection generatedSources() {
+        return getObjects().fileCollection().from((Callable<List<FileCollection>>) () -> sourceSets.stream()
+                .map(sourceSet -> sourceSet.getAllJava().filter(new InGeneratedDirectory(projectDir)))
+                .toList());
+    }
+
     private FormatterStep spotlessJavaFormatStep() {
         if (getNativeImageSupport().isNativeImageConfigured()
                 && JavaVersion.current().compareTo(JavaVersion.VERSION_21) < 0) {
@@ -76,6 +99,28 @@ private FormatterStep spotlessJavaFormatStep() {
         }
         logger.info("Using the Java-based formatter {}", JavaVersion.current());
         return PalantirJavaFormatStep.create(
-                getConfigurations().getByName(PalantirJavaFormatProviderPlugin.CONFIGURATION_NAME), formatterService);
+                getConfigurations().getByName(PalantirJavaFormatProviderPlugin.CONFIGURATION_NAME));
+    }
+
+    /**
+     * Whether a file of the project is in a generated directory, see {@link #GENERATED}. A class, not a record: the
+     * configuration cache stores it with the Spotless task's target, and could not create it again as a record.
+     */
+    private static final class InGeneratedDirectory implements Spec<File> {
+        private final File projectDir;
+
+        InGeneratedDirectory(File projectDir) {
+            this.projectDir = projectDir;
+        }
+
+        @Override
+        public boolean isSatisfiedBy(File file) {
+            var project = projectDir.toPath();
+            var path = file.toPath();
+            return path.startsWith(project)
+                    && GENERATED
+                            .matcher(project.relativize(path).toString().replace(File.separatorChar, '/'))
+                            .matches();
+        }
     }
 }

gradle-open-java-format/src/main/java/com/palantir/javaformat/gradle/spotless/PalantirJavaFormatStep.java

@@ -18,11 +18,9 @@
 import com.diffplug.spotless.FileSignature;
 import com.diffplug.spotless.FormatterFunc;
 import com.diffplug.spotless.FormatterStep;
+import com.google.errorprone.annotations.InlineMe;
+import com.palantir.javaformat.gradle.FormatterServiceLoader;
 import com.palantir.javaformat.java.FormatterService;
-import java.io.File;
-import java.io.IOException;
-import java.io.Serializable;
-import java.io.UncheckedIOException;
 import java.util.function.Supplier;
 import org.gradle.api.artifacts.Configuration;
 
@@ -35,68 +33,36 @@ private PalantirJavaFormatStep() {}
     private static final String NAME = "open-java-format";
 
     /** Creates a step which formats everything - code, import order, and unused imports. */
-    public static FormatterStep create(Configuration palantirJavaFormat, Supplier<FormatterService> memoizedService) {
+    public static FormatterStep create(Configuration palantirJavaFormat) {
         ensureImplementationNotDirectlyLoadable();
+        // Spotless keeps a step in two forms, and neither can hold the configuration or a loaded formatter, which do
+        // not serialize. The configuration cache stores the jars, resolved when the entry is written at the earliest.
+        // The up-to-date check compares their signature, so that another formatter version makes the task run again;
+        // Spotless takes it when the task runs, or with the configuration cache when the entry is written. The
+        // formatter is loaded from the jars on first use.
         return FormatterStep.createLazy(
-                NAME, () -> new State(palantirJavaFormat::getFiles, memoizedService), State::createFormat);
+                NAME,
+                () -> FileSignature.promise(palantirJavaFormat.getFiles()),
+                FileSignature.Promised::get,
+                PalantirJavaFormatStep::createFormat);
     }
 
-    static final class State implements Serializable {
-        private static final long serialVersionUID = 1L;
-
-        // Kept for state serialization purposes.
-        @SuppressWarnings("unused")
-        private final String stepName = NAME;
-
-        // Spotless' `FormatterStepImpl` implements Java's `Serializable` interface in a weird way:
-        // It serializes this `State` class[1].
-        //
-        // Gradle understands Java's `Serializable`, and uses it to invalidate `@Input`s to tasks.
-        //
-        // Since FormatterStepImpl is an input to `SpotlessTask`[2], anything serialized as part of this `State`
-        // is used for up-to-date checking for the `SpotlessTask`
-        //
-        // [1]
-        // https://github.com/diffplug/spotless/blob/52654ef8c4a6191d983b10a2370d53b1ca023f7d/lib/src/main/java/com/diffplug/spotless/LazyForwardingEquality.java#L68
-        // [2]
-        // https://github.com/diffplug/spotless/blob/f32701212bf8d327c67d10c35316cb80dcdf577b/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessTask.java#L163
-        @SuppressWarnings({"unused", "FieldCanBeLocal"})
-        private FileSignature jarsSignature;
-
-        private final transient Supplier<Iterable<File>> jarsSupplier;
-
-        // Transient as this is not serializable.
-        private final transient Supplier<FormatterService> memoizedFormatter;
-
-        /**
-         * Build a cacheable state for spotless from the given jars, that uses the given {@link FormatterService}.
-         *
-         * @param jarsSupplier Supplies the jars that contain the open-java-format implementation. This is only used for caching and
-         * up-to-dateness purposes.
-         */
-        @SuppressWarnings("for-rollout:NullAway")
-        State(Supplier<Iterable<File>> jarsSupplier, Supplier<FormatterService> memoizedFormatter) {
-            this.jarsSupplier = jarsSupplier;
-            this.memoizedFormatter = memoizedFormatter;
-        }
-
-        @SuppressWarnings("NullableProblems")
-        FormatterFunc createFormat() {
-            return input -> {
-                try {
-                    // Only resolve the jars and compute the signature at execution time!
-                    Iterable<File> jars = jarsSupplier.get();
-
-                    // Not a performance issue, as Spotless caches this
-                    // https://github.com/diffplug/spotless/blob/228eb10af382b19e130d8d9479f7a95238cb4358/lib/src/main/java/com/diffplug/spotless/FileSignature.java#L138-L143
-                    this.jarsSignature = FileSignature.signAsSet(jars);
+    /**
+     * Creates the same step as {@link #create(Configuration)}.
+     *
+     * @deprecated the step loads the formatter from the configuration's jars, and ignores {@code memoizedService}.
+     */
+    @Deprecated
+    @InlineMe(
+            replacement = "PalantirJavaFormatStep.create(palantirJavaFormat)",
+            imports = "com.palantir.javaformat.gradle.spotless.PalantirJavaFormatStep")
+    public static FormatterStep create(Configuration palantirJavaFormat, Supplier<FormatterService> memoizedService) {
+        return create(palantirJavaFormat);
+    }
 
-                    return memoizedFormatter.get().formatSourceReflowStringsAndFixImports(input);
-                } catch (IOException e) {
-                    throw new UncheckedIOException(e);
-                }
-            };
-        }
+    private static FormatterFunc createFormat(FileSignature jars) {
+        FormatterService formatter = FormatterServiceLoader.load(jars.files());
+        return formatter::formatSourceReflowStringsAndFixImports;
     }
 
     private static void ensureImplementationNotDirectlyLoadable() {