pinterest/ktlint 0.49.0

on GitHub

WARNING: This version of KtLint contains a number of breaking changes in KtLint CLI and KtLint API. If you are using KtLint with custom ruleset jars or custom reporter jars, then those need to be upgraded before you can use them with this version of ktlint. Please contact the maintainers of those jars and ask them to upgrade a.s.a.p.

All rule id's in the output of Ktlint are now prefixed with a rule set. Although KtLint currently supports standard rules to be unqualified, users are encouraged to include the rule set id in all references to rules. This includes following:

• The --disabled-rules parameter in KtLint CLI.
• The .editorconfig properties used to enable or disable rule and rule sets. Note that properties disabled_rules and ktlint_disabled_rules have been removed in this release. See disabled rules for more information.
• The source element in the KtLint CLI baseline.xml file. Regenerating this file, fixes all rule references automatically.
• The KtLint disable directives ktlint-enable / ktlint-disable and the @Suppress('ktlint:...') annotations.
• The VisitorModifier.RunAfterRule.

Moving experimental rules to standard rule set

The experimental rule set has been merged with standard rule set. The rules which formerly were part of the experimental rule set are still being treated as before. The rules will only be run in case .editorconfig property ktlint_experimental is enabled or in case the rule is explicitly enabled.

Note that the prefix experimental: has to be removed from all references to this rule. Check references in:

• The --disabled-rules parameter in KtLint CLI.
• The .editorconfig properties used to enable or disable rule and rule sets. Note that properties disabled_rules and ktlint_disabled_rules have been removed in this release. See disabled rules for more information.
• The KtLint disable directives ktlint-enable / ktlint-disable and the @Suppress('ktlint:...') annotations.
• The VisitorModifier.RunAfterRule.

Promote experimental rules to non-experimental

The rules below have been promoted to non-experimental rules:

• block-comment-initial-star-alignment
• class-naming
• comment-wrapping
• function-return-type-spacing
• function-start-of-body-spacing
• function-type-reference-spacing
• fun-keyword-spacing
• kdoc-wrapping
• modifier-list-spacing
• nullable-type-spacing
• spacing-between-function-name-and-opening-parenthesis
• unnecessary-parentheses-before-trailing-lambda

Note that this only affects users that have enabled the standard ruleset while having the experimental rules disabled.

API Changes & RuleSet providers & Reporter Providers

This release is intended to be the last release before the 1.0.x release of ktlint. If all goes as planned, the 1.0.x release does not contain any new breaking changes with except of removal of functionality which is deprecated in this release.

This release contains a lot of breaking changes which aims to improve the future maintainability of Ktlint. If you get stuck while migrating, please reach out to us by creating an issue.

Experimental rules

Rules in custom rule sets can now be marked as experimental by implementing the Rule.Experimental interface on the rule. Rules marked with this interface will only be executed by Ktlint if .editorconfig property ktlint_experimental is enabled or if the rule itself has been enabled explicitly.

When using this feature, experimental rules should not be defined in a separate rule set as that would require a distinct rule set id. When moving a rule from an experimental rule set to a non-experimental rule set this would mean that the qualified rule id changes. For users of such rules this means that ktlint directives to suppress the rule and properties in the .editorconfig files have to be changed.

EditorConfig

Field defaultAndroidValue in class EditorConfigProperty has been renamed to androidStudioCodeStyleDefaultValue. New fields ktlintOfficialCodeStyleDefaultValue and intellijIdeaCodeStyleDefaultValue have been added. Read more about this in the section "Ktlint Official code style".

The .editorconfig properties disabled_rules and ktlint_disabled_rules are no longer supported. Specifying those properties in the editorConfigOverride or editorConfigDefaults result in warnings at runtime.

'Ktlint Official` code style and renaming of existing code styles

A new code style ktlint_official is introduced. This code style is work in progress but will become the default code style in the 1.0 release. Please try out the new code style and provide your feedback via the issue tracker.

This ktlint_official code style combines the best elements from the Kotlin Coding conventions and Android's Kotlin styleguide. This code style also provides additional formatting on topics which are not (explicitly) mentioned in those conventions and style guide. But do note that this code style sometimes formats code in a way which is not accepted by the default code formatters in IntelliJ IDEA and Android Studio. The formatters of those editors produce nicely formatted code in the vast majority of cases. But in a number of edge cases, the formatting contains bugs which are waiting to be fixed for several years. The new code style formats code in a way which is compatible with the default formatting of the editors whenever possible. When using this codestyle, it is best to disable (e.g. not use) code formatting in the editor.

The existing code styles have been renamed to make more clear what the basis of the code style is.

The official code style has been renamed to intellij_idea. Code formatted with this code style aims to be compatible with default formatter of IntelliJ IDEA. This code style is based on Kotlin Coding conventions. If .editorconfig property ktlint_code_style has been set to android then do not forget to change the value of that property to intellij_idea. When not set, this is still the default code style of ktlint 0.49. Note that the default code style will be changed to ktlint_official in the 1.0 release.

Code style android has been renamed to android_studio. Code formatted with this code style aims to be compatible with default formatter of Android Studio. This code style is based on Android's Kotlin styleguide. If .editorconfig property ktlint_code_style has been set to android then do not forget to change the value of that property to android_studio.

Package restructuring and class relocation

The internal structure of the Ktlint project has been revised. The Ktlint CLI and KtLint API modules have been decoupled where possible. Modules have been restructured and renamed. See API Overview for more information.

This is the last release that contains module ktlint-core as it had too many responsibilities. All classes in this module are relocated to other modules. Some classes have also been renamed. See tables below for details. Classes that are left behind in the ktlint-core module are deprecated and were kept in this version for backwards compatibility only. The ktlint-core module will be removed in Ktlint 0.50.x.

Classes below have been moved from module ktlint-core to the new module ktlint-rule-engine-core:

Classes below have been moved from module ktlint-core to the new module ktlint-rule-engine:

Class com.pinterest.ktlint.core.KtLint.Code.CodeFile has been replaced with factory method com.pinterest.ktlint.rule.engine.api.Code.fromFile. Likewise, class com.pinterest.ktlint.core.KtLint.Code.CodeSnippet has been replaced with factory method com.pinterest.ktlint.rule.engine.api.Code.fromSnippet.

Class below has been moved from module ktlint-core to the new module ktlint-cli-ruleset-core:

Class below has been moved from module ktlint-core to the new module ktlint-cli-reporter-core:

Class below has been moved from module ktlint-core to the new module ktlint-logger:

Class below has been relocated from module ktlint-core to module ktlint-cli:

Module ktlint-reporter-baseline has been renamed to ktlint-cli-reporter-baseline. Class below has been relocated:

Module ktlint-reporter-checkstyle has been renamed to ktlint-cli-reporter-checkstyle. Class below has been relocated:

Module ktlint-reporter-format has been renamed to ktlint-cli-reporter-format. Class below has been relocated:

Module ktlint-reporter-html has been renamed to ktlint-cli-reporter-html. Class below has been relocated:

Module ktlint-reporter-json has been renamed to ktlint-cli-reporter-json. Class below has been relocated:

Module ktlint-reporter-plain has been renamed to ktlint-cli-reporter-plain. Class below has been relocated:

Module ktlint-reporter-plain-summary has been renamed to ktlint-cli-reporter-plain-summary. Class below has been relocated:

Module ktlint-reporter-sarif has been renamed to ktlint-cli-reporter-sarif. Class below has been relocated:

Custom Ruleset Provider RuleSetProviderV2

Custom rule sets build for older versions of KtLint are no longer supported by this version of KtLint. The com.pinterest.ktlint.core.RuleSetProviderV2 interface has been replaced with RuleSetProviderV3. The accompanying interfaces com.pinterest.ktlint.core.RuleProvider and com.pinterest.ktlint.core.Rule have been replaced with com.pinterest.ktlint.ruleset.core.api.RuleProvider and com.pinterest.ktlint.ruleset.core.api.Rule respectively.

Contrary to RuleSetProviderV2, the RuleSetProviderV3 no longer contains information about the rule set. About information now has to be specified in the new Rule class. This allows custom rule set providers to combine rules originating from different rule sets into a new rule set without loosing information about its origin. The type of the id of the rule set is changed from String to RuleSetId.

Note that due to renaming and relocation of the RuleSetProviderV3 interface the name of the service provider in the custom reporter needs to be changed from resources/META-INF/services/com.pinterest.ktlint.core.RuleSetProviderV2 to resources/META-INF/services/com.pinterest.ktlint.cli.ruleset.core.api.RuleSetProviderV3.

The rule id's in com.pinterest.ktlint.ruleset.core.api.Rule have been changed from type String to RuleId. A RuleId has a value that must adhere the convention "rule-set-id:rule-id". The rule set id standard is reserved for rules which are maintained by the KtLint project. Rules created by custom rule set providers and API Consumers should use a prefix other than standard to mark the origin of rules which are not maintained by the KtLint project.

When wrapping a rule from the ktlint project and modifying its behavior, please change the ruleId and about fields in the wrapped rule, so that it is clear to users whenever they use the original rule provided by KtLint versus a modified version which is not maintained by the KtLint project.

The typealias com.pinterest.ktlint.core.api.EditorConfigProperties has been replaced with com.pinterest.ktlint.rule.engine.core.api.EditorConfig. The interface com.pinterest.ktlint.core.api.UsesEditorConfigProperties has been removed. Instead, the Rule property usesEditorConfigProperties needs to be set. As a result of those changes, the beforeFirstNode function in each rule has to changed to something like below:

public class SomeRule : Rule(
  ruleId = RuleId("some-rule-set:some-rule"),
  usesEditorConfigProperties = setOf(MY_EDITOR_CONFIG_PROPERTY),
) {
  private lateinit var myEditorConfigProperty: MyEditorConfigProperty

  override fun beforeFirstNode(editorConfig: EditorConfig) {
    myEditorConfigProperty = editorConfig[MY_EDITOR_CONFIG_PROPERTY]
  }
  
  ...
}

Fields loadOnlyWhenOtherRuleIsLoaded and runOnlyWhenOtherRuleIsEnabled have been removed from class com.pinterest.ktlint.rule.engine.core.api.Rule.VisitorModifier.RunAfterRule and are replaced with a single field mode. The mode either contains value REGARDLESS_WHETHER_RUN_AFTER_RULE_IS_LOADED_OR_DISABLED or ONLY_WHEN_RUN_AFTER_RULE_IS_LOADED_AND_ENABLED.

Custom Reporter Provider ReporterProvider

Custom Reporters build for older versions of KtLint are no longer supported by this version of KtLint. The com.pinterest.ktlint.core.ReporterProvider interface has been replaced with com.pinterest.ktlint.cli.reporter.core.api.ReporterProviderV2. The accompanying interface com.pinterest.ktlint.core.Reporter has been replaced with com.pinterest.ktlint.cli.reporter.core.api.ReporterV2.

Note that due to renaming and relocation of the ReporterProviderV2 interface the name of the service provider in the custom reporter needs to be changed from resources/META-INF/services/com.pinterest.ktlint.core.ReporterProvider to resources/META-INF/services/com.pinterest.ktlint.cli.reporter.core.api.ReporterProviderV2.

The biggest change in the ReporterV2 is the replacement of the LintError class with KtlintCliError class. The latter class now contains a status field which more clearly explains the difference between a lint error which can be autocorrected versus a lint error that actually has been autocorrected.

Custom rules provided by API Consumer

API Consumers provide a set of rules directly to the Ktlint Rule Engine. The com.pinterest.ktlint.core.Rule has been replaced with com.pinterest.ktlint.ruleset.core.api.Rule.

The type of the rule id's has been changed from type String to RuleId. A RuleId has a value that must adhere to the convention "rule-set-id:rule-id". Rule set id standard is reserved for rules which are maintained by the KtLint project. Custom rules created by the API Consumer should use a prefix other than standard to clearly mark the origin of rules which are not maintained by the KtLint project.

Also, the field About has been added. This field specifies the name of the maintainer, and the repository url and issue tracker url of the rule. The about information of a rule is printed whenever a rule throws an exception which is caught by the Ktlint Rule Engine.

When wrapping a rule from the ktlint project and modifying its behavior, please change the ruleId and about fields in the wrapped rule, so that it is clear to users whenever they use the original rule provided by KtLint versus a modified version which is not maintained by the KtLint project.

The typealias com.pinterest.ktlint.core.api.EditorConfigProperties has been replaced with com.pinterest.ktlint.rule.engine.core.api.EditorConfig. The interface com.pinterest.ktlint.core.api.UsesEditorConfigProperties has been removed. Instead, the Rule property usesEditorConfigProperties needs to be set. As a result of those changes, the beforeFirstNode function in each rule has to changed to something like below:

public class SomeRule : Rule(
  ruleId = RuleId("some-rule-set:some-rule"),
  usesEditorConfigProperties = setOf(MY_EDITOR_CONFIG_PROPERTY),
) {
  private lateinit var myEditorConfigProperty: MyEditorConfigProperty

  override fun beforeFirstNode(editorConfig: EditorConfig) {
    myEditorConfigProperty = editorConfig[MY_EDITOR_CONFIG_PROPERTY]
  }
  
  ...
}

Fields loadOnlyWhenOtherRuleIsLoaded and runOnlyWhenOtherRuleIsEnabled have been removed from class com.pinterest.ktlint.rule.engine.core.api.Rule.VisitorModifier.RunAfterRule and are replaced with a single field mode. The mode either contains value REGARDLESS_WHETHER_RUN_AFTER_RULE_IS_LOADED_OR_DISABLED or ONLY_WHEN_RUN_AFTER_RULE_IS_LOADED_AND_ENABLED.

Like before, the API Consumer can still offer a mix of rules originating from ktlint-ruleset-standard as well as custom rules.

.editorconfig property max_line_length default value

Previously, the default value for .editorconfig property max_line_length was set to -1 in ktlint unless the property was defined explicitly in the .editorconfig or when ktlint_code_style was set to Android. As a result of that rules have to check that max_line_length contains a positive value before checking that the actual line length is exceeding the maximum. Now the value Int.MAX_VALUE (use constant MAX_LINE_LENGTH_PROPERTY_OFF to refer to that value) is used instead.

Psi filename replaces FILE_PATH_USER_DATA_KEY

Constant KtLint.FILE_PATH_USER_DATA_KEY has been removed. The file path is passed correctly to the node with element type FILE and can be retrieved as follows:

if (node.isRoot()) {
  val filePath = (node.psi as? KtFile)?.virtualFilePath
    ...
}

Added

• Add new code style ktlint_offical. The code style is work in progress and should be considered a preview. It is intended to become the default code style in the next release. Please try it out and give your feedback. See code styles for more information. The following rules have been added to the ktlint_official code style (the rules can also be run for other code styles when enabled explicitly):
  • Add new experimental rule no-empty-first-line-in-class-body. This rule disallows a class to start with a blank line.
  • Add new experimental rule if-else-bracing. This rules enforces consistent usage of braces in all branches of a single if, if-else or if-else-if statement.
  • Add new experimental rule no-consecutive-comments. This rule disallows consecutive comments except EOL comments (see [examples](See https://pinterest.github.io/ktlint/rules/experimental/#disallow-consecutive-comments)).
  • Add new experimental rule try-catch-finally-spacing. This rule enforces consistent spacing in try-catch, try-finally and try-catch-finally statement. This rule can also be run for other code styles, but then it needs to be enabled explicitly.
  • Add new experimental rule no-blank-line-in-list. This rule disallows blank lines to be used in super type lists, type argument lists, type constraint lists, type parameter lists, value argument lists, and value parameter lists. (#1224)
  • Add new experimental rule multiline-expression-wrapping. This forces a multiline expression as value in an assignment to start on a separate line. (#1217)
  • Add new experimental rule string-template-indent. This forces multiline string templates which are post-fixed with .trimIndent() to be formatted consistently. The opening and closing """ are placed on separate lines and the indentation of the content of the template is aligned with the """. (#925)
  • Add new experimental rule if-else-wrapping. This enforces that a single line if-statement is kept simple. A single line if-statement may contain no more than one else-branch. The branches a single line if-statement may not be wrapped in a block. (#812)
• Wrap the type or value of a function or class parameter in case the maximum line length is exceeded parameter-wrapping (#1846)
• Wrap the type or value of a property in case the maximum line length is exceeded property-wrapping (#1846)
• Recognize Kotlin Script when linting and formatting code from stdin with KtLint CLI (#1832)
• Support Bill of Materials (BOM), now you can integrate Ktlint in your build.gradle like:

  dependencies {
      implementation(platform("com.pinterest:ktlint-bom:0.49.0"))
      implementation("com.pinterest:ktlint-core")
      implementation("com.pinterest:ktlint-reporter-html")
      implementation("com.pinterest:ktlint-ruleset-standard")
      ...
  }

• Add new experimental rule enum-wrapping for all code styles. An enum should either be a single line, or each enum entry should be defined on a separate line. (#1903)

Removed

• Remove support of the .editorconfig properties disabled_rules and ktlint_disabled_rules. See disabled rules for more information.
• Remove CLI option --print-ast. Use IntelliJ IDEA PsiViewer plugin instead. (#1925)

Fixed

• An enumeration class having a primary constructor and in which the list of enum entries is followed by a semicolon then do not remove the semicolon in case it is followed by code element no-semi (#1733)
• Do not add the (first line of the) body expression on the same line as the function signature in case the max line length would be exceeded. function-signature.
• Do not add the first line of a multiline body expression on the same line as the function signature in case function body expression wrapping property is set to multiline. function-signature.
• Disable the standard:filename rule whenever Ktlint CLI is run with option --stdin (#1742)
• The parameters of a function literal containing a multiline parameter list are aligned with first parameter whenever the first parameter is on the same line as the start of that function literal (not allowed in ktlint_official code style) indent (#1756)
• Do not throw exception when enum class does not contain entries trailing-comma-on-declaration-site (#1711)
• Fix continuation indent for a dot qualified array access expression in ktlint_official code style only indent (#1540)
• When generating the .editorconfig use value off for the max_line_length property instead of value -1 to denote that lines are not restricted to a maximum length (#1824)
• Do not report an "unnecessary semicolon" after adding a trailing comma to an enum class containing a code element after the last enum entry trailing-comma-on-declaration-site (#1786)
• A newline before a function return type should not be removed in case that leads to exceeding the maximum line length function-return-type-spacing (#1764)
• Wrap annotations on type arguments in same way as with other constructs annotation, wrapping (#1725)
• Fix indentation of try-catch-finally when catch or finally starts on a newline indent (#1788)
• Fix indentation of a multiline typealias indent (#1788)
• Fix false positive when multiple KDOCs exists between a declaration and another annotated declaration spacing-between-declarations-with-annotations (#1802)
• Fix false positive when a single line statement containing a block having exactly the maximum line length is preceded by a blank line wrapping (#1808)
• Fix false positive when a single line contains multiple dot qualified expressions and/or safe expressions indent (#1830)
• Enforce spacing around rangeUntil operator ..< similar to the range operator .. in range-spacing (#1858)
• When .editorconfig property ij_kotlin_imports_layout contains a | but no import exists that match any pattern before the first | then do not report a violation nor insert a blank line import-ordering (#1845)
• When negate-patterns only are specified in Ktlint CLI then automatically add the default include patterns (**/*.kt and **/*.kts) so that all Kotlin files excluding the files matching the negate-patterns will be processed (#1847)
• Do not remove newlines from multiline type parameter lists type-parameter-list-spacing (#1867)
• Wrap each type parameter in a multiline type parameter list wrapping (#1867)
• Allow value arguments with a multiline expression to be indented on a separate line indent (#1217)
• When enabled, the ktlint rule checking is disabled for all code surrounded by the formatter tags (see faq) (#670)
• Remove trailing comma if last two enum entries are on the same line and trailing commas are not allowed. trailing-comma-on-declaration-site (#1905)
• Wrap annotated function parameters to a separate line in code style ktlint_official only. function-signature, parameter-list-wrapping (#1908)
• Wrap annotated projection types in type argument lists to a separate line annotation (#1909)
• Add newline after adding trailing comma in parameter list of a function literal trailing-comma-on-declaration-site (#1911)
• Wrap annotations before class constructor in code style ktlint_official. annotation (#1916)
• Annotations on type projections should be wrapped in same way as other annotations annotation (#1917)
• An if-else followed by an elvis operator should not be wrapped in an else-block multiline-if-else (#1904)

Changed

• Wrap the parameters of a function literal containing a multiline parameter list (only in ktlint_official code style) parameter-list-wrapping (#1681).
• KtLint CLI exits with an error in any of following cases (this list is not exhaustive):
  • A custom ruleset jar is to be loaded and that jar contains a deprecated RuleSetProviderV2.
  • A custom ruleset jar is to be loaded and that jar does not contain the required RuleSetProviderV3.
  • A custom reporter jar is to be loaded and that jar contains a deprecated ReporterProvider.
  • A custom reporter jar is to be loaded and that jar does not contain the required ReporterProviderV2.
• Disable the default patterns if the option --patterns-from-stdin is specified (#1793)
• Update Kotlin development version to 1.8.20 and Kotlin version to 1.8.20.
• Revert to matrix build to speed up build, especially for the Windows related build (#1787)
• For the new code style ktlint_official, do not allow wildcard imports java.util and kotlinx.android.synthetic by default. Important: .editorconfig property ij_kotlin_packages_to_use_import_on_demand needs to be set to value unset in order to enforce IntelliJ IDEA default formatter to not generate wildcard imports no-wildcard-imports (#1797)
• Convert a single line block comment to an EOL comment if not preceded or followed by another code element on the same line comment-wrapping (#1941)
• Ignore a block comment inside a single line block comment-wrapping (#1942)