> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Config (qlty.toml)

Project configuration stored in a `qlty.toml` file is used by both Qlty CLI and Qlty Cloud. We strongly recommend that this file is committed into Git version control.

This file uses the [TOML](https://toml.io/en/) format and is located at `.qlty/qlty.toml` in your repository:

```text theme={"system"}
your-git-repository/
├── .qlty/
│   ├── ... other qlty files
│   └── qlty.toml
└── ... rest of your repository files
```

<Note>
  If you do not have a `.qlty/qlty.toml` file checked in to your repository, Qlty Cloud will
  generate a new, temporary configuration file before running the analysis using `qlty init`.
</Note>

## `qlty.toml` Specification

Each field in the `qlty.toml` file corresponds to a specific configuration setting. Detailed descriptions of these settings are provided below.

### `config_version`

The version of the `qlty.toml` configuration file format. Currently, all `config_version`s are `0`. We may use this field in the future to introduce breaking changes to the configuration file format.

### `sources`

`sources` are defined at the top-level and specify repositories which contain plugin definitions. By convention, sources are placed at the top of the `qlty.toml` file.

The default auto-generated configuration file will include a default source conveniently named `default`. You can add additional sources from other Git repositories and name them as you like.

Below are the accepted properties to define a source:

| Name         | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `name`       | A unique name for this source                                  |
| `default`    | Set to `true` for the primary source (only one allowed)        |
| `repository` | The URL of the git repository                                  |
| `tag`        | The tag to fetch from the repository (conflicts with `branch`) |
| `branch`     | The branch to fetch from the repository (conflicts with `tag`) |

Follow the example below to add a new source:

```toml lines theme={"system"}
[[source]]
name = "example"
repository = "https://github.com/example/example.git"
branch = "main"
```

<Warning>
  For each source, you can specify either a `tag` or a `branch`, but not both. If you specify
  both, the `tag` will be used.
</Warning>

### `exclude_patterns`

Qlty is Git-aware and honors `.gitignore` files. The `exclude_patterns` setting allows you to specify additional directories and/or files that should be completely excluded from all Qlty activities, both from Qlty Cloud and Qlty CLI. This setting uses [glob syntax](https://en.wikipedia.org/wiki/Glob_\(programming\)) to match file and directory names.

This setting is useful for excluding files that are not relevant for Qlty, such as generated code, build artifacts, temporary files, or third-party libraries. Below is an example of how to customize the `exclude_patterns` setting to fit your project:

```toml lines theme={"system"}
exclude_patterns = [
  "*.log",
  "**/*.min.js",
  "**/node_modules/**",
  "**/*.spec.js"
]
```

### `test_patterns`

The `test_patterns` setting allows you to specify directories and/or files that should considered automated tests run at build time rather than runtime application code. Qlty Cloud uses this information in order to provide higher quality analysis results.

This setting uses [glob syntax](https://en.wikipedia.org/wiki/Glob_\(programming\)) to match file and directory names. Below is an example of how to customize the `test_patterns` setting to fit your project:

```toml lines theme={"system"}
test_patterns = [
  "**/test/**",
  "**/spec/**",
  "**/test_*.*",
  "**/spec_*.*",
  "**/*_test.*",
  "**/*_spec.*",
]
```

### `smells`

The `smells` setting defined at the top-level is used to configure the functioning of the `qlty smell` CLI command, which is employed by Qlty Cloud to identify code smells in your project. This allows you to customize the detection and management of various code quality smells.

These settings apply for all supported programming languages, and can be customized further for each language using the `languages` setting.

#### `smells.mode`

The `mode` setting determines how Qlty Cloud handles detected code smells. Four modes are available:

| Mode                | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `block`             | Code smells may fail the Qlty Gate (post them as pull request comments) |
| `comment` (default) | Post comments on pull requests but never fail the Qlty Gate             |
| `monitor`           | Analyze and report smells on Qlty Cloud but never post them to GitHub   |
| `disabled`          | Smell detection will be disabled                                        |

#### `smells.[name].enabled`

The `enabled` setting allows you to enable or disable the detection of specific code smells. By default, all smells are enabled, but you can selectively disable those that are not relevant to your project.

Below is an example of how to enable or disable specific smells:

```toml lines theme={"system"}
[smells.boolean_logic]
enabled = true

[smells.nested_control_flow]
enabled = false
```

#### `smells.[name].threshold`

The `smells.[name].threshold` setting allows you to fine-tune the parameters for identifying specific types of code smells. Below is a comprehensive list of all available smell settings and their default thresholds:

| Smell Name            | Threshold                                                                          | Default |
| --------------------- | ---------------------------------------------------------------------------------- | ------- |
| `boolean_logic`       | Maximum number of boolean operators (such as `and` or `or`) in a single expression | 5       |
| `nested_control_flow` | Maximum number of nested control flow statements                                   | 5       |
| `function_parameters` | Maximum number of function parameters                                              | 5       |
| `return_statements`   | Maximum number of return statements in a function                                  | 6       |
| `file_complexity`     | Maximum allowed complexity for a single file                                       | 50      |
| `function_complexity` | Maximum function complexity                                                        | 15      |
| `identical_code`      | Minimum number of duplicated lines for identical code to be flagged                | 12      |
| `similar_code`        | Minimum number of duplicated lines for similar code to be flagged                  | 12      |

#### `smells.duplication`

The `smells.duplication` setting configures umbrella settings for duplicated code detection (*copypasta code*) that apply to both the `identical_code` and `similar_code` smells.

| Setting Name      | Description                                                                                            | Default |
| ----------------- | ------------------------------------------------------------------------------------------------------ | ------- |
| `nodes_threshold` | The minimum number of AST children nodes for a single node to be included in the duplication detection | 50      |
| `filter_patterns` | Glob patterns to exclude from duplication checks                                                       |         |

To control the `enabled` and `threshold` settings for duplication, use `smells.identical_code` and `smells.similar_code` instead:

```toml lines theme={"system"}
[smells.identical_code]
enabled = true
threshold = 20

[smells.similar_code]
enabled = true
threshold = 20

[smells.duplication]
nodes_threshold = 30
```

<Note>
  These settings apply to all programming languages. You can customize the duplication detection
  settings for specific languages using the `language` setting.
</Note>

### `language.[name]`

The `language.[name]` setting allows you to customize various settings on a per-language basis, applicable to both Qlty Cloud and Qlty CLI.

#### `language.[name].smells`

This setting enables you to configure the detection and management of various code quality smells for a specific programming language. Below is an example of how to customize the detection of code smells for a particular language:

```toml lines theme={"system"}
[language.rust.smells]
duplication.filter_patterns = ["(use_declaration _)"]
duplication.nodes_threshold = 40
function_parameters.threshold = 6
function_complexity.threshold = 20
```

Alternatively, you can use this equally valid [TOML](https://toml.io/en/) syntax:

```toml lines theme={"system"}
[language.rust.smells.duplication]
filter_patterns = ["(use_declaration _)"]
nodes_threshold = 40

[language.rust.smells.function_parameters]
threshold = 6

[language.rust.smells.function_complexity]
threshold = 20
```

### `[[plugin]]`

Each `[[plugin]]` entry must be defined at the top-level of the `qlty.toml` file, specifying the configuration for a specific plugin. You will need one `[[plugin]]` entry for each plugin you want to enable in your project.

Below are the accepted properties for defining a `[[plugin]]` entry:

| Name              | Description                                                                                                                                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | The plugin name, e.g., *eslint*, *rubocop*, etc                                                                                                                                                                                                                                  |
| `version`         | The plugin version, following the version specification used by the plugin (this may vary across plugins)                                                                                                                                                                        |
| `extra_packages`  | Some plugins, like the *stylelint* plugin, are usually used in combination with other packages such as `stylelint-config-standard-scss`. This setting allows you to define these additional packages. This is also commonly used by other plugins such as *eslint* and *rubocop* |
| `package_file`    | This setting is only relevant to some plugins, like *eslint*, that heavily depend on external files. It specifies where a certain package file is located. For *eslint*, you may want to indicate the location of your `package.json`                                            |
| `package_filters` | This setting is only relevant when package\_file is specified, it is a list of strings, if a package in the package\_file has a name containing a filter, it is filtered out and the rest are removed from package file, so that only relevant packages can be installed.        |
| `drivers`         | List of drivers to activate for the plugin, if not specified all drivers are activated.                                                                                                                                                                                          |
| `config_files`    | List of file names (not paths), that contain configuration information needed to run the plugin, for example custom cop files for rubocop.                                                                                                                                       |
| `affects_cache`   | List of file names (not paths), changing which can affect the cache of existing issues for a plugin.                                                                                                                                                                             |
| `mode`            | Enum with the values: `block`, `comment`, `monitor`, `disabled`. <br /> - `block`: sends red statuses on Github <br /> - `comment`: only sends comments <br /> - `monitor`: just records the issues <br /> - `disabled`: disables the plugin                                     |
| `triggers`        | List of enum values: `manual`, `ide`, `agent`, `pre-commit`, `pre-push`, `build`. <br /> Use to trigger the plugin on specific events only and not all.                                                                                                                          |
| `skip_upstream`   | Whether the plugin should run against the upstream or not. The default is `false`                                                                                                                                                                                                |
| `prefix`          | Run the plugin in a specific subdirectory of the project root, the plugin's targets and config files are limited to that subdirectory only. Useful for monorepo setups, as same plugin can be specified with multiple prefixes.                                                  |

Follow the example below to customize the execution of a plugin:

```toml lines theme={"system"}
[[plugin]]
name = "stylelint"
version = "15.10.3"
extra_packages = ["stylelint-config-standard-scss@11.0.0"]
```

<Note> To get started with a new plugin, you can run `qlty plugins enable <plugin-name>` to automatically add the plugin to your `qlty.toml file`.</Note>

### `[[exclude]]`

The `[[exclude]]` block allows you to declare rules to ignore certain issues in your project, applicable to both Qlty Cloud and Qlty CLI. Each `[[exclude]]` entry can specify conditions based on `plugins`, and `file patterns`. Qlty will avoid running the given plugins on files matching the patterns and ignore any issues that match them.

Below are the accepted properties for defining an `[[exclude]]` entry:

| Name             | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `file_patterns	` | A list of glob patterns to match files that should be ignored. The default pattern is `*` which matches all files |
| `plugins`        | A list of *plugin* names. Issues reported by these plugins will be ignored                                        |

Below is an example of how to use the `[[exclude]]` setting:

```toml lines theme={"system"}
# Exclude eslint from running on files in remix/app/components/ui/
[[exclude]]
plugins = ["eslint"]
file_patterns = ["react-app/app/components/ui/**"]
```

<Note> `[[exclude]]` blocks are evaluated sequentially, and the first match will be applied. </Note>

### `[[triage]]`

The `[[triage]]` block allows you to modify certain properties of issues detected by Qlty. Each `[[triage]]` entry is broken down into two parts, `match` and `set`. Match can specify conditions based on `plugins`, `levels`, `rules`, and `file patterns` to determine which issues the triage apply to. If an issue matches all the specified conditions, its properties will be overridden by the values specified in the set part of the `[[triage]]` entry.

Below are the properties for defining an `[[triage]]` entry, divided into *match.* and *set.*:

#### Match

| Name            | Description                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `plugins`       | A list of plugin names. Issues reported by these plugins will be matched                                                  |
| `rules`         | A list of rule names. Issues reported by these rules will be matched. Rules are plugin specific                           |
| `levels`        | A list of levels. Issues reported at these levels will be matched.                                                        |
| `file_patterns` | A list of glob patterns to match files whose issues should be matched. The default pattern is `*` which matches all files |

#### Set

| Name       | Description                                                                                                                                                                                                                                           |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `level`    | The new level for the issues that match the conditions. Possible values are `unspecified`, `fmt`, `low`, `medium`, `high`                                                                                                                             |
| `category` | The new category for the issues that match the conditions. Accepted categories are: `bug`, `vulnerability`, `structure`, `duplication`, `security_hotspot`, `performance`, `documentation`, `type_check`, `style`, `anti_pattern` and `accessibility` |
| `mode`     | The new mode for the issues that match the conditions. Possible values are `block`, `comment`, `monitor`, `disabled`                                                                                                                                  |
| `ignored`  | The issues are ignored if set to true. Accepts boolean values true or false                                                                                                                                                                           |

Below are examples of how to use the `[[triage]]` setting:

```toml lines theme={"system"}
# Override the level of eslint react/prop-types issues in react-app/components/ui/ to "low"
[[triage]]
match.rules = ["eslint:react/prop-types"]
match.file_patterns = ["react-app/components/ui/**"]
set.level = "low"

# Override the mode of all rubocop issues to "comment"
[[triage]]
match.plugins = ["rubocop"]
set.mode = "comment"

# Override the category of issues in node_modules directory to "dependency"
[[triage]]
match.file_patterns = ["**/node_modules/**"]
set.category = "dependency"
```

<Note> `[[triage]]` blocks are evaluated sequentially, and the first match will be applied </Note>

## Glob Syntax Reference

Following, a table that illustrates the most commonly used glob syntaxes accepted by Qlty:

| Example Pattern | Matches                                                  |
| --------------- | -------------------------------------------------------- |
| `foo.rb`        | `foo.rb` at the top-level of the repository              |
| `*.rb`          | all files at the top-level that end with `.rb`           |
| `**/foo.rb`     | `foo.rb` anywhere in the repository                      |
| `**/*.rb`       | all files that end with `.rb` anywhere in the repository |
| `**/test/**`    | All folders named `test` at any level                    |

## Full Example

The exact auto generated version of your `.qlty/qlty.toml` file will vary depending on the languages and frameworks used in your project. Below is a general example of how it may look like for a JavaScript project.

```toml lines theme={"system"}
config_version = "0" # Required, must be the string "0"

exclude_patterns = ["**/node_modules/**","**/vendor/**"]
test_patterns = ["**/test/**", "**/spec/**"]

[[source]]
name = "default"
default = true # The default source for plugin definitions

[[plugin]]
name = "actionlint"

[[plugin]]
name = "checkov"
version = "3.2.49"

[[plugin]]
name = "markdownlint"
version = "0.31.1"

[[plugin]]
name = "osv-scanner"

[[plugin]]
name = "prettier"
version = "2.8.4"

[[plugin]]
name = "ripgrep"

[[plugin]]
name = "shellcheck"
version = "0.9.0"

[[plugin]]
name = "shfmt"

[[plugin]]
name = "trivy"

[[plugin]]
name = "trufflehog"

[[plugin]]
name = "yamllint"
```

<Info>
  The list of auto-enabled plugins provided by the Qlty CLI is a recommended suggestion. You are
  encouraged to add or remove plugins as needed.
</Info>