@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,200 @@
+# `change-file.mjs`
+
+Модуль для роботи з одиничним **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,203 @@
+# fallback.mjs
+
+## Огляд
+
+Модуль `fallback.mjs` реалізує **третє рішення** з ADR `n-cursor-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/rust/docs/fix.md

@@ -0,0 +1,129 @@
+# `fix.mjs` — entry-point правила `rust`
+
+## Огляд
+
+Файл `npm/rules/rust/fix.mjs` — мінімальний adapter, який реєструє правило `rust` у двох ролях одночасно:
+
+- **library mode** — модуль експортує функцію `run(ctx)`, яку викликає CLI-оркестратор пакета `@nitra/cursor` (через `import + run(ctx)`), передаючи спільний контекст прогону (наприклад, `walkCache` для шерингу обходу файлів між правилами).
+- **standalone mode** — якщо файл запущено напряму (`bun npm/rules/rust/fix.mjs`), він поводиться як повний еквівалент команди `npx @nitra/cursor fix rust`: підвантажує конфіг, застосовує whitelist, друкує summary та повертає процесу exit-code.
+
+Уся реальна логіка правила (порядок фаз: `applies → JS-concerns → policy → mdc-refs`) інкапсульована у двох helper-модулях зі спільної бібліотеки `npm/scripts/lib/`. Цей файл — лише тонкий wrapper, що з'єднує конвенцію розташування (`npm/rules/<id>/fix.mjs`) із цими helpers і не містить власної бізнес-логіки правила `rust`.
+
+Файл слідує усталеному в репозиторії патерну "двох ролей `fix.mjs`": library + standalone — тому самий код використовується і коли правило виконується як частина мульти-rule прогону, і коли його запускають окремо для дебагу/CI.
+
+## Експорти / API
+
+Модуль експортує одну іменовану функцію:
+
+| Експорт | Тип                                      | Призначення                                                        |
+| ------- | ---------------------------------------- | ------------------------------------------------------------------ |
+| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-mode entry: запуск правила `rust` зі стандартним pipeline. |
+
+Default-експорту немає. Імпортний шлях для зовнішніх споживачів — `@nitra/cursor/rules/rust/fix.mjs` (або еквівалентний relative-шлях усередині монорепо).
+
+Тип `RuleContext` визначений у `npm/scripts/lib/run-standard-rule.mjs` і реекспортується через JSDoc-`import('...')`-тип у сигнатурі `run`.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx)
+```
+
+- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
+- **Параметри:**
+  - `ctx` — _(опційний)_ контекст прогону, який передає CLI-оркестратор. Структура задана в `run-standard-rule.mjs` (`RuleContext`); типове поле — `walkCache`, що дозволяє декільком правилам розділяти один обхід файлової системи в межах однієї сесії. Якщо `ctx` не передано (наприклад, у standalone), `runStandardRule` сам ініціалізує внутрішні структури.
+- **Повертає:** `Promise<number>`
+  - `0` — правило завершилось успішно, порушень не знайдено.
+  - `1` — знайдено порушення (стандартний exit-code для CI/IDE).
+- **Алгоритм:** делегує виконання у `runStandardRule(import.meta.dirname, ctx)`. Перший аргумент — абсолютний шлях до каталогу правила (`npm/rules/rust/`), завдяки якому `runStandardRule` сам читає `meta.json`, виявляє підкаталоги `js/`, `policy/`, `coverage/`, `lib/` і відповідний `.mdc`-файл (`rust.mdc`) для розв'язання refs.
+- **Side effects:**
+  - Власних side effects не має; усі ефекти (I/O, лог, walk-cache) виникають усередині `runStandardRule`.
+  - Не модифікує `process.exit`, не пише в `process.stderr/stdout` напряму — це робить уже helper або стандартний CLI summary.
+
+### Standalone entry-block
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Тип:** top-level side-effect блок (виконується при імпорті модуля).
+- **Умова входу:** `isRunAsCli(import.meta.url)` повертає `true`, тобто файл виконано як головний модуль (`bun fix.mjs` / `node fix.mjs`), а не імпортовано з іншого модуля.
+- **Що робить:** викликає `runRuleCli(import.meta.dirname)` — повний CLI-pipeline пакета `@nitra/cursor` для одного правила: завантаження конфіга, застосування whitelist, друк summary, повернення числового exit-code. Результат передається у `process.exit(...)`, щоб процес завершився з відповідним кодом для CI/IDE.
+- **Чому два eslint-disable:**
+  - `n/no-process-exit` (плагін `eslint-plugin-n`) — забороняє виклик `process.exit` у бібліотечному коді.
+  - `unicorn/no-process-exit` (плагін `eslint-plugin-unicorn`) — теж забороняє `process.exit`.
+    Тут вони відключені свідомо: standalone entry-point має повертати exit-code, інакше неможливо коректно інтегруватися з CI/IDE runners (вони чекають саме на код виходу процесу).
+- **Side effects:** завершує процес викликом `process.exit(code)`.
+
+## Залежності
+
+### Внутрішні (relative imports)
+
+| Шлях                                      | Що використовується        | Роль                                                                                                                                       |
+| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Helpers для standalone-режиму: детекція "запущено як CLI" та повний CLI-pipeline одного правила.                                           |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний рантайм правила: оркестрація фаз `applies → JS-concerns → policy → mdc-refs`. JSDoc-тип `RuleContext` теж імпортується звідси. |
+
+### Зовнішні
+
+Прямих залежностей від npm-пакетів немає. Усі external-залежності (наприклад, `fast-glob`, ESLint API тощо) інкапсульовані всередині `runStandardRule` / `runRuleCli` і сюди не "протікають".
+
+### Runtime/Node API
+
+- `import.meta.dirname` — стандартний Node.js / Bun API; використовується для передачі абсолютного шляху до каталогу правила в helpers.
+- `import.meta.url` — використовується `isRunAsCli` для порівняння з `process.argv[1]`.
+- `process.exit(code)` — завершення процесу в standalone-режимі.
+- `await` на top level — потребує Node ≥ 14.8 (ESM top-level await) або Bun (підтримує з коробки).
+
+### Конвенції розташування
+
+Файл лежить за конвенцією `npm/rules/<id>/fix.mjs`, де `<id> = rust`. Поряд із ним мають існувати:
+
+- `meta.json` — метадані правила (читається `runStandardRule`/`runRuleCli`).
+- `rust.mdc` — людинозрозумілий опис правила (для mdc-refs).
+- Підкаталоги `js/`, `policy/`, `coverage/`, `lib/` — фази правила.
+- `docs/` — каталог із згенерованою документацією (включно з цим файлом).
+
+## Потік виконання / Використання
+
+### Сценарій A: виклик з CLI-оркестратора (library mode)
+
+1. Оркестратор `@nitra/cursor` сканує `npm/rules/*/fix.mjs`.
+2. Для правила `rust` виконує `import('npm/rules/rust/fix.mjs')`.
+3. Викликає `run(ctx)`, передаючи спільний `RuleContext` (включно з `walkCache`).
+4. `run` повертає `runStandardRule(import.meta.dirname, ctx)`, який послідовно виконує фази:
+   - **applies** — фільтрує файли, до яких правило застосовне.
+   - **JS-concerns** — запускає JS-аспекти правила (`js/`-фолдер).
+   - **policy** — застосовує policy-checks (`policy/`-фолдер).
+   - **mdc-refs** — валідує посилання в `rust.mdc`.
+5. Результуючий `Promise<number>` (`0` або `1`) повертається оркестратору.
+6. Оркестратор агрегує exit-коди всіх правил і повертає єдиний summary.
+
+### Сценарій B: standalone-запуск
+
+1. Користувач/CI виконує `bun npm/rules/rust/fix.mjs` (або `node npm/rules/rust/fix.mjs`).
+2. Модуль завантажується; `isRunAsCli(import.meta.url)` повертає `true`.
+3. Виконується `await runRuleCli(import.meta.dirname)`:
+   - читає конфіг проєкту,
+   - застосовує whitelist шляхів,
+   - усередині сам викликає `runStandardRule` (або еквівалент),
+   - друкує summary в stdout.
+4. Отриманий числовий exit-code передається в `process.exit(code)`.
+5. Процес завершується кодом `0` (ok) або `1` (порушення) — CI/IDE підхоплюють статус.
+
+### Як додавати/змінювати поведінку
+
+- **НЕ** додавати бізнес-логіку правила прямо в цей файл — він має лишатись тонким wrapper'ом.
+- Зміни порядку фаз або їх складу — у `runStandardRule` (спільно для всіх стандартних правил).
+- Зміни CLI-флагів / summary / whitelist — у `runRuleCli`.
+- Зміни специфічні для правила `rust` — у відповідних підкаталогах (`js/`, `policy/`, `coverage/`, `lib/`) і файлі `rust.mdc`.
+
+### Контракт із оркестратором
+
+- Експорт `run` повинен бути **функцією** (не stream/generator) і повертати `Promise<number>`.
+- Не повинен викидати unhandled rejections — усі помилки обгортаються всередині `runStandardRule`.
+- Exit-коди суворо `0` або `1` (інші значення оркестратор може інтерпретувати як збій).