Add blank line check between package and import statements by maheen8q · Pull Request #3266 · pinterest/ktlint

maheen8q · 2026-03-15T12:26:41Z

Description

Add blank line check between package and import statements

The Android Kotlin Style Guide requires exactly one blank line between
the package statement and import statements:
https://developer.android.com/kotlin/style-guide#structure

ktlint was not enforcing this rule. This PR extends the existing
PackageNameRule to also check for the missing blank line, with
autocorrect support.

Fixes #3251

Checklist

Before submitting the PR, please check following (checks which are not relevant may be ignored):

[✅] Commit message are well written. In addition to a short title, the commit message also explain why a change is made.
[✅] At least one commit message contains a reference Closes #<xxx> or Fixes #<xxx> (replace<xxx> with issue number)
[✅] Tests are added
KtLint format has been applied on source code itself and violations are fixed
[✅] PR title is short and clear (it is used as description in the release changelog)
[✅] PR description added (background information)

Documentation is updated. See difference between snapshot and release documentation

[] Snapshot documentation in case documentation is to be released together with a code change
Release documentation in case documentation is related to a released version of ktlint and has to be published as soon as the change is merged to master

…, and resolve TOOD's

Remove deprecated methods which were marked for removal in Ktlint 2.0, and resolve TODO's

If a files starts with the UTF BOM character, it is removed before the file is formatted, and restored after formatting. When the UTF BOM character is not at the start of the file, it should not be removed before formatting, and has to be preserved in the formatted file. The existing test for a file starting with UTF BOM character was not effective because the file was not modified at all. In that case, the unmodified input is returned by ktlint format. Closes pinterest#3220

paul-dingemans

Tnx for giving this a try so quickly. Please try to adhere more with existing code patterns and standards in current ktlint code.

paul-dingemans · 2026-03-15T13:19:26Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

 }
 }
+ // https://developer.android.com/kotlin/style-guide#structure
+ if (node.elementType == IMPORT_DIRECTIVE) {


Looking backwards. (or up) in the AST to find the spot where to fix the AST causes problems. You need to find the PACKAGE statement, and then look forwards whether it is followed by a blank line instead.

paul-dingemans · 2026-03-15T13:20:40Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

+ if (newlineCount < 2) {
+ val decision = emit(
+ node.startOffset,
+ "Missing blank line between package statement and import statements",


Follow the existing patterns in other rules, and use the .ifAutocorrectAllowed extension to fix the violation.

paul-dingemans · 2026-03-15T13:22:04Z

...-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRuleTest.kt

+ package com.example
+ import foo.bar
+ """.trimIndent()
+ val formattedCode = """


It looks like that you did not apply Ktlint formatting.

paul-dingemans · 2026-03-15T13:22:44Z

...-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRuleTest.kt

 }
+
+ @Test
+ fun `passes when blank line exists between package and import`() {


Use naming patterns consisting with rest of ktlint, eg Given ... then (all tests)

paul-dingemans · 2026-03-15T13:23:31Z

...-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRuleTest.kt

+ }
+
+ @Test
+ fun `autocorrects missing blank line between package and import`() {


This test should be merged with previous test. There is no need to have separate tests for report and fixing.

paul-dingemans · 2026-03-15T13:23:58Z

...-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRuleTest.kt

+ .hasLintViolation(
+ line = 2,
+ col = 1,
+ detail = "Missing blank line between package statement and import statements",


Don use named arguments for hasLintViolation

paul-dingemans · 2026-03-15T13:24:02Z

...-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRuleTest.kt

+ """.trimIndent()
+ packageNameRuleAssertThat(code)
+ .hasLintViolation(2, 1, "Missing blank line between package statement and import statements")
+ .isFixedTo(formattedCode)


This is a non-existing extension function in the Ktlint AssertThat library. Probably you meant isFormattedAs/

…tatements

maheen8q · 2026-03-15T19:01:38Z

Review comments addressed, please take another look

…terest#3267) Fix backwards compatibility with Ktlint 1.x rulesets by readding the RuleAutocorrectApproveHandler, and overriding the methods of the RuleV2 method to fallback to the actual implementation of the Rule (V1). In Ktlint CLI ensure that custom ruleset with RuleSetProviderV3 interface is loaded successful, and a deprecation warning is printed. Fix Ktlint CLI to load the custom rule sets only once by initialized the ruleProviders lazily. Remove the main,kt.test file from the custom-ruleset resource directory as it is not used.

paul-dingemans

Tnx for follow-up. I have some more remarks.

paul-dingemans · 2026-03-15T19:45:22Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

+ val nextCodeSibling = packageNode.nextCodeSibling20
+ if (nextCodeSibling?.elementType == IMPORT_DIRECTIVE) {
+ val newlineCount = nextSibling.text.count { it == '\n' }
+ if (newlineCount < 2) {


The style guide describes that there should be exactly 1 blank line between package and imports. So test on on "newLineCount != 2, and add a test:

package foo import bar.*

Also, tests corner case with comment above imports

package foo // Some comment import bar.*

paul-dingemans · 2026-03-15T19:49:02Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

 }
 }
+
+ // https://developer.android.com/kotlin/style-guide#structure


In hindsight this should be in separate rule. I asked you change extend the package rule if it existed. When I wrote that comment, I did not have access to the repository to check that. Now I see that the new check is added to the PackageNameRule which might be confusing.

paul-dingemans · 2026-03-15T20:14:56Z

...-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRuleTest.kt

 }
-}
+
+ // FIX: Renamed using "Given ... then" pattern


Remove all "FIX" comments

…results in a compilation error (pinterest#3268) Closes pinterest#3213

…portSpacingRule

maheen8q · 2026-03-16T00:46:08Z

Hi @paul-dingemans , thanks for the feedback! I've moved the blank line check into a separate PackageImportSpacingRule as suggested. Here's a summary of all changes made:

Moved blank line between package and import check to new PackageImportSpacingRule
Cleaned up PackageNameRule to only handle package naming validation
Used newlineCount != 2 to enforce exactly 1 blank line
Created PackageImportSpacingRuleTest with all test cases including:

No blank line between package and import
Too many blank lines between package and import
Comment above import edge case

Removed blank line tests from PackageNameRuleTest

Please take another look, happy to make any further changes!

paul-dingemans · 2026-03-16T17:09:11Z

...dard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageImportSpacingRule.kt

+ * https://developer.android.com/kotlin/style-guide#structure
+ */
+@SinceKtlint("1.x", EXPERIMENTAL)
+public class PackageImportSpacingRule : StandardRule("package-import-spacing") {


This should have resulted in a failing test. The rule is only annotated with an EXPERIMENTAL tag, but has not implemented the marker interface Experimental.

Please change to:

@SinceKtlint("2.,0", EXPERIMENTAL) public class PackageImportSpacingRule : StandardRule("package-import-spacing"), RuleV2.Experimental {

...dard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageImportSpacingRule.kt

paul-dingemans · 2026-03-16T17:17:09Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

+ val VALID_PACKAGE_NAME_REGEXP =
+ "[a-z_][a-zA-Z\\d_]*(\\.[a-z_][a-zA-Z\\d_]*)*"
+ .regExIgnoringDiacriticsAndStrokesOnLetters()


Please revert all changes on the PackageName rule.

paul-dingemans · 2026-03-16T17:17:16Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

 ) {
 node
- .takeIf { node.elementType == PACKAGE_DIRECTIVE }
+ .takeIf { it.elementType == PACKAGE_DIRECTIVE }


Please revert all changes on the PackageName rule.

paul-dingemans · 2026-03-16T17:17:21Z

...eset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageNameRule.kt

- // The Kotlin inspections (preference > Editor > Inspections) for 'Package naming convention' allows
- // underscores as well. But as this has been forbidden by KtLint since early versions, this is still
- // prohibited.


Please revert all changes on the PackageName rule.

…results in a compilation error (pinterest#3269) Closes pinterest#3213

maheen8q · 2026-03-16T21:57:44Z

Hi Paul, thank you for the detailed feedback and the AST explanation!
I have updated the PR with the following changes:
PackageImportSpacingRule:
Implemented the RuleV2.Experimental marker interface as requested.
Updated the @SinceKtlint annotation to ("2.0", EXPERIMENTAL).
Refactored the logic to use the siblings() and takeWhile { it.elementType != IMPORT_LIST } approach. This is much cleaner and handles intermediate comments correctly.
PackageNameRule:
Reverted all changes to this rule, including the regex and the it.elementType refactor, to keep this PR focused and consistent with the existing codebase.
Let me know if there is anything else you'd like me to adjust.

…tatements

…portSpacingRule

…blank-line' into pr/3266 # Conflicts: # ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageImportSpacingRule.kt # ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/PackageImportSpacingRuleTest.kt

paul-dingemans · 2026-03-17T17:52:34Z

Hmm, I had to make quite some changes to make it actually work. Did you run the tests on your local machine? Also, documentation was missing.

paul-dingemans and others added 5 commits March 14, 2026 16:09

Remove deprecated methods which were marked for removal in Ktlint 2.0…

531eccb

…, and resolve TOOD's

Fix api contracts

f6d5e91

Add blank line check between package and import statements

943e893

Merge pull request pinterest#3263 from pinterest/cleanup-deprecations

9d987e0

Remove deprecated methods which were marked for removal in Ktlint 2.0, and resolve TODO's

paul-dingemans requested changes Mar 15, 2026

View reviewed changes

Add rule to enforce blank line between package statement and import s…

0555150

…tatements

maheen8q requested a review from paul-dingemans March 15, 2026 19:01

paul-dingemans requested changes Mar 15, 2026

View reviewed changes

paul-dingemans and others added 2 commits March 15, 2026 21:16

Do not wrap an annotated expression before a lambda expression as it …

c5feb55

…results in a compilation error (pinterest#3268) Closes pinterest#3213

Address review comments - move blank line check to separate PackageIm…

eaea76c

…portSpacingRule

maheen8q requested a review from paul-dingemans March 16, 2026 15:17

paul-dingemans reviewed Mar 16, 2026

View reviewed changes

paul-dingemans requested changes Mar 16, 2026

View reviewed changes

paul-dingemans and others added 2 commits March 16, 2026 20:00

Do not wrap an annotated expression before a lambda expression as it …

7d6ada1

…results in a compilation error (pinterest#3269) Closes pinterest#3213

reviews-addressed

00f69c1

maheen8q and others added 10 commits March 17, 2026 18:28

Add blank line check between package and import statements

3bc83a7

Add rule to enforce blank line between package statement and import s…

0b33e98

…tatements

Address review comments - move blank line check to separate PackageIm…

729a805

…portSpacingRule

reviews-addressed

7da2f63

Revert changes on PackageNameRule(Test)

afcb4d1

Fix formatting

9d2d095

Fix API contract

5bcbd0f

Add documentation

d09b947

Fix failing test

b1e2699

Add more tests

fb6392f

paul-dingemans added 2 commits March 17, 2026 18:43

Add rule to StandardRuleSetProvider

5a444f0

Fix formatting violations

c9fce28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add blank line check between package and import statements#3266

Add blank line check between package and import statements#3266
maheen8q wants to merge 24 commits intopinterest:masterfrom
maheen8q:package-import-blank-line

maheen8q commented Mar 15, 2026 •

edited by paul-dingemans

Loading

paul-dingemans left a comment

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

maheen8q commented Mar 15, 2026

paul-dingemans left a comment

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

paul-dingemans Mar 15, 2026

maheen8q commented Mar 16, 2026

paul-dingemans Mar 16, 2026

Uh oh!

paul-dingemans Mar 16, 2026

paul-dingemans Mar 16, 2026

paul-dingemans Mar 16, 2026

maheen8q commented Mar 16, 2026

paul-dingemans commented Mar 17, 2026

Labels

2 participants

Conversation

maheen8q commented Mar 15, 2026 • edited by paul-dingemans Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

paul-dingemans left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maheen8q commented Mar 15, 2026

paul-dingemans left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maheen8q commented Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maheen8q commented Mar 16, 2026

paul-dingemans commented Mar 17, 2026

Labels

2 participants

maheen8q commented Mar 15, 2026 •

edited by paul-dingemans

Loading