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

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

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

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

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

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

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

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

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

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

Тиры

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

Тир 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]"); без него правило молчит.

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

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

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

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

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

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

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

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