Rework the Gradle attributes to make them integrate better with the ecosystem (#4334)

Unfortunately, Gradle's matching algorithm prioritises the number of attributes matched over the actual attribute values. (Note that if a candidate does not have a requested attribute this still counts as a match!) This behaviour makes it impossible to strictly match Configurations, and leads to situations like this where two 'ecosystems' step on each other's toes.

The solution is in two parts:

1. Reduce the number of attributes DGP uses.

   This prevents the matching algorithm from over-matching based on attributes alone. The Bundling attribute is removed, since this is not important for DGP classpaths.
4. (As suggested by @martinbonnin) DGP configurations use a custom value for the `Usage` attribute, and use a one-way `AttributeCompatibilityRule` so DGP can still resolve dependencies.
   (A one-way rule should minimise ugly issues [where rules can leak](gradle/gradle#30921).)

See the KDoc of `DokkaJavaRuntimeUsageCompatibilityRule` for details.


---------

Co-authored-by: Martin Bonnin <[email protected]>

Author: adam-enko

dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt

@@ -10,6 +10,7 @@ import org.gradle.api.NamedDomainObjectContainer
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.artifacts.Configuration
+import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE
 import org.gradle.api.file.ProjectLayout
 import org.gradle.api.file.RegularFileProperty
 import org.gradle.api.logging.Logger
@@ -25,6 +26,7 @@ import org.jetbrains.dokka.gradle.dependencies.BaseDependencyManager
 import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaClasspathAttribute
 import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaFormatAttribute
 import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaModuleComponentAttribute
+import org.jetbrains.dokka.gradle.dependencies.DokkaJavaRuntimeUsageCompatibilityRule
 import org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceSetSpec
 import org.jetbrains.dokka.gradle.engine.parameters.KotlinPlatform
 import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
@@ -152,6 +154,10 @@ constructor(
             attribute(DokkaFormatAttribute)
             attribute(DokkaModuleComponentAttribute)
             attribute(DokkaClasspathAttribute)
+
+            attribute(USAGE_ATTRIBUTE) {
+                compatibilityRules.add(DokkaJavaRuntimeUsageCompatibilityRule::class)
+            }
         }
     }
 

dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt

@@ -39,6 +39,7 @@ interface DokkaAttribute {
     }
 
     @InternalDokkaGradlePluginApi
+    @Suppress("ConstPropertyName")
     companion object {
         /**
          * Describes the type of generated output that Dokka generates.
@@ -65,5 +66,15 @@ interface DokkaAttribute {
          */
         val DokkaClasspathAttribute: Attribute<String> =
             Attribute("org.jetbrains.dokka.classpath")
+
+        /**
+         * The [org.gradle.api.attributes.Usage] attribute for Dokka JARs.
+         *
+         * We are not using [org.gradle.api.attributes.Usage.JAVA_RUNTIME] because this would create
+         * two outgoing variants exposing JARs and potentially confuse consumers.
+         *
+         * See https://github.com/adamko-dev/dokkatoo/issues/165
+         */
+        const val DokkaJavaRuntimeUsage = "dokka-java-runtime"
     }
 }

dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaJavaRuntimeUsageCompatibilityRule.kt

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2014 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package org.jetbrains.dokka.gradle.dependencies
+
+import org.gradle.api.attributes.AttributeCompatibilityRule
+import org.gradle.api.attributes.CompatibilityCheckDetails
+import org.gradle.api.attributes.Usage
+
+/**
+ * # Dokka Java Runtime Usage Compatibility Rule
+ *
+ * If the consumer requests [DokkaAttribute.DokkaJavaRuntimeUsage],
+ * then [Usage.JAVA_RUNTIME] is compatible.
+ *
+ * If the consumer requests [Usage.JAVA_RUNTIME], then do not apply the rule.
+ *
+ * ### Context
+ *
+ * When a project has both a JVM (e.g. Java or Kotlin/JVM) plugin and Dokka plugin,
+ * both plugins add consumable Configurations:
+ * - The traditional 'project JAR' one, containing the compiled JAR of the project
+ *   (e.g. `runtimeElements`).
+ * - The Dokka one, containing Dokka plugins required when aggregating the consumable Dokka module
+ *   (e.g. [org.jetbrains.dokka.gradle.dependencies.DependencyContainerNames.publicationPluginClasspathApiOnlyConsumable]).
+ *
+ * Since both Configurations contain JARs, and have transitive dependencies on JARs,
+ * it is logical for both to use attributes that describe them as 'contains Java classpath JARs'
+ * (e.g. [Usage.JAVA_RUNTIME]).
+ * However, this creates a tension when a consuming project, also with Dokka and JVM plugins applied,
+ * depends on this project:
+ * - The Dokka plugin wants the 'Dokka plugins' Configuration.
+ * - The Java plugin wants the 'project JAR' Configuration.
+ * - Both must resolve the dependencies with [Usage.JAVA_RUNTIME] to include transitive dependencies.
+ * - Since both have 'contains Java classpath JARs' attributes, when they are resolved
+ *   Gradle can't differentiate between them.
+ * - What happens is the Java plugin ends up resolving the 'Dokka plugins' Configuration,
+ *   which leads to extremely confusing errors and behaviours that are very hard to diagnose.
+ *   See https://github.com/adamko-dev/dokkatoo/issues/165
+ *
+ * Basically, Gradle's attribute-matching algorithm is too lenient,
+ * and does not provide a mechanism of making matching strictly require on a specific attribute.
+ *
+ * ### Fix
+ *
+ * So, how can Dokka fix this?
+ *
+ * First, here's what won't work:
+ * Adding _more_ attributes to the 'Dokka plugins' Configuration,
+ * like [org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.DokkaClasspathAttribute],
+ * - The Dokka plugin will be able to correctly resolve the 'Dokka plugins' Configuration.
+ * - But the JVM plugin will still get confused, because the consumer will _ignore_ unknown attributes.
+ * - It doesn't make sense for the JVM plugin to modify its attributes, since they are
+ *   already established and used in the general ecosystem.
+ *   (For similar reasons, Dokka shouldn't modify the Configurations of other plugins.)
+ *
+ * Instead, Dokka can use a custom [Usage] attribute value:
+ * [org.jetbrains.dokka.gradle.dependencies.DokkaAttribute],
+ * and a compatibility rule
+ * [org.jetbrains.dokka.gradle.dependencies.DokkaJavaRuntimeUsageCompatibilityRule].
+ *
+ * - Dokka consumers are able to resolve the transitive dependencies of plugins
+ *   thanks to the compatibility rule.
+ * - Traditional consumers disambiguate the Dokka plugins variants because the
+ *   compatibility rule is one way.
+ *   If the consumer asks for [Usage.JAVA_RUNTIME],
+ *   then the rule expresses no opinion.
+ */
+internal abstract class DokkaJavaRuntimeUsageCompatibilityRule : AttributeCompatibilityRule<Usage> {
+    override fun execute(details: CompatibilityCheckDetails<Usage>) {
+        details.run {
+            if (
+                consumerValue?.name == DokkaAttribute.DokkaJavaRuntimeUsage
+                &&
+                producerValue?.name == Usage.JAVA_RUNTIME
+            ) {
+                compatible()
+            }
+        }
+    }
+}

dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/FormatDependenciesManager.kt

@@ -7,21 +7,18 @@ import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.Project
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.attributes.AttributeContainer
-import org.gradle.api.attributes.Bundling.BUNDLING_ATTRIBUTE
-import org.gradle.api.attributes.Bundling.EXTERNAL
 import org.gradle.api.attributes.Category.CATEGORY_ATTRIBUTE
 import org.gradle.api.attributes.Category.LIBRARY
 import org.gradle.api.attributes.LibraryElements.JAR
 import org.gradle.api.attributes.LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE
-import org.gradle.api.attributes.Usage.JAVA_RUNTIME
 import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE
 import org.gradle.api.attributes.java.TargetJvmEnvironment.STANDARD_JVM
 import org.gradle.api.attributes.java.TargetJvmEnvironment.TARGET_JVM_ENVIRONMENT_ATTRIBUTE
 import org.gradle.api.model.ObjectFactory
-import org.gradle.kotlin.dsl.dependencies
 import org.gradle.kotlin.dsl.named
 import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaClasspathAttribute
 import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaFormatAttribute
+import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaJavaRuntimeUsage
 import org.jetbrains.dokka.gradle.internal.*
 
 /**
@@ -51,18 +48,18 @@ class FormatDependenciesManager(
             formatName = formatName,
         )
 
-    init {
-        project.dependencies {
-            applyAttributeHacks()
-        }
-    }
-
-    private fun AttributeContainer.jvmJar() {
-        attribute(USAGE_ATTRIBUTE, objects.named(AttributeHackPrefix + JAVA_RUNTIME))
-        attribute(CATEGORY_ATTRIBUTE, objects.named(AttributeHackPrefix + LIBRARY))
-        attribute(BUNDLING_ATTRIBUTE, objects.named(AttributeHackPrefix + EXTERNAL))
-        attribute(TARGET_JVM_ENVIRONMENT_ATTRIBUTE, objects.named(AttributeHackPrefix + STANDARD_JVM))
-        attribute(LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(AttributeHackPrefix + JAR))
+    /**
+     * Specifically request JVM JARs for any Dokka classpath.
+     * I.e., uses [DokkaJavaRuntimeUsage] instead of [org.gradle.api.attributes.Usage.JAVA_RUNTIME].
+     *
+     * @see DokkaJavaRuntimeUsage
+     * @see DokkaJavaRuntimeUsage
+     */
+    private fun AttributeContainer.dokkaJvmJar() {
+        attribute(USAGE_ATTRIBUTE, objects.named(DokkaJavaRuntimeUsage))
+        attribute(LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(JAR))
+        attribute(CATEGORY_ATTRIBUTE, objects.named(LIBRARY))
+        attribute(TARGET_JVM_ENVIRONMENT_ATTRIBUTE, objects.named(STANDARD_JVM))
     }
 
     //region Dokka Generator Plugins
@@ -93,7 +90,7 @@ class FormatDependenciesManager(
             extendsFrom(dokkaPluginsClasspath)
             isTransitive = false
             attributes {
-                jvmJar()
+                dokkaJvmJar()
                 attribute(DokkaFormatAttribute, formatAttributes.format.name)
                 attribute(DokkaClasspathAttribute, baseAttributes.dokkaPlugins.name)
             }
@@ -122,7 +119,7 @@ class FormatDependenciesManager(
             resolvable()
             extendsFrom(dokkaPublicationPluginClasspath.get())
             attributes {
-                jvmJar()
+                dokkaJvmJar()
                 attribute(DokkaFormatAttribute, formatAttributes.format.name)
                 attribute(DokkaClasspathAttribute, baseAttributes.dokkaPublicationPlugins.name)
             }
@@ -153,7 +150,7 @@ class FormatDependenciesManager(
             consumable()
             extendsFrom(dokkaPublicationPluginClasspathApiOnly)
             attributes {
-                jvmJar()
+                dokkaJvmJar()
                 attribute(DokkaFormatAttribute, formatAttributes.format.name)
                 attribute(DokkaClasspathAttribute, baseAttributes.dokkaPublicationPlugins.name)
             }
@@ -202,7 +199,7 @@ class FormatDependenciesManager(
             extendsFrom(dokkaGeneratorClasspath.get())
 
             attributes {
-                jvmJar()
+                dokkaJvmJar()
                 attribute(DokkaFormatAttribute, formatAttributes.format.name)
                 attribute(DokkaClasspathAttribute, baseAttributes.dokkaGenerator.name)
             }

dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/attributesHack.kt

@@ -4,12 +4,16 @@
 package org.jetbrains.dokka.gradle
 
 import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.string.shouldNotBeBlank
 import org.jetbrains.dokka.gradle.internal.DokkaConstants.DOKKA_VERSION
 import org.jetbrains.dokka.gradle.utils.*
 
-
-class AttributeHackTest : FunSpec({
-    context("verify that DGP does not interfere with JAR Configurations") {
+/**
+ * Test Dokka creates Configurations that do not interfere with
+ * the dependency resolution of other JVM plugins.
+ */
+class DokkaDependenciesCompatibilityTest : FunSpec({
+    context("verify that DGP does not interfere with resolving JAR Configurations") {
 
         val project = initProject()
 
@@ -23,7 +27,19 @@ class AttributeHackTest : FunSpec({
             .forwardOutput()
             .build {
                 test("resolving JARs from a Dokka-enabled project should not contain Dokka plugin JARs") {
-                    output.shouldNotContainAnyOf(
+
+                    val fileCoords = output
+                        .substringAfter("--- fileCoords ---", "")
+                        .substringBefore("--- fileCoords ---", "")
+
+                    fileCoords.shouldNotBeBlank()
+
+                    fileCoords.shouldContainAll(
+                        "project :subproject-with-dokka",
+                        "org.jetbrains.kotlin:kotlin-stdlib",
+                    )
+
+                    fileCoords.shouldNotContainAnyOf(
                         "org.jetbrains.dokka",
                         "all-modules-page-plugin",
                     )
@@ -105,7 +121,9 @@ private fun initProject(
                 |  }
                 |  inputs.files(jarFilesResolver).withPropertyName("jarFilesResolver")
                 |  doLast {
+                |    println("--- fileCoords ---")
                 |    println(fileCoords.get().joinToString("\n"))
+                |    println("--- fileCoords ---")
                 |  }
                 |}
                 |