ISBL Check - утилита для проверки ISBL-кода

Программисты наверняка слышали и использовали такие инструменты, как статические анализаторы кода, например, Resharper, PVS-Studio, FxCop и пр. Было бы неплохо иметь такой инструмент и для ISBL. Также подумали и мы, и на одном из хакатонов уже в далеком 2015 году был реализован прототип статического анализатора ISBL-кода. Он представлял собой набор сценариев на ISBL. Проект с тех пор не стоял на месте, и прототип стал отдельной утилитой. Инструментом пользовались и развивали внутри компании. А сегодня мы представляем его вам

Что это такое?

ISBL Check  – простой статический анализатор ISBL кода. ISBL Check умеет загружать разработку из базы данных, пакета с разработкой (*.ISX), а также из папки с разработкой, созданной утилитой DTU, о которой писали ранее (https://club.directum.ru/post/118056). Можно проверять как отдельные элементы разработки, так и всю разработку сразу.

По итогам проверки утилита покажет найденные ошибки в окне со списком ошибок. Отчет можно экспортировать в CSV-файл.

Ошибки делятся по критичности на:

• Ошибки – критичные дефекты в коде, на которых скорее всего выдаст ошибку интерпретатор ISBL;
• Предупреждения, например, неиспользуемая переменная;
• Информационные сообщения, например, подсказки по возможным оптимизациям и улучшению кода.

На текущий момент реализовано около 20 проверок:

• Проверки на означенность переменных, присваивание переменной самой себе;
• Проверки на неиспользуемые переменные;
• Проверки параметров функции;
• Использование несуществующих строк локализации и справочников;
• Проверка шаблонов строк и аргументов, передаваемых в функции Format(), LoadStringFormat();
• Проверка на показ интерактивных окон в событиях справочника (сохранение/удаление до/после, события на показ и скрытие карточки);
• Различные информационные проверки, как например наличие в коде комментариев TODO и DONE.

Из списка ошибок можно сразу перейти к коду, где подсвечивается место, в котором была найдена ошибка:

У утилиты есть также консольный агент (без GUI), с помощью которого можно запустить проверку и получить результат в виде csv-файла, либо вывести список ошибок на консоль. Агент удобно использовать для регулярной проверки кода на этапе разработки, запуская его назначенным заданием. Агент настраивается через файл конфигурации, где указываются параметры загрузки разработки и способ вывода отчета (прямо на консоль или в csv-файл):

  <agent ruleLibraryPath="Rules">
    <contextProviders>
      <add provider="Package" filePath=""/>
      <add provider="Database" connectionString="…"/>
      <add provider="Folder" folderPath=""/>
    </contextProviders>
    <reportPrinters>
      <reportPrinter printer="Console"/>
      <reportPrinter printer="CSV" filePath="report.csv"/>
    </reportPrinters>
  </agent>

Где можно посмотреть?

Исходный код утилиты опубликован на GitHub, и его можно посмотреть по ссылке: https://github.com/DirectumCompany/IsblCheck.

Готовый билд ISBL Check также можно скачать отсюда https://github.com/DirectumCompany/IsblCheck/releases/tag/v1.1.1

Как это работает?

Анализ кода реализуется через правила. Правило внутри себя реализует проверку одного элемента разработки. На вход правилу передается информация о вычислении в виде объекта документа, отчет, в который правило записывает ошибки, и контекст с разработкой. Правило анализирует переданные isbl-вычисления с помощью грамматики ISBL. Грамматика ISBL написана с использованием библиотеки Antlr. Правило строит по вычислению синтаксическое дерево и анализирует его, выполняя нужные проверки.

Проверка вычислений выполняется в несколько потоков. Для каждого документа прогоняются все подгруженные правила.

Правила размещаются в отдельных сборках и подгружаются как плагины при старте ISBLCheck. На текущий момент есть только одна «встроенная» сборка с правилами - IsblCheck.BaseRules.dll. Но при желании любой разработчик может написать свои правила и распространять их в отдельной сборке - ISBLCheck будет подхватывать их при запуске и использовать при проверке разработки.

Как создать свою сборку с правилами?

Чтобы создать собственную сборку, нужно:

1. Создать в Visual Studio проект типа Class Library.
2. Подключить к проекту общие для правил сборки IsblCheck.Core и Antlr4.Runtime из состава ISBLCheck.
3. Подключить к проекту сборку System.ComponentModel.Composition (фреймворк MEF) для поддержки загрузки сборки в виде плагина.
4. Добавить класс фабрики правил, экспортирующий интерфейс IRuleFactory. Для этого можно просто унаследовать класс от AbstractRuleFactory и пометить тип IRuleFactory для экспорта, например, как сделано здесь.
5. Реализовать собственные правила и зарегистрировать их в фабрике.

После сборки библиотеку нужно разместить в подкаталоге Rules рядом со сборкой IsblCheck.BaseRules.

Как написать собственное правило?

Каждое правило для ISBLCheck представляет собой класс, в котором содержится логика анализа ISBL-кода и выявления в нем ошибок. Найденные ошибки правило накапливает в отчете, который выводится пользователю в конце проверки. Каждое правило реализует интерфейс IRule.

Каждое базовое правило ISBLCheck имеет код. Правила, разрабатываемые сторонними разработчиками, могут иметь произвольный код. Код служит лишь для удобства анализа ошибок ISBL-разработчиком.

Чтобы создать свой класс с правилом, нужно:

1. Добавить новый класс для правила в свой проект.
2. Реализовать интерфейс IRule. Для этого достаточно унаследовать правило от AbstractRule.
3. При необходимости анализа исходного кода документа нужно реализовать обход синтаксического дерева документа.

Типовой код для обхода дерева документа:

var tree = document.GetSyntaxTree();
var walker = new ParseTreeWalker();
var listener = new ExceptionClassNotSpecifiedRuleListener();
walker.Walk(listener, tree);
foreach (var emptyExceptionClassParam in listener.EmptyExceptionClassParams)
{
  report.AddInformation(Code, Resources.ExceptionClassNotSpecified, document,
    emptyExceptionClassParam.GetTextPosition());
}

Здесь ExceptionClassNotSpecifiedRuleListener – специальный класс-слушатель для обхода синтаксического дерева документа. Класс наследуется от IsblBaseListener. В нем и реализуется основная логика по выявлению и накоплению ошибок. Подробности и пример реализации слушателя можно посмотреть в документации к Antlr и в готовых правилах.

Что дальше?

Надеюсь, что этот инструмент поможет повысить качество исходного кода на ISBL. Ведь чем раньше ошибка будет обнаружена, тем дешевле стоит ее исправление. А именно такие ошибки и находит в ISBL-коде наш анализатор.

ISBL Check планируется развивать:

• Реализовывать новые проверки;
• Добавить управление правилами (например, включение/отключение определенных правил для проверки);
• Добавить анализ работы с объектной моделью платформы;
• Добавить поддержку нескольких версий DIRECTUM (сейчас утилита рассчитана на работу с последней выпущенной версией DIRECTUM 5.5, но может и анализировать более старые версии);
• Исправлять ошибки и реализовывать пожелания.

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