guicedee-jpms-shade

# GuicedEE JPMS Shade

Turn an automatic-module dependency into a proper, named JPMS module published as a
`com.guicedee.modules.services` artifact, then make the consuming GuicedEE module require the
shaded module instead of the automatic one. This yields a clean `jlink` image (no automatic
modules on the module path).

## When This Applies
- A GuicedEE module `requires <some.automatic.module>` that resolves to a plain JAR.
- `jlink` / `jpms` rejects or warns about automatic modules.
- Goal: a fully-named module graph for a reliable runtime image.

## Inputs To Gather First
1. The upstream coordinates and resolved version (e.g. `com.graphql-java:graphql-java:26.0`).
   Resolve the EXACT version the parent already pulls (check the dependency's own POM, the BOM
   that imports it, or `mvn dependency:tree`). Pin to that version — do not guess.
2. The **module name** the JAR advertises. Read it from the JAR manifest
   `Automatic-Module-Name`; if absent, derive a stable name from the root package.
   See `references/inspect-jar.md` for ready-to-run commands to read the manifest and enumerate
   packages (needed for accurate `exports`).
3. The dependency's own external module dependencies (its compile deps that are NOT already
   bundled/relocated inside the JAR). Each becomes a `requires` in the module-info.
   Annotation-only deps (jspecify, jsr305, checker, error_prone) become `requires static`.

> Many libraries already relocate their transitives internally (e.g. graphql-java bundles ANTLR
> and Guava under `graphql.*`). Inspect the package list — only NON-relocated, externally-visible
> dependencies need a `requires`.

## Workflow

### 1. Create the shade module
Create `GuicedEE/services/Libraries/<artifactId>/` (mirror the `json` / `kafka-client` modules):
- `pom.xml` — parent `com.guicedee:parent`, groupId `com.guicedee.modules.services`, the shade
  `artifactSet` pinned to the single upstream artifact, and the standard plugin chain
  (shade → antrun → moditect → flatten → copy-rename → javadoc). Exclude transitives that you
  re-add as their own proper modules.
- `src/moditect/module-info.java` — the named module descriptor.

Use the exact templates in `references/templates.md`.

### 2. Write the moditect module-info
- `module <module-name> { ... }` using the manifest's Automatic-Module-Name.
- `exports` every public package found in the JAR EXCEPT internally-relocated/shaded packages
  (e.g. `*.com.google.*`, `*.org.antlr.*`).
- `requires transitive` for deps whose types appear in the exported API (e.g. `org.reactivestreams`).
- `requires static` for annotation-only deps.
- Add `provides ... with ...` for any `META-INF/services` the JAR ships (the SPI needs explicit
  `provides` in the descriptor, even though the shade keeps the service files).

### 3. Register versions and BOMs
- `GuicedEE/bom/Versioner/pom.xml` — add `<...version>` properties for the upstream artifact(s).
- `GuicedEE/bom/StandaloneBOM/pom.xml` — `dependencyManagement` for the UPSTREAM artifacts (so the
  shade module's `pom.xml` and its exclusions resolve versions).
- `GuicedEE/bom/pom.xml` (guicedee-bom) — `dependencyManagement` for the new
  `com.guicedee.modules.services:<artifactId>` at `${guicedee.version}` (so consumers omit versions).

### 4. Register in the dev-suite build (the "workflows")
- Root `DevSuite/pom.xml` → `services` profile `<modules>` list. This is the module list the
  dev-suite GitHub workflows build/deploy; the reusable workflows in `GuicedEE/workflows` are generic
  templates and do NOT enumerate modules. Each shade also ships as its own GitHub repo that calls the
  reusable `Projects Builder` workflow — mention this to the user, but it is created outside DevSuite.
- Optionally document the mapping table in `GuicedEE/services/services.md`.

### 5. Rewire the consuming module
In the GuicedEE module that used the automatic module:
- Exclude the upstream automatic artifact(s) from whatever transitively brought them in
  (e.g. exclude `com.graphql-java:graphql-java` from `io.vertx:vertx-web-graphql`).
- Add a dependency on the new `com.guicedee.modules.services:<artifactId>`.
- The consumer's `module-info.java` usually needs **no change**: the shaded module keeps the same
  module name, so `requires <module-name>` already resolves — now to a real named module.

### 6. Validate
Install the updated BOMs first (they are SNAPSHOTs the shade module imports), then build:
```
mvn -B -N install        # in Versioner, then StandaloneBOM, then GuicedEE/bom
mvn -B install -DskipTests -Dmaven.javadoc.skip=true   # in each new shade module
jar --describe-module --file target/<artifactId>-<ver>.jar   # confirm requires/exports
mvn -B -o clean compile  # in the consumer module — must compile on the module path
```
Confirm `jar --describe-module` shows the expected named module with correct `requires`/`exports`,
and that the consumer compiles with `[debug release N module-path]`.

## Pitfalls
- **Build env (Windows)**: the repo `mvnw` wrapper may be broken; a system Maven 4
  (`C:\Software\maven4`) + `JAVA_HOME=c:\software\jdk\25` works. Chain PowerShell commands with `;`.
- **Relocated deps need explicit `requires` for JDK modules.** When a library internally relocates
  its dependencies (e.g. graphql-java bundles Guava under `graphql.com.google.*` and ANTLR under
  `graphql.org.antlr.*`), those classes still use JDK APIs such as `java.util.logging`. As an
  *automatic* module the jar implicitly read every module, so it worked; as a *named* module it only
  reads what it `requires`. Missing ones surface at RUNTIME, not compile time, as
  `IllegalAccessError: class X (in module M) cannot access class Y (in module java.logging) because
  module M does not read module java.logging`. Add the JDK module (e.g. `requires java.logging;`).
  Compile + `jar --describe-module` will NOT catch this — only running the code does. Always run the
  consumer's integration tests after a shade.
- **Missing version errors** in the shade module mean the updated StandaloneBOM was not installed yet.
- **Split packages**: never let the shaded module and a separately-required module both export the
  same package — exclude the transitive from one side.
- **Don't export relocated internals** — they are implementation detail and break encapsulation.

## References
- `references/templates.md` — copy-paste `pom.xml` and `module-info.java` templates + BOM snippets.
- `references/inspect-jar.md` — PowerShell snippets to read the manifest module name and package list.
- `references/worked-example.md` — the graphql-java + java-dataloader case, end to end.