Move type-use annotations to array brackets during JSpecify migration by timtebeek · Pull Request #1038 · openrewrite/rewrite-migrate-java

timtebeek · 2026-03-31T20:28:44Z

Summary

Fixes MigrateFromJavaxAnnotationApi does not modify annotations to the type level #934
Adds a new MoveAnnotationToArrayType recipe that moves type-use annotations (e.g. @Nullable) from declaration position to the array brackets (e.g. @Nullable byte[] → byte @Nullable[] ), as required by the JSpecify spec.
Wires the recipe into all 6 JSpecify migration recipes in jspecify.yml, running after MoveFieldAnnotationToType.
Handles method return types, method parameters, and field declarations.

Test plan

Unit tests for MoveAnnotationToArrayType: return types, parameters, fields, non-array no-ops, multi-dimensional arrays
Integration test in JSpecifyBestPracticesTest for end-to-end javax → JSpecify migration with array types
All existing jspecify tests continue to pass

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."

…ected 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.

…ArrayType

…notations

steve-aom-elliott · 2026-03-31T21:40:56Z

+                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);


I suppose I'm trying to figure out if we have recipes that are going to be fragile in light of leading annotations being dropped and whether any of our recipes need to be adapted to handle the change in position for the annotations (have not had a chance to dig into this further yet)

Let me know what you'd need to be comfortable seeing this merged!

steve-aom-elliott · 2026-04-02T18:30:35Z

+    void moveNullableToNestedClassArrayField() {
+        rewriteRun(
+          //language=java
+          java(
+            """
+              import javax.annotation.Nullable;
+              import java.util.Map;
+
+              class Foo {
+                  @Nullable
+                  public Map.Entry<String, String>[] entries;
+              }
+              """,
+            """
+              import javax.annotation.Nullable;
+              import java.util.Map;
+
+              class Foo {
+                  public Map.Entry<String, String> @Nullable[] entries;
+              }
+              """
+          )
+        );
+    }


I think this test may actually be incorrect. Based on this, these could be different meanings:

@Nullable X[] x // I believe the nested equivalent would be y.@Nullable X[] x

means individual elements can be null, but not the array itself

X @Nullable [] x // I believe the nested equivalent would be y.X @Nullable [] x

means individual elements cannot be null, but the array can

@Nullable X @Nullable [] x // I believe the nested equivalent would be y.@Nullable X @Nullable [] x

means both individual elements and the array itself can be null

hmm; I thought it was different for the javax nullable annotation:

javax.annotation.Nullable is NOT a TYPE_USE annotation — it only targets METHOD, FIELD, PARAMETER, etc. When someone writes @javax.annotation.Nullable Map.Entry[], the annotation is in declaration position — it doesn’t have the element-vs-array distinction. It’s syntactically equivalent to “this whole thing might be null.”

The recipe deliberately targets pre-migration annotations (before ChangeType renames them to JSpecify). By the time the annotation becomes org.jspecify.annotations.Nullable (which IS TYPE_USE), it’s already in the correct array-bracket position with the intended meaning: “the array reference can be null.”

The annotations targeted by MoveAnnotationToArrayType are:

javax.annotation.*ull* — No @Target at all (JSR-305). Implicitly applies everywhere including TYPE_USE.

jakarta.annotation.*ull* — @Target({METHOD, PARAMETER, FIELD, TYPE_USE}) — yes, TYPE_USE

org.jetbrains.annotations.*ull* — @Target({METHOD, FIELD, PARAMETER, LOCAL_VARIABLE, TYPE_USE}) — yes, TYPE_USE

io.micrometer.core.lang.*ull* — @Target({METHOD, FIELD, PARAMETER, LOCAL_VARIABLE}) — no TYPE_USE

org.springframework.lang.*ull* — @Target({METHOD, PARAMETER, FIELD}) — no TYPE_USE

io.micronaut.core.annotation.*ull* — @Target({METHOD, PARAMETER, FIELD, TYPE_USE, ANNOTATION_TYPE}) — yes, TYPE_USE

So three of the six (jakarta, JetBrains, Micronaut) are explicitly TYPE_USE annotations, and javax is implicitly usable in TYPE_USE positions. Only Micrometer and Spring are purely declaration-position.

Your concern is valid for at least half the migration paths — for those annotations, @Nullable X[] on the element type genuinely has different semantics than X @Nullable[] on the array. The recipe is making a deliberate semantic choice to reposition the annotation to mean "array can be null" rather than "elements can be null."

You could be correct on that. I guess I'm just not as familiar with the intricacies of different targets for annotations and how they affect the interpretation of the statement. Given we're targetting specific sets of annotations, it's probably fine, if just possible to misuse given there aren't target guards in the recipe if you were for example to give it JSpecify annotation FQNs to start with. Would it make sense to just guard against asking to move JSpecify annotations to JSpecify 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.

Move type-use annotations to array brackets during JSpecify migration (…

5420515

…#934)

moderne-meeseeks Bot added this to OpenRewrite Mar 31, 2026

moderne-meeseeks Bot assigned timtebeek Mar 31, 2026

github-project-automation Bot moved this to In Progress in OpenRewrite Mar 31, 2026

timtebeek added 10 commits March 31, 2026 22:46

Fix copyright year, use import, and early returns in MoveAnnotationTo…

ed23fc5

…ArrayType

Narrow annotation type patterns to *ull* to match only nullability an…

6f7b27c

…notations

Replace AtomicReference with find-then-remove using equality check

a64835e

Merge branch 'main' into tim/issue-934-investigation

f40ea20

Use ListUtils.map result equality check instead of stream

b2b687a

Remove AtomicReference and redundant test

4da435e

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

fd94c84

Update generated recipes.csv

4d3de37

timtebeek mentioned this pull request Mar 31, 2026

MigrateFromJavaxAnnotationApi does not modify annotations to the type level #934

Closed

timtebeek marked this pull request as ready for review March 31, 2026 21:25

timtebeek requested a review from steve-aom-elliott March 31, 2026 21:25

steve-aom-elliott reviewed Mar 31, 2026

View reviewed changes

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

steve-aom-elliott reviewed Mar 31, 2026

View reviewed changes

Add test for nested class array type annotation movement

b816016

steve-aom-elliott reviewed Apr 2, 2026

View reviewed changes

timtebeek marked this pull request as draft April 2, 2026 18:41

Skip MoveAnnotationToArrayType for TYPE_USE annotations

b4c7d30

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.

timtebeek marked this pull request as ready for review April 2, 2026 19:03

steve-aom-elliott approved these changes Apr 2, 2026

View reviewed changes

github-project-automation Bot moved this from In Progress to Ready to Review in OpenRewrite Apr 2, 2026

timtebeek merged commit 9e138a7 into main Apr 2, 2026
1 check passed

timtebeek deleted the tim/issue-934-investigation branch April 2, 2026 19:18

github-project-automation Bot moved this from Ready to Review to Done in OpenRewrite Apr 2, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Move type-use annotations to array brackets during JSpecify migration#1038
timtebeek merged 13 commits intomainfrom
tim/issue-934-investigation

timtebeek commented Mar 31, 2026 •

edited by moderne-meeseeks Bot

Loading

Uh oh!

Uh oh!

steve-aom-elliott Mar 31, 2026

Uh oh!

timtebeek Apr 1, 2026

Uh oh!

steve-aom-elliott Apr 2, 2026 •

edited

Loading

Uh oh!

timtebeek Apr 2, 2026

Uh oh!

timtebeek Apr 2, 2026

Uh oh!

steve-aom-elliott Apr 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

timtebeek commented Mar 31, 2026 • edited by moderne-meeseeks Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Uh oh!

steve-aom-elliott Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

timtebeek Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

steve-aom-elliott Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timtebeek Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

timtebeek Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

steve-aom-elliott Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

timtebeek commented Mar 31, 2026 •

edited by moderne-meeseeks Bot

Loading

steve-aom-elliott Apr 2, 2026 •

edited

Loading