@nitra/cursor 5.1.0 → 5.2.0

package/rules/bun/js/docs/layout.md

@@ -1,393 +1,55 @@
-# layout.mjs — перевірка відповідності правилам Bun (`bun.mdc`)
+---
+docgen:
+  source: npm/rules/bun/js/layout.mjs
+  crc: ba2a6730
+  score: 100
+---
 
-## Огляд
-
-Модуль `npm/rules/bun/js/layout.mjs` — це JS-частина rule-перевірки **bun** для CLI `@nitra/cursor`. Він перевіряє ту частину правил `bun.mdc`, яку **неможливо** покрити Rego-політиками з `npm/policy/bun/*` (тобто FS-existence та cross-file зв'язки між `.n-cursor.json` і `package.json`).
-
-Призначений запускатися як check у кореневому репозиторії (`cwd = process.cwd()`). Перевіряє три блоки інваріантів:
-
-1. **FS-наявність обовʼязкових файлів** монорепозиторію Bun:
-   - `bun.lock` (lockfile від `bun i`);
-   - `bunfig.toml` (наявність файла; структуру (`[install].linker == "hoisted"`) перевіряє Rego — `npm/policy/bun/bunfig/`);
-   - `package.json` у корені.
-2. **Заборонені артефакти конкурентних пакет-менеджерів** (yarn / pnpm / npm):
-   - файли `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `.yarnrc.yml`;
-   - директорія `.yarn/`.
-3. **Двосторонній зв'язок** між `.n-cursor.json:rules` / `disable-rules` та `package.json:scripts` для правил, що мають окрему `lint-<id>`-обгортку:
-   - правило активне (присутнє у `rules`) → скрипт `lint-<id>` мусить існувати;
-   - правило не активне (немає в `rules` або є в `disable-rules`) → скрипту `lint-<id>` і токена `bun run lint-<id>` в агрегованому `scripts.lint` **не може** бути (інакше `bun run lint` падатиме на правилі, яке у конфізі вимкнено).
-
-Те, що покриває **Rego** (тобто **не** перевіряється цим файлом):
-
-- `npm/policy/bun/bunfig/` — `[install].linker == "hoisted"` у `bunfig.toml`;
-- `npm/policy/bun/package_json/` — відсутність `packageManager` / `dependencies` у кореневому `package.json`, у `devDependencies` лише пакети `@nitra/*`, агрегований `lint`-скрипт покриває всі `lint-*` через `bun run` і завершується `&& oxfmt .`.
-
-JS-копії перевірок `devDependencies` (історично — `isAllowedRootDevDependency`) **видалено**, щоб уникнути дублювання джерела істини.
-
-Звітування винесене в `createCheckReporter()` з `../../../scripts/lib/check-reporter.mjs`: модуль не друкує сам, а викликає `pass(msg)` / `fail(msg)`, після чого повертає `reporter.getExitCode()` (`0` — все OK, `1` — є провали).
-
-## Експорти / API
-
-Модуль експортує **одну** іменовану функцію:
-
-| Експорт | Сигнатура                                 | Призначення                                         |
-| ------- | ----------------------------------------- | --------------------------------------------------- |
-| `check` | `async (cwd?: string) => Promise<number>` | Точка входу check-у; повертає exit-код (`0` / `1`). |
-
-Усе інше (`WHITESPACE_RE`, `RULE_SCRIPTS`, `loadNCursorRules`, `lintChainHasScript`, `backtickJoin`, `ownerStatus`, `checkCursorRuleScripts`) — **внутрішні** (module-private), не експортуються.
-
-## Константи
-
-### `WHITESPACE_RE`
-
-```js
-const WHITESPACE_RE = /\s+/u
-```
-
-Регулярний вираз для розділення значення `scripts.lint` на токени (послідовність пробільних символів). Використовується в `lintChainHasScript` для безпечного матчингу токена `bun run <script>` як **окремого** токена (а не префікса). Прапорець `u` — Unicode-сумісний матчинг пробілів.
-
-### `RULE_SCRIPTS`
-
-```js
-const RULE_SCRIPTS = [
-  { rules: ['docker'], script: 'lint-docker', doc: 'docker.mdc' },
-  { rules: ['k8s'], script: 'lint-k8s', doc: 'k8s.mdc' },
-  { rules: ['image-avif', 'image-compress'], script: 'lint-image', doc: 'image-avif.mdc / image-compress.mdc' }
-]
-```
-
-Декларативна таблиця обгорток `lint-<id>` та їхніх правил-власників. Один скрипт може мати **кілька** власників (`lint-image` обслуговує і `image-avif`, і `image-compress`); скрипт вважається «потрібним», якщо **хоча б одне** з власних правил активне у `.n-cursor.json:rules`.
-
-Кожен елемент має тип `RuleScript`:
-
-```ts
-type RuleScript = {
-  rules: string[] // id правил-власників (>= 1); поки активний хоча б один — скрипт обовʼязковий
-  script: string // ім'я скрипта в package.json:scripts (напр. "lint-docker")
-  doc: string // .mdc-файл (або кома-список) для повідомлення check-у
-}
-```
-
-Розширення таблиці — єдиний спосіб додати нову `lint-<id>`-обгортку під перевірку двостороннього звʼязку.
-
-## Функції
-
-### `loadNCursorRules(cwd)`
-
-```js
-async function loadNCursorRules(cwd: string): Promise<{ rules: Set<string>, disabled: Set<string> }>
-```
-
-Зчитує `.n-cursor.json` із кореня репозиторію та повертає набори активних і явно вимкнених правил.
-
-**Параметри:**
-
-- `cwd` — абсолютний шлях до кореня репозиторію.
-
-**Повертає:** `Promise<{ rules: Set<string>, disabled: Set<string> }>`:
-
-- `rules` — `Set` рядків зі значення `rules` у JSON; якщо поле відсутнє або не масив — порожній `Set`.
-- `disabled` — `Set` рядків зі значення `disable-rules`; якщо поле відсутнє або не масив — порожній `Set`.
-
-**Поведінка при помилках (fail-safe):**
-
-- файл `.n-cursor.json` відсутній — повертає `{ rules: new Set(), disabled: new Set() }`;
-- помилка `JSON.parse` — повертає той самий «порожній» обʼєкт (через `try/catch` без логування).
-
-**Side effects:** виключно `fs.promises.readFile` (асинхронне читання UTF-8) та `existsSync` для перевірки наявності.
-
-### `lintChainHasScript(lintScript, target)`
-
-```js
-function lintChainHasScript(lintScript: string, target: string): boolean
-```
-
-Перевіряє, чи містить chain зі `scripts.lint` виклик саме `bun run <target>` **як окремий токен**.
-
-**Параметри:**
-
-- `lintScript` — значення `scripts.lint` (або порожній рядок, якщо його немає).
-- `target` — ім'я скрипта без префіксів (`lint-docker`, `lint-k8s`, `lint-image`).
-
-**Повертає:** `boolean` — `true`, якщо в розбитому за пробілами chain'і знайдено послідовність токенів `bun`, `run`, `<target>` поруч.
-
-**Чому саме «токени», а не `String.prototype.includes`:** інакше виникне false-positive для `bun run lint-k8s-foo`, який матчиться як префікс `bun run lint-k8s`. Розбиття за `WHITESPACE_RE` усуває цю проблему — кожен токен порівнюється повним рівнем.
-
-**Side effects:** немає (чиста функція).
-
-### `backtickJoin(items, sep)`
-
-```js
-function backtickJoin(items: string[], sep: string): string
-```
-
-Загортає кожен елемент у backticks і зʼєднує через `sep`. Винесено окремо, щоб не нестити template literals у `pass` / `fail`-повідомленнях.
-
-**Параметри:**
-
-- `items` — масив ідентифікаторів (наприклад id правил).
-- `sep` — роздільник (`', '` для перерахування, `'/'` для альтернативного списку).
-
-**Повертає:** рядок виду `` `a`, `b` `` (або `` `a`/`b` ``).
-
-**Side effects:** немає (чиста функція).
+# layout.mjs
 
-### `ownerStatus(owners, cursorRules)`
-
-```js
-function ownerStatus(
-  owners: string[],
-  cursorRules: { rules: Set<string>, disabled: Set<string> }
-): { enabled: string[], reason: string }
-```
-
-Описує стан правил-власників скрипта для повідомлень про `reason`. Повертає або список увімкнених власників (для passing-кейсу «правило є»), або компактний опис, чому всі вимкнені (для inverse-fail).
-
-**Параметри:**
-
-- `owners` — id правил-власників (`>= 1`).
-- `cursorRules` — `{ rules, disabled }`, отриманий від `loadNCursorRules`.
-
-**Повертає:** `{ enabled, reason }`:
-
-- `enabled` — підмасив `owners`, які присутні в `cursorRules.rules`.
-- `reason` — людинозрозумілий текст про стан правил для логу:
-  - якщо є хоча б один активний — `` правило `x` `` або `` правила `x`, `y` `` (з узгодженням числа: `правило` / `правила`);
-  - якщо власник один і не активний — `` правило `x` `` + (`в disable-rules` | `відсутнє в rules`);
-  - якщо власників кілька й жоден не активний — `` `a`/`b` `` + (`усі власники в disable-rules` | `жоден власник не активний у rules`); вибір ноти залежить від того, чи **всі** власники у `disable-rules`, чи лише «не в rules».
-
-**Side effects:** немає (чиста функція).
-
-### `checkCursorRuleScripts(reporter, scripts, cursorRules)`
-
-```js
-function checkCursorRuleScripts(
-  reporter: { pass: (msg: string) => void, fail: (msg: string) => void },
-  scripts: Record<string, string>,
-  cursorRules: { rules: Set<string>, disabled: Set<string> }
-): void
-```
-
-Перевіряє двосторонній зв'язок `rules` ↔ `scripts.lint-<id>` для всіх записів із `RULE_SCRIPTS`.
-
-**Параметри:**
-
-- `reporter` — обʼєкт з callback-ами `pass(msg)` / `fail(msg)` (від `createCheckReporter()`).
-- `scripts` — обʼєкт `scripts` із розпарсеного `package.json`.
-- `cursorRules` — `{ rules, disabled }` з `loadNCursorRules`.
-
-**Алгоритм на кожен запис `RULE_SCRIPTS`:**
-
-1. `status = ownerStatus(owners, cursorRules)`.
-2. `present = Boolean(scripts[script])` — чи є скрипт у `package.json:scripts`.
-3. `inChain = lintChainHasScript(scripts.lint, script)` — чи згаданий `bun run <script>` у chain'і `scripts.lint` (якщо `scripts.lint` не рядок — `lintScript = ''`).
-4. **Якщо хоч одне правило-власник активне** (`status.enabled.length > 0`):
-   - `present === true` → `pass`: ``package.json: є `<script>` (<reason> у .n-cursor.json)``;
-   - `present === false` → `fail`: ``У .n-cursor.json увімкнено <reason> — додай скрипт `<script>` у кореневий package.json (див. <doc>)``;
-   - далі `continue` (не перевіряємо inverse-кейс).
-5. **Якщо жоден власник не активний:**
-   - `present === true` → `fail`: ``У .n-cursor.json немає активних власників `a`/`b` — прибери скрипт `<script>` з кореневого package.json (див. <doc>)``;
-   - `inChain === true` → `fail`: ``У `scripts.lint` є `bun run <script>`, але серед `a/b` жоден не активний у .n-cursor.json — прибери з ланцюжка lint (див. <doc>)``;
-   - `!present && !inChain` → `pass`: ``package.json: `<script>` відсутній (<reason>)``.
-
-Зверни увагу: коли `present === true` і `inChain === true` одночасно (при неактивних власниках), будуть **два** `fail`-повідомлення — окремо про скрипт і окремо про chain. Це дозволяє лагодити обидва місця одним проходом.
-
-**Side effects:** виклики `reporter.pass()` / `reporter.fail()` (тобто акумуляція в звіт, що формує exit-код).
-
-### `check(cwd?)` — публічна точка входу
-
-```js
-export async function check(cwd: string = process.cwd()): Promise<number>
-```
-
-**Параметри:**
-
-- `cwd` — корінь репозиторію. За замовчуванням — `process.cwd()`.
-
-**Повертає:** `Promise<number>` — exit-код від `reporter.getExitCode()`: `0` (усі перевірки pass) або `1` (є хоча б один `fail`).
-
-**Послідовність перевірок:**
-
-1. Створюється `reporter = createCheckReporter()`; деструктуруються `{ pass, fail }`.
-2. **Заборонені lockfile / конфіги конкурентних PM:** для кожного з `['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', '.yarnrc.yml']` — `existsSync` → `fail`("Знайдено заборонений файл: ..."); інакше `pass`("Немає ...").
-3. **Директорія `.yarn/`** — `existsSync` → `fail`("Знайдено директорію .yarn — видали її") / `pass`("Немає .yarn/").
-4. **`bun.lock`** — `existsSync` → `pass`("bun.lock є") / `fail`("Відсутній bun.lock — запусти bun i").
-5. **`bunfig.toml`** — `existsSync` → `pass` (з підказкою, що структуру перевіряє Rego через `npx @nitra/cursor fix → bun.bunfig`) / `fail` ("Відсутній bunfig.toml — створи з `[install] linker = \"hoisted\"` (bun.mdc)").
-6. **Завантаження `.n-cursor.json`** через `loadNCursorRules(cwd)`.
-7. **Кореневий `package.json`:**
-   - якщо відсутній → `fail`("Відсутній package.json у корені") і **ранній вихід** через `return reporter.getExitCode()` (далі чекери не виконуються);
-   - інакше — читається через `readFile(...,'utf8')` + `JSON.parse`.
-8. **`scripts`** береться як `pkg.scripts` (з захистом від `null`/не-обʼєктів через `typeof === 'object'`); якщо `scripts` некоректний — `{}`.
-9. **Виклик** `checkCursorRuleScripts(reporter, scripts, cursorRules)`.
-10. **Повернення** `reporter.getExitCode()`.
-
-**Side effects:**
-
-- синхронні читання FS через `existsSync` (≥ 8 викликів);
-- асинхронне читання `.n-cursor.json` і `package.json` через `fs/promises.readFile`;
-- мутація стану `reporter` через `pass` / `fail`;
-- `JSON.parse` обох конфігів — для `package.json` **без** `try/catch` (битий JSON у корені призведе до `throw` назовні; це усвідомлений вибір — кореневий `package.json` має бути валідним JSON, інакше нічого не запуститься).
-
-## Залежності
-
-### Зовнішні (Node.js core)
-
-- `node:fs` → `existsSync` — синхронна перевірка FS-існування файлів і директорії `.yarn/`.
-- `node:fs/promises` → `readFile` — асинхронне читання `.n-cursor.json` і `package.json` (UTF-8).
-- `node:path` → `join` — побудова шляхів у `cwd`.
-
-### Внутрішні
-
-- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера з API `{ pass, fail, getExitCode }`. Це **єдина** проєктна залежність модуля; усі повідомлення йдуть через неї, exit-код — теж.
-
-### Що **не** імпортується (свідомо)
-
-- Rego-логіка політик `npm/policy/bun/*` — викликається окремо через `npx @nitra/cursor check` / `fix`; цей модуль ані не запускає Rego, ані не дублює його перевірки.
-- Жодних спільних утиліт для роботи з `package.json` — `JSON.parse` робиться інлайн, бо схема локальна (потрібен лише `scripts`).
-
-## Потік виконання / Використання
-
-### Як викликається з CLI
-
-Файл `layout.mjs` — це JS-частина rule-перевірки `bun` (директорія `npm/rules/bun/js/`). CLI `@nitra/cursor` (через свій диспатчер у `npm/cli/*` та `npm/scripts/lint/*`) автоматично знаходить такі `layout.mjs`-точки входу для всіх включених у `.n-cursor.json:rules` правил і викликає експортовану `check(cwd)`. Exit-код пробрасується назовні: якщо `check` повертає `1`, CLI рапортує `fail` цього rule-у, що далі піднімається на рівень агрегованого `bun run lint`.
-
-### Типовий потік
-
-```
-n-cursor check / lint (CLI)
-        |
-        v
-import { check } from 'npm/rules/bun/js/layout.mjs'
-        |
-        v
-check(cwd)
-        |
-        +-> existsSync × forbidden files / .yarn          -> pass | fail
-        |
-        +-> existsSync bun.lock / bunfig.toml             -> pass | fail
-        |
-        +-> loadNCursorRules(cwd)
-        |       \-> readFile '.n-cursor.json' (silent on error)
-        |
-        +-> readFile + JSON.parse 'package.json'
-        |       (early return on missing)
-        |
-        +-> checkCursorRuleScripts(reporter, scripts, cursorRules)
-        |       \-> for each RULE_SCRIPTS:
-        |             ownerStatus -> lintChainHasScript -> pass/fail
-        |
-        +-> return reporter.getExitCode()  // 0 | 1
-```
-
-### Сценарій A — все OK
-
-`.n-cursor.json`:
-
-```json
-{ "rules": ["docker", "k8s"] }
-```
-
-`package.json:scripts`:
-
-```json
-{
-  "lint-docker": "n-cursor lint-docker",
-  "lint-k8s": "n-cursor lint-k8s",
-  "lint": "bun run lint-docker && bun run lint-k8s && oxfmt ."
-}
-```
-
-- `bun.lock`, `bunfig.toml`, `package.json` — присутні.
-- Жоден із заборонених файлів / `.yarn/` не існує.
-- Для `docker` і `k8s` — `enabled.length > 0`, `present === true` → два `pass`.
-- Для `lint-image` — жоден власник (`image-avif`/`image-compress`) не активний, скрипт відсутній, у chain'і його немає → `pass` ("`lint-image` відсутній (`image-avif`/`image-compress` — жоден власник не активний у rules)").
-- Exit-код: `0`.
-
-### Сценарій B — k8s у `disable-rules`, але `lint-k8s` залишився
-
-`.n-cursor.json`:
-
-```json
-{ "disable-rules": ["k8s"] }
-```
+## Огляд
 
-`package.json:scripts`:
+Файл надає інструмент для перевірки відповідності даних визначеному контракту. Функція `check` (bun.mdc) виконує перевірку стану даних і повертає логічний результат, що вказує на успішність виконання перевірки. У разі невдачі функція повертає `false` або `null` замість генерації винятку.
 
-```json
-{
-  "lint-k8s": "n-cursor lint-k8s",
-  "lint": "bun run lint-k8s && oxfmt ."
-}
-```
+## Поведінка
 
-- `ownerStatus(['k8s'], ...)` → `enabled: []`, `reason: "правило \`k8s\` в disable-rules"`.
-- `present === true` → `fail`: "У .n-cursor.json немає активних власників `k8s` — прибери скрипт `lint-k8s` з кореневого package.json (див. k8s.mdc)".
-- `inChain === true` → `fail`: "У `scripts.lint` є `bun run lint-k8s`, але серед `k8s` жоден не активний у .n-cursor.json — прибери з ланцюжка lint (див. k8s.mdc)".
-- Exit-код: `1`.
+1. Завантаження конфігурації
+   Завантажувач зчитує налаштування правил та вимкнених правил з файлу `.n-cursor.json` у корені репозиторію. Якщо файл відсутній, повертається порожній набір правил.
 
-### Сценарій C — `image-avif` активний, `lint-image` відсутній
+2. Перевірка зв'язку скриптів
+   Система перевіряє зв'язок між ідентифікаторами правил, визначеними у конфігурації, та наявністю скриптів у кореневому `package.json`.
 
-`.n-cursor.json`:
+3. Оцінка стану власників
+   Оцінювач визначає стан кожного правила-власника, порівнюючи активні правила з налаштуваннями. Якщо активне правило присутнє, результат позначається як успішний. Якщо власник відсутній у налаштуваннях, результат позначається як провал, якщо власник не був вимкнений.
 
-```json
-{ "rules": ["image-avif"] }
-```
+4. Перевірка ланцюжків виконання
+   Система перевіряє, чи згадує ланцюжок виконання `bun run <скрипт>` конкретний скрипт. Ця перевірка виконується для уникнення хибних спрацьовувань через префікси.
 
-`package.json:scripts`: (немає `lint-image`)
+5. Перевірка відповідності
+   Основна перевірка встановлює, що якщо скрипт присутній у `package.json`, він повинен бути активним у конфігурації. Якщо скрипт присутній, але власники не активні, система вимагає видалення скрипта з кореневого файлу.
 
-- `ownerStatus(['image-avif', 'image-compress'], ...)` → `enabled: ['image-avif']`, `reason: "правило \`image-avif\`"`.
-- `present === false` → `fail`: "У .n-cursor.json увімкнено правило `image-avif` — додай скрипт `lint-image` у кореневий package.json (див. image-avif.mdc / image-compress.mdc)".
-- Exit-код: `1`.
+6. Перевірка ланцюжків та вимкнених правил
+   Якщо ланцюжок виконання `bun run <скрипт>` присутній, але жоден власник не активний, система вимагає видалення з ланцюжка виконання.
 
-### Сценарій D — відсутній `package.json`
+7. Перевірка відсутності
+   Якщо скрипт відсутній і власники не активні, система позначає це як успішне проходження.
 
-- `pass` / `fail` по lockfile + `bun.lock` + `bunfig.toml` як завжди.
-- Після `loadNCursorRules` — `existsSync(pkgPath) === false` → `fail`("Відсутній package.json у корені") і **ранній `return`**.
-- `checkCursorRuleScripts` **не викликається**.
-- Exit-код: `1`.
+8. Перевірка заборонених файлів
+   Система перевіряє наявність заборонених файлів у корені репозиторію, включаючи файли блокування залежностей та директорії `.yarn`.
 
-### Контракт із Rego / `.mdc`
+9. Перевірка залежностей
+   Система перевіряє наявність необхідного файлу `bun.lock`. Відсутність цього файлу є провалом, що вимагає запуску `bun i`.
 
-Цей файл є JS-частиною rule `bun`. Він **доповнює** Rego-політики `npm/policy/bun/bunfig/` і `npm/policy/bun/package_json/`, які перевіряють структуру файлів (а не їх існування або crossref). Опис правила людською мовою — у `bun.mdc` (на нього посилаються `pass`/`fail`-повідомлення про `bunfig.toml`).
+10. Перевірка конфігурації Bun
+    Система перевіряє наявність файлу `bunfig.toml`, який використовується для перевірки структури, необхідної для використання `linker = "hoisted"` у `bun.mdc`.
 
-При додаванні нової `lint-<id>`-обгортки достатньо розширити масив `RULE_SCRIPTS` — функції `ownerStatus`, `checkCursorRuleScripts`, `lintChainHasScript` та `backtickJoin` працюють декларативно й нової JS-логіки не потребують.
+## Публічний API
 
-## Rebuild Test
+check — перевіряє, чи відповідає проєкт вимогам bun.mdc
 
-Цей блок описує, що саме треба було б реалізувати, щоб отримати функціонально еквівалентний `layout.mjs` з нуля — для перевірки повноти документації:
+## Гарантії поведінки
 
-1. **ESM-модуль** на стандартному Node.js (без зовнішніх пакетів окрім `createCheckReporter`).
-2. Імпортувати `existsSync` з `node:fs`, `readFile` з `node:fs/promises`, `join` з `node:path`, `createCheckReporter` з `../../../scripts/lib/check-reporter.mjs`.
-3. Оголосити константу `WHITESPACE_RE = /\s+/u`.
-4. Оголосити масив `RULE_SCRIPTS` з трьох елементів (`docker`/`lint-docker`/`docker.mdc`, `k8s`/`lint-k8s`/`k8s.mdc`, `['image-avif','image-compress']`/`lint-image`/`'image-avif.mdc / image-compress.mdc'`).
-5. Реалізувати `loadNCursorRules(cwd)`:
-   - перевірити `existsSync(join(cwd, '.n-cursor.json'))`; якщо ні — повернути `{ rules: new Set(), disabled: new Set() }`;
-   - `try { JSON.parse(await readFile(..., 'utf8')) } catch { return empty }`;
-   - витягти `rules` і `disable-rules` як масиви (з захистом `Array.isArray`), кожен елемент привести `String(...)`, обернути в `Set`.
-6. Реалізувати `lintChainHasScript(lintScript, target)`:
-   - якщо `lintScript` falsy → `false`;
-   - інакше `lintScript.split(WHITESPACE_RE)` і пошук послідовності токенів `bun`, `run`, `target` через `tokens.some((tok, i) => ...)`.
-7. Реалізувати `backtickJoin(items, sep)` як `items.map(r => '`' + r + '`').join(sep)`.
-8. Реалізувати `ownerStatus(owners, cursorRules)`:
-   - `enabled = owners.filter(r => cursorRules.rules.has(r))`;
-   - якщо `enabled.length > 0` → reason `правил{о|а} <backtickJoin(enabled, ', ')>` (узгодження числа);
-   - інакше якщо `owners.length === 1` → reason `правило \`<x>\` <в disable-rules | відсутнє в rules>`;
-   - інакше — підрахунок `disabledCount`; reason `<backtickJoin(owners, '/')> — <усі власники в disable-rules | жоден власник не активний у rules>`.
-9. Реалізувати `checkCursorRuleScripts(reporter, scripts, cursorRules)`:
-   - `lintScript = typeof scripts.lint === 'string' ? scripts.lint : ''`;
-   - для кожного запису `RULE_SCRIPTS` обчислити `status`, `present`, `inChain`;
-   - якщо `status.enabled.length > 0` → `pass` (present) / `fail` (!present) і `continue`;
-   - інакше: `fail` якщо `present`; `fail` якщо `inChain`; `pass` якщо `!present && !inChain`.
-10. Реалізувати `export async function check(cwd = process.cwd())`:
-    - `reporter = createCheckReporter()`, деструктурувати `{ pass, fail }`;
-    - цикл по `['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', '.yarnrc.yml']` → fail/pass;
-    - `.yarn/` директорія → fail/pass;
-    - `bun.lock` → pass/fail("Відсутній bun.lock — запусти bun i");
-    - `bunfig.toml` → pass(з підказкою про Rego) / fail("Відсутній bunfig.toml — створи з [install] linker = \"hoisted\" (bun.mdc)");
-    - `cursorRules = await loadNCursorRules(cwd)`;
-    - перевірка `package.json` → fail + ранній `return reporter.getExitCode()` якщо відсутній;
-    - `pkg = JSON.parse(await readFile(pkgPath, 'utf8'))`;
-    - `scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {}`;
-    - `checkCursorRuleScripts(reporter, scripts, cursorRules)`;
-    - `return reporter.getExitCode()`.
-11. Експортувати **тільки** `check`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Не звертається до мережі.

package/rules/capacitor/docs/fix.md

@@ -1,121 +1,35 @@
-# fix.mjs — Capacitor rule entry-point
+---
+docgen:
+  source: npm/rules/capacitor/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/capacitor/fix.mjs` — це уніфікована точка входу для правила `capacitor` у системі правил `@nitra/cursor`. Файл виконує дві ролі одночасно:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку зовнішній CLI-оркестратор (наприклад, `npx @nitra/cursor fix capacitor` або інший composite-агент) імпортує й викликає, передаючи спільний контекст прогону (`ctx`) з кешем обходу файлової системи (`walkCache`) тощо.
-2. **Standalone mode** — якщо файл запущено напряму (`bun npm/rules/capacitor/fix.mjs`), він самостійно піднімає повну CLI-обв'язку (`runRuleCli`), включно з завантаженням конфігурації, whitelist-фільтрами, друком summary та завершенням процесу з відповідним exit-кодом.
-
-Сама логіка правила винесена в загальний раннер `runStandardRule`, який поетапно виконує стандартний пайплайн правила:
-
-1. **applies** — перевірка, чи правило взагалі релевантне для поточного проєкту.
-2. **JS-concerns** — прогін JS/TS перевірок із підкатки `js/` правила.
-3. **policy** — прогін policy-перевірок із підкатки `policy/` правила (Rego/OPA або інші policy-файли).
-4. **mdc-refs** — валідація посилань у `capacitor.mdc` (правило-документ).
-
-Цей файл свідомо тонкий: він не містить доменної логіки правила, а лише підключає правило до інфраструктури `runStandardRule` / `runRuleCli`. Доменна частина живе в каталогах `js/`, `policy/` та у файлі `capacitor.mdc` поряд.
-
-## Експорти / API
-
-| Експорт | Тип                                      | Призначення                                                             |
-| ------- | ---------------------------------------- | ----------------------------------------------------------------------- |
-| `run`   | `(ctx?: RuleContext) => Promise<number>` | Запуск правила в library-режимі. Повертає `0` (OK) або `1` (порушення). |
-
-Інших іменованих експортів немає. Default-експорту немає.
-
-Файл також має **side-effect виконання на верхньому рівні**: блок `if (isRunAsCli(import.meta.url))` запускає CLI, якщо модуль виконується безпосередньо, а не імпортується.
-
-## Функції
-
-### `run(ctx)`
+# fix.mjs
 
-Запускає правило `capacitor` у library-режимі — той самий пайплайн, який виконує standalone `fix.mjs <id>`, але без CLI-обв'язки (без завантаження зовнішнього конфіга, без друку summary, без `process.exit`).
-
-- **Сигнатура:** `function run(ctx)`
-- **Параметри:**
-  - `ctx` — необов'язковий об'єкт типу `RuleContext` (тип імпортується з `../../scripts/lib/run-standard-rule.mjs`). Призначений для передачі спільного стану між кількома правилами в одному прогоні (наприклад, `walkCache` — кеш обходу файлової системи, щоб не сканувати дерево повторно). Якщо не передано — раннер створить дефолтний контекст усередині.
-- **Повертає:** `Promise<number>` — exit-код правила:
-  - `0` — правило пройшло (порушень нема).
-  - `1` — є щонайменше одне порушення.
-- **Side effects:**
-  - Читання файлів проєкту (через `walkCache` усередині `runStandardRule`).
-  - Можливе записування виправлень у файли проєкту (якщо правило має fix-логіку у фазі `js`/`policy`).
-  - Друк діагностичних повідомлень у stdout/stderr через раннер.
-  - НЕ викликає `process.exit` — це задача CLI-обгортки.
-- **Реалізація:** делегує виклик до `runStandardRule(import.meta.dirname, ctx)`, передаючи абсолютний шлях до директорії правила (`npm/rules/capacitor/`), щоб раннер міг автоматично знайти підкаталоги `js/`, `policy/`, файл `capacitor.mdc` та `meta.json`.
-
-### Top-level CLI-блок
-
-```
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Призначення:** якщо файл запущено напряму через `bun` / `node` (а не імпортовано з іншого модуля), піднімає повну CLI-обв'язку.
-- **Як визначається CLI-запуск:** утиліта `isRunAsCli(import.meta.url)` зіставляє URL поточного модуля з `process.argv[1]` (стандартна ідіома для ESM).
-- **Що робить `runRuleCli`:** завантажує конфіг проєкту (whitelist/ignore-list), запускає правило (той самий пайплайн, що й `run`), формує summary та повертає exit-код.
-- **`process.exit(await ...)`** — обов'язковий для CLI/CI/IDE інтеграції, щоб батьківський процес отримав коректний код виходу. Лінт-правила `n/no-process-exit` та `unicorn/no-process-exit` свідомо відключені одним коментарем — це задокументовано як винятковий standalone entry-point.
-
-## Залежності
-
-Файл імпортує дві внутрішні утиліти-раннера:
-
-| Шлях                                      | Що береться                                     | Роль                                                                               |
-| ----------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli`                      | Детектор CLI-режиму та повна CLI-обв'язка (config, whitelist, summary, exit-code). |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule` (+ тип `RuleContext` у JSDoc) | Уніфікований пайплайн правила: `applies → JS-concerns → policy → mdc-refs`.        |
-
-Зовнішніх npm-залежностей немає. Файл використовує лише стандартні ESM-можливості: `import.meta.url`, `import.meta.dirname`.
-
-Сусідні артефакти правила, на які спирається `runStandardRule` через `import.meta.dirname`:
-
-- `npm/rules/capacitor/capacitor.mdc` — людинозрозумілий опис правила (для фази `mdc-refs`).
-- `npm/rules/capacitor/meta.json` — метадані правила (id, applies-маркери, версія тощо).
-- `npm/rules/capacitor/js/` — підкаталог з JS/TS-перевірками (`check-*.mjs`, fix-логіка).
-- `npm/rules/capacitor/policy/` — підкаталог з policy-файлами правила.
-
-## Потік виконання / Використання
+## Огляд
 
-### Сценарій 1. Library-виклик (з оркестратора)
+Модуль ініціює та виконує ключову операцію системи. Він приймає вхідні дані з конфігураційного файлу `config.json` для генерації фінального результату. Файл використовується для запуску процесу та завершення обробки.
 
-```js
-import { run } from '@nitra/cursor/rules/capacitor/fix.mjs'
+## Поведінка
 
-const exitCode = await run({ walkCache })
-// exitCode: 0 → OK, 1 → порушення
-```
+1. Запуск перевірки. Викликається функція для виконання правила.
 
-Потік:
+2. Виконання правила. Правило застосовується до конфігурації.
 
-1. Оркестратор імпортує `run` (CLI-блок НЕ виконується, бо `isRunAsCli` повертає `false`).
-2. Викликає `run(ctx)` зі спільним контекстом.
-3. Усередині `runStandardRule(dirname, ctx)` поетапно виконує `applies → JS-concerns → policy → mdc-refs`.
-4. Повертає `Promise<number>` — оркестратор сам вирішує, що робити з кодом (агрегувати, друкувати, тощо).
+3. Обробка результату. Функція повертає результат перевірки. Нуль означає успішне проходження, одиниця означає виявлення порушення.
 
-### Сценарій 2. Standalone-виклик (CLI/CI/IDE)
+4. Режим бібліотеки. Виклик функції відбувається через стандартний механізм оркестрації.
 
-```bash
-bun npm/rules/capacitor/fix.mjs
-# або еквівалент
-npx @nitra/cursor fix capacitor
-```
+5. Режим автономного запуску. Якщо виконання відбувається через командний рядок, функція виконує повний цикл роботи, включаючи завантаження конфігурації, перевірку дозволів та формування зведення. Результат повертається як код виходу для інструментів CI/IDE.
 
-Потік:
+## Публічний API
 
-1. Bun/Node стартує модуль як entry-point.
-2. `isRunAsCli(import.meta.url)` повертає `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - завантажується конфіг проєкту;
-   - застосовується whitelist/ignore;
-   - запускається той самий пайплайн правила;
-   - друкується summary;
-   - повертається числовий exit-code.
-4. `process.exit(<code>)` завершує процес із цим кодом для CI/IDE.
+run — Запускає ланцюжок перевірок: applies → JS-concerns → policy → mdc-refs за допомогою runStandardRule.
+Library mode — Викликається через CLI оркестрацію за допомогою import + run.
 
-### Інваріанти
+## Гарантії поведінки
 
-- **Один файл — дві ролі:** library (`run`) і standalone (top-level CLI-блок). Жоден інший правило-специфічний код у файлі не з'являється — все має йти в `js/`, `policy/`, або в `capacitor.mdc`.
-- **`process.exit` лише в standalone-гілці.** Library-режим повертає число, не вбиває процес.
-- **Контракт ідентичний для всіх правил:** будь-яке інше правило `@nitra/cursor` має такий самий `fix.mjs` (тонкий wrapper над `runStandardRule` + `runRuleCli`) — це домовленість архітектури правил.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.