Руководство пользователя XBSL

Полное руководство по инструментарию — установка, флаги CLI, настройка CI, механизм baseline и скаффолдинг метаданных.

Полное руководство по инструментарию. README – короткая обзорная экскурсия; всё, на что он ссылается “подробнее”, живёт здесь. Полный перечень правил – отдельный документ RULES.ru.md.

• Данные о языке
• Подробности установки
• Флаги CLI
• Язык вывода
• Использование в CI
• Правила подробно
• Базлайн: легаси-долг и исключения с причиной
• Скаффолдинг метаданных
• Расширение: свои правила, данные и уровни
• LSP-сервер
• Шаблоны кода
• Поиск по документации
• MCP-сервер
• Веб-интерфейс
• Версии Элемента

Данные о языке

Линтер работает по таблицам языка (двуязычные ключевые слова, операторы), каталогу типов stdlib и метамодели конфигурации (свойства элементов). XBSL реализован на Eclipse Xtext + ANTLR; эти данные извлекаются из вашего дистрибутива 1С:Элемент (грамматика InternalBsl.g, документация и метамодель .xcore) и в репозиторий НЕ включены. Сгенерируйте их локально:

python tools/extract_grammar.py   --dist "<каталог дистрибутива 1С:Элемент>"
python tools/extract_stdlib.py    --dist "<каталог дистрибутива 1С:Элемент>"
python tools/extract_metamodel.py --dist "<каталог дистрибутива 1С:Элемент>"

Скрипты сами определяют версию платформы и кладут данные в xbsl/data/element/<версия>/ (каталог в .gitignore). Без данных линтер и тесты подскажут, что их нужно сгенерировать. Ключ --data-dir (или env XBSL_DATA_DIR) кладёт данные в другое место – например в закрытый пакет, который их и поставляет, см. Расширение.

Экстракторы лежат в репозитории, а не в пакете PyPI – чтобы сгенерировать данные, нужен клон репозитория.

Подробности установки

pip install xbsl              # или из клона репозитория: pip install -e .
xbsl путь/к/исходникам        # или: python -m xbsl путь/к/исходникам
xbsl self-update              # обновиться до последней версии с PyPI

self-update обновляет пакет распаковкой колеса прямо в site-packages – это безопасно, даже когда pip install --upgrade падает с WinError 32 из-за занятых exe (типовой случай: xbsl-lsp.exe держит LSP-сервер VS Code, xbsl-mcp.exe – MCP-сессию агента). Занятые стабы не трогаются и при следующем запуске вызывают уже новый код; долгоживущие процессы после обновления нужно перезапустить. --version X.Y.Z ставит конкретную версию. В editable-установке из клона команда откажет – там обновляет git pull.

Горячие модули (лексер и парсер) могут компилироваться mypyc’ом в C-расширения: XBSL_MYPYC=1 при сборке (нужны mypy и C-компилятор: Windows – MSVC Build Tools, macOS – Xcode CLT, Linux – gcc). Пользователю компилятор не нужен: готовые нативные колёса собирает CI (native-wheels.yml), а без подходящего колеса пакет работает обычным Python – без компилятора и без потери функциональности.

Флаги CLI

--list-rules, --where (корень данных Элемента, источник и версии), --select/--enable/ --ignore (по id правила, группе – части id до / – или букве тира), --fix, --baseline/--write-baseline, --element-version, --data-dir, --lang, --format text|json|codeclimate.

--fix чинит механические находки прямо в файлах – хвостовые пробелы, символы типографики (длинное тире → среднее, … → ..., кудрявые кавычки и ёлочки в комментариях → прямые), смешанные переводы строк (нормализуются к преобладающему стилю) – и отчитывается об оставшемся. Применяются только однозначные правки и только для правил текущего прогона (поэтому --fix --enable typography заодно гасит долг по тире и ёлочкам); всё, что требует суждения, не трогается.

Для интеграции с редактором --stdin --filename ИМЯ проверяет один буфер из stdin (только пофайловые правила); JSON ({diagnostics, summary}) – тот же, что отдаёт MCP-сервер.

xbsl --index ПУТЬ вместо проверки выводит в stdout JSON-индекс проекта – объекты (с табличными частями, локальными типами модулей и семействами членов для автодополнения после точки), объявления методов с аннотациями и именованные компоненты форм; пути POSIX относительно корня, строки 1-based – для перехода к определению и автодополнения в редакторах.

--format codeclimate печатает отчёт GitLab Code Quality (issue Code Climate) с путями относительно текущего каталога – запускайте из корня репозитория и сохраняйте вывод как артефакт codequality.

Язык вывода

Заголовки правил и тексты замечаний – на русском и английском. Язык выбирается так: --lang ru|en > env XBSL_LANG > локаль системы > русский. Имена типов, ключевые слова и прочий XBSL-текст внутри сообщения не переводятся – только формулировки вокруг них. MCP-сервер и веб-панель подчиняются той же настройке (в веб-панели есть ещё переключатель RU/EN на странице).

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

xbsl возвращает ненулевой код только при находке уровня error, поэтому командой можно гейтить пайплайн как есть – предупреждения и info сборку не валят. Единственное условие – данные о языке (см. Данные о языке): сгенерируйте их в джобе (экстракторы лежат в репозитории – чекаутьте его) либо поставьте пакет, который несёт данные через entry point xbsl.data (см. Расширение), – тогда достаточно pip install.

GitHub Actions

lint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with: { python-version: "3.12" }
    - run: pip install xbsl
    # генерация данных из вашего дистрибутива 1С:Элемент (или установите пакет с данными):
    - run: |
        python tools/extract_grammar.py  --dist "$ELEMENT_DIST"
        python tools/extract_stdlib.py   --dist "$ELEMENT_DIST"
        python tools/extract_metamodel.py --dist "$ELEMENT_DIST"
    - run: xbsl acme/          # джоба падает при любой находке уровня error

GitLab CI (виджет Code Quality)

--format codeclimate пишет отчёт Code Climate, который GitLab показывает прямо в merge request. Запускайте из корня репозитория и сохраняйте вывод как отчёт codequality. Код возврата при error-находках остаётся ненулевым, поэтому artifacts.when: always сохраняет отчёт, даже когда джоба гейтит пайплайн (нужен только виджет – добавьте || true):

lint:
  script:
    - pip install xbsl
    - xbsl --format codeclimate acme/ > gl-code-quality-report.json
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json

Правила подробно

Полный перечень всех 87 правил (severity, включённость по умолчанию, область, ссылки на разделы документации платформы) – в RULES.ru.md; в рантайме – xbsl --list-rules. Обзор по тирам – в README; ниже – что именно проверяют глубокие тиры.

Типовые правила тира D покрывают каждую типовую позицию в коде (новый, приведение как, аннотации, сигнатуры) и каждое значение Тип: в yaml (объединения А|Б|?, дженерики, nullable): корень обязан быть известным типом – stdlib, объект проекта, локальный тип модуля или глобальный тип подключённой библиотеки (см. ниже), – а цепочка с корнем-объектом проекта не выходит за семейство порождаемых им типов: производные из документации дистрибутива (Ссылка, Объект, СоздатьОбъект, автоформы…), табличные части и структуры модулей. Квалификация через пространство имён (Справочник.X.Ссылка) дополнительно сверяет вид объекта; значения перечислений проекта проверяются и в коде, и в yaml-биндингах.

Типы подключённых библиотек линтер берёт из их архивов. Проект.yaml объявляет только координаты (Поставщик, Имя, Версия), поэтому имена ищутся в архиве {Поставщик}-{Имя}-{Версия}.xlib – в каталоге описания проекта и выше (до четырёх уровней), то есть там, где архив и лежит при поставке исходников. Известным становится элемент с ОбластьВидимости: Глобально: остальное – внутреннее дело библиотеки. Архива рядом нет – типы библиотеки остаются неизвестными, как и до появления этой поддержки.

Межфайловые правила тира D ловят то, о чём компилятор сообщает поздно или молчит: обработчик из yaml без метода в парном модуле, тип чужой подсистемы без секции Импорт:, динамический список с типом автоформы без реквизита объекта в полях, кросс-компонентный вызов Компоненты.X.Метод() без аннотации видимости, несоответствия окружений (@НаСервере из клиентского обработчика без @ДоступноСКлиента, клиентский модуль в HttpСервисе), зарезервированные имена (Тип/type у поля или параметра, свойство компонента с встроенным именем), методы без единой ссылки и свойства верхнего уровня объектов по метамодели конфигурации. Группа query/ разбирает блоки Запрос{ ... } и сверяет таблицы ИЗ/СОЕДИНЕНИЕ с объектами проекта и их табличными частями; блок с конструкциями вне поддержанного подмножества (временные таблицы, объединения, подзапросы) пропускается целиком, а не угадывается.

Подробные описания групп – query/ (составной тип в В с подзапросом), project/ (свойства проекта), naming/ (стандарт имён, extra [morph]) и style/ (соглашения по написанию кода, договорённость включено/выключено) – в RULES.ru.md.

Базлайн: легаси-долг и исключения с причиной

Чтобы включить правило на коде, который его уже нарушает, и не утонуть в старых находках, текущие находки замораживают в базлайн и спрашивают по правилу только с нового кода:

xbsl acme/app --enable style --write-baseline baseline.json   # заморозить долг один раз
xbsl acme/app --enable style --baseline baseline.json         # всплывает только НОВОЕ

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

Тот же файл хранит и точечные исключения с причиной: значение записи – либо голое количество, либо {"count": N, "reason": "..."}, где причина объясняет, почему код правильный намеренно. Причины записывает действие “Исключить проверку” из лампочки расширения VS Code (или правка руками); --write-baseline сохраняет причины выживших записей при перезаписи. LSP-сервер принимает тот же ключ --baseline ФАЙЛ, поэтому исключённое гаснет и в редакторе. В идентичность входит текст сообщения: записывайте и проверяйте базлайн под одним языком вывода.

Скаффолдинг метаданных

Механику создания метаданных инструмент берёт на себя: UUID, отступы, точечные вставки в yaml, проверки дублей и совместимости секции с видом объекта. Одни и те же операции доступны из CLI (подкоманды, вывод – JSON), из MCP (инструменты meta_* для агентов) и из LSP (кастомные запросы xbsl/meta* – на них работает дерево метаданных расширения VS Code).

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

xbsl new-project . vendor Приложение                      # описание проекта + модуль + подсистема
xbsl new-object <каталог-подсистемы> <вид> <имя>          # вид: Справочник, Документ, Перечисление, ...
xbsl add-field <объект>.yaml <секция> <поле> --type <тип>
xbsl add-form . --name <объект>                           # формы объекта и списка + регистрация
xbsl add-form . --name <объект> --forms list-cards        # форма списка карточками
xbsl new-object <каталог-подсистемы> <вид-http-сервиса> <имя> --routes "GET /, POST /, GET /{id}"
xbsl add-route  <сервис>.yaml "DELETE /{id}"              # шаблон URL + заготовка обработчика
xbsl add-method <модуль>.xbsl <метод> --annotations <аннотация> --after <существующий-метод>
xbsl add-subsystem vendor/Приложение <имя>
xbsl add-dependency . acme CurrencyConverter 2.0          # подключить библиотеку к проекту
xbsl rename-object . <старое-имя> <новое-имя>             # файлы + ссылки по всему проекту
xbsl set-access . --name <объект> --default <способ-доступа>
xbsl object-info . --name <объект>                        # реквизиты, ТЧ, формы, namespace
xbsl project-info .                                       # проекты, подсистемы, объекты по видам

Вид, секция, аннотации, способы доступа и все идентификаторы пишутся на языке разработки проекта – платформа так документирует свой словарь метаданных, и инструмент принимает ровно эти написания, поэтому в примерах выше стоят плейсхолдеры. Какие виды бывают в проекте, покажет xbsl new-object --help.

Формы генерируются с наполнением: поля ввода по реквизитам объекта (включая стандартные Наименование / Номер / Дата и иерархию), колонки динамического списка, таблицы табличных частей, форма отчёта с параметрами; готовая форма регистрируется в секции Интерфейс владельца. Ключ --dry-run печатает изменения (с полными текстами файлов), ничего не записывая – так расширение применяет правки через свой механизм undo.

--forms list-cards собирает форму списка не таблицей, а сеткой карточек: ПроизвольныйСписок с матричной группой в КонтейнерСтрок плюс компонент строки СтрокаСписка<Имя>. На карточку идут заголовок, фото (реквизит ДвоичныйОбъект.Ссылка переключает её на ПроизвольнаяКарточка с изображением над подписью) и ещё до трёх полей, даты – с форматированием; что попало на карточку, а что нет, перечисляют notes. Ширину колонки сетки задаёт --card-min-width (по умолчанию 400, с фото – 250), картинку-заглушку пустого фото – --card-placeholder.

add-dependency подключает библиотеку – раздел Библиотеки файла Проект.yaml (Имя, Поставщик, Версия). Версия – это версия релиза библиотеки: релиз выпускается в панели управления, и версия сборки с суффиксом (1.0-42) отклоняется. Разные версии одной библиотеки в проекте не допускаются, поэтому повторное подключение обновляет версию существующей записи. Что подключено сейчас – в project-info (projects[].libraries). Поставщика, имя, версию и полные имена типов библиотеки даёт разбор её архива: elemctl inspect <файл.xlib>.

set-access точечно правит КонтрольДоступа.Разрешения, зная, что допускает вид объекта: --default задаёт право ПоУмолчанию, --permission Чтение=РазрешеноВсем – отдельное право (в том числе пользовательское от ПравоНаЭлемент), --calc-by заполняет РасчетРазрешенийПо – он обязателен для РазрешенияВычисляютсяДляКаждогоОбъекта. Неизвестный способ, право, которого у вида нет, и построчные разрешения у НаборКонстант отклоняются; обработчики вычисления разрешений остаются за разработчиком (какие нужны – скажут notes). object-info показывает текущие разрешения и права вида, project-info – ПоУмолчанию каждого объекта; нет секции – значит, платформа применяет РазрешеноАдминистраторам.

rename-object переименовывает файлы объекта (вместе с формами и компонентом строки СтрокаСписка<Имя>) и обновляет ссылки контекстно по всему проекту: значения ссылочных ключей yaml (Тип/Таблица/ИсточникДанных/Форма/ТипФормы), биндинги =... и код .xbsl. Реквизиты, компоненты и поля динамических списков, лишь совпадающие со старым именем, не трогаются; строковые литералы (UI-текст) – тоже. Ключи --new-presentation / --old-presentation обновляют Заголовок/Представление объекта и его форм. Ид объекта сохраняется – данные на платформе переживают переименование.

Расширение: свои правила, данные и уровни

Три группы entry points позволяют отдельному пакету дополнить линтер, не форкая его. Это нужно тем, чьи правила или языковые данные нельзя публиковать: их держат в закрытом пакете, который зависит от xbsl.

# pyproject.toml вашего пакета
dependencies = ["xbsl>=0.16"]

[project.entry-points."xbsl.rules"]
мой-проект = "мой_проект.rules"      # импорт модуля выполняет его декораторы @rule

[project.entry-points."xbsl.data"]
мой-проект = "мой_проект:data_root"  # путь либо функция, возвращающая путь

[project.entry-points."xbsl.severity"]
мой-проект = "мой_проект:severity_overrides"   # {id правила: "error"|"warning"|"info"|"off"}

Пакеты, объявившие группы под старым именем (xbsllint.rules/xbsllint.data/xbsllint.severity), продолжают работать: легаси-группы сканируются вслед за новыми.

Словарь уровней (или функция без аргументов, возвращающая его) поднимает или понижает уровень любого правила – встроенного или из плагина – для всех запусков этой установки: проект может считать, например, style/abbreviation-case предупреждением, пока публичный дефолт остаётся info. "off" убирает правило из набора по умолчанию (явный --select/--enable всё равно включает его, с базовым уровнем).

Пакет установлен – и CLI, и MCP-сервер, и веб-панель видят все расширения: без ключей и файлов настройки. Сбой точки расширения роняет запуск, а не печатает предупреждение: линтер, молча потерявший правило, остаётся зелёным в CI и ничего не гарантирует; переопределение с неизвестным id правила или уровнем падает по той же причине. XBSL_NO_PLUGINS=1 игнорирует все внешние пакеты – только встроенные правила, вшитые данные и уровни по умолчанию.

LSP-сервер

xbsl-lsp (extra [lsp]: pip install "xbsl[lsp]") запускает линтер долгоживущим Language Server по stdio: живые пофайловые диагностики при наборе, проектные – по сохранению, переход к определению, автодополнение и hover по резидентному индексу проекта, quick-fix-правки – без платы за старт интерпретатора на каждый вызов. Флаги: --project-root (корень исходников относительно папки воркспейса), --select/--ignore/--enable, --data-dir, --baseline, --templates. Подойдёт любому редактору с LSP (VS Code, Neovim, JetBrains).

Шаблоны кода

Шаблон – это аббревиатура и конструкция за ней: набираете есл, жмёте Ctrl+Space, выбираете если – и получаете готовый оператор с точками ввода, между которыми ходит Tab. Механизм повторяет шаблоны 1С:EDT (Параметры – Шаблоны), включая формат файла выгрузки.

Шаблоны предлагаются до остальных подсказок: конструкция, которую вы набираете, нужнее имени, которое просто начинается так же. Данные Элемента им не нужны, нужен только LSP-сервер (xbsl.lsp.enabled, включён по умолчанию) – в режиме CLI-индекса расширение их не предлагает.

Встроенный набор – 51 шаблон (xbsl/templates_builtin.py): управляющие конструкции, объявления (методы с аннотациями, структуры, перечисления, типы исключений), запросы и прикладные идиомы – обход справочника, движения регистра, обработчик HttpСервиса, разрешения доступа по объектам, события объекта, обработчики формы. Каждый шаблон разбирается тем же парсером, что и линтер (tests/test_templates.py), – вставить некомпилируемый код он не может.

В тексте шаблона живут точки ввода и списки выбора. Переменные записываются синтаксисом шаблонов 1С:EDT (${...}) и именуются на языке разработки проекта:

Собственные шаблоны лежат в .xbsl-templates.json в корне воркспейса (--file или настройка xbsl.templates.file): файл дополняет встроенный набор, одноимённый шаблон замещает встроенный. Хранится только то, что отличается от встроенного набора, – поэтому следующий релиз до вас дойдёт.

xbsl templates list                        # весь набор: встроенные и свои (свои помечены *)
xbsl templates export --output мои.json    # выгрузка (например, чтобы перенести на другую машину)
xbsl templates import выгрузка.json        # влить выгрузку в свой файл

В VS Code то же самое – панель XBSL: шаблоны кода, устроенная как диалог EDT: список с контекстом вызова, описание и текст шаблона, кнопки добавления, правки, удаления, импорта, экспорта и восстановления умолчаний. После сохранения работающий сервер перечитывает набор – следующий Ctrl+Space уже предлагает исправленный шаблон.

Поиск по документации

tools/extract_docs.py извлекает справку Элемента из дистрибутива (.car сервера-с-IDE) в базу docs.sqlite рядом с данными языка: страницы stdlib (тип, его методы, свойства, параметры) с очищенным HTML, полнотекстовый индекс (SQLite FTS5, из стандартной библиотеки) и канонические ссылки на первоисточник (https://1cmycloud.com/docs/help/..., адрес берётся из sitemap.xml дистрибутива). Картинки страниц сохраняются рядом. Справка 1С под копирайтом, поэтому в пакет базу не кладут – её генерируют из своего дистрибутива, как и данные языка.

python tools/extract_docs.py --dist "$ELEMENT_DIST"

Рантайм-API xbsl.docs (search, page, tree, for_symbol, asset) читает docs.sqlite; если базы нет, поиск просто пуст. На нём работают инструменты MCP (ниже) и – в дальнейшем – панель справки в расширении VS Code.

MCP-сервер

Тонкий адаптер над тем же ядром – агент (напр. Claude Code) зовёт проверки как инструменты и получает структурированные диагностики.

pip install -e ".[mcp]"
claude mcp add xbsl -- xbsl-mcp

Инструменты: lint_paths(paths), lint_source(filename, content), list_rules(); поиск по документации – docs_search(query), docs_page(id), docs_symbol(name) (нужна база docs.sqlite, см. выше); type_members(name) – члены stdlib-типа с корнями типов возвратов его методов одним компактным ответом (дешевле страницы доков, когда нужен только список членов); скаффолдинг метаданных – meta_new_project, meta_new_object, meta_add_field, meta_add_route, meta_add_method, meta_add_form, meta_add_subsystem, meta_add_dependency, meta_rename_object (с режимом плана dry_run), meta_set_access, meta_object_info, meta_project_info. Каждый пишущий meta_* применяет изменения и в том же ответе возвращает линт записанных файлов – создание и проверка за один вызов. Ядро и CLI зависимости mcp не требуют – она только в extra [mcp].

Веб-интерфейс

Локальная страница: указать папку проекта – увидеть замечания. Стандартная библиотека (без внешних зависимостей), слушает только 127.0.0.1.

xbsl-web            # затем открыть http://127.0.0.1:8771/

Настройки правил по тирам, выбор версии данных, фильтры по severity/тексту, тёмная/светлая тема; клик по замечанию открывает файл в VS Code (vscode://).

Версии Элемента

Данные версионированы по версии платформы:

xbsl/data/element/
    index.json            # { available: [...], default: "<версия>" }
    <версия>/{language.json, stdlib.json, metamodel.json}

Выбор версии – --element-version / env XBSL_ELEMENT_VERSION / default из индекса; --version показывает доступные. Новая версия – повторный запуск экстракторов с новым --dist.

Сам корень данных ищется по порядку: --data-dir > env XBSL_DATA_DIR > корень из установленной точки расширения xbsl.data > xbsl/data/element внутри пакета.