# Файл конфигурации pvs\-settings\.toml

## Обзор

Анализаторы языков Go, JavaScript и TypeScript, а также плагины PVS\-Studio для [Visual Studio Code](https://pvs-studio.ru/ru/docs/manual/6646/), [WebStorm](https://pvs-studio.ru/ru/docs/manual/7189/) и [GoLand](https://pvs-studio.ru/ru/docs/manual/7190/) используют файл формата [TOML](https://toml.io/en/) для хранения конфигурации\. Конфигурация может быть сохранена как на уровне конкретного пользователя, так и на уровне проекта\. Для описания конфигурации используется [TOML v1\.0\.0](https://toml.io/en/v1.0.0)\.

Файлы конфигурации могут использоваться неявно или через специальный флаг явно передаваться инструментам\.

## Быстрый старт

Путь до файла настроек уровня пользователя:

* На Windows: `%APPDATA%/PVS-Studio LLC/PVS-Studio/pvs-settings.toml`\.
* На Linux и macOS: `$XDG_CONFIG_HOME/PVS-Studio LLC/PVS-Studio/pvs-settings.toml`\.


> \*\*Примечание\\\.\*\* На Linux и macOS при отсутствии переменной окружения \`XDG\_CONFIG\_HOME\` файл настроек располагается по пути \`\~/\.config/PVS\-Studio LLC/PVS\-Studio/pvs\-settings\.toml\`\\\.

Настройки из файла конфигурации применяются автоматически при запуске анализа\.

Минимальный файл конфигурации анализа может выглядеть следующим образом:

```cpp
version = 1

[analyzers.all]

analysis-paths = [ "skip-analysis=*/tests/*" ]
rules = [ "ALL=on" ]

[analyzers.javascript]

analysis-paths.append = [ "skip-analysis=*/third-party/*" ]
rules.override = [ "ALL=off", "OWASP=on" ]
```

В этом примере для всех анализаторов:

* включаются все группы диагностических правил;
* исключаются из анализа файлы, пути которых соответствуют glob\-паттерну `*/tests/*`;
* для JavaScript и TypeScript анализатора дополнительно исключаются из анализа файлы, пути которых соответствуют glob\-паттерну `*/third-party/*`;
* для JavaScript и TypeScript анализатора включается только группа диагностических правил OWASP\.

## Иерархичность конфигураций

Файлы конфигурации предполагают возможность создания иерархий настроек\. Более специфичные настройки перезаписывают более базовые\. Иерархия настроек от общих к специфичным выглядит следующим образом:

1. Настройки уровня пользователя;
1. Настройки проекта;
1. Настройки, переданные через CLI\.

Файл настроек уровня пользователя находится по пути:

* На Windows: `%APPDATA%/PVS-Studio LLC/PVS-Studio/pvs-settings.toml`\. 
* На Linux и macOS: `$XDG_CONFIG_HOME/PVS-Studio LLC/PVS-Studio/pvs-settings.toml`\. 


> \*\*Примечание\\\.\*\* На Linux и macOS при отсутствии переменной окружения \`XDG\_CONFIG\_HOME\` файл настроек располагается по пути \`\~/\.config/PVS\-Studio LLC/PVS\-Studio/pvs\-settings\.toml\`\\\.

Файл настроек проекта находится в корневой директории проекта:

```cpp
project/
├── src/
├── tests/
├── README.md
└── pvs-settings.toml
```

Настройки можно передать напрямую в CLI анализатора\. В этом случае они будут иметь наибольший приоритет и переопределят настройки из файлов конфигураций:

```cpp
pvs-js analyze --analysis-paths skip-analysis=*/test/* \
               --rules ALL=off \
               --rules GA=on \
               /path/to/project
```

## Структура файла

Настройки внутри файла конфигурации делятся на три типа: общие настройки, настройки плагинов \(`[plugins]`\) и настройки анализаторов \(`[analyzers]`\)\.

Настройки плагинов и анализаторов подразделяются на общие \(секции `[plugins.all]` и `[analyzers.all]`\) и специфичные\.

К специфичным относятся следующие настройки:

* Анализаторы:
  * `[analyzers.javascript]`
  * `[analyzers.golang]`
* Плагины:
  * `[plugins.VSCode]`
  * `[plugins.WebStorm]`
  * `[plugins.GoLand]`

Пример структуры файла уровня пользователя:

```cpp
# Общие настройки

version = 1

[analyzers.all]

# Общие настройки для всех анализаторов

rules = [ "ALL=off", "OWASP=on" ]

[analyzers.golang]

# Настройки, специфичные для анализатора Go
rules.append = [ "GA=on" ] 

[analyzers.javascript]

# Настройки, специфичные для анализатора JavaScript and TypeScript
analysis-paths.override = [ "skip-analysis=*/third-party/*" ]

[plugins.VSCode]

# Настройки, специфичные для плагина Visual Studio Code

show-false-alarms = true
show-best-warnings-button = false

[plugins.WebStorm]

# Настройки, специфичные для плагина WebStorm

show-false-alarms = false
show-best-warnings-button = true

[plugins.GoLand]

# Настройки, специфичные для плагина GoLand

show-false-alarms = false
show-best-warnings-button = true
```

Пример структуры файла уровня проекта:

```cpp
# Общие настройки

version = 1

# Преобразуем относительные пути через директорию 'src',
# которая находится в той же директории, что и файл проектных настроек
working-directory = 'src'

# Игнорируем пользовательские настройки для проекта
ignore-user-settings = true

[analyzers.all]

# Общие настройки для всех анализаторов

# Отключаем все правила, а затем включаем группу GA и OWASP
rules.override = [ "ALL=off", "GA=on", "OWASP=on" ]

# Исключаем из анализ директорию 'src/third-party'
analysis-paths = [ "skip-analysis=third-party" ]

[analyzers.golang]

# Настройки, специфичные для анализатора Go

# Дополнительно для анализатора Go отключаем правило V8018,
# все остальные правила из группы GA и OWASP активны
rules.append = [ "V8018=off" ]

[analyzers.javascript]

# Настройки, специфичные для анализатора JavaScript and TypeScript

# Дополнительно для анализатора JavaScript и TypeScript
# отключаем правило V7008, все остальные правила из группы
# GA и OWASP активны
rules.append = [ "V7008=off" ]
```

## Работа с путями и glob\-паттернами

На уровне пользовательской конфигурации каждая настройка, отражающая сущность "путь", должна принимать значение в виде абсолютного пути \(начинается с корневой директории `/`\)\. 

Также путь может быть представлен в виде абсолютного glob\-паттерна \(начинается с корневой директории `/` или с символа подстановки \(`*` или `?`\)\)\.

На уровне проектной конфигурации каждая настройка, отражающая сущность "путь", должна принимать значение в виде относительного пути или любого glob\-паттерна\. Это необходимо для переносимости файла конфигурации между машинами\.

## Настройки типа "массив"

Для некоторых настроек типа "массив" важен порядок передаваемых значений\. Например, если в поле `rules` сначала включить диагностические правила общего назначения, а после выключить все правила, ни одно диагностическое правило не будет включено\.

```cpp
rules = ["GA=on", "ALL=off"]
```

Начиная со специфичных настроек уровня пользователя, все настройки типа "массив" становятся таблицами с двумя возможными значениями:

* `override` — полностью переопределяет более базовые настройки;
* `append` — дополняет новыми значениями более базовые настройки\.

**Пример**

В файле конфигурации уровня пользователя заданы файлы, исключаемые из анализа для всех анализаторов\. Для JavaScript и TypeScript анализатора нужно исключить эти пути и ещё один дополнительный\. Для Go анализатора эти пути, наоборот, должны попадать в анализ, а исключить нужно другие\.

Файл конфигурации в таком случае будет выглядеть так:

```cpp
version = 1

[analyzers.all]

analysis-paths = [
  "skip-analysis=*/excluded/path/*",
  "skip-analysis=*/one/more/*",
]

[analyzers.javascript]

analysis-paths.append = [
  "skip-analysis=*/additional/path*"
]

[analyzers.golang]

analysis-paths.override = [
  "skip-analysis=*/only/this/path/*"
]
```

## Доступные общие настройки

### version 

Определяет схему файла настроек\.

Обязательная настройка\.

Принимает интегральное значение `1`\.

### working\-directory

Позволяет задать иную рабочую директорию, через которую относительные пути будут преобразовываться в абсолютные\. Доступна только на уровне настроек проекта\.

Принимает строку с относительным путём\. Поддерживаются символы текущей директории `.` и родительской директории `..`\.

Значение по умолчанию: `"."`\.

### ignore\-user\-settings

Позволяет игнорировать пользовательские настройки и учитывать только настройки, указанные на уровне проекта\. Доступна только на уровне настроек проекта\.

Значение по умолчанию: `false`\.

## Доступные настройки анализаторов

### analysis\-threads

Задаёт количество потоков для анализа\.

Принимает значения интегрального типа\.

Если задано значение `0`, анализатор будет распараллеливать анализ на все доступные логические ядра\. Если настройка опущена, анализатор сам выберет оптимальное количество потоков для анализа\.

Пример:

```cpp
[analyzers.all]

analysis-threads = 8
```

### rules

Определяет поведение диагностических правил\. 

Представляет собой непустой массив строк формата:

* `Group=on|off` — для настройки групп диагностических правил;
* `Vxxxx=on|off` — для настройки отдельных диагностических правил;
* `Vxxxx-Vyyyy=on|off` — для настройки диапазона диагностических правил\. Значение `xxxx` должно быть меньше `yyyy`\.

Доступные группы для настройки:

* `ALL` — все диагностические правила;
* `GA` — диагностические правила общего назначения;
* `OWASP` — диагностические правила, ищущие отклонения от OWASP ASVS\.

Пример:

```cpp
[analyzers.javascript]

rules.override = [
  "ALL=off", 
  "GA=off", 
  "V7001-V7005=on", 
  "V7008=on"
]
```

При заданной настройке анализаторы неявно добавляют в начало списка включение группы правил общего назначения \(`"GA=on"`\)\.

Значение по умолчанию: `[ "ALL=off", "GA=on" ]`\.

### fails

Определяет поведение предупреждений о проблемах при работе анализатора\.

Представляет собой непустой массив строк формата:

* `ALL=on|off` — для настройки всей группы;
* `Vxxx=on|off` — для настройки отдельных предупреждений;
* `Vxxx-Vyyy=on|off` — для настройки диапазонов предупреждений\. Значение `xxx` должно быть меньше `yyy`\.

Пример:

```cpp
[analyzers.javascript]

fails.override = [
    "ALL=off",
    "V071-V072=on",
    "V074=on"
]
```

При заданной настройке анализаторы неявно добавляют в начало списка включение всех предупреждений о проблемах \(`"ALL=on"`\)\.

Значение по умолчанию: `[ "ALL=on" ]`\.

### analysis\-paths

Определяет поведение анализатора на указанном пути\.

Представляет собой непустой массив строк формата:

* `analyze=path|glob` — включает анализ на указанном значении;
* `skip-analysis=path|glob` — отключает анализ на указанном значении\.

Пример:

```cpp
[analyzers.javascript]

analysis-paths.override = [
  "skip-analysis=*/excluded/path/*",
  "analyze=/path/to/project/excluded/path/file.js"
]
```

При заданной настройке анализаторы неявно добавляют в начало списка включение всех файлов в анализ \(`"analyze=*"`\)\.

Значение по умолчанию: `[ "analyze=*" ]`\.

### source\-tree\-root

Анализаторы могут заменять заданные пользователем префиксы путей на последовательность `|?|` \(source tree root\)\. Это позволяет генерировать переносимые между машинами отчёты анализа\.

Настройка представляет собой таблицу со следующими ключами:

* `path` — использовать заданный путь в виде строки в качестве source tree root;
* `use-project-directory` — использовать родительскую директорию файла настроек проекта как source tree root\. Принимает значения логического типа\. Значение по умолчанию: `false`\.

Настройки `source-tree-root.path` и `source-tree-root.use-project-directory` могут быть заданы одновременно\. В таком случае при выборе заменяемого префикса приоритет будет у последней настройки\.

Пример:

```cpp
[analyzers.javascript]

source-tree-root = { path = "/path/to/projects/js",
                     use-project-directory = true }

[analyzers.golang]

source-tree-root.path = "/path/to/projects/golang"
source-tree-root.use-project-directory = false
```

### file\-analysis\-timeout

Определяет время, через которое будет остановлен анализ единичного файла\. Принимает строки формата `XXhYYmZZs`\.

Пример:

```cpp
[analyzers.javascript]

file-analysis-timeout = "1h10m15s"
```

Значение по умолчанию: `"10m"`\.

### no\-noise

Позволяет отключить генерацию предупреждений низкого уровня достоверности\.

Принимает значения логического типа\.

Значение по умолчанию:** **`false`\.

### security\-related\-issues

Позволяет включить добавление SEC\-меток в поле `sastId` отчёта анализатора\.

SEC\-метки отображают группы срабатываний анализатора согласно классификации критических ошибок из ГОСТ Р 71207—2024\. Подробнее узнать об этом можно [здесь](https://pvs-studio.ru/ru/pvs-studio/gost-71207/)\.

Принимает значения логического типа\.

Значение по умолчанию: `false`\.

### suppress\-files

Определяет пути до файлов подавления срабатываний анализатора\. Подробнее об этой функциональности можно прочитать [здесь](https://pvs-studio.ru/ru/docs/manual/0032/)\.

Доступна только на уровне настроек проекта\.

Представляет собой непустой массив строк, содержащих пути до файлов\.

Пример: 

```cpp
[analyzers.all]

suppress-files = [ "./suppress_base.suppress.json" ]
```

### keep\-intermediate\-files

Позволяет сохранять временные файлы после анализа\.

Принимает значения логического типа\.

Значение по умолчанию: `false`\.

### node\-path

Настройка для JavaScript анализатора\. Определяет путь до NodeJS, с помощью которого будет запущен TypeScript Server\.

Представляет собой строку\.

Значение по умолчанию: `node`\.

## Доступные настройки плагинов

### help\-language

Определяет язык для встроенной документации\.

Принимает строку со значением `"ru"` или `"en"`\.

Доступна только на уровне настроек пользователя\.

Значение по умолчанию: `"en"`\.

### show\-best\-warnings\-button

Определяет отображение кнопки [Best Warnings](https://pvs-studio.ru/ru/docs/manual/6532/) для показа 10 лучших предупреждений из отчёта анализатора\.

Принимает значения логического типа\.

Доступна только на уровне настроек пользователя\.

Значение по умолчанию: `true`\.

### show\-false\-alarms

Определяет отображение предупреждений, помеченных как [ложноположительные](https://pvs-studio.ru/ru/docs/manual/0017/)\.

Принимает значения логического типа\.

Доступна только на уровне настроек пользователя\.

Значение по умолчанию: `false`\.

### save\-file\-after\-false\-alarm\-mark

Позволяет плагину сохранять изменения в файле после вставки [маркера подавления](https://pvs-studio.ru/ru/docs/manual/0017/) в строку\.

Принимает значения логического типа\.

Доступна только на уровне настроек пользователя\.

Значение по умолчанию: `true`\.