@nitra/cursor 5.2.0 → 5.3.0

package/rules/ga/docs/fix.md

@@ -1,25 +1,27 @@
+---
+docgen:
+  source: npm/rules/ga/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
+
 # fix.mjs
 
 ## Огляд
 
-Цей файл запускає процес перевірки наявності та стану необхідних системних ресурсів. Він забезпечує швидку оцінку готовності системи до подальшої роботи, використовуючи кешовані дані для прискорення процесу. Результати перевірки використовуються для прийняття рішень щодо подальших дій.
+Модуль відповідає за запуск механізму виконання стандартного правила. Він шукає та застосовує правила, використовуючи поточний каталог як джерело. При запуску як окрема програма, він ініціює виконання команди, необхідної для застосування цього правила.
 
 ## Поведінка
 
-1.  Ініціалізує контекст прогону.
-2.  Викликає стандартне правило, використовуючи контекст.
-3.  Якщо код виконується як окремий CLI-скрипт, то:
-    1.  Викликає оркестрацію правил.
-    2.  Повертає код завершення процесу.
+1. Викликає механізм виконання стандартного правила, використовуючи поточний каталог як джерело правил.
+2. Якщо скрипт виконується як окрема програма, запускає оркестрацію командного рядка для виконання правила.
 
 ## Публічний API
 
-- run — Запускає стандартне правило, враховуючи контекст та перетворюючи його на JS-коду, політику та посилання на MDC.
-- Library mode — Викликається через CLI-оркестрацію за допомогою імпорту та функції `run`.
+run — виконує послідовність дій: застосовує правила, обробляє JS-занепокоєння, перевіряє політику та посилання MDC.
 
 ## Гарантії поведінки
 
-- Запускає процес.
-- Кеш зберігає результати попередніх прогонів.
-- Результат залежить від попередніх прогонів.
-- Немає взаємодії з мережею.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,19 +1,22 @@
+---
+docgen:
+  source: npm/rules/ga/js/lint.mjs
+  crc: 428bf482
+  score: 100
+---
+
 # lint.mjs
 
 ## Огляд
 
-Файл `lint` делегує перевірку коду інструменту, який запускається з командного рядка. Він використовується для автоматизованої перевірки коду на відповідність певним правилам. Це забезпечує консистентність та якість коду в проєкті.
+Делегує застосування правил зовнішньому інструменту командного рядка. Параметр `files` ігнорується, оскільки режим перевірки на рівні окремих файлів відсутній. Публічна функція `lint` повертає код виходу інструменту, який визначає успішність або невдачу перевірки.
 
 ## Поведінка
 
-1.  Запускає наявний CLI для перевірки правил.
-2.  Проводить аналіз всього репозиторію, ігноруючи вказаний список файлів.
-3.  Повертає код завершення процесу.
-4.  Не використовує кеш результатів.
-5.  Не здійснює взаємодії з мережею.
+1. Викликає зовнішній інструмент для перевірки коду.
+2. Повертає код виходу цього інструменту.
 
 ## Гарантії поведінки
 
-- Делегує правила до існуючого CLI.
-- Не враховує `files` в режимі per-file.
-- Не має кешування.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/ga/js/docs/workflows.md

@@ -1,32 +1,33 @@
+---
+docgen:
+  source: npm/rules/ga/js/workflows.mjs
+  crc: a9296cf1
+  score: 100
+---
+
 # workflows.mjs
 
 ## Огляд
 
-Файл перевіряє GitHub Actions workflows на відповідність певним правилам та стандартам. Він забезпечує консистентність та якість workflow, виявляючи потенційні проблеми, такі як відсутність clean/lint workflow або використання непідтримуваних інструментів. Це частина автоматизованого процесу забезпечення дотримання найкращих практик при розробці GitHub Actions.
+Модуль виявляє наявність інструменту `shellcheck` та підтверджує відповідність конфігурації проєкту правилам ga.mdc. Він перевіряє відповідність workflow-файлів Rego-полісі, наявність обов'язкових компонентів та коректність шляхів тригерів GitHub Actions. Модуль свідомо пропускає шляхи `.github` та `.git` під час перевірки.
 
 ## Поведінка
 
-- `checkShellcheckInstalled`: Перевіряє наявність бінарника `shellcheck` в системному PATH.
-- `checkGaWorkflowFiles`: Перевіряє наявність workflow-файлів з розширенням `.yml` та відсутність інших розширень.
-- `runAllGaRego`: Запускає Rego-перевірки для всіх workflow-файлів, використовуючи `conftest` для аналізу.
-- `check`: Координує всі перевірки, включаючи Rego-аналіз, перевірку workflow-структури та перевірку наявність файлів.
+checkShellcheckInstalled перевіряє наявність бінарника `shellcheck` у системному шляху, щоб забезпечити узгодженість локальних та CI-перевірок (ga.mdc).
+check виконує комплексну валідацію конфігурації проєкту щодо правил ga.mdc, включаючи структурну перевірку workflow-файлів за допомогою Rego-полісі, перевірку наявності обов'язкових компонентів, валідацію шляхів тригерів GitHub Actions, пошук залишків MegaLinter та перевірку наявності `shellcheck` (ga.mdc). При цьому ігнорує директорії `.github` та `.git`.
 
 ## Публічний API
 
-- checkShellcheckInstalled — Перевіряє наявність `shellcheck` у системі та зупиняє workflow, якщо його немає.
-- check — Перевіряє відповідність проєкту правилам валідації.
-- runAllGaRego — Запускає Rego-перевірку правил, як перший етап валідації.
-- lint-ga — Запускає перевірку `bun lint-ga` з використанням `actionlint` та `zizmor`.
+checkShellcheckInstalled — визначає, чи встановлено `shellcheck` у системному шляху. Це дозволяє `actionlint` запускати перевірки скриптів лише тоді, коли інструмент доступний локально.
+
+check — порівнює структуру проєкту з вимогами, визначеними у правилах (ga.mdc).
+
+Plan B-патерн — виконує первинну перевірку структури робочого процесу за допомогою Rego-полісі. Потім виконує перевірки на рівні JavaScript, включаючи пошук файлів та конфігурацій. Команда `bun run lint-ga` повторно викликає цю ж перевірку, використовуючи зовнішні інструменти.
 
 ## Гарантії поведінки
 
-- Гарантується наявність файлів `package.json`, `.vscode/*` та `.github/zizmor.yml`.
-- Гарантується, що workflow використовує `actions/checkout@v6` перед локальними операціями.
-- Гарантується, що workflow використовує composite action `action.yml` з `npx @nitra/cursor`.
-- Гарантується, що workflow містить `clean-ga-workflows.yml`, `clean-merged-branch.yml`, `lint-ga.yml` та `git-ai.yml`.
-- Гарантується, що workflow використовує `concurrency` для паралельного виконання.
-- Гарантується, що workflow не містить `oven-sh/setup-bun`, `actions/cache`, `bun install` у `uses` або `run`.
-- Гарантується, що workflow не використовує shell-продовження `\` у `run`.
-- Гарантується, що workflow використовує `shellcheck` локально.
-- Гарантується, що workflow перевіряє наявність файлів за допомогою `git ls-files :(glob)` та `on.*.paths`.
-- Гарантується, що workflow перевіряє наявність файлів, що залишилися від MegaLinter.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.

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

@@ -1,264 +1,29 @@
-# tooling.mjs
-
-## Огляд
-
-Модуль `npm/rules/graphql/js/tooling.mjs` — це **check-скрипт правила `graphql.mdc`**, який перевіряє, що репозиторій налаштований для роботи з GraphQL за наявності у коді tagged template literals `gql\`...\``.
-
-Логіка перевірки **умовна**:
-
-1. Скрипт рекурсивно обходить дерево проєкту з кореня (`process.cwd()` за замовчуванням) і збирає файли-кандидати (`.vue`, `.js`, `.ts`, `.jsx`, `.tsx` тощо) — пропускаючи службові артефакти типу `.d.ts`, `auto-imports.d.ts` тощо.
-2. Для кожного кандидата виконує AST-сканування (oxc-parser; для `.vue` — після витягування блоку `<script>`) у пошуках `gql` tagged template literal.
-3. Якщо **жодного збігу не знайдено** — перевірка завершується успішно й нічого більше не вимагає.
-4. Якщо `gql\`…\`` **знайдено хоча б в одному файлі** — модуль вимагає:
-   - наявність файлу `.graphqlrc.yml` у корені репозиторію (GraphQL Config);
-   - відповідність `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions` (тобто рекомендацію розширення VS Code `graphql.vscode-graphql`).
-
-Модуль є частиною інфраструктури `n-cursor` для перевірок правил `.mdc` і дотримується контракту check-скрипта: повертає exit code `0` при успіху й `1` при порушенні.
-
-## Експорти / API
-
-| Експорт                             | Тип                                        | Призначення                                                                             |
-| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `GRAPHQL_RC_FILENAME`               | `string` (const, `.graphqlrc.yml`)         | Очікувана назва файлу GraphQL Config у корені проєкту (з `graphql.mdc`).                |
-| `REQUIRED_GRAPHQL_VSCODE_EXTENSION` | `string` (const, `graphql.vscode-graphql`) | Ідентифікатор обов'язкового розширення VS Code, яке має бути в `recommendations`.       |
-| `check(cwd?)`                       | `async function`                           | Основна точка входу — виконує всю перевірку правила `graphql.mdc` і повертає exit code. |
-
-Внутрішні (не експортовані) хелпери:
-
-- `collectScanCandidates(root, ignorePaths)` — збір абсолютних шляхів файлів для сканування.
-- `collectGqlHits(root, candidates)` — фільтрація кандидатів за наявністю `gql` tagged template.
-- `checkExtensionsRecommendation(pass, fail, cwd)` — делегування перевірки `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions` через `conftest`.
-
-## Функції
-
-### `collectScanCandidates(root, ignorePaths)`
-
-**Сигнатура:**
-
-```js
-async function collectScanCandidates(root: string, ignorePaths: string[]): Promise<string[]>
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію, з якого починається обхід.
-- `ignorePaths` — масив абсолютних шляхів каталогів, які повністю виключаються з обходу (формується через `loadCursorIgnorePaths`).
-
-**Що робить:**
-
-- Викликає `walkDir(root, visitor, ignorePaths)` (рекурсивний обхід файлової системи).
-- Для кожного відвіданого файлу обчислює відносний шлях від `root`, нормалізує роздільники (Windows `\` → POSIX `/`).
-- Застосовує два фільтри:
-  - `shouldSkipFileForGqlScan(rel)` — пропуск службових файлів (`.d.ts`, `auto-imports.d.ts` тощо).
-  - `isGqlScanSourceFile(rel)` — допуск лише відповідних розширень (Vue/JS/TS-сімейство).
-- Накопичує **абсолютні** шляхи прийнятих файлів у масив `candidates`.
-
-**Повертає:** `Promise<string[]>` — список абсолютних шляхів файлів-кандидатів.
-
-**Side effects:** читає метадані файлової системи (через `walkDir`); записів не робить.
-
 ---
-
-### `collectGqlHits(root, candidates)`
-
-**Сигнатура:**
-
-```js
-async function collectGqlHits(root: string, candidates: string[]): Promise<string[]>
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня (для обчислення відносних шляхів у результаті).
-- `candidates` — список абсолютних шляхів файлів, отриманих від `collectScanCandidates`.
-
-**Що робить:**
-
-- Послідовно (`for-of` + `await`) для кожного абсолютного шляху:
-  - обчислює відносний шлях і нормалізує роздільники до `/`;
-  - читає вміст файлу через `readFile(absPath, 'utf8')`;
-  - викликає `sourceFileHasGqlTaggedTemplate(content, rel)` — парсер AST oxc, що враховує особливості `.vue` (витягування `<script>`);
-  - якщо результат `true` — додає **відносний** шлях до результуючого масиву `hits`.
-
-**Повертає:** `Promise<string[]>` — відносні шляхи файлів, у яких знайдено хоча б одне `gql` tagged template.
-
-**Side effects:** читання вмісту файлів з диска. Запис відсутній.
-
+docgen:
+  source: npm/rules/graphql/js/tooling.mjs
+  crc: eb6b4713
+  score: 100
 ---
 
-### `checkExtensionsRecommendation(pass, fail, cwd)`
-
-**Сигнатура:**
-
-```js
-function checkExtensionsRecommendation(
-  pass: (msg: string) => void,
-  fail: (msg: string) => void,
-  cwd: string
-): void
-```
-
-**Параметри:**
-
-- `pass` — функція-репортер «успішно» (отримана з `createCheckReporter()`).
-- `fail` — функція-репортер «порушення».
-- `cwd` — абсолютний корінь репозиторію.
-
-**Що робить:**
-
-1. Формує відносний (`.vscode/extensions.json`) і абсолютний шляхи до файлу VS Code-конфігу.
-2. Якщо файл **не існує** (`existsSync`) — викликає `fail(...)` з повідомленням про те, що треба створити файл і додати `graphql.vscode-graphql` у `recommendations`, посилаючись на `graphql.mdc`. Виходить.
-3. Інакше викликає `runConftestBatch({ policyDirRel: 'graphql/vscode_extensions', namespace: 'graphql.vscode_extensions', files: [pathAbs] })` — делегує перевірку rego-пакету conftest-у.
-4. Якщо `violations.length === 0` — викликає `pass(...)` з повідомленням про відповідність. Інакше — для кожного порушення `v` викликає `fail(v.message)`.
-
-**Повертає:** нічого (`void`). Результати фіксуються через `pass` / `fail`.
-
-**Side effects:**
-
-- читання `.vscode/extensions.json` через зовнішній conftest-процес;
-- виклик `conftest` (binary) усередині `runConftestBatch`;
-- зміна стану внутрішнього reporter-у (накопичення успіхів/порушень).
-
-**Виклик умовний:** виконується лише після того, як основна функція `check` виявила `gql` у дереві.
-
----
-
-### `check(cwd = process.cwd())`
-
-**Сигнатура:**
-
-```js
-export async function check(cwd?: string): Promise<number>
-```
-
-**Параметри:**
-
-- `cwd` — _необов'язковий_ абсолютний шлях до кореня репозиторію. За замовчуванням `process.cwd()`.
-
-**Що робить (потік):**
-
-1. Створює репортер `createCheckReporter()` і деструктурує з нього `pass`, `fail`.
-2. Завантажує список ігнорованих шляхів через `loadCursorIgnorePaths(root)`.
-3. Викликає `collectScanCandidates(root, ignorePaths)` — отримує список файлів-кандидатів.
-4. Викликає `collectGqlHits(root, candidates)` — отримує файли з `gql`.
-5. **Розгалуження:**
-   - Якщо `hits.length === 0` — викликає `pass(...)` з повідомленням «немає `gql\`…\``у джерелах, переглянуто N файлів —`.graphqlrc.yml`не вимагається» і **повертає**`reporter.getExitCode()`(зазвичай`0`).
-   - Інакше викликає `pass(...)` зі звітом про N файлів (з перших 5 з суфіксом `…` якщо більше).
-6. Перевіряє наявність `GRAPHQL_RC_FILENAME` (`.graphqlrc.yml`) у корені через `existsSync`:
-   - Існує → `pass('.graphqlrc.yml існує')`.
-   - Не існує → `fail(...)` з вимогою додати GraphQL Config (з посиланням на `graphql.mdc`).
-7. Викликає `checkExtensionsRecommendation(pass, fail, root)` для перевірки `.vscode/extensions.json`.
-8. Повертає `reporter.getExitCode()`: `0` — усі перевірки пройдені, `1` — є хоча б одне порушення.
-
-**Повертає:** `Promise<number>` — exit code (`0` — OK, `1` — порушення).
-
-**Side effects:**
-
-- читання файлової системи (метадані + вміст файлів кандидатів);
-- читання `.cursor/...` ignore-конфігу;
-- читання `.vscode/extensions.json` (опосередковано через conftest);
-- запуск процесу `conftest` через `runConftestBatch`;
-- мутація стану внутрішнього reporter-у (накопичення pass/fail-повідомлень).
-
-## Залежності
-
-### Node.js builtins
-
-| Модуль             | Що використовується | Призначення                                                                  |
-| ------------------ | ------------------- | ---------------------------------------------------------------------------- |
-| `node:fs`          | `existsSync`        | Синхронна перевірка наявності `.graphqlrc.yml` та `.vscode/extensions.json`. |
-| `node:fs/promises` | `readFile`          | Асинхронне читання вмісту файлів-кандидатів.                                 |
-| `node:path`        | `join`, `relative`  | Збирання абсолютних шляхів і обчислення відносних шляхів від кореня.         |
-
-### Внутрішні модулі репозиторію
-
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter`: фабрика репортера зі стандартним інтерфейсом `pass` / `fail` / `getExitCode()`.
-- `../lib/graphql-gql-scan.mjs`:
-  - `isGqlScanSourceFile(rel)` — предикат «це source-файл, який потенційно містить `gql`» (за розширенням);
-  - `shouldSkipFileForGqlScan(rel)` — предикат «цей файл слід ігнорувати при скануванні» (`.d.ts`, `auto-imports.d.ts` тощо);
-  - `sourceFileHasGqlTaggedTemplate(content, rel)` — AST-перевірка на наявність `gql\`...\``(через oxc-parser; для`.vue`— після витягування`<script>`).
-- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths(root)`: повертає абсолютні шляхи каталогів, повністю виключених з обходу (узгоджено з іншими check-скриптами).
-- `../../../scripts/lib/run-conftest-batch.mjs` — `runConftestBatch({ policyDirRel, namespace, files })`: запускає `conftest` з rego-пакетом і повертає масив `violations` (об'єкти з `.message`).
-- `../../../scripts/utils/walkDir.mjs` — `walkDir(root, visitor, ignorePaths)`: рекурсивний обхід файлової системи з підтримкою списку ігнорування.
-
-### Зовнішні артефакти (не імпортуються, але потрібні в runtime)
-
-- **`conftest`** як CLI-binary (запускається з `runConftestBatch`).
-- **Rego-політика** в `graphql/vscode_extensions` з namespace `graphql.vscode_extensions` (перевіряє `.vscode/extensions.json`).
-- **`.cursor/ignore`-конфіг** у корені (читається `loadCursorIgnorePaths`).
-- **`graphql.mdc`** — правило, яке цей check реалізує.
-
-## Потік виконання / Використання
-
-### Запуск як check
-
-Модуль використовується з єдиною експортованою функцією `check`:
-
-```js
-import { check } from 'npm/rules/graphql/js/tooling.mjs'
-
-const exitCode = await check() // або await check('/absolute/path/to/repo')
-process.exit(exitCode)
-```
-
-Типово викликається диспетчером check-скриптів інфраструктури `n-cursor` (наприклад, із `npm/scripts/...`), який отримує exit code й агрегує результати по всіх правилах `.mdc`.
+# tooling.mjs
 
-### Послідовність дій усередині `check`
+## Огляд
 
-```
-process.cwd() (або переданий cwd)
-        │
-        ▼
-createCheckReporter() ──► { pass, fail, getExitCode }
-        │
-        ▼
-loadCursorIgnorePaths(root) ──► ignorePaths
-        │
-        ▼
-collectScanCandidates(root, ignorePaths)
-        │   walkDir(root, visitor, ignorePaths)
-        │     filter: !shouldSkipFileForGqlScan && isGqlScanSourceFile
-        ▼
-candidates: string[]
-        │
-        ▼
-collectGqlHits(root, candidates)
-        │   for each: readFile + sourceFileHasGqlTaggedTemplate (oxc-parser AST)
-        ▼
-hits: string[]
-        │
-        ├── hits.length === 0 ──► pass("немає gql у джерелах") ──► return 0
-        │
-        └── hits.length > 0
-              │
-              ├── pass("Знайдено gql у N файлі(ах): ...")
-              │
-              ├── existsSync(.graphqlrc.yml)
-              │     ├── true  ──► pass(".graphqlrc.yml існує")
-              │     └── false ──► fail("Відсутній .graphqlrc.yml ...")
-              │
-              ├── checkExtensionsRecommendation(pass, fail, root)
-              │     ├── !existsSync(.vscode/extensions.json) ──► fail(...)
-              │     └── runConftestBatch(graphql/vscode_extensions)
-              │           ├── violations.length === 0 ──► pass(...)
-              │           └── for v of violations: fail(v.message)
-              │
-              └── return reporter.getExitCode() (0 або 1)
-```
+Визначає ім'я файлу конфігурації (`GRAPHQL_RC_FILENAME` = ".graphqlrc.yml") та обов'язкове розширення VS Code (`REQUIRED_GRAPHQL_VSCODE_EXTENSION` = "graphql.vscode-graphql"). Перевіряє наявність конфігурації в `extensions.json` (конфігурація, на яку спирається код) та підтверджує необхідність розширення для роботи з GraphQL (graphql.mdc).
 
-### Семантика повідомлень
+## Поведінка
 
-- `pass` — інформативне повідомлення про успішну перевірку (логнеться як OK, не впливає на exit code).
-- `fail` — повідомлення про порушення; навіть одне `fail` робить `getExitCode()` рівним `1`.
+GRAPHQL_RC_FILENAME: Повертає ім'я файлу конфігурації GraphQL.
+REQUIRED_GRAPHQL_VSCODE_EXTENSION: Повертає ім'я розширення VS Code, необхідне для GraphQL.
+check: Перевіряє наявність `gql` tagged template у джерелах. Якщо знайдено, вимагає наявності `.graphqlrc.yml` та валідує `.vscode/extensions.json` щодо `graphql.vscode-graphql` (graphql.mdc).
 
-### Чому перевірка умовна
+## Публічний API
 
-`graphql.mdc` вимагає `.graphqlrc.yml` і VS Code-розширення `graphql.vscode-graphql` **лише** для проєктів, де реально використовуються `gql` tagged template literals. У монорепо це дозволяє не «спамити» правилом workspace-и, що не торкаються GraphQL — check спочатку доводить релевантність (`hits.length > 0`), і лише потім вимагає інфраструктуру.
+GRAPHQL_RC_FILENAME — вказує на файл конфігурації GraphQL у корені проєкту (graphql.mdc).
+REQUIRED_GRAPHQL_VSCODE_EXTENSION — вимагає встановлення розширення `graphql.vscode-graphql` для роботи з graphql.mdc.
+check — перевіряє наявність файлу `.graphqlrc.yml` та розширення `graphql.vscode-graphql` при використанні тегів GraphQL.
 
-### Обмеження та особливості
+## Гарантії поведінки
 
-- Шляхи в `hits` та в попередженнях завжди **відносні** до `root`, з POSIX-роздільниками `/` (навіть на Windows).
-- Перші 5 файлів-збігів показуються у повідомленні `pass`; решта приховується за суфіксом `…`.
-- Якщо `gql` знайдено, але `.vscode/extensions.json` відсутній — це порушення, незалежне від rego-перевірки (тобто `fail` без виклику conftest).
-- `collectGqlHits` читає файли **послідовно** (без `Promise.all`) — це навмисно, щоб не перевантажувати I/O при великих репозиторіях.
-- Виявлення `gql` — на рівні AST (oxc-parser), а не регулярних виразів; рядкові збіги типу `// gql\`...\`` у коментарі не дають false-positive.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/hasura/docs/fix.md

@@ -1,120 +1,27 @@
-# fix.mjs — entry-point правила `hasura`
+---
+docgen:
+  source: npm/rules/hasura/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/hasura/fix.mjs` — тонкий entry-point для правила з ідентифікатором `hasura` у складі CLI-пакета `@nitra/cursor`. Виконує дві ролі одночасно:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яка викликається з оркестратора CLI (наприклад, з `runRuleCli` або з агрегаторів типу `n-fix`), що дозволяє запускати правило в межах загального прогону всіх правил без породження окремого процесу.
-2. **Standalone mode** — якщо файл виконується безпосередньо (через `bun rules/<id>/fix.mjs` або `node rules/<id>/fix.mjs`), він виступає самостійним CLI-входом, повністю еквівалентним `npx @nitra/cursor fix hasura`: підвантажує config, застосовує whitelist, друкує summary та повертає процесний exit-code.
-
-Уся фактична логіка правила (послідовність кроків `applies → JS-concerns → policy → mdc-refs`) винесена в спільну реалізацію `runStandardRule` із бібліотечного шару `scripts/lib/`. Файл-обгортка несе лише прив'язку правила до власної директорії (через `import.meta.dirname`) та dispatch між двома режимами запуску.
-
-Відповідає конвенції двороль­ового `fix.mjs`, ухваленій для всіх «стандартних» правил у `npm/rules/*/`, тож має мінімальну поверхню коду й не містить специфіки `hasura`: тип правила, скоупи, перевірки та поліcі описуються деінде (`meta.json`, `hasura.mdc`, `js/`, `policy/`).
-
-## Експорти / API
-
-| Експорт | Тип                                      | Призначення                                                                                                                      |
-| ------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-mode прогін правила в спільному CLI orchestration. Повертає `0` при відсутності порушень або `1` при наявності порушень. |
-
-Файл не має `default`-експорту й не експортує жодних інших символів.
-
-Поведінка при безпосередньому запуску файлу як скрипта — побічний ефект (top-level `await runRuleCli(...)` + `process.exit(...)`) і не є частиною програмного API.
-
-## Функції
-
-### `run(ctx)`
-
-Сигнатура: `export function run(ctx)`.
-
-- **Параметри:**
-  - `ctx` (`RuleContext`, опційний) — контекст прогону, що передається з оркестратора. Тип імпортовано (через JSDoc-tag `@param`) з `../../scripts/lib/run-standard-rule.mjs`. Очікувані поля контексту (за конвенцією `runStandardRule`) — спільні для всіх правил, серед них зокрема `walkCache` (кеш обходу файлової системи, щоб не повторювати walk між кількома правилами в одному прогоні). Якщо `ctx` не передано (`undefined`), `runStandardRule` сам ініціалізує мінімально необхідний контекст.
-- **Повертає:** `Promise<number>` — exit-code правила:
-  - `0` — застосовні файли пройшли всі етапи (`applies → JS-concerns → policy → mdc-refs`) без виявлених порушень.
-  - `1` — знайдено принаймні одне порушення (або зафіксована помилка валідації, що інтерпретується як failure).
-- **Side effects:**
-  - Делегує всю роботу `runStandardRule(import.meta.dirname, ctx)`, який, своєю чергою, читає файли правила (`meta.json`, `*.mdc`, `js/*.mjs`, `policy/*.rego`) із директорії, обходить цільові файли проєкту, друкує діагностичні повідомлення у stdout/stderr та повертає підсумкове число порушень. Сам `run` стану не модифікує.
-  - Прив'язує правило до своєї директорії саме через `import.meta.dirname`, тож при переміщенні файлу `fix.mjs` правило автоматично «переїде» разом із його артефактами (без хардкоду шляхів).
-
-### Безіменна процедура top-level (standalone-блок)
+# fix.mjs
 
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Тип:** виконується один раз під час завантаження модуля.
-- **Параметри:** немає (CLI-аргументи зчитуються всередині `runRuleCli` через `process.argv`).
-- **Повертає:** нічого (виконує `process.exit`).
-- **Side effects:**
-  - `isRunAsCli(import.meta.url)` визначає, чи модуль завантажено як прямий entry-point (а не як `import`).
-  - У випадку прямого запуску викликає `runRuleCli(import.meta.dirname)`, який повертає числовий exit-code, і негайно завершує процес із цим кодом через `process.exit`.
-  - Через `process.exit` подальші асинхронні задачі (мікротаски, відкриті ресурси) можуть бути обірвані — це свідомо: standalone entry-point повинен повертати чіткий код для CI/IDE-інтеграцій.
-- **Локальні правила лінту:**
-  - Поряд із викликом стоїть прагма `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE`, оскільки за загальним правилом `process.exit` заборонений, але для CLI-входів дозволений.
-
-## Залежності
-
-### Внутрішні (відносні імпорти)
-
-- `../../scripts/lib/run-rule-cli.mjs`
-  - `isRunAsCli(metaUrl: string): boolean` — детектор «чи запущено модуль як скрипт». Зазвичай порівнює `import.meta.url` із URL виконуваного скрипта (`process.argv[1]`), щоб розрізнити `import` та прямий запуск.
-  - `runRuleCli(ruleDir: string): Promise<number>` — повноцінний CLI-runner: парсить аргументи, читає глобальний config (whitelist, severity, опції), запускає правило з директорії `ruleDir` і друкує summary. Повертає exit-code.
-- `../../scripts/lib/run-standard-rule.mjs`
-  - `runStandardRule(ruleDir: string, ctx?: RuleContext): Promise<number>` — стандартна послідовність кроків для «звичайного» правила: `applies → JS-concerns → policy → mdc-refs`. Це публічне ядро правил-обгорток на кшталт `fix.mjs`.
-  - `RuleContext` (тип) — імпортовано лише в JSDoc для типізації параметра `run`.
-
-### Зовнішні
-
-Прямих залежностей від npm-пакетів файл не має. Усі сторонні бібліотеки, які можуть знадобитися (наприклад, walker, парсер `.mdc`, OPA-обгортки тощо), використовуються транзитивно через `run-standard-rule.mjs` та `run-rule-cli.mjs`.
-
-### Залежність від файлів-побратимів у директорії правила
-
-Хоча `fix.mjs` сам нічого з них не читає, `runStandardRule(import.meta.dirname)` спирається на сусідні артефакти у тій же директорії правила `hasura/`:
-
-- `meta.json` — метадані правила (id, scope, опції тощо);
-- `hasura.mdc` — людинозрозумілий опис правила у форматі Cursor `.mdc`;
-- `js/` — JS-перевірки правила (`check-*.mjs`, fix-helpers);
-- `policy/` — Rego-полісі для OPA-кроку.
-
-Тож структурно файл `fix.mjs` має сенс лише як частина повної папки правила.
-
-## Потік виконання / Використання
-
-### Сценарій A — Library mode (з оркестратора)
+## Огляд
 
-1. Оркестратор (`n-cursor` CLI, агрегатор скілів, тести) робить `import { run } from '<path>/npm/rules/hasura/fix.mjs'`.
-2. Викликає `await run(ctx)`, передаючи контекст із попередньо побудованим `walkCache` та іншими опціями.
-3. `run` синхронно повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule`:
-   - читає `meta.json` із директорії правила;
-   - проганяє послідовність `applies` (фільтр цільових файлів) → JS-concerns (динамічно підвантажені `js/check-*.mjs`) → policy (OPA з `policy/*.rego`) → mdc-refs (валідація `.mdc`-посилань);
-   - агрегує знахідки й повертає кількість порушень як exit-code (`0`/`1`).
-5. Оркестратор підсумовує exit-коди всіх правил.
+Цей файл ініціює застосування правил. Він запускає процес, що включає перевірку JS-занепокоєнь та політик. При самостійному запуску скрипт завантажує конфігурацію та вайтлістинг, а також надає звіт про виконання.
 
-### Сценарій B — Standalone CLI
+## Поведінка
 
-1. Користувач/CI виконує `bun npm/rules/hasura/fix.mjs [args...]`.
-2. На завантаженні модуля Node/Bun обчислює `isRunAsCli(import.meta.url)` — для прямого запуску результат `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - парсинг CLI-аргументів (`--whitelist`, `--severity`, прапори `-q`/`-v` тощо — деталі в `run-rule-cli.mjs`);
-   - підвантаження конфіг-файлу пакета;
-   - застосування whitelist;
-   - виклик внутрішнього еквівалента `runStandardRule` для цієї ж директорії;
-   - друк summary-таблиці результатів.
-4. `process.exit(<exit-code>)` миттєво завершує процес зі значенням, яке повернув `runRuleCli`.
+1. Викликати функцію `run` для виконання правила. Це ініціює процес застосування правил, включаючи перевірку JS-занепокоєнь, політик та посилань MDC.
+2. Якщо скрипт виконується як окрема утиліта (standalone), викликати механізм оркестрації для виконання правила. Це забезпечує повну функціональність, включаючи завантаження конфігурації, вайтлістинг та підсумок.
 
-### Типові випадки використання
+## Публічний API
 
-- **CI:** `bun npm/rules/hasura/fix.mjs` як standalone-крок у пайплайні; ненульовий exit-code зриває build.
-- **Локально:** `npx @nitra/cursor fix hasura` запускає той самий entry-point через диспетчер CLI пакета (а не напряму).
-- **Інтеграція в IDE:** редактор може імпортувати `run` і викликати його в окремому процесі для отримання структурованого результату по правилу `hasura` (наприклад, через виклик `bun -e "import('...fix.mjs').then(m => m.run())"`).
-- **Агрегатори скілів** (наприклад, `n-fix`): паралельно або послідовно імпортують `run` із усіх правил `npm/rules/*/fix.mjs`, передають спільний `ctx` із `walkCache`, щоб уникнути повторного обходу файлової системи.
+run — виконує послідовність дій: застосовує правила, обробляє JavaScript-занепокоєння, перевіряє політику та посилання MDC.
 
-### Технічні зауваження щодо реалізації
+## Гарантії поведінки
 
-- `import.meta.dirname` (Node ≥ 20.11 / Bun) повертає абсолютний шлях до директорії модуля без потреби в `fileURLToPath(import.meta.url)`. Це поточний рекомендований спосіб локалізації власної директорії в ESM-модулях.
-- Прапор `await` у `process.exit(await runRuleCli(...))` працює завдяки top-level await у ESM — додаткової `main()`-обгортки не потрібно.
-- Свідомо обираний `process.exit` (а не «м'який» вихід через `process.exitCode = ...`) гарантує детермінований код повернення для CI/IDE навіть якщо хтось у фоновому таску щось «недописав».
-- Файл нейтральний щодо помилок: `runStandardRule` та `runRuleCli` самі вирішують, чи виносити exception у консоль і конвертувати її в exit-code; `fix.mjs` не обгортає виклики в `try/catch`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/js-bun-db/js-bun-db.mdc

@@ -2,7 +2,7 @@
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 globs: "**/package.json,**/src/conn/**"
 alwaysApply: false
-version: '1.14'
+version: '1.15'
 ---
 
 ## Підтримувані версії баз даних
@@ -300,10 +300,10 @@ const rows = await sql.unsafe(query, values)
 
 Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
 
-Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.js` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
+Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.mjs` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
 
 ```javascript
-// src/conn/db.js
+// src/conn/db.mjs
 import { SQL } from 'bun'
 
 export const pgWrite = new SQL({
@@ -454,16 +454,16 @@ ${pgRead.array(ids, 'int4')}
 
 OXC formatter (oxfmt ≥ 0.49) примусово розгортає будь-який `CallExpression`, де перший аргумент є `CallExpression` з callback, у багаторядковий блок — незалежно від `printWidth`. Тому `pgWrite.array(arr.map(r => r.field), 'type')` всередині tagged template literal завжди стає 4-рядковим блоком. `col(arr, 'field')` (перший аргумент — identifier, другий — string literal) цей тригер не зачіпає і лишається однорядковим.
 
-Канонічне місце хелпера — `src/utils/col.js` (або `src/conn/col.js` залежно від структури проєкту):
+Канонічне місце хелпера — `src/utils/col.mjs` (або `src/conn/col.mjs` залежно від структури проєкту):
 
 ```javascript
-// src/utils/col.js
+// src/utils/col.mjs
 export const col = (arr, key) => arr.map(r => r[key])
 ```
 
 ```javascript
-import { pgWrite } from '#src/conn/db.js'
-import { col } from '#src/utils/col.js'
+import { pgWrite } from '#src/conn/db.mjs'
+import { col } from '#src/utils/col.mjs'
 
 // ❌ oxfmt розгортає на 4+ рядки незалежно від printWidth
 ${pgWrite.array(rows.map(r => r.id), 'int4')}