Require JSpecify annotations on new Public API and Experimental API classes by dondonz · Pull Request #3892

Require JSpecify annotations on new Public API and Experimental API classes by dondonz · Pull Request #3892 · graphql-java/graphql-java

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