21. CLI

CLI archlang намеренно сделан небольшим. Четыре подкоманды покрывают всё, что нужно работающему проекту: проверить пакет, отформатировать файлы, выполнить производные проверки и вывести сводку по пакету. Никакого serve, никакого diff, никаких плагинов — для этих задач есть расширения редактора и Viewer. Эта глава описывает, что делает каждая подкоманда, какие флаги она принимает и как встроить их в CI и pre-commit хуки.

Установка

npm install -g @archlang/cli

После этого archlang появится в вашем PATH. CLI — это тонкая обёртка над @archlang/core, @archlang/parser и @archlang/lsp; всё содержимое node_modules этих пакетов уже включено в бинарник. Никаких нативных зависимостей, никакой Java, никакого Docker.

archlang --help
archlang --version

--version печатает версию инструментария. --help перечисляет четыре подкоманды и их флаги.

`archlang validate`

archlang validate <path>

Парсит каждый .arch файл внутри <path> (рекурсивно, с учётом вложенных границ package.archspace), запускает резолвер, запускает валидатор. Печатает диагностики в stdout. Возвращает ненулевой код выхода, если что-то не прошло.

archlang validate .                       # текущий каталог
archlang validate examples/demo           # конкретный пакет
archlang validate orders.arch             # отдельный файл (его пакет определяется автоматически)

Диагностики используют тот же формат, что выдаёт LSP, — то есть ошибка, которую вы видите в редакторе, совпадает с тем, что печатает CLI. Примеры:

orders.arch:14:5  ERROR  Required field 'team' is not fulfilled and not dropped
checkout.arch:8:9 ERROR  Process step callee 'Payments' resolves to a module, not an interface

Режим наблюдения

archlang validate --watch <path>

Перезапускает валидацию при каждом сохранении .arch. Удобно держать терминал открытым рядом с редактором, когда не хочется включать встроенный предпросмотр.

Использование в CI

Ненулевой код выхода — это контракт. В CI:

- run: npm install -g @archlang/cli
- run: archlang validate .

Pull-запросы не проходят, пока валидация не пройдёт. Сочетайте с format --check ниже.

`archlang format`

archlang format <path>

Переписывает файл (или каждый .arch файл внутри каталога) в каноническую форму: нормализованные пробелы, согласованные отступы, выровненные многострочные строки. Форматтер не меняет семантическое содержимое — он только нормализует раскладку.

Два флага меняют поведение:

archlang format --check <path>       # ненулевой код выхода, если что-то изменилось бы
archlang format --diff  <path>       # печатает дифф, который применился бы, но не пишет

--check — флаг для CI. --diff — локальный флаг “а что бы это сделало?”.

Стабильные идентификаторы

Стабильные идентификаторы назначаются инструментарием, когда декларация создаётся без них. Расширения редактора делают это при сохранении через языковой сервер. Со стороны CLI соответствующий шаг происходит на путях format и validate, которые касаются исходника. Не редактируйте стабильные идентификаторы вручную после записи; переименования опираются на них (Глава 13).

`archlang check`

archlang check <path>

Запускает validate и дополнительно все производные проверки, которые может выполнить валидатор: целостность каскада, инварианты меток, корректность шагов процесса, разрешение межпакетных ссылок, обнаружение пропущенных обязательных полей.

check — это более тяжёлый собрат validate. Используйте validate во внутреннем редакторском цикле, где нужна быстрая обратная связь; используйте check в CI и на крупных контрольных точках.

`archlang info`

archlang info <path>

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

Сценарии использования:

Введение в проект. Новый член команды запускает archlang info на пакете, в котором ему предстоит работать; он получает обзор размером в один экран, не открывая файлы.
Артефакты CI. Сохраняйте вывод как артефакт сборки, чтобы рецензенты PR могли с одного взгляда увидеть, как выглядит архитектура ветки.
Аудит миграций. Запускайте на старом пакете при его моделировании, затем перезапускайте после каждого прохода рефакторинга.

Комбинирование команд

Типичный pre-commit хук:

#!/usr/bin/env bash
set -e
archlang format --check .
archlang validate .

Типичная CI-задача:

- run: npm install -g @archlang/cli
- run: archlang format --check .
- run: archlang check .
- run: archlang info . > arch-summary.txt
- uses: actions/upload-artifact@v4
  with:
    name: arch-summary
    path: arch-summary.txt

format --check гарантирует, что каждый файл канонически отформатирован. check запускает полный валидатор. info выдаёт артефакт для рецензентов.

Коды выхода

Для целей CI любой ненулевой код выхода считайте провалом. CLI возвращает:

0 — успех, ошибок нет.
Ненулевой — ошибки, проблемы использования или прерывание режима наблюдения.

format --check возвращает ненулевой код, если что-то было бы переформатировано. validate --watch работает до Ctrl-C; код выхода отражает результат последней валидации.

Чего CLI не делает

Нет Viewer и сервера. Диаграммы отрисовываются расширениями редактора (встроенный предпросмотр) или хостируемым/встроенным Viewer (Глава 23). CLI не поставляет рендерер.
Нет подкоманды diff. Дифф предоставляется как библиотечный API (Глава 24) и отображается Viewer в режиме диффа. Конвейеры, которым нужен дифф, потребляют библиотеку.
Нет stdio-запускалки языкового сервера. Расширения редактора включают LSP напрямую. Если вы строите собственную интеграцию с редактором, см. Главу 22.
Нет системы плагинов. Всё, что делает CLI, — это одна из четырёх подкоманд. Настройка происходит через библиотечные API.

Итог

Четыре подкоманды: validate, format, check, info.
validate — для внутреннего цикла; check — для CI; info — для сводок.
format нормализует раскладку (пробелы, отступы, многострочные строки); --check для CI, --diff для локальной проверки.
Коды выхода стабильны; конвейеры ориентируются на них.
Нет рендерера, нет команды diff, нет системы плагинов — это всё живёт в других местах по дизайну.

Что дальше

Глава 22: Интеграция с редактором → — что языковой сервер даёт в VS Code и JetBrains.