Add JSpecify @NullMarked annotations to TraversalContext

andimarek · cursoragent · andimarek · commit b65e8c3e83a0 · 2026-01-29T20:03:02.000+10:00
- Add @NullMarked at class level - Add @nullable to fields: directive, argument - Add @nullable to public methods that can return null: getOutputType, getParentType, getInputType, getDefaultValue, getFieldDef, getQueryPath, getDirective, getArgument - Add @nullable to private methods that can return null: lastElement, find, getFieldDef(schema, parentType, field), getNullableType - Add @nullable to parameters that accept null: addOutputType, addParentType, addInputType, addDefaultValue, addFieldDef, getNullableType Co-authored-by: Cursor <cursoragent@cursor.com>
diff --git a/src/main/java/graphql/validation/TraversalContext.java b/src/main/java/graphql/validation/TraversalContext.java
@@ -1,6 +1,5 @@
 package graphql.validation;
 
-
 import graphql.Assert;
 import graphql.Internal;
 import graphql.execution.TypeFromAST;
@@ -33,6 +32,8 @@
 import graphql.schema.GraphQLUnionType;
 import graphql.schema.GraphQLUnmodifiedType;
 import graphql.schema.InputValueWithState;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -43,6 +44,7 @@
 import static graphql.schema.GraphQLTypeUtil.unwrapOne;
 
 @Internal
+@NullMarked
 public class TraversalContext implements DocumentVisitor {
     private final GraphQLSchema schema;
     private final List<GraphQLOutputType> outputTypeStack = new ArrayList<>();
@@ -51,8 +53,8 @@ public class TraversalContext implements DocumentVisitor {
     private final List<InputValueWithState> defaultValueStack = new ArrayList<>();
     private final List<GraphQLFieldDefinition> fieldDefStack = new ArrayList<>();
     private final List<String> nameStack = new ArrayList<>();
-    private GraphQLDirective directive;
-    private GraphQLArgument argument;
+    private @Nullable GraphQLDirective directive;
+    private @Nullable GraphQLArgument argument;
 
 
     public TraversalContext(GraphQLSchema graphQLSchema) {
@@ -187,7 +189,7 @@ private void enterImpl(ObjectField objectField) {
         addDefaultValue(inputField != null ? inputField.getInputFieldDefaultValue() : null);
     }
 
-    private GraphQLArgument find(List<GraphQLArgument> arguments, String name) {
+    private @Nullable GraphQLArgument find(List<GraphQLArgument> arguments, String name) {
         for (GraphQLArgument argument : arguments) {
             if (argument.getName().equals(name)) {
                 return argument;
@@ -245,23 +247,23 @@ private boolean isEmpty(String name) {
         return name == null || name.isEmpty();
     }
 
-    private GraphQLNullableType getNullableType(GraphQLType type) {
+    private @Nullable GraphQLNullableType getNullableType(@Nullable GraphQLType type) {
         return (GraphQLNullableType) (isNonNull(type) ? unwrapOne(type) : type);
     }
 
     /**
      * @return can be null if current node does not have a OutputType associated: for example
      * if the current field is unknown
      */
-    public GraphQLOutputType getOutputType() {
+    public @Nullable GraphQLOutputType getOutputType() {
         return lastElement(outputTypeStack);
     }
 
-    private void addOutputType(GraphQLOutputType type) {
+    private void addOutputType(@Nullable GraphQLOutputType type) {
         outputTypeStack.add(type);
     }
 
-    private <T> T lastElement(List<T> list) {
+    private <T> @Nullable T lastElement(List<T> list) {
         if (list.isEmpty()) {
             return null;
         }
@@ -275,53 +277,54 @@ private <T>  T pop(List<T> list) {
     /**
      * @return can be null if the parent is not a CompositeType
      */
-    public GraphQLCompositeType getParentType() {
+    public @Nullable GraphQLCompositeType getParentType() {
         return lastElement(parentTypeStack);
     }
 
-    private void addParentType(GraphQLCompositeType compositeType) {
+    private void addParentType(@Nullable GraphQLCompositeType compositeType) {
         parentTypeStack.add(compositeType);
     }
 
-    public GraphQLInputType getInputType() {
+    public @Nullable GraphQLInputType getInputType() {
         return lastElement(inputTypeStack);
     }
-    public InputValueWithState getDefaultValue() {
+
+    public @Nullable InputValueWithState getDefaultValue() {
         return lastElement(defaultValueStack);
     }
 
-    private void addInputType(GraphQLInputType graphQLInputType) {
+    private void addInputType(@Nullable GraphQLInputType graphQLInputType) {
         inputTypeStack.add(graphQLInputType);
     }
 
-    private void addDefaultValue(InputValueWithState defaultValue) {
+    private void addDefaultValue(@Nullable InputValueWithState defaultValue) {
         defaultValueStack.add(defaultValue);
     }
 
-    public GraphQLFieldDefinition getFieldDef() {
+    public @Nullable GraphQLFieldDefinition getFieldDef() {
         return lastElement(fieldDefStack);
     }
 
-    public List<String> getQueryPath() {
+    public @Nullable List<String> getQueryPath() {
         if (nameStack.isEmpty()) {
             return null;
         }
         return new ArrayList<>(nameStack);
     }
 
-    private void addFieldDef(GraphQLFieldDefinition fieldDefinition) {
+    private void addFieldDef(@Nullable GraphQLFieldDefinition fieldDefinition) {
         fieldDefStack.add(fieldDefinition);
     }
 
-    public GraphQLDirective getDirective() {
+    public @Nullable GraphQLDirective getDirective() {
         return directive;
     }
 
-    public GraphQLArgument getArgument() {
+    public @Nullable GraphQLArgument getArgument() {
         return argument;
     }
 
-    private GraphQLFieldDefinition getFieldDef(GraphQLSchema schema, GraphQLType parentType, Field field) {
+    private @Nullable GraphQLFieldDefinition getFieldDef(GraphQLSchema schema, GraphQLType parentType, Field field) {
         if (schema.getQueryType().equals(parentType)) {
             if (field.getName().equals(schema.getIntrospectionSchemaFieldDefinition().getName())) {
                 return schema.getIntrospectionSchemaFieldDefinition();
