Default to preserving lambda line breaks (Kotlin#614)

Summary:
This is a continuation of Kotlin#574 with the updated option control to orient around the requested `--preserve-lambda-breaks` simple option. With this, lambda block line breaks are simply just respected rather than have ktfmt impose anything.

Aside from finishing up the previous PR, this also adds a setting to the IJ plugin.

I cherrypicked the original commits to preserve authorship history (CC loganj)

Resolves Kotlin#547

**Edit**

After chatting on slack I updated the PR with a couple things:
- Added a builder API for CLI tools to use in the future to avoid ABI breakages
- Flipped the semantics to enable this by default, but can revert if you want to keep the old setup. I do think enabled by default is good

Pull Request resolved: Kotlin#614

Reviewed By: ermattt

Differential Revision: D105690093

Pulled By: hick209

fbshipit-source-id: 8a2a3232329a796a8f777d7bf7ef96016651ef61

Author: ZacSweers

.gitignore

@@ -1,4 +1,5 @@
 .idea/
+.kotlin/
 *.ims
 *.iml
 
@@ -23,3 +24,4 @@ release-ktfmt-website/
 .gradle
 **/build/
 !src/**/build/
+.claude/

CHANGELOG.md

@@ -17,6 +17,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Support for lists within quoted blocks in KDoc comments (https://github.com/facebook/ktfmt/commit/68fa1585b759ad4b12ca4802bccd297f6a33b0f3)
 - Fix `ONLY_ADD` trailing commas strategy causing lines over MAX_WIDTH length (https://github.com/facebook/ktfmt/issues/610)
 - Remove forced breaking of `context` function types (https://github.com/facebook/ktfmt/pull/613)
+- Preserve user-authored line breaks inside lambda bodies by default, rather than have ktfmt impose anything. This can be particularly useful for DSL syntax like Compose UI or Kotlin Gradle script. The behavior follows the `FormattingOptions.preserveLambdaBreaks` setting of the chosen style. (https://github.com/facebook/ktfmt/pull/614)
+- Add a `FormattingOptions.Builder` API for tools to avoid breaking ABI changes with new options. (https://github.com/facebook/ktfmt/pull/614)
 
 ## [0.62]
 ### Added

README.md

@@ -88,6 +88,28 @@ following subset of editorconfig properties:
 | `ij_continuation_indent_size`                             | will override the continuation indent                                                            |
 | `ktfmt_trailing_comma_management_strategy`                | one of `none`, `only_add` or `complete`<br/>will override the trailing comma management strategy |
 
+#### Preserving Lambda Line Breaks
+
+By default, `ktfmt` respects user-authored line breaks inside lambda bodies. This is useful for DSLs
+where nesting carries semantic meaning (Jetpack Compose UI hierarchies, Kotlin Gradle scripts, etc.)
+without ktfmt prescribing a specific outcome.
+
+A lambda body whose source spans multiple lines stays multi-line; one that fits on a single line
+stays single-line if written that way. For example, the following is left as-is:
+
+```kotlin
+// Multi-line in source is preserved
+App {
+  SelectableCard {
+    Button { Text("Click me") }
+  }
+}
+
+// Single-line in source is also preserved
+dependencies { implementation(libs.androidx.activity) }
+val state = remember { mutableStateOf(false) }
+```
+
 ***Note:***
 *There is no configurability as to the formatter's algorithm for formatting (apart from the different styles
 or limited `.editorconfig` support). This is a deliberate design decision to unify our code formatting on a

core/api/ktfmt.api

@@ -122,9 +122,12 @@ public final class com/facebook/ktfmt/format/Formatter {
 
 public final class com/facebook/ktfmt/format/FormattingOptions {
 	public static final field Companion Lcom/facebook/ktfmt/format/FormattingOptions$Companion;
+	public static final field DEFAULT_BLOCK_INDENT I
+	public static final field DEFAULT_CONTINUATION_INDENT I
 	public static final field DEFAULT_MAX_WIDTH I
 	public fun <init> (IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZ)V
-	public synthetic fun <init> (IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZZ)V
+	public synthetic fun <init> (IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun <init> (IIIZZZ)V
 	public synthetic fun <init> (IIIZZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()I
@@ -133,19 +136,34 @@ public final class com/facebook/ktfmt/format/FormattingOptions {
 	public final fun component4 ()Lcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;
 	public final fun component5 ()Z
 	public final fun component6 ()Z
-	public final fun copy (IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZ)Lcom/facebook/ktfmt/format/FormattingOptions;
-	public static synthetic fun copy$default (Lcom/facebook/ktfmt/format/FormattingOptions;IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZILjava/lang/Object;)Lcom/facebook/ktfmt/format/FormattingOptions;
+	public final fun component7 ()Z
+	public final fun copy (IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZZ)Lcom/facebook/ktfmt/format/FormattingOptions;
+	public static synthetic fun copy$default (Lcom/facebook/ktfmt/format/FormattingOptions;IIILcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;ZZZILjava/lang/Object;)Lcom/facebook/ktfmt/format/FormattingOptions;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getBlockIndent ()I
 	public final fun getContinuationIndent ()I
 	public final fun getDebuggingPrintOpsAfterFormatting ()Z
 	public final fun getMaxWidth ()I
+	public final fun getPreserveLambdaBreaks ()Z
 	public final fun getRemoveUnusedImports ()Z
 	public final fun getTrailingCommaManagementStrategy ()Lcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;
 	public fun hashCode ()I
+	public final fun toBuilder ()Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class com/facebook/ktfmt/format/FormattingOptions$Builder {
+	public fun <init> ()V
+	public final fun blockIndent (I)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+	public final fun build ()Lcom/facebook/ktfmt/format/FormattingOptions;
+	public final fun continuationIndent (I)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+	public final fun debuggingPrintOpsAfterFormatting (Z)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+	public final fun maxWidth (I)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+	public final fun preserveLambdaBreaks (Z)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+	public final fun removeUnusedImports (Z)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+	public final fun trailingCommaManagementStrategy (Lcom/facebook/ktfmt/format/TrailingCommaManagementStrategy;)Lcom/facebook/ktfmt/format/FormattingOptions$Builder;
+}
+
 public final class com/facebook/ktfmt/format/FormattingOptions$Companion {
 }
 

core/src/main/java/com/facebook/ktfmt/cli/ParsedArgs.kt

@@ -75,19 +75,19 @@ data class ParsedArgs(
         |Commands options:
         |  -h, --help                        Show this help message
         |  -v, --version                     Show version
-        |  -n, --dry-run                     Don't write to files, only report files which 
+        |  -n, --dry-run                     Don't write to files, only report files which
         |                                        would have changed
         |  --meta-style                      Use 2-space block indenting (default)
         |  --google-style                    Google internal style (2 spaces)
         |  --kotlinlang-style                Kotlin language guidelines style (4 spaces)
         |  --stdin-name=<name>               Name to report when formatting code from stdin
-        |  --set-exit-if-changed             Sets exit code to 1 if any input file was not 
+        |  --set-exit-if-changed             Sets exit code to 1 if any input file was not
         |                                        formatted/touched
         |  --do-not-remove-unused-imports    Leaves all imports in place, even if not used
         |  --enable-editorconfig             Enable .editorconfig overrides for supported formatting options (limited)
         |                                        see https://github.com/facebook/ktfmt/blob/main/README.md
         |  --quiet                           Suppress all non-error output
-        |  
+        |
         |ARGFILE:
         |  If the only argument begins with '@', the remainder of the argument is treated
         |  as the name of a file to read options and arguments from, one per line.

core/src/main/java/com/facebook/ktfmt/format/FormattingOptions.kt

@@ -57,6 +57,29 @@ data class FormattingOptions(
     /** Whether ktfmt should remove imports that are not used. */
     val removeUnusedImports: Boolean = true,
 
+    /**
+     * Whether to preserve user-authored line breaks inside lambda bodies. Enabled by default.
+     *
+     * When enabled, a lambda whose body spans multiple lines in the source is kept multi-line. A
+     * lambda that fits on a single line in the source is left alone. This is general-purpose and
+     * lets callers preserve structure they care about without ktfmt prescribing a specific outcome.
+     *
+     * For example, with this option enabled, the following stays multi-line:
+     * ```
+     * App {
+     *   SelectableCard {
+     *     Button { Text("Hello") }
+     *   }
+     * }
+     * ```
+     *
+     * While this stays single-line:
+     * ```
+     * App { SelectableCard { Button { Text("Hello") } } }
+     * ```
+     */
+    val preserveLambdaBreaks: Boolean = true,
+
     /**
      * Print the Ops generated by KotlinInputAstVisitor to help reason about formatting (i.e.,
      * newline) decisions
@@ -65,6 +88,8 @@ data class FormattingOptions(
 ) {
   companion object {
     const val DEFAULT_MAX_WIDTH: Int = 100
+    const val DEFAULT_BLOCK_INDENT: Int = 2
+    const val DEFAULT_CONTINUATION_INDENT: Int = 4
   }
 
   @Deprecated("Here just for retrocompatibility reasons. Will be removed on 1.0.0")
@@ -81,11 +106,122 @@ data class FormattingOptions(
       continuationIndent = continuationIndent,
       trailingCommaManagementStrategy = if (manageTrailingCommas) COMPLETE else NONE,
       removeUnusedImports = removeUnusedImports,
+      // Pinned to false to preserve the behavior callers of this deprecated constructor had before
+      // preserveLambdaBreaks existed and became the default.
+      preserveLambdaBreaks = false,
+      debuggingPrintOpsAfterFormatting = debuggingPrintOpsAfterFormatting,
+  )
+
+  @Deprecated("Here just for retrocompatibility reasons. Will be removed on 1.0.0")
+  constructor(
+      maxWidth: Int,
+      blockIndent: Int,
+      continuationIndent: Int,
+      trailingCommaManagementStrategy: TrailingCommaManagementStrategy,
+      removeUnusedImports: Boolean,
+      debuggingPrintOpsAfterFormatting: Boolean,
+  ) : this(
+      maxWidth = maxWidth,
+      blockIndent = blockIndent,
+      continuationIndent = continuationIndent,
+      trailingCommaManagementStrategy = trailingCommaManagementStrategy,
+      removeUnusedImports = removeUnusedImports,
+      // Set to false to preserve the behavior callers of this deprecated constructor had before
+      // preserveLambdaBreaks existed and became the default.
+      preserveLambdaBreaks = false,
       debuggingPrintOpsAfterFormatting = debuggingPrintOpsAfterFormatting,
   )
 
   internal val manageTrailingCommas: Boolean
     get() = trailingCommaManagementStrategy != NONE
+
+  /**
+   * Returns a [Builder] pre-populated with this instance's values.
+   *
+   * Handy for deriving a new [FormattingOptions] from an existing one (such as one of the
+   * [Formatter] presets) while overriding only a few fields.
+   */
+  fun toBuilder(): Builder =
+      Builder()
+          .maxWidth(maxWidth)
+          .blockIndent(blockIndent)
+          .continuationIndent(continuationIndent)
+          .trailingCommaManagementStrategy(trailingCommaManagementStrategy)
+          .removeUnusedImports(removeUnusedImports)
+          .preserveLambdaBreaks(preserveLambdaBreaks)
+          .debuggingPrintOpsAfterFormatting(debuggingPrintOpsAfterFormatting)
+
+  /**
+   * A fluent builder for [FormattingOptions].
+   *
+   * Prefer this (or [toBuilder]) over the constructor and generated [copy] when constructing
+   * options from outside this module. New options can be introduced as additional builder methods
+   * without breaking source or binary compatibility for existing callers, which is not true of the
+   * constructor or [copy] overloads.
+   *
+   * For example:
+   * ```
+   * val options =
+   *     FormattingOptions.Builder()
+   *         .blockIndent(2)
+   *         .continuationIndent(4)
+   *         .preserveLambdaBreaks(true)
+   *         .build()
+   * ```
+   */
+  class Builder {
+    private var maxWidth: Int = DEFAULT_MAX_WIDTH
+    private var blockIndent: Int = DEFAULT_BLOCK_INDENT
+    private var continuationIndent: Int = DEFAULT_CONTINUATION_INDENT
+    private var trailingCommaManagementStrategy: TrailingCommaManagementStrategy = COMPLETE
+    private var removeUnusedImports: Boolean = true
+    private var preserveLambdaBreaks: Boolean = true
+    private var debuggingPrintOpsAfterFormatting: Boolean = false
+
+    /** @see FormattingOptions.maxWidth */
+    fun maxWidth(maxWidth: Int): Builder = apply { this.maxWidth = maxWidth }
+
+    /** @see FormattingOptions.blockIndent */
+    fun blockIndent(blockIndent: Int): Builder = apply { this.blockIndent = blockIndent }
+
+    /** @see FormattingOptions.continuationIndent */
+    fun continuationIndent(continuationIndent: Int): Builder = apply {
+      this.continuationIndent = continuationIndent
+    }
+
+    /** @see FormattingOptions.trailingCommaManagementStrategy */
+    fun trailingCommaManagementStrategy(
+        trailingCommaManagementStrategy: TrailingCommaManagementStrategy
+    ): Builder = apply { this.trailingCommaManagementStrategy = trailingCommaManagementStrategy }
+
+    /** @see FormattingOptions.removeUnusedImports */
+    fun removeUnusedImports(removeUnusedImports: Boolean): Builder = apply {
+      this.removeUnusedImports = removeUnusedImports
+    }
+
+    /** @see FormattingOptions.preserveLambdaBreaks */
+    fun preserveLambdaBreaks(preserveLambdaBreaks: Boolean): Builder = apply {
+      this.preserveLambdaBreaks = preserveLambdaBreaks
+    }
+
+    /** @see FormattingOptions.debuggingPrintOpsAfterFormatting */
+    fun debuggingPrintOpsAfterFormatting(debuggingPrintOpsAfterFormatting: Boolean): Builder =
+        apply {
+          this.debuggingPrintOpsAfterFormatting = debuggingPrintOpsAfterFormatting
+        }
+
+    /** Builds a new [FormattingOptions] from the current builder state. */
+    fun build(): FormattingOptions =
+        FormattingOptions(
+            maxWidth = maxWidth,
+            blockIndent = blockIndent,
+            continuationIndent = continuationIndent,
+            trailingCommaManagementStrategy = trailingCommaManagementStrategy,
+            removeUnusedImports = removeUnusedImports,
+            preserveLambdaBreaks = preserveLambdaBreaks,
+            debuggingPrintOpsAfterFormatting = debuggingPrintOpsAfterFormatting,
+        )
+  }
 }
 
 enum class TrailingCommaManagementStrategy(

core/src/main/java/com/facebook/ktfmt/format/KotlinInputAstVisitor.kt

@@ -930,8 +930,13 @@ class KotlinInputAstVisitor(
       builder.breakOp(Doc.FillMode.UNIFIED, "", bracePlusBlockIndent)
       builder.block(bracePlusBlockIndent) {
         builder.blankLineWanted(OpsBuilder.BlankLineWanted.NO)
+
+        val shouldForceMultiline =
+            options.preserveLambdaBreaks && hasSourceNewlineInLambdaBody(lambdaExpression)
+
         if (
-            expressionStatements.size == 1 &&
+            !shouldForceMultiline &&
+                expressionStatements.size == 1 &&
                 expressionStatements.first() !is KtReturnExpression &&
                 !bodyExpression.startsWithComment()
         ) {
@@ -1605,6 +1610,20 @@ class KotlinInputAstVisitor(
     return false
   }
 
+  /**
+   * Returns true if the source code contains a newline anywhere inside the body of
+   * [lambdaExpression] — that is, between the opening `{` and the closing `}` of the function
+   * literal. Used by [FormattingOptions.preserveLambdaBreaks] to keep user-authored multi-line
+   * lambdas multi-line.
+   */
+  private fun hasSourceNewlineInLambdaBody(lambdaExpression: KtLambdaExpression): Boolean {
+    val functionLiteral = lambdaExpression.functionLiteral
+    for (child in functionLiteral.node.children()) {
+      if (child.psi is PsiWhiteSpace && child.text.contains('\n')) return true
+    }
+    return false
+  }
+
   /** See [isLambdaOrScopingFunction] for examples. */
   private fun visitLambdaOrScopingFunction(expr: PsiElement?) {
     val breakToExpr = genSym()