Respect formatter tags when enabled

Closes #670 Closes #1163
pinterest · Mar 28, 2023 · 52cc432 · 52cc432
1 parent 102175d
commit 52cc432
Show file tree

Hide file tree

Showing 8 changed files with 369 additions and 103 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -274,6 +274,7 @@ Previously the default value for `.editorconfig` property `max_line_length` was
 * Do not remove newlines from multiline type parameter lists `type-parameter-list-spacing` ([#1867](https://github.com/pinterest/ktlint/issues/1867))
 * Wrap each type parameter in a multiline type parameter list `wrapping` ([#1867](https://github.com/pinterest/ktlint/issues/1867))
 * Allow value arguments with a multiline expression to be indented on a separate line `indent` ([#1217](https://github.com/pinterest/ktlint/issues/1217))
+* When enabled, the ktlint rule checking is disabled for all code surrounded by the formatter tags (see [faq](https://pinterest.github.io/ktlint/faq/#are-formatter-tags-respected)) ([#670](https://github.com/pinterest/ktlint/issues/670)) 
 
 ### Changed
 * Wrap the parameters of a function literal containing a multiline parameter list (only in `ktlint_official` code style) `parameter-list-wrapping` ([#1681](https://github.com/pinterest/ktlint/issues/1681)).

diff --git a/docs/faq.md b/docs/faq.md
@@ -112,9 +112,9 @@ or
 ```
 
 ## How do I globally disable a rule?
-With [`.editorConfig` property `disabled_rules`](../rules/configuration-ktlint#disabled-rules) a rule can be disabled globally.
+Rules can be disabled globally by setting a [`.editorConfig` property](../rules/configuration-ktlint#disabled-rules).
 
-You may also pass a list of disabled rules via the `--disabled_rules` command line flag. It has the same syntax as the EditorConfig property.
+You may also pass a list of disabled rules via the `--disabled_rules` command line flag of Ktlint CLI. The value is a comma separated list of rule id's that have to be disabled. The rule id must be fully qualified (e.g. must be prefixed with the rule set id). 
 
 
 ## Why is `.editorconfig` property `disabled_rules` deprecated and how do I resolve this?
@@ -199,3 +199,14 @@ kotlinFile.writeText(
   )
 )
 ```
+
+# Are formatter tags respected?
+
+As of version `0.49.x` the formatter tags of IntelliJ IDEA are respected. By default, those formatter tags are disabled. The formatter tags can be enabled with `.editorconfig` properties below:
+```editorconfig
+ij_formatter_tags_enabled = true # Defaults to 'false'
+ij_formatter_off_tag = some-custom-off-tag # Defaults to '@formatter:off'
+ij_formatter_on_tag = some-custom-on-tag # Defaults to '@formatter:on'
+```
+
+When enabled, the ktlint rule checking is disabled for all code surrounded by the formatter tags.
diff --git a/...le-engine/src/main/kotlin/com/pinterest/ktlint/rule/engine/internal/EditorConfigLoader.kt b/...le-engine/src/main/kotlin/com/pinterest/ktlint/rule/engine/internal/EditorConfigLoader.kt
@@ -13,6 +13,9 @@ import com.pinterest.ktlint.rule.engine.core.api.editorconfig.EXPERIMENTAL_RULES
 import com.pinterest.ktlint.rule.engine.core.api.editorconfig.EditorConfig
 import com.pinterest.ktlint.rule.engine.core.api.editorconfig.EditorConfigProperty
 import com.pinterest.ktlint.rule.engine.core.api.editorconfig.INDENT_SIZE_PROPERTY
+import com.pinterest.ktlint.rule.engine.internal.FormatterTags.Companion.FORMATTER_TAGS_ENABLED_PROPERTY
+import com.pinterest.ktlint.rule.engine.internal.FormatterTags.Companion.FORMATTER_TAG_OFF_ENABLED_PROPERTY
+import com.pinterest.ktlint.rule.engine.internal.FormatterTags.Companion.FORMATTER_TAG_ON_ENABLED_PROPERTY
 import com.pinterest.ktlint.rule.engine.internal.ThreadSafeEditorConfigCache.Companion.THREAD_SAFE_EDITOR_CONFIG_CACHE
 import mu.KotlinLogging
 import org.ec4j.core.EditorConfigLoader
@@ -98,6 +101,18 @@ internal class EditorConfigLoader(
                          * Used by [VisitorProvider] to determine whether experimental rules have to be executed.
                          */
                         EXPERIMENTAL_RULES_EXECUTION_PROPERTY,
+                        /**
+                         * Used by [FormatterTags] to determine whether formatter tags should be respected.
+                         */
+                        FORMATTER_TAGS_ENABLED_PROPERTY,
+                        /**
+                         * Used by [FormatterTags] to get the tag to disable the formatter.
+                         */
+                        FORMATTER_TAG_OFF_ENABLED_PROPERTY,
+                        /**
+                         * Used by [FormatterTags] to get the tag to enable the formatter.
+                         */
+                        FORMATTER_TAG_ON_ENABLED_PROPERTY,
                     )
             }
     }

diff --git a/...nt-rule-engine/src/main/kotlin/com/pinterest/ktlint/rule/engine/internal/FormatterTags.kt b/...nt-rule-engine/src/main/kotlin/com/pinterest/ktlint/rule/engine/internal/FormatterTags.kt
@@ -0,0 +1,59 @@
+package com.pinterest.ktlint.rule.engine.internal
+
+import com.pinterest.ktlint.rule.engine.core.api.editorconfig.EditorConfig
+import com.pinterest.ktlint.rule.engine.core.api.editorconfig.EditorConfigProperty
+import org.ec4j.core.model.PropertyType
+
+internal data class FormatterTags(
+    val formatterTagOff: String?,
+    val formatterTagOn: String?,
+) {
+    companion object {
+        private val DISABLED_FORMATTER_TAGS = FormatterTags(null, null)
+
+        fun from(editorConfig: EditorConfig): FormatterTags =
+            if (editorConfig[FORMATTER_TAGS_ENABLED_PROPERTY]) {
+                FormatterTags(
+                    formatterTagOff = editorConfig[FORMATTER_TAG_OFF_ENABLED_PROPERTY],
+                    formatterTagOn = editorConfig[FORMATTER_TAG_ON_ENABLED_PROPERTY],
+                )
+            } else {
+                DISABLED_FORMATTER_TAGS
+            }
+
+        val FORMATTER_TAGS_ENABLED_PROPERTY: EditorConfigProperty<Boolean> =
+            EditorConfigProperty(
+                type =
+                PropertyType.LowerCasingPropertyType(
+                    "ij_formatter_tags_enabled",
+                    "When enabled, IntelliJ IDEA Formatter tags will be respected (e.g. disable and enable all ktlint rules for the " +
+                            "code enclosed between the formatter tags.",
+                    PropertyType.PropertyValueParser.BOOLEAN_VALUE_PARSER,
+                    setOf(true.toString(), false.toString()),
+                ),
+                defaultValue = false,
+            )
+
+        val FORMATTER_TAG_OFF_ENABLED_PROPERTY: EditorConfigProperty<String> =
+            EditorConfigProperty(
+                type =
+                PropertyType.LowerCasingPropertyType(
+                    "ij_formatter_off_tag",
+                    "The IntelliJ IDEA formatter tag to disable formatting. This also disables the ktlint rules.",
+                    PropertyType.PropertyValueParser.IDENTITY_VALUE_PARSER,
+                ),
+                defaultValue = "@formatter:off",
+            )
+
+        val FORMATTER_TAG_ON_ENABLED_PROPERTY: EditorConfigProperty<String> =
+            EditorConfigProperty(
+                type =
+                PropertyType.LowerCasingPropertyType(
+                    "ij_formatter_on_tag",
+                    "The IntelliJ IDEA formatter tag to enable formatting. This also enables the ktlint rules.",
+                    PropertyType.PropertyValueParser.IDENTITY_VALUE_PARSER,
+                ),
+                defaultValue = "@formatter:on",
+            )
+    }
+}
diff --git a/...-engine/src/main/kotlin/com/pinterest/ktlint/rule/engine/internal/RuleExecutionContext.kt b/...-engine/src/main/kotlin/com/pinterest/ktlint/rule/engine/internal/RuleExecutionContext.kt
@@ -39,7 +39,7 @@ internal class RuleExecutionContext private constructor(
     }
 
     fun rebuildSuppressionLocator() {
-        suppressionLocator = SuppressionLocatorBuilder.buildSuppressedRegionsLocator(rootNode)
+        suppressionLocator = SuppressionLocatorBuilder.buildSuppressedRegionsLocator(rootNode, editorConfig)
     }
 
     fun executeRule(