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

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

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

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

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

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

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

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

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

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

Палитра автодополнения ограничена тем, что область фактически импортирует. Редактор также предоставляет просмотрщик типов поверх палитры use уровня области — явного списка типов, объявленных доступными в манифесте package.archspace, — так что вы можете пролистать весь словарь, который предлагает область, прежде чем тянуться за типом. Объявление импортов на уровне области держит эту палитру обнаружимой в одном месте.

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

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

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

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

Диагностики

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

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

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

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

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

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

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

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

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

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

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

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

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

Предпросмотр — это выводимое представление: он отражает текст, а не является поверхностью редактирования. Тут нечего перетаскивать, нет раскладки, которую нужно подправлять — это работа рендерера. Пишите ради точной и полной модели, и диаграмма последует за ней; не переформируйте модель ради более красивой картинки.

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

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

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

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

frontend Portal {
    aspect domain: "Web"   ⋯ (required on type frontend)
}

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

Распределённое авторство и быстрые черновики

Авторство в ArchLang идёт снизу вверх: тот, кто владеет частью, — лучший человек, чтобы её описать. Редактор построен под это. Форма in Parent позволяет владельцу прикрепить свой модуль к родителю, объявленному в чужом файле, а файлово-локальные импорты дают каждому участнику вытянуть ровно те типы, которые ему нужны, — так что люди правят свои части в своих файлах, не согласовывая один гигантский документ. Межфайловые переход к определению, поиск ссылок и переименование сшивают эти разрозненные файлы обратно в одну модель.

Однофайловые черновики тоже полноправны здесь. Откройте новый .arch, обопритесь на локальные типы плюс типы стандартной библиотеки — и языковой сервер даёт вам полный цикл автодополнения/подсказок/диагностик без настройки пакета. Панель предпросмотра отрисовывает его так же, как отрисовывает полноценное рабочее пространство. Повысьте черновик до управляемого пакета, когда он это заслужит.

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

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: Встраивание диаграмм → — как разместить архитектурные диаграммы в собственных страницах, дашбордах и инструментах ревью.