@nitra/cursor 5.3.3 → 5.4.0

package/rules/js-bun-db/docs/fix.md

@@ -1,148 +1,32 @@
-# `fix.mjs` — entry-point правила `js-bun-db`
+---
+docgen:
+  source: npm/rules/js-bun-db/fix.mjs
+  crc: 38cf876b
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/js-bun-db/fix.mjs` — це **точка входу** (entry-point) для правила `js-bun-db` пакета `@nitra/cursor`. Правило перевіряє/виправляє код, що працює з базою даних у середовищі Bun (JavaScript runtime), і виконується у стандартному CI4-пайплайні:
-
-1. `applies` — визначає, до яких файлів застосовується правило;
-2. `JS-concerns` — перевіряє/чинить специфічні JS-аспекти (через стандартний пайплайн);
-3. `policy` — застосовує політики правила (наприклад, заборонені патерни, переписування коду);
-4. `mdc-refs` — оновлює перехресні посилання у `.mdc`-документах (Markdown Cursor).
-
-Файл виконує **дві ролі одночасно**:
-
-- **Library mode** — експортує функцію `run(ctx)`, яку викликає зовнішній orchestrator (CLI `@nitra/cursor`, ESLint-обгортка, інші правила) для виконання пайплайну у спільному процесі (з можливістю переюзу `walkCache` через переданий `ctx`).
-- **Standalone mode** — якщо файл запущено напряму як CLI (`bun rules/js-bun-db/fix.mjs`), він проганяє повний CLI-цикл (`runRuleCli`) із завантаженням конфігурації, whitelist-фільтрацією та підсумковим виводом, після чого виставляє відповідний `process.exit(code)` для CI/IDE.
-
-Файл свідомо мінімалістичний: уся реальна логіка винесена у бібліотечні утиліти (`run-standard-rule.mjs`, `run-rule-cli.mjs`); `fix.mjs` лише делегує виклики, передаючи `import.meta.dirname` як ідентифікатор поточної директорії правила.
-
-## Експорти / API
-
-| Експорт | Тип        | Призначення                                                                              |
-| ------- | ---------- | ---------------------------------------------------------------------------------------- |
-| `run`   | `function` | Library-режим: виконує стандартний пайплайн правила для переданого/дефолтного контексту. |
-
-Інших іменованих експортів немає. Файл також містить **side-effect-блок** верхнього рівня (див. секцію [Потік виконання](#потік-виконання--використання)), який спрацьовує лише за умови запуску модуля як CLI.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-**Призначення.** Запускає стандартний пайплайн правила (`applies → JS-concerns → policy → mdc-refs`) для директорії, у якій лежить сам `fix.mjs`. Тобто — для правила `js-bun-db`. Делегує всю роботу функції `runStandardRule`.
-
-**Параметри.**
-
-| Ім'я  | Тип                                                         | Обов'язковість | Опис                                                                                                                                                                            |
-| ----- | ----------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx` | `RuleContext` (з `../../scripts/lib/run-standard-rule.mjs`) | Опціональний   | Контекст прогону (наприклад, `walkCache` — закешований обхід файлової системи, поділюваний між правилами одного CLI-сеансу). Якщо не передано — `runStandardRule` створює свій. |
-
-**Повертає.** `Promise<number>`:
-
-- `0` — правило відпрацювало успішно, порушень немає (або всі виправлені автоматично, якщо це fix-режим);
-- `1` — виявлено порушення, які не вдалося виправити автоматично.
-
-**Side effects.**
-
-- Може **читати** файли проєкту (через walk у `runStandardRule`).
-- Може **записувати/змінювати** файли проєкту, якщо стандартний пайплайн застосовує автоматичні фіксери.
-- Може **писати у stdout/stderr** діагностичні повідомлення стандартного пайплайну.
-- **Не** викликає `process.exit` — рішення про exit-code залишається за викликачем.
-
-**Ключовий момент.** Перший аргумент `runStandardRule` — `import.meta.dirname` — це абсолютний шлях до директорії, у якій лежить `fix.mjs` (тобто `…/npm/rules/js-bun-db/`). За цим шляхом `runStandardRule` визначає **id правила** і завантажує його `.mdc`, `check-*.mjs`, тощо.
-
-## Залежності
+# fix.mjs
 
-### Внутрішні модулі (npm/scripts/lib)
-
-| Імпорт            | Звідки                                    | Роль                                                                                                                                                                                                   |
-| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Утиліта-детектор: повертає `true`, якщо переданий `import.meta.url` відповідає файлу, який запущено як головний модуль (`process.argv[1]`). Дозволяє відрізнити library-import від standalone-запуску. |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Standalone CLI orchestration: завантажує конфіг (`.cursor.json`/`package.json`), застосовує whitelist, запускає правило з директорії, друкує summary і повертає `Promise<number>` (exit-code).         |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Бібліотечний прогон стандартного пайплайну правила (`applies → JS-concerns → policy → mdc-refs`). Не виконує CLI-обв'язку (конфіг, summary).                                                           |
-
-### Системні API
-
-| API                   | Використання                                                                                                                       |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `import.meta.dirname` | Абсолютний шлях до директорії, що містить цей `fix.mjs`. Передається у `runStandardRule` та `runRuleCli` як ідентифікатор правила. |
-| `import.meta.url`     | URL поточного модуля. Передається в `isRunAsCli` для перевірки, чи запущено модуль як CLI.                                         |
-| `process.exit`        | Викликається лише у standalone-гілці з кодом, поверненим `runRuleCli`. Дає змогу CI/IDE отримати exit-status.                      |
-
-### ESLint-директива
-
-Файл містить рядкову директиву:
-
-```text
-// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
-```
-
-Свідоме вимкнення правил `n/no-process-exit` та `unicorn/no-process-exit` для рядка з `process.exit`. Виправдання: standalone entry-point **зобов'язаний** повертати exit-code для CI/IDE-консьюмерів.
-
-## Потік виконання / Використання
-
-### Дві ролі модуля
-
-Файл проектувався так, щоб **той самий код** обслуговував і library-, і standalone-сценарії, без дублювання логіки.
-
-#### Library mode (import + run)
-
-```js
-import { run } from '@nitra/cursor/rules/js-bun-db/fix.mjs'
-
-const exitCode = await run({ walkCache })
-//   ^^^^^^^^   0 = OK, 1 = порушення
-```
-
-- Викликач (наприклад, головний CLI `@nitra/cursor`) уже завантажив конфіг, побудував список правил, створив спільний `walkCache`.
-- Викликає `run(ctx)`, отримує число (exit-code-семантика), сам приймає рішення про `process.exit`.
-- Гілка `if (isRunAsCli(...))` **не виконується**, бо `import.meta.url` цього файлу не збігається з URL головного модуля процесу.
-
-#### Standalone mode (bun rules/js-bun-db/fix.mjs)
-
-```bash
-bun npm/rules/js-bun-db/fix.mjs
-# еквівалентно:
-npx @nitra/cursor fix js-bun-db
-```
-
-- Bun запускає `fix.mjs` як головний модуль.
-- `isRunAsCli(import.meta.url)` повертає `true`.
-- Виконується `await runRuleCli(import.meta.dirname)` — повний CLI-цикл: завантаження конфігурації, whitelist-фільтрація, прогон, друк підсумку.
-- Результат (number) передається у `process.exit`, який завершує процес із потрібним exit-code для CI/IDE.
-
-### Послідовність кроків при standalone-запуску
-
-1. Інтерпретатор виконує верхньорівневі імпорти (`isRunAsCli`, `runRuleCli`, `runStandardRule`).
-2. Створюється/реєструється функція `run` (експорт).
-3. Перевіряється `isRunAsCli(import.meta.url)` — для standalone дає `true`.
-4. Викликається `await runRuleCli(import.meta.dirname)` — повертає `Promise<number>`.
-5. `process.exit(<number>)` завершує процес.
+## Огляд
 
-### Послідовність кроків при library-import
+Виконує застосування JS-занепокоєних на наданому контексті прогону. Застосовує визначену політику та генерує посилання MDC. Повертає результат прогону.
 
-1. Інтерпретатор виконує верхньорівневі імпорти.
-2. Створюється функція `run` (експорт стає доступним викликачу).
-3. `isRunAsCli(...)` повертає `false` — гілка `if (...)` пропускається.
-4. Модуль готовий: викликач у будь-який момент викликає `run(ctx)`.
+## Поведінка
 
-### Архітектурні нотатки
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
-- **Чому два режими в одному файлі.** Така подвійна роль (`library + standalone`) — конвенція пакета `@nitra/cursor` для всіх `fix.mjs` правил. Це дає:
-  - можливість швидко прогнати **одне правило** локально під час розробки (`bun rules/<id>/fix.mjs`);
-  - можливість CLI-оркестратору **імпортувати** правило без форку процесу;
-  - єдиний контракт (`run(ctx) → Promise<number>`) для всіх правил пакета.
-- **Чому `import.meta.dirname`.** Це абсолютний шлях, який не залежить від CWD виклику; правило знаходить свої артефакти (`.mdc`, `check-*.mjs`, `meta.json`) відносно власного розташування на диску.
-- **Чому `await` перед `runRuleCli`.** `runRuleCli` — асинхронна функція; `process.exit` має отримати готове число, а не `Promise`.
+## Публічний API
 
-## Rebuild Test
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-З опису вище можна реконструювати поведінку файлу:
+## Гарантії поведінки
 
-1. **Імпорти.** Дві утиліти з `../../scripts/lib/run-rule-cli.mjs` (`isRunAsCli`, `runRuleCli`) та одна з `../../scripts/lib/run-standard-rule.mjs` (`runStandardRule`).
-2. **Експорт `run(ctx)`.** Повертає `runStandardRule(import.meta.dirname, ctx)`. Сигнатура: `(ctx?: RuleContext) => Promise<number>`. `0` — OK, `1` — порушення.
-3. **CLI-блок.** Умова `if (isRunAsCli(import.meta.url))`. Усередині — `process.exit(await runRuleCli(import.meta.dirname))`. Перед `process.exit` стоїть `eslint-disable-next-line` для `n/no-process-exit` та `unicorn/no-process-exit` із поясненням, що standalone entry-point має повертати exit-code.
-4. **Жодної іншої логіки.** Файл не містить ні констант, ні класів, ні допоміжних функцій — лише делегування.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/js-bun-db/js/docs/safety.md

@@ -1,231 +1,43 @@
-# `safety.mjs` — перевірка правила `js-bun-db.mdc`
+---
+docgen:
+  source: npm/rules/js-bun-db/js/safety.mjs
+  crc: eaeb52bc
+  score: 100
+---
 
-## Огляд
-
-Модуль `npm/rules/js-bun-db/js/safety.mjs` — основний JS-чекер правила `js-bun-db.mdc`. Його завдання — обійти репозиторій і переконатися, що проєкт використовує **Bun native SQL** (`import { sql, SQL } from 'bun'`) замість застарілих PostgreSQL/MySQL клієнтів, та що Bun SQL використовується безпечно.
-
-Чекер виконує три великі групи перевірок:
-
-1. **Заборона `pg-format` / `mysql2`** у `dependencies` будь-якого `package.json`. Цю частину закриває окремий Rego-поліс у `npm/policy/js_bun_db/package_json/` — `safety.mjs` лише довіряє йому й не дублює перевірку.
-2. **Виключення для `pg`** — dependency `pg` дозволено тільки тоді, коли в коді справді використовується `LISTEN` / `NOTIFY` / `UNLISTEN` або listener `.on('notification', ...)` (Bun SQL поки не покриває LISTEN/NOTIFY). Перевірка йде на двох рівнях: на рівні кожного `package.json` (якщо в проекті взагалі немає LISTEN/NOTIFY — `pg` забороняється) і per-file (файл з `import 'pg'` сам має містити LISTEN/NOTIFY-патерн).
-3. **Безпечне використання Bun SQL** у файлах з `import { sql|SQL } from 'bun'`. Сюди входять перевірки на `new SQL(...)` у функції (має бути модульний singleton), `sql.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`, динамічні `.join(',')` у `IN (...)` / `VALUES (...)`, IN-списки без guard на пустоту, pg-format-сумісні шими (`format` / `quoteLiteral` / `quoteIdent`) і `query(text, params)`-обгортки над `<obj>.unsafe(...)`.
-
-Усі знайдені порушення повідомляються через `createCheckReporter()` як `fail`, а кожна «чиста» категорія дає окремий `pass`. Підсумкове значення — `0` (все чисто) або `1` (є порушення) — повертає функція `check`.
-
-## Експорти / API
-
-| Експорт       | Тип              | Призначення                                                                                          |
-| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
-| `check(cwd?)` | `async function` | Публічна точка входу. Виконує всі перевірки правила `js-bun-db.mdc` і повертає exit-код (`0` / `1`). |
-
-Решта функцій (`findAllSourcePathsForBunSqlScan`, `scanSourcesForBunSqlPatterns`, `collectPgUsageForFile`, `scanFileForBunSqlPatterns`, `checkPgDependencyAndUsage`, `messageForBunSqlInListGuard`) — внутрішні; з модуля не експортуються.
-
-Константи модульного скоупу (теж не експортуються):
-
-- `LISTEN_NOTIFY_KEYWORD_RE` — `/\b(LISTEN|UNLISTEN|NOTIFY)\b/iu`. Дешевий pre-filter regex для пошуку SQL-ключових слів.
-- `NOTIFICATION_LITERAL_RE` — `/['"`]notification['"`]/u`. Дешевий pre-filter regex для рядкового літерала `'notification'`(як ім'я події в`.on('notification', ...)`).
-
-Обидві винесені у модульний скоуп, щоб не перекомпілювати `RegExp` на кожен виклик `collectPgUsageForFile`.
-
-## Функції
-
-### `findAllSourcePathsForBunSqlScan(repoRoot, ignorePaths)`
-
-- **Сигнатура:** `async function findAllSourcePathsForBunSqlScan(repoRoot: string, ignorePaths: string[]): Promise<string[]>`
-- **Параметри:**
-  - `repoRoot` — абсолютний шлях до кореня репозиторію.
-  - `ignorePaths` — масив абсолютних шляхів каталогів, які повністю виключаються з обходу (звичайно отримується з `loadCursorIgnorePaths`).
-- **Повертає:** масив абсолютних шляхів файлів, що проходять `isBunSqlScanSourceFile(rel)`, відсортований за відносним posix-шляхом (через `localeCompare`).
-- **Side effects:** виключно читання директорій через `walkDir`; нічого не пише.
-- **Деталі:** використовує `walkDir` із зовнішнього колбека: для кожного знайденого `absPath` обчислює відносний шлях, нормалізує windows-роздільники (`\\` → `/`) і викликає `isBunSqlScanSourceFile`. Сортування потрібне, щоб порядок повідомлень про порушення був детермінованим.
-
-### `scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter)`
-
-- **Сигнатура:** `async function scanSourcesForBunSqlPatterns(sourcePaths: string[], repoRoot: string, reporter: { pass: (m: string) => void, fail: (m: string) => void }): Promise<{ hasBunSqlImport: boolean, perRequest: number, unsafeCall: number, unsafeTemplateInterp: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number, pgUsage: Array<{ rel: string, imports: { line: number, snippet: string }[], listenNotify: { line: number, snippet: string, kind: string }[] }> }>`
-- **Параметри:**
-  - `sourcePaths` — абсолютні шляхи джерел, відібраних `findAllSourcePathsForBunSqlScan`.
-  - `repoRoot` — абсолютний шлях до кореня.
-  - `reporter` — обʼєкт з `pass`/`fail` (тут використовується лише `fail`).
-- **Повертає:** обʼєкт з прапором `hasBunSqlImport`, лічильниками порушень за категоріями (`perRequest`, `unsafeCall`, `unsafeTemplateInterp`, `dynamicList`, `inListGuard`, `pgLeftover`, `pgFormatShim`, `queryWrapper`) та масивом `pgUsage` (тільки файли з імпортом `'pg'` або LISTEN/NOTIFY-патерном).
-- **Side effects:** читає файли через `readFile`; викликає `fail(...)` для кожного порушення (через `scanFileForBunSqlPatterns`).
-- **Деталі:** проходить по всіх файлах послідовно (`for ... of`), щоб не створювати лавину паралельних `readFile`. Прапор `hasBunSqlImport` встановлюється тільки один раз — після першого знайденого `import { sql|SQL } from 'bun'`. У повернутому обʼєкті лічильник `unsafeTemplateInterp` присутній фактично, хоча у JSDoc-типі формально не задекларований (важлива деталь для подальшого використання у `check`).
-
-### `collectPgUsageForFile(content, rel, pgUsage)`
-
-- **Сигнатура:** `function collectPgUsageForFile(content: string, rel: string, pgUsage: Array<{ rel, imports, listenNotify }>): void`
-- **Параметри:**
-  - `content` — повний вміст файлу.
-  - `rel` — posix-шлях відносно кореня репо.
-  - `pgUsage` — масив-акумулятор (мутується in place).
-- **Повертає:** нічого.
-- **Side effects:** мутує `pgUsage` через `push`.
-- **Деталі:**
-  1. Дешевий текстовий pre-filter: `mayHaveListenNotify = LISTEN_NOTIFY_KEYWORD_RE.test(content) || NOTIFICATION_LITERAL_RE.test(content)`.
-  2. Якщо файл не імпортує `'pg'` І не пройшов pre-filter — швидкий `return` (AST не парситься).
-  3. Інакше викликаються AST-сканери `findPgLibImportInText` і `findPgListenNotifyUsageInText`.
-  4. Якщо обидва пусті — запис не додається.
-  5. Інакше у `pgUsage` пушиться `{ rel, imports, listenNotify }`.
-
-Логіка економить памʼять (не зберігаються метадані файлів без сигналу) і CPU (AST не парситься для файлів без жодного зі слів LISTEN / NOTIFY / UNLISTEN / `'notification'` і без імпорту `'pg'`).
-
-### `scanFileForBunSqlPatterns(content, rel, fail, counts)`
+# safety.mjs
 
-- **Сигнатура:** `function scanFileForBunSqlPatterns(content: string, rel: string, fail: (msg: string) => void, counts: { perRequest, unsafeCall, unsafeTemplateInterp, dynamicList, inListGuard, pgLeftover, pgFormatShim, queryWrapper }): void`
-- **Параметри:**
-  - `content` — вміст файлу.
-  - `rel` — posix-шлях відносно `repoRoot`.
-  - `fail` — колбек з reporter'а для запису повідомлень про порушення.
-  - `counts` — обʼєкт-акумулятор лічильників (мутується).
-- **Повертає:** нічого.
-- **Side effects:** інкрементує лічильники `counts.*` та викликає `fail(...)` для кожного знайденого порушення.
-- **Деталі:** запускає по черзі сімейство сканерів з `bun-sql-scan.mjs`:
-
-  | Сканер                                           | Лічильник              | Тип порушення                                                                                                         |
-  | ------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
-  | `findBunSqlPerRequestConnectionInText`           | `perRequest`           | `new SQL(...)` всередині функції — має бути модульний singleton.                                                      |
-  | `findBunSqlUnsafeUseWithoutAllowMarkerInText`    | `unsafeCall`           | `<obj>.unsafe(...)` без маркера `// allow-unsafe: <reason>` на тому ж/попередньому рядку.                             |
-  | `findBunSqlUnsafeWithInterpolatedTemplateInText` | `unsafeTemplateInterp` | `sql.unsafe(\`...\${x}...\`)` з template-літералом + інтерполяцією (заборонено навіть з allow-маркером).              |
-  | `findBunSqlPgLeftoverCallInText`                 | `pgLeftover`           | `<obj>.connect(...)` / `<obj>.end(...)` у файлах з Bun SQL (Bun сам керує пулом).                                     |
-  | `findUnsafeBunSqlDynamicSqlListInText`           | `dynamicList`          | Динамічний список через `.join(',')` у `IN (...)` / `VALUES (...)`.                                                   |
-  | `findUnsafeBunSqlInListMissingEmptyGuardInText`  | `inListGuard`          | IN-список без перевірки на пустоту з `throw` — повідомлення формує `messageForBunSqlInListGuard`.                     |
-  | `findPgFormatShimDefinitionInText`               | `pgFormatShim`         | Локальне визначення pg-format-сумісного шиму (`format` з `%L` / `%I` / `%s`, або `quoteLiteral` / `quoteIdent` тощо). |
-  | `findPgFormatLikeQueryWrapperInText`             | `queryWrapper`         | `query(text, params)` обгортка над `<obj>.unsafe(...)` — прихований pg-сумісний шим.                                  |
-
-  Кожне повідомлення містить шлях, номер рядка, людський опис проблеми, посилання на правило `js-bun-db.mdc` і сам snippet порушення. Для `findPgFormatShimDefinitionInText` повідомлення розгалужується за `v.kind === 'format_function'` (повна функція з форматерами) vs інше (escape-хелпер на кшталт `quoteLiteral`).
-
-### `checkPgDependencyAndUsage(pkgJsonPaths, repoRoot, pgUsage, reporter)`
-
-- **Сигнатура:** `async function checkPgDependencyAndUsage(pkgJsonPaths: string[], repoRoot: string, pgUsage: Array<{ rel, imports, listenNotify }>, reporter: { fail: (m: string) => void }): Promise<{ pgDepFails: number, pgImportFails: number, pgDepsFound: number, hasAnyListenNotify: boolean, listenNotifyEvidence: string | null }>`
-- **Параметри:**
-  - `pkgJsonPaths` — абсолютні шляхи всіх знайдених `package.json`.
-  - `repoRoot` — корінь репозиторію.
-  - `pgUsage` — метадані з `scanSourcesForBunSqlPatterns`.
-  - `reporter` — обʼєкт з `fail`.
-- **Повертає:** обʼєкт зі статистикою:
-  - `pgDepFails` — скільки `package.json` мають `dependencies.pg` без підтвердженого LISTEN/NOTIFY у проекті.
-  - `pgImportFails` — скільки окремих файлів-імпортів `'pg'` не мають власного LISTEN/NOTIFY.
-  - `pgDepsFound` — скільки `package.json` оголошують `dependencies.pg` (для `pass`-повідомлення про виключення).
-  - `hasAnyListenNotify` — чи хоч десь у проекті є LISTEN/NOTIFY.
-  - `listenNotifyEvidence` — рядок виду `"<rel>:<line>"` — перший доказ LISTEN/NOTIFY (або `null`).
-- **Side effects:** читає `package.json` через `readFile`; викликає `reporter.fail(...)` за кожне порушення.
-- **Деталі:**
-  1. Спочатку шукає у `pgUsage` перший файл з непустим `listenNotify` (`firstWithListenNotify`) — фіксується доказ (`<rel>:<firstLine>`).
-  2. Цикл по `pkgJsonPaths`: парсить кожен `package.json` (`JSON.parse`), на невалідному — `continue` (це проблема інших правил). Якщо немає `dependencies.pg` — пропускає. Інакше інкрементує `pgDepsFound` і, якщо у проекті немає LISTEN/NOTIFY взагалі, інкрементує `pgDepFails` та пише `fail` про заборону `dependencies.pg`.
-  3. Цикл по `pgUsage`: для кожного файлу з імпортом `'pg'`, але без LISTEN/NOTIFY — інкрементує `pgImportFails` і пише `fail` по кожному імпорту окремо.
-
-### `messageForBunSqlInListGuard(rel, v)`
-
-- **Сигнатура:** `function messageForBunSqlInListGuard(rel: string, v: { line: number, snippet: string, name?: string, reason: string }): string`
-- **Параметри:**
-  - `rel` — posix-шлях файлу.
-  - `v` — обʼєкт порушення від `findUnsafeBunSqlInListMissingEmptyGuardInText`: містить `line`, `snippet`, опційне `name` (ідентифікатор змінної) і `reason` (підвид діагностики).
-- **Повертає:** готовий рядок-повідомлення для `fail`.
-- **Side effects:** немає; чиста функція.
-- **Деталі:** діагностика розгалужується за `v.reason`:
-  - `'missing_guard'` — змінна-IN не має перевірки на пустоту з `throw`.
-  - `'sql_helper_not_var'` — у `${sql(...)}` всередині IN-списку має бути Identifier (а не вираз/виклик).
-  - інакше (default) — значення IN-списку у template literal треба винести в окрему змінну, валідувати на пустоту і кинути `throw` замість прямої підстановки.
-
-### `check(cwd?)`
-
-- **Сигнатура:** `export async function check(cwd: string = process.cwd()): Promise<number>`
-- **Параметри:**
-  - `cwd` — корінь репозиторію; за замовчуванням `process.cwd()`.
-- **Повертає:** `0`, якщо порушень не знайдено; `1` — інакше. Точне значення обчислює `reporter.getExitCode()`.
-- **Side effects:** читання файлів (`existsSync`, `readFile`, `walkDir`); виклики `reporter.pass(...)` / `reporter.fail(...)` (у дефолтній імплементації — друкують у консоль).
-- **Деталі (порядок виконання):**
-  1. Створює reporter через `createCheckReporter()`; деструктурує `{ pass }`.
-  2. Перевіряє існування `package.json` у корені. Якщо немає — `pass('js-bun-db: package.json у корені відсутній — перевірку пропущено')` і ранній вихід.
-  3. Підвантажує `ignorePaths` через `loadCursorIgnorePaths(repoRoot)` (читає `.cursorignore` тощо).
-  4. Шукає всі `package.json` у репо (`findAllPackageJsonPaths`). Якщо нічого — `pass(...)` і вихід.
-  5. Збирає всі JS/TS-джерела для скану (`findAllSourcePathsForBunSqlScan`). Якщо нічого — `pass(...)` і вихід.
-  6. Сканує всі джерела (`scanSourcesForBunSqlPatterns`) і отримує лічильники + `pgUsage` + `hasBunSqlImport`.
-  7. Перевіряє dependency `pg` і per-file імпорти (`checkPgDependencyAndUsage`). На основі `pgDepFails === 0` / `pgImportFails === 0` пише відповідні `pass`-повідомлення (з різним текстом залежно від `pgDepsFound`).
-  8. Якщо `hasBunSqlImport === false` — `pass('Bun SQL не використовується в коді')` і ранній вихід (немає сенсу скаржитися на патерни Bun SQL у проекті, що ним не користується).
-  9. Інакше для кожної категорії з `count === 0` пише позитивний `pass` (`new SQL` singleton, `sql.unsafe` маркерована, `unsafeTemplateInterp`, pg-leftover, dynamic list, in-list guard, pg-format шими, query-обгортки).
-  10. Повертає `reporter.getExitCode()`.
-
-## Залежності
-
-Зовнішні (Node.js core):
-
-- `node:fs` → `existsSync` — перевірка наявності кореневого `package.json`.
-- `node:fs/promises` → `readFile` — асинхронне читання файлів.
-- `node:path` → `join`, `relative` — побудова шляхів і обчислення відносних.
-
-Внутрішні модулі репозиторію:
-
-- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика reporter'а з `pass` / `fail` / `getExitCode`.
-- `../lib/bun-sql-scan.mjs` — набір AST-сканерів і дешевих текстових пре-фільтрів:
-  - `findBunSqlPerRequestConnectionInText`
-  - `findBunSqlPgLeftoverCallInText`
-  - `findBunSqlUnsafeUseWithoutAllowMarkerInText`
-  - `findBunSqlUnsafeWithInterpolatedTemplateInText`
-  - `findPgFormatLikeQueryWrapperInText`
-  - `findPgFormatShimDefinitionInText`
-  - `findPgLibImportInText`
-  - `findPgListenNotifyUsageInText`
-  - `findUnsafeBunSqlDynamicSqlListInText`
-  - `findUnsafeBunSqlInListMissingEmptyGuardInText`
-  - `isBunSqlScanSourceFile` — фільтр шляхів (які файли скануються взагалі).
-  - `textHasBunSqlImport` — швидкий текстовий тест на наявність `import { sql|SQL } from 'bun'`.
-  - `textHasPgLibImport` — швидкий текстовий тест на наявність `import ... from 'pg'`.
-- `../../../scripts/utils/find-package-json-paths.mjs` → `findAllPackageJsonPaths` — обхід репо і збір усіх `package.json` (з урахуванням ignore-паттернів).
-- `../../../scripts/lib/load-cursor-config.mjs` → `loadCursorIgnorePaths` — список абсолютних шляхів, виключених з обходу (на основі конфігу Cursor).
-- `../../../scripts/utils/walkDir.mjs` → `walkDir` — рекурсивний обхід каталогу з підтримкою ignore-list.
-
-Покладається на наявність ESM, `bun`/`node` runtime з підтримкою top-level `process.cwd()`.
-
-## Потік виконання / Використання
-
-### Імпорт як бібліотека
-
-```js
-import { check } from './safety.mjs'
-
-const exitCode = await check(process.cwd())
-process.exit(exitCode)
-```
+## Огляд
 
-### Запуск у складі checker-пайплайна
+Огляд
 
-Функція `check(cwd)` — це стандартний контракт правил `npm/rules/<rule-id>/js/safety.mjs` у репозиторії. Зовнішній runner викликає її, отримує `0` / `1` і за потреби агрегує з іншими правилами.
+Файл перевіряє шляхи до файлів та залежностей, пов'язаних з Bun SQL та бібліотекою `pg`. Файл збирає метадані про використання `pg` та механізми LISTEN/NOTIFY. (js-bun-db.mdc)
 
-### Логічний потік `check`
+## Поведінка
 
-```
-check(cwd)
-  ├── existsSync(<cwd>/package.json)?       // ні → pass + exit
-  ├── loadCursorIgnorePaths(repoRoot)
-  ├── findAllPackageJsonPaths(...)          // 0 → pass + exit
-  ├── findAllSourcePathsForBunSqlScan(...)  // 0 → pass + exit
-  ├── scanSourcesForBunSqlPatterns(...)
-  │     для кожного файлу:
-  │       ├── textHasBunSqlImport → встановити hasBunSqlImport
-  │       ├── scanFileForBunSqlPatterns → 8 сканерів, fail + counts
-  │       └── collectPgUsageForFile → текст-prefilter → AST → push pgUsage
-  ├── checkPgDependencyAndUsage(...)
-  │     ├── знайти firstWithListenNotify → listenNotifyEvidence
-  │     ├── по кожному package.json з dependencies.pg → fail якщо нема LISTEN/NOTIFY
-  │     └── по кожному файлу з import 'pg' без LISTEN/NOTIFY → fail
-  ├── pass-повідомлення про pg (залежно від pgDepsFound / listenNotifyEvidence)
-  ├── якщо !hasBunSqlImport → pass + exit
-  └── pass для кожної категорії з count === 0
-        (perRequest, unsafeCall, unsafeTemplateInterp,
-         pgLeftover, dynamicList, inListGuard,
-         pgFormatShim, queryWrapper)
-  └── return reporter.getExitCode()
-```
+1. Завантажити шляхи до файлів з коду
+2. Просканувати джерела за патернами Bun SQL
+3. Зібрати метадані про використання `pg` та LISTEN/NOTIFY
+4. Перевірити залежності `pg` та використання LISTEN/NOTIFY
+5. Перевірити імпорти `pg` та використання LISTEN/NOTIFY
+6. Перевірити наявність `package.json` для залежностей `pg`
+7. Перевірити використання `import { sql|SQL } from 'bun'`
+8. Перевірити відсутність створення `new SQL` всередині функцій
+9. Перевірити використання `sql.unsafe` без маркерів дозволу
+10. Перевірити використання `sql.unsafe` з template-літералами
+11. Перевірити використання `pg-leftover` викликів
+12. Перевірити використання `findBunSqlUnsafeBunSqlDynamicSqlListInText`
+13. Перевірити використання `findUnsafeBunSqlInListMissingEmptyGuardInText`
+14. Перевірити використання `findPgFormatShimDefinitionInText`
+15. Перевірити використання `findPgFormatLikeQueryWrapperInText`
+16. Перевірити наявність використання `import { sql } from 'bun'`
 
-### Як інтерпретувати вивід
+## Публічний API
 
-- Кожне порушення друкується через `fail(...)` з префіксом `js-bun-db:`, шляхом `<rel>:<line>`, описом і snippet.
-- Кожна чиста категорія дає `pass(...)` — це корисно для логів CI, щоб бачити, що перевірка не «мовчки» пропущена.
-- Exit-код `0` гарантує, що жоден `fail` не був викликаний; `1` — є щонайменше один.
+check — Перевіряє відповідність проєкту правилу js-bun-db.mdc
 
-### Сценарії раннього виходу
+## Гарантії поведінки
 
-- Корінь без `package.json` — нічого перевіряти.
-- `package.json` не знайдено взагалі — те саме.
-- Немає файлів для скану (`isBunSqlScanSourceFile` повернув `false` для всіх) — Bun SQL-патерни ніде шукати.
-- У жодному файлі немає `import { sql|SQL } from 'bun'` — у проекті немає Bun SQL, тож перевірки на `new SQL`, `unsafe`, IN-списки тощо нерелевантні. Перевірка `pg`-dependency при цьому виконується завжди (до цього раннього виходу), бо її цінність не залежить від Bun SQL.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

package/rules/js-bun-redis/docs/fix.md

@@ -1,123 +1,34 @@
-# fix.mjs — правило `js-bun-redis`
+---
+docgen:
+  source: npm/rules/js-bun-redis/fix.mjs
+  crc: 38cf876b
+  score: 80
+---
 
-## Огляд
-
-Файл `npm/rules/js-bun-redis/fix.mjs` — це тонкий **entry-point** правила `js-bun-redis` у системі `@nitra/cursor`. Він не містить власної бізнес-логіки перевірки/виправлення: уся робота (resolve `applies`, JS-concerns, policy, mdc-refs) делегується утиліті `runStandardRule`, а CLI-обгортка — `runRuleCli`.
-
-Файл реалізує **дві ролі одночасно**:
-
-1. **Library mode** — інші модулі імпортують функцію `run(ctx)` і запускають правило в межах загального оркестрування (наприклад, `npx @nitra/cursor fix` обходить набір правил, передаючи спільний `walkCache` через `ctx`).
-2. **Standalone mode** — пряме виконання через `bun npm/rules/js-bun-redis/fix.mjs`. У цьому випадку модуль самостійно завантажує конфіг, застосовує whitelist і друкує summary, повертаючи коректний exit-code для CI/IDE.
-
-Правило `js-bun-redis` належить до родини "standard rules" і параметризується тим, що `runStandardRule` отримує `import.meta.dirname` поточної теки — далі допоміжна бібліотека сама читає `meta.json`, `applies.mjs`, `check-*.mjs` тощо, які знаходяться поруч у каталозі `npm/rules/js-bun-redis/`.
-
-## Експорти / API
-
-| Експорт | Тип                                  | Опис                                                                                                                      |
-| ------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function (ctx?) => Promise<number>` | Іменований експорт. Запускає правило в library-режимі. Сумісний із загальним runner-ом, який очікує сигнатуру `run(ctx)`. |
-
-Default-експорту немає. Side-effect-ний блок наприкінці файлу не експортується — він активний лише при прямому виконанні модуля як CLI.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` (необовʼязковий) — обʼєкт контексту прогону правила (`RuleContext`, тип реекспортовано з `../../scripts/lib/run-standard-rule.mjs`). Типово містить кешовані результати обходу файлової системи (`walkCache`) та інші спільні структури, які передаються між правилами під час оркестрованого прогону. Якщо викликати без аргументу — `runStandardRule` створить локальний контекст самостійно.
-- **Повертає:** `Promise<number>` — exit-код:
-  - `0` — правило пройшло без порушень,
-  - `1` — знайдено порушення (`runStandardRule` сам формує summary з деталями знайдених проблем у stdout/stderr).
-- **Side effects:**
-  - Читання файлів проєкту, які матчаться `applies.mjs` цього правила.
-  - Логування результатів (summary) у stdout залежить від внутрішньої поведінки `runStandardRule`.
-  - Безпосередньо у `fix.mjs` ніяких глобальних мутацій, мережевих викликів чи запису у ФС немає — все інкапсульовано в делегованих бібліотеках.
-
-### CLI-блок (top-level, без імені)
+# fix.mjs
 
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Умова:** `isRunAsCli(import.meta.url)` повертає `true`, коли цей файл є entry-point поточного Node/Bun-процесу (а не імпортується з іншого модуля).
-- **Дія:** виконує `await runRuleCli(import.meta.dirname)` — повний еквівалент `npx @nitra/cursor fix <id>`, включно з:
-  - завантаженням конфігурації,
-  - застосуванням whitelist,
-  - друком підсумкового summary.
-- **Завершення процесу:** результат (числовий exit-code) передається у `process.exit(...)`, що зупиняє процес із потрібним статусом для CI / IDE-інтеграції.
-- **ESLint-винятки:**
-  - `n/no-process-exit` та `unicorn/no-process-exit` локально відключено через те, що standalone-точка входу зобовʼязана повертати числовий exit-code (інакше CI не побачить статус правила).
-
-## Залежності
-
-### Внутрішні модулі
-
-- `../../scripts/lib/run-rule-cli.mjs` — реекспортує:
-  - `isRunAsCli(metaUrl)` — детектор того, чи виконується модуль як CLI entry-point.
-  - `runRuleCli(dirname)` — повна CLI-обгортка для одного правила.
-- `../../scripts/lib/run-standard-rule.mjs` — реекспортує:
-  - `runStandardRule(dirname, ctx?)` — стандартний пайплайн для "звичайного" правила: `applies` → JS-concerns → policy → mdc-refs.
-  - JSDoc-тип `RuleContext` (використовується лише в анотації параметра `ctx`).
-
-### Сусідні артефакти правила (читаються опосередковано через `runStandardRule` / `runRuleCli`)
-
-- `npm/rules/js-bun-redis/meta.json` — метаінформація правила (id, severity, applies-патерни, посилання на `.mdc` тощо).
-- `npm/rules/js-bun-redis/applies.mjs` — фільтр файлів, до яких застосовується правило.
-- `npm/rules/js-bun-redis/check-*.mjs` — конкретні перевірки JS-concerns.
-- `npm/rules/js-bun-redis/policy.mjs` (за наявності) — policy-шар.
-- Звʼязаний `.mdc` у каталозі `mdc/` — людинозрозумілий опис правила (`mdc-refs`-перевірка переконується, що посилання збігаються).
-
-### Зовнішні залежності
-
-Прямих імпортів npm-пакетів у файлі немає. Усі сторонні залежності (наприклад, `fs`, `path` тощо) приходять транзитивно через `runStandardRule` / `runRuleCli`.
-
-### Глобалі та середовище виконання
-
-- `import.meta.dirname` — абсолютний шлях до теки `npm/rules/js-bun-redis/`. Використовується як ідентифікатор правила (`runStandardRule` із `dirname` зчитує `meta.json` та інші файли поруч).
-- `import.meta.url` — URL поточного модуля. Передається в `isRunAsCli` для детекту режиму запуску.
-- `process.exit(code)` — глобальний Node/Bun API. Використовується **виключно** у standalone-режимі.
-- Підтримка top-level `await` — обовʼязкова; код розрахований на ESM-runtime (Node ≥ 14.8 з ESM або Bun).
-
-## Потік виконання / Використання
-
-### Сценарій 1. Library mode (виклик з оркестратора)
+## Огляд
 
-1. Зовнішній runner (`npx @nitra/cursor fix`) імпортує `run` з цього файлу.
-2. Передає підготовлений `ctx` (зазвичай зі спільним `walkCache`, аби не повторювати обхід файлової системи між правилами).
-3. `run(ctx)` повертає `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule`:
-   - читає `meta.json` поточної теки правила,
-   - виконує `applies` → JS-concerns → policy → mdc-refs (стандартний пайплайн "стандартного" правила),
-   - повертає `0`/`1`.
-5. Runner агрегує exit-коди всіх правил і вирішує загальний статус.
+Файл запускає визначене правило. Приймає контекст прогону, виконує пропуск через `runStandardRule` і повертає результат. Запуск через командний рядок виконує повний еквівалент команди `npx @nitra/cursor fix <id>` і встановлює код виходу процесу на результат `runRuleCli`.
 
-### Сценарій 2. Standalone mode
+## Поведінка
 
-1. Користувач/CI запускає:
-   ```bash
-   bun npm/rules/js-bun-redis/fix.mjs
-   ```
-2. Module-evaluation сягає блоку `if (isRunAsCli(import.meta.url))` — умова `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - завантаження конфігу,
-   - whitelist,
-   - повний CLI-пайплайн (включно з summary),
-   - повертає числовий exit-code.
-4. `process.exit(<code>)` завершує процес із цим кодом — CI/IDE бачить fail (`1`) або success (`0`).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує пропуск через runStandardRule.
+    *   Повертає результат прогону.
+2. Запуск у режимі CLI.
+    *   Виконується при запуску через CLI.
+    *   Виконує повний еквівалент `npx @nitra/cursor fix <id>`.
+    *   Встановлює код виходу процесу на результат runRuleCli.
 
-### Чому два режими в одному файлі
+## Публічний API
 
-Це уніфікована конвенція системи правил `@nitra/cursor`: кожен `fix.mjs` є **і** імпортованим модулем (для оркестрованого прогону), **і** виконуваним скриптом (для локальної відладки конкретного правила). Завдяки `isRunAsCli` обидва шляхи безпечно співіснують: при імпорті side-effect-блок не спрацьовує.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-### Типові команди
+## Гарантії поведінки
 
-- Прогнати лише це правило локально: `bun npm/rules/js-bun-redis/fix.mjs`.
-- Прогнати в межах усього набору правил: `npx @nitra/cursor fix` (runner викличе саме `run(ctx)`).
-- Прогнати з конкретним id через CLI: `npx @nitra/cursor fix js-bun-redis` (виконує по суті те саме, що й standalone-режим цього файлу).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.