Как в GitHub смотреть красивые отчеты об ошибках с помощью SARIF

Вы пользуетесь GitHub, пишете код и делаете прочие веселые штуки. Для повышения качества своей работы и оптимизации своего времени используете статический анализатор. И вот вам приходит идея — а почему бы не смотреть на ошибки, которые выдал анализатор, прямо в GitHub? Да и еще, чтобы это красиво выглядело. Что же делать в этом случае? Ответ очень простой. Ваш выбор – SARIF. О том что это такое, как это настроить, и будет рассказано в данной статье. Приятного чтения.

Что такое SARIF?

SARIF (Static Analysis Results Interchange Format) – это формат обмена результатами статического анализа на основе JSON для вывода инструментов статического анализа. То есть нам достаточно получить отчет анализатора в этом формате, и далее мы можем его использовать в тех продуктах, которые поддерживают данный формат — например, на GitHub или в Visual Studio Code.

Этот формат появился из-за того, что в мире инструментов статического анализа каждый создавал свой собственный выходной формат. Однако, даже если отчёты разных анализаторов представлены в одном и том же формате (например, JSON), структура самих отчетов может кардинально отличаться друг от друга. Поэтому один общий стандарт был лишь вопросом времени.

Данный формат (SARIF) быстро развивается, и его начинают использовать все чаще и чаще. Однако на данный момент у него есть небольшой недостаток. Иногда он меняет свою структуру, и приходится немного корректировать код, чтобы SARIF файл проходил валидацию. Однако это мелочи по сравнению с тем, какую пользу он несёт. В теории, в идеальном мире, достаточно получить отчет в этом формате и далее его можно открыть в любой программе\системе, которая работает с результатами статического анализа. Ну красота же!

Настройка репозитория GitHub

Чтобы GitHub начал анализировать SARIF файлы, сначала необходимо настроить репозиторий. При настройке мы пользовались вот этой инструкцией.

Итак, открываем свой репозиторий и нажимаем на «Security».

Находим по центру «Code scanning alerts» и нажимаем справа на кнопку «Set up code scanning».

Далее нажимаем на «Set up this workflow».

Теперь даем имя для yml файла (например upload-sarif.yml) и пишем следующее содержимое:

name: "Upload SARIF"  # Run workflow each time code is pushed to your repository and on a schedule. # The scheduled workflow runs every at 00:00 on Sunday UTC time. on:   push:   schedule:   - cron: '0 0 * * 0'  jobs:   build:     runs-on: ubuntu-latest     steps:     # This step checks out a copy of your repository.     - name: Checkout repository       uses: actions/checkout@v2     - name: Upload SARIF file       uses: github/codeql-action/upload-sarif@v1       with:         # Path to SARIF file relative to the root of the repository         sarif_file: results.sarif 

Выглядеть это должно следующим образом:

Теперь нажимаем «Start commit», пишем какое-то сообщение (например «Create upload-sarif.yml») и коммитим.

Отлично, мы настроили репозиторий! Можно приступать к получению SARIF файла.

Получение SARIF файла

Как вы поняли, SARIF – унифицированный стандарт, и получить его можно с помощью разных статических анализаторов и инструментов. В этой статье мы будем использовать PVS-Studio и PlogConverter. Обо всем об этом – далее.

Проверяем проект

Чтобы получить SARIF файл, сначала нам необходимо проверить проект с помощью статического анализатора. Поэтому в настроенный выше репозиторий мы добавили небольшой тестовый С++ проект с одним файлом для демонстрации. Ибо что мы будет проверять-то в самом деле? 🙂 Вот содержимое файла:

#include <iostream> void f(unsigned int ch)  {   unsigned int chx = -1;   if (ch >= 0x0fff0)   {     if ( !((ch >= 0x0FF10) &amp;&amp; (ch &lt;= 0x0FF19))         || ((ch >= 0x0FF21) &amp;&amp; (ch &lt;= 0x0FF3A))         || ((ch >= 0x0FF41) &amp;&amp; (ch &lt;= 0x0FF5A)))     {       ch = chx;     }   } } int main() {   std::cout &lt;&lt; "error" &lt;&lt; std::endl; } 

Кстати, синтетический пример с ошибкой имеет реальный прототип, описанный в статье «Как PVS-Studio оказался внимательнее, чем три с половиной программиста«.

Как уже было упомянуто выше, проверка будет осуществляться с помощью статического анализатора PVS-Studio. А именно — с помощью консольной утилиты «PVS-Studio_Cmd.exe». Данная утилита позволяет производить анализ C++, C# MSBuild-проектов на Windows. По умолчанию найти ее можно по пути «C:\Program Files (x86)\PVS-Studio». Подробнее о данной утилите Вы можете почитать здесь.

Если у вас нет лицензии для проверки, то не отчаивайтесь. Кликнув сюда, вы перейдёте на сайт анализатора, где сможете скачать его, а также получить триальную лицензию.

Собственно, приступаем к анализу. Чтобы его произвести достаточно выполнить вот эту команду:

PVS-Studio_Cmd.exe -t "D:\Use_SARIF_Example\BestProjectCpp.sln" \ -o "D:\Use_SARIF_Example\results.plog" -e "D:\Use_SARIF_Example\" 

Рассмотрим строку запуска немного подробнее. Флаг «-t» является обязательным. Он позволяет указать объект для проверки (sln или csproj/vcxproj файл). Флаг «-o» отвечает за путь до файла, в который будут записаны результаты анализа. Флаг «-e» — корневая часть пути, которую PVS-Studio будет использовать при генерации относительных путей в предупреждениях. Нужно это потому, что отчет будет обрабатываться в облаке.

Отлично, теперь нужно преобразовать plog файл в SARIF файл. Для этого воспользуемся утилитой PlogConverter.

Преобразование из Plog в SARIF

Преобразование мы будем выполнять с помощью утилиты PlogConverter, поэтому пару слов о ней. PlogConverter – это утилита с открытым исходным кодом, предназначенная для преобразования отчетов анализатора PVS-Studio из одного формата в другой. Более подробно утилита описана в документации.

Итак, нам необходимо найти PlogConverter.exe на компьютере. Эта утилита устанавливается вместе с PVS-Studio и располагается рядом с «PVS-Studio_Cmd.exe». Переходим туда, открываем консоль и пишем следующую команду:

PlogConverter.exe "D:\Use_SARIF_Example\results.plog" \ -o "D:\Use_SARIF_Example" -t sarif -n results 

Вот и все. Теперь можно заливать этот файл и смотреть результаты анализа.

Проверяем, что все работает

Чтобы проверить, что мы все сделали правильно, быстренько загрузим наш SARIF файл руками и посмотрим результаты анализа. Для этого переходим в репозиторий и нажимаем «Add file -> Upload files».

Далее добавляем SARIF файл и ждем, пока он обработается. Если хочется посмотреть, как там проходит обработка, то необходимо нажать на «Actions» и далее выбрать работающую задачу.

Как только все будет готово, заходим во вкладку «Security». В ней выбираем слева «Code scanning alerts -> PVS-Studio».

Справа у нас и будут сообщения анализатора. Откроем какое-нибудь предупреждение:

Мы видим:

1. Быстрый фильтр по ошибкам;

2. Сообщение об ошибке. Оно же и указывает, где именно в исходном коде находится ошибка;

3. Ссылка на документацию для предупреждения анализатора.

Реальный сценарий использования SARIF в GitHub

Пришло время посмотреть, как это все может работать на практике. Предлагаю рассмотреть сценарий, когда человек скачает репозиторий, выполнит какую-то работу и с помощью описанных выше команд, создаст SARIF файл и зальет изменения в отдельную ветку. В итоге такой сценарий позволит нам смотреть не только, какие файлы изменил пользователь, но и какие ошибки он допустил. Поэтому скачиваем репозиторий и делаем изменения в файле с C++ кодом:

#include <iostream> void f(unsigned int ch)  {   unsigned int chx = -1;   if (ch >= 0x0fff0)   {     if (!((ch >= 0x0FF10) &amp;&amp; (ch &lt;= 0x0FF19))        || ((ch >= 0x0FF21) &amp;&amp; (ch &lt;= 0x0FF3A))        || ((ch >= 0x0FF41) &amp;&amp; (ch &lt;= 0x0FF5A)))     {       ch = chx;     }   } }  int ComputeProjectionMatrixFOV(float fov) {   float yScale = 1.0 / tan((3.141592538 / 180.0) * fov / 2);   return yScale; }  int main() {   std::cout &lt;&lt; "error" &lt;&lt; std::endl; } 

Далее проверяем файл, сохраняем отчет, получаем SARIF файл (заменяя им уже лежащий в скаченном репозитории) и делаем коммит в отдельную ветку. Все, пользователь сделал свое дело. Теперь черед смотреть ошибки.

Заходим в репозиторий. Далее «Security» -> «Code scanning alerts» -> «PVS-Studio» и справа в «Branch» выбираем нужную ветку. Смотрим результаты:

Как вы видите, сообщения об ошибках в ветке хранятся отдельно. Согласитесь, это достаточно удобно. При желании можно, например, создать bat файл, который будет запускать анализатор, конвертировать отчет в SARIF и заменять существующий SARIF файл.

Что можно делать результатами?

Итак, вы остались один на один с отчетом. Что доступно в вашем распоряжении? Первое, на что нужно обратить внимание, — это то, что все ошибки разделены на две группы. Это «Open» и «Closed». «Open» — это активные ошибки, которые мы не обработали. «Closed» – это ошибки, которые мы исправили или пометили как ложные.

Второе — это фильтры по статусам ошибок (закрытые, отрытые и все такое).

Еще есть фильтры по характеристикам ошибок. Например, можно отсортировать по номеру ошибки.

Также GitHub позволяет нам помечать сообщения как «false positive», «used in tests», и мое любимое «won’t fix» :). Чтобы пометить сообщение, необходимо его выбрать (слева от сообщения есть checkbox) и справа вверху нажать на «Dismiss».

Сообщения, которые вы так разметите, не будут попадать в графу открытых ошибок при следующей загрузке SARIF файла.

Если у нас появилась необходимость вернуть сообщения в «Open», то это очень легко сделать. Для этого выбираем «Closed», далее выбираем то, что хотим вернуть, и нажимаем справа «Reopen».

Также обратите внимание, что если загрузить новый лог, то он перезаписывает текущие открытые ошибки. Если ошибки, которые были в «Open», не встретились в новом логе, то они попадают в «Closed». Поэтому рекомендуем использовать SARIF только для анализа всего проекта. Если вам требуется проанализировать только pull request, то для этого у нас есть ряд статей на эту тему. Например, вот эта. Использовать же SARIF для анализа pull request будет не очень удобно.

А работает только для C++?

Конечно же нет, вы вообще не зависите от языка. Все, что вам нужно – это инструмент статического анализа, который сможет проанализировать ваш код и создать SARIF файл. Например, используемый в этой статье PVS-Studio умеет анализировать C++, C#, Java. Поэтому давайте еще попробуем проверить код на C#, потому что это лучший язык в мире один из авторов статьи его любит. Для примера быстренько проделываем все то же самое, о чем говорилось в статье, но уже для C# проекта. Вот содержимое файла, который был проанализирован:

using System; using System.Collections.Generic; using System.Linq;  namespace TestSarif {   class Program   {     static void Main()     {       var result = Formula42(3, 5);     }      static int Formula42(int? coefficientA, int? coefficientB)     {       var data = new List<int>();       if (coefficientA != null)         data.Add(Formula42(coefficientA.Value));       else if (coefficientB != null)         data.Add(Formula42(coefficientA.Value));       return data.SingleOrDefault();     }      static private int Formula42(int coefficient)     {       return coefficient;     }   } } 

Вот результат:

Ну и посмотрим на саму ошибку.

Вывод

Подводя итог, хочется сказать, что SARIF — это удобный формат, который позволяет просматривать результаты анализа. Да и настройка использования SARIF быстрая и простая. Например, в VS Code это вообще делается в пару кликов. Кстати, если вам будет интересно, как это сделать, то напишите об этом в комментариях. Да и вообще, если у вас есть какие-то пожелания по темам статьи, то напишите об этом.

Так что пробуйте и пользуйтесь. Спасибо за внимание.

Если хотите поделиться этой статьей с англоязычной аудиторией, то прошу использовать ссылку на перевод: Nikolay Mironov, Evgeniy Ovsannikov. How to Get Nice Error Reports Using SARIF.