Cachable task (#1905)

* Add tests for Gradle caching scenarios and adjust
tasks to honor caching such that tests pass

* Make dokka tasks cachable

* Make dokka tasks cachable

* Make dokka tasks cachable

* Fix gradle assertion

Co-authored-by: Volker Leck <volker.leck@gmail.com>

5 files changed, 257 insertions, 9 deletions

diff --git a/integration-tests/gradle/projects/it-basic/build.gradle.kts b/integration-tests/gradle/projects/it-basic/build.gradle.kts
index 414037fe..e5abd7e1 100644
--- a/integration-tests/gradle/projects/it-basic/build.gradle.kts
+++ b/integration-tests/gradle/projects/it-basic/build.gradle.kts
@@ -50,5 +50,5 @@ tasks.withType<DokkaTask> {
     }
     suppressObviousFunctions.set(false)
 
-    pluginsMapConfiguration.set(mapOf(DokkaBase::class.qualifiedName to """{ "customStyleSheets": ["${file("customResources/logo-styles.css")}", "${file("customResources/custom-style-to-add.css")}"], "customAssets" : ["${file("customResources/custom-resource.svg")}"] }"""))
+    pluginsMapConfiguration.set(mapOf(DokkaBase::class.qualifiedName to """{ "customStyleSheets": ["${file("../customResources/logo-styles.css")}", "${file("../customResources/custom-style-to-add.css")}"], "customAssets" : ["${file("../customResources/custom-resource.svg")}"] }"""))
 }
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleCachingIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleCachingIntegrationTest.kt
new file mode 100644
index 00000000..2bce02aa
--- /dev/null
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleCachingIntegrationTest.kt
@@ -0,0 +1,136 @@
+package org.jetbrains.dokka.it.gradle
+
+import org.gradle.util.GradleVersion
+import java.io.File
+import kotlin.test.*
+
+abstract class AbstractGradleCachingIntegrationTest(override val versions: BuildVersions): AbstractGradleIntegrationTest() {
+    fun setupProject(project: File) {
+        val templateProjectDir = File("projects", "it-basic")
+        project.mkdirs()
+        templateProjectDir.listFiles().orEmpty()
+            .filter { it.isFile }
+            .forEach { topLevelFile -> topLevelFile.copyTo(File(project, topLevelFile.name)) }
+
+        File(templateProjectDir, "src").copyRecursively(File(project, "src"))
+        val customResourcesDir = File(templateProjectDir, "customResources")
+        if(customResourcesDir.exists() && customResourcesDir.isDirectory) {
+            val destination = File(project.parentFile, "customResources")
+            destination.mkdirs()
+            destination.deleteRecursively()
+            customResourcesDir.copyRecursively(destination)
+        }
+
+        // clean local cache for each test
+        if (versions.gradleVersion >= GradleVersion.version("7.0")) {
+            //Gradle 7.0 removed the old syntax
+            project.toPath().resolve("settings.gradle.kts").toFile().appendText(
+                """
+                buildCache {
+                    local {
+                        // Set local build cache directory.
+                        directory = File("${projectDir.absolutePath}", "build-cache")
+                    }
+                }
+            """.trimIndent()
+            )
+        } else {
+            project.toPath().resolve("settings.gradle.kts").toFile().appendText(
+                """
+                buildCache {
+                    local<DirectoryBuildCache> {
+                        // Set local build cache directory.
+                        directory = File("${projectDir.absolutePath}", "build-cache")
+                    }
+                }
+            """.trimIndent()
+            )
+        }
+    }
+
+    fun File.assertHtmlOutputDir() {
+        assertTrue(isDirectory, "Missing dokka html output directory")
+
+        val imagesDir = File(this, "images")
+        assertTrue(imagesDir.isDirectory, "Missing images directory")
+
+        val scriptsDir = File(this, "scripts")
+        assertTrue(scriptsDir.isDirectory, "Missing scripts directory")
+        val reactFile = File(this, "scripts/main.js")
+        assertTrue(reactFile.isFile, "Missing main.js")
+
+        val stylesDir = File(this, "styles")
+        assertTrue(stylesDir.isDirectory, "Missing styles directory")
+        val reactStyles = File(this, "styles/main.css")
+        assertTrue(reactStyles.isFile, "Missing main.css")
+
+        val navigationHtml = File(this, "navigation.html")
+        assertTrue(navigationHtml.isFile, "Missing navigation.html")
+
+        val moduleOutputDir = File(this, "-basic -project")
+        assertTrue(moduleOutputDir.isDirectory, "Missing module directory")
+
+        val moduleIndexHtml = File(this, "index.html")
+        assertTrue(moduleIndexHtml.isFile, "Missing module index.html")
+
+        val modulePackageDir = File(moduleOutputDir, "it.basic")
+        assertTrue(modulePackageDir.isDirectory, "Missing it.basic package directory")
+
+        val modulePackageIndexHtml = File(modulePackageDir, "index.html")
+        assertTrue(modulePackageIndexHtml.isFile, "Missing module package index.html")
+
+        val moduleJavaPackageDir = File(moduleOutputDir, "it.basic.java")
+        assertTrue(moduleJavaPackageDir.isDirectory, "Missing it.basic.java package directory")
+
+        allHtmlFiles().forEach { file ->
+            assertContainsNoErrorClass(file)
+            assertNoUnresolvedLinks(file)
+            assertNoHrefToMissingLocalFileOrDirectory(file)
+            assertNoSuppressedMarker(file)
+            assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
+        }
+
+        assertTrue(
+            allHtmlFiles().any { file -> "Basic Project" in file.readText() },
+            "Expected configured moduleName to be present in html"
+        )
+
+        assertTrue(
+            allHtmlFiles().any { file ->
+                "https://github.com/Kotlin/dokka/tree/master/" +
+                        "integration-tests/gradle/projects/it-basic/" +
+                        "src/main/kotlin/it/basic/PublicClass.kt" in file.readText()
+            },
+            "Expected `PublicClass` source link to GitHub"
+        )
+
+        assertTrue(
+            allHtmlFiles().any { file ->
+                "https://github.com/Kotlin/dokka/tree/master/" +
+                        "integration-tests/gradle/projects/it-basic/" +
+                        "src/main/java/it/basic/java/SampleJavaClass.java" in file.readText()
+            },
+            "Expected `SampleJavaClass` source link to GitHub"
+        )
+
+        val anchorsShouldNotHaveHashes = "<a data-name=\".*#.*\"\\sanchor-label=\"*.*\">".toRegex()
+        assertTrue(
+            allHtmlFiles().all { file ->
+                !anchorsShouldNotHaveHashes.containsMatchIn(file.readText())
+            },
+            "Anchors should not have hashes inside"
+        )
+
+        assertEquals(
+            """#logo{background-image:url('https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg');}""",
+            stylesDir.resolve("logo-styles.css").readText().replace("\\s".toRegex(), ""),
+        )
+        assertTrue(stylesDir.resolve("custom-style-to-add.css").isFile)
+        assertEquals("""/* custom stylesheet */""", stylesDir.resolve("custom-style-to-add.css").readText())
+        allHtmlFiles().forEach { file ->
+            if(file.name != "navigation.html") assertTrue("custom-style-to-add.css" in file.readText(), "custom styles not added to html file ${file.name}")
+        }
+        assertTrue(imagesDir.resolve("custom-resource.svg").isFile)
+    }
+}
\ No newline at end of file
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicCachingIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicCachingIntegrationTest.kt
new file mode 100644
index 00000000..2207a13f
--- /dev/null
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicCachingIntegrationTest.kt
@@ -0,0 +1,47 @@
+package org.jetbrains.dokka.it.gradle
+
+import org.gradle.testkit.runner.TaskOutcome
+import org.junit.runners.Parameterized.Parameters
+import java.io.File
+import kotlin.test.*
+
+class BasicCachingIntegrationTest(override val versions: BuildVersions) : AbstractGradleCachingIntegrationTest(versions) {
+
+    companion object {
+        @get:JvmStatic
+        @get:Parameters(name = "{0}")
+        val versions = BuildVersions.permutations(
+            gradleVersions = listOf("7.0", *ifExhaustive("6.6", "6.1.1")),
+            kotlinVersions = listOf("1.3.30", *ifExhaustive("1.3.72", "1.4.32"), "1.5.0")
+        ) + BuildVersions.permutations(
+            gradleVersions = listOf("5.6.4", "6.0"),
+            kotlinVersions = listOf("1.3.30", *ifExhaustive("1.4.32"))
+        )
+    }
+
+    @BeforeTest
+    fun setupProjectFiles(){
+        setupProject(projectDir)
+    }
+
+    @Test
+    fun execute() {
+        runAndAssertOutcome(TaskOutcome.SUCCESS)
+        runAndAssertOutcome(TaskOutcome.FROM_CACHE)
+    }
+
+    private fun runAndAssertOutcome(expectedOutcome: TaskOutcome) {
+        val result = createGradleRunner(
+            "clean",
+            "dokkaHtml",
+            "-i",
+            "-s",
+            "-Dorg.gradle.caching.debug=true",
+            "--build-cache"
+        ).buildRelaxed()
+
+        assertEquals(expectedOutcome, assertNotNull(result.task(":dokkaHtml")).outcome)
+
+        File(projectDir, "build/dokka/html").assertHtmlOutputDir()
+    }
+}
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt
index 11f20ae8..1322356f 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt
@@ -29,18 +29,35 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac
 
         File(templateProjectDir, "src").copyRecursively(File(projectDir, "src"))
         val customResourcesDir = File(templateProjectDir, "customResources")
-        if(customResourcesDir.exists() && customResourcesDir.isDirectory) customResourcesDir.copyRecursively(File(projectDir, "customResources"))
+
+        if (customResourcesDir.exists() && customResourcesDir.isDirectory) {
+            val destination = File(projectDir.parentFile, "customResources")
+            destination.mkdirs()
+            destination.deleteRecursively()
+            customResourcesDir.copyRecursively(destination)
+        }
     }
 
     @Test
     fun execute() {
-        val result = createGradleRunner("dokkaHtml", "dokkaJavadoc", "dokkaGfm", "dokkaJekyll", "-i", "-s")
-            .buildRelaxed()
+        runAndAssertOutcome(TaskOutcome.SUCCESS)
+        runAndAssertOutcome(TaskOutcome.UP_TO_DATE)
+    }
 
-        assertEquals(TaskOutcome.SUCCESS, assertNotNull(result.task(":dokkaHtml")).outcome)
-        assertEquals(TaskOutcome.SUCCESS, assertNotNull(result.task(":dokkaJavadoc")).outcome)
-        assertEquals(TaskOutcome.SUCCESS, assertNotNull(result.task(":dokkaGfm")).outcome)
-        assertEquals(TaskOutcome.SUCCESS, assertNotNull(result.task(":dokkaJekyll")).outcome)
+    private fun runAndAssertOutcome(expectedOutcome: TaskOutcome) {
+        val result = createGradleRunner(
+            "dokkaHtml",
+            "dokkaJavadoc",
+            "dokkaGfm",
+            "dokkaJekyll",
+            "-i",
+            "-s"
+        ).buildRelaxed()
+
+        assertEquals(expectedOutcome, assertNotNull(result.task(":dokkaHtml")).outcome)
+        assertEquals(expectedOutcome, assertNotNull(result.task(":dokkaJavadoc")).outcome)
+        assertEquals(expectedOutcome, assertNotNull(result.task(":dokkaGfm")).outcome)
+        assertEquals(expectedOutcome, assertNotNull(result.task(":dokkaJekyll")).outcome)
 
         File(projectDir, "build/dokka/html").assertHtmlOutputDir()
         File(projectDir, "build/dokka/javadoc").assertJavadocOutputDir()
@@ -129,7 +146,10 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac
         assertTrue(stylesDir.resolve("custom-style-to-add.css").isFile)
         assertEquals("""/* custom stylesheet */""", stylesDir.resolve("custom-style-to-add.css").readText())
         allHtmlFiles().forEach { file ->
-            if(file.name != "navigation.html") assertTrue("custom-style-to-add.css" in file.readText(), "custom styles not added to html file ${file.name}")
+            if (file.name != "navigation.html") assertTrue(
+                "custom-style-to-add.css" in file.readText(),
+                "custom styles not added to html file ${file.name}"
+            )
         }
         assertTrue(imagesDir.resolve("custom-resource.svg").isFile)
     }
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/GradleRelocatedCachingIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/GradleRelocatedCachingIntegrationTest.kt
new file mode 100644
index 00000000..d82c3827
--- /dev/null
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/GradleRelocatedCachingIntegrationTest.kt
@@ -0,0 +1,45 @@
+package org.jetbrains.dokka.it.gradle
+
+import org.gradle.testkit.runner.TaskOutcome
+import org.junit.runners.Parameterized.Parameters
+import java.io.File
+import kotlin.test.*
+
+class GradleRelocatedCachingIntegrationTest(override val versions: BuildVersions) : AbstractGradleCachingIntegrationTest(versions) {
+
+    companion object {
+        @get:JvmStatic
+        @get:Parameters(name = "{0}")
+        val versions = BuildVersions.permutations(
+            gradleVersions = listOf("7.0", *ifExhaustive("6.6", "6.1.1")),
+            kotlinVersions = listOf("1.3.30", *ifExhaustive("1.3.72", "1.4.32"), "1.5.0")
+        ) + BuildVersions.permutations(
+            gradleVersions = listOf("5.6.4", "6.0"),
+            kotlinVersions = listOf("1.3.30", *ifExhaustive("1.4.32"))
+        )
+    }
+
+    @BeforeTest
+    fun prepareProjectFiles() {
+        setupProject(projectFolder(1))
+        setupProject(projectFolder(2))
+    }
+
+    @Test
+    fun execute() {
+        runAndAssertOutcome(projectFolder(1), TaskOutcome.SUCCESS)
+        runAndAssertOutcome(projectFolder(2), TaskOutcome.FROM_CACHE)
+    }
+
+    private fun runAndAssertOutcome(project: File, expectedOutcome: TaskOutcome) {
+        val result = createGradleRunner("clean", "dokkaHtml", "-i", "-s", "-Dorg.gradle.caching.debug=true", "--build-cache")
+            .withProjectDir(project)
+            .buildRelaxed()
+
+        assertEquals(expectedOutcome, assertNotNull(result.task(":dokkaHtml")).outcome)
+
+        File(project, "build/dokka/html").assertHtmlOutputDir()
+    }
+
+    private fun projectFolder(index: Int) = File(projectDir.absolutePath + index)
+}