Перейти к содержанию

Раздел 11. Дополнительные инструменты

Инструмент «vanessa-sonar» – тонкая настройка анализа файлов

Назначение инструмента:

  • Формирование блока («модулей») исходников с группировкой по подсистемам конфигурации 1С
  • В т.ч. с группировкой по некоторым подсистемами, а не по всем подсистемам

  • Первичное формирование файла анализа «sonar-project.properties» для текущего проекта

«vanessa-sonar» — это консольное приложение, написанное в виде пакета скриптов для языка OneScript.

Установка «vanessa-sonar» осуществляется через пакетный менеджер «opm» из OneScript. Для этого в системе должен быть предварительно уже установлен интерпретатор OneScript с сайта http://www.oscript.io/

Выполняем установку пакета «vanessa-sonar-1.1.0.ospx» через командную строку (с правами Администратора) из каталога, в котором расположен сам пакет:

opm install -f vanessa-sonar-1.1.0.ospx

После установки проверяем, что приложение доступно в командной строке

vanessa-sonar -–help

image-20200812124328139

В версии 1.1.0 доступна одна полезная команда:

  • configure, c – команда, осуществляющая настройку файла «sonar-project.properties» для группировки исходников на сервере SonarQube по подсистемам 1С.

Более подробно ознакомиться с командой и ее аргументами, можно выполнив команду

vanessa-sonar configure –-help

image-20200812124409855

Создание базового файла настроек

Для создания базового конфигурационного файла необходимо выполнить команду:

vanessa-sonar configure –k <ключ проекта> -n <имя проекта> –-org <ключ организации> --src <Путь к исходникам>

image-20200812124435425

Теперь в текущем каталоге появится файл настроек «sonar-project.properties».

Данный конфигурационный файл содержит все требуемые настройки для анализа с помощью плагина «SonarQube 1C (BSL) Plugin».

В большинстве случае не предполагается последующее ручное изменение этого файла.

Дальнейшие действия стандартны, указанный файл помещается в git-репозиторий проекта и уже при анализе анализатор «Sonar-Scanner» извлекает из него требуемые настройки анализа.

Создание файла настроек с группировкой по подсистемам 1C

Для создания расширенного конфигурационного файла необходимо выполнить команду с ключом «--group».

vanessa-sonar configure –k <ключ проекта> -n <имя проекта> –-org <ключ организации> --src <Путь к исходникам> --group

В этом случае код будет разбит на модули согласно списку верхнеуровневых подсистем из конфигурации 1С, находящейся по указанному пути исходников.

На сервере SonarQube фильтрация по модулям проекта будет доступна в группировке «Модуль»

image-20200812124518879

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

Существует дополнительная функциональность - использовать фильтрацию/отбор по нужным подсистемам, например, для анализа только «своих» подсистем без анализа подсистем поставщика основной конфигурации

Указание списка подсистем выполняется через настроечный json-файл

Пример передачи через командную строку:

vanessa-sonar configure –k <ключ проекта> -n <имя проекта> –-org <ключ организации> --src <Путь к исходникам> --group subsystemsConfPath <Путь/sonar.subsystem.json>

Пример json-файла:

{
    "match": [
        "Интеграция",
        "НСИ"
    ]
}

Импорт замечаний от сторонних статических анализаторов

В версии 1.16 нашего плагина появилась замечательная возможность по импорту замечаний от сторонних статических анализаторов, таких, как 1С:АПК («Автоматизированная проверка конфигураций») или 1C:EDT («Enterprise Development Tools») или каких-то других, например, собственных.

Важно, что после импорта подобные «внешние» замечания остаются полностью управляемы. Их статус можно изменить, например, отметить замечание как исправленное или как неактуальное. Можно назначать ответственных за исправление замечаний и т.д.

Для выполнения импорта подобных внешних замечаний необходимо

  • Подготовить файл описания правил от внешнего анализатора
  • Подготовить файл замечаний от внешнего анализатора
  • Настроить сервер SonarQube для автоматической загрузки файла описания правил при загрузке сервера
  • Указать использование соответствующего файла замечаний при анализе исходных кодов

Подготовка файла описания правил от внешнего анализатора

В файле описания правил должно быть описано каждое правило от стороннего анализатора, замечания по которому должно быть показано на сервере SonarQube.

Важно понимать, что ключ правила должен быть уникальным для всех правил на сервере SonarQube.

Поэтому проще всего добавлять уникальный префикс или суффикс по наименованию. Например, «edt_bug» или «acc_func_124».

Файл описания правил должен иметь формат и расширение xml.

В файле должен быть корневой узел «rules» и его потомки «rule».

У узла «rule» могут быть следующие поля:

  • key – ключ правила, по которому будет выполняться связь замечания из файла замечаний с замечанием на сервере SonarQube
  • name – имя правила, которое будет отображаться в описании правила на сервере
  • severity – важность правила. Возможные значения - INFO, MINOR, MAJOR (по умолчанию), CRITICAL, BLOCKER
  • cardinality – возможные значения: SINGLE (по умолчанию) and MULTIPLE (для шаблонных правил)
  • remediationFunctionBaseEffort – время исправления. Например, «5min»
  • status – статус правила. Возможные значения - BETA, READY (по умолчанию), DEPRECATED
  • type – тип правила. Возможные значения - CODE_SMELL (по умолчанию), BUG and VULNERABILITY
  • tag – набор произвольных тегов правила. Несколько тегов можно указать через запятую.
  • description – расширенное описание правила. Можно указать простой набор строк или строки в формате HTML. HTML-описание нужно заключить в рамки «<![CDATA[<» и «]», как в примере ниже.

Пример файла

<?xml version="1.0" encoding="UTF-8"?>
<rules>
    <rule>
        <key>external-system-bug</key>
        <name>Описание правила</name>
        <severity>MAJOR</severity>
        <cardinality>SINGLE</cardinality>
        <remediationFunction>CONSTANT_ISSUE</remediationFunction>
        <remediationFunctionBaseEffort>5min</remediationFunctionBaseEffort>
        <remediationFunctionGapMultiplier/>
        <status>READY</status>
        <type>BUG</type>
        <tag>edt-test-rule</tag>
        <description>
            <![CDATA[<HTML><HEAD>
<META content="text/html; charset=utf-8" http-equiv=Content-Type></HEAD>
<BODY>Тестовое правило-ошибка из стороннего анализатора</BODY></HTML>]]></description>
    </rule>
</rules>

Формат файла совпадает с описанием файла импорта из официальной документации SonarQube по настройке импорта сторонних результатов.

Подготовка файла замечаний от внешнего анализатора

Файл замечаний от сторонних анализаторов должен быть в формате json.

В файле должен быть корневой узел «issues» и массив описаний замечаний.

Каждое замечание должно иметь следующие поля

  • engineId – строка. Ключ стороннего анализатора.
  • ruleId – строка. Ключ правила. Должен совпадать с полем «key» из описания правила.
  • primaryLocation – объект «Размещение»
  • type - строка. Тип замечания. Варианты - BUG, VULNERABILITY, CODE_SMELL
  • severity - строка. Важность. Варианты - BLOCKER, CRITICAL, MAJOR, MINOR, INFO
  • effortMinutes - число, необязательный. Время на исправления. По умолчанию 0
  • secondaryLocations – массив дополнительных размещений. Необязательный.

Поля объекта «Размещение»:

  • message - строка. Текст замечания, который будет показан пользователю
  • filePath - строка. Путь к модулю. Должен быть относительным от корня исходников.
  • textRange – объект «Диапазон текста», Необязательный, используется только для дополнительных размещений

Поля объекта «Диапазон текста»:

  • startLine - число. Нумерация с 1.
  • endLine - число, необязательный. Нумерация с 1.
  • startColumn - число, необязательный. Нумерация с 0.
  • endColumn - число, необязательный. Нумерация с 0.

ВАЖНО: при формировании файла замечаний ключ правила для замечания должен совпадать с ключом правила из файла настройки правил, который подключается на сервере SonarQube.

Пример файла:

{
  "issues": [
    {
      "engineId": "external-system",
      "ruleId": "external-system-bug",
      "type": "BUG",
      "severity": "MAJOR",
      "effortMinutes": 5,
      "secondaryLocations": [],
      "primaryLocation": {
        "message": "ВНЕШНЯЯ ошибка - выявлена проблема в коде!",
        "filePath": "src/cf/Catalogs/Справочник1/Ext/ObjectModule.bsl",
        "textRange": {
          "startLine": 2
        }
      }
    }
  ]
}

Настройка сервера SonarQube для загрузки файла описания правил

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

Список действий:

  1. Файл правил нужно поместить на компьютер, на котором запускается сервер SonarQube.
  2. Далее в веб-интерфейсе сервера открыть настройки администрирования «1C (BSL)»

image-20200812125023354

  1. Затем нужно указать все файлы описания правил в параметре «External rules definitions path». Указывается полный или относительный путь файла на машине, на которой запускается сервер SonarQube.

image-20200812125051413

  1. Сохранить указанный параметр

  2. Перезапустить сервер SonarQube для вступления настроек в силу.

Важно: если по каким-то причинам не удалось загрузить файл внешних правил, автоматически будет загружен внутренний файл описания правил от 1С:АПК.

Если при загрузке сервера SonarQube не удается загрузить внешний файл правил, то в лог сервера пишется следующий текст

External rule definition file not exists - /opt/sonarqube/extensions/wrong-rules.xml
Internal rule definition for 1C:ACC is loading

а если удалось загрузить, то пишется только

External rule definition file is loading - /opt/sonarqube/extensions/ext_rules.xml

И загрузка внутренних правил уже не происходит.

Указание файла замечаний при анализе исходников

После настройки правил на сервере SonarQube можно подключать файлы замечаний от сторонних анализаторов, основанные на указанных правилах.

Для этого нужно задать путь к файлам замечаний при выполнении анализа через sonar-scanner.

Это можно выполнить 3-мя способами:

  1. (рекомендуем) В файле настроек проекта для параметра «sonar.bsl.acc.externalRulesPath» нужно задать пути к файлам замечаний. Например, «edt-validate.json,ext-issues.json»

  2. В настройках своего проекта выберите «Administration – General Settings – 1C (BSL)» и задайте параметр «External result path»

  3. В настройках сервера «Administration – General Settings– 1C (BSL)» нужно задать параметр «External result path»

image-20200812125242542

Можно задавать как путь к одному файлу, так и путь к нескольким файлам, указав их через запятую.

После указания путей к файлам замечаний можно выполнять анализ через «sonar-scaner».

Интеграция «АПК» и SonarQube

Для интеграции «АПК» и «SonarQube» используется описанный выше механизм «Импорт замечаний от сторонних статических анализаторов» с единственным отличием – файл замечаний должен быть в формате «xml», а не «json».

Для подготовки файла правил и получения результатов от 1С:АПК используется поставляемое расширение из состава плагина – это доработка конфигурации АПК, позволяющее сформировать отчет об ошибках для последующего экспорта в «SonarQube», в виде расширения конфигурации 1С. Расширение протестировано на версиях АПК 1.2.2.56, 1.2.1.53 и ниже.

Также в поставке идет файл «acc_rules.xml», находящийся в папке «extresults» архива поставки. Этот файл – описания файлов правил, полученный для версии АПК 1.2.2.

Возможности расширения:

  • Формирование файла правил из АПК для загрузки описания «внешних» правил на сервере SonarQube
  • Предварительно изучите раздел – «Подготовка файла описания правил от внешнего анализатора»

  • Запуск в командном режиме проверки АПК и формирование файла результатов/замечаний в формате xml для передачи анализатору sonar-scaner.

Установка расширения

Расширение подключается к версии АПК штатными средствами 1С:Предприятия - через Предприятие или Конфигуратор.

Установка расширения в режиме 1С:Предприятие

Для установки в режиме Предприятия нужно запустить АПК в управляемом приложении.

Установка расширения в режиме 1С:Конфигуратор

Для установки через Конфигуратор потребуется зайти в Конфигуратор и вызвать меню «Расширения конфигурации».

Далее в открывшемся окне нажать кнопку «Добавить» и согласиться с предложенными системой настройками. Будет добавлена строка в таблицу расширений.

Эту строку необходимо выделить мышью в списке и выбрать в командной панели окна «Расширения конфигурации» подменю «Конфигурация/Загрузить конфигурацию из файла».

Далее необходимо выбрать файл расширения «AccExporter.cfe» и снова согласиться со всеми предупреждениями системы.

Настройка расширения

После этого имя расширения в таблице должно будет измениться на «спИнтеграцияSonarQube». В строке с этим расширением также потребуется снять флажки:

· Безопасный режим

Защита от опасных действий.

image-20200812125456466

Расширение предназначено для формирования файлов (правил и результатов проверки), поэтому возможность формировать файлы на диске (которую запрещает безопасный режим) должна быть включена.

По возникающим проблемам при подключении расширения обращайтесь к документации «1С:Предприятие 8.3».

Формирование файла правил

После установки расширения появляется возможность выгрузки файла правил из базы 1С:АПК.

Также есть возможность указывать собственные настройки правил, отличные от настроек 1С:АПК. Например, среднее время исправления замечаний по правилу, важность, тип правила и т.п.

Для этого выполните следующие действия:

  • Откройте меню «Операции» - «Обработки»

  • Далее в списке найдите и откройте «Подготовка описания правил АПК для интеграции с SonarQube (SilverBulleters,LLC)»

Из-за особенностей использования толстого клиента обычного приложения обработку приходится открывать через меню «Операции».

image-20200812125539184

В открывшейся форме можно выполнить следующее:

  • Указать имя выходного файла правил, который нужно будет установить на сервере SonarQube
  • Не устанавливать отбор по правилам, т.е. выгрузить абсолютно все правила АПК.
  • Или, напротив, выполнить отбор по коллекции выбранных правил/требований

  • Указать файл предыдущих правил с оценкой времени для переноса ранее установленной информации о ручных настройках правил – времени исправления, серьезности и т.п.

Формат файла правила задокументирован в разделе «Подготовка файла описания правил от внешнего анализатора».

После установки необходимых настроек выполните создание файла правил, нажав на кнопку «Создать файл правил из правил АПК».

Далее полученный файл правил нужно перенести и установить на сервере SonarQube, как описано в разделе «Настройка сервера SonarQube для загрузки файла описания правил».

Возможные проблемы:

  • Вопрос: При запуске 1С:АПК на платформе 1С 8.3.10.ХХХ нельзя открыть обработку, находящуюся внутри расширения, через интерфейс толстого клиента обычного приложения.
  • Ответ: Это баг платформы 1С. Используется платформы 8.3.11 и выше для запуска 1С:АПК.

Запуск проверки АПК и формирование файла результатов

После подключения расширения к базе АПК можно запускать конфигурацию АПК с ключом вида:

/C"ключ1=значение1;ключ2=значение2"

Допустимые ключи:

  • NameVerifiableConfiguration - наименование проверяемой конфигурации
  • NameOfResponsible - имя ответственного пользователя
  • PathToVerifiableConfiguration - путь к ИБ проверяемой конфигурации
  • IBUsername - имя пользователя ИБ проверяемой конфигурации
  • IBPassword - пароль пользователя ИБ проверяемой конфигурации
  • PathToFileResult - путь к файлу с отчетом о результатах
  • NameVerificationVariant - имя варианта проверки в АПК
  • Ключи «NameVerifiableConfiguration», «PathToVerifiableConfiguration» и «PathToFileResult» являются обязательными. При этом сама проверяемая конфигурация может не существовать в 1С-базе АПК. Она будет создана автоматически при запуске проверки.

Пример командной строки запуска проверки с помощью «vanessa-runner»

vrunner run --command "PathToVerifiableConfiguration=C:\demo\mybase; NameVerifiableConfiguration=My configs;NameOfResponsible=admin;PathToFileResult=.\acc-reports.xml;NameVerificationVariant=My_configs;IBUsername= Администратор" --ibconnection /Fc:\demo\DemoACC --db-user Администратор --ordinaryapp 1

Импорт результатов проверки в SonarQube

(рекомендуем) В файле настроек анализа «sonar-project.properties» в свойстве «sonar.bsl.acc.resultsPath» нужно указать путь к полученному из АПК xml-отчету с замечаниями.

Пример:

 sonar.bsl.acc.resultsPath=./acc-reports.xml

Или можно это сделать в свойствах проекта на сервере SonarQube и заполнить параметр «1C:ACC result path»

image-20200812125825302

После выполнения одной из данных настроек можно запускать анализ качества кода через «sonar-scaner».

Интеграция результатов EDT и SonarQube

Для решения это задачи нужно воспользоваться инструментом «sonar-edt-result».

«sonar-edt-result» - это конвертер результатов проверки 1C:Enterprise Development Tools (EDT) в формат json для SonarQube.

Назначение

Результаты валидации проекта от EDT конвертируются в json-файл, который можно импортировать с помощью нашего плагина.

Формат выгрузки в json-файл для SonarQube документирован в разделе «Подготовка файла замечаний от внешнего анализатора».

Необходимое ПО

Установка

  1. Скопируйте файл «sonar-edt-result.ospx» из поставки
  2. Выполните команду
opm install -f путь/к/sonar-edt-result.ospx

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

Получение файла валидации из EDT

Выполните команду с необходимыми настройками.

ring edt validate

Документация по команде из официальной справки EDT

Получение json-файла для SonarQube из файла валидации EDT

Выполните команду

sonar-edt-result t ./edt-result.tsv ./edt-validate.json ./src
  • Где «t» или «transform» - команда конвертации

Аргументы команды:

  • ключ edt_result - Путь файла с результатами валидации из EDT в формате tsv/csv. Например, ./edt-result.csv

  • ключ sonarqube_json - Путь файла результата для SonarQube. Например, ./edt-json.json`

  • Этот путь также нужно указать в sonar-project.properties. Пример ниже.
  • ключ sources - Путь проверяемого каталога с исходниками. Например, ./src. Лучше указывать путь относительно корня проекта.
  • этот путь должен совпадать с путями к исходникам из файла sonar-project.properties. Пример ниже.
  • Также важно указывать прямой слеш /.

Все указанные аргументы можно задавать и через одноименные параметры окружения.

В файл sonar-project.properties нужно добавить строку

sonar.externalIssuesReportPaths=./edt-validate.json

с указанием пути импортируемого json-файла.

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

файл sonar-project.properties

sonar.projectKey=my-project
sonar.projectName=My project name
sonar.projectVersion=1.1

sonar.sources=./src
sonar.inclusions=**/*.bsl,**/*.os,**/*.xml
sonar.exclusions=**/*.html
sonar.lang.patterns.xml=**/*.xsd,**/*.xsl

sonar.sourceEncoding=UTF-8

sonar.externalIssuesReportPaths=edt-validate.json

sonar.host.url=http://localhost:9000
sonar.login=admin
sonar.password=admin