Skip to content

Commit

Permalink
docs: explain how users can customize linting behavior of rules
Browse files Browse the repository at this point in the history
  • Loading branch information
bjaglin committed Sep 1, 2024
1 parent 90d0edb commit ab36713
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 2 deletions.
68 changes: 68 additions & 0 deletions docs/users/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,71 @@ triggered.rules = [
DisableSyntax
]
```

## Overriding the linting behavior

By default, only lints raised with `LintSeverity.Error` will result in a
non-zero exit code. To force Scalafix to return a non-zero exit code for other
diagnostics, it is possible to promote non-error diagnostics to the error level
without touching the rules(s) source code, thanks to `lint.error`.

This key accepts as value either
* a string, interpreted as a regular expression to match diagnostics using the
`<rule_name>[.<lint_id>]` pattern,
* a list of strings, treated as several regular expressions like above,
* an object, with `include` and `exclude` attributes, each treated as regular
expressions like above.

As an example, to force all linter reports to trigger an error, except for unused
suppressions, any of the 3 configuration files below can be used, as they are
effectively equivalent.

```scala
// .scalafix.conf
lint.error = "^((?!UnusedScalafixSuppression).)*$"
```

```scala
// .scalafix.conf
lint.error = [
"^((?!UnusedScalafixSuppression).)*$"
]
```

```scala
// .scalafix.conf
lint.error = {
includes = ".*"
excludes = "UnusedScalafixSuppression"
}
```

Similarly, diagnostics can be controlled through `lint.ignore`, `lint.info`,
and `lint.warning`, which respectively suppress matching diagnostics, force
them to be at info level, and force them to be at warning level.

## Passing configuration as CLI arguments

It is possible to pass configuration flags with scalar values as CLI arguments,
overriding any potential value set in the configuration file, by prefixing the
qualified name of each attribute with `--settings.`.

For example, the configuration file below

```scala
// .scalafix.conf
DisableSyntax {
noFinalize = true
}
lint.error.includes = ".*"
lint.error.excludes = "UnusedScalafixSuppression"
```

is equivalent to the following CLI arguments

```
scalafix ... \
--settings.DisableSyntax.noFinalize=true \
--settings.lint.error.includes=.* \
--settings.lint.error.excludes=UnusedScalafixSuppression
```
11 changes: 9 additions & 2 deletions docs/users/suppression.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,15 @@ id: suppression
title: Suppressing rules
---

Sometimes you need to ignore the output from Scalafix. Scalafix provides two
methods for suppressing rules: annotations and comments.
Sometimes you need to ignore the output from Scalafix.

For linters, and for linters only, an easy way to achieve that is to
selectively ignore some diagnostics via
[`lint.ignore`](configuration.md#overriding-the-linting-behavior).
However, this toggle is global, which is rarely what is needed.

Scalafix provides two methods for suppressing rules in source code: annotations
and comments.

- Annotations: great for disabling regions of code but some source code
locations are impossible to annotate.
Expand Down

0 comments on commit ab36713

Please sign in to comment.