Конфигурирование BSL Language Server¶

BSL Language Server предоставляет возможность изменения настроек с помощью конфигурационного файла в формате JSON.

Глобальная и локальная конфигурация¶

BSL Language Server использует двухуровневую систему конфигурации:

Глобальная конфигурация — общие настройки, применяемые ко всем рабочим областям. Содержит параметры language, sendErrors, traceLog, а также capabilities (textDocumentSync.change) и workspaceSymbol (syncFuzzySearch).
Локальная (per-workspace) конфигурация — индивидуальные настройки для каждой рабочей области, включая диагностики, codeLens, inlayHint и другие параметры. Каждая рабочая область может иметь собственный конфигурационный файл.

Стратегия поиска конфигурационного файла¶

Глобальная конфигурация¶

При запуске BSL Language Server ищет глобальный конфигурационный файл в следующем порядке:

Файл, указанный в ключе -c (--configuration), если он передан при запуске.
Файл .bsl-language-server.json в текущем рабочем каталоге (CWD).
Файл .bsl-language-server.json в домашнем каталоге пользователя (%HOMEPATH% / $HOME).

Используется первый найденный файл. Если ни один из файлов не найден, применяются настройки по умолчанию.

Локальная конфигурация (per-workspace)¶

Для каждой рабочей области BSL Language Server ищет файл .bsl-language-server.json в корневом каталоге рабочей области. Если файл найден, его настройки применяются к этой рабочей области; в противном случае используются настройки по умолчанию (дополненные глобальной конфигурацией).

Отслеживание изменений¶

BSL Language Server автоматически отслеживает изменения конфигурационных файлов:

Изменение глобального файла приводит к обновлению глобальных параметров (language, sendErrors, traceLog, capabilities, workspaceSymbol).
Изменение файла в рабочей области приводит к обновлению настроек только этой рабочей области, включая пересчёт диагностик.
При добавлении рабочей области автоматически регистрируется наблюдатель за её конфигурационным файлом.
При удалении рабочей области наблюдатель снимается с регистрации.

Описание настроек¶

Наименование	Тип	Описание
`language`	`Строка`	Этот параметр устанавливает язык отображения диагностированных замечаний. На данный момент поддерживаются два языка: `ru` - для русского языка (используется по умолчанию) `en` - для английского языка
`codeLens`	`JSON-Объект`	Содержит настройки отображения `линз` в продвинутых кода/IDE (например Visual Studio Code), в которых выводится различная информация над блоком кода.
⤷ `parameters`	`JSON-Объект`	Коллекция настроек линз. Элементами коллекции являются json-объекты следующей структуры: ключ объекта - строка, являющаяся идентификатором линзы значение объекта - может принимать либо булево значение, и тогда интерпретируется как отключение линзы (`false`) или ее включение с параметрами по умолчанию (`true`), либо значение типа `json-объект`, представляющего собой набор настроек линзы.
⤷ `cognitiveComplexity`	`Булево` или `JSON-Объект`	Включает отображение значения когнитивной сложности метода над его определением. По умолчанию настройка установлена в `true`. Доступные параметры линзы: `complexityThreshold` - порог, после которого линза начинает срабатывать. Значение параметра по умолчанию - `-1`.
⤷ `cyclomaticComplexity`	`Булево` или `JSON-Объект`	Включает отображение значения цикломатической сложности метода. По умолчанию настройка установлена в `true`. Доступные параметры линзы: `complexityThreshold` - порог, после которого линза начинает срабатывать. Значение параметра по умолчанию - `-1`.
⤷ `injectionPoint`	`Булево` или `JSON-Объект`	Включает линзу навигации к производителю желудя над точками внедрения `&Пластилин` (OneScript, DI-фреймворк «ОСень»). По умолчанию настройка установлена в `true`.
⤷ `beanUsages`	`Булево` или `JSON-Объект`	Включает линзу с количеством точек внедрения и навигацией к ним над производителями желудей — конструктором компонентного желудя и методами `&Завязь` (OneScript, DI-фреймворк «ОСень»). По умолчанию настройка установлена в `true`.
⤷ `testRunner`	`JSON-Объект`	Настройки тестового фреймворка, используемые линзами запуска тестов (`Запустить тест`, `Запустить все тесты`, `Отладить тест`).
⤷ `testSources`	`Массив` `Строка`	Каталоги с исходными файлами тестов. По умолчанию `["tests"]`.
⤷ `annotations`	`Массив` `Строка`	Имена аннотаций, маркирующих тестовые методы. По умолчанию `["Тест", "Test"]`.
⤷ `executable`	`Строка`	Путь/имя исполняемого файла тест-раннера (Linux и macOS). По умолчанию `1testrunner`.
⤷ `executableWin`	`Строка`	Путь/имя исполняемого файла тест-раннера (Windows). По умолчанию `1testrunner.bat`.
⤷ `getTestsByTestRunner`	`Булево`	Получать имена тестовых методов через исполняемый файл тест-раннера. Если `false`, методы ищутся внутренним парсером по аннотации `&Тест`. По умолчанию `true`.
⤷ `getTestsArguments`	`Строка`	Аргументы тест-раннера для получения списка тестов. `%s` заменяется на путь к текущему файлу. По умолчанию `-show %s`.
⤷ `getTestsResultPattern`	`Строка`	Регулярное выражение для разбора вывода тест-раннера и извлечения имён методов. По умолчанию `^[^<]Имя\sтеста\s<([^>]+)>.`.
⤷ `runTestArguments`	`Строка`	Аргументы для запуска одного теста. Первый `%s` — путь к файлу, второй `%s` — имя тестового метода. По умолчанию `-run %s %s`.
⤷ `debugTestArguments`	`Строка`	Аргументы для отладки одного теста. По умолчанию не заполнено.
⤷ `runAllTestsArguments`	`Строка`	Аргументы для запуска всех тестов файла. `%s` заменяется на путь к текущему файлу. По умолчанию `-run %s`.
`diagnostics`	`JSON-Объект`	Содержит настройки диагностик
⤷ `computeTrigger`	`Строка`	С помощью этого параметра можно указать событие, при котором будет вызвана процедура анализа кода для диагностирования замечаний. Возможные значения: `onType` - при редактировании файла (онлайн) на больших файлах может ЗНАЧИТЕЛЬНО замедлять редактирование `onSave` - при сохранении файла (используется по умолчанию) * `never` - анализ выполняться не будет
⤷ `ordinaryAppSupport`	`Булево`	Поддержка обычного клиента. Диагностики будут требовать учитывать особенности обычного приложения. Возможные значения: `true` - конфигурация разрабатывается с поддержкой обычного клиента (установлен по умолчанию) `false` - игнорировать предупреждения связанные с особенностями обычного клиента
⤷ `skipSupport`	`Строка`	Этим параметром настраивается режим пропуска файлов (т.е. файлы не анализируются на предмет наличия замечаний) конфигурации 1С, находящихся "на поддержке" конфигурации поставщика. Возможные значения: `withSupport` - пропускаются все модули, находящиеся "на поддержке" (все виды "замков") `withSupportLocked` - пропускаются только модули, находящиеся "на поддержке" с запретом изменений ("желтый закрытый замок") `never` - режим поддержки не анализируется и модули не пропускаются (установлен по умолчанию)*
⤷ `mode`	`Строка`	Настройка для управления режимом учета настроек диагностик. Возможные варианты: `OFF` - Все диагностики считаются выключенными, вне зависимости от их настроек `ON` - Все диагностики включенные по умолчанию считаются включенными, остальные - в зависимости от личных настроек `EXCEPT` - Все диагностистики, кроме указанных, считаются включенными `ONLY` - Только указанные диагностики считаются включенными * `ALL` - Все диагностики считаются включенными
⤷ `parameters`	`JSON-Объект`	Параметр представляет собой коллекцию настроек диагностик. Элементами коллекции являются json-объекты следующей структуры: ключ объекта - строка, являющаяся ключом диагностики значение объекта - может принимать либо булево значение, и тогда интерпретируется как отключение диагностики (`false`) или ее включение с параметрами по умолчанию (`true`), либо значение типа `json-объект`, представляющего собой набор настроек диагностики. Ключ, включена ли по умолчанию, а также описание возможных параметров и примеры для конфигурационного файла представлены на странице с описанием каждой диагностики.
⤷ `minimumLSPDiagnosticLevel`	`Строка`	Этот параметр позволяет задать минимальный уровень серьезности LSP диагностик для запуска. Диагностики с уровнем серьезности ниже указанного не будут запускаться. Возможные значения: `Error` - ошибка `Warning` - предупреждение `Information` - информация `Hint` - подсказка По умолчанию параметр не задан и запускаются все диагностики согласно другим настройкам.
⤷ `overrideMinimumLSPDiagnosticLevel`	`Строка`	Этот параметр позволяет задать минимальный уровень серьезности для LSP диагностик. Если уровень диагностики ниже указанного, он будет повышен до указанного. Возможные значения: `Error` - ошибка `Warning` - предупреждение `Information` - информация `Hint` - подсказка По умолчанию параметр не задан и уровни диагностик используются согласно их определению.
⤷ `metadata`	`JSON-Объект`	Параметр представляет собой коллекцию переопределений метаданных диагностик. Элементами коллекции являются json-объекты следующей структуры: ключ объекта - строка, являющаяся ключом диагностики значение объекта - json-объект с переопределяемыми параметрами диагностики. Можно переопределить: `type`, `severity`, `scope`, `modules`, `minutesToFix`, `activatedByDefault`, `compatibilityMode`, `tags`, `canLocateOnProject`, `extraMinForComplexity`, `lspSeverity`. Значения из конфигурационного файла накладываются поверх заданных в исходном коде. Параметр `lspSeverity` позволяет явно задать LSP-уровень серьезности (`Error`, `Warning`, `Information`, `Hint`), если не указан - рассчитывается автоматически.
⤷ `subsystemsFilter`	`JSON-Объект`	Фильтр по подсистемам конфигурации
⤷ `analyzeOnStart`	`Булево`	Запустить анализ всего проекта при запуске сервера. Если включено, после построения контекста на клиента будет отправлена информация о диагностиках во всех файлах проекта.
⤷ `ignoredAuthors`	`Массив` `Строка`	Список email-адресов авторов, строки кода которых исключаются из анализа на основе данных `git blame`. Если список пуст (по умолчанию), фильтрация по авторству не выполняется.
⤷ `include`	`Массив` `Строка`	Список имен подсистем по объектам которых выполняется анализ, включая подчиненные подсистемы
⤷ `exclude`	`Массив` `Строка`	Список имен подсистем исключенных из анализа, включая подчиненные подсистемы
`documentLink`	`JSON-Объект`	Содержит настройки ссылок на документацию
⤷ `showDiagnosticDescription`	`Булево`	Показывать дополнительные ссылки на документацию по диагностикам. По умолчанию параметр выключен (установлен в `false`)
`inlayHint`	`JSON-Объект`	Содержит настройки отображения `inlay hints` в продвинутых редакторах кода/IDE (например Visual Studio Code), в которых выводится различная информация прямо в строке с кодом.
⤷ `parameters`	`JSON-Объект`	Коллекция настроек inlay hints. Элементами коллекции являются json-объекты следующей структуры: ключ объекта - строка, являющаяся идентификатором inlay hint значение объекта - может принимать либо булево значение, и тогда интерпретируется как отключение inlay hint (`false`) или их включение с параметрами по умолчанию (`true`), либо значение типа `json-объект`, представляющего собой набор настроек inlay hint.
⤷ `cognitiveComplexity`	`Булево` или `JSON-Объект`	Включает отображение значения когнитивной сложности метода в виде inlay hints. По умолчанию настройка установлена в `true`.
⤷ `cyclomaticComplexity`	`Булево` или `JSON-Объект`	Включает отображение значения цикломатической сложности метода в виде inlay hints. По умолчанию настройка установлена в `true`.
⤷ `methodCall`	`Булево` или `JSON-Объект`	Включает отображение параметров вызываемого метода (как методов конфигурации/библиотеки, так и платформенных) в виде inlay hints. По умолчанию настройка установлена в `true`. Доступные параметры: `showParametersWithTheSameName` - отображать параметры с именами, содержащимися в передаваемом значении. Значение параметра по умолчанию - `false`. `showDefaultValues` - отображать значения по умолчанию для непереданных параметров. Значение параметра по умолчанию - `true`.
⤷ `sourceDefinedMethodCall`	`Булево` или `JSON-Объект`	Устарело, используйте `methodCall` (единая настройка для методов конфигурации/библиотеки и платформенных методов). Ключ сохранён для совместимости со старыми конфигурационными файлами. Доступные параметры те же, что у `methodCall`.
⤷ `variableType`	`Булево` или `JSON-Объект`	Включает отображение выведенного типа переменных в присваиваниях в виде inlay hints. По умолчанию настройка установлена в `true`.
`capabilities`	`JSON-Объект`	Настройки возможностей сервера LSP, которые он сообщает клиенту. Позволяет переопределить значения по умолчанию, например, режим синхронизации документов.
⤷ `textDocumentSync`	`JSON-Объект`	Настройки синхронизации текстовых документов.
⤷ `change`	`Строка`	Стратегия синхронизации, передаваемая клиенту. Поддерживаются значения `Incremental` (по умолчанию), `Full`, `None`. Чтобы новое значение вступило в силу, перезапустите BSL Language Server, иначе клиент не получит обновлённые возможности.
`workspaceSymbol`	`JSON-Объект`	Настройки поиска символов рабочей области (`workspace/symbol`).
⤷ `syncFuzzySearch`	`Булево`	Включает синхронный блокирующий fuzzy-поиск (по подстроке/подпоследовательности), дописываемый в ответ, для клиентов, не поддерживающих потоковую выдачу частичных результатов. Возможные значения: `true`, `false` (по умолчанию). Используйте `true` для клиентов без потоковой выдачи частичных результатов (VS Code на данный момент её не поддерживает). В потоковом режиме fuzzy-хвост досылается всегда, независимо от этой настройки.
`useDevSite`	`Булево`	При включении настройки формирующиеся ссылки на документацию будут вести на develop-версию сайта. По умолчанию параметр выключен (установлен в `false`)
`siteRoot`	`Строка`	Путь к корню сайта с документацией. По умолчанию параметр имеет значение `"https://1c-syntax.github.io/bsl-language-server"`
`traceLog`	`Строка`	Для логирования всех запросов (входящих и исходящих) между BSL Language Server и Language Client из используемого редактора/IDE, в этом параметре можно указать путь к файлу лога. Путь можно указывать как абсолютный, так и относительный (от корня анализируемого проекта), по умолчанию значение не заполнено. ВНИМАНИЕ При запуске BSL Language Server перезаписывает указанный файл Скорость взаимодействия между клиентом и сервером ЗНАЧИТЕЛЬНО ЗАМЕДЛЯЕТСЯ
`configurationRoot`	`Строка`	Данный параметр предназначен для указания корневого каталога, в котором находятся файлы конфигурации 1С в каталоге проекта. Может быть полезен в случае нахождения нескольких каталогов конфигураций в одном каталоге проекта либо при сложной структуре каталога проекта. По умолчанию параметр не заполнен и `BSL Language Server` самостоятельно определяет расположение корневого каталога конфигурации
`sendErrors`	`Строка`	Режим отправки сообщений об ошибках разработчикам BSL Language Server. Подробнее - на странице Мониторинг и отправка ошибок. Возможные значения: `ask` - спрашивать разрешение при каждой ошибке (установлен по умолчанию). `send` - всегда отправлять сообщения об ошибках. * `never` - никогда не отправлять сообщения об ошибках.
`references`	`JSON-Объект`	Содержит настройки построения индекса ссылок
⤷ `commonModuleAccessors`	`Массив` `Строка`	Список паттернов "Модуль.Метод" для методов, возвращающих ссылку на общий модуль (например, `ОбщегоНазначения.ОбщийМодуль("ИмяМодуля")`). Поддерживается как формат с указанием модуля (`ОбщегоНазначения.ОбщийМодуль`), так и локальный вызов (`ОбщийМодуль`). По умолчанию включает стандартные варианты из БСП: `ОбщийМодуль`, `CommonModule`, `ОбщегоНазначения.ОбщийМодуль`, `ОбщегоНазначенияКлиент.ОбщийМодуль`, `ОбщегоНазначенияСервер.ОбщийМодуль`, `ОбщегоНазначенияКлиентСервер.ОбщийМодуль`, `ОбщегоНазначенияПовтИсп.ОбщийМодуль` и их английские эквиваленты.
`formatting`	`JSON-Объект`	Содержит настройки форматирования кода.
⤷ `useUpperCaseForOrNotAndKeywords`	`Булево`	Регистр ключевых слов `И`/`ИЛИ`/`НЕ` (`And`/`Or`/`Not`) при форматировании. Возможные значения: `true` - верхний регистр (`ИЛИ`, `НЕ`, `И`) (установлен по умолчанию) `false` - CamelCase (`Или`, `Не`, `И`)
⤷ `useKeywordsFormatting`	`Булево`	Приводить ключевые слова к каноническому виду при форматировании. По умолчанию `true`.
⤷ `useOnTypeFormatting`	`Булево`	Включить форматирование по нажатию символа-триггера (`textDocument/onTypeFormatting`). Триггеры — `Enter` и `;`. По умолчанию `true`.
`semanticTokens`	`JSON-Объект`	Содержит настройки семантических токенов.
⤷ `strTemplateMethods`	`Массив` `Строка`	Список паттернов "Модуль.Метод" для функций-шаблонизаторов строк, аналогичных `СтрШаблон`/`StrTemplate`. Строки внутри вызовов этих функций подсвечиваются с выделением плейсхолдеров (`%1`, `%2` и т.д.). Поддерживается формат с указанием модуля и локальный вызов. По умолчанию: `ПодставитьПараметрыВСтроку`, `SubstituteParametersToString`, `СтроковыеФункцииКлиентСервер.ПодставитьПараметрыВСтроку`, `StringFunctionsClientServer.SubstituteParametersToString`.
`oscript`	`JSON-Объект`	Содержит настройки подсистемы библиотек OneScript.
⤷ `libRoots`	`Массив` `Строка`	Дополнительные корневые каталоги для поиска библиотек OneScript (в подкаталогах каждого ищется `lib.config`). Путь может быть абсолютным или относительным (от рабочей области). По умолчанию список пуст.
⤷ `useEnvLibLocation`	`Булево`	Дополнительно к `libRoots` учитывать пути из переменной окружения `OSCRIPT_LIB_LOCATION`. По умолчанию `false` (чтобы избежать неожиданного подхвата библиотек, например на CI).
⤷ `showImplicitLibraryEntriesInCompletion`	`Булево`	Предлагать в автодополнении (без точки) неявные записи библиотек — `.os`-файлы, не объявленные в `lib.config`. По умолчанию `false`. Полезно включить разработчику самой библиотеки.
`v8platform`	`JSON-Объект`	Содержит настройки платформенных типов 1С:Предприятие.
⤷ `binPath`	`Строка`	Путь к каталогу `bin` установленной платформы 1С (где лежат файлы синтакс-помощника `shcntx_.hbk`, `shlang_.hbk`). Если не задан, автоматически определяется самая свежая установка на машине. Пример: `C:\Program Files\1cv8\8.3.27.1786\bin`.
⤷ `enabled`	`Булево`	Разрешить загрузку платформенного контекста из синтакс-помощника установленной 1С. По умолчанию `true`. Можно отключить (например, в тестовом окружении), чтобы избежать дорогой автодетекции и парсинга HBK.
⤷ `targetVersion`	`Строка`	Целевая версия платформы 1С для диагностик совместимости (устаревание, недоступность члена по версии). Имеет приоритет над режимом совместимости конфигурации. Если не задана — используется режим совместимости конфигурации, а при его отсутствии берётся самая свежая платформа. Формат: `8.3.21`.
`excludePaths`	`Массив` `Строка`	Шаблоны путей, исключаемых из индексации. Сопоставляются с путями относительно корня конфигурации (например, имена каталогов `.git`, `node_modules` или glob `/.git/`, `*/.`). Из индексации и анализа исключаются только BSL/OS-файлы внутри указанных путей. По умолчанию список пуст.

Для облегчения составления и редактирования конфигурационного файла можно использовать следующую JSON-схему:

https://1c-syntax.github.io/bsl-language-server/configuration/schema.json

Примеры¶

Пример 1: Использование minimumLSPDiagnosticLevel для фильтрации диагностик¶

Этот пример демонстрирует фильтрацию диагностик по уровню серьезности LSP:

Устанавливает язык сообщений диагностик - английский;
Изменяет настройку диагностики LineLength - Ограничение на длину строки, устанавливая предел длины строки в 140 символов;
Отключает диагностику MethodSize - Ограничение на размер метода.
Фильтрует диагностики, не запуская диагностики с уровнем серьезности ниже Warning (диагностики Information и Hint не будут запускаться)

{
  "$schema": "https://1c-syntax.github.io/bsl-language-server/configuration/schema.json",
  "language": "en",
  "diagnostics": {
    "minimumLSPDiagnosticLevel": "Warning",
    "parameters": {
      "LineLength": {
        "maxLineLength": 140
      },
      "MethodSize": false
    }
  }
}

Пример 2: Использование overrideMinimumLSPDiagnosticLevel для изменения серьезности¶

Этот пример демонстрирует изменение отображаемого уровня серьезности диагностик:

Устанавливает язык сообщений диагностик - английский;
Включает расчет диагностик в непрерывном режиме (computeTrigger = onType)
Диагностики рассчитываются только по объектам подсистемы "СтандартныеПодсистемы" за исключением "ВариантыОтчетов" и " ВерсионированиеОбъектов"
Повышает уровень серьезности до Warning для всех запускаемых диагностик (диагностики с Information или Hint будут отображаться как Warning)
Переопределяет тип диагностики EmptyCodeBlock на ERROR и серьезность на BLOCKER

{
  "$schema": "https://1c-syntax.github.io/bsl-language-server/configuration/schema.json",
  "language": "en",
  "diagnostics": {
    "computeTrigger": "onType",
    "overrideMinimumLSPDiagnosticLevel": "Warning",
    "metadata": {
      "EmptyCodeBlock": {
        "type": "ERROR",
        "severity": "BLOCKER"
      }
    },
    "subsystemsFilter": {
      "include": [
        "СтандартныеПодсистемы"
      ],
      "exclude": [
        "ВариантыОтчетов",
        "ВерсионированиеОбъектов"
      ]
    }
  }
}