🌐 AI搜索 & 代理 主页
Skip to content

Require JSpecify annotations on new Public API and Experimental API classes #3892

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
Merged
dondonz merged 17 commits into from
Aug 10, 2025
Merged

Require JSpecify annotations on new Public API and Experimental API classes #3892

dondonz merged 17 commits into from
Aug 10, 2025

Conversation

@dondonz
Copy link
Member

@dondonz dondonz commented Apr 5, 2025 •
edited
Loading

Resolves #3877

This PR adds an ArchUnit test to require new Public API and Experimental API classes have the @NullMarked annotation on the class. See the documentation: https://jspecify.dev/docs/user-guide/#nullmarked

I put a PR up so it's easier to have a discussion, I'm open to ideas.

I originally tried to allow list all classes, but because we're starting off from almost zero, we have another 1,200 classes to go. That's a very, very long allow list! I thought instead we can start with public & experimental API classes, which is a mere ~350 classes. This would add the most value for users of the library.

I had thought about using Git to collect a list of new classes, but I don't want to spin up a new process every time we do a test run.

Sample test output

https://github.com/graphql-java/graphql-java/actions/runs/14279382170/job/40027003549?pr=3892

JSpecifyAnnotationsCheck > ensure all public API and experimental API classes have @NullMarked annotation STANDARD_OUT
    The following public API and experimental API classes are missing @NullMarked annotation:
                graphql.AssertException
            
    Add @NullMarked to these public API classes and add @Nullable annotations where appropriate. See documentation at https://jspecify.dev/docs/user-guide/#nullmarked

JSpecifyAnnotationsCheck > ensure all public API and experimental API classes have @NullMarked annotation FAILED
    Condition not satisfied:

    false

    Found 1 public API and experimental API classes missing @NullMarked annotation
        at graphql.JSpecifyAnnotationsCheck.ensure all public API and experimental API classes have @NullMarked annotation(JSpecifyAnnotationsCheck.groovy:394)

Update, now with a new test to make sure we keep the exemption list up to date!

The following classes are in the JSpecify exemption list but are annotated with @NullMarked:
graphql.execution.DataFetcherResult
graphql.execution.RawVariables
graphql.schema.DataFetchingEnvironment
graphql.schema.idl.FieldWiringEnvironment
graphql.schema.idl.InterfaceWiringEnvironment
graphql.schema.idl.MockedWiringFactory
graphql.schema.idl.ScalarInfo
graphql.schema.idl.ScalarWiringEnvironment
graphql.schema.idl.SchemaParser
graphql.schema.idl.TypeDefinitionRegistry
graphql.schema.idl.UnionWiringEnvironment
graphql.schema.idl.WiringEnvironment

@github-actions
Copy link
Contributor

github-actions bot commented Apr 5, 2025 •
edited
Loading

Test Results

  324 files    324 suites   3m 26s ⏱️
5 018 tests 5 012 ✅ 6 💤 0 ❌
5 107 runs  5 101 ✅ 6 💤 0 ❌

Results for commit c36c533.

♻️ This comment has been updated with latest results.

@dondonz dondonz requested review from andimarek and bbakerman May 11, 2025 03:34
dondonz
dondonz commented Jul 10, 2025
View reviewed changes
src/test/groovy/graphql/JSpecifyAnnotationsCheck.groovy Outdated
"graphql.ErrorClassification",
"graphql.ErrorType",
"graphql.ExceptionWhileDataFetching",
"graphql.ExecutionInput",
Copy link
Member Author

@dondonz dondonz Jul 10, 2025

Choose a reason for hiding this comment

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

Can remove ExecutionInput

@dondonz
Copy link
Member Author

dondonz commented Jul 31, 2025

Todo - some classes have since been updated to include nullability annotations like GraphQL, Execution Input, remove agent

To do - add a rule to double check when a class does have nullability annotations added, we want to progressively make this list smaller

dondonz
dondonz commented Aug 2, 2025
View reviewed changes
src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy
class JSpecifyAnnotationsCheck extends Specification {

private static final Set<String> JSPECIFY_EXEMPTION_LIST = [
"graphql.AssertException",
Copy link
Member Author

@dondonz dondonz Aug 2, 2025

Choose a reason for hiding this comment

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

Now updated to remove a bunch of classes we've since annotated

dondonz
dondonz commented Aug 3, 2025
View reviewed changes
src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy
}
}

def "exempted classes should not be annotated with @NullMarked or @NullUnmarked"() {
Copy link
Member Author

@dondonz dondonz Aug 3, 2025

Choose a reason for hiding this comment

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

Now also allows @NullUnmarked, which we usually put on builders

andimarek
andimarek approved these changes Aug 7, 2025
View reviewed changes
Copy link
Member

@andimarek andimarek left a comment

Choose a reason for hiding this comment

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

Approve, but this needs to be updated after 4075 and 3899 are merged

@dondonz dondonz merged commit e62055e into master Aug 10, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@andimarek andimarek andimarek approved these changes

@bbakerman bbakerman Awaiting requested review from bbakerman

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

25.x breaking changes

Development

Successfully merging this pull request may close these issues.

Enforce JSpecify annotations on new classes

3 participants

@dondonz @andimarek