Awesome

gradle-nullaway-plugin

This plugin is a companion to the net.ltgt.errorprone Gradle plugin that adds a Gradle DSL to configure NullAway

Requirements

This plugin requires using at least Gradle 6.8, and applying the net.ltgt.errorprone plugin (it won't do anything otherwise).

Usage

plugins {
    id("net.ltgt.errorprone") version "<error prone plugin version>"
    id("net.ltgt.nullaway") version "<plugin version>"
}

then add the NullAway dependency to the errorprone configuration:

dependencies {
    errorprone("com.uber.nullaway:nullaway:$nullawayVersion")
}

and finally configure NullAway's annotated packages:

nullaway {
    annotatedPackages.add("net.ltgt")
}

Configuration

Other NullAway flags, as well as the check severity, can be configured on the JavaCompile tasks:

tasks.withType(JavaCompile).configureEach {
    options.errorprone.nullaway {
        error()
        unannotatedSubPackages.add("com.foo.baz")
    }
}

or with Kotlin DSL:

import net.ltgt.gradle.errorprone.errorprone
import net.ltgt.gradle.nullaway.nullaway

tasks.withType<JavaCompile>().configureEach {
    options.errorprone.nullaway {
        error()
        unannotatedSubPackages.add("com.foo.baz")
    }
}

Properties

Please note that all properties are lazy, so while you can use = in place of .set(…) in the Groovy DSL, you cannot use << or += to add to lists for instance.

Each property (except for severity) maps to an -XepOpt:NullAway:[propertyName]=[value] Error Prone argument.

Property	Description
`severity`	The check severity. Almost equivalent to `options.errorprone.check("NullAway", severity)` (NullAway won't actually appear in `options.errorprone.checks`). Can be set to `CheckSeverity.OFF` to disable NullAway.
`annotatedPackages`	The list of packages that should be considered properly annotated according to the NullAway convention. This can be used to add to or override the `annotatedPackages` at the project level.
`unannotatedSubPackages`	A list of subpackages to be excluded from the AnnotatedPackages list.
`unannotatedClasses`	A list of classes within annotated packages that should be treated as unannotated.
`knownInitializers`	The fully qualified name of those methods from third-party libraries that NullAway should treat as initializers.
`excludedClassAnnotations`	A list of annotations that cause classes to be excluded from nullability analysis.
`excludedClasses`	A list of classes to be excluded from the nullability analysis.
`excludedFieldAnnotations`	A list of annotations that cause fields to be excluded from being checked for proper initialization.
`customInitializerAnnotations`	A list of annotations that should be considered equivalent to `@Initializer` annotations, and thus mark methods as initializers.
`externalInitAnnotations`	A list of annotations for classes that are "externally initialized."
`treatGeneratedAsUnannotated`	If set to true, NullAway treats any class annotated with `@Generated` as if its APIs are unannotated when analyzing uses from other classes.
`acknowledgeRestrictiveAnnotations`	If set to true, NullAway will acknowledge nullability annotations whenever they are available in unannotated code and also more restrictive than it's optimistic defaults.
`checkOptionalEmptiness`	If set to true, NullAway will check for `.get()` accesses to potentially empty `Optional` values, analogously to how it handles dereferences to `@Nullable` values.
`checkOptionalEmptinessCustomClasses`	A list of classes to be treated as `Optional` implementations (e.g. Guava's `com.google.common.base.Optional`).
`suggestSuppressions`	If set to true, NullAway will use Error Prone's suggested fix functionality to suggest suppressing any warning that it finds.
`autoFixSuppressionComment`	A comment that will be added alongside the `@SuppressWarnings("NullAway")` annotation when `isSuggestSuppressions` is set to true.
`castToNonNullMethod`	The fully qualified name of a method to be used for downcasting to a non-null value rather than standard suppressions in some instances.
`assertsEnabled`	(`isAssertsEnabled` with Kotlin DSL) If set to true, NullAway will handle assertions, and use that to reason about the possibility of null dereferences in the code that follows these assertions. This assumes that assertions will always be enabled at runtime.
`handleTestAssertionLibraries`	If set to true, NullAway will handle assertions from test libraries, like `assertThat(...).isNotNull()`, and use that to reason about the possibility of null dereferences in the code that follows these assertions.
`exhaustiveOverride`	(`isExhaustiveOverride` with Kotlin DSL) If set to true, NullAway will check every method to see whether or not it overrides a method of a super-type, rather than relying only on the `@Override` annotation.
`acknowledgeAndroidRecent`	If set to true, treats `@RecentlyNullable` as `@Nullable`, and `@RecentlyNonNull` as `@NonNull`; requires that `acknowledgeRestrictiveAnnotations` is also set to true.
`checkContracts`	If set to true, NullAway will check `@Contract` annotations.
`customContractAnnotations`	A list of annotations that should be considered equivalent to `@Contract` annotations.
`customNullableAnnotations`	A list of annotations that should be considered equivalent to `@Nullable` annotations.
`customNonnullAnnotations`	A list of annotations that should be considered equivalent to `@NonNull` annotations, for the cases where NullAway cares about such annotations (see e.g. `acknowledgeRestrictiveAnnotations`).
`customGeneratedCodeAnnotations`	A list of annotations that should be considered equivalent to `@Generated` annotations, for the cases where NullAway cares about such annotations (see e.g. `treatGeneratedAsUnannotated`).
`jspecifyMode`	(`isJSpecifyMode` with Kotlin DSL) If set to true, enables new checks based on JSpecify (like checks for generic types).
`extraFuturesClasses`	A list of classes to be treated equivalently to Guava `Futures` and `FluentFuture`; this special support will likely be removed once NullAway's JSpecify support is more complete.

Methods

Method	Description
`enable()`	Enable NullAway. Equivalent to `severity.set(CheckSeverity.DEFAULT)`.
`disable()`	Disable NullAway. Equivalent to `severity.set(CheckSeverity.OFF)`.
`warn()`	Enable NullAway as a warning. Equivalent to `severity.set(CheckSeverity.WARN)`.
`error()`	Enable NullAway as an error. Equivalent to `severity.set(CheckSeverity.ERROR)`.