@nitra/cursor 1.8.209 → 1.8.210

package/CHANGELOG.md

@@ -4,6 +4,25 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.210] - 2026-05-08
+
+### Added
+
+- `js-bun-db` v1.6: правило тепер забороняє локальні pg-format-сумісні шими у
+  файлах з Bun SQL.
+  - Розділ `## pg-format: повне видалення, без шимів` у `npm/mdc/js-bun-db.mdc`:
+    типові ідіоми `format(...)` → tagged template, заборонений drop-in `format()`
+    і `pg`-сумісна `query(text, params)`-обгортка над `sql.unsafe(...)`.
+  - Два нові AST-детектори у `npm/scripts/utils/bun-sql-scan.mjs`:
+    `findPgFormatShimDefinitionInText` (функції `format` / `pgFormat` /
+    `sqlFormat` / `pgFmt` з `%L`/`%I`/`%s` у тілі, плюс `quoteLiteral` /
+    `quoteIdent` / `escapeLiteral` / `escapeIdent` без додаткової перевірки)
+    та `findPgFormatLikeQueryWrapperInText` (`{ query(text, params) { ...
+    <obj>.unsafe(...) ... } }`). Скан запускається лише у файлах з
+    `import { sql|SQL } from 'bun'`.
+  - `npm/scripts/check-js-bun-db.mjs` рапортує `pgFormatShim` / `queryWrapper` —
+    окремі лічильники й `pass`-рядки, без зміни існуючих перевірок.
+
 ## [1.8.209] - 2026-05-08
 
 ### Removed

package/mdc/js-bun-db.mdc

@@ -1,7 +1,7 @@
 ---
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 alwaysApply: true
-version: '1.5'
+version: '1.6'
 ---
 
 ## Підтримувані версії баз даних
@@ -18,6 +18,58 @@ PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом,
 
 `pg-format` — це ручне форматування SQL через escape (`format('... %L ...', value)`); такі рядки легко поламати неправильним типом, locale-залежним escape або забутим `%L`. Tagged template Bun SQL параметризує значення нативно (`sql\`... ${value} ...\``) і не лишає простору для injection — окремий «форматер» не потрібен.
 
+## `pg-format`: повне видалення, без шимів
+
+Міграція з `pg-format` — це **зміна стилю запитів**, а не збереження API. У проєкті після переходу на Bun SQL **заборонено** залишати:
+
+- функцію з іменем `format` (чи `pgFormat`, `sqlFormat`, `pgFmt`), що приймає шаблон з `%L` / `%I` / `%s` і значення;
+- допоміжні `quoteLiteral`, `quoteIdent`, `escapeLiteral`, `escapeIdent` як публічні експорти модуля;
+- обгортки `pgRead.query(text, params)` / `pgWrite.query(text, params)` / `db.query(text, params)`, які складають SQL-рядок (з або без `format`) і викликають `sql.unsafe(text, params)` — це повертає injection-поверхню, від якої ми йдемо, тільки під «зручним» іменем.
+
+Замість цього всі точки використання потрібно перевести на tagged template `sql\`...\${value}...\``. Кожне `${value}` стає окремим параметром bind, без рядкового екранування.
+
+### Типові ідіоми `pg-format` → Bun SQL
+
+| Було (`pg-format`)                                 | Стало (Bun SQL)                                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `format('... WHERE id = %L', id)`                  | `sql\`... WHERE id = ${id}\``                                                                    |
+| `format('... IN (%L)', ids)`                       | `sql\`... IN ${sql(ids)}\`` (з guard на пустоту перед запитом)                                   |
+| `format('INSERT ... VALUES %L', [row])` (1 рядок)  | `sql\`INSERT ... VALUES (${a}, ${b}, ...)\``                                                     |
+| `format('INSERT ... VALUES %L', rows)` (N рядків)  | `sql\`INSERT INTO t ${sql(rows, 'a', 'b')}\`` або `unnest($1::T[], $2::T[]) AS t(a, b)`          |
+| `format('MERGE ... USING (VALUES %L) AS d(...)')`  | `sql\`MERGE ... USING (SELECT * FROM unnest(${arrA}::A[], ${arrB}::B[]) AS t(a, b)) AS d\``      |
+| `format('... %I ...', tableName)` (whitelist)      | `sql.unsafe(\`... \${tableName} ...\`)` з маркером `// allow-unsafe: <причина>` і whitelist'ом   |
+
+Для multi-row `VALUES` у `MERGE` / `INSERT` з конкретними типами — паралельні масиви по колонках і `unnest($1::TYPE[], $2::TYPE[], ...) AS t(col1, col2, ...)`. Кожна колонка передається одним параметром-масивом; типи задаються кастом масиву (`::uuid[]`, `::bigint[]`, `::numeric[]`, `::text[]`, …).
+
+### Заборонений «drop-in» шим
+
+```javascript
+// ❌ pg-format-сумісний шим, що ховає `unsafe` під «безпечним» іменем
+export function format(fmt, ...args) {
+  let i = 0
+  return fmt.replaceAll(/%[LIs]/g, () => quoteLiteral(args[i++]))
+}
+
+// ❌ і його типовий call-site — той самий injection-вектор, що і прямий sql.unsafe із конкатенацією
+await sql.unsafe(format('... WHERE id = %L', userId))
+```
+
+```javascript
+// ❌ pg-сумісна обгортка над Bun SQL — ще один прихований `unsafe`
+export const pgWrite = {
+  query(text, params) {
+    return sql.unsafe(text, params)
+  }
+}
+```
+
+```javascript
+// ✅ напряму tagged template — параметризація через wire-protocol bind
+await sql`... WHERE id = ${userId}`
+```
+
+Виняток для шиму `format()` під час поетапної міграції допускається **тільки** в окремому commit'і з TODO-маркером і дедлайном; готовий код у main з таким шимом — `fail` правила (детектори: `pg-format shim`, `query wrapper over unsafe`).
+
 ## Підключення (singleton + env)
 
 Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
@@ -197,6 +249,8 @@ function getUser(id) {
 
 Якщо в коді з'явився `import { sql } from 'bun'`, то `pg`, `pg-format` та `mysql2` мають бути прибрані і з `dependencies`, і з імпортів — щоб не лишалось двох паралельних шляхів до БД та ручного форматування поряд із параметризованими template literal.
 
+Те саме стосується **локальних шимів**: будь-який модуль, що експортує `format`, `pgRead`, `pgWrite`, `query(text, params)`, `quoteLiteral`, `quoteIdent` як обгортку над `sql.unsafe(...)`, потрібно переписати — всі call-site на tagged template, сам шим видалити (див. `## pg-format: повне видалення, без шимів`).
+
 ## Перевірка
 
 `npx @nitra/cursor check js-bun-db`.

package/package.json

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

package/scripts/check-js-bun-db.mjs

@@ -30,6 +30,8 @@ import {
   findBunSqlPerRequestConnectionInText,
   findBunSqlPgLeftoverCallInText,
   findBunSqlUnsafeUseWithoutAllowMarkerInText,
+  findPgFormatLikeQueryWrapperInText,
+  findPgFormatShimDefinitionInText,
   findUnsafeBunSqlDynamicSqlListInText,
   findUnsafeBunSqlInListMissingEmptyGuardInText,
   isBunSqlScanSourceFile,
@@ -67,13 +69,21 @@ async function findAllSourcePathsForBunSqlScan(repoRoot, ignorePaths) {
  * @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 }>}
+ * @returns {Promise<{ hasBunSqlImport: boolean, perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number }>}
  *   `hasBunSqlImport` — чи знайдено хоч один `import { sql|SQL } from 'bun'` у джерелах;
  *   решта — кількість порушень кожного типу.
  */
 async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
   const { fail } = reporter
-  const counts = { perRequest: 0, unsafeCall: 0, dynamicList: 0, inListGuard: 0, pgLeftover: 0 }
+  const counts = {
+    perRequest: 0,
+    unsafeCall: 0,
+    dynamicList: 0,
+    inListGuard: 0,
+    pgLeftover: 0,
+    pgFormatShim: 0,
+    queryWrapper: 0
+  }
   let hasBunSqlImport = false
 
   for (const absPath of sourcePaths) {
@@ -93,7 +103,7 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
  * @param {string} content вміст файлу
  * @param {string} rel posix-шлях відносно `repoRoot`
  * @param {(msg: string) => void} fail callback при помилці
- * @param {{ perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number }} counts акумулятори
+ * @param {{ perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number }} counts акумулятори
  * @returns {void}
  */
 function scanFileForBunSqlPatterns(content, rel, fail, counts) {
@@ -134,6 +144,30 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
     counts.inListGuard++
     fail(messageForBunSqlInListGuard(rel, v))
   }
+  for (const v of findPgFormatShimDefinitionInText(content, rel)) {
+    counts.pgFormatShim++
+    if (v.kind === 'format_function') {
+      fail(
+        `js-bun-db: ${rel}:${v.line} — функція ${JSON.stringify(v.name)} виглядає як pg-format-сумісний шим ` +
+          `(тіло містить %L / %I / %s). Видали шим і переведи всі call-site на tagged template ` +
+          `sql\`...\${value}...\` (js-bun-db.mdc): ${v.snippet}`
+      )
+    } else {
+      fail(
+        `js-bun-db: ${rel}:${v.line} — ${JSON.stringify(v.name)} — це pg-format-специфічний escape-хелпер; ` +
+          `з Bun SQL він не потрібен (параметризація через tagged template), видали і перепиши call-site ` +
+          `(js-bun-db.mdc): ${v.snippet}`
+      )
+    }
+  }
+  for (const v of findPgFormatLikeQueryWrapperInText(content, rel)) {
+    counts.queryWrapper++
+    fail(
+      `js-bun-db: ${rel}:${v.line} — query(text, params)-обгортка над <obj>.unsafe(...) — це прихований ` +
+        `pg-сумісний шим. Видали обгортку (pgRead/pgWrite/db.query) і переведи всі call-site на tagged template ` +
+        `sql\`...\${value}...\` (js-bun-db.mdc): ${v.snippet}`
+    )
+  }
 }
 
 /**
@@ -194,7 +228,7 @@ export async function check() {
     return reporter.getExitCode()
   }
 
-  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard, pgLeftover } =
+  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard, pgLeftover, pgFormatShim, queryWrapper } =
     await scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter)
 
   if (!hasBunSqlImport) {
@@ -220,6 +254,12 @@ export async function check() {
   if (inListGuard === 0) {
     pass('js-bun-db: усі IN-списки винесені у змінні та мають перевірку на пустоту з throw')
   }
+  if (pgFormatShim === 0) {
+    pass('js-bun-db: немає pg-format-сумісних шимів (format/quoteLiteral/quoteIdent/...) у файлах з Bun SQL')
+  }
+  if (queryWrapper === 0) {
+    pass('js-bun-db: немає query(text, params)-обгорток над unsafe(...) у файлах з Bun SQL')
+  }
 
   return reporter.getExitCode()
 }

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

@@ -25,6 +25,7 @@ import {
   offsetToLine,
   parseProgramAndCommentsOrNull,
   parseProgramOrNull,
+  templateQuasisText,
   walkAstWithAncestors
 } from './ast-scan-utils.mjs'
 
@@ -43,6 +44,18 @@ const ALLOW_PG_LEFTOVER_MARKER_RE = /\ballow-pg-leftover\s*:\s*\S+/u
 // формально існують і там, тому опт-аут маркером лишається доречним.
 const PG_LEFTOVER_METHOD_NAMES = new Set(['connect', 'end'])
 
+// pg-format placeholders — `%L` (literal), `%I` (identifier), `%s` (raw string).
+// Якщо у тілі функції з підозрілим іменем зустрічається такий літерал/regex —
+// це pg-format-сумісний шим (drop-in замінник pg-format поверх Bun SQL).
+const PG_FORMAT_PLACEHOLDER_RE = /%[LIs]/u
+// Імена функцій-кандидатів на pg-format-шим. Спрацьовує лише у поєднанні
+// з наявністю `%L` / `%I` / `%s` у тілі — щоб не плутати з невинним `format(date)`.
+const PG_FORMAT_SHIM_FUNC_NAMES = new Set(['format', 'pgFormat', 'sqlFormat', 'pgFmt'])
+// Імена quote/escape-хелперів — самі по собі сильний сигнал pg-format-шиму,
+// без додаткової перевірки тіла. Це pg-format-специфічні API, нерідко публікуються
+// як named export з модуля-обгортки.
+const QUOTE_HELPER_NAMES = new Set(['quoteLiteral', 'quoteIdent', 'escapeLiteral', 'escapeIdent'])
+
 /**
  * @param {unknown} node AST node
  * @param {string} name імʼя змінної
@@ -267,6 +280,185 @@ function asPgLeftoverCall(node) {
   return { name: /** @type {'connect' | 'end'} */ (prop.name) }
 }
 
+/**
+ * Чи це CallExpression `<obj>.unsafe(...)` (для пошуку в тілі query-шиму).
+ * Дублює `isUnsafeCall` з основного скану, але локально — щоб не залежати
+ * від порядку оголошень у файлі.
+ * @param {unknown} node AST node
+ * @returns {boolean} true для `<obj>.unsafe(...)`
+ */
+function isUnsafeCallNode(node) {
+  if (!node || node.type !== 'CallExpression') return false
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return false
+  const prop = callee.property
+  return !!prop && prop.type === 'Identifier' && prop.name === 'unsafe'
+}
+
+/**
+ * Чи містить піддерево вузла рядковий або regex-літерал з `%L` / `%I` / `%s`.
+ * Покриває:
+ * - `Literal` зі строковим `value`,
+ * - `StringLiteral` (oxc),
+ * - `TemplateLiteral` (через текст quasis),
+ * - `RegExpLiteral` / `Literal` з `regex.pattern`.
+ * @param {unknown} root корінь піддерева (зазвичай тіло функції)
+ * @returns {boolean} true, якщо знайдено pg-format-плейсхолдер
+ */
+function nodeContainsPgFormatPlaceholder(root) {
+  let found = false
+  walkAstWithAncestors(root, [], n => {
+    if (found) return
+    const t = n.type
+    if (t === 'Literal' || t === 'StringLiteral') {
+      if (typeof n.value === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(n.value)) {
+        found = true
+        return
+      }
+      const regex = n.regex
+      if (regex && typeof regex.pattern === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(regex.pattern)) {
+        found = true
+        return
+      }
+    }
+    if (t === 'RegExpLiteral' && typeof n.pattern === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(n.pattern)) {
+      found = true
+      return
+    }
+    if (t === 'TemplateLiteral') {
+      if (PG_FORMAT_PLACEHOLDER_RE.test(templateQuasisText(n))) {
+        found = true
+      }
+    }
+  })
+  return found
+}
+
+/**
+ * Витягає (name, body) з вузла, що оголошує функцію верхнього рівня:
+ * - `function format(...) {...}`,
+ * - `const format = (...) => {...}` / `= function(...) {...}`.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {{ name: string, body: unknown } | null} ім'я та тіло, або null
+ */
+function asNamedFunctionDecl(node) {
+  if (node.type === 'FunctionDeclaration' && node.id?.type === 'Identifier') {
+    return { name: node.id.name, body: node.body }
+  }
+  if (node.type === 'VariableDeclarator' && node.id?.type === 'Identifier') {
+    const init = node.init
+    if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+      return { name: node.id.name, body: init.body }
+    }
+  }
+  return null
+}
+
+/**
+ * Знаходить визначення pg-format-сумісних шимів у джерелі. Прапорує:
+ * - функції з іменами `format` / `pgFormat` / `sqlFormat` / `pgFmt`, у тілі яких
+ *   зустрічається літерал/regex з `%L` / `%I` / `%s` — це drop-in pg-format;
+ * - функції з іменами `quoteLiteral` / `quoteIdent` / `escapeLiteral` / `escapeIdent`
+ *   незалежно від тіла — це pg-format-специфічні API, не потрібні з Bun SQL.
+ *
+ * Скан запускається лише в файлах, де є `import { sql|SQL } from 'bun'`, щоб
+ * не плутати, наприклад, форматер дат чи URL-escape з SQL-шимом.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, kind: 'format_function' | 'quote_helper', name: string }[]} список порушень
+ */
+export function findPgFormatShimDefinitionInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string, kind: 'format_function' | 'quote_helper', name: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    const decl = asNamedFunctionDecl(node)
+    if (!decl) return
+    /** @type {'format_function' | 'quote_helper' | null} */
+    let kind = null
+    if (QUOTE_HELPER_NAMES.has(decl.name)) {
+      kind = 'quote_helper'
+    } else if (PG_FORMAT_SHIM_FUNC_NAMES.has(decl.name) && nodeContainsPgFormatPlaceholder(decl.body)) {
+      kind = 'format_function'
+    }
+    if (!kind) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, Math.min(node.end, node.start + 240))),
+      kind,
+      name: decl.name
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить pg-сумісні query-обгортки виду
+ * `{ query(text, params) { return <sql>.unsafe(text, params) } }`
+ * у файлах, що імпортують Bun SQL. Така обгортка маскує `unsafe` під
+ * «безпечним» ім'ям і повертає injection-поверхню в код.
+ *
+ * Спрацьовує, коли всі умови виконані:
+ * - вузол — `Property` з `key.name === 'query'` всередині `ObjectExpression`;
+ * - значення — функція з 1–2 параметрами, перший — Identifier з типовим
+ *   pg-іменем (`text` / `sql` / `query`);
+ * - у тілі функції є виклик `<obj>.unsafe(...)`.
+ *
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findPgFormatLikeQueryWrapperInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (node.type !== 'ObjectExpression') return
+    const properties = node.properties
+    if (!Array.isArray(properties)) return
+    for (const prop of properties) {
+      if (!prop || prop.type !== 'Property') continue
+      const key = prop.key
+      const keyName =
+        key && key.type === 'Identifier' ? key.name : key && key.type === 'Literal' ? key.value : null
+      if (keyName !== 'query') continue
+      const value = prop.value
+      if (!value || (value.type !== 'FunctionExpression' && value.type !== 'ArrowFunctionExpression')) continue
+      const params = value.params
+      const firstName = Array.isArray(params) && params[0]?.type === 'Identifier' ? params[0].name : null
+      const looksLikePgQuery =
+        Array.isArray(params) && params.length >= 1 && params.length <= 2 && /^(text|sql|query)$/u.test(firstName || '')
+      if (!looksLikePgQuery) continue
+      if (!nodeContainsUnsafeCall(value.body)) continue
+      out.push({
+        line: offsetToLine(content, prop.start),
+        snippet: normalizeSnippet(content.slice(prop.start, prop.end))
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * Чи є у піддереві виклик `<obj>.unsafe(...)`.
+ * @param {unknown} root корінь піддерева
+ * @returns {boolean} true, якщо знайдено
+ */
+function nodeContainsUnsafeCall(root) {
+  let found = false
+  walkAstWithAncestors(root, [], n => {
+    if (found) return
+    if (isUnsafeCallNode(n)) found = true
+  })
+  return found
+}
+
 /**
  * Знаходить `new SQL(...)` всередині функцій (handler на кожен запит замість singleton).
  * @param {string} content вихідний код