Add context-receiver-list-wrapping rule (#3034)

paul-dingemans · web-flow · commit 47c536f0fb0d · 2025-07-05T16:08:41.000+02:00
* Ignore context parameters in rule `context-receiver-wrapping` Closes #3028 * Add `context-receiver-list-wrapping` rule Similar to `context-receiver-list` but it only wraps when the list contains a context parameter instead of a context receiver Closes #3029 * Fix API contract
diff --git a/documentation/snapshot/docs/rules/standard.md b/documentation/snapshot/docs/rules/standard.md
@@ -4367,7 +4367,13 @@ Suppress or disable rule (1)
 
 ### Context receiver wrapping
 
-Wraps the context receiver list of a function to a separate line regardless of maximum line length. If the maximum line length is configured and is exceeded, wrap the context receivers and if needed its projection types to separate lines.
+!!! important
+    Context receivers are deprecated starting from Kotlin 2.2.0 and will be removed in a future version. Once KtLint is upgraded to a Kotlin version that no longer supports context receivers, then you will not be able to use that KtLint version as long as your code still contains context receiver.
+
+!!! tip
+    This rule does not affect context parameters. See rule `context-receiver-list-wrapping` for wrapping of context parameters.
+
+Wraps the context receiver list containing a context receiver to a separate line regardless of maximum line length. If the maximum line length is configured and is exceeded, wrap the context receivers and if needed its projection types to separate lines.
 
 === "[:material-heart:](#) Ktlint"
 
@@ -4438,6 +4444,83 @@ Suppress or disable rule (1)
     ```editorconfig
     ktlint_standard_context-receiver-wrapping = disabled
     ```
+   
+### Context receiver list wrapping
+
+!!! tip
+    This rule does not affect context receivers. See rule `context-receiver-wrapping` for wrapping of context receivers.
+
+Wraps the context receiver list containing a context parameter to a separate line regardless of maximum line length. If the maximum line length is configured and is exceeded, wrap the context receivers and if needed its projection types to separate lines.
+
+=== "[:material-heart:](#) Ktlint"
+
+    ```kotlin
+    // Always wrap regardless of whether max line length is set
+    context(_: Foo)
+    fun fooBar()
+    
+    // Wrap each context receiver to a separate line when the
+    // entire context receiver list does not fit on a single line
+    context(
+        foo1: Fooooooooooooooooooo1,
+        foo2: Foooooooooooooooooooooooooooooo2
+    )
+    fun fooBar()
+    
+    // Wrap each context receiver to a separate line when the
+    // entire context receiver list does not fit on a single line.
+    // Also, wrap each of it projection types in case a context
+    // receiver does not fit on a single line after it has been
+    // wrapped.
+    context(
+        _: Foooooooooooooooo<
+            Foo,
+            Bar,
+            >
+    )
+    fun fooBar()
+    ```
+
+=== "[:material-heart-off-outline:](#) Disallowed"
+
+    ```kotlin
+    // Should be wrapped regardless of whether max line length is set
+    context(_: Foo) fun fooBar()
+
+    // Should be wrapped when the entire context receiver list does not
+    // fit on a single line
+    context(foo1: Fooooooooooooooooooo1, foo2: Foooooooooooooooooooooooooooooo2)
+    fun fooBar()
+
+    // Should be wrapped when the entire context receiver list does not
+    // fit on a single line. Also, it should wrap each of it projection
+    // type in case a context receiver does not fit on a single line 
+    // after it has been wrapped.
+    context(_: Foooooooooooooooo<Foo, Bar>)
+    fun fooBar()
+    ```
+
+| Configuration setting                                                                                                                                                                                                         | ktlint_official | intellij_idea | android_studio |
+|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:|
+| `max_line_length`<br/><i>Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule.</i> |       140       |     `off`     |     `100`      |
+
+Rule id: `standard:context-receiver-list-wrapping`
+
+Suppress or disable rule (1)
+{ .annotate }
+
+1. Suppress rule in code with annotation below:
+    ```kotlin
+    @Suppress("ktlint:standard:context-receiver-list-wrapping")
+    ```
+   Enable rule via `.editorconfig`
+    ```editorconfig
+    ktlint_standard_context-receiver-list-wrapping = enabled
+    ```
+   Disable rule via `.editorconfig`
+    ```editorconfig
+    ktlint_standard_context-receiver-list-wrapping = disabled
+    ```
 
 ### Enum wrapping
 
diff --git a/ktlint-ruleset-standard/api/ktlint-ruleset-standard.api b/ktlint-ruleset-standard/api/ktlint-ruleset-standard.api
@@ -180,6 +180,16 @@ public final class com/pinterest/ktlint/ruleset/standard/rules/ConditionWrapping
 	public static final fun getCONDITION_WRAPPING_RULE_ID ()Lcom/pinterest/ktlint/rule/engine/core/api/RuleId;
 }
 
+public final class com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverListWrappingRule : com/pinterest/ktlint/ruleset/standard/StandardRule {
+	public fun <init> ()V
+	public fun beforeFirstNode (Lcom/pinterest/ktlint/rule/engine/core/api/editorconfig/EditorConfig;)V
+	public fun beforeVisitChildNodes (Lorg/jetbrains/kotlin/com/intellij/lang/ASTNode;Lkotlin/jvm/functions/Function3;)V
+}
+
+public final class com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverListWrappingRuleKt {
+	public static final fun getCONTEXT_RECEIVER_LIST_WRAPPING_RULE_ID ()Lcom/pinterest/ktlint/rule/engine/core/api/RuleId;
+}
+
 public final class com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverWrappingRule : com/pinterest/ktlint/ruleset/standard/StandardRule {
 	public fun <init> ()V
 	public fun beforeFirstNode (Lcom/pinterest/ktlint/rule/engine/core/api/editorconfig/EditorConfig;)V
diff --git a/ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/StandardRuleSetProvider.kt b/ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/StandardRuleSetProvider.kt
@@ -18,6 +18,7 @@ import com.pinterest.ktlint.ruleset.standard.rules.ClassSignatureRule
 import com.pinterest.ktlint.ruleset.standard.rules.CommentSpacingRule
 import com.pinterest.ktlint.ruleset.standard.rules.CommentWrappingRule
 import com.pinterest.ktlint.ruleset.standard.rules.ConditionWrappingRule
+import com.pinterest.ktlint.ruleset.standard.rules.ContextReceiverListWrappingRule
 import com.pinterest.ktlint.ruleset.standard.rules.ContextReceiverWrappingRule
 import com.pinterest.ktlint.ruleset.standard.rules.DiscouragedCommentLocationRule
 import com.pinterest.ktlint.ruleset.standard.rules.EnumEntryNameCaseRule
@@ -121,6 +122,7 @@ public class StandardRuleSetProvider : RuleSetProviderV3(RuleSetId.STANDARD) {
             RuleProvider { CommentWrappingRule() },
             RuleProvider { ConditionWrappingRule() },
             RuleProvider { ContextReceiverWrappingRule() },
+            RuleProvider { ContextReceiverListWrappingRule() },
             RuleProvider { DiscouragedCommentLocationRule() },
             RuleProvider { EnumEntryNameCaseRule() },
             RuleProvider { EnumWrappingRule() },
diff --git a/ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverListWrappingRule.kt b/ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverListWrappingRule.kt
@@ -0,0 +1,193 @@
+package com.pinterest.ktlint.ruleset.standard.rules
+
+import com.pinterest.ktlint.rule.engine.core.api.AutocorrectDecision
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.CONTEXT_RECEIVER
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.CONTEXT_RECEIVER_LIST
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.FUN
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.FUNCTION_TYPE
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.GT
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.RPAR
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.TYPE_ARGUMENT_LIST
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.TYPE_PROJECTION
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.TYPE_REFERENCE
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.VALUE_PARAMETER
+import com.pinterest.ktlint.rule.engine.core.api.ElementType.VALUE_PARAMETER_LIST
+import com.pinterest.ktlint.rule.engine.core.api.IndentConfig
+import com.pinterest.ktlint.rule.engine.core.api.IndentConfig.Companion.DEFAULT_INDENT_CONFIG
+import com.pinterest.ktlint.rule.engine.core.api.RuleId
+import com.pinterest.ktlint.rule.engine.core.api.SinceKtlint
+import com.pinterest.ktlint.rule.engine.core.api.SinceKtlint.Status.STABLE
+import com.pinterest.ktlint.rule.engine.core.api.children20
+import com.pinterest.ktlint.rule.engine.core.api.editorconfig.EditorConfig
+import com.pinterest.ktlint.rule.engine.core.api.editorconfig.INDENT_SIZE_PROPERTY
+import com.pinterest.ktlint.rule.engine.core.api.editorconfig.INDENT_STYLE_PROPERTY
+import com.pinterest.ktlint.rule.engine.core.api.editorconfig.MAX_LINE_LENGTH_PROPERTY
+import com.pinterest.ktlint.rule.engine.core.api.firstChildLeafOrSelf20
+import com.pinterest.ktlint.rule.engine.core.api.ifAutocorrectAllowed
+import com.pinterest.ktlint.rule.engine.core.api.indent20
+import com.pinterest.ktlint.rule.engine.core.api.indentWithoutNewlinePrefix
+import com.pinterest.ktlint.rule.engine.core.api.isPartOf
+import com.pinterest.ktlint.rule.engine.core.api.isPartOfComment20
+import com.pinterest.ktlint.rule.engine.core.api.isWhiteSpaceWithNewline20
+import com.pinterest.ktlint.rule.engine.core.api.isWhiteSpaceWithoutNewline20
+import com.pinterest.ktlint.rule.engine.core.api.lastChildLeafOrSelf20
+import com.pinterest.ktlint.rule.engine.core.api.nextLeaf
+import com.pinterest.ktlint.rule.engine.core.api.parent
+import com.pinterest.ktlint.rule.engine.core.api.prevLeaf
+import com.pinterest.ktlint.rule.engine.core.api.upsertWhitespaceAfterMe
+import com.pinterest.ktlint.rule.engine.core.api.upsertWhitespaceBeforeMe
+import com.pinterest.ktlint.ruleset.standard.StandardRule
+import org.jetbrains.kotlin.com.intellij.lang.ASTNode
+
+/**
+ * Wrapping of context receiver list to a separate line.
+ *
+ * IMPORTANT: This rule only affects a context receiver list that does not contain a context receiver. Context receivers are deprecated
+ * since Kotlin 2.2.0, and are wrapped by the 'context-receiver-wrapping' rule.
+ */
+@SinceKtlint("1.7", STABLE)
+public class ContextReceiverListWrappingRule :
+    StandardRule(
+        id = "context-receiver-list-wrapping",
+        usesEditorConfigProperties =
+            setOf(
+                INDENT_SIZE_PROPERTY,
+                INDENT_STYLE_PROPERTY,
+                MAX_LINE_LENGTH_PROPERTY,
+            ),
+    ) {
+    private var indentConfig = DEFAULT_INDENT_CONFIG
+    private var maxLineLength = MAX_LINE_LENGTH_PROPERTY.defaultValue
+
+    override fun beforeFirstNode(editorConfig: EditorConfig) {
+        indentConfig =
+            IndentConfig(
+                indentStyle = editorConfig[INDENT_STYLE_PROPERTY],
+                tabWidth = editorConfig[INDENT_SIZE_PROPERTY],
+            )
+        maxLineLength = editorConfig.maxLineLength()
+    }
+
+    override fun beforeVisitChildNodes(
+        node: ASTNode,
+        emit: (offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> AutocorrectDecision,
+    ) {
+        when {
+            node.elementType == CONTEXT_RECEIVER_LIST && node.isContextParameter() -> {
+                visitContextReceiverList(node, emit)
+            }
+
+            node.elementType == TYPE_ARGUMENT_LIST && node.isContextParameter() -> {
+                visitContextReceiverTypeArgumentList(node, emit)
+            }
+        }
+    }
+
+    private fun ASTNode.isContextParameter(): Boolean = isPartOf(CONTEXT_RECEIVER_LIST) && findChildByType(CONTEXT_RECEIVER) == null
+
+    private fun visitContextReceiverList(
+        node: ASTNode,
+        emit: (offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> AutocorrectDecision,
+    ) {
+        // Context receiver must be followed by new line or comment unless it is a type reference of a parameter
+        node
+            .takeUnless { it.isTypeReferenceParameterInFunction() }
+            ?.lastChildLeafOrSelf20
+            ?.nextLeaf { !it.isWhiteSpaceWithoutNewline20 && !it.isPartOfComment20 }
+            ?.takeIf { !it.isWhiteSpaceWithNewline20 }
+            ?.let { nodeAfterContextReceiver ->
+                emit(nodeAfterContextReceiver.startOffset, "Expected a newline after the context parameter", true)
+                    .ifAutocorrectAllowed {
+                        nodeAfterContextReceiver
+                            .firstChildLeafOrSelf20
+                            .upsertWhitespaceBeforeMe(indentConfig.parentIndentOf(node))
+                    }
+            }
+
+        // Check line length assuming that the context receiver is indented correctly. Wrapping rule must however run before indenting.
+        if (!node.textContains('\n') &&
+            node.indentWithoutNewlinePrefix.length + node.textLength > maxLineLength
+        ) {
+            node
+                .children20
+                .filter { it.elementType == VALUE_PARAMETER }
+                .forEach {
+                    emit(
+                        it.startOffset,
+                        "Newline expected before context parameter as max line length is violated",
+                        true,
+                    ).ifAutocorrectAllowed {
+                        it
+                            .prevLeaf
+                            ?.upsertWhitespaceAfterMe(indentConfig.childIndentOf(node))
+                    }
+                }
+            node
+                .findChildByType(RPAR)
+                ?.let { rpar ->
+                    emit(
+                        rpar.startOffset,
+                        "Newline expected before closing parenthesis as max line length is violated",
+                        true,
+                    ).ifAutocorrectAllowed {
+                        rpar.upsertWhitespaceBeforeMe(node.indent20)
+                    }
+                }
+        }
+    }
+
+    private fun ASTNode.isTypeReferenceParameterInFunction() =
+        takeIf { it.elementType == CONTEXT_RECEIVER_LIST }
+            ?.parent
+            ?.takeIf { it.elementType == FUNCTION_TYPE }
+            ?.parent
+            ?.takeIf { it.elementType == TYPE_REFERENCE }
+            ?.parent
+            ?.takeIf { it.elementType == VALUE_PARAMETER }
+            ?.parent
+            ?.takeIf { it.elementType == VALUE_PARAMETER_LIST }
+            ?.parent
+            ?.let { it.elementType == FUN }
+            ?: false
+
+    private fun visitContextReceiverTypeArgumentList(
+        node: ASTNode,
+        emit: (offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> AutocorrectDecision,
+    ) {
+        val contextReceiverText = node.parent?.text.orEmpty()
+        // Check line length assuming that the context receiver is indented correctly. Wrapping rule must however run
+        // before indenting.
+        if (!contextReceiverText.contains('\n') &&
+            node.indentWithoutNewlinePrefix.length + contextReceiverText.length > maxLineLength
+        ) {
+            node
+                .children20
+                .filter { it.elementType == TYPE_PROJECTION }
+                .forEach {
+                    emit(
+                        it.startOffset,
+                        "Newline expected before context parameter type projection as max line length is violated",
+                        true,
+                    ).ifAutocorrectAllowed {
+                        it.upsertWhitespaceBeforeMe(indentConfig.childIndentOf(node))
+                    }
+                }
+            node
+                .findChildByType(GT)
+                ?.let { gt ->
+                    emit(
+                        gt.startOffset,
+                        "Newline expected before closing angle bracket as max line length is violated",
+                        true,
+                    ).ifAutocorrectAllowed {
+                        // Ideally, the closing angle bracket should be de-indented to make it consistent with
+                        // de-indentation of closing ")", "}" and "]". This however would be inconsistent with how the
+                        // type argument lists are formatted by IntelliJ IDEA default formatter.
+                        gt.upsertWhitespaceBeforeMe(indentConfig.childIndentOf(node))
+                    }
+                }
+        }
+    }
+}
+
+public val CONTEXT_RECEIVER_LIST_WRAPPING_RULE_ID: RuleId = ContextReceiverListWrappingRule().ruleId
diff --git a/ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverListWrappingRuleTest.kt b/ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/ContextReceiverListWrappingRuleTest.kt
