@nitra/cursor 1.8.159 → 1.8.160

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.160] - 2026-05-01
+
+### Changed
+
+- `js-bun-db.mdc` (v1.4): `sql.unsafe(...)` тепер заборонено за замовчуванням — допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням; інакше переробляємо на tagged template `sql\`...${value}...\``. Кожен легітимний виклик має супроводжуватись маркером `// allow-unsafe: <причина>` на тому ж рядку або рядком вище.
+- `check-js-bun-db.mjs`: замість вузької перевірки `sql.unsafe(\`...${expr}...\`)` тепер сканер `findBunSqlUnsafeUseWithoutAllowMarkerInText` падає на будь-якому `<obj>.unsafe(...)` без маркера-коментаря з непорожньою причиною (line- або block-коментар на тому ж рядку чи безпосередньо перед викликом).
+- `ast-scan-utils.mjs`: додано `parseProgramAndCommentsOrNull` — окремий вхід для перевірок, яким потрібні коментарі поряд з AST.
+
 ## [1.8.159] - 2026-05-01
 
 ### Added

package/mdc/js-bun-db.mdc

@@ -1,7 +1,7 @@
 ---
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 alwaysApply: true
-version: '1.3'
+version: '1.4'
 ---
 
 ## Підтримувані версії баз даних
@@ -116,22 +116,43 @@ await sql.begin(async tx => {
 await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
 ```
 
-## Що НЕ робити
+## `sql.unsafe(...)` за замовчуванням заборонено
+
+Будь-який виклик `sql.unsafe(...)` (так само `tx.unsafe(...)` всередині `sql.begin`) **заборонено**, окрім випадків, коли **обидві** умови виконані:
+
+1. значення підставляється з **коду** — константа, конфіг, whitelist; **не з user input**;
+2. треба підставити те, що **не можна параметризувати** через tagged template:
+   - назву **таблиці**,
+   - назву **колонки**,
+   - **dynamic SQL / DDL** (`CREATE`, `ALTER`, `DROP`, multi-statement migration, серверні `SET`/`SHOW` і подібне).
+
+В усіх інших випадках — переробити на звичайний tagged template `sql\`...\${value}...\``: значення біндяться як параметри й injection не лишається.
 
-### Не використовувати `sql.unsafe(...)` з конкатенацією
+Кожен легітимний `sql.unsafe(...)` має супроводжуватись **маркером-коментарем** з причиною — на тому ж рядку (trailing) або на рядку безпосередньо перед викликом. Маркер — opt-in для перевірки `js-bun-db` і слід для ревʼюера:
 
 ```javascript
-// ❌ конкатенація даних у SQL — SQL injection
+// allow-unsafe: DDL — назву таблиці параметризувати не можна
+await sql.unsafe(`CREATE TABLE ${tableName} (id int)`)
+
+await sql.unsafe('SELECT pg_advisory_lock($1)', [lockId]) // allow-unsafe: pg_advisory_lock — окремий шлях, без tagged template
+```
+
+Формат маркера: `allow-unsafe: <непорожня причина>` у line- або block-коментарі. Без причини (`// allow-unsafe:`) і без маркера взагалі — **fail** перевірки.
+
+❌ Заборонені кейси (треба переробити на tagged template):
+
+```javascript
+// ❌ дані від користувача — параметризуй через tagged template
 await sql.unsafe(`SELECT * FROM users WHERE id = ${userId}`)
 
 // ❌ навіть у tagged template — динамічний список через .join(',')
 await sql`SELECT * FROM users WHERE id IN (${ids.join(',')})`
 ```
 
-`sql.unsafe(text, params)` допустимий лише для **статичного** SQL без даних від користувача (наприклад, разовий DDL-скрипт), і обов'язково з масивом параметрів — ніяких `${...}` у самому рядку.
-
 Для динамічних списків — `sql([...])` або `sql(rows, 'colA', 'colB')`, **не** `.join(',')`.
 
+## Що НЕ робити
+
 ### Не створювати підключення на кожен запит
 
 ```javascript

package/package.json

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

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

@@ -10,7 +10,11 @@
  * 2) Якщо в коді використовується Bun SQL (імпорт `sql`/`SQL` з `'bun'`), додатково
  *    перевіряє небезпечні патерни:
  *    - `new SQL(...)` всередині функції (пул має бути singleton на рівні модуля).
- *    - `sql.unsafe(\`...${expr}...\`)` (інтерполяція даних у `unsafe` ламає параметризацію).
+ *    - Будь-який `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ *      на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено;
+ *      допустимий лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL,
+ *      коли значення контролюється кодом (не user input) — в інших випадках
+ *      переробляємо на tagged template `sql\`...\${value}...\``.
  *    - Динамічні SQL-списки через `.join(',')` у `IN (...)` / `VALUES (...)`
  *      (треба `sql([...])`).
  */
@@ -21,9 +25,9 @@ import { join, relative, sep } from 'node:path'
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import {
   findBunSqlPerRequestConnectionInText,
+  findBunSqlUnsafeUseWithoutAllowMarkerInText,
   findUnsafeBunSqlDynamicSqlListInText,
   findUnsafeBunSqlInListMissingEmptyGuardInText,
-  findUnsafeBunSqlUnsafeCallInText,
   isBunSqlScanSourceFile,
   textHasBunSqlImport
 } from './utils/bun-sql-scan.mjs'
@@ -155,11 +159,14 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
         `тримай singleton на рівні модуля (js-bun-db.mdc): ${v.snippet}`
     )
   }
-  for (const v of findUnsafeBunSqlUnsafeCallInText(content, rel)) {
+  for (const v of findBunSqlUnsafeUseWithoutAllowMarkerInText(content, rel)) {
     counts.unsafeCall++
     fail(
-      `js-bun-db: ${rel}:${v.line} — sql.unsafe(\`...\${...}...\`) недопустимо: ` +
-        `використовуй tagged template sql\`...\${value}...\` або sql.unsafe('static', [params]) (js-bun-db.mdc): ${v.snippet}`
+      `js-bun-db: ${rel}:${v.line} — sql.unsafe(...) заборонено за замовчуванням; ` +
+        `допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням, ` +
+        `інакше переробити на tagged template sql\`...\${value}...\`. ` +
+        `Якщо випадок легітимний — додай маркер "// allow-unsafe: <причина>" на тому ж рядку або рядком вище ` +
+        `(js-bun-db.mdc): ${v.snippet}`
     )
   }
   for (const v of findUnsafeBunSqlDynamicSqlListInText(content, rel)) {
@@ -245,7 +252,7 @@ export async function check() {
     pass('js-bun-db: немає створення new SQL(...) всередині функцій (singleton на рівні модуля)')
   }
   if (unsafeCall === 0) {
-    pass('js-bun-db: немає небезпечних викликів sql.unsafe з інтерполяцією в шаблонному рядку')
+    pass('js-bun-db: усі sql.unsafe(...) або відсутні, або супроводжуються маркером "// allow-unsafe: <причина>"')
   }
   if (dynamicList === 0) {
     pass("js-bun-db: немає небезпечних динамічних SQL-списків через .join(',') у IN/VALUES")

package/scripts/utils/ast-scan-utils.mjs

@@ -112,6 +112,29 @@ export function parseProgramOrNull(content, virtualPath) {
   return result.program
 }
 
+/**
+ * Парсить файл і повертає `{ program, comments }` або null. Окремий вхід для перевірок,
+ * яким потрібні коментарі (наприклад, маркер `// allow-unsafe: ...` біля виклику) —
+ * базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
+ * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null}
+ */
+export function parseProgramAndCommentsOrNull(content, virtualPath) {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath || 'scan.ts', content, { lang, sourceType: 'module' })
+  } catch {
+    return null
+  }
+  if (result.errors?.length) return null
+  return {
+    program: result.program,
+    comments: Array.isArray(result.comments) ? result.comments : []
+  }
+}
+
 /**
  * Чи це `.join(...)` виклик (типово для динамічних списків у SQL).
  * @param {unknown} node AST node

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

@@ -4,9 +4,11 @@
  * Знаходить:
  * - `new SQL(...)` всередині функції — пул має бути singleton на рівні модуля,
  *   а не на кожен виклик handler-а.
- * - Виклик `sql.unsafe(\`...${expr}...\`)` з даними у TemplateLiteral —
- *   `sql.unsafe` приймає лише статичний SQL (плюс масив параметрів); інтерполяція
- *   у текст руйнує параметризацію і відкриває SQL injection.
+ * - Будь-який виклик `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ *   на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
+ *   тільки якщо значення контролюється кодом (не user input) і потрібно підставити
+ *   назву таблиці/колонки або dynamic SQL/DDL. Інакше — переробити на tagged template
+ *   `sql\`...\${value}...\``. Маркер фіксує цю причину для ревʼюера.
  * - Динамічні SQL-списки у tagged template `sql\`... IN (${arr.join(',')}) ...\``:
  *   навіть «через tagged template» у запит потрапляє готовий шматок SQL замість
  *   параметризованих значень — треба `sql([...])`.
@@ -21,6 +23,7 @@ import {
   isSqlListContextTemplate,
   normalizeSnippet,
   offsetToLine,
+  parseProgramAndCommentsOrNull,
   parseProgramOrNull,
   walkAstWithAncestors
 } from './ast-scan-utils.mjs'
@@ -28,6 +31,9 @@ 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
 const IN_PLACEHOLDER_END_RE = /\bin\s*(\(\s*)?$/iu
+// `// allow-unsafe: <reason>` — `allow-unsafe`, двокрапка, **непорожня** причина.
+// Без причини маркер не приймається: ціль — лишити слід для ревʼюера, а не «німий» прапорець.
+const ALLOW_UNSAFE_MARKER_RE = /\ballow-unsafe\s*:\s*\S+/u
 
 /**
  * @param {unknown} node AST node
@@ -192,23 +198,46 @@ function isNewSqlConstructor(node) {
 }
 
 /**
- * Чи це виклик `<obj>.unsafe(...)` з TemplateLiteral як першим аргументом і expressions усередині нього.
- * Допустимий лише `sql.unsafe('static text', [params])`; з `${...}` у TemplateLiteral — небезпечно.
+ * Чи це виклик `<obj>.unsafe(...)` (будь-який обʼєкт, не тільки `sql`).
+ * Файл сканується лише якщо є `import { sql|SQL } from 'bun'`, тож у практиці це
+ * або `sql.unsafe`, або `tx.unsafe` всередині `sql.begin(async tx => ...)` —
+ * обидва однаково небезпечні, тому розрізняти імʼя обʼєкта не треба.
  * @param {unknown} node AST node
- * @returns {boolean} true для небезпечного `sql.unsafe(\`... ${x} ...\`)`
+ * @returns {boolean} true для будь-якого `<obj>.unsafe(...)`
  */
-function isUnsafeCallWithInterpolatedTemplate(node) {
+function isUnsafeCall(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
-  if (!prop || prop.type !== 'Identifier' || prop.name !== 'unsafe') return false
-  const args = node.arguments
-  if (!Array.isArray(args) || args.length === 0) return false
-  const first = args[0]
-  if (!first || first.type !== 'TemplateLiteral') return false
-  const expressions = first.expressions
-  return Array.isArray(expressions) && expressions.length > 0
+  return !!prop && prop.type === 'Identifier' && prop.name === 'unsafe'
+}
+
+/**
+ * Чи є біля виклику `<obj>.unsafe(...)` маркер-коментар `// allow-unsafe: <reason>`
+ * (або `/* allow-unsafe: <reason> *\/`) на тому ж рядку, що й початок виклику,
+ * або на рядку, що передує початку виклику. Це навмисно строга суміжність:
+ * відірваний коментар через порожній рядок не зараховується — щоб маркер
+ * стояв саме біля виклику, а не «загубився десь вище».
+ * @param {{ start: number }} callNode виклик `<obj>.unsafe(...)`
+ * @param {{ type: 'Line' | 'Block', value: string, start: number, end: number }[]} comments коментарі з парсера
+ * @param {string} content вихідний код
+ * @returns {boolean} true, якщо маркер знайдено
+ */
+function hasAllowUnsafeMarkerNear(callNode, comments, content) {
+  const callStartLine = offsetToLine(content, callNode.start)
+  for (const c of comments) {
+    if (!c || (c.type !== 'Line' && c.type !== 'Block')) continue
+    if (typeof c.value !== 'string' || !ALLOW_UNSAFE_MARKER_RE.test(c.value)) continue
+    const startLine = offsetToLine(content, c.start)
+    const endLine = offsetToLine(content, c.end)
+    // trailing-коментар на тому ж рядку (`sql.unsafe(...) // allow-unsafe: ...`)
+    if (startLine === callStartLine) return true
+    // коментар на рядку, що безпосередньо передує виклику — для блокових
+    // коментарів важливим є саме `endLine`, бо block може займати кілька рядків.
+    if (endLine === callStartLine - 1) return true
+  }
+  return false
 }
 
 /**
@@ -236,19 +265,28 @@ export function findBunSqlPerRequestConnectionInText(content, virtualPath = 'sca
 }
 
 /**
- * Знаходить виклики `sql.unsafe(\`...${...}...\`)` (TemplateLiteral з expressions).
+ * Знаходить виклики `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ * на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
+ * лише коли значення контролюється кодом (не user input) і потрібно підставити те, що
+ * не можна параметризувати — назву таблиці/колонки або dynamic SQL/DDL. У всіх інших
+ * випадках — переробити на tagged template `sql\`...\${value}...\``.
+ *
+ * Маркер-коментар фіксує причину для ревʼюера й одночасно слугує opt-in: без нього
+ * перевірка падає, навіть якщо у `unsafe` лежить статичний рядок без інтерполяції.
  * @param {string} content вихідний код
  * @param {string} [virtualPath] шлях для вибору `lang`
  * @returns {{ line: number, snippet: string }[]} список порушень
  */
-export function findUnsafeBunSqlUnsafeCallInText(content, virtualPath = 'scan.ts') {
-  const program = parseProgramOrNull(content, virtualPath)
-  if (!program) return []
+export function findBunSqlUnsafeUseWithoutAllowMarkerInText(content, virtualPath = 'scan.ts') {
+  const parsed = parseProgramAndCommentsOrNull(content, virtualPath)
+  if (!parsed) return []
+  const { program, comments } = parsed
 
   /** @type {{ line: number, snippet: string }[]} */
   const out = []
   walkAstWithAncestors(program, [], node => {
-    if (!isUnsafeCallWithInterpolatedTemplate(node)) return
+    if (!isUnsafeCall(node)) return
+    if (hasAllowUnsafeMarkerNear(node, comments, content)) return
     out.push({
       line: offsetToLine(content, node.start),
       snippet: normalizeSnippet(content.slice(node.start, node.end))