refactor (jspecify): roll @NullMarked out to all sub-packages

[adityamparikh]

Summary

Extends JSpecify null-safety enforcement from the single root package org.apache.solr.mcp.server to every sub-package in the codebase — main and test alike.

Before this change, NullAway:OnlyNullMarked=true was silently skipping all production code except the (mostly empty) root package. So the project advertised null-safety but only enforced it on Main.java.

Supersedes #109 and #115 (both now closed) — each was a subset of this rollout:

• fix: add JSpecify @Nullable annotations to SearchService parameters #109 (search package only): the search/package-info.java and SearchService.search parameter annotations are included here.
• fix: add JSpecify @Nullable annotations for accurate null contracts #115 (DTOs + utils + service returns): all Dtos.java, CollectionUtils.get{Long,Float,Integer}, CollectionService cache/handler method returns, and JsonResponseParser.convertValue annotations are included here. (The SolrConfig#useHttp1_1(true) change that rode along with fix: add JSpecify @Nullable annotations for accurate null contracts #115 has already landed separately via fix(solr): force HTTP/1.1 in SolrJ client to avoid flaky H2 EOF #130.)

Changes

1. package-info.java with @NullMarked added to 10 packages (8 main + 2 test-only):

   • main: .collection, .config, .indexing, .indexing.documentcreator, .schema, .search, .security, .util
   • test-only: .containerization, .observability

2. Production code annotated with @Nullable where appropriate, derived from running NullAway:

   • CollectionUtils.getLong/getFloat/getInteger — return null on missing/unparseable keys
   • CollectionService cache/handler metrics methods — return null when the Solr endpoint is unavailable (graceful degradation by design; always the case on Solr 10, where /admin/mbeans was removed)
   • Many Dtos.java record components: SolrMetrics.{cacheStats,handlerStats}, all of CacheStats/CacheInfo/HandlerStats/HandlerInfo, SolrHealthStatus.{errorMessage,responseTime,totalDocuments}, IndexStats.{numDocs,segmentCount}
   • @McpToolParam(required = false) parameters on CollectionService.createCollection and SearchService.search
   • JsonResponseParser.convertValue — JSON null inputs
   • CollectionService.isCacheStatsEmpty — accepts @nullable

3. HttpSecurityConfiguration Spring @Value fields initialised with defaults ("" for issuerUrl matching the property default, List.of() for allowedOrigins) so the analyser can see they are always non-null after construction.

4. NullAway is explicitly disabled on compileTestJava (one-line in build.gradle.kts with explanatory comment).

   • The rollout exposes ~30 test sites that unbox or dereference values now declared @Nullable in production (Map.get returns, optional metric fields, etc.).
   • Each can be tightened by extracting to a local + assertNotNull, but the volume makes test-side cleanup a deliberate follow-up.
   • Production code is fully enforced.

Rebase note

Rebased onto main @ be84c90. Two conflicts arose from upstream changes landing on the exact lines this PR annotates, both resolved in favour of upstream:

• collection/Dtos.java — refactor: remove dead fields and unused FieldStats type #106 removed the dead SolrHealthStatus.solrVersion / status components (so they are no longer annotated here) and refactor: replace mutable Date with Instant in DTO records #113 replaced java.util.Date with java.time.Instant.
• search/SearchService.java — feat(search): document eDisMax local params in search tool description #161 rewrote the q / fq tool-parameter descriptions; those descriptions are kept verbatim, with @Nullable layered on top.

Test plan

• ./gradlew build — full build green after rebase (compile + spotless + unit + integration): 359 tests, 0 failures
• NullAway enforces null safety on all production code
• All 9 main packages verified to have a @NullMarked package-info.java; new files carry the ASF license header required by the RAT check added in feat(build): RAT license-header enforcement as a buildSrc convention plugin (stacked on #138) #150

🤖 Generated with Claude Code

[adityamparikh]

Follow-up stacked on this PR: #179, which marks the six test packages this
one leaves unmarked (server root, collection, config, indexing,
schema, search). Together they take the test tree from 2/8 packages marked
to 8/8, matching what this PR's summary describes as "main and test alike".

No action needed here — #179 is based on this branch, so its diff currently
shows these commits too and will collapse to its own six files once this
merges. Reviewing this one first is the right order.

One correction worth folding in here rather than there, since the line belongs
to this PR: the new build.gradle.kts comment estimates ~30 test sites
behind the compileTestJava disable. Measured on the stacked branch, the
actual count is 48 errors across 14 test files (temporarily replacing the
options.errorprone.disable("NullAway") line and running ./gradlew compileTestJava --rerun-tasks). Same conclusion — still a follow-up, not a
rider — just a bigger follow-up than the comment implies.

[adityamparikh]

Closing as superseded — every part of this PR is already on main (a84033b).

I checked each piece rather than assuming:

1. All 10 package-info.java files exist upstream. Both the 8 main-package ones (collection, config, indexing, indexing.documentcreator, schema, search, security, util) and the 2 test-only ones (containerization, observability) — plus more that landed with #179.

2. The build.gradle.kts change is byte-identical upstream, including the comment. main already has:

option("NullAway:HandleTestAssertionLibraries", "true") // Teach NullAway that JUnit assertNotNull narrows nullness

and the compileTestJava NullAway disable with the same ~30-sites rationale comment this PR wrote.

3. The @Nullable annotations are in place. CollectionUtils, Dtos, JsonResponseParser and HttpSecurityConfiguration are now character-for-character what this branch proposed — 0 differing lines each.

4. Nothing is left over. Diffing this branch against main per file, the only remaining differences are places where the branch is behind: it would revert #166's list-collections remediation hint in CollectionService and reintroduce a non-final local in SearchService. So rebasing it produces either an empty diff or a regression — there is no residue worth keeping.

The one thing here that has not landed and is worth its own issue if anyone wants it: NullAway is still disabled on compileTestJava, so the ~30 test sites that dereference production @Nullable values are still unchecked. That was always scoped as a follow-up in this PR's own comment, and it survives the close.

No action needed — closing.