Качество кода (Code Smells)¶

Модуль Качество кода (техническое название — Code smells) находит в исходном коде признаки проблем дизайна и качества — так называемые «запахи кода»: например, магические числа, мёртвый или закомментированный код, слишком длинные функции, дублированную логику. Это не уязвимости безопасности, а замечания о сопровождаемости: код с такими признаками работает, но его сложнее и дороже развивать. Модуль хранит историю сканирований по репозиторию и позволяет просматривать каждое замечание с переходом к конкретным строкам кода.

Что находит анализ¶

Каждое замечание относится к одной из категорий:

Категория	Что охватывает
Лучшие практики	Нарушения общепринятых практик написания кода
Поддерживаемость кода	Признаки, усложняющие сопровождение: длинные функции, дублированная логика, избыточная связанность
Производительность	Конструкции, способные приводить к неэффективной работе кода

Анализ поддерживает множество языков программирования; для каждого замечания указывается технология, к которой оно относится.

Как запускается анализ¶

Сканирование запускается по требованию: пользователь вручную запускает пайплайн проекта с шагом анализа качества кода. Каждый запуск формирует отдельный отчёт (сканирование) с собственным номером и привязкой к ветке. Результаты появляются в разделе аналитики через несколько минут после завершения пайплайна.

Для подключения шага анализа качества кода в пайплайн необходимо выполнить следующие шаги:

В меню проекта выберите пункт Сборка и его подпункт Редактор конвейера.
На странице Редактор конвейера представлена кнопка Аналитика качества. Она копирует шаблон для анализа в буфер обмена. Шаблон включает в себя фрагмент для анализа качества кода code_smells с вызовом скрипта analyze.sh. Содержимое шаблона можно вставить в конфигурационный файл пайплайна .appsec_code-ci.yml. В секции variables: можно настроить работу скрипта анализа качества кода, указав значения переменных. Шаблон включает в себя их описание.
Результаты выполнения скрипта выводятся в лог пайплайна. Созданные отчёты сохраняются в формате JSON в артефактах выполненного задания в каталоге code_smells_reports.
Результаты появляются в разделе аналитики через несколько минут после завершения пайплайна.

Где смотреть результаты¶

Раздел доступен на уровне проекта:

Проект → боковое меню → Анализ → Качество кода

Список отчётов¶

Таблица всех сканирований по репозиторию содержит следующую информацию:

Колонка	Что показывает
Отчёт	Порядковый номер сканирования в репозитории
Запущено	Время, когда сканирование было запущено
Завершено	Время, когда сканирование завершилось
Замечания	Количество замечаний, найденных в этом сканировании

Над таблицей отображаются:

Ветка, по которой выполнялось сканирование.
От и До - выбранный диапазон дат.
Количество отчётов в выборке.

Список отчётов можно сортировать; по умолчанию отчёты отсортированы по дате создания, новые сверху. Клик по строке (действие Открыть отчёт) открывает страницу деталей.

Если за выбранный период сканирований не было, выводится сообщение Отчётов по аналитике качества пока нет.

Детали отчёта¶

Страница конкретного сканирования содержит сводку — репозиторий, ветка, время запуска и завершения, общее число замечаний, версия анализатора, идентификатор отчёта, ссылка на файл отчёта в формате JSON, просканированные пути, пропущенные правила — и таблицу замечаний:

Колонка	Что показывает
Правило	Идентификатор правила анализа, по которому найдено замечание
Файл	Путь к файлу и диапазон строк. Это ссылка: по клику открывается файл в репозитории с подсвеченным диапазоном строк
Сообщение	Описание проблемы и рекомендация по исправлению
Серьёзность	Критичность замечания (см. ниже)
Категория	Лучшие практики / Поддерживаемость кода / Производительность
Технологии	Языки или технологии, к которым относится замечание
Является ошибкой	Уверенность анализа в том, что замечание — реальная проблема: Высокая / Средняя / Низкая вероятность
Влияние	Степень влияния проблемы на код: Высокая / Средняя / Низкая
Вероятность эксплуатации	Вероятность того, что проблема проявится: Высокая / Средняя / Низкая

Если замечаний в отчёте нет, выводится соответсвующее уведомление.

Уровни критичности¶

Уровень	Что означает
Критическая проблема	Замечание, требующее исправления
Потенциальная проблема	Замечание, которое стоит проверить и при подтверждении исправить
Рекомендация	Информационное замечание, улучшение по желанию

Каждое замечание имеет устойчивый идентификатор, поэтому одно и то же замечание прослеживается между сканированиями — это позволяет отличать новые проблемы от уже известных.

Как читать результаты¶

Начинайте с замечаний уровня Критическая проблема и с высокой вероятностью ошибки — это наиболее достоверные и значимые находки.
Динамика количества замечаний между отчётами по одной ветке показывает, улучшается или деградирует качество кода.
Сканируйте перед слиянием значимых изменений: сравнение отчёта по рабочей ветке с отчётом по основной ветке покажет, какие замечания привнесены именно вашими изменениями.
Замечания категории Поддерживаемость кода редко требуют срочной реакции, но их накопление — сигнал к плановому рефакторингу.

Работа с правилами Semgrep из внешних источников¶

На данный момент для использования нестандартных правил Semgrep (т.е. не встроенных в скрипт по умолчанию) предусмотрен следующий процесс:

Подготовка каталога с правилами.

Необходимо создать директорию для хранения правил. Это можно сделать двумя способами:
- Заранее разместить каталог в репозитории проекта.
- Создать его динамически во время выполнения пайплайна с помощью дополнительных скриптов.
Наполнение каталога правилами.

В созданную директорию нужно поместить файлы с правилами. Источниками могут служить:
- Популярные публичные репозитории с правилами Semgrep, например:
  - trailofbits/semgrep-rules.
  - semgrep/semgrep-rules.
- Собственные правила, разработанные внутри команды.
Способы получения правил из внешних репозиториев:
- Клонирование всего репозитория с правилами.
- Скачивание репозитория в виде архива с последующей распаковкой нужных каталогов.
Запуск сканирования.

На завершающем этапе необходимо передать Semgrep путь к созданному каталогу через переменную CODE_SMELLS_RULES:
```
CODE_SMELLS_RULES: "./path/to/rules/directory"
```