22. Интеграция с редактором

В большинстве случаев .arch файлы пишутся в редакторе, а не из CLI. Эта глава о том, что фактически делают расширения редактора — какие предложения автодополнения вы получаете, что показывает всплывающая подсказка, какие появляются действия с кодом, где живёт встроенный предпросмотр и как всё настроить, если ваш редактор не входит в первоклассно поддерживаемые.

Два расширения поддерживаются как первоклассные:

VS Code — найдите “Archlang” в маркетплейсе.
JetBrains (IDEA, WebStorm, GoLand, PyCharm, RubyMine, Rider, CLion) — найдите “Archlang” в маркетплейсе плагинов JetBrains.

Оба включают один и тот же языковой сервер (@archlang/lsp). Паритет возможностей — это цель; они идут в ногу.

Что даёт языковой сервер

Как только расширение установлено и вы открываете .arch файл, языковой сервер активируется. С этого момента:

Автодополнение

Набираете micro, и список автодополнения показывает service (и любые другие зарегистрированные виды, подходящие под префикс). После ключевого слова вида автодополнение предлагает свежие стабильные идентификаторы и соглашения об именовании модулей. Внутри тела автодополнение знает, какие поля предоставляет тип и какие обязательные поля остались незаполненными — для экземпляра service в начале списка вы увидите team, labels.domain и свойства widget.*.

Внутри шагов процесса автодополнение знает путь: наберите Customer > Payments., и вы получите список интерфейсов (и фасетов, в которые можно углубиться через точку), объявленных на Payments. Языковой сервер знает всё рабочее пространство — автодополнение между файлами в вашем пакете и через импортированные пакеты работает одинаково.

Всплывающая подсказка

Наведите курсор на любой идентификатор. Языковой сервер отрисует:

Для ссылки на модуль: вид модуля, команду, описание (с markdown + [[ссылки]] + @метки) и список его интерфейсов.
Для ссылки на интерфейс: вид интерфейса, описание и любую разводку subscribes:.
Для ключевого слова вида: тип, определяющий этот вид, его обязательные поля и цепочку до базового вида.
Для стабильного идентификатора: именованную декларацию и её расположение.

Тот же самый рендерер описаний, который использует Viewer, работает и во всплывающей подсказке. То, что вы видите в редакторе, совпадает с тем, что вы видите на диаграмме.

Диагностики

При каждом сохранении запускается полный валидатор. Ошибки и предупреждения подчёркиваются в исходнике и появляются в панели Problems. Коды диагностик (USE_TYPE_NOT_EXPORTED, DEP_CYCLE, WIDGETS_FILE_NOT_FOUND и т.п.) стабильны между релизами — вы можете фильтровать или повышать важность конкретных кодов в настройках проекта.

Переход к определению и поиск ссылок

Кликните правой кнопкой на любой идентификатор и перейдите туда, где он объявлен. Поиск ссылок показывает все места его использования — каждый шаг процесса, вызывающий данный интерфейс, каждый модуль, объявляющий его, каждое описание, в котором он упоминается.

Это работает между файлами пакета и через импортированные пакеты. Импортированные типы разрешаются в свою декларацию в исходном пакете (языковой сервер идёт по цепочке use).

Переименование

Переименуйте модуль — и каждая ссылка обновится: шаги процесса, упоминающие его, описания со ссылками на него, шаблоны include/exclude проекций, которые ему соответствовали. Переименования сохраняют стабильный идентификатор, так что движок диффа всё ещё видит один переименованный модуль, а не удаление-плюс-добавление (Глава 14).

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

Действия с кодом

Языковой сервер предоставляет действия с кодом (лампочки) для частых правок. Точный набор эволюционирует между релизами; типичные действия — заполнить обязательное поле значением по умолчанию, отбросить унаследованную декларацию и преобразовать между точечной и блочной формой меток. Наведите курсор на лампочку в любом контексте, чтобы посмотреть, что доступно.

Семантические токены

Подсветка синтаксиса в .arch файлах не лексическая — языковой сервер предоставляет семантические токены. Ключевые слова видов, стабильные идентификаторы, квалифицированные имена, описания и пути меток каждый получают свой тип токена, благодаря чему ваша цветовая тема может их различать. Подсветка идентична в VS Code и JetBrains, потому что оба потребляют один и тот же языковой сервер.

Встроенный предпросмотр диаграммы

Оба расширения включают встроенную панель предпросмотра. Откройте палитру команд и выполните Archlang: Preview Diagram (или используйте сочетание клавиш). Боковая панель отрисовывает диаграмму текущего пакета и обновляется при каждом сохранении — тот же дифф-цикл, что в разобранном примере Главы 2. Панель использует тот же рендерер, что и хостируемый и встроенный Viewer.

Управление панелью предпросмотра:

Переключение между проекцией пакета по умолчанию и любой объявленной view в файле.
Зум и панорамирование; применяются правила LOD из Главы 20.
Наведение на узел показывает его полное тело во всплывающем окне сбоку.
Клик по узлу возвращает к его декларации в редакторе.

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

Когда экземпляр модуля заполняет обязательное поле, редактор показывает тип, который изначально объявил это поле, как тусклую подсказку рядом со значением:

service Payments {
    team: Payments        ⋯ (required cascade on type service)
}

Подсказки внутри кода можно отключить, если они мешают. Они полезны, пока вы учите метамодель; уходят на второй план, когда вы её знаете.

Заметки по настройке для каждого редактора

VS Code

Расширение активируется автоматически на файлах .arch и package.archspace. При первой активации скачивается включённый бинарь языкового сервера (он поставляется внутри расширения, отдельная установка не нужна).

Стоит знать о таких настройках:

Настройка	По умолчанию	Эффект
`archlang.format.onSave`	`true`	Запускать форматтер при каждом сохранении
`archlang.preview.enabled`	`true`	Разрешить открытие встроенной панели предпросмотра
`archlang.stdlib.path`	(по умолчанию инструментария)	Указать на свою стандартную библиотеку, если вы работаете над самим инструментарием

JetBrains

Установите из маркетплейса плагинов. Плагин регистрирует файловый тип для .arch и лениво запускает встроенный языковой сервер при первом открытии файла.

Особенности JetBrains:

Окно Structure показывает модули, интерфейсы и процессы в виде дерева.
Действие правой кнопки “Show in Archlang Viewer” в окне Project открывает встроенный предпросмотр для любого .arch файла или каталога пакета.
Find Usages и Refactor → Rename привязаны к соответствующим запросам LSP.

Другие редакторы

Языковой сервер — это стандартный протокол LSP по stdio:

@archlang/lsp                    # если установлено через npm
archlang-lsp                     # если установлено через @archlang/cli (бинарь поставляется и там, и там)

Передайте эту команду LSP-клиенту вашего редактора и languageId arch. Конкретно:

Neovim с nvim-lspconfig: зарегистрируйте сервер, указывающий на archlang-lsp для типа файла arch.
Emacs с lsp-mode: добавьте (arch-mode . "archlang-lsp") в lsp-language-id-configuration.
Helix: добавьте блок [language] в languages.toml, указывающий на archlang-lsp.
Sublime Text с пакетом LSP: зарегистрируйте новый языковой сервер с той же командой.

Браузерные редакторы, которым нужен языковой сервер без бэкенда, могут использовать точку входа startBrowserServer(vfs) из @archlang/lsp/browser, которая запускает сервер как web worker с виртуальной файловой системой в памяти. Хостируемое демо на archlang.dev/demo использует именно это.

Чего языковой сервер не делает

Сам не отрисовывает диаграммы. Панель предпросмотра делегирует рендереру Viewer; языковой сервер только предоставляет разрешённую модель и обновления.
Не выполняет процессы. Archlang — описательный язык; процессы — это документация, не оркестрация. Языковой сервер описывает поток; он его не выполняет.
Не загружает пакеты по сети. Зависимости разрешаются относительно локальных путей файловой системы, объявленных в package.archspace. Если вам нужен реестр — это следующий уровень.

Итог

Расширения VS Code и JetBrains — первоклассные; оба включают один и тот же языковой сервер.
Языковой сервер обеспечивает автодополнение, всплывающие подсказки, диагностики, переход к определению, поиск ссылок, переименование, действия с кодом, семантические токены, подсказки внутри кода и встроенную панель предпросмотра.
Другие редакторы подключаются через стандартный протокол LSP по stdio (archlang-lsp) или как браузерный worker (@archlang/lsp/browser).
Коды диагностик стабильны между релизами; инструментарий ориентируется на них для фильтрации и проверки в CI.

Что дальше

Глава 23: Встраивание диаграмм → — как разместить архитектурные диаграммы в собственных страницах, дашбордах и инструментах ревью.