JSpecify big wave 2 #4184

dondonz · 2025-12-04T03:13:58Z

We have many classes left to go for JSpecify, so rather than one class at a time I will do the remainder in large bundles. This adds annotations on ~50 classes.

The general recipe here is

Use IntelliJ's infer nullity tool, which is a start and covers the basics
AI prompt to read JavaDoc, inspect nearby methods, with self-verification using NullAway
And finally a manual check from me, as some items are hard to infer nullity without understanding the GraphQL specification or the codebase

What will be in a future PR: better Kotlin tooling as reported recently in #4179

dondonz · 2025-12-04T03:29:33Z

src/main/java/graphql/GraphQL.java

        ParseAndValidateResult parseResult = parse(executionInput, graphQLSchema, instrumentationState);
        if (parseResult.isFailure()) {
-            return new PreparsedDocumentEntry(parseResult.getSyntaxException().toInvalidSyntaxError());
+            return new PreparsedDocumentEntry(assertNotNull(parseResult.getSyntaxException(), "Parse result syntax exception cannot be null when failed").toInvalidSyntaxError());


A similar change now has to happen in a bunch of places: now we must be asserting not null on selected lines or else you'll get a NullAway compile warning because the nullity is not clear at this point in the execution

dondonz · 2025-12-04T03:30:26Z

src/main/java/graphql/GraphQL.java


        Predicate<Class<?>> validationRulePredicate = executionInput.getGraphQLContext().getOrDefault(ParseAndValidate.INTERNAL_VALIDATION_PREDICATE_HINT, r -> true);
-        Locale locale = executionInput.getLocale() != null ? executionInput.getLocale() : Locale.getDefault();
+        Locale locale = executionInput.getLocale();


And now there are IDE alerts of null checks we can remove. When we are done with all JSpecify annotations on public API classes, we will find many more null checks to remove

src/main/java/graphql/GraphQLError.java

src/main/java/graphql/GraphqlErrorException.java

dondonz · 2025-12-04T03:34:58Z

src/main/java/graphql/ParseAndValidateResult.java

     * @return the parsed document or null if it's syntactically invalid.
     */
-    public Document getDocument() {
+    public @Nullable Document getDocument() {


Inferred from the Javadoc

src/main/java/graphql/SerializationError.java

dondonz · 2025-12-04T03:39:21Z

src/main/java/graphql/analysis/FieldComplexityEnvironment.java

    private final Map<String, Object> arguments;

-    public FieldComplexityEnvironment(Field field, GraphQLFieldDefinition fieldDefinition, GraphQLCompositeType parentType, Map<String, Object> arguments, FieldComplexityEnvironment parentEnvironment) {
+    public FieldComplexityEnvironment(Field field, GraphQLFieldDefinition fieldDefinition, GraphQLCompositeType parentType, Map<String, Object> arguments, @Nullable FieldComplexityEnvironment parentEnvironment) {


It can be nullable because a method that calls this constructor may pass in a null value for parentEnvironment

dondonz · 2025-12-04T03:40:22Z

src/main/java/graphql/analysis/MaxQueryComplexityInstrumentation.java


    @Override
-    public @Nullable CompletableFuture<InstrumentationState> createStateAsync(InstrumentationCreateStateParameters parameters) {
+    public CompletableFuture<InstrumentationState> createStateAsync(InstrumentationCreateStateParameters parameters) {


I think these @Nullable annotations were not correct initially. This method always will return a completed future

dondonz · 2025-12-04T03:41:05Z

src/main/java/graphql/analysis/MaxQueryComplexityInstrumentation.java


    @Override
-    public @Nullable InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState rawState) {
+    public InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState rawState) {


Same as above, I think this was incorrectly marked as nullable initially

dondonz · 2025-12-04T03:41:15Z

src/main/java/graphql/analysis/MaxQueryComplexityInstrumentation.java


    @Override
-    public @Nullable InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters instrumentationExecuteOperationParameters, InstrumentationState rawState) {
+    public InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters instrumentationExecuteOperationParameters, InstrumentationState rawState) {


Same as above, I think this was incorrectly marked as nullable initially

dondonz · 2025-12-04T03:42:36Z

src/main/java/graphql/analysis/MaxQueryDepthInstrumentation.java


    @Override
-    public @Nullable InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state) {
+    public InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state) {


Same as above, I think this was incorrectly marked as nullable initially

dondonz · 2025-12-04T03:49:47Z

src/main/java/graphql/relay/Connection.java


    /**
-     * @return a list of {@link graphql.relay.Edge}s that are really a node of data and its cursor
+     * @return a list of {@link graphql.relay.Edge}s that contain a node of data and its cursor. Can be null as defined in the spec.


From the specification

dondonz · 2025-12-04T03:50:06Z

src/main/java/graphql/relay/DefaultConnectionCursor.java


    public DefaultConnectionCursor(String value) {
-        Assert.assertTrue(value != null && !value.isEmpty(), "connection value cannot be null or empty");
+        Assert.assertTrue(!value.isEmpty(), "connection value cannot be null or empty");


Remove null check

dondonz · 2025-12-04T03:50:56Z

src/main/java/graphql/relay/DefaultPageInfo.java

 import java.util.Objects;

 @PublicApi
+@NullMarked


A wider question: these Relay classes are quite old and never got much love. Do we want to retain these classes at all?

dondonz · 2025-12-04T03:53:50Z

src/main/java/graphql/schema/GraphQLScalarType.java

    @Internal
    private GraphQLScalarType(String name,
-                              String description,
+                              @Nullable String description,


By definition in the specification, the description, and specified by URL can be null.

dondonz · 2025-12-04T03:54:56Z

src/main/java/graphql/schema/GraphQLSchema.java

    private final ImmutableList<SchemaExtensionDefinition> extensionDefinitions;
    private final String description;
-    private final GraphQLCodeRegistry codeRegistry;
+    private final @Nullable GraphQLCodeRegistry codeRegistry;


See previous discussion in #4098 (comment) (this PR supercedes the older one)

If we want to remove the nullable annotation here, we'd also need to change another callsite that assumes this parameter to be null

dondonz · 2025-12-04T03:57:15Z

src/main/java/graphql/schema/PropertyDataFetcher.java

-    private final String propertyName;
-    private final Function<Object, Object> function;
+    private final @Nullable String propertyName;
+    private final @Nullable Function<Object, Object> function;


See the constructors below, it is possible for either field to be nullable

dondonz · 2025-12-04T03:57:51Z

src/main/java/graphql/util/Anonymizer.java

            return NonNullType.newNonNullType(replaceTypeName(((NonNullType) type).getType(), newName)).build();
        } else {
-            graphql.Assert.assertShouldNeverHappen();
-            return null;


This throws, so the null is never reached

src/main/java/graphql/validation/ValidationError.java

dondonz · 2025-12-04T04:03:15Z

src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy

-            "graphql.validation.ValidationError",
-            "graphql.validation.ValidationErrorClassification",
-            "graphql.validation.ValidationErrorType",
+            // These classes will not be public API later, exempt here while marked as experimental


There is an edge case where some classes have been annotated with "Experimental API" for the purposes of the defer work. They won't become public API later so I made a note in the JSpecify exemption rule

dondonz · 2025-12-07T03:58:03Z

src/main/java/graphql/GraphqlErrorException.java

-    private final List<SourceLocation> locations;
-    private final Map<String, Object> extensions;
-    private final List<Object> path;
+    private final @Nullable List<SourceLocation> locations;


The builder creates a non-nullable list, but that's only if the builder is called

dondonz · 2025-12-07T23:29:44Z

src/main/java/graphql/GraphQLContext.java

     * @return a value or null
     */
-    public <T> T get(Object key) {
+    public <T> @Nullable T get(Object key) {


TODO: another case of the nullable generic issue

dondonz · 2025-12-07T23:31:02Z

src/main/java/graphql/TypeResolutionEnvironment.java

     */
    @SuppressWarnings("unchecked")
-    public <T> T getObject() {
+    public @Nullable <T> T getObject() {


TODO: another generic nullable check

dondonz added 30 commits August 21, 2025 19:23

Annotate GraphQLAppliedDirective

1b01d2b

Add GraphQLSchema annotation

8684b48

Remove exemption

0cdc8de

Annotate GraphQLType and GraphQLEnumType

30d0abe

Add Nullmarked to GraphQLEnumType

6ee01b8

Annotate GraphQLCodeRegistry

a45c613

Annotate GraphQLList

70336d5

Annotate PropertyDataFetcher

29f8363

Annotate GraphQLUnionType

083b2ab

Tidy up

b4761ef

Annotate GraphQLScalarType

9a78fb3

Annotate GraphQLNamedInputType

7bbfd9c

Add ErrorType

7427f64

Annotate Directives

120095c

Annotate ErrorClassification

012f49c

Annotate ExceptionWhileDataFetching

afdd408

Annotate ExecutionResult

803c924

Annotate GraphQLContext

a322ed0

Annotate AssertException and GraphQLError

41320d4

Annotate GraphQLErrorBuilder

9765c21

Annotate GraphQLErrorException

0ee713c

Annotate ParseAndValidate

e54fca2

Annotate ParseAndValidateResult

603c00d

Annotate Scalars

9fcaea1

Annotate SerializationError

88b02f3

Update GraphQLError with a nullable location list

e65217c

Annotate TypeMismatchError

19000a5

Annotate UnresolvedTypeError

313bf4f

Remove agent as no longer exists

0846c55

Add JSpecify prompt

d2d87cd

dondonz marked this pull request as draft December 4, 2025 03:27