Support shadowed sources JAR

[Goooler]

---

• CHANGELOG's "Unreleased" section has been updated, if applicable.

[Copilot]

🟡 Changes recommended

There are confirmed correctness/behavior issues (notably a ClassCastException risk in includedSourcesJars and non-deterministic ZIP timestamps) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds first-class support for generating and publishing a shadowed sources JAR alongside the shadowed binary JAR, including relocation of source contents/paths and optional filtering of sources for minimized dependencies.

Changes:

• Add a new internal implementation to generate a relocated/merged sources JAR from project sources plus dependency -sources.jars.
• Extend ShadowJar/plugins to wire source directories, resolve dependency sources, and publish a new shadowSourcesElements variant.
• Add functional/unit tests plus documentation updates covering publishing and doc-generation (Javadoc/Dokka) from shadowed sources.

File summaries

File	Description
src/testKit/kotlin/com/github/jengelman/gradle/plugins/shadow/testkit/JarPath.kt	Exposes toEntries() for broader test assertions.
src/test/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/ShadowSourcesJarTest.kt	Unit tests for package parsing, unused filtering, and package-dir normalization.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar.kt	Generates shadowed sources JAR during shadowJar execution; tracks unused classes for source filtering.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/ShadowKmpPlugin.kt	Wires KMP JVM sources directories into shadowJar.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/ShadowJavaPlugin.kt	Registers/publishes shadowSourcesElements configuration/variant and attaches sources artifact.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/ShadowApplicationPlugin.kt	Fixes application classpaths to use the shadow JAR archive file provider.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/relocation/SimpleRelocator.kt	Removes outdated comment about source relocation usage.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/ShadowSourcesJar.kt	New generator for relocated/merged sources JAR (project + dependency sources).
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/DefaultDependencyFilter.kt	Adds dependency-sources resolution (-sources.jar) honoring include/exclude rules.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/util/LocalMavenRepository.kt	Test repo now publishes sources jars for selected modules.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/util/GradleModuleMetadata.kt	Adds accessor for new shadowSourcesElements variant.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/util/AppendableMavenRepository.kt	Supports publishing an additional sources artifact in test publications.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/RelocationTest.kt	Adds functional coverage for relocated sources jar output/content and empty-sources behavior.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/PublishingTest.kt	Verifies publishing outputs include shadowed sources jar + new variant metadata; adds KMP publication test.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/MinimizeTest.kt	Verifies minimized dependencies also prune corresponding sources from shadowed sources jar (dependency-analyzer mode).
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/KotlinPluginsTest.kt	Adds Dokka + package-dir normalization tests consuming shadowed sources jar.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/JavaPluginsTest.kt	Adds Javadoc generation test consuming shadowed sources jar.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/FilteringTest.kt	Ensures dependency excludes apply consistently to both binary and sources jars.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/BasePluginTest.kt	Test scaffolding now produces sources jars + exposes standard shadowed sources jar output paths.
src/documentTest/kotlin/com/github/jengelman/gradle/plugins/shadow/SnippetExecutable.kt	Adds Dokka-related gradle.properties to stabilize snippet execution in isolated builds.
gradle/libs.versions.toml	Adds Dokka version + plugin alias; refactors Dokka plugin declaration to use version ref.
docs/publishing/README.md	Documents shadowed sources jar behavior, publishing variant, customization, and Javadoc/Dokka usage.
docs/kotlin-plugins/README.md	Links KMP publishing docs for shadowed artifacts/sources.
docs/getting-started/README.md	Notes automatic shadowed sources jar generation + variant behavior.
docs/configuration/minimizing/README.md	Documents limitation for R8 minimization vis-à-vis sources filtering.
CHANGELOG.md	Adds unreleased entry for shadowed sources jar support.
build.gradle.kts	Adds Dokka to test plugin runtime classpath.
api/shadow.api	Updates ABI dump for new public API surface (sources elements constant + archiveSourcesFile).

Review details

• Files reviewed: 27/28 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 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

The new shadowed sources JAR generation currently has reproducibility and correctness risks (non-deterministic ZIP ordering and a fragile @file:[...] JvmName(...) regex) that should be addressed before approval.

Review details

Suppressed comments (6)

Previously missed (5) — in code that hasn't changed since the last review.

src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/ShadowSourcesJar.kt:49

• walkTopDown() and iteration over sourceSetsSourceDirs can yield non-deterministic file ordering (filesystem / Set iteration), which makes the generated shadowed sources JAR vary between runs and hurts cacheability/reproducibility. Sorting the source directories and their walked files by relative path produces stable ZIP entry ordering.
  src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/ShadowSourcesJar.kt:92
• sourcesJars comes from a FileCollection and may have non-stable iteration order, which can make ZIP entry ordering vary between builds. Sorting the input jars makes the output more reproducible.
  src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar.kt:53
• This file’s KDoc references [WARN] (DuplicatesStrategy) later on, but the corresponding DuplicatesStrategy.WARN import was removed in this change. That can break Dokka/KDoc link resolution for the WARN strategy; re-add the import to keep the links resolvable.
  src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/ShadowJavaPlugin.kt:129
• Typo in comment: “If withSourcesJar presents.” should be grammatically “is present”.
  src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/ShadowSourcesJar.kt:152
• parentDirectoryEntries() already returns parent directories from root-to-leaf (see Zip.kt), but the extra .asReversed() flips it back to leaf-to-root. This looks unintentional and produces directory entries in a surprising order; iterating in the original order is simpler and more consistent.

src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/internal/ShadowSourcesJar.kt:171

• jvmNameRegex intends to support bracketed file annotations (e.g. @file:[Suppress(...) JvmName("X")]), but the current (?:\[[^]]*\b)? sub-pattern can stop before the closing ] and prevent a match. That makes isUnused miss custom facades and keep sources that should be filtered when minimizing.

private val jvmNameRegex =
  """@file\s*:\s*(?:\[[^]]*\b)?(?:kotlin\s*\.\s*jvm\s*\.\s*)?JvmName\s*\(\s*(?:name\s*=\s*)?"([^"]+)""""
    .toRegex()

• Files reviewed: 27/28 changed files
• Comments generated: 0 new
• Review effort level: Lite