chore(library): add Detekt rule for forbidding enums (#2339)

Part of
#1578.

The goal is to prevent us from using enums that are problematic when it
comes to using values that aren't known when publishing a given version
of the library. We should generally use sealed interfaces/classes with
sth like `class Custom(val value: String)`. This Detekt rule can be
skipped for legitimate cases, on a case basis.

Author: krzema12

github-workflows-kt/build.gradle.kts

@@ -19,6 +19,11 @@ plugins {
     id("org.jetbrains.dokka") version "2.2.0"
 }
 
+detekt {
+    buildUponDefaultConfig = true
+    config.setFrom("$projectDir/detekt.yml")
+}
+
 group = rootProject.group
 version = rootProject.version
 
@@ -35,6 +40,7 @@ dependencies {
     testImplementation(kotlin("compiler"))
     testImplementation(kotlin("reflect"))
     testImplementation(projects.testUtils)
+    detektPlugins(project(":github-workflows-kt:detekt-rules"))
 
     // GitHub action bindings
     testImplementation("actions:checkout:v4")
@@ -85,3 +91,7 @@ tasks.withType<FormatTask> {
 dokka {
     moduleName.set("github-workflows-kt")
 }
+
+apiValidation {
+    ignoredProjects.addAll(listOf("detekt-rules"))
+}

github-workflows-kt/detekt-rules/build.gradle.kts

@@ -0,0 +1,10 @@
+plugins {
+    buildsrc.convention.`kotlin-jvm`
+}
+
+dependencies {
+    compileOnly("io.gitlab.arturbosch.detekt:detekt-api:1.23.8")
+
+    testImplementation("io.gitlab.arturbosch.detekt:detekt-test:1.23.8")
+    testImplementation("org.jetbrains.kotlin:kotlin-compiler-embeddable")
+}

github-workflows-kt/detekt-rules/src/main/kotlin/io/github/typesafegithub/workflows/detekt/rules/NoEnumRule.kt

@@ -0,0 +1,45 @@
+package io.github.typesafegithub.workflows.detekt.rules
+
+import io.gitlab.arturbosch.detekt.api.CodeSmell
+import io.gitlab.arturbosch.detekt.api.Config
+import io.gitlab.arturbosch.detekt.api.Debt
+import io.gitlab.arturbosch.detekt.api.Entity
+import io.gitlab.arturbosch.detekt.api.Issue
+import io.gitlab.arturbosch.detekt.api.Rule
+import io.gitlab.arturbosch.detekt.api.Severity
+import org.jetbrains.kotlin.psi.KtClass
+import org.jetbrains.kotlin.psi.KtClassOrObject
+
+public class NoEnumRule(
+    config: Config,
+) : Rule(config) {
+    private companion object {
+        private const val RATIONALE =
+            "GitHub Actions' API may require or return values that weren't anticipated when this library was " +
+                "published. Sealed interfaces/classes allow adding a class that accepts an arbitrary value as " +
+                "an escape hatch."
+    }
+
+    override val issue: Issue =
+        Issue(
+            id = "NoEnum",
+            severity = Severity.Style,
+            description = "Enums are forbidden. Use sealed interfaces/classes instead. $RATIONALE",
+            debt = Debt.FIVE_MINS,
+        )
+
+    override fun visitClassOrObject(classOrObject: KtClassOrObject) {
+        if (classOrObject is KtClass && classOrObject.isEnum()) {
+            report(
+                CodeSmell(
+                    issue = issue,
+                    entity = Entity.from(classOrObject),
+                    message =
+                        "Enum class '${classOrObject.name}' is forbidden. Use a sealed interface/class instead. " +
+                            RATIONALE,
+                ),
+            )
+        }
+        super.visitClassOrObject(classOrObject)
+    }
+}

github-workflows-kt/detekt-rules/src/main/kotlin/io/github/typesafegithub/workflows/detekt/rules/NoEnumRuleSetProvider.kt

@@ -0,0 +1,15 @@
+package io.github.typesafegithub.workflows.detekt.rules
+
+import io.gitlab.arturbosch.detekt.api.Config
+import io.gitlab.arturbosch.detekt.api.RuleSet
+import io.gitlab.arturbosch.detekt.api.RuleSetProvider
+
+public class NoEnumRuleSetProvider : RuleSetProvider {
+    override val ruleSetId: String = "custom-style"
+
+    override fun instance(config: Config): RuleSet =
+        RuleSet(
+            id = ruleSetId,
+            rules = listOf(NoEnumRule(config)),
+        )
+}

github-workflows-kt/detekt-rules/src/main/resources/META-INF/services/io.gitlab.arturbosch.detekt.api.RuleSetProvider

@@ -0,0 +1 @@
+io.github.typesafegithub.workflows.detekt.rules.NoEnumRuleSetProvider

github-workflows-kt/detekt-rules/src/test/kotlin/io/github/typesafegithub/workflows/detekt/rules/NoEnumRuleTest.kt

@@ -0,0 +1,37 @@
+package io.github.typesafegithub.workflows.detekt.rules
+
+import io.gitlab.arturbosch.detekt.test.TestConfig
+import io.gitlab.arturbosch.detekt.test.compileAndLint
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+
+class NoEnumRuleTest :
+    FunSpec({
+        test("reports enum class") {
+            val code = """
+                enum class Color { RED, GREEN, BLUE }
+            """
+            val findings = NoEnumRule(TestConfig()).compileAndLint(code)
+            findings.size shouldBe 1
+        }
+
+        test("does not report sealed class") {
+            val code = """
+                sealed class Color {
+                    data object RED : Color()
+                    data object GREEN : Color()
+                    data object BLUE : Color()
+                }
+            """
+            val findings = NoEnumRule(TestConfig()).compileAndLint(code)
+            findings.size shouldBe 0
+        }
+
+        test("does not report regular class") {
+            val code = """
+                class Foo
+            """
+            val findings = NoEnumRule(TestConfig()).compileAndLint(code)
+            findings.size shouldBe 0
+        }
+    })

github-workflows-kt/detekt.yml

@@ -0,0 +1,3 @@
+custom-style:
+  NoEnum:
+    active: true

settings.gradle.kts

@@ -11,6 +11,7 @@ include(
     "shared-internal",
     "code-generator",
     "test-utils",
+    "github-workflows-kt:detekt-rules",
 )
 
 plugins {