Run detekt using the Compiler Plugin

You can integrate detekt in your project using the Detekt Compiler Plugin instead of the classic Detekt Gradle Plugin. Detekt offers a compiler plugin for K1 which allows you to run detekt as part of the Kotlin compilation process. This allows you to run detekt on your code without having separate tasks to invoke and results in much faster execution of detekt, especially if you're using type resolution.

caution

Please note that Detekt Compiler Plugin is an experimental extension of detekt. We expect it to be stable with the upcoming release of detekt (2.x)

Using Gradle

Adding the Compiler Plugin

To use the detekt Compiler Plugin, you will have to add the following Gradle Plugin:

plugins {
  id("io.github.detekt.gradle.compiler-plugin") version "1.23.3"
}

Configuring the Compiler Plugin

The compiler plugin can be configured using the react{} block in your gradle file.

The following options are allowed:

detekt {
    // Define the detekt configuration(s) you want to use.
    // Defaults to the default detekt configuration.
    config.setFrom("path/to/config.yml")

    // Applies the config files on top of detekt's default config file. `false` by default.
    buildUponDefaultConfig = false

    // Turns on all the rules. `false` by default.
    allRules = false

    // Specifying a baseline file. All findings stored in this file in subsequent runs of detekt.
    baseline = file("path/to/baseline.xml")

    // Disables all default detekt rulesets and will only run detekt with custom rules
    // defined in plugins passed in with `detektPlugins` configuration. `false` by default.
    disableDefaultRuleSets = false

    // Adds debug output during task execution. `false` by default.
    debug = false

    // Kill switch to turn off the Compiler Plugin execution entirely.
    enableCompilerPlugin = true
}

Moreover, detekt reports can be configured at the Kotlin Compilation tasks level as follows

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
    detekt {
        reports {
            xml.enabled.set(true)
            txt.enabled.set(false)
            create("custom") {
                enabled.set(false)
            }
        }
    }
}

Adding third party plugins

As for the Detekt Gradle Plugin, you can add third party plugins to the Compiler Plugin using the detektPlugins configuration.

dependencies {
    detektPlugins("io.gitlab.arturbosch.detekt:detekt-formatting:1.23.3")
}

Running the Compiler Plugin

The compiler plugin will run during your compileKotlin tasks execution:

$ ./gradlew compileKotlin

> Task :example:compileKotlin
w: Analysis failed with 1 weighted issues.
w: file:///.../example/src/main/java/Sample.kt:4:17 MagicNumber: This expression contains a magic number. Consider defining it to a well named constant.

BUILD SUCCESSFUL in 1s
5 actionable tasks: 1 executed, 4 up-to-date

Using CLI compiler

You can also use the Compiler Plugin with the Kotlin command-line compiler.

You'll need to grab detekt-compiler-plugin-<version>-all.jar from our GitHub releases page or Maven Central io.github.detekt:detekt-compiler-plugin artifact (note that you'll need the uber-jar file, the one with the all classifier).

You can attach the plugin by providing the path to its JAR file using the -Xplugin kotlinc option:

kotlinc Main.kt -Xplugin=./detekt-compiler-plugin-1.23.7-all.jar

It's possible to pass options to the plugin using the -P kotlinc option:

# The plugin option format is: "-P plugin:detekt-compiler-plugin:<key>=<value>".
# Options can be repeated.

-P plugin:detekt-compiler-plugin:config=path/to/config.yml
-P plugin:detekt-compiler-plugin:debug=true

The available options are:

config=<path|paths> # Comma separated paths to detekt config files.
baseline=<path> # Path to a detekt baseline file.
debug=<true|false> # Print debug messages.
isEnabled=<true|false> # Should detekt run?
useDefaultConfig=<true|false> # Use the default detekt config as baseline.
allRules=<true|false> # Turns on all the rules.
disableDefaultRuleSets=<true|false> # Disables all default detekt rulesets.
parallel=<true|false> # Enables parallel compilation and analysis of source files.
rootPath=<path> # Root path used to relativize paths when using exclude patterns.
excludes=<base64-encoded globs> # A base64-encoded list of the globs used to exclude paths from scanning.
report=<report-id:path> # Generates a report for given 'report-id' and stores it on given 'path'. Available 'report-id' values: 'txt', 'xml', 'html'.

Known Issues

1. The rule InvalidPackageDeckaration is known to not be working well with the Compiler Plugin #5747.