@nitra/cursor 1.13.52 → 1.13.57

package/CHANGELOG.md

@@ -4,6 +4,36 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.57] - 2026-05-19
+
+### Changed
+
+- `check js-bun-db`: новий **hard fail** на `sql.unsafe(template_literal_with_interpolation)` — будь-який виклик з template-літералом, що містить `${...}`-інтерполяцію, тепер падає **навіть з маркером** `// allow-unsafe`. Причина: шаблонна підстановка `${name}` у `sql.unsafe`-рядок не екранує identifier'ів (reserved words, спецсимволи, пробіли в імені) і не біндить значень; такий код виглядає звично через знайому tagged-template-форму, але насправді робить просту строкову конкатенацію без жодних гарантій. Канон — зібрати `text` окремо: identifiers через `@scaleleap/pg-format` `format('%I', name)`, values як позиційні `$N` + другий аргумент `sql.unsafe(text, [params])`. Раніше дозволений приклад `sql.unsafe(\\\`CREATE TABLE \\\${TABLE} (id int)\\\`)` з marker'ом тепер fail — переписати через `format('CREATE TABLE %I (id int)', TABLE)`. Не зачепило: `sql.unsafe('SELECT 1')` (статичний рядок), `sql.unsafe(\\\`SELECT 1\\\`)` (template без інтерполяції), `sql.unsafe(text, [params])` зі змінною `text`. Зачеплено: [bun-sql-scan.mjs](scripts/utils/bun-sql-scan.mjs) (новий експорт `findBunSqlUnsafeWithInterpolatedTemplateInText`, що флагає лише `<obj>.unsafe(TemplateLiteral)` з `expressions.length > 0`), [check.mjs](rules/js-bun-db/fix/safety/check.mjs) (новий лічильник `unsafeTemplateInterp` + окреме повідомлення з порадою на `@scaleleap/pg-format`), [check.test.mjs](rules/js-bun-db/fix/safety/check.test.mjs) (попередній DDL-тест переписано на безпечний `format('%I', ...)`-варіант, додано **негативний** тест на template-interp + marker і **позитивний** тест на статичний template без інтерполяції), [js-bun-db.mdc](rules/js-bun-db/js-bun-db.mdc) (нова підсекція «sql.unsafe з template-літералом і ${...}-інтерполяцією — заборонено навіть з маркером» зі зразками поганого/гарного коду; основний приклад DDL у секції unsafe-allowlist переписано на `format` + готовий `text`). Bump `js-bun-db.mdc` `1.10` → `1.11`.
+
+## [1.13.56] - 2026-05-19
+
+### Changed
+
+- `check js-bun-db`: пакет **`pg`** більше не повністю заборонений — додано виключення для **PostgreSQL LISTEN/NOTIFY**, який Bun SQL поки не реалізує. Причина: dev-теми з notifications (черги нотифікацій, інвалідація кешу через `pg_notify`, бот-консьюмери на каналі) досі мають законну потребу у клієнті `pg`, а попереднє правило flat-out забороняло це навіть у файлах, що буквально нічого не роблять, окрім виклику `client.query` з рядком `LISTEN ...` плюс listener `client.on` на події `notification`. Тепер `dependencies.pg` дозволено, **якщо** AST-сканер знаходить у проєкті хоч один сигнал LISTEN/NOTIFY: метод `query` / `queryArray` / `queryStream` зі string- або template-літералом, що починається з `LISTEN`, `UNLISTEN` або `NOTIFY` (case-insensitive), або метод `on` із першим аргументом-рядком `notification`, або tagged template з тегом `sql` і першим quasi, що починається з тих самих ключових слів. Якщо жодного — `fail` з посиланням на нову секцію .mdc. Додатково — **per-file**: будь-який файл з `import 'pg'` (або `require('pg')`) повинен сам містити LISTEN/NOTIFY; звичайні `SELECT`/`INSERT`/`UPDATE` через `pg` лишаються забороненими (переписати на Bun SQL і лишити LISTEN/NOTIFY в окремому модулі). Заборона `pg-format` і `mysql2` не змінилася. Зачеплено: [bun-sql-scan.mjs](scripts/utils/bun-sql-scan.mjs) (нові експорти `textHasPgLibImport`, `findPgLibImportInText`, `findPgListenNotifyUsageInText` + AST-хелпери для розпізнавання pg-style LISTEN/NOTIFY-запитів і `notification`-listener'ів), [check.mjs](rules/js-bun-db/fix/safety/check.mjs) (нова функція `checkPgDependencyAndUsage`, що пробігає по всіх `package.json` і per-file pg-imports; перевірку `pg` повністю переведено з Rego в JS, бо Rego не бачить JS-коду), [package.json.deny.json](rules/js-bun-db/policy/package_json/template/package.json.deny.json) (прибрано `pg`, лишилися `pg-format`/`mysql2`), [package_json_test.rego](rules/js-bun-db/policy/package_json/package_json_test.rego) (`test_deny_pg` → `test_allow_pg_in_dependencies` + новий `test_deny_pg_format`), [check.test.mjs](rules/js-bun-db/fix/safety/check.test.mjs) (5 нових сценаріїв: успіх з LISTEN, успіх з notification-listener, помилка `pg` без LISTEN/NOTIFY, помилка змішаних файлів — один із LISTEN, інший зі звичайними запитами, успіх з `NOTIFY` як виправдання). `.mdc` отримало нову секцію «pg: виключення для LISTEN/NOTIFY» з прикладом окремого `pg-listen.ts`-модуля і явним переліком сигналів, які зважує сканер. Bump `js-bun-db.mdc` `1.9` → `1.10`.
+
+## [1.13.55] - 2026-05-19
+
+### Changed
+
+- `check js-bun-db`: правило [js-bun-db.mdc](rules/js-bun-db/js-bun-db.mdc) **пом'якшено** для випадків, де Bun SQL принципово не може допомогти — **динамічних SQL identifiers** (назви schema/table/column/index/role/database) і whitelist-фрагментів типу `ASC`/`DESC`. Раніше для них рекомендувалось будувати рядок шаблонною підстановкою у `sql.unsafe`, але інтерполяція identifier'у в template literal не робить escape (reserved words, спецсимволи) — це слабкий захист. Тепер канон — окремий пакет **`@scaleleap/pg-format`** (scoped форк, не unscoped `pg-format`): виклик типу `format('SELECT * FROM %I', name)` повертає коректно екранований PostgreSQL identifier, далі рядок іде у `sql.unsafe(query, [bindParams])` з обов'язковим маркером `// allow-unsafe: <причина>`. Значення (user input, фільтри, INSERT/UPDATE) — **завжди** через Bun parameters (tagged template або `$N` + `sql.unsafe(text, values)`); `%L` для значень лишається забороненим, як і власні шими `format`/`pgFormat`/`quoteIdent` тощо. Unscoped `pg-format` лишається у [deny-списку](rules/js-bun-db/policy/package_json/template/package.json.deny.json) — виключення стосується **тільки** scoped `@scaleleap/pg-format`. Зачеплено: вступ секції «Заміна на Bun native SQL» (зафіксовано виключення), рядок таблиці ідіом для `%I` (тепер через `@scaleleap/pg-format`, не через `sql.unsafe` з шаблонним рядком), нова секція «Динамічна SQL-структура: @scaleleap/pg-format для identifiers» з прикладами (динамічний `ORDER BY` зі whitelist, multi-row `INSERT` через `VALUES %L`, dynamic `WHERE` через ручні `$N`) і коротка таблиця рішень. AST-сканер [bun-sql-scan.mjs](scripts/utils/bun-sql-scan.mjs) не зачеплений — він знаходить лише **визначення** функцій-шимів (`format` з `%L`/`%I`/`%s` у тілі), а імпорт `format` із `@scaleleap/pg-format` як зовнішня бібліотека не флагається. Bump `js-bun-db.mdc` `1.8` → `1.9`.
+
+## [1.13.54] - 2026-05-19
+
+### Changed
+
+- `check k8s` / `lint-k8s`: правила під `npm/rules/k8s/` спрощено — за каноном `k8s.mdc` тримаємо лише `.yaml`, тож **rego-цілі** і **rego-вирази** очищено від `.yml`. Зачеплено: глоби `walkGlob` у `npm/rules/k8s/policy/{manifest,base_manifest,gateway,hpa_pdb}/target.json` — лише `**/*.yaml`; у [base_kustomization.rego](rules/k8s/policy/base_kustomization/base_kustomization.rego) `is_hpa_or_pdb_filename` більше не містить `hpa.yml` / `pdb.yml`; тест `test_deny_hpa_yml_in_subdir` → `test_deny_hpa_yaml_in_subdir`. **Safety-net** у [check.mjs](rules/k8s/fix/manifests/check.mjs) **збережено**: `findK8sYamlFiles` та `checkK8sYamlFile` все ще пропускають `.yml` далі, але одразу падають з повідомленням `розширення .yml — перейменуй на .yaml (див. k8s.mdc)` — щоб випадково створений `*.yml` під `k8s/` не залишився непоміченим (автоматичне перейменування — окрема ручна команда `npx @nitra/cursor rename-yaml-extensions`, яка з `check k8s` не викликається). Згадки про `.github/workflows/*.yml` у JSDoc лишилися (це чуже правило `ga.mdc`, де канон — `.yml`). Bump `k8s.mdc` `1.40` → `1.41`.
+
+## [1.13.53] - 2026-05-19
+
+### Changed
+
+- `check k8s`: **NetworkPolicy переїхав з `components/` у `base/`**. Раніше канон вимагав `…/k8s/<pkg>/components/networkpolicy.yaml` (Kustomize Component, sibling до `base/`), а локальний `networkpolicy.yaml` у base був забороненим (file-existence error) — через що **dev-середовище** (рендер лише з base без overlay → без components) **не отримувало жодних мережевих обмежень** і pod'и були відкриті для будь-якого трафіку. Тепер NP лежить у `base/networkpolicy.yaml` поруч з workload-маніфестом і підключений через `base/kustomization.yaml` `resources:` — обмеження діють і на dev, і на всіх overlays через звичайний `resources: [- ../base]`. Канон `components/`: лише `hpa.yaml` + `pdb.yaml` (HPA/PDB лишаються env-залежними й підключаються тільки прод-overlays). У не-base overlays `networkpolicy.yaml` поруч з workload — опційний overlay-specific override. Зачеплено: [npm/rules/k8s/k8s.mdc](rules/k8s/k8s.mdc) (нова секція «NetworkPolicy у `base/`», оновлені приклади `components/kustomization.yaml` без NP і новий приклад `base/networkpolicy.yaml`), [npm/rules/k8s/fix/manifests/check.mjs](rules/k8s/fix/manifests/check.mjs) (видалено `failIfBaseLayerHasLocalNetworkPolicy` і `validateComponentsNetworkPolicyFile`; `validateNetworkPoliciesForK8sWorkloads` і `ensureNetworkPoliciesForWorkloadsInDir` тепер завжди шукають `networkpolicy.yaml` у `dir`, autofix додає його у `base/kustomization.yaml` `resources:`; `validateComponentsKustomizationManifest` більше не вимагає NP у resources), [npm/rules/k8s/policy/base_kustomization/base_kustomization.rego](rules/k8s/policy/base_kustomization/base_kustomization.rego) (deny прибирає `networkpolicy.yaml` зі списку заборонених у base resources — лишаються тільки HPA/PDB), [npm/rules/k8s/lint/lint.mjs](rules/k8s/lint/lint.mjs) (оновлено JSDoc про C-0260: NP тепер у base і kustomize-збірка нормалізує namespace природньо). Bump `k8s.mdc` `1.39` → `1.40`.
+
 ## [1.13.52] - 2026-05-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.52",
+  "version": "1.13.57",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/image-avif/fix/avif_generation/check.mjs

@@ -413,9 +413,7 @@ export async function check() {
   const ignorePaths = await loadCursorIgnorePaths(process.cwd())
 
   if (!(await hasAnyVueRasterReference(ignorePaths))) {
-    pass(
-      'image-avif: у .vue/.html немає raster-посилань для переписування — AVIF-генерація і cleanup пропущені'
-    )
+    pass('image-avif: у .vue/.html немає raster-посилань для переписування — AVIF-генерація і cleanup пропущені')
     return reporter.getExitCode()
   }
 

package/rules/js-bun-db/fix/safety/check.mjs

@@ -2,12 +2,20 @@
  * Перевіряє правило js-bun-db.mdc.
  *
  * 1) У жодному `package.json` (включно з workspace-пакетами) у `dependencies` не повинно
- *    бути `pg`, `pg-format` чи `mysql2` — ці бібліотеки треба замінити на Bun native SQL
- *    (`import { sql, SQL } from 'bun'`, https://bun.com/docs/runtime/sql).
- *    `pg-format` — ручне форматування SQL через escape; tagged template Bun SQL
- *    параметризує значення нативно і не лишає простору для injection.
+ *    бути `pg-format` чи `mysql2` — їх треба замінити на Bun native SQL
+ *    (`import { sql, SQL } from 'bun'`, https://bun.com/docs/runtime/sql). `pg-format` —
+ *    ручне форматування SQL через escape; tagged template Bun SQL параметризує значення
+ *    нативно і не лишає простору для injection. Перевірка цих двох — у Rego-полісі
+ *    `npm/policy/js_bun_db/package_json/`.
  *
- * 2) Якщо в коді використовується Bun SQL (імпорт `sql`/`SQL` з `'bun'`), додатково
+ * 2) Для `pg` діє виключення: Bun SQL поки не реалізує LISTEN/NOTIFY, тож якщо у
+ *    проекті знайдено реальне використання `LISTEN ...` / `NOTIFY ...` / `UNLISTEN ...`
+ *    або listener'а `.on('notification', ...)`, dependency `pg` дозволено. Інакше
+ *    `pg` лишається забороненим — fail з підказкою про виключення. Додатково — per-file:
+ *    кожен файл з `import ... from 'pg'` повинен сам містити LISTEN/NOTIFY-патерн;
+ *    звичайні SELECT/INSERT/UPDATE через `pg` (replace на Bun SQL!) не дозволені.
+ *
+ * 3) Якщо в коді використовується Bun SQL (імпорт `sql`/`SQL` з `'bun'`), додатково
  *    перевіряє небезпечні патерни:
  *    - `new SQL(...)` всередині функції (пул має бути singleton на рівні модуля).
  *    - Будь-який `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
@@ -30,12 +38,16 @@ import {
   findBunSqlPerRequestConnectionInText,
   findBunSqlPgLeftoverCallInText,
   findBunSqlUnsafeUseWithoutAllowMarkerInText,
+  findBunSqlUnsafeWithInterpolatedTemplateInText,
   findPgFormatLikeQueryWrapperInText,
   findPgFormatShimDefinitionInText,
+  findPgLibImportInText,
+  findPgListenNotifyUsageInText,
   findUnsafeBunSqlDynamicSqlListInText,
   findUnsafeBunSqlInListMissingEmptyGuardInText,
   isBunSqlScanSourceFile,
-  textHasBunSqlImport
+  textHasBunSqlImport,
+  textHasPgLibImport
 } from '../../../../scripts/utils/bun-sql-scan.mjs'
 import { findAllPackageJsonPaths } from '../../../../scripts/utils/find-package-json-paths.mjs'
 import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-config.mjs'
@@ -65,19 +77,32 @@ async function findAllSourcePathsForBunSqlScan(repoRoot, ignorePaths) {
 }
 
 /**
- * Сканує JS/TS-джерела на небезпечні патерни Bun SQL.
+ * Сканує JS/TS-джерела на небезпечні патерни Bun SQL і збирає метадані про
+ * використання `pg`/LISTEN-NOTIFY (для виключення dependency `pg`).
  * @param {string[]} sourcePaths абсолютні шляхи джерел
  * @param {string} repoRoot абсолютний шлях до кореня
  * @param {{ pass: (m: string) => void, fail: (m: string) => void }} reporter колбеки pass і fail з перевірки
- * @returns {Promise<{ hasBunSqlImport: boolean, perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number }>}
- *   `hasBunSqlImport` — чи знайдено хоч один `import { sql|SQL } from 'bun'` у джерелах;
- *   решта — кількість порушень кожного типу.
+ * @returns {Promise<{
+ *   hasBunSqlImport: boolean,
+ *   perRequest: number,
+ *   unsafeCall: number,
+ *   dynamicList: number,
+ *   inListGuard: number,
+ *   pgLeftover: number,
+ *   pgFormatShim: number,
+ *   queryWrapper: number,
+ *   pgUsage: { rel: string, imports: { line: number, snippet: string }[], listenNotify: { line: number, snippet: string, kind: string }[] }[]
+ * }>}
+ *   `hasBunSqlImport` — чи є хоч один `import { sql|SQL } from 'bun'`;
+ *   `pgUsage` — список файлів, що або імпортують `'pg'`, або містять LISTEN/NOTIFY-патерн
+ *   (інші — пропущено, щоб не тримати в пам'яті метадані про всі файли).
  */
 async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
   const { fail } = reporter
   const counts = {
     perRequest: 0,
     unsafeCall: 0,
+    unsafeTemplateInterp: 0,
     dynamicList: 0,
     inListGuard: 0,
     pgLeftover: 0,
@@ -85,6 +110,8 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
     queryWrapper: 0
   }
   let hasBunSqlImport = false
+  /** @type {{ rel: string, imports: { line: number, snippet: string }[], listenNotify: { line: number, snippet: string, kind: string }[] }[]} */
+  const pgUsage = []
 
   for (const absPath of sourcePaths) {
     const rel = relative(repoRoot, absPath).split('\\').join('/')
@@ -93,9 +120,30 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
       hasBunSqlImport = true
     }
     scanFileForBunSqlPatterns(content, rel, fail, counts)
+    collectPgUsageForFile(content, rel, pgUsage)
   }
 
-  return { hasBunSqlImport, ...counts }
+  return { hasBunSqlImport, pgUsage, ...counts }
+}
+
+/**
+ * Якщо у файлі є імпорт `'pg'` АБО LISTEN/NOTIFY-патерн — додає запис у `pgUsage`.
+ * Файли без жодного сигналу не зберігаються, щоб уникнути зайвої пам'яті.
+ * @param {string} content вміст файлу
+ * @param {string} rel posix-шлях відносно кореня
+ * @param {{ rel: string, imports: { line: number, snippet: string }[], listenNotify: { line: number, snippet: string, kind: string }[] }[]} pgUsage акумулятор
+ * @returns {void}
+ */
+function collectPgUsageForFile(content, rel, pgUsage) {
+  // Дешевий pre-filter за текстом: AST-парсинг тільки коли файл містить
+  // або імпорт `'pg'`, або хоча б одне зі слів LISTEN / NOTIFY / UNLISTEN /
+  // 'notification' — інакше LISTEN/NOTIFY у ньому точно немає.
+  const mayHaveListenNotify = /\b(LISTEN|UNLISTEN|NOTIFY)\b/iu.test(content) || /['"`]notification['"`]/u.test(content)
+  if (!textHasPgLibImport(content) && !mayHaveListenNotify) return
+  const imports = findPgLibImportInText(content, rel)
+  const listenNotify = findPgListenNotifyUsageInText(content, rel)
+  if (imports.length === 0 && listenNotify.length === 0) return
+  pgUsage.push({ rel, imports, listenNotify })
 }
 
 /**
@@ -124,6 +172,16 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
         `(js-bun-db.mdc): ${v.snippet}`
     )
   }
+  for (const v of findBunSqlUnsafeWithInterpolatedTemplateInText(content, rel)) {
+    counts.unsafeTemplateInterp++
+    fail(
+      `js-bun-db: ${rel}:${v.line} — sql.unsafe(\`...\${x}...\`) з template-літералом і \${...}-інтерполяцією ` +
+        `заборонено навіть з allow-unsafe маркером: шаблонна підстановка identifier'у не екранує (reserved words, ` +
+        `спецсимволи), а значення не біндяться. Збери text через @scaleleap/pg-format format('%I', name) для ` +
+        `identifiers або позиційні $N для values, потім sql.unsafe(text, [params]). Деталі — секція ` +
+        `«Динамічна SQL-структура» в js-bun-db.mdc: ${v.snippet}`
+    )
+  }
   for (const v of findBunSqlPgLeftoverCallInText(content, rel)) {
     counts.pgLeftover++
     fail(
@@ -170,6 +228,71 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
   }
 }
 
+/**
+ * Перевіряє виключення `pg` для LISTEN/NOTIFY: по кожному `package.json` з
+ * `dependencies.pg` — чи є у проекті хоч одне використання LISTEN/NOTIFY-патерну;
+ * додатково — кожен файл з `import 'pg'` повинен сам містити LISTEN/NOTIFY (інакше
+ * звичайні SELECT/INSERT/UPDATE через `pg` ховаються за легітимним dependency).
+ * @param {string[]} pkgJsonPaths абсолютні шляхи до всіх package.json
+ * @param {string} repoRoot абсолютний шлях до кореня
+ * @param {{ rel: string, imports: { line: number, snippet: string }[], listenNotify: { line: number, snippet: string, kind: string }[] }[]} pgUsage метадані з scanSourcesForBunSqlPatterns
+ * @param {{ fail: (m: string) => void }} reporter колбек fail для повідомлень
+ * @returns {Promise<{ pgDepFails: number, pgImportFails: number, pgDepsFound: number, hasAnyListenNotify: boolean, listenNotifyEvidence: string | null }>}
+ *   counters і метадані для підсумкового `pass`-повідомлення (де саме знайдено перший LISTEN/NOTIFY).
+ */
+async function checkPgDependencyAndUsage(pkgJsonPaths, repoRoot, pgUsage, reporter) {
+  const { fail } = reporter
+  let pgDepFails = 0
+  let pgImportFails = 0
+  let pgDepsFound = 0
+
+  const firstWithListenNotify = pgUsage.find(u => u.listenNotify.length > 0)
+  const hasAnyListenNotify = !!firstWithListenNotify
+  const listenNotifyEvidence = firstWithListenNotify
+    ? `${firstWithListenNotify.rel}:${firstWithListenNotify.listenNotify[0].line}`
+    : null
+
+  for (const absPkgPath of pkgJsonPaths) {
+    const relPkg = relative(repoRoot, absPkgPath).split('\\').join('/')
+    let pkg
+    try {
+      pkg = JSON.parse(await readFile(absPkgPath, 'utf8'))
+    } catch {
+      // невалідний JSON у package.json — це проблема інших правил, тут пропускаємо
+      continue
+    }
+    if (!pkg || typeof pkg !== 'object') continue
+    const deps = pkg.dependencies
+    if (!deps || typeof deps !== 'object' || !Object.prototype.hasOwnProperty.call(deps, 'pg')) continue
+    pgDepsFound++
+    if (!hasAnyListenNotify) {
+      pgDepFails++
+      fail(
+        `js-bun-db: ${relPkg}: dependencies.pg заборонено — у проекті не знайдено LISTEN / NOTIFY / UNLISTEN ` +
+          `(або listener'а .on('notification', ...)). Bun SQL покриває звичайні запити; ` +
+          `\`pg\` дозволений лише як виняток для LISTEN/NOTIFY (js-bun-db.mdc, ` +
+          `секція «pg для LISTEN/NOTIFY»)`
+      )
+    }
+  }
+
+  for (const f of pgUsage) {
+    if (f.imports.length === 0) continue
+    if (f.listenNotify.length > 0) continue
+    for (const imp of f.imports) {
+      pgImportFails++
+      fail(
+        `js-bun-db: ${f.rel}:${imp.line} — import 'pg' дозволено лише у файлах з LISTEN / NOTIFY / UNLISTEN ` +
+          `або .on('notification', ...). Перенеси звичайні запити на Bun SQL ` +
+          `(import { sql } from 'bun'), а LISTEN/NOTIFY-логіку лиши в окремому модулі ` +
+          `(js-bun-db.mdc): ${imp.snippet}`
+      )
+    }
+  }
+
+  return { pgDepFails, pgImportFails, pgDepsFound, hasAnyListenNotify, listenNotifyEvidence }
+}
+
 /**
  * Будує повідомлення `fail` для порушення `findUnsafeBunSqlInListMissingEmptyGuardInText`
  * залежно від `reason` (різні діагностики однакового сімейства).
@@ -218,9 +341,9 @@ export async function check() {
     return reporter.getExitCode()
   }
 
-  // Перевірку `dependencies` (заборона `pg` / `pg-format` / `mysql2`) перенесено
-  // в Rego-полісі `npm/policy/js_bun_db/package_json/`; `npx @nitra/cursor check`
-  // запускає її по всіх workspace-`package.json`. Тут лишився лише AST-скан коду.
+  // Заборону `pg-format` / `mysql2` у `dependencies` тримає Rego-поліс
+  // `npm/policy/js_bun_db/package_json/`. `pg` оброблено тут — як виняток для
+  // LISTEN/NOTIFY (Rego не бачить JS-коду, тож не може зважити сигнал).
 
   const sourcePaths = await findAllSourcePathsForBunSqlScan(repoRoot, ignorePaths)
   if (sourcePaths.length === 0) {
@@ -228,8 +351,38 @@ export async function check() {
     return reporter.getExitCode()
   }
 
-  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard, pgLeftover, pgFormatShim, queryWrapper } =
-    await scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter)
+  const {
+    hasBunSqlImport,
+    pgUsage,
+    perRequest,
+    unsafeCall,
+    unsafeTemplateInterp,
+    dynamicList,
+    inListGuard,
+    pgLeftover,
+    pgFormatShim,
+    queryWrapper
+  } = await scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter)
+
+  const { pgDepFails, pgImportFails, pgDepsFound, listenNotifyEvidence } = await checkPgDependencyAndUsage(
+    pkgJsonPaths,
+    repoRoot,
+    pgUsage,
+    reporter
+  )
+  if (pgDepFails === 0) {
+    if (pgDepsFound === 0) {
+      pass('js-bun-db: dependencies.pg відсутнє у жодному package.json')
+    } else {
+      pass(
+        `js-bun-db: dependencies.pg виправдано LISTEN/NOTIFY у коді (виключення з js-bun-db.mdc; ` +
+          `доказ: ${listenNotifyEvidence})`
+      )
+    }
+  }
+  if (pgImportFails === 0) {
+    pass("js-bun-db: усі `import 'pg'` або відсутні, або у файлах з LISTEN/NOTIFY")
+  }
 
   if (!hasBunSqlImport) {
     pass("js-bun-db: Bun SQL не використовується в коді (немає import { sql|SQL } from 'bun')")
@@ -242,6 +395,12 @@ export async function check() {
   if (unsafeCall === 0) {
     pass('js-bun-db: усі sql.unsafe(...) або відсутні, або супроводжуються маркером "// allow-unsafe: <причина>"')
   }
+  if (unsafeTemplateInterp === 0) {
+    pass(
+      'js-bun-db: немає sql.unsafe(`...${x}...`) з template-інтерполяцією ' +
+        '(identifiers через @scaleleap/pg-format %I, values — позиційні $N)'
+    )
+  }
   if (pgLeftover === 0) {
     pass(
       'js-bun-db: немає pg-leftover викликів .connect()/.end() у файлах з Bun SQL ' +

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

@@ -2,7 +2,7 @@
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 globs: "**/package.json,**/src/conn/**"
 alwaysApply: false
-version: '1.8'
+version: '1.11'
 ---
 
 ## Підтримувані версії баз даних
@@ -13,13 +13,15 @@ PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом,
 
 Якщо в проєкті використовуються бібліотеки `pg`, `pg-format` або `mysql2`, їх потрібно замінити на Bun native SQL: <https://bun.com/docs/runtime/sql>.
 
-- Видалити з `dependencies`: `pg`, `pg-pool`, `pg-native`, `pg-format`, `mysql`, `mysql2`.
+- Видалити з `dependencies`: `pg-pool`, `pg-native`, `pg-format`, `mysql`, `mysql2`.
 - Видалити з коду: усі `import` / `require` цих пакетів та власні обгортки над ними.
 - Замінити на `import { sql, SQL } from 'bun'` — Bun має вбудований клієнт із пулом, prepared statements та tagged templates.
 
-Канон заборонених `dependencies` (`pg`, `pg-format`, `mysql2`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json).
+Канон заборонених `dependencies` (`pg-format`, `mysql2`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json). Сам `pg` із денилисту прибрано — він має одне легітимне виключення (LISTEN/NOTIFY), яке зважує AST-сканер; деталі — `## pg: виключення для LISTEN/NOTIFY`.
 
-`pg-format` — це ручне форматування SQL через escape (`format('... %L ...', value)`); такі рядки легко поламати неправильним типом, locale-залежним escape або забутим `%L`. Tagged template Bun SQL параметризує значення нативно (`sql\`... ${value} ...\``) і не лишає простору для injection — окремий «форматер» не потрібен.
+`pg-format` (unscoped) — це ручне форматування SQL через escape (`format('... %L ...', value)`); такі рядки легко поламати неправильним типом, locale-залежним escape або забутим `%L`. Tagged template Bun SQL параметризує значення нативно (`sql\`... ${value} ...\``) і не лишає простору для injection — окремий «форматер» **для значень** не потрібен.
+
+Виключення є **лише** для **динамічних identifiers** (назви схем / таблиць / колонок / індексів / ролей / БД) і whitelist-фрагментів типу `ASC`/`DESC`: Bun SQL їх параметризувати не вміє, тож тут дозволено окремий пакет **`@scaleleap/pg-format`** (scoped форк, не unscoped `pg-format`) — деталі й приклади у `## Динамічна SQL-структура: @scaleleap/pg-format для identifiers`.
 
 ## `pg-format`: повне видалення, без шимів
 
@@ -40,7 +42,7 @@ PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом,
 | `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)      | `sql.unsafe(\`... \${tableName} ...\`)` з маркером `// allow-unsafe: <причина>` і whitelist'ом   |
+| `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[]`, …).
 
@@ -73,6 +75,160 @@ 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                |
+
+Головне правило:
+
+- **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` створювати не треба.
@@ -186,14 +342,45 @@ await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
 Кожен легітимний `sql.unsafe(...)` має супроводжуватись **маркером-коментарем** з причиною — на тому ж рядку (trailing) або на рядку безпосередньо перед викликом. Маркер — opt-in для перевірки `js-bun-db` і слід для ревʼюера:
 
 ```javascript
-// allow-unsafe: DDL — назву таблиці параметризувати не можна
-await sql.unsafe(`CREATE TABLE ${tableName} (id int)`)
+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

package/rules/js-bun-db/policy/package_json/template/package.json.deny.json

@@ -1,6 +1,5 @@
 {
   "dependencies": {
-    "pg": "заміни на Bun native SQL (js-bun-db.mdc)",
     "pg-format": "заміни на Bun native SQL — без ручного форматування (js-bun-db.mdc)",
     "mysql2": "заміни на Bun native SQL (js-bun-db.mdc)"
   }