Check whether @SInCE tag contains date or version (#694)

### What's done:
* Added logic
* Added tests
* Renamed warning
* Updated docs on chapter 2
* Pass version regex via configuration

diktat-analysis.yml

@@ -115,6 +115,11 @@
 # Checks that KDoc does not contain single line with words 'return', 'get' or 'set'
 - name: KDOC_TRIVIAL_KDOC_ON_FUNCTION
   enabled: true
+# Checks that kdoc does not contain @author tag or date
+- name: KDOC_CONTAINS_DATE_OR_AUTHOR
+  enabled: true
+  configuration:
+    versionRegex: \d+\.\d+\.\d+[-.\w\d]*
 # Checks that there is newline after header KDoc
 - name: HEADER_WRONG_FORMAT
   enabled: true
@@ -130,9 +135,6 @@
 # Checks that header kdoc is located before package directive
 - name: HEADER_NOT_BEFORE_PACKAGE
   enabled: true
-# Checks that header kdoc does not contain @author tag ar date
-- name: HEADER_CONTAINS_DATE_OR_AUTHOR
-  enabled: true
 # Checks that file does not contain lines > maxSize
 - name: FILE_IS_TOO_LONG
   enabled: true

diktat-rules/src/main/kotlin/generated/WarningNames.kt

@@ -86,14 +86,14 @@ public object WarningNames {
     public const val KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT: String =
             "KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT"
 
+    public const val KDOC_CONTAINS_DATE_OR_AUTHOR: String = "KDOC_CONTAINS_DATE_OR_AUTHOR"
+
     public const val HEADER_WRONG_FORMAT: String = "HEADER_WRONG_FORMAT"
 
     public const val HEADER_MISSING_OR_WRONG_COPYRIGHT: String = "HEADER_MISSING_OR_WRONG_COPYRIGHT"
 
     public const val WRONG_COPYRIGHT_YEAR: String = "WRONG_COPYRIGHT_YEAR"
 
-    public const val HEADER_CONTAINS_DATE_OR_AUTHOR: String = "HEADER_CONTAINS_DATE_OR_AUTHOR"
-
     public const val HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE: String =
             "HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE"
 

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt

@@ -67,10 +67,10 @@ enum class Warnings(
     KDOC_NO_CONSTRUCTOR_PROPERTY(true, "2.1.1", "all properties from the primary constructor should be documented in a @property tag in KDoc"),
     KDOC_EXTRA_PROPERTY(false, "2.1.1", "There is property in KDoc which is not present in the class"),
     KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT(true, "2.1.1", "replace comment before property with @property tag in class KDoc"),
+    KDOC_CONTAINS_DATE_OR_AUTHOR(false, "2.1.3", "KDoc should not contain creation date and author name"),
     HEADER_WRONG_FORMAT(true, "2.2.1", "file header comments should be properly formatted"),
     HEADER_MISSING_OR_WRONG_COPYRIGHT(true, "2.2.1", "file header comment must include copyright information inside a block comment"),
     WRONG_COPYRIGHT_YEAR(true, "2.2.1", "year defined in copyright and current year are different"),
-    HEADER_CONTAINS_DATE_OR_AUTHOR(false, "2.2.1", "file header comment should not contain creation date and author name"),
     HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE(false, "2.2.1", "files that contain multiple or no classes should contain description of what is inside of this file"),
     HEADER_NOT_BEFORE_PACKAGE(true, "2.2.1", "header KDoc should be placed before package and imports"),
     COMMENTED_OUT_CODE(false, "2.4.2", "you should not comment out code, use VCS to save it in history and delete this block"),

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

@@ -451,7 +451,7 @@ class IdentifierNaming(private val configRules: List<RulesConfig>) : Rule("ident
 
         // FixMe: this should be moved to properties
         val oneCharIdentifiers = setOf("i", "j", "k", "x", "y", "z")
-        val booleanMethodPrefixes = setOf("has", "is", "are", "have", "should")
+        val booleanMethodPrefixes = setOf("has", "is", "are", "have", "should", "can")
         val confusingIdentifierNames = setOf("O", "D", "I", "l", "Z", "S", "e", "B", "h", "n", "m", "rn")
     }
 }

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/comments/HeaderCommentRule.kt

@@ -4,17 +4,18 @@ import org.cqfn.diktat.common.config.rules.RuleConfiguration
 import org.cqfn.diktat.common.config.rules.RulesConfig
 import org.cqfn.diktat.common.config.rules.getRuleConfig
 import org.cqfn.diktat.ruleset.constants.EmitType
-import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_CONTAINS_DATE_OR_AUTHOR
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_MISSING_OR_WRONG_COPYRIGHT
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_NOT_BEFORE_PACKAGE
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_WRONG_FORMAT
+import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_CONTAINS_DATE_OR_AUTHOR
 import org.cqfn.diktat.ruleset.constants.Warnings.WRONG_COPYRIGHT_YEAR
 import org.cqfn.diktat.ruleset.utils.copyrightWords
 import org.cqfn.diktat.ruleset.utils.findChildAfter
 import org.cqfn.diktat.ruleset.utils.findChildBefore
 import org.cqfn.diktat.ruleset.utils.getAllChildrenWithType
 import org.cqfn.diktat.ruleset.utils.getFirstChildWithType
+import org.cqfn.diktat.ruleset.utils.kDocTags
 import org.cqfn.diktat.ruleset.utils.moveChildBefore
 
 import com.pinterest.ktlint.core.Rule
@@ -29,8 +30,12 @@ import org.jetbrains.kotlin.com.intellij.lang.ASTNode
 import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.LeafElement
 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.kdoc.parser.KDocKnownTag
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
 
 import java.time.LocalDate
+import java.time.format.DateTimeFormatter
+import java.time.temporal.ChronoField
 
 /**
  * Visitor for header comment in .kt file:
@@ -59,18 +64,7 @@ class HeaderCommentRule(private val configRules: List<RulesConfig>) : Rule("head
     }
 
     private fun checkHeaderKdoc(node: ASTNode) {
-        val headerKdoc = node.findChildBefore(PACKAGE_DIRECTIVE, KDOC)
-        headerKdoc?.let {
-            // fixme we should also check date of creation, but it can be in different formats
-            headerKdoc
-                .text
-                .split('\n')
-                .filter { it.contains("@author") }
-                .forEach {
-                    HEADER_CONTAINS_DATE_OR_AUTHOR.warn(configRules, emitWarn, isFixMode,
-                        it.trim(), headerKdoc.startOffset, headerKdoc)
-                }
-
+        node.findChildBefore(PACKAGE_DIRECTIVE, KDOC)?.let { headerKdoc ->
             if (headerKdoc.treeNext != null && headerKdoc.treeNext.elementType == WHITE_SPACE &&
                     headerKdoc.treeNext.text.count { it == '\n' } != 2) {
                 HEADER_WRONG_FORMAT.warnAndFix(configRules, emitWarn, isFixMode,

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocFormatting.kt

@@ -1,7 +1,10 @@
 package org.cqfn.diktat.ruleset.rules.kdoc
 
+import org.cqfn.diktat.common.config.rules.RuleConfiguration
 import org.cqfn.diktat.common.config.rules.RulesConfig
+import org.cqfn.diktat.common.config.rules.getRuleConfig
 import org.cqfn.diktat.ruleset.constants.EmitType
+import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_CONTAINS_DATE_OR_AUTHOR
 import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_EMPTY_KDOC
 import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_NEWLINES_BEFORE_BASIC_TAGS
 import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_NO_DEPRECATED_TAG
@@ -43,19 +46,25 @@ import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
 import org.jetbrains.kotlin.lexer.KtTokens
 import org.jetbrains.kotlin.psi.psiUtil.startOffset
 
+import java.time.format.DateTimeFormatter
+import java.time.temporal.ChronoField
+
 /**
  * Formatting visitor for Kdoc:
  * 1) removing all blank lines between Kdoc and the code it's declaring
  * 2) ensuring there are no tags with empty content
  * 3) ensuring there is only one white space between tag and it's body
  * 4) ensuring tags @apiNote, @implSpec, @implNote have one empty line after their body
  * 5) ensuring tags @param, @return, @throws are arranged in this order
+ * 6) ensuring @author tag is not used
+ * 7) ensuring @since tag contains only versions and not dates
  */
 @Suppress("ForbiddenComment")
 class KdocFormatting(private val configRules: List<RulesConfig>) : Rule("kdoc-formatting") {
     private val basicTagsList = listOf(KDocKnownTag.PARAM, KDocKnownTag.RETURN, KDocKnownTag.THROWS)
     private val specialTagNames = setOf("implSpec", "implNote", "apiNote")
     private var isFixMode: Boolean = false
+    private var versionRegex: Regex? = null
     private lateinit var emitWarn: EmitType
 
     /**
@@ -69,6 +78,13 @@ class KdocFormatting(private val configRules: List<RulesConfig>) : Rule("kdoc-fo
         isFixMode = autoCorrect
         emitWarn = emit
 
+        versionRegex ?: run {
+            versionRegex = KdocFormatConfiguration(
+                configRules.getRuleConfig(KDOC_CONTAINS_DATE_OR_AUTHOR)?.configuration ?: emptyMap()
+            )
+                .versionRegex
+        }
+
         if (node.elementType == KDOC && isKdocNotEmpty(node)) {
             checkNoDeprecatedTag(node)
             checkEmptyTags(node.kDocTags())
@@ -77,6 +93,7 @@ class KdocFormatting(private val configRules: List<RulesConfig>) : Rule("kdoc-fo
             node.kDocBasicTags()?.let { checkEmptyLinesBetweenBasicTags(it) }
             checkBasicTagsOrder(node)
             checkNewLineAfterSpecialTags(node)
+            checkAuthorAndDate(node)
         }
     }
 
@@ -307,6 +324,17 @@ class KdocFormatting(private val configRules: List<RulesConfig>) : Rule("kdoc-fo
         }
     }
 
+    private fun checkAuthorAndDate(node: ASTNode) {
+        node.kDocTags()
+            ?.filter {
+                it.knownTag == KDocKnownTag.AUTHOR ||
+                        it.knownTag == KDocKnownTag.SINCE && it.hasInvalidVersion()
+            }
+            ?.forEach {
+                KDOC_CONTAINS_DATE_OR_AUTHOR.warn(configRules, emitWarn, isFixMode, it.text.trim(), it.startOffset, it.node)
+            }
+    }
+
     // fixme this method can be improved and extracted to utils
     private fun ASTNode.hasEmptyLineAfter(): Boolean {
         require(this.elementType == KDOC_TAG) { "This check is only for KDOC_TAG" }
@@ -321,4 +349,43 @@ class KdocFormatting(private val configRules: List<RulesConfig>) : Rule("kdoc-fo
     private fun ASTNode.applyToPrevSibling(elementType: IElementType, consumer: ASTNode.() -> Unit) {
         prevSibling { it.elementType == elementType }?.apply(consumer)
     }
+
+    /**
+     * Checks whether this tag's content represents an invalid version
+     */
+    private fun KDocTag.hasInvalidVersion(): Boolean {
+        val content = getContent().trim()
+        if (' ' in content || '/' in content) {
+            // Filter based on symbols that are not allowed in versions. Assuming that people put either version or date in `@since` tag.
+            return true
+        }
+        return versionRegex?.matches(content)?.not()
+            ?: dateFormats.mapNotNull {
+                // try to parse using some standard date patterns
+                runCatching {
+                    it.parse(content).get(ChronoField.YEAR)
+                }
+                    .getOrNull()
+            }
+                .isNotEmpty()
+    }
+
+    /**
+     * A [RuleConfiguration] for KDoc formatting
+     */
+    class KdocFormatConfiguration(config: Map<String, String>) : RuleConfiguration(config) {
+        /**
+         * Regular expression, if present, against which a version should be matched in `@since` tag.
+         */
+        val versionRegex: Regex? by lazy {
+            config["versionRegex"]?.let { Regex(it) }
+        }
+    }
+
+    companion object {
+        val dateFormats: List<DateTimeFormatter> = listOf("yyyy-dd-mm", "yy-dd-mm", "yyyy-mm-dd", "yy-mm-dd", "yyyy.mm.dd", "yyyy.dd.mm")
+            .map {
+                DateTimeFormatter.ofPattern(it)
+            }
+    }
 }

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

@@ -112,6 +112,11 @@
 # Checks that special tags `@apiNote`, `@implNote`, `@implSpec` have exactly one empty line after
 - name: KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS
   enabled: true
+# Checks that kdoc does not contain @author tag or date
+- name: KDOC_CONTAINS_DATE_OR_AUTHOR
+  enabled: true
+  configuration:
+    versionRegex: \d+\.\d+\.\d+[-.\w\d]*
 # Checks that KDoc does not contain single line with words 'return', 'get' or 'set'
 - name: KDOC_TRIVIAL_KDOC_ON_FUNCTION
   enabled: true
@@ -130,9 +135,6 @@
 # Checks that header kdoc is located before package directive
 - name: HEADER_NOT_BEFORE_PACKAGE
   enabled: true
-# Checks that header kdoc does not contain @author tag ar date
-- name: HEADER_CONTAINS_DATE_OR_AUTHOR
-  enabled: true
 # Checks that file does not contain lines > maxSize
 - name: FILE_IS_TOO_LONG
   enabled: true

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

@@ -111,6 +111,11 @@
 # Checks that special tags `@apiNote`, `@implNote`, `@implSpec` have exactly one empty line after
 - name: KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS
   enabled: true
+# Checks that kdoc does not contain @author tag or date
+- name: KDOC_CONTAINS_DATE_OR_AUTHOR
+  enabled: true
+  configuration:
+    versionRegex: \d+\.\d+\.\d+[-.\w\d]*
 # Checks that KDoc does not contain single line with words 'return', 'get' or 'set'
 - name: KDOC_TRIVIAL_KDOC_ON_FUNCTION
   enabled: true
@@ -129,9 +134,6 @@
 # Checks that header kdoc is located before package directive
 - name: HEADER_NOT_BEFORE_PACKAGE
   enabled: true
-# Checks that header kdoc does not contain @author tag ar date
-- name: HEADER_CONTAINS_DATE_OR_AUTHOR
-  enabled: true
 # Checks that file does not contain lines > maxSize
 - name: FILE_IS_TOO_LONG
   enabled: true

diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter2/HeaderCommentRuleTest.kt

@@ -2,11 +2,11 @@ package org.cqfn.diktat.ruleset.chapter2
 
 import org.cqfn.diktat.common.config.rules.RulesConfig
 import org.cqfn.diktat.ruleset.constants.Warnings
-import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_CONTAINS_DATE_OR_AUTHOR
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_MISSING_OR_WRONG_COPYRIGHT
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_NOT_BEFORE_PACKAGE
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_WRONG_FORMAT
+import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_CONTAINS_DATE_OR_AUTHOR
 import org.cqfn.diktat.ruleset.rules.DIKTAT_RULE_SET_ID
 import org.cqfn.diktat.ruleset.rules.comments.HeaderCommentRule
 import org.cqfn.diktat.util.LintTestBase
@@ -256,26 +256,6 @@ class HeaderCommentRuleTest : LintTestBase(::HeaderCommentRule) {
         )
     }
 
-    @Test
-    @Tag(WarningNames.HEADER_CONTAINS_DATE_OR_AUTHOR)
-    fun `@author tag is not allowed in header comment`() {
-        lintMethod(
-            """
-                |$copyrightBlock
-                |/**
-                | * Description of this file
-                | * @author anonymous
-                | */
-                |
-                |package org.cqfn.diktat.example
-                |
-                |class Example { }
-            """.trimMargin(),
-            LintError(4, 1, ruleId, "${HEADER_CONTAINS_DATE_OR_AUTHOR.warnText()} * @author anonymous"),
-            rulesConfigList = rulesConfigList
-        )
-    }
-
     @Test
     @Tag(WarningNames.HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE)
     fun `file with zero classes should have header KDoc`() {