gradle-scalafix

This plugin allows you to run Scalafix (a refactoring and linting tool for Scala) on Gradle projects. It supports both syntactic and semantic rules and lets you load your own custom rules via Gradle dependencies.

Compatibility

• Gradle: 4.10 or later (except 5.0)
• Scala: 2.12.x / 2.13.x / 3.x (requires Gradle 7.3 or later)
• JDK: 8 or later

Usage

To use the Scalafix plugin, please include the following snippet in your build script:

plugins {
    id 'scala' // <-- required
    id 'io.github.cosmicsilence.scalafix' version '<version>'
}

Selecting Rules

By default, Scalafix won't run any rules unless they are specified via configuration file or command line argument. In order to decide what rules to pick and how to configure them, please check out Scalafix's built-in rules as well as external rules provided by the community.

1. Via config file:

This is the recommended approach if you want to repeatedly run Scalafix as part of your build and day-to-day development. For that you need to create a file named .scalafix.conf in the root directory of your project and enter the configuration for the rules you want to have enabled. The configuration uses the HOCON syntax and is well documented on the Scalafix website. If you are using external rules, please take a look at the documentation provided by them. Below is a basic example of using one of the Scalafix's built-in rules so you can quickly get started:

rules = [
  DisableSyntax
]

DisableSyntax.noNulls = true
DisableSyntax.noVars = true

Tip: Multi-modules Gradle projects are allowed to define different combinations of Scalafix rules/settings for each individual subproject. This can be achieved by having a .scalafix.conf file defined in the subproject folder. The Scalafix plugin will first try to locate the config file at the subproject level and, if not found, at the root project level. It is also possible to inform a custom path via the plugin extension in the build script. See the extension section for more details.

2. Via command line argument:

There are times when it may be desirable to run a single or a subset of Scalafix rules without having to touch the configuration file. For those one-off scenarios, you can inform the rule(s) you want to run using the scalafix.rules property:

./gradlew scalafix -Pscalafix.rules=DisableSyntax,RemoveUnused

Required Compiler Options

Some Scalafix rules (e.g. RemoveUnused in Scala 2.x) require additional options to be passed into the Scala compiler. That can be achieved as following:

tasks.withType(ScalaCompile) {
    scalaCompileOptions.additionalParameters = [ "-Ywarn-unused" ]
}

Tasks

The following Gradle tasks are created when the Scalafix plugin is applied to a project:

Note: If the SemanticDB Scala compiler plugin is enabled (see the extension section for more details), any of these tasks will trigger partial or complete compilation of Scala source files.

Extension

The plugin defines the scalafix extension which enables some customisations. None of the properties are mandatory:

semanticdb is a closure where the following properties can be configured:

Example:

scalafix {
    configFile = file("config/myscalafix.conf")
    includes = ["/com/**/*.scala"]
    excludes = ["**/generated/**"]
    ignoreSourceSets = ["scoverage"]
    semanticdb {
        autoConfigure = false
    }
}

Loading Custom Rules

One of the nice things about the Scalafix tool is that it is extensible. That means that you can implement your own custom rules or reuse rules somebody else has already implemented and load them into Scalafix to run in your projects. The Gradle Scalafix plugin lets you take advantage of that feature by allowing external rules to be informed as regular dependencies in your Gradle build script using the scalafix configuration. Examples:

dependencies {
    // From a published jar
    scalafix "org.typelevel:typelevel-scalafix_${scalaVersion}:+"

    // From a local subproject
    scalafix project(':my-scalafix-rules')

    // From a local source set
    scalafix sourceSets.myScalafixRules.output
}

Maintainers

• Felix Sanjuan - @fsanjuan
• Marcelo Cenerino - @marcelocenerine