chore: MXTS-77488: build microdocs on gradle 9.6.1 / jdk 25 and cut 5.0.0

[mxt-nilesh-wani]

Summary

buildMicroDocs fails on every Gradle 9 repo today. This fixes it and rebuilds the
plugin for JDK 25, cut as 5.0.0.

Two independent Gradle 9 breakages, both in MicroDocs.groovy (fbc6c56):

• Gradle 9 made Javadoc's service-injection getters abstract, so a concrete
  subclass no longer compiles -> abstract class MicroDocs.
• Groovy 4 no longer resolves the Groovy-3-compiled dynamic super-dispatch to
  protected Javadoc.generate() -> @CompileStatic (with a CoreJavadocOptions
  cast, since getOptions() is declared to return MinimalJavadocOptions).

Then all three modules moved to Gradle 9.6.1 / JDK 25, with microdocs-core-java
and microdocs-crawler-gradle on maxxton-conventions 5.0.0-RC-3, and all three
cut to 5.0.0 in lockstep.

Consumer requirement (please read)

microdocs 5.0.0 requires the consuming build's Gradle daemon JVM AND javadoc
toolchain to be JDK 25+. The plugin's bytecode moves from major 52 to major 69.

This is deliberate. The major version bump is what gates adoption:
config-server pins microdocs_version=4.+, which cannot resolve 5.0.0, so the
JDK 21 consumers stay safely on 4.0.2. Note that maxxton-conventions sets the
toolchain, not the daemon JVM, so "consumer is on RC-3" does not imply its daemon
is 25 -- a consumer whose JAVA_HOME is still 21 fails at plugin-apply.

This ships to nobody until two follow-ups land

1. 5.0.0 is not published. This PR is source changes only.
2. The catalog is not bumped -- maxxton-version-catalog/gradle/libs.versions.toml:15
   still pins microdocs = "4.0.2" exactly, at every tag through v5.0.0.

Notable decisions

• The doclet deliberately does NOT adopt the convention plugin. RC-3 sets
  archiveBaseName to "app" on every Jar task, which would rename the fat jar and
  break the microdocs-crawler-doclet-all-*.jar glob at publish.sh:18. It gets an
  explicit JDK 25 toolchain instead.
• microdocs-crawler-gradle gains mavenLocal() and a regenerated gradle.lockfile,
  since both siblings now compile against microdocs-core-java:5.0.0, which does not
  exist in the registry until the publish above.
• No API drift surfaced repointing core-java 3.0.0 -> 5.0.0; no source changes needed.

Verification

No new unit tests -- build-configuration change with no behavioural code (these
modules have no test sources). Instead:

• Clean, non-cached build of all three modules -- all BUILD SUCCESSFUL.
• Bytecode assertions: major 69 on MicroDocsCrawlerPlugin, MicroDocs,
  DocletRunner, and core-java's Project.
• publish.sh embed step simulated -- the doclet glob matches exactly one file.
• End-to-end: buildMicroDocs green in reallocation-engine-service on JDK 25
  against the locally-published 5.0.0.

Known pre-existing issues (not addressed here)

• MicroDocsCrawlerPlugin reads project.sourceSets eagerly at apply time, so it
  must be declared after java/java-library in a consumer's plugins {} block.
• project.buildDir and the archives configuration are Gradle-10 removal candidates.
• ~100 javadoc warnings in microdocs-core-java.

Ticket: MXTS-77488

[Copilot]

Pull request overview

This PR updates the MicroDocs Gradle plugin and its companion modules to build successfully on Gradle 9.6.1 with JDK 25, and aligns all module versions to 5.0.0 as part of the major-version/JDK-baseline bump.

Changes:

• Fix MicroDocs Javadoc task subclassing for Gradle 9 + Groovy 4 (abstract class + @CompileStatic with CoreJavadocOptions cast).
• Upgrade Gradle wrappers to 9.6.1 (including wrapper scripts and distributionSha256Sum) across modules.
• Bump module versions/dependencies to 5.0.0 and update conventions plugin usage where applicable (plus local-resolution support for the unpublished core artifact).

Reviewed changes

Copilot reviewed 16 out of 19 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
microdocs-crawler-gradle/src/main/groovy/com/maxxton/microdocs/crawler/gradle/tasks/MicroDocs.groovy	Makes the custom Javadoc task compatible with Gradle 9/Groovy 4.
microdocs-crawler-gradle/gradlew.bat	Updates Gradle wrapper Windows script to Gradle 9 template.
microdocs-crawler-gradle/gradlew	Updates Gradle wrapper POSIX script to Gradle 9 template.
microdocs-crawler-gradle/gradle/wrapper/gradle-wrapper.properties	Bumps wrapper to Gradle 9.6.1 and adds SHA256 verification.
microdocs-crawler-gradle/gradle.properties	Bumps module version to 5.0.0.
microdocs-crawler-gradle/gradle.lockfile	Regenerates dependency lockfile for the new core dependency version.
microdocs-crawler-gradle/build.gradle	Updates conventions plugin version, adds mavenLocal(), bumps core dependency to 5.0.0.
microdocs-crawler-doclet/gradlew.bat	Updates Gradle wrapper Windows script to Gradle 9 template.
microdocs-crawler-doclet/gradlew	Updates Gradle wrapper POSIX script to Gradle 9 template.
microdocs-crawler-doclet/gradle/wrapper/gradle-wrapper.properties	Bumps wrapper to Gradle 9.6.1 and adds SHA256 verification.
microdocs-crawler-doclet/build.gradle	Bumps to 5.0.0 and sets a JDK 25 toolchain explicitly for the doclet build.
microdocs-core-java/gradlew.bat	Updates Gradle wrapper Windows script to Gradle 9 template.
microdocs-core-java/gradlew	Updates Gradle wrapper POSIX script to Gradle 9 template.
microdocs-core-java/gradle/wrapper/gradle-wrapper.properties	Bumps wrapper to Gradle 9.6.1 and adds SHA256 verification.
microdocs-core-java/gradle.properties	Bumps module version to 5.0.0.
microdocs-core-java/build.gradle	Updates conventions plugin version for the Gradle 9/JDK 25 baseline.

Suppressed comments (1)

microdocs-crawler-gradle/build.gradle:20

• mavenLocal() is currently the first repository. That makes dependency resolution non-reproducible (local artifacts can silently override the intended published ones) and can lead to CI/dev differences. Since the only reason to include it here is to pick up the unpublished com.maxxton:microdocs-core-java:5.0.0, it can be placed last without breaking that use case.

repositories {
  mavenLocal()
  mavenCentral()
  maven {
    url "artifactregistry://europe-maven.pkg.dev/dynamic-concept-192711/maxxton-maven-registry"
  }
}

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 19 changed files in this pull request and generated no new comments.

Suppressed comments (6)

Previously missed (3) — in code that hasn't changed since the last review.

microdocs-crawler-gradle/gradlew.bat:54

• This early error path does not actually stop the script. "%COMSPEC%" /c exit 1 only sets ERRORLEVEL in a child cmd and then execution falls through into :findJavaFromJavaHome / :execute, which can lead to confusing follow-on errors (and may even attempt to run with an empty JAVA_EXE). Use a batch-exit (exit /b 1) or goto :eof here.

This issue also appears on line 68 of the same file.

"%COMSPEC%" /c exit 1

microdocs-crawler-doclet/gradlew.bat:54

• This early error path does not actually stop the script. "%COMSPEC%" /c exit 1 exits only the child cmd and then the batch continues into :findJavaFromJavaHome / :execute, potentially attempting to run with an invalid JAVA_EXE. Use exit /b 1 (or goto :eof) to stop execution here.

This issue also appears on line 68 of the same file.

"%COMSPEC%" /c exit 1

microdocs-core-java/gradlew.bat:54

• This early error path does not stop the script. "%COMSPEC%" /c exit 1 runs in a child process and then the batch falls through into :findJavaFromJavaHome / :execute, which can cause misleading follow-on errors. Use exit /b 1 (or goto :eof) here to terminate the batch immediately.

This issue also appears on line 68 of the same file.

"%COMSPEC%" /c exit 1

microdocs-crawler-gradle/gradlew.bat:68

• Same as above: this error path falls through to :execute after setting ERRORLEVEL in a child cmd. It should exit the batch file immediately to avoid attempting to run Gradle with an invalid JAVA_EXE.

"%COMSPEC%" /c exit 1

microdocs-crawler-doclet/gradlew.bat:68

• Same fall-through issue here: "%COMSPEC%" /c exit 1 doesn't exit the batch file, so execution continues to :execute. Replace with exit /b 1 to stop immediately on invalid JAVA_HOME.

"%COMSPEC%" /c exit 1

microdocs-core-java/gradlew.bat:68

• Same fall-through issue: this error path should exit the batch file immediately. As written, it continues to :execute after launching a child cmd. Replace with exit /b 1.

"%COMSPEC%" /c exit 1