Fix tools.forma.includer plugin behavior (#128)

* Fix `tools.forma.includer` plugin behavior

- Skip including nested projects
- Consider only dirs with `build.gradle(.kts)` files as subprojects
- Extend `IncluderPluginFunctionalTest` to cover problematic use cases

* Make Includer plugin more flexible and configurable

- Allowed to disable arbitrary build file names
- Allowed to specify additional folder names to ignore
- Do not allow to configure the project if a module with more than one build file is encountered
- Covered all use cases of the plugin with tests
- Added documentation to the README

* Made Includer configurable via extension in settings.gradle.kts

- Create IncluderExtension and Dsl function `includer` for it
- Add docs for IncluderExtension properties
- Disable arbitraryBuildScriptNames by default
- Covered all use cases of the plugin with tests
- Update documentation in the README

* Includer 0.2

---------

Co-authored-by: Stepan Goncharov <[email protected]>

Author: tonykolomeytsev

application/settings.gradle.kts

@@ -1,5 +1,3 @@
-import org.gradle.api.internal.artifacts.dependencies.DefaultDependencyConstraint.strictly
-
 pluginManagement {
     apply(
         from =
@@ -19,6 +17,8 @@ plugins {
     id("tools.forma.depgen")
 }
 
+includer { arbitraryBuildScriptNames = true }
+
 rootProject.name = "application"
 
 val filteredTokens =
@@ -58,7 +58,7 @@ dependencyResolutionManagement {
             addPlugin("tools.forma.demo:dependencies", "0.0.1")
             addPlugin(
                 "com.google.devtools.ksp",
-                "1.8.10-1.0.9",
+                "$embeddedKotlinVersion-1.0.9",
                 "androidx.room:room-compiler:$roomVersion"
             )
         }

includer/Changelog.md

@@ -1,3 +1,7 @@
+# 0.2.0 Minor patch release
+
+- Includer configuration extension added
+
 # 0.1.3 Minor patch release
 
 - Prevent traversing nested projects

includer/Readme.md

@@ -1,6 +1,7 @@
 # Includer
 
-Simple and powerful plugin which helps you to save time and avoid writing tons of boilerplate code. Uses kotlin coroutines to efficiently traverse even deeply nested project trees.
+Simple and powerful plugin which helps you to save time and avoid writing tons of boilerplate code. 
+Uses kotlin coroutines to efficiently traverse even deeply nested project trees.
 
 ## Installation
 
@@ -11,3 +12,55 @@ plugins {
     id("tools.forma.includer") version "0.1.3"
 }
 ```
+
+# How does it work?
+
+Includer traverses the project's file tree and includes as subprojects all directories that have 
+files with `build.gradle(.kts)` files.
+
+Includer skips directories that have `settings.gradle(.kts)` files, treating them as nested projects.
+
+Example:
+
+```
+rootProject
+|--app <- will be included as :app
+|----build.gradle.kts
+|
+|--build-logic <- will be ignored
+|----settings.gradle.kts
+|
+|--feature1
+|----api <- will be included as :feature1-api
+|------build.gradle.kts
+```
+
+# Plugin configuration
+
+The plugin is configurable by specifying properties in the `includer` extension.
+
+## Ignored folders
+
+Includer always skips directories with following names: `build`, `src`, `buildSrc`. But you can 
+specify additional ignored folder names:
+
+```kotlin
+// in settings.gradle.kts file after `plugins` block
+includer {
+    excludeFolders(".cmake_cache", "scripts")
+}
+```
+
+## Arbitrary build file names
+
+If you want the plugin to look for any `*.gradle(.kts)` files, not just `build.gradle(.kts)`:
+
+```kotlin
+// in settings.gradle.kts file after `plugins` block
+includer {
+    arbitraryBuildScriptNames = true
+}
+```
+
+> NOTE: If you use this property, there can only be one `*.gradle(.kts)` file in the root 
+> of any module.

includer/plugin/build.gradle.kts

@@ -1,20 +1,19 @@
 @file:Suppress("UnstableApiUsage")
 
 plugins {
-    id("com.gradle.plugin-publish") version "1.1.0"
+    id("com.gradle.plugin-publish") version "1.2.0"
     id("org.jetbrains.kotlin.jvm") version embeddedKotlinVersion
 }
 
-version = "0.1.3"
+version = "0.2.0"
 group = "tools.forma"
 
 repositories {
     mavenCentral()
 }
 
 dependencies {
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.6.4")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.2")
 }
 
 val javaLanguageVersion = JavaLanguageVersion.of(11)
@@ -34,19 +33,18 @@ testing {
     suites {
         // Configure the built-in test suite
         val test by getting(JvmTestSuite::class) {
-            // Use Kotlin Test test framework
+            // Use Kotlin Test framework
             useKotlinTest(embeddedKotlinVersion)
         }
 
         // Create a new test suite
         val functionalTest by registering(JvmTestSuite::class) {
-            // Use Kotlin Test test framework
+            // Use Kotlin Test framework
             useKotlinTest(embeddedKotlinVersion)
 
             dependencies {
                 // functionalTest test suite depends on the production code in tests
                 implementation(project())
-                // implementation("org.gradle:gradle-test-kit:${gradle.gradleVersion}")
             }
 
             targets {

includer/plugin/src/functionalTest/kotlin/tools/forma/includer/IncluderPluginFunctionalTest.kt

@@ -3,11 +3,14 @@
  */
 package tools.forma.includer
 
-import java.io.File
-import kotlin.test.assertTrue
-import kotlin.test.Test
 import org.gradle.testkit.runner.GradleRunner
+import org.junit.jupiter.api.assertThrows
 import org.junit.jupiter.api.io.TempDir
+import java.io.File
+import kotlin.test.BeforeTest
+import kotlin.test.Test
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
 
 /**
  * A simple functional test includer plugin.
@@ -17,26 +20,44 @@ class IncluderPluginFunctionalTest {
     @field:TempDir
     lateinit var projectDir: File
 
-    private val rootBuildFile by lazy { projectDir.resolve("build.gradle.kts") }
-    private val settingsFile by lazy { projectDir.resolve("settings.gradle.kts") }
-    private val projectFile by lazy {
-        File(projectDir, "app").mkdir()
-        projectDir.resolve("app/build.gradle.kts")
-    }
-
-    @Test
-    fun `include extra projects`() {
-        // Set up the test build
-        rootBuildFile.writeText("")
-        projectFile.writeText("")
-        settingsFile.writeText(
+    @BeforeTest
+    fun `prepare filesystem`() {
+        projectDir.resolve("build.gradle.kts").createNewFile()
+        projectDir.resolve("settings.gradle.kts").writeText(
             """
             plugins {
                 id("tools.forma.includer")
             }
+            
         """.trimIndent()
         )
+        // :app
+        File(projectDir, "app").mkdir()
+        projectDir.resolve("app/build.gradle.kts").createNewFile()
+
+        // :feature1-api
+        File(projectDir, "feature1/api").mkdirs()
+        projectDir.resolve("feature1/api/api.gradle.kts").createNewFile()
 
+        // :feature1-impl
+        File(projectDir, "feature1/impl").mkdirs()
+        projectDir.resolve("feature1/impl/impl.gradle.kts").createNewFile()
+
+        // :util-android
+        File(projectDir, "util/android").mkdirs()
+        projectDir.resolve("util/android/build.gradle.kts").createNewFile()
+
+        // composite build :build-logic
+        File(projectDir, "build-logic").mkdir()
+        projectDir.resolve("build-logic/settings.gradle.kts").createNewFile()
+
+        // composite build :build-logic:conventions
+        File(projectDir, "build-logic/conventions").mkdir()
+        projectDir.resolve("build-logic/conventions/build.gradle.kts").createNewFile()
+    }
+
+    @Test
+    fun `include projects with default options`() {
         // Run the build
         val runner = GradleRunner.create()
         runner.forwardOutput()
@@ -46,6 +67,163 @@ class IncluderPluginFunctionalTest {
         val result = runner.build()
 
         // Verify the result
-        assertTrue(result.output.contains("Project ':app'"))
+        assertTrue("Should include ':app' project") {
+            result.output.contains("Project ':app'")
+        }
+        assertFalse(
+            "Shouldn't include ':feature1-api' project " +
+                    "because this project has a non-standard build file name"
+        ) {
+            result.output.contains("Project ':feature1-api'")
+        }
+        assertFalse(
+            "Shouldn't include ':feature1-impl' project " +
+                    "because this project has a non-standard build file name"
+        ) {
+            result.output.contains("Project ':feature1-impl'")
+        }
+        assertTrue("Should include ':util-android' project") {
+            result.output.contains("Project ':util-android'")
+        }
+        assertFalse(
+            "Shouldn't include ':build-logic' project " +
+                    "because it's a nested project"
+        ) {
+            result.output.contains("Project ':build-logic'")
+        }
+        assertFalse(
+            "Shouldn't include ':build-logic:conventions' project " +
+                    "because it's a subproject of a nested project"
+        ) {
+            result.output.contains("Project ':build-logic-conventions'")
+        }
+    }
+
+    @Test
+    fun `include projects with 'arbitraryBuildScriptNames=true' option`() {
+        // Enable option `arbitraryBuildScriptNames`
+        projectDir.resolve("settings.gradle.kts").appendText("""
+            includer {
+                arbitraryBuildScriptNames = true
+            }
+        """.trimIndent())
+
+        // Run the build
+        val runner = GradleRunner.create()
+        runner.forwardOutput()
+        runner.withPluginClasspath()
+        runner.withArguments("projects")
+        runner.withProjectDir(projectDir)
+        val result = runner.build()
+
+        // Verify the result
+        assertTrue("Should include ':app' project") {
+            result.output.contains("Project ':app'")
+        }
+        assertTrue("Should include ':feature1-api' project" +
+                "because 'arbitraryBuildScriptNames = true'") {
+            result.output.contains("Project ':feature1-api'")
+        }
+        assertTrue("Should include ':feature1-impl' project" +
+                "because 'arbitraryBuildScriptNames = true'") {
+            result.output.contains("Project ':feature1-impl'")
+        }
+        assertTrue("Should include ':util-android' project") {
+            result.output.contains("Project ':util-android'")
+        }
+        assertFalse(
+            "Shouldn't include ':build-logic' project " +
+                    "because it's a nested project"
+        ) {
+            result.output.contains("Project ':build-logic'")
+        }
+        assertFalse(
+            "Shouldn't include ':build-logic:conventions' project " +
+                    "because it's a subproject of a nested project"
+        ) {
+            result.output.contains("Project ':build-logic-conventions'")
+        }
+    }
+
+
+    @Test
+    fun `include projects with 'excludeFolders' option`() {
+        // Exclude additional folders with `excludeFolders(...)`
+        projectDir.resolve("settings.gradle.kts").appendText("""
+            includer {
+                excludeFolders("android", "impl")
+            }
+        """.trimIndent())
+
+        // Run the build
+        val runner = GradleRunner.create()
+        runner.forwardOutput()
+        runner.withPluginClasspath()
+        runner.withArguments("projects")
+        runner.withProjectDir(projectDir)
+        val result = runner.build()
+
+        // Verify the result
+        assertTrue("Should include ':app' project") {
+            result.output.contains("Project ':app'")
+        }
+        assertFalse(
+            "Shouldn't include ':feature1-api' project " +
+                    "because this project has a non-standard build file name"
+        ) {
+            result.output.contains("Project ':feature1-api'")
+        }
+        assertFalse(
+            "Shouldn't include ':feature1-impl' project " +
+                    "because this project has a non-standard build file name"
+        ) {
+            result.output.contains("Project ':feature1-impl'")
+        }
+        assertFalse(
+            "Shouldn't include ':util-android' project " +
+                    "because its folder name is in ignored folder names"
+        ) {
+            result.output.contains("Project ':util-android'")
+        }
+        assertFalse(
+            "Shouldn't include ':build-logic' project " +
+                    "because it's a nested project"
+        ) {
+            result.output.contains("Project ':build-logic'")
+        }
+        assertFalse(
+            "Shouldn't include ':build-logic:conventions' project " +
+                    "because it's a subproject of a nested project"
+        ) {
+            result.output.contains("Project ':build-logic-conventions'")
+        }
+    }
+
+    @Test
+    fun `include projects with multiple build files`() {
+        // Enable option `arbitraryBuildScriptNames`
+        projectDir.resolve("settings.gradle.kts").appendText("""
+            includer {
+                arbitraryBuildScriptNames = true
+            }
+        """.trimIndent())
+
+        // Create a second build file in addition to the existing one
+        projectDir.resolve("app/something.gradle").createNewFile()
+
+        // Run the build
+        val runner = GradleRunner.create()
+        runner.forwardOutput()
+        runner.withPluginClasspath()
+        runner.withArguments("projects")
+        runner.withProjectDir(projectDir)
+
+        // Verify the result
+        val exception = assertThrows<Exception>("The build should fail") {
+            runner.build()
+        }
+        assertTrue("Should detect more than one build file in :app module") {
+            exception.message?.contains("app has more than one gradle build file") == true
+        }
     }
 }

includer/plugin/src/main/kotlin/Dsl.kt

@@ -0,0 +1,5 @@
+import org.gradle.api.initialization.Settings
+import tools.forma.includer.IncluderExtension
+
+fun Settings.includer(action: IncluderExtension.() -> Unit) =
+    extensions.getByType(IncluderExtension::class.java).action()