Lint that Kotlin

Code formatting is often not taken seriously and sometimes even omitted, but it's actually something that brings enjoyment to our eyes while doing code reviews. In this talk, we will dig into ktlint (Kotlin formatting linter), its internals (UAST, Psi), how to create a custom rule and how to have the formatting automated.

Transcript

1. LINT THAT KOTLIN Roman Zavarnitsyn
2. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } }
3. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } }
4. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } }
5. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } }
6. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } }
7. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } // empty line }
8. Kotlin code formatting fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } }
9. Kotlin linter
10. ktlint
11. ktlint • Reflects official Kotlin style guide (+ Android) • Built-in formatter • Customizable output (plain, json, checkstyle, html) • Customizable ruleset • Integration with Maven, Gradle, IntelliJ IDEA
12. $ sh ktlint SomeFile.kt fun someMethod(): Unit { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } } SomeFile.kt:1:19: Unnecessary "Unit" return type SomeFile.kt:2:1: Unexpected newline before "{" SomeFile.kt:4:16: Missing spacing around ">=" SomeFile.kt:5:20: Redundant curly braces SomeFile.kt:7:1: Unexpected blank line(s) before "}"
13. $ sh ktlint SomeFile.kt --format fun someMethod(): Unit { { val someVar = resolveVar() if (someVar>=0) { // valid println("Var is valid and is equal to ${someVar}") } } } }
14. $ sh ktlint SomeFile.kt --format fun someMethod() { { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } } }
15. Scanning the code
16. import resolver.resolveVar fun someMethod() { { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } } } File
17. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } File • Imports
18. import resolver.resolveVar fun someMethod() { { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } } } File • Imports • Functions
19. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } File • Imports • Functions • Properties
20. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } } } File • Imports • Functions • Properties • Expressions
21. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } } File • Imports • Functions • Properties • Expressions • Operations
22. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") }} }} File • Imports • Functions • Properties • Expressions • Operations Psi Psi Psi Psi Psi Psi
23. import resolver.resolveVar fun someMethod() {{ val someVar = resolveVar() if (someVar >= 0) {{// valid println("Var is valid and is equal to $someVar") }} }} PsiFile PsiImports PsiFunctions PsiProperties PsiExpressions PsiOperations
24. import resolver.resolveVar fun someMethod() {{ val someVar = resolveVar() if (someVar >= 0) {{// valid println("Var is valid and is equal to $someVar") }} }} PsiFile : PsiElement PsiImports : PsiElement PsiFunctions : PsiElement PsiProperties : PsiElement PsiExpressions : PsiElement PsiOperations : PsiElement
25. import resolver.resolveVar fun someMethod() {{ val someVar = resolveVar() if (someVar >= 0) {{// valid println("Var is valid and is equal to $someVar") }} }} PsiFile : PsiElement PsiImports : PsiElement PsiFunctions : PsiElement PsiProperties : PsiElement PsiExpressions : PsiElement PsiOperations : PsiElement PsiWhiteSpace : PsiElement
26. $ sh ktlint SomeFile.kt --print-ast ~.psi.KtFile (FILE) ~.psi.KtPackageDirective (PACKAGE_DIRECTIVE) "" ~.psi.KtImportList (IMPORT_LIST) "" ~.psi.KtNamedFunction (FUN) ~.c.i.p.impl.source.tree.LeafPsiElement (FUN_KEYWORD) "fun" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.c.i.p.impl.source.tree.LeafPsiElement (IDENTIFIER) "someMethod" ~.psi.KtParameterList (VALUE_PARAMETER_LIST) ~.c.i.p.impl.source.tree.LeafPsiElement (LPAR) "(" ~.c.i.p.impl.source.tree.LeafPsiElement (RPAR) ")" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.psi.KtBlockExpression (BLOCK) ~.c.i.p.impl.source.tree.LeafPsiElement (LBRACE) "{" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) "\n " ~.psi.KtProperty (PROPERTY) ~.c.i.p.impl.source.tree.LeafPsiElement (VAL_KEYWORD) "val" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.c.i.p.impl.source.tree.LeafPsiElement (IDENTIFIER) "someVar" fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } }
27. $ sh ktlint SomeFile.kt --print-ast ~.psi.KtFile (FILE) ~.psi.KtPackageDirective (PACKAGE_DIRECTIVE) "" ~.psi.KtImportList (IMPORT_LIST) "" ~.psi.KtNamedFunction (FUN) ~.c.i.p.impl.source.tree.LeafPsiElement (FUN_KEYWORD) "fun" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.c.i.p.impl.source.tree.LeafPsiElement (IDENTIFIER) "someMethod" ~.psi.KtParameterList (VALUE_PARAMETER_LIST) ~.c.i.p.impl.source.tree.LeafPsiElement (LPAR) "(" ~.c.i.p.impl.source.tree.LeafPsiElement (RPAR) ")" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.psi.KtBlockExpression (BLOCK) ~.c.i.p.impl.source.tree.LeafPsiElement (LBRACE) "{" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) "\n " ~.psi.KtProperty (PROPERTY) ~.c.i.p.impl.source.tree.LeafPsiElement (VAL_KEYWORD) "val" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.c.i.p.impl.source.tree.LeafPsiElement (IDENTIFIER) "someVar" fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } }
28. $ sh ktlint SomeFile.kt --print-ast ~.psi.KtFile (FILE) ~.psi.KtPackageDirective (PACKAGE_DIRECTIVE) "" ~.psi.KtImportList (IMPORT_LIST) "" ~.psi.KtNamedFunction (FUN) ~.c.i.p.impl.source.tree.LeafPsiElement (FUN_KEYWORD) "fun" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.c.i.p.impl.source.tree.LeafPsiElement (IDENTIFIER) "someMethod" ~.psi.KtParameterList (VALUE_PARAMETER_LIST) ~.c.i.p.impl.source.tree.LeafPsiElement (LPAR) "(" ~.c.i.p.impl.source.tree.LeafPsiElement (RPAR) ")" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.psi.KtBlockExpression (BLOCK) ~.c.i.p.impl.source.tree.LeafPsiElement (LBRACE) "{" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) "\n " ~.psi.KtProperty (PROPERTY) ~.c.i.p.impl.source.tree.LeafPsiElement (VAL_KEYWORD) "val" ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (WHITE_SPACE) " " ~.c.i.p.impl.source.tree.LeafPsiElement (IDENTIFIER) "someVar" fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } }
29. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } val file: KtFile
30. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } val file: KtFile val method = file.findChildByTypeOrClass(KtStubElementTypes.FUNCTION_TYPE, KtFunctionType::class.java)
31. import resolver.resolveVar fun someMethod() { val someVar = resolveVar() if (someVar >= 0) { // valid println("Var is valid and is equal to $someVar") } } val file: KtFile val method = file.findChildByTypeOrClass(KtStubElementTypes.FUNCTION_TYPE, KtFunctionType::class.java) val operator = method.findDescendantOfType<LeafPsiElement> { it.elementType == KtTokens.GTEQ }
32. Writing a custom rule
33. Range operator for (i in 1..100) when (score) { in 1..3 -> "bad" in 4..8 -> "good" in 9..10 -> "excellent" } }
34. Range operator when (score) { in 1 .. 3 -> "bad" in 4 .. 8 -> "good" in 9 .. 10 -> "excellent" } } for (i in 1 .. 100)
35. class SpacingAroundRangeOperatorRule : Rule(“range-spacing") Writing a custom rule for (i in 1 .. 100)
36. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit( node: ASTNode, autoCorrect: Boolean, emit: ( offset: Int, errorMessage: String, canBeAutoCorrected: Boolean ) -> Unit ) { // Implementation... } } for (i in 1 .. 100)
37. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit( node: ASTNode, autoCorrect: Boolean, emit: ( offset: Int, errorMessage: String, canBeAutoCorrected: Boolean ) -> Unit ) { // Implementation... } } for (i in 1 .. 100)
38. UAST
39. Unified Abstract Syntax Tree https://speakerdeck.com/alecstrong/whats-the-big-idea-writing-intellij-plugins-for-kotlin?slide=104
40. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit( node: ASTNode, autoCorrect: Boolean, emit: ( offset: Int, errorMessage: String, canBeAutoCorrected: Boolean ) -> Unit ) { // Implementation... } } for (i in 1 .. 100)
41. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit( node: ASTNode, autoCorrect: Boolean, emit: ( offset: Int, errorMessage: String, canBeAutoCorrected: Boolean ) -> Unit ) { // Implementation... } } } } for (i in 1 .. 100)
42. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit(...) { ... } } } } for (i in 1 .. 100)
43. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit(...) { if (node.elementType == RANGE) { val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() } } } } } for (i in 1 .. 100)
44. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit(...) { if (node.elementType == RANGE) { val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() } } } KtSingleValueToken RANGE = new KtSingleValueToken("RANGE", ".."); for (i in 1 .. 100)
45. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit(...) { if (node.elementType == RANGE) { val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() } } } for (i in 1 .. 100)
46. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") {{ override fun visit(...) {{ if (node.elementType == RANGE) {{ val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() }} }} }} for (i in 1 .. 100)
47. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") {{ override fun visit(...) {{ if (node.elementType == RANGE) {{ val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() when {{ prevLeaf is PsiWhiteSpace && nextLeaf is PsiWhiteSpace -> {{ emit(node.startOffset, "Unexpected spacing around \"..\"") if (autoCorrect) { prevLeaf.treeParent.removeChild(prevLeaf) nextLeaf.treeParent.removeChild(nextLeaf) }} }} }} }} }}} }} for (i in 1 .. 100)
48. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit(...) { if (node.elementType == RANGE) { val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() when { prevLeaf is PsiWhiteSpace && nextLeaf is PsiWhiteSpace -> { emit(node.startOffset, "Unexpected spacing around \"..\"") if (autoCorrect) { prevLeaf.treeParent.removeChild(prevLeaf) nextLeaf.treeParent.removeChild(nextLeaf) } } } } } } for (i in 1 .. 100)
49. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") { override fun visit(...) { if (node.elementType == RANGE) { val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() when { prevLeaf is PsiWhiteSpace && nextLeaf is PsiWhiteSpace -> { emit(node.startOffset, "Unexpected spacing around \"..\"") if (autoCorrect) { prevLeaf.treeParent.removeChild(prevLeaf) nextLeaf.treeParent.removeChild(nextLeaf) } } } } } } } for (i in 1 .. 100)
50. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") {{ override fun visit(...) {{ if (node.elementType == RANGE) {{ val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() when {{ prevLeaf is PsiWhiteSpace && nextLeaf is PsiWhiteSpace -> {{{ emit(node.startOffset, "Unexpected spacing around \"..\"") if (autoCorrect) {{ prevLeaf.treeParent.removeChild(prevLeaf) nextLeaf.treeParent.removeChild(nextLeaf) }} }} }} }} }} }} for (i in 1 .. 100)
51. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") {{ override fun visit(...) {{ if (node.elementType == RANGE) {{ val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() when {{ ... prevLeaf is PsiWhiteSpace -> {{ emit(node.startOffset, "Unexpected spacing before \"..\"") if (autoCorrect) {{ prevLeaf.treeParent.removeChild(prevLeaf) }} }} }} }} }} }} for (i in 1 .. 100)
52. Writing a custom rule class SpacingAroundRangeOperatorRule : Rule("range-spacing") {{ override fun visit(...) {{ if (node.elementType == RANGE) {{ val prevLeaf = node.prevLeaf() val nextLeaf = node.nextLeaf() when {{ ... nextLeaf is PsiWhiteSpace -> {{ emit(node.startOffset, "Unexpected spacing after \"..\"") if (autoCorrect) {{ nextLeaf.treeParent.removeChild(nextLeaf) }} }} }} }} }} }} for (i in 1 .. 100)
53. Automation
54. Automation • Prevent everyone from pushing unformatted code • Moreover, do the formatting automatically on each commit • If the unformatted code leaks to remote, CI bot leaves a comment on a pull request
55. Git hooks • pre-commit, pre-push, post-commit, etc. • Are essentially shell scripts • Live under version control
56. Git hooks (pre-commit) #!/bin/bash echo "Running ktlint formatter..." files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') # Format only staged files using ktlint chmod a+x tools/ktlint/ktlint tools/ktlint/ktlint -F --android $files # Stage the changes after formatting git add $files echo "ktlint formatted the code successfully." exit 0
57. files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$')
58. files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') --- a/sample/src/main/kotlin/com/sample/DeletedClass.java +++ b/sample/src/main/kotlin/com/sample/SomeClass.java @@ -0,0 +1,4 @@ +class SomeClass { +} +++ b/sample/src/main/kotlin/com/sample/SomeFile.kt @@ -0,0 +1,8 @@ +fun someMethod(): Unit +{ + val someVar = resolveVar() + if (someVar>=0) { // valid + println("Var is valid and is equal to ${someVar}") + } + +}
59. files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') sample/src/main/kotlin/com/sample/DeletedClass.java sample/src/main/kotlin/com/sample/SomeClass.java sample/src/main/kotlin/com/sample/SomeFile.kt
60. files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') sample/src/main/kotlin/com/sample/SomeClass.java sample/src/main/kotlin/com/sample/SomeFile.kt
61. files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') sample/src/main/kotlin/com/sample/SomeFile.kt
62. Git hooks (pre-commit) #!/bin/bash echo "Running ktlint formatter..." files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') # Format only staged files using ktlint chmod a+x tools/ktlint/ktlint tools/ktlint/ktlint -F --android $files # Stage the changes after formatting git add $files echo "ktlint formatted the code successfully." exit 0
63. Git hooks (pre-commit) #!/bin/bash echo "Running ktlint formatter..." files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') # Format only staged files using ktlint chmod a+x tools/ktlint/ktlint tools/ktlint/ktlint -F --android $files # Stage the changes after formatting git add $files echo "ktlint formatted the code successfully." exit 0
64. Git hooks (pre-commit) #!/bin/bash echo "Running ktlint formatter..." files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.kt\?$') # Format only staged files using ktlint chmod a+x tools/ktlint/ktlint tools/ktlint/ktlint -F --android $files # Stage the changes after formatting git add $files echo "ktlint formatted the code successfully." exit 0
65. CI setup (Jenkins + Bitbucket) • A job, which runs over the opened pull requests • When there’s a new commit on PR - runs static code analysis (ktlint is part of them) • A Jenkins plugin that allows to leave comments on PRs
66. github.com/pinterest/ktlint
67. Thanks! Roman Zavarnitsyn github.com/rom4ek