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

Инструмент «gitsync» – cинхронизация хранилища 1С с репозиторием git

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

Выгрузка исходного кода из хранилища конфигураций и расширений 1С в GIT в разрезе авторов и коммитов
В дальнейшем исходый код в GIT может использоваться в sonar для привязки замечаний/ошибок к авторам кода, по которому формируются замечания

Подробнее об установке и запуске gitsync см. в репозитории проекта https://github.com/oscript-library/gitsync

Инструмент «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

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

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

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

vanessa-sonar configure –-help

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Указание списка подсистем выполняется через настроечный 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.

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

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

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

Сохранить указанный параметр
Перезапустить сервер 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-мя способами:

(рекомендуем) В файле настроек проекта для параметра «sonar.bsl.acc.externalRulesPath» нужно задать пути к файлам замечаний. Например, «edt-validate.json,ext-issues.json»
В настройках своего проекта выберите «Administration – General Settings – 1C (BSL)» и задайте параметр «External result path»
В настройках сервера «Administration – General Settings– 1C (BSL)» нужно задать параметр «External result path»

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

После указания путей к файлам замечаний можно выполнять анализ через «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». В строке с этим расширением также потребуется снять флажки:

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

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

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

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

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

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

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

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

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

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

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

Указать имя выходного файла правил, который нужно будет установить на сервере 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»

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

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

Для решения это задачи нужно воспользоваться инструментом stebi.

«stebi» - это конвертер результатов проверки 1C:Enterprise Development Tools (EDT) в формат json для SonarQube. Актуальная инструкция находится на странице проекта на GitHub.

Назначение

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

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

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

В файл sonar-project.properties нужно добавить строку с именем файла, полученного в результате работы «stebi»

sonar.externalIssuesReportPaths=./edt-validate.json

Отображение процента покрытия кода тестами в SonarQube

Собрать покрытие кода автоматическими тестами можно с помощью инструмента Coverage41С.

Назначение

Coverage41C собирает список выполненных строк кода конфигурации в клиенте тестирования посредством подключения в качестве отладчика. Собранные замеры накладываются на исходный код проекта и конвертируются в Generic Test Coverage Format для последующей загрузки в SonarQube.

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

Собрать замеры ручного или автоматизированно тестирования в соответствии с инструкцией. В файл sonar-project.properties или в параметры запуска sonar-scanner добавить параметр sonar.coverageReportPaths с именем полученного файла

sonar.coverageReportPaths=./genericCoverage.xml