Skip to content

Complete JSpecify annotation coverage for public APIs and SPIs - #4301

Merged
andimarek merged 18 commits into
masterfrom
claude/jspecify-wave4
Nov 13, 2026
Merged

andimarek merged 18 commits into
masterfrom
claude/jspecify-wave4

Conversation

@dondonz

@dondonz dondonz commented Mar 7, 2026 •

Copy link
Copy Markdown
Member

This PR completes JSpecify coverage for public API, public SPI, and experimental API classes. It annotates the existing behavior and restrictions, including nullable resolver results, collection elements, future results, optional metadata, traversal state, and deleted transformation roots. All 42 remaining exemption entries across 41 source files are migrated; the ArchUnit exemption lists are removed. Builders remain @NullUnmarked where appropriate.

Production changes beyond annotations are limited to supporting accurate nullness checking:

Supporting change Why it is needed
assertNotNull at required-value uses Nullable lookup/visitor/callback APIs also serve paths that already require a value. Assertions expose those existing invariants to NullAway. Conditional uses remain conditional, including introspection-type skipping and error-reporting branches. Invalid null inputs remain rejected; some failures become diagnostic AssertExceptions instead of incidental NPEs.
Typed MutableRef<T> reducer accumulator Preserves the nullness relationship between the initial value, reducer input/output, and return type. The original Object[] representation loses that relationship and produces four NullAway errors. Traversal order and callback behavior are unchanged.
Type-preserving execution filter and nullness cast List<T> input and List<@NonNull T> output preserve the caller's element type while filtering nullable cancellation entries. The existing fast path still returns the input list when it contains no nulls; the cast narrows nullness without widening a mutable subtype list.
JDK empty maps for nullable-value contracts Needed in CoercedVariables and ExtensionsBuilder because Guava's non-null generic bounds cannot represent nullable value types. The original DataFetchingEnvironmentImpl supplier is retained. The empty extensions map remains unmodifiable in content, but permits no-op clear()/absent-key remove() calls that Guava rejected.
Removal of redundant null initializers for constructor-assigned fields Allows those fields to be correctly non-null without assigning null first. The cycle analyzer's separate phase-dependent workspace remains nullable, with its original allocation, detachment, and reset lifecycle.
Nullness relationship annotations on helpers Contracts on AbstractNode.deepCopy and SchemaPrinter.shouldPrintAsAst express the existing non-null-copy and guarded-definition relationships, avoiding 18 runtime assertions. Other helper contracts likewise preserve their implementations.

NodeZipper continues to accept a nullable adapter for operations that do not rebuild parents, including the existing parallel transformation path. The adapter is required only where parent reconstruction uses it. ValueTraverser retains its existing Guava copying restriction. Parser error handling, comparator equality, directive printing, and deferred-execution state retain their existing behavior. No new fallback policies, runtime bug fixes, algorithm refactors, or unrelated cleanups are included.

The annotation contracts are verified by Java consumer fixtures compiled with NullAway, Kotlin nullable-resolver fixtures, reflection checks for nested type-use annotations, and ArchUnit. Positive fixtures include root zippers without adapters and preservation of execution-filter element subtypes; negative fixtures reject six unsafe API usages and six unsafe SPI usages. Three focused runtime features verify existing reducer, root-deletion, and predicate behavior affected by the annotation adaptations. The checker does not model every JDK collection/callback generic use, so reflection checks supplement compilation. Stricter published contracts can surface downstream nullness diagnostics.

The separately requested nullness-tooling upgrades are retained:

Component Previous Updated
JSpecify 1.0.0 1.0.1
NullAway 0.13.8 0.14.3
Error Prone 2.50.0 2.52.0
Error Prone Gradle plugin 5.1.1 5.2.0
Kotlin test plugin/stdlib 2.4.20 2.4.21

NullAway remains an error with OnlyNullMarked and JSpecifyMode; no nullness suppressions or dependencies are added. The existing merge of master at 32e924f0c7d8f27f93ae923a0cfb18af9aaa8173 is retained. .claude files, unrelated local Unicode tests, CI configuration, and the coverage baseline are excluded.

Validation:

  • Full Java 25 command ./gradlew test testng check javadoc jacocoTestReport passed for 50cf905bb: 6,440 Spock cases (seven expected skips) and 190 reactive-streams TCK cases (49 expected skips), with zero failures/errors. The local total includes 33 unrelated, uncommitted Unicode cases.
  • The updated subtype-preserving consumer fixture fails against the previous implementation and passes with this signature. The unsafe mutable subtype-list alias is rejected by Java before execution.
  • The eight restored AST classes and DataFetchingEnvironmentImpl match the base executable code after stripping nullness annotations and imports.
  • JaCoCo comparison shows zero per-class coverage regressions against the unchanged baseline.
  • GitHub CI for 50cf905bb passed Java 17/21/25 tests, concurrency tests, build checks, Javadoc, and the per-class coverage gate. File-validation checks also passed.

@dondonz
dondonz changed the base branch from claude/agent-team-jspecify-Frd74 to master March 7, 2026 20:35
@github-actions

github-actions Bot commented Mar 7, 2026 •

Copy link
Copy Markdown
Contributor

Test Report

Test Results

Java Version Total Passed Failed Errors Skipped
Java 17 6597 (+13 🟢) 6541 (+13 🟢) 0 (±0) 0 (±0) 56 (±0)
Java 21 6597 (+13 🟢) 6541 (+13 🟢) 0 (±0) 0 (±0) 56 (±0)
Java 25 6597 (+13 🟢) 6541 (+13 🟢) 0 (±0) 0 (±0) 56 (±0)
jcstress 32 (±0) 32 (±0) 0 (±0) 0 (±0) 0 (±0)
Total 19823 (+39 🟢) 19655 (+39 🟢) 0 (±0) 0 (±0) 168 (±0)

Code Coverage (Java 25)

Metric Covered Missed Coverage vs Master
Lines 30689 3001 91.1% ±0.0%
Branches 9151 1483 86.1% ±0.0%
Methods 8178 1160 87.6% ±0.0%

Changed Class Coverage (4 classes)

Class Line Branch Method
g.a.QueryTraverser +0.1% 🟢 ±0.0% ±0.0%
g.i.Introspection ±0.0% +0.7% 🟢 ±0.0%
g.s.SchemaTransformer +0.1% 🟢 ±0.0% ±0.0%
g.u.NodeZipper +0.2% 🟢 ±0.0% ±0.0%

Full HTML report: build artifact jacoco-html-report

Updated: 2026-11-13 10:39:41 UTC

public void compute() {
currentContext.setPhase(TraverserContext.Phase.ENTER);
currentContext.setVar(List.class, myZippers);
currentContext.setVar(NodeAdapter.class, nodeAdapter);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Another interesting bugfix surfaced by JSpecify

@dondonz

dondonz commented May 23, 2026

Copy link
Copy Markdown
Member Author

Note this is only failing the coverage test for now

@dondonz
dondonz marked this pull request as ready for review May 24, 2026 00:31
return objectTypeDefinition.build();
}

@SuppressWarnings("NullAway")

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Should remove these NullAway suppress warnings

@andimarek
andimarek force-pushed the claude/jspecify-wave4 branch from e03fe2b to c08d855 Compare August 6, 2026 22:09
@andimarek andimarek changed the title JSpecify gigantic wave 4 Complete JSpecify annotation coverage for public APIs and SPIs Nov 12, 2026
@andimarek
andimarek merged commit 42b4f85 into master Nov 13, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants