Add task for generating archrules documentation in library plugin (#57)

Author: emilyyuan03

README.md

@@ -76,6 +76,11 @@ You may declare dependencies on the `archRulesImplementation` configuration. Thi
 1) using a dependency as helper for your rule code
 2) transitively depending on a standalone rules library so that its rules are run in any project which runs the current project's rules
 
+#### Automated Documentation
+
+The ArchRules Library plugin provides the `generateRulesDocumentation` task to generate markdown documentation for all of your library's rules authored in the `archRules` source set.
+Running `./gradlew generateRulesDocumentation` creates documentation at `build/docs/archrules.md`, which includes all rules, descriptions, and priorities.
+
 ### Testing Rules
 
 The ArchRules Library plugin creates a test suite called `archRulesTest`. You can write unit tests for your rules in the `archRulesTest` source set.

nebula-archrules-gradle-plugin/src/main/kotlin/com/netflix/nebula/archrules/gradle/ArchrulesLibraryPlugin.kt

@@ -3,7 +3,6 @@ package com.netflix.nebula.archrules.gradle
 import com.netflix.nebula.archrules.gradle.ArchRuleAttribute.ARCH_RULES
 import org.gradle.api.Plugin
 import org.gradle.api.Project
-import org.gradle.api.artifacts.type.ArtifactTypeDefinition
 import org.gradle.api.attributes.Usage
 import org.gradle.api.component.AdhocComponentWithVariants
 import org.gradle.api.internal.artifacts.dsl.LazyPublishArtifact
@@ -74,6 +73,15 @@ class ArchrulesLibraryPlugin : Plugin<Project> {
                 archiveClassifier.set("arch-rules")
                 dependsOn(generateServicesTask)
             }
+            project.tasks.register<GenerateRulesDocumentationTask>("generateRulesDocumentation") {
+                description = "Generates documentation for ArchRules"
+                group = "documentation"
+                rulesClasspath.from(archRulesSourceSet.output)
+                outputFile.convention(
+                    project.layout.buildDirectory.file("docs/archrules.md")
+                )
+                dependsOn(generateServicesTask)
+            }
             registerRuntimeFeatureForSourceSet(project, archRulesSourceSet, jarTask)
             project.pluginManager.withPlugin("jvm-test-suite") {
                 val ext = project.extensions.getByType<TestingExtension>()

nebula-archrules-gradle-plugin/src/main/kotlin/com/netflix/nebula/archrules/gradle/GenerateRulesDocumentationTask.kt

@@ -0,0 +1,81 @@
+package com.netflix.nebula.archrules.gradle
+
+import com.netflix.nebula.archrules.core.ArchRulesService
+import com.netflix.nebula.archrules.core.Runner
+import com.tngtech.archunit.lang.ArchRule
+import com.tngtech.archunit.lang.Priority
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.tasks.CacheableTask
+import org.gradle.api.tasks.Classpath
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.TaskAction
+import java.net.URLClassLoader
+import java.util.ServiceLoader
+
+@CacheableTask
+abstract class GenerateRulesDocumentationTask : DefaultTask() {
+
+    @get:Classpath
+    abstract val rulesClasspath: ConfigurableFileCollection
+
+    @get:OutputFile
+    abstract val outputFile: RegularFileProperty
+
+    @TaskAction
+    fun generateDocs() {
+        val rules = mutableListOf<RuleMetadata>()
+        val classPathUrls = rulesClasspath.files.map { it.toURI().toURL() }.toTypedArray()
+
+        URLClassLoader(classPathUrls, this.javaClass.classLoader).use { classLoader ->
+            ServiceLoader.load(ArchRulesService::class.java, classLoader).forEach { service ->
+                val serviceClassName = service.javaClass.name
+                service.rules.forEach { (ruleName, archRule) ->
+                    rules.add(
+                        RuleMetadata(
+                            ruleClass = serviceClassName,
+                            ruleName = ruleName,
+                            description = archRule.description,
+                            priority = getPriority(archRule)
+                        )
+                    )
+                }
+            }
+        }
+
+        val output = outputFile.get().asFile
+        output.parentFile.mkdirs()
+        output.writeText(formatMarkdown(rules))
+    }
+
+    private fun formatMarkdown(rules: List<RuleMetadata>): String {
+        val str = StringBuilder()
+        str.append("# ArchRules Documentation\n\n")
+        str.append("List of all archrules defined in this library.\n\n")
+
+        val sortedRulesByName = rules.sortedBy { it.ruleName }
+        sortedRulesByName.forEach { rule ->
+            str.append("## ${rule.ruleName}\n\n")
+            str.append("**Description:** ${rule.description}\n\n")
+            str.append("**Priority:** ${rule.priority}\n\n")
+            str.append("**Class:** `${rule.ruleClass}`\n\n")
+            str.append("---\n\n")
+        }
+
+        return str.toString()
+    }
+
+    // workaround since ArchRule priority is private
+    private fun getPriority(archRule: ArchRule): Priority {
+        val dummyResult = Runner.check(archRule)
+        return dummyResult.priority
+    }
+
+    private data class RuleMetadata(
+        val ruleClass: String,
+        val ruleName: String,
+        val description: String,
+        val priority: Priority
+    )
+}

nebula-archrules-gradle-plugin/src/test/kotlin/com/netflix/nebula/archrules/gradle/ArchrulesLibraryPluginTest.kt

@@ -331,4 +331,57 @@ class ArchrulesLibraryPluginTest {
             .hasNoMutableStateWarnings()
             .hasNoDeprecationWarnings()
     }
-}
+
+
+    @Test
+    fun `test generateRulesDocumentation task`() {
+        val runner = testProject(projectDir) {
+            properties {
+                buildCache(true)
+            }
+            settings {
+                name("library-with-rules")
+            }
+            rootProject {
+                plugins {
+                    id("java-library")
+                    id("com.netflix.nebula.archrules.library")
+                }
+                repositories {
+                    maven("https://netflixoss.jfrog.io/artifactory/gradle-plugins")
+                    mavenCentral()
+                }
+                src {
+                    sourceSet("archRules") {
+                        dontUseRule()
+                        exampleDeprecatedHighArchRule()
+                    }
+                }
+                dependencies("""
+                    archRulesImplementation("com.netflix.nebula:archrules-nullability:0.+")
+                """.trimIndent()
+                )
+            }
+        }
+
+        val result = runner.run("generateRulesDocumentation", "--stacktrace") {
+            forwardOutput()
+        }
+
+        assertThat(result.task(":generateRulesDocumentation"))
+            .hasOutcome(TaskOutcome.SUCCESS, TaskOutcome.FROM_CACHE)
+
+        val docsFile = projectDir.resolve("build/docs/archrules.md")
+        assertThat(docsFile).exists()
+
+        assertThat(docsFile.readText())
+            .contains("# ArchRules Documentation")
+            .contains("## deprecated\n" +
+                "\n" +
+                "**Description:** No code should reference deprecated APIs, because usage of deprecated APIs introduces risk that future upgrades and migrations will be blocked\n" +
+                "\n" +
+                "**Priority:** HIGH")
+            .contains("## dont use")
+            .doesNotContain("## public classes should be @NullMarked")
+    }
+}