Recommendation 3.1 - recommended order of imports (#380)

### What's done:
* Implementation
* Tests

diktat-analysis.yml

@@ -136,9 +136,12 @@
 - name: FILE_CONTAINS_ONLY_COMMENTS
   enabled: true
   configuration: {}
+  # order imports alphabetically
 - name: FILE_UNORDERED_IMPORTS
   enabled: true
-  configuration: {}
+  configuration:
+    # use logical imports grouping with sorting inside of a group
+    useRecommendedImportsOrder: true
 - name: FILE_INCORRECT_BLOCKS_ORDER
   enabled: true
   configuration: {}

diktat-common/src/test/resources/test-rules-config.yml

@@ -149,7 +149,9 @@
   configuration: {}
 - name: FILE_WILDCARD_IMPORTS
   enabled: true
-  configuration: {}
+  configuration:
+    allowedWildcards: "" # Allowed wildcards for imports (e.g. "import org.cqfn.diktat.*, import org.jetbrains.kotlin.*")
+    useRecommendedImportsOrder: true
 - name: NO_BRACES_IN_CONDITIONALS_AND_LOOPS
   enabled: true
   configuration: {}

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/files/FileStructureRule.kt

@@ -12,12 +12,15 @@ import com.pinterest.ktlint.core.ast.ElementType.PACKAGE_DIRECTIVE
 import com.pinterest.ktlint.core.ast.ElementType.WHITE_SPACE
 import org.cqfn.diktat.common.config.rules.RuleConfiguration
 import org.cqfn.diktat.common.config.rules.RulesConfig
+import org.cqfn.diktat.common.config.rules.getCommonConfiguration
 import org.cqfn.diktat.common.config.rules.getRuleConfig
 import org.cqfn.diktat.ruleset.constants.Warnings.FILE_CONTAINS_ONLY_COMMENTS
 import org.cqfn.diktat.ruleset.constants.Warnings.FILE_INCORRECT_BLOCKS_ORDER
 import org.cqfn.diktat.ruleset.constants.Warnings.FILE_NO_BLANK_LINE_BETWEEN_BLOCKS
 import org.cqfn.diktat.ruleset.constants.Warnings.FILE_UNORDERED_IMPORTS
 import org.cqfn.diktat.ruleset.constants.Warnings.FILE_WILDCARD_IMPORTS
+import org.cqfn.diktat.ruleset.rules.PackageNaming.Companion.PACKAGE_SEPARATOR
+import org.cqfn.diktat.ruleset.utils.StandardPlatforms
 import org.cqfn.diktat.ruleset.utils.findChildBefore
 import org.cqfn.diktat.ruleset.utils.getFileName
 import org.cqfn.diktat.ruleset.utils.handleIncorrectOrder
@@ -26,6 +29,7 @@ import org.jetbrains.kotlin.com.intellij.lang.ASTNode
 import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.LeafPsiElement
 import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.PsiWhiteSpaceImpl
 import org.jetbrains.kotlin.com.intellij.psi.tree.TokenSet
+import org.jetbrains.kotlin.name.Name
 import org.jetbrains.kotlin.psi.KtFile
 import org.jetbrains.kotlin.psi.KtImportDirective
 
@@ -43,6 +47,9 @@ class FileStructureRule(private val configRules: List<RulesConfig>) : Rule("file
     private lateinit var emitWarn: ((offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> Unit)
     private var isFixMode: Boolean = false
     private var fileName: String = ""
+    private val domainName by lazy {
+        configRules.getCommonConfiguration().value.domainName
+    }
 
     override fun visit(node: ASTNode,
                        autoCorrect: Boolean,
@@ -52,10 +59,14 @@ class FileStructureRule(private val configRules: List<RulesConfig>) : Rule("file
 
         if (node.elementType == ElementType.FILE) {
             fileName = node.getFileName()
-            val configuration = WildCardImportsConfig(
-                    this.configRules.getRuleConfig(FILE_WILDCARD_IMPORTS)?.configuration ?: mapOf()
+            val wildcardImportsConfig = WildCardImportsConfig(
+                this.configRules.getRuleConfig(FILE_WILDCARD_IMPORTS)?.configuration ?: emptyMap()
+            )
+            val importsGroupingConfig = ImportsGroupingConfig(
+                this.configRules.getRuleConfig(FILE_UNORDERED_IMPORTS)?.configuration ?: emptyMap()
             )
-            node.findChildByType(IMPORT_LIST)?.let { checkImportsOrder(it, configuration) }
+            node.findChildByType(IMPORT_LIST)
+                ?.let { checkImportsOrder(it, wildcardImportsConfig, importsGroupingConfig) }
             if (checkFileHasCode(node)) {
                 checkCodeBlocksOrderAndEmptyLines(node)
             }
@@ -64,7 +75,10 @@ class FileStructureRule(private val configRules: List<RulesConfig>) : Rule("file
     }
 
     private fun checkFileHasCode(node: ASTNode): Boolean {
-        val codeTokens = TokenSet.andNot(TokenSet.ANY, TokenSet.create(WHITE_SPACE, KDOC, BLOCK_COMMENT, EOL_COMMENT, PACKAGE_DIRECTIVE, IMPORT_LIST))
+        val codeTokens = TokenSet.andNot(
+            TokenSet.ANY,
+            TokenSet.create(WHITE_SPACE, KDOC, BLOCK_COMMENT, EOL_COMMENT, PACKAGE_DIRECTIVE, IMPORT_LIST)
+        )
         val hasCode = node.getChildren(codeTokens).isNotEmpty()
         if (!hasCode) {
             FILE_CONTAINS_ONLY_COMMENTS.warn(configRules, emitWarn, isFixMode, fileName, node.startOffset, node)
@@ -88,7 +102,14 @@ class FileStructureRule(private val configRules: List<RulesConfig>) : Rule("file
         listOfNotNull(copyrightComment, headerKdoc, fileAnnotations).handleIncorrectOrder({
             getSiblingBlocks(copyrightComment, headerKdoc, fileAnnotations, packageDirectiveNode)
         }) { astNode, beforeThisNode ->
-            FILE_INCORRECT_BLOCKS_ORDER.warnAndFix(configRules, emitWarn, isFixMode, astNode.text.lines().first(), astNode.startOffset, astNode) {
+            FILE_INCORRECT_BLOCKS_ORDER.warnAndFix(
+                configRules,
+                emitWarn,
+                isFixMode,
+                astNode.text.lines().first(),
+                astNode.startOffset,
+                astNode
+            ) {
                 node.moveChildBefore(astNode, beforeThisNode, true)
                 astNode.treeNext?.let { node.replaceChild(it, PsiWhiteSpaceImpl("\n\n")) }
             }
@@ -98,7 +119,8 @@ class FileStructureRule(private val configRules: List<RulesConfig>) : Rule("file
         arrayOf(copyrightComment, headerKdoc, fileAnnotations, packageDirectiveNode, importsList).forEach { astNode ->
             astNode?.treeNext?.apply {
                 if (elementType == WHITE_SPACE && text.count { it == '\n' } != 2) {
-                    FILE_NO_BLANK_LINE_BETWEEN_BLOCKS.warnAndFix(configRules, emitWarn, isFixMode, astNode.text.lines().first(), astNode.startOffset, astNode) {
+                    FILE_NO_BLANK_LINE_BETWEEN_BLOCKS.warnAndFix(configRules, emitWarn, isFixMode, astNode.text.lines().first(),
+                        astNode.startOffset, astNode) {
                         (this as LeafPsiElement).replaceWithText("\n\n${text.replace("\n", "")}")
                     }
                 }
@@ -107,56 +129,116 @@ class FileStructureRule(private val configRules: List<RulesConfig>) : Rule("file
     }
 
     @Suppress("UnsafeCallOnNullableType")
-    private fun checkImportsOrder(node: ASTNode, configuration: WildCardImportsConfig) {
+    private fun checkImportsOrder(
+        node: ASTNode,
+        wildCardImportsConfig: WildCardImportsConfig,
+        importsGroupingConfig: ImportsGroupingConfig
+    ) {
         val imports = node.getChildren(TokenSet.create(IMPORT_DIRECTIVE)).toList()
 
         // importPath can be null if import name cannot be parsed, which should be a very rare case, therefore !! should be safe here
         imports
                 .filter {
                     (it.psi as KtImportDirective).importPath!!.run {
-                        isAllUnder && toString() !in configuration.allowedWildcards
+                        isAllUnder && toString() !in wildCardImportsConfig.allowedWildcards
                     }
                 }
                 .forEach { FILE_WILDCARD_IMPORTS.warn(configRules, emitWarn, isFixMode, it.text, it.startOffset, it) }
 
-        val sortedImports = imports.sortedBy { it.text }
-        if (sortedImports != imports) {
+        val sortedImportsGroups = if (importsGroupingConfig.useRecommendedImportsOrder) {
+            regroupImports(imports.map { it.psi as KtImportDirective })
+                .map { group -> group.map { it.node } }
+        } else {
+            listOf(imports)
+        }
+            .map { group -> group.sortedBy { it.text } }
+
+        if (sortedImportsGroups.flatten() != imports) {
             FILE_UNORDERED_IMPORTS.warnAndFix(configRules, emitWarn, isFixMode, fileName, node.startOffset, node) {
-                rearrangeImports(node, imports, sortedImports)
+                rearrangeImports(node, imports, sortedImportsGroups)
             }
         }
     }
 
-    private fun rearrangeImports(node: ASTNode, imports: List<ASTNode>, sortedImports: List<ASTNode>) {
+    private fun rearrangeImports(node: ASTNode, imports: List<ASTNode>, sortedImportsGroups: List<List<ASTNode>>) {
         require(node.elementType == IMPORT_LIST)
         // move all commented lines among import before imports block
         node.getChildren(TokenSet.create(EOL_COMMENT))
-                .forEach {
-                    node.treeParent.addChild(it.clone() as ASTNode, node)
-                    node.treeParent.addChild(PsiWhiteSpaceImpl("\n"), node)
-                }
+            .forEach {
+                node.treeParent.addChild(it.clone() as ASTNode, node)
+                node.treeParent.addChild(PsiWhiteSpaceImpl("\n"), node)
+            }
 
         node.removeRange(imports.first(), imports.last())
-        sortedImports.forEachIndexed { index, importNode ->
-            if (index != 0) {
-                node.addChild(PsiWhiteSpaceImpl("\n"), null)
+        sortedImportsGroups.filterNot { it.isEmpty() }
+            .run {
+                forEachIndexed { groupIndex, group ->
+                    group.forEachIndexed { index, importNode ->
+                        node.addChild(importNode, null)
+                        if (index != group.size - 1) {
+                            node.addChild(PsiWhiteSpaceImpl("\n"), null)
+                        }
+                    }
+                    if (groupIndex != size - 1) {
+                        node.addChild(PsiWhiteSpaceImpl("\n\n"), null)
+                    }
+                }
             }
-            node.addChild(importNode, null)
-        }
     }
 
-    private fun ASTNode.getSiblingBlocks(copyrightComment: ASTNode?,
-                                         headerKdoc: ASTNode?,
-                                         fileAnnotations: ASTNode?,
-                                         packageDirectiveNode: ASTNode
+    private fun ASTNode.getSiblingBlocks(
+        copyrightComment: ASTNode?,
+        headerKdoc: ASTNode?,
+        fileAnnotations: ASTNode?,
+        packageDirectiveNode: ASTNode
     ): Pair<ASTNode?, ASTNode> = when (elementType) {
         BLOCK_COMMENT -> null to listOfNotNull(headerKdoc, fileAnnotations, packageDirectiveNode).first()
         KDOC -> copyrightComment to (fileAnnotations ?: packageDirectiveNode)
         FILE_ANNOTATION_LIST -> (headerKdoc ?: copyrightComment) to packageDirectiveNode
         else -> error("Only BLOCK_COMMENT, KDOC and FILE_ANNOTATION_LIST are valid inputs.")
     }
 
+    private fun regroupImports(imports: List<KtImportDirective>): List<List<KtImportDirective>> {
+        val (android, notAndroid) = imports.partition {
+            it.isStandard(StandardPlatforms.ANDROID)
+        }
+
+        val (ownDomain, tmp) = notAndroid.partition { import ->
+            import.importPath?.fqName?.pathSegments()
+                ?.zip(domainName.split(PACKAGE_SEPARATOR).map(Name::identifier))
+                ?.all { it.first == it.second }
+                ?: false
+        }
+
+        val (others, javaAndKotlin) = tmp.partition {
+            !it.isStandard(StandardPlatforms.JAVA) && !it.isStandard(StandardPlatforms.KOTLIN)
+        }
+
+        val (java, kotlin) = javaAndKotlin.partition { it.isStandard(StandardPlatforms.JAVA) }
+
+        return listOf(android, ownDomain, others, java, kotlin)
+    }
+
+    private val standardImportsAsName = StandardPlatforms.values()
+        .map { it to it.packages }
+        .toMap()
+        .mapValues { (_, value) ->
+            value.map { it.split(PACKAGE_SEPARATOR).map(Name::identifier) }
+        }
+
+    private fun KtImportDirective.isStandard(platformName: StandardPlatforms) = standardImportsAsName[platformName]?.any { names ->
+        names.zip(importPath?.fqName?.pathSegments() ?: emptyList())
+            .all { it.first == it.second }
+    } ?: false
+
     class WildCardImportsConfig(config: Map<String, String>) : RuleConfiguration(config) {
         val allowedWildcards = config["allowedWildcards"]?.split(",")?.map { it.trim() } ?: listOf()
     }
+
+    class ImportsGroupingConfig(config: Map<String, String>) : RuleConfiguration(config) {
+        /**
+         * Use imports grouping according to recommendation 3.1
+         */
+        val useRecommendedImportsOrder = config["useRecommendedImportsOrder"]?.toBoolean() ?: true
+    }
 }

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/utils/ASTConstants.kt

@@ -18,3 +18,10 @@ internal const val SET_PREFIX = "set"
 val emptyBlockList = listOf(LBRACE, WHITE_SPACE, RBRACE)
 
 internal const val EMPTY_BLOCK_TEXT = "{}"
+
+enum class StandardPlatforms(val packages: List<String>) {
+    ANDROID(listOf("android", "androidx", "com.android")),
+    JAVA(listOf("java", "javax")),
+    KOTLIN(listOf("kotlin", "kotlinx")),
+    ;
+}

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/utils/PsiUtils.kt

@@ -8,7 +8,6 @@ import org.jetbrains.kotlin.psi.KtCallExpression
 import org.jetbrains.kotlin.psi.KtConstantExpression
 import org.jetbrains.kotlin.psi.KtDotQualifiedExpression
 import org.jetbrains.kotlin.psi.KtExpression
-import org.jetbrains.kotlin.psi.KtFunctionLiteral
 import org.jetbrains.kotlin.psi.KtIfExpression
 import org.jetbrains.kotlin.psi.KtNameReferenceExpression
 import org.jetbrains.kotlin.psi.KtProperty

diktat-rules/src/main/resources/diktat-analysis-huawei.yml

@@ -135,9 +135,12 @@
 - name: FILE_CONTAINS_ONLY_COMMENTS
   enabled: true
   configuration: {}
+  # order imports alphabetically
 - name: FILE_UNORDERED_IMPORTS
   enabled: true
-  configuration: {}
+  configuration:
+    # use logical imports grouping with sorting inside of a group
+    useRecommendedImportsOrder: true
 - name: FILE_INCORRECT_BLOCKS_ORDER
   enabled: true
   configuration: {}
@@ -146,7 +149,9 @@
   configuration: {}
 - name: FILE_WILDCARD_IMPORTS
   enabled: true
-  configuration: {}
+  configuration:
+    allowedWildcards: "" # Allowed wildcards for imports (e.g. "import org.cqfn.diktat.*, import org.jetbrains.kotlin.*")
+    useRecommendedImportsOrder: true
 - name: NO_BRACES_IN_CONDITIONALS_AND_LOOPS
   enabled: true
   configuration: {}

diktat-rules/src/main/resources/diktat-analysis.yml

@@ -136,9 +136,12 @@
 - name: FILE_CONTAINS_ONLY_COMMENTS
   enabled: true
   configuration: {}
+  # order imports alphabetically
 - name: FILE_UNORDERED_IMPORTS
   enabled: true
-  configuration: {}
+  configuration:
+    # use logical imports grouping with sorting inside of a group
+    useRecommendedImportsOrder: true
 - name: FILE_INCORRECT_BLOCKS_ORDER
   enabled: true
   configuration: {}
@@ -150,6 +153,7 @@
   enabled: true
   configuration:
     allowedWildcards: "" # Allowed wildcards for imports (e.g. "import org.cqfn.diktat.*, import org.jetbrains.kotlin.*")
+    useRecommendedImportsOrder: true
 - name: NO_BRACES_IN_CONDITIONALS_AND_LOOPS
   enabled: true
   configuration: {}

diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter3/FileStructureRuleTestFix.kt

@@ -1,9 +1,11 @@
 package org.cqfn.diktat.ruleset.chapter3
 
 import generated.WarningNames
+import org.cqfn.diktat.common.config.rules.DIKTAT_COMMON
+import org.cqfn.diktat.common.config.rules.RulesConfig
+import org.cqfn.diktat.ruleset.constants.Warnings
 import org.cqfn.diktat.ruleset.rules.files.FileStructureRule
 import org.cqfn.diktat.util.FixTestBase
-import org.junit.jupiter.api.Disabled
 import org.junit.jupiter.api.Tag
 import org.junit.jupiter.api.Test
 
@@ -35,11 +37,32 @@ class FileStructureRuleTestFix : FixTestBase("test/paragraph3/file_structure", :
     @Test
     @Tag(WarningNames.FILE_UNORDERED_IMPORTS)
     fun `should reorder imports alphabetically with saving of EOL comments`() {
-        fixAndCompare("ReorderingImportsExpected.kt", "ReorderingImportsTest.kt")
+        fixAndCompare(
+            "ReorderingImportsExpected.kt", "ReorderingImportsTest.kt",
+            overrideRulesConfigList = listOf(
+                RulesConfig(
+                    Warnings.FILE_UNORDERED_IMPORTS.name, true,
+                    mapOf("useRecommendedImportsOrder" to "false")
+                )
+            )
+        )
     }
 
     @Test
     @Tag(WarningNames.FILE_UNORDERED_IMPORTS)
-    @Disabled("not yet implemented")
-    fun `should reorder imports according to recommendation 3_1`() = Unit
+    fun `should reorder imports according to recommendation 3_1`() {
+        fixAndCompare(
+            "ReorderingImportsRecommendedExpected.kt", "ReorderingImportsRecommendedTest.kt",
+            overrideRulesConfigList = listOf(
+                RulesConfig(
+                    DIKTAT_COMMON, true,
+                    mapOf("domainName" to "org.cqfn.diktat")
+                ),
+                RulesConfig(
+                    Warnings.FILE_UNORDERED_IMPORTS.name, true,
+                    mapOf("useRecommendedImportsOrder" to "true")
+                )
+            )
+        )
+    }
 }

diktat-rules/src/test/resources/test/paragraph3/file_structure/ReorderingImportsRecommendedExpected.kt

@@ -0,0 +1,24 @@
+package test.paragraph3.file_structure
+
+// comment about java imports
+import android.*
+import androidx.*
+import com.android.*
+
+import org.cqfn.*
+import org.cqfn.diktat.*
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.google.common.base.CaseFormat
+import io.gitlab.arturbosch.detekt.Detekt
+import org.junit.jupiter.api.Assertions
+import org.slf4j.Logger
+import org.springframework.context.annotation.Bean
+
+import java.io.IOException
+import java.net.URL
+import java.nio.charset.Charset
+
+import kotlin.system.exitProcess
+
+class Example