Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt by Copilot · Pull Request #4216 · graphql-java/graphql-java · GitHub

Annotates 10 foundational classes in graphql.language with JSpecify nullability markers, continuing the repository-wide nullability annotation effort. Also updates the JSpecify annotation prompt with effectiveness improvements for future annotation work.

Changes

Interfaces (4): Node, Definition, Type, NodeVisitor

Added @NullMarked at class level

Simple classes (4): IgnoredChar, IgnoredChars, NodeVisitorStub, Comment

Added @NullMarked at class level
Marked Comment.sourceLocation as @Nullable (parser may create comments without location)

Complex classes (2): SourceLocation, NodeChildrenContainer

Added @NullMarked at class level
Marked SourceLocation.sourceName and getLocation() return as @Nullable
Marked NodeChildrenContainer.getChildOrNull() return as @Nullable
Used @NullUnmarked for NodeChildrenContainer.Builder per JSpecify builder pattern

Exemption list: Removed all 10 classes from JSpecifyAnnotationsCheck.groovy

Prompt improvements: Enhanced .claude/commands/jspecify-annotate.md with:

Batch size guidance (10 classes per batch for optimal context management)
Class prioritization strategy (start with interfaces/simple classes first)
Exploration phase guidance (use grep to understand null usage patterns)
Concrete pattern examples (interface, nullable field, nullable return type, builder)
Incremental validation strategy (compile after every 3-5 classes)

All changes validated with NullAway static analysis via ./gradlew compileJava.

Original prompt

Task

Add JSpecify annotations to approximately 10 classes in the graphql.language package, following the established JSpecify annotation pattern used in this repository.

Classes to annotate (first batch of ~10)

From the graphql.language package, annotate these classes:

Node

Definition

Type

Comment

SourceLocation

IgnoredChar

IgnoredChars

NodeChildrenContainer

NodeVisitor

NodeVisitorStub

Instructions

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

Set the 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 (see https://spec.graphql.org/draft/)

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

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

Important Notes

JSpecify is already imported in this repository (org.jspecify.annotations.NullMarked, org.jspecify.annotations.Nullable, org.jspecify.annotations.NullUnmarked)

Use @Nullable for fields, parameters, and return types that can be null

The base branch is infer-nullity-3 which already has some JSpecify work done

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.

💡 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>

This is from me, I'm experimenting with Copilot agents running in parallel

builds didn't run because I am targeting an inprogress JSpecify branch

I will later change this branch to target master for merging. The other JSpecify PR should be merged in first

I ran the NullAway checks, and the full test suite locally, and it's passed.

Very impressed with Copilot agents for parallelising this work. This was made with Claude Sonnet 4.5

Other learnings - I tried 40-50 classes at a time with Opus 4.5 via Antigravity. It couldn't cope with too much context. Much better results with doing 10 at a time, as done here

@copilot Excellent work. Coming back to the original JSpecify prompt, what would you change to make the next agent run even more effective?

@copilot Excellent work. Coming back to the original JSpecify prompt, what would you change to make the next agent run even more effective?

Based on this run, here are suggestions to make the prompt even more effective:

Add to the prompt:

Explicit class prioritization: "Start with interface/simple classes first, then tackle complex classes with builders. This helps identify patterns early."
Exploration phase guidance: "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."
Pattern examples: Add 2-3 concrete before/after examples showing:
- Interface with just @NullMarked
- Class with nullable field
- Class with nullable return type
- Builder with @NullUnmarked
Validation strategy: "Run ./gradlew compileJava after every 3-5 classes annotated, not just at the end. This catches issues early and makes debugging easier."
Batch size confirmation: "You mentioned 10 classes works well - add this explicitly: 'Annotate approximately 10 classes per batch for optimal context management.'"

Already working well:

The builder pattern guidance (@NullUnmarked)
GraphQL spec compliance section
Minimal changes emphasis
Exemption list cleanup reminder

The current prompt is solid - these additions would just reduce exploration time and catch issues faster.

@copilot Make these changes to the prompt in this pull request

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

@copilot Make these changes to the prompt in this pull request

Updated the prompt in .claude/commands/jspecify-annotate.md with the suggested improvements (commit 3db2dde):

Added sections:

Batch Size and Prioritization: 10 classes per batch, prioritize simple classes first
Exploration Phase: Use grep to understand null usage patterns
Pattern Examples: 4 concrete before/after examples (interface, nullable field, nullable return, builder)
Validation Strategy: Compile after every 3-5 classes for early error detection

The prompt now provides clearer guidance on workflow and includes practical examples to reduce exploration time.

Copliot PRs always have a / in the name, which makes it appear like the jar is in another directory when developing locally. This sanitises the name

This diff looks unusual because it depends on the first large jspecify pr to go in

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

Test Results

335 files ±0 335 suites ±0 5m 6s ⏱️ -1s
5 371 tests ±0 5 362 ✅ - 1 9 💤 +1 0 ❌ ±0
5 460 runs ±0 5 451 ✅ - 1 9 💤 +1 0 ❌ ±0

Results for commit 5aaada6. ± 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@26350ea2 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@1e9469b8 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@5a08efdc 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@2d3ef181 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@a2341c6 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@6e4c0d8c 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@642f9a77 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@4052c8c2 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@518bfd90 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@45acdd11 delegate=inaccessible owner=inaccessible thisObject=inaccessible resolveStrategy=inaccessible directive=inaccessible parameterTypes=inaccessible maximumNumberOfParameters=inaccessible bcw=inaccessible thisType=inaccessible>, expectedMessage: error arg1, #0]
…

This pull request skips 1 test.

graphql.schema.fetching.LambdaFetchingSupportTest ‑ different class loaders induce certain behaviours

♻️ This comment has been updated with latest results.

# Conflicts: # .claude/commands/jspecify-annotate.md # build.gradle # src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy

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	28775	3120	90.2%	±0.0%
Branches	8354	1506	84.7%	±0.0%
Methods	7698	1222	86.3%	±0.0%

No per-class coverage changes detected.

Full HTML report: build artifact jacoco-html-report

Updated: 2026-03-21 07:13:51 UTC

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>

Initial plan

c60fdf6

Copilot AI assigned Copilot and dondonz Jan 24, 2026

Copilot started work on behalf of dondonz January 24, 2026 20:32 View session

Add JSpecify annotations to 10 classes in graphql.language package

c02fa4e

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

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

Copilot AI requested a review from dondonz January 24, 2026 20:44

Copilot finished work on behalf of dondonz January 24, 2026 20:44

dondonz marked this pull request as ready for review January 24, 2026 20:52

dondonz marked this pull request as draft January 24, 2026 20:52

Copilot started work on behalf of dondonz January 24, 2026 21:21 View session

Copilot finished work on behalf of dondonz January 24, 2026 21:23

Copilot started work on behalf of dondonz January 24, 2026 21:24 View session

Update JSpecify annotation prompt with effectiveness improvements

3db2dde

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

Copilot AI changed the title Add JSpecify annotations to 10 classes in graphql.language package Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt Jan 24, 2026

Copilot finished work on behalf of dondonz January 24, 2026 21:26

Copilot AI mentioned this pull request Jan 28, 2026

Review all open JSpecify PRs #4231

Closed

dondonz changed the base branch from infer-nullity-3 to master February 8, 2026 07:17

dondonz changed the base branch from master to infer-nullity-3 February 8, 2026 21:37

Allow slashes in dev branch names

e7144c6

dondonz reviewed Feb 8, 2026

View reviewed changes

dondonz changed the base branch from infer-nullity-3 to master February 8, 2026 21:59

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

5aaada6

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

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

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

0c7b9c3

# Conflicts: # .claude/commands/jspecify-annotate.md # build.gradle # src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy

Remove already-annotated classes from JSpecify exemption list

4665320

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>

github-actions Bot mentioned this pull request Mar 21, 2026

CI Failure DoctorCI Failure - Run #23374241737 - JSpecifyAnnotationsCheck test fails on Java 21 #4345

Closed

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

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

github-actions Bot mentioned this pull request Mar 22, 2026

CI Failure DoctorCI Failure - Run #23398087408 - JSpecifyAnnotationsCheck exemption list conflict #4351

Closed

1 task

Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt by Copilot · Pull Request #4216 · graphql-java/graphql-java · GitHub

Uh oh!

Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt - #4216

Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt#4216
dondonz merged 7 commits into
masterfrom
copilot/add-jspecify-annotations-to-classes

Copilot AI commented Jan 24, 2026 •
edited
Loading

Uh oh!

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

Copilot AI commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

Copilot AI commented Jan 24, 2026

Uh oh!

dondonz Feb 8, 2026

Uh oh!

dondonz commented Feb 8, 2026

Uh oh!

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

Uh oh!

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!

2 participants

+                  def sanitizedBranchName = branchName.replace('/', '-')
-                  return makeDevelopmentVersion(["0.0.0", branchName, "SNAPSHOT"])
+                  return makeDevelopmentVersion(["0.0.0", sanitizedBranchName, "SNAPSHOT"])

Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt by Copilot · Pull Request #4216 · graphql-java/graphql-java · GitHub

Uh oh!

Add JSpecify annotations to 10 classes in graphql.language package and improve annotation prompt - #4216

Conversation

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

Uh oh!

Changes

Task

Classes to annotate (first batch of ~10)

Instructions

Validation

Cleanup

Important Notes

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

Copilot AI commented Jan 24, 2026

Uh oh!

dondonz commented Jan 24, 2026

Uh oh!

Copilot AI commented Jan 24, 2026

Uh oh!

dondonz Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

dondonz commented Feb 8, 2026

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!

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!

2 participants

Copilot AI commented Jan 24, 2026 •
edited
Loading

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

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