graphql-java · Copilot · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026 · Jan 25, 2026
diff --git a/.claude/commands/jspecify-annotate.md b/.claude/commands/jspecify-annotate.md
@@ -4,6 +4,14 @@ Note that JSpecify is already used in this repository so it's already imported.
 
 If you see a builder static class, you can label it `@NullUnmarked` and not need to do anymore for this static class in terms of annotations.
 
+## Batch Size and Prioritization
+
+Annotate approximately 10 classes per batch for optimal context management. Start with interface/simple classes first, then tackle complex classes with builders. This helps identify patterns early.
+
+## Exploration Phase
+
+Before annotating, use `grep` to search for how each class is instantiated (e.g., `grep -r "new Comment"`) to understand which parameters can be null. Check constructor calls, method returns, and field assignments to inform your nullability decisions.
+
 Analyze this Java class and add JSpecify annotations based on:
 1. Set the class to be `@NullMarked`
 2. Remove all the redundant `@NonNull` annotations that IntelliJ added
@@ -12,14 +20,73 @@ Analyze this Java class and add JSpecify annotations based on:
 5. Method implementations that return null or check for null
 6. GraphQL specification details (see details below)
 
+## Pattern Examples
+
+Here are concrete examples of common annotation patterns:
+
+**Interface:**
+```java
+@PublicApi
+@NullMarked
+public interface MyInterface {
+    // Methods inherit @NullMarked context
+}
+```
+
+**Class with nullable field:**
+```java
+@PublicApi
+@NullMarked
+public class Comment {
+    private final String content;
+    private final @Nullable SourceLocation sourceLocation;
+
+    public Comment(String content, @Nullable SourceLocation sourceLocation) {
+        this.content = content;
+        this.sourceLocation = sourceLocation;
+    }
+
+    public @Nullable SourceLocation getSourceLocation() {
+        return sourceLocation;
+    }
+}
+```
+
+**Class with nullable return type:**
+```java
+@PublicApi
+@NullMarked
+public class Container {
+    public @Nullable Node getChildOrNull(String key) {
+        // May return null
+        return children.get(key);
+    }
+}
+```
+
+**Builder with @NullUnmarked:**
+```java
+@PublicApi
+@NullMarked
+public class MyClass {
+    @NullUnmarked
+    public static class Builder {
+        // No further annotations needed in builder
+    }
+}
+```
+
 ## GraphQL Specification Compliance
 This is a GraphQL implementation. When determining nullability, consult the GraphQL specification (https://spec.graphql.org/draft/) for the relevant concept. Key principles:
 
 The spec defines which elements are required (non-null) vs optional (nullable). Look for keywords like "MUST" to indicate when an element is required, and conditional words such as "IF" to indicate when an element is optional.
 
 If a class implements or represents a GraphQL specification concept, prioritize the spec's nullability requirements over what IntelliJ inferred.
 
-## How to validate
+## Validation Strategy
+
+Run `./gradlew compileJava` after every 3-5 classes annotated, not just at the end. This catches issues early and makes debugging easier.
+
 Finally, please check all this works by running the NullAway compile check.
 
 If you find NullAway errors, try and make the smallest possible change to fix them. If you must, you can use assertNotNull. Make sure to include a message as well.
@@ -56,4 +123,3 @@ The bound on a type parameter determines whether nullable type arguments are all
 - When the type parameter represents a concrete non-null object
 - Even if some methods return `@Nullable T` (meaning "can be null even if T is non-null")
 - Example: `Edge<T>` with `@Nullable T getNode()` — node may be null, but T represents the object type
-
diff --git a/src/main/java/graphql/language/Comment.java b/src/main/java/graphql/language/Comment.java
@@ -1,18 +1,21 @@
 package graphql.language;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
 
 /**
  * A single-line comment. These are comments that start with a {@code #} in source documents.
  */
 @PublicApi
+@NullMarked
 public class Comment implements Serializable {
     public final String content;
-    public final SourceLocation sourceLocation;
+    public final @Nullable SourceLocation sourceLocation;
 
-    public Comment(String content, SourceLocation sourceLocation) {
+    public Comment(String content, @Nullable SourceLocation sourceLocation) {
         this.content = content;
         this.sourceLocation = sourceLocation;
     }
@@ -21,7 +24,7 @@ public String getContent() {
         return content;
     }
 
-    public SourceLocation getSourceLocation() {
+    public @Nullable SourceLocation getSourceLocation() {
         return sourceLocation;
     }
 }
diff --git a/src/main/java/graphql/language/Definition.java b/src/main/java/graphql/language/Definition.java
@@ -2,8 +2,10 @@
 
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public interface Definition<T extends Definition> extends Node<T> {
 
 }
diff --git a/src/main/java/graphql/language/IgnoredChar.java b/src/main/java/graphql/language/IgnoredChar.java
@@ -1,6 +1,8 @@
 package graphql.language;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
 import java.util.Objects;
@@ -12,6 +14,7 @@
  * This costs more memory but for certain use cases (like editors) this maybe be useful
  */
 @PublicApi
+@NullMarked
 public class IgnoredChar implements Serializable {
 
     public enum IgnoredCharKind {
@@ -51,7 +54,7 @@ public String toString() {
     }
 
     @Override
-    public boolean equals(Object o) {
+    public boolean equals(@Nullable Object o) {
         if (this == o) {
             return true;
         }

diff --git a/src/main/java/graphql/language/IgnoredChars.java b/src/main/java/graphql/language/IgnoredChars.java
@@ -3,6 +3,7 @@
 import com.google.common.collect.ImmutableList;
 import graphql.PublicApi;
 import graphql.collect.ImmutableKit;
+import org.jspecify.annotations.NullMarked;
 
 import java.io.Serializable;
 import java.util.List;
@@ -14,6 +15,7 @@
  * This costs more memory but for certain use cases (like editors) this maybe be useful
  */
 @PublicApi
+@NullMarked
 public class IgnoredChars implements Serializable {
 
     private final ImmutableList<IgnoredChar> left;

diff --git a/src/main/java/graphql/language/Node.java b/src/main/java/graphql/language/Node.java
@@ -4,6 +4,7 @@
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
@@ -21,6 +22,7 @@
  * Every Node is immutable
  */
 @PublicApi
+@NullMarked
 public interface Node<T extends Node> extends Serializable {
 
     /**

diff --git a/src/main/java/graphql/language/NodeChildrenContainer.java b/src/main/java/graphql/language/NodeChildrenContainer.java
@@ -1,6 +1,9 @@
 package graphql.language;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
@@ -15,6 +18,7 @@
  * Container of children of a {@link Node}.
  */
 @PublicApi
+@NullMarked
 public class NodeChildrenContainer {
 
     private final Map<String, List<Node>> children = new LinkedHashMap<>();
@@ -27,7 +31,7 @@ public <T extends Node> List<T> getChildren(String key) {
         return (List<T>) children.getOrDefault(key, emptyList());
     }
 
-    public <T extends Node> T getChildOrNull(String key) {
+    public <T extends Node> @Nullable T getChildOrNull(String key) {
         List<? extends Node> result = children.getOrDefault(key, emptyList());
         if (result.size() > 1) {
             throw new IllegalStateException("children " + key + " is not a single value");
@@ -61,6 +65,7 @@ public boolean isEmpty() {
         return this.children.isEmpty();
     }
 
+    @NullUnmarked
     public static class Builder {
         private final Map<String, List<Node>> children = new LinkedHashMap<>();
 

diff --git a/src/main/java/graphql/language/NodeVisitor.java b/src/main/java/graphql/language/NodeVisitor.java
@@ -3,11 +3,13 @@
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Used by {@link NodeTraverser} to visit {@link Node}.
  */
 @PublicApi
+@NullMarked
 public interface NodeVisitor {
     TraversalControl visitArgument(Argument node, TraverserContext<Node> data);
 

diff --git a/src/main/java/graphql/language/NodeVisitorStub.java b/src/main/java/graphql/language/NodeVisitorStub.java
@@ -3,11 +3,13 @@
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Convenient implementation of {@link NodeVisitor} for easy subclassing methods handling different types of Nodes in one method.
  */
 @PublicApi
+@NullMarked
 public class NodeVisitorStub implements NodeVisitor {
     @Override
     public TraversalControl visitArgument(Argument node, TraverserContext<Node> context) {

diff --git a/src/main/java/graphql/language/SDLNamedDefinition.java b/src/main/java/graphql/language/SDLNamedDefinition.java
@@ -2,13 +2,15 @@
 
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * A interface for named Schema Definition Language (SDL) definition.
  *
  * @param <T> the actual Node type
  */
 @PublicApi
+@NullMarked
 public interface SDLNamedDefinition<T extends SDLNamedDefinition> extends SDLDefinition<T> {
 
     /**

diff --git a/src/main/java/graphql/language/ScalarTypeDefinition.java b/src/main/java/graphql/language/ScalarTypeDefinition.java
@@ -7,6 +7,9 @@
 import graphql.collect.ImmutableKit;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -20,6 +23,7 @@
 import static graphql.language.NodeChildrenContainer.newNodeChildrenContainer;
 
 @PublicApi
+@NullMarked
 public class ScalarTypeDefinition extends AbstractDescribedNode<ScalarTypeDefinition> implements TypeDefinition<ScalarTypeDefinition>, DirectivesContainer<ScalarTypeDefinition>, NamedNode<ScalarTypeDefinition> {
 
     private final String name;
@@ -30,8 +34,8 @@ public class ScalarTypeDefinition extends AbstractDescribedNode<ScalarTypeDefini
     @Internal
     protected ScalarTypeDefinition(String name,
                                    List<Directive> directives,
-                                   Description description,
-                                   SourceLocation sourceLocation,
+                                   @Nullable Description description,
+                                   @Nullable SourceLocation sourceLocation,
                                    List<Comment> comments,
                                    IgnoredChars ignoredChars,
                                    Map<String, String> additionalData) {
@@ -94,7 +98,7 @@ public ScalarTypeDefinition withNewChildren(NodeChildrenContainer newChildren) {
     }
 
     @Override
-    public boolean isEqualTo(Node o) {
+    public boolean isEqualTo(@Nullable Node o) {
         if (this == o) {
             return true;
         }
@@ -109,7 +113,7 @@ public boolean isEqualTo(Node o) {
 
     @Override
     public ScalarTypeDefinition deepCopy() {
-        return new ScalarTypeDefinition(name, deepCopy(directives.getDirectives()), description, getSourceLocation(), getComments(), getIgnoredChars(), getAdditionalData());
+        return new ScalarTypeDefinition(name, assertNotNull(deepCopy(directives.getDirectives())), description, getSourceLocation(), getComments(), getIgnoredChars(), getAdditionalData());
     }
 
     @Override
@@ -135,6 +139,7 @@ public ScalarTypeDefinition transform(Consumer<Builder> builderConsumer) {
         return builder.build();
     }
 
+    @NullUnmarked
     public static final class Builder implements NodeDirectivesBuilder {
         private SourceLocation sourceLocation;
         private ImmutableList<Comment> comments = emptyList();

diff --git a/src/main/java/graphql/language/ScalarTypeExtensionDefinition.java b/src/main/java/graphql/language/ScalarTypeExtensionDefinition.java
@@ -4,6 +4,9 @@
 import graphql.Internal;
 import graphql.PublicApi;
 import graphql.collect.ImmutableKit;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -14,21 +17,22 @@
 import static graphql.collect.ImmutableKit.emptyList;
 
 @PublicApi
+@NullMarked
 public class ScalarTypeExtensionDefinition extends ScalarTypeDefinition implements SDLExtensionDefinition {
 
     @Internal
     protected ScalarTypeExtensionDefinition(String name,
                                             List<Directive> directives,
-                                            Description description,
-                                            SourceLocation sourceLocation,
+                                            @Nullable Description description,
+                                            @Nullable SourceLocation sourceLocation,
                                             List<Comment> comments,
                                             IgnoredChars ignoredChars, Map<String, String> additionalData) {
         super(name, directives, description, sourceLocation, comments, ignoredChars, additionalData);
     }
 
     @Override
     public ScalarTypeExtensionDefinition deepCopy() {
-        return new ScalarTypeExtensionDefinition(getName(), deepCopy(getDirectives()), getDescription(), getSourceLocation(), getComments(), getIgnoredChars(), getAdditionalData());
+        return new ScalarTypeExtensionDefinition(getName(), assertNotNull(deepCopy(getDirectives())), getDescription(), getSourceLocation(), getComments(), getIgnoredChars(), getAdditionalData());
     }
 
     @Override
@@ -57,6 +61,7 @@ public ScalarTypeExtensionDefinition transformExtension(Consumer<Builder> builde
         return builder.build();
     }
 
+    @NullUnmarked
     public static final class Builder implements NodeDirectivesBuilder {
         private SourceLocation sourceLocation;
         private ImmutableList<Comment> comments = emptyList();