@nitra/cursor 5.3.4 → 5.4.0

package/rules/adr/docs/fix.md

@@ -1,154 +1,39 @@
 ---
 docgen:
   source: npm/rules/adr/fix.mjs
-  crc: b46c541a
+  crc: 38cf876b
+  score: 100
 ---
 
-# `npm/rules/adr/fix.mjs`
+# fix.mjs
 
 ## Огляд
 
-Файл `fix.mjs` — це **entry-point правила `adr`** у складі пакета `@nitra/cursor`. Він виконує дві ролі одночасно й тримає мінімум власної логіки, делегуючи всю роботу до загальних бібліотечних функцій оркестрації правил:
+Виконує обробку JS-занепокоєних та політики на наданому контексті прогону. Генерація посилання MDC та повернення результату прогону.
 
-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`.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
+2. Виконання у режимі CLI.
+    *   Виконується як автономний скрипт.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації.
+    *   Виконує перевірку дозволених елементів.
+    *   Генерує зведену інформацію.
+    *   Визначає код виходу процесу.
 
-## Експорти / API
+## Публічний API
 
-Файл публікує один іменований експорт:
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-| Експорт | Тип / сигнатура | Призначення |
-| --- | --- | --- |
-| `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` всередині — уся механіка делегована бібліотечним функціям.
-
-Реконструйована версія за цими інваріантами буде функціонально еквівалентною оригіналу.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/bun/docs/fix.md

@@ -1,165 +1,32 @@
 ---
 docgen:
   source: npm/rules/bun/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# `npm/rules/bun/fix.mjs`
+# fix.mjs
 
 ## Огляд
 
-Файл є точкою входу для правила `bun` у системі правил `@nitra/cursor`. Він виконує дві ролі одночасно:
+Виконує обробку JS-занепокоєних даних у наданому контексті прогону. Застосовує визначену політику та генерує посилання MDC. Повертає результат прогону.
 
-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/`).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
-Цей патерн ідентичний у всіх однотипних правил `npm/rules/<id>/fix.mjs` — фактично це тонкий «диспатчер», який прив’язує конкретне правило (визначене теками-сусідами через `import.meta.dirname`) до загальної інфраструктури запуску.
+## Публічний API
 
-## Експорти / API
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-| Експорт | Тип                                            | Опис                                                                                                                                                  |
-| ------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/capacitor/docs/fix.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/capacitor/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
   score: 100
 ---
 
@@ -9,24 +9,27 @@ docgen:
 
 ## Огляд
 
-Модуль ініціює та виконує ключову операцію системи. Він приймає вхідні дані з конфігураційного файлу `config.json` для генерації фінального результату. Файл використовується для запуску процесу та завершення обробки.
+Виконує застосування JS-занепокоєних на вхідний контекст прогону, застосовує визначену політику, генерує посилання MDC та повертає результат
 
 ## Поведінка
 
-1. Запуск перевірки. Викликається функція для виконання правила.
-
-2. Виконання правила. Правило застосовується до конфігурації.
-
-3. Обробка результату. Функція повертає результат перевірки. Нуль означає успішне проходження, одиниця означає виявлення порушення.
-
-4. Режим бібліотеки. Виклик функції відбувається через стандартний механізм оркестрації.
-
-5. Режим автономного запуску. Якщо виконання відбувається через командний рядок, функція виконує повний цикл роботи, включаючи завантаження конфігурації, перевірку дозволів та формування зведення. Результат повертається як код виходу для інструментів CI/IDE.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат.
+2. Запуск у режимі CLI.
+    *   Виконується як повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації.
+    *   Виконує перевірку дозволених записів.
+    *   Генерує зведену інформацію.
+    *   Використовує `process.exitCode` для визначення виходу.
 
 ## Публічний API
 
-run — Запускає ланцюжок перевірок: applies → JS-concerns → policy → mdc-refs за допомогою runStandardRule.
-Library mode — Викликається через CLI оркестрацію за допомогою import + run.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
 ## Гарантії поведінки
 

package/rules/capacitor/js/docs/platforms.md

@@ -1,89 +1,77 @@
 ---
 docgen:
   source: npm/rules/capacitor/js/platforms.mjs
-  crc: eb8d6293
-  score: 100
+  crc: d102129c
+  score: 85
 ---
 
 # platforms.mjs
 
 ## Огляд
 
-Модуль інспектує та збирає дані конфігурацій Capacitor для оцінки сумісності версій. Він використовується для перевірки наявності та відповідності версій Capacitor, необхідних для коректної роботи з iOS-проєктами. Функції, такі як `collectCapacitorDataFromAllPackageJson`, забезпечують збір необхідної інформації. Модуль спирається на конфігурації, визначені у файлі `.config.json`. Функція `check` та `isCapacitorRelevantForCheck` застосовуються для визначення релевантності конфігурації. (capacitor.mdc)
+Огляд
+
+Цей файл містить інструменти для витягування та перевірки версій Capacitor з залежностей та конфігурацій. Використовується для визначення сумісності версій Capacitor з конфігураціями, а також для збору даних про версії з різних файлів.
 
 ## Поведінка
 
 capacitorSegmentMinMajor
-Витягує мінімальний мажорний номер з частини діапазону npm версій
+Витягує мінімальну мажорну версію з частини діапазону npm версії
 
 capacitorVersionRangeMinMajor
-Обчислює мінімальний мажорний номер для повного діапазону npm версій з урахуванням `||`
+Витягує мінімальну мажорну версію з повного діапазону npm версії
 
 isCapacitorCoreVersionAtLeast8
-Перевіряє, чи нижня межа версії Capacitor є більшою або дорівнює заданому мінімуму
+Перевіряє, чи нижня межа версії Capacitor ≥ мінімальної версії
 
 recordCapacitorFromOnePackageJson
-Записує інформацію про залежності Capacitor у накопичувач
+Записує дані Capacitor з об'єкта з залежностей у накопичувач
 
 collectCapacitorDataFromAllPackageJson
-Рекурсивно шукає та збирає інформацію про залежності Capacitor з усіх `package.json` у репозиторії
+Зчитує дані Capacitor з усіх package.json у дереві
 
 hasCapacitorConfigInRoot
-Перевіряє наявність конфігураційних файлів Capacitor у корені репозиторію
+Перевіряє наявність конфігурації Capacitor у корені
 
 isCapacitorRelevantForCheck
-Визначає, чи потрібно застосовувати перевірку Capacitor на основі наявності конфігурації або залежностей
+Визначає, чи потрібно застосовувати перевірку Capacitor
 
 walkIosForPodfileSkipPods
-Рекурсивно шукає файли `Podfile` у каталозі `ios`, ігноруючи папки `Pods`, `build` та `DerivedData`
+Рекурсивно шукає Podfile у каталозі ios, ігноруючи Pods та build
 
 findFirstPodfileUnderIosExcludingPods
-Шукає перший знайдений `Podfile` у каталозі `ios`, ухиляючись від кешу CocoaPods
+Знаходить перший Podfile у каталозі ios, усуваючи Pods
 
 nitrAObjectAllowsIosCocoaPods
-Перевіряє, чи дозволяє об'єкт `nitra` використання `Podfile` на iOS через спеціальні прапори
-
-extractNitraObjectBodySource
-Витягує текст тіла об'єкта `{...}` після маркера `nitra:` у конфігураційному файлі
-
-nitraObjectBodyStringAllowsCocoaPodsExempt
-Перевіряє, чи містить витягнутий текст виняток, який дозволяє пропуск аналізу SPM
-
-pathJsonShowsNitraCocoapodsExempt
-Перевіряє, чи містить об'єкт `nitra` у JSON-файлі виняток, який дозволяє пропуск аналізу SPM
-
-capacitorConfigTsMjsNitraCocoapodsExempt
-Перевіряє, чи містить конфігураційні файли `.ts` або `.mjs` виняток, який дозволяє пропуск аналізу SPM
-
-isIosCocoaPodsExemptByNitraConfig
-Перевіряє, чи дозволяє конфігурація `nitra` використання `Podfile` на iOS
+Перевіряє, чи дозволяє об'єкт nitra використання Podfile
 
 check
-Виконує повну перевірку конфігурації Capacitor, включаючи перевірку залежностей та налаштувань iOS
+Запускає перевірку відповідності версій Capacitor та конфігурації
 
-Повертає помилку, якщо не знайдено необхідної залежності `@capacitor/core` з версією, сумісною з `MIN_CAPACITOR_MAJOR`
+reportOneCapacitorCoreRange
+Друкує повідомлення про сумісність версії Capacitor з (capacitor.mdc)
 
-Повертає помилку, якщо знайдено `Podfile` на iOS, який не дозволяє використання CocoaPods без винятку `nitra`
+recordCapacitorFromDependencyObject
+Записує дані Capacitor з об'єкта з залежностей у накопичувач
 
 ## Публічний API
 
-capacitorSegmentMinMajor — визначає нижню межу для однієї частини діапазону npm.
-capacitorVersionRangeMinMajor — визначає мінімальну можливу (нижню) major-версію для повного діапазону npm, включаючи `||`.
-isCapacitorCoreVersionAtLeast8 — перевіряє, чи відповідає версія ядру Capacitor мінімальному рівню 8.
-recordCapacitorFromOnePackageJson — записує дані Capacitor з одного файлу `package.json`.
-collectCapacitorDataFromAllPackageJson — збирає дані Capacitor з усіх `package.json` у дереві, накопичуючи `byPath` та `anyCapacitor`.
+capacitorSegmentMinMajor — визначає найнижчу межу для однієї частини діапазону npm.
+capacitorVersionRangeMinMajor — визначає найнижчу можливу версію major для повного діапазону npm, включаючи `||`.
+isCapacitorCoreVersionAtLeast8 — перевіряє, чи версія Capacitor Core становить мінімум 8.
+recordCapacitorFromOnePackageJson — записує дані Capacitor з одного файлу package.json.
+collectCapacitorDataFromAllPackageJson — зчитує всі package.json з дерева, збирає byPath та anyCapacitor.
 hasCapacitorConfigInRoot — перевіряє наявність конфігурації Capacitor у кореневому файлі.
-isCapacitorRelevantForCheck — визначає, чи слід застосовувати правила, залежно від наявності конфігу або `@capacitor/` у залежностях.
-walkIosForPodfileSkipPods — рекурсивно шукає `Podfile` у директорії `ios/`, ігноруючи директорії `Pods` (кеш CocoaPods) та типові build-каталоги.
-findFirstPodfileUnderIosExcludingPods — знаходить перший `Podfile` у директорії `ios/`, пропуская директорії `Pods`.
-nitrAObjectAllowsIosCocoaPods — перевіряє, чи дозволяє об’єкт `nitra` використовувати `Podfile` (CocoaPods) на iOS (див. (capacitor.mdc); `@nitra/SPM` не аналізується).
-check — виконує загальну перевірку.
+isCapacitorRelevantForCheck — визначає, чи слід використовувати правила, залежно від конфігу або `@capacitor/` у залежностях.
+walkIosForPodfileSkipPods — рекурсивно шукає Podfile у ios/, ігноруючи Pods та типові build-каталоги.
+findFirstPodfileUnderIosExcludingPods — знаходить перший Podfile у ios/, виключаючи Pods.
+nitrAObjectAllowsIosCocoaPods — перевіряє, чи дозволяє об'єкт nitra використовувати Podfile на iOS (див. capacitor.mdc та @nitra/).
+check — виконує перевірку.
 
 ## Гарантії поведінки
 
 - Read-only: файл не виконує операцій запису у файлову систему.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдалої перевірки повертає `false`/`null` замість винятку.
-- Кешує результати в межах одного прогону.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Свідомо пропускає шляхи: `.git`, `node_modules`.
 - Не звертається до мережі.