@nitra/cursor 3.22.0 → 3.23.1

package/rules/python/lint/docs/lint.md

@@ -0,0 +1,322 @@
+# `lint.mjs` — лінт-крок `lint-python`
+
+## Огляд
+
+Модуль `npm/rules/python/lint/lint.mjs` реалізує крок `lint-python` — частину
+загального лінт-пайплайну монорепозиторію. Крок виконує перевірку Python-частини
+проєкту відповідно до правила `python.mdc` і базується на пакетному менеджері
+[uv](https://docs.astral.sh/uv/).
+
+Поведінкові ключові точки:
+
+- Якщо у корені, переданому як `cwd` (за замовчуванням `process.cwd()`), немає
+  файлу `pyproject.toml`, крок завершується успіхом (`exit code 0`) без запуску
+  будь-яких інструментів. Це дозволяє безпечно вмикати крок у репозиторіях
+  без Python-частини.
+- Якщо `pyproject.toml` присутній, але бінарника `uv` немає в `PATH`, крок
+  завершується помилкою. Інших пакет-менеджерів (Poetry, pip, pdm тощо) модуль
+  не підтримує — `uv` є єдиним каноном.
+- Обовʼязкові кроки `uv lock --check` і `uv sync --frozen` запускаються завжди,
+  якщо `uv` доступний.
+- Опційні лінтери (`ruff check --fix`, `ruff format`, `mypy`) запускаються
+  лише якщо вони доступні через `uv run --frozen <tool> --version`. Якщо
+  відповідного інструмента у uv-середовищі немає — крок пропускається з
+  pass-повідомленням (аналогічно «optional vendor-tools» у `php.mdc`).
+- `ruff` працює в auto-fix-режимі (`--fix`, потім `format`), тобто може
+  мутувати робоче дерево, подібно до `markdownlint-cli2 --fix` у `lint-text`
+  чи `clippy --fix` у `lint-rust`.
+- Серіалізація запусків CLI організована через `runStandardLint` (а не через
+  безпосередній `withLock`) — це відповідає канону патерну `lint-*`, описаному
+  в `.cursor/rules/scripts.mdc` (секція «Серіалізація важких CLI-команд»).
+
+Файл одночасно є:
+
+1. Бібліотекою (експортує функції `runLintPythonSteps` та `runLintPython`).
+2. CLI-точкою входу — при запуску напряму (`isRunAsCli`) виконує
+   `runLintPython()` і виставляє `process.exitCode`.
+
+## Експорти / API
+
+| Експорт              | Тип                     | Призначення                                                                                                                                               |
+| -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runLintPythonSteps` | `function`              | Виконує внутрішні кроки `lint-python` (без зовнішнього локу). Призначений для повторного використання з обгортки `runStandardLint` та для тестування.     |
+| `runLintPython`      | `() => Promise<number>` | Публічна CLI-форма: запускає `runLintPythonSteps` через `runStandardLint`, який бере глобальний лок `lint-python` і дедупає прогони за станом git-дерева. |
+
+Модуль не має default-export. Усі експорти — іменовані ES Module exports.
+
+Side effect модуля верхнього рівня: якщо файл запущений як CLI
+(`isRunAsCli(import.meta.url)` повертає `true`), на верхньому рівні
+виконується `await runLintPython()` і результат записується у
+`process.exitCode`.
+
+## Функції
+
+### `runTool(label, cmd, args, pass, fail)`
+
+Внутрішня (не експортується) функція-обгортка над `child_process.spawnSync`,
+яка запускає вказаний CLI-крок і репортить результат через колбеки репортера.
+
+- Сигнатура: `runTool(label: string, cmd: string, args: string[], pass: (msg: string) => void, fail: (msg: string) => void): boolean`
+- Параметри:
+  - `label` — людиночитана назва кроку, використовується у повідомленнях
+    (`lint-python: <label> — OK` / `lint-python: <label> — помилка ...`).
+  - `cmd` — абсолютний шлях до виконуваного файлу (наприклад, отриманий через
+    `resolveCmd('uv')`).
+  - `args` — масив аргументів CLI.
+  - `pass` — callback репортера для успіху.
+  - `fail` — callback репортера для невдачі.
+- Повертає: `true`, якщо процес завершився з `status === 0`, інакше `false`.
+- Спосіб запуску: `spawnSync(cmd, args, { stdio: 'inherit', shell: false })`.
+  Це означає, що stdout/stderr CLI-кроку успадковуються від батьківського
+  процесу (видно користувачу), а інтерпретація аргументів shell-ом
+  вимкнена — аргументи передаються «as is».
+- Обробка статусу: якщо `r.status` не число (наприклад, процес був убитий
+  сигналом), у повідомлення про помилку підставляється `1`.
+- Side effects: запуск зовнішнього процесу; запис у stdout/stderr батька;
+  виклик `pass` або `fail` репортера.
+
+### `uvToolAvailable(uv, tool)`
+
+Внутрішня (не експортується) перевірка наявності лінтера всередині
+uv-середовища.
+
+- Сигнатура: `uvToolAvailable(uv: string, tool: string): boolean`
+- Параметри:
+  - `uv` — абсолютний шлях до бінарника `uv`.
+  - `tool` — назва бінарника, що перевіряється (`ruff`, `mypy`, тощо).
+- Повертає: `true`, якщо `uv run --frozen <tool> --version` завершився з
+  кодом `0`, інакше `false`.
+- Спосіб запуску: `spawnSync(uv, ['run', '--frozen', tool, '--version'],
+{ stdio: 'ignore', shell: false })`. `stdio: 'ignore'` гасить весь вивід
+  пробної команди, щоб не засмічувати лог.
+- Side effects: запуск дочірнього процесу `uv run --frozen <tool> --version`.
+  Опція `--frozen` гарантує, що `uv` не намагатиметься оновлювати lock-файл
+  під час перевірки.
+
+### `runLintPythonSteps(cwd?)`
+
+Експортована функція. Виконує всю послідовність кроків `lint-python` без
+зовнішнього серіалізаційного локу.
+
+- Сигнатура: `runLintPythonSteps(cwd?: string): number`
+- Параметри:
+  - `cwd` — корінь репозиторію. За замовчуванням `process.cwd()`.
+- Повертає: код виходу — `0`, якщо всі обовʼязкові кроки пройшли успішно,
+  `1` — якщо хоча б один крок зафейлив. Кінцевий код повертається через
+  `reporter.getExitCode()` (інстансу `createCheckReporter`).
+- Алгоритм:
+  1. Створює репортер: `const reporter = createCheckReporter()`,
+     дістає колбеки `{ pass, fail }`.
+  2. Перевіряє `existsSync(join(cwd, 'pyproject.toml'))`. Якщо файла
+     немає — викликає `pass(...)` з повідомленням «кроки Python пропущено»
+     і повертає `reporter.getExitCode()`.
+  3. `const uv = resolveCmd('uv')` — резолвить абсолютний шлях до `uv`.
+     Якщо `uv` не знайдено — `fail(...)` і повернення коду.
+  4. Виконує `runTool('uv lock --check', uv, ['lock', '--check'], pass, fail)`.
+     За невдачі — повертає поточний код (далі не йде).
+  5. Виконує `runTool('uv sync --frozen', uv, ['sync', '--frozen'], pass,
+fail)`. За невдачі — повертає поточний код.
+  6. Створює локальний хелпер `runOptionalUvTool(tool, label, args)`
+     (див. нижче) і послідовно запускає:
+     - `runOptionalUvTool('ruff', 'ruff check --fix', ['check', '--fix', '.'])`
+     - `runOptionalUvTool('ruff', 'ruff format', ['format', '.'])`
+     - `runOptionalUvTool('mypy', 'mypy', ['.'])`
+       За першої ж справжньої невдачі (повертає `false`) — повернення поточного
+       коду виходу.
+  7. Повертає `reporter.getExitCode()`.
+- Side effects:
+  - Запуск зовнішніх процесів (`uv lock`, `uv sync`, `uv run ruff`,
+    `uv run mypy`).
+  - `ruff check --fix` та `ruff format` можуть **модифікувати файли
+    проєкту** (auto-fix Python-коду).
+  - `uv sync --frozen` може створювати або оновлювати `.venv` (з повним
+    дотриманням `uv.lock`).
+  - Запис у stdout/stderr через `stdio: 'inherit'`.
+
+### `runOptionalUvTool(tool, label, args)` (вкладена у `runLintPythonSteps`)
+
+Внутрішній замикач, доступний лише всередині `runLintPythonSteps`. Захоплює
+`uv`, `pass`, `fail` із зовнішньої області видимості.
+
+- Сигнатура: `runOptionalUvTool(tool: string, label: string, args: string[]): boolean`
+- Параметри:
+  - `tool` — імʼя інструмента (`ruff`, `mypy`).
+  - `label` — назва кроку для повідомлень.
+  - `args` — аргументи, які слід передати інструменту після `uv run --frozen <tool>`.
+- Повертає: `true`, якщо крок успішно завершився **або** інструмент
+  відсутній у uv-середовищі (тоді крок пропускається з pass-повідомленням).
+  `false` повертається тільки коли інструмент доступний і завершився з
+  ненульовим статусом.
+- Логіка:
+  1. `if (!uvToolAvailable(uv, tool))` → `pass(...)` з повідомленням «крок
+     пропущено» і повертає `true` (це коректне продовження пайплайну,
+     інструмент трактується як optional).
+  2. Інакше викликає `runTool(label, uv, ['run', '--frozen', tool, ...args],
+pass, fail)`.
+- Side effects: ті ж, що й у `runTool` / `uvToolAvailable` (запуск дочірніх
+  процесів, оновлення репортера).
+
+### `runLintPython`
+
+Публічна обгортка-стрілкова функція.
+
+- Сигнатура: `runLintPython(): Promise<number>`
+- Параметри: немає.
+- Повертає: `Promise<number>` — код виходу, отриманий з `runStandardLint`.
+- Реалізація: `runStandardLint(import.meta.dirname, runLintPythonSteps)`.
+  Сенс параметрів:
+  - `import.meta.dirname` — директорія самого модуля; використовується
+    `runStandardLint` як ідентифікатор для дедуплікації / стану git-дерева.
+  - `runLintPythonSteps` — функція кроків, яку `runStandardLint` викличе
+    всередині глобального локу `lint-python`.
+- Серіалізація: `runStandardLint` бере глобальний лок `lint-python` (як
+  описано в `scripts.mdc`) та дедупає прогони за станом git-дерева, тому
+  паралельні виклики `runLintPython()` не перетинатимуться по запуску
+  `uv`.
+- Side effects: ті самі, що й у `runLintPythonSteps`, плюс блокування на
+  файловому локу.
+
+## CLI-вхід (верхній рівень модуля)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = await runLintPython()
+}
+```
+
+- Перевірка `isRunAsCli(import.meta.url)` встановлює, чи запущений файл
+  безпосередньо як CLI-точка входу (наприклад, `node lint.mjs` або через
+  `n-cursor`), а не імпортований як модуль.
+- Якщо так — виконується top-level `await runLintPython()`, а результат
+  кладеться у `process.exitCode`. Це означає, що Node завершиться з цим
+  кодом після того, як event loop спорожніє.
+- Якщо файл імпортовано як модуль, цей блок не виконується — викликач сам
+  вирішує, як використати експортовані функції.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:child_process` → `spawnSync` — синхронний запуск зовнішніх процесів
+  (`uv`, `uv run …`).
+- `node:fs` → `existsSync` — перевірка наявності `pyproject.toml`.
+- `node:path` → `join` — побудова повного шляху до `pyproject.toml` від `cwd`.
+
+### Внутрішні модулі репозиторію
+
+- `../../../scripts/cli-entry.mjs` → `isRunAsCli` — детекція CLI-режиму
+  через `import.meta.url`.
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` —
+  фабрика репортера з методами `pass`, `fail`, `getExitCode`. Цей патерн
+  єдиний для всіх лінт-кроків.
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd` — пошук
+  виконуваного файлу в `PATH` (повертає абсолютний шлях або `null`).
+- `../../../scripts/lib/run-standard-lint.mjs` → `runStandardLint` —
+  стандартизована обгортка над лінт-кроком (глобальний лок + дедуплікація
+  за станом git-дерева).
+
+### Зовнішні бінарники (runtime-залежності)
+
+- `uv` — обовʼязковий у `PATH`, якщо в репозиторії є `pyproject.toml`.
+- `ruff` — опційний, перевіряється через `uv run --frozen ruff --version`.
+- `mypy` — опційний, перевіряється через `uv run --frozen mypy --version`.
+
+### Артефакти у проєкті
+
+- `pyproject.toml` (у корені `cwd`) — тригер запуску Python-частини.
+- `uv.lock` — використовується `uv lock --check` та `uv sync --frozen`,
+  має бути актуальним.
+
+## Потік виконання / Використання
+
+### Сценарій 1: Python-частини немає
+
+1. `runLintPython()` → `runStandardLint(...)` → `runLintPythonSteps()`.
+2. `existsSync('<cwd>/pyproject.toml')` повертає `false`.
+3. Репортер фіксує pass-повідомлення «немає pyproject.toml у корені — кроки
+   Python пропущено».
+4. Повертається `0`.
+
+### Сценарій 2: Python є, але `uv` не встановлений
+
+1. `existsSync('pyproject.toml')` → `true`.
+2. `resolveCmd('uv')` → `null`.
+3. `fail('lint-python: `uv` не знайдено в PATH ...')`.
+4. Повертається `1`.
+
+### Сценарій 3: Повний прогон з усіма лінтерами
+
+1. `uv lock --check` — перевірка lock-файлу. За невдачі вихід `1`.
+2. `uv sync --frozen` — інсталяція середовища строго за `uv.lock`. За
+   невдачі вихід `1`.
+3. `uvToolAvailable(uv, 'ruff')` → `true` → `uv run --frozen ruff check
+--fix .`. Може **змінити файли**.
+4. `uv run --frozen ruff format .`. Також може **змінити файли**.
+5. `uvToolAvailable(uv, 'mypy')` → `true` → `uv run --frozen mypy .`.
+   Лише читає, не змінює дерево.
+6. Якщо всі кроки повернули `0` — підсумок `0`. Інакше — перший
+   ненульовий код розриває послідовність і повертається.
+
+### Сценарій 4: `ruff` або `mypy` не встановлені у uv-середовищі
+
+- Для відповідного інструмента `uvToolAvailable` поверне `false`.
+- Виводиться pass-повідомлення «<tool> недоступний у uv-середовищі —
+  крок пропущено».
+- Інші кроки виконуються штатно.
+
+### Як викликати з коду
+
+```js
+import { runLintPython, runLintPythonSteps } from './lint.mjs'
+
+// Стандартний шлях: з локом, дедуплікацією, асинхронно.
+const code = await runLintPython()
+process.exit(code)
+
+// Прямий виклик без локу (наприклад, у тестах або з власною серіалізацією):
+const codeRaw = runLintPythonSteps('/path/to/repo')
+```
+
+### Як викликати з CLI
+
+Файл є виконуваною точкою входу для лінт-пайплайну. У звичайному монорепо
+він викликається через спільний раннер (`n-cursor`, `bun run lint` тощо).
+Прямий запуск:
+
+```bash
+node npm/rules/python/lint/lint.mjs
+```
+
+Кодом виходу буде число з `runLintPython()` (`0` — OK, `1` — є помилки).
+
+## Rebuild Test
+
+За цією документацією можна відтворити модуль так:
+
+1. Створити ES Module-файл, що імпортує `spawnSync` з `node:child_process`,
+   `existsSync` з `node:fs`, `join` з `node:path`, а також `isRunAsCli`,
+   `createCheckReporter`, `resolveCmd`, `runStandardLint` з відповідних
+   шляхів `../../../scripts/...`.
+2. Реалізувати приватну `runTool(label, cmd, args, pass, fail)`:
+   `spawnSync` з `stdio: 'inherit'`, `shell: false`; при `status === 0`
+   викликати `pass`, інакше `fail` з кодом (типу number або `1` при
+   неприродному завершенні); повертати `boolean`.
+3. Реалізувати `uvToolAvailable(uv, tool)`: `spawnSync(uv, ['run',
+'--frozen', tool, '--version'], { stdio: 'ignore', shell: false })` →
+   `r.status === 0`.
+4. Експортувати `runLintPythonSteps(cwd = process.cwd())`:
+   - створити репортер;
+   - якщо `pyproject.toml` відсутній → `pass(...)` і повернути код;
+   - резолвити `uv`; якщо немає → `fail(...)` і повернути;
+   - послідовно: `uv lock --check`, `uv sync --frozen` (обовʼязкові);
+   - опційні через локальну функцію-замикач `runOptionalUvTool`: `ruff
+check --fix .`, `ruff format .`, `mypy .` — кожен через
+     `uvToolAvailable` + `runTool`;
+   - повернути `reporter.getExitCode()`.
+5. Експортувати `runLintPython = () => runStandardLint(import.meta.dirname,
+runLintPythonSteps)`.
+6. На верхньому рівні: `if (isRunAsCli(import.meta.url)) process.exitCode =
+await runLintPython()`.
+
+Результат повинен поведінково збігтися з оригіналом: ті самі повідомлення,
+ті самі коди виходу, така ж серіалізація та обробка опційних інструментів.

package/rules/rego/docs/fix.md

@@ -0,0 +1,121 @@
+# fix.mjs — точка входу правила `rego`
+
+## Огляд
+
+Файл `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` забезпечує єдину точку зміни поведінки для всіх правил.
+
+### 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` із зовнішнього коду (приклад)
+
+```js
+import { run } from './npm/rules/rego/fix.mjs'
+
+const code = await run() // або: await run({ walkCache: myCache })
+if (code !== 0) {
+  // правило знайшло порушення
+}
+```
+
+### Як викликати у standalone
+
+```sh
+bun npm/rules/rego/fix.mjs
+echo $? # 0 — OK, 1 — violations
+```
+
+### Подвійна роль файлу
+
+Дві ролі — `library` (іменований експорт `run`) та `standalone` (top-level CLI з `process.exit`) — навмисно поєднані в одному файлі: це дозволяє оркестратору не дублювати code path для одного й того самого правила, а розробнику — швидко прогнати окреме правило без запуску всього батча. Конвенція повторюється для всіх правил у `npm/rules/<id>/fix.mjs`, тож структура файлу `rego/fix.mjs` ідентична іншим правилам у каталозі — змінюється лише імпліцитна тека-«корінь» (`import.meta.dirname`).

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

@@ -0,0 +1,174 @@
+# applies.mjs — applies-гейт правила `rego`
+
+## Огляд
+
+Модуль `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**
+
+- Читає `.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-конфіги, бо вони неактуальні.
+
+### Приклад прямого виклику з тестів або сервісного коду
+
+```js
+import { applies, check } from './applies.mjs'
+
+const shouldRun = await applies('/abs/path/to/repo')
+if (shouldRun) {
+  const code = check()
+  process.exit(code)
+}
+```
+
+## Rebuild Test
+
+Маючи лише цей документ, інженер має змогу відтворити файл наступним чином:
+
+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 із параметрами/повертанням.
+
+Очікуваний зовнішній контракт після rebuild:
+
+- `applies('/repo/with/rego/files')` → `Promise<true>`.
+- `applies('/repo/without/rego/files')` → `Promise<false>`.
+- `check()` → синхронно повертає число (exit-code від check-reporter), друкує pass-повідомлення.