48. Nullness checked with NullAway in the core build
Date: 2026-10-16
Status
Accepted
Context
ADR 0041 marked the exported packages of
bikesched-core with JSpecify, but left the internal packages unmarked and the build without a
checker. The implementation therefore guarded itself: most internal constructors and records
started with Objects.requireNonNull for every argument, although the values came from other
internal code that never passes null. Which internal fields, parameters and record components may
be null was only stated in Javadoc, and a missing @Nullable on the API was only caught in
review.
The alternatives were to keep checking with NullAway now and then by hand, or to use the Checker Framework’s nullness checker, which is stricter but much slower and needs more annotations (initialization, map keys).
Decision
bikesched checks nullness at compile time with Error Prone and
NullAway in JSpecify mode, applied to bikesched-core by the
convention plugin bikesched.errorprone.
- Every package of
bikesched-coreis@NullMarked, the internal ones included. Fields, parameters, returns and record components that may benullare@Nullable. - NullAway checks only
@NullMarkedcode (OnlyNullMarked); unannotated libraries are trusted. A NullAway finding is a compile error. - Error Prone’s default checks run too; their warnings fail the build like other compiler warnings
(
-Werror). Test sources are not checked. - Internal code does not check for
nullwhat the types already exclude: norequireNonNullon arguments coming from other internal code. Checks stay at the API boundary, where callers may be unchecked code (user arguments ofBikesched,Joband the builders, user SPIs returning values). Sql.Rowis@NullUnmarked: whether a column getter returnsnulldepends on the schema, which the types cannot see. Rows map NOT NULL columns into non-null fields and nullable columns into@Nullableones.checker-qualis a compile-only dependency of core: NullAway reads the package annotations of the PostgreSQL driver, which refer to it.
Consequences
- Dereferencing a possibly
nullvalue, or passingnullwhere it is not allowed, fails the build instead of surfacing as aNullPointerExceptionat runtime, and a missing@Nullableon the API is caught when its implementation passesnull. - About 140 null checks of internal arguments are gone, and the nullness of internal state is part of its type instead of its Javadoc.
- Compiling core takes longer (Error Prone runs as a javac plugin), and new code must keep the annotations correct; a value NullAway cannot follow (a field read twice) needs a local variable.
- Follow-up: the other Java modules are not checked yet (
IDEAS.md).