@nitra/cursor 3.22.0 → 3.23.0

package/rules/abie/lib/docs/http-route.md

@@ -0,0 +1,44 @@
+# http-route.mjs
+
+## Огляд
+
+Cross-документна аналітика abie `HTTPRoute`-маніфестів: рахує посилання (`backendRefs`) на спільні `-hl`-сервіси у base-шарі пакета (поза overlay `ua`) і водночас фіксує порушення `namespace`. Слугує джерелом істини для `ua_http_route`-концерну, який звіряє кількість namespace-patch-ів в overlay із кількістю base-reference.
+
+## Поведінка
+
+1. Обходить переданий перелік YAML-файлів під k8s-каталогом, лишаючи тільки ті, що належать base-шару abie-пакета й не входять до overlay `ua`.
+2. Кожен відібраний файл читається й безпечно парситься як набір YAML-документів; документи з помилками парсингу пропускаються (інші документи в тому ж файлі продовжують аналізуватися).
+3. Враховуються лише документи з `kind: HTTPRoute`. Інші види та структурно некоректні корені дають нульовий внесок.
+4. Для `HTTPRoute` обхід заходить у `spec.rules[].backendRefs[]` і для кожного посилання перевіряє, чи його `name` належить набору спільних cross-namespace сервісів.
+5. Спільними вважаються рівно два сервіси: `auth-run-hl` та `file-link-hl`. Кожне таке посилання збільшує загальний лічильник посилань на 1.
+6. Якщо посилання на спільний сервіс не має `namespace: dev`, додається помилка виду `<rel>: HTTPRoute backendRefs до <name> має містити namespace: dev (abie.mdc)`.
+7. Підсумок по всьому пакету повертається як агрегований лічильник посилань (`refCount`) і список base-помилок (`baseErrors`).
+
+Приклад спільного backend-посилання, яке проходить перевірку:
+
+```yaml
+kind: HTTPRoute
+spec:
+  rules:
+    - backendRefs:
+        - name: auth-run-hl
+          namespace: dev
+```
+
+## Публічний API
+
+- `analyzeAbieSharedBackendRefsInPackageK8s` — за коренем репозиторію, шляхом каталогу пакета й переліком YAML-файлів повертає сумарну кількість base-посилань на спільні `-hl`-сервіси та список порушень `namespace` у base-шарі.
+- `ABIE_SHARED_CROSS_NS_BACKEND_NAMES` — заморожений перелік імен спільних cross-namespace сервісів (`auth-run-hl`, `file-link-hl`), за якими ведеться підрахунок.
+
+## Де використовується
+
+Споживається `ua_http_route`-концерном (`npm/rules/abie/js/ua_http_route.mjs`) для синхронізації числа namespace-patch-ів в overlay `ua` із кількістю base-reference.
+
+## Гарантії поведінки
+
+- Read-only: файли лише читаються, аналіз нічого не пише на диск.
+- Парсинг fail-safe: помилки читання/розбору YAML придушуються, а документи з помилками не враховуються — некоректний файл не зриває аналіз пакета.
+- Структурна стійкість: `null`, масиви та поля неочікуваного типу на будь-якому рівні (корінь, `spec`, `rules`, окреме посилання) дають нульовий внесок без винятків.
+- Лічильник рахує тільки посилання на два визначені спільні сервіси; інші backend-сервіси ігноруються.
+- Перелік спільних імен заморожений і не може бути змінений споживачами.
+- Шляхи у повідомленнях нормалізовані до `/`, тож вихід однаковий на POSIX і Windows.

package/rules/abie/lib/docs/k8s-tree.md

@@ -0,0 +1,40 @@
+# k8s-tree
+
+## Огляд
+
+Модуль обходить дерево репозиторію й постачає правилу `abie` два набори даних про Kubernetes-маніфести: усі YAML-файли під сегментом `k8s/` та каталоги, що містять `Deployment`. Результати кешуються на час одного прогону (module-level singleton), тож кілька перевірок у межах однієї сесії перевикористовують єдиний обхід замість повторного I/O.
+
+## Поведінка
+
+Пошук YAML-файлів під `k8s/`:
+
+1. Рекурсивно обходить дерево від кореня репозиторію, поважаючи передані шляхи-виключення.
+2. Каталог `.github/` свідомо пропускається — він належить іншому правилу (`ga.mdc`).
+3. До результату потрапляє файл лише якщо його шлях містить сегмент `k8s/` і має розширення `.yaml` чи `.yml`.
+4. Повертає абсолютні шляхи, відсортовані за алфавітом (детермінований вивід).
+
+Пошук каталогів із `Deployment`:
+
+1. Приймає набір абсолютних шляхів до YAML-файлів (зазвичай результат попереднього кроку).
+2. Кожен файл читається й розбивається на окремі YAML-документи.
+3. Документ враховується лише якщо розпарсився без помилок і є маніфестом `kind: Deployment`.
+4. Каталог кожного такого файлу додається до результуючого набору унікальних каталогів.
+5. Пошкоджені або непарсабельні YAML за замовчуванням мовчки пропускаються; формальний reporter помилок caller може передати окремо.
+
+## Публічний API
+
+- `findK8sYamlFiles` — повертає відсортований список абсолютних шляхів до YAML-файлів під `k8s/`, з урахуванням виключень і пропуском `.github/`.
+- `collectDeploymentDirs` — за набором YAML-файлів повертає множину абсолютних каталогів, де знайдено хоча б один `Deployment`-маніфест.
+
+Обидві точки повертають Promise. Результат кожної кешується за стабільним ключем (для пошуку файлів — за коренем і набором виключень; для пошуку каталогів — за коренем і набором YAML-шляхів), тож повторний виклик із тими самими аргументами не виконує повторного обходу чи читання. У кеші зберігається сам Promise, тому конкурентні виклики з однаковим ключем склеюються в один реальний обхід файлової системи.
+
+## Де використовується
+
+Допоміжний модуль правила `abie` (`npm/rules/abie/`), що постачає спільні дані про Kubernetes-деплойменти для його перевірок.
+
+## Гарантії поведінки
+
+- Read-only: модуль лише читає файлову систему, нічого не змінює.
+- Детермінований вивід: списки результатів і ключі кешу сортуються, тож результат не залежить від порядку обходу чи порядку переданих аргументів.
+- Fail-safe щодо вмісту: документи з помилками парсингу ігноруються, а пошкоджені YAML за замовчуванням не зривають обхід — без переданого reporter про них просто мовчиться.
+- Кеш діє в межах життя процесу й не має інвалідації: у межах одного прогону файлова система вважається незмінною, а між прогонами процес стартує заново.

package/rules/abie/lib/docs/kustomization-patches.md

@@ -0,0 +1,47 @@
+# kustomization-patches.mjs
+
+## Огляд
+
+Модуль розпізнає inline JSON6902-патчі всередині `kustomization.yaml` для abie ua-overlay і перевіряє, що вони відповідають вимогам правила `abie.mdc`. Обслуговує два сценарії: патч `nodeSelector` на `Deployment` (закріплення подів на не-preemptible вузлах) і патчі `HTTPRoute` (домени, namespace для `parentRefs` і `backendRefs`). Тіло `patch:` у YAML — це рядок із вкладеним JSON6902, тому розпізнавання спирається на пошук характерних підрядків (`path: …`, `value: …`), а не на повторний парсинг.
+
+## Поведінка
+
+Спільний препроцесинг тексту `kustomization.yaml`: знімається BOM; якщо перший рядок — editor-modeline, його відкидають; решта розбирається як набір YAML-документів (можливо кілька через `---`). Будь-яка помилка розбору перехоплюється і дає безпечний результат (`false` або порожній рядок).
+
+### Перевірка nodeSelector-патча для Deployment
+
+1. Серед документів шукають той, де `kind: Kustomization` і є масив `patches`.
+2. Підходить елемент `patches`, у якого `target.kind` дорівнює `Deployment`, а текст патча містить одночасно шлях `/spec/template/spec/nodeSelector` і ключ `preem: false` (з лапками або без).
+3. Якщо хоча б один такий патч знайдено — результат позитивний.
+
+### Збір і валідація HTTPRoute-патчів
+
+1. З усіх документів `Kustomization` збираються тексти патчів, у яких `target.kind` дорівнює `HTTPRoute` і `target.name` непорожній; зібрані фрагменти склеюються в один текст.
+2. Об'єднаний текст перевіряється послідовно. Кожна невдала умова повертає конкретне україномовне повідомлення з посиланням на `abie.mdc`; повний успіх — `null`:
+   - текст не може бути порожнім;
+   - має бути шлях `/spec/hostnames`;
+   - серед значень `hostnames` має бути хоча б один з доменів abie: `abie.app`, `vybeerai.com.ua`, `*.abie.app`, `*.vybeerai.com.ua`;
+   - має бути шлях `/spec/parentRefs/0/namespace` зі значенням `ua` (дозволено й `ua-*`, напр. `ua-b2b`);
+   - якщо в base-HTTPRoute є cross-namespace `backendRefs` до спільних сервісів (`auth-run-hl`, `file-link-hl`), то на кожен такий ref має бути окремий патч `path: /spec/rules/.../backendRefs/.../namespace` зі значенням `ua[-…]`; якщо патчів менше очікуваного — помилка з числами «потрібно/є».
+
+Очікувана кількість cross-namespace патчів передається ззовні (з аналізу base-маніфестів). Некоректне чи від'ємне значення нормалізується до невід'ємного цілого; `0` означає, що ця перевірка пропускається.
+
+Приклади namespace, що проходять: `ua`, `ua-b2b`.
+
+## Публічний API
+
+- `kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode)` — за повним текстом `kustomization.yaml` повертає `true`, якщо в ньому є коректний inline-патч `nodeSelector` (`preem: false`) на `Deployment` для overlay `ua`.
+- `getCombinedNginxRunPatchTextFromKustomization(raw)` — повертає об'єднаний текст усіх inline JSON6902-фрагментів HTTPRoute (з непорожнім `target.name`); порожній рядок, якщо таких немає або файл не розбирається.
+- `validateAbieNginxRunHttpRoutePatches(combined, mode, _fullKustomizationRaw, sharedCrossNsBackendRefCount)` — перевіряє об'єднаний текст HTTPRoute-патчів на відповідність abie.mdc; повертає `null` при успіху або повідомлення про помилку. Параметр `_fullKustomizationRaw` лишений лише для сумісності сигнатури й не використовується.
+
+## Де використовується
+
+- `npm/rules/abie/js/ua_node_selector.mjs` — перевірка наявності nodeSelector-патча в ua-overlay.
+- `npm/rules/abie/js/ua_http_route.mjs` — збирає об'єднаний текст HTTPRoute-патчів і валідує його з урахуванням кількості спільних cross-namespace backendRefs.
+
+## Гарантії поведінки
+
+- Read-only: модуль лише обробляє переданий текст, нічого не змінює, не звертається до файлової системи чи мережі — IO виконують виклики на рівні правила.
+- Стійкість до поганого вводу: помилки розбору YAML перехоплюються (предикат → `false`, збирач → `''`); некоректні чи відсутні поля (`patches` не масив, відсутній `target`, нерядкове тіло `patch`) безпечно ігноруються.
+- Враховується тільки рядкове тіло `patch:` — елементи зі структурованим (об'єктним) патчем пропускаються.
+- Логіка розрахована лише на `mode === 'ua'` (і похідні `ua-*`); для інших значень HTTPRoute-підрахунок повертає `0`.

package/rules/abie/lib/docs/overlay-paths.md

@@ -0,0 +1,38 @@
+# overlay-paths
+
+## Огляд
+
+Набір path-хелперів для перевірок правила abie, що працює з k8s-структурою пакетів монорепо. Розрізняє base-шар пакета та `ua/` overlay, виводить каталог пакета зі шляху overlay і визначає, які додаткові вимоги (HTTPRoute, Deployment) застосовуються до конкретного overlay. Усі хелпери — чисті обчислення над шляхами без побічних ефектів, окрім перевірок наявності файлів `vite.config.*` на диску.
+
+## Поведінка
+
+Очікувана структура пакета, з якою працює модуль:
+
+```
+<пакет>/
+  k8s/
+    base/...               ← base-шар
+    ua/
+      kustomization.yaml    ← abie overlay
+  vite.config.{js,mjs,ts}   ← опційно, ознака Vite-пакета
+```
+
+1. Розпізнавання overlay-маніфесту: шлях, що закінчується на `…/ua/kustomization.yaml`, вважається abie overlay. Перед матчингом backslash-роздільники нормалізуються в `/`, тож перевірка однакова на Windows і POSIX.
+
+2. Виведення каталогу пакета: для overlay вигляду `…/k8s/ua/kustomization.yaml` обчислюється абсолютний шлях до каталогу пакета (батько `k8s/`). Якщо шлях не відповідає цьому шаблону — повертається `null`, що сигналізує, що це не валідний overlay-маніфест abie-пакета.
+
+3. Gate на HTTPRoute за наявністю Vite: вимога HTTPRoute застосовується до overlay лише тоді, коли в каталозі пакета присутній один із `vite.config.js`, `vite.config.mjs` або `vite.config.ts`. Для не-Vite пакетів вимога не вмикається. Якщо каталог пакета вивести не вдалося — вимога теж не вмикається.
+
+4. Наявність Deployment у дереві пакета: перевіряється, чи серед заздалегідь зібраного набору каталогів із Deployment є хоча б один усередині `k8s/`-піддерева цього пакета (сам корінь `k8s/` або будь-який вкладений каталог). Набір каталогів передається ззовні — модуль сам файлову систему не сканує.
+
+5. Розрізнення base vs overlay для yaml-файлу:
+   - швидка ознака base-шару — наявність сегмента `base/` будь-де у шляху;
+   - точніша перевірка приналежності до base конкретного пакета — yaml має лежати під `<пакет>/k8s/`, але поза піддеревом `ua/`. Файли overlay (`ua/`) виключаються.
+
+## Гарантії поведінки
+
+- Хелпери read-only щодо вмісту файлів; єдина взаємодія з ФС — перевірка існування `vite.config.*`. Вони не читають, не пишуть і не модифікують файли.
+- Шляхи з `\` нормалізуються в `/` перед порівнянням, тож результати не залежать від ОС.
+- Якщо overlay-шлях не відповідає очікуваному шаблону `…/k8s/ua/kustomization.yaml`, обчислення каталогу пакета повертає `null`, а похідні від нього перевірки (HTTPRoute, Deployment) безпечно повертають `false` замість помилки.
+- Кінцевий слеш у переданому каталозі пакета ігнорується при перевірці приналежності yaml до base-шару.
+- Перевірка приналежності до `k8s/`-піддерева враховує точний збіг кореня й порівнює з межею `/`, тож не дає хибних спрацювань на сусідніх каталогах із подібним префіксом.

package/rules/abie/lib/docs/yaml.md

@@ -0,0 +1,29 @@
+# yaml.mjs
+
+## Огляд
+
+Спільний набір YAML-хелперів для перевірок правила `abie`. Інкапсулює читання й розбір YAML-файлів Kubernetes-маніфестів так, щоб усі abie-перевірки розбирали вміст однаково: з прибиранням BOM, ігноруванням службового modeline-рядка `# yaml-language-server: $schema=` і fail-safe-поведінкою при пошкоджених файлах.
+
+## Поведінка
+
+Читання й розбір YAML-документів з файлу:
+
+1. Намагається прочитати файл за абсолютним шляхом. Якщо читання не вдалося — викликає переданий обробник помилок із повідомленням, що включає відносний шлях і причину, і повертає `null`.
+2. Прибирає BOM на початку вмісту, якщо він є.
+3. Якщо перший рядок — це YAML-language-server modeline (`# yaml-language-server: $schema=...`), пропускає його перед розбором; решта вмісту парситься без нього. Інакше парситься весь вміст.
+4. Розбирає всі YAML-документи у файлі (мультидокументні файли з `---` підтримуються). При помилці розбору викликає обробник помилок із повідомленням і повертає `null`; інакше повертає масив розібраних документів.
+
+Окремо надає предикат розпізнавання маніфестів `Deployment`: документ вважається `Deployment`, лише якщо це звичайний об'єкт (не масив, не `null`) із полем `kind` рівним `'Deployment'`.
+
+Передбачено готовий «тихий» обробник помилок — для викликів, які мають мовчки повертати порожній результат при поганому вводі, бо пошкоджені файли діагностує окрема перевірка (`check-k8s`), а не abie.
+
+## Де використовується
+
+Хелпери імпортуються іншими модулями abie, що аналізують Kubernetes-маніфести, зокрема `lib/k8s-tree.mjs`, `lib/kustomization-patches.mjs`, `lib/http-route.mjs`, `lib/hc-yaml.mjs` та перевіркою `js/hc_pairing.mjs`.
+
+## Гарантії поведінки
+
+- Read-only: модуль лише читає й розбирає файли, не змінює їх.
+- Fail-safe: помилки читання чи розбору YAML не кидаються назовні — натомість викликається переданий обробник, а результатом стає `null`. Це дозволяє перевіркам пропускати биті файли замість падіння.
+- Розбір стійкий до BOM і до службового modeline-рядка `$schema` на першому рядку — вони не ламають парсинг і не потрапляють у результат.
+- Предикат розпізнавання `Deployment` безпечний для будь-якого вводу: повертає `false` для `null`, масивів і не-об'єктів, ніколи не кидає винятків.

package/rules/adr/docs/fix.md

@@ -0,0 +1,148 @@
+# `npm/rules/adr/fix.mjs`
+
+## Огляд
+
+Файл `fix.mjs` — це **entry-point правила `adr`** у складі пакета `@nitra/cursor`. Він виконує дві ролі одночасно й тримає мінімум власної логіки, делегуючи всю роботу до загальних бібліотечних функцій оркестрації правил:
+
+1. **Library mode (бібліотечний режим).** Експортує функцію `run(ctx)`, яку викликає зовнішній оркестратор `@nitra/cursor` (наприклад, команда `npx @nitra/cursor fix adr` або агрегований прогін усіх правил). У цьому режимі правило виконує стандартну послідовність кроків `applies → JS-concerns → policy → mdc-refs` через `runStandardRule`, а контекст (наприклад, спільний `walkCache` для обходу файлів) передається ззовні.
+2. **Standalone mode (самостійний запуск).** Якщо файл запущено напряму як CLI (наприклад, `bun npm/rules/adr/fix.mjs`), він повністю емулює виклик `npx @nitra/cursor fix adr`: завантажує конфіг, застосовує whitelist, виводить summary і повертає процесу exit-code 0/1 для CI/IDE.
+
+Файл сам по собі **не містить** ні логіки перевірки правила ADR, ні визначень policy/mdc-refs — він лише підключає механіку, спільну для всіх правил у директорії `npm/rules/*/fix.mjs`. Власне поведінка правила `adr` визначається сусідніми файлами в каталозі `npm/rules/adr/` (наприклад, `check-adr.mjs`, `.mdc`-файл, конфіг правила), які `runStandardRule` підхоплює за конвенцією на основі `import.meta.dirname`.
+
+## Експорти / API
+
+Файл публікує один іменований експорт:
+
+| Експорт | Тип / сигнатура | Призначення |
+| --- | --- | --- |
+| `run` | `(ctx?: RuleContext) => Promise<number>` | Запуск правила `adr` у library-режимі через `runStandardRule`. Повертає 0 (OK) або 1 (порушення). |
+
+Окрім експорту, файл має **top-level side-effect**: блок `if (isRunAsCli(import.meta.url)) { … }` виконується одразу при імпорті/запуску модуля та, у разі прямого CLI-запуску, завершує процес викликом `process.exit(...)`. У бібліотечному режимі (`import { run } from '...'`) цей блок не спрацьовує, бо `isRunAsCli` повертає `false`.
+
+Default-експортів, констант чи класів файл **не** надає.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Призначення.** Виконати стандартний конвеєр правила `adr`: `applies → JS-concerns → policy → mdc-refs`. Уся механіка делегується бібліотечній функції `runStandardRule`; локальної логіки немає, окрім прокидання директорії правила й контексту.
+- **Параметри.**
+  - `ctx` (необов'язковий) — `RuleContext` із `../../scripts/lib/run-standard-rule.mjs`. Контекст переноситься між викликами різних правил у межах одного запуску оркестратора й може містити, наприклад, кешований обхід файлової системи (`walkCache`), що дозволяє не повторювати дорогі операції для кожного правила. Якщо `ctx` не передано, `runStandardRule` створює власний контекст за замовчуванням.
+- **Повертає.** `Promise<number>` — `0`, якщо порушень правила немає; `1`, якщо знайдено хоча б одне порушення. Це **exit-code-сумісний** код, який далі використовується CLI-обгорткою для `process.exit`.
+- **Side effects.** У межах самого `run` побічних ефектів **не вводить**; усі ефекти (читання файлів, друк звіту, кешування) виконуються всередині `runStandardRule`. Identифікатор правила визначається неявно через `import.meta.dirname` — тобто директорія, у якій лежить цей `fix.mjs` (`npm/rules/adr`), стає каноном для пошуку всіх supplementary-файлів правила (checks, mdc, конфіг).
+- **Помилки.** Власних `try/catch` немає. Якщо `runStandardRule` кидає виняток, він проростає до викликача незмінно. У standalone-режимі винятки обробляються вже не `run`, а `runRuleCli`.
+
+### Top-level CLI-блок (не функція, але виконуваний код модуля)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Призначення.** Якщо файл запущено як головний модуль (тобто `import.meta.url` відповідає `argv[1]`), активується standalone-режим — еквівалент `npx @nitra/cursor fix adr`.
+- **Логіка.**
+  1. `isRunAsCli(import.meta.url)` визначає, чи модуль є entry-point процесу (а не імпортовано бібліотечно).
+  2. `runRuleCli(import.meta.dirname)` виконує повний CLI-pipeline для правила в цій директорії: завантаження конфігу, застосування whitelist, виклик внутрішнього `run`, друк summary, повернення numeric exit-code.
+  3. `process.exit(...)` завершує процес із цим exit-кодом — це потрібно, аби CI/IDE могли інтерпретувати успіх/невдачу.
+- **Top-level `await`.** Виклик `await runRuleCli(...)` працює завдяки ESM top-level await (`.mjs`).
+- **Pragma-коментар.** Над `process.exit` стоїть `eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` із поясненням: standalone entry-point **повинен** повертати exit-code, тому загальна заборона `process.exit` тут свідомо відключена.
+- **Чому два режими в одному файлі.** В коментарі прямо зазначено: "Дві ролі fix.mjs: library (run) + standalone (main)". Це конвенція пакета `@nitra/cursor` — кожне правило має один `fix.mjs`, який можна і `import`-ити, і запускати безпосередньо.
+
+## Залежності
+
+### Внутрішні (workspace `@nitra/cursor`)
+
+| Шлях | Імпортовані символи | Роль |
+| --- | --- | --- |
+| `../../scripts/lib/run-rule-cli.mjs` | `isRunAsCli`, `runRuleCli` | `isRunAsCli` — перевірка, чи модуль є CLI entry-point. `runRuleCli` — повний CLI-pipeline (config + whitelist + summary + exit-code). |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule` | Реалізація стандартного конвеєра правила: `applies → JS-concerns → policy → mdc-refs`. Також звідси походить JSDoc-тип `RuleContext`. |
+
+Шляхи відносні: з `npm/rules/adr/` два рівні вгору ведуть у `npm/`, далі — `scripts/lib/`.
+
+### Зовнішні (npm-пакети)
+
+Прямих імпортів зовнішніх пакетів файл **не** має. Опосередковано, через бібліотечні модулі, можуть бути задіяні стандартні утиліти Node (`node:fs`, `node:path` тощо) — але це деталь реалізації `runStandardRule` / `runRuleCli`, а не цього файла.
+
+### Платформенні вимоги
+
+- **ESM**. Розширення `.mjs` + використання `import.meta.dirname` і `import.meta.url`.
+- **`import.meta.dirname`** — доступне в Node.js ≥ 20.11 та Bun. Без цієї властивості модуль не запрацює.
+- **Top-level `await`** — для standalone-блоку.
+
+## Потік виконання / Використання
+
+### Сценарій 1. Library-режим (виклик із оркестратора)
+
+```js
+import { run } from '@nitra/cursor/rules/adr/fix.mjs'
+
+const code = await run({ walkCache /*, … */ })
+if (code !== 0) {
+  // знайдені порушення правила adr
+}
+```
+
+Послідовність кроків усередині `run`:
+
+1. `runStandardRule` отримує абсолютний шлях директорії правила (`import.meta.dirname` → `…/npm/rules/adr`).
+2. За конвенціями цієї директорії бібліотека сама знаходить:
+   - `applies`-фільтр (які файли підпадають під правило),
+   - JS-concerns-перевірки,
+   - policy-частину (rego/правила політики, якщо є),
+   - `mdc-refs` (перевірка посилань на `.mdc`-файли).
+3. Кожен крок виконується послідовно; якщо хоч один знаходить порушення — фінальний exit-code = `1`.
+4. Promise резолвиться числом `0` або `1`.
+
+Сам файл `fix.mjs` у цьому потоці — **тонка обгортка**: він не приймає рішень і не друкує нічого власноруч.
+
+### Сценарій 2. Standalone-режим (запуск напряму)
+
+```bash
+bun npm/rules/adr/fix.mjs
+# або
+node npm/rules/adr/fix.mjs
+```
+
+Послідовність:
+
+1. Модуль завантажується, `run` стає експортованим.
+2. Виконується top-level умова `isRunAsCli(import.meta.url)` → `true`.
+3. `runRuleCli(import.meta.dirname)` бере на себе:
+   - читання конфігу (наприклад, `.cursor`-конфіг або CLI-параметри),
+   - застосування whitelist (обмеження файлів, які проходять перевірку),
+   - виклик внутрішньої функції `run` цього ж правила,
+   - друк підсумкового summary (скільки файлів, скільки порушень),
+   - повернення exit-code (`0` або `1`).
+4. `process.exit(...)` зупиняє процес із цим кодом — CI/IDE отримують стандартний сигнал успіху/невдачі.
+
+Цей режим — еквівалент `npx @nitra/cursor fix adr`, але без потреби у глобально встановленому CLI: достатньо мати checkout репозиторію.
+
+### Сценарій 3. Імпорт без виконання (рідкісний)
+
+Якщо файл імпортується умовами, де `import.meta.url !== argv[1]`, спрацьовує лише експорт `run`; CLI-блок мовчазно пропускається. Це і є основою «двох ролей»: ESM-модуль безпечно імпортувати з будь-якого місця без сайд-ефекту запуску процесу.
+
+### Контекст у системі правил
+
+Файл вписується у плаский набір правил `npm/rules/<id>/fix.mjs`. Кожне правило має такий самий каркас, відрізняючись лише іменем директорії (а отже — `import.meta.dirname`) та допоміжними файлами поруч (`check-*.mjs`, `*.mdc` тощо). Логіка спільного pipeline винесена у `scripts/lib/run-standard-rule.mjs` і `scripts/lib/run-rule-cli.mjs`, що робить `fix.mjs` максимально декларативним: він — «адаптер» між директорією правила та оркестратором.
+
+## Rebuild Test
+
+Якщо знищити цей файл і реконструювати з документації вище, відновлювана версія повинна:
+
+1. Бути ESM-модулем (`.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)` (без `await`, бо promise повертається як є).
+5. Мати JSDoc-блок до `run` з посиланням на тип `RuleContext` з `run-standard-rule.mjs` та описом `@returns {Promise<number>}` із семантикою `0 — OK, 1 — порушення`.
+6. Містити top-level умову `if (isRunAsCli(import.meta.url))`, всередині якої виконується `process.exit(await runRuleCli(import.meta.dirname))`.
+7. Над `process.exit` мати ESLint-disable-коментар для `n/no-process-exit` та `unicorn/no-process-exit` із поясненням, що standalone entry-point повинен повертати exit-code для CI/IDE.
+8. **Не** містити жодної додаткової логіки правила `adr` всередині — уся механіка делегована бібліотечним функціям.
+
+Реконструйована версія за цими інваріантами буде функціонально еквівалентною оригіналу.