Javadoc CI fails when downstream project shares package namespace with dependency

[carlosuc3m]

TLDR
Maven project depending on another project that shares the package namespace ai.nets.samj.* makes scijava ci-build.sh fail during maven-javadoc-plugin:jar (attach-javadocs) because dependency with same namespace seems to be missing

Summary

In SAMJ-IJ, the normal GitHub CI build fails during maven-javadoc-plugin:jar (attach-javadocs) with missing symbols from dependency ai.nets:samj:0.0.4, even though Maven resolves that dependency correctly and the project compiles.

The failure only appears in the normal CI lifecycle path run via scijava-scripts/build.sh, not in a simpler direct mvn javadoc:jar debug path.

Link to a failed run: https://github.com/segment-anything-models-java/SAMJ-IJ/actions/runs/23507953635/job/68420905158

Observed failure

Javadoc reports missing packages/classes from the samj dependency, e.g.:

• package ai.nets.samj.annotation does not exist
• package ai.nets.samj.gui.components does not exist
• package ai.nets.samj.models does not exist
• package ai.nets.samj.ui does not exist

Affected source examples:

• ai.nets.samj.annotation.Mask
• ai.nets.samj.ui.ConsumerInterface
• ai.nets.samj.communication.model.SAMModel

What I verified

1. Maven dependency resolution is fine on CI.
   dependency:build-classpath includes:
   /home/runner/.m2/repository/ai/nets/samj/0.0.4/samj-0.0.4.jar

2. The samj jar is physically present in ~/.m2 on CI.

3. The project compiles successfully before the Javadoc failure.

4. The failure is reproducible locally if samj-0.0.4.jar is manually removed from the generated Javadoc command classpath.

5. The failing CI Javadoc invocation is not using normal classpath mode.
   The generated target/reports/apidocs/options contains:

• --add-modules ALL-MODULE-PATH
• --module-path ...
• --patch-module ai.nets.samj=...

and notably does not contain samj-0.0.4.jar.

Key finding

There is a discrepancy between:

• Maven’s resolved build classpath (cp.txt), which includes samj-0.0.4.jar
• the generated Javadoc command options for attach-javadocs, which omit samj-0.0.4.jar

So the issue is not dependency resolution in general; it is the Javadoc plugin invocation generated in the normal lifecycle.

Why this seems to happen

SAMJ-IJ depends on ai.nets:samj, and both use the ai.nets.samj.* namespace.

During CI, the Javadoc plugin appears to switch to Java 9+ modular mode and treats the current project as module ai.nets.samj, using:

--patch-module ai.nets.samj=...

In that mode, the external samj jar is omitted from the generated Javadoc inputs, which makes all ai.nets.samj.* imported dependency types unresolved.

Why this is not a library artifact problem

• SAMJ itself builds successfully
• samj-0.0.4.jar resolves and exists on CI
• the jar is on the Maven dependency classpath
• only the generated Javadoc command in the normal lifecycle loses it

Minimal reproduction pattern

Downstream project:

• depends on external artifact ai.nets:samj
• also uses ai.nets.samj.* package root in its own sources
• CI build runs maven-javadoc-plugin:jar in lifecycle/attach phase
• generated modular Javadoc invocation drops the dependency jar

Workaround

Adding explicit Javadoc plugin config in downstream pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <legacyMode>true</legacyMode>
  </configuration>
</plugin>

This is being tested as a workaround to force classic classpath-based Javadoc generation and avoid the broken modular invocation.

Files / evidence

From CI debug artifacts:

• cp.txt includes samj-0.0.4.jar
• target/reports/apidocs/options omits it and uses module-path mode
• mvn-log shows failure only at attach-javadocs

Question

Is this a known issue/interaction in the SciJava CI build path or inherited Maven Javadoc configuration, where attach-javadocs switches to modular mode and drops dependency jars when the downstream project shares the dependency’s package/module namespace?