@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,148 @@
+# `fix.mjs` — entry-point правила `js-bun-db`
+
+## Огляд
+
+Файл `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`, тощо.
+
+## Залежності
+
+### Внутрішні модулі (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
+
+1. Інтерпретатор виконує верхньорівневі імпорти.
+2. Створюється функція `run` (експорт стає доступним викликачу).
+3. `isRunAsCli(...)` повертає `false` — гілка `if (...)` пропускається.
+4. Модуль готовий: викликач у будь-який момент викликає `run(ctx)`.
+
+### Архітектурні нотатки
+
+- **Чому два режими в одному файлі.** Така подвійна роль (`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`.
+
+## Rebuild Test
+
+З опису вище можна реконструювати поведінку файлу:
+
+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. **Жодної іншої логіки.** Файл не містить ні констант, ні класів, ні допоміжних функцій — лише делегування.

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

@@ -0,0 +1,231 @@
+# `safety.mjs` — перевірка правила `js-bun-db.mdc`
+
+## Огляд
+
+Модуль `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)`
+
+- **Сигнатура:** `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` і за потреби агрегує з іншими правилами.
+
+### Логічний потік `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()
+```
+
+### Як інтерпретувати вивід
+
+- Кожне порушення друкується через `fail(...)` з префіксом `js-bun-db:`, шляхом `<rel>:<line>`, описом і snippet.
+- Кожна чиста категорія дає `pass(...)` — це корисно для логів CI, щоб бачити, що перевірка не «мовчки» пропущена.
+- Exit-код `0` гарантує, що жоден `fail` не був викликаний; `1` — є щонайменше один.
+
+### Сценарії раннього виходу
+
+- Корінь без `package.json` — нічого перевіряти.
+- `package.json` не знайдено взагалі — те саме.
+- Немає файлів для скану (`isBunSqlScanSourceFile` повернув `false` для всіх) — Bun SQL-патерни ніде шукати.
+- У жодному файлі немає `import { sql|SQL } from 'bun'` — у проекті немає Bun SQL, тож перевірки на `new SQL`, `unsafe`, IN-списки тощо нерелевантні. Перевірка `pg`-dependency при цьому виконується завжди (до цього раннього виходу), бо її цінність не залежить від Bun SQL.

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

@@ -60,9 +60,9 @@ await pgWrite.unsafe(sql)
 await pgWrite`
   WITH s(id, date, data) AS (
     SELECT * FROM unnest(
-      ${pgWrite.array(batch.map(r => r.id),   'int4')},
-      ${pgWrite.array(batch.map(r => r.date), 'date')},
-      ${pgWrite.array(batch.map(r => r.data), 'jsonb')}
+      ${pgWrite.array(col(batch, 'id'),   'int4')},
+      ${pgWrite.array(col(batch, 'date'), 'date')},
+      ${pgWrite.array(col(batch, 'data'), 'jsonb')}
     )
   )
   MERGE INTO my_table AS t
@@ -107,7 +107,7 @@ await sql`SELECT * FROM unnest(${sql.array(batch.map(r => JSON.stringify(r.data)
 // ✅ об'єкт/масив передається напряму
 await sql`INSERT INTO events (details) VALUES (${detailsForEvent}::jsonb)`
 
-await sql`SELECT * FROM unnest(${sql.array(batch.map(r => r.data), 'jsonb')})`
+await sql`SELECT * FROM unnest(${sql.array(col(batch, 'data'), 'jsonb')})`
 ```
 
 `UNION ALL`-цикл замість `unnest` підходить для малих динамічних запитів (2–5 рядків), де кожна гілка семантично різна. Для bulk upsert — завжди `unnest`.
@@ -300,18 +300,25 @@ 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** на рівні модуля, а не на кожен запит:
+Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.js` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
 
 ```javascript
-// db.js
+// src/conn/db.js
 import { SQL } from 'bun'
 
-export const sql = new SQL({
+export const pgWrite = new SQL({
   url: process.env.DATABASE_URL,
   max: 20,
   idleTimeout: 30,
   connectionTimeout: 10
 })
+
+export const pgRead = new SQL({
+  url: process.env.PG_CONN_READ ?? process.env.DATABASE_URL,
+  max: 10,
+  idleTimeout: 30,
+  connectionTimeout: 10
+})
 ```
 
 Connection string обирає адаптер автоматично:
@@ -443,6 +450,28 @@ ${pgRead.array(ids, 'int4')}
 | date string   | date           | `'date'`        |
 | ISO datetime  | timestamptz    | `'timestamptz'` |
 
+### `col(arr, key)` — хелпер для unnest-колонок
+
+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` залежно від структури проєкту):
+
+```javascript
+// src/utils/col.js
+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'
+
+// ❌ oxfmt розгортає на 4+ рядки незалежно від printWidth
+${pgWrite.array(rows.map(r => r.id), 'int4')}
+
+// ✅ col(arr, key) — перший аргумент не є callback; oxfmt лишає однорядковим
+${pgWrite.array(col(rows, 'id'), 'int4')}
+```
+
 ### Повний приклад (UNNEST + MERGE)
 
 ```javascript
@@ -450,10 +479,10 @@ await pgWrite`
   MERGE INTO "order".product p
   USING (
     SELECT * FROM unnest(
-      ${pgWrite.array(rows.map(r => r.order_id), 'uuid')},
-      ${pgWrite.array(rows.map(r => r.product_id), 'int4')},
-      ${pgWrite.array(rows.map(r => r.qty), 'numeric')},
-      ${pgWrite.array(rows.map(r => r.is_refund), 'bool')}
+      ${pgWrite.array(col(rows, 'order_id'), 'uuid')},
+      ${pgWrite.array(col(rows, 'product_id'), 'int4')},
+      ${pgWrite.array(col(rows, 'qty'), 'numeric')},
+      ${pgWrite.array(col(rows, 'is_refund'), 'bool')}
     ) AS s(order_id, product_id, qty, is_refund)
   ) AS s ON p.order_id = s.order_id AND p.product_id = s.product_id
   WHEN MATCHED THEN
@@ -582,8 +611,8 @@ ws.connect(url) // allow-pg-leftover: WebSocket, не pg
 ```javascript
 // ❌ нове підключення/інстанс на кожен виклик
 function getUser(id) {
-  const sql = new SQL(process.env.DATABASE_URL)
-  return sql`SELECT * FROM users WHERE id = ${id}`
+  const pgWrite = new SQL(process.env.DATABASE_URL)
+  return pgWrite`SELECT * FROM users WHERE id = ${id}`
 }
 ```