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

• Обзор
• Быстрый старт
• Иерархичность конфигураций
• Структура файла
• Работа с путями и glob-паттернами
• Настройки типа "массив"
• Доступные общие настройки
  • version
  • working-directory
  • ignore-user-settings
• Доступные настройки анализаторов
  • analysis-threads
  • rules
  • fails
  • analysis-paths
  • source-tree-root
  • file-analysis-timeout
  • no-noise
  • security-related-issues
  • suppress-files
  • keep-intermediate-files
  • node-path
• Доступные настройки плагинов
  • help-language
  • show-best-warnings-button
  • show-false-alarms
  • save-file-after-false-alarm-mark

Обзор

Анализаторы языков Go, JavaScript и TypeScript, а также плагины PVS-Studio для Visual Studio Code, WebStorm и GoLand используют файл формата TOML для хранения конфигурации. Конфигурация может быть сохранена как на уровне конкретного пользователя, так и на уровне проекта. Для описания конфигурации используется TOML v1.1.0.

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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]

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

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

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

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

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

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 сначала включить диагностические правила общего назначения, а после выключить все правила, ни одно диагностическое правило не будет включено.

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

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

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

Пример

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

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

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, анализатор будет распараллеливать анализ на все доступные логические ядра. Если настройка опущена, анализатор сам выберет оптимальное количество потоков для анализа.

Пример:

[analyzers.all]

analysis-threads = 8

rules

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

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

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

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

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

Пример:

[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.

Пример:

[analyzers.javascript]

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

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

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

analysis-paths

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

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

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

Пример:

[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 могут быть заданы одновременно. В таком случае при выборе заменяемого префикса приоритет будет у последней настройки.

Пример:

[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.

Пример:

[analyzers.javascript]

file-analysis-timeout = "1h10m15s"

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

no-noise

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

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

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

security-related-issues

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

SEC-метки отображают группы срабатываний анализатора согласно классификации критических ошибок из ГОСТ Р 71207—2024. Подробнее узнать об этом можно здесь.

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

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

suppress-files

Определяет пути до файлов подавления срабатываний анализатора. Подробнее об этой функциональности можно прочитать здесь.

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

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

Пример:

[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 для показа 10 лучших предупреждений из отчёта анализатора.

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

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

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

show-false-alarms

Определяет отображение предупреждений, помеченных как ложноположительные.

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

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

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

save-file-after-false-alarm-mark

Позволяет плагину сохранять изменения в файле после вставки маркера подавления в строку.

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

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

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