detekt

Meet detekt, a static code analysis tool for the Kotlin programming language. It operates on the abstract syntax tree provided by the Kotlin compiler.

Features

code smell analysis for your kotlin projects
complexity report based on logical lines of code, McCabe complexity and amount of code smells
highly configurable (rule set or rule level)
suppress findings with Kotlin's @Suppress and Java's @SuppressWarnings annotations
specify code smell thresholds to break your build or print a warning
code Smell baseline and ignore lists for legacy projects
gradle plugin for code analysis via Gradle builds
gradle tasks to use local intellij distribution for formatting and inspecting kotlin code
optionally configure detekt for each sub module by using profiles (gradle-plugin)
sonarqube integration
NEW extensible by own rule sets and FileProcessListener's

Commandline interface
Gradle plugin
Standalone gradle task
Standalone maven task
Rule sets
Rule set configuration
Suppress rules
Build failure
Extending detekt
Black- and Whitelist code smells
Contributors
Mentions

Build & use the commandline interface

git clone https://github.com/arturbosch/detekt
cd detekt
./gradlew build shadowJar
java -jar detekt-cli/build/libs/detekt-cli-[version]-all.jar [parameters]*

Parameters for CLI

The following parameters are shown when --help is entered. The --input/-i option is required:

Usage: detekt [options]
  Options:
    --baseline, -b
      If a baseline xml file is passed in, only new code smells not in the 
      baseline are printed in the console.
    --config, -c
      Path to the config file (path/to/config.yml).
    --config-resource, -cr
      Path to the config resource on detekt's classpath (path/to/config.yml).
    --create-baseline, -cb
      Treats current analysis findings as a smell baseline for future detekt
      runs. 
      Default: false
    --debug
      Debugs given ktFile by printing its elements.
      Default: false
    --disable-default-rulesets, -dd
      Disables default rule sets.
      Default: false
    --filters, -f
      Path filters defined through regex with separator ';' (".*test.*").
    --generate-config, -gc
      Export default config to default-detekt-config.yml.
      Default: false
    --help, -h
      Shows the usage.
  * --input, -i
      Input path to analyze (path/to/project).
    --output, -o
      Directory where output reports are stored.
    --output-name, -on
      The base name for output reports is derived from this parameter.
    --parallel
      Enables parallel compilation of source files. Should only be used if the 
      analyzing project has more than ~200 kotlin files.
      Default: false
    --plugins, -p
      Extra paths to plugin jars separated by ',' or ';'.

--input can either be a directory or a single Kotlin file. The currently only supported configuration format is yaml. --config should point to one. Generating a default configuration file is as easy as using the --generate-config parameter. filters can be used for example to exclude all test directories. With rules you can point to additional ruleset.jar's creating by yourself or others. More on this topic see section Custom RuleSets.

Using the detekt-gradle-plugin

Use the groovy or kotlin dsl of gradle and configure the detekt closure as described here.

Configuration when using groovy dsl

For gradle version >= 2.1

buildscript {
    repositories {
        jcenter()
    }
}

plugins {
    id "io.gitlab.arturbosch.detekt" version "1.0.0.[version]"
}

detekt {
    version = "1.0.0.[version]"
    profile("main") {
        input = "$projectDir/src/main/kotlin"
        config = "$projectDir/detekt.yml"
        filters = ".*test.*,.*/resources/.*,.*/tmp/.*"
    }
}

For all gradle versions:

buildscript {
  repositories {
    jcenter()
    maven { url "https://plugins.gradle.org/m2/" }
  }
  dependencies {
    classpath "gradle.plugin.io.gitlab.arturbosch.detekt:detekt-gradle-plugin:1.0.0.[version]"
  }
}

apply plugin: "io.gitlab.arturbosch.detekt"

detekt {
    version = "1.0.0.[version]"
    profile("main") {
        input = "$projectDir/src/main/kotlin"
        config = "$projectDir/detekt.yml"
        filters = ".*test.*,.*/resources/.*,.*/tmp/.*"
    }
}

Configuration when using kotlin dsl

For gradle version >= 4.1

import io.gitlab.arturbosch.detekt.DetektExtension

buildscript {
    repositories {
        jcenter()
    }
}
plugins {
    id("io.gitlab.arturbosch.detekt").version("1.0.0.[version]")
}

detekt {
    version = "1.0.0.[version]"
    profile("main", Action {
        input = "$projectDir/src/main/kotlin"
        config = "$projectDir/detekt.yml"
        filters = ".*test.*,.*/resources/.*,.*/tmp/.*"
    })
}

Configuration for Android projects

When using Android make sure to have detekt configured in the project level build.gradle file. The new preferred plugin configuration way is used, the old way is commented out.

buildscript {
    repositories {
//        maven { url "https://plugins.gradle.org/m2/" }
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.3.3'
//        classpath "gradle.plugin.io.gitlab.arturbosch.detekt:detekt-gradle-plugin:1.0.0.[version]"
    }

}
plugins {
    id "io.gitlab.arturbosch.detekt" version "1.0.0.[version]"
}

//apply plugin: 'io.gitlab.arturbosch.detekt'

allprojects {
    repositories {
        jcenter()
    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

detekt {
    version = "1.0.0.[version]"
    profile("main") {
        input = "$projectDir/your/app"
        config = "$projectDir/detekt.yml"
        filters = ".*test.*,.*/resources/.*,.*/tmp/.*"
    }
}

Available plugin tasks

detektCheck - Runs a detekt analysis and complexity report. Configure the analysis inside the detekt-closure. By default the standard rule set is used without output report or black- and whitelist checks.
detektGenerateConfig - Generates a default detekt config file into your projects location.
detektBaseline - Like detektCheck, but creates a code smell baseline. Further detekt runs will only feature new smells not in this list.
detektIdeaFormat - Uses a local idea installation to format your kotlin (and other) code according to the specified code-style.xml.
detektIdeaInspect Uses a local idea installation to run inspections on your kotlin (and other) code according to the specified inspections.xml profile.

Options for detekt configuration closure

detekt {
    version = "1.0.0.[version]"  // When unspecified the latest detekt version found, will be used. Override to stay on the same version.
    
     // A profile basically abstracts over the argument vector passed to detekt. 
     // Different profiles can be specified and used for different sub modules or testing code.
    profile("main") {
        input = "$projectDir/src/main/kotlin" // Which part of your project should be analyzed?
        config = "$projectDir/detekt.yml" // Use $project.projectDir or to navigate inside your project 
        configResource = "/detekt.yml" // Use this parameter instead of config if your detekt yaml file is inside your resources. Is needed for multi project maven tasks.
        filters = ".*test.*, .*/resources/.*" // What paths to exclude? Use comma or semicolon to separate
        ruleSets = "other/optional/ruleset.jar" // Custom rule sets can be linked to this, use comma or semicolon to separate, remove if unused.
        disableDefaultRuleSets = false // Disables the default rule set. Just use detekt as the detection engine with your custom rule sets.
        output = "$project.projectDir/reports" // Directory where output reports are stored (if present).
        outputName = "my-module" // This parameter is used to derive the output report name
        baseline = "$project.projectDir/reports/baseline.xml" // If present all current findings are saved in a baseline.xml to only consider new code smells for further runs.
        parallel = true // Use this flag if your project has more than 200 files. 
   }
   
   // Definines a secondary profile `gradle detektCheck -Ddetekt.profile=override` will use this profile. 
   // The main profile gets always loaded but specified profiles override main profiles parameters.
   profile("override") {
       config = "$projectDir/detekt-test-config.yml"
   }
}

Configure a local idea for detekt

download the community edition of Intellij IDEA
extract the file to your preferred location eg. ~/.idea
let detekt know about idea inside the detekt-closure
extract code-style.xml and inpect.xml from idea settings (Settings>CodeStyle>Scheme and Settings>Inspections>Profile)
run detektIdeaFormat or detektIdeaInspect
all parameters in the following detekt-closure are mandatory for both tasks
make sure that current or default profile have an input path specified!

String USER_HOME = System.getProperty("user.home")

detekt {  
    profile("main") {
        input = "$projectDir/src/main/kotlin"
        output = "$projectDir/reports/report.xml"
        outputFormat = "xml"
    }
    idea {
        path = "$USER_HOME/.idea"
        codeStyleScheme = "$USER_HOME/.idea/idea-code-style.xml"
        inspectionsProfile = "$USER_HOME/.idea/inspect.xml"
        report = "project.projectDir/reports"
        mask = "*.kt,"
    }
}

For more information on using idea as a headless formatting/inspection tool see here.

Using detekt in custom gradle projects

Add following lines to your build.gradle file.
Run gradle detekt
Add check.dependsOn detekt if you want to run detekt on every build

repositories {
    jcenter()
}

configurations {
	detekt
}

task detekt(type: JavaExec) {
	main = "io.gitlab.arturbosch.detekt.cli.Main"
	classpath = configurations.detekt
	def input = "$projectDir"
	def config = "$projectDir/detekt.yml"
	def filters = ".*test.*"
	def rulesets = ""
	def params = [ '-i', input, '-c', config, '-f', filters, '-r', rulesets]
	args(params)
}

dependencies {
	detekt 'io.gitlab.arturbosch.detekt:detekt-cli:1.0.0.[version]'
}

Attention Android Developers! the dependencies section must be at the bottom, after the repository, configurations and task sections!

Using detekt in Maven Projects

Add following lines to your pom.xml.
Run mvn verify (when using the verify phase as I did here)

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-antrun-plugin</artifactId>
            <version>1.8</version>
            <executions>
                <execution>
                    <!-- This can be run separately with mvn antrun:run@detekt -->
                    <id>detekt</id>
                    <phase>verify</phase>
                    <configuration>
                        <target name="detekt">
                            <java taskname="detekt" dir="${basedir}" fork="true" failonerror="true"
                                  classname="io.gitlab.arturbosch.detekt.cli.Main" classpathref="maven.plugin.classpath">
                                <arg value="-i"/>
                                <arg value="${basedir}/src"/>
                                <arg value="-f"/>
                                <arg value=".*test.*"/>
                                <arg value="--useTabs"/>
                            </java>
                        </target>
                    </configuration>
                    <goals><goal>run</goal></goals>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>io.gitlab.arturbosch.detekt</groupId>
                    <artifactId>detekt-cli</artifactId>
                    <version>1.0.0.[CURRENT_MILESTONE]</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

<pluginRepositories>
  <pluginRepository>
    <id>arturbosch-code-analysis</id>
    <name>arturbosch-code-analysis (for detekt)</name>
    <url>https://dl.bintray.com/arturbosch/code-analysis/</url>
    <layout>default</layout>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>never</updatePolicy>
    </releases>
    <snapshots>
      <enabled>false</enabled>
      <updatePolicy>never</updatePolicy>
    </snapshots>
  </pluginRepository>
</pluginRepositories>

RuleSets

Currently there are seven rule sets which are used per default when running the CLI.

complexity - This rule set contains rules that report complex code.
style - The Style ruleset provides rules that assert the style of the code. This will help keep code in line with the given code style guidelines.
comments - This rule set provides rules that address issues in comments and documentation of the code.
exceptions - Rules in this rule set report issues related to how code throws and handles Exceptions.
empty-blocks - The empty-blocks ruleset contains rules that will report empty blocks of code which should be avoided.
potential-bugs - The potential-bugs rule set provides rules that detect potential bugs.
performance - The performance rule set analyzes code for potential performance problems.

RuleSet Configuration

To turn off specific rules/rule sets or change threshold values for certain rules a yaml configuration file can be used. There are two approaches to configuring your rulesets.

Copy defaults and modify

Export the default config with the --generate-config flag or copy and modify the default-detekt-config.yml for your needs.

Override defaults (via `failFast` option)

Set failFast: true in your detekt.yml configuration file. As a result, every rule will be enabled and warningThreshold and errorThreshold will be set to 0. Weights can then be ignored and left untouched.

To adjust, for example, the maxLineLength value, use this configuration file:

failFast:true
autoCorrect: true

style:
  MaxLineLength:
    maxLineLength: 100

All rules are turned on by default and the value of maxLineLength is adjusted to 100. If you don't want to have the CommentOverPrivateMethod turned on, you append:

comments:
  CommentOverPrivateMethod:
    active: false

Suppress code smell rules

detekt supports the Java (@SuppressWarnings) and Kotlin (@Suppress) style suppression. If both annotations are present, only Kotlin's annotation is used! To suppress a rule, the id of the rule must be written inside the values field of the annotation e.g. @Suppress("LongMethod", "LongParameterList", ...)

Configure build failure thresholds

detekt now can throw a BuildFailure(Exception) and let the build fail with following config parameters:

build:
  warningThreshold: 5 // Five weighted findings 
  failThreshold: 10 // Ten weighted smells to fail the build
  weights:
    complexity: 2 // Whole complexity rule should add two for each finding.
    LongParameterList: 1 // The specific rule should not add two.
    comments: 0 // Comments should not fail the build at all?!

Every rule and rule set can be attached with an integer value which is the weight of the finding. For example: If you have 5 findings of the category complexity, then your failThreshold of 10 is reached as 5 x 2 = 10.

The formula for weights: RuleID > RuleSetID > 1. Only integer values are supported.

Extending detekt

Custom RuleSets

detekt uses a ServiceLoader to collect all instances of RuleSetProvider-interfaces. So it is possible to define rules/rule sets and enhance detekt with your own flavor. Attention: You need a resources/META-INF/services/io.gitlab.arturbosch.detekt.api.RuleSetProvider file which has as content the fully qualified name of your RuleSetProvider e.g. io.gitlab.arturbosch.detekt.sampleruleset.SampleProvider.

The easiest way to define a rule set is to clone the provided detekt-sample-ruleset project.

Own rules have to extend the abstract Rule class and override the visitXXX functions from the AST. A RuleSetProvider must be implemented which declares a RuleSet in the instance method. To allow your rule to be configurable, pass it a Config object from within your rule set provider. You can also specify a Severity type for your rule.

Example of a custom rule:

class TooManyFunctions : Rule("TooManyFunctions") {

	private var amount: Int = 0

	override fun visitFile(file: PsiFile) {
		super.visitFile(file)
		if (amount > 10) {
			addFindings(CodeSmell(id, Entity.from(file)))
		}
	}

	override fun visitNamedFunction(function: KtNamedFunction) {
		amount++
	}

}

Example of a much preciser rule in terms of more specific CodeSmell constructor and Rule attributes:

class TooManyFunctions2(config: Config) : Rule("TooManyFunctionsTwo", Severity.Maintainability, config) {

	private var amount: Int = 0

	override fun visitFile(file: PsiFile) {
		super.visitFile(file)
		if (amount > 10) {
			addFindings(CodeSmell(
					id = id, entity = Entity.from(file),
					description = "Too many functions can make the maintainability of a file costlier",
					metrics = listOf(Metric(type = "SIZE", value = amount, threshold = 10)),
					references = listOf())
			)
		}
	}

	override fun visitNamedFunction(function: KtNamedFunction) {
		amount++
	}

}

If you want your rule to be configurable, write down your properties inside the detekt.yml file and use the withConfig function:

MyRuleSet:
  MyRule:
    MyMetric: 5
    threshold: 10
  OtherRule:
    active: false

By specifying the rule set and rule ids, detekt will use the sub configuration of MyRule:

val threshold = withConfig { valueOrDefault("threshold") { threshold } }

Maven

If your using maven to build rule sets or use detekt as a dependency, you have to run the additional task publishToMavenLocal

Custom Processors

TODO

Custom Reports

detekt allows you to extend the console output and to create custom output formats.

For example if you do not like the default printing of findings, we can ... TODO

Testing your rules

To test your rules you need a KtFile object and use its visit method. There are two predefined methods to help obtaining a KtFile:

compileContentForTest(content: String): KtFile
compileForTest(path: Path): KtFile

New with M3 there is a special detekt-test module, which specifies above two methods but also Rule extension functions that allow to skip compilation, ktFile and visit procedures.

Rule.lint(StringContent/Path/KtFile) returns just the findings for given content

Code Smell baseline and ignore list

Specify a report output with --output parameter and specify its format with --output-format. Now you can generate a report which holds all findings of current analysis.

With --baseline you generate a baseline.xml where code smells are white- or blacklisted.

<SmellBaseline>
  <Blacklist timestamp="1483388204705">
    <ID>CatchRuntimeException:Junk.kt$e: RuntimeException</ID>
  </Blacklist>
  <Whitelist timestamp="1496432564542">
    <ID>NestedBlockDepth:Indentation.kt$Indentation$override fun procedure(node: ASTNode)</ID>
    <ID>ComplexCondition:SpacingAroundOperator.kt$SpacingAroundOperator$tokenSet.contains(node.elementType) &amp;&amp; node is LeafPsiElement &amp;&amp; !node.isPartOf(KtPrefixExpression::class) &amp;&amp; // not unary !node.isPartOf(KtTypeParameterList::class) &amp;&amp; // fun &lt;T&gt;fn(): T {} !node.isPartOf(KtTypeArgumentList::class) &amp;&amp; // C&lt;T&gt; !node.isPartOf(KtValueArgument::class) &amp;&amp; // fn(*array) !node.isPartOf(KtImportDirective::class) &amp;&amp; // import * !node.isPartOf(KtSuperExpression::class)</ID>
    <ID>TooManyFunctions:LargeClass.kt$io.gitlab.arturbosch.detekt.rules.complexity.LargeClass.kt</ID>
    <ID>ComplexMethod:DetektExtension.kt$DetektExtension$fun convertToArguments(): MutableList&lt;String&gt;</ID>
  </Whitelist>
</SmellBaseline>

The intention of a whitelist is that only new code smells are printed on further analysis. The blacklist can be used to write down false positive detections. The ID node must be build of <RuleID>:<Signature>. Both values can be found inside the report file.

Contributors

Artur Bosch - Maintainer
Marvin Ramin - Collaborator, Bunch of rules, Active on Issues, refactorings, MultiRule
schalks - Collaborator, Active on Issues, Bunch of rules, Project metrics
Niklas Baudy - Active on Issues, Bunch of rules, Bug fixes
lummax - Cli enhancements
Svyatoslav Chatchenko - Active on Issues, NamingConventions and UnusedImport fixes
Sean Flanigan - Config from classpath resource
Sebastian Schuberth - Active on Issues, Windows support
Olivier Lemasle - NP-Bugfix
Marc Prengemann - Support for custom output formats, prototyped Rule-Context-Issue separation
Sebastiano Poggi - Enhanced milestone report script, Magic number fixes
Ilya Tretyakov - Sonar runs should not auto correct formatting.
Andrey T - Readme fix
Ivan Balaksha - Rules: UnsafeCast, SpreadOperator, UnsafeCallOnNullableType, LabeledExpression
Anna Y - Readme fix
Karol Wrótniak - Treat comments as not empty blocks
Radim Vaculik - VariableMaxLength - bugfix
Martin Nonnenmacher - UndocumentedPublicClass - enum support
Dmytro Troynikov - Updated Magic Number rule to ignore Named Arguments
Andrew Ochsner - Updated Readme for failFast option
Paul Merlin - Gradle build improvements
Konstantin Aksenov - Coding improvement
Matthew Haughton - Started type resolution, Dependency updates, Coding + Documentation improvements
Janusz Bagiński - Fixed line number reporting for MaxLineLengthRule
Mike Kobit - Gradle build improvements
Philipp Hofmann - Readme improvements
Olivier PEREZ - Fixed Typo in Readme
Sebastian Kaspari - Html-Output-Format, Documentation fix
Ilya Zorin - Rule improvement: UnnecessaryAbstractClass
Gesh Markov - Improve error message for incorrect configuration file
Patrick Pilch - Rule improvement: ReturnCount
Serj Lotutovici - Rule improvement: LongParameterList

Mentions

As mentioned/used in ...

Credits

JetBrains - Creating Intellij + Kotlin
PMD & Checkstyle & KtLint - Ideas for threshold values and style rules

jvilya/detekt

detekt

Features

Table of contents

Build & use the commandline interface

Parameters for CLI

Using the detekt-gradle-plugin

Configuration when using groovy dsl

Configuration when using kotlin dsl

Configuration for Android projects

Available plugin tasks

Options for detekt configuration closure

Configure a local idea for detekt

Using detekt in custom gradle projects

Using detekt in Maven Projects

RuleSets

RuleSet Configuration

Copy defaults and modify

Override defaults (via `failFast` option)

Suppress code smell rules

Configure build failure thresholds

Extending detekt

Custom RuleSets

Maven

Custom Processors

Custom Reports

Testing your rules

Code Smell baseline and ignore list

Contributors

Mentions

Credits

jvilya/detekt

detekt

Features

Table of contents

Parameters for CLI

Copy defaults and modify

Override defaults (via failFast option)

Maven

Credits

Override defaults (via `failFast` option)