Yarn Constraints: как задать правила для workspaces

Что проверяют Yarn Constraints в monorepo

В крупном Yarn workspace проблемы часто возникают не из-за установки пакетов, а из-за постепенного расхождения манифестов. Один пакет забывает `license`, другой использует устаревшую версию TypeScript, третий добавляет зависимость не в ту секцию. Yarn Constraints дают проекту программируемый слой правил поверх workspaces. В актуальной документации Yarn рекомендует JavaScript-based constraints, определяемые в `yarn.config.cjs`; старый Prolog-подход считается устаревшим. Это не линтер исходного кода и не security scanner: механизм работает прежде всего с метаданными workspace и зависимостями, поэтому хорошо подходит для архитектурных инвариантов monorepo.

Совет: Не начинайте с десятков правил. Сначала автоматизируйте 2–3 нарушения, которые команда действительно регулярно ловит вручную на code review.

Как добавить первое правило и включить проверку

1. Убедитесь, что проект действительно управляется Yarn workspaces и использует версию Yarn, документацию которой вы читаете. Синтаксис constraints менялся, поэтому не копируйте старые Prolog-примеры в современную конфигурацию.
2. Создайте или откройте `yarn.config.cjs` в корне проекта. В нём экспортируется функция constraints, которая получает API для обхода workspaces и задания требований.
3. Сформулируйте одно простое правило: например, обязательное поле в каждом workspace или единая версия выбранной dependency. Правило должно быть детерминированным и объяснимым разработчику.
4. Запустите `yarn constraints` и посмотрите список нарушений. На этом этапе ничего не исправляйте массово: сначала убедитесь, что правило не зацепило служебные или исключённые workspaces.
5. Если правило поддерживает безопасную автоматическую правку, выполните `yarn constraints --fix`, затем обязательно просмотрите diff package.json и lockfile, если он изменился.
6. Добавьте `yarn constraints` в CI как отдельный быстрый шаг. Тогда новый drift будет остановлен до merge, а не накопится до большой миграции.

Предупреждение: Автофикс не отменяет review: constraint может технически привести файлы к правилу, но само правило тоже может быть ошибочным.

Практичные правила для workspace-проектов

• Все публикуемые пакеты обязаны иметь одинаковое поле `license` и корректный `repository`.
• Определённый инструмент, например TypeScript, должен использовать одну согласованную версию во всех workspace, где он присутствует.
• Внутренний пакет разрешено подключать только через выбранный диапазон или протокол, если это часть политики репозитория.
• Приложения и библиотеки могут иметь разные требования: правило может учитывать имя, путь или другие свойства workspace вместо принудительного одинакового манифеста для всех.

Почему constraints не заменяют immutable install

`yarn install --immutable` и constraints проверяют разные уровни. Immutable install отвечает на вопрос, соответствует ли lockfile и install-state ожидаемому результату установки и можно ли выполнить её без запрещённой модификации. Constraints отвечают на вопрос, соответствует ли структура workspace вашим собственным правилам. Репозиторий может иметь идеальный lockfile и при этом содержать два пакета с разными version policy или отсутствующим обязательным полем. И наоборот, все manifests могут удовлетворять constraints, но lockfile устарел. В CI эти проверки дополняют друг друга, поэтому объединять их в один неясный «install check» не стоит.

Важно: Разделяйте сообщения CI: `yarn install --immutable` и `yarn constraints` должны падать отдельными шагами. Тогда причина видна без чтения длинного общего лога.

Что лучше проверять каким инструментом

• package.json нарушает внутреннюю политику. Yarn Constraints. Правило относится к workspace metadata
• lockfile потребовал бы изменения. yarn install --immutable. Это проверка воспроизводимой установки
• Ошибки JS/TS-кода. ESLint/TypeScript. Constraints не анализируют программную семантику исходников
• Известная уязвимость зависимости. Audit/security scanner. Нужна база advisory, а не только policy manifests

Как проектировать правила без постоянной борьбы с исключениями

Плохое constraint-правило звучит как «все package.json должны быть одинаковыми». В реальном monorepo приложение, CLI, private tooling и публикуемая библиотека имеют разные обязанности. Поэтому сначала разделите workspace на осмысленные группы, а затем формулируйте инварианты для каждой. Если исключение постоянно повторяется, возможно, это не исключение, а отдельный класс пакетов. Также избегайте правил, которые каждую неделю принудительно поднимают версии без тестирования совместимости: constraints хорошо фиксируют выбранную политику, но не должны самостоятельно принимать продуктовые решения об обновлении.

Готовность constraints к CI

• Правила хранятся в репозитории и проходят code review.
• Каждое правило имеет понятную цель и не дублирует линтер или install-check.
• Локальный запуск `yarn constraints` даёт тот же результат, что и CI.
• Автофикс проверен на тестовой ветке и не меняет лишние workspaces.
• Исключения сформулированы явно, а не зависят от случайного порядка файлов.
• После `--fix` выполняются install/test, если правка затрагивает зависимости.

Как внедрить проверку в существующий большой репозиторий

Если включить строгие constraints в зрелом monorepo одним коммитом, первая проверка может вывести сотни исторических нарушений и команда просто отключит её. Более безопасный путь — выбрать правило с маленьким числом нарушений, исправить текущее состояние и только потом сделать CI blocking. Следующее правило добавляется отдельным изменением. Для массовой нормализации сначала запустите проверку в режиме отчёта, сохраните список затронутых пакетов и разбейте правки по категориям. Такой rollout превращает constraints в инструмент предотвращения drift, а не в бесконечный проект по переписыванию всех manifests.

Что именно делает yarn constraints --fix и где нужен ручной review

`yarn constraints --fix` не является универсальным форматтером package.json: он пытается применить только те изменения, которые однозначно следуют из заданных constraints. Актуальная CLI-документация описывает multi-pass исправление с максимумом в 10 итераций; неоднозначные случаи команда может оставить пользователю. Поэтому безопасный CI обычно разделяет проверку и исправление: в pull request запускается обычный `yarn constraints`, а `--fix` разработчик применяет локально и просматривает diff. После автоправки зависимостей нужен `yarn install` и тесты, потому что изменение declared range может повлиять на lockfile и реальное разрешение пакетов. Для крупных репозиториев особенно полезно давать каждому правилу узкую цель и понятное сообщение: так нарушение объясняет, какую политику оно защищает, а не превращается в безымянный красный job.

Что учитывать

`yarn install --immutable` и constraints проверяют разные уровни. Immutable install отвечает на вопрос, соответствует ли lockfile и install-state ожидаемому результату установки и можно ли выполнить её без запрещённой модификации. Constraints отвечают на вопрос, соответствует ли структура workspace вашим собственным правилам. Репозиторий может иметь идеальный lockfile и при этом содержать два пакета с разными version policy или отсутствующим обязательным полем. И наоборот, все manifests могут…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. Constraints). Пример и формулировки — редакция N1RO на 2026-09-21.

• Constraints
• yarn constraints