@nitra/cursor 3.21.1 → 3.23.0

package/rules/rego/js/docs/lint.md

@@ -0,0 +1,118 @@
+# lint.mjs
+
+## Огляд
+
+Файл `npm/rules/rego/js/lint.mjs` — це тонкий ESM-адаптер, що виконує роль CI-кроку (`lint`) для правила `rego` в монорепо. Він не містить власної логіки перевірки чи парсингу, а лише делегує виклик у вже існуючий CLI-модуль правила — `../lint/lint.mjs`. Файл існує задля відповідності уніфікованому контракту CI-кроків (`lint(files?)`), де очікується експорт функції `lint` з певною сигнатурою.
+
+Ключова особливість: режим перевірки **per-file** для правила `rego` не підтримується — аналіз завжди виконується на всьому репозиторії (whole-repo). Тому параметр `files`, який зазвичай передається CI-фреймворком у крок `lint`, тут навмисно ігнорується (на що вказує префікс `_` у назві аргументу — `_files`). Це маркер для лінтерів та читачів коду, що значення параметра не використовується.
+
+Файл є частиною інфраструктури правил (`.cursor/rules/n-rego.mdc`, `.cursor/rules/n-ci4.mdc`) і служить мостом між уніфікованою CI-сигнатурою кроків та конкретною реалізацією перевірки Rego-файлів.
+
+## Експорти / API
+
+Файл експортує одну іменовану асинхронну функцію:
+
+| Експорт | Тип                                                 | Призначення                                          |
+| ------- | --------------------------------------------------- | ---------------------------------------------------- |
+| `lint`  | `async function(files?: string[]): Promise<number>` | CI-крок для лінтингу Rego-файлів; повертає exit code |
+
+Default-експорт відсутній. Експорт іменований, що відповідає конвенції CI-кроків у проєкті (де runner імпортує саме `{ lint }`).
+
+## Функції
+
+### `lint(_files)`
+
+#### Сигнатура
+
+```js
+export async function lint(_files)
+```
+
+#### Параметри
+
+| Параметр | Тип                     | Обов'язковий | Опис                                                                                                                                                                               |
+| -------- | ----------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_files` | `string[] \| undefined` | ні           | Список файлів для перевірки. **Ігнорується** — `rego`-лінтер не має per-file режиму та виконує whole-repo аналіз. Префікс `_` сигналізує, що параметр свідомо не використовується. |
+
+#### Повертає
+
+`Promise<number>` — exit code від `runLintRego()`:
+
+- `0` — лінтинг пройшов без помилок;
+- ненульове значення — виявлено порушення або стався збій під час перевірки.
+
+Конкретні значення коду визначає реалізація `runLintRego` у `../lint/lint.mjs` — цей файл лише транслює його далі.
+
+#### Side effects
+
+Сама функція `lint` не має прямих побічних ефектів — вона не пише у файлову систему, не звертається до мережі, не модифікує глобальний стан і не виводить нічого у консоль. Усі побічні ефекти (виклики `opa`/`regal`, читання Rego-файлів, друк діагностики, можливі тимчасові файли тощо) реалізовані всередині `runLintRego` із сусіднього модуля `../lint/lint.mjs` та повністю інкапсульовані там.
+
+#### Винятки
+
+Функція не має власних `try`/`catch`. Якщо `runLintRego()` відхилить проміс (`reject`) або викине синхронну помилку, виняток прозоро прокинеться вгору до викликача (зазвичай — CI-runner, який очікує саме на exit code).
+
+## Залежності
+
+### Внутрішні (relative)
+
+| Імпорт        | Шлях               | Призначення                                                                                                                         |
+| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `runLintRego` | `../lint/lint.mjs` | Реалізація whole-repo лінтингу Rego-файлів — фактично виконує перевірку та повертає exit code. Цей файл є єдиною залежністю модуля. |
+
+### Зовнішні
+
+Зовнішніх npm-залежностей файл напряму не використовує. Усі сторонні інструменти (наприклад, `opa`, `regal` тощо) транзитивно підключаються через `runLintRego`.
+
+### Runtime
+
+ESM-модуль (`.mjs`), потребує Node.js / Bun з підтримкою native ESM та `async/await`.
+
+## Потік виконання / Використання
+
+### Послідовність дій
+
+1. CI-runner (наприклад, фреймворк CI-кроків `n-ci4`) виявляє файл як крок `lint` правила `rego`.
+2. Runner викликає `lint(files)` — передає або список змінених файлів, або `undefined`, залежно від режиму запуску.
+3. Функція ігнорує аргумент `_files` і одразу викликає `runLintRego()` без параметрів.
+4. `runLintRego()` повертає `Promise<number>` із exit code; `lint` повертає цей самий проміс (через `return` в `async`-функції — фактично awaits та віддає значення).
+5. Runner отримує exit code і інтерпретує його як результат CI-кроку.
+
+### Контрактна позиція в системі правил
+
+Файл реалізує уніфікований інтерфейс CI-кроку `lint(files?)`, очікуваний фреймворком правил репозиторію (`n-ci4`). Завдяки тонкому шару адаптації:
+
+- сам runner може бути неуважним до особливостей правила (per-file vs whole-repo);
+- логіка перевірки залишається інкапсульованою у `../lint/lint.mjs` і може використовуватися як з CI, так і з CLI напряму;
+- зміна реалізації `runLintRego` не вимагає правок цього файла.
+
+### Приклад використання
+
+```js
+import { lint } from './npm/rules/rego/js/lint.mjs'
+
+// CI-режим: список файлів є, але буде проігнорований
+const exitCode = await lint(['policy/a.rego', 'policy/b.rego'])
+process.exit(exitCode)
+
+// Або без аргументів — поведінка ідентична
+const code2 = await lint()
+process.exit(code2)
+```
+
+### Що НЕ робить цей файл
+
+- Не парсить аргументи командного рядка — це не CLI-entrypoint.
+- Не фільтрує файли за розширенням — фільтрація (за потреби) — справа `runLintRego`.
+- Не агрегує помилки кількох інструментів — повертає лише підсумковий exit code.
+- Не пише у `stdout`/`stderr` — увесь вивід походить із `runLintRego`.
+
+## Rebuild Test
+
+Документація достатня, щоб переписати файл з нуля без перегляду оригіналу:
+
+- Модуль ESM (`.mjs`).
+- Імпорт: `runLintRego` із `../lint/lint.mjs`.
+- Один іменований експорт — `async function lint(_files)`.
+- Тіло: `return runLintRego()` (виклик без аргументів).
+- JSDoc: параметр `_files` — `string[] | undefined`, описаний як ігнорований (whole-repo аналіз); повертає `Promise<number>` (exit code).
+- Коментар верхнього рівня: пояснює, що це CI-крок `rego`, делегує у CLI правила, per-file режиму немає, `files` ігнорується.

package/rules/rego/lint/docs/lint.md

@@ -0,0 +1,204 @@
+# lint.mjs — Лінт Rego-полісі (`opa` + `regal` + опційний `conftest`)
+
+## Огляд
+
+Модуль реалізує лінт-крок для Rego-полісі пакета `@nitra/cursor`, який живуть у каталозі
+`npm/rules/<id>/policy/<concern>/`. Він послідовно запускає три інструменти й повертає код
+виходу першого, що впав:
+
+1. `opa check --strict` — компіляція Rego з типами та строгим режимом (ловить мертвий код,
+   неоднозначні правила, незадекларовані змінні).
+2. `regal lint` — статичний лінтер стилю/ідіоматичності Rego (v0-синтаксис, неявні set-rules,
+   відхилення від `rego.v1`, плюс правила категорій bugs/idiomatic/performance — див.
+   `https://docs.styra.com/regal`).
+3. `conftest verify` — опційно: виконує `test_*` правила у `*_test.rego` (юніт-тести
+   полісі). Якщо `conftest` відсутній у `PATH`, крок пропускається без помилки (з
+   повідомленням, як його встановити).
+
+Бінарники `opa` й `regal` резолвляться через `ensureTool` (`PATH` → локальний кеш → автоматичне
+встановлення через `brew`/`scoop`/GitHub Release → hard-fail). `conftest` шукається лише в
+`PATH` через `resolveCmd` без авто-install.
+
+Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) описаний
+у `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд». Публічна CLI-форма
+обгорнута в `withLock('lint-rego')` з дедуплікацією за станом git-дерева.
+
+Файл одночасно є ESM-модулем (експортує функції) і CLI-точкою входу: якщо запущений напряму
+(`isRunAsCli`), виконує `await runLintRego()` і виставляє `process.exitCode`.
+
+## Експорти / API
+
+Модуль експортує два символи:
+
+| Експорт            | Тип                          | Призначення                                                                                                                                             |
+| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runLintRegoSteps` | named function               | Внутрішня форма без локу: запускає три кроки в заданому `cwd`. Призначена для тестів у тимчасових каталогах, де потрібен fresh-прогон без дедуплікації. |
+| `runLintRego`      | named const (arrow function) | Публічна CLI-форма: серіалізує виконання через `withLock('lint-rego')` + дедуп за станом git-дерева (через `runStandardLint`).                          |
+
+Також модуль має side-effect при прямому запуску: якщо `isRunAsCli(import.meta.url)` повертає
+`true`, виконується `await runLintRego()` із записом результату в `process.exitCode`.
+
+## Функції
+
+### `runStep(bin, args, cwd)`
+
+Внутрішня (не експортована) допоміжна функція. Запускає процес із успадкованим `stdio`, щоб
+вивід виглядав як прямий виклик у shell, і пре-логує команду користувачу.
+
+- **Сигнатура:** `runStep(bin: string, args: string[], cwd: string) => number`
+- **Параметри:**
+  - `bin` — абсолютний шлях до бінарника (`opa`, `regal`, `conftest`).
+  - `args` — масив аргументів командного рядка.
+  - `cwd` — робочий каталог для дочірнього процесу.
+- **Повертає:** код виходу (`0` — OK). Якщо `spawnSync` не зміг запустити бінарник
+  (`result.error`), повертає `1`.
+- **Side effects:**
+  - Друкує рядок `▶ <bin> <args...>` у `stdout` (логування команди).
+  - У випадку помилки запуску пише `❌ Не вдалося запустити <bin>: <message>\n` у `stderr`.
+  - Породжує дочірній процес через `spawnSync` з `stdio: 'inherit'` і `env: process.env`
+    (наслідування поточного середовища).
+
+### `runLintRegoSteps(cwd?)`
+
+Експортована функція, що виконує послідовність кроків лінту без локу.
+
+- **Сигнатура:** `runLintRegoSteps(cwd?: string) => number`
+- **Параметри:**
+  - `cwd` — робочий каталог (за замовчуванням `process.cwd()`).
+- **Повертає:** число — код виходу.
+  - `0` — усі кроки OK або жодної цілі не знайдено (skip).
+  - Ненульове — код виходу першого кроку, що впав (раннє повернення).
+- **Алгоритм:**
+  1. Резолвить `root = resolve(cwd)`.
+  2. `opa = ensureTool('opa')` — гарантує наявність `opa` (інакше `ensureTool` hard-fail).
+  3. `regal = ensureTool('regal')` — те саме для `regal`.
+  4. Фільтрує `LINT_TARGETS` за наявністю на диску (через `existsSync`). Якщо порожньо —
+     повертає `0` (skip).
+  5. `runStep(opa, ['check', '--strict', ...targets], root)` — якщо `!== 0`, повертає цей код.
+  6. `runStep(regal, ['lint', ...targets], root)` — якщо `!== 0`, повертає цей код.
+  7. `conftest = resolveCmd('conftest')` — якщо `null`, друкує інформативне повідомлення про
+     пропуск кроку й рекомендацію зі встановлення, повертає `0`.
+  8. Інакше `runStep(conftest, ['verify', ...targets.flatMap(t => ['-p', t])], root)` —
+     повертає його код виходу.
+- **Side effects:** виконує `ensureTool` (може встановити бінарник або hard-fail), породжує
+  дочірні процеси з успадкованим `stdio`, пише в `stdout`/`stderr`.
+
+### `runLintRego()`
+
+Експортована публічна CLI-форма (arrow-const).
+
+- **Сигнатура:** `runLintRego() => Promise<number>`
+- **Параметри:** немає.
+- **Повертає:** `Promise<number>` — код виходу.
+- **Поведінка:** делегує в `runStandardLint(import.meta.dirname, () => runLintRegoSteps())`.
+  `runStandardLint` забезпечує:
+  - Серіалізацію через `withLock('lint-rego')` (іменем серіалізатора виступає назва каталогу
+    `lint`, отримана з `import.meta.dirname` — конвенція `runStandardLint`).
+  - Дедуплікацію проти попереднього прогону за станом git-дерева.
+- **Side effects:** через делегування — ті самі, що в `runLintRegoSteps`, плюс файлові
+  side-effects лок-файлу й кешу станів від `runStandardLint`.
+
+### CLI-вхід (на верхньому рівні модуля)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = await runLintRego()
+}
+```
+
+- Виконується лише при прямому запуску модуля як скрипта (а не при імпорті).
+- Очікує проміс `runLintRego()` і записує отриманий код у `process.exitCode` (не викликає
+  `process.exit` явно, щоб лог-флаш не обрізався).
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:child_process` → `spawnSync` — синхронний запуск дочірніх процесів із `stdio: 'inherit'`.
+- `node:fs` → `existsSync` — перевірка наявності каталогів-цілей.
+- `node:path` → `resolve` — нормалізація абсолютних шляхів.
+
+### Внутрішні модулі (відносні шляхи від `npm/rules/rego/lint/lint.mjs`)
+
+- `../../../scripts/cli-entry.mjs` → `isRunAsCli` — детектор «запущений напряму як CLI».
+- `../../../scripts/lib/ensure-tool.mjs` → `ensureTool` — резолв бінарників (`PATH` → кеш →
+  авто-install brew/scoop/GitHub Release → hard-fail).
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd` — м'який пошук команди в `PATH`
+  (повертає шлях або `null`, без авто-install і без hard-fail).
+- `../../../scripts/lib/run-standard-lint.mjs` → `runStandardLint` — обгортка з локом і
+  дедуплікацією для лінт-кроків.
+
+### Зовнішні бінарники (системні)
+
+- `opa` — обов'язковий, авто-install через `ensureTool` (Open Policy Agent CLI).
+- `regal` — обов'язковий, авто-install через `ensureTool` (Styra Regal lint CLI).
+- `conftest` — опційний, лише з `PATH` (без авто-install). За відсутності — `verify`
+  пропускається.
+
+### Константи модуля
+
+- `LINT_TARGETS = ['npm/rules']` — список відносних шляхів-цілей, що передаються в усі три
+  інструменти. Перед запуском фільтрується за `existsSync`.
+
+## Потік виконання / Використання
+
+### Як модуль (програмний імпорт)
+
+```js
+import { runLintRego, runLintRegoSteps } from './npm/rules/rego/lint/lint.mjs'
+
+// CLI-форма (з локом і дедуплікацією) — рекомендована для оркестрації
+const code = await runLintRego()
+
+// Внутрішня форма (без локу) — для тестів у тимчасових каталогах
+const codeFresh = runLintRegoSteps('/tmp/fixture-cwd')
+```
+
+### Як CLI (прямий запуск)
+
+```sh
+node npm/rules/rego/lint/lint.mjs
+```
+
+При прямому запуску модуль викликає `runLintRego()` і виставляє `process.exitCode` відповідно
+до результату. Це дозволяє оркестратору лінту (наприклад, кореневому `bun run lint`)
+підхопити цей файл як один із кроків і отримати правильний код виходу процесу.
+
+### Логічний потік (один прогон `runLintRegoSteps`)
+
+1. Резолв `cwd → root`.
+2. `ensureTool('opa')` — повертає шлях до бінарника або hard-fail (з повідомленням
+   `ensureTool`).
+3. `ensureTool('regal')` — те саме.
+4. Перевірка цілей: `LINT_TARGETS.filter(existsSync)`. Порожньо → `return 0` (skip).
+5. `opa check --strict <targets...>` → `runStep`. `!== 0` → early-return з цим кодом.
+6. `regal lint <targets...>` → `runStep`. `!== 0` → early-return з цим кодом.
+7. `resolveCmd('conftest')`:
+   - `null` → інформативний `console.log` із рекомендацією встановлення, `return 0`.
+   - інакше → `conftest verify -p <t1> -p <t2> ...` через `runStep`; повертається його код.
+8. Повернутий код піднімається до `runLintRego` → у `runStandardLint` → у `process.exitCode`
+   (для CLI-режиму).
+
+### Семантика помилок і пропусків
+
+- **Усі цілі відсутні** → skip із кодом `0` (немає чого лінтити на ранніх стадіях/у мінімальних
+  фікстурах).
+- **`opa`/`regal` відсутні** → hard-fail усередині `ensureTool` (без авто-install або з
+  невдалим авто-install).
+- **`opa check` або `regal lint` повернули `!== 0`** → раннє повернення з цим кодом; наступні
+  кроки не виконуються.
+- **`conftest` відсутній у `PATH`** → лог-нотатка про пропуск, фінальний код `0` (вважається
+  не помилкою — юніт-тести полісі опційні в локальному середовищі; у CI рекомендовано
+  встановлювати `conftest`).
+- **`spawnSync` не зміг запустити бінарник** (`result.error`) → лог `❌ Не вдалося запустити
+...` у `stderr`, `runStep` повертає `1`.
+
+### Контекст у проєкті
+
+- Цілі лінту — каталог `npm/rules` пакета `@nitra/cursor`, де живуть Rego-полісі у
+  `npm/rules/<id>/policy/<concern>/`. Усі три інструменти приймають один шлях і рекурсивно
+  знаходять `.rego`, ігноруючи інші розширення (наприклад, `target.json` чи template-фіх).
+- `opa` додатково потрібен VS Code-розширенню `tsandall.opa` (LSP, format-on-save через
+  `opa fmt`) — деталі в `mdc/rego.mdc`.
+- Канон патерну `lint-*` із серіалізацією через `runStandardLint` (а не прямий `withLock`) —
+  див. `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».

package/rules/release/docs/change.md

@@ -0,0 +1,185 @@
+# `change.mjs` — створення одного change-файлу
+
+## Огляд
+
+Модуль реалізує CLI-команду `n-cursor change`, яка створює **один** change-файл у каталозі `<ws>/.changes/<timestamp>-<rand>.md` усередині конкретного workspace монорепо. Файл містить мінімальний YAML-frontmatter (`bump`, `section`) та текст опису зміни.
+
+Призначення — замінити ручне редагування `CHANGELOG.md` під час feature-флоу: розробник (або агент) додає декларативний запис про зміну, а агрегація у фінальний `CHANGELOG.md` відбувається пізніше в CI (відповідно до правила `n-changelog.mdc` v3.0).
+
+Файл експонує дві функції:
+
+- `writeChange(...)` — програмний API для запису одного change-файлу;
+- `runChangeCli(args)` — обгортка для запуску з аргументів командного рядка.
+
+Серіалізація, парсинг, валідація та формування імені файлу делеговані сусідньому модулю `./lib/change-file.mjs`.
+
+## Експорти / API
+
+| Експорт        | Тип              | Призначення                                                                                                                 |
+| -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `writeChange`  | `async function` | Створює один change-файл у `<ws>/.changes/` та повертає його шлях відносно workspace.                                       |
+| `runChangeCli` | `async function` | Парсить CLI-аргументи (`--bump`, `--section`, `--message`, `--ws`), викликає `writeChange` і повертає exit-код для процесу. |
+
+Модуль не має експортованих констант чи класів, лише ці дві функції. `default`-експорт відсутній — використовуються лише іменовані експорти.
+
+## Функції
+
+### `writeChange({ bump, section, message, ws, cwd })`
+
+Програмний рівень: створює один change-файл і повертає його шлях, придатний для логування.
+
+**Сигнатура:**
+
+```js
+async function writeChange({
+  bump,           // string: 'major' | 'minor' | 'patch'
+  section,        // string: 'Added' | 'Changed' | 'Fixed' | 'Removed'
+  message,        // string: текст опису (буде обрізаний trim'ом)
+  ws = '.',       // string: відносний шлях workspace від cwd (за замовчуванням поточний)
+  cwd = process.cwd(), // string: корінь репозиторію
+}): Promise<string>
+```
+
+**Параметри:**
+
+- `bump` _(string, обов'язковий)_ — рівень semver-бампу. Дозволені значення: `major`, `minor`, `patch` (перевіряється у `parseChangeFile`).
+- `section` _(string, обов'язковий)_ — секція Keep a Changelog. Дозволені значення: `Added`, `Changed`, `Fixed`, `Removed`.
+- `message` _(string, обов'язковий)_ — людиночитаний опис зміни. Якщо `null/undefined`, перетворюється на порожній рядок; далі застосовується `trim()`. Порожній (після обрізки) опис призведе до помилки валідації.
+- `ws` _(string, необов'язковий, default `.`)_ — шлях workspace відносно `cwd`. Дозволяє писати change-файли в конкретний підпроект монорепо.
+- `cwd` _(string, необов'язковий, default `process.cwd()`)_ — корінь репозиторію. Винесений у параметр для тестованості.
+
+**Повертає:** `Promise<string>` — відносний шлях створеного файлу від кореня workspace (`ws`), у форматі `.changes/<timestamp>-<rand>.md`. Зауважте: шлях **не** включає сам `ws` — це робить його зручним для подальшого логування `join(ws, rel)`.
+
+**Side effects:**
+
+1. Серіалізує запис через `serializeChangeFile({ bump, section, description })`.
+2. **Валідує** серіалізований вміст через `parseChangeFile(content)` — це гарантує, що файл, який буде записаний, є валідним відповідно до тих самих правил, що використовуються при подальшому читанні. Невалідні `bump`/`section` чи порожній опис призведуть до `throw Error(...)` зі зрозумілим повідомленням українською.
+3. Створює каталог `<cwd>/<ws>/.changes/` (рекурсивно, `mkdir(..., { recursive: true })`) — не падає, якщо каталог уже існує.
+4. Генерує унікальне ім'я файлу через `newChangeFileName()` (timestamp + випадковий hex-суфікс, що захищає від колізій паралельних агентів у тій самій мілісекунді).
+5. Записує файл на диск (`writeFile`). Якщо файл випадково існує — буде перезаписаний (хоча колізія за іменем практично виключена через rand-суфікс).
+
+**Виняткові ситуації:**
+
+- Помилка валідації `parseChangeFile` (невалідні `bump`/`section`, порожній опис) — кидає `Error` із текстом помилки українською.
+- Помилки FS (наприклад, відсутність прав на створення каталогу) — кидаються як стандартні `Error` із Node.js.
+
+### `runChangeCli(args)`
+
+CLI-обгортка: розбирає аргументи, викликає `writeChange` і повертає exit-код. Не викликає `process.exit` — це робить виклична сторона (`bin`-скрипт).
+
+**Сигнатура:**
+
+```js
+async function runChangeCli(args: string[]): Promise<number>
+```
+
+**Параметри:**
+
+- `args` _(string[], обов'язковий)_ — масив аргументів CLI (зазвичай `process.argv.slice(2)`).
+
+**Розпізнавані прапори** (парсер мінімалістичний, не використовує бібліотеку):
+
+- `--bump <major|minor|patch>` — обов'язковий.
+- `--section <Added|Changed|Fixed|Removed>` — обов'язковий.
+- `--message "<опис>"` — обов'язковий.
+- `--ws <шлях>` — необов'язковий, default `.`.
+
+Кожен прапор шукається через `args.indexOf(flag)`; значення береться з наступного елемента (`args[i + 1]`). Якщо прапора немає, або він є останнім — значення `undefined`. Через таку реалізацію значення `--message`, що починається з тире (наприклад, `--message "--foo"`), розбереться коректно, але кілька прапорів з одним іменем не підтримуються (береться перше входження).
+
+**Повертає:** `Promise<number>` — exit-код:
+
+- `0` — успіх; у `stdout` пишеться `✅ <ws>/<rel>` (де `rel` — шлях, повернений `writeChange`).
+- `1` — помилка:
+  - Якщо бракує одного з обов'язкових прапорів (`--bump`, `--section`, `--message`) — у `stderr` пишеться рядок-підказка з повним usage-описом українською.
+  - Якщо `writeChange` кинув виняток — у `stderr` пишеться `❌ <message>` (для `Error` — `error.message`, для всього іншого — `String(error)`).
+
+**Side effects:**
+
+- Пише в `console.log` (`stdout`) на успіх.
+- Пише в `console.error` (`stderr`) на помилку.
+- Через `writeChange` — створює каталог і файл (див. вище).
+
+## Залежності
+
+### Зовнішні (Node.js core)
+
+- `node:fs/promises`:
+  - `mkdir` — рекурсивне створення `<ws>/.changes/`.
+  - `writeFile` — запис вмісту файлу.
+- `node:path`:
+  - `join` — побудова абсолютних і відносних шляхів (платформонезалежно).
+
+### Внутрішні (сусідній модуль `./lib/change-file.mjs`)
+
+- `CHANGES_DIR` _(string-константа `'.changes'`)_ — назва підкаталогу всередині workspace.
+- `newChangeFileName()` — генератор унікального імені файлу (`<Date.now()>-<3byte-hex>.md`).
+- `parseChangeFile(text)` — парсер + валідатор; використовується **тут** для валідації перед записом. Кидає `Error` зі зрозумілим текстом при невалідних `bump`, `section` або порожньому описі.
+- `serializeChangeFile({ bump, section, description })` — формує текст change-файлу: `---\nbump: ...\nsection: ...\n---\n<description>\n`.
+
+Валідні значення `bump` — `major|minor|patch`; валідні значення `section` — `Added|Changed|Fixed|Removed` (експортовані як `VALID_BUMPS` та `VALID_SECTIONS` у `change-file.mjs`).
+
+### Глобальні
+
+- `process.cwd()` — використовується як default для `cwd` у `writeChange`.
+- `console.log`, `console.error` — для CLI-виводу.
+
+## Потік виконання / Використання
+
+### Сценарій 1: програмний виклик `writeChange`
+
+```js
+import { writeChange } from './change.mjs'
+
+const rel = await writeChange({
+  bump: 'patch',
+  section: 'Fixed',
+  message: 'Fix off-by-one у валідаторі change-файлів',
+  ws: 'npm/rules/release'
+})
+// rel === '.changes/1735000000000-a1b2c3.md'
+```
+
+Послідовність кроків усередині:
+
+1. `description = (message ?? '').trim()`.
+2. `content = serializeChangeFile({ bump, section, description })` — формується текст із frontmatter.
+3. `parseChangeFile(content)` — перевіряє коректність (`bump`, `section`, непорожній опис); кидає `Error` за невалідних даних.
+4. `mkdir(join(cwd, ws, '.changes'), { recursive: true })` — створює каталог за потреби.
+5. `name = newChangeFileName()` — `Date.now() + 3-byte hex`.
+6. `writeFile(join(dir, name), content)` — атомарно записує файл.
+7. Повертає `join('.changes', name)` — шлях відносно `ws`.
+
+### Сценарій 2: запуск через CLI
+
+```bash
+n-cursor change \
+  --bump patch \
+  --section Fixed \
+  --message "Fix off-by-one у валідаторі change-файлів" \
+  --ws npm/rules/release
+```
+
+Послідовність кроків усередині `runChangeCli`:
+
+1. Витягуються чотири значення через локальну функцію `get(flag)`.
+2. Якщо бракує `--bump`, `--section` або `--message` — друкується usage-рядок у `stderr`, повертається `1`.
+3. У `try/catch` викликається `writeChange({ bump, section, message, ws })`.
+4. На успіх — `console.log('✅ <ws>/<rel>')`, return `0`.
+5. На виняток — `console.error('❌ <message>')`, return `1`.
+
+### Інтеграція з feature-флоу
+
+Файл є частиною release-інфраструктури (`npm/rules/release/`). Створені цією командою change-файли пізніше зчитуються через `readChangeFiles(ws)` з `./lib/change-file.mjs` під час релізу, агрегуються та конвертуються в записи `CHANGELOG.md`. Це усуває конфлікти злиття в `CHANGELOG.md` при паралельних feature-гілках: кожен PR додає **новий** файл із унікальним іменем замість редагування спільного.
+
+### Анти-колізія паралельних агентів
+
+Унікальність імені файлу гарантується комбінацією:
+
+- `Date.now()` — мілісекундний timestamp (порядок створення зберігається лексикографічно).
+- `randomBytes(3).toString('hex')` — 6 шістнадцяткових символів випадковості (≈ 16M варіантів) у межах однієї мілісекунди.
+
+Це робить безпечним одночасний запис із різних worktree чи паралельних агентів `n-cursor` без блокувань і без координації через FS.
+
+## Rebuild Test
+
+Документація відображає реальний стан файлу `change.mjs` (60 рядків, версія на момент створення документації): два іменовані експорти `writeChange` та `runChangeCli`, валідація через `parseChangeFile` після серіалізації, default `ws = '.'`, default `cwd = process.cwd()`, обов'язкові CLI-прапори `--bump`/`--section`/`--message`, опціональний `--ws`, exit-коди `0`/`1`, повідомлення українською з префіксами `✅`/`❌`. Залежності — `node:fs/promises` (`mkdir`, `writeFile`), `node:path` (`join`), `./lib/change-file.mjs` (`CHANGES_DIR`, `newChangeFileName`, `parseChangeFile`, `serializeChangeFile`).

package/rules/release/docs/fix.md

@@ -0,0 +1,119 @@
+# fix.mjs — точка входу правила `release`
+
+## Огляд
+
+Файл `npm/rules/release/fix.mjs` — це **точка входу (entry-point)** для правила `release` у системі правил репозиторію. Він виконує дві ролі:
+
+1. **Library mode** — експортує асинхронну функцію `run(ctx)`, яку викликають інші скрипти/оркестратори через `import + run(ctx)`. Делегує виконання у стандартний раннер правил `runStandardRule`.
+2. **CLI mode** — якщо файл запущено напряму як standalone-скрипт (`node fix.mjs` або через bun), він викликає `runRuleCli` й завершує процес кодом виходу (`process.exit`), щоб CI/IDE могли орієнтуватися на exit-code.
+
+Сам файл не містить жодної бізнес-логіки правила: всі перевірки (`applies → JS-concerns → policy → mdc-refs`) живуть у супровідних модулях каталогу `npm/rules/release/`, а оркестрацію виконує `runStandardRule`. Це — лише тонкий адаптер між іменем правила (визначається як ім'я каталогу через `import.meta.dirname`) і загальним механізмом запуску правил.
+
+## Експорти / API
+
+| Експорт | Тип                               | Призначення                                                                             |
+| ------- | --------------------------------- | --------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?): Promise<number>` | Library-mode запуск правила. Повертає exit-code: `0` — без порушень, `1` — є порушення. |
+
+Інших публічних експортів (типів, констант, default-експорту) файл не оголошує.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
+- **Параметри:**
+  - `ctx` (необов'язковий) — об'єкт типу `RuleContext`, імпортований із `../../scripts/lib/run-standard-rule.mjs`. Передається через виклик і несе спільний стан прогону (наприклад, `walkCache` для повторного використання обходу файлової системи між декількома правилами в одному прогоні). Якщо `ctx` не передано, стандартний раннер працює без зовнішнього кешу.
+- **Повертає:** `Promise<number>` — exit-code правила:
+  - `0` — порушень не знайдено;
+  - `1` — знайдені порушення (їх вже надруковано/зібрано раннером).
+- **Side effects:** Безпосередньо у тілі `run` сайд-ефектів немає — функція просто проксує виклик у `runStandardRule`. Усі реальні ефекти (читання файлів, обчислення `applies`, друк звітів, mdc-refs-перевірки) залежать від реалізації `runStandardRule` і відповідних check-модулів каталогу правила.
+- **Як визначає ім'я правила:** через `import.meta.dirname` — абсолютний шлях до каталогу `npm/rules/release/`. `runStandardRule` сам витягне з нього базове ім'я (`release`), знайде сусідні check-модулі (`check-*.mjs`, `applies.mjs`, `policy.*` тощо) й оркеструє конвеєр.
+
+### CLI-блок (модульний top-level код)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Не є функцією**, але це частина public-API файлу як CLI-скрипта.
+- **Умова виконання:** `isRunAsCli(import.meta.url)` повертає `true` лише коли файл є точкою входу процесу (а не імпортований як модуль). Це класичний еквівалент Node-патерна `require.main === module` для ESM.
+- **Дія:** Дочекатися `runRuleCli(import.meta.dirname)` (top-level `await`) і завершити процес із отриманим exit-code через `process.exit`.
+- **ESLint:** Спеціально дозволено `n/no-process-exit` і `unicorn/no-process-exit` — standalone-entry-point має повертати CI-сумісний код.
+- **Side effects:** Завершує Node-процес. Через top-level `await` блокує закриття модульного завантаження, поки CLI-прогін не завершиться.
+
+## Залежності
+
+Файл імпортує **дві** утиліти з локальної бібліотеки скриптів репозиторію (відносні шляхи до `npm/scripts/lib/`):
+
+- `../../scripts/lib/run-rule-cli.mjs`
+  - **`isRunAsCli(metaUrl: string): boolean`** — перевіряє, чи модуль викликано як CLI, а не як `import`.
+  - **`runRuleCli(ruleDir: string): Promise<number>`** — CLI-обгортка над раннером: парсить аргументи, налаштовує оточення прогону як standalone і повертає exit-code.
+- `../../scripts/lib/run-standard-rule.mjs`
+  - **`runStandardRule(ruleDir: string, ctx?: RuleContext): Promise<number>`** — стандартний конвеєр правила: дізнається, до яких файлів воно застосовується (`applies`), запускає JS-concerns (зазвичай файли `check-*.mjs`), policy-перевірки і `mdc-refs` (узгодженість з `.mdc`-документами), збирає й виводить порушення.
+  - **Тип `RuleContext`** — структура контексту прогону. Цей файл лише re-references його в JSDoc-`@param`.
+
+Жодних інших імпортів (зовнішніх npm-пакетів, Node core-модулів, динамічних `import()`) немає. Глобально використовується лише `process` (Node-built-in) — у CLI-блоці для `process.exit`.
+
+## Потік виконання / Використання
+
+### Library mode (виклик з іншого модуля)
+
+```js
+import { run } from './npm/rules/release/fix.mjs'
+
+const exitCode = await run(ctx) // ctx — опційний
+if (exitCode !== 0) {
+  // знайдено порушення правила release
+}
+```
+
+Послідовність:
+
+1. Викликач робить `import { run } from '.../release/fix.mjs'`.
+2. Виклик `run(ctx)` → `runStandardRule(import.meta.dirname, ctx)`.
+3. `runStandardRule` визначає каталог правила (`release`), знаходить і запускає сусідні модулі правила (`applies` → JS-concerns → policy → mdc-refs), обмінюючись із викликачем кешем через `ctx` (за наявності).
+4. Повертається числовий exit-code (`0`/`1`).
+
+### CLI mode (запуск файлу як скрипта)
+
+```bash
+node npm/rules/release/fix.mjs
+# або через bun
+bun run npm/rules/release/fix.mjs
+```
+
+Послідовність:
+
+1. Node/Bun стартує файл як точку входу — `isRunAsCli(import.meta.url)` повертає `true`.
+2. `await runRuleCli(import.meta.dirname)` запускає CLI-обгортку правила: парсить можливі аргументи/прапорці, ініціалізує стандартне середовище правила, всередині сам викликає аналог `runStandardRule` і повертає exit-code.
+3. `process.exit(<exitCode>)` завершує процес: CI-конвеєр або IDE-runner отримує `0` (успіх) або `1` (порушення).
+
+### Типове місце у системі правил
+
+Файл є членом сім'ї однотипних entry-point'ів `npm/rules/<rule-name>/fix.mjs`: кожне правило репозиторію має такий-самий шаблон («тонкий fix.mjs + сусідні check-модулі»). Це уніфікує запуск як з оркестратора (`bun run lint`, агрегатори, `runStandardRule`-цикли), так і з окремих CI-кроків чи дебагу через IDE.
+
+### Контракт повернення (exit-code)
+
+| Значення | Семантика                                                                 |
+| -------- | ------------------------------------------------------------------------- |
+| `0`      | Правило `release` не знайшло порушень для файлів, до яких воно `applies`. |
+| `1`      | Принаймні одне порушення (вже зафіксоване й виведене раннером).           |
+
+Інших кодів файл не вводить — будь-яка деталізація залежить від `runStandardRule` / `runRuleCli`.
+
+## Примітки щодо реалізації
+
+- **Чому `import.meta.dirname`, а не явне ім'я правила:** Це дає змогу шаблону `fix.mjs` бути ідентичним для всіх правил без захардкоджування рядкового імені — раннер сам ідентифікує правило за каталогом.
+- **Чому `await` на top-level:** Файл — ESM (`.mjs`), top-level `await` дозволений. У CLI-режимі потрібен синхронно-доступний exit-code до виклику `process.exit`.
+- **Чому виключені два ESLint-правила:** Обидва (`n/no-process-exit`, `unicorn/no-process-exit`) у проєкті заборонені для бібліотечного коду, але для standalone-entry-points exit-code — це і є контракт. Інлайн-коментар із поясненням обов'язковий за стилем репозиторію.
+- **Що файл свідомо не робить:** не парсить CLI-аргументи самостійно, не читає файли, не звертається до мережі, не імпортує бізнес-логіку правила напряму — все це делеговано в `run-standard-rule.mjs` та `run-rule-cli.mjs`.