diktat

Strict coding standard for Kotlin and a custom set of rules for detecting code smells, code style issues and bugs

View the Project on GitHub saveourtool/diktat

Build and test deteKT static analysis diKTat code style codecov

Releases Maven Central FOSSA Status Chat on Telegram

Hits-of-Code Lines of code GitHub repo size Awesome Kotlin Badge

DiKTat is a strict coding standard for Kotlin and a collection of Kotlin code style rules implemented as AST visitors on the top of KTlint. It can be used for detecting and autofixing code smells in CI/CD process. The full list of available supported rules and inspections can be found here.

Now diKTat was already added to the lists of static analysis tools, to kotlin-awesome and to kompar. Thanks to the community for this support!

See first

           
Codestyle Inspections Examples Demo White Paper Groups of Inspections

Why should I use diktat in my CI/CD?

There are several tools like detekt and ktlint that are doing static analysis. Why do I need diktat?

First of all - actually you can combine diktat with any other static analyzers. And diKTat is even using ktlint framework for parsing the code into the AST. Main features of diktat are the following:

1) More inspections. It has 100+ inspections that are tightly coupled with it’s Codestyle.

2) Unique Inspections that are missing in other linters.

3) Highly configurable. Each and every inspection can be configured or suppressed.

4) Strict detailed Codestyle that you can adopt and use in your project.

Run as CLI-application

Download and install binaries

  1. Install KTlint manually: here

    OR use curl:

    # another option is "brew install ktlint"
    
    curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.46.1/ktlint && chmod a+x ktlint
    
  2. Load diKTat manually: here

    OR use curl:

    $ curl -sSLO https://github.com/saveourtool/diKTat/releases/download/v1.2.4.2/diktat-1.2.4.2.jar
    

Run diKTat

Finally, run KTlint (with diKTat injected) to check your ‘*.kt’ files in ‘dir/your/dir’:

$ ./ktlint -R diktat.jar --disabled_rules=standard "dir/your/dir/**/*.kt"

To autofix all code style violations, use -F option.

Run with Maven using diktat-maven-plugin

:heavy_exclamation_mark: If you are using Java 16+, you need to add --add-opens java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED flag to the JVM. For more information, see: https://github.com/pinterest/ktlint/issues/1195 This can be done by setting MAVEN_OPTS variable:

export MAVEN_OPTS="--add-opens java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED"

This plugin is available since version 0.1.3. You can see how it is configured in our project for self-checks: pom.xml. If you use it and encounter any problems, feel free to open issues on github.

Add this plugin to your pom.xml: ```xml org.cqfn.diktat diktat-maven-plugin ${diktat.version} diktat none check fix ${project.basedir}/src/main/kotlin</input> ${project.basedir}/src/test/kotlin</input> diktat-analysis.yml ${project.basedir}/src/test/kotlin/excluded ```

To run diktat in only-check mode use command $ mvn diktat:check@diktat. To run diktat in autocorrect mode use command $ mvn diktat:fix@diktat.

Requesting a specific Maven executionId on the command line (the trailing diktat in the above example) may be essential in these cases:

If you omit the executionId:

$ mvn diktat:check

— the plug-in will use the default configuration and search for diktat-analysis.yml file in the project directory (you can still customize the rule sets by editing the YAML file).

Run with Gradle using diktat-gradle-plugin

Requires a gradle version no lower than 5.3.

This plugin is available since version 0.1.5. You can see how the plugin is configured in our examples: build.gradle.kts.

Add this plugin to your `build.gradle.kts`: ```kotlin plugins { id("org.cqfn.diktat.diktat-gradle-plugin") version "1.2.4.2" } ``` Or use buildscript syntax: ```kotlin buildscript { repositories { mavenCentral() } dependencies { classpath("org.cqfn.diktat:diktat-gradle-plugin:1.2.4.2") } } apply(plugin = "org.cqfn.diktat.diktat-gradle-plugin") ``` You can then configure diktat using `diktat` extension: ```kotlin diktat { inputs { include("src/**/*.kt") // path matching this pattern (per PatternFilterable) that will be checked by diktat exclude("src/test/kotlin/excluded/**") // path matching this pattern will not be checked by diktat } debug = true // turn on debug logging } ``` Also in `diktat` extension you can configure different reporters and their output. You can specify `json`, `html`, `sarif`, `plain` (default). If `output` is set, it should be a file path. If not set, results will be printed to stdout. ```kotlin diktat { // since 1.2.4.2 to keep in line with maven properties reporter = "json" // "html", "json", "plain" (default), "sarif" // before 1.2.4.2 // reporterType = "json" // "html", "json", "plain" (default), "sarif" output = "someFile.json" } ```

You can run diktat checks using task diktatCheck and automatically fix errors with tasks diktatFix.

Run with Spotless

Spotless is a linter aggregator.

Gradle

Diktat can be run via spotless-gradle-plugin since version 5.10.0

Add this plugin to your build.gradle.kts ```kotlin plugins { id("com.diffplug.spotless") version "5.10.0" } spotless { kotlin { diktat() } kotlinGradle { diktat() } } ```
You can provide a version and configuration path manually as configFile. ```kotlin spotless { kotlin { diktat("1.2.4.2").configFile("full/path/to/diktat-analysis.yml") } } ```

Maven

Diktat can be run via spotless-maven-plugin since version 2.8.0

Add this plugin to your pom.xml ```xml com.diffplug.spotless spotless-maven-plugin ${spotless.version} ```
You can provide a version and configuration path manually as configFile ```xml 1.2.4.2 full/path/to/diktat-analysis.yml ```

GitHub Integration

We suggest everyone to use common “sarif” format as a reporter (reporterType) in CI/CD. GitHub has an integration with SARIF format and provides you a native reporting of diktat issues in Pull Requests.

img.png

Github Integration 1) Add the following configuration to your project's setup for GitHub Actions: Gradle Plugin: ```text githubActions = true ``` Maven Plugin (pom.xml): ```xml true ``` Maven Plugin (cli options): ```text mvn -B diktat:check@diktat -Ddiktat.githubActions=true ``` 2) Add the following code to your GitHub Action to upload diktat SARIF report (after it was generated): ```yml - name: Upload SARIF to Github using the upload-sarif action uses: github/codeql-action/upload-sarif@v1 if: $ with: sarif_file: $ ``` *Note*: `codeql-action/upload-sarif` limits the number of uploaded files at 15. If your project has more than 15 subprojects, the limit will be exceeded and the step will fail. To solve this issue one can merge SARIF reports. `diktat-gradle-plugin` provides this capability with `mergeDiktatReports` task. This task aggregates reports of all diktat tasks of all Gradle project, which produce SARIF reports, and outputs the merged report into root project's build directory. Then this single file can be used as an input for Github action: ```yaml with: sarif_file: build/reports/diktat/diktat-merged.sarif ```

Customizations via diktat-analysis.yml

In KTlint, rules can be configured via .editorconfig, but this does not give a chance to customize or enable/disable each and every rule independently. That is why we have supported diktat-analysis.yml that can be easily changed and help in customization of your own rule set. It has simple fields: name — name of the rule, enabled (true/false) — to enable or disable that rule (all rules are enabled by the default), configuration — a simple map of some extra unique configurations for this particular rule. For example:

- name: HEADER_MISSING_OR_WRONG_COPYRIGHT
  # all rules are enabled by the default. To disable add 'enabled: false' to the config.
  enabled: true
  configuration:
    isCopyrightMandatory: true
    copyrightText: Copyright (c) Jeff Lebowski, 2012-2020. All rights reserved.

Note, that you can specify and put diktat-analysis.yml that contains configuration of diktat in the parent directory of your project on the same level where build.gradle/pom.xml is stored.
See default configuration in diktat-analysis.yml
Also see the list of all rules supported by diKTat.

Suppress warnings/inspections

Suppress warnings on individual code blocks In addition to enabling/disabling warning globally via config file (`enable = false`), you can suppress warnings by adding `@Suppress` annotation on individual code blocks or `@file:Suppress()` annotation on a file-level. For example: ``` kotlin @Suppress("FUNCTION_NAME_INCORRECT_CASE") class SomeClass { fun methODTREE(): String { } } ```
Disable all inspections on selected code blocks Also you can suppress **all** warnings by adding `@Suppress("diktat")` annotation on individual code blocks. For example: ``` kotlin @Suppress("diktat") class SomeClass { fun methODTREE(): String { } } ```
ignoreAnnotated: disable inspections on blocks with predefined annotation In the `diktat-analysis.yml` file for each inspection it is possible to define a list of annotations that will cause disabling of the inspection on that particular code block: ```yaml - name: HEADER_NOT_BEFORE_PACKAGE enabled: true ignoreAnnotated: [MyAnnotation, Compose, Controller] ```
Suppress groups of inspections by chapters It is easy to suppress even groups of inspections in diKTat. These groups are linked to chapters of [Codestyle](/info/guide/diktat-coding-convention.html). To disable chapters, you will need to add the following configuration to common configuration (`- name: DIKTAT_COMMON`): ```yaml disabledChapters: "1, 2, 3" ``` Mapping of inspections to chapters can be found in [Groups of Inspections](/info/rules-mapping.html).

Running against the baseline

When setting up code style analysis on a large existing project, one often doesn’t have an ability to fix all findings at once. To allow gradual adoption, diktat and ktlint support baseline mode. When running ktlint for the first time with active baseline, the baseline file will be generated. It is a xml file with a complete list of findings by the tool. On later invocations, only the findings that are not in the baseline file will be reported. Baseline can be activated with CLI flag:

java -jar ktlint -R diktat.jar --baseline=diktat-baseline.xml **/*.kt

or with corresponding configuration options in maven or gradle plugins. Baseline report is intended to be added into the VCS, but it can be removed and re-generated later, if needed.

Contribution

See our Contributing Policy and Code of Conduct