Add JSpecify annotations to 10 instrumentation classes by Copilot · Pull Request #4226 · graphql-java/graphql-java

Copilot · 2026-01-25T06:37:34Z

Annotates 10 classes in graphql.execution.instrumentation package with JSpecify nullability markers, reducing the exemption list and improving null-safety guarantees.

Changes

Class-level annotations: Added @NullMarked to all 10 target classes (DeferredExecution, ChainedInstrumentation, DocumentAndVariables, NoContextChainedInstrumentation, ResponseMapFactory, SimpleInstrumentation, SimpleInstrumentationContext, SimplePerformantInstrumentation, FieldAndArguments, FieldValidationEnvironment)
Inner class handling: Marked Builder and private static classes as @NullUnmarked per established pattern
Nullable annotations: Added @Nullable to:
- NoContextChainedInstrumentation override methods that intentionally return null
- ChainedInstrumentation methods matching interface contracts
- SimpleInstrumentationContext nullable fields and parameters
- DeferredExecution.getLabel() return type (label can be null per GraphQL defer spec)
Exemption list: Removed all 10 classes from JSpecifyAnnotationsCheck.groovy

Example

@PublicApi
@NullMarked
public class DocumentAndVariables {
    // Fields are non-null by default under @NullMarked
    private final Document document;
    
    @NullUnmarked  // Builder doesn't need fine-grained annotations
    public static class Builder {
        // ...
    }
}

Original prompt

Task

Add JSpecify annotations to the following 10 classes in the graphql.execution.instrumentation package and subpackages, following the established JSpecify annotation pattern documented in .claude/commands/jspecify-annotate.md.

Classes to annotate

graphql.execution.incremental.DeferredExecution

graphql.execution.instrumentation.ChainedInstrumentation

graphql.execution.instrumentation.DocumentAndVariables

graphql.execution.instrumentation.NoContextChainedInstrumentation

graphql.execution.ResponseMapFactory

graphql.execution.instrumentation.SimpleInstrumentation

graphql.execution.instrumentation.SimpleInstrumentationContext

graphql.execution.instrumentation.SimplePerformantInstrumentation

graphql.execution.instrumentation.fieldvalidation.FieldAndArguments

graphql.execution.instrumentation.fieldvalidation.FieldValidationEnvironment

Instructions

Follow the JSpecify annotation process documented in .claude/commands/jspecify-annotate.md:

Set each class to be @NullMarked at the class level

Remove all redundant @NonNull annotations that IntelliJ may have added

Check Javadoc for @param tags mentioning "null", "nullable", "may be null"

Check Javadoc @return tags mentioning "null", "optional", "if available"

Inspect method implementations that return null or check for null

Consider GraphQL specification details when determining nullability

For Builder static classes, label them @NullUnmarked and no further annotations needed

Validation

After making changes, run the NullAway compile check:
./gradlew compileJava
If you find NullAway errors, make the smallest possible change to fix them. You can use assertNotNull with a message if needed.

Cleanup

Remove each completed class from the exemption list in src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy

Delete all unused imports from the classes you've annotated

Do not make spacing or formatting changes - only make minimal changes necessary for the annotations

Reference

Look at existing annotated classes in the repository for reference patterns.

This pull request was created from Copilot chat.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: dondonz <13839920+dondonz@users.noreply.github.com>

dondonz · 2026-01-25T09:39:37Z

src/main/java/graphql/execution/instrumentation/ChainedInstrumentation.java

    }

+    @NullUnmarked
    static class ChainedInstrumentationState implements InstrumentationState {


TODO: I think the prompt has confused builders and static classes

…c15c-45b6-ace7-d0ef898a87a8 # Conflicts: # .claude/commands/jspecify-annotate.md # src/main/java/graphql/schema/GraphQLSchema.java

github-actions · 2026-02-14T22:10:44Z

Test Results

335 files ±0 335 suites ±0 5m 6s ⏱️ +6s
5 376 tests ±0 5 368 ✅ +1 8 💤 - 1 0 ❌ ±0
5 465 runs ±0 5 457 ✅ +1 8 💤 - 1 0 ❌ ±0

Results for commit 408514a. ± Comparison against base commit 9ae83ab.

This pull request removes 196 and adds 172 tests. Note that renamed tests count towards both.

	?

	, expected: combo-\"\\\b\f\n\r\t, #4]
                __schema { types { fields { args { type { name fields { name }}}}}}
                __schema { types { fields { type { name fields { name }}}}}
                __schema { types { inputFields { type { inputFields { name }}}}}
                __schema { types { interfaces { fields { type { interfaces { name } } } } } }
                __schema { types { name} }
                __type(name : "t") { name }
                a1: __schema { types { name} }
                a1: __type(name : "t") { name }
…

graphql.AssertTest ‑ assertFalse with different number of error args but false does not throw assertions [toRun: <graphql.AssertTest$__spock_feature_0_21prov0_closure23@1e60b459 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1, #0]
graphql.AssertTest ‑ assertFalse with different number of error args but false does not throw assertions [toRun: <graphql.AssertTest$__spock_feature_0_21prov0_closure24@7c0777b5 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1 arg2, #1]
graphql.AssertTest ‑ assertFalse with different number of error args but false does not throw assertions [toRun: <graphql.AssertTest$__spock_feature_0_21prov0_closure25@29ebbdf4 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1 arg2 arg3, #2]
graphql.AssertTest ‑ assertFalse with different number of error args throws assertions [toRun: <graphql.AssertTest$__spock_feature_0_20prov0_closure20@6ba060f3 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1, #0]
graphql.AssertTest ‑ assertFalse with different number of error args throws assertions [toRun: <graphql.AssertTest$__spock_feature_0_20prov0_closure21@411a5965 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1 arg2, #1]
graphql.AssertTest ‑ assertFalse with different number of error args throws assertions [toRun: <graphql.AssertTest$__spock_feature_0_20prov0_closure22@18a25bbd delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1 arg2 arg3, #2]
graphql.AssertTest ‑ assertNotNull with different number of  error args throws assertions [toRun: <graphql.AssertTest$__spock_feature_0_5prov0_closure3@5a0bef24 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1, #0]
graphql.AssertTest ‑ assertNotNull with different number of  error args throws assertions [toRun: <graphql.AssertTest$__spock_feature_0_5prov0_closure4@17092fff delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1 arg2, #1]
graphql.AssertTest ‑ assertNotNull with different number of  error args throws assertions [toRun: <graphql.AssertTest$__spock_feature_0_5prov0_closure5@22c75c01 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1 arg2 arg3, #2]
graphql.AssertTest ‑ assertNotNull with different number of error args with non null does not throw assertions [toRun: <graphql.AssertTest$__spock_feature_0_6prov0_closure6@63d5874f delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1, #0]
…

♻️ This comment has been updated with latest results.

…c15c-45b6-ace7-d0ef898a87a8

dondonz · 2026-02-26T09:20:54Z

Copilot has gone off the rails and ran the prompt twice on the same branch

dondonz · 2026-02-27T21:01:06Z

Copilot's attempt was not correct - confused about which files to annotate and other errors. I'm redoing this PR

Copilot AI and others added 4 commits January 24, 2026 20:32

Initial plan

c60fdf6

Add JSpecify annotations to 10 classes in graphql.language package

c02fa4e

Co-authored-by: dondonz <13839920+dondonz@users.noreply.github.com>

Update JSpecify annotation prompt with effectiveness improvements

3db2dde

Co-authored-by: dondonz <13839920+dondonz@users.noreply.github.com>

Initial plan

a6321b9

Copilot AI assigned Copilot and dondonz Jan 25, 2026

Copilot started work on behalf of dondonz January 25, 2026 07:01 View session

Add JSpecify annotations to 10 classes and update exemption list

bd30364

Co-authored-by: dondonz <13839920+dondonz@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add JSpecify annotations to 10 classes in instrumentation package~~ Add JSpecify annotations to 10 instrumentation classes Jan 25, 2026

Copilot AI requested a review from dondonz January 25, 2026 07:17

Copilot finished work on behalf of dondonz January 25, 2026 07:17

dondonz reviewed Jan 25, 2026

View reviewed changes

Copilot AI mentioned this pull request Jan 28, 2026

Review all open JSpecify PRs #4231

Draft

dondonz changed the base branch from copilot/add-jspecify-annotations-to-classes to master February 8, 2026 07:15

Copilot AI mentioned this pull request Feb 14, 2026

Unable to complete task - wrong repository environment graphql-java/java-dataloader#265

Closed

Merge master into copilot/add-jspecify-annotations branch

d59890a

dondonz marked this pull request as ready for review February 14, 2026 22:04

Merge branch 'master' into copilot/add-jspecify-annotations-ce85e181-…

87ebe35

…c15c-45b6-ace7-d0ef898a87a8 # Conflicts: # .claude/commands/jspecify-annotate.md # src/main/java/graphql/schema/GraphQLSchema.java

dondonz marked this pull request as draft February 14, 2026 22:23

Merge branch 'master' into copilot/add-jspecify-annotations-ce85e181-…

408514a

…c15c-45b6-ace7-d0ef898a87a8

dondonz closed this Feb 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add JSpecify annotations to 10 instrumentation classes#4226

Add JSpecify annotations to 10 instrumentation classes#4226
Copilot wants to merge 8 commits intomasterfrom
copilot/add-jspecify-annotations-ce85e181-c15c-45b6-ace7-d0ef898a87a8

Copilot AI commented Jan 25, 2026 •

edited

Loading

Uh oh!

dondonz Jan 25, 2026

Uh oh!

github-actions bot commented Feb 14, 2026 •

edited

Loading

Uh oh!

dondonz commented Feb 26, 2026

Uh oh!

dondonz commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Copilot AI commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example

Task

Classes to annotate

Instructions

Validation

Cleanup

Reference

Uh oh!

dondonz Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

dondonz commented Feb 26, 2026

Uh oh!

dondonz commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 25, 2026 •

edited

Loading

github-actions bot commented Feb 14, 2026 •

edited

Loading