Move type-use annotations to array brackets during JSpecify migration (#1038)

* Move type-use annotations to array brackets during JSpecify migration (#934)

* Run MoveAnnotationToArrayType before ChangeType to preserve semantics

Move the recipe before ChangeType in each migration pipeline so it
matches on the old annotation type (e.g. javax.annotation.*). This
avoids incorrectly moving pre-existing JSpecify annotations where
@nullable String[] intentionally means "array of nullable Strings."

* Add test: pre-existing JSpecify array-of-nullable-elements is not affected

Verifies that a project with both javax annotations (to migrate) and
pre-existing JSpecify @nullable String[] (meaning array of nullable
elements) only migrates the javax annotations without touching the
already-correct JSpecify annotations.

* Fix copyright year, use import, and early returns in MoveAnnotationToArrayType

* Narrow annotation type patterns to *ull* to match only nullability annotations

* Replace AtomicReference with find-then-remove using equality check

* Use ListUtils.map result equality check instead of stream

* Remove AtomicReference and redundant test

* Capture match from ListUtils.map lambda, drop separate for loop

* Update generated recipes.csv

* Add test for nested class array type annotation movement

* Skip MoveAnnotationToArrayType for TYPE_USE annotations

Jakarta, JetBrains, and Micronaut annotations target TYPE_USE, so
`@Nullable X[]` (element nullable) already has distinct semantics from
`X @nullable[]` (array nullable). Moving them would change meaning.

Author: timtebeek

src/main/java/org/openrewrite/java/migrate/jspecify/MoveAnnotationToArrayType.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2026 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * 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 org.openrewrite.java.migrate.jspecify;
+
+import lombok.EqualsAndHashCode;
+import lombok.Value;
+import org.openrewrite.*;
+import org.openrewrite.internal.ListUtils;
+import org.openrewrite.java.JavaIsoVisitor;
+import org.openrewrite.java.TypeMatcher;
+import org.openrewrite.java.search.UsesType;
+import org.openrewrite.java.tree.*;
+
+import org.jspecify.annotations.Nullable;
+
+import java.util.List;
+
+import static java.util.Collections.singletonList;
+
+@EqualsAndHashCode(callSuper = false)
+@Value
+public class MoveAnnotationToArrayType extends Recipe {
+
+    @Option(displayName = "Annotation type",
+            description = "The type of annotation to move to the array type. " +
+                          "Should target the pre-migration annotation type to avoid changing the semantics " +
+                          "of pre-existing type-use annotations on object arrays.",
+            example = "javax.annotation.*ull*")
+    String annotationType;
+
+    String displayName = "Move annotation to array type";
+
+    String description = "When an annotation like `@Nullable` is applied to an array type in declaration position, " +
+                         "this recipe moves it to the array brackets. " +
+                         "For example, `@Nullable byte[]` becomes `byte @Nullable[]`. " +
+                         "Best used before `ChangeType` in a migration pipeline, targeting the pre-migration annotation type.";
+
+    @Override
+    public TreeVisitor<?, ExecutionContext> getVisitor() {
+        return Preconditions.check(new UsesType<>(annotationType, null), new JavaIsoVisitor<ExecutionContext>() {
+            final TypeMatcher typeMatcher = new TypeMatcher(annotationType);
+
+            @Override
+            public J.MethodDeclaration visitMethodDeclaration(J.MethodDeclaration method, ExecutionContext ctx) {
+                J.MethodDeclaration md = super.visitMethodDeclaration(method, ctx);
+
+                if (!(md.getReturnTypeExpression() instanceof J.ArrayType)) {
+                    return md;
+                }
+
+                J.@Nullable Annotation[] match = {null};
+                List<J.Annotation> leading = ListUtils.map(md.getLeadingAnnotations(), a -> {
+                    if (match[0] == null && matchesType(a)) {
+                        match[0] = a;
+                        return null;
+                    }
+                    return a;
+                });
+                if (leading == md.getLeadingAnnotations()) {
+                    return md;
+                }
+                md = md.withLeadingAnnotations(leading);
+
+                J.ArrayType arrayType = (J.ArrayType) md.getReturnTypeExpression();
+                //noinspection DataFlowIssue
+                arrayType = arrayType.withAnnotations(
+                        singletonList(match[0].withPrefix(Space.SINGLE_SPACE)));
+                md = md.withReturnTypeExpression(arrayType);
+                if (md.getLeadingAnnotations().isEmpty()) {
+                    md = md.withReturnTypeExpression(arrayType.withPrefix(
+                            arrayType.getPrefix().withWhitespace("")));
+                }
+                return autoFormat(md, arrayType, ctx, getCursor().getParentOrThrow());
+            }
+
+            @Override
+            public J.VariableDeclarations visitVariableDeclarations(J.VariableDeclarations multiVariable, ExecutionContext ctx) {
+                J.VariableDeclarations mv = super.visitVariableDeclarations(multiVariable, ctx);
+
+                if (!(mv.getTypeExpression() instanceof J.ArrayType)) {
+                    return mv;
+                }
+
+                J.@Nullable Annotation[] match = {null};
+                List<J.Annotation> leading = ListUtils.map(mv.getLeadingAnnotations(), a -> {
+                    if (match[0] == null && matchesType(a)) {
+                        match[0] = a;
+                        return null;
+                    }
+                    return a;
+                });
+                if (leading == mv.getLeadingAnnotations()) {
+                    return mv;
+                }
+                mv = mv.withLeadingAnnotations(leading);
+
+                J.ArrayType arrayType = (J.ArrayType) mv.getTypeExpression();
+                //noinspection DataFlowIssue
+                arrayType = arrayType.withAnnotations(
+                        singletonList(match[0].withPrefix(Space.SINGLE_SPACE)));
+                if (mv.getLeadingAnnotations().isEmpty()) {
+                    arrayType = arrayType.withPrefix(arrayType.getPrefix().withWhitespace(""));
+                }
+                mv = mv.withTypeExpression(arrayType);
+                return autoFormat(mv, arrayType, ctx, getCursor().getParentOrThrow());
+            }
+
+            private boolean matchesType(J.Annotation ann) {
+                JavaType.FullyQualified fq = TypeUtils.asFullyQualified(ann.getType());
+                return fq != null && typeMatcher.matches(fq);
+            }
+        });
+    }
+}

src/main/resources/META-INF/rewrite/jspecify.yml

@@ -65,6 +65,8 @@ recipeList:
       version: latest.release
       onlyIfUsing: javax.annotation.*ull*
       acceptTransitive: true
+  - org.openrewrite.java.migrate.jspecify.MoveAnnotationToArrayType:
+      annotationType: javax.annotation.*ull*
   - org.openrewrite.java.ChangeType:
       oldFullyQualifiedTypeName: javax.annotation.Nullable
       newFullyQualifiedTypeName: org.jspecify.annotations.Nullable
@@ -93,6 +95,8 @@ recipeList:
       version: 1.0.0
       onlyIfUsing: jakarta.annotation.*ull*
       acceptTransitive: true
+  # Not moving jakarta annotations to array brackets; they target TYPE_USE,
+  # so `@Nullable X[]` (element nullable) already differs from `X @Nullable[]` (array nullable).
   - org.openrewrite.java.ChangeType:
       oldFullyQualifiedTypeName: jakarta.annotation.Nullable
       newFullyQualifiedTypeName: org.jspecify.annotations.Nullable
@@ -117,6 +121,8 @@ recipeList:
       version: 1.0.0
       onlyIfUsing: org.jetbrains.annotations.*ull*
       acceptTransitive: true
+  # Not moving JetBrains annotations to array brackets; they target TYPE_USE,
+  # so `@Nullable X[]` (element nullable) already differs from `X @Nullable[]` (array nullable).
   - org.openrewrite.java.ChangeType:
       oldFullyQualifiedTypeName: org.jetbrains.annotations.Nullable
       newFullyQualifiedTypeName: org.jspecify.annotations.Nullable
@@ -141,6 +147,8 @@ recipeList:
       version: 1.0.0
       onlyIfUsing: org.springframework.lang.*ull*
       acceptTransitive: true
+  - org.openrewrite.java.migrate.jspecify.MoveAnnotationToArrayType:
+      annotationType: io.micrometer.core.lang.*ull*
   - org.openrewrite.java.ChangeType:
       oldFullyQualifiedTypeName: io.micrometer.core.lang.Nullable
       newFullyQualifiedTypeName: org.jspecify.annotations.Nullable
@@ -165,6 +173,8 @@ recipeList:
       version: 1.0.0
       onlyIfUsing: org.springframework.lang.*ull*
       acceptTransitive: true
+  - org.openrewrite.java.migrate.jspecify.MoveAnnotationToArrayType:
+      annotationType: org.springframework.lang.*ull*
   - org.openrewrite.java.ChangeType:
       oldFullyQualifiedTypeName: org.springframework.lang.Nullable
       newFullyQualifiedTypeName: org.jspecify.annotations.Nullable
@@ -189,6 +199,8 @@ recipeList:
       version: 1.0.0
       onlyIfUsing: io.micronaut.core.annotation.*ull*
       acceptTransitive: true
+  # Not moving Micronaut annotations to array brackets; they target TYPE_USE,
+  # so `@Nullable X[]` (element nullable) already differs from `X @Nullable[]` (array nullable).
   - org.openrewrite.java.ChangeType:
       oldFullyQualifiedTypeName: io.micronaut.core.annotation.Nullable
       newFullyQualifiedTypeName: org.jspecify.annotations.Nullable