Edit markers (command line)

Обзор

Функциональность edit-markers позволяет автоматически обрабатывать маркеры при импорте данных с помощью правил, заданных в JSON-файле. Поддерживаются три типа операций:

skip — пропуск (удаление) маркеров, соответствующих условию
change — изменение полей маркеров
deduplicate — объединение дублирующихся маркеров. У маркеров, подходящих под правило, объединяется трасса и остается только один (случайный) маркер с объединенной трассой, остальные маркеры удаляются.

Все операции происходят на стороне клиента до загрузки данных на сервер. При импорте результатов Svace, а также sarif (без указания флага --upload) изменяется .svacer-dir. Директория .svace-dir остается неизменной. Снимок остается неизменным при импорте.

Использование

Импорт результатов Svace

svacer import --edit-markers <файл_правил.json> [другие опции]

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

Импорт SARIF

svacer sarif2 import --edit-markers <файл_правил.json> [другие опции]

Применяет правила при импорте SARIF-файлов.

Импорт снимка с редактированием

svacer server import --edit-markers <файл_правил.json> [другие опции]

Применяет правила к снимку при импорте. Дополнительно можно сохранить отредактированный снимок:

svacer server import --edit-markers rules.json --save-edited-snapshot edited_snapshot.snap

Формат файла правил

Правила задаются в виде JSON-файла, содержащего массив объектов правил:

 [{
   "action": "тип_действия",
   "rules": "условие_или_список_полей",
   "change": { /* только для action: "change" */ }
 }]

Типы действий

skip — Пропуск маркеров

Удаляет маркеры, соответствующие условию.

{
 "action": "skip",
 "rules": "file == 'test.cpp' and line > 100"
}

change — Изменение маркеров

Изменяет указанные поля маркеров.

 {
 "action": "change",
 "rules": "warnclass == 'UNREACHABLE_CODE'",
 "change": {
   "warnclass": "IGNORED",
   "msg": "Код помечен как недостижимый"
 }}

Доступные поля для изменения: warnclass, msg, lang, tool, file, details, line, mtid, function.

deduplicate — Дедупликация

Объединяет маркеры с одинаковыми значениями указанных полей.

{
 "action": "deduplicate",
 "rules": "file,line,warnclass"
}

Поля для группировки (можно указать от 1 до 8): file, line, function, warnclass, lang, tool, mtid, details.

Доступные поля и операторы

Поля маркеров

В условиях можно использовать следующие поля:

file — путь к файлу (строка)
line — номер строки (число)
function — имя функции (строка)
warnclass — класс предупреждения (строка)
lang — язык программирования (строка)
tool — инструмент анализа (строка)
mtid — ID типа маркера (строка)
msg — сообщение маркера (строка)
details — детали маркера (строка)

Операторы сравнения

==, != — равно, не равно
>, >=, <, <= — сравнение чисел
and, or, &&, || — логические операторы
not, ! — логическое НЕ
in — проверка вхождения в список (например: warnclass in ['ERROR', 'WARNING'])
contains — проверка вхождения подстроки

Функции для работы со строками

icontains(s, substring) — содержит подстроку (без учета регистра)
hasPrefix(s, prefix) — начинается с префикса
hasSuffix(s, suffix) — заканчивается суффиксом
equalsFold(a, b) — сравнение строк без учета регистра
lower(s) — преобразование в нижний регистр
upper(s) — преобразование в верхний регистр
trim(s) — удаление пробелов в начале и конце строки
replace(s, old, new) — замена всех вхождений подстроки
regex(s, pattern) — проверка соответствия регулярному выражению
nregex(s, pattern) — проверка НЕсоответствия регулярному выражению

Примеры

Пропуск тестовых файлов

[
 {
   "action": "skip",
   "rules": "icontains(file, 'test') or icontains(file, 'spec')"
 }
]

Изменение класса предупреждений

[
 {
   "action": "change",
   "rules": "warnclass == 'UNREACHABLE_CODE' and icontains(file, 'generated')",
   "change": {
     "warnclass": "INFO",
     "msg": "Недостижимый код в сгенерированном файле"
   }
 }
]

Удаление дубликатов

[
 {
   "action": "deduplicate",
   "rules": "file,line,warnclass"
 }
]

Комплексный пример

[
 {
   "action": "skip",
   "rules": "file == '.build/src/generated.c'"
 },
 {
   "action": "deduplicate",
   "rules": "file,line,function"
 },
 {
   "action": "change",
   "rules": "warnclass in ['DEBUG', 'TRACE', 'INFO'] and line > 1000",
   "change": {
     "warnclass": "LOW_PRIORITY",
     "msg": "Низкоприоритетное предупреждение в длинном файле"
   }
 },
 {
   "action": "skip",
   "rules": "regex(file, \".*_test\\\\.(c|cpp)$\")"
 }
]

Изменение приоритета для определенных классов

Понижаем приоритет информационных сообщений:

[ 
 {
   "action": "change",
   "rules": "warnclass in ['UNREACHABLE_CODE.ENUM', 'UNREACHABLE_CODE.RET', 'UNUSED_VALUE.PARAM_ASSIGN']",
   "change": {
     "warnclass": "UNREACHABLE_CODE"
   }
 }
]

Обработка сгенерированных файлов

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

[ 
 {
   "action": "skip",
   "rules": "contains(file, 'generated') or contains(file, '.build') or hasPrefix(file, 'vendor/')"
 }
]

Дедупликация с последующей фильтрацией

Сначала объединяем дубликаты, потом удаляем ненужные:

[
 {
   "action": "deduplicate",
   "rules": "file,line,warnclass,function"
 },
 {
   "action": "skip",
   "rules": "icontains(file, 'third_party') or icontains(file, 'external')"
 }
]

Работа с регулярными выражениями

Фильтрация по сложным паттернам путей:

[
 {
   "action": "skip",
   "rules": "regex(file, \"^(tests?|spec|mock|stub)/.*$\") or nregex(file, \"^src/.*\\.(c|cpp|h|hpp)$\")"
 }
]

Дополнительные опции

Сохранение отредактированного снимка

При импорте снимка можно сохранить результат применения правил:

 svacer server import  --edit-markers rules.json --save-edited-snapshot result.snap ...

Обязательно должно быть расширение .snap для сохранения.

Важные замечания

Порядок правил — правила применяются последовательно в порядке их описания в файле
Валидация — при загрузке правил проверяется корректность JSON и соответствие полей
Формат файла — файл правил должен иметь расширение .json
Логирование — результат применения правил выводится в лог (количество обработанных и удаленных маркеров)
Поле line в change — должно быть строкой с неотрицательным числом
Поле warnclass в change — может принимать только русские, английский буквы, цифры, а также специальные символы, которые находятся на цифровой панели клавиатуры (и печатаются через Shift)