feat!(*): Migrate to JSpecify

.checkstyle/checkstyle.xml

@@ -101,7 +101,7 @@
 
     <!-- https://checkstyle.org/config_imports.html#IllegalImport -->
     <module name="IllegalImport">
-      <property name="illegalPkgs" value="sun, jdk, com.sun"/>
+      <property name="illegalPkgs" value="sun, jdk, com.sun, org.jetbrains.annotations"/>
     </module>
 
     <!-- https://checkstyle.org/config_coding.html#IllegalTokenText -->

build.gradle

@@ -17,7 +17,7 @@ indraSonatype {
 }
 
 dependencies {
-  compileOnlyApi libs.jetbrainsAnnotations
+  compileOnlyApi libs.jspecify
   implementation gradleApi()
 
   testImplementation platform(libs.junit.bom)

gradle/libs.versions.toml

@@ -9,7 +9,7 @@ stylecheck = "0.2.1"
 errorprone = "2.30.0"
 
 [libraries]
-jetbrainsAnnotations = "org.jetbrains:annotations:25.0.0"
+jspecify = { module = "org.jspecify:jspecify", version = "1.0.0" }
 
 # test
 junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }

mammoth-test/build.gradle

@@ -3,7 +3,7 @@ description = "JUnit extensions for testing Gradle plugins"
 dependencies {
   api gradleApi()
   api gradleTestKit()
-  compileOnlyApi libs.jetbrainsAnnotations
+  compileOnlyApi libs.jspecify
   api platform(libs.junit.bom)
   api libs.junit.api
   implementation libs.junit.platformCommons

mammoth-test/src/main/java/net/kyori/mammoth/test/GradleFunctionalTestExtension.java

@@ -36,8 +36,8 @@
 import java.util.List;
 import java.util.Optional;
 import java.util.stream.Stream;
-import javax.annotation.Nullable;
 import org.gradle.util.GradleVersion;
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.extension.Extension;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.TestTemplateInvocationContext;

mammoth-test/src/main/java/net/kyori/mammoth/test/TestContext.java

@@ -37,7 +37,6 @@
 import java.util.regex.Pattern;
 import org.gradle.testkit.runner.BuildResult;
 import org.gradle.testkit.runner.GradleRunner;
-import org.jetbrains.annotations.NotNull;
 import org.junit.jupiter.api.Assertions;
 
 import static java.util.Objects.requireNonNull;
@@ -78,11 +77,11 @@ public final class TestContext {
    * @return the output directory
    * @since 1.1.0
    */
-  public @NotNull Path outputDirectory() {
+  public Path outputDirectory() {
     return this.outputDirectory;
   }
 
-  @NotNull String gradleVersion() {
+  String gradleVersion() {
     return this.gradleVersion;
   }
 
@@ -93,7 +92,7 @@ public final class TestContext {
    * @throws IOException if an error occurs writing the input file to disk
    * @since 1.1.0
    */
-  public void copyInput(final @NotNull String name) throws IOException {
+  public void copyInput(final String name) throws IOException {
     this.copyInput(name, name);
   }
 
@@ -105,7 +104,7 @@ public void copyInput(final @NotNull String name) throws IOException {
    * @throws IOException if an error occurs writing the input file to disk
    * @since 1.1.0
    */
-  public void copyInput(final @NotNull String fromName, final @NotNull String toName) throws IOException {
+  public void copyInput(final String fromName, final String toName) throws IOException {
     requireNonNull(fromName, "fromName");
     requireNonNull(toName, "toName");
     try (final InputStream is = this.resourceBase.getResourceAsStream(this.testName + "/in/" + fromName)) {
@@ -130,7 +129,7 @@ public void copyInput(final @NotNull String fromName, final @NotNull String toNa
    * @throws IOException if an error occurs writing the text
    * @since 1.2.0
    */
-  public void writeText(final @NotNull String destination, final @NotNull String text) throws IOException {
+  public void writeText(final String destination, final String text) throws IOException {
     requireNonNull(destination, "destination");
     requireNonNull(text, "text");
 
@@ -149,7 +148,7 @@ public void writeText(final @NotNull String destination, final @NotNull String t
    * @throws IOException if thrown while attempting to read the output file
    * @since 1.1.0
    */
-  public @NotNull String readOutput(final @NotNull String fileName) throws IOException {
+  public String readOutput(final String fileName) throws IOException {
     final StringBuilder builder = new StringBuilder();
     try (final BufferedReader reader = Files.newBufferedReader(this.outputDirectory.resolve(fileName), StandardCharsets.UTF_8)) {
       final char[] buffer = new char[8192];
@@ -169,7 +168,7 @@ public void writeText(final @NotNull String destination, final @NotNull String t
    * @throws IOException if an error occurs reading the text
    * @since 1.2.0
    */
-  public void assertOutputEqualsLiteral(final @NotNull String destination, final @NotNull String text) throws IOException {
+  public void assertOutputEqualsLiteral(final String destination, final String text) throws IOException {
     requireNonNull(destination, "destination");
     requireNonNull(text, "text");
 
@@ -188,7 +187,7 @@ public void assertOutputEqualsLiteral(final @NotNull String destination, final @
    * @throws IOException if failed to read one of the files
    * @since 1.1.0
    */
-  public void assertOutputEquals(final @NotNull String resourceName, final @NotNull String fileName) throws IOException {
+  public void assertOutputEquals(final String resourceName, final String fileName) throws IOException {
     final String actualOutput = this.readOutput(fileName);
 
     final StringBuilder builder = new StringBuilder();
@@ -215,7 +214,7 @@ public void assertOutputEquals(final @NotNull String resourceName, final @NotNul
    * @return the new runner
    * @since 1.1.0
    */
-  public @NotNull GradleRunner runner(final @NotNull String@NotNull... extraArgs) {
+  public GradleRunner runner(final String... extraArgs) {
     final List<String> args = new ArrayList<>(this.commonArguments.size() + extraArgs.length);
     args.addAll(this.commonArguments);
     Collections.addAll(args, extraArgs);
@@ -234,7 +233,7 @@ public void assertOutputEquals(final @NotNull String resourceName, final @NotNul
    * @return the result of an executed build
    * @since 1.1.0
    */
-  public @NotNull BuildResult build(final @NotNull String@NotNull... extraArgs) {
+  public BuildResult build(final String... extraArgs) {
     return this.runner(extraArgs).build();
   }
 

mammoth-test/src/main/java/net/kyori/mammoth/test/package-info.java

@@ -28,4 +28,7 @@
  * annotating methods that have a parameter of either type {@link net.kyori.mammoth.test.TestContext}
  * or {@link org.gradle.testkit.runner.GradleRunner}.</p>
  */
+@NullMarked
 package net.kyori.mammoth.test;
+
+import org.jspecify.annotations.NullMarked;

src/main/java/net/kyori/mammoth/Configurable.java

@@ -24,8 +24,7 @@
 package net.kyori.mammoth;
 
 import org.gradle.api.Action;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 import static java.util.Objects.requireNonNull;
 
@@ -47,7 +46,7 @@ private Configurable() {
    * @return the provided {@code instance}
    * @since 1.0.0
    */
-  public static <T> @NotNull T configure(final @NotNull T instance, final @NotNull Action<T> configureAction) {
+  public static <T> T configure(final T instance, final Action<T> configureAction) {
     requireNonNull(configureAction, "configureAction").execute(instance);
     return instance;
   }
@@ -61,7 +60,7 @@ private Configurable() {
    * @return the provided {@code instance}
    * @since 1.0.0
    */
-  public static <T> @NotNull T configureIfNonNull(final @NotNull T instance, final @Nullable Action<T> configureAction) {
+  public static <T> T configureIfNonNull(final T instance, final @Nullable Action<T> configureAction) {
     if (configureAction != null) {
       configureAction.execute(instance);
     }

src/main/java/net/kyori/mammoth/GradleCompat.java

@@ -28,7 +28,7 @@
 import org.gradle.api.Project;
 import org.gradle.api.provider.Provider;
 import org.gradle.util.GradleVersion;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 final class GradleCompat {
   static final boolean SHOULD_USE_CONVENTION = hasMethod(Project.class, "getConvention") && !hasMinGradleVersion("8.2");

src/main/java/net/kyori/mammoth/IsolatingClassLoader.java

@@ -30,8 +30,7 @@
 import java.util.Iterator;
 import java.util.Set;
 import org.gradle.api.file.FileCollection;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A factory for classloaders that will load classes from themselves rather than its parent where possible.
@@ -54,7 +53,7 @@ private IsolatingClassLoader() {
    * @return the newly created loader
    * @since 1.4.0
    */
-  public static @NotNull URLClassLoader isolatingClassLoader(final @Nullable ClassLoader parent, final @NotNull URL @NotNull... urls) {
+  public static URLClassLoader isolatingClassLoader(final @Nullable ClassLoader parent, final URL... urls) {
     return new IsolatingClassLoaderImpl(urls, parent);
   }
 
@@ -66,7 +65,7 @@ private IsolatingClassLoader() {
    * @return the newly created loader
    * @since 1.4.0
    */
-  public static @NotNull URLClassLoader isolatingClassLoader(final @Nullable ClassLoader parent, final @NotNull FileCollection files) {
+  public static URLClassLoader isolatingClassLoader(final @Nullable ClassLoader parent, final FileCollection files) {
     final Set<File> unwrapped = files.getFiles();
     final URL[] urls = new URL[unwrapped.size()];
     final Iterator<File> it = files.iterator();

src/main/java/net/kyori/mammoth/IsolatingClassLoaderImpl.java

@@ -28,25 +28,24 @@
 import java.net.URLClassLoader;
 import java.util.Enumeration;
 import java.util.NoSuchElementException;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 final class IsolatingClassLoaderImpl extends URLClassLoader {
   static {
     ClassLoader.registerAsParallelCapable();
   }
 
-  private final ClassLoader parent;
+  private final @Nullable ClassLoader parent;
 
   // todo: maybe add transformer function (UnaryOperator<byte[]>)? just for fun
   // todo: add a filter
-  IsolatingClassLoaderImpl(final URL[] urls, final ClassLoader parent) {
+  IsolatingClassLoaderImpl(final URL[] urls, final @Nullable ClassLoader parent) {
     super(urls, parent);
     this.parent = parent;
   }
 
   @Override
-  protected @Nullable Class<?> loadClass(final @NotNull String name, final boolean resolve) throws ClassNotFoundException {
+  protected @Nullable Class<?> loadClass(final String name, final boolean resolve) throws ClassNotFoundException {
     synchronized (this.getClassLoadingLock(name)) {
       Class<?> result = this.findLoadedClass(name);
       if (result == null) {
@@ -78,7 +77,7 @@ final class IsolatingClassLoaderImpl extends URLClassLoader {
   }
 
   @Override
-  public @NotNull Enumeration<URL> getResources(final String name) throws IOException {
+  public Enumeration<URL> getResources(final String name) throws IOException {
     return new Enumeration<URL>() {
       @Nullable Enumeration<URL> active = IsolatingClassLoaderImpl.this.findResources(name);
       @Nullable Enumeration<URL> staged = IsolatingClassLoaderImpl.this.parent == null
@@ -102,7 +101,7 @@ public boolean hasMoreElements() {
       }
 
       @Override
-      public @NotNull URL nextElement() {
+      public URL nextElement() {
         final @Nullable Enumeration<URL> component = this.nextComponent();
         if (component == null) {
           throw new NoSuchElementException();

src/main/java/net/kyori/mammoth/ProjectOrSettingsPlugin.java

@@ -32,8 +32,7 @@
 import org.gradle.api.plugins.PluginContainer;
 import org.gradle.api.tasks.TaskContainer;
 import org.gradle.util.GradleVersion;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A plugin that can be applied to either a {@link Project} or {@link Settings}.
@@ -42,7 +41,7 @@
  */
 public interface ProjectOrSettingsPlugin extends Plugin<Object> {
   @Override
-  default void apply(final @NotNull Object target) {
+  default void apply(final Object target) {
     if (target instanceof Project) {
       final Project project = (Project) target;
       GradleCompat.requireMinimumVersion(this.minimumGradleVersion(), this, project.getDisplayName());
@@ -71,10 +70,10 @@ default void apply(final @NotNull Object target) {
    * @since 1.3.0
    */
   void applyToProject(
-    final @NotNull Project target,
-    final @NotNull PluginContainer plugins,
-    final @NotNull ExtensionContainer extensions,
-    final @NotNull TaskContainer tasks
+    final Project target,
+    final PluginContainer plugins,
+    final ExtensionContainer extensions,
+    final TaskContainer tasks
   );
 
   /**
@@ -86,9 +85,9 @@ void applyToProject(
    * @since 1.3.0
    */
   void applyToSettings(
-    final @NotNull Settings target,
-    final @NotNull PluginContainer plugins,
-    final @NotNull ExtensionContainer extensions
+    final Settings target,
+    final PluginContainer plugins,
+    final ExtensionContainer extensions
   );
 
   /**
@@ -108,7 +107,7 @@ void applyToSettings(
    * @return whether the Settings that created the provided project has this plugin applied
    * @since 1.3.0
    */
-  default boolean isAppliedToSettingsOf(final @NotNull Project project) {
+  default boolean isAppliedToSettingsOf(final Project project) {
     return project.getGradle().getPlugins().hasPlugin(this.getClass());
   }
 }

src/main/java/net/kyori/mammoth/ProjectPlugin.java

@@ -31,8 +31,7 @@
 import org.gradle.api.plugins.PluginContainer;
 import org.gradle.api.tasks.TaskContainer;
 import org.gradle.util.GradleVersion;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A more friendly interface for creating a {@link Plugin} that operates on a {@link Project}.
@@ -44,7 +43,7 @@
 public interface ProjectPlugin extends Plugin<Project> {
   @Override
   @SuppressWarnings("deprecation") // workaround
-  default void apply(final @NotNull Project project) {
+  default void apply(final Project project) {
     // Check version
     GradleCompat.requireMinimumVersion(this.minimumGradleVersion(), this, project.getDisplayName());
 
@@ -79,11 +78,11 @@ default void apply(final @NotNull Project project) {
    */
   @Deprecated
   default void apply(
-    final @NotNull Project project,
-    final @NotNull PluginContainer plugins,
-    final @NotNull ExtensionContainer extensions,
-    final @NotNull Convention convention,
-    final @NotNull TaskContainer tasks
+    final Project project,
+    final PluginContainer plugins,
+    final ExtensionContainer extensions,
+    final Convention convention,
+    final TaskContainer tasks
   ) {
     this.apply(project, plugins, extensions, tasks);
   }
@@ -98,10 +97,10 @@ default void apply(
    * @since 1.1.0
    */
   default void apply(
-    final @NotNull Project project,
-    final @NotNull PluginContainer plugins,
-    final @NotNull ExtensionContainer extensions,
-    final @NotNull TaskContainer tasks
+    final Project project,
+    final PluginContainer plugins,
+    final ExtensionContainer extensions,
+    final TaskContainer tasks
   ) {
     throw new GradleException("The plugin in class " + this.getClass() + " has not been updated" +
       "to override the non-Convention apply method in ProjectPlugin!");