Публикация пакетов ядра в npm

Все пакеты @aom-js/* выходят одной версией и все сразу, даже если часть из них в выпуске не менялась.

Почему одна версия

• Пакеты тесно связаны: api зависит от core, schemer, router, visualizer; от core зависят все остальные (граф — Архитектура ядра). Изменение в core почти всегда тянет выпуск зависящих пакетов.
• Две копии core в одном приложении ломают его: у каждой копии свой реестр мета-инстансов, и метаданные, записанные декораторами одной копии, не видны другой. Одна версия и точные ссылки между пакетами исключают такую смесь.
• Пользователю правило одно: все пакеты @aom-js ставятся одной версии.

Пакет без изменений выходит с новым номером и тем же содержимым — это нормально.

Где версия

• Номер — только в поле version корневого package.json. scripts/prebuild.js подставляет его в package.json каждого пакета; своей версии у пакета нет.
• Ссылки между пакетами в package.src.json — workspace:*. При публикации bun publish заменяет их на точную версию выпуска: @aom-js/api@0.1.0 требует ровно @aom-js/core@0.1.0.
• Первая общая версия — 0.1.0: она выше всех номеров, под которыми пакеты уже опубликованы в npm по отдельности.

Какую цифру поднимать

Пока версия начинается с 0.:

Изменение	Пример
несовместимое: удалён или переименован публичный символ, изменилось поведение, на которое опирается приложение	0.1.3 → 0.2.0
исправление или новая возможность без поломки	0.1.3 → 0.1.4
пробный выпуск	0.2.0-next.1

1.0.0 — когда публичный API устоялся; дальше обычный semver: несовместимое — первая цифра, новое — вторая, исправление — третья.

Как выпустить

1. Ворота зелёные (из корня ядра): bunx vitest run, bun run build (сборка со smoke-проверкой), затем bunx tsc -p tsconfig.json --noEmit и node scripts/lint-ratchet.js — подробности в Архитектура ядра.
2. Поднять version в корневом package.json, выполнить node scripts/prebuild.js && bun install (номер попадёт в bun.lock), дописать раздел версии в CHANGELOG.md, закоммитить всё вместе.
3. Проверить без публикации: bun run release:dry — тесты, сборка и состав архива каждого пакета (bun pm pack --dry-run); вход в npm не нужен.
4. Выпустить: bun run release (нужен вход в npm с правом публикации в скоуп @aom-js).
5. Отправить метку: git push origin v<версия>.

Что делает scripts/release.js:

• отказывает, если рабочее дерево не чистое — выпуск только из коммита;
• пропускает пакеты, у которых эта версия уже есть в npm, и отказывает, если она есть у всех: забыли поднять версию. Поэтому прерванный выпуск дотягивается повторным запуском;
• прогоняет bunx vitest run и bun run build (сборка с prebuild и smoke-проверкой);
• публикует пакеты в порядке зависимостей (core первым, api последним) с --access public; версия с дефисом (0.2.0-next.1) уходит под меткой npm next, остальные — под latest;
• ставит git-метку v<версия>.

Нельзя

• Публиковать один пакет в обход bun run release или давать пакету свою версию.
• Ссылаться между пакетами ядра на диапазон версий вместо workspace:*.
• Перевыпускать опубликованную версию: npm её не примет. Ошибочный выпуск — исправить следующей версией, сломанную пометить npm deprecate @aom-js/<пакет>@<версия> "<причина>"; npm unpublish не использовать.