@nitra/cursor 5.3.4 → 5.4.0

package/rules/python/js/docs/tooling.md

@@ -1,153 +1,36 @@
-# tooling.mjs — FS-перевірка вимог правила `python.mdc`
+---
+docgen:
+  source: npm/rules/python/js/tooling.mjs
+  crc: f4dc22e2
+  score: 95
+---
 
-## Огляд
-
-Модуль `npm/rules/python/js/tooling.mjs` — це **check-частина** правила `python.mdc` для Python-проєктів, які перейшли на пакет-менеджер [uv](https://github.com/astral-sh/uv). Його єдина відповідальність — перевірити **наявність/відсутність файлів** у корені репозиторію, які не може покрити декларативний шар (`conftest`, `Rego`-policies для `fix`-команди).
-
-Модуль експортує функцію `check(cwd)`, що повертає exit-code (0/1) і друкує діагностику через спільний `check-reporter`. Викликається CLI `@nitra/cursor` після того, як `applies.mjs` вирішив, що правило застосовується до поточного workspace.
-
-Розподіл відповідальностей між шарами правила `python`:
-
-| Шар                                     | Що перевіряє                                                                                                             |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `applies.mjs`                           | Чи це Python-проєкт узагалі (наявність `pyproject.toml` як вхідний гейт).                                                |
-| `tooling.mjs` (цей файл)                | FS-existence: `uv.lock`, `package.json`, `.github/workflows/lint-python.yml`, відсутність `poetry.lock` / `poetry.toml`. |
-| `python/pyproject_toml/` (Rego, `fix`)  | Заборона `[tool.poetry]`, вимога `PEP 621` `[project].name` / `[project].version`.                                       |
-| `python/package_json/` (Rego, `fix`)    | Наявність скрипта `lint-python` у кореневому `package.json`.                                                             |
-| `python/lint_python_yml/` (Rego, `fix`) | Канонічна структура `uses`/`run`-кроків у `.github/workflows/lint-python.yml`.                                           |
-
-Свідомо **не перевіряється** наявність `.venv/`: uv теж створює `.venv/`, тож сам по собі цей каталог не є ознакою Poetry й давав би хибнопозитивні спрацювання.
-
-## Експорти / API
-
-| Символ  | Тип            | Призначення                                                                         |
-| ------- | -------------- | ----------------------------------------------------------------------------------- |
-| `check` | named function | Головна (і єдина) точка входу — FS-перевірка проєкту на відповідність `python.mdc`. |
-
-Default-експорт відсутній. Усі імпорти модуля повинні використовувати іменований імпорт:
-
-```js
-import { check } from './tooling.mjs'
-```
-
-## Функції
-
-### `check(cwd = process.cwd())`
-
-**Сигнатура**
-
-```js
-export function check(cwd = process.cwd()): number
-```
-
-**Параметри**
-
-| Імʼя  | Тип      | Значення за замовч. | Опис                                                                                                                                                                                           |
-| ----- | -------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cwd` | `string` | `process.cwd()`     | Абсолютний шлях до кореня репозиторію, який перевіряється. У звичайному CLI-прогоні передається з runtime; у тестах та standalone-сценаріях — явним аргументом для ізоляції від реального CWD. |
-
-**Повертає**
-
-`number` — exit-code, отриманий від `reporter.getExitCode()`:
-
-- `0` — усі очікувані файли на місці, заборонених артефактів немає.
-- `1` — щонайменше один `fail(...)` був викликаний (відсутня обовʼязкова сутність або присутній заборонений артефакт).
-
-**Side effects**
-
-- Виклик `createCheckReporter()` створює репортер, який пише форматовану діагностику в `stdout` / `stderr` через зареєстровані `pass(message)` та `fail(message)`. Кожен виклик `pass` / `fail` усередині `check()` — потенційний рядок у виведенні CLI.
-- Виконує синхронні `existsSync(...)` для серії шляхів (читання FS — read-only).
-- **Жодних мутацій FS, мережі чи процесу** функція не робить (не пише файли, не виходить через `process.exit`).
+# tooling.mjs
 
-**Алгоритм (покроково)**
-
-1. Створює репортер: `const reporter = createCheckReporter()` і деструктурує `{ pass, fail }`.
-2. **Захисний гейт.** Якщо у `cwd` немає `pyproject.toml` — повертає поточний exit-code репортера (на цей момент `0`, оскільки жодних `fail` ще не було). Це дублює гейт `applies.mjs` і потрібне лише для прямого виклику `check()` поза CLI (тести/standalone).
-3. **Перевірка `uv.lock`** (uv-проєкт коммітить lock-файл):
-   - є → `pass('uv.lock є')`,
-   - немає → ``fail('uv.lock не знайдено — згенеруй `uv lock` (python.mdc, без Poetry)')``.
-4. **Заборона Poetry-артефактів.** Для кожного імені з масиву `['poetry.lock', 'poetry.toml']`:
-   - файл існує → `fail('<file> знайдено — прибери Poetry, мігруй на uv (python.mdc)')`,
-   - файла немає → `pass('<file> відсутній')`.
-5. **Наявність кореневого `package.json`** (для запуску `bun run lint-python`):
-   - є → `pass('package.json є (наявність lint-python перевіряє fix → python.package_json)')`,
-   - немає → ``fail('package.json не знайдено в корені — додай для `bun run lint-python` (python.mdc)')``.
-6. **Наявність `.github/workflows/lint-python.yml`** (CI workflow для lint):
-   - є → `pass('<wfPath> є (структуру перевіряє fix → python.lint_python_yml)')`,
-   - немає → `fail('<wfPath> не існує — створи згідно python.mdc')`.
-7. Повертає `reporter.getExitCode()`.
-
-**Інваріанти**
-
-- Послідовність перевірок фіксована й важить для читабельності виводу. Гейт `pyproject.toml` — обовʼязково першим (інакше для не-Python репо посипалися б `fail`-и).
-- Жодна перевірка не «короткозамикає» наступні: навіть якщо `uv.lock` відсутній, далі будуть зроблені перевірки Poetry, `package.json` і workflow — це дозволяє за один прогін побачити повний список проблем.
-
-## Залежності
-
-### Зовнішні (Node.js standard library)
-
-| Імпорт       | Звідки      | Використання                                                                 |
-| ------------ | ----------- | ---------------------------------------------------------------------------- |
-| `existsSync` | `node:fs`   | Синхронна перевірка існування файлу за абсолютним шляхом.                    |
-| `join`       | `node:path` | Кросплатформне склеювання `cwd` із відносним шляхом файла, що перевіряється. |
-
-### Внутрішні (проєкт)
-
-| Імпорт                | Звідки                                    | Використання                                                                                                                                                                        |
-| --------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `createCheckReporter` | `../../../scripts/lib/check-reporter.mjs` | Фабрика репортера для check-скриптів. Очікувані поля результату: `pass(msg: string)`, `fail(msg: string)`, `getExitCode(): number` (0 поки не було `fail`, 1 після першого `fail`). |
-
-### Зовнішні сутності (контекст правила)
-
-Файл логічно повʼязаний (але **не імпортує** їх) із:
-
-- `npm/rules/python/python.mdc` — текстове формулювання правила.
-- `npm/rules/python/applies.mjs` — гейт, який вирішує, чи запускати `check()`.
-- Rego-полісі `python/pyproject_toml/`, `python/package_json/`, `python/lint_python_yml/` — покривають структурні (а не FS-existence) аспекти, які цей файл свідомо **не** перевіряє.
-
-## Потік виконання / Використання
-
-### Типовий запуск через CLI
-
-```bash
-npx @nitra/cursor check python
-```
-
-CLI послідовно:
-
-1. Резолвить правило `python`.
-2. Викликає `applies(cwd)` — якщо `false`, правило пропускається повністю.
-3. Якщо `true`, викликає `check(cwd)` із цього файла.
-4. Друкує зібрану діагностику й завершується з отриманим exit-code.
-
-### Прямий виклик (тест / standalone)
-
-```js
-import { check } from '@nitra/cursor/rules/python/js/tooling.mjs'
-
-const code = check('/abs/path/to/repo')
-// code === 0 → проєкт відповідає python.mdc
-// code === 1 → у виводі репортера є помилки, треба полагодити
-process.exitCode = code
-```
+## Огляд
 
-### Виправлення виявлених проблем
+Файл виконує перевірку наявності конфігураційних та залежностей у кореневому каталозі репозиторію. Він перевіряє структуру проекту відповідно до вимог, визначених у package.json.
 
-Файл лише **діагностує** — нічого не змінює. Виправлення:
+## Поведінка
 
-| Проблема (`fail`-message)                       | Що зробити                                                                                                                             |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `uv.lock не знайдено`                           | Запустити `uv lock` у корені проєкту й закомітити результат.                                                                           |
-| `poetry.lock знайдено` / `poetry.toml знайдено` | Завершити міграцію з Poetry: видалити файл, перенести залежності в `pyproject.toml` під `[project]` (PEP 621) і згенерувати `uv.lock`. |
-| `package.json не знайдено в корені`             | Створити `package.json` з полем `scripts.lint-python`. Структуру скрипта перевіряє Rego `python.package_json`.                         |
-| `.github/workflows/lint-python.yml не існує`    | Створити workflow за шаблоном з `python.mdc`. Канонічну структуру кроків перевіряє Rego `python.lint_python_yml`.                      |
+1. Перевірити наявність `pyproject.toml` у корені репозиторію.
+2. Перевірити наявність `uv.lock` у корені репозиторію.
+3. Якщо `uv.lock` відсутній, повернути код виходу.
+4. Перевірити наявність `poetry.lock` у корені репозиторію.
+5. Якщо `poetry.lock` знайдено, повернути помилку.
+6. Якщо `poetry.lock` відсутній, пропустити.
+7. Перевірити наявність `package.json` у корені репозиторію.
+8. Якщо `package.json` відсутній, повернути помилку.
+9. Перевірити наявність файлу `.github/workflows/lint-python.yml` у корені репозиторію.
+10. Якщо файлу `.github/workflows/lint-python.yml` немає, повернути помилку.
+11. Повернути код виходу.
 
-### Граничні випадки
+## Публічний API
 
-- **Не-Python репо** (немає `pyproject.toml`) — `check()` повертає `0` без виводу. Безпечно викликати в монорепо корені.
-- **Рівно один `fail`** — exit-code усе одно `1`. Репортер не накопичує «вагу» помилок, лише факт.
-- **Усі `pass`** — exit-code `0`, але всі повідомлення `pass` усе одно потрапляють у вивід (для прозорості та CI-логів).
+check — Перевіряє відповідність проєкту правилам python.mdc.
 
-## Rebuild Test
+## Гарантії поведінки
 
-Документ описує модуль розміром 70 рядків з єдиним експортом `check`, кореневим гейтом по `pyproject.toml`, чотирма блоками перевірок (`uv.lock`, заборона Poetry, `package.json`, workflow `lint-python.yml`), залежністю від `node:fs`, `node:path` та `../../../scripts/lib/check-reporter.mjs`. На основі цього опису можна відтворити функціональний еквівалент: створити фабрику репортера, повернути `getExitCode()` без перевірок при відсутності `pyproject.toml`, інакше — викликати `pass`/`fail` для кожного шляху в наведеному порядку зі вказаними повідомленнями (українська локалізація, посилання на `python.mdc`). Сигнатура `check(cwd = process.cwd()): number`, side effects обмежені виводом репортера й читанням FS.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.

package/rules/rego/docs/fix.md

@@ -1,121 +1,33 @@
-# fix.mjs — точка входу правила `rego`
+---
+docgen:
+  source: npm/rules/rego/fix.mjs
+  crc: 38cf876b
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/rego/fix.mjs` — це **entry-point правила `rego`** з кодової бази `@nitra/cursor`. Він є тонкою (thin) обгорткою навколо стандартного пайплайну виконання правила і виконує **дві ролі одночасно**:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку CLI-оркестратор (`@nitra/cursor fix <id>`) викликає через динамічний `import`, передаючи спільний контекст прогону (наприклад, `walkCache`).
-2. **Standalone mode** — якщо файл запущено напряму як CLI (наприклад, `bun npm/rules/rego/fix.mjs`), він виконує **повний еквівалент** команди `npx @nitra/cursor fix rego`: завантажує конфіг, застосовує whitelist, друкує summary та повертає процесові exit-code.
-
-Внутрішня логіка правила (що саме перевіряється/виправляється у файлах `.rego`, OPA-політиках тощо) **не реалізована в цьому файлі** — вся послідовність кроків (`applies → JS-concerns → policy → mdc-refs`) інкапсульована у спільному хелпері `runStandardRule`. Сам `fix.mjs` лише делегує виконання, передаючи `import.meta.dirname` як точку відліку для конвенційного пошуку файлів-супутників правила (наприклад, `applies.mjs`, `check-*.mjs`, `policy/`, `mdc/`).
-
-Така структура повторюється для кожного правила в `npm/rules/<id>/fix.mjs` — це шаблонний стандартний boilerplate, у якому індивідуальною є лише тека `<id>` (тут — `rego`).
-
-## Експорти / API
-
-| Назва | Тип                               | Опис                                                                                                                        |
-| ----- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `run` | `function(ctx?): Promise<number>` | Named-експорт. Library-точка входу для оркестратора. Запускає стандартний пайплайн правила `rego` у директорії цього файлу. |
-
-Файл **не має default-експорту** і **не експортує** жодних інших символів. Side-effect на верхньому рівні модуля — перевірка `isRunAsCli(import.meta.url)`; якщо вона істинна, виконується `process.exit(await runRuleCli(...))`.
-
-### Сигнатура `run`
-
-```js
-export function run(ctx)
-```
-
-- **Параметр `ctx`** — необов'язковий об'єкт типу `RuleContext` (тип імпортується через JSDoc із `../../scripts/lib/run-standard-rule.mjs`). У контексті, зокрема, передається `walkCache` — кеш обходу файлів, який дозволяє багаторазовим прогонам різних правил не дублювати дискові операції під час однієї сесії `@nitra/cursor fix`.
-- **Повертає** — `Promise<number>`, де `0` означає **OK** (порушень не знайдено / усе виправлено), а `1` означає **наявність порушень** (failure). Це класична CLI-конвенція exit-code, узгоджена з типами в `runStandardRule`.
-- **Прив'язка до директорії правила** — `import.meta.dirname` (нативне Node.js property для ESM, доступне у сучасних рантаймах) дає абсолютний шлях до теки, де лежить сам `fix.mjs`. Цей шлях передається у `runStandardRule` як «корінь правила», аби той знаходив супровідні файли (`applies.mjs`, `check-*.mjs`, `policy/*.rego`, `mdc/*` тощо) за конвенцією.
-
-## Функції
-
-### `run(ctx)`
-
-- **Сигнатура:** `function run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` (опційний) — контекст прогону правила. Передається оркестратором (`runRuleCli` / `runMany`), коли правило запускається не самостійно, а в складі батча; містить, серед іншого, спільний `walkCache`. У standalone-режимі (див. нижче) `ctx` не передається — використовується дефолт, який сконструює `runStandardRule` самостійно.
-- **Повертає:** `Promise<number>` — exit-code:
-  - `0` — правило пройшло (`OK`).
-  - `1` — правило виявило порушення (`violation`).
-- **Side effects:**
-  - Не має жодних побічних ефектів на рівні самої функції-обгортки.
-  - Усі побічні ефекти (читання файлів, запис виправлень, друк у `stdout`/`stderr`, доступ до `walkCache`, мережа/диск) делеговані у `runStandardRule` і виконуються вже в його реалізації.
-- **Чому така тонка обгортка?** Оркестратор `@nitra/cursor fix` під час батчового прогону **динамічно імпортує** `fix.mjs` кожного правила й викликає `run(ctx)`. Якби логіка пайплайну дублювалася в кожному `fix.mjs`, її було б неможливо змінювати централізовано — `runStandardRule` забезпечує єдину точку зміни поведінки для всіх правил.
+# fix.mjs
 
-### Standalone-блок (не функція, top-level код)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Умова входу:** `isRunAsCli(import.meta.url)` повертає `true`, якщо модуль запущений як головний (а не імпортований іншим). Реалізація хелпера — у `npm/scripts/lib/run-rule-cli.mjs`.
-- **Що виконує:** `runRuleCli(import.meta.dirname)` запускає **повний CLI** для цього правила — еквівалент `npx @nitra/cursor fix rego`. На відміну від `run(ctx)`, цей шлях додатково завантажує конфіг репозиторію, застосовує whitelist (ігнорування файлів/паттернів за конфігом), друкує summary прогону тощо.
-- **`process.exit(...)`** — потрібен, щоб standalone-запуск повертав **коректний exit-code** у виклик shell/CI (інакше `bun` міг би завершитися з `0` навіть за провалу).
-- **ESLint-винятки:** `n/no-process-exit` і `unicorn/no-process-exit` локально відключені коментарем — це свідома відмова на користь правильного CI/IDE-поведінки (standalone entry-point **зобов'язаний** повертати exit-code).
-- **`await` на top-level:** використовується top-level `await`, що в ESM-модулях Node 20+ є штатною можливістю.
-
-## Залежності
-
-Файл імпортує лише **два внутрішніх модулі** (relative imports), зовнішніх npm-пакетів не використовує безпосередньо.
-
-| Імпорт            | Звідки                                    | Призначення                                                                                                                        |
-| ----------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: повертає `true`, якщо файл запущено напряму (а не імпортовано). Використовується у standalone-блоці.                     |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Запуск **повного CLI** для одного правила (config-loading + whitelist + summary). Викликається в standalone-режимі.                |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Запуск **стандартного пайплайну** правила: `applies → JS-concerns → policy → mdc-refs`. Викликається з library-функції `run(ctx)`. |
-
-Додатково через JSDoc підтягується **тип** `RuleContext` (для типізації `ctx`) із того ж `../../scripts/lib/run-standard-rule.mjs`.
-
-Інші **неявні залежності** (через `runStandardRule` / `runRuleCli`):
-
-- файлова система — для пошуку файлів за конвенцією правила;
-- сам `import.meta.dirname` — як спосіб самоідентифікації правила без хардкоду шляху.
-
-## Потік виконання / Використання
-
-### Сценарій 1: Library mode (виклик з оркестратора)
-
-1. Користувач виконує `bun cursor fix` або `npx @nitra/cursor fix`.
-2. Оркестратор знаходить усі активні правила (зокрема `rego`) і динамічно імпортує `npm/rules/rego/fix.mjs`.
-3. Оркестратор викликає `run(ctx)`, де `ctx` містить, зокрема, `walkCache`.
-4. `run(ctx)` повертає `runStandardRule(import.meta.dirname, ctx)`.
-5. `runStandardRule` послідовно виконує стандартні етапи правила:
-   - **applies** — визначає, до яких файлів застосовується правило (через супровідний `applies.mjs`);
-   - **JS-concerns** — перевірки/виправлення, що стосуються JS-коду навколо правила;
-   - **policy** — застосування полісі/політик (для `rego` це конкретні OPA-rego-фрагменти);
-   - **mdc-refs** — звірка з посиланнями на правила в `.mdc`-документах.
-6. Результат — `Promise<number>` (`0` або `1`) — повертається оркестратору, який агрегує підсумок по всіх правилах.
-
-### Сценарій 2: Standalone mode (прямий запуск)
-
-1. Розробник виконує, наприклад, `bun npm/rules/rego/fix.mjs` (або еквівалентно `node npm/rules/rego/fix.mjs`).
-2. Виконується top-level код модуля; `isRunAsCli(import.meta.url)` повертає `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)` — це **повний CLI-флоу** для одного правила (включно з config-loading, whitelist та summary).
-4. Результат — `number` (exit-code) — передається у `process.exit(...)`, який негайно завершує процес із цим кодом.
-5. Shell / IDE / CI отримує exit-code: `0` (OK) або `1` (violations) — і може відповідно сигналізувати про результат.
+## Огляд
 
-### Як викликати `run` із зовнішнього коду (приклад)
+Огляд: Функція run виконує перевірку правила. Повертає число, що інформує про успішність або порушення. Виконання правила через командний рядок повертає код виходу, який встановлює статус процесу.
 
-```js
-import { run } from './npm/rules/rego/fix.mjs'
+## Поведінка
 
-const code = await run() // або: await run({ walkCache: myCache })
-if (code !== 0) {
-  // правило знайшло порушення
-}
-```
+1. Запуск правила.
+    - Вхід: контекст прогону.
+    - Вихід: обіцянка, що повертає число. 0 означає успіх, 1 означає порушення.
+2. Виконання правила у режимі CLI.
+    - Умова: виконання через командний рядок.
+    - Дія: повернення коду виходу з функції.
+    - Вихід: встановлення коду виходу процесу.
 
-### Як викликати у standalone
+## Публічний API
 
-```sh
-bun npm/rules/rego/fix.mjs
-echo $? # 0 — OK, 1 — violations
-```
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-### Подвійна роль файлу
+## Гарантії поведінки
 
-Дві ролі — `library` (іменований експорт `run`) та `standalone` (top-level CLI з `process.exit`) — навмисно поєднані в одному файлі: це дозволяє оркестратору не дублювати code path для одного й того самого правила, а розробнику — швидко прогнати окреме правило без запуску всього батча. Конвенція повторюється для всіх правил у `npm/rules/<id>/fix.mjs`, тож структура файлу `rego/fix.mjs` ідентична іншим правилам у каталозі — змінюється лише імпліцитна тека-«корінь» (`import.meta.dirname`).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,174 +1,30 @@
-# applies.mjs — applies-гейт правила `rego`
+---
+docgen:
+  source: npm/rules/rego/js/applies.mjs
+  crc: 059e378c
+  score: 100
+---
 
-## Огляд
-
-Модуль `applies.mjs` реалізує **rule-level applies-гейт** для правила `rego` (див. `rego.mdc`). Призначення модуля — відповісти на запитання: «Чи має CLI взагалі застосовувати правило `rego` до цього репозиторію?»
-
-Логіка гейту проста: правило **застосовне лише тоді**, коли в дереві репозиторію (з урахуванням типових skip-каталогів і ігнор-патернів із `.n-cursor.json:ignore`) існує хоча б один `.rego`-файл. Якщо таких файлів немає — CLI пропускає правило **цілком**, включно з усіма його полісі-концернами (`package_json`, `vscode_extensions`, `vscode_settings`), оскільки вимоги rego-tooling стають неактуальними для проєкту без OPA/rego-коду.
-
-Чому це не виражено декларативно через `target.json`-маніфести? Бо це **cross-file** гейт: вирішення базується на пошуку файлу по дереву (`walkDir`), а не на перевірці властивостей одного конкретного файлу. Декларативна модель `target.json` для цього не підходить, тому залишається імперативний JS.
-
-Окрім самого гейта, файл також експортує невелику функцію `check()`, яка лише друкує контекстне pass-повідомлення (фактичні порушення вже повертають окремі policy-концерни).
-
-## Експорти / API
-
-Модуль експортує два public-символи:
-
-| Символ          | Тип              | Призначення                                                            |
-| --------------- | ---------------- | ---------------------------------------------------------------------- |
-| `applies(cwd?)` | `async function` | Rule-level applies-гейт: чи застосовне правило `rego` до репозиторію.  |
-| `check()`       | `function`       | Друкує короткий context-pass; повертає exit-code від `check-reporter`. |
-
-Внутрішня (не експортована) допоміжна функція:
-
-| Символ                                   | Тип              | Призначення                                                        |
-| ---------------------------------------- | ---------------- | ------------------------------------------------------------------ |
-| `projectHasRegoFiles(root, ignorePaths)` | `async function` | Чи є хоча б один `.rego` у дереві від `root` (зупинка на першому). |
-
-## Функції
-
-### `projectHasRegoFiles(root, ignorePaths)` (internal)
-
-**Сигнатура**
-
-```js
-async function projectHasRegoFiles(root: string, ignorePaths: string[]): Promise<boolean>
-```
-
-**Параметри**
-
-- `root` — абсолютний шлях до кореня репозиторію, від якого починати обхід.
-- `ignorePaths` — масив шляхів каталогів, повністю виключених з обходу (зазвичай результат `loadCursorIgnorePaths(cwd)`).
-
-**Повертає**
-
-- `Promise<boolean>` — `true`, якщо в дереві знайдено принаймні один `.rego`-файл; інакше `false`.
-
-**Side effects / нотатки**
-
-- Виконує файлову систему-операцію через `walkDir`.
-- **Не короткозамикається** ранньо у сенсі «зупинити walk» — `walkDir` тут не отримує сигнал на дострокове припинення, але всередині callback просто переписує локальну змінну `found = true` при першому матчі (подальші зустрічі залишають значення тим самим). Таким чином, фактично функція **проходить усе дерево**, проте семантично відповідає на питання «чи знайшовся хоч один».
-- Жодних throw-ів не передбачено в самому коді функції — будь-які помилки I/O бульбашиться з `walkDir`.
-
-### `applies(cwd = process.cwd())` (exported)
-
-**Сигнатура**
-
-```js
-export async function applies(cwd?: string): Promise<boolean>
-```
-
-**Параметри**
-
-- `cwd` _(опц.)_ — корінь репозиторію. За замовчуванням — поточна робоча директорія процесу (`process.cwd()`).
-
-**Повертає**
-
-- `Promise<boolean>` — `true`, якщо правило `rego` застосовне (в репо знайдено принаймні один `.rego`); `false` — якщо правило слід пропустити.
-
-**Side effects**
+# applies.mjs
 
-- Читає `.n-cursor.json` через `loadCursorIgnorePaths(cwd)`, щоб одержати каталоги, які слід ігнорувати.
-- Виконує файловий обхід через `projectHasRegoFiles` (внутрішньо — `walkDir`).
-- Не модифікує файлову систему, не пише в stdout/stderr.
-
-### `check()` (exported)
-
-**Сигнатура**
-
-```js
-export function check(): number
-```
-
-**Параметри**
-
-- Немає.
-
-**Повертає**
-
-- `number` — exit-code, який повертає `reporter.getExitCode()` (зазвичай `0`, оскільки тут викликається лише `reporter.pass(...)`).
-
-**Side effects**
-
-- Створює локальний `check-reporter` через `createCheckReporter()`.
-- Друкує context-pass повідомлення: `Знайдено *.rego у дереві — перевіряємо канонічні конфіги rego.mdc`.
-- Фактичні порушення rego-правила цей `check()` **не повертає** — вони приходять від окремих policy-концернів, які CLI запускає декларативно через `policy/<name>/target.json`.
-
-## Залежності
-
-Модуль явно імпортує три внутрішніх допоміжних модулі:
-
-| Імпорт                  | Шлях                                          | Роль                                                                     |
-| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
-| `createCheckReporter`   | `../../../scripts/lib/check-reporter.mjs`     | Фабрика репортера для check-функцій; дає `pass()`, `getExitCode()` тощо. |
-| `loadCursorIgnorePaths` | `../../../scripts/lib/load-cursor-config.mjs` | Зчитує `.n-cursor.json` і повертає список ігнор-шляхів для обходу.       |
-| `walkDir`               | `../../../scripts/utils/walkDir.mjs`          | Рекурсивний обхід директорії з підтримкою skip-патернів і ignorePaths.   |
-
-Зовнішніх npm-залежностей у файлі немає; стандартних Node-API напряму не використовується (окрім `process.cwd()` як значення дефолту параметра).
-
-## Потік виконання / Використання
-
-### Контракт CLI
-
-Файл `applies.mjs` — стандартна точка входу для CLI правила. CLI (npm/n-cursor) обходить правила (`npm/rules/*/`) і для кожного шукає `js/applies.mjs`. Якщо файл є — CLI імпортує `applies` і викликає її, передаючи `cwd` репозиторію. Залежно від результату:
-
-- `applies(cwd)` повернуло `true` → CLI продовжує: запускає всі полісі-концерни правила (`policy/<name>/target.json`), а також (опціонально) викликає `check()` для друку контекстного pass-повідомлення.
-- `applies(cwd)` повернуло `false` → CLI **повністю пропускає** правило `rego`: жодний полісі не запускається, `check()` не викликається.
-
-### Внутрішня послідовність викликів `applies(cwd)`
-
-1. **Отримати ignorePaths** — викликати `loadCursorIgnorePaths(cwd)`. Результат — масив шляхів каталогів з `.n-cursor.json:ignore`, які слід виключити з обходу.
-2. **Перевірити наявність `.rego`** — викликати `projectHasRegoFiles(cwd, ignorePaths)`:
-   - `walkDir` обходить дерево від `cwd`, оминаючи `ignorePaths` і типові skip-каталоги (`node_modules`, `.git`, тощо — згідно семантики `walkDir`).
-   - Кожен знайдений шлях `p` перевіряється на суфікс `.rego`; перший збіг встановлює `found = true`.
-3. **Повернути результат** — `Promise<boolean>`.
-
-### Внутрішня послідовність викликів `check()`
-
-1. Створити репортер: `const reporter = createCheckReporter()`.
-2. Зареєструвати pass-подію: `reporter.pass('Знайдено *.rego у дереві — перевіряємо канонічні конфіги rego.mdc')`.
-3. Повернути exit-code: `return reporter.getExitCode()`.
-
-### Типовий сценарій для проєкту з OPA-полісі
-
-Якщо у вашому репозиторії під CI/security лежать файли на kшталт `policies/foo.rego`, `infra/opa/*.rego` тощо:
-
-- `applies(cwd)` поверне `true`.
-- CLI прогонить полісі-концерни `rego`-правила: перевірить, що `package.json` містить очікувані скрипти/devDependencies, що `.vscode/extensions.json` рекомендує OPA-розширення, що `.vscode/settings.json` має канонічні налаштування — все це декларативно через `policy/<name>/target.json`.
-- Додатково CLI може надрукувати pass-рядок із `check()`.
-
-### Типовий сценарій для проєкту без rego
-
-Якщо `.rego` файлів у дереві немає:
-
-- `applies(cwd)` поверне `false`.
-- CLI пропустить правило `rego` цілком — користувач не побачить жодних повідомлень про відсутні rego-tooling-конфіги, бо вони неактуальні.
+## Огляд
 
-### Приклад прямого виклику з тестів або сервісного коду
+Файл виконує перевірку наявності файлів із розширенням `.rego` у визначеній директорії. Функція видає повідомлення про старт перевірки та повертає код виходу.
 
-```js
-import { applies, check } from './applies.mjs'
+## Поведінка
 
-const shouldRun = await applies('/abs/path/to/repo')
-if (shouldRun) {
-  const code = check()
-  process.exit(code)
-}
-```
+applies
+Перевіряє наявність `.rego` файлів у дереві від вказаного шляху.
 
-## Rebuild Test
+check
+Друкує повідомлення про початок перевірки та повертає код виходу.
 
-Маючи лише цей документ, інженер має змогу відтворити файл наступним чином:
+## Публічний API
 
-1. Створити модуль `applies.mjs` у каталозі `npm/rules/rego/js/`.
-2. Імпортувати три залежності з відносними шляхами `../../../scripts/lib/check-reporter.mjs`, `../../../scripts/lib/load-cursor-config.mjs`, `../../../scripts/utils/walkDir.mjs`.
-3. Реалізувати **приватну** `async function projectHasRegoFiles(root, ignorePaths)`: завести локальну змінну `found = false`, викликати `await walkDir(root, callback, ignorePaths)`, де callback перевіряє `p.endsWith('.rego')` і виставляє `found = true`. Повернути `found`.
-4. Експортувати **`async function applies(cwd = process.cwd())`**: одержати `ignorePaths` через `await loadCursorIgnorePaths(cwd)`, повернути результат `projectHasRegoFiles(cwd, ignorePaths)`.
-5. Експортувати **`function check()`**: створити `reporter` через `createCheckReporter()`, викликати `reporter.pass('Знайдено *.rego у дереві — перевіряємо канонічні конфіги rego.mdc')`, повернути `reporter.getExitCode()`.
-6. Додати JSDoc-коментарі: file-header пояснює призначення applies-гейта і чому JS, а не `target.json`; кожна з трьох функцій має JSDoc із параметрами/повертанням.
+- applies — Правило застосовується, якщо в репозиторії відсутні файли `.rego`.
+- check — Виводить короткий контекст — політика пройде через CLI через `policy/<name>/target.json`.
 
-Очікуваний зовнішній контракт після rebuild:
+## Гарантії поведінки
 
-- `applies('/repo/with/rego/files')` → `Promise<true>`.
-- `applies('/repo/without/rego/files')` → `Promise<false>`.
-- `check()` → синхронно повертає число (exit-code від check-reporter), друкує pass-повідомлення.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.