Правила линтера XBSL

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

Полный перечень проверок линтера. Файл дополняется при добавлении правил; актуальный список в рантайме – xbsl --list-rules (или MCP list_rules). Сейчас правил: 191.

Таблица описывает инструментарий в поставке. Установленный плагин может добавить свои правила и переопределить severity и включённость по умолчанию (см. Расширение), поэтому список в рантайме способен отличаться от этого: xbsl --list-rules показывает, что действительно работает в вашем окружении, а XBSL_NO_PLUGINS=1 – набор ниже.

Граница: линтер дополняет компилятор, но не заменяет его

Линтер работает по тексту, AST и модели проекта. Правила знают типы “на первом шаге”: объявленный номинальный тип переменной и его члены, объекты проекта и порождаемые ими типы, значения перечислений, глобальные типы подключённых библиотек (из архива .xlib).

Вывод типа ВЫРАЖЕНИЯ у движка есть – модуль xbsl.typeinfer отвечает про получателя, член, конструктор, приведение и настойчивую операцию, а вывод типов цепочек и локальных переменных питает ховер и автодополнение в редакторе. Проверки на него не опираются: правила судят по объявленным типам – см. ниже про то, чего линтер не делает.

Часть находок поймал бы и компилятор: неизвестный тип, число аргументов, не-исключение в поймать, возврат не по сигнатуре. Здесь ценность линтера не в том, что он видит больше, а в том, что он видит это раньше – за секунды на рабочей машине, до сборки и деплоя, и показывает точное место. Остального же компилятор не проверяет вовсе: соглашения по написанию кода, типографику, структуру проекта (дубли Ид, парность файлов), неиспользуемые переменные, секреты в исходниках.

Чего линтер не делает – всё, что требует полного вывода типов выражений: избыточное приведение, утечку ресурса в общем случае, соответствие ТИПА возвращаемого значения сигнатуре. Два последних стоит различать. Структурное несоответствие возврата (значение в методе-ничто, пустой возврат в типизированном) правило code/return-mismatch ловит, а возврат строки из метода с : Число пропустит – для этого нужно вывести тип выражения. Ресурс же судится единственной формой, где всё сказано самим объявлением: правило code/unclosed-resource прослеживает закрываемое от объявления до перебора в том же методе, а ресурс, ушедший в вызовы или коллекции, остаётся вне досягаемости.

Проверка корректности кода – серверная компиляция при деплое; линтер идёт перед ней и снимает частые ошибки заранее.

Как читать таблицу

• Правило – идентификатор группа/имя. Группа (часть до /) позволяет включать и выключать правила пачкой.
• Уровень – error (сборка и CI должны падать), warning (нарушено соглашение), info (подсказка, обычно выключена).
• Умолч. – ✓ правило входит в набор по умолчанию, – включается явно.
• Область – файл (правило видит один файл) или проект (нужен индекс всего проекта: дубли Ид, неизвестные типы, кросс-модульные вызовы).
• Ссылка в конце описания – раздел документации платформы, стоящий за правилом. В VS Code код такого правила в панели “Проблемы” открывает этот раздел прямо в редакторе.

Тиры

Правила разбиты на тиры A–D по тому, на что они опираются. Тир – это и есть быстрый фильтр для --select/--ignore (наряду с группой и идентификатором): --select A,B гоняет только структуру и текст, --ignore D убирает семантику над stdlib.

Как читать колонки: error · warning · info; ✓ – входит в набор по умолчанию, – включается явно; область – один файл или весь проект.

Тир A – структура и YAML

Файл существует, парсится, у объекта есть уникальный UUID, имя совпадает с файлом.

Тир B – текст и соглашения

Кодировка, переводы строк, пробелы, типографика (тире, кавычки, многоточие), длина строки, секреты в исходниках.

Тир C – структура кода, базовый синтаксис и соглашения по написанию

Баланс блоков и скобок, заголовки циклов и методов, локальные переменные и группа style/ – соглашения из раздела документации “Рекомендации по написанию кода”. Часть правил style/ выключена по умолчанию (накопленный долг, info): включаются --select style для замера.

Тир D – семантика над stdlib, формы и метамодель

Требует индекс проекта и данные платформы: неизвестные типы и объекты, значения перечислений, модель выполнения (клиент/сервер), обработчики форм, свойства и запросы.

Подробнее о группах

Запросы: В с подзапросом по составному типу (правило query/in-subquery-composite)

Стандарт платформы “Использование выражения В с подзапросом для выражений составного типа”: на большинстве СУБД такой вариант реализован неэффективно, и условие пишется через СУЩЕСТВУЕТ. Правило – предупреждение, стандарт обязателен:

ГДЕ Т.Значение В (ВЫБРАТЬ Ф.Значение ИЗ Фильтры КАК Ф)          // предупреждение
ГДЕ СУЩЕСТВУЕТ (ВЫБРАТЬ 1 ИЗ Фильтры КАК Ф ГДЕ Ф.Значение = Т.Значение)   // так

Составным считается тип поля с двумя и более альтернативами в yaml (Строка|Число|?): ? – не тип, а допустимость Неопределено, и Массив<Строка|Число> тоже не составной. Под сомнение ставится только поле, тип которого известен наверняка: Алиас.Поле или Таблица.Поле, где алиас однозначен в пределах блока, а поле нашлось в yaml таблицы; список значений (В (1, 2, &Коды)) стандарта не касается. Правило понимает и английские формы (IN, NOT, SELECT).

Свойства проекта (правила project/)

Четыре правила по стандарту “Заполнение свойств проекта”: Поставщик и Имя – идентификаторы, образованные от представлений (каждое слово с прописной буквы: КабинетСотрудника, НовыеЭлементарныеТехнологии); Представление и ПредставлениеПоставщика заполнены – это официальное название проекта и название компании-разработчика; Версия – три числа A.B.C (семантическое версионирование), а не 1.0.

Имена элементов проекта (правила naming/)

Двенадцать правил по стандарту платформы “Имена элементов проекта” – он обязателен в новом коде, поэтому все они предупреждения. Проверяются описания (.yaml): имя самого элемента и имена его реквизитов, измерений, ресурсов, табличных частей и значений перечисления.

Число имени сверяется с видом элемента: справочники, документы, регистры и табличные части именуются во множественном числе, перечисления и структуры – в единственном (naming/number). Для русского имени это разбор морфологический, а не по окончаниям: Номенклатура единственного числа стандарту не противоречит, а Задачи и Партии без падежа читаются как родительный падеж единственного. Нужен extra [morph] (pip install "xbsl[morph]"); без него русские имена молчат. Английское имя (переведённое дерево) судится по последнему слову суффиксной эвристикой с перечнем неправильных множественных, extra ему не нужен; несчисляемые слова и неоднозначные хвосты остаются нерешёнными.

Остальное: буква ё и подчёркивания в именах, аббревиатура одним словом (Ндс, а не НДС), англоязычный термин оригиналом (Xml, а не Хмл), Вид вместо Тип у перечислений, вид элемента внутри его имени (ОтчетЗависшиеЗадачи), слова-пустышки (Управление, Менеджер), постфикс окружения у общего модуля (ОбменДаннымиКлиентИСервер – окружение задаётся свойством), булев реквизит через отрицание (НетОшибок вместо Успешно), незаполненное Представление и обязательные префиксы отдельных видов (КлючДоступа, ПравоНа, Навигация).

Соглашения по написанию кода (правила style/)

Двадцать восемь правил по документации платформы (“Соглашения по написанию кода”, “Идиомы языка”) и стандарту разработки “Имена переменных и констант”: оформление и переносы выражений, именование, описание типов и сигнатуры, литералы коллекций, интерполяция строк, проверки булевых значений и Неопределено.

Из стандарта имён переменных и констант проверяется доказуемая по токенам часть: абстрактные имена, однобуквенные имена вне лямбд, кириллические и латинские аббревиатуры не одним словом, булевы имена от отрицания, тип-контейнер в имени, числительные в именах констант и тень имён элементов проекта. Остаются на авторе и ревью: избыточные слова в имени, сокращения за пределами регистра аббревиатур, числа вместо уточнения при осмысленной основе (Этап1 против Данные1 различаются только смыслом) и абстрактность имени константы за пределами числительных (роль НАЧАЛЬНЫЙ_ЭТАП против значения ЭТАП_ПРИЕМА_АНКЕТА токенам не видна).

Правила, которым чистый код уже соответствует, включены по умолчанию (warning) – они защищают от регресса. Правила, под которые обычно накоплен долг, идут как info и выключены – их включают, чтобы замерить долг и убирать его:

xbsl путь/к/исходникам --select style     # все соглашения, включая выключенные
xbsl путь/к/исходникам --ignore style     # без них

Блоки Запрос{ ... } (отдельный DSL) и строковые литералы (HTML/CSS/SVG вставок) из этих проверок исключены. Не проверяются и остаются на авторе с ревью: кратность отступа четырём, идиомы коллекций, Строки.Соединить() при массовой конкатенации, идиомы ?. / ?? и выбор вместо цепочки иначе если.

Семантика кода (правила code/)

Самая большая группа – шестьдесят четыре правила, тридцать четыре из них ошибки. Это то, что компилятор отвергнет или что платформа выполнит не так, как читается: неизвестное имя или член типа, число аргументов вызова, окружение (клиентский код в серверном методе и наоборот), обращение к экземпляру через тип, неперехваченное не-исключение, незакрытый ресурс, обход по коллекции при её изменении, а также обходы платформенных ловушек, у которых нет иного признака, кроме формы кода. Часть правил проектные (--stdin их не гоняет): им нужны парный yaml и имена объектов.

Описания элементов (правила yaml/)

Пятьдесят семь правил по описаниям (.yaml): обязательные и уникальные Ид, известные ключи и типы, ссылки на компоненты, обработчики и локализованные строки, требования платформы к типам полей (ссылка и перечисление допускают пустое значение), настройки динамических списков и форм, а также ловушки вёрстки, которые применяются без ошибки, но рисуются не так, как задумано. Шесть правил – info и выключены: они говорят “так работает платформа”, а не “здесь ошибка”.

Соглашения проекта (правила conventions/)

Правила о том, о чём договорился ПРОЕКТ, а не о том, чего требует платформа. В базовом наборе живёт семья двуязычного проекта: conventions/untranslated-visible-literal (включено по умолчанию) сообщает про видимый текст, оставшийся кириллическим литералом там, где то же свойство проект уже ведёт через словарь локализации, а conventions/untranslated-code-literal и conventions/missing-translation (оба выключены) расширяют это на литералы модулей и словарь перевода – обязана ли каждая читаемая человеком строка приходить из словаря, каждый проект решает сам, и базовый набор этого не навязывает.

Группа заодно и точка расширения: надстройка проекта регистрирует под conventions/ свои правила-соглашения (запрет номеров задач в комментариях, внутренних отсылок и подобное) и сама решает их severity и включённость – см. Расширение. Правда рантайма – xbsl --list-rules; таблица выше описывает только базовый набор.

Мелкие группы

• typography/ – типографские символы в прозе и комментариях: длинное тире, символ многоточия, кудрявые кавычки, ёлочки в комментариях, а также буква “ё” в тексте, который читает пользователь;
• whitespace/ – хвостовые пробелы и смешанные переводы строк;
• encoding/ – файл не в UTF-8;
• structure/ – парность Имя.yaml и Имя.xbsl;
• security/ – секрет в исходниках (токен, пароль, ключ);
• form/ – обработчик формы, которого нет в модуле, и обработчик, сигнатура которого противоречит событию компонента (проектные правила);
• query/ – запросы: неизвестная таблица, ЕСТЬNULL, именованный параметр, немедленная пометка удаления и стандарт про В с подзапросом (разобран выше).

Включение и выключение

--select и --ignore принимают идентификатор правила, группу (часть до /, напр. style) или букву тира A/B/C/D. Плагин может переопределить severity правила (группа entry-points xbsl.severity); XBSL_NO_PLUGINS=1 отключает плагины и возвращает встроенные значения из этой таблицы.