Stop bundling third-party code in the IntelliJ uber JARs

[alexander-yevsyukov]

Why

In delivery-server, jibDockerBuild failed with a NoSuchMethodError in commons-compress: the intellij-platform fat JAR bundles 575 packages of unrelocated third-party classes (Guava 31, commons-compress 1.21, Caffeine, Netty, …) that reach consumers' buildscript classpaths and shadow genuine artifacts by classloader order. No version constraint or BOM can fix it — the shaded copies are not dependencies, they are bytecode inside another artifact. See .agents/tasks/unshade-intellij-platform-third-party.md for the full incident analysis.

What

A single shading policy (buildSrc/.../shade/IntelliJUberJar.kt) applied identically to intellij-platform and intellij-platform-java (they form a layered pair — the java JAR subtracts the platform JAR's contents at build time):

• Include filter: only JetBrains groups (com.jetbrains.intellij*, org.jetbrains.intellij*) are shaded.
• Central artifacts → POM dependencies: everything else is declared in the published POM instead of bundled — intellij-platform 20 runtime entries, intellij-platform-java 84 (83 runtime third-party plus the sibling intellij-platform at compile scope, since the java JAR's classes extend platform types it deliberately does not contain). Consumers now upgrade e.g. commons-compress by normal Gradle conflict resolution — precisely the fix for the Jib incident.
• JetBrains forks → relocated under io.spine.tools.ij: jdom, log4j, trove4j, fastutil, Batik, ion-java, commons-imaging. Exceptions: JNA is excluded outright and jcef stays unrelocated (their natives bind JNI entry points to literal class names); self-namespaced forks (asm-all, jb-jdi, …) are shaded as is.
• Dropped entirely — machinery never exercised by headless PSI, so neither shaded nor declared: pty4j, purejavacomm, jediterm, winp (OS/terminal integration, replacing the incomplete per-file exclude patterns), and the BouncyCastle stack plus marketplace-zip-signer (remote-development and plugin-signing crypto — see below).
• The java module's subtraction filter reverse-maps Shadow's transforms (relocated paths, renamed service files, .shadow.kotlin_module) via sourceFormOf, so nothing duplicates across the pair.

Result: intellij-platform 25.8 → 17.4 MB, intellij-platform-java 115.1 → 78.6 MB.

The published POM resolves conflict-free

Replacing a dependency-less POM with an 84-entry one moves work onto consumers unless the entries are curated, so three problems found downstream were fixed in this PR after the first review round:

1. Entries are published non-transitive. Each declared entry initially carried its own transitive graph, re-requesting commons-*, kotlin-*, annotations, and objenesis at the version that entry was built against rather than the resolved version pinned here — 10 conflicting modules for a bare consumer under failOnVersionConflict(), forcing boilerplate the old dependency-less POM never required. Every entry now carries a wildcard <exclusions> block. The declared list is already the complete flattened runtime closure (each entry's transitives are themselves entries), so nothing is lost, every module is requested at exactly one version, and the POM resolves with zero conflicts and no consumer-side forces. The curation also becomes authoritative — Slf4J, the Kotlin runtime, and the dropped groups cannot re-enter through an entry's own POM. Consumers still upgrade any entry by ordinary resolution, so the commons-compress fix is preserved.

2. Pins align with the Spine stack. With entries non-transitive, the remaining conflict source is a pin that disagrees with the consumer's own graph. core-jvm-compiler/tests (strict resolution) surfaced Jackson 2.13.0 and Caffeine 3.0.4 — the versions the IJ-213 POMs request, which stood because this repo never forced these families. uber-jar-module now forces the Jackson family and Caffeine in the uber modules' resolution, so the published pins are the versions this repository is built and tested with (2.22.1/2.22, 3.2.4), the same treatment Guava already receives from forceVersions().

3. The BouncyCastle clash. core-jvm-compiler's integration tests hit Conflict found for module 'org.bouncycastle:bcprov-jdk15on': between versions 1.69 and 1.64 against the .410 POM: ide-impl reaches BouncyCastle by two disagreeing paths — bcpg-jdk15on:1.69 (via remote-dev-util) wants bcprov:1.69, while marketplace-zip-signer:0.1.3 wants bcpkix:1.64 → bcprov:1.64. Neither bcprov nor bcpkix is on this repo's runtime classpath, so the clash was invisible here and surfaced only in consumers, which re-resolve each declared entry's own POM. Both entry points are remote-dev and plugin-signing machinery, so dropping them removes the cryptography surface entirely rather than merely aligning versions. POM entries 86 → 84; org.jetbrains:annotations and annotations-java5 verified to survive the artifact-level drop.

Verification

• Full ./gradlew build dokkaGenerate green; psi / psi-java suites: 148 tests pass against the relocated JARs.
• Both POMs regenerated and inspected: 20 and 84 entries, every one carrying the wildcard exclusion; aligned pins (Jackson 2.22.1, Caffeine 3.2.4, Guava 33.6.0-jre) present as published values.
• All 83 distinct third-party POM entries across both modules verified present on Maven Central (blockmap, which is absent from Central, is shaded instead).
• JAR entry listings diffed at every step and byte-identical across the dependency-alignment change; cross-JAR duplicates reduced to META-INF/MANIFEST.MF only. The two non-IJ uber modules (jvm-tool-plugins, protobuf-setup-plugins) are unaffected by the shared forcing block.
• IntelliJUberJarSpec (8 tests) covers the pure policy logic — group filtering, per-artifact drops, and all three sourceFormOf reversals.
• End-to-end consumer proof: a scratch Gradle project resolving io.spine.tools:intellij-platform-java:2.0.0-SNAPSHOT.410 from Maven Local gets 85 artifacts (uber JAR + the sibling at compile scope + all 83 third-party, with commons-compress:1.21, guava:33.6.0-jre, jackson-databind:2.22.1 as pinned), and resolves conflict-free under failOnVersionConflict() with no consumer-side forces.
• Pre-PR reviewer round: spine-code-review, kotlin-engineer, review-docs, dependency-audit, gradle-review — all APPROVE after fixes (tests added, KDoc link repaired, CC-hardening of the subtraction task wiring). Codex's compile-scope finding is fixed and resolved.

Reviewer notes

• The fork relocation is why this bump is breaking (version .404 → .410): previously bundled classes disappear or move to io.spine.tools.ij.*. No Spine source imports the affected packages (verified by grep).
• Known transition-window skew: Jackson pins still disagree with artifacts published before the stack moved to 2.22.1 (e.g. compiler-jvm .066 requests 2.21.1 via palantir-java-format). The consumer conventions' JacksonV2 forces cover it until the stack republishes, after which it disappears.
• The POM is the only metadata these artifacts publish, and that is load-bearing. Because fatJar is an artifact-only publication (artifact(tasks.shadowJar), no software component), Gradle emits no .module file — verified: publishToMavenLocal yields exactly .jar + .pom for both IJ modules, while component-based siblings like psi-java do get a .module. Gradle consumers therefore fall back to the POM this PR populates. If anyone later switches fatJar to from(components[...]), the generated Module Metadata would take precedence and silently bypass declareUnshadedDependencies — disable metadata generation for the publication in that case. (Raised by Copilot; the two threads carry the measurements.)
• Two unrelated one-line edits ride along in Line.java and ExternalModules.java: parenthesising instanceof patterns to clear an ErrorProne OperatorPrecedence warning surfaced by these builds.
• A --configuration-cache probe is recorded in the task log: the POM-generation tasks execute under CC, but the entry is discarded (the withXml action's captured Configuration is not serializable; the root script's gcloud call is a pre-existing blocker). Full CC readiness is out of scope — the repo does not enable it.
• Remaining follow-up (tracked in the task file): consumer proof in delivery-server — drop the CommonsCompress classpath-ordering workaround once these artifacts are published.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4645845dcf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.73%. Comparing base (cca5d03) to head (31f2213).

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #188   +/-   ##
=========================================
  Coverage     90.73%   90.73%           
  Complexity      547      547           
=========================================
  Files           122      122           
  Lines          2245     2245           
  Branches        313      313           
=========================================
  Hits           2037     2037           
  Misses           86       86           
  Partials        122      122           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR changes how the intellij-platform and intellij-platform-java uber JARs are produced so they no longer bundle (and thereby shadow) large sets of unrelocated third-party classes; instead, only JetBrains artifacts are shaded into the JARs, JetBrains forks are relocated, and the remaining third-party artifacts are published as normal dependencies.

Changes:

• Introduce a shared IntelliJ uber-JAR shading policy (IntelliJUberJar) and apply it to both IntelliJ uber modules (shade only JetBrains artifacts + relocation + POM dependency declaration).
• Align selected dependency versions (Jackson family + Caffeine) within uber-jar modules so the published dependency pins match what this repo builds/tests with.
• Bump published version and refresh dependency documentation / reports accordingly.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
version.gradle.kts	Bumps the version published by this repository to .410.
tool-base/src/main/java/io/spine/tools/fs/ExternalModules.java	Adds parentheses to equals expression to clarify instanceof/operator precedence.
tool-base/src/main/java/io/spine/tools/code/Line.java	Adds parentheses to equals expression to clarify instanceof/operator precedence.
intellij-platform/build.gradle.kts	Switches Shadow configuration to the shared IntelliJ shading policy and adds POM dependency declaration hook.
intellij-platform-java/build.gradle.kts	Applies the shared IntelliJ shading policy, hardens the subtraction/exclusion logic against Shadow transforms, and adds POM dependency declaration hook.
docs/dependencies/pom.xml	Updates documented dependency versions (including tool-base snapshot and spine-base snapshot) and adds missing Kotlin entries.
docs/dependencies/dependencies.md	Regenerates the dependency/license report to reflect the new version and updated resolved dependency set.
buildSrc/src/test/kotlin/io/spine/gradle/shade/IntelliJUberJarSpec.kt	Adds tests for the IntelliJ shading/POM policy logic (group filters, drops, reverse-mapping).
buildSrc/src/main/kotlin/uber-jar-module.gradle.kts	Forces Jackson/Caffeine alignment in uber-jar modules and updates shared Shadow excludes (notably JNA path exclusion).
buildSrc/src/main/kotlin/io/spine/gradle/shade/IntelliJUberJar.kt	Adds the central policy for what gets shaded/relocated vs declared in the published metadata, plus helper extensions.
buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt	Updates the pinned spine-base snapshot version used by this repo (.425 → .440).
.idea/kotlinc.xml	Removes Kotlin language/api version options from IDE config (IDE-only change).
.agents/tasks/unshade-intellij-platform-third-party.md	Adds a task log/analysis document describing the incident and the implemented approach.

Files not reviewed (1)

• .idea/kotlinc.xml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.