Apply errorprone and nullaway

The main java on which Gradle is running is 25 (via Toolchains), therefore
compilation is done with options.release = 17 flag for compatiblity. It
no longer means that project is compiled with Java 17 - it's compiled
with Java 25, with bytecode compatibility with Java 17.

Author: damianmalczewski

.github/copilot-instructions.md

@@ -21,7 +21,9 @@
 
 - **Bootstrap:** No explicit bootstrap step; dependencies managed via Gradle.
 - **Build:**
-    - Run `./gradlew build` from the repository root (or `gradlew.bat build` on Windows).
+    - Run `./gradlew` from the repository root  (or `./gradlew.bat` on Windows), default tasks are `spotlessApply build`
+      so this is a convenience method.
+    - Run `./gradlew build` only if you explicitly want to exclude code formatting for some reason.
     - Java 17+ required.
 - **Test:**
     - Tests run automatically with `./gradlew build` or separately via `./gradlew test`.

.github/workflows/gradle-build.yml

@@ -24,18 +24,22 @@ on:
 
 jobs:
   build:
-    name: Build
+    name: Build (Java ${{ matrix.java }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [17, 21, 25]
     permissions:
       contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Set up JDK 17
+      - name: Set up JDK ${{ matrix.java }}
         uses: actions/setup-java@v5
         with:
-          java-version: "17"
+          java-version: "${{ matrix.java }}"
           distribution: "temurin"
 
       # Configure Gradle for optimal use in GitHub Actions, including caching of downloaded dependencies.

.github/workflows/gradle-dependency-submission.yml

@@ -1,6 +1,6 @@
 name: Dependency Submission
 
-# workflow limited to only files related to gradle dependencies
+# workflow limited to only files related to Gradle dependencies
 on:
   push:
     branches:

README.md

@@ -216,21 +216,31 @@ dependency.
 <details>
 <summary><b>Expand...</b></summary>
 
-Gradle **9.x+** requires **Java 17+** to run, but higher Java versions can also be used. All modules of this project are
-compiled using a **Java 17 toolchain**, so the produced artifacts are compatible with **Java 17**, regardless of the
-Java version Gradle runs on.
+Gradle **9.x+** requires **Java 17** or higher to run. For building the project, Gradle automatically picks up **Java
+25** via **toolchains** and the `foojay-resolver-convention` plugin. This Java version is needed because the project
+uses **ErrorProne** and **NullAway** for static nullness analysis.
+
+The produced artifacts are compatible with **Java 17** thanks to `options.release = 17` in Gradle `JavaCompile` tasks.
+This means that regardless of the Java version used to run Gradle, the resulting bytecode remains compatible.
+
+The **default Gradle tasks** include `spotlessApply` (for code formatting) and `build` (for compilation and tests).The
+simplest way to build the project is to run:
 
 ```bash
-./gradlew build
+./gradlew
 ```
 
-To execute tests use `test` task.
+---
+
+To **execute tests** use `test` task. Tests do not change `options.release` so newer Java API can be used. 
 
 ```bash
 ./gradlew test
 ```
 
-To format the code according to the style defined in [`build.gradle.kts`](./build.gradle.kts) rules use `spotlessApply`
+---
+
+To **format the code** according to the style defined in [`build.gradle.kts`](./build.gradle.kts) rules use `spotlessApply`
 task. **Note** that **building will fail** if code is not properly formatted.
 
 ```bash
@@ -245,7 +255,9 @@ for local development and builds you can choose to skip it and update the year l
 ./gradlew spotlessApply -Pspotless.license-year-enabled
 ```
 
-To publish the built artifacts to local Maven repository, use `publishToMavenLocal` task.
+---
+
+To **publish** the built artifacts to **local Maven repository**, use `publishToMavenLocal` task.
 
 ```bash
 ./gradlew publishToMavenLocal

build.gradle.kts

@@ -43,9 +43,15 @@ spotless {
         target("**/src/**/package-info.java", "**/src/**/module-info.java")
 
         // License headers in these files are not formatted with standard java group, so we need to use custom settings.
-        // The regex is designed find out where the code starts in these files, so the license header can be placed
-        // before it. The code starts with either "package", "import", "module" or "/**" in case of a global JavaDoc.
-        val delimiter = "^(package|import|module|/\\*\\*)"
+        // The regex is designed to find out where the code starts in these files, so the license header can be placed
+        // before it.
+        //
+        // The code starts with either:
+        //
+        // - any annotation (ex. @NullMarked before package declaration),
+        // - package, module or import declaration,
+        // - "/**" in case of a pre-package (or pre-module) JavaDoc.
+        val delimiter = "^(\\s*@|package|import|module|/\\*\\*)"
 
         licenseHeaderFile(licenseHeader, delimiter).updateYearWithLatest(updateLicenseYear)
     }
@@ -84,3 +90,5 @@ spotless {
         lineEndings = LineEnding.UNIX
     }
 }
+
+defaultTasks("spotlessApply", "build")

buildSrc/build.gradle.kts

@@ -8,5 +8,14 @@ plugins {
 version = "current"
 
 repositories {
+    gradlePluginPortal()
     mavenCentral()
 }
+
+dependencies {
+    implementation(plugin(libs.plugins.errorprone))
+}
+
+fun plugin(plugin: Provider<PluginDependency>): Provider<String> = plugin.map {
+    "${it.pluginId}:${it.pluginId}.gradle.plugin:${it.version}"
+}

buildSrc/settings.gradle.kts

@@ -0,0 +1,18 @@
+// Note that usage of version catalogs in buildSrc is not as straightforward as in regular modules.
+// For more information, see:
+// https://docs.gradle.org/current/userguide/version_catalogs.html#sec:buildsrc-version-catalog
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}
+
+rootProject.name = "buildSrc"

buildSrc/src/main/kotlin/internal.errorprone-convention.gradle.kts

@@ -0,0 +1,15 @@
+import net.ltgt.gradle.errorprone.errorprone
+
+plugins {
+    id("internal.java-convention")
+    id("net.ltgt.errorprone")
+}
+
+tasks.withType<JavaCompile>().configureEach {
+    options.errorprone {
+        disableAllChecks.set(true)
+        error("NullAway")
+        option("NullAway:OnlyNullMarked", "true")
+        option("NullAway:JSpecifyMode", "true")
+    }
+}

buildSrc/src/main/kotlin/internal.java-convention.gradle.kts

@@ -0,0 +1,64 @@
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+import org.gradle.api.tasks.testing.logging.TestLogEvent
+
+plugins {
+    id("internal.common-convention")
+    id("java-library")
+}
+
+// The project is built using a JDK 25 toolchain, but the main sources are compiled with --release 17.
+//
+// This means:
+// - Gradle can run on any JDK 17+,
+// - javac from JDK 25 is used,
+// - the produced bytecode and available Java API for main sources are restricted to Java 17.
+//
+// This setup lets us use a modern JDK for tooling (ErrorProne, NullAway) while keeping Java 17 binary compatibility for
+// library consumers.
+//
+// Tests are NOT compiled with --release XYZ, so they may use newer Java APIs.
+
+java {
+    toolchain.languageVersion = JavaLanguageVersion.of(25)
+}
+
+tasks.withType<JavaCompile>().configureEach {
+    options.compilerArgs.add("-parameters")
+    options.encoding = "UTF-8"
+}
+
+tasks.named<JavaCompile>("compileJava") {
+    options.release = 17
+}
+
+tasks.withType<Test>().configureEach {
+    useJUnitPlatform()
+
+    testLogging {
+        events(TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED)
+        exceptionFormat = TestExceptionFormat.SHORT
+        showStandardStreams = true
+    }
+
+    // For resolving warnings from mockito.
+    jvmArgs("-XX:+EnableDynamicAgentLoading")
+
+    systemProperty("user.language", "en")
+    systemProperty("user.country", "US")
+}
+
+tasks.withType<Javadoc>().configureEach {
+    javadocTool = javaToolchains.javadocToolFor { languageVersion.set(JavaLanguageVersion.of(17)) }
+}
+
+tasks.withType<Jar>().configureEach {
+    manifest {
+        attributes["Implementation-Title"] = project.name
+        attributes["Implementation-Version"] = project.version
+        attributes["Created-By"] = "Gradle ${gradle.gradleVersion}"
+    }
+    from("${rootProject.rootDir}/LICENSE") {
+        into("META-INF/")
+        rename { "LICENSE.txt" }
+    }
+}

buildSrc/src/main/kotlin/internal.java-library-convention.gradle.kts

@@ -1,50 +1,13 @@
-import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-
 plugins {
-    id("internal.common-convention")
+    id("internal.java-convention")
     id("java-library")
 }
 
 java {
-    toolchain.languageVersion = JavaLanguageVersion.of(17)
     withSourcesJar()
     withJavadocJar()
 }
 
-tasks.withType<JavaCompile>().configureEach {
-    options.compilerArgs.add("-parameters")
-    options.encoding = "UTF-8"
-}
-
-tasks.withType<Jar>().configureEach {
-    manifest {
-        attributes["Implementation-Title"] = project.name
-        attributes["Implementation-Version"] = project.version
-        attributes["Build-Jdk-Spec"] = java.toolchain.languageVersion.get().toString()
-        attributes["Created-By"] = "Gradle ${gradle.gradleVersion}"
-    }
-    from("${rootProject.rootDir}/LICENSE") {
-        into("META-INF/")
-        rename { "LICENSE.txt" }
-    }
-}
-
-tasks.withType<Test>().configureEach {
-    useJUnitPlatform()
-
-    testLogging {
-        events("passed", "skipped", "failed", "standardOut", "standardError")
-        exceptionFormat = TestExceptionFormat.SHORT
-        showStandardStreams = true
-    }
-
-    // For resolving warnings from mockito.
-    jvmArgs("-XX:+EnableDynamicAgentLoading")
-
-    systemProperty("user.language", "en")
-    systemProperty("user.country", "US")
-}
-
 // buildSrc/src/main/kotlin/internal.common-convention.gradle.kts - "printVersion" task definition
 tasks.withType<PublishToMavenLocal>().configureEach {
     finalizedBy("printVersion")