pkl-core: Migrate nullness to JSpecify (#1601)

Replace pkl-core's local nullness annotations with JSpecify annotations.
Enable NullAway checking for pkl-core packages except org.pkl.core.ast
and org.pkl.core.stdlib.

Notable code changes:
- Add a dedicated late-init constructor to VmTyped
- Move VmExceptionBuilder's fallback message derivation from withCause()
to build()
- Split VmException rendering between builder-provided messages and
string-backed messages
- Initialize MessageTransport handlers with default throwing handlers
- Update JSON helper collection types to allow nullable values JSON
arrays and objects can contain JSON null,
so the Java Map/List element types need to model nullable elements
explicitly
- Make public command transform APIs accept nullable transformed values 
   Command transforms can produce null for optional/default handling,
so the BiFunction and options-map element types now model that
explicitly
- Make ExecutorSpiException accept nullable message and cause 
Existing call sites can pass nullable causes from Throwable.getCause()
- Remove JSR-305 semantics from `@LateInit`
   JSpecify does not support the same type-qualifier-nickname pattern,
so `@LateInit` is now documentation plus a NullAway
constructor-initialization exemption

Out of scope:
- NullAway checking of org.pkl.core.ast and org.pkl.core.stdlib
- IntelliJ warnings related to `@LateInit` fields
- Removing the JSR-305 dependency, since concurrency annotations are
still in use
This commit is contained in:
odenix
2026-05-21 22:57:20 +02:00
committed by GitHub
parent 63ef60f3c4
commit 3dc93cbd4a
261 changed files with 709 additions and 723 deletions
@@ -39,6 +39,7 @@ import javax.lang.model.element.Modifier;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.type.TypeMirror;
import org.jspecify.annotations.Nullable;
/**
* Generates a subclass of {@code org.pkl.core.stdlib.registry.ExternalMemberRegistry} for each
@@ -114,6 +115,7 @@ public final class MemberRegistryGenerator extends AbstractProcessor {
Comparator.comparing(
(TypeElement element) -> {
var enclosingElement = element.getEnclosingElement();
assert enclosingElement != null;
return enclosingElement.getKind() == ElementKind.PACKAGE
? ""
: enclosingElement.getSimpleName().toString();
@@ -155,6 +157,7 @@ public final class MemberRegistryGenerator extends AbstractProcessor {
for (var nodeClass : nodeClasses) {
var enclosingClass = nodeClass.getEnclosingElement();
assert enclosingClass != null;
var pklClassName = getAnnotatedPklName(enclosingClass);
if (pklClassName == null) {
@@ -226,7 +229,7 @@ public final class MemberRegistryGenerator extends AbstractProcessor {
writeJavaFile(REGISTRY_PACKAGE_NAME, registryFactoryClass.build());
}
private String getAnnotatedPklName(Element element) {
private @Nullable String getAnnotatedPklName(Element element) {
for (var annotation : element.getAnnotationMirrors()) {
var annotationName = annotation.getAnnotationType().asElement().getSimpleName().toString();
@@ -0,0 +1,4 @@
@NullMarked
package org.pkl.core.generator;
import org.jspecify.annotations.NullMarked;