Migrate to JSpecify annotations

[jvandort]

Expected Behavior

Since we have now merged Kotlin 1.8.20 support into Gradle, we should now be able to migrate to JSpecify annotations.

Current Behavior (optional)

We currently use javax.annotation.Nonnull and org.jetbrains.annotations.NotNull annotations on Gradle's own @NonNullApi. We should investigate if we can instead annotate this annotation with one of JSPecify's annotations, or see if we can completely migrate to an alternative provided by JSpecify.

Context

Some things to consider:

• How would this change interact with javax.annotation.Nullable annotations we use on methods and fields in the codebase?
• What is the migration path to using JSpecify annotations instead of javax annotations throughout the codebase?
• Will switching to JSpecify annotations affect Kotlin integration in any way in terms of source or binary compatibility.

[octylFractal]

We should migrate to the NullMarked annotation instead of using @NonNullApi.

[eskatos]

The way the support for provider.map { null } was done in #19088 actually rely on a Kotlin compiler bug in handling nullability annotations. With jsr305 or jetbrains annotations it is currently impossible to represent that use case. JSpecify should work.

As part of this work we should make sure we can remove the workaround introduced in c3168f2 that adds a kotlin compiler flag to restore the compiler bug (along with loooots of type system imprecisions).

[lptr]

Is this actually planned for 8.3? Would be lovely.

[octylFractal]

Yes, it is.

[vlsi]

https://github.com/jspecify/jspecify#jspecify

Any and all aspects of the API and specifications are subject to change prior to the 1.0 release. Using the annotations in a released library is not recommended.

:(

[octylFractal]

See the more recently-updated https://github.com/jspecify/jspecify/wiki/adoption, we feel it is safe to adopt now. Assuming there are no major issues and it improves Kotlin DSL nullness, it should be a net positive overall.

[kevinb9n]

Whoops, I should have fixed that wording on the main github page a while ago.

The jar is very safe to depend on. The absolute most we might change in the actual artifact at this point would be to remove @Target(METHOD) from @NullMarked and @NullUnmarked. Even if you'd been using them on methods, it wouldn't cause you any trouble (worse than having avoided them in the first place) and should be a nonevent to clients as well. No other removals or renames (or the bizarre addition of a mandatory default-less attribute) will be considered.

[octylFractal]

Blocked by https://youtrack.jetbrains.com/issue/KT-59352 and another potentially related issue.

[eskatos]

KT-59352 and the related blocking issue are both fixed in Kotlin 2.0.0-RC1.

[eskatos]

• About Provider.map { nullableValue } in Kotlin DSL does not work #12388

It seems that even if it could theoretically be possible to express this using JSpecify, there's no implementation commitment on the Kotlin side. IOW, migrating to JSpecify will not allow to resolve #12388.

[cpovirk]

Is there an easy way for me to help out from the JSpecify side? My guess would be that #12388 could be fixed by adding @NullMarked to Transformer without any further changes, since #23164 did most of what I would have done. (I could also make some other changes that I don't think are necessary. But I'd start simple unless those changes turn out to be more necessary than I would think :)) I have tried to browse through various related issue, but I don't know if there's a standalone test that I could run easily with a Gradle built from head, so I'm not sure how easily I can test my claims.

For what it's worth, Kotlin has implemented enough JSpecify support that I would expect that much to work today. I know that you've seen some other issues (as have those of us at Google in our usage of the JSpecify annotations with Kotlin), so I could understand if you want to wait until Kotlin 2+ is widely adopted before switching to JSpecify. I would only add that we have found the support to be good enough to use widely in our codebase, and the Kotlin developers have been of help when we've encountered problems.