GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — JSpecify big wave 2 by dondonz · Pull Request #4184 · graphql-java/graphql-java

Conversation

dondonz commented Dec 4, 2025 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Member

We have many classes left to go for JSpecify, so rather than one class at a time I will do the remainder in large bundles. This adds annotations on ~50 classes.

The general recipe here is

Use IntelliJ's infer nullity tool, which is a start and covers the basics
AI prompt to read JavaDoc, inspect nearby methods, with self-verification using NullAway
And finally a manual check from me, as some items are hard to infer nullity without understanding the GraphQL specification or the codebase

What will be in a future PR: better Kotlin tooling as reported recently in #4179

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz added 30 commits

August 21, 2025 19:23


          Annotate GraphQLAppliedDirective

1b01d2b


          Add GraphQLSchema annotation

8684b48


          Remove exemption

0cdc8de


          Annotate GraphQLType and GraphQLEnumType

30d0abe


          Add Nullmarked to GraphQLEnumType

6ee01b8


          Annotate GraphQLCodeRegistry

a45c613


          Annotate GraphQLList

70336d5


          Annotate PropertyDataFetcher

29f8363


          Annotate GraphQLUnionType

083b2ab


          Tidy up

b4761ef


          Annotate GraphQLScalarType

9a78fb3


          Annotate GraphQLNamedInputType

7bbfd9c


          Add ErrorType

7427f64


          Annotate Directives

120095c


          Annotate ErrorClassification

012f49c


          Annotate ExceptionWhileDataFetching

afdd408


          Annotate ExecutionResult

803c924


          Annotate GraphQLContext

a322ed0


          Annotate AssertException and GraphQLError

41320d4


          Annotate GraphQLErrorBuilder

9765c21


          Annotate GraphQLErrorException

0ee713c


          Annotate ParseAndValidate

e54fca2


          Annotate ParseAndValidateResult

603c00d


          Annotate Scalars

9fcaea1


          Annotate SerializationError

88b02f3


          Update GraphQLError with a nullable location list

e65217c


          Annotate TypeMismatchError

19000a5


          Annotate UnresolvedTypeError

313bf4f


          Remove agent as no longer exists

0846c55


          Add JSpecify prompt

d2d87cd

dondonz commented

Dec 4, 2025

View reviewed changes

Comment thread

src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy

		"graphql.validation.ValidationError",
		"graphql.validation.ValidationErrorClassification",
		"graphql.validation.ValidationErrorType",
		// These classes will not be public API later, exempt here while marked as experimental

dondonz Dec 4, 2025

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an edge case where some classes have been annotated with "Experimental API" for the purposes of the defer work. They won't become public API later so I made a note in the JSpecify exemption rule

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz commented

Dec 7, 2025

View reviewed changes

Comment thread

src/main/java/graphql/GraphqlErrorException.java

		private final List<SourceLocation> locations;
		private final Map<String, Object> extensions;
		private final List<Object> path;
		private final @Nullable List<SourceLocation> locations;

dondonz Dec 7, 2025 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The builder creates a non-nullable list, but that's only if the builder is called

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions


          Change GraphQL error message to be non-nullable

c78124c

dondonz marked this pull request as ready for review

December 7, 2025 04:13


          Improve prompt

5b7104e

dondonz commented

Dec 7, 2025

View reviewed changes

Comment thread

src/main/java/graphql/GraphQLContext.java

		* @return a value or null
		*/
		public <T> T get(Object key) {
		public <T> @Nullable T get(Object key) {

dondonz Dec 7, 2025

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: another case of the nullable generic issue

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz Jan 23, 2026

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update - all values stored in the GraphQLContext are non-null. It's only going to return null if the key is not found. Let's keep it like this.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz commented

Dec 7, 2025

View reviewed changes

Comment thread

src/main/java/graphql/TypeResolutionEnvironment.java

		*/
		@SuppressWarnings("unchecked")
		public <T> T getObject() {
		public @Nullable <T> T getObject() {

dondonz Dec 7, 2025

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: another generic nullable check

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz Jan 23, 2026

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Edit: object should also be nullable

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz Jan 26, 2026

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the prompt with more information on generics

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

dondonz added 14 commits

January 23, 2026 13:49


          Add clarification on generics type arguments

de00e30


          Merge branch 'master' into infer-nullity-3

e27bf54


          Make TypeResolutionEnvironment value nullable

d5de341


          Annotate TypeResolutionParameters

0496a3d


          Add Nullmarked to TypeResolutionParameters

d2983da


          Add prompt to reduce whitespace diff

92b3ac1


          Prompt updates

0bf48d3


          Adjulst description of validation error to be nonnull


          Adjust tests to be compliant with non-nullable description

66f3fa0


          Update error message

cd232df


          Update tests given classiciation is not nullable

b8b8a5a


          Correctly set local context and context to nullable

91f0f5c


          Add mocks for i18n to accommodate non-nullable validation errors

4a05a72


          Add another i18n mock

b00dafe

dondonz commented Jan 26, 2026

Copy link

Copy Markdown

Member Author

I had a fix a bunch of tests when I changed Validation Error messages to be non-nullable

This is as per the spec - messages in GraphQL errors must be present

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

Copilot AI mentioned this pull request

Jan 28, 2026

Review all open JSpecify PRs #4231

Closed

dondonz added 3 commits

February 8, 2026 17:48


          Merge branch 'master' into infer-nullity-3

85e9854

# Conflicts:
#	src/main/java/graphql/schema/GraphQLSchema.java


          Add more nullable annotations

0a4d5d0


          Add assert

d83f175

dondonz merged commit 2f0dc5b into master

Feb 11, 2026

7 checks passed

Uh oh!

There was an error while loading. Please reload this page.

dondonz commented Feb 11, 2026

Copy link

Copy Markdown

Member Author

Special note for release notes: ValidationError technically has a breaking change, now a description must be not-nullable, which is consistent with the specification

Previously there was a mismatch that ValidationError didn't enforce description. However that doesn't make much sense, if a user receives a validation error they should also receive a description to help explain and diagnose the error

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

dondonz added the breaking change requires a new major version to be relased label

Feb 11, 2026

dondonz commented

Feb 11, 2026

View reviewed changes

Comment thread

.claude/commands/jspecify-annotate.md

		@@ -0,0 +1,59 @@
		The task is to annotate public API classes (marked with `@PublicAPI`) with JSpecify nullability annotations.

dondonz Feb 11, 2026

Copy link

Copy Markdown

Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This prompt is checked in so subagents can all share this context

This prompt will be deleted after this series of JSpecify annotations is completed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Reviewers

No reviews

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

breaking change

requires a new major version to be relased

Projects

None yet

Milestone

26.x is a breaking change release (ot...

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

1 participant

Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

Conversation

dondonz commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dondonz Dec 7, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dondonz commented Jan 26, 2026

Uh oh!

Uh oh!

dondonz commented Feb 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dondonz commented Dec 4, 2025 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

dondonz Dec 7, 2025 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.