@7n/rules 1.0.0

package/rules/release/lib/docs/change-file.md

@@ -0,0 +1,206 @@
+---
+type: JS Module
+title: change-file.mjs
+resource: npm/rules/release/lib/change-file.mjs
+docgen:
+  crc: 1540b895
+---
+
+Модуль для роботи з одиничним **change-файлом** релізного процесу — невеликою markdown-нотаткою, що описує одну зміну в межах workspace і агрегується пізніше при формуванні CHANGELOG / bump версії.
+
+## Огляд
+
+Файли change-нотаток лежать у `<ws>/.changes/<timestamp>-<rand>.md` (де `<ws>` — корінь окремого workspace монорепо) і мають мінімалістичний YAML-подібний frontmatter із рівно двома ключами:
+
+- `bump` — рівень semver-бампу (`major` | `minor` | `patch`);
+- `section` — секція Keep a Changelog (`Added` | `Changed` | `Fixed` | `Removed`).
+
+Після `---` йде довільний markdown-опис зміни.
+
+Модуль повністю **самодостатній**: без зовнішніх npm-залежностей; парсер frontmatter — простий рядковий розбір на `:`, без YAML-бібліотеки. Це навмисне обмеження — підтримуються тільки два передбачувані ключі, що знімає клас помилок (мультирядкові значення, типи, escape).
+
+Сценарії використання:
+
+- запис нової нотатки з CLI/агента (`newChangeFileName` + `serializeChangeFile`);
+- читання усіх нотаток workspace для агрегації (`readChangeFiles`);
+- одинична валідація/розбір (`parseChangeFile`).
+
+## Експорти / API
+
+| Експорт                             | Тип                 | Призначення                                                                                                                                                                                                            |
+| ----------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VALID_BUMPS`                       | `readonly string[]` | Дозволені semver-бампи `['major', 'minor', 'patch']` у порядку від найбільшого до найменшого (порядок є частиною контракту — використовується зовнішнім агрегатором для обчислення `max`). Заморожено `Object.freeze`. |
+| `VALID_SECTIONS`                    | `readonly string[]` | Дозволені секції Keep a Changelog: `['Added', 'Changed', 'Fixed', 'Removed']`. Заморожено `Object.freeze`.                                                                                                             |
+| `CHANGES_DIR`                       | `string`            | Назва підкаталогу з change-файлами в межах workspace — `.changes`.                                                                                                                                                     |
+| `parseChangeFile(text)`             | `function`          | Парсить вміст change-файлу у структурований запис. Кидає `Error` при будь-яких відхиленнях.                                                                                                                            |
+| `serializeChangeFile(entry)`        | `function`          | Серіалізує запис назад у текст change-файлу (frontmatter + опис + завершальний `\n`).                                                                                                                                  |
+| `changeFileName(timestamp, suffix)` | `function`          | Формує імʼя файлу `<timestamp>-<suffix>.md`.                                                                                                                                                                           |
+| `newChangeFileName()`               | `function`          | Згенерувати унікальне імʼя для нового change-файлу (`Date.now()` + 3 байти hex).                                                                                                                                       |
+| `readChangeFiles(ws, cwd?)`         | `async function`    | Прочитати й розпарсити всі `.md`-файли з `<cwd>/<ws>/.changes/`.                                                                                                                                                       |
+
+Внутрішнє (не експортується):
+
+- `FRONTMATTER_RE` — regexp `/^---\n([\s\S]*?)\n---\n([\s\S]*)$/` для виокремлення frontmatter і тіла.
+- `parseFrontmatterBlock(block)` — допоміжний парсер «ключ: значення» по рядках.
+
+## Функції
+
+### `parseFrontmatterBlock(block)` (внутрішня)
+
+- **Сигнатура:** `(block: string) => Record<string, string>`
+- **Параметри:**
+  - `block` — тіло frontmatter (рядки між `---`).
+- **Повертає:** обʼєкт із ключами/значеннями, кожен взятий із рядка через перший `:`; обидві частини `.trim()`-нуті. Рядки без `:` ігноруються.
+- **Side effects:** немає (чиста функція).
+- **Обмеження:** не підтримує квоти, escape, мультирядкові значення; коментарі `#` не розпізнаються (рядок із `#` обробляється як звичайна пара ключ-значення, якщо містить `:`).
+
+### `parseChangeFile(text)`
+
+- **Сигнатура:** `(text: string) => { bump: string, section: string, description: string }`
+- **Параметри:**
+  - `text` — повний вміст change-файлу (frontmatter + опис).
+- **Повертає:** обʼєкт із трьома полями: `bump`, `section`, `description` (опис — з `.trim()`).
+- **Кидає `Error`:**
+  - `change-файл: відсутній frontmatter \`---\``— якщо текст не відповідає`FRONTMATTER_RE`.
+  - `change-файл: bump має бути одним із major|minor|patch (отримано «…»)` — якщо `bump` поза `VALID_BUMPS` (включно з відсутнім ключем — тоді в підстановці буде порожній рядок).
+  - `change-файл: section має бути одним із Added|Changed|Fixed|Removed (отримано «…»)` — якщо `section` поза `VALID_SECTIONS`.
+  - `change-файл: порожній опис` — якщо тіло після frontmatter порожнє після `.trim()`.
+- **Side effects:** немає (чиста функція).
+- **Примітка:** повідомлення помилок українською — використовуються користувачем як діагностика прямо в CLI.
+
+### `serializeChangeFile(entry)`
+
+- **Сигнатура:** `(entry: { bump: string, section: string, description: string }) => string`
+- **Параметри:**
+  - `entry.bump` — один із `VALID_BUMPS` (функція **не** валідує — припускається, що валідація вже зроблена або значення підконтрольне виклику).
+  - `entry.section` — один із `VALID_SECTIONS` (без валідації).
+  - `entry.description` — текст опису.
+- **Повертає:** рядок виду:
+  ```
+  ---
+  bump: <bump>
+  section: <section>
+  ---
+  <description>
+  ```
+  із завершальним `\n` у кінці.
+- **Side effects:** немає (чиста функція).
+- **Round-trip:** `parseChangeFile(serializeChangeFile(entry))` повертає еквівалентний запис, якщо `entry.description` уже трімнутий.
+
+### `changeFileName(timestamp, suffix)`
+
+- **Сигнатура:** `(timestamp: number, suffix: string) => string`
+- **Параметри:**
+  - `timestamp` — епоха у мс (зазвичай `Date.now()`).
+  - `suffix` — короткий випадковий суфікс (як правило hex).
+- **Повертає:** `\`${timestamp}-${suffix}.md\``.
+- **Side effects:** немає (чиста функція).
+
+### `newChangeFileName()`
+
+- **Сигнатура:** `() => string`
+- **Параметри:** немає.
+- **Повертає:** `\`<Date.now()>-<rand6hex>.md\``, де `rand6hex`—`randomBytes(3).toString('hex')` (6 hex-символів).
+- **Side effects:** виклик `Date.now()` і CSPRNG `crypto.randomBytes(3)` — результат недетермінований.
+- **Призначення:** анти-колізія для випадку, коли кілька паралельних агентів у різних git-worktree пишуть нову нотатку в ту саму мілісекунду. Порядкове сортування за timestamp залишається стабільним; випадковий хвіст лише розриває нічию.
+
+### `readChangeFiles(ws, cwd = process.cwd())`
+
+- **Сигнатура:** `async (ws: string, cwd?: string) => Array<{ file: string, entry: { bump: string, section: string, description: string } }>`
+- **Параметри:**
+  - `ws` — шлях workspace (як правило відносний відносно `cwd`, наприклад `npm/foo`).
+  - `cwd` — корінь репозиторію; за замовчуванням `process.cwd()`.
+- **Повертає:** масив записів `{ file, entry }`, відсортований за іменем файлу через `Array#toSorted()` (лексикографічно; завдяки префіксу `<timestamp>` відповідає хронологічному порядку для timestamp однакової довжини).
+- **Side effects:**
+  - синхронна перевірка існування каталогу `<cwd>/<ws>/.changes/` через `existsSync`;
+  - читання списку директорії `readdir` (async);
+  - послідовне (не паралельне) читання кожного `.md`-файлу через `readFile(…, 'utf8')`.
+- **Поведінка крайових випадків:**
+  - якщо каталог `.changes` відсутній — повертає `[]` без помилок;
+  - якщо каталог існує, але порожній або не містить `.md` — повертає `[]`;
+  - якщо будь-який файл містить невалідний frontmatter / bump / section / опис — пробросає `Error` із `parseChangeFile` (не глушиться).
+- **Сортування:** `.toSorted()` — імʼя файлу як рядок, тому порядок: чим менший timestamp — тим раніше; для однакового timestamp вирішує hex-суфікс.
+
+## Залежності
+
+Тільки стандартна бібліотека Node.js (без npm-залежностей):
+
+- `node:crypto` — `randomBytes` (генерація випадкового суфікса для імені файлу).
+- `node:fs` — `existsSync` (швидка перевірка існування `.changes`).
+- `node:fs/promises` — `readdir`, `readFile` (читання каталогу і вмісту файлів).
+- `node:path` — `join` (склейка шляху `cwd/ws/.changes`).
+
+Внутрішні залежності модуля від інших файлів проєкту відсутні. Це робить модуль безпечно імпортованим із будь-якого контексту (CLI, тест, агент, ESLint-плагін).
+
+## Потік виконання / Використання
+
+### Створення нової нотатки
+
+```js
+import { writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CHANGES_DIR, newChangeFileName, serializeChangeFile } from './change-file.mjs'
+
+const ws = 'npm/some-pkg'
+const dir = join(process.cwd(), ws, CHANGES_DIR)
+await mkdir(dir, { recursive: true })
+
+const text = serializeChangeFile({
+  bump: 'patch',
+  section: 'Fixed',
+  description: 'Виправлено падіння CLI при відсутньому `.changes`.'
+})
+await writeFile(join(dir, newChangeFileName()), text)
+```
+
+### Читання й агрегація
+
+```js
+import { readChangeFiles, VALID_BUMPS } from './change-file.mjs'
+
+const items = await readChangeFiles('npm/some-pkg')
+// items: [{ file: '1700000000000-ab12cd.md', entry: { bump, section, description } }, …]
+
+// Обчислити максимальний bump: VALID_BUMPS впорядковані від major → patch,
+// тож менший індекс = «більший» bump.
+const maxIdx = items.reduce((acc, { entry }) => Math.min(acc, VALID_BUMPS.indexOf(entry.bump)), VALID_BUMPS.length)
+const finalBump = VALID_BUMPS[maxIdx] // або undefined, якщо items порожній
+```
+
+### Валідація одного файлу
+
+```js
+import { readFile } from 'node:fs/promises'
+import { parseChangeFile } from './change-file.mjs'
+
+const text = await readFile('npm/some-pkg/.changes/1700000000000-ab12cd.md', 'utf8')
+const entry = parseChangeFile(text) // кине Error із локалізованим повідомленням, якщо файл невалідний
+```
+
+### Контракт frontmatter
+
+Точний формат, який очікує `FRONTMATTER_RE`:
+
+```
+---
+bump: patch
+section: Fixed
+---
+<довільний markdown-опис>
+```
+
+Особливості:
+
+- frontmatter відкривається/закривається саме рядком `---` (3 дефіси, без пробілів);
+- символ розділювача — `\n` (LF); CRLF не підтримується regexp-ом без додаткової нормалізації;
+- ключі `bump` і `section` мають бути в нижньому регістрі точно так, як у `VALID_BUMPS`/`VALID_SECTIONS`;
+- значення секції — у титульному регістрі (`Added`, не `added`), оскільки воно безпосередньо використовується як заголовок `### {section}` у CHANGELOG;
+- зайві ключі у frontmatter не забороняються парсером (вони просто потрапляють у `out`-обʼєкт і ігноруються верхнім рівнем), але контракт модуля передбачає лише два;
+- після `---` має бути непорожній (після `trim`) markdown-опис, інакше — помилка.
+
+### Інваріанти, корисні викликачу
+
+- `parseChangeFile(serializeChangeFile(e)) ≡ e` для будь-якого валідного `e` із трімнутим `description`.
+- `newChangeFileName()` завжди відповідає шаблону `^\d+-[0-9a-f]{6}\.md$`.
+- `readChangeFiles` ніколи не повертає шляхи поза `<cwd>/<ws>/.changes/` — лише імена файлів у полі `file`.
+- Відсутність `.changes` — не помилка, а сигнал «змін немає».

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

@@ -0,0 +1,207 @@
+---
+type: JS Module
+title: fallback.mjs
+resource: npm/rules/release/lib/fallback.mjs
+docgen:
+  crc: 0ca2c46a
+---
+
+Модуль `fallback.mjs` реалізує **третє рішення** з ADR `n-rules-release-design`: коли в певному workspace монорепо виявлено релевантні зміни, але **жодного change-файлу** від розробника не з’явилося, релізний пайплайн все одно повинен мати запис у CHANGELOG. Для цього модуль **синтезує** один штучний запис `change` із commit-subject-ів, які з’явилися від моменту останнього релізного тегу формату `<name>@*` до `HEAD`, обмежуючи журнал git pathspec-ом самого workspace.
+
+Файл експортує дві функції:
+
+- `defaultRunGit(cwd)` — фабрика «тихого» git-раннера: повертає stdout або `null` у разі будь-якої помилки (без кидання винятків).
+- `synthesizeChangeFromCommits(name, ws, opts?)` — асинхронна функція, що повертає одну синтетичну change-запис `{ bump, section, description }` або `null`, якщо синтез неможливий (bootstrap-релізу немає тегу або немає комітів у діапазоні).
+
+Усі git-виклики **навмисно** йдуть через інжектований раннер (`opts.runGit`), щоб тести могли мокати git без реальних `execFile`-викликів.
+
+## Експорти / API
+
+| Експорт                                        | Тип                  | Призначення                                                     |
+| ---------------------------------------------- | -------------------- | --------------------------------------------------------------- |
+| `defaultRunGit(cwd)`                           | named function       | Створює дефолтний git-раннер, прив’язаний до конкретного `cwd`. |
+| `synthesizeChangeFromCommits(name, ws, opts?)` | named async function | Синтезує один change-запис із git-історії або повертає `null`.  |
+
+Default-експортів немає.
+
+### TypeScript-подібна сигнатура
+
+```text
+defaultRunGit(cwd: string): (args: string[]) => Promise<string | null>
+
+synthesizeChangeFromCommits(
+  name: string,
+  ws: string,
+  opts?: { runGit?: (args: string[]) => Promise<string | null> }
+): Promise<{ bump: 'patch'; section: 'Changed'; description: string } | null>
+```
+
+## Функції
+
+### `defaultRunGit(cwd)`
+
+**Сигнатура:** `function defaultRunGit(cwd: string): (args: string[]) => Promise<string | null>`
+
+**Параметри:**
+
+- `cwd` _(string)_ — абсолютний або відносний шлях до робочого каталогу, у якому виконуються git-команди.
+
+**Повертає:** функцію-раннер `async (args: string[]) => Promise<string | null>`. Раннер:
+
+- виконує `git <...args>` у заданому `cwd` через `execFile` (без shell, без інтерполяції аргументів);
+- у разі успіху повертає **повний stdout** як рядок (без обрізання, без декодування);
+- у разі будь-якої помилки (non-zero exit, ENOENT, відсутність git, repo not found тощо) повертає `null` — **жоден виняток не пробивається назовні**.
+
+**Side effects:**
+
+- Спавнить дочірній процес `git` через `node:child_process.execFile`.
+- Читає файлову систему репозиторію (через сам git).
+- Не пише у stdout/stderr батьківського процесу, не змінює стан репо.
+
+**Дизайнерські рішення:**
+
+- `execFile` (а не `exec`) — захист від shell-injection; аргументи передаються як масив.
+- `try/catch` обгортає виклик, перетворюючи помилку на `null`. Це дозволяє викликачу не дбати про обробку винятків і однаково реагувати на «команда не виконалась» та «команда повернула порожньо».
+
+### `synthesizeChangeFromCommits(name, ws, opts?)`
+
+**Сигнатура:**
+
+```text
+async function synthesizeChangeFromCommits(
+  name: string,
+  ws: string,
+  opts?: { runGit?: (args: string[]) => Promise<string | null> }
+): Promise<{ bump: string; section: string; description: string } | null>
+```
+
+**Параметри:**
+
+- `name` _(string)_ — ім’я npm-пакета. Використовується для побудови патерну тегу `<name>@*` у `git describe --match`.
+- `ws` _(string)_ — workspace, що виступає pathspec-ом для `git log`. Спеціальне значення `'.'` означає «весь репозиторій, без обмеження шляху»; будь-яке інше значення інтерпретується як директорія і додається до команди як `-- <ws>/`.
+- `opts` _(object, optional)_ — опції:
+  - `opts.runGit` _((args) => Promise\<string|null\>)_ — кастомний git-раннер (ін’єкція для тестів). Якщо не задано, використовується `defaultRunGit(process.cwd())`.
+
+**Повертає:** `Promise` що резолвиться в:
+
+- **об’єкт** `{ bump: 'patch', section: 'Changed', description: <string> }` — синтетичний change-запис, де `description` є склейкою всіх commit-subject-ів через роздільник `'; '`;
+- **`null`** — у двох випадках:
+  1. **Bootstrap-кейс:** `git describe` не знайшов жодного попереднього тегу `<name>@*` (повернув `null` або порожній рядок після `trim`). Перший реліз робиться вручну, fallback не повинен дублювати bump.
+  2. **No-op кейс:** теги є, але `git log <lastTag>..HEAD` для даного workspace не повернув жодного непорожнього subject-а (немає змін у скоупі workspace після останнього релізу).
+
+**Side effects:**
+
+- Через `runGit` спавнить **до двох** git-процесів (`git describe`, потім `git log`).
+- Не пише на диск, не мутує жодних аргументів.
+
+**Алгоритм покроково:**
+
+1. Розв’язати раннер: `runGit = opts.runGit ?? defaultRunGit(process.cwd())`.
+2. Викликати `git describe --tags --abbrev=0 --match <name>@* HEAD`. Якщо результат — `null`/порожньо/whitespace після `trim()` — повернути `null` (bootstrap).
+3. Сформувати pathspec: `[]` для `ws === '.'`, інакше `['--', `${ws}/`]`.
+4. Викликати `git log --no-merges --format=%s <lastTag>..HEAD [-- <ws>/]`.
+5. Розділити stdout по `\n`, обрізати кожен рядок, відкинути порожні (`filter(Boolean)`).
+6. Якщо масив subjects порожній — повернути `null`.
+7. Інакше — повернути `{ bump: 'patch', section: 'Changed', description: subjects.join('; ') }`.
+
+**Інваріанти / контракти:**
+
+- `bump` завжди дорівнює рядку `'patch'` — fallback не вгадує `minor`/`major`; підвищити рівень bump-у можна лише явним change-файлом.
+- `section` завжди `'Changed'` — без класифікації за типом коміту (Added/Fixed/тощо).
+- `description` ніколи не порожній (інакше функція повертає `null`).
+- Якщо `logRaw` дорівнює `null` (git-помилка) — це трактується **тотожно** з порожнім логом: `(logRaw ?? '').split('\n')` дасть `['']`, що після фільтрів стане `[]` → результат `null`. Тобто помилка `git log` свідомо **не** кидається назовні; це частина контракту «тихого» раннера.
+
+## Залежності
+
+### Зовнішні (стандартна бібліотека Node.js)
+
+- **`node:child_process.execFile`** — запуск дочірнього процесу `git` без shell.
+- **`node:util.promisify`** — перетворення `execFile` callback-стилю на `Promise`-сумісний `execFileAsync`.
+
+### Внутрішні
+
+Файл **не імпортує** жодних внутрішніх модулів проєкту. Він самодостатній і використовується іншими модулями релізного пайплайна (зокрема `aggregate.mjs` у тому ж каталозі) як інструмент синтезу запису.
+
+### Передумови середовища
+
+- У `PATH` має бути доступний бінарник `git`.
+- `cwd` повинен вказувати на git-репозиторій (інакше `git describe` поверне `null` і функція коректно деградує до bootstrap-кейсу).
+- Теги релізів мають іти за конвенцією `<pkg-name>@<version>` — інакше `--match <name>@*` нічого не знайде.
+
+## Потік виконання / Використання
+
+### Типова інтеграція в релізному пайплайні
+
+```js
+import { synthesizeChangeFromCommits } from './fallback.mjs'
+
+// В межах одного workspace монорепо:
+const change = await synthesizeChangeFromCommits('@scope/pkg', 'packages/pkg')
+if (change) {
+  // Додаємо як єдиний запис у агрегацію change-ів цього релізу
+  applyChange(change)
+} else {
+  // Або bootstrap-реліз (тегу ще не існує), або нічого не змінилося в скоупі workspace
+}
+```
+
+### З кастомним git-раннером (тестовий сценарій)
+
+```js
+const fakeGit = async args => {
+  if (args[0] === 'describe') return '@scope/pkg@1.2.3\n'
+  if (args[0] === 'log') return 'fix: foo\nchore: bar\n\n'
+  return null
+}
+const change = await synthesizeChangeFromCommits('@scope/pkg', 'packages/pkg', { runGit: fakeGit })
+// => { bump: 'patch', section: 'Changed', description: 'fix: foo; chore: bar' }
+```
+
+### Сценарій «весь репо» (root-workspace)
+
+```js
+// ws === '.' → pathspec не додається, log читає історію всього репо
+await synthesizeChangeFromCommits('root', '.')
+```
+
+### Діаграма послідовності
+
+```
+caller
+  │
+  ├─ runGit(['describe', '--tags', '--abbrev=0', '--match', `<name>@*`, 'HEAD'])
+  │     └─→ null  ───► return null  (bootstrap)
+  │     └─→ '<tag>\n'
+  │
+  ├─ runGit(['log', '--no-merges', '--format=%s', '<tag>..HEAD', '--', '<ws>/'])
+  │     └─→ null | ''   ───► return null  (no commits in scope)
+  │     └─→ 'subj1\nsubj2\n…'
+  │
+  └─ return { bump: 'patch', section: 'Changed', description: 'subj1; subj2; …' }
+```
+
+### Ключові випадки повернення `null`
+
+| Випадок   | Причина                                          | Реакція пайплайна                                       |
+| --------- | ------------------------------------------------ | ------------------------------------------------------- |
+| Bootstrap | Немає жодного тегу `<name>@*`                    | Не синтезувати fallback; перший реліз — вручну.         |
+| No-op     | Тег є, але `git log` у скоупі workspace порожній | У workspace немає релевантних змін → реліз не потрібен. |
+| Git error | Будь-яка помилка `git` (через тихий раннер)      | Інтерпретується як «нічого синтезувати», `null`.        |
+
+## Rebuild Test
+
+Перевірка контекстної повноти документа: за описом вище можна **відновити** ключові властивості реалізації без перегляду коду:
+
+1. Модуль ES (`.mjs`), імпортує `execFile` з `node:child_process` і `promisify` з `node:util`; створює `execFileAsync = promisify(execFile)`.
+2. Експортує дві іменовані функції: `defaultRunGit(cwd)` і `synthesizeChangeFromCommits(name, ws, opts)`. Default-експорту немає.
+3. `defaultRunGit(cwd)` повертає async-функцію `args => …`, що викликає `execFileAsync('git', args, { cwd })` у `try/catch`; в успіху — `stdout`, у будь-якій помилці — `null`.
+4. `synthesizeChangeFromCommits`:
+   - бере `runGit` з `opts.runGit ?? defaultRunGit(process.cwd())`;
+   - `git describe --tags --abbrev=0 --match \`${name}@\*\` HEAD`→`lastTagRaw`; `lastTag = lastTagRaw?.trim()`; якщо falsy — `return null`;
+   - `pathspec = ws === '.' ? [] : ['--', \`${ws}/\`]`;
+   - `git log --no-merges --format=%s \`${lastTag}..HEAD\` ...pathspec`→`logRaw`;
+   - `subjects = (logRaw ?? '').split('\n').map(s => s.trim()).filter(Boolean)`;
+   - якщо `subjects.length === 0` → `return null`;
+   - інакше `return { bump: 'patch', section: 'Changed', description: subjects.join('; ') }`.
+5. `bump` зашитий як `'patch'`, `section` — як `'Changed'`; роздільник опису — `'; '`.
+6. Жодні винятки з git не пробиваються назовні — раннер обгортає їх у `null`, а `synthesizeChangeFromCommits` коректно деградує до `null` у всіх граничних кейсах.

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

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/rules/release/lib
+resource: npm/rules/release/lib/
+---
+
+# npm/rules/release/lib
+
+| Файл                              | Тип       |
+| --------------------------------- | --------- |
+| [aggregate.mjs](aggregate.md)     | JS Module |
+| [change-file.mjs](change-file.md) | JS Module |
+| [fallback.mjs](fallback.md)       | JS Module |

package/rules/release/lib/fallback.mjs

@@ -0,0 +1,48 @@
+/**
+ * Fallback (n-rules-release-design рішення 3): коли в workspace є релевантні зміни,
+ * але жодного change-файлу — синтезуємо один запис із commit-subjects від останнього
+ * релізного тегу `<name>@*`. Усі git-виклики через `runGit` (ін'єкція для тестів).
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * @param {string} cwd робочий каталог
+ * @returns {(args: string[]) => Promise<string | null>} тихий git-раннер (null при помилці)
+ */
+export function defaultRunGit(cwd) {
+  return async args => {
+    try {
+      const { stdout } = await execFileAsync('git', args, { cwd })
+      return stdout
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * @param {string} name ім'я пакета (для тегу `<name>@*`)
+ * @param {string} ws workspace (pathspec для `git log`; `.` → без обмеження шляху)
+ * @param {object} [opts] опції
+ * @param {(args: string[]) => Promise<string | null>} [opts.runGit] git-раннер
+ * @returns {Promise<{ bump: string, section: string, description: string } | null>} синтезований запис або null
+ */
+export async function synthesizeChangeFromCommits(name, ws, opts = {}) {
+  const runGit = opts.runGit ?? defaultRunGit(process.cwd())
+  const lastTagRaw = await runGit(['describe', '--tags', '--abbrev=0', '--match', `${name}@*`, 'HEAD'])
+  const lastTag = lastTagRaw?.trim()
+  // Bootstrap: якщо жодного попереднього тегу немає — перший реліз зроблено вручну;
+  // fallback-синтез не запускаємо, щоб не подвоїти bump.
+  if (!lastTag) return null
+  const pathspec = ws === '.' ? [] : ['--', `${ws}/`]
+  const logRaw = await runGit(['log', '--no-merges', '--format=%s', `${lastTag}..HEAD`, ...pathspec])
+  const subjects = (logRaw ?? '')
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
+  if (subjects.length === 0) return null
+  return { bump: 'patch', section: 'Changed', description: subjects.join('; ') }
+}

package/rules/release/main.json

@@ -0,0 +1 @@
+{}

package/rules/release/main.mdc

@@ -0,0 +1,10 @@
+---
+description: n-rules release та @7n/n ch — автоматичний version-bump і CHANGELOG із change-файлів
+version: '1.0'
+globs: "**/package.json,**/pyproject.toml,**/CHANGELOG.md,**/.changes/*.md"
+alwaysApply: false
+---
+
+Версія та CHANGELOG **не редагуються вручну**. Єдиний артефакт зміни — **change-файл** (`npx @7n/n ch [--bump <major|minor|patch>] [--section <Added|Changed|Fixed|Removed>] [--message "<…>"]`). Bump `version` і генерацію секції CHANGELOG виконує `n-rules release` у CI на `main`.
+
+Детальна модель (база порівняння, формат CHANGELOG, post-release-інваріант) — у `n-changelog.mdc`.