@nitra/cursor 1.13.54 → 1.13.58

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.58] - 2026-05-20
+
+### Added
+
+- `check security`: новий concern **`security.sample_secret`** — placeholder фейкових credential-значень у прикладних файлах має бути `sample-secret`, а не bare `secret`. Причина: `sample-secret` містить підрядок `sample` із вшитого списку `DefaultFalsePositives` TruffleHog і відсіюється сканером гарантовано та незалежно від версії; bare `secret` наразі ігнорується лише тому, що випадково присутнє у словнику `fp_words.txt` — крихка, версієзалежна поведінка. [check.mjs](rules/security/fix/sample_secret/check.mjs) обходить дерево, відбирає прикладні файли (basename із суфіксом `.example`/`.sample`/`.template`/`.dist` чи infix `.example.`/`.sample.`/`.template.`, а також усе всередині каталогів `fixtures`/`fixture`/`__fixtures__`) і порядково шукає `secret` у позиції значення — одразу після `=`, `:` або `=>` з опційними лапками; імена ключів (`client_secret`, `JWT_SECRET`) не чіпаються, бо матч прив'язаний до значення. Решта файлів не сканується — там `secret` майже завжди частина реального коду. Скан текстовий (regex, не AST/Rego): прикладні файли — різнорідні конфіги (`.env`, YAML, JSON, TOML, plain `.dist`) без єдиного AST, а відбір файлів потребує обходу дерева. Зачеплено: [check.mjs](rules/security/fix/sample_secret/check.mjs) і [check.test.mjs](rules/security/fix/sample_secret/check.test.mjs) (новий concern + 9 тестів), [security.mdc](rules/security/security.mdc) (нова секція «Placeholder для секретів — `sample-secret`» та секція «Перевірка»). Bump `security.mdc` `2.0` → `2.1`.
+
+## [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

package/package.json

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

package/rules/bun/fix/layout/check.mjs

@@ -53,8 +53,8 @@ async function loadNCursorRules() {
  */
 function lintChainHasScript(lintScript, target) {
   if (!lintScript) return false
-  const escaped = target.replaceAll(/[.*+?^${}()|[\]\\]/gu, '\\$&')
-  return new RegExp(`(?:^|\\s)bun\\s+run\\s+${escaped}(?:$|\\s)`, 'u').test(lintScript)
+  const escaped = target.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`)
+  return new RegExp(String.raw`(?:^|\s)bun\s+run\s+${escaped}(?:$|\s)`, 'u').test(lintScript)
 }
 
 /**
@@ -74,6 +74,17 @@ const RULE_SCRIPTS = [
   { rules: ['image-avif', 'image-compress'], script: 'lint-image', doc: 'image-avif.mdc / image-compress.mdc' }
 ]
 
+/**
+ * Загортає кожен ідентифікатор у backticks та зʼєднує через роздільник. Винесено
+ * окремою функцією, щоб не нестити template literals у `pass`/`fail`-повідомленнях.
+ * @param {string[]} items ідентифікатори правил
+ * @param {string} sep роздільник (наприклад `, ` або `/`)
+ * @returns {string} рядок виду "`a`, `b`"
+ */
+function backtickJoin(items, sep) {
+  return items.map(r => '`' + r + '`').join(sep)
+}
+
 /**
  * Описує стан правил-власників скрипта для повідомлень про reason. Повертає або список увімкнених
  * правил (для passing-кейсу «правило є»), або компактний опис, чому всі вимкнені (для inverse-fail).
@@ -84,7 +95,7 @@ const RULE_SCRIPTS = [
 function ownerStatus(owners, cursorRules) {
   const enabled = owners.filter(r => cursorRules.rules.has(r))
   if (enabled.length > 0) {
-    return { enabled, reason: `правил${enabled.length === 1 ? 'о' : 'а'} ${enabled.map(r => `\`${r}\``).join(', ')}` }
+    return { enabled, reason: `правил${enabled.length === 1 ? 'о' : 'а'} ${backtickJoin(enabled, ', ')}` }
   }
   if (owners.length === 1) {
     const [only] = owners
@@ -93,7 +104,7 @@ function ownerStatus(owners, cursorRules) {
   }
   const disabledCount = owners.filter(r => cursorRules.disabled.has(r)).length
   const note = disabledCount === owners.length ? 'усі власники в disable-rules' : 'жоден власник не активний у rules'
-  return { enabled, reason: `${owners.map(r => `\`${r}\``).join('/')} — ${note}` }
+  return { enabled, reason: `${backtickJoin(owners, '/')} — ${note}` }
 }
 
 /**
@@ -104,7 +115,7 @@ function ownerStatus(owners, cursorRules) {
  * вимкненому правилі: `n-cursor lint-<id>` ігнорує `.n-cursor.json` і обходить дерево
  * незалежно від конфігу (як було в cursor-репо: `disable-rules: ["k8s"]` + залишений `lint-k8s`
  * ламав chain на template-сорцях власного правила).
- * @param {{ pass: (msg: string) => void, fail: (msg: string) => void }} reporter
+ * @param {{ pass: (msg: string) => void, fail: (msg: string) => void }} reporter callback-и `pass`/`fail` для звіту
  * @param {Record<string, string>} scripts scripts з package.json
  * @param {{ rules: Set<string>, disabled: Set<string> }} cursorRules `rules` та `disable-rules`
  */
@@ -127,7 +138,7 @@ function checkCursorRuleScripts(reporter, scripts, cursorRules) {
     }
     if (present) {
       fail(
-        `У .n-cursor.json немає активних власників ${owners.map(r => `\`${r}\``).join('/')} — прибери скрипт \`${script}\` з кореневого package.json (див. ${doc})`
+        `У .n-cursor.json немає активних власників ${backtickJoin(owners, '/')} — прибери скрипт \`${script}\` з кореневого package.json (див. ${doc})`
       )
     }
     if (inChain) {

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,17 +38,27 @@ 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'
 import { walkDir } from '../../../../scripts/utils/walkDir.mjs'
 
+// Дешеві pre-filter regex'и для AST-сканера LISTEN/NOTIFY: уникаємо парсингу
+// файлів, у яких ніяких сигналів немає. Винесено в модульний скоуп, щоб не
+// перекомпілювати RegExp на кожному виклику `collectPgUsageForFile`.
+const LISTEN_NOTIFY_KEYWORD_RE = /\b(LISTEN|UNLISTEN|NOTIFY)\b/iu
+const NOTIFICATION_LITERAL_RE = /['"`]notification['"`]/u
+
 /**
  * Збирає абсолютні шляхи JS/TS джерел у репозиторії для скану Bun SQL патернів.
  * @param {string} repoRoot абсолютний шлях до кореня репозиторію
@@ -65,19 +83,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 +116,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 +126,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 = LISTEN_NOTIFY_KEYWORD_RE.test(content) || NOTIFICATION_LITERAL_RE.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 +178,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 +234,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.hasOwn(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 +347,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 +357,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 +401,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(template literal з інтерполяцією) ' +
+        '(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)"
   }

package/rules/security/fix/sample_secret/check.mjs

@@ -0,0 +1,105 @@
+/**
+ * FS-частина правила `security`: concern `sample_secret`.
+ *
+ * Перевіряє, що фейкові credential-значення у *прикладних* файлах записані як
+ * канонічний placeholder `sample-secret`, а не як bare `secret`.
+ *
+ * `sample-secret` містить підрядок `sample`, який є у вшитому списку
+ * `DefaultFalsePositives` TruffleHog — таке значення сканер відсіює
+ * гарантовано й незалежно від версії. Bare `secret` наразі не репортиться
+ * лише тому, що випадково присутнє у словнику `fp_words.txt`; це крихка,
+ * версієзалежна поведінка, на яку не варто покладатися.
+ *
+ * Прикладними вважаються файли, чий basename має суфікс `.example` / `.sample`
+ * / `.template` / `.dist` або infix `.example.` / `.sample.` / `.template.`, а
+ * також будь-які файли всередині каталогів `fixtures` / `fixture` /
+ * `__fixtures__`. Решта файлів не сканується — там `secret` майже завжди
+ * частина реального коду, а не placeholder.
+ *
+ * Порушенням є лише `secret` у *позиції значення* — одразу після `=`, `:` чи
+ * `=>` (з опційними лапками). Імена ключів (`client_secret`, `JWT_SECRET`) не
+ * чіпаються: матч прив'язаний до значення, не до ключа.
+ *
+ * Чому regex, а не AST: прикладні файли — різнорідні конфіги (`.env`, YAML,
+ * JSON, TOML, plain `.dist`), єдиного AST для них немає, тож скан порядковий.
+ * Чому JS, а не Rego: щоб знайти прикладні файли, треба обійти дерево
+ * (`readdir`), а вміст — неструктурований текст (conftest парсить лише
+ * структуровані документи).
+ */
+import { readFile } from 'node:fs/promises'
+import { relative, sep } from 'node:path'
+
+import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mjs'
+import { walkDir } from '../../../../scripts/utils/walkDir.mjs'
+
+/** Суфікс basename'а прикладного файлу (`config.example`, `.env.dist`). */
+const EXAMPLE_SUFFIX_RE = /\.(?:example|sample|template|dist)$/iu
+
+/** Infix у basename'і (`docker-compose.example.yml`, `app.config.sample.json`). */
+const EXAMPLE_INFIX_RE = /\.(?:example|sample|template)\./iu
+
+/** Сегмент шляху з фікстурами (`fixtures/`, `fixture/`, `__fixtures__/`). */
+const FIXTURE_DIR_RE = /(?:^|\/)(?:__fixtures__|fixtures?)(?:\/|$)/u
+
+/**
+ * Bare-`secret` у позиції значення: після `=`, `:` або `=>` (опційні лапки), а
+ * далі лише пробіли / завершальна пунктуація / коментар до кінця рядка. Прив'язка
+ * до `$` гарантує, що `secret` — увесь токен значення (`secret-key`, `secretValue`
+ * не матчаться); прив'язка до `[:=]` відсікає імена ключів (`client_secret`).
+ * Регістронезалежно.
+ */
+const VALUE_SECRET_RE = /[:=]>?\s*(['"]?)secret\1[\s,;}\])]*(?:(?:#|\/\/).*)?$/iu
+
+/**
+ * Чи є файл «прикладним» — таким, де `secret` очікувано є placeholder'ом.
+ * @param {string} relPosix відносний шлях від cwd у posix-форматі
+ * @returns {boolean} `true`, якщо файл треба сканувати
+ */
+function isExampleFile(relPosix) {
+  const base = relPosix.slice(relPosix.lastIndexOf('/') + 1)
+  return EXAMPLE_SUFFIX_RE.test(base) || EXAMPLE_INFIX_RE.test(base) || FIXTURE_DIR_RE.test(relPosix)
+}
+
+/**
+ * @returns {Promise<number>} exit-код перевірки (0 — OK, 1 — є bare `secret`)
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const cwd = process.cwd()
+
+  /** @type {Array<{ abs: string, rel: string }>} */
+  const examples = []
+  await walkDir(cwd, abs => {
+    const rel = relative(cwd, abs).split(sep).join('/')
+    if (isExampleFile(rel)) examples.push({ abs, rel })
+  })
+  examples.sort((a, b) => a.rel.localeCompare(b.rel))
+
+  if (examples.length === 0) {
+    pass('прикладних файлів не знайдено — placeholder перевіряти нема де')
+    return reporter.getExitCode()
+  }
+
+  let violations = 0
+  for (const { abs, rel } of examples) {
+    let content
+    try {
+      content = await readFile(abs, 'utf8')
+    } catch {
+      continue
+    }
+    const lines = content.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].endsWith('\r') ? lines[i].slice(0, -1) : lines[i]
+      if (!VALUE_SECRET_RE.test(line)) continue
+      violations++
+      fail(`${rel}:${i + 1}: \`${line.trim()}\` — заміни placeholder \`secret\` на \`sample-secret\` (security.mdc)`)
+    }
+  }
+
+  if (violations === 0) {
+    pass(`прикладні файли (${examples.length}) не містять bare \`secret\``)
+  }
+  return reporter.getExitCode()
+}

package/rules/security/security.mdc

@@ -1,8 +1,8 @@
 ---
-description: Локальний та CI-секюріті-лінт через TruffleHog — скрипт `lint-security`, `.trufflehog-exclude`, інтеграція в агрегований `lint`
+description: Локальний та CI-секюріті-лінт через TruffleHog — скрипт `lint-security`, `.trufflehog-exclude`, інтеграція в агрегований `lint`; канонічний placeholder `sample-secret` у прикладних файлах
 globs: "**/.trufflehog-exclude,**/package.json,**/.github/workflows/**/*.yml"
 alwaysApply: false
-version: '2.0'
+version: '2.1'
 ---
 
 [TruffleHog](https://github.com/trufflesecurity/trufflehog) — глобальний CLI (як `shellcheck`, `conftest`); **не** додавай до `dependencies`/`devDependencies`.
@@ -35,3 +35,18 @@ Workflow обовʼязковий — забезпечує незалежний
 - Канон: [lint-security.yml.snippet.yml](./policy/lint_security_yml/template/lint-security.yml.snippet.yml)
 
 Перевіряється policy `security.lint_security_yml`: серед `uses:` має бути крок з `trufflesecurity/trufflehog@main`. Універсальні workflow-перевірки (checkout, permissions, persist-credentials) — у `ga.workflow_common`. Для повного скану історії потрібен `fetch-depth: 0`.
+
+## Placeholder для секретів — `sample-secret`
+
+Фейкові credential-значення у **прикладних файлах** (`.env.example`, `.env.dist`, `*.example`, `*.sample`, `*.template`, вміст каталогів `fixtures/`) пиши як `sample-secret`, а не як bare `secret`.
+
+`sample-secret` містить підрядок `sample` із вшитого списку `DefaultFalsePositives` TruffleHog — таке значення сканер відсіює **гарантовано** й незалежно від версії. Bare `secret` наразі не репортиться лише тому, що випадково присутнє у словнику `fp_words.txt`; це крихка, версієзалежна поведінка.
+
+- Правильно: `DB_PASSWORD=sample-secret`, `password: "sample-secret"`
+- Неправильно: `DB_PASSWORD=secret`, `password: "secret"`
+
+Перевіряється лише `secret` у позиції значення (після `=`, `:`, `=>`); імена ключів на кшталт `client_secret` не чіпаються. Concern `security.sample_secret` — деталі скану в `fix/sample_secret/check.mjs`.
+
+## Перевірка
+
+`npx @nitra/cursor check security`

package/scripts/utils/bun-sql-scan.mjs

@@ -31,6 +31,16 @@ import {
 
 const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
 const BUN_SQL_IMPORT_RE = /\bimport\s*\{[\s\S]*?\b(sql|SQL)\b[\s\S]*?\}\s*from\s*["']bun["']/u
+// Імпорт із npm-пакета `pg` — будь-яка з форм: default, named, namespace, side-effect,
+// а також `require('pg')`. `pg-format`/`pg-pool` свідомо НЕ матчаться: на них діє
+// окрема заборона (denylist) і свої повідомлення. Виключення для LISTEN/NOTIFY
+// стосується лише самого клієнта `pg`.
+const PG_LIB_IMPORT_RE = /(?:\bimport\b[\s\S]*?\bfrom\s*["']pg["']|\brequire\s*\(\s*["']pg["']\s*\))/u
+// Першоквазі-рядок або string literal, що починається з LISTEN / UNLISTEN / NOTIFY
+// (case-insensitive), з опційним leading whitespace. Сигнал, що в коді запит
+// `LISTEN ch` / `NOTIFY ch, 'msg'` / `UNLISTEN *` — це функціонал, якого Bun SQL
+// поки не має, тож у проекті лишається легітимна потреба у клієнті `pg`.
+const PG_LISTEN_NOTIFY_SQL_RE = /^\s*(LISTEN|UNLISTEN|NOTIFY)\b/iu
 const IN_PLACEHOLDER_END_RE = /\bin\s*(\(\s*)?$/iu
 // `// allow-unsafe: <reason>` — `allow-unsafe`, двокрапка, **непорожня** причина.
 // Без причини маркер не приймається: ціль — лишити слід для ревʼюера, а не «німий» прапорець.
@@ -531,6 +541,43 @@ export function findBunSqlUnsafeUseWithoutAllowMarkerInText(content, virtualPath
   return out
 }
 
+/**
+ * Знаходить `<obj>.unsafe(template_literal_with_interpolation)` — навіть із маркером
+ * `// allow-unsafe`. Шаблонна підстановка `${name}` у `sql.unsafe`-рядок **не екранує**
+ * identifier'ів (reserved words, спецсимволи) і ніяк не біндить значення — це
+ * структурна injection-поверхня, яку легко не помітити в ревʼю. Канон — побудувати
+ * `text` через `@scaleleap/pg-format` `format('%I', name)` (для identifiers) або
+ * звичайні позиційні `$N`-placeholder'и (для values), і передати в `sql.unsafe(text, [params])`.
+ *
+ * Прапорує саме `TemplateLiteral` з `expressions.length > 0`; статичні рядки
+ * (`Literal`, `StringLiteral`, `TemplateLiteral` без `${...}`) і виклики з готовим
+ * `text` як змінною — не зачіпає (для них діє основна перевірка allow-unsafe).
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findBunSqlUnsafeWithInterpolatedTemplateInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (!isUnsafeCall(node)) return
+    const args = node.arguments
+    if (!Array.isArray(args) || args.length === 0) return
+    const first = args[0]
+    if (!first || first.type !== 'TemplateLiteral') return
+    const expressions = first.expressions
+    if (!Array.isArray(expressions) || expressions.length === 0) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
 /**
  * Знаходить pg-leftover виклики `<obj>.connect(...)` / `<obj>.end(...)` без маркера
  * `// allow-pg-leftover: <reason>` у файлах, де **в цьому ж файлі** є `import { sql|SQL } from 'bun'`.
@@ -685,6 +732,193 @@ export function textHasBunSqlImport(content) {
   return BUN_SQL_IMPORT_RE.test(content)
 }
 
+/**
+ * Чи імпортує файл npm-пакет `pg` (`import ... from 'pg'` або `require('pg')`).
+ * Текстова перевірка — без AST, дешевий pre-filter; для строгої локалізації
+ * (рядок/snippet) використай `findPgLibImportInText`. Не матчить `pg-format`,
+ * `pg-pool`, `@types/pg` — лише сам клієнт.
+ * @param {string} content вміст файлу
+ * @returns {boolean} true, якщо у файлі є імпорт `'pg'`
+ */
+export function textHasPgLibImport(content) {
+  return PG_LIB_IMPORT_RE.test(content)
+}
+
+/**
+ * Знаходить ImportDeclaration / CallExpression `require('pg')` для пакета `pg`
+ * (саме точна назва, не `pg-format` тощо). Повертає рядок і snippet — щоб у
+ * повідомленнях `fail` показати конкретне місце.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список місць, де імпортується `pg`
+ */
+export function findPgLibImportInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (node.type === 'ImportDeclaration' && getStringLiteralValue(node.source) === 'pg') {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end))
+      })
+      return
+    }
+    if (node.type === 'CallExpression' && isRequireOfModule(node, 'pg')) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end))
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * Знаходить використання PostgreSQL LISTEN/NOTIFY у коді — сигнал, що проект
+ * потребує `pg` як виняток (Bun SQL поки не реалізує LISTEN/NOTIFY). Прапорує:
+ * - `<obj>.query(...)` / `<obj>.queryArray(...)` / `<obj>.queryStream(...)`, де
+ *   перший аргумент — string literal або template literal, що починається з
+ *   `LISTEN ` / `UNLISTEN ` / `NOTIFY ` (case-insensitive);
+ * - `<obj>.on('notification', ...)` — pg-listener notification-подій (другий
+ *   аргумент — функція; перший — точно рядок `'notification'`);
+ * - TaggedTemplateExpression виду sql tagged template з LISTEN/UNLISTEN/NOTIFY
+ *   на початку першого quasi — на випадок, якщо хтось використовує Bun
+ *   SQL-tagged-template, а LISTEN/NOTIFY все одно лишається у тексті запиту
+ *   (це не запрацює у Bun SQL, але як сигнал — приймаємо).
+ *
+ * Регістр SQL-слів не важливий, провідні пробіли допускаються.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, kind: 'listen_sql' | 'notify_sql' | 'unlisten_sql' | 'notification_listener' }[]} список знахідок
+ */
+export function findPgListenNotifyUsageInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string, kind: 'listen_sql' | 'notify_sql' | 'unlisten_sql' | 'notification_listener' }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    const fromCall = listenNotifyFromCallExpression(node)
+    if (fromCall) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        kind: fromCall
+      })
+      return
+    }
+    const fromTagged = listenNotifyFromTaggedTemplate(node)
+    if (fromTagged) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        kind: fromTagged
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * @param {Record<string, unknown>} node ImportDeclaration.source або CallExpression.arguments[0]
+ * @returns {string | null} значення string literal або null
+ */
+function getStringLiteralValue(node) {
+  if (!node || typeof node !== 'object') return null
+  if ((node.type === 'Literal' || node.type === 'StringLiteral') && typeof node.value === 'string') {
+    return node.value
+  }
+  return null
+}
+
+/**
+ * Чи це `require('<moduleName>')` — CallExpression з callee Identifier `require`
+ * і єдиним string-літералом-аргументом.
+ * @param {Record<string, unknown>} node CallExpression
+ * @param {string} moduleName очікувана назва модуля (точне співпадіння)
+ * @returns {boolean} true, якщо це саме require цього модуля
+ */
+function isRequireOfModule(node, moduleName) {
+  const callee = node.callee
+  if (!callee || callee.type !== 'Identifier' || callee.name !== 'require') return false
+  const args = node.arguments
+  if (!Array.isArray(args) || args.length !== 1) return false
+  return getStringLiteralValue(args[0]) === moduleName
+}
+
+/**
+ * Аналізує CallExpression на предмет pg-style LISTEN/NOTIFY-запиту або listener'а
+ * подій `'notification'`. Повертає тип сигналу або `null`.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | 'notification_listener' | null} kind знахідки
+ */
+function listenNotifyFromCallExpression(node) {
+  if (!node || node.type !== 'CallExpression') return null
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return null
+  const prop = callee.property
+  if (!prop || prop.type !== 'Identifier' || typeof prop.name !== 'string') return null
+  const args = node.arguments
+  if (!Array.isArray(args) || args.length === 0) return null
+
+  if (prop.name === 'on') {
+    return getStringLiteralValue(args[0]) === 'notification' ? 'notification_listener' : null
+  }
+  if (prop.name === 'query' || prop.name === 'queryArray' || prop.name === 'queryStream') {
+    return sqlStringStartsWithListenNotify(args[0])
+  }
+  return null
+}
+
+/**
+ * Аналізує TaggedTemplateExpression: якщо перший quasi починається з
+ * LISTEN/UNLISTEN/NOTIFY — повертає відповідний kind.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | null} kind знахідки
+ */
+function listenNotifyFromTaggedTemplate(node) {
+  if (!node || node.type !== 'TaggedTemplateExpression') return null
+  const quasi = node.quasi
+  if (!quasi || quasi.type !== 'TemplateLiteral') return null
+  const text = templateQuasisText(quasi)
+  return kindFromListenNotifyMatch(text)
+}
+
+/**
+ * Перший аргумент виклику `.query(...)` — це string literal або template literal,
+ * текст якого починається з LISTEN / UNLISTEN / NOTIFY (case-insensitive)?
+ * @param {unknown} arg AST node першого аргумента
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | null} kind знахідки або null
+ */
+function sqlStringStartsWithListenNotify(arg) {
+  if (!arg || typeof arg !== 'object') return null
+  if ((arg.type === 'Literal' || arg.type === 'StringLiteral') && typeof arg.value === 'string') {
+    return kindFromListenNotifyMatch(arg.value)
+  }
+  if (arg.type === 'TemplateLiteral') {
+    return kindFromListenNotifyMatch(templateQuasisText(arg))
+  }
+  return null
+}
+
+/**
+ * Перетворює текст SQL-рядка у kind знахідки (`listen_sql` / `notify_sql` /
+ * `unlisten_sql`) або `null`, якщо рядок не починається з ключового слова.
+ * @param {string} text SQL-текст
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | null} kind знахідки
+ */
+function kindFromListenNotifyMatch(text) {
+  const m = PG_LISTEN_NOTIFY_SQL_RE.exec(text)
+  if (!m) return null
+  const keyword = m[1].toUpperCase()
+  if (keyword === 'LISTEN') return 'listen_sql'
+  if (keyword === 'NOTIFY') return 'notify_sql'
+  return 'unlisten_sql'
+}
+
 /**
  * Чи сканувати цей файл за розширенням (JS/TS-сімʼя, без `.d.ts`).
  * @param {string} relativePathPosix відносний шлях (posix)