Skip to content

Add JSpecify annotations to 10 language package classes#4220

Draft
Copilot wants to merge 80 commits intomasterfrom
copilot/add-jspecify-annotations-yet-again
Draft

Add JSpecify annotations to 10 language package classes#4220
Copilot wants to merge 80 commits intomasterfrom
copilot/add-jspecify-annotations-yet-again

Conversation

Copy link
Contributor

Copilot AI commented Jan 25, 2026 •
edited
Loading

Annotates 10 classes in graphql.language package with JSpecify nullability markers to improve type safety and enable static null checking via NullAway.

Changes

  • Added @NullMarked to: NodeTraverser, NonNullType, ObjectField, ObjectTypeDefinition, ObjectTypeExtensionDefinition, OperationDefinition, OperationTypeDefinition, PrettyAstPrinter, SDLDefinition, SDLExtensionDefinition

  • Marked nullable fields/parameters with @Nullable:

    • SourceLocation (consistently nullable across codebase)
    • OperationDefinition.name and operation (null for anonymous operations)
    • OperationDefinition.selectionSet
    • Description in type definitions
    • Method parameters in PrettyAstPrinter helper methods

  • Added @NullUnmarked to all Builder static classes per pattern

  • Removed NamedNode interface from OperationDefinition - the interface requires non-null names but operations support null names for anonymous queries:

    // Anonymous operation - name is null
{
  field
}

  • Used assertNotNull in deepCopy methods where nullable values are passed to non-null constructor parameters

  • Removed annotated classes from JSpecifyAnnotationsCheck.groovy exemption list

Example

@PublicApi
@NullMarked
public class OperationDefinition extends AbstractNode<OperationDefinition> {
    private final @Nullable String name;
    private final @Nullable Operation operation;
    private final @Nullable SelectionSet selectionSet;
    
    public @Nullable String getName() {
        return name;
    }
    
    @NullUnmarked
    public static final class Builder {
        // No further annotations needed
    }
}
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.NodeTraverser
  2. graphql.language.NonNullType
  3. graphql.language.ObjectField
  4. graphql.language.ObjectTypeDefinition
  5. graphql.language.ObjectTypeExtensionDefinition
  6. graphql.language.OperationDefinition
  7. graphql.language.OperationTypeDefinition
  8. graphql.language.PrettyAstPrinter
  9. graphql.language.SDLDefinition
  10. graphql.language.SDLExtensionDefinition

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.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

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 20 commits August 31, 2025 20:04
@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
d7d046b
Copilot AI changed the title [WIP] Add JSpecify annotations to classes in graphql.language package Add JSpecify annotations to 10 language package classes Jan 25, 2026
Copilot AI requested a review from dondonz January 25, 2026 07:01
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:16
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