XBSL для VS Code

Расширение VS Code для 1С:Элемент: подсветка синтаксиса, линтинг на лету с Quick Fix, визуальный конструктор форм, обозреватель метаданных и навигация по проекту – всё на движке xbsl.

Подсветка синтаксиса и проверка на лету исходников 1С:Элемент (.xbsl) линтером xbsl.

Хотите пощупать всё на игрушечном проекте? Откройте папку demo/ репозитория – крошечное приложение 1С:Элемент с формой и несколькими нарочными находками линтера.

Возможности

• Подсветка синтаксиса .xbsl: ключевые слова (русские и английские формы), объявления, операторы, @-декораторы, числа, комментарии и строки с интерполяцией %имя / ${...}.
• Живые диагностики при наборе (с задержкой) и по сохранению – баланс скобок и блоков, неиспользуемые переменные, типографика, соглашения по стилю и всё остальное, что видит линтер. Подчёркивания несут идентификатор правила (например, code/brackets) и важность.
• Диагностики по всему проекту – сохранение любого .xbsl/.yaml запускает линтер по всей папке воркспейса в фоне, так что проектные правила (code/unknown-type, yaml/unknown-type, уникальность Ид) видны прямо в редакторе по всем файлам. Управляется xbsl.workspaceLint (включено по умолчанию).
• Проверка всего проекта по требованию – команда XBSL: проверить весь проект.
• Переход к определению, поиск всех ссылок и автодополнение по проекту – на индексе, который строит линтер (xbsl --index). См. Навигация и автодополнение.
• Quick Fix для механических находок – лампочка на исправимой диагностике (хвостовые пробелы, типографские символы) применяет ровно ту правку, которую сообщил линтер; source-действие исправить все (source.fixAll.xbsl) чинит весь файл и умеет запускаться по сохранению через editor.codeActionsOnSave. Нужен xbsl >= 0.7.1. См. Quick Fix.
• Деплой на стенд – команда XBSL: деплой на стенд (elemctl) (и кнопка-облачко в заголовке редактора у .xbsl) запускает elemctl deploy терминальной задачей: сборка из исходников → загрузка → применение → перезапуск → проверка фактического применения. См. Деплой на стенд.
• Конструктор формы – панель из трёх областей: дерево структуры слева, данные формы справа, каркас формы под ними. Следует за активным редактором и обновляется при наборе; выделение связано между областями, курсором в yaml и панелью свойств. Палитра компонентов – рядом с деревом метаданных, пока панель открыта. См. Конструктор формы.
• Обозреватель метаданных – отдельная иконка на панели действий: дерево объектов проекта по видам, с поддеревьями (реквизиты, измерения, формы, значения перечисления …), редактируемой панелью свойств, созданием объектов/полей/подсистем и отбором по подсистеме. См. Обозреватель метаданных.
• Документация – отдельный вид на панели действий: справка 1С:Элемент как на сайте – дерево “Содержание” (руководства разработчика и администратора, справочники типов и языка запросов), полнотекстовый поиск и просмотр страницы с картинками и ссылкой на первоисточник. Правый клик на типе или переменной открывает её документацию. См. Документация.

.yaml-описания элементов сохраняют встроенную подсветку YAML.

Требования

Расширение – тонкий клиент над CLI xbsl, проверку оно не встраивает. Нужны:

1. Python 3.10+ и линтер: pip install xbsl. Если линтер не найден, расширение само предложит установку прямо из сообщения об ошибке.
2. Данные языка Элемента – генерируются один раз из вашего дистрибутива 1С:Элемент, см. шаг 1 README линтера. Без них большинство правил не работает; ошибку линтера расширение показывает один раз.

По умолчанию расширение зовёт xbsl из PATH. Перенаправить можно настройками xbsl.linter.command (исполняемый файл) или xbsl.linter.pythonPath (интерпретатор – линтер тогда запускается как <python> -m xbsl).

Новый проект

Команда XBSL: новый проект 1С:Элемент (xbsl.project.new) заводит проект с нуля. Мастер спрашивает четыре вещи – имя проекта, поставщика, вид проекта (приложение или библиотека) и папку, – после чего создаёт заготовку через тот же движок, что и остальные операции с метаданными, и открывает готовый Проект.yaml.

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

Структурный поиск по формам

Команда XBSL: структурный поиск по формам (xbsl.forms.search) ищет не по тексту, а по структуре: задаётся тип компонента и, если нужно, условия по свойствам вида ключ=значение. Расширение собирает формы проекта (включая несохранённые буферы), отдаёт их движку и показывает совпадения списком – выбор перемещает курсор на строку компонента в его yaml.

Поиск нужен, когда вопрос звучит как “где у нас поля ввода с таким-то свойством” – текстовым поиском такое не находится, потому что в yaml свойство и тип компонента лежат на разных строках.

Требует режима LSP: подбор совпадений выполняет движок, а в CLI-режиме он не запущен.

Навигация и автодополнение

Расширение запрашивает у линтера индекс проекта при активации и перестраивает его (с задержкой, не более одного процесса за раз) при сохранении .xbsl/.yaml. Команда индекса пробуется как xbsl index <корень>, затем xbsl --index <корень> как запасной вариант. Если установленный линтер индекс ещё не умеет, навигация тихо выключена – детали в панели вывода XBSL, без всплывающих окон.

Переход к определению (F12 / Ctrl+клик), в .xbsl и .yaml:

• имя объекта проекта (голое или корень точечной цепочки) → его .yaml;
• Объект.ЛокальныйТип → объявление типа; Объект.ТабличнаяЧасть → секция в yaml объекта; Перечисление.Значение → строка значения;
• Модуль.Метод (включая модули менеджера, названные по объекту) и голое имя метода внутри своего модуля → метод;
• Компоненты.Имя → узел компонента в yaml текущей формы; Компоненты.Имя.Метод → метод модуля этой формы;
• в yaml значение Обработчик: Имя → обработчик в парном .xbsl.

Найти все ссылки (Shift+F12 или Перейти к ссылкам / Найти все ссылки в контекстном меню), для методов, объектов и компонентов интерфейса – все использования по тому же индексу:

• метод → его вызовы внутри модуля, Модуль.Метод и Компоненты.Модуль.Метод, а также обработчики Обработчик: Имя в yaml;
• объект → все места, где он корень точечной цепочки;
• компонент → его обращения Компоненты.Имя в модуле формы.

Цепочки глубже, требующие вывода типов, вне охвата – как и для перехода к определению.

Автодополнение (по . и :):

• после Объект. – семейство типов (Ссылка, Объект, …), табличные части, локальные типы и методы модуля менеджера; для перечисления – его значения;
• после Компоненты. – компоненты текущей формы; после Компоненты.X. – методы модуля X;
• в yaml после Тип: – имена объектов проекта (вид объекта показан в подсказке).

Дополнение по типам – только в LSP-режиме (разбор идёт по токенам, поэтому ключевые слова понимаются в обеих формах – пер/var, новый/new):

• внутри Запрос{ ... } после таблицы – её поля: стандартные поля вида, реквизиты и табличные части. Таблицу узнаём и по алиасу: ИЗ Акция КАК А → после А. те же поля;
• после переменной цикла по результату запроса (для С из Результат → С.) – колонки выборки (алиасы ВЫБРАТЬ ... КАК; у поля без алиаса именем становится последний сегмент);
• после переменной известного типа (пер Список = новый Массив<Строка>() → Список.) – члены этого типа; тип берётся из аннотации или из новый, годятся и параметры метода;
• после типа или глобали stdlib (КонтекстДоступа.) – её члены. Свойства и методы показаны раздельно: у метода свой значок, и вставляется он со скобками.

Члены типов stdlib берутся из данных Элемента (каталог --data-dir), остальное – из индекса проекта. Имя в области видимости сильнее одноимённого типа: если объявлена переменная Список, то Список. – это про её тип, а не про компонент Список. Нужен линтер xbsl >= 0.10.0.

Известные пределы – так задумано: вне LSP-режима индекс знает объявления, а не типы (нет дополнения после переменных). Вывода типов для произвольных выражений и цепочек глубже одного уровня нет нигде, переименования нет. В неоднозначном контексте провайдеры молчат, а не гадают.

Quick Fix

Находки, которые линтер чинит механически, несут правку; расширение превращает её в Quick Fix:

• Лампочка на диагностике (Ctrl+.) – Исправить: <правило> – применяет точную правку: снятые хвостовые пробелы, длинное тире → среднее, … → ..., кудрявые кавычки → прямые.

• Source-действие “исправить все” – Исправить все (xbsl) – чинит все исправимые находки файла одной правкой. Запуск по сохранению – добавьте в настройки:

  "editor.codeActionsOnSave": { "source.fixAll.xbsl": "explicit" }

Правки нужны от линтера, который отдаёт их в JSON (xbsl >= 0.7.1). Предлагаются только однозначные правки и только к тому тексту, на котором они были вычислены, – снимок с версией защищает от применения смещения к изменившемуся тексту. Правки всего файла (смешанные переводы строк) остаются за xbsl --fix в командной строке.

Настройки

Правила: уровни и отключение

По группам – в UI настроек. Секция “Группы правил” (наберите xbsl.groups в поиске настроек или пройдите Расширения → XBSL) даёт выпадающий список на каждый тип находок – код, описания yaml, стиль, типографика, пробелы, кодировка, структура, формы, запросы, именование, проект, безопасность: оставить собственные уровни правил группы, показывать все её находки одним уровнем (error / warning / info / hint) либо выключить группу целиком – off не просто прячет находки, а исключает правила из прогона.

По отдельным правилам – с находки. У каждой находки в лампочке (Ctrl+.) есть действие “Настроить правило…”: отключить правило или переопределить его уровень, не уходя со строки; проверка тут же перезапускается. Выбор сохраняется в настройку xbsl.rules – словарь из идентификатора правила (whitespace/trailing) или целой группы (style) в уровень или off. Точный идентификатор сильнее группы, а любой ключ xbsl.rules сильнее выпадающих списков групп. Работает и в CLI-, и в LSP-режиме.

Исключение находки (базлайн)

Отключение правила глушит его везде; иногда же не надо исправлять одну конкретную находку – код правильный намеренно. Для этого у каждой находки в лампочке (Ctrl+.) есть действие “Исключить эту находку (в базлайн): <правило>”: введите причину, и идентичность находки (файл + правило + сообщение) запишется в файл базлайна вместе с ней. Исключается только эта одна находка – правило продолжает проверять остальные файлы и имена (выключить правило целиком – действие “Настроить правило…”). Находка исчезает из редактора, а гейт CI по тому же файлу (xbsl ... --baseline) перестаёт её показывать.

Файл – .xbsllint-baseline в папке воркспейса (создаётся при первом исключении) либо тот, на который указывает xbsl.baseline. Причина хранится рядом с замороженной находкой, и xbsl --write-baseline сохраняет её при перезаписи:

"acme/site/Основное/Полезное.yaml": {
 "naming/number": {
  "Имя 'Полезное' в единственном числе – ...": { "count": 1, "reason": "историческое имя" }
 }
}

В LSP-режиме гашение выполняет сервер – нужен движок 0.15.0 или новее; CLI-режим работает с любым движком, знающим --baseline. В идентичность входит текст сообщения, поэтому базлайн привязан к языку вывода – записывайте и проверяйте под одним xbsl.linter.lang.

LSP-режим (по умолчанию)

Расширение работает через долгоживущий сервер xbsl-lsp, а не запускает CLI на каждое событие: данные языка Элемента и индекс проекта живут в памяти, поэтому диагностика при наборе отвечает за миллисекунды, появляется hover (карточка объекта проекта, метода или компонента формы при наведении) и дополнение по типам. Переход к определению, проектная диагностика по сохранению и quick fix работают как раньше, только быстрее. Нужен линтер с extra [lsp] (pip install "xbsl[lsp]"); сервер ищется как xbsl-lsp в PATH, через xbsl.linter.pythonPath (запуск модулем) или явной командой xbsl.lsp.command.

Если сервера нет, расширение молча продолжает в прежнем CLI-режиме (подробности – в панели вывода XBSL, а фактический режим виден в статус-баре). Выключить сервер совсем – "xbsl.lsp.enabled": false; смена настройки требует перезагрузки окна.

Шаблоны кода

Команда XBSL: шаблоны кода (xbsl.templates.manage) открывает панель управления набором – это аналог диалога Параметры – Шаблоны в 1С:EDT: слева список, справа редактор, кнопки добавить, изменить, удалить, импортировать и выгрузить.

Набор состоит из двух частей. Встроенные шаблоны идут с инструментом, пользовательские лежат в файле .xbsl-templates.json в корне воркспейса – путь меняется настройкой xbsl.templates.file. Пользовательский набор дополняет встроенный, а шаблон с тем же именем замещает встроенный: так правится поведение по умолчанию, ничего не ломая.

Формат файла – тот же, что у выгрузки шаблонов 1С:EDT, поэтому набор переносится между средой и редактором в обе стороны:

• XBSL: импорт шаблонов кода (xbsl.templates.import) – влить выгрузку EDT в свой файл;
• XBSL: экспорт шаблонов кода (xbsl.templates.export) – выгрузить набор в файл того же формата.

Панель ничего не пишет сама: и чтение, и запись идут через xbsl templates – тот же механизм, что у консольной команды. Поэтому набор одинаков в обоих режимах расширения, а из шелла с ним можно работать теми же средствами (xbsl templates list / export / import).

Подстановка шаблонов при наборе работает в режиме LSP. В режиме CLI панель и обмен файлами доступны, а автодополнения по шаблонам нет.

Палитра кода

Команда XBSL: палитра кода (xbsl.choosePalette) перекрашивает синтаксис XBSL одной из популярных палитр: стиль веб-среды 1С:Элемент (красные ключевые слова, синие строки), One Dark, Monokai, Dracula, GitHub Dark – либо возвращает цвета активной темы редактора. Выбор применяется правилами editor.tokenColorCustomizations, адресованными только скоупам *.xbsl, поэтому глобальная тема и другие языки не затрагиваются; расширение управляет только своими правилами (префикс xbsl-palette) и сохраняет ваши собственные настройки.

Конструктор формы

Команда XBSL: конструктор формы (xbsl.previewForm, она же кнопка в заголовке редактора у yaml форм – файлов с КомпонентИнтерфейса) открывает панель формы. Форма зависит от собственных свойств, поэтому её структура и данные правятся там же, где она показана: слева дерево структуры, справа данные, под ними каркас формы; между областями – перетаскиваемые разделители, их положение запоминается.

Панель – на каждую форму. Вторая форма открывается своей вкладкой рядом с первой; у каждой панели своё дерево, выделение и память раскрытия. Панель и её yaml ходят парой: выбор вкладки с одной стороны выводит вперёд другую, а закрытие панели закрывает yaml формы (несохранённый – остаётся). Клавиши работают в самой панели: стрелки по дереву, Alt+Вверх/Alt+Вниз, F2, Delete, Ctrl+C/Ctrl+V и Ctrl+Z/Ctrl+Y.

Структура – дерево слотов и компонентов с иконкой по виду и бейджами линтера. Контекстное меню и клавиши: Alt+Вверх/Alt+Вниз двигают компонент, F2 переименовывает, Delete удаляет, Ctrl+C/Ctrl+V переносят фрагмент yaml, есть оборачивание в контейнер, дублирование, фокус на поддереве и фильтр именованных. Узел перетаскивается на другой узел: контейнер принимает вложением, лист – следом за собой.

Данные – собственные Свойства: компонента и реквизиты объекта-владельца. Двойной клик или перетаскивание записи на узел структуры создаёт компонент ввода с готовым биндингом (Булево –> флажок, иначе поле ввода с Значение: =...).

Каркас формы рисует по yaml вложенные вертикальные/горизонтальные группы, надписи, поля ввода с подписями и =биндингами, кнопки (основная – залита), флажки, таблицы с настоящими колонками, переключаемые вкладки (Страницы), карточки, заглушки картинок и HTML-контейнеров, панель команд формы. Неизвестные и собственные типы компонентов рисуются рамкой с подписью типа и содержимым внутри – ничего не пропадает. В шапке области – масштаб (−/+, колесо над регулятором и Ctrl+колесо над каркасом) и переключатель темы: светлая (вид веб-клиента платформы, по умолчанию), тёмная или тема редактора; выбор запоминается.

Выделение общее для трёх областей. Клик по блоку каркаса и движение курсора в yaml раскрывают свёрнутые группы по пути к узлу, встают на него в структуре и наполняют панель “Свойства”; выбранный узел светится полным цветом выделения независимо от того, где сейчас фокус. Обратный ход тот же: клик по узлу структуры ставит курсор на его yaml, двойной клик переводит туда и фокус, Ctrl+клик по блоку каркаса – переход к его yaml.

Палитра компонентов живёт рядом с деревом метаданных и появляется, пока панель формы открыта. Двойной клик по компоненту палитры вставляет его в выделенный узел структуры. Перетащить из палитры в панель нельзя – платформа не переносит перетаскивание из своего дерева в webview, поэтому вставка сделана кликом.

Панель свойств. Клик по элементу выделяет его и открывает отдельную панель “Свойства” (самостоятельная вкладка – перетащите вниз или в сторону, как удобно) – как в веб-редакторе платформы: перечисления выпадающими списками (Компоновка, выравнивания, интервалы, ширина, вид кнопки), Растягивать* – переключателем Авто / Истина / Ложь, остальное текстом; показывается стандартный набор компонента плюс все свойства из yaml (значения-объекты – только для чтения). Правки применяются к yaml-документу точечными заменами – обычный undo работает; пустое значение / (авто) снимает свойство. Выбор элемента и каждая правка позиционируют yaml-редактор на затронутой строке (не забирая фокус); Ctrl+клик или кнопка Показать в yaml переводят в редактор – удобно ориентироваться в больших формах.

Типизированные редакторы значений. Свойство-цвет открывает нативный пикер и образцы цветов, уже использованных в форме, плюс недавние – клик переиспользует оттенок. У любого однострочного значения есть тумблер литерал/биндинг: нажмите =, чтобы привязать свойство к данным, – в режиме биндинга автокомплит предлагает биндинги, уже встречающиеся в форме, и реквизиты объекта-владельца формы (=Объект.Наименование); кнопка abc возвращает к литералу.

Это каркас, а не рендер платформы: компоновка, вложенность и подписи передаются точно, размеры и стили – приблизительно (явные цвет и размер шрифта надписей применяются).

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

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

Обозреватель метаданных

Отдельная иконка 1С:Элемент на панели действий (Activity Bar) открывает дерево метаданных проекта – по образу конфигуратора платформы, но внутри VS Code.

Экспериментально. Обозреватель метаданных – экспериментальная функция, возможны ошибки и неудобства.

Дерево. Корень – проект (Проект.yaml), серым рядом Поставщик\Имя; правый клик открывает модуль приложения (Проект.xbsl). Ниже – ветка Подсистемы и категории по виду (ВидЭлемента): справочники, документы, регистры сведений/накопления, перечисления, общие модули, HTTP-сервисы, структуры, клиентские события и т.д. – каждая со своей иконкой. Пара Имя.yaml + Имя.xbsl показана одной строкой; форма объекта/списка вложена под свой объект-владелец, формы без владельца – в раздел Общие формы.

Поддеревья объектов. Справочник и документ раскрываются в Реквизиты, Табличные части, Формы; регистр – в Измерения, Ресурсы, Реквизиты; перечисление – в Значения; структура – в Поля; параметры работы клиента – в Параметры; HTTP-сервис – в Шаблоны URL с их методами.

Клики. Объект или поле открывает панель свойств справа (тип поля – комбобокс из примитивов, ссылок <Объект>.Ссылка? и перечислений проекта, значение можно и ввести вручную); общий модуль – свой .xbsl; форма – конструктор. Правый клик добавляет Свойства, открыть описание / модуль / модуль объекта.

Панель свойств (та же, что у конструктора формы). Скалярные свойства правятся на месте: выпадающие списки для ОбластьВидимости / Окружение, переключатель Истина / Ложь, остальное текстом. Ид и ВидЭлемента – только для чтения; коллекции (реквизиты и т.п.) правятся в дереве. Правки точечные (обычный undo работает); сохраните файл (Ctrl+S), чтобы дерево обновилось.

Секция “Все свойства” показывает и то, чего в файле ещё нет, – не только у самого объекта, но и у элемента любой его коллекции: реквизита, измерения, ресурса, поля структуры, реквизита табличной части, значения перечисления, параметра. Класс элемента называет сама метамодель, а где элементы разнотипные – выбирает его по имени: встроенные Код, Наименование и Владелец справочника имеют собственные классы, поэтому и наборы свойств у них свои.

Составные (вложенные) свойства – например ВыравниваниеСодержимогоПоГоризонтали { ... } – показаны, но не редактируются: правьте их прямо в yaml.

Создание объектов. В корне категории – действие “Добавить <класс>” (справочник, документ, перечисление, регистр сведений/накопления, общий модуль, HTTP-сервис, структуру, клиентское событие, фрагмент командного интерфейса, параметры работы клиента, общую форму): спрашивает имя и подсистему-папку, пишет минимальный валидный yaml (свежий Ид; парный .xbsl у модульных видов) и открывает его. Классы показаны, даже когда их в проекте ещё нет. В группах поддерева кнопка “+” добавляет реквизит / измерение / ресурс / значение / параметр / поле; у справочника и документа – “Добавить форму объекта”: движок генерирует форму с наполнением по реквизитам (по выбору – сразу и форму списка с колонками) и регистрирует её в Интерфейс.

Шаблоны и правки yaml считает движок (xbsl 0.16+): те же операции доступны агентам через его MCP-инструменты meta_* и любому редактору через LSP-запросы xbsl/meta* или подкоманды CLI – дерево лишь собирает параметры и применяет присланные изменения (обычный undo работает).

Подсистемы. Ветка Подсистемы перечисляет папки-подсистемы (клик открывает Подсистема.yaml); “Добавить подсистему” создаёт папку с Подсистема.yaml. На корне проекта – “Отбор по подсистеме” (мультивыбор) и “Снять отбор”; активный отбор виден серым рядом с проектом.

Статус git. Строки объектов, форм, подсистем и проекта несут SCM-декорацию файла (цвет и бейдж) как в Проводнике, сохраняя иконку вида.

Удаление. Правый клик по объекту – “Удалить объект” (с подтверждением; удаляет файлы объекта, обратимо через Undo; ссылки не обновляются – оборванные покажет линтер).

Созданный объект – это заготовка в файлах, он не деплоится сам; невалидный всплывёт только при следующем деплое (откат ловит elemctl), рабочие файлы не портит.

Пример: демо-приложение деревом и деплой на 1cmycloud.com

Дерево умеет собрать рабочее приложение с нуля (yaml генерируют те же шаблоны, что и дерево):

1. Открыть папку с файлом проекта – в дереве появится корень-проект.
2. Подсистемы → “+” → Добавить подсистему → Основное.
3. Справочники → “+” → Добавить справочник → Товары (подсистема Основное); так же Категории.
4. Под Товары → Реквизиты → “+” → Добавить реквизит → Цена, Артикул.
5. Перечисления → Добавить перечисление → СтатусТовара; в Значения → ВНаличии, ПодЗаказ.
6. Задеплоить: elemctl deploy --app-id <app> --project-dir <папка проекта> --output <tmp> (создать приложение заранее: elemctl apps ensure <app> --latest-build --wait).

Отчёт деплоя на 1cmycloud.com (ok: true только при ФАКТИЧЕСКОМ применении):

собран архив <проект> 1.0-N.xasm (версия 1.0-N)
сборка загружена, применение запущено, ждём стабилизации приложения...
приложение в статусе Running, проверяем фактическое применение...
проверка пройдена: сборка применена
{
  "uri": "https://<хост>.1cmycloud.com/applications/<app>",
  "status": "Running",
  "applied-version": "1.0-N",
  "applied": true,
  "uri-status": 200,
  "problems": [],
  "ok": true
}

applied: true и ok: true означают, что сборка реально применилась – справочники Товары / Категории и перечисление СтатусТовара, собранные деревом, открываются в стандартном интерфейсе (демо не требует OIDC/входа).

Документация

Отдельный контейнер Документация (1С:Элемент) на панели действий – справка платформы так, как её показывает сайт документации, но собранная из вашего дистрибутива: она совпадает с вашей версией платформы и работает без сети.

Дерево. Курируемое “Содержание”, совпадающее с сайтом: руководства разработчика и администратора, справочник типов (Стд::Коллекции → Массив → …) и язык запросов. Строится из данных сайдбара самого дистрибутива, поэтому структура как на сайте. Клик по узлу открывает страницу.

Поиск. Кнопка поиска в заголовке вида (команда XBSL: поиск по документации) ищет полнотекстово по всему справочнику и руководству; выбор из списка открывает страницу.

Страница. Открывается вкладкой редактора сбоку и не забирает фокус: очищенная статья с кодом (у примеров – кнопка Копировать), таблицами и картинками и ссылкой Первоисточник на ту же страницу на сайте. Разделы страницы вложены в её узел дерева, внутренние ссылки ведут к другим страницам в этой же вкладке, а при открытии страницы дерево “Содержание” на неё позиционируется.

Документация по символу. Правый клик на типе или переменной в .xbsl – XBSL: документация по символу – открывает её страницу. Для типа сразу открывается страница справочника; для метода или неоднозначного имени показывается список кандидатов, ранжированный по приёмнику перед точкой (Задание.Настроить отдаёт предпочтение страницам запланированного задания, а не топику руководства).

Куда ведут остальные входы. Подсказка при наведении на имя в .xbsl показывает описание типа и ссылку Документация; в конструкторе форм у элемента палитры есть действие Открыть документацию (краткое описание видно и в подсказке). Оба открывают страницу в этой же панели – читать про незнакомый компонент не нужно уходить из редактора.

Данные даёт LSP-сервер линтера, поэтому нужен LSP-режим и база документации, собранная из вашего дистрибутива (xbsl >= 0.12.0, см. README линтера). В обычном режиме (CLI) вид сообщает, что документация доступна в LSP-режиме.

Деплой на стенд

Команда XBSL: деплой на стенд (elemctl) (xbsl.deploy, она же кнопка-облачко в заголовке редактора у .xbsl-файлов) запускает elemctl deploy – сборка, загрузка, применение и проверка фактического применения – терминальной задачей, после диалога подтверждения с точной командной строкой. Настройки xbsl.deploy.*, цикл деплоя и конфигурация ELEMENT_* описаны в README расширения XBSL Debug проекта elemctl (Marketplace).

Команды

• XBSL: новый проект 1С:Элемент (xbsl.project.new) – мастер создания проекта (см. выше).
• XBSL: проверить весь проект (xbsl.lintProject) – проверить весь воркспейс.
• XBSL: структурный поиск по формам (xbsl.forms.search) – поиск компонентов по типу и свойствам (см. выше).
• XBSL: перезапустить линтер (xbsl.restartLinter) – сбросить и перепроверить открытые файлы.
• XBSL: палитра кода (xbsl.choosePalette) – выбрать палитру подсветки XBSL (см. выше).
• XBSL: шаблоны кода (xbsl.templates.manage), импорт (xbsl.templates.import) и экспорт (xbsl.templates.export) – набор шаблонов и обмен выгрузкой EDT (см. выше).
• XBSL: деплой на стенд (elemctl) (xbsl.deploy) – развернуть проект на стенде (см. выше).
• XBSL: конструктор формы (xbsl.previewForm) – панель активной yaml-формы (см. выше).
• XBSL: поиск по документации (xbsl.docs.search) и документация по символу (xbsl.docs.showForSymbol) – вид Документация (см. выше).
• Команды обозревателя метаданных (xbsl.metadata.*) вызываются из самого дерева и его контекстных меню: свойства, добавить объект / поле / подсистему, форму объекта, отбор по подсистеме, удалить объект, обновить. См. Обозреватель метаданных.

Как это устроено

Расширение – тонкий клиент движка xbsl: в LSP-режиме по умолчанию все возможности – диагностика, навигация, панель документации и скаффолдинг метаданных – разговаривают с одним долгоживущим сервером xbsl-lsp; без сервера те же проверки и скаффолдинг идут через CLI:

В режиме CLI одну коллекцию диагностик наполняют два источника, разделение – по состоянию буфера:

• Пока вы печатаете (несохранённый буфер) расширение запускает xbsl --stdin --filename <имя> --format json по живому тексту – только пофайловые правила, быстро, с задержкой. Результат замещает диагностики только этого буфера.
• По сохранению любого .xbsl/.yaml расширение запускает в фоне xbsl <папка воркспейса> --format json (с задержкой, не более одного прогона за раз; сохранение во время прогона отменяет устаревший и начинает заново). Результат покрывает и пофайловые, и проектные правила, поэтому замещает диагностики всех файлов папки – кроме буферов, к тому моменту снова несохранённых: за ними остаётся их живая --stdin-картина до следующего сохранения.

Так нет ни дублей, ни потерянных правил: чистый файл всегда показывает полную картину прогона по воркспейсу, редактируемый – мгновенную пофайловую, и каждое сохранение сводит их вместе. Оба прогона говорят на одном JSON-контракте {diagnostics, summary}, который отдаёт и MCP-сервер линтера.

Упавший или превысивший xbsl.workspaceLintTimeout фоновый прогон сообщается только в панель вывода XBSL – без всплывающих окон на каждое сохранение.

Обратная связь и ошибки

Расширение активно развивается, поэтому возможны ошибки и шероховатости – особенно в обозревателе метаданных и конструкторе форм. Если что-то работает не так, пожалуйста, сообщите об этом (по возможности с шагами воспроизведения и версиями расширения/движка из строки состояния) в issues проекта на GitHub:

https://github.com/keyfire/xbsl/issues

VS Code также предлагает Report Issue на странице расширения (по ссылке bugs из манифеста).

Разработка

npm install
npm run compile          # esbuild-бандл -> dist/extension.js
npm run check            # проверка типов tsc
npm test                 # юнит-тесты ядра навигации (чистый Node, без раннера)
npm run package          # сборка .vsix (через @vscode/vsce)

F5 в VS Code запускает Extension Development Host с загруженным расширением.

Лицензия

MIT – см. репозиторий.