Add new experimental rule chain-method-continuation

CHANGELOG.md

@@ -8,6 +8,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 * Add experimental rule `class-signature`. This rule rewrites the class header to a consistent format. In code style `ktlint_official`, super types are always wrapped to a separate line. In other code styles, super types are only wrapped in classes having multiple super types. Especially for code style `ktlint_official` the class headers are rewritten in a more consistent format. See [examples in documentation](https://pinterest.github.io/ktlint/latest/rules/experimental/#class-signature). `class-signature` [#875](https://github.com/pinterest/ktlint/issues/1349), [#1349](https://github.com/pinterest/ktlint/issues/875)
 * Add experimental rule `function-expression-body`. This rule rewrites function bodies only contain a `return` or `throw` expression to an expression body. [#2150](https://github.com/pinterest/ktlint/issues/2150)
+* Add experimental rule `chain-method-continuation` to the `ktlint_official` code style, but it can be enabled explicitly for the other code styles as well. This rule requires the operators (`.` or `?.`) for chaining method calls, to be aligned with each other. This rule is enabled by ([#1953](https://github.com/pinterest/ktlint/issues/1953))
 
 ### Removed
 * As a part of public API stabilization, data classes are no longer used in the public API. As of that, functions like `copy()` or `componentN()` (used for destructuring declarations) are not available anymore. This is a binary incompatible change, breaking backwards compatibility. ([#2133](https://github.com/pinterest/ktlint/issues/2133))

build-logic/build.gradle.kts

@@ -10,7 +10,14 @@ repositories {
 }
 
 kotlin {
-    jvmToolchain(libs.versions.java.compilation.get().toInt())
+    jvmToolchain(
+        libs
+            .versions
+            .java
+            .compilation
+            .get()
+            .toInt(),
+    )
 }
 
 // TODO: Remove setting `options.release` and `compilerOptions.jvmTarget` after upgrade to Kotlin Gradle Plugin 1.9

build-logic/src/main/kotlin/ktlint-kotlin-common.gradle.kts

@@ -56,7 +56,12 @@ tasks.withType<Test>().configureEach {
             (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1
         }
 
-    if (javaLauncher.get().metadata.languageVersion.canCompileOrRun(JavaLanguageVersion.of(11))) {
+    if (javaLauncher
+            .get()
+            .metadata
+            .languageVersion
+            .canCompileOrRun(JavaLanguageVersion.of(11))
+    ) {
         // workaround for https://github.com/pinterest/ktlint/issues/1618. Java 11 started printing warning logs. Java 16 throws an error
         jvmArgs("--add-opens=java.base/java.lang=ALL-UNNAMED")
     }

build.gradle.kts

@@ -4,7 +4,14 @@ plugins {
     alias(libs.plugins.kotlin.jvm) apply false
     alias(libs.plugins.checksum) apply false
     alias(libs.plugins.shadow) apply false
-    alias(libs.plugins.kotlinx.binary.compatibiltiy.validator)
+    alias(
+        libs
+            .plugins
+            .kotlinx
+            .binary
+            .compatibiltiy
+            .validator,
+    )
 }
 
 val internalNonPublishableProjects by extra(
@@ -57,6 +64,9 @@ tasks.register<JavaExec>("ktlintFormat") {
 
 tasks.wrapper {
     distributionSha256Sum =
-        URI.create("$distributionUrl.sha256").toURL()
-            .openStream().use { it.reader().readText().trim() }
+        URI
+            .create("$distributionUrl.sha256")
+            .toURL()
+            .openStream()
+            .use { it.reader().readText().trim() }
 }

documentation/release-latest/docs/rules/experimental.md

@@ -930,3 +930,54 @@ A function, class/object body or other block body statement has to be placed on
     ```
 
 Rule id: `statement-wrapping`
+
+### Chain method continuation
+
+In multi line method chain, this rule requires a chain operators(`.` or `?.`) to be aligned with the next method or in case when previous ending brace is `}` then it should also be aligned with chain operator method call.
+
+=== "[:material-heart:](#) Ktlint"
+
+    ```kotlin
+    val foo1 = listOf(1, 2, 3).
+                filter { it > 2 }!!.
+                takeIf { it > 2 }.
+                map {
+                    it * it
+                }?.
+                map {
+                    it * it
+                }
+    val foo2 = listOf(1, 2, 3)
+                .filter {
+                    it > 2
+                }
+                .map {
+                    2 * it
+                }
+                ?.map {
+                    2 * it
+                }
+    ```
+
+=== "[:material-heart-off-outline:](#) Disallowed"
+
+    ```kotlin
+    val foo1 = listOf(1, 2, 3)
+                .filter { it > 2 }!!
+                .takeIf { it > 2 }
+                .map {
+                    it * it
+                }?.map {
+                    it * it
+                }
+    val foo2 = listOf(1, 2, 3)
+                .filter {
+                    it > 2
+                }.map {
+                    2 * it
+                }?.map {
+                    2 * it
+                }
+    ```
+
+Rule id: `chain-method-continuation` (`standard` rule set)

documentation/snapshot/docs/rules/configuration-ktlint.md

@@ -54,6 +54,20 @@ insert_final_newline = true
 
 This setting only takes effect when rule `final-newline` is enabled.
 
+## Force multiline chained methods based on number of chain operators
+
+Setting `ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than` forces a chained method to be wrapped at each chain operator (`.` or `?.`) in case it contains the specified minimum number of chain operators even in case the entire chained method fits on a single line. Use value `unset` (default) to disable this setting.
+
+!!! note
+    By default, chained methods are wrapped when an expression contains 4 or more chain operators in an expression. Note that if a chained method contains nested expressions the chain operators of the inner expression are not taken into account.
+
+```ini
+[*.{kt,kts}]
+ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than=unset
+```
+
+This setting only takes effect when rule `chain-method-continution` is enabled.
+
 ## Force multiline function signature based on number of parameters
 
 Setting `ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than` forces a multiline function signature in case the function contains the specified minimum number of parameters even in case the function signature would fit on a single line. Use value `unset` (default) to disable this setting.

documentation/snapshot/docs/rules/experimental.md

@@ -87,6 +87,89 @@ Requires a blank line before any class or function declaration. No blank line is
 
 Rule id: `blank-line-before-declaration` (`standard` rule set)
 
+!!! Note
+    This rule is only run when `ktlint_code_style` is set to `ktlint_official` or when the rule is enabled explicitly.
+
+### Chain method continuation
+
+In a multiline method chain, the chain operators (`.` or `?.`) have to be aligned with each other. 
+
+Multiple chained methods on a single line are allowed as long as the maximum line length, and the maximum number of chain operators are not exceeded. Under certain conditions, it is allowed that the expression before the first and/or the expression after the last chain operator is a multiline expression.
+
+The `.` in `java.class` is ignored when wrapping on chain operators.
+
+This rule can be configured with `.editorconfig` property [`ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than`](../configuration-ktlint/#force-multiline-chained-methods-based-on-number-of-chain-operators).
+
+!!! warning
+    Binary expression for which the left and/or right operand consist of method chain are currently being ignored by this rule. Please reach out, if you can help to determine what the best strategy is to deal with such kind of expressions.
+
+=== "[:material-heart:](#) Ktlint"
+
+    ```kotlin
+    val foo1 =
+        listOf(1, 2, 3)
+            .filter { it > 2 }!!
+            .takeIf { it > 2 }
+            .map {
+                it * it
+            }?.map {
+                it * it
+            }
+    val foo2 =
+        listOf(1, 2, 3)
+            .filter {
+                it > 2
+            }.map {
+                2 * it
+            }?.map {
+                2 * it
+            }
+    val foo3 = foo().bar().map {
+        it.foobar()
+    }
+    val foo4 =
+        """
+        Some text
+        """.trimIndent().foo().bar()
+    ```
+
+=== "[:material-heart-off-outline:](#) Disallowed"
+
+    ```kotlin
+    val foo1 =
+        listOf(1, 2, 3).
+            filter { it > 2 }!!.
+            takeIf { it > 2 }.
+            map {
+                it * it
+            }?.
+            map {
+                it * it
+            }
+    val foo2 =
+        listOf(1, 2, 3)
+            .filter {
+                it > 2
+            }
+            .map {
+                2 * it
+            }
+            ?.map {
+                2 * it
+            }
+    val foo3 = foo()
+        .bar().map {
+            it.foobar()
+        }
+    val foo4 =
+        """
+        Some text
+        """.trimIndent().foo()
+            .bar()
+    ```
+
+Rule id: `chain-method-continuation` (`standard` rule set)
+
 !!! Note
     This rule is only run when `ktlint_code_style` is set to `ktlint_official` or when the rule is enabled explicitly.
 

ktlint-api-consumer/src/test/kotlin/com/pinterest/ktlint/api/consumer/KtLintRuleEngineTest.kt

@@ -293,8 +293,7 @@ class KtLintRuleEngineTest {
                                     .properties(
                                         EXPERIMENTAL_RULES_EXECUTION_PROPERTY.toPropertyBuilderWithValue("enabled"),
                                     ),
-                            )
-                            .build(),
+                            ).build(),
                     ),
                 fileSystem = ktlintTestFileSystem.fileSystem,
             )

ktlint-cli-reporter-baseline/src/main/kotlin/com/pinterest/ktlint/cli/reporter/baseline/Baseline.kt

@@ -160,7 +160,8 @@ private class BaselineLoader(
                 getAttribute("source")
                     .let { ruleId ->
                         // Ensure backwards compatibility with baseline files in which the rule set id for standard rules is not saved
-                        RuleId.prefixWithStandardRuleSetIdWhenMissing(ruleId)
+                        RuleId
+                            .prefixWithStandardRuleSetIdWhenMissing(ruleId)
                             .also { prefixedRuleId ->
                                 if (prefixedRuleId != ruleId) {
                                     ruleReferenceWithoutRuleSetIdPrefix++

ktlint-cli-reporter-baseline/src/main/kotlin/com/pinterest/ktlint/cli/reporter/baseline/BaselineReporter.kt

@@ -44,7 +44,8 @@ public class BaselineReporter(
     }
 
     private fun String.escapeXMLAttrValue() =
-        this.replace("&", "&")
+        this
+            .replace("&", "&")
             .replace("\"", """)
             .replace("'", "'")
             .replace("<", "&lt;")

ktlint-cli-reporter-checkstyle/src/main/kotlin/com/pinterest/ktlint/cli/reporter/checkstyle/CheckStyleReporter.kt

@@ -40,6 +40,10 @@ public class CheckStyleReporter(
     }
 
     private fun String.escapeXMLAttrValue() =
-        this.replace("&", "&").replace("\"", """).replace("'", "'")
-            .replace("<", "&lt;").replace(">", "&gt;")
+        this
+            .replace("&", "&amp;")
+            .replace("\"", "&quot;")
+            .replace("'", "&apos;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
 }

ktlint-cli-reporter-checkstyle/src/test/kotlin/com/pinterest/ktlint/cli/reporter/checkstyle/CheckStyleReporterTest.kt

@@ -54,8 +54,7 @@ class CheckStyleReporterTest {
                 </file>
             </checkstyle>
 
-            """.trimIndent()
-                .replace("\n", System.lineSeparator()),
+            """.trimIndent().replace("\n", System.lineSeparator()),
         )
     }
 }

ktlint-cli-reporter-core/src/main/kotlin/com/pinterest/ktlint/cli/reporter/core/api/KtlintVersion.kt

@@ -13,7 +13,6 @@ import java.util.jar.Manifest
 public fun <T> ktlintVersion(javaClass: Class<T>): String? = javaClass.`package`.implementationVersion ?: getManifestVersion(javaClass)
 
 private fun <T> getManifestVersion(javaClass: Class<T>) =
-    javaClass.getResourceAsStream("/META-INF/MANIFEST.MF")
-        ?.run {
-            Manifest(this).mainAttributes.getValue("Implementation-Version")
-        }
+    javaClass
+        .getResourceAsStream("/META-INF/MANIFEST.MF")
+        ?.run { Manifest(this).mainAttributes.getValue("Implementation-Version") }

ktlint-cli-reporter-html/src/main/kotlin/com/pinterest/ktlint/cli/reporter/html/HtmlReporter.kt

@@ -153,6 +153,10 @@ public class HtmlReporter(
     }
 
     private fun String.escapeHTMLAttrValue() =
-        this.replace("&", "&").replace("\"", """).replace("'", "'")
-            .replace("<", "&lt;").replace(">", "&gt;")
+        this
+            .replace("&", "&amp;")
+            .replace("\"", "&quot;")
+            .replace("'", "&apos;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
 }

ktlint-cli-reporter-json/src/test/kotlin/com/pinterest/ktlint/cli/reporter/json/JsonReporterTest.kt

@@ -74,8 +74,7 @@ class JsonReporterTest {
                 }
             ]
 
-            """.trimIndent()
-                .replace("\n", System.lineSeparator()),
+            """.trimIndent().replace("\n", System.lineSeparator()),
         )
     }
 
@@ -104,8 +103,7 @@ class JsonReporterTest {
                 }
             ]
 
-            """.trimIndent()
-                .replace("\n", System.lineSeparator()),
+            """.trimIndent().replace("\n", System.lineSeparator()),
         )
     }
 }

ktlint-cli-reporter-sarif/src/main/kotlin/com/pinterest/ktlint/cli/reporter/sarif/SarifReporter.kt

@@ -25,9 +25,14 @@ import kotlin.io.path.relativeToOrSelf
 private const val SRCROOT = "%SRCROOT%"
 
 internal fun String.sanitize(): String =
-    this.replace(File.separatorChar, '/')
+    this
+        .replace(File.separatorChar, '/')
         .let {
-            if (it.endsWith('/')) it else "$it/"
+            if (it.endsWith('/')) {
+                it
+            } else {
+                "$it/"
+            }
         }
 
 public class SarifReporter(

ktlint-cli/build.gradle.kts

@@ -146,7 +146,15 @@ tasks.withType<Test>().configureEach {
 
     // TODO: Use providers directly after https://github.com/gradle/gradle/issues/12247 is fixed.
     val executableFilePath =
-        providers.provider { shadowJarExecutable.get().outputs.files.first { it.name == "ktlint" }.absolutePath }.get()
+        providers
+            .provider {
+                shadowJarExecutable
+                    .get()
+                    .outputs
+                    .files
+                    .first { it.name == "ktlint" }
+                    .absolutePath
+            }.get()
     val ktlintVersion = providers.provider { version }.get()
     doFirst {
         systemProperty(

ktlint-cli/src/main/kotlin/com/pinterest/ktlint/cli/internal/FileUtils.kt

@@ -108,15 +108,16 @@ internal fun FileSystem.fileSequence(
                     ): FileVisitResult {
                         val path =
                             if (onWindowsOS) {
-                                Paths.get(
-                                    filePath
-                                        .absolutePathString()
-                                        .replace(File.separatorChar, '/'),
-                                ).also {
-                                    if (it != filePath) {
-                                        LOGGER.trace { "On WindowsOS transform '$filePath' to '$it'" }
+                                Paths
+                                    .get(
+                                        filePath
+                                            .absolutePathString()
+                                            .replace(File.separatorChar, '/'),
+                                    ).also {
+                                        if (it != filePath) {
+                                            LOGGER.trace { "On WindowsOS transform '$filePath' to '$it'" }
+                                        }
                                     }
-                                }
                             } else {
                                 filePath
                             }