@nitra/cursor 5.3.3 → 5.4.0

package/rules/rego/js/docs/lint.md

@@ -1,118 +1,23 @@
+---
+docgen:
+  source: npm/rules/rego/js/lint.mjs
+  crc: 8c033173
+  score: 100
+---
+
 # lint.mjs
 
 ## Огляд
 
-Файл `npm/rules/rego/js/lint.mjs` — це тонкий ESM-адаптер, що виконує роль CI-кроку (`lint`) для правила `rego` в монорепо. Він не містить власної логіки перевірки чи парсингу, а лише делегує виклик у вже існуючий CLI-модуль правила — `../lint/lint.mjs`. Файл існує задля відповідності уніфікованому контракту CI-кроків (`lint(files?)`), де очікується експорт функції `lint` з певною сигнатурою.
-
-Ключова особливість: режим перевірки **per-file** для правила `rego` не підтримується — аналіз завжди виконується на всьому репозиторії (whole-repo). Тому параметр `files`, який зазвичай передається CI-фреймворком у крок `lint`, тут навмисно ігнорується (на що вказує префікс `_` у назві аргументу — `_files`). Це маркер для лінтерів та читачів коду, що значення параметра не використовується.
-
-Файл є частиною інфраструктури правил (`.cursor/rules/n-rego.mdc`, `.cursor/rules/n-ci4.mdc`) і служить мостом між уніфікованою CI-сигнатурою кроків та конкретною реалізацією перевірки Rego-файлів.
-
-## Експорти / API
-
-Файл експортує одну іменовану асинхронну функцію:
-
-| Експорт | Тип                                                 | Призначення                                          |
-| ------- | --------------------------------------------------- | ---------------------------------------------------- |
-| `lint`  | `async function(files?: string[]): Promise<number>` | CI-крок для лінтингу Rego-файлів; повертає exit code |
-
-Default-експорт відсутній. Експорт іменований, що відповідає конвенції CI-кроків у проєкті (де runner імпортує саме `{ lint }`).
-
-## Функції
-
-### `lint(_files)`
-
-#### Сигнатура
-
-```js
-export async function lint(_files)
-```
-
-#### Параметри
-
-| Параметр | Тип                     | Обов'язковий | Опис                                                                                                                                                                               |
-| -------- | ----------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_files` | `string[] \| undefined` | ні           | Список файлів для перевірки. **Ігнорується** — `rego`-лінтер не має per-file режиму та виконує whole-repo аналіз. Префікс `_` сигналізує, що параметр свідомо не використовується. |
-
-#### Повертає
-
-`Promise<number>` — exit code від `runLintRego()`:
-
-- `0` — лінтинг пройшов без помилок;
-- ненульове значення — виявлено порушення або стався збій під час перевірки.
-
-Конкретні значення коду визначає реалізація `runLintRego` у `../lint/lint.mjs` — цей файл лише транслює його далі.
-
-#### Side effects
-
-Сама функція `lint` не має прямих побічних ефектів — вона не пише у файлову систему, не звертається до мережі, не модифікує глобальний стан і не виводить нічого у консоль. Усі побічні ефекти (виклики `opa`/`regal`, читання Rego-файлів, друк діагностики, можливі тимчасові файли тощо) реалізовані всередині `runLintRego` із сусіднього модуля `../lint/lint.mjs` та повністю інкапсульовані там.
-
-#### Винятки
-
-Функція не має власних `try`/`catch`. Якщо `runLintRego()` відхилить проміс (`reject`) або викине синхронну помилку, виняток прозоро прокинеться вгору до викликача (зазвичай — CI-runner, який очікує саме на exit code).
-
-## Залежності
-
-### Внутрішні (relative)
-
-| Імпорт        | Шлях               | Призначення                                                                                                                         |
-| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `runLintRego` | `../lint/lint.mjs` | Реалізація whole-repo лінтингу Rego-файлів — фактично виконує перевірку та повертає exit code. Цей файл є єдиною залежністю модуля. |
-
-### Зовнішні
-
-Зовнішніх npm-залежностей файл напряму не використовує. Усі сторонні інструменти (наприклад, `opa`, `regal` тощо) транзитивно підключаються через `runLintRego`.
-
-### Runtime
-
-ESM-модуль (`.mjs`), потребує Node.js / Bun з підтримкою native ESM та `async/await`.
-
-## Потік виконання / Використання
-
-### Послідовність дій
-
-1. CI-runner (наприклад, фреймворк CI-кроків `n-ci4`) виявляє файл як крок `lint` правила `rego`.
-2. Runner викликає `lint(files)` — передає або список змінених файлів, або `undefined`, залежно від режиму запуску.
-3. Функція ігнорує аргумент `_files` і одразу викликає `runLintRego()` без параметрів.
-4. `runLintRego()` повертає `Promise<number>` із exit code; `lint` повертає цей самий проміс (через `return` в `async`-функції — фактично awaits та віддає значення).
-5. Runner отримує exit code і інтерпретує його як результат CI-кроку.
-
-### Контрактна позиція в системі правил
-
-Файл реалізує уніфікований інтерфейс CI-кроку `lint(files?)`, очікуваний фреймворком правил репозиторію (`n-ci4`). Завдяки тонкому шару адаптації:
-
-- сам runner може бути неуважним до особливостей правила (per-file vs whole-repo);
-- логіка перевірки залишається інкапсульованою у `../lint/lint.mjs` і може використовуватися як з CI, так і з CLI напряму;
-- зміна реалізації `runLintRego` не вимагає правок цього файла.
-
-### Приклад використання
-
-```js
-import { lint } from './npm/rules/rego/js/lint.mjs'
-
-// CI-режим: список файлів є, але буде проігнорований
-const exitCode = await lint(['policy/a.rego', 'policy/b.rego'])
-process.exit(exitCode)
-
-// Або без аргументів — поведінка ідентична
-const code2 = await lint()
-process.exit(code2)
-```
-
-### Що НЕ робить цей файл
+Файл виконує передачу перевірок у наявні CLI правила. Функція повертає Promise з кодом виходу.
 
-- Не парсить аргументи командного рядка — це не CLI-entrypoint.
-- Не фільтрує файли за розширенням — фільтрація (за потреби) — справа `runLintRego`.
-- Не агрегує помилки кількох інструментів — повертає лише підсумковий exit code.
-- Не пише у `stdout`/`stderr` — увесь вивід походить із `runLintRego`.
+## Поведінка
 
-## Rebuild Test
+1. lint приймає масив рядків або undefined
+2. lint делегує виконання у CLI правила
+3. lint повертає Promise з кодом виходу
 
-Документація достатня, щоб переписати файл з нуля без перегляду оригіналу:
+## Гарантії поведінки
 
-- Модуль ESM (`.mjs`).
-- Імпорт: `runLintRego` із `../lint/lint.mjs`.
-- Один іменований експорт — `async function lint(_files)`.
-- Тіло: `return runLintRego()` (виклик без аргументів).
-- JSDoc: параметр `_files` — `string[] | undefined`, описаний як ігнорований (whole-repo аналіз); повертає `Promise<number>` (exit code).
-- Коментар верхнього рівня: пояснює, що це CI-крок `rego`, делегує у CLI правила, per-file режиму немає, `files` ігнорується.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/release/docs/fix.md

@@ -1,128 +1,30 @@
 ---
 docgen:
   source: npm/rules/release/fix.mjs
-  crc: 0508fb5e
+  crc: 22936815
+  score: 100
 ---
 
-# fix.mjs — точка входу правила `release`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/release/fix.mjs` — це **точка входу (entry-point)** для правила `release` у системі правил репозиторію. Він виконує дві ролі:
+Файл ініціює виконання визначеного правила. Правило виконує необхідні дії з наданим контекстом. Виконане правило повертає отриманий результат.
 
-1. **Library mode** — експортує асинхронну функцію `run(ctx)`, яку викликають інші скрипти/оркестратори через `import + run(ctx)`. Делегує виконання у стандартний раннер правил `runStandardRule`.
-2. **CLI mode** — якщо файл запущено напряму як standalone-скрипт (`node fix.mjs` або через bun), він викликає `runRuleCli` й завершує процес кодом виходу (`process.exit`), щоб CI/IDE могли орієнтуватися на exit-code.
+## Поведінка
 
-Сам файл не містить жодної бізнес-логіки правила: всі перевірки (`applies → JS-concerns → policy → mdc-refs`) живуть у супровідних модулях каталогу `npm/rules/release/`, а оркестрацію виконує `runStandardRule`. Це — лише тонкий адаптер між іменем правила (визначається як ім'я каталогу через `import.meta.dirname`) і загальним механізмом запуску правил.
+1. Запуск правила.
+2. Виконання правила.
+3. Передача контексту прогону.
+4. Повернення результату.
 
-## Експорти / API
+## Публічний API
 
-| Експорт | Тип                               | Призначення                                                                             |
-| ------- | --------------------------------- | --------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?): Promise<number>` | Library-mode запуск правила. Повертає exit-code: `0` — без порушень, `1` — є порушення. |
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-Інших публічних експортів (типів, констант, default-експорту) файл не оголошує.
+## Гарантії поведінки
 
-## Функції
-
-### `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` для повторного використання обходу файлової системи між декількома правилами в одному прогоні). Якщо `ctx` не передано, стандартний раннер працює без зовнішнього кешу.
-- **Повертає:** `Promise<number>` — exit-code правила:
-  - `0` — порушень не знайдено;
-  - `1` — знайдені порушення (їх вже надруковано/зібрано раннером).
-- **Side effects:** Безпосередньо у тілі `run` сайд-ефектів немає — функція просто проксує виклик у `runStandardRule`. Усі реальні ефекти (читання файлів, обчислення `applies`, друк звітів, mdc-refs-перевірки) залежать від реалізації `runStandardRule` і відповідних check-модулів каталогу правила.
-- **Як визначає ім'я правила:** через `import.meta.dirname` — абсолютний шлях до каталогу `npm/rules/release/`. `runStandardRule` сам витягне з нього базове ім'я (`release`), знайде сусідні check-модулі (`check-*.mjs`, `applies.mjs`, `policy.*` тощо) й оркеструє конвеєр.
-
-### CLI-блок (модульний top-level код)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Не є функцією**, але це частина public-API файлу як CLI-скрипта.
-- **Умова виконання:** `isRunAsCli(import.meta.url)` повертає `true` лише коли файл є точкою входу процесу (а не імпортований як модуль). Це класичний еквівалент Node-патерна `require.main === module` для ESM.
-- **Дія:** Дочекатися `runRuleCli(import.meta.dirname)` (top-level `await`) і завершити процес із отриманим exit-code через `process.exit`.
-- **ESLint:** Спеціально дозволено `n/no-process-exit` і `unicorn/no-process-exit` — standalone-entry-point має повертати CI-сумісний код.
-- **Side effects:** Завершує Node-процес. Через top-level `await` блокує закриття модульного завантаження, поки CLI-прогін не завершиться.
-
-## Залежності
-
-Файл імпортує **дві** утиліти з локальної бібліотеки скриптів репозиторію (відносні шляхи до `npm/scripts/lib/`):
-
-- `../../scripts/lib/run-rule-cli.mjs`
-  - **`isRunAsCli(metaUrl: string): boolean`** — перевіряє, чи модуль викликано як CLI, а не як `import`.
-  - **`runRuleCli(ruleDir: string): Promise<number>`** — CLI-обгортка над раннером: парсить аргументи, налаштовує оточення прогону як standalone і повертає exit-code.
-- `../../scripts/lib/run-standard-rule.mjs`
-  - **`runStandardRule(ruleDir: string, ctx?: RuleContext): Promise<number>`** — стандартний конвеєр правила: дізнається, до яких файлів воно застосовується (`applies`), запускає JS-concerns (зазвичай файли `check-*.mjs`), policy-перевірки і `mdc-refs` (узгодженість з `.mdc`-документами), збирає й виводить порушення.
-  - **Тип `RuleContext`** — структура контексту прогону. Цей файл лише re-references його в JSDoc-`@param`.
-
-Жодних інших імпортів (зовнішніх npm-пакетів, Node core-модулів, динамічних `import()`) немає. Глобально використовується лише `process` (Node-built-in) — у CLI-блоці для `process.exit`.
-
-## Потік виконання / Використання
-
-### Library mode (виклик з іншого модуля)
-
-```js
-import { run } from './npm/rules/release/fix.mjs'
-
-const exitCode = await run(ctx) // ctx — опційний
-if (exitCode !== 0) {
-  // знайдено порушення правила release
-}
-```
-
-Послідовність:
-
-1. Викликач робить `import { run } from '.../release/fix.mjs'`.
-2. Виклик `run(ctx)` → `runStandardRule(import.meta.dirname, ctx)`.
-3. `runStandardRule` визначає каталог правила (`release`), знаходить і запускає сусідні модулі правила (`applies` → JS-concerns → policy → mdc-refs), обмінюючись із викликачем кешем через `ctx` (за наявності).
-4. Повертається числовий exit-code (`0`/`1`).
-
-### CLI mode (запуск файлу як скрипта)
-
-```bash
-node npm/rules/release/fix.mjs
-# або через bun
-bun run npm/rules/release/fix.mjs
-```
-
-Послідовність:
-
-1. Node/Bun стартує файл як точку входу — `isRunAsCli(import.meta.url)` повертає `true`.
-2. `await runRuleCli(import.meta.dirname)` запускає CLI-обгортку правила: парсить можливі аргументи/прапорці, ініціалізує стандартне середовище правила, всередині сам викликає аналог `runStandardRule` і повертає exit-code.
-3. `process.exit(<exitCode>)` завершує процес: CI-конвеєр або IDE-runner отримує `0` (успіх) або `1` (порушення).
-
-### Типове місце у системі правил
-
-Файл є членом сім'ї однотипних entry-point'ів `npm/rules/<rule-name>/fix.mjs`: кожне правило репозиторію має такий-самий шаблон («тонкий fix.mjs + сусідні check-модулі»). Це уніфікує запуск як з оркестратора (`bun run lint`, агрегатори, `runStandardRule`-цикли), так і з окремих CI-кроків чи дебагу через IDE.
-
-### Контракт повернення (exit-code)
-
-| Значення | Семантика                                                                 |
-| -------- | ------------------------------------------------------------------------- |
-| `0`      | Правило `release` не знайшло порушень для файлів, до яких воно `applies`. |
-| `1`      | Принаймні одне порушення (вже зафіксоване й виведене раннером).           |
-
-Інших кодів файл не вводить — будь-яка деталізація залежить від `runStandardRule` / `runRuleCli`.
-
-## Примітки щодо реалізації
-
-- **Чому `import.meta.dirname`, а не явне ім'я правила:** Це дає змогу шаблону `fix.mjs` бути ідентичним для всіх правил без захардкоджування рядкового імені — раннер сам ідентифікує правило за каталогом.
-- **Чому `await` на top-level:** Файл — ESM (`.mjs`), top-level `await` дозволений. У CLI-режимі потрібен синхронно-доступний exit-code до виклику `process.exit`.
-- **Чому виключені два ESLint-правила:** Обидва (`n/no-process-exit`, `unicorn/no-process-exit`) у проєкті заборонені для бібліотечного коду, але для standalone-entry-points exit-code — це і є контракт. Інлайн-коментар із поясненням обов'язковий за стилем репозиторію.
-- **Що файл свідомо не робить:** не парсить CLI-аргументи самостійно, не читає файли, не звертається до мережі, не імпортує бізнес-логіку правила напряму — все це делеговано в `run-standard-rule.mjs` та `run-rule-cli.mjs`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/rust/docs/fix.md

@@ -1,129 +1,34 @@
-# `fix.mjs` — entry-point правила `rust`
+---
+docgen:
+  source: npm/rules/rust/fix.mjs
+  crc: 38cf876b
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/rust/fix.mjs` — мінімальний adapter, який реєструє правило `rust` у двох ролях одночасно:
-
-- **library mode** — модуль експортує функцію `run(ctx)`, яку викликає CLI-оркестратор пакета `@nitra/cursor` (через `import + run(ctx)`), передаючи спільний контекст прогону (наприклад, `walkCache` для шерингу обходу файлів між правилами).
-- **standalone mode** — якщо файл запущено напряму (`bun npm/rules/rust/fix.mjs`), він поводиться як повний еквівалент команди `npx @nitra/cursor fix rust`: підвантажує конфіг, застосовує whitelist, друкує summary та повертає процесу exit-code.
-
-Уся реальна логіка правила (порядок фаз: `applies → JS-concerns → policy → mdc-refs`) інкапсульована у двох helper-модулях зі спільної бібліотеки `npm/scripts/lib/`. Цей файл — лише тонкий wrapper, що з'єднує конвенцію розташування (`npm/rules/<id>/fix.mjs`) із цими helpers і не містить власної бізнес-логіки правила `rust`.
-
-Файл слідує усталеному в репозиторії патерну "двох ролей `fix.mjs`": library + standalone — тому самий код використовується і коли правило виконується як частина мульти-rule прогону, і коли його запускають окремо для дебагу/CI.
-
-## Експорти / API
-
-Модуль експортує одну іменовану функцію:
-
-| Експорт | Тип                                      | Призначення                                                        |
-| ------- | ---------------------------------------- | ------------------------------------------------------------------ |
-| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-mode entry: запуск правила `rust` зі стандартним pipeline. |
-
-Default-експорту немає. Імпортний шлях для зовнішніх споживачів — `@nitra/cursor/rules/rust/fix.mjs` (або еквівалентний relative-шлях усередині монорепо).
-
-Тип `RuleContext` визначений у `npm/scripts/lib/run-standard-rule.mjs` і реекспортується через JSDoc-`import('...')`-тип у сигнатурі `run`.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` — _(опційний)_ контекст прогону, який передає CLI-оркестратор. Структура задана в `run-standard-rule.mjs` (`RuleContext`); типове поле — `walkCache`, що дозволяє декільком правилам розділяти один обхід файлової системи в межах однієї сесії. Якщо `ctx` не передано (наприклад, у standalone), `runStandardRule` сам ініціалізує внутрішні структури.
-- **Повертає:** `Promise<number>`
-  - `0` — правило завершилось успішно, порушень не знайдено.
-  - `1` — знайдено порушення (стандартний exit-code для CI/IDE).
-- **Алгоритм:** делегує виконання у `runStandardRule(import.meta.dirname, ctx)`. Перший аргумент — абсолютний шлях до каталогу правила (`npm/rules/rust/`), завдяки якому `runStandardRule` сам читає `meta.json`, виявляє підкаталоги `js/`, `policy/`, `coverage/`, `lib/` і відповідний `.mdc`-файл (`rust.mdc`) для розв'язання refs.
-- **Side effects:**
-  - Власних side effects не має; усі ефекти (I/O, лог, walk-cache) виникають усередині `runStandardRule`.
-  - Не модифікує `process.exit`, не пише в `process.stderr/stdout` напряму — це робить уже helper або стандартний CLI summary.
+# fix.mjs
 
-### Standalone entry-block
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Тип:** top-level side-effect блок (виконується при імпорті модуля).
-- **Умова входу:** `isRunAsCli(import.meta.url)` повертає `true`, тобто файл виконано як головний модуль (`bun fix.mjs` / `node fix.mjs`), а не імпортовано з іншого модуля.
-- **Що робить:** викликає `runRuleCli(import.meta.dirname)` — повний CLI-pipeline пакета `@nitra/cursor` для одного правила: завантаження конфіга, застосування whitelist, друк summary, повернення числового exit-code. Результат передається у `process.exit(...)`, щоб процес завершився з відповідним кодом для CI/IDE.
-- **Чому два eslint-disable:**
-  - `n/no-process-exit` (плагін `eslint-plugin-n`) — забороняє виклик `process.exit` у бібліотечному коді.
-  - `unicorn/no-process-exit` (плагін `eslint-plugin-unicorn`) — теж забороняє `process.exit`.
-    Тут вони відключені свідомо: standalone entry-point має повертати exit-code, інакше неможливо коректно інтегруватися з CI/IDE runners (вони чекають саме на код виходу процесу).
-- **Side effects:** завершує процес викликом `process.exit(code)`.
-
-## Залежності
-
-### Внутрішні (relative imports)
-
-| Шлях                                      | Що використовується        | Роль                                                                                                                                       |
-| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Helpers для standalone-режиму: детекція "запущено як CLI" та повний CLI-pipeline одного правила.                                           |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний рантайм правила: оркестрація фаз `applies → JS-concerns → policy → mdc-refs`. JSDoc-тип `RuleContext` теж імпортується звідси. |
-
-### Зовнішні
-
-Прямих залежностей від npm-пакетів немає. Усі external-залежності (наприклад, `fast-glob`, ESLint API тощо) інкапсульовані всередині `runStandardRule` / `runRuleCli` і сюди не "протікають".
-
-### Runtime/Node API
-
-- `import.meta.dirname` — стандартний Node.js / Bun API; використовується для передачі абсолютного шляху до каталогу правила в helpers.
-- `import.meta.url` — використовується `isRunAsCli` для порівняння з `process.argv[1]`.
-- `process.exit(code)` — завершення процесу в standalone-режимі.
-- `await` на top level — потребує Node ≥ 14.8 (ESM top-level await) або Bun (підтримує з коробки).
-
-### Конвенції розташування
-
-Файл лежить за конвенцією `npm/rules/<id>/fix.mjs`, де `<id> = rust`. Поряд із ним мають існувати:
-
-- `meta.json` — метадані правила (читається `runStandardRule`/`runRuleCli`).
-- `rust.mdc` — людинозрозумілий опис правила (для mdc-refs).
-- Підкаталоги `js/`, `policy/`, `coverage/`, `lib/` — фази правила.
-- `docs/` — каталог із згенерованою документацією (включно з цим файлом).
-
-## Потік виконання / Використання
+## Огляд
 
-### Сценарій A: виклик з CLI-оркестратора (library mode)
+Огляд
+Файл надає механізм для виконання стандартних правил. Використовується для запуску правил через функцію runStandardRule та для запуску правил у режимі командного рядка через runRuleCli.
 
-1. Оркестратор `@nitra/cursor` сканує `npm/rules/*/fix.mjs`.
-2. Для правила `rust` виконує `import('npm/rules/rust/fix.mjs')`.
-3. Викликає `run(ctx)`, передаючи спільний `RuleContext` (включно з `walkCache`).
-4. `run` повертає `runStandardRule(import.meta.dirname, ctx)`, який послідовно виконує фази:
-   - **applies** — фільтрує файли, до яких правило застосовне.
-   - **JS-concerns** — запускає JS-аспекти правила (`js/`-фолдер).
-   - **policy** — застосовує policy-checks (`policy/`-фолдер).
-   - **mdc-refs** — валідує посилання в `rust.mdc`.
-5. Результуючий `Promise<number>` (`0` або `1`) повертається оркестратору.
-6. Оркестратор агрегує exit-коди всіх правил і повертає єдиний summary.
+## Поведінка
 
-### Сценарій B: standalone-запуск
+1. Запуск правила.
+    *   Виклик runStandardRule з контекстом.
+    *   Повернення результату.
 
-1. Користувач/CI виконує `bun npm/rules/rust/fix.mjs` (або `node npm/rules/rust/fix.mjs`).
-2. Модуль завантажується; `isRunAsCli(import.meta.url)` повертає `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - читає конфіг проєкту,
-   - застосовує whitelist шляхів,
-   - усередині сам викликає `runStandardRule` (або еквівалент),
-   - друкує summary в stdout.
-4. Отриманий числовий exit-code передається в `process.exit(code)`.
-5. Процес завершується кодом `0` (ok) або `1` (порушення) — CI/IDE підхоплюють статус.
+2. Запуск у режимі CLI.
+    *   Виклик runRuleCli з директорією.
+    *   Вихід з процесом залежно від результату.
 
-### Як додавати/змінювати поведінку
+## Публічний API
 
-- **НЕ** додавати бізнес-логіку правила прямо в цей файл — він має лишатись тонким wrapper'ом.
-- Зміни порядку фаз або їх складу — у `runStandardRule` (спільно для всіх стандартних правил).
-- Зміни CLI-флагів / summary / whitelist — у `runRuleCli`.
-- Зміни специфічні для правила `rust` — у відповідних підкаталогах (`js/`, `policy/`, `coverage/`, `lib/`) і файлі `rust.mdc`.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-### Контракт із оркестратором
+## Гарантії поведінки
 
-- Експорт `run` повинен бути **функцією** (не stream/generator) і повертати `Promise<number>`.
-- Не повинен викидати unhandled rejections — усі помилки обгортаються всередині `runStandardRule`.
-- Exit-коди суворо `0` або `1` (інші значення оркестратор може інтерпретувати як збій).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/rust/js/docs/applies.md

@@ -1,140 +1,31 @@
+---
+docgen:
+  source: npm/rules/rust/js/applies.mjs
+  crc: 4cc601f5
+  score: 100
+---
+
 # applies.mjs
 
 ## Огляд
 
-Модуль `applies.mjs` реалізує **applies-гейт** для правила `rust` у системі правил `n-cursor`. Його завдання — швидко відповісти на питання: «чи має взагалі сенс прогонити це правило в поточному репозиторії?». Якщо репозиторій не містить жодного Rust-кореня (тобто немає `Cargo.toml` ані в корені, ані в жодному вкладеному робочому каталозі), функція повертає `false`, і ранер `runStandardRule` пропускає всі концерни цього правила — як JS-перевірки, так і policy-концерни. Це уникає зайвої роботи в репозиторіях без Rust-коду.
-
-Маркером застосовності є файл `Cargo.toml`:
-
-- спершу швидка перевірка в `cwd` через `existsSync` (синхронно, без I/O-обходу);
-- якщо в корені маркера немає — рекурсивний обхід дерева через `hasCargoTomlInTree`, який ігнорує штучні / службові директорії (`node_modules`, `.git`, `.next`, `.turbo`).
-
-Окремо експортується функція `check()` — це **context-pass** репортер: коли applies повернув `true`, ранер усе одно очікує, що файл правила розрукує хоча б один контекст. `check()` просто друкує повідомлення «знайдено Cargo.toml — застосовуємо правила rust.mdc» і повертає exit-код `0`. Жодної реальної логіки лінтування / перевірок у цьому файлі немає — вся робота винесена в **policy-концерни** правила `rust`.
-
-Файл написаний у форматі ESM (`.mjs`) та сумісний з Bun і Node.js (≥ модулів з підтримкою ESM та `node:` префіксу).
-
-## Експорти / API
-
-| Експорт   | Тип                                  | Призначення                                                              |
-| --------- | ------------------------------------ | ------------------------------------------------------------------------ |
-| `applies` | `(cwd?: string) => Promise<boolean>` | Гейт-функція: чи активувати правило `rust` для заданого `cwd`.           |
-| `check`   | `() => number`                       | Context-pass репортер: друкує позитивне повідомлення, повертає exit-код. |
-
-Інших публічних експортів немає. Константа `IGNORED_DIR_NAMES` — внутрішня (module-level), назовні не експортується.
-
-## Функції
-
-### `applies(cwd = process.cwd())`
-
-**Сигнатура:** `applies(cwd?: string): Promise<boolean>`
-
-**Параметри:**
-
-- `cwd` _(string, опційний)_ — абсолютний (або відносний від процесу) шлях до кореня репозиторію, який треба перевірити. За замовчуванням — `process.cwd()` (поточний робочий каталог процесу Node/Bun).
-
-**Повертає:** `Promise<boolean>`
-
-- `true` — правило `rust` застосовне (знайдено хоча б один `Cargo.toml` у корені або десь у дереві);
-- `false` — застосовувати правило не треба (Rust у репозиторії не знайдено).
-
-**Алгоритм:**
-
-1. Складає шлях `join(cwd, 'Cargo.toml')` і синхронно перевіряє його існування через `existsSync`.
-2. Якщо файл є — одразу повертає `Promise.resolve(true)` (швидкий вихід; решта дерева не сканується).
-3. Якщо в корені маркера немає — викликає `hasCargoTomlInTree(cwd, IGNORED_DIR_NAMES)` і повертає його результат, загорнутий у промісі (значення може бути проміс або bool — у будь-якому разі `Promise.resolve` нормалізує до `Promise<boolean>`).
-
-**Side effects:**
-
-- Один синхронний виклик `existsSync` (file-system stat) для шляху `<cwd>/Cargo.toml`.
-- За потреби — рекурсивний обхід директорії `cwd` (виконує `hasCargoTomlInTree`); у межах цього обходу директорії з `IGNORED_DIR_NAMES` пропускаються.
-- Не модифікує файлову систему, не пише в `stdout`/`stderr`, не виконує мережевих запитів.
-
-**Не кидає винятків** у нормальних умовах: `existsSync` повертає `false` для неіснуючих/недоступних шляхів. Виняткові ситуації можуть прилетіти лише з глибин `hasCargoTomlInTree` (наприклад, помилка `readdir`), але це поведінка залежного модуля, а не самого `applies`.
-
-### `check()`
-
-**Сигнатура:** `check(): number`
-
-**Параметри:** немає.
-
-**Повертає:** `number` — exit-код:
-
-- `0` — все OK (стандартний шлях; функція завжди йде цим шляхом, бо вона лише друкує `pass`);
-- `1` — порушення (теоретично можливо, якщо репортер у майбутньому почне накопичувати помилки; зараз цей кейс не використовується).
-
-**Алгоритм:**
-
-1. Створює інстанс репортера через `createCheckReporter()`.
-2. Викликає `reporter.pass('Знайдено Cargo.toml — застосовуємо правила rust.mdc')` — реєструє позитивний context-pass.
-3. Повертає `reporter.getExitCode()`.
-
-**Side effects:**
-
-- Друкує повідомлення про `pass` у stdout у форматі, заданому `createCheckReporter` (зазвичай — рядок з префіксом / маркером).
-- Не торкається файлової системи й мережі.
-
-**Контракт із ранером:** `runStandardRule` викликає `check()` лише після того, як `applies()` повернув `true`. Тому повідомлення в стилі «знайдено Cargo.toml» завжди коректне на момент друку — applies-гейт уже відпрацював перед цим.
-
-## Залежності
-
-### Зовнішні (стандартна бібліотека Node.js)
-
-- `node:fs` → `existsSync` — синхронна перевірка існування файлу.
-- `node:path` → `join` — крос-платформне склеювання сегментів шляху.
-
-### Внутрішні (відносні до файлу)
-
-- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера для context-pass / помилок із підрахунком exit-коду.
-- `../lib/has-cargo-toml.mjs` → `hasCargoTomlInTree` — рекурсивний обхід дерева директорій з пошуком `Cargo.toml` і пропуском ігнор-папок.
-
-### Module-level константи
-
-- `IGNORED_DIR_NAMES: Set<string>` — `{ 'node_modules', '.git', '.next', '.turbo' }`. Передається в `hasCargoTomlInTree` як набір імен директорій, у які заходити не треба під час рекурсивного пошуку.
-
-## Потік виконання / Використання
-
-### Типовий сценарій (ранер правил)
-
-1. `runStandardRule` для правила `rust` спершу імпортує модуль `applies.mjs`.
-2. Викликає `await applies()` (без аргументів — буде використано `process.cwd()`).
-3. Якщо результат `false` — ранер пропускає правило цілком: ні JS-концерни (`check`), ні policy-концерни не виконуються; правило вважається «not applicable».
-4. Якщо результат `true` — ранер послідовно виконує всі концерни правила:
-   - викликає експортований `check()` як «context-pass» — щоб у звіті був видимий маркер «правило застосовано»;
-   - запускає policy-концерни (фактичні перевірки коду / структури), які живуть в інших файлах модуля `rust`.
-
-### Приклад прямого виклику
-
-```js
-import { applies, check } from './npm/rules/rust/js/applies.mjs'
-
-const ok = await applies('/path/to/some/repo')
-if (ok) {
-  const code = check()
-  process.exit(code)
-}
-```
+Огляд
+Файл виконує перевірку наявності файлу Cargo.toml у кореневому репозиторії та підкаталогах. Функція check генерує звіт про порушення конфігураційних правил.
 
-### Ребра (edge cases)
+## Поведінка
 
-- **`cwd` не існує / недоступний:** `existsSync` поверне `false`; далі `hasCargoTomlInTree` обходитиме неіснуючий шлях (поведінка визначається ним).
-- **`Cargo.toml` лежить глибоко під ігнор-папкою** (наприклад, всередині `node_modules/.../Cargo.toml`): його **не** знайдуть — `IGNORED_DIR_NAMES` свідомо пропускає такі директорії, бо це не «справжній» Rust-корінь репозиторію.
-- **`Cargo.toml` у корені `cwd`:** виконується лише `existsSync` — рекурсивний обхід не запускається (оптимізація).
-- **Множинні `Cargo.toml` глибоко в дереві:** достатньо знайти хоча б один — `hasCargoTomlInTree` має повернути `true` при першому ж збігу.
+applies
+Перевіряє наявність Cargo.toml у корені репозиторію або в його підкаталогах, і повертає булеве значення.
 
-### Інваріанти
+check
+Генерує звіт про застосування правил і повертає код виходу.
 
-- `applies()` завжди повертає `Promise<boolean>` — навіть для синхронного fast-path через `Promise.resolve(true)`.
-- `check()` синхронна — не повертає Promise; завжди повертає число (exit-код).
-- `applies()` ідемпотентна та не має станy між викликами (немає кешу).
+## Публічний API
 
-## Rebuild Test
+applies формує файл
 
-Якщо видалити файл `applies.mjs` і відновлювати його з нуля по цій документації, реалізація має:
+## Гарантії поведінки
 
-- бути ESM-модулем (`.mjs`) з ES-імпортами `node:fs` / `node:path`;
-- імпортувати `createCheckReporter` із `../../../scripts/lib/check-reporter.mjs` і `hasCargoTomlInTree` із `../lib/has-cargo-toml.mjs`;
-- містити module-level `Set` з рівно цими іменами: `'node_modules'`, `'.git'`, `'.next'`, `'.turbo'`;
-- експортувати **named** функцію `applies(cwd = process.cwd())` з логікою «`existsSync(join(cwd, 'Cargo.toml'))` → інакше делегат у `hasCargoTomlInTree(cwd, IGNORED_DIR_NAMES)`», результати загорнуті в `Promise.resolve`;
-- експортувати **named** синхронну функцію `check()`, яка створює репортер, реєструє `pass('Знайдено Cargo.toml — застосовуємо правила rust.mdc')` і повертає `reporter.getExitCode()`;
-- не мати default-експорту;
-- не мати побічних ефектів на рівні модуля (тільки декларація `Set` — допустимо).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.
+- Не звертається до мережі.