@nitra/cursor 3.22.0 → 3.23.0

package/rules/adr/js/docs/hooks.md

@@ -0,0 +1,259 @@
+# hooks.mjs
+
+## Огляд
+
+Модуль `npm/rules/adr/js/hooks.mjs` — це скрипт-перевірник (check) правила `adr.mdc` пакета `@nitra/cursor`. Його завдання — переконатися, що в репозиторії-споживачі правильно встановлені та підтримуються ADR (Architecture Decision Records) Stop-hook'и для двох LLM-середовищ: Claude Code та Cursor Agent.
+
+Skрипт перевіряє, що:
+
+- Канонічні bash-скрипти `capture-decisions.sh` і `normalize-decisions.sh` присутні у `.claude/hooks/` цільового репо й байт-у-байт збігаються з версіями, які поставляє npm-пакет у `.claude-template/hooks/` (sync керує файлами повністю — будь-яке локальне редагування фіксується як `fail`).
+- Файл `.claude/settings.json` (project-shared конфіг Claude Code) існує — глибша валідація `hooks.Stop[]` робиться окремими policy-правилами (`npm/policy/adr/settings_json/`, `npm/policy/adr/settings_local_json/`).
+- Файл `.cursor/hooks.json` валідний JSON і містить у `hooks.stop[]` entries з `command`, що посилаються на обидва managed-скрипти (це дозволяє Cursor Agent також запускати ADR capture/normalize по `stop`-події).
+- `.gitignore` у корені покриває лог-файли `.claude/hooks/capture-decisions.log` і `.claude/hooks/normalize-decisions.log`, інакше runtime-логи потраплятимуть у git.
+- Наявність LLM CLI (`claude` або `cursor-agent`) у `PATH` — це **інформативна** перевірка (warning через `pass`-меседж), бо хук без CLI просто мовчки no-op'ає, а не фейлиться.
+
+Модуль експортує єдину асинхронну функцію `check(cwd)`, яка повертає numeric exit-code (0 = OK, 1 = є проблеми). Усе зведення результатів і форматування проходить через `createCheckReporter()` з `npm/scripts/lib/check-reporter.mjs`.
+
+## Експорти / API
+
+| Назва | Тип | Призначення |
+| ----- | --- | ----------- |
+| `check` | `async (cwd?: string) => Promise<number>` | Єдиний публічний експорт. Запускає весь набір перевірок правила `adr.mdc` для дерева репозиторію за шляхом `cwd` (default — `process.cwd()`). Повертає 0 при повному success або 1, якщо принаймні одна перевірка зафейлилась. |
+
+Усі інші ідентифікатори файлу (`HOOK_ARTIFACTS`, `PROJECT_SETTINGS_REL`, `CURSOR_HOOKS_REL`, `EOL_RE`, `BUNDLED_HOOKS_DIR`, `projectHookPath`, `projectLogPath`, `gitignoreLineCoversHookLog`, `checkHookScript`, `checkProjectSettings`, `readJsonSafe`, `cursorConfigHasStopHook`, `checkCursorHooks`, `checkGitignoreForLog`, `checkGitignore`, `isBinaryInPath`, `checkLlmCliAvailable`) — внутрішні (module-private).
+
+## Функції
+
+### `projectHookPath(scriptName)`
+
+- **Сигнатура:** `(scriptName: string) => string`
+- **Параметри:**
+  - `scriptName` — базове ім'я hook-скрипта (наприклад `capture-decisions.sh`).
+- **Повертає:** відносний шлях вигляду `.claude/hooks/<scriptName>`.
+- **Side effects:** немає (чиста функція конкатенації шляху).
+
+### `projectLogPath(logName)`
+
+- **Сигнатура:** `(logName: string) => string`
+- **Параметри:**
+  - `logName` — базове ім'я лог-файлу (наприклад `capture-decisions.log`).
+- **Повертає:** відносний шлях вигляду `.claude/hooks/<logName>`.
+- **Side effects:** немає.
+
+### `gitignoreLineCoversHookLog(line, logPath)`
+
+- **Сигнатура:** `(line: string, logPath: string) => boolean`
+- **Параметри:**
+  - `line` — одна нормалізована (trim) лінія з `.gitignore`.
+  - `logPath` — шлях до конкретного лог-файлу, який треба покрити.
+- **Повертає:** `true`, якщо рядок покриває цей лог. Підтримує матчі:
+  - точний шлях (`logPath`);
+  - glob `.claude/hooks/*.log` або `.claude/hooks/**/*.log`;
+  - широкий glob `*.log` або `**/*.log`.
+  - Порожні рядки та коментарі (`#…`) ігноруються.
+- **Side effects:** немає.
+
+### `checkHookScript(reporter, cwd, scriptName)`
+
+- **Сигнатура:** `async (reporter: CheckReporter, cwd: string, scriptName: string) => Promise<void>`
+- **Параметри:**
+  - `reporter` — інстанс, створений `createCheckReporter()`; з нього використовуються `pass` і `fail`.
+  - `cwd` — корінь репозиторію-споживача.
+  - `scriptName` — базове ім'я hook-скрипта.
+- **Повертає:** нічого (звітує результат через reporter).
+- **Поведінка:**
+  1. Якщо `<cwd>/.claude/hooks/<scriptName>` не існує → `fail` з підказкою запустити `npx @nitra/cursor`.
+  2. Якщо канонічний скрипт у пакеті (`<пакет>/.claude-template/hooks/<scriptName>`, обчислюється від `import.meta.url`) не існує → `fail` про перевстановлення `@nitra/cursor`.
+  3. Інакше читає обидва файли паралельно через `Promise.all`+`readFile` і порівнює як рядки UTF-8. При повному збігу — `pass`, інакше — `fail` із підказкою про повторний sync.
+- **Side effects:** файлова система — `existsSync`, `readFile`. Мутує внутрішній стан репортера.
+
+### `checkProjectSettings(reporter, cwd)`
+
+- **Сигнатура:** `(reporter: CheckReporter, cwd: string) => void`
+- **Параметри:**
+  - `reporter` — репортер для збору результату.
+  - `cwd` — корінь репозиторію.
+- **Повертає:** нічого.
+- **Поведінка:** перевіряє лише факт наявності `.claude/settings.json` (`existsSync`). `pass`, якщо файл є, інакше — `fail` з підказкою про `npx @nitra/cursor`. Глибша валідація структури `hooks.Stop[]` навмисно винесена в policy-правила `adr.settings_json` і `adr.settings_local_json`.
+- **Side effects:** одне `existsSync`.
+
+### `readJsonSafe(path)`
+
+- **Сигнатура:** `async (path: string) => Promise<unknown | null>`
+- **Параметри:**
+  - `path` — шлях до JSON-файлу.
+- **Повертає:** результат `JSON.parse(await readFile(path, 'utf8'))` або `null`, якщо читання чи парсинг кинули виняток.
+- **Side effects:** читання файлу; виняток придушується try/catch і конвертується у `null`.
+
+### `cursorConfigHasStopHook(config, marker)`
+
+- **Сигнатура:** `(config: unknown, marker: string) => boolean`
+- **Параметри:**
+  - `config` — попередньо розпарсений вміст `.cursor/hooks.json`.
+  - `marker` — підрядок, який має зустрічатися в `command` шуканого entry (зазвичай — шлях до managed hook-скрипта, наприклад `.claude/hooks/capture-decisions.sh`).
+- **Повертає:** `true`, якщо у `config.hooks.stop` є щонайменше один елемент-об'єкт з рядковим `command`, який містить `marker`. Кожен крок обходу (`config` — об'єкт-не-масив, `hooks` — об'єкт-не-масив, `stop` — масив) явно валідовано, тож не-канонічна структура повертає `false` без винятків.
+- **Side effects:** немає.
+
+### `checkCursorHooks(reporter, cwd)`
+
+- **Сигнатура:** `async (reporter: CheckReporter, cwd: string) => Promise<void>`
+- **Параметри:**
+  - `reporter` — репортер.
+  - `cwd` — корінь репо.
+- **Повертає:** нічого.
+- **Поведінка:**
+  1. Якщо `.cursor/hooks.json` не існує — `fail` (запропонувати `npx @nitra/cursor`).
+  2. Інакше парсить через `readJsonSafe`. Якщо повернуло `null` — `fail` ("не парситься як JSON").
+  3. Для кожного елемента `HOOK_ARTIFACTS` обчислює marker через `projectHookPath(scriptName)` і шукає stop-entry за допомогою `cursorConfigHasStopHook`. На кожен скрипт — окремий `pass` або `fail`.
+- **Side effects:** читання файлу, мутація стану репортера.
+
+### `checkGitignoreForLog(reporter, logName, gitignoreContent)`
+
+- **Сигнатура:** `(reporter: CheckReporter, logName: string, gitignoreContent: string) => void`
+- **Параметри:**
+  - `reporter` — репортер.
+  - `logName` — базове ім'я лог-файлу.
+  - `gitignoreContent` — наперед прочитаний вміст `.gitignore` (передається ззовні, щоб не читати файл двічі).
+- **Повертає:** нічого.
+- **Поведінка:** розбиває контент по `EOL_RE` (`\r?\n`), тримує кожну лінію та перевіряє через `gitignoreLineCoversHookLog`. Якщо хоч одна лінія покриває шлях — `pass`, інакше — `fail` з підказкою додати рядок.
+- **Side effects:** мутація стану репортера.
+
+### `checkGitignore(reporter, cwd)`
+
+- **Сигнатура:** `async (reporter: CheckReporter, cwd: string) => Promise<void>`
+- **Параметри:**
+  - `reporter` — репортер.
+  - `cwd` — корінь репо.
+- **Повертає:** нічого.
+- **Поведінка:**
+  1. Якщо `.gitignore` у корені відсутній — викидає по `fail` на кожен `HOOK_ARTIFACTS.logName` (один fail для кожного логу окремо, а не один загальний).
+  2. Інакше один раз читає файл і прокручує `HOOK_ARTIFACTS`, делегуючи кожен лог у `checkGitignoreForLog`.
+- **Side effects:** одне `readFile`, кілька викликів `fail`/`pass` через репортер.
+
+### `isBinaryInPath(name)`
+
+- **Сигнатура:** `(name: string) => boolean`
+- **Параметри:**
+  - `name` — ім'я бінарника без розширення.
+- **Повертає:** `true`, якщо у каталогах `process.env.PATH` (розділених `path.delimiter`) знайдено файл з таким іменем. Чек робиться через `existsSync(join(dir, name))` — без виклику `spawn`/`child_process`, тому не залежить від executable-біта і працює як легкий `which`.
+- **Side effects:** читання env через `node:process` + `existsSync` на кожен каталог `PATH`.
+
+### `checkLlmCliAvailable(reporter)`
+
+- **Сигнатура:** `(reporter: CheckReporter) => void`
+- **Параметри:**
+  - `reporter` — репортер.
+- **Повертає:** нічого.
+- **Поведінка:** перевіряє `isBinaryInPath('claude')` та `isBinaryInPath('cursor-agent')`. Виводить **завжди `pass`** з одним із чотирьох повідомлень (обидва знайдено / лише `claude` / лише `cursor-agent` / жодного). Це навмисний дизайн — відсутність CLI означає, що hook просто no-op'ає й не валить білд.
+- **Side effects:** мутація стану репортера (тільки `pass`-меседжі).
+
+### `check(cwd?)` *(експорт)*
+
+- **Сигнатура:** `async (cwd?: string) => Promise<number>`
+- **Параметри:**
+  - `cwd` — корінь репо. За замовчуванням — `process.cwd()`.
+- **Повертає:** exit-code зі `reporter.getExitCode()` (0 або 1).
+- **Поведінка (порядок виконання):**
+  1. Створює свіжий репортер через `createCheckReporter()`.
+  2. Послідовно (через `for…of` + `await`) для кожного `HOOK_ARTIFACTS` запускає `checkHookScript`.
+  3. Викликає `checkProjectSettings` (синхронно).
+  4. Викликає `await checkCursorHooks`.
+  5. Викликає `await checkGitignore`.
+  6. Викликає `checkLlmCliAvailable` (синхронно).
+  7. Повертає `reporter.getExitCode()`.
+- **Side effects:** усі ті, що зведено у внутрішніх перевірках (FS read, env read).
+
+## Константи модуля
+
+| Ім'я | Тип/значення | Призначення |
+| ---- | ------------ | ----------- |
+| `HOOK_ARTIFACTS` | `readonly [{ scriptName, logName }, …]` | Перелік hook-артефактів (`capture-decisions.sh`+`.log`, `normalize-decisions.sh`+`.log`), які перевіряються однотипно. `as const` через JSDoc-каст `/** @type {const} */`. |
+| `PROJECT_SETTINGS_REL` | `'.claude/settings.json'` | Project-shared конфіг Claude Code. |
+| `CURSOR_HOOKS_REL` | `'.cursor/hooks.json'` | Конфіг Cursor Agent. |
+| `EOL_RE` | `/\r?\n/u` | Регекс для split рядків `.gitignore` (підтримує LF і CRLF). |
+| `here` | `string` | Каталог цього модуля, обчислений через `fileURLToPath(import.meta.url)` + `dirname`. |
+| `BUNDLED_HOOKS_DIR` | `string` | Абсолютний шлях до `.claude-template/hooks/` усередині пакета `@nitra/cursor`: `<here>/../../../.claude-template/hooks`. Використовується як джерело канонічних скриптів. |
+
+## Залежності
+
+### Node.js builtins
+
+- `node:fs` → `existsSync` — синхронна перевірка наявності файлу.
+- `node:fs/promises` → `readFile` — асинхронне читання UTF-8 контенту.
+- `node:path` → `delimiter`, `dirname`, `join` — крос-платформне склеювання шляхів і split `PATH`.
+- `node:process` → `env` — доступ до `PATH` для пошуку LLM CLI.
+- `node:url` → `fileURLToPath` — конверсія `import.meta.url` у локальний шлях для обчислення `BUNDLED_HOOKS_DIR`.
+
+### Внутрішні модулі пакета
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера з API `{ pass(msg), fail(msg), getExitCode() }`. Усі результати модуля проходять через нього.
+
+### Зовнішні файли репо-споживача (читаються, не модифікуються)
+
+- `<cwd>/.claude/hooks/capture-decisions.sh`, `<cwd>/.claude/hooks/normalize-decisions.sh` — managed bash-скрипти.
+- `<cwd>/.claude/settings.json` — project-shared Claude config.
+- `<cwd>/.cursor/hooks.json` — Cursor Agent hooks config.
+- `<cwd>/.gitignore` — для перевірки покриття лог-файлів.
+
+### Файли пакета (джерело істини для diff)
+
+- `<package-root>/.claude-template/hooks/capture-decisions.sh`
+- `<package-root>/.claude-template/hooks/normalize-decisions.sh`
+
+Шлях обчислюється статично від `import.meta.url` — модуль не залежить від `process.cwd()` для пошуку bundled-файлів.
+
+## Потік виконання / Використання
+
+### Як модуль викликається
+
+Скрипт — частина уніфікованої check-системи `@nitra/cursor`. Зовнішній рантайм (`npx @nitra/cursor check` або еквівалент у тестах) імпортує функцію `check` і викликає її:
+
+```js
+import { check } from '@nitra/cursor/rules/adr/js/hooks.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+### Порядок перевірок усередині `check`
+
+1. **Канонічність bash-скриптів** — для кожного з `HOOK_ARTIFACTS`:
+   - FS-existence cцільового файлу;
+   - FS-existence канонічного файлу в пакеті;
+   - byte-exact diff обох контентів.
+2. **`.claude/settings.json` existence** — sanity-check, що project-shared конфіг є.
+3. **`.cursor/hooks.json`** — JSON parsing + наявність `hooks.stop[].command` markers для обох scriptName.
+4. **`.gitignore` log-coverage** — для кожного логу шукається покривна лінія (точна, scoped-glob або wide-glob).
+5. **LLM CLI availability** — інформативна перевірка `claude`/`cursor-agent` у `PATH`; **не валить exit code**.
+
+### Як інтерпретувати результат
+
+- **Return `0`** — усі обов'язкові перевірки пройшли; LLM-CLI-секція могла видати warning, але це нормально.
+- **Return `1`** — хоч одна `fail`-перевірка. Усі повідомлення `fail` містять actionable-підказку (зазвичай `npx @nitra/cursor` або конкретний рядок для `.gitignore`).
+
+### Типові сценарії регресії
+
+- Локальний редактор bash-скрипта → `checkHookScript` зафейлить byte-diff.
+- Видалення `.cursor/hooks.json` чи поламана структура → `checkCursorHooks` повідомить через JSON-error або відсутність marker.
+- Перенесення hook entry в `settings.local.json` → деталі ловить policy-правило, але `checkProjectSettings` гарантує, що project-shared файл хоча б присутній.
+- Відсутність `.gitignore`-покриття для логів → багато `fail`-меседжів з конкретним рядком, що треба додати.
+- Відсутність LLM CLI → `pass` із warning-меседжем, але `exit 0` (hook буде no-op'ати).
+
+### Контекстні нюанси
+
+- Усі шляхи в `fail`/`pass`-меседжах — відносні до `cwd` (не абсолютні), щоб output був стабільний у CI та однаковий між машинами.
+- `readJsonSafe` свідомо приглушує помилки парсингу — рішення про "JSON broken" приймається в `checkCursorHooks` через `config === null`.
+- `cursorConfigHasStopHook` робить точкову, але повну валідацію типів, бо `.cursor/hooks.json` керується одночасно автоматичним sync і людьми — не можна вважати, що структура завжди канонічна.
+- `BUNDLED_HOOKS_DIR` обчислений `dirname(fileURLToPath(import.meta.url))` + три `..` — цей розрахунок чутливий до **переміщень файлу всередині пакета**: якщо змінити structure `npm/rules/adr/js/`, треба синхронно правити кількість `..` сегментів.
+
+## Rebuild Test
+
+Якщо файл `hooks.mjs` загубити, його можна відновити з цієї документації, дотримуючись таких інваріантів:
+
+- Один експорт `async function check(cwd = process.cwd()): Promise<number>`.
+- Внутрішні константи `HOOK_ARTIFACTS`, `PROJECT_SETTINGS_REL`, `CURSOR_HOOKS_REL`, `EOL_RE`, `BUNDLED_HOOKS_DIR` мають описані значення.
+- Усі перевірки звітують через `createCheckReporter()` з `npm/scripts/lib/check-reporter.mjs`.
+- Канонічні bash-скрипти беруться з `<тут>/../../../.claude-template/hooks/` (три `..` від каталогу модуля).
+- `.gitignore`-матч підтримує точний шлях + `.claude/hooks/*.log` + `.claude/hooks/**/*.log` + `*.log` + `**/*.log`, ігнорує порожні й коментарі.
+- LLM-CLI-перевірка завжди завершується `pass` — exit-code від неї не залежить.
+- Порядок викликів усередині `check` має значення для читабельного output: hook-скрипти → settings → cursor hooks → gitignore → llm cli.

package/rules/bun/docs/fix.md

@@ -0,0 +1,156 @@
+# `npm/rules/bun/fix.mjs`
+
+## Огляд
+
+Файл є точкою входу для правила `bun` у системі правил `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку CLI-оркестрація викликає через динамічний `import(...)`, щоб виконати правило в межах загального батч-прогону всіх правил.
+2. **Standalone mode** — якщо файл запущено напряму через `bun rules/bun/fix.mjs`, він повністю емулює виклик `npx @nitra/cursor fix bun` (з конфіг-завантаженням, whitelist-фільтрацією та фінальним summary) і завершує процес кодом виходу, придатним для CI/IDE.
+
+Власної логіки перевірки/виправлення файл не містить — він делегує роботу стандартному пайплайну правил `runStandardRule`, який послідовно прогонює фази `applies → JS-concerns → policy → mdc-refs` на основі сусідніх файлів правила (`meta.json`, `bun.mdc`, тек `js/`, `policy/`).
+
+Цей патерн ідентичний у всіх однотипних правил `npm/rules/<id>/fix.mjs` — фактично це тонкий «диспатчер», який прив’язує конкретне правило (визначене теками-сусідами через `import.meta.dirname`) до загальної інфраструктури запуску.
+
+## Експорти / API
+
+| Експорт | Тип                                            | Опис                                                                                                                                                  |
+| ------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?: RuleContext): Promise<number>` | Іменований експорт. Точка входу в library-режимі: викликається оркестратором CLI через ESM `import` після динамічного резолву шляху до файлу правила. |
+
+Default-експорту немає. Окрім `run`, файл має **top-level side-effect**: при виконанні в standalone-режимі (див. нижче) виконує `process.exit(...)` ще до того, як модуль завершить ініціалізацію.
+
+## Функції
+
+### `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` — кеш обходу файлової системи, щоб не повторювати `fs.readdir` для тих самих директорій). Якщо `undefined`, `runStandardRule` створює власний контекст за замовчуванням.
+- **Повертає:** `Promise<number>` з кодом виходу:
+  - `0` — правило не знайшло порушень (OK);
+  - `1` — знайдено порушення (правило завершилося з помилками).
+- **Алгоритм:** єдине виконуване твердження — `return runStandardRule(import.meta.dirname, ctx)`. Тут `import.meta.dirname` — абсолютний шлях до теки правила (`npm/rules/bun/`); саме на основі цього шляху `runStandardRule` визначає ідентифікатор правила (остання сегментна назва — `bun`) та підвантажує сусідні артефакти (`meta.json`, `bun.mdc`, скрипти з `js/` та `policy/`).
+- **Side effects:**
+  - Делеговані до `runStandardRule`: читання конфіг-файлу, обхід дерева проєкту згідно з applies-фільтрами, можливі модифікації цільових файлів у фазі JS-concerns / policy, запис лог-повідомлень у stdout.
+  - Сам `run` не звертається до `process.exit`, не змінює `process.env` і не змінює глобальний стан — повертає чистий `Promise`, який повністю керується викликачем.
+
+### Standalone-блок (top-level)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Що це:** не функція, а IIFE-подібний top-level guard. Виконується один раз на завантаженні модуля.
+- **Умова:** `isRunAsCli(import.meta.url)` повертає `true`, лише коли цей файл стартовано напряму як entry-point (а не імпортовано як модуль із оркестратора). Перевірка зазвичай зводиться до порівняння `import.meta.url` з `pathToFileURL(process.argv[1])`.
+- **Дія:** викликає `runRuleCli(import.meta.dirname)`, дочікується резолву та передає результат у `process.exit(...)`. На відміну від `run`, тут запускається повний CLI-pipeline (а не лише стандартне правило): завантаження користувацького конфігу, фільтр whitelist, фінальний summary та форматування виводу.
+- **Side effects:**
+  - Завершує процес Node/Bun із кодом виходу `0` або `1`.
+  - У файлі присутні директиви `eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` — це свідомий виняток для standalone-точок входу, які повинні повертати exit-code для CI та IDE.
+  - Використано top-level `await`, тому модуль працює лише в ESM-середовищі з підтримкою TLA (Bun, Node.js 14.8+ у ESM-режимі).
+
+## Залежності
+
+### Внутрішні (relative imports)
+
+| Модуль                                    | Імпорти                    | Призначення                                                                                                                                                              |
+| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Утиліти для standalone-режиму: визначити, чи файл запущено як CLI, та виконати повноцінний CLI-pipeline для одного правила.                                              |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний рантайм правила: послідовність фаз `applies → JS-concerns → policy → mdc-refs`. Також експортує тип `RuleContext`, на який посилається JSDoc-анотація `run`. |
+
+### Зовнішні (npm-пакети, runtime)
+
+- Зовнішніх npm-залежностей файл не імпортує напряму.
+- Опосередковано через `runStandardRule` / `runRuleCli` залучається інфраструктура `@nitra/cursor` (logger, конфіг-парсер, walker файлової системи тощо).
+
+### Платформенні залежності
+
+- ESM (`import`, `import.meta.url`, `import.meta.dirname`).
+- Top-level `await` — потрібна Node.js ≥ 14.8 в ESM або Bun.
+- `process.exit` — Node/Bun-середовище.
+
+### Сусідні артефакти правила (читаються через `import.meta.dirname`)
+
+Файл сам не імпортує їх явно, але `runStandardRule` / `runRuleCli` підхоплюють з тієї ж теки:
+
+- `meta.json` — метадані правила (id, applies-патерни, опис тощо).
+- `bun.mdc` — людинозрозумілий опис правила у форматі MDC.
+- `js/` — JS-concerns (check-/fix-скрипти, що працюють із JS/AST).
+- `policy/` — policy-фаза (rego/інші policy-чеки).
+
+## Потік виконання / Використання
+
+### Сценарій 1: виклик з оркестратора (library mode)
+
+```js
+import { run } from '@nitra/cursor/rules/bun/fix.mjs'
+
+const exitCode = await run({ walkCache })
+if (exitCode !== 0) {
+  // правило знайшло порушення
+}
+```
+
+Послідовність:
+
+1. Оркестратор резолвить шлях до `fix.mjs` (наприклад, у циклі по `npm/rules/*/fix.mjs`).
+2. Виконує `import(...)` — модуль завантажується, `isRunAsCli(...)` повертає `false`, тому standalone-блок не спрацьовує, `process.exit` не викликається.
+3. Оркестратор отримує іменований експорт `run` і викликає його з підготованим `ctx`.
+4. `run` делегує до `runStandardRule(import.meta.dirname, ctx)`, який:
+   - читає `meta.json` сусідньої теки;
+   - проходить фази `applies → JS-concerns → policy → mdc-refs`;
+   - повертає `0` або `1`.
+5. Оркестратор агрегує коди повернення всіх правил та формує підсумковий exit-code.
+
+### Сценарій 2: прямий запуск файлу (standalone mode)
+
+```bash
+bun npm/rules/bun/fix.mjs
+# або
+node npm/rules/bun/fix.mjs
+```
+
+Послідовність:
+
+1. Bun/Node стартує модуль як entry-point.
+2. Модуль виконує імпорти `run-rule-cli.mjs` та `run-standard-rule.mjs`.
+3. Створюється експорт `run` (просто зв’язується з функцією).
+4. Перевірка `isRunAsCli(import.meta.url)` повертає `true`.
+5. Виконується `await runRuleCli(import.meta.dirname)` — це **повний** еквівалент `npx @nitra/cursor fix bun`: завантаження конфігу, whitelist-фільтрація, прогон правила, фінальний summary.
+6. Результат (число — exit-code) передається у `process.exit(...)`, процес завершується одразу.
+
+### Еквівалентність CLI-команд
+
+| Спосіб запуску              | Внутрішній шлях                                                 | Поведінка                                                |
+| --------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
+| `npx @nitra/cursor fix bun` | CLI знаходить правило `bun`, імпортує `run` → `runStandardRule` | Library mode                                             |
+| `bun npm/rules/bun/fix.mjs` | Standalone-блок → `runRuleCli`                                  | Standalone mode (повний CLI-pipeline для одного правила) |
+
+### Чому дві ролі в одному файлі
+
+- **Library mode** потрібен для батч-прогону: оркестратор не повинен форкати процес під кожне правило і не повинен дублювати конфіг-завантаження.
+- **Standalone mode** потрібен для зручного дебагу одного правила в IDE/CI: достатньо вказати шлях до файлу як entry-point, не запускаючи всю CLI-обгортку.
+
+Обидві ролі узгоджуються через стандартний `import.meta.dirname` — точку прив’язки до сусідніх артефактів правила.
+
+## Rebuild Test
+
+Якщо файл видалити і відтворити з нуля за цією документацією, мають виконуватись усі наступні твердження:
+
+1. Файл містить рівно два імпорти з відносних шляхів: `../../scripts/lib/run-rule-cli.mjs` (іменовані `isRunAsCli`, `runRuleCli`) та `../../scripts/lib/run-standard-rule.mjs` (іменований `runStandardRule`).
+2. Експортується іменована функція `run(ctx)`, яка повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`. `ctx` — необов’язковий параметр.
+3. JSDoc над `run` описує: фази правила (`applies → JS-concerns → policy → mdc-refs`), library-режим (`import + run(ctx)`), тип параметра `RuleContext`, повертає `Promise<number>` з кодами `0`/`1`.
+4. Після експорту функції є top-level guard `if (isRunAsCli(import.meta.url)) { ... }`.
+5. Усередині guard — `process.exit(await runRuleCli(import.meta.dirname))`.
+6. Рядок із `process.exit` має eslint-disable-коментар, що вимикає правила `n/no-process-exit` та `unicorn/no-process-exit` з поясненням, що це standalone entry-point для CI/IDE.
+7. Стандартний коментар поряд із guard пояснює подвійну роль файлу (`library (run) + standalone (main)`) та еквівалентність до `npx @nitra/cursor fix <id>`.
+8. У файлі немає інших експортів, default-експорту, побічних викликів `process.exit` поза guard-блоком та жодних звернень до `process.env`, файлової системи чи мережі — все делеговано в `runStandardRule` / `runRuleCli`.
+9. Файл коректно виконується в Bun і Node.js ≥ 14.8 у ESM-режимі завдяки top-level `await`.
+10. При імпорті як модуль (`import { run } from '.../fix.mjs'`) `process.exit` не викликається — guard повертає `false`.