graphql-java · dondonz · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/.claude/commands/jspecify-annotate.md b/.claude/commands/jspecify-annotate.md
@@ -1,7 +1,11 @@
-The task is to annotate public API classes (marked with `@PublicAPI`) with JSpecify nullability annotations.
+The task is to annotate public API classes (marked with `@PublicApi` or `@PublicSpi`) with JSpecify nullability annotations.
 
 Note that JSpecify is already used in this repository so it's already imported.
 
+## Scope: Public API only
+
+Only annotate classes marked `@PublicApi` or `@PublicSpi`. Do **not** add JSpecify annotations to `@Internal` classes — these are implementation details and are intentionally left unannotated.
+
 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.
 
 Analyze this Java class and add JSpecify annotations based on:
@@ -29,9 +33,11 @@ If you find NullAway errors, try and make the smallest possible change to fix th
 Do not make spacing or formatting changes. Avoid adjusting whitespace, line breaks, or other formatting when editing code. These changes make diffs messy and harder to review. Only make the minimal changes necessary to accomplish the task.
 
 ## Cleaning up
-Finally, can you remove this class from the JSpecifyAnnotationsCheck as an exemption
+Finally, remove this class from the exemption list in `JSpecifyAnnotationsCheck.groovy`.
+
+The exemption list contains fully-qualified class names. Remove **only** the class you just annotated — do not remove entries for `@Internal` classes or any other class you did not annotate.
 
-You do not need to run the JSpecifyAnnotationsCheck. Removing the completed class is enough.
+You do not need to run the JSpecifyAnnotationsCheck. Removing the completed class from the list is enough.
 
 Remember to delete all unused imports when you're done from the class you've just annotated.
 

diff --git a/.claude/commands/jspecify-team-prompt.md b/.claude/commands/jspecify-team-prompt.md
@@ -0,0 +1,178 @@
+# JSpecify Annotation Team Orchestrator Prompt
+
+You are an orchestrator agent responsible for coordinating a team of worker
+agents to add JSpecify nullability annotations to public API classes in the
+graphql-java project.
+
+## Your Job
+
+1. Read the current exemption list from:
+   `src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy`
+   Before building batch assignments, check which classes from the lists below
+   are still present in the exemption list. Only assign classes that remain.
+   This makes the orchestrator safe to re-run after interruption.
+
+2. Group the remaining classes into batches (see batches below).
+
+3. Launch worker agents in **waves of 2** (only 2 workers this wave).
+   After the wave completes, launch the reviewer.
+
+4. After the reviewer confirms no errors, launch the validator.
+
+## Execution Flow
+
+### Wave 1
+Launch Workers 1, 2 in parallel. Wait for all to complete.
+Launch Reviewer for Wave 1. Wait for completion and NullAway confirmation.
+
+### Final Step
+Launch the validator to remove completed classes from
+`JSpecifyAnnotationsCheck.groovy` and push the branch.
+
+---
+
+## Batch Assignments
+
+### Worker 1 — graphql.normalized (5 classes)
+```
+graphql.normalized.incremental.NormalizedDeferredExecution
+graphql.normalized.nf.NormalizedDocument
+graphql.normalized.nf.NormalizedDocumentFactory
+graphql.normalized.nf.NormalizedField
+graphql.normalized.nf.NormalizedOperation
+```
+
+### Worker 2 — graphql.normalized + schema + util (4 classes)
+```
+graphql.normalized.nf.NormalizedOperationToAstCompiler
+graphql.schema.diffing.SchemaGraph
+graphql.schema.validation.OneOfInputObjectRules
+graphql.util.CyclicSchemaAnalyzer
+graphql.util.querygenerator.QueryGenerator
+graphql.util.querygenerator.QueryGeneratorOptions
+graphql.util.querygenerator.QueryGeneratorResult
+```
+
+---
+
+## Instructions for Each Worker Agent
+
+Each worker agent must follow these rules for every class in its batch:
+
+### Per-class steps
+1. Find the class at `src/main/java/<package/ClassName>.java`
+2. Add `@NullMarked` at the class level
+3. Remove redundant `@NonNull` annotations added by IntelliJ
+4. Check Javadoc `@param` tags mentioning "null", "nullable", "may be null"
+5. Check Javadoc `@return` tags mentioning "null", "optional", "if available"
+6. Check method bodies that return null or check for null
+7. Consult the GraphQL spec (https://spec.graphql.org/draft/) for the
+   relevant concept — prioritize spec nullability over IntelliJ inference
+8. If the class has a static Builder inner class, annotate it `@NullUnmarked`
+   and skip further annotation of that inner class
+9. Delete unused imports from the class after editing
+10. Do NOT modify `JSpecifyAnnotationsCheck.groovy`
+
+### IntelliJ inspection check
+After editing each file, use the IntelliJ MCP `inspections` tool to check
+for warnings in the modified file. Fix any nullability-related warnings
+before moving on. This catches issues that NullAway alone may miss.
+
+### Generics rules
+- `<T>` does NOT allow `@Nullable` type arguments (`Box<@Nullable String>` illegal)
+- `<T extends @Nullable Object>` DOES allow `@Nullable` type arguments
+- Use `<T extends @Nullable Object>` only when callers genuinely need nullable types
+
+### After each class
+- Commit with message: `"Add JSpecify annotations to ClassName"`
+- `git pull` before starting the next class to pick up any concurrent changes
+
+### If a class has NullAway errors
+- Make the smallest possible fix
+- Use `Objects.requireNonNull(x, "message")` or `assertNotNull(x, "message")`
+  only as a last resort
+- Do NOT run the full build — leave that for the reviewer
+
+---
+
+## Reviewer Agent Instructions
+
+After each wave of workers completes, launch a single reviewer agent.
+The reviewer must NOT read any worker agent output or context — it works
+only from the git diff.
+
+### Step 1 — Get the diffs
+
+For each class annotated in this wave, get its diff:
+```
+git diff origin/main...HEAD -- <path/to/ClassName.java>
+```
+
+### Step 2 — Review each diff independently
+
+For each changed file, check:
+
+**JSpecify correctness:**
+- `@NullMarked` is present at the class level
+- No redundant `@NonNull` annotations remain
+- `@Nullable` is used where null is genuinely possible, not speculatively
+- `<T extends @Nullable Object>` only used when callers truly need nullable
+  type arguments
+- Builder inner classes are marked `@NullUnmarked` and nothing more
+
+**GraphQL spec compliance:**
+Fetch https://spec.graphql.org/draft/ for the relevant concept.
+`MUST` = non-null. Conditional/IF = nullable.
+Does the annotation match the spec?
+
+**Unused imports:**
+Are there leftover imports (e.g. `org.jetbrains.annotations.NotNull`)?
+
+### Step 3 — Fix any issues found
+
+Make the minimal fix directly in the file.
+Do NOT revert the whole annotation — fix only the specific problem.
+Do NOT modify `JSpecifyAnnotationsCheck.groovy`.
+
+If you make any fixes, commit with:
+```
+"Review fixes: correct JSpecify annotations for ClassName"
+```
+
+### Step 4 — Run the compile check
+
+```
+./gradlew compileJava
+```
+
+If it passes, report success and stop.
+
+If it fails:
+- Read the NullAway error output carefully
+- Make the smallest possible fix (prefer `assertNotNull(x, "message")`
+  over restructuring code)
+- Re-run `./gradlew compileJava`
+- Repeat until it passes or you have tried 3 times
+- If still failing after 3 attempts, report the error details to the
+  orchestrator so it can decide whether to continue to the next wave
+
+---
+
+## Validator Agent Instructions
+
+All waves are complete and the reviewer has confirmed `compileJava` passes
+for each wave. Your job is cleanup and push only.
+
+1. Read the current exemption list from `JSpecifyAnnotationsCheck.groovy`
+2. For each class that now has `@NullMarked` in its source file, remove it
+   from the `JSPECIFY_EXEMPTION_LIST` in `JSpecifyAnnotationsCheck.groovy`
+3. Run `./gradlew compileJava` one final time to confirm the full build passes
+4. Commit: `"Remove annotated classes from JSpecify exemption list"`
+5. Push: `git push -u origin claude/jspecify-wave5`
+
+---
+
+## Repository Details
+- Working directory: `/Users/dondonz/Development/graphql-java`
+- Branch: `claude/jspecify-wave5`
+- NullAway compile check: `./gradlew compileJava`
diff --git a/src/main/java/graphql/ExceptionWhileDataFetching.java b/src/main/java/graphql/ExceptionWhileDataFetching.java
@@ -27,7 +27,7 @@ public class ExceptionWhileDataFetching implements GraphQLError {
     private final List<SourceLocation> locations;
     private final @Nullable Map<String, Object> extensions;
 
-    public ExceptionWhileDataFetching(ResultPath path, Throwable exception, SourceLocation sourceLocation) {
+    public ExceptionWhileDataFetching(ResultPath path, Throwable exception, @Nullable SourceLocation sourceLocation) {
         this.path = assertNotNull(path).toList();
         this.exception = assertNotNull(exception);
         this.locations = Collections.singletonList(sourceLocation);

diff --git a/src/main/java/graphql/GraphQL.java b/src/main/java/graphql/GraphQL.java
@@ -547,7 +547,7 @@ private CompletableFuture<ExecutionResult> parseValidateAndExecute(ExecutionInpu
                 return CompletableFuture.completedFuture(new ExecutionResultImpl(preparsedDocumentEntry.getErrors()));
             }
             try {
-                return execute(Assert.assertNotNull(executionInputRef.get()), preparsedDocumentEntry.getDocument(), graphQLSchema, instrumentationState, engineRunningState, profiler);
+                return execute(Assert.assertNotNull(executionInputRef.get()), assertNotNull(preparsedDocumentEntry.getDocument(), "document must not be null"), graphQLSchema, instrumentationState, engineRunningState, profiler);
             } catch (AbortExecutionException e) {
                 return CompletableFuture.completedFuture(e.toExecutionResult());
             }

diff --git a/src/main/java/graphql/UnresolvedTypeError.java b/src/main/java/graphql/UnresolvedTypeError.java
@@ -32,8 +32,8 @@ private String mkMessage(ResultPath path, UnresolvedTypeException exception, Exe
         return format("Can't resolve '%s'. Abstract type '%s' must resolve to an Object type at runtime for field '%s.%s'. %s",
                 path,
                 exception.getInterfaceOrUnionType().getName(),
-                simplePrint(info.getParent().getUnwrappedNonNullType()),
-                info.getFieldDefinition().getName(),
+                simplePrint(assertNotNull(info.getParent(), "executionStepInfo parent must not be null").getUnwrappedNonNullType()),
+                assertNotNull(info.getFieldDefinition(), "fieldDefinition must not be null").getName(),
                 exception.getMessage());
     }
 

diff --git a/src/main/java/graphql/analysis/MaxQueryDepthInstrumentation.java b/src/main/java/graphql/analysis/MaxQueryDepthInstrumentation.java
@@ -9,6 +9,7 @@
 import graphql.execution.instrumentation.SimplePerformantInstrumentation;
 import graphql.execution.instrumentation.parameters.InstrumentationExecuteOperationParameters;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.function.Function;
 
@@ -84,7 +85,7 @@ QueryTraverser newQueryTraverser(ExecutionContext executionContext) {
                 .build();
     }
 
-    private int getPathLength(QueryVisitorFieldEnvironment path) {
+    private int getPathLength(@Nullable QueryVisitorFieldEnvironment path) {
         int length = 1;
         while (path != null) {
             path = path.getParentEnvironment();

diff --git a/src/main/java/graphql/analysis/QueryComplexityCalculator.java b/src/main/java/graphql/analysis/QueryComplexityCalculator.java
@@ -4,6 +4,9 @@
 import graphql.execution.CoercedVariables;
 import graphql.language.Document;
 import graphql.schema.GraphQLSchema;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -16,12 +19,13 @@
  * into it.
  */
 @PublicApi
+@NullMarked
 public class QueryComplexityCalculator {
 
     private final FieldComplexityCalculator fieldComplexityCalculator;
     private final GraphQLSchema schema;
     private final Document document;
-    private final String operationName;
+    private final @Nullable String operationName;
     private final CoercedVariables variables;
 
     public QueryComplexityCalculator(Builder builder) {
@@ -95,6 +99,7 @@ public static Builder newCalculator() {
         return new Builder();
     }
 
+    @NullUnmarked
     public static class Builder {
         private FieldComplexityCalculator fieldComplexityCalculator;
         private GraphQLSchema schema;

diff --git a/src/main/java/graphql/analysis/QueryComplexityInfo.java b/src/main/java/graphql/analysis/QueryComplexityInfo.java
@@ -3,17 +3,20 @@
 import graphql.PublicApi;
 import graphql.execution.instrumentation.parameters.InstrumentationExecuteOperationParameters;
 import graphql.execution.instrumentation.parameters.InstrumentationValidationParameters;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import org.jspecify.annotations.NullUnmarked;
 
 /**
  * The query complexity info.
  */
 @PublicApi
+@NullMarked
 public class QueryComplexityInfo {
 
     private final int complexity;
-    private final InstrumentationValidationParameters instrumentationValidationParameters;
-    private final InstrumentationExecuteOperationParameters instrumentationExecuteOperationParameters;
+    private final @Nullable InstrumentationValidationParameters instrumentationValidationParameters;
+    private final @Nullable InstrumentationExecuteOperationParameters instrumentationExecuteOperationParameters;
 
     private QueryComplexityInfo(Builder builder) {
         this.complexity = builder.complexity;
@@ -35,7 +38,7 @@ public int getComplexity() {
      *
      * @return the instrumentation validation parameters.
      */
-    public InstrumentationValidationParameters getInstrumentationValidationParameters() {
+    public @Nullable InstrumentationValidationParameters getInstrumentationValidationParameters() {
         return instrumentationValidationParameters;
     }
 
@@ -44,7 +47,7 @@ public InstrumentationValidationParameters getInstrumentationValidationParameter
      *
      * @return the instrumentation execute operation parameters.
      */
-    public InstrumentationExecuteOperationParameters getInstrumentationExecuteOperationParameters() {
+    public @Nullable InstrumentationExecuteOperationParameters getInstrumentationExecuteOperationParameters() {
         return instrumentationExecuteOperationParameters;
     }
 

diff --git a/src/main/java/graphql/analysis/QueryDepthInfo.java b/src/main/java/graphql/analysis/QueryDepthInfo.java
@@ -1,12 +1,14 @@
 package graphql.analysis;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.NullUnmarked;
 
 /**
  * The query depth info.
  */
 @PublicApi
+@NullMarked
 public class QueryDepthInfo {
 
     private final int depth;

diff --git a/src/main/java/graphql/analysis/QueryReducer.java b/src/main/java/graphql/analysis/QueryReducer.java
@@ -1,6 +1,7 @@
 package graphql.analysis;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Used by {@link QueryTraverser} to reduce the fields of a Document (or part of it) to a single value.
@@ -10,6 +11,7 @@
  * See {@link QueryTraverser#reducePostOrder(QueryReducer, Object)} and {@link QueryTraverser#reducePreOrder(QueryReducer, Object)}
  */
 @PublicApi
+@NullMarked
 @FunctionalInterface
 public interface QueryReducer<T> {
 

diff --git a/src/main/java/graphql/analysis/QueryTransformer.java b/src/main/java/graphql/analysis/QueryTransformer.java
@@ -13,6 +13,7 @@
 
 import java.util.LinkedHashMap;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.NullUnmarked;
 
 import static graphql.Assert.assertNotNull;
@@ -31,6 +32,7 @@
  * visitField calls.
  */
 @PublicApi
+@NullMarked
 public class QueryTransformer {
 
     private final Node root;
@@ -82,7 +84,7 @@ public Node transform(QueryVisitor queryVisitor) {
 
             @Override
             public TraversalControl enter(TraverserContext<Node> context) {
-                return context.thisNode().accept(context, nodeVisitor);
+                return assertNotNull(context.thisNode(), "thisNode should not be null").accept(context, nodeVisitor);
             }
 
             @Override
@@ -91,7 +93,7 @@ public TraversalControl leave(TraverserContext<Node> context) {
                 return TraversalControl.CONTINUE;
             }
         };
-        return new TreeTransformer<>(AST_NODE_ADAPTER).transform(root, nodeTraverserVisitor, rootVars);
+        return assertNotNull(new TreeTransformer<>(AST_NODE_ADAPTER).transform(root, nodeTraverserVisitor, rootVars), "transform result should not be null");
     }
 
     public static Builder newQueryTransformer() {