From 492231eb21650129129c9975c58607728a1354b5 Mon Sep 17 00:00:00 2001
From: Leon van Zantvoort <zantvoort@beatgridmedia.com>
Date: Sat, 22 Aug 2026 14:19:06 +0200
Subject: [PATCH 1/4] fix: skip Dokka when the build asks for no javadoc, which
 unbreaks CodeQL

CodeQL's java-kotlin analysis has failed on every build since Dokka moved
to 2.2.0 in the Ktor modules. Its autobuild runs

  mvnw clean package -Dmaven.javadoc.skip -DskipTests ...

and the reactor reaches storm-ktor, where Dokka 2.2.0 loads a Kotlin 2.2
analysis into the Maven JVM, and then storm-kotlin-test, whose kapt runs
on Kotlin 2.0.21. CodeQL's extractor is injected into that compilation as
a compiler plugin and is now bound against the wrong generation:

  The provided plugin com.github.codeql.KotlinExtractorComponentRegistrar
  is not compatible with this version of compiler.
  java.lang.AbstractMethodError: ... does not define or inherit an
  implementation of the resolved method registerProjectComponents ...

The green build before it ran Dokka 2.0.0 at the same point, in the same
order, under the same CodeQL, and the same kapt succeeded.

Dokka is this project's javadoc, so it now honours the switch that says a
build wants none. The scan asked for no documentation and gets none, which
keeps a documentation engine's Kotlin out of the JVM that is compiling
Kotlin. Releases and the docs workflow do not set the property, so they
still produce the javadoc jar Maven Central requires.

Only the two Ktor modules opt in, since they are the only ones whose Dokka
runs a different Kotlin generation than the reactor compiles with.
---
 pom.xml                 | 4 ++++
 storm-ktor-test/pom.xml | 1 +
 storm-ktor/pom.xml      | 1 +
 3 files changed, 6 insertions(+)

diff --git a/pom.xml b/pom.xml
index 42ed5eb2b..d5f6000b0 100644
--- a/pom.xml
+++ b/pom.xml
@@ -25,6 +25,10 @@
         <jacoco.version>0.8.12</jacoco.version>
         <jspecify.version>1.0.1</jspecify.version>
         <spotless.version>2.43.0</spotless.version>
+        <!-- Dokka is this project's javadoc, so the standard switch skips it too: a build that asked for
+             no documentation should not load a documentation engine, let alone a second Kotlin generation
+             into the same JVM as the compiler. -->
+        <maven.javadoc.skip>false</maven.javadoc.skip>
     </properties>
     <groupId>st.orm</groupId>
     <artifactId>storm-framework</artifactId>
diff --git a/storm-ktor-test/pom.xml b/storm-ktor-test/pom.xml
index 83fb6a825..3006f07e2 100644
--- a/storm-ktor-test/pom.xml
+++ b/storm-ktor-test/pom.xml
@@ -149,6 +149,7 @@
                      roots, which include Maven's src/main/java whether it exists or not. Naming the Kotlin root
                      keeps a missing directory from being reported as an error on every build. -->
                 <configuration>
+                    <skip>${maven.javadoc.skip}</skip>
                     <sourceDirectories>
                         <dir>${project.basedir}/src/main/kotlin</dir>
                     </sourceDirectories>
diff --git a/storm-ktor/pom.xml b/storm-ktor/pom.xml
index acf878de8..72c3861e7 100644
--- a/storm-ktor/pom.xml
+++ b/storm-ktor/pom.xml
@@ -177,6 +177,7 @@
                      roots, which include Maven's src/main/java whether it exists or not. Naming the Kotlin root
                      keeps a missing directory from being reported as an error on every build. -->
                 <configuration>
+                    <skip>${maven.javadoc.skip}</skip>
                     <sourceDirectories>
                         <dir>${project.basedir}/src/main/kotlin</dir>
                     </sourceDirectories>

From 3a71c68b5fc673babf636a4a30468739fcd70eb2 Mon Sep 17 00:00:00 2001
From: Leon van Zantvoort <zantvoort@beatgridmedia.com>
Date: Sat, 22 Aug 2026 14:33:43 +0200
Subject: [PATCH 2/4] fix: restore the build configuration CodeQL's Kotlin
 extractor works with

The tidy-up in the previous change broke CodeQL's java-kotlin analysis on
every build since, and skipping Dokka's output was not enough: the mojo
returns early but its plugin realm is still loaded, and the failure
reproduced unchanged. Rather than leave the analysis red while narrowing
which half of that tidy-up is responsible, both halves go back.

The Ktor modules return to Dokka 2.0.0, the generation the rest of the
framework runs, and the three modules that declared the Kotlin plugin as
a build extension declare it that way again. Both carry a comment saying
what they cost and why they stay: Dokka 2.0 reports metadata errors it
cannot read for a Kotlin 2.3 module, and the extension synthesises
duplicate compile and kapt executions.

What stays from the tidy-up is what cannot affect the extractor: Dokka's
source root is still named explicitly, so a module with no src/main/java
does not report a missing directory, and Dokka now honours
maven.javadoc.skip, so a build that asks for no documentation gets none.
---
 storm-kotlin-spring/pom.xml |  4 ++++
 storm-ktor-test/pom.xml     | 12 ++++++++----
 storm-ktor/pom.xml          | 12 ++++++++----
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/storm-kotlin-spring/pom.xml b/storm-kotlin-spring/pom.xml
index d006639d0..317288047 100644
--- a/storm-kotlin-spring/pom.xml
+++ b/storm-kotlin-spring/pom.xml
@@ -74,6 +74,10 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
+                <!-- Contributes the plugin's lifecycle mapping, which also synthesises default-compile and
+                     default-kapt executions beside the ones declared below. That duplication is deliberate for
+                     now: dropping it changed what CodeQL's Kotlin extractor sees and broke its analysis. -->
+                <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
                     <args>
diff --git a/storm-ktor-test/pom.xml b/storm-ktor-test/pom.xml
index 3006f07e2..3114ecf72 100644
--- a/storm-ktor-test/pom.xml
+++ b/storm-ktor-test/pom.xml
@@ -56,6 +56,10 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
+                <!-- Contributes the plugin's lifecycle mapping, which also synthesises default-compile and
+                     default-kapt executions beside the ones declared below. That duplication is deliberate for
+                     now: dropping it changed what CodeQL's Kotlin extractor sees and broke its analysis. -->
+                <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
                     <args>
@@ -141,10 +145,10 @@
             <plugin>
                 <groupId>org.jetbrains.dokka</groupId>
                 <artifactId>dokka-maven-plugin</artifactId>
-                <!-- Dokka 2.0 analyses with a Kotlin 2.0 frontend, which cannot read the Kotlin 2.3 metadata this
-                     module and its stdlib carry; 2.2 can. The rest of the framework stays on 2.0 with its own
-                     compiler generation. -->
-                <version>2.2.0</version>
+                <!-- Pinned to the generation the rest of the framework runs. Dokka 2.2 reads this module's
+                     Kotlin 2.3 metadata, which 2.0 reports errors for, but loading it into the reactor breaks
+                     CodeQL's Kotlin extractor on the next module the reactor compiles at Kotlin 2.0. -->
+                <version>2.0.0</version>
                 <!-- The module has no Java sources, and Dokka's default source roots are the project's compile
                      roots, which include Maven's src/main/java whether it exists or not. Naming the Kotlin root
                      keeps a missing directory from being reported as an error on every build. -->
diff --git a/storm-ktor/pom.xml b/storm-ktor/pom.xml
index 72c3861e7..24e8af9ab 100644
--- a/storm-ktor/pom.xml
+++ b/storm-ktor/pom.xml
@@ -58,6 +58,10 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
+                <!-- Contributes the plugin's lifecycle mapping, which also synthesises default-compile and
+                     default-kapt executions beside the ones declared below. That duplication is deliberate for
+                     now: dropping it changed what CodeQL's Kotlin extractor sees and broke its analysis. -->
+                <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
                     <args>
@@ -169,10 +173,10 @@
             <plugin>
                 <groupId>org.jetbrains.dokka</groupId>
                 <artifactId>dokka-maven-plugin</artifactId>
-                <!-- Dokka 2.0 analyses with a Kotlin 2.0 frontend, which cannot read the Kotlin 2.3 metadata this
-                     module and its stdlib carry; 2.2 can. The rest of the framework stays on 2.0 with its own
-                     compiler generation. -->
-                <version>2.2.0</version>
+                <!-- Pinned to the generation the rest of the framework runs. Dokka 2.2 reads this module's
+                     Kotlin 2.3 metadata, which 2.0 reports errors for, but loading it into the reactor breaks
+                     CodeQL's Kotlin extractor on the next module the reactor compiles at Kotlin 2.0. -->
+                <version>2.0.0</version>
                 <!-- The module has no Java sources, and Dokka's default source roots are the project's compile
                      roots, which include Maven's src/main/java whether it exists or not. Naming the Kotlin root
                      keeps a missing directory from being reported as an error on every build. -->

From b846263d20e306b00fe1f16f0ebeb3c2260e6f62 Mon Sep 17 00:00:00 2001
From: Leon van Zantvoort <zantvoort@beatgridmedia.com>
Date: Sat, 22 Aug 2026 15:32:18 +0200
Subject: [PATCH 3/4] fix: keep the Kotlin plugin extension, which CodeQL's
 extractor depends on

Isolating the two halves of the reverted tidy-up shows Dokka is innocent:
Dokka 2.2.0 with the extension left in place analyses green. So the
extension flag comes back and Dokka 2.2.0 stays, keeping the metadata fix
for the two modules Dokka 2.0 cannot read.

The flag now says why it cannot be removed, since the duplicate compile
and kapt executions it synthesises look like an obvious cleanup and are
not one.
---
 storm-kotlin-spring/pom.xml |  8 +++++---
 storm-ktor-test/pom.xml     | 16 +++++++++-------
 storm-ktor/pom.xml          | 16 +++++++++-------
 3 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/storm-kotlin-spring/pom.xml b/storm-kotlin-spring/pom.xml
index 317288047..6b812b4ee 100644
--- a/storm-kotlin-spring/pom.xml
+++ b/storm-kotlin-spring/pom.xml
@@ -74,9 +74,11 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
-                <!-- Contributes the plugin's lifecycle mapping, which also synthesises default-compile and
-                     default-kapt executions beside the ones declared below. That duplication is deliberate for
-                     now: dropping it changed what CodeQL's Kotlin extractor sees and broke its analysis. -->
+                <!-- Load-bearing beyond this module. It contributes the plugin's lifecycle mapping, which
+                     synthesises default-compile and default-kapt executions beside the ones declared below; the
+                     duplicate compilation looks removable and is not. Without it, CodeQL's Kotlin extractor binds
+                     against the wrong compiler generation and fails the analysis on a later module in the
+                     reactor, with an AbstractMethodError on ComponentRegistrar. Verified both ways. -->
                 <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
diff --git a/storm-ktor-test/pom.xml b/storm-ktor-test/pom.xml
index 3114ecf72..531ae97ca 100644
--- a/storm-ktor-test/pom.xml
+++ b/storm-ktor-test/pom.xml
@@ -56,9 +56,11 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
-                <!-- Contributes the plugin's lifecycle mapping, which also synthesises default-compile and
-                     default-kapt executions beside the ones declared below. That duplication is deliberate for
-                     now: dropping it changed what CodeQL's Kotlin extractor sees and broke its analysis. -->
+                <!-- Load-bearing beyond this module. It contributes the plugin's lifecycle mapping, which
+                     synthesises default-compile and default-kapt executions beside the ones declared below; the
+                     duplicate compilation looks removable and is not. Without it, CodeQL's Kotlin extractor binds
+                     against the wrong compiler generation and fails the analysis on a later module in the
+                     reactor, with an AbstractMethodError on ComponentRegistrar. Verified both ways. -->
                 <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
@@ -145,10 +147,10 @@
             <plugin>
                 <groupId>org.jetbrains.dokka</groupId>
                 <artifactId>dokka-maven-plugin</artifactId>
-                <!-- Pinned to the generation the rest of the framework runs. Dokka 2.2 reads this module's
-                     Kotlin 2.3 metadata, which 2.0 reports errors for, but loading it into the reactor breaks
-                     CodeQL's Kotlin extractor on the next module the reactor compiles at Kotlin 2.0. -->
-                <version>2.0.0</version>
+                <!-- Dokka 2.0 analyses with a Kotlin 2.0 frontend, which cannot read the Kotlin 2.3 metadata this
+                     module and its stdlib carry; 2.2 can. The rest of the framework stays on 2.0 with its own
+                     compiler generation. -->
+                <version>2.2.0</version>
                 <!-- The module has no Java sources, and Dokka's default source roots are the project's compile
                      roots, which include Maven's src/main/java whether it exists or not. Naming the Kotlin root
                      keeps a missing directory from being reported as an error on every build. -->
diff --git a/storm-ktor/pom.xml b/storm-ktor/pom.xml
index 24e8af9ab..8f5c8807c 100644
--- a/storm-ktor/pom.xml
+++ b/storm-ktor/pom.xml
@@ -58,9 +58,11 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
-                <!-- Contributes the plugin's lifecycle mapping, which also synthesises default-compile and
-                     default-kapt executions beside the ones declared below. That duplication is deliberate for
-                     now: dropping it changed what CodeQL's Kotlin extractor sees and broke its analysis. -->
+                <!-- Load-bearing beyond this module. It contributes the plugin's lifecycle mapping, which
+                     synthesises default-compile and default-kapt executions beside the ones declared below; the
+                     duplicate compilation looks removable and is not. Without it, CodeQL's Kotlin extractor binds
+                     against the wrong compiler generation and fails the analysis on a later module in the
+                     reactor, with an AbstractMethodError on ComponentRegistrar. Verified both ways. -->
                 <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
@@ -173,10 +175,10 @@
             <plugin>
                 <groupId>org.jetbrains.dokka</groupId>
                 <artifactId>dokka-maven-plugin</artifactId>
-                <!-- Pinned to the generation the rest of the framework runs. Dokka 2.2 reads this module's
-                     Kotlin 2.3 metadata, which 2.0 reports errors for, but loading it into the reactor breaks
-                     CodeQL's Kotlin extractor on the next module the reactor compiles at Kotlin 2.0. -->
-                <version>2.0.0</version>
+                <!-- Dokka 2.0 analyses with a Kotlin 2.0 frontend, which cannot read the Kotlin 2.3 metadata this
+                     module and its stdlib carry; 2.2 can. The rest of the framework stays on 2.0 with its own
+                     compiler generation. -->
+                <version>2.2.0</version>
                 <!-- The module has no Java sources, and Dokka's default source roots are the project's compile
                      roots, which include Maven's src/main/java whether it exists or not. Naming the Kotlin root
                      keeps a missing directory from being reported as an error on every build. -->

From 8d9df7d22f960c3536cb9b47f61bcdb60a693d9c Mon Sep 17 00:00:00 2001
From: Leon van Zantvoort <zantvoort@beatgridmedia.com>
Date: Sat, 22 Aug 2026 21:11:57 +0200
Subject: [PATCH 4/4] docs: state the Kotlin plugin extension constraint
 plainly in the poms

---
 storm-kotlin-spring/pom.xml | 10 +++++-----
 storm-ktor-test/pom.xml     | 10 +++++-----
 storm-ktor/pom.xml          | 10 +++++-----
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/storm-kotlin-spring/pom.xml b/storm-kotlin-spring/pom.xml
index 6b812b4ee..684a5cfc5 100644
--- a/storm-kotlin-spring/pom.xml
+++ b/storm-kotlin-spring/pom.xml
@@ -74,11 +74,11 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
-                <!-- Load-bearing beyond this module. It contributes the plugin's lifecycle mapping, which
-                     synthesises default-compile and default-kapt executions beside the ones declared below; the
-                     duplicate compilation looks removable and is not. Without it, CodeQL's Kotlin extractor binds
-                     against the wrong compiler generation and fails the analysis on a later module in the
-                     reactor, with an AbstractMethodError on ComponentRegistrar. Verified both ways. -->
+                <!-- Contributes the plugin's lifecycle mapping, which synthesises default-compile and
+                     default-kapt executions beside the ones declared below. The duplicate compilation is what
+                     this flag costs, and the flag has to stay: without it, CodeQL's Kotlin extractor binds
+                     against the wrong compiler generation and fails its analysis on a later module in the
+                     reactor, with an AbstractMethodError on ComponentRegistrar. -->
                 <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
diff --git a/storm-ktor-test/pom.xml b/storm-ktor-test/pom.xml
index 531ae97ca..0a9a19412 100644
--- a/storm-ktor-test/pom.xml
+++ b/storm-ktor-test/pom.xml
@@ -56,11 +56,11 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
-                <!-- Load-bearing beyond this module. It contributes the plugin's lifecycle mapping, which
-                     synthesises default-compile and default-kapt executions beside the ones declared below; the
-                     duplicate compilation looks removable and is not. Without it, CodeQL's Kotlin extractor binds
-                     against the wrong compiler generation and fails the analysis on a later module in the
-                     reactor, with an AbstractMethodError on ComponentRegistrar. Verified both ways. -->
+                <!-- Contributes the plugin's lifecycle mapping, which synthesises default-compile and
+                     default-kapt executions beside the ones declared below. The duplicate compilation is what
+                     this flag costs, and the flag has to stay: without it, CodeQL's Kotlin extractor binds
+                     against the wrong compiler generation and fails its analysis on a later module in the
+                     reactor, with an AbstractMethodError on ComponentRegistrar. -->
                 <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>
diff --git a/storm-ktor/pom.xml b/storm-ktor/pom.xml
index 8f5c8807c..caa863a8f 100644
--- a/storm-ktor/pom.xml
+++ b/storm-ktor/pom.xml
@@ -58,11 +58,11 @@
                 <groupId>org.jetbrains.kotlin</groupId>
                 <artifactId>kotlin-maven-plugin</artifactId>
                 <version>${kotlin.version}</version>
-                <!-- Load-bearing beyond this module. It contributes the plugin's lifecycle mapping, which
-                     synthesises default-compile and default-kapt executions beside the ones declared below; the
-                     duplicate compilation looks removable and is not. Without it, CodeQL's Kotlin extractor binds
-                     against the wrong compiler generation and fails the analysis on a later module in the
-                     reactor, with an AbstractMethodError on ComponentRegistrar. Verified both ways. -->
+                <!-- Contributes the plugin's lifecycle mapping, which synthesises default-compile and
+                     default-kapt executions beside the ones declared below. The duplicate compilation is what
+                     this flag costs, and the flag has to stay: without it, CodeQL's Kotlin extractor binds
+                     against the wrong compiler generation and fails its analysis on a later module in the
+                     reactor, with an AbstractMethodError on ComponentRegistrar. -->
                 <extensions>true</extensions>
                 <configuration>
                     <jvmTarget>21</jvmTarget>