Report KDoc comments that refer to encapsulated properties of a class

New rule to address the issue of breaking encapsulation principle when KDoc comments have references to encapsulated (private) properties.
Clients do not need to know the implementation details.

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

@@ -67,6 +67,9 @@ comments:
     matchTypeParameters: true
     matchDeclarationsOrder: true
     allowParamOnConstructorProperties: false
+  ReferencedEncapsulatedProperty:
+    active: false
+    excludes: ['**/test/**', '**/androidTest/**', '**/commonTest/**', '**/jvmTest/**', '**/jsTest/**', '**/iosTest/**']
   UndocumentedPublicClass:
     active: false
     excludes: ['**/test/**', '**/androidTest/**', '**/commonTest/**', '**/jvmTest/**', '**/jsTest/**', '**/iosTest/**']

detekt-generator/src/main/kotlin/io/gitlab/arturbosch/detekt/generator/printer/defaultconfig/Exclusion.kt

@@ -41,6 +41,7 @@ private object TestExclusions : Exclusions() {
         "UndocumentedPublicFunction",
         "UndocumentedPublicProperty",
         "UnsafeCallOnNullableType",
+        "ReferencedEncapsulatedProperty",
     )
 }
 

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/CommentSmellProvider.kt

@@ -24,7 +24,8 @@ class CommentSmellProvider : DefaultRuleSetProvider {
             UndocumentedPublicClass(config),
             UndocumentedPublicFunction(config),
             UndocumentedPublicProperty(config),
-            AbsentOrWrongFileLicense(config)
+            AbsentOrWrongFileLicense(config),
+            ReferencedEncapsulatedProperty(config)
         )
     )
 }

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/ReferencedEncapsulatedProperty.kt

@@ -0,0 +1,77 @@
+package io.gitlab.arturbosch.detekt.rules.documentation
+
+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.KtNamedDeclaration
+import org.jetbrains.kotlin.psi.KtObjectDeclaration
+import org.jetbrains.kotlin.psi.KtProperty
+import org.jetbrains.kotlin.psi.psiUtil.containingClassOrObject
+import org.jetbrains.kotlin.psi.psiUtil.getTopmostParentOfType
+import org.jetbrains.kotlin.psi.psiUtil.isPublic
+
+/**
+ * This rule will report any KDoc comments that refer to encapsulated properties of a class.
+ * Clients do not need to know the implementation details.
+ * See [Encapsulation](https://en.wikipedia.org/wiki/Encapsulation_(computer_programming))
+ */
+class ReferencedEncapsulatedProperty(config: Config = Config.empty) : Rule(config) {
+
+    override val issue = Issue(
+        javaClass.simpleName,
+        Severity.Maintainability,
+        "KDoc comments should not refer to encapsulated properties.",
+        Debt.FIVE_MINS
+    )
+
+    override fun visitProperty(property: KtProperty) {
+        val enclosingClass = property.getTopmostParentOfType<KtClass>()
+        val comment = enclosingClass?.docComment?.text ?: return
+
+        if (property.isEncapsulatedInherited() && property.isReferencedInherited(comment)) {
+            report(property)
+        }
+
+        super.visitProperty(property)
+    }
+
+    private fun KtProperty.isEncapsulatedInherited(): Boolean {
+        if (!isPublic) {
+            return true
+        }
+        var classOrObject = containingClassOrObject
+        while (classOrObject != null && classOrObject is KtObjectDeclaration) {
+            if (!classOrObject.isPublic) {
+                return true
+            }
+            classOrObject = classOrObject.containingClassOrObject
+        }
+        return false
+    }
+
+    private fun KtProperty.isReferencedInherited(comment: String): Boolean {
+        var qualifiedName = nameAsSafeName.asString()
+        var classOrObject = containingClassOrObject
+        while (classOrObject != null && classOrObject is KtObjectDeclaration) {
+            qualifiedName = "${classOrObject.nameAsSafeName.asString()}.$qualifiedName"
+            classOrObject = classOrObject.containingClassOrObject
+        }
+        return comment.contains("[$qualifiedName]")
+    }
+
+    private fun report(property: KtNamedDeclaration) {
+        report(
+            CodeSmell(
+                issue,
+                Entity.atName(property),
+                "The property ${property.nameAsSafeName} " +
+                    "is encapsulated and should not be referenced from KDoc comments."
+            )
+        )
+    }
+}

detekt-rules-documentation/src/test/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/ReferencedEncapsulatedPropertySpec.kt

@@ -0,0 +1,98 @@
+package io.gitlab.arturbosch.detekt.rules.documentation
+
+import io.gitlab.arturbosch.detekt.test.compileAndLint
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.jupiter.api.Nested
+import org.junit.jupiter.api.Test
+
+class ReferencedEncapsulatedPropertySpec {
+    val subject = ReferencedEncapsulatedProperty()
+
+    @Nested
+    inner class `ReferencedEncapsulatedProperty rule` {
+
+        @Test
+        fun `reports referenced encapsulated properties`() {
+            val code = """ 
+            /**
+             * Comment
+             * [prop1] - encapsulated property
+             * [prop2] - public property
+             */
+            class Test {
+                private val prop1 = 0 // report
+                val prop2 = 0 // do not report
+            }
+            """.trimIndent()
+            assertThat(subject.compileAndLint(code)).hasSize(1)
+        }
+
+        @Test
+        fun `reports referenced encapsulated properties in private class`() {
+            val code = """ 
+            /**
+             * Comment
+             * [prop1] - encapsulated property
+             * [prop2] - public property
+             */
+            private class Test {
+                private val prop1 = 0 // report
+                val prop2 = 0 // do not report
+            }
+            """.trimIndent()
+            assertThat(subject.compileAndLint(code)).hasSize(1)
+        }
+
+        @Test
+        fun `reports referenced encapsulated properties in nested objects`() {
+            val code = """ 
+            /**
+             * Comment
+             * [prop1] - encapsulated property
+             * [A.prop2] - encapsulated property
+             * [A.B.prop3] - encapsulated property
+             * [A.C.prop4] - encapsulated property
+             */
+            class Test {
+                private val prop1 = 0
+                
+                object A {
+                    private val prop2 = 0
+                    
+                    private object B {
+                        val prop3 = 0
+                    }
+                    object C {
+                        private val prop4 = 0
+                    }
+                }
+            }
+            """.trimIndent()
+            assertThat(subject.compileAndLint(code)).hasSize(4)
+        }
+
+        @Test
+        fun `does not report referenced public properties in nested objects`() {
+            val code = """ 
+            /**
+             * Comment
+             * [prop1] - public property
+             * [A.B.prop2] - public property
+             * [C.prop3] - public property
+             */
+            class Test {
+                val prop1 = 0
+                object A {
+                    object B {
+                        val prop2 = 0
+                    }
+                }
+                object C {
+                    val prop3 = 0
+                }
+            }
+            """.trimIndent()
+            assertThat(subject.compileAndLint(code)).isEmpty()
+        }
+    }
+}