@nitra/cursor 3.22.0 → 3.23.0

package/rules/release/docs/release.md

@@ -0,0 +1,222 @@
+# `release.mjs` — оркестратор реліз-процесу `n-cursor release`
+
+## Огляд
+
+Модуль `npm/rules/release/release.mjs` — це ядро команди `n-cursor release`. Він агрегує per-workspace change-файли (накопичені у `CHANGES_DIR` кожного воркспейсу) у:
+
+1. version-bump у маніфесті пакета (`package.json` для npm-пакетів або `pyproject.toml` для Python),
+2. новий розділ у `CHANGELOG.md` відповідного воркспейсу,
+3. git-коміт зі стандартизованим subject `release: <name@version>, ...`,
+4. git-теги у форматі `<name>@<version>` для кожного зрелізованого пакета,
+5. фізичне видалення «спожитих» change-файлів,
+6. `git push --follow-tags`.
+
+Модуль розрахований на запуск у CI на гілці `main` (варіант A з ADR `n-cursor-release-design`). Сам він **нічого не публікує** у реєстри (npm/PyPI) — цим займаються окремі CI-кроки, орієнтовані на створені теги.
+
+Підтримуються:
+
+- monorepo (root має суб-воркспейси) — root-пакет автоматично пропускається, релізиться лише кожен суб-воркспейс окремо;
+- single-package репо (`workspaces === ['.']`) — релізиться сам root.
+
+Якщо явних change-файлів у воркспейсі немає, але в історії з останнього тегу `<name>@<version>` є коміти, модуль робить **fallback-синтез** запису з commit log (через `synthesizeChangeFromCommits`).
+
+## Експорти / API
+
+| Символ                        | Тип              | Призначення                                                                                       |
+| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
+| `release(opts?)`              | `async function` | Програмний API: виконує повний реліз-цикл і повертає масив зрелізованих пакетів.                  |
+| `runReleaseCli(_args, opts?)` | `async function` | CLI-обгортка: запускає `release`, друкує підсумок у stdout/stderr, повертає exit-код (`0` / `1`). |
+
+Внутрішні (не експортовані) функції-помічники: `writeManifestVersion`, `prependWorkspaceChangelog`, `collectChangeFiles`.
+
+Внутрішні константи: `SEMVER_LINE_RE`, `PY_VERSION_LINE_RE` — regex для in-place заміни рядка `version` у відповідних типах маніфесту.
+
+## Функції
+
+### `writeManifestVersion(cwd, manifest, newVersion)` (внутрішня)
+
+Записує нову version у маніфест пакета, зберігаючи форматування файлу.
+
+- **Сигнатура:** `async (cwd: string, manifest: PackageManifest, newVersion: string) => Promise<void>`
+- **Параметри:**
+  - `cwd` — абсолютний шлях кореня репо (root проекту);
+  - `manifest` — об'єкт маніфесту з типу `PackageManifest`, що містить поля `ws` (відносний шлях до воркспейсу, або `.` для root), `manifestRel` (відносний шлях до файлу маніфесту в межах воркспейсу) і `kind` (`'npm'` чи інший — трактується як Python);
+  - `newVersion` — новий рядок версії (SemVer для npm, PEP 440 / SemVer для Python — не валідується тут).
+- **Повертає:** `Promise<void>` після успішного запису.
+- **Side effects:**
+  - читає файл маніфесту з диска;
+  - перезаписує його зі зміненим рядком версії;
+  - **обирає regex за типом маніфесту**: `SEMVER_LINE_RE` для `'npm'`, `PY_VERSION_LINE_RE` інакше;
+  - **кидає `Error`**, якщо в файлі не знайдено патерн рядка `version` (тобто `text.replace(...)` не змінив текст).
+
+### `prependWorkspaceChangelog(cwd, ws, sectionBlock)` (внутрішня)
+
+Доклеює (prepend) новий блок CHANGELOG до початку `<ws>/CHANGELOG.md`; якщо файл не існує — створює.
+
+- **Сигнатура:** `async (cwd: string, ws: string, sectionBlock: string) => Promise<void>`
+- **Параметри:**
+  - `cwd` — корінь репо;
+  - `ws` — відносний шлях воркспейсу від `cwd` (наприклад, `'npm'`, `'.'`);
+  - `sectionBlock` — готовий markdown-блок нового розділу (формат сформований `aggregateWorkspace`).
+- **Повертає:** `Promise<void>`.
+- **Side effects:** читає (за наявності) і пише `<cwd>/<ws>/CHANGELOG.md`. Логіку конкатенації керує `prependChangelogSection` з `./lib/aggregate.mjs` — модуль `release.mjs` лише викликає її, не дублюючи правил вставки.
+
+### `collectChangeFiles(cwd, manifest, runGit)` (внутрішня)
+
+Збирає всі change-записи для воркспейсу: спочатку явні файли з `CHANGES_DIR`, інакше — fallback-синтез з історії комітів.
+
+- **Сигнатура:** `async (cwd: string, manifest: PackageManifest, runGit: (args: string[]) => Promise<string | null>) => Promise<Array<{ file: string | null, entry: { bump: string, section: string, description: string } }>>`
+- **Параметри:**
+  - `cwd` — корінь репо;
+  - `manifest` — маніфест воркспейсу;
+  - `runGit` — git-раннер; повертає stdout як рядок, або `null`, якщо команда зафейлилася.
+- **Повертає:** масив об'єктів `{ file, entry }`:
+  - `file` — ім'я change-файлу у `CHANGES_DIR` (для подальшого видалення), або `null` для синтезованого запису;
+  - `entry` — нормалізований опис зміни: `{ bump, section, description }` (типи `bump`/`section` визначаються форматом change-файлу і `synthesizeChangeFromCommits`).
+- **Поведінка:**
+  1. Викликає `readChangeFiles(manifest.ws, cwd)`; якщо результат непустий — повертає його (явні мають пріоритет).
+  2. Інакше: якщо у маніфесті немає `name` — повертає `[]` (без імені неможливо знайти попередній тег для fallback).
+  3. Інакше викликає `synthesizeChangeFromCommits(name, ws, { runGit })`; якщо нічого не синтезувалося — `[]`.
+  4. Якщо синтезовано — друкує в stderr попередження `⚠️  <ws>: немає change-файлів — синтезовано запис із комітів (fallback)` і повертає `[{ file: null, entry: synthesized }]`.
+- **Side effects:** виклики git через `runGit` (всередині `synthesizeChangeFromCommits`); `console.warn` при fallback.
+
+### `release(opts?)` (експорт)
+
+Основний програмний вхід — виконує повний реліз-цикл для всіх релевантних воркспейсів.
+
+- **Сигнатура:**
+  ```
+  async (opts?: {
+    cwd?: string,
+    date?: string,
+    runGit?: (args: string[]) => Promise<string | null>,
+  }) => Promise<Array<{ ws: string, name: string | null, newVersion: string }>>
+  ```
+- **Параметри `opts` (усі необов'язкові):**
+  - `cwd` — корінь репо; за замовчуванням `process.cwd()`;
+  - `date` — рядок у форматі `YYYY-MM-DD` для дати релізу в CHANGELOG; за замовчуванням сьогоднішня UTC-дата (`new Date().toISOString().slice(0, 10)`);
+  - `runGit` — інжектований git-раннер; за замовчуванням `defaultRunGit(cwd)` (виконує справжні git-команди у `cwd`).
+- **Повертає:** масив зрелізованих пакетів, кожен — `{ ws, name, newVersion }`. Якщо релізити нічого не було — повертає `[]` (без коміту/тегу/пушу).
+- **Алгоритм:**
+  1. Отримує список воркспейсів через `getMonorepoProjectRootDirs(cwd)`.
+  2. Визначає, чи це monorepo: `subWorkspaces = workspaces.filter(w => w !== '.')`, `isMonorepoRoot = subWorkspaces.length > 0`.
+  3. Для кожного `ws`:
+     - якщо `ws === '.'` і `isMonorepoRoot` — пропустити (root у monorepo не релізиться сам по собі);
+     - читає маніфест через `readPackageManifest(ws, cwd)`; якщо манfest відсутній або без `version` — пропустити;
+     - збирає change-записи через `collectChangeFiles`;
+     - викликає `aggregateWorkspace({ currentVersion, changeFiles, date })` — якщо повертає `null` (нема чого релізити, всі записи відфільтровано) — пропустити;
+     - інакше: записує нову версію у маніфест (`writeManifestVersion`), prepend новий розділ у `CHANGELOG.md` (`prependWorkspaceChangelog`), видаляє кожен спожитий change-файл (`rm` у `<cwd>/<ws>/<CHANGES_DIR>/<file>`), додає запис у `released`, а якщо є `manifest.name` — формує тег `<name>@<newVersion>`.
+  4. Якщо `released.length > 0`:
+     - формує subject коміту: список тегів через `, `, або (якщо тегів нема — наприклад, у пакетів без `name`) — `<ws>@<newVersion>`-значення;
+     - `git add -A`;
+     - `git commit -m "release: <subject>"` — якщо `runGit` повертає `null` (коміт не вдався), кидає `Error('release: git commit не вдався — теги та push скасовано')`;
+     - для кожного тегу — `git tag <tag>`;
+     - `git push --follow-tags`.
+- **Side effects:**
+  - читання/запис файлів маніфестів і `CHANGELOG.md`;
+  - видалення change-файлів з диска (`rm`);
+  - виконання git-команд через `runGit` (включно з push до remote);
+  - `console.warn` при fallback (через `collectChangeFiles`).
+- **Помилки:** кидаються через `throw new Error(...)` у двох місцях:
+  - не знайдено патерн `version` у маніфесті (`writeManifestVersion`);
+  - не вдався `git commit` (`runGit` повернув `null`).
+
+### `runReleaseCli(_args, opts?)` (експорт)
+
+CLI-фасад: викликає `release(opts)`, друкує підсумок, мапить помилки на exit-код.
+
+- **Сигнатура:** `async (_args: string[], opts?: { cwd?: string, date?: string, runGit?: ... }) => Promise<number>`
+- **Параметри:**
+  - `_args` — позиційні CLI-аргументи (поточна імплементація опцій з CLI не приймає, тому ігнорується; параметр підкреслений `_` для лінту);
+  - `opts` — ті самі опції, що в `release` (використовується тестами для інжекції `cwd`/`date`/`runGit`).
+- **Повертає:** `Promise<number>` — exit-код:
+  - `0` — успіх (включно з випадком «немає що релізити»);
+  - `1` — будь-яка помилка з `release`.
+- **Поведінка:**
+  - якщо `released.length === 0` — друкує `release: немає змін для релізу`;
+  - інакше для кожного запису — `console.log` рядок `✅ <name або ws>@<newVersion>`;
+  - при exception — `console.error("❌ <message>")` і повертає `1`. Підтримує і `Error` (бере `.message`), і не-`Error`-значення (приводить через `String(...)`).
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:fs` — `existsSync` (для перевірки існування `CHANGELOG.md`);
+- `node:fs/promises` — `readFile`, `writeFile`, `rm`;
+- `node:path` — `join`.
+
+### Внутрішні модулі проекту
+
+- `../changelog/lib/package-manifest.mjs`:
+  - `getMonorepoProjectRootDirs(cwd)` — повертає список воркспейсів (включно з `.`);
+  - `readPackageManifest(ws, cwd)` — читає маніфест воркспейсу;
+  - тип `PackageManifest` (через JSDoc-імпорт).
+- `./lib/aggregate.mjs`:
+  - `aggregateWorkspace({ currentVersion, changeFiles, date })` — обчислює `newVersion` і `sectionBlock` CHANGELOG за зібраними change-записами; повертає `null`, якщо немає змін до релізу;
+  - `prependChangelogSection(existing, sectionBlock)` — формує новий вміст `CHANGELOG.md` зі вставкою блоку на початок.
+- `./lib/change-file.mjs`:
+  - константа `CHANGES_DIR` — назва теки з change-файлами всередині воркспейсу;
+  - `readChangeFiles(ws, cwd)` — читає всі change-файли воркспейсу.
+- `./lib/fallback.mjs`:
+  - `defaultRunGit(cwd)` — фабрика git-раннера з прив'язкою до `cwd`;
+  - `synthesizeChangeFromCommits(name, ws, { runGit })` — синтезує change-запис із commit-історії з останнього тегу `<name>@*`.
+
+### Зовнішні залежності
+
+Жодних npm-пакетів — лише вбудовані модулі Node.js та внутрішні модулі проекту.
+
+## Потік виконання / Використання
+
+### CLI-використання (через диспатчер `n-cursor`)
+
+`runReleaseCli` під'єднується до точки входу `n-cursor release`. Зазвичай викликається в CI на `main` після злиття PR:
+
+```bash
+n-cursor release
+```
+
+Exit-код `0` — навіть якщо нічого не зрелізовано (в стандартний випадок «нічого не змінилось»). Exit-код `1` — фейл (помилка запису маніфесту, фейл `git commit`, тощо).
+
+### Програмне використання (у тестах / інших скриптах)
+
+```js
+import { release, runReleaseCli } from './release.mjs'
+
+// 1) Прямий виклик
+const released = await release({
+  cwd: '/abs/path/to/repo',
+  date: '2026-06-03',
+  runGit: async args => '...stdout...' // або null при помилці
+})
+
+// 2) Через CLI-фасад
+const code = await runReleaseCli([], { cwd, date, runGit })
+process.exit(code)
+```
+
+### Послідовність кроків у `release()`
+
+1. **Дискавер воркспейсів** — `getMonorepoProjectRootDirs(cwd)`.
+2. **Класифікація** — root пропускається у monorepo (де є суб-воркспейси).
+3. **Для кожного воркспейсу:**
+   - читання маніфесту;
+   - збір change-файлів (явні → fallback-синтез з комітів);
+   - агрегація → `newVersion` + `sectionBlock`;
+   - запис маніфесту;
+   - prepend CHANGELOG;
+   - видалення «спожитих» change-файлів;
+   - реєстрація запису і (за наявності `name`) тегу.
+4. **Якщо є зрелізоване хоча б одне:**
+   - формування subject коміту;
+   - `git add -A` → `git commit -m "release: <subject>"`;
+   - перевірка успішності коміту (інакше throw);
+   - проставляння всіх тегів;
+   - `git push --follow-tags`.
+5. **Повернення масиву** зрелізованих пакетів.
+
+### Інваріанти
+
+- Жодних версій/тегів/коміту, якщо немає реальних змін у жодному воркспейсі — масив `released` залишається порожнім, і блок git взагалі не виконується.
+- Якщо хоча б у одному воркспейсі не вдалось оновити маніфест — функція кидає виняток до `git add -A`; часткові зміни на диску можуть залишитися (виклик не транзакційний — це відповідальність CI/runner-а відкотити робоче дерево).
+- Якщо `git commit` зафейлився — теги не проставляються і push не виконується; кидається явна помилка.
+- Усі git-операції проходять через інжектований `runGit`, що дає змогу тестувати функцію без реальних git-викликів.

package/rules/release/lib/docs/aggregate.md

@@ -0,0 +1,246 @@
+# aggregate.mjs
+
+## Огляд
+
+Модуль `aggregate.mjs` забезпечує **агрегацію change-файлів одного workspace** у дві основні сутності:
+
+1. Новий рядок версії згідно semver-правил (`x.y.z` → бамп `major|minor|patch`).
+2. Markdown-секцію для файлу `CHANGELOG.md`, побудовану у форматі [Keep a Changelog 1.1.0](https://keepachangelog.com/uk/1.1.0/), де новіша версія додається зверху.
+
+Модуль є **чистим обчислювальним шаром** — він **не має побічних ефектів**: не читає й не пише файли, не викликає `git`, не звертається до мережі чи процесів. Усі операції зводяться до парсингу/рендерингу рядків та арифметики на номерах версії. Відповідальність за читання `CHANGELOG.md` з диску, виконання `git`-команд, видалення спожитих change-файлів та оновлення `package.json` (чи аналогічного маніфесту) лежить на викликачі — за конвенцією проєкту це `release.mjs`.
+
+Через відсутність побічних ефектів модуль легко тестується юніт-тестами без mock’ів файлової системи й використовується як деталізована «бібліотечна» частина CLI `n-cursor release` для монорепо.
+
+## Експорти / API
+
+| Експорт                                                     | Тип     | Призначення                                                                      |
+| ----------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `bumpVersion(version, bump)`                                | функція | Інкремент semver-рядка згідно з рівнем бампа                                     |
+| `maxBump(bumps)`                                            | функція | Найвищий пріоритет бампа у списку (`major` > `minor` > `patch`)                  |
+| `renderChangelogSection(version, date, entries)`            | функція | Рендер однієї версійної секції у markdown                                        |
+| `prependChangelogSection(existingText, sectionBlock)`       | функція | Вставка нової секції зверху наявного `CHANGELOG.md`                              |
+| `aggregateWorkspace({ currentVersion, changeFiles, date })` | функція | Високорівневе об’єднання change-файлів workspace у `newVersion` + `sectionBlock` |
+
+Усі експорти — **іменовані** (`export function …`). Default-export відсутній.
+
+## Функції
+
+### `bumpVersion(version, bump)`
+
+**Сигнатура:** `bumpVersion(version: string, bump: 'major'|'minor'|'patch'): string`
+
+**Параметри:**
+
+- `version` — поточна версія у форматі `x.y.z`, де `x`, `y`, `z` — невід’ємні цілі (валідується регулярним виразом `^(\d+)\.(\d+)\.(\d+)$`).
+- `bump` — рівень бампа: `'major'`, `'minor'` або `'patch'`. Будь-яке інше значення (включно з `undefined`, помилковим написанням) поведеться як `'patch'` (через гілку `return` без явної перевірки).
+
+**Повертає:** новий рядок версії згідно з правилами semver:
+
+- `major` → `(major + 1).0.0`
+- `minor` → `major.(minor + 1).0`
+- `patch` (за замовчуванням у `else`-гілці) → `major.minor.(patch + 1)`
+
+**Помилки:** `Error('aggregate: невалідний semver «<version>»')`, якщо вхідний рядок не відповідає формату `x.y.z`.
+
+**Side effects:** немає.
+
+**Приклади:**
+
+- `bumpVersion('1.2.3', 'major')` → `'2.0.0'`
+- `bumpVersion('1.2.3', 'minor')` → `'1.3.0'`
+- `bumpVersion('1.2.3', 'patch')` → `'1.2.4'`
+- `bumpVersion('0.0.1', 'major')` → `'1.0.0'`
+
+### `maxBump(bumps)`
+
+**Сигнатура:** `maxBump(bumps: string[]): string`
+
+**Параметри:**
+
+- `bumps` — непорожній (за контрактом виклику) список рядків-рівнів бампа. Допускаються лише значення зі `VALID_BUMPS` (`['major', 'minor', 'patch']`), але функція не валідує їх явно.
+
+**Повертає:** найвищий рівень бампа з масиву за пріоритетом `major > minor > patch`. Якщо у `bumps` немає жодного з `VALID_BUMPS`, повертається `'patch'` (через оператор `??`).
+
+**Реалізація:** використовує `VALID_BUMPS.find(level => bumps.includes(level))`. Оскільки `VALID_BUMPS` упорядкований як `['major', 'minor', 'patch']`, `find` поверне **перший** наявний у `bumps` рівень — тобто максимальний.
+
+**Side effects:** немає.
+
+**Приклади:**
+
+- `maxBump(['patch', 'minor'])` → `'minor'`
+- `maxBump(['patch', 'major', 'minor'])` → `'major'`
+- `maxBump(['patch'])` → `'patch'`
+- `maxBump([])` → `'patch'` (через fallback `?? 'patch'`)
+
+### `renderChangelogSection(version, date, entries)`
+
+**Сигнатура:** `renderChangelogSection(version: string, date: string, entries: Array<{ section: string, description: string }>): string`
+
+**Параметри:**
+
+- `version` — нова версія (рядок `x.y.z`).
+- `date` — дата релізу у форматі `YYYY-MM-DD` (не валідується функцією).
+- `entries` — масив записів change-файлів, де кожен запис має ключі `section` (один із `VALID_SECTIONS`) та `description`. Поле `bump` тут уже не використовується.
+
+**Повертає:** markdown-рядок, який починається з заголовка `## [<version>] - <date>\n`. Далі для кожного значення з `VALID_SECTIONS` (`Added`, `Changed`, `Fixed`, `Removed`) — за наявності записів — додається блок:
+
+```
+\n### <section>\n\n- <description1>\n- <description2>\n
+```
+
+Порядок секцій у виводі **фіксований** і відповідає порядку у `VALID_SECTIONS`, незалежно від порядку записів на вході. Усередині секції рядки додаються у тому ж порядку, у якому йшли у `entries` (стабільність забезпечується `Array.prototype.filter`).
+
+Секції без записів пропускаються (`continue`).
+
+**Side effects:** немає.
+
+**Приклад:**
+
+Вхід:
+
+- `version = '1.3.0'`
+- `date = '2026-06-03'`
+- `entries = [{ section: 'Added', description: 'нова опція X' }, { section: 'Fixed', description: 'падіння на Y' }]`
+
+Вихід:
+
+```
+## [1.3.0] - 2026-06-03
+
+### Added
+
+- нова опція X
+
+### Fixed
+
+- падіння на Y
+```
+
+### `prependChangelogSection(existingText, sectionBlock)`
+
+**Сигнатура:** `prependChangelogSection(existingText: string, sectionBlock: string): string`
+
+**Параметри:**
+
+- `existingText` — наявний вміст `CHANGELOG.md` (може бути порожнім рядком, або починатися з пробільних символів).
+- `sectionBlock` — попередньо зрендерений markdown-блок (зазвичай результат `renderChangelogSection`).
+
+**Повертає:** оновлений текст `CHANGELOG.md` у форматі Keep a Changelog (новіше зверху).
+
+**Логіка:**
+
+1. `existingText.trimStart()` — обрізаються провідні пробільні символи.
+2. Якщо отриманий текст **не** починається з заголовка `# Changelog`, повертається свіжий документ: `# Changelog\n\n<sectionBlock>` (тобто все попереднє вмонтоване як «без заголовка» відкидається — викликач має самостійно дбати про коректний вхідний файл).
+3. Інакше:
+   - `head` — перший рядок до `\n` (зазвичай `# Changelog`, може містити додаткові символи у тому ж рядку).
+   - `rest` — решта тексту після першого `\n`, із обрізаним початком (`trimStart`).
+   - Повертається конкатенація `head + '\n\n' + sectionBlock + '\n' + rest`.
+4. Якщо у тексті немає жодного `\n` (тобто текст складається тільки із заголовка-рядка), `rest = ''`, що дає коректний результат із порожньою «рештою».
+
+**Side effects:** немає.
+
+**Приклади:**
+
+- Порожній `existingText`:
+  - вихід: `# Changelog\n\n<sectionBlock>`.
+- `existingText = '# Changelog\n\n## [1.0.0] - 2026-01-01\n…'`:
+  - вихід: `# Changelog\n\n<sectionBlock>\n## [1.0.0] - 2026-01-01\n…`.
+- `existingText = 'тут нічого корисного'`:
+  - вихід: `# Changelog\n\n<sectionBlock>` (попередній вміст відкидається).
+
+### `aggregateWorkspace({ currentVersion, changeFiles, date })`
+
+**Сигнатура:**
+
+```
+aggregateWorkspace({
+  currentVersion: string,
+  changeFiles: Array<{ file: string, entry: { bump: string, section: string, description: string } }>,
+  date: string,
+}): { newVersion: string, sectionBlock: string, consumedFiles: string[] } | null
+```
+
+**Параметри (іменований об’єкт):**
+
+- `currentVersion` — поточна версія маніфесту workspace (`x.y.z`).
+- `changeFiles` — масив об’єктів, що відповідає виходу `readChangeFiles` з `change-file.mjs`. Кожен елемент має `file` (ім’я файлу `.md`) та `entry` (розпарсений frontmatter + опис).
+- `date` — рядок дати `YYYY-MM-DD` для секції CHANGELOG.
+
+**Повертає:**
+
+- `null`, якщо `changeFiles.length === 0` (явна ознака «нема чого релізити»).
+- Інакше — об’єкт:
+  - `newVersion` — результат `bumpVersion(currentVersion, maxBump(<усі bumps>))`.
+  - `sectionBlock` — результат `renderChangelogSection(newVersion, date, <усі entries>)`.
+  - `consumedFiles` — імена change-файлів (`c.file`), які мають бути видалені викликачем після успішного запису маніфесту й `CHANGELOG.md`.
+
+**Side effects:** немає. Функція суто комбінує попередньо описані `bumpVersion`, `maxBump`, `renderChangelogSection`.
+
+**Контракт із викликачем:** саме виклик `release.mjs` (або тести) відповідає за:
+
+- запис `CHANGELOG.md` (зазвичай через `prependChangelogSection(readFileSync('CHANGELOG.md'), sectionBlock)`);
+- оновлення поля `version` у `package.json`;
+- видалення файлів зі списку `consumedFiles` із `<ws>/.changes/`;
+- git-операції (commit / tag / push).
+
+## Залежності
+
+### Внутрішні (цей модуль імпортує)
+
+- `./change-file.mjs`:
+  - `VALID_BUMPS` — `Object.freeze(['major', 'minor', 'patch'])` — порядок використовується у `maxBump` для пріоритету «найвищого».
+  - `VALID_SECTIONS` — `Object.freeze(['Added', 'Changed', 'Fixed', 'Removed'])` — порядок секцій у markdown-виводі `renderChangelogSection`.
+
+### Зовнішні
+
+Немає. Жодних імпортів зі стандартної бібліотеки Node.js (`node:fs`, `node:path`, `node:crypto` тощо) або сторонніх пакетів. Це підкреслює статус модуля як «pure compute».
+
+### Внутрішні константи (не експортуються)
+
+- `SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/` — валідація формату `x.y.z`. Розрізняє лише три цілі числа, **не** підтримує pre-release / build-metadata.
+- `CHANGELOG_HEADER = '# Changelog'` — очікуваний заголовок `CHANGELOG.md` (Keep a Changelog convention).
+
+## Потік виконання / Використання
+
+Типовий потік релізу одного workspace (з боку викликача `release.mjs`):
+
+1. **Збір change-файлів.** Викликач звертається до `readChangeFiles(ws, cwd)` з `change-file.mjs`, отримуючи `Array<{ file, entry }>` — усі `.md` із `<ws>/.changes/`, відсортовані за іменем (тобто де-факто за `timestamp`).
+2. **Отримання поточної версії.** Викликач читає `package.json` (або інший маніфест) і дістає `currentVersion`.
+3. **Дата.** Викликач формує `date = new Date().toISOString().slice(0, 10)` або еквівалент.
+4. **Агрегація.** Виклик `aggregateWorkspace({ currentVersion, changeFiles, date })`:
+   - Якщо повертає `null` — викликач пропускає workspace (нема `change-файлів`).
+   - Якщо повертає об’єкт — отримуємо `newVersion`, `sectionBlock`, `consumedFiles`.
+5. **Оновлення `CHANGELOG.md`.** Викликач читає поточний `CHANGELOG.md` (або порожній рядок, якщо файлу нема), застосовує `prependChangelogSection(existingText, sectionBlock)` і записує результат на диск.
+6. **Оновлення маніфесту.** Викликач замінює `"version"` у `package.json` на `newVersion`.
+7. **Видалення change-файлів.** Викликач видаляє файли зі списку `consumedFiles` з `<ws>/.changes/`.
+8. **Git-операції.** Викликач виконує `git add`, `git commit`, опційно `git tag` згідно з політикою релізу.
+
+### Чому split: `aggregate.mjs` без I/O, `release.mjs` з I/O
+
+- **Тестованість.** Юніт-тести викликають експорти `aggregate.mjs` із чистих вхідних даних — без файлових моків, без часу.
+- **Чітка межа відповідальності.** Помилки парсингу / валідації лежать у `change-file.mjs`, помилки I/O / git — у `release.mjs`, а помилки «бізнес-логіки» semver/CHANGELOG — тут.
+- **Передбачуваність.** Жоден виклик функцій модуля не може зіпсувати ФС чи git-стан, навіть за хибних даних — упаде лише `throw` із описом проблеми.
+
+### Особливості / гарантії
+
+- **Стабільний порядок секцій** у виводі CHANGELOG: завжди `Added` → `Changed` → `Fixed` → `Removed` (порядок із `VALID_SECTIONS`), навіть якщо у вхідному масиві records записи перемішані.
+- **Пріоритет бампа** `major > minor > patch` гарантується порядком елементів у `VALID_SECTIONS`/`VALID_BUMPS`, а не явним порівнянням рядків.
+- **Fallback `maxBump`** — якщо у `bumps` немає жодного з відомих значень, повертається `'patch'`. Однак на практиці `change-file.mjs::parseChangeFile` уже валідує `bump`, тому до `maxBump` доходять лише валідні значення.
+- **Idempotency `prependChangelogSection`** не гарантується — функція не перевіряє, чи така версія вже існує у файлі. Викликач має сам слідкувати, щоб не дублювати реліз.
+- **Формат semver** обмежений `x.y.z` без префіксів (`v1.2.3` спричинить `Error`) та без pre-release/build (`1.2.3-rc.1` теж спричинить `Error`).
+
+## Rebuild Test
+
+За цією документацією має бути можливо переписати `aggregate.mjs` з нуля, отримавши функціонально-еквівалентний модуль, який:
+
+1. Імпортує `VALID_BUMPS` і `VALID_SECTIONS` з `./change-file.mjs`.
+2. Експортує функцію `bumpVersion(version, bump)`, що валідує semver через регулярний вираз `^(\d+)\.(\d+)\.(\d+)$`, кидає `Error('aggregate: невалідний semver «…»')` за невалідним входом і повертає інкрементовану версію за правилами `major/minor/patch`, з default-гілкою `patch` для будь-якого іншого значення `bump`.
+3. Експортує функцію `maxBump(bumps)`, яка шукає у масиві `bumps` перший елемент із `VALID_BUMPS` (тобто за пріоритетом `major > minor > patch`) і повертає `'patch'`, якщо нічого не знайдено.
+4. Експортує функцію `renderChangelogSection(version, date, entries)`, що повертає рядок із заголовком `## [<version>] - <date>\n`, далі — секції у порядку `VALID_SECTIONS`, кожна з заголовком `### <section>` та bullet-списком `- <description>`, із порожніми рядками-роздільниками згідно з форматом Keep a Changelog. Секції без записів пропускаються.
+5. Експортує функцію `prependChangelogSection(existingText, sectionBlock)`, яка:
+   - Якщо `existingText.trimStart()` не починається з `# Changelog`, повертає `# Changelog\n\n<sectionBlock>`.
+   - Інакше відокремлює перший рядок (`head`) і решту (`rest`, із `trimStart`) і повертає `head + '\n\n' + sectionBlock + '\n' + rest`.
+6. Експортує функцію `aggregateWorkspace({ currentVersion, changeFiles, date })`, яка:
+   - Повертає `null`, якщо `changeFiles` порожній.
+   - Інакше повертає `{ newVersion, sectionBlock, consumedFiles }`, де `newVersion = bumpVersion(currentVersion, maxBump(<усі c.entry.bump>))`, `sectionBlock = renderChangelogSection(newVersion, date, <усі c.entry>)`, `consumedFiles = <усі c.file>`.
+7. Не виконує жодного I/O й не залежить від `node:*`.