Skip to content

Add JSpecify annotations to 10 graphql.language classes #4217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
Copilot wants to merge 79 commits into
base: master
Choose a base branch
from
Draft

Add JSpecify annotations to 10 graphql.language classes #4217

Copilot wants to merge 79 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Jan 25, 2026 •
edited
Loading

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

  1. graphql.language.AbstractDescribedNode
  2. graphql.language.AstNodeAdapter
  3. graphql.language.AstPrinter
  4. graphql.language.AstSignature
  5. graphql.language.AstSorter
  6. graphql.language.AstTransformer
  7. graphql.language.DescribedNode
  8. graphql.language.Description
  9. graphql.language.Directive
  10. graphql.language.DirectiveDefinition

Instructions

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

  1. Set each class to be @NullMarked at the class level
  2. Remove all redundant @NonNull annotations that IntelliJ may have added
  3. Check Javadoc for @param tags mentioning "null", "nullable", "may be null"
  4. Check Javadoc @return tags mentioning "null", "optional", "if available"
  5. Inspect method implementations that return null or check for null
  6. Consider GraphQL specification details when determining nullability
  7. 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

  1. Remove each completed class from the exemption list in src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy
  2. Delete all unused imports from the classes you've annotated
  3. 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.

dondonz added 30 commits August 21, 2025 19:23
@dondonz
Annotate GraphQLAppliedDirective
1b01d2b
@dondonz
Add GraphQLSchema annotation
8684b48
@dondonz
Remove exemption
0cdc8de
@dondonz
Annotate GraphQLType and GraphQLEnumType
30d0abe
@dondonz
Add Nullmarked to GraphQLEnumType
6ee01b8
@dondonz
Annotate GraphQLCodeRegistry
a45c613
@dondonz
Annotate GraphQLList
70336d5
@dondonz
Annotate PropertyDataFetcher
29f8363
@dondonz
Annotate GraphQLUnionType
083b2ab
@dondonz
Tidy up
b4761ef
@dondonz
Annotate GraphQLScalarType
9a78fb3
@dondonz
Annotate GraphQLNamedInputType
7bbfd9c
@dondonz
Add ErrorType
7427f64
@dondonz
Annotate Directives
120095c
@dondonz
Annotate ErrorClassification
012f49c
@dondonz
Annotate ExceptionWhileDataFetching
afdd408
@dondonz
Annotate ExecutionResult
803c924
@dondonz
Annotate GraphQLContext
a322ed0
@dondonz
Annotate AssertException and GraphQLError
41320d4
@dondonz
Annotate GraphQLErrorBuilder
9765c21
@dondonz
Annotate GraphQLErrorException
0ee713c
@dondonz
Annotate ParseAndValidate
e54fca2
@dondonz
Annotate ParseAndValidateResult
603c00d
@dondonz
Annotate Scalars
9fcaea1
@dondonz
Annotate SerializationError
88b02f3
@dondonz
Update GraphQLError with a nullable location list
e65217c
@dondonz
Annotate TypeMismatchError
19000a5
@dondonz
Annotate UnresolvedTypeError
313bf4f
@dondonz
Remove agent as no longer exists
0846c55
@dondonz
Add JSpecify prompt
d2d87cd
dondonz and others added 21 commits August 31, 2025 20:04
@dondonz
Add Nullmarked
de6ad66
@dondonz
Revert to nullable description and type for ValidationError
fd3b4af
@dondonz
Update test for Argument, and make nonnullable field clearer
71ef680
@dondonz
Annotate Anonymizer
23afaea
@dondonz
Merge branch 'master' into infer-nullity-3
bd2bd8d 
# Conflicts:
#	src/main/java/graphql/relay/DefaultConnectionCursor.java
#	src/main/java/graphql/relay/DefaultEdge.java
#	src/main/java/graphql/relay/SimpleListConnection.java
@dondonz
Use string literal optimisation for assert
09a5236
@dondonz
Tidy up
d1e2e54
@dondonz
Make path length not nullable
95e7dc9
@dondonz
Use string literal for assert messages
f8920d8
@dondonz
Change GraphQL error message to be non-nullable
c78124c
@dondonz
Improve prompt
5b7104e
@dondonz
Add clarification on generics type arguments
de00e30
@dondonz
Merge branch 'master' into infer-nullity-3
e27bf54
@dondonz
Make TypeResolutionEnvironment value nullable
d5de341
@dondonz
Annotate TypeResolutionParameters
0496a3d
@dondonz
Add Nullmarked to TypeResolutionParameters
d2983da
@dondonz
Add prompt to reduce whitespace diff
92b3ac1
Initial plan
c60fdf6
@dondonz
Add JSpecify annotations to 10 classes in graphql.language package
c02fa4e 
Co-authored-by: dondonz <[email protected]>
@dondonz
Update JSpecify annotation prompt with effectiveness improvements
3db2dde 
Co-authored-by: dondonz <[email protected]>
Initial plan
70d3d76
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 AI mentioned this pull request Jan 28, 2026
Draft
@dondonz dondonz changed the base branch from copilot/add-jspecify-annotations-to-classes to master February 8, 2026 07:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dondonz dondonz Awaiting requested review from dondonz

Assignees

@dondonz dondonz

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@dondonz