Stop bundling the Protobuf runtime into the plugin uber JARs

[alexander-yevsyukov]

Problem

The uber JARs of protobuf-setup-plugins and jvm-tool-plugins — published as protobuf-setup-plugins[-all] and jvm-tool-plugins[-all] — embedded about 1,100 unrelocated classes of protobuf-java, protobuf-java-util, and protobuf-kotlin. com/google/protobuf/RuntimeVersion in .426 reads 4.36.2. So every build pinned the Protobuf runtime it was built with on the build classpath of its consumers.

Gradle cannot see that copy, because it is bytecode inside another artifact, not a dependency. force(...), constraints, and BOMs do not reach it. In the dependency refresh wave (Protobuf 4.36.0 → 4.36.2), code generated by 4.36.2 next to the .422 or .425 JARs failed with ProtobufRuntimeVersionException: … gencode 4.36.2, runtime 4.36.0. That broke core-jvm-compiler, core-jvm, and jdbc-storage, which now carry temporary resolution rules.

Change

The new repo-owned buildSrc/…/shade/ProtobufRuntime.kt adds Project.unbundleProtobufRuntime(). Both modules call it. For each of Protobuf.libs, it:

• excludes the library from shadowJar through the dependency filter, not by path. That way the SBOM does not describe the library as bundled (see SbomContent.bundled(task));
• adds the library, non-transitively, to a new protobufRuntime configuration. shadowRuntimeElements extends that configuration, so plugin-publish lists the library in the .module and the POM of the Gradle plugin publication. The shadow configuration would do the same, but Shadow also writes its files into the manifest Class-Path (Class-Path: protobuf-java-4.36.0.jar …). In a directory that holds several Protobuf JARs, that entry would put the build-time runtime first again;
• writes it into the POM of the artifact-only fatJar publication of uber-jar-module. That publication publishes with artifact(...) and gets no dependencies from Gradle.

The declarations are non-transitive because the libraries' own dependencies are covered elsewhere:

• Guava and Gson are already bundled.
• protobuf-java is declared itself.
• The Gradle runtime provides Kotlin.

So consumers get the same classes as before. Only the Protobuf runtime now comes from genuine artifacts, at the version the consumer resolves.

Relocation is not an option, because the Protobuf runtime depends on the names of its classes. Bundling is not needed either: Protobuf is on Maven Central. This is the approach of #188 (IntelliJUberJar.kt), applied to Protobuf.

Verification

• The JARs no longer contain the Protobuf runtime. RuntimeVersion is absent, and the size drops from 6.9 MB to 4.7 MB for jvm-tool-plugins and from 7.3 MB to 5.1 MB for protobuf-setup-plugins.
• The pluginMaven and fatJar POMs and the .module files declare protobuf-java, protobuf-java-util, and protobuf-kotlin in the runtime scope with *:* exclusions.
• The JAR manifests have no Class-Path attribute.
• ./gradlew build dokkaGenerate passes.

Version

2.0.0-SNAPSHOT.427. It skips .426, which the in-flight refresh wave (#195) claims.

Follow-ups for consumers

Once a consumer pins ToolBase .427 or later:

• core-jvm and jdbc-storage can drop their eachDependency rules that lift protobuf-setup-plugins from .422/.425 to .426.
• core-jvm-compiler can go back to ToolBase.jvmToolPluginDogfooding once dogfoodingVersion is .427 or later.

Future Protobuf bumps no longer need such rules.

Not in scope

protobuf-setup-plugins still bundles the protobuf-gradle-plugin classes (com/google/protobuf/gradle/**) and its OS-detector dependencies, unrelocated. They are not the runtime, and nothing failed on them. Declaring them in the same way could be a separate change.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-16T16:47:56.863816Z	858874d	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🔵 Needs a closer look

The central publication helper remains outside the permitted review scope, and downstream dependency resolution requires human validation.

0 open findings

What changed in this PR

Moves the Protobuf runtime out of plugin uber JARs so consumers can resolve its version through normal dependency management.

Changes:

• Applies runtime unbundling to both plugin modules.
• Adds explicit runtime dependencies to publication metadata.
• Advances the release to 2.0.0-SNAPSHOT.427 and refreshes dependency reports.

File	Description
version.gradle.kts	Advances the publication version.
protobuf-setup-plugins/​build.gradle.kts	Applies runtime unbundling.
jvm-tool-plugins/​build.gradle.kts	Applies runtime unbundling.
docs/​dependencies/​pom.xml	Updates the reported version.
docs/​dependencies/​dependencies.md	Refreshes report versions and timestamps.
buildSrc/​src/​main/​kotlin/​io/​spine/​gradle/​shade/​ProtobufRuntime.kt	Adds shading exclusions and runtime publication declarations.
.agents/​tasks/​unbundle-protobuf-runtime.md	Records implementation and verification progress.

🧠 Review effort: Balanced

---

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

[Copilot]

🔵 Needs a closer look

Publication and classpath changes need human confirmation of downstream dependency resolution for both plugin and artifact consumers.

0 open findings

🧠 Review effort: Balanced

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.96%. Comparing base (d903a41) to head (d1e8027).

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #196   +/-   ##
=========================================
  Coverage     91.96%   91.96%           
  Complexity      840      840           
=========================================
  Files           163      163           
  Lines          2999     2999           
  Branches        373      373           
=========================================
  Hits           2758     2758           
  Misses          109      109           
  Partials        132      132           

🚀 New features to boost your workflow:

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

[Copilot]

🔵 Needs a closer look

Cross-publication dependency metadata and downstream classloader behavior warrant final human validation.

0 open findings

🧠 Review effort: Balanced