@nitra/cursor 12.8.6 → 12.8.7

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

@@ -5,621 +5,31 @@ alwaysApply: false
 version: '1.15'
 ---
 
-## Підтримувані версії баз даних
+Правило забезпечує безпечне підключення й виконання запитів через Bun native SQL замість `pg` / `pg-format` / `mysql2`, із захистом від SQL injection, pg-leftover та небезпечних патернів `sql.unsafe`.
 
-PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом, підключаємось як `mysql://`).
+[js-bun-db-bun-sql-migration](./js/bun-sql-migration.mdc)
 
-## Заміна на Bun native SQL
+[js-bun-db-pg-format-shim](./js/pg-format-shim.mdc)
 
-Якщо в проєкті використовуються бібліотеки `pg`, `pg-format` або `mysql2`, їх потрібно замінити на Bun native SQL: <https://bun.com/docs/runtime/sql>.
+[js-bun-db-pg-listen-notify](./js/pg-listen-notify.mdc)
 
-- Видалити з `dependencies`: `pg-pool`, `pg-native`, `pg-format`, `mysql`, `mysql2`.
-- Видалити з коду: усі `import` / `require` цих пакетів та власні обгортки над ними.
-- Замінити на `import { sql, SQL } from 'bun'` — Bun має вбудований клієнт із пулом, prepared statements та tagged templates.
+[js-bun-db-pg-format-identifiers](./js/pg-format-identifiers.mdc)
 
-Канон заборонених `dependencies` (`pg-format`, `mysql2`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json). Сам `pg` із денилисту прибрано — він має одне легітимне виключення (LISTEN/NOTIFY), яке зважує AST-сканер; деталі — `## pg: виключення для LISTEN/NOTIFY`.
+[js-bun-db-connection](./js/connection.mdc)
 
-`pg-format` (unscoped) — це ручне форматування SQL через escape (`format('... %L ...', value)`); такі рядки легко поламати неправильним типом, locale-залежним escape або забутим `%L`. Tagged template Bun SQL параметризує значення нативно (`sql\`... ${value} ...\``) і не лишає простору для injection — окремий «форматер» **для значень** не потрібен.
+[js-bun-db-query-safety](./js/query-safety.mdc)
 
-Виключення є **лише** для **динамічних identifiers** (назви схем / таблиць / колонок / індексів / ролей / БД) і whitelist-фрагментів типу `ASC`/`DESC`: Bun SQL їх параметризувати не вміє, тож тут дозволено окремий пакет **`@scaleleap/pg-format`** (scoped форк, не unscoped `pg-format`) — деталі й приклади у `## Динамічна SQL-структура: @scaleleap/pg-format для identifiers`.
+[js-bun-db-sql-array](./js/sql-array.mdc)
 
-## `pg-format`: повне видалення, без шимів
+[js-bun-db-unsafe](./js/unsafe.mdc)
 
-Міграція з `pg-format` — це **зміна стилю запитів**, а не збереження API. У проєкті після переходу на Bun SQL **заборонено** залишати:
+[js-bun-db-pg-leftover](./js/pg-leftover.mdc)
 
-- функцію з іменем `format` (чи `pgFormat`, `sqlFormat`, `pgFmt`), що приймає шаблон з `%L` / `%I` / `%s` і значення;
-- допоміжні `quoteLiteral`, `quoteIdent`, `escapeLiteral`, `escapeIdent` як публічні експорти модуля;
-- обгортки `pgRead.query(text, params)` / `pgWrite.query(text, params)` / `db.query(text, params)`, які складають SQL-рядок (з або без `format`) і викликають `sql.unsafe(text, params)` — це повертає injection-поверхню, від якої ми йдемо, тільки під «зручним» іменем.
+## Швидкий gate через conftest
 
-Замість цього всі точки використання потрібно перевести на tagged template `sql\`...\${value}...\``. Кожне`${value}` стає окремим параметром bind, без рядкового екранування.
+Rego-пакет `js_bun_db.package_json` (файл `policy/package_json/package_json.rego`) перевіряє `dependencies` у `package.json` проти deny-списку [`package.json.deny.json`](./policy/package_json/template/package.json.deny.json):
 
-### Типові ідіоми `pg-format` → Bun SQL
+- `pg-format` → заміни на Bun native SQL — без ручного форматування
+- `mysql2` → заміни на Bun native SQL
 
-| Було (`pg-format`)                                 | Стало (Bun SQL)                                                                                  |
-| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `format('... WHERE id = %L', id)`                  | `sql\`... WHERE id = ${id}\``                                                                    |
-| `format('... IN (%L)', ids)`                       | `sql\`... IN ${sql(ids)}\`` (з guard на пустоту перед запитом)                                   |
-| `format('INSERT ... VALUES %L', [row])` (1 рядок)  | `sql\`INSERT ... VALUES (${a}, ${b}, ...)\``                                                     |
-| `format('INSERT ... VALUES %L', rows)` (N рядків)  | `sql\`INSERT INTO t ${sql(rows, 'a', 'b')}\`` або `unnest($1::T[], $2::T[]) AS t(a, b)`          |
-| `format('MERGE ... USING (VALUES %L) AS d(...)')`  | `sql\`MERGE ... USING (SELECT * FROM unnest(${arrA}::A[], ${arrB}::B[]) AS t(a, b)) AS d\``      |
-| `format('... %I ...', tableName)` (whitelist)      | `@scaleleap/pg-format`: `format('%I', name)` + `sql.unsafe(text, [params])` з маркером           |
-
-Для multi-row `VALUES` у `MERGE` / `INSERT` з конкретними типами — паралельні масиви по колонках і `unnest($1::TYPE[], $2::TYPE[], ...) AS t(col1, col2, ...)`. Кожна колонка передається одним параметром-масивом; типи задаються кастом масиву (`::uuid[]`, `::bigint[]`, `::numeric[]`, `::text[]`, …).
-
-#### Приклад: MERGE з UNNEST і динамічними колонками
-
-```javascript
-// ❌ format + pgWrite.unsafe — N×7 окремих значень, план змінюється при кожному batch.length
-const valuesSql = batch
-  .map(row => format('(%L::int, %L::date, %L::jsonb)', row.id, row.date, JSON.stringify(row.data)))
-  .join(',')
-const sql = format(`MERGE INTO t USING (VALUES %s) AS s(id, date, data) ON ...`, valuesSql)
-await pgWrite.unsafe(sql)
-
-// ✅ UNNEST — 3 параметри незалежно від розміру batch; план стабільний і може кешуватись
-await pgWrite`
-  WITH s(id, date, data) AS (
-    SELECT * FROM unnest(
-      ${pgWrite.array(col(batch, 'id'),   'int4')},
-      ${pgWrite.array(col(batch, 'date'), 'date')},
-      ${pgWrite.array(col(batch, 'data'), 'jsonb')}
-    )
-  )
-  MERGE INTO my_table AS t
-  USING s ON t.id = s.id
-  WHEN MATCHED THEN
-    UPDATE SET date = s.date, data = s.data
-  WHEN NOT MATCHED THEN
-    INSERT (id, date, data) VALUES (s.id, s.date, s.data)
-`
-```
-
-Якщо частина колонок у SET/INSERT залежить від параметра (plan/fact, тип тощо) — динамічні імена колонок не можна параметризувати через `${value}`; використовуй умовні Bun SQL фрагменти:
-
-```javascript
-// ✅ умовні фрагменти для динамічних ідентифікаторів колонок
-const colFrag  = isPlan ? pgWrite`plan_value`  : pgWrite`fact_value`
-const hashFrag = isPlan ? pgWrite`hash = s.hash,` : pgWrite``
-
-await pgWrite`
-  ...
-  WHEN MATCHED THEN
-    UPDATE SET
-      ${colFrag} = s.value,
-      ${hashFrag}
-      updated_by = s.updated_by
-  WHEN NOT MATCHED THEN
-    INSERT (id, ${colFrag}, updated_by)
-    VALUES (s.id, s.value, s.updated_by)
-`
-```
-
-## JSONB-параметри: без `JSON.stringify`
-
-Bun SQL серіалізує JS-об'єкти й масиви у JSON автоматично — викликати `JSON.stringify` перед передачею в `::jsonb` / `::jsonb[]` **заборонено**.
-
-```javascript
-// ❌ зайвий JSON.stringify — подвійна серіалізація або зайвий рядок
-await sql`INSERT INTO events (details) VALUES (${JSON.stringify(detailsForEvent)}::jsonb)`
-
-await sql`SELECT * FROM unnest(${sql.array(batch.map(r => JSON.stringify(r.data)), 'jsonb')})`
-
-// ✅ об'єкт/масив передається напряму
-await sql`INSERT INTO events (details) VALUES (${detailsForEvent}::jsonb)`
-
-await sql`SELECT * FROM unnest(${sql.array(col(batch, 'data'), 'jsonb')})`
-```
-
-`UNION ALL`-цикл замість `unnest` підходить для малих динамічних запитів (2–5 рядків), де кожна гілка семантично різна. Для bulk upsert — завжди `unnest`.
-
-### Заборонений «drop-in» шим
-
-```javascript
-// ❌ pg-format-сумісний шим, що ховає `unsafe` під «безпечним» іменем
-export function format(fmt, ...args) {
-  let i = 0
-  return fmt.replaceAll(/%[LIs]/g, () => quoteLiteral(args[i++]))
-}
-
-// ❌ і його типовий call-site — той самий injection-вектор, що і прямий sql.unsafe із конкатенацією
-await sql.unsafe(format('... WHERE id = %L', userId))
-```
-
-```javascript
-// ❌ pg-сумісна обгортка над Bun SQL — ще один прихований `unsafe`
-export const pgWrite = {
-  query(text, params) {
-    return sql.unsafe(text, params)
-  }
-}
-```
-
-```javascript
-// ✅ напряму tagged template — параметризація через wire-protocol bind
-await sql`... WHERE id = ${userId}`
-```
-
-Виняток для шиму `format()` під час поетапної міграції допускається **тільки** в окремому commit'і з TODO-маркером і дедлайном; готовий код у main з таким шимом — `fail` правила (детектори: `pg-format shim`, `query wrapper over unsafe`).
-
-## `pg`: виключення для LISTEN/NOTIFY
-
-Bun SQL **поки не реалізує PostgreSQL LISTEN/NOTIFY** (асинхронні нотифікації через `pg_notify` / `LISTEN <channel>`). Тому якщо проєкт справді користується LISTEN/NOTIFY, npm-пакет `pg` дозволено тримати в `dependencies` **виключно** для LISTEN/NOTIFY-клієнта. Усі інші запити (SELECT/INSERT/UPDATE/DELETE/migration) — далі через Bun SQL.
-
-Перевірка `pg` зважує цей сигнал автоматично (тому `pg` прибрано з [denylist](./policy/package_json/template/package.json.deny.json) — Rego не бачить JS-коду, тож зважування LISTEN/NOTIFY перенесено в `check-js-bun-db`).
-
-### Як перевірка визначає, що LISTEN/NOTIFY у проєкті є
-
-AST-сканер шукає будь-який із сигналів:
-
-- `client.query('LISTEN <channel>')` / `client.query('UNLISTEN *')` / `client.query('NOTIFY <channel>, ...')` — string- або template-literal-аргумент, що починається з `LISTEN` / `UNLISTEN` / `NOTIFY` (case-insensitive, leading whitespace допускається). Також покриті `queryArray` / `queryStream`.
-- `client.on('notification', handler)` — listener на pg-події `notification`.
-- TaggedTemplateExpression `<tag>\`LISTEN ...\`` — на випадок, якщо хтось загорнув LISTEN у власний tagged template.
-
-Якщо хоч один сигнал є — `dependencies.pg` зважено як виправдане; інакше — `fail` із посиланням на цю секцію.
-
-### Правила для файлів з `import 'pg'`
-
-Кожен файл, який імпортує `'pg'`, повинен **сам** містити один із LISTEN/NOTIFY-сигналів. Сценарій «один файл слухає, інший виконує `SELECT * FROM users`» — теж `fail`: звичайні запити через `pg` треба переписати на Bun SQL, а LISTEN/NOTIFY-логіку лишити в окремому модулі.
-
-### Приклад — окремий модуль для LISTEN
-
-```javascript
-// src/db/pg-listen.ts — єдине місце, де живе import 'pg'
-import { Client } from 'pg'
-
-const listener = new Client({ connectionString: process.env.DATABASE_URL })
-
-// allow-pg-leftover: pg LISTEN-клієнт не керується Bun SQL пулом
-await listener.connect()
-await listener.query('LISTEN orders_channel')
-listener.on('notification', msg => {
-  // обробка нотифікації
-})
-```
-
-```javascript
-// src/db/users.ts — звичайні запити, через Bun SQL
-import { sql } from 'bun'
-
-export const getUser = id => sql`SELECT * FROM users WHERE id = ${id}`
-```
-
-`pg-listen.ts` буде дозволений завдяки `LISTEN orders_channel` і `.on('notification', ...)`; `users.ts` не має імпорту `'pg'`, тож вільно живе з Bun SQL. `client.connect()` у файлі з Bun SQL потребував би маркер `// allow-pg-leftover: ...`; у файлі, де **Bun SQL не імпортовано**, pg-leftover-сканер не спрацьовує (див. `## Прибирати pg-leftover виклики`), але маркер як коментар-причина — корисний для рев'ю.
-
-### Що лишається забороненим
-
-- `import 'pg'` у файлі без LISTEN/NOTIFY — `fail` з повідомленням «перенеси на Bun SQL, лиши LISTEN в окремому модулі».
-- `dependencies.pg` без жодного LISTEN/NOTIFY-сигналу у проєкті — `fail` навіть якщо `pg` нібито «потрібен історично».
-- `pg-format` (unscoped) — лишається у [denylist](./policy/package_json/template/package.json.deny.json); виключення для LISTEN/NOTIFY стосується **тільки** самого `pg`.
-- `pg-pool`, `pg-native`, `mysql`, `mysql2` — виключень немає, видаляти повністю.
-
-## Динамічна SQL-структура: `@scaleleap/pg-format` для identifiers
-
-Bun SQL **не вміє** параметризувати назви схем, таблиць, колонок, індексів, ролей, БД — а `sql\`SELECT * FROM ${table}\`` забіндив би це як значення і зламав би синтаксис. Для **динамічних identifiers** дозволено окремий пакет:
-
-```bash
-bun add @scaleleap/pg-format
-```
-
-⚠️ Це **scoped `@scaleleap/pg-format`**, а не unscoped `pg-format` (той у [deny-списку](./policy/package_json/template/package.json.deny.json)). Беремо форк `@scaleleap` **тільки** заради `%I` / `%s`-можливостей; значення все одно проходять через Bun parameters, **не** через `%L`.
-
-### Дозволений патерн
-
-- **`%I`** — escape SQL identifier (schema / table / column / index / role / database).
-- **`%s`** — raw fragment, **тільки** для whitelist-значень (`ASC` / `DESC`, тип JOIN'у тощо).
-- Значення — позиційні параметри `$1, $2, …`, які передаються другим аргументом у `sql.unsafe(query, [bindParams])`.
-- На рядку виклику `sql.unsafe(...)` обов'язковий маркер `// allow-unsafe: <причина>` (див. `## sql.unsafe(...) за замовчуванням заборонено`).
-
-```javascript
-import format from '@scaleleap/pg-format'
-import { sql } from 'bun'
-
-const allowedColumns = new Set(['created_at', 'email', 'name'])
-if (!allowedColumns.has(sortBy)) throw new Error('Invalid sort column')
-
-const direction = sortDir === 'asc' ? 'ASC' : 'DESC'
-
-const query = format(
-  'SELECT * FROM %I.%I ORDER BY %I %s LIMIT $1',
-  schemaName,
-  tableName,
-  sortBy,
-  direction
-)
-// allow-unsafe: динамічні schema/table/column; значення біндяться через $N
-const rows = await sql.unsafe(query, [limit])
-```
-
-Multi-row `INSERT` через `VALUES %L` теж типовий легітимний кейс, але передавай значення колонок як паралельні масиви через `unnest(...)` Bun SQL — `format('VALUES %L', rows)` лишай тільки коли альтернатива з `unnest` неможлива:
-
-```javascript
-const query = format(
-  /* sql */ `
-    INSERT INTO "order".delivery_status (order_id, status, changed_at)
-    SELECT v.order_id::uuid, v.status, v.changed_at::timestamptz
-    FROM (VALUES %L) AS v(order_id, status, changed_at)
-  `,
-  values
-)
-// allow-unsafe: multi-row VALUES для бекфілу; values формуються з валідованого input
-await sql.unsafe(query)
-```
-
-### Заборонено й після підключення `@scaleleap/pg-format`
-
-- **`%L` для user input** — це повернення `pg-format`-стилю. Завжди bind через Bun (`sql\`... = ${value}\``) або позиційний параметр `$N` + `sql.unsafe(query, [params])`.
-- Збирати весь `WHERE` через `format(...)` з `%L` — користуйся whitelist полів і ручним складанням `$N`-placeholder'ів (приклад нижче).
-- Власні функції `format` / `pgFormat` / `sqlFormat` / `pgFmt` з тілом, що містить `%L` / `%I` / `%s`, — `fail` сканера (це шим, а не імпорт з бібліотеки).
-- Експортовані `quoteLiteral` / `quoteIdent` / `escapeLiteral` / `escapeIdent` — `fail` сканера (pg-format-специфічні API замість Bun parameters).
-
-### Dynamic `WHERE` — без `format(...)`, через whitelist + `$N`
-
-```javascript
-const conditions = []
-const values = []
-
-if (email) {
-  values.push(email)
-  conditions.push(`email = $${values.length}`)
-}
-if (status) {
-  values.push(status)
-  conditions.push(`status = $${values.length}`)
-}
-
-const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''
-const query = `SELECT * FROM users ${where}`
-// allow-unsafe: динамічний WHERE з whitelist-полів; значення біндяться через $N
-const rows = await sql.unsafe(query, values)
-```
-
-### Коротка таблиця рішень
-
-| Сценарій                          | Що використовувати                                   |
-| --------------------------------- | ---------------------------------------------------- |
-| `WHERE id = ${...}`               | Bun SQL tagged template                              |
-| `INSERT` одного рядка             | Bun SQL tagged template                              |
-| `INSERT` масиву (object/colset)   | Bun SQL helper `sql(rows, 'a', 'b')` або `unnest`    |
-| `UPDATE field = ${value}`         | Bun SQL tagged template                              |
-| Динамічна назва schema / table    | `@scaleleap/pg-format` `%I` + `sql.unsafe(q, [...])` |
-| Динамічна назва колонки           | `@scaleleap/pg-format` `%I` + bind                   |
-| Динамічний `ORDER BY column`      | whitelist + `%I`                                     |
-| `ASC` / `DESC`, тип JOIN'у        | whitelist + `%s`                                     |
-| Динамічний `WHERE` (полів багато) | whitelist + ручні `$N` + `sql.unsafe(text, vals)`    |
-| Сирий migration / DDL             | `sql.unsafe(text)` з `// allow-unsafe: <причина>`    |
-| User input як value               | **тільки** Bun parameters / `$N` bind                |
-| Масив значень у `unnest(...)`     | `sql.array(arr, type)` — обов'язково з типом         |
-
-Головне правило:
-
-- **SQL values** → Bun SQL parameters (tagged template `${value}` або `$N` + `sql.unsafe(text, values)`).
-- **SQL identifiers** → `@scaleleap/pg-format` `%I` (schema, table, column, index, role, database).
-- **SQL fragments** (`ASC`/`DESC` тощо) → whitelist + `%s`.
-
-## Підключення (singleton + env)
-
-Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
-
-Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.mjs` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
-
-```javascript
-// src/conn/db.mjs
-import { SQL } from 'bun'
-
-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 обирає адаптер автоматично:
-
-- `postgres://...` / `postgresql://...` → PostgreSQL
-- `mysql://...` / `mysql2://...` → MySQL/MariaDB
-- `sqlite://...` / `file://...` / `:memory:` → SQLite
-
-## Як виконувати запити (безпечно)
-
-Тільки **tagged template** з `${...}` — Bun сам біндить позиційні параметри й захищає від SQL injection:
-
-```javascript
-import { sql } from 'bun'
-
-const userId = 42
-const status = 'active'
-
-const users = await sql`
-  SELECT * FROM users
-  WHERE id = ${userId} AND status = ${status}
-`
-```
-
-Об'єктний INSERT/UPDATE та `IN (...)` — через helper `sql(...)`:
-
-```javascript
-const user = { name: 'Alice', email: 'a@example.com' }
-
-const [created] = await sql`
-  INSERT INTO users ${sql(user)}
-  RETURNING *
-`
-
-await sql`UPDATE users SET ${sql(user, 'name', 'email')} WHERE id = ${created.id}`
-
-const ids = [1, 2, 3]
-await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
-```
-
-Multi-row INSERT з масиву об'єктів — `sql(rows)` генерує column list і VALUES автоматично:
-
-```javascript
-// ❌ format + pgWrite.unsafe — ручне склеювання рядків, injection-вектор
-const insertWfQry = `insert into approval.workflow (request_id, job_title_id, name, status)
-  values ${approverJobs.map(job => `('${request.id}', ${job.id}, '${job.short_name}', 'pending')`).join(', ')}`
-await pgWrite.unsafe(insertWfQry)
-
-// ✅ sql(rows) — один параметр-масив, bind через wire-protocol
-const wfRows = approverJobs.map(job => ({
-  request_id: request.id,
-  job_title_id: job.id,
-  name: job.short_name,
-  status: job.id === nextJobId ? 'current' : 'pending'
-}))
-await sql`INSERT INTO approval.workflow ${sql(wfRows)}`
-```
-
-Коли потрібен стабільний план для великих batch'ів (N > 20) або строгі типи колонок — використовуй `unnest` (деталі у `#### Приклад: MERGE з UNNEST і динамічними колонками`). Для невеликих INSERT'ів де колонки відомі — `sql(rows)` коротший і зрозуміліший.
-
-## `IN (...)`: значення з template literal — тільки через змінну + guard на пустоту
-
-Якщо список для `IN (...)` підставляється через `${...}` у template literal, його **потрібно**:
-
-- винести в **окрему змінну** (не підставляти вираз напряму в `${...}`);
-- **перевірити на пустоту** перед запитом і **throw** (щоб не виконувати некоректний SQL або запит з неочікуваною семантикою).
-
-Приклад:
-
-```javascript
-const ids = inputIds.map(Number).filter(n => Number.isFinite(n))
-if (!ids.length) throw new Error('ids is empty')
-
-await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
-```
-
-Транзакції — через `sql.begin` (auto-commit/rollback), вкладені — через `tx.savepoint`:
-
-```javascript
-await sql.begin(async tx => {
-  await tx`INSERT INTO users ${sql(user)}`
-  await tx`UPDATE accounts SET balance = balance - ${100} WHERE user_id = ${user.id}`
-})
-```
-
-## `sql.array(arr, type)` для передачі масивів
-
-Коли JS-масив передається як параметр у Bun SQL template literal всередині `unnest(...)` або іншого контексту, де PostgreSQL очікує типізований масив (`int4[]`, `uuid[]` тощо), — обов'язково використовувати `sql.array(arr, type)` (або `pgWrite.array` / `pgRead.array` — вони є екземплярами `SQL`). Другий аргумент (тип елементів) — обов'язковий.
-
-### Заборонені патерни
-
-```javascript
-// ❌ пряма підстановка масиву — Bun серіалізує як рядок, не як pg-масив
-${ids}
-
-// ❌ cast-синтаксис без .array() — працює в деяких версіях, але не гарантований
-${ids}::int8[]
-
-// ❌ відсутній тип — Bun не може вивести тип pg, можливий mismatch
-sql.array(ids)
-```
-
-### Дозволені патерни
-
-```javascript
-// ✅ pgWrite.array з явним типом
-${pgWrite.array(ids, 'int8')}
-${pgWrite.array(uuids, 'uuid')}
-${pgWrite.array(flags, 'bool')}
-${pgWrite.array(amounts, 'numeric')}
-${pgWrite.array(names, 'text')}
-${pgWrite.array(dates, 'date')}
-${pgWrite.array(timestamps, 'timestamptz')}
-
-// ✅ pgRead.array — те саме правило
-${pgRead.array(ids, 'int4')}
-```
-
-### Таблиця типів
-
-| JS-тип        | PostgreSQL тип | Аргумент        |
-| ------------- | -------------- | --------------- |
-| number (int)  | int4           | `'int4'`        |
-| bigint / id   | int8           | `'int8'`        |
-| UUID string   | uuid           | `'uuid'`        |
-| boolean       | bool           | `'bool'`        |
-| decimal/float | numeric        | `'numeric'`     |
-| string        | text           | `'text'`        |
-| 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.mjs` (або `src/conn/col.mjs` залежно від структури проєкту):
-
-```javascript
-// src/utils/col.mjs
-export const col = (arr, key) => arr.map(r => r[key])
-```
-
-```javascript
-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')}
-
-// ✅ col(arr, key) — перший аргумент не є callback; oxfmt лишає однорядковим
-${pgWrite.array(col(rows, 'id'), 'int4')}
-```
-
-### Повний приклад (UNNEST + MERGE)
-
-```javascript
-await pgWrite`
-  MERGE INTO "order".product p
-  USING (
-    SELECT * FROM unnest(
-      ${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
-    UPDATE SET qty = s.qty
-  WHEN NOT MATCHED THEN
-    INSERT (order_id, product_id, qty, is_refund)
-    VALUES (s.order_id, s.product_id, s.qty, s.is_refund)
-`
-```
-
-## Коментар під час виправлення SQL injection
-
-Коли виправляєш місце з потенційним **SQL injection** (наприклад, заміна конкатенації/`.join(',')` на `sql(ids)` або перехід з `sql.unsafe(...)` на tagged template), **додай поруч короткий коментар** з описом причини.
-
-Вимоги до коментаря:
-
-- пояснити **що саме було небезпечно** (конкатенація, підмішування user input, динамічний `IN (...)`, тощо);
-- пояснити **чому новий варіант безпечний** (параметризація через tagged template / `sql(...)`);
-- без “романів”: 1–2 рядки, достатньо для ревʼю.
-
-Приклад:
-
-```javascript
-// SQLi fix: не конкатенуємо значення в `IN (...)`; Bun parameterize через `sql(ids)`.
-await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
-```
-
-## `sql.unsafe(...)` за замовчуванням заборонено
-
-Будь-який виклик `sql.unsafe(...)` (так само `tx.unsafe(...)` всередині `sql.begin`) **заборонено**, окрім випадків, коли **обидві** умови виконані:
-
-1. значення підставляється з **коду** — константа, конфіг, whitelist; **не з user input**;
-2. треба підставити те, що **не можна параметризувати** через tagged template:
-   - назву **таблиці**,
-   - назву **колонки**,
-   - **dynamic SQL / DDL** (`CREATE`, `ALTER`, `DROP`, multi-statement migration, серверні `SET`/`SHOW` і подібне).
-
-В усіх інших випадках — переробити на звичайний tagged template `sql\`...\${value}...\``: значення біндяться як параметри й injection не лишається.
-
-Кожен легітимний `sql.unsafe(...)` має супроводжуватись **маркером-коментарем** з причиною — на тому ж рядку (trailing) або на рядку безпосередньо перед викликом. Маркер — opt-in для перевірки `js-bun-db` і слід для ревʼюера:
-
-```javascript
-import format from '@scaleleap/pg-format'
-
-const query = format('CREATE TABLE %I (id int)', tableName)
-// allow-unsafe: DDL — назву таблиці параметризувати не можна; ідентифікатор екранує pg-format
-await sql.unsafe(query)
-
-await sql.unsafe('SELECT pg_advisory_lock($1)', [lockId]) // allow-unsafe: pg_advisory_lock — окремий шлях, без tagged template
-```
-
-Формат маркера: `allow-unsafe: <непорожня причина>` у line- або block-коментарі. Без причини (`// allow-unsafe:`) і без маркера взагалі — **fail** перевірки.
-
-### `sql.unsafe` з template-літералом і `${...}`-інтерполяцією — заборонено навіть з маркером
-
-`sql.unsafe(\`...\${x}...\`)` — окремий **hard fail**, який не знімається маркером `// allow-unsafe`. Шаблонна підстановка`${x}` у `sql.unsafe`-рядок:
-
-- **не екранує** identifier'ів (reserved words, спецсимволи, пробіли в імені);
-- **не біндить** значень (вони потрапляють у запит сирим текстом, як injection-вектор);
-- виглядає «безпечно» через знайому tagged-template-форму, але не має жодних гарантій Bun SQL.
-
-Канон — побудувати `text` окремо, потім передати в `sql.unsafe(text, [params])`:
-
-- для **identifiers** — `@scaleleap/pg-format` `format('%I', name)` (екранує спецсимволи, reserved words);
-- для **values** — позиційні `$1`, `$2`, … як placeholder'и в тексті + масив значень другим аргументом;
-- для **fragments** з whitelist (`ASC`/`DESC`) — `format('%s', whitelistedValue)`.
-
-```javascript
-// ❌ template-літерал з ${...} — fail навіть з allow-unsafe
-// allow-unsafe: DDL
-await sql.unsafe(`CREATE TABLE ${tableName} (id int)`)
-
-// ✅ format('%I', ...) екранує identifier, sql.unsafe приймає готовий text
-import format from '@scaleleap/pg-format'
-const query = format('CREATE TABLE %I (id int)', tableName)
-// allow-unsafe: DDL — назву таблиці параметризувати не можна
-await sql.unsafe(query)
-```
-
-Статичні `sql.unsafe(\`SELECT 1\`)` (без `${...}`) і`sql.unsafe(text, [params])` зі змінною `text`, зібраною заздалегідь, — допустимі (за наявності`// allow-unsafe`-маркера).
-
-❌ Заборонені кейси (треба переробити на tagged template):
-
-```javascript
-// ❌ дані від користувача — параметризуй через tagged template
-await sql.unsafe(`SELECT * FROM users WHERE id = ${userId}`)
-
-// ❌ навіть у tagged template — динамічний список через .join(',')
-await sql`SELECT * FROM users WHERE id IN (${ids.join(',')})`
-```
-
-Для динамічних списків — `sql([...])` або `sql(rows, 'colA', 'colB')`, **не** `.join(',')`.
-
-## Прибирати pg-leftover виклики (`.connect()`, `.end()`)
-
-У файлах з Bun SQL (`import { sql, SQL } from 'bun'`) залишки від `pg` — `pool.connect()`, `client.end()`, `pool.end()` — мають бути видалені. Bun SQL пулом керує сам: на першому запиті підключається, idle/lifetime закриває за конфігом — окремий життєвий цикл вручну не потрібен.
-
-```javascript
-// ❌ pg-leftover: ручний lifecycle, який Bun SQL робить за тебе
-const client = await pool.connect()
-try {
-  await client.query('...')
-} finally {
-  await client.end()
-}
-
-// ✅ Bun SQL — без явних .connect()/.end()
-await sql`...`
-```
-
-Якщо виклик дійсно потрібен (наприклад, `sql.end()` у graceful shutdown або `.connect()` на сторонньому об'єкті, що випадково ділить імʼя методу), додай маркер `// allow-pg-leftover: <причина>` на тому ж рядку (trailing) або на рядку безпосередньо перед викликом:
-
-```javascript
-// allow-pg-leftover: graceful shutdown — закриваємо пул перед exit
-await sql.end()
-
-ws.connect(url) // allow-pg-leftover: WebSocket, не pg
-```
-
-Формат маркера: `allow-pg-leftover: <непорожня причина>` у line- або block-коментарі. Без маркера й без причини — **fail** перевірки.
-
-## Що НЕ робити
-
-### Не створювати підключення на кожен запит
-
-```javascript
-// ❌ нове підключення/інстанс на кожен виклик
-function getUser(id) {
-  const pgWrite = new SQL(process.env.DATABASE_URL)
-  return pgWrite`SELECT * FROM users WHERE id = ${id}`
-}
-```
-
-`new SQL(...)` має створюватись **один раз** на рівні модуля. Bun сам тримає пул (`max`, `idleTimeout`, `maxLifetime`) — окремих `Pool`/`Client` як у `pg` не потрібно.
-
-### Не лишати `pg` / `pg-format` / `mysql2` поряд із Bun SQL
-
-Якщо в коді з'явився `import { sql } from 'bun'`, то `pg`, `pg-format` та `mysql2` мають бути прибрані і з `dependencies`, і з імпортів — щоб не лишалось двох паралельних шляхів до БД та ручного форматування поряд із параметризованими template literal.
-
-Те саме стосується **локальних шимів**: будь-який модуль, що експортує `format`, `pgRead`, `pgWrite`, `query(text, params)`, `quoteLiteral`, `quoteIdent` як обгортку над `sql.unsafe(...)`, потрібно переписати — всі call-site на tagged template, сам шим видалити (див. `## pg-format: повне видалення, без шимів`).
+AST-скан коду (`new SQL(...)` у функціях, `unsafe()` без маркера, pg-leftover, динамічні `IN (…)` через `.join(',')`) лишається у JS-перевірці (`js/safety.mjs`). Виключення `pg` для LISTEN/NOTIFY зважується у JS (Rego не бачить JS-коду).