Add comments with a list of regexes to ForbiddenComment

detekt-core/src/main/resources/default-detekt-config.yml

@@ -566,12 +566,14 @@ style:
         value: 'java.lang.annotation.Inherited'
   ForbiddenComment:
     active: true
-    values:
-      - 'FIXME:'
-      - 'STOPSHIP:'
-      - 'TODO:'
+    comments:
+      - reason: 'some fixes are pending.'
+        value: 'FIXME:'
+      - reason: 'some changes are present which needs to be addressed before ship.'
+        value: 'STOPSHIP:'
+      - reason: 'some changes are pending.'
+        value: 'TODO:'
     allowedPatterns: ''
-    customMessage: ''
   ForbiddenImport:
     active: false
     imports: []

detekt-core/src/main/resources/deprecation.properties

@@ -16,6 +16,8 @@ potential-bugs>IgnoredReturnValue>restrictToAnnotatedMethods=Use `restrictToConf
 potential-bugs>LateinitUsage>excludeAnnotatedProperties=Use `ignoreAnnotated` instead
 potential-bugs>MissingWhenCase=Rule deprecated as compiler performs this check by default
 potential-bugs>RedundantElseInWhen=Rule deprecated as compiler performs this check by default
+style>ForbiddenComment>customMessage=Use `comments` and provide `reason` against each `value`
+style>ForbiddenComment>values=Use `comments` instead, make sure you escape your text for Regular Expressions.
 style>ForbiddenPublicDataClass=Rule migrated to `libraries` ruleset plugin
 style>FunctionOnlyReturningConstant>excludeAnnotatedFunction=Use `ignoreAnnotated` instead
 style>LibraryCodeMustSpecifyReturnType=Rule migrated to `libraries` ruleset plugin

detekt-rules-style/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/style/ForbiddenComment.kt

@@ -10,6 +10,7 @@ import io.gitlab.arturbosch.detekt.api.Severity
 import io.gitlab.arturbosch.detekt.api.config
 import io.gitlab.arturbosch.detekt.api.internal.ActiveByDefault
 import io.gitlab.arturbosch.detekt.api.internal.Configuration
+import io.gitlab.arturbosch.detekt.api.valuesWithReason
 import org.jetbrains.kotlin.com.intellij.psi.PsiComment
 import org.jetbrains.kotlin.com.intellij.psi.PsiElement
 import org.jetbrains.kotlin.kdoc.psi.impl.KDocSection
@@ -38,17 +39,30 @@ class ForbiddenComment(config: Config = Config.empty) : Rule(config) {
     )
 
     @Configuration("forbidden comment strings")
-    private val values: List<String> by config(listOf("FIXME:", "STOPSHIP:", "TODO:"))
+    @Deprecated("Use `comments` instead, make sure you escape your text for Regular Expressions.")
+    private val values: List<String> by config(emptyList())
+
+    @Configuration("forbidden comment string patterns")
+    private val comments: List<Comment> by config(
+        valuesWithReason(
+            "FIXME:" to "some fixes are pending.",
+            "STOPSHIP:" to "some changes are present which needs to be addressed before ship.",
+            "TODO:" to "some changes are pending.",
+        )
+    ) { list ->
+        list.map { Comment(it.value.toRegex(), it.reason) }
+    }
 
     @Configuration("ignores comments which match the specified regular expression. For example `Ticket|Task`.")
     private val allowedPatterns: Regex by config("", String::toRegex)
 
     @Configuration("error message which overrides the default one")
+    @Deprecated("Use `comments` and provide `reason` against each `value`")
     private val customMessage: String by config("")
 
     override fun visitComment(comment: PsiComment) {
         super.visitComment(comment)
-        val text = comment.text
+        val text = comment.getContent()
         checkForbiddenComment(text, comment)
     }
 
@@ -63,6 +77,7 @@ class ForbiddenComment(config: Config = Config.empty) : Rule(config) {
     private fun checkForbiddenComment(text: String, comment: PsiElement) {
         if (allowedPatterns.pattern.isNotEmpty() && allowedPatterns.containsMatchIn(text)) return
 
+        @Suppress("DEPRECATION")
         values.forEach {
             if (text.contains(it, ignoreCase = true)) {
                 report(
@@ -74,13 +89,82 @@ class ForbiddenComment(config: Config = Config.empty) : Rule(config) {
                 )
             }
         }
+
+        comments.forEach {
+            if (it.value.containsMatchIn(text)) {
+                report(
+                    CodeSmell(
+                        issue,
+                        Entity.from(comment),
+                        getErrorMessage(it)
+                    )
+                )
+            }
+        }
     }
 
+    private fun PsiComment.getContent(): String = text.getCommentContent()
+
+    private fun getErrorMessage(comment: Comment): String =
+        comment.reason
+            ?.let { reason -> String.format(DEFAULT_ERROR_MESSAGE, comment.value.pattern, reason) }
+            ?: String.format(DEFAULT_ERROR_MESSAGE_WITH_NO_REASON, comment.value.pattern)
+
+    @Suppress("DEPRECATION")
     private fun getErrorMessage(value: String): String =
-        customMessage.takeUnless { it.isEmpty() } ?: String.format(DEFAULT_ERROR_MESSAGE, value)
+        customMessage.takeUnless { it.isEmpty() } ?: String.format(DEFAULT_ERROR_MESSAGE_WITH_NO_REASON, value)
+
+    private data class Comment(val value: Regex, val reason: String?)
 
     companion object {
-        const val DEFAULT_ERROR_MESSAGE = "This comment contains '%s' " +
+        const val DEFAULT_ERROR_MESSAGE_WITH_NO_REASON = "This comment contains '%s' " +
             "that has been defined as forbidden in detekt."
+
+        const val DEFAULT_ERROR_MESSAGE = "This comment contains '%s' " +
+            "that has been forbidden: %s."
     }
 }
+
+internal fun String.getCommentContent(): String {
+    return if (this.startsWith("//")) {
+        this.removePrefix("//").removePrefix(" ")
+    } else {
+        this
+            .trimIndentIgnoringFirstLine()
+            // Process line by line.
+            .lineSequence()
+            // Remove starting, aligning and ending markers.
+            .map {
+                it
+                    .let { fullLine ->
+                        val trimmedStartLine = fullLine.trimStart()
+                        if (trimmedStartLine.startsWith("/*")) {
+                            trimmedStartLine.removePrefix("/*").removePrefix(" ")
+                        } else if (trimmedStartLine.startsWith("*") && trimmedStartLine.startsWith("*/").not()) {
+                            trimmedStartLine.removePrefix("*").removePrefix(" ")
+                        } else {
+                            fullLine
+                        }
+                    }
+                    .let { lineWithoutStartMarker ->
+                        if (lineWithoutStartMarker.endsWith("*/")) {
+                            lineWithoutStartMarker.removeSuffix("*/").removeSuffix(" ")
+                        } else {
+                            lineWithoutStartMarker
+                        }
+                    }
+            }
+            // Trim trailing empty lines.
+            .dropWhile(String::isEmpty)
+            // Reconstruct the comment contents.
+            .joinToString("\n")
+    }
+}
+
+private fun String.trimIndentIgnoringFirstLine(): String =
+    if ('\n' !in this) {
+        this
+    } else {
+        val lines = this.lineSequence()
+        lines.first() + "\n" + lines.drop(1).joinToString("\n").trimIndent()
+    }