@nitra/cursor 3.22.0 → 3.23.0

package/rules/efes/docs/fix.md

@@ -0,0 +1,203 @@
+# `fix.mjs` — entry-point правила `efes`
+
+## Огляд
+
+Файл `npm/rules/efes/fix.mjs` — це **уніфікований entry-point** одного з правил пакету `@nitra/cursor` (правило `efes`, директорія `npm/rules/efes/`). Він виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор `@nitra/cursor` (через динамічний `import` модуля та виклик `run()` із підготовленим контекстом).
+2. **Standalone mode** — якщо файл запущено напряму (наприклад, `bun npm/rules/efes/fix.mjs`), він виконує повний CLI-цикл правила (завантаження конфігу, whitelist, summary), еквівалентний `npx @nitra/cursor fix efes`, і завершує процес із відповідним exit-кодом для CI/IDE.
+
+Сам файл навмисно мінімальний — уся реальна логіка (виконання `applies → JS-concerns → policy → mdc-refs`) делегована у спільну бібліотечну функцію `runStandardRule`, що живе у `npm/scripts/lib/run-standard-rule.mjs`. Тому цей файл слугує лише **тонкою обгорткою (shim)** для одного конкретного правила `efes`, прив’язуючись до власної директорії через `import.meta.dirname`.
+
+Така архітектура — стандартна для всіх правил із сімейства `npm/rules/<id>/fix.mjs`: одне правило = одна директорія = один однаковий `fix.mjs`, який відрізняється від сусідів лише розміщенням (`import.meta.dirname` бере шлях до **цієї** директорії правила).
+
+## Експорти / API
+
+| Експорт | Тип                                      | Призначення                                                                                                                     |
+| ------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library API — викликається CLI-оркестратором `@nitra/cursor` для запуску правила в межах одного спільного прогону над монорепо. |
+
+Інших іменованих або дефолтних експортів файл не має. Окрім експорту, файл містить **side-effect блок** (top-level `if (isRunAsCli(...))`), що активується тільки коли файл запущено напряму.
+
+### Сигнатура `run`
+
+```js
+export function run(ctx)
+```
+
+- **Параметри**:
+  - `ctx` _(optional)_ — об’єкт типу `RuleContext`, імпортований із `npm/scripts/lib/run-standard-rule.mjs`. Містить розділяємий між правилами стан прогону: зокрема `walkCache` (кеш обходу файлів монорепо), а також іншу контекстну інформацію, передану CLI-оркестратором. Якщо `ctx` не передано (наприклад, при ad-hoc виклику), `runStandardRule` створює власний внутрішній контекст.
+- **Повертає**: `Promise<number>` —
+  - `0` — правило не знайшло порушень (OK);
+  - `1` — є щонайменше одне порушення (fail).
+- **Сторонні ефекти**:
+  - Сам `run` нічого не пише в `stdout`/`stderr` напряму, проте делегована функція `runStandardRule` веде логування прогресу, виводить summary порушень і — за потреби — модифікує файли проєкту (`autofix`).
+  - Може читати файлову систему монорепо (через walk), читати конфіг `@nitra/cursor` та `meta.json` правила.
+  - Не викликає `process.exit` у library mode — exit-код доручений викликаючій стороні.
+
+## Функції
+
+### `run(ctx)`
+
+#### Сигнатура
+
+```js
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+#### Параметри
+
+| Ім’я  | Тип                                          | Обов’язковий | Опис                                                                                                                                                                                                                             |
+| ----- | -------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx` | `RuleContext` (див. `run-standard-rule.mjs`) | ні           | Спільний контекст прогону, який оркестратор `@nitra/cursor` створює один раз для всієї пачки правил. Дозволяє ділити дорогий стан (наприклад, `walkCache` — список відсканованих файлів) між правилами без повторного обходу ФС. |
+
+#### Повертає
+
+`Promise<number>` — `0` або `1`. Семантика — звичайна для UNIX exit codes:
+
+- `0` — все добре, правило `efes` не зафіксувало порушень.
+- `1` — правило знайшло хоча б одне порушення (CI має впасти).
+
+#### Логіка
+
+Функція складається з єдиного рядка — `return runStandardRule(import.meta.dirname, ctx)`. Тобто:
+
+1. Беремо абсолютний шлях директорії, у якій лежить **цей** `fix.mjs` (`import.meta.dirname` дає `.../npm/rules/efes`).
+2. Передаємо цей шлях як перший аргумент у `runStandardRule` — щоб бібліотечна функція знала, **яке саме правило** запускає (звідки читати `meta.json`, `efes.mdc`, `policy/*` тощо).
+3. Передаємо отриманий `ctx` (або `undefined`).
+4. Повертаємо отриману `Promise<number>` — без обгортки, без додаткової обробки.
+
+#### Сторонні ефекти
+
+Усі побічні ефекти зосереджені всередині `runStandardRule` (читання файлів, walk, виконання checks, можливі autofix-записи). Сам `run` лише проксує виклик.
+
+### Top-level CLI-блок (без імені, не функція)
+
+```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))
+}
+```
+
+#### Поведінка
+
+- Виконується **тільки** коли модуль запущено як CLI-точку входу (`bun npm/rules/efes/fix.mjs` або `node ...`). Перевірка `isRunAsCli(import.meta.url)` порівнює URL модуля з `process.argv[1]` (стандартна ідіома для ESM).
+- Якщо умова виконалась — асинхронно (через `await` на top-level, що дозволяє ESM) викликає `runRuleCli(import.meta.dirname)`, який реалізує **повний CLI-цикл**:
+  - завантаження конфігу `@nitra/cursor`;
+  - застосування whitelist/ignore;
+  - запуск самого правила (через ту саму `runStandardRule` або еквівалентний механізм);
+  - друк summary;
+  - повернення exit-коду.
+- Завершує процес через `process.exit(...)` із отриманим кодом (0 або 1).
+
+#### Чому є коментар `eslint-disable-next-line`
+
+У проєкті заборонено `process.exit` (`n/no-process-exit`, `unicorn/no-process-exit`) — але standalone entry-point **повинен** повертати exit-код, інакше CI не зрозуміє результат. Виключення оформлене явним коментарем із поясненням («standalone entry-point має повертати exit-code для CI/IDE»), щоб лінт не падав.
+
+#### Чому є подвійний кінець рядка / два правила в одному disable
+
+Бо обидва правила (`n/no-process-exit` від `eslint-plugin-n` і `unicorn/no-process-exit` від `eslint-plugin-unicorn`) забороняють те саме незалежно — disable має покривати обидва.
+
+## Залежності
+
+### Внутрішні (з того ж монорепо)
+
+| Шлях                                      | Що імпортується                                    | Призначення                                                                                                                                       |
+| ----------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli`                         | `isRunAsCli` — детектор «модуль виконано напряму». `runRuleCli` — повний CLI-обгортка для standalone-режиму (config loading, whitelist, summary). |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`, тип `RuleContext` (через JSDoc) | Бібліотечна реалізація стандартного потоку правила: `applies → JS-concerns → policy → mdc-refs`.                                                  |
+
+Шляхи з `../../` ведуть на `npm/scripts/lib/` (бо файл лежить у `npm/rules/efes/`).
+
+### Зовнішні
+
+Жодних `npm`-залежностей файл не імпортує напряму — усі вони транзитивно підвантажуються через `runStandardRule` / `runRuleCli`.
+
+### Файли поруч (через `import.meta.dirname`)
+
+Бібліотечні функції очікують у директорії правила (`npm/rules/efes/`) певні файли — їх імпортує не `fix.mjs` напряму, а саме `runStandardRule`/`runRuleCli`:
+
+- `meta.json` — метадані правила (id, applies, policy hints, тощо);
+- `efes.mdc` — людиночитаний опис правила (Markdown + frontmatter);
+- `policy/` — директорія з policy-чеками правила.
+
+## Потік виконання / Використання
+
+### Сценарій A — виклик з CLI `@nitra/cursor` (library mode)
+
+```text
+$ npx @nitra/cursor fix
+└─ CLI оркестратор будує список правил і прогонить кожне:
+   └─ import('npm/rules/efes/fix.mjs')
+      └─ run(ctx)
+         └─ runStandardRule('.../npm/rules/efes', ctx)
+            ├─ читає meta.json + efes.mdc
+            ├─ застосовує applies-фільтри
+            ├─ запускає JS-concerns (eslint-подібні чеки)
+            ├─ запускає policy/* (специфічні чеки правила)
+            └─ перевіряє mdc-refs (узгодженість документації)
+         └─ повертає 0 / 1
+      └─ оркестратор агрегує exit-коди всіх правил
+```
+
+У цьому сценарії **жодних виходів через `process.exit`** із цього файлу — exit-код повертає оркестратор уже наприкінці всього прогону.
+
+### Сценарій B — прямий запуск файлу (standalone mode)
+
+```text
+$ bun npm/rules/efes/fix.mjs
+
+1. ESM завантажує модуль.
+2. На етапі імпорту виконуються top-level statements.
+3. `isRunAsCli(import.meta.url)` -> true.
+4. `await runRuleCli(import.meta.dirname)`:
+   - повністю емулює `npx @nitra/cursor fix efes`;
+   - завантажує конфіг проєкту, whitelist;
+   - запускає правило;
+   - виводить summary в stdout/stderr.
+5. `process.exit(<code>)` — повертає exit-код shell-у / CI / IDE.
+```
+
+Це зручно для:
+
+- швидкого ad-hoc запуску однієї конкретної перевірки під час дебагу правила;
+- інтеграції в IDE-таски (наприклад, окремі run configurations VSCode/JetBrains);
+- ізольованого прогону в pre-commit hook на одне правило.
+
+### Сценарій C — імпорт із тестів
+
+```js
+import { run } from 'npm/rules/efes/fix.mjs'
+const code = await run() // 0 або 1
+```
+
+CLI-блок **не запускається** (бо файл не є entry-point процесу), а `run` доступний як звичайна функція. Це дає змогу писати unit/e2e-тести правила без spawn-у дочірнього процесу.
+
+### Інваріанти / нюанси
+
+- `import.meta.dirname` доступний у Node ≥ 20.11 та Bun. Якщо середовище старіше — потрібен fallback через `path.dirname(fileURLToPath(import.meta.url))`. У монорепо `@nitra/cursor` офіційно підтримується Bun-середовище, тому це не проблема.
+- Top-level `await` працює тільки в ESM (`.mjs`) — саме тому файл має розширення `.mjs`, а не `.js`.
+- Дві ролі файлу (library + standalone) — це усвідомлений патерн «dual entry-point»: ESM-import не запускає CLI-блок, бо `isRunAsCli` повертає `false`.
+- Файл навмисно ідентичний по структурі з усіма іншими `npm/rules/<id>/fix.mjs`. Уся специфіка правила `efes` живе в сусідніх файлах (`meta.json`, `efes.mdc`, `policy/`) — у самому `fix.mjs` нічого правило-специфічного немає, окрім розташування.
+
+## Rebuild Test
+
+Уявно «перебудувавши» файл лише за цією документацією, маємо отримати:
+
+- ESM-модуль `.mjs` із двома імпортами зі спільної бібліотеки `npm/scripts/lib/`:
+  - `{ isRunAsCli, runRuleCli }` із `../../scripts/lib/run-rule-cli.mjs`;
+  - `{ runStandardRule }` із `../../scripts/lib/run-standard-rule.mjs`.
+- Один іменований експорт `run(ctx)` із JSDoc, що описує параметр `ctx` як `RuleContext` (тип взято через `import('...')` JSDoc-нотацію) і повертає `Promise<number>` (`0` — OK, `1` — порушення). Тіло — один рядок `return runStandardRule(import.meta.dirname, ctx)`.
+- Top-level guard `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }` із коментарем-disable для двох ESLint-правил (`n/no-process-exit`, `unicorn/no-process-exit`) і поясненням «standalone entry-point має повертати exit-code для CI/IDE».
+- Жодних інших declarations, експортів чи побічних ефектів.
+
+Такий «реконструйований» файл функціонально й текстово збігається з оригіналом `npm/rules/efes/fix.mjs`.

package/rules/feedback/docs/fix.md

@@ -0,0 +1,140 @@
+# `npm/rules/feedback/fix.mjs`
+
+## Огляд
+
+Файл є точкою входу (entry-point) для правила `feedback` у CLI-наборі `@nitra/cursor`. Він реалізує дві паралельні ролі того ж самого модуля:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку викликають інші частини оркестратора (наприклад, агрегований `fix`/`lint`-прогін, де всі правила запускаються послідовно з шарінгом кешу обходу файлів `walkCache`).
+2. **Standalone mode** — якщо файл стартує безпосередньо як CLI-скрипт (`bun rules/feedback/fix.mjs`), він виконується як повний аналог команди `npx @nitra/cursor fix feedback` із завантаженням конфігу, застосуванням whitelist та підсумком.
+
+Сам файл логіки правила не містить — він є тонким адаптером, що делегує роботу до спільного раннера `runStandardRule`. Стандартний потік правила, який запускається через цей адаптер: `applies → JS-concerns → policy → mdc-refs` (тобто перевіряється застосовність до проєкту, далі — JS-специфічні перевірки, далі — policy-шар, наприкінці — синхронізація посилань у відповідному `.mdc`-файлі).
+
+Модуль використовує `import.meta.dirname`, тому він повністю прив'язаний до місця свого розташування: каталог правила (`npm/rules/feedback/`) автоматично стає коренем, у якому раннер шукає `meta.json`, `feedback.mdc` та інші артефакти.
+
+## Експорти / API
+
+| Експорт | Тип                               | Призначення                                                                                          |
+| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?): Promise<number>` | Library-точка входу правила. Викликається оркестратором; повертає exit-code (0 — OK, 1 — порушення). |
+
+Side-експортів немає. Default-експорту немає.
+
+Поведінка при прямому запуску файлу як CLI (через `process.exit(await runRuleCli(...))`) — це не експорт, а top-level side-effect, активний лише коли `isRunAsCli(import.meta.url)` повертає `true`.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx)
+```
+
+- **Призначення:** запустити правило `feedback` у library-режимі. Делегує всю роботу до `runStandardRule`, передаючи каталог поточного файлу як ідентифікатор правила.
+- **Параметри:**
+  - `ctx` — `RuleContext | undefined`. Опціональний контекст прогону. Тип імпортується через JSDoc-посилання `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`. Зокрема, контекст несе спільні структури між правилами (наприклад, `walkCache` — кеш обходу файлової системи, щоб не сканувати дерево кілька разів у разі прогону кількох правил поспіль). Якщо `ctx` не переданий, `runStandardRule` створює власний внутрішній контекст.
+- **Повертає:** `Promise<number>` — exit-code:
+  - `0` — правило застосовне і порушень не знайдено, або правило не застосовне до поточного проєкту (`applies` повернув `false`);
+  - `1` — знайдені порушення (policy / JS-concerns / mdc-refs).
+- **Side effects:** жодних прямих у цій функції. Опосередковано через `runStandardRule` можливі: читання файлів проєкту, читання `meta.json` і `feedback.mdc`, лог у stdout/stderr, мутація переданого `walkCache`.
+- **Винятки:** функція сама не кидає; будь-яка помилка приходить як rejected promise від `runStandardRule`.
+
+### Top-level standalone-блок
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Призначення:** перетворити цей же модуль на CLI-скрипт. Якщо файл був запущений напряму (а не імпортований), виконується повний CLI-цикл правила — еквівалент `npx @nitra/cursor fix feedback`.
+- **Виклик:** `runRuleCli(import.meta.dirname)` отримує абсолютний шлях до каталогу правила; всередині раннера це задає, який саме `meta.json`/`*.mdc` і `applies/policy/...`-функції підтягуються.
+- **Повертає / завершення:** результат `runRuleCli` (число) йде в `process.exit(...)`, тобто процес одразу завершується з відповідним exit-code. Це навмисно: standalone entry-point має повернути код виходу для CI/IDE-інтеграцій.
+- **Спеціальні маркери:**
+  - `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` — свідома відмова від загальної заборони `process.exit` саме тут, бо це standalone-точка входу.
+- **Side effects:** завершує процес Node/Bun.
+
+## Залежності
+
+Файл імпортує два внутрішні модулі (relative-шляхи, без зовнішніх npm-пакетів):
+
+| Імпорт            | З файлу                                   | Що використовується                     | Роль                                                                                                                                                   |
+| ----------------- | ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Функція-предикат                        | Визначає, чи цей `.mjs`-файл був запущений напряму як CLI (через `import.meta.url`), а не імпортований як модуль.                                      |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Async-функція                           | Виконує повний CLI-цикл правила: завантаження конфігу, whitelist-фільтрацію, прогін стандартного раннера, форматування підсумку, повернення exit-code. |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Async-функція + JSDoc-тип `RuleContext` | Стандартний раннер для правил: `applies → JS-concerns → policy → mdc-refs`. Шукає артефакти у переданому каталозі.                                     |
+
+Глобали з рантайму:
+
+- `import.meta.dirname` — абсолютний шлях каталогу поточного `.mjs`-файлу (Bun / Node ≥ 20.11). Використовується як «корінь правила».
+- `import.meta.url` — file-URL модуля; передається в `isRunAsCli` для надійного порівняння з `process.argv[1]`.
+- `process.exit` — викликається лише у standalone-гілці.
+
+Зовнішні пакети не імпортуються.
+
+## Потік виконання / Використання
+
+### Сценарій A — імпорт як library
+
+```js
+import { run } from './npm/rules/feedback/fix.mjs'
+
+const code = await run(/* ctx */)
+if (code !== 0) {
+  // правило знайшло порушення
+}
+```
+
+Послідовність всередині:
+
+1. Викликається `run(ctx)`.
+2. `run` повертає `runStandardRule(import.meta.dirname, ctx)`.
+3. Усередині `runStandardRule`:
+   - перевіряє `applies` (чи правило застосовне до проєкту);
+   - проганяє JS-concerns (lint/structure);
+   - проганяє policy-перевірки;
+   - звіряє `mdc-refs` (узгодженість посилань між кодом і `feedback.mdc`).
+4. Повертається `0` або `1`.
+
+Top-level `if (isRunAsCli(...))` у цьому випадку не спрацьовує — `isRunAsCli(import.meta.url)` повертає `false`, бо стартова точка процесу — інший файл.
+
+### Сценарій B — прямий запуск як CLI
+
+```bash
+bun npm/rules/feedback/fix.mjs
+# або еквівалент:
+npx @nitra/cursor fix feedback
+```
+
+Послідовність:
+
+1. Node/Bun завантажує модуль; виконуються `import`-и.
+2. Перевіряється `isRunAsCli(import.meta.url)` → `true`.
+3. Викликається `await runRuleCli(import.meta.dirname)`. Цей раннер:
+   - завантажує загальний конфіг проєкту;
+   - застосовує whitelist (якщо в конфізі обмежений набір правил);
+   - всередині все одно проганяє ту ж саму `runStandardRule`-логіку;
+   - друкує форматований summary;
+   - повертає exit-code.
+4. `process.exit(code)` миттєво завершує процес із отриманим кодом, який потім читає CI/IDE.
+
+### Чому дві ролі в одному файлі
+
+Конвенція в `npm/rules/<id>/fix.mjs` дозволяє:
+
+- оркестратору проганяти всі правила одним процесом, шарячи `walkCache` (швидко, для batch-режимів);
+- розробнику запустити **одне** правило точково з шелла без обгорток і отримати CI-сумісний exit-code.
+
+Жодного дублювання логіки немає — обидві гілки в кінцевому рахунку викликають один і той самий `runStandardRule`, просто standalone-гілка додає шар CLI-обгортки (`runRuleCli`).
+
+## Rebuild Test
+
+Чи можна за цим документом без доступу до файлу відтворити модуль еквівалентної поведінки? Так:
+
+- ім'я експорту: `run`, сигнатура `(ctx) => Promise<number>`;
+- тіло: `return runStandardRule(import.meta.dirname, ctx)`;
+- top-level `if`: `isRunAsCli(import.meta.url)` → `process.exit(await runRuleCli(import.meta.dirname))`;
+- два імпорти з точно вказаних шляхів (`../../scripts/lib/run-rule-cli.mjs` для `isRunAsCli`/`runRuleCli`, `../../scripts/lib/run-standard-rule.mjs` для `runStandardRule`);
+- ESLint-disable коментар над `process.exit` для `n/no-process-exit` і `unicorn/no-process-exit`;
+- JSDoc-блок над `run` із посиланням на тип `RuleContext` через `import('...')`-нотацію.
+
+Усі ці елементи описані вище — реконструкція еквівалентного файлу можлива.

package/rules/flow/docs/fix.md

@@ -0,0 +1,152 @@
+# `npm/rules/flow/fix.mjs`
+
+## Огляд
+
+Файл є точкою входу (entry point) правила `flow` у каталозі правил пакета `@nitra/cursor`. Правило `flow` належить до категорії **pure-doc contract-правил**: воно не має програмних concern-ів і фактично валідує лише супровідний документ `.mdc` (Markdown-Contract) у тій самій теці.
+
+Модуль виконує дві основні задачі:
+
+1. Експортує функцію `run(ctx)`, яка делегує всю роботу стандартному пайплайну виконання правил (`runStandardRule`). Цей експорт використовується диспетчером CLI `@nitra/cursor` (наприклад, командою `npx @nitra/cursor fix flow`) та внутрішніми оркестраторами правил.
+2. Підтримує **standalone-режим** — якщо файл запущено напряму як CLI-скрипт (через `bun rules/flow/fix.mjs`), він викликає універсальний CLI-раннер `runRuleCli` і завершує процес коректним exit-кодом, придатним для CI/IDE-інтеграцій.
+
+Стандартний пайплайн правила, який запускає `runStandardRule`, виглядає так (порядок фіксований):
+`applies` → `JS-concerns` → `policy` → `mdc-refs`. Оскільки в цьому правилі програмних concern-ів немає, реальна перевірка зводиться до етапів `applies`, `policy` та валідації посилань у `.mdc`-файлі.
+
+## Експорти / API
+
+Модуль є **ES-модулем** (`.mjs`), має такі експорти:
+
+| Експорт | Тип                                            | Призначення                                                                                                     |
+| ------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?: RuleContext): Promise<number>` | Іменований експорт; основна точка входу для виконання правила. Викликається диспетчером правил `@nitra/cursor`. |
+
+Side-effect верхнього рівня (не експорт, але частина публічної поведінки модуля):
+
+- Якщо `import.meta.url` відповідає стартовому файлу процесу (`isRunAsCli`), модуль запускає `runRuleCli(import.meta.dirname)` та викликає `process.exit(...)` із кодом, який повернув раннер.
+
+Default-експорту **немає**.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx)
+```
+
+- **Призначення.** Запустити стандартизований пайплайн правила `flow` для поточної теки (`import.meta.dirname` — каталог, де лежить `fix.mjs`, тобто `npm/rules/flow/`).
+- **Параметри:**
+  - `ctx` _(необов'язковий, `RuleContext`)_ — контекст прогону правил. Тип `RuleContext` імпортується з `../../scripts/lib/run-standard-rule.mjs`. У контексті, зокрема, передаються спільні структури між правилами — наприклад, `walkCache` (кеш обходу файлової системи), щоб не повторювати дорогі сканування при послідовному запуску багатьох правил.
+- **Повертає:** `Promise<number>`.
+  - `0` — правило виконано успішно, порушень не виявлено.
+  - `1` — знайдено порушення (наприклад, проблеми у відповідному `.mdc`-файлі).
+- **Side effects:** жодних безпосередньо у функції; усі побічні ефекти (читання FS, виведення повідомлень, агрегація знахідок) інкапсульовані всередині `runStandardRule`.
+- **Контракт пайплайну, який вмикає `runStandardRule`:**
+  - `applies` — визначає, чи правило застосовне до поточного проєкту/контексту.
+  - `JS-concerns` — програмні перевірки JS/MJS-коду (у цьому правилі — фактично відсутні, бо правило pure-doc).
+  - `policy` — політики/обмеження, спільні для всіх правил.
+  - `mdc-refs` — валідація посилань і структури супровідного `.mdc`-файлу.
+
+### IIFE-блок CLI-режиму (top-level, не функція)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Призначення.** Дозволити запуск файлу як самостійного скрипта (`bun rules/flow/fix.mjs`), повністю еквівалентний `npx @nitra/cursor fix flow`.
+- **Семантика умови.** `isRunAsCli(import.meta.url)` повертає `true`, якщо цей файл є стартовим модулем процесу (а не імпортованим іншим модулем). Це стандартний у пакеті паттерн dual-mode (бібліотека + CLI).
+- **Параметри `runRuleCli`:** передається `import.meta.dirname` — абсолютний шлях до каталогу `npm/rules/flow/`. Раннер сам читає `meta.json`/`fix.mjs`/`.mdc` із цього каталогу.
+- **Завершення.** `process.exit(...)` із цілочисельним exit-кодом, який повернув `runRuleCli`. Це важливо для CI/IDE: ненульовий код → провалена перевірка.
+- **ESLint-винятки в коді:** рядок із `process.exit` навмисно вимикає правила `n/no-process-exit` та `unicorn/no-process-exit` через коментар `// eslint-disable-next-line ... -- standalone entry-point має повертати exit-code для CI/IDE`. Це задокументоване відхилення: для standalone CLI вихід кодом потрібен.
+
+## Залежності
+
+Усі залежності — **внутрішні**, з підкаталогу `scripts/lib/` пакета:
+
+| Імпорт            | Шлях                                      | Що дає                                                                                                                                                 |
+| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: чи `import.meta.url` модуля збігається зі стартовим файлом процесу (визначає standalone-запуск).                                             |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Універсальний CLI-раннер для одного правила: парсить аргументи, готує контекст, викликає `run`, форматує вивід, повертає exit-код.                     |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний пайплайн правил `applies → JS-concerns → policy → mdc-refs`; читає сусідній `.mdc`, виконує перевірки, агрегує результат у код повернення. |
+
+Зовнішніх (npm-пакетних) залежностей файл не імпортує.
+
+Опосередковано (через `runStandardRule`) використовуються:
+
+- Сусідні файли у каталозі `npm/rules/flow/` — насамперед `.mdc` (Markdown-Contract правила) та `meta.json` (метадані правила), якщо такі присутні.
+- Спільна інфраструктура з `npm/scripts/lib/` (логування, форматування результатів, утиліти FS-обходу).
+
+## Потік виконання / Використання
+
+### Сценарій 1. Виклик з диспетчера правил (типовий)
+
+1. CLI `@nitra/cursor` (або інший оркестратор) визначає, що потрібно запустити правило `flow` у режимі `fix`.
+2. Диспетчер імпортує `fix.mjs` як модуль і викликає `run(ctx)`, передаючи спільний `ctx` (наприклад, із заповненим `walkCache`).
+3. `run` делегує виконання `runStandardRule(import.meta.dirname, ctx)`.
+4. `runStandardRule` послідовно виконує етапи `applies → JS-concerns → policy → mdc-refs`.
+5. Повертається `Promise<number>` — `0` або `1`.
+6. Оркестратор агрегує коди повернення з усіх правил.
+
+### Сценарій 2. Standalone CLI-запуск
+
+Команда:
+
+```bash
+bun npm/rules/flow/fix.mjs
+```
+
+(еквівалентно `npx @nitra/cursor fix flow`).
+
+1. Інтерпретатор виконує модуль як стартовий файл процесу.
+2. Рядок `if (isRunAsCli(import.meta.url))` повертає `true`.
+3. Викликається `await runRuleCli(import.meta.dirname)`:
+   - Раннер парсить CLI-аргументи (флаги, шляхи).
+   - Готує `ctx` для одиничного запуску.
+   - Викликає `run` цього ж модуля (або еквівалентний внутрішній механізм через `runStandardRule`).
+   - Форматує вивід (звіт про знахідки, кольори, summary).
+4. `process.exit(<код>)` — процес завершується з кодом раннера: `0` за успіху, `1` за порушень.
+
+### Сценарій 3. Імпорт у тестах / скриптах
+
+Можливий імпорт `run` для unit-/інтеграційного тестування або для написання кастомних оркестраторів:
+
+```js
+import { run } from '@nitra/cursor/rules/flow/fix.mjs'
+
+const code = await run() // або await run(customCtx)
+if (code !== 0) {
+  // обробити порушення
+}
+```
+
+У цьому випадку top-level блок `if (isRunAsCli(...))` **не спрацьовує** (файл імпортовано, а не запущено напряму), отже `process.exit` не викликається — побічних ефектів на процес немає.
+
+### Контракт повернення
+
+| Код | Значення                                                                                         | Дія викликача                                    |
+| --- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| `0` | Правило застосоване й порушень немає; або правило не застосовне (etap `applies` повернув false). | Продовжувати конвеєр.                            |
+| `1` | Знайдено порушення (зазвичай — невідповідність `.mdc`-файлу контракту).                          | CI має зафейлити збірку; IDE — показати помилку. |
+
+## Особливості реалізації / Нотатки
+
+- **Pure-doc rule.** За коментарем у JSDoc функції `run`, правило `flow` не має програмних concern-ів. Це означає, що каталог `npm/rules/flow/` навмисно не містить (або містить лише мінімум) перевірок поверх JS-коду — основний контракт описано в `.mdc`-файлі, який і валідується через підетап `mdc-refs`.
+- **Стандартизований шаблон.** Файл написаний за єдиним шаблоном для всіх правил пакета: тонкий wrapper над `runStandardRule` + опційний standalone CLI-блок. Це спрощує генерацію/підтримку правил і робить їх взаємозамінними для оркестратора.
+- **`import.meta.dirname`** використовується замість `__dirname` (який недоступний в ES-модулях) і передається у `runStandardRule`/`runRuleCli` як локалізатор каталогу правила.
+- **Top-level `await`** у блоці `process.exit(await runRuleCli(...))` дозволений, тому що модуль є ES-модулем (`.mjs`).
+- **ESLint-disable з обґрунтуванням.** Вимкнення `n/no-process-exit` та `unicorn/no-process-exit` зроблено з явним коментарем-обґрунтуванням після `--`, що відповідає внутрішнім js-lint правилам пакета (вимога описувати причину disable).
+
+## Rebuild Test (контрольна реконструкція)
+
+Спираючись виключно на цю документацію, файл `fix.mjs` можна відновити так:
+
+1. Створити ES-модуль `npm/rules/flow/fix.mjs`.
+2. Імпортувати з `../../scripts/lib/run-rule-cli.mjs` іменовані експорти `isRunAsCli` та `runRuleCli`.
+3. Імпортувати з `../../scripts/lib/run-standard-rule.mjs` іменований експорт `runStandardRule`.
+4. Експортувати функцію `run(ctx)`, яка повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`. Контракт: `Promise<number>` (`0` — OK, `1` — порушення). JSDoc описує пайплайн `applies → JS-concerns → policy → mdc-refs` та зазначає, що правило pure-doc.
+5. Додати top-level блок: `if (isRunAsCli(import.meta.url)) process.exit(await runRuleCli(import.meta.dirname))`.
+6. Поряд із `process.exit` поставити `eslint-disable-next-line` для `n/no-process-exit` та `unicorn/no-process-exit` з обґрунтуванням, що standalone entry-point має повертати exit-code для CI/IDE.
+
+Такий файл буде функціонально еквівалентним оригіналу.