Create rule S6519(Kotlin): Structural equality tests should use "==" (#1630)

rules/S6519/kotlin/metadata.json

@@ -0,0 +1,17 @@
+{
+  "title": "Structural equality tests should use \"==\"",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-6519",
+  "sqKey": "S6519",
+  "scope": "All",
+  "defaultQualityProfiles": ["Sonar way"],
+  "quickfix": "unknown"
+}

rules/S6519/kotlin/rule.adoc

@@ -0,0 +1,65 @@
+== Why is this an issue?
+
+In Kotlin, `==` means structural equality and maps to the left-side term's `equals()` function.
+It is, therefore, redundant to call `equals()` as a function.
+Also, `==` is more general than `equals()` because it allows either of both operands to be `null`.
+
+Developers using `equals()` instead of `==` is often the result of adapting
+styles from other languages like Java, where `==` means reference equality.
+
+=== What is the potential impact?
+
+==== Wrong logic
+
+`==` allows either of both operands to be `null`, while `equals()` doesn't.
+
+==== Readability and Understanding
+
+The `==` operator is a more concise and elegant way to test structural equality than calling a function.
+
+== How to fix it
+
+Replace `a.equals(b)` with `a == b`.
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,kotlin]
+----
+data class Person(
+    val name: String,
+    val firstName: String,
+    val age: Int,
+    val address: String
+)
+----
+
+[source,kotlin,diff-id=1,diff-type=noncompliant]
+----
+fun checkEquality() {
+    val personA = Person("Claus", "Santa", 200, "North Pole")
+    val personB = Person("Nicholas", "Saint", 1700, "Myra")
+    personA.name.equals(personB.name) // Noncompliant, should use `==` instead
+    personA.equals(personB) // Noncompliant, should use `==` instead
+}
+----
+
+==== Compliant solution
+
+[source,kotlin,diff-id=1,diff-type=compliant]
+----
+fun checkEquality() {
+    val personA = Person("Claus", "Santa", 200, "North Pole")
+    val personB = Person("Nicholas", "Saint", 1700, "Myra")
+    personA.name == personB.name // Compliant
+    personA == personB // Compliant
+}
+----
+
+== Resources
+
+=== Documentation
+
+* https://kotlinlang.org/docs/operator-overloading.html#equality-and-inequality-operators[Kotlin Docs, Equality and inequality operators]
+

rules/S6519/metadata.json

@@ -0,0 +1,2 @@
+{
+}