test(ci): sweep every module's effective javadoc config for silencers (#203)

.github/workflows/ci.yml

@@ -149,6 +149,25 @@ jobs:
 
           echo "javadoc strictness confirmed: the poisoned build failed with 'error: reference not found'"
 
+      # The canary above only poisons rift-java-core, so it pins the ROOT pluginManagement. A
+      # per-module <failOnError>false</failOnError> in some other module leaves it — and the main
+      # release build — green while that module ships broken javadoc to Central (#203). This sweeps
+      # the effective pom of EVERY module in the release reactor for the known silencers. Same flags
+      # as the main step, so the reactor inspected is the one that actually publishes.
+      - name: Javadoc strictness across all modules (effective-pom sweep)
+        run: |
+          set -euo pipefail
+          EFF=$(mktemp)
+          trap 'rm -f "$EFF"' EXIT
+          # Prove the detector still detects before trusting a clean sweep: a checker edit that
+          # stopped flagging anything would otherwise report "confirmed" forever.
+          python3 scripts/check-javadoc-strictness.py --self-test
+          ./mvnw -B -ntp -Prelease,natives-bundle -DdualEmbedded help:effective-pom -Doutput="$EFF"
+          # --require names the modules this JDK-21 + -DdualEmbedded reactor must contain, so a
+          # module silently dropping out of the reactor fails the sweep instead of shrinking it.
+          python3 scripts/check-javadoc-strictness.py "$EFF" --require \
+            rift-java-parent,rift-java-core,rift-java-jackson,rift-java-junit5,rift-java-natives,rift-java-spring,rift-java-testcontainers,rift-java-conformance,rift-java-bom,rift-java-embedded,rift-java-embedded-jdk21
+
   # The Docker-enabled lane for rift-java-testcontainers: RIFT_IT=1 un-gates the RiftContainer
   # round-trip ITs (they self-skip everywhere else). ubuntu-latest runners ship a Docker daemon.
   testcontainers-it:

.gitignore

@@ -28,3 +28,7 @@ native-local/
 
 # MkDocs build output
 site/
+
+# Bytecode from scripts/*.py (the javadoc-strictness sweep)
+__pycache__/
+*.pyc

CONTRIBUTING.md

@@ -46,13 +46,38 @@ both; release-smoke covers them on every PR.
 
 Missing-tag warnings (`no @param`, `no @return`) are *not* errors and do not fail the build.
 
-That strictness is itself guarded. A clean build cannot distinguish "strict and clean" from
-"permissive and clean", so release-smoke runs a canary step that injects a broken `{@link}` into
-`Rift.java` and fails the job if the release-lane build *succeeds* — re-adding `failOnError=false`,
-`doclint=none`, or any other silencer cannot slip through unnoticed. The step reverts its own edit.
-One maintenance note: it anchors on the phrase `admin API.` in `Rift.java`'s opening javadoc
-sentence, so if you reword that sentence, update the anchor in `.github/workflows/ci.yml`. The step
-fails loudly and says so when the anchor stops matching.
+That strictness is itself guarded, by two complementary release-smoke steps. A clean build cannot
+distinguish "strict and clean" from "permissive and clean", so neither step trusts a green build.
+
+**The canary** injects a broken `{@link}` into `Rift.java` and fails the job if the release-lane
+build *succeeds*. It proves the *behaviour* — that a bad reference really is fatal — and reverts its
+own edit. One maintenance note: it anchors on the phrase `admin API.` in `Rift.java`'s opening
+javadoc sentence, so if you reword that sentence, update the anchor in `.github/workflows/ci.yml`.
+The step fails loudly and says so when the anchor stops matching.
+
+**The effective-pom sweep** (`scripts/check-javadoc-strictness.py`) covers what the canary cannot:
+the canary poisons only `rift-java-core`, so it pins the root `pluginManagement`, and a per-module
+override elsewhere would leave it green. The sweep runs `help:effective-pom` over the release
+reactor and rejects any module whose *effective* javadoc config silences errors — `failOnError`,
+`skip`, `skippedModules`, a `doclint` value other than `all`, an `-Xdoclint` option that disables a
+group, or the equivalent `maven.javadoc.*` / `doclint` **properties**, which need no `<configuration>`
+at all. Run it locally with:
+
+```sh
+# -DdualEmbedded matches CI, so the sweep covers rift-java-embedded too
+./mvnw -Prelease,natives-bundle -DdualEmbedded help:effective-pom -Doutput=/tmp/eff.xml
+python3 scripts/check-javadoc-strictness.py /tmp/eff.xml
+python3 scripts/check-javadoc-strictness.py --self-test   # asserts the detector still detects
+```
+
+The module set depends on your JDK (`rift-java-embedded-jdk21` only joins on JDK 21), so a local run
+sweeps fewer modules than CI — pass `--require` only if you know which set to expect.
+
+Two things it deliberately does *not* do: it reads configuration, not behaviour (that is the
+canary's job), and it cannot see a `-Dmaven.javadoc.failOnError=false` added to a workflow's own
+`mvn` command line. Its `--require` list in `ci.yml` names the modules the reactor must contain, so
+a module dropping out of the reactor fails the sweep instead of silently shrinking it — add new
+published modules there.
 
 ## Module layout
 

pom.xml

@@ -70,6 +70,7 @@
     <exec-maven-plugin.version>3.5.0</exec-maven-plugin.version>
     <flatten-maven-plugin.version>1.6.0</flatten-maven-plugin.version>
     <maven-invoker-plugin.version>3.8.0</maven-invoker-plugin.version>
+    <maven-help-plugin.version>3.5.2</maven-help-plugin.version>
     <build-helper-maven-plugin.version>3.6.0</build-helper-maven-plugin.version>
   </properties>
 
@@ -137,6 +138,14 @@
           <artifactId>maven-javadoc-plugin</artifactId>
           <version>${maven-javadoc-plugin.version}</version>
         </plugin>
+        <!-- Not bound to any phase: CI's javadoc-strictness sweep invokes help:effective-pom by
+             goal prefix (#203). Prefix-invoked goals otherwise resolve whatever is newest on Central
+             at run time, so pinning keeps the sweep reproducible. -->
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-help-plugin</artifactId>
+          <version>${maven-help-plugin.version}</version>
+        </plugin>
       </plugins>
     </pluginManagement>
   </build>