Быстрый старт

Поставить инструментарий, сгенерировать данные о языке из своего дистрибутива 1С:Элемент и получить первую проверку.

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

Как всё устроено

Движок один, а обратиться к нему можно тремя способами. Редактор держит связь с долгоживущим сервером. Агент зовёт те же операции инструментами MCP. В терминале работает CLI. Читают и пишут все трое одни и те же исходники на диске.

Весь путь: сверху источники установки – Open VSX с расширением, PyPI с движком и elemctl, дистрибутив платформы, отдающий справку с типами движку и debug-адаптер elemctl; ниже редактор с движком читают исходники проекта, а elemctl несёт деплой и отладку на стенд платформы

Дальше на этой странице – как до этого дойти: пакет, данные, язык вывода.

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

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 – его держит агент. Занятые заглушки exe команда не трогает, и при следующем запуске они вызовут уже новый код. Долгоживущие процессы после обновления перезапустите сами. Конкретную версию ставит --version X.Y.Z. Если процесс держит сам пакет, команда называет его по pid и командной строке и отказывает, а прежняя установка остается на месте. --stop-holders сначала снимает серверы: LSP-сервер, рабочий процесс супервизора MCP, веб-сервер. Идущую команду xbsl другой сессии, проверку или создание метаданных, он не трогает, поэтому дождитесь ее конца. --stop-holders=all снимет и ее, и она оборвется без результата. В установке из клона (pip install -e) команда откажет: там обновляет git pull.

Выпуск, опубликованный несколько минут назад, оба списка выпусков PyPI могут еще не показывать. Без --version команда читает оба списка и вдобавок запрашивает страницу следующей версии: ее PyPI отдает сразу после выпуска. Если источники расходятся, команда пишет, что сказал каждый. Установку более старым выпуском она не заменяет никогда.

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

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

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

xbsl extract --dist "<каталог дистрибутива 1С:Элемент>"          # все наборы данных разом
xbsl extract --dist ... --only stdlib,terms                      # подмножество шагов
xbsl extract --dist ... --skip docs                              # docs строит большой индекс

Команда запускает шесть экстракторов в правильном порядке: uischema читает то, что собрал шаг docs. Из клона репозитория те же точки входа называются python tools/extract.py и tools/extract_<шаг>.py. Версию платформы экстракторы определяют сами и кладут данные в xbsl/data/element/<версия>/. Этот каталог перечислен в .gitignore. Если данных нет, линтер и тесты скажут, что их пора сгенерировать. Положить данные в другое место можно ключом --data-dir или переменной окружения XBSL_DATA_DIR – например в закрытый пакет, который их и поставляет, см. Расширение.

Язык вывода

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