Use JSpecify's @nullable, and no other nullness annotation

jsr305's javax.annotation.Nullable gives way to
org.jspecify.annotations.Nullable, and the jsr305 dependency to
jspecify 1.0.1, the version Guava already brings. Obs's
@CheckReturnValue, the other jsr305 annotation in use, is now Error
Prone's.

JetBrains' @NotNull goes from the IntelliJ plugin: what is not
@nullable is non-null, and NullAway checks it. The plugin does not
instrument its code, so the annotations added no runtime checks either.

JSpecify's @nullable is a type-use annotation. Where it stood above an
@OverRide it now follows it, next to the return type it annotates.
CLAUDE.md names the annotation and where it goes on nested and array
types.

Author: abashev

CLAUDE.md

@@ -8,8 +8,10 @@ Building and testing: the README's "Building and testing locally" section. Gradl
 - **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.
-- **Nullability.** One annotation, `javax.annotation.Nullable` (jsr305), the one the code uses; do not add another
-  `Nullable`.
+- **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
+  the brackets (`String @Nullable []`).
 - **Local variables.** `var` wherever the initializer gives the type unchanged, in `for` loops too. Not where it
   would box a primitive (`for (var n : List<Integer>)`), and not without an initializer that has a type of its own
   (a lambda, `null`).

gradle/libs.versions.toml

@@ -39,7 +39,7 @@ jackson-datatype-jdk8 = { module = "com.fasterxml.jackson.datatype:jackson-datat
 jackson-module-parameterNames = { module = "com.fasterxml.jackson.module:jackson-module-parameter-names", version = "2.22.4" }
 jmh-core = { module = "org.openjdk.jmh:jmh-core", version = "1.37" }
 jmh-generator-annprocess = { module = "org.openjdk.jmh:jmh-generator-annprocess", version = "1.37" }
-jsr305 = { module = "com.google.code.findbugs:jsr305", version = "3.0.2" }
+jspecify = { module = "org.jspecify:jspecify", version = "1.0.1" }
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version = "6.1.3" }
 junit-jupiter-migrationsupport = { module = "org.junit.jupiter:junit-jupiter-migrationsupport", version = "6.1.3" }
 junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher", version = "6.1.3" }

open-java-format-eclipse-plugin/build.gradle

@@ -28,7 +28,7 @@ dependencies {
     compileOnly libs.eclipse.text
 
     implementation project(':open-java-format')
-    implementation libs.jsr305
+    implementation libs.jspecify
 }
 
 // The dependencies embedded in the plugin jar. Named once, so the manifest can list exactly what

open-java-format-eclipse-plugin/src/main/java/com/palantir/javaformat/java/PalantirJavaFormatter.java

@@ -19,30 +19,30 @@
 import com.palantir.javaformat.java.SnippetFormatter.SnippetKind;
 import java.util.ArrayList;
 import java.util.List;
-import javax.annotation.Nullable;
 import org.eclipse.jdt.core.dom.ASTParser;
 import org.eclipse.jdt.core.formatter.CodeFormatter;
 import org.eclipse.jface.text.IRegion;
 import org.eclipse.jface.text.Region;
 import org.eclipse.text.edits.MultiTextEdit;
 import org.eclipse.text.edits.ReplaceEdit;
 import org.eclipse.text.edits.TextEdit;
+import org.jspecify.annotations.Nullable;
 
 /** Runs the Palantir Java formatter on the given code. */
 public class PalantirJavaFormatter extends CodeFormatter {
 
     private static final int INDENTATION_SIZE = 4;
 
-    @Nullable
     @Override
+    @Nullable
     public TextEdit format(
             int kind, String source, int offset, int length, int indentationLevel, String _lineSeparator) {
         IRegion[] regions = new IRegion[] {new Region(offset, length)};
         return formatInternal(kind, source, regions, indentationLevel);
     }
 
-    @Nullable
     @Override
+    @Nullable
     public TextEdit format(int kind, String source, IRegion[] regions, int indentationLevel, String _lineSeparator) {
         return formatInternal(kind, source, regions, indentationLevel);
     }

open-java-format-idea-plugin/build.gradle

@@ -81,7 +81,7 @@ dependencies {
     testImplementation libs.assertj
     testImplementation libs.junit.jupiter
     testImplementation libs.junit.platform.launcher
-    implementation libs.jsr305
+    implementation libs.jspecify
 }
 
 intellijPlatform {

open-java-format-idea-plugin/src/main/java/com/palantir/javaformat/intellij/EmbeddedNativeImage.java

@@ -43,7 +43,7 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.regex.Pattern;
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * The native binary the plugin downloads for the IDE's platform, one for the whole IDE. It is kept in the IDE's system

open-java-format-idea-plugin/src/main/java/com/palantir/javaformat/intellij/InitialConfigurationStartupActivity.java

@@ -18,11 +18,10 @@
 
 import com.intellij.openapi.project.Project;
 import com.intellij.openapi.startup.StartupActivity;
-import org.jetbrains.annotations.NotNull;
 
 public final class InitialConfigurationStartupActivity implements StartupActivity.DumbAware {
     @Override
-    public void runActivity(@NotNull Project project) {
+    public void runActivity(Project project) {
         PalantirJavaFormatSettings settings = PalantirJavaFormatSettings.getInstance(project);
         if (settings.isUninitialized()) {
             settings.setEnabled(false);

open-java-format-idea-plugin/src/main/java/com/palantir/javaformat/intellij/NativeImageNoticeStartupActivity.java

@@ -22,8 +22,7 @@
 import com.intellij.openapi.startup.StartupActivity;
 import com.palantir.javaformat.intellij.EmbeddedNativeImage.Status;
 import java.util.Optional;
-import javax.annotation.Nullable;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Tells the user, as the IDE does about outdated spelling dictionaries, when the embedded native binary is older than
@@ -41,7 +40,7 @@ record Missing() implements Notice {}
     }
 
     @Override
-    public void runActivity(@NotNull Project project) {
+    public void runActivity(Project project) {
         var embedded = EmbeddedNativeImage.getInstance();
         embedded.removeStale();
 

open-java-format-idea-plugin/src/main/java/com/palantir/javaformat/intellij/PalantirJavaFormatConfigurable.java

@@ -41,7 +41,6 @@
 import java.nio.file.InvalidPathException;
 import java.nio.file.Path;
 import java.util.Optional;
-import javax.annotation.Nullable;
 import javax.swing.Box;
 import javax.swing.JCheckBox;
 import javax.swing.JComponent;
@@ -50,7 +49,7 @@
 import javax.swing.JTextArea;
 import javax.swing.event.DocumentEvent;
 import org.jetbrains.annotations.Nls;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.Nullable;
 
 class PalantirJavaFormatConfigurable extends BaseConfigurable implements SearchableConfigurable {
 
@@ -130,14 +129,13 @@ protected void textChanged(DocumentEvent event) {
                 .getPanel();
     }
 
-    @NotNull
     @Override
     public String getId() {
         return "open-java-format.settings";
     }
 
-    @Nullable
     @Override
+    @Nullable
     public Runnable enableSearch(String option) {
         return null;
     }
@@ -148,14 +146,14 @@ public String getDisplayName() {
         return "open-java-format Settings";
     }
 
-    @Nullable
     @Override
+    @Nullable
     public String getHelpTopic() {
         return null;
     }
 
-    @Nullable
     @Override
+    @Nullable
     public JComponent createComponent() {
         if (uiDisposable == null) {
             uiDisposable = Disposer.newDisposable("open-java-format settings page");

open-java-format-idea-plugin/src/main/java/com/palantir/javaformat/intellij/PalantirJavaFormatFormattingService.java

@@ -33,9 +33,8 @@
 import com.palantir.javaformat.java.FormatterException;
 import com.palantir.javaformat.java.FormatterService;
 import com.palantir.javaformat.java.Replacement;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.Nullable;
 
-import javax.annotation.Nullable;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
@@ -57,7 +56,7 @@ class PalantirJavaFormatFormattingService extends AsyncDocumentFormattingService
     private PluginDescriptor pluginDescriptor;
 
     @Override
-    public void setPluginDescriptor(@NotNull PluginDescriptor pluginDescriptor) {
+    public void setPluginDescriptor(PluginDescriptor pluginDescriptor) {
         this.pluginDescriptor = pluginDescriptor;
     }
 
@@ -66,7 +65,7 @@ Optional<PluginDescriptor> getPluginDescriptor() {
     }
 
     @Override
-    protected FormattingTask createFormattingTask(@NotNull AsyncFormattingRequest request) {
+    protected FormattingTask createFormattingTask(AsyncFormattingRequest request) {
         Project project = request.getContext().getProject();
         // The marketplace verifier reports this class as experimental, and newer IDEs also deprecate it. It stays:
         // its replacement, com.intellij.ide.trustedProjects.TrustedProjects, is @ApiStatus.Internal — a worse thing
@@ -84,22 +83,22 @@ protected FormattingTask createFormattingTask(@NotNull AsyncFormattingRequest re
     }
 
     @Override
-    protected @NotNull String getNotificationGroupId() {
+    protected String getNotificationGroupId() {
         return Notifications.PARSING_ERROR_NOTIFICATION_GROUP;
     }
 
     @Override
-    protected @NotNull @NlsSafe String getName() {
+    protected @NlsSafe String getName() {
         return "open-java-format";
     }
 
     @Override
-    public @NotNull Set<Feature> getFeatures() {
+    public Set<Feature> getFeatures() {
         return Set.of(Feature.FORMAT_FRAGMENTS);
     }
 
     @Override
-    public boolean canFormat(@NotNull PsiFile file) {
+    public boolean canFormat(PsiFile file) {
         return JavaFileType.INSTANCE.equals(file.getFileType())
                 && PalantirJavaFormatSettings.getInstance(file.getProject()).isEnabled();
     }