improve NPM Gradle task caching (#3479)

* improve NPM Gradle task caching

- bump Gradle Node Plugin version
- add path-sensitivity to task inputs, so cache can be re-used across machines
- add property names to task (easier debugging/reporting)
- update npmRunBuild input files so glob matching works
- enable fastNpmInstall so Gradle delegates node_modules dir management to NPM

dokka-subprojects/plugin-base-frontend/build.gradle.kts

@@ -3,9 +3,9 @@
  */
 
 import com.github.gradle.node.npm.task.NpmTask
+import org.gradle.api.tasks.PathSensitivity.RELATIVE
 import org.jetbrains.kotlin.util.parseSpaceSeparatedArgs
 
-@Suppress("DSL_SCOPE_VIOLATION") // fixed in Gradle 8.1 https://github.com/gradle/gradle/pull/23639
 plugins {
     id("dokkabuild.setup-html-frontend-files")
     alias(libs.plugins.gradleNode)
@@ -17,6 +17,9 @@ node {
     // https://github.com/node-gradle/gradle-node-plugin/blob/3.5.1/docs/faq.md#is-this-plugin-compatible-with-centralized-repositories-declaration
     download.set(true)
     distBaseUrl.set(null as String?) // Strange cast to avoid overload ambiguity
+
+    // Stop Gradle from monitoring node_modules dir; it will be managed by NPM. This helps performance and task-avoidance.
+    fastNpmInstall = true
 }
 
 val distributionDirectory = layout.projectDirectory.dir("dist")
@@ -27,13 +30,25 @@ val npmRunBuild by tasks.registering(NpmTask::class) {
     npmCommand.set(parseSpaceSeparatedArgs("run build"))
 
     inputs.dir("src/main")
+        .withPropertyName("mainSources")
+        .withPathSensitivity(RELATIVE)
+
     inputs.files(
-        "package.json",
-        "webpack.config.js",
+        layout.projectDirectory.asFileTree.matching {
+            include(
+                "package.json",
+                "tsconfig.json",
+                "*.config.js",
+            )
+        }
     )
+        .withPropertyName("javascriptConfigFiles")
+        .withPathSensitivity(RELATIVE)
+
+    outputs.cacheIf("always cache, because this task has a defined output directory") { true }
 
     outputs.dir(distributionDirectory)
-    outputs.cacheIf { true }
+        .withPropertyName("distributionDirectory")
 }
 
 configurations.dokkaHtmlFrontendFilesElements.configure {
@@ -45,8 +60,5 @@ configurations.dokkaHtmlFrontendFilesElements.configure {
 }
 
 tasks.clean {
-    delete(
-        file("node_modules"),
-        file("dist"),
-    )
+    delete(distributionDirectory)
 }

dokka-subprojects/plugin-base/build.gradle.kts

@@ -37,7 +37,12 @@ dependencies {
     testImplementation(libs.junit.jupiterParams)
 
     symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
+    descriptorsTestConfiguration(
+        project(
+            path = ":dokka-subprojects:analysis-kotlin-descriptors",
+            configuration = "shadow"
+        )
+    )
     testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils) {
         exclude(module = "analysis-kotlin-descriptors")
     }
@@ -56,7 +61,7 @@ val dokkaHtmlFrontendFiles: Provider<FileCollection> =
         frontendFiles.incoming.artifacts.artifactFiles
     }
 
-val preparedokkaHtmlFrontendFiles by tasks.registering(Sync::class) {
+val prepareDokkaHtmlFrontendFiles by tasks.registering(Sync::class) {
     description = "copy Dokka Base frontend files into the resources directory"
 
     from(dokkaHtmlFrontendFiles) {
@@ -70,10 +75,12 @@ val preparedokkaHtmlFrontendFiles by tasks.registering(Sync::class) {
     }
 
     into(layout.buildDirectory.dir("generated/src/main/resources"))
+
+    outputs.cacheIf("always cache: avoid fetching files from another subproject") { true }
 }
 
 sourceSets.main {
-    resources.srcDir(preparedokkaHtmlFrontendFiles.map { it.destinationDir })
+    resources.srcDir(prepareDokkaHtmlFrontendFiles.map { it.destinationDir })
 }
 
 tasks.test {

gradle/libs.versions.toml

@@ -56,7 +56,7 @@ node = "16.13.0"
 ## Publishing
 gradlePlugin-shadow = "8.1.1"
 gradlePlugin-gradlePluginPublish = "1.2.1"
-gradlePlugin-gradleNode = "3.5.1"
+gradlePlugin-gradleNode = "7.0.1"
 
 ## Test
 junit = "5.9.3"