From 863ee5680b379ce13ea0c54a79ac9d0f0c39a6f8 Mon Sep 17 00:00:00 2001
From: Leon van Zantvoort <zantvoort@beatgridmedia.com>
Date: Wed, 1 Jul 2026 22:15:30 +0200
Subject: [PATCH] ci: fix Java Javadoc aggregate so /api/java deploys

The aggregate report pulled in Kotlin modules (Ktor and the
compiler-plugin variants) that have no module descriptor. Mixing these
unnamed modules with the named Java modules makes javadoc:aggregate fail
with "named and unnamed modules"; because failOnError=false is set, the
step reported success while producing no output, leaving
https://orm.st/api/java a 404.

- Exclude the Kotlin / non-module-path modules from the aggregate (they
  are documented separately as KDoc under /api/kotlin).
- Require index.html in the copy step, so an empty aggregate fails the
  build loudly instead of silently deploying an empty /api/java.
---
 .github/workflows/docs.yml | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ab4b70b18..c37318dbf 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -42,11 +42,18 @@ jobs:
 
       - name: Generate Javadoc (aggregate)
         run: |
+          # The aggregate covers the Java API only. Kotlin modules (Ktor and the
+          # compiler-plugin variants) have no module descriptor; mixing these
+          # "unnamed" modules with the named Java modules makes javadoc:aggregate
+          # fail ("named and unnamed modules"), which — with failOnError=false —
+          # silently produced no output and left /api/java 404. Exclude them here
+          # (Kotlin APIs are documented separately via KDoc under /api/kotlin).
+          # NOTE: add any future storm-compiler-plugin-<kotlin> variant below.
           mvn javadoc:aggregate -q \
             -Dmaven.javadoc.failOnError=false \
             -DadditionalJOption=--enable-preview \
             -Ddoclint=none \
-            -pl '!:storm-kotlin,!:storm-kotlin-spring,!:storm-kotlin-spring-boot-starter,!:storm-kotlinx-serialization,!:storm-metamodel-ksp,!:storm-spring-boot-starter,!:storm-jackson3'
+            -pl '!:storm-kotlin,!:storm-kotlin-spring,!:storm-kotlin-spring-boot-starter,!:storm-kotlinx-serialization,!:storm-metamodel-ksp,!:storm-spring-boot-starter,!:storm-jackson3,!:storm-ktor,!:storm-ktor-test,!:storm-compiler-plugin-2.0,!:storm-compiler-plugin-2.1,!:storm-compiler-plugin-2.2,!:storm-compiler-plugin-2.3,!:storm-compiler-plugin-2.4'
 
       - name: Copy Javadoc to website/static/api/java
         run: |
@@ -54,8 +61,11 @@ jobs:
           # The aggregate report goal writes under the reporting output dir:
           # target/site/apidocs on Maven 3.x, target/reports/apidocs on Maven 4.x.
           copied=""
+          # Require index.html specifically: a failed aggregate can still leave
+          # an empty apidocs dir, and a plain -d check would treat that as success
+          # and deploy an empty /api/java.
           for src in target/site/apidocs target/reports/apidocs; do
-            if [ -d "$src" ]; then
+            if [ -f "$src/index.html" ]; then
               cp -r "$src"/* website/static/api/java/
               copied="$src"
               break