Review replication

Репликация разметки по правилам (экспериментальная функциональность)

При использовании разных версий Svace (или иных анализаторов), разных настроек CI/CD и прочих факторах возможны ситуации, когда снимки (snapshots) в рамках одной ветки (branch) могут иметь различные инварианты и разметка автоматически не переносится. Для решения задачи переноса разметки в таких случаях разработана утилита reviewer, которая позволяет применить декларативно описанные правила переноса к существующей разметке. В дальнейшем данная функциональность будет включена в Svacer и доступна в веб интерфейсе.

Описание утилиты

Утилита reviewer предназначена для Svacer версии 10 и выше.

NAME:
   reviewer - Svacer review help tool

USAGE:
   reviewer [global options] command [command options] [arguments...]

COMMANDS:
   syntax     Prints help information about rule syntax
   replicate  Replicate non-empty review to invariants according to rules
   help, h    Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --debug              Enabled debug output (default: false)
   --log-file value     Define log file for output
   --host value         Defines URL to svacer server. Format: http://host:port
   --user value         User login. When using env variable SVACER_AUTH_CREDS the format is SVACER_AUTH_CREDS=<login>:<password> (default: admin) [$SVACER_AUTH_CREDS]
   --password value     User password (default: admin)
   --ldap_server value  Server for LDAP authentication [$SVACER_LDAP_SERVER]
   --token value        Defines access token for svacer server [$SVACER_AUTH_TOKEN]
   --help, -h           show help

Основная команда, это replicate - она позволяет применить декларативные правила к разметке, полученной либо с сервера либо из файла, куда ранее она была выгружена командой svacer markup2 export.

NAME:
   reviewer replicate - Replicate non-empty review to invariants according to rules

USAGE:
   reviewer replicate [command options] <file name> - path to output file with applied rules

OPTIONS:
   --project value  Project name or id
   --branch value   Branch name or id (default: master)
   --file value     Load review from file instead of server. File must be in 'json with new line separator' format. File may be gzipped (must have *.gz extension)
   --rule value     Path to file containing replicate rules
   --html           Produce HTML report showing applied changes.Report wil have name <file name>.html (default: false)
   --verbose        Verbose output of rule applications (default: false)
   --process-all    Process all reviews, even with non-default values (default: false)
   --skip-comments  Skip comments while replicating review information (default: false)
   --skip-status    Skip review status and copy only comments while replicating review information (default: false)
   --help, -h       show help

Шаги применения утилиты

Задача: В проекте myproject на ветке master необходимо перенести существующую разметку по некоторым правилам. Сервер запущен на localhost на порте 8080.

Шаги решения:

• (опционально, но рекомендуется) Выгрузить разметку с ветке в файл использую команду

svacer markup2 --host=http://localhost:8080 --user admin --password admin export --project myproject --branch master  --uncompressed --format json --export-all /tmp/myproject.json

• написать правила переноса разметки в файл /tmp/map.txt (формат будет описан ниже)
• (если разметка была выгружена) применить утилиту reviewer с загрузкой данных из файла (флаг --html создаст дополнительно HTML с информацией об изменениях , имя файла /tmp/out.json.html)

reviewer replicate --file /tmp/myproject.json --rule /tmp/map.txt --html /tmp/out.json

• (без выгрузки разметки) применить утилиту reviewer с загрузкой данных с сервера (флаг --html создаст дополнительно HTML с информацией об изменениях , имя файла /tmp/out.json.html)

reviewer --host=http://localhost:8080 --user admin --password admin replicate --project myproject --branch master --rule /tmp/map.txt --html /tmp/out.json

• просмотреть созданный файл /tmp/out.json.html
• если результат устраивает, то загрузить обновленную разметку в сервер

svacer markup2 --host=http://localhost:8080 --user admin --password admin import --project myproject --branch master /tmp/out.json

Пояснения

Разметка в Svacer привязана к инвариантам. Инвариант это некоторый хэш, формируемый из полей предупреждения. Алгоритм формирования хэша описан здесь: формирование инвариантов. В рамках одного снимка все инварианты всегда уникальны.

Команда markup2 export с флагом --export-all выгружает все инварианты с ветки с информацией о разметке и комментариях.

Алгоритм переноса разметки

Входные данные (разметка), полученная из файла или с сервера разбивается на два вектора source и target. В source включаются все элементы с разметкой отличной от разметки по умолчанию. В target включаются все оставшиеся элементы. Если указана опция --process-all , то в source и target включаются все элементы (данная опция предназначена для случаев, если мы хотим заместить существующую разметку)

Процедура проходит по парам (