Add JSpecify annotations to 10 graphql.language classes by Copilot · Pull Request #4217 · graphql-java/graphql-java · GitHub

Adds JSpecify null-safety annotations to 10 core AST classes in graphql.language, removing them from the exemption list.

Changes

Annotated classes:

AbstractDescribedNode, DescribedNode - @Nullable on description field/return (descriptions are optional in GraphQL SDL)
Description - @Nullable on content and sourceLocation fields
AstPrinter, AstSignature, AstSorter, AstTransformer - @Nullable on method parameters that accept nulls
AstNodeAdapter - Non-null throughout
Directive, DirectiveDefinition - @NullUnmarked on Builder inner classes per convention

NullAway fixes:

Added assertNotNull() calls in deepCopy() methods where generic @Nullable List<V> returns are passed to non-null constructors (lists are always non-null at call site)

Example

@PublicApi
@NullMarked
public class Description implements Serializable {
    public final @Nullable String content;
    public final @Nullable SourceLocation sourceLocation;
    
    public Description(@Nullable String content, @Nullable SourceLocation sourceLocation, boolean multiLine) {
        // ...
    }
}

Removed all 10 classes from JSpecifyAnnotationsCheck.groovy exemption list.

Original prompt

Task

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

Classes to annotate

graphql.language.AbstractDescribedNode

graphql.language.AstNodeAdapter

graphql.language.AstPrinter

graphql.language.AstSignature

graphql.language.AstSorter

graphql.language.AstTransformer

graphql.language.DescribedNode

graphql.language.Description

graphql.language.Directive

graphql.language.DirectiveDefinition

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 like IntValue.java, StringValue.java, AbstractNode.java in the same package for reference patterns.

This pull request was created from Copilot chat.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

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

# Conflicts: # .claude/commands/jspecify-annotate.md

Test Results

335 files ±0 335 suites ±0 5m 5s ⏱️ ±0s
5 371 tests ±0 5 363 ✅ ±0 8 💤 ±0 0 ❌ ±0
5 460 runs ±0 5 452 ✅ ±0 8 💤 ±0 0 ❌ ±0

Results for commit 2d02ff0. ± Comparison against base commit 89b4446.

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@5f5effb0 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@3468ee6e 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@751ae8a4 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@b0a1231 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@3b1dc579 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@3b7eac14 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@5115f590 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@4483d35 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@3a8d467e 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@332bcab0 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.

An interesting note: descriptions do not need to exist on GraphQL schema elements. However this is the AST representation - this Description element is only created when one exists.

I feel like code get missed here in diff terms??

I removed it because the input is not nullable - so the question becomes can the input be nullable?

Is it possible or normal behaviour to pass in a null node into the printer?

I think there is a code delete problem here

Resolve JSpecifyAnnotationsCheck conflict by taking master's exemption list updates (classes already annotated on master removed, new exemptions added). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

NodeVisitor, NodeVisitorStub, SourceLocation, and Type are already annotated with @NullMarked so they should not be in the exemption list. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Test Report

Test Results

Java Version	Total	Passed	Failed	Errors	Skipped
Java 11	5708 (±0)	5652 (±0)	0 (±0)	0 (±0)	56 (±0)
Java 17	5708 (±0)	5651 (±0)	0 (±0)	0 (±0)	57 (±0)
Java 21	5708 (±0)	5651 (±0)	0 (±0)	0 (±0)	57 (±0)
Java 25	5708 (±0)	5651 (±0)	0 (±0)	0 (±0)	57 (±0)
jcstress	32 (±0)	32 (±0)	0 (±0)	0 (±0)	0 (±0)
Total	22864 (±0)	22637 (±0)	0 (±0)	0 (±0)	227 (±0)

Code Coverage (Java 25)

Metric	Covered	Missed	Coverage	vs Master
Lines	28774	3118	90.2%	±0.0%
Branches	8353	1505	84.7%	±0.0%
Methods	7698	1221	86.3%	±0.0%

Changed Class Coverage (1 class)

Class	Line	Branch	Method
g.l.AstPrinter	+0.4% 🟢	+0.4% 🟢	+1.0% 🟢

Full HTML report: build artifact jacoco-html-report

Updated: 2026-03-22 03:59:09 UTC

…y-annotations

Initial plan

70d3d76

Copilot AI assigned Copilot and dondonz Jan 25, 2026

Copilot started work on behalf of dondonz January 25, 2026 06:36 View session

Add JSpecify annotations to 10 classes in graphql.language package

9d0253c

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

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

Copilot AI requested a review from dondonz January 25, 2026 06:56

Copilot finished work on behalf of dondonz January 25, 2026 06:56

Copilot AI mentioned this pull request Jan 28, 2026

Review all open JSpecify PRs #4231

Closed

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

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

5842edf

# Conflicts: # .claude/commands/jspecify-annotate.md

Not nullable when Node is created

a87a8a3

dondonz reviewed Feb 15, 2026

View reviewed changes

dondonz added 2 commits February 15, 2026 15:57

Remove unnecessary null check

dcb7a66

Add nullable to input that ought to be nullable

2d02ff0

dondonz marked this pull request as ready for review February 15, 2026 05:15

bbakerman reviewed Feb 19, 2026

View reviewed changes

bbakerman requested changes Feb 19, 2026

View reviewed changes

dondonz and others added 2 commits March 21, 2026 17:57

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

2612804

Resolve JSpecifyAnnotationsCheck conflict by taking master's exemption list updates (classes already annotated on master removed, new exemptions added). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove already-annotated classes from JSpecify exemption list

21261ed

NodeVisitor, NodeVisitorStub, SourceLocation, and Type are already annotated with @NullMarked so they should not be in the exemption list. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

dondonz added this to the 26.x is a breaking change release (other fixes as well) milestone Mar 21, 2026

Merge remote-tracking branch 'origin/master' into copilot/add-jspecif…

9d851ec

…y-annotations

dondonz merged commit e3d076b into master Mar 22, 2026
11 checks passed

Add JSpecify annotations to 10 graphql.language classes by Copilot · Pull Request #4217 · graphql-java/graphql-java · GitHub

Uh oh!

Add JSpecify annotations to 10 graphql.language classes - #4217

Add JSpecify annotations to 10 graphql.language classes#4217
dondonz merged 9 commits into
masterfrom
copilot/add-jspecify-annotations

Copilot AI commented Jan 25, 2026 •
edited
Loading

Uh oh!

Uh oh!

github-actions Bot commented Feb 15, 2026 •
edited
Loading

Uh oh!

Uh oh!

dondonz Feb 15, 2026

Uh oh!

bbakerman Feb 19, 2026 •
edited
Loading

Uh oh!

Uh oh!

dondonz Feb 20, 2026

Uh oh!

bbakerman left a comment

Uh oh!

github-actions Bot commented Mar 21, 2026 •
edited
Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-                      if (node == null) {
-                          return (out, type) -> {
-                          };
-                      }

Add JSpecify annotations to 10 graphql.language classes by Copilot · Pull Request #4217 · graphql-java/graphql-java · GitHub

Uh oh!

Add JSpecify annotations to 10 graphql.language classes - #4217

Add JSpecify annotations to 10 graphql.language classes#4217dondonz merged 9 commits intomastergraphql-java/graphql-java:masterfrom copilot/add-jspecify-annotationsgraphql-java/graphql-java:copilot/add-jspecify-annotationsCopy head branch name to clipboard

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!

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

Uh oh!

Test Results

Uh oh!

dondonz Feb 15, 2026

Choose a reason for hiding this comment

Uh oh!

bbakerman Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dondonz Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

bbakerman left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Report

Test Results

Code Coverage (Java 25)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add JSpecify annotations to 10 graphql.language classes#4217
dondonz merged 9 commits into
masterfrom
copilot/add-jspecify-annotations

Copilot AI commented Jan 25, 2026 •
edited
Loading

github-actions Bot commented Feb 15, 2026 •
edited
Loading

bbakerman Feb 19, 2026 •
edited
Loading

github-actions Bot commented Mar 21, 2026 •
edited
Loading