@nitra/cursor 1.8.150 → 1.8.152

package/AGENTS.template.md

@@ -18,6 +18,14 @@ The primary development rules are stored in the Cursor rules directory:
 {{name}}
 {{/skills}}
 
+## Commands
+
+Generated from the root `package.json` on each `npx @nitra/cursor` sync. Prefer `bun run <script>` for project scripts.
+
+{{#commands}}
+{{name}}
+{{/commands}}
+
 ## Instructions for all agents
 
 Before making changes, read the relevant rule files for the area you are working on.

package/README.md

@@ -63,7 +63,7 @@ CLI автоматично (команда завантаження правил
 1. Знайде або створить `.n-cursor.json` у поточній директорії (із полем `$schema` на JSON Schema пакету; якщо файл уже є без коректного `$schema`, поле буде додано або оновлено при зчитуванні конфігу)
 2. Створить директорію `.cursor/rules/`, якщо її ще немає
 3. Скопіює кожне з перелічених у конфігу правило з `mdc/` установленого пакету і збереже файли з префіксом `n-`
-4. Після оновлення файлів на диску згенерує в корені проєкту **`AGENTS.md`**: повний вміст береться з шаблону пакету `AGENTS.template.md`, а список правил у шаблоні формується з **усіх наявних файлів `*.mdc`** у `.cursor/rules/` (відсортовано за ім’ям)
+4. Після оновлення файлів на диску згенерує в корені проєкту **`AGENTS.md`**: повний вміст береться з шаблону пакету `AGENTS.template.md`, а список правил у шаблоні формується з **усіх наявних файлів `*.mdc`** у `.cursor/rules/` (відсортовано за ім’ям); секція команд — з **`package.json`** кореня (див. `{{#commands}}` у шаблоні).
 
 ## Приклад виводу
 
@@ -114,13 +114,18 @@ npm/
 
 Під час запуску CLI тіло між `{{#services}}` і `{{/services}}` повторюється для кожного `*.mdc` у `.cursor/rules/`; у `{{name}}` підставляється вже готовий markdown-рядок (наприклад `- .cursor/rules/n-text.mdc`).
 
-3. Після змін у шаблоні перевірте локально: у тестовому репозиторії з `.n-cursor.json` виконайте `npx`/`bunx` на зібраному пакеті або `node npm/bin/n-cursor.js` з кореня того репозиторію і переконайтеся, що **`AGENTS.md`** виглядає як очікується.
+3. Для секції **Skills** використовуйте блок **`{{#skills}}` … `{{/skills}}`** з тим самим `{{name}}`: рядки формуються з каталогів у `.cursor/skills/` (див. також `buildSkillBulletItems` у `bin/n-cursor.js`).
+
+4. Для секції **Commands** використовуйте **`{{#commands}}` … `{{/commands}}`**: список генерується з кореневого **`package.json`** (поле `scripts` — відомі ключі у фіксованому порядку, плюс додаткові `lint-*`) та завжди доповнюється рядками про **`npx @nitra/cursor`** і **`npx @nitra/cursor check`**. Логіка винесена в **`npm/scripts/build-agents-commands.mjs`**.
+
+5. Після змін у шаблоні перевірте локально: у тестовому репозиторії з `.n-cursor.json` виконайте `npx`/`bunx` на зібраному пакеті або `node npm/bin/n-cursor.js` з кореня того репозиторію і переконайтеся, що **`AGENTS.md`** виглядає як очікується.
 
 ### Логіка в коді CLI
 
 - Шлях до шаблону: поруч із `mdc/`, тобто `…/node_modules/@nitra/cursor/AGENTS.template.md` після встановлення пакету.
 - Оновлення **`AGENTS.md`** виконується **після** циклу завантаження правил, щоб список відображав актуальний вміст `.cursor/rules/` на диску.
 - Якщо каталогу `.cursor/rules/` немає або в ньому немає `*.mdc`, блок `{{#services}}` стає порожнім; решта шаблону все одно записується в **`AGENTS.md`**.
+- Секція **`commands`** залежить лише від **`package.json` у корені cwd**; якщо файлу немає або `scripts` відсутній, у блоці лишаються мінімальні рядки (`bun i`, виклики CLI).
 
 ## Мета проекту
 

package/bin/n-cursor.js

@@ -18,6 +18,7 @@
  *
  * Файл AGENTS.md у корені: щоразу повністю перезаписується змістом з AGENTS.template.md
  * пакету; список правил у шаблоні будується з файлів *.mdc у .cursor/rules поточного проєкту.
+ * Секція команд — з кореневого package.json (scripts) та фіксовані рядки про CLI синхрону/перевірок.
  *
  * Після завантаження: у .cursor/rules видаляються файли *.mdc з префіксом «n-» (керовані
  * пакетом), яких немає у списку rules у .n-cursor.json. Інші .mdc у цій директорії залишаються.
@@ -45,6 +46,7 @@ import { basename, dirname, join } from 'node:path'
 import { cwd } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
+import { buildAgentsCommandBulletItems } from '../scripts/build-agents-commands.mjs'
 import { detectAutoRulesAndSkills, mergeConfigWithAutoDetected, normalizeIdList } from '../scripts/auto-rules.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
 import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
@@ -424,19 +426,21 @@ function expandMustacheSection(template, section, items, prop) {
 }
 
 /**
- * Підставляє у вміст AGENTS.template.md список шляхів до файлів правил і skills
+ * Підставляє у вміст AGENTS.template.md список шляхів до файлів правил, skills і команд з package.json
  * @param {string} templateText вміст AGENTS.template.md
  * @param {string[]} mdcBasenames імена файлів (*.mdc) з .cursor/rules
  * @param {{ name: string }[]} skillItems рядки для секції Skills
+ * @param {{ name: string }[]} commandItems рядки для секції commands
  * @returns {string} готовий markdown для AGENTS.md
  */
-function renderAgentsTemplate(templateText, mdcBasenames, skillItems) {
+function renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems) {
   let result = templateText
   const serviceItems = mdcBasenames.map(mdcName => ({
     name: `- ${RULES_DIR}/${mdcName}`
   }))
   result = expandMustacheSection(result, 'services', serviceItems, 'name')
   result = expandMustacheSection(result, 'skills', skillItems, 'name')
+  result = expandMustacheSection(result, 'commands', commandItems, 'name')
   return result
 }
 
@@ -650,7 +654,8 @@ async function syncAgentsMd(agentsTemplatePath = BUNDLED_AGENTS_TEMPLATE_PATH) {
   const templateText = await readFile(agentsTemplatePath, 'utf8')
   const mdcFiles = await listProjectRulesMdcFiles()
   const skillItems = await buildSkillBulletItems()
-  const body = renderAgentsTemplate(templateText, mdcFiles, skillItems)
+  const commandItems = await buildAgentsCommandBulletItems(cwd())
+  const body = renderAgentsTemplate(templateText, mdcFiles, skillItems, commandItems)
   const agentsPath = join(cwd(), AGENTS_FILE)
   const hadFile = existsSync(agentsPath)
   const out = body.endsWith('\n') ? body : `${body}\n`

package/mdc/js-bun-db.mdc

@@ -1,7 +1,7 @@
 ---
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 alwaysApply: true
-version: '1.1'
+version: '1.2'
 ---
 
 ## Підтримувані версії баз даних
@@ -72,6 +72,22 @@ const ids = [1, 2, 3]
 await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
 ```
 
+## `IN (...)`: значення з template literal — тільки через змінну + guard на пустоту
+
+Якщо список для `IN (...)` підставляється через `${...}` у template literal, його **потрібно**:
+
+- винести в **окрему змінну** (не підставляти вираз напряму в `${...}`);
+- **перевірити на пустоту** перед запитом і **throw** (щоб не виконувати некоректний SQL або запит з неочікуваною семантикою).
+
+Приклад:
+
+```javascript
+const ids = inputIds.map(Number).filter(n => Number.isFinite(n))
+if (!ids.length) throw new Error('ids is empty')
+
+await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
+```
+
 Транзакції — через `sql.begin` (auto-commit/rollback), вкладені — через `tx.savepoint`:
 
 ```javascript
@@ -81,6 +97,23 @@ await sql.begin(async tx => {
 })
 ```
 
+## Коментар під час виправлення SQL injection
+
+Коли виправляєш місце з потенційним **SQL injection** (наприклад, заміна конкатенації/`.join(',')` на `sql(ids)` або перехід з `sql.unsafe(...)` на tagged template), **додай поруч короткий коментар** з описом причини.
+
+Вимоги до коментаря:
+
+- пояснити **що саме було небезпечно** (конкатенація, підмішування user input, динамічний `IN (...)`, тощо);
+- пояснити **чому новий варіант безпечний** (параметризація через tagged template / `sql(...)`);
+- без “романів”: 1–2 рядки, достатньо для ревʼю.
+
+Приклад:
+
+```javascript
+// SQLi fix: не конкатенуємо значення в `IN (...)`; Bun parameterize через `sql(ids)`.
+await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
+```
+
 ## Що НЕ робити
 
 ### Не використовувати `sql.unsafe(...)` з конкатенацією

package/mdc/js-mssql.mdc

@@ -1,7 +1,7 @@
 ---
 description: Використання mssql в nodejs
 alwaysApply: true
-version: '1.2'
+version: '1.3'
 ---
 
 ## Підтримувана версія SQL Server
@@ -54,6 +54,23 @@ const result = await pool.request().query`
 
 Ключове: pool.request().query\...`— бекті́ки післяquery`, без круглих дужок. Це той самий tagged template, тільки контекст — конкретний пул, а не глобальний.
 
+## Коментар під час виправлення SQL injection
+
+Коли виправляєш місце з потенційним **SQL injection** (наприклад, заміна `query(\`...\`)` на `query\`...\`` або прибирання динамічних списків/конкатенації), **додай поруч короткий коментар** з описом причини.
+
+Вимоги до коментаря:
+
+- вказати **що було небезпечно** (звичайна інтерполяція в рядок, конкатенація, динамічний список);
+- вказати **чому новий варіант безпечний** (tagged template / параметризація / TVP);
+- 1–2 рядки, без дублювання очевидного.
+
+Приклад:
+
+```javascript
+// SQLi fix: query`...` (tagged template) параметризує значення; query(`...`) небезпечний через інтерполяцію.
+await pool.request().query`SELECT * FROM users WHERE id = ${userId}`
+```
+
 ## Що НЕ робити
 
 ### Не робити `query(\`...\`)`
@@ -166,6 +183,11 @@ WHERE NOT EXISTS (
 
 Якщо `IN (...)` все ж використовується (а не `JOIN` на TVP), значення в `${...}` **обовʼязково** мають бути попередньо приведені числовим парсером і відфільтровані від `NaN`. Це знімає будь-яку можливість SQL injection: SQL-метасимволи в `Number`/`parseInt(...)` перетворюються на `NaN` і відсіюються.
 
+Додатково:
+
+- значення для `IN (${...})` потрібно **винести в окрему змінну** перед запитом (не підставляти вираз напряму в `${...}`);
+- цю змінну потрібно **перевірити на пустоту** і якщо список порожній — **throw error** (щоб не виконувати некоректний запит).
+
 ```javascript
 // ❌ НЕ МОЖНА: значення з req.body / зовнішнього джерела без парсингу
 const outIds = pgQ.rows.flatMap(x => x.req_body.Orders.map(o => o.OutletId))
@@ -176,9 +198,11 @@ await pool.query(/* sql */ String.raw`
 
 ```javascript
 // ✅ МОЖНА: parseInt + filter(!isNaN) гарантує, що в SQL потраплять лише числа
+// і перед запитом робимо guard на пустоту, щоб не виконувати некоректний SQL.
 const outIds = pgQ.rows
   .flatMap(x => x.req_body.Orders.map(o => parseInt(o.OutletId)))
   .filter(n => !isNaN(n))
+if (!outIds.length) throw new Error('outIds is empty')
 await pool.request().query`
   SELECT ... WHERE so.OutletId IN (${outIds})
 `

package/package.json

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

package/scripts/build-agents-commands.mjs

@@ -0,0 +1,88 @@
+/**
+ * Формує markdown-рядки для секції «Команди» у AGENTS.md.
+ *
+ * Джерело істини — `package.json` у корені цільового репозиторію: з поля `scripts` беруться відомі ключі
+ * у стабільному порядку, додатково — усі `lint-*`, яких не було в основному списку.
+ *
+ * Наприкінці завжди додаються рядки про CLI `@nitra/cursor` (синхрон правил / programmatic check),
+ * на початку — рекомендована команда `bun i` за конвенціями monorepo.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const PACKAGE_NAME = '@nitra/cursor'
+const AGENTS_MD = 'AGENTS.md'
+
+/** Порядок виводу скриптів із `package.json` (лише ті, що реально існують). */
+const SCRIPT_KEYS_ORDER = /** @type {const} */ ([
+  'test',
+  'lint',
+  'lint-js',
+  'lint-text',
+  'lint-ga',
+  'lint-k8s',
+  'lint-docker',
+  'start',
+  'dev',
+  'build'
+])
+
+/**
+ * Зчитує `scripts` з `package.json` у `projectRoot` або повертає порожній об'єкт.
+ * @param {string} projectRoot абсолютний шлях до кореня репозиторію
+ * @returns {Promise<Record<string, string>>} об'єкт скриптів
+ */
+async function readPackageScripts(projectRoot) {
+  const pkgPath = join(projectRoot, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return {}
+  }
+  try {
+    const raw = await readFile(pkgPath, 'utf8')
+    const pkg = JSON.parse(raw)
+    if (pkg && typeof pkg === 'object' && pkg.scripts && typeof pkg.scripts === 'object') {
+      return /** @type {Record<string, string>} */ (pkg.scripts)
+    }
+  } catch {
+    // некоректний JSON або IO — секція команд лишиться з мінімумом (bun i + npx)
+  }
+  return {}
+}
+
+/**
+ * Повертає елементи для Mustache-секції `commands` у AGENTS.template.md.
+ * @param {string} projectRoot абсолютний шлях до кореня репозиторію (зазвичай `process.cwd()`)
+ * @returns {Promise<{ name: string }[]>} рядки з полем `name` для `expandMustacheSection`
+ */
+export async function buildAgentsCommandBulletItems(projectRoot) {
+  const scripts = await readPackageScripts(projectRoot)
+  const items = /** @type {{ name: string }[]} */ ([])
+
+  items.push({ name: `- **Залежності**: \`bun i\`` })
+
+  const added = new Set()
+
+  for (const key of SCRIPT_KEYS_ORDER) {
+    if (typeof scripts[key] === 'string' && scripts[key].length > 0) {
+      items.push({ name: `- **${key}**: \`bun run ${key}\`` })
+      added.add(key)
+    }
+  }
+
+  const lintExtraKeys = Object.keys(scripts)
+    .filter(k => k.startsWith('lint-') && !added.has(k) && typeof scripts[k] === 'string')
+    .toSorted((a, b) => a.localeCompare(b))
+
+  for (const key of lintExtraKeys) {
+    items.push({ name: `- **${key}**: \`bun run ${key}\`` })
+    added.add(key)
+  }
+
+  items.push({
+    name: `- **Оновити правила та ${AGENTS_MD}** (після змін у правилах/шаблоні CLI): \`npx ${PACKAGE_NAME}\``
+  })
+  items.push({ name: `- **Перевірки правил (programmatic)**: \`npx ${PACKAGE_NAME} check\`` })
+
+  return items
+}

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

@@ -20,6 +20,7 @@ import { createCheckReporter } from './utils/check-reporter.mjs'
 import {
   findBunSqlPerRequestConnectionInText,
   findUnsafeBunSqlDynamicSqlListInText,
+  findUnsafeBunSqlInListMissingEmptyGuardInText,
   findUnsafeBunSqlUnsafeCallInText,
   isBunSqlScanSourceFile,
   textHasBunSqlImport
@@ -125,6 +126,7 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
   let perRequest = 0
   let unsafeCall = 0
   let dynamicList = 0
+  let inListGuard = 0
 
   for (const absPath of sourcePaths) {
     const rel = relative(repoRoot, absPath).split('\\').join('/')
@@ -154,9 +156,28 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
           `у IN (...) / VALUES (...); використовуй sql([...]) (js-bun-db.mdc): ${v.snippet}`
       )
     }
+    for (const v of findUnsafeBunSqlInListMissingEmptyGuardInText(content, rel)) {
+      inListGuard++
+      if (v.reason === 'missing_guard') {
+        fail(
+          `js-bun-db: ${rel}:${v.line} — перед IN-списком ${JSON.stringify(v.name)} потрібна перевірка на пустоту ` +
+            `з throw (наприклад if (!${v.name}.length) throw ...), інакше можливі некоректні запити (js-bun-db.mdc): ${v.snippet}`
+        )
+      } else if (v.reason === 'sql_helper_not_var') {
+        fail(
+          `js-bun-db: ${rel}:${v.line} — IN-список у \${sql(...)} має підставлятись зі змінної (Identifier) ` +
+            `після валідації на пустоту + throw (js-bun-db.mdc): ${v.snippet}`
+        )
+      } else {
+        fail(
+          `js-bun-db: ${rel}:${v.line} — значення для IN (...) у template literal треба винести в окрему змінну ` +
+            `і перевірити на пустоту (throw), не підставляти вираз напряму (js-bun-db.mdc): ${v.snippet}`
+        )
+      }
+    }
   }
 
-  return { hasBunSqlImport, perRequest, unsafeCall, dynamicList }
+  return { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard }
 }
 
 /**
@@ -188,7 +209,7 @@ export async function check() {
     return reporter.getExitCode()
   }
 
-  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList } = await scanSourcesForBunSqlPatterns(
+  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard } = await scanSourcesForBunSqlPatterns(
     sourcePaths,
     repoRoot,
     reporter
@@ -208,6 +229,9 @@ export async function check() {
   if (dynamicList === 0) {
     pass("js-bun-db: немає небезпечних динамічних SQL-списків через .join(',') у IN/VALUES")
   }
+  if (inListGuard === 0) {
+    pass('js-bun-db: усі IN-списки винесені у змінні та мають перевірку на пустоту з throw')
+  }
 
   return reporter.getExitCode()
 }

package/scripts/check-js-mssql.mjs

@@ -19,6 +19,7 @@ import {
   findUnsafeMssqlQueryTemplateCallInText,
   findUnsafeMssqlDynamicSqlListInText,
   findUnsafeMssqlInListUnparsedInText,
+  findUnsafeMssqlInListMissingEmptyGuardInText,
   isMssqlScanSourceFile
 } from './utils/mssql-pool-scan.mjs'
 import { walkDir } from './utils/walkDir.mjs'
@@ -203,6 +204,20 @@ function scanMssqlOneSourceFile(rel, content, counters, fail) {
       `js-mssql: ${rel}:${v.line} — у SQL IN (\${...}) значення мають бути попередньо приведені числовим парсером (parseInt/Number/BigInt/parseFloat) і відфільтровані від NaN, інакше можливий SQL injection (js-mssql.mdc): ${v.snippet}`
     )
   }
+  for (const v of findUnsafeMssqlInListMissingEmptyGuardInText(content, rel)) {
+    counters.inListGuardViolations++
+    if (v.reason === 'missing_guard') {
+      fail(
+        `js-mssql: ${rel}:${v.line} — перед IN-списком ${JSON.stringify(v.name)} потрібна перевірка на пустоту з throw ` +
+          `(наприклад if (!${v.name}.length) throw ...), інакше можливі некоректні запити (js-mssql.mdc): ${v.snippet}`
+      )
+    } else {
+      fail(
+        `js-mssql: ${rel}:${v.line} — значення для IN (\${...}) у template literal треба винести в окрему змінну ` +
+          `і перевірити на пустоту (throw), не підставляти вираз напряму (js-mssql.mdc): ${v.snippet}`
+      )
+    }
+  }
 }
 
 /**
@@ -226,6 +241,9 @@ function reportZeroMssqlSourceViolations(counters, pass) {
   if (counters.unparsedInLists === 0) {
     pass(`js-mssql: немає підстановок IN (\${...}) без числового парсера значень`)
   }
+  if (counters.inListGuardViolations === 0) {
+    pass('js-mssql: усі IN-списки винесені у змінні та мають перевірку на пустоту з throw')
+  }
 }
 
 /**
@@ -247,7 +265,8 @@ async function auditMssqlSources(repoRoot, pass, fail) {
     sharedRequestViolations: 0,
     unsafeQueryCalls: 0,
     unsafeDynamicSqlLists: 0,
-    unparsedInLists: 0
+    unparsedInLists: 0,
+    inListGuardViolations: 0
   }
   for (const absPath of sourcePaths) {
     const rel = relative(repoRoot, absPath).split('\\').join('/')

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

@@ -27,6 +27,157 @@ 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
+
+/**
+ * @param {unknown} node AST node
+ * @param {string} name імʼя змінної
+ * @returns {boolean} true, якщо це MemberExpression `${name}.length`
+ */
+function isLengthMember(node, name) {
+  return (
+    !!node &&
+    typeof node === 'object' &&
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object &&
+    node.object.type === 'Identifier' &&
+    node.object.name === name &&
+    node.property &&
+    node.property.type === 'Identifier' &&
+    node.property.name === 'length'
+  )
+}
+
+/**
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це числовий 0-літерал
+ */
+function isZeroNumberLiteral(node) {
+  return (
+    !!node &&
+    typeof node === 'object' &&
+    ((node.type === 'NumericLiteral' && node.value === 0) || (node.type === 'Literal' && node.value === 0))
+  )
+}
+
+/**
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це Identifier з імʼям `sql`
+ */
+function isSqlHelperIdentifier(node) {
+  return !!node && typeof node === 'object' && node.type === 'Identifier' && node.name === 'sql'
+}
+
+/**
+ * Витягає імʼя змінної списку для `IN ...`:
+ * - `${ids}` → `ids`
+ * - `${sql(ids)}` → `ids`
+ * @param {unknown} expr template expression
+ * @returns {{ name: string } | { error: 'not_var' } | { error: 'sql_helper_not_var' }} імʼя змінної або причина відмови
+ */
+function extractInListVarNameFromExpr(expr) {
+  if (!expr || typeof expr !== 'object') return { error: 'not_var' }
+  if (expr.type === 'Identifier' && typeof expr.name === 'string') return { name: expr.name }
+
+  if (expr.type === 'CallExpression' && isSqlHelperIdentifier(expr.callee)) {
+    const args = expr.arguments
+    if (!Array.isArray(args) || args.length === 0) return { error: 'sql_helper_not_var' }
+    const first = args[0]
+    if (first && typeof first === 'object' && first.type === 'Identifier' && typeof first.name === 'string') {
+      return { name: first.name }
+    }
+    return { error: 'sql_helper_not_var' }
+  }
+
+  return { error: 'not_var' }
+}
+
+/**
+ * Чи містить тест if-умови перевірку “список порожній”.
+ * Підтримує базові форми:
+ * - `if (!ids.length) ...`
+ * - `if (ids.length === 0) ...` / `<= 0` / `< 1`
+ * @param {unknown} test IfStatement.test
+ * @param {string} name імʼя змінної списку
+ * @returns {boolean} true, якщо це перевірка на пустоту списку
+ */
+function isEmptyListTest(test, name) {
+  if (!test || typeof test !== 'object') return false
+
+  if (test.type === 'UnaryExpression' && test.operator === '!') {
+    const arg = test.argument
+    if (!arg || typeof arg !== 'object') return false
+    return isLengthMember(arg, name)
+  }
+
+  if (test.type === 'BinaryExpression') {
+    const { left, right, operator } = test
+    if (!['===', '==', '<=', '<'].includes(operator)) return false
+    if (isLengthMember(left, name) && isZeroNumberLiteral(right)) return true
+    // допускаємо `0 === ids.length` теж
+    if (isZeroNumberLiteral(left) && isLengthMember(right, name) && (operator === '===' || operator === '==')) return true
+  }
+
+  return false
+}
+
+/**
+ * Чи є в consequent (або в його BlockStatement) ThrowStatement.
+ * @param {unknown} consequent IfStatement.consequent
+ * @returns {boolean} true, якщо consequent містить throw
+ */
+function consequentHasThrow(consequent) {
+  if (!consequent || typeof consequent !== 'object') return false
+  if (consequent.type === 'ThrowStatement') return true
+  if (consequent.type === 'BlockStatement' && Array.isArray(consequent.body)) {
+    return consequent.body.some(s => s && typeof s === 'object' && s.type === 'ThrowStatement')
+  }
+  return false
+}
+
+/**
+ * Шукає “guard” `if (empty) throw` перед statementIndex у межах того ж BlockStatement.
+ * @param {unknown} block BlockStatement
+ * @param {number} statementIndex індекс statement, перед яким шукаємо guard
+ * @param {string} name імʼя змінної списку
+ * @returns {boolean} true, якщо guard знайдено
+ */
+function hasEmptyGuardBefore(block, statementIndex, name) {
+  if (!block || typeof block !== 'object' || block.type !== 'BlockStatement') return false
+  const body = block.body
+  if (!Array.isArray(body)) return false
+  for (let i = 0; i < statementIndex; i++) {
+    const st = body[i]
+    if (!st || typeof st !== 'object') continue
+    if (st.type !== 'IfStatement') continue
+    if (!isEmptyListTest(st.test, name)) continue
+    if (!consequentHasThrow(st.consequent)) continue
+    return true
+  }
+  return false
+}
+
+/**
+ * Знаходить найближчий enclosing BlockStatement і statement всередині нього.
+ * @param {unknown[]} ancestors ancestors масив з walkAstWithAncestors
+ * @returns {{ block: unknown, index: number } | null} block+індекс statement або null
+ */
+function findEnclosingBlockAndStatementIndex(ancestors) {
+  if (!Array.isArray(ancestors) || ancestors.length === 0) return null
+
+  // statement — перший зверху вузол, який лежить у block.body
+  // шукаємо пару (block, statement), де statement ∈ block.body
+  for (let i = ancestors.length - 1; i >= 1; i--) {
+    const maybeStatement = ancestors[i]
+    const maybeBlock = ancestors[i - 1]
+    if (!maybeBlock || typeof maybeBlock !== 'object' || maybeBlock.type !== 'BlockStatement') continue
+    if (!Array.isArray(maybeBlock.body)) continue
+    const idx = maybeBlock.body.indexOf(maybeStatement)
+    if (idx !== -1) return { block: maybeBlock, index: idx }
+  }
+  return null
+}
 
 /**
  * Чи це `new SQL(...)` (Identifier callee з імʼям `SQL`).
@@ -139,6 +290,80 @@ export function findUnsafeBunSqlDynamicSqlListInText(content, virtualPath = 'sca
   return out
 }
 
+/**
+ * Збирає порушення для одного TemplateLiteral вузла: `IN ... ${...}` потребує
+ * змінної + guard `if (empty) throw`.
+ * @param {Record<string, unknown>} template TemplateLiteral
+ * @param {unknown[]} ancestors ancestors з walkAstWithAncestors
+ * @param {string} content вихідний код
+ * @param {{ line: number, snippet: string, reason: 'not_var' | 'sql_helper_not_var' | 'missing_guard', name?: string }[]} out буфер результатів
+ */
+function collectInListGuardViolationsFromTemplate(template, ancestors, content, out) {
+  const expressions = template.expressions
+  const quasis = template.quasis
+  if (!Array.isArray(expressions) || expressions.length === 0) return
+  if (!Array.isArray(quasis) || quasis.length === 0) return
+
+  for (const [i, expr] of expressions.entries()) {
+    const q = quasis[i]
+    const raw =
+      q && typeof q === 'object' && q.value && typeof q.value === 'object' && typeof q.value.raw === 'string' ? q.value.raw : ''
+    if (!IN_PLACEHOLDER_END_RE.test(raw)) continue
+
+    const extracted = extractInListVarNameFromExpr(expr)
+    if ('error' in extracted) {
+      out.push({
+        line: offsetToLine(content, template.start),
+        snippet: normalizeSnippet(content.slice(template.start, template.end)),
+        reason: extracted.error
+      })
+      continue
+    }
+
+    const place = findEnclosingBlockAndStatementIndex(ancestors)
+    if (!place || !hasEmptyGuardBefore(place.block, place.index, extracted.name)) {
+      out.push({
+        line: offsetToLine(content, template.start),
+        snippet: normalizeSnippet(content.slice(template.start, template.end)),
+        reason: 'missing_guard',
+        name: extracted.name
+      })
+    }
+  }
+}
+
+/**
+ * Знаходить підстановки списків у `IN (...)`, які:
+ * - не винесені в окрему змінну (в `${...}` стоїть не Identifier або `sql(<non-Identifier>)`);
+ * - або винесені, але перед запитом немає перевірки на пустоту з `throw`.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, reason: 'not_var' | 'sql_helper_not_var' | 'missing_guard', name?: string }[]} список порушень
+ */
+export function findUnsafeBunSqlInListMissingEmptyGuardInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string, reason: 'not_var' | 'sql_helper_not_var' | 'missing_guard', name?: string }[]} */
+  const out = []
+
+  walkAstWithAncestors(program, [], (node, ancestors) => {
+    /** @type {unknown} */
+    let template = null
+    if (node.type === 'TemplateLiteral') {
+      template = node
+    } else if (node.type === 'TaggedTemplateExpression') {
+      template = node.quasi
+    }
+
+    if (!template || typeof template !== 'object' || template.type !== 'TemplateLiteral') return
+    if (!isSqlListContextTemplate(template)) return
+    collectInListGuardViolationsFromTemplate(template, ancestors, content, out)
+  })
+
+  return out
+}
+
 /**
  * Чи містить текст джерела імпорт імені `sql` або `SQL` з `"bun"`.
  * Скан по сирому тексту — без AST, щоб бути дешевим: викликається на кожному

package/scripts/utils/mssql-pool-scan.mjs

@@ -36,6 +36,113 @@ const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/
 const IN_PLACEHOLDER_END_RE = /\bin\s*\(\s*$/iu
 const NUMERIC_PARSE_FN_NAMES = new Set(['parseInt', 'parseFloat', 'Number', 'BigInt'])
 
+/**
+ * Чи містить тест if-умови перевірку “список порожній”.
+ * Підтримує базові форми:
+ * - `if (!ids.length) ...`
+ * - `if (ids.length === 0) ...` / `<= 0` / `< 1`
+ *
+ * @param {unknown} test IfStatement.test
+ * @param {string} name імʼя змінної списку
+ * @returns {boolean}
+ */
+function isEmptyListTest(test, name) {
+  if (!test || typeof test !== 'object') return false
+
+  if (test.type === 'UnaryExpression' && test.operator === '!') {
+    const arg = test.argument
+    if (!arg || typeof arg !== 'object') return false
+    if (arg.type === 'MemberExpression' && !arg.computed) {
+      const obj = arg.object
+      const prop = arg.property
+      return !!obj && obj.type === 'Identifier' && obj.name === name && !!prop && prop.type === 'Identifier' && prop.name === 'length'
+    }
+  }
+
+  if (test.type === 'BinaryExpression') {
+    const { left, right, operator } = test
+    const isLen = node =>
+      !!node &&
+      typeof node === 'object' &&
+      node.type === 'MemberExpression' &&
+      !node.computed &&
+      node.object &&
+      node.object.type === 'Identifier' &&
+      node.object.name === name &&
+      node.property &&
+      node.property.type === 'Identifier' &&
+      node.property.name === 'length'
+    const isZero = node =>
+      !!node &&
+      typeof node === 'object' &&
+      ((node.type === 'NumericLiteral' && node.value === 0) || (node.type === 'Literal' && node.value === 0))
+
+    if (!['===', '==', '<=', '<'].includes(operator)) return false
+    if (isLen(left) && isZero(right)) return true
+    // допускаємо `0 === ids.length` теж
+    if (isZero(left) && isLen(right) && (operator === '===' || operator === '==')) return true
+  }
+
+  return false
+}
+
+/**
+ * Чи є в consequent (або в його BlockStatement) ThrowStatement.
+ * @param {unknown} consequent IfStatement.consequent
+ * @returns {boolean}
+ */
+function consequentHasThrow(consequent) {
+  if (!consequent || typeof consequent !== 'object') return false
+  if (consequent.type === 'ThrowStatement') return true
+  if (consequent.type === 'BlockStatement' && Array.isArray(consequent.body)) {
+    return consequent.body.some(s => s && typeof s === 'object' && s.type === 'ThrowStatement')
+  }
+  return false
+}
+
+/**
+ * Шукає “guard” `if (empty) throw` перед statementIndex у межах того ж BlockStatement.
+ * @param {unknown} block BlockStatement
+ * @param {number} statementIndex індекс statement, перед яким шукаємо guard
+ * @param {string} name імʼя змінної списку
+ * @returns {boolean}
+ */
+function hasEmptyGuardBefore(block, statementIndex, name) {
+  if (!block || typeof block !== 'object' || block.type !== 'BlockStatement') return false
+  const body = block.body
+  if (!Array.isArray(body)) return false
+  for (let i = 0; i < statementIndex; i++) {
+    const st = body[i]
+    if (!st || typeof st !== 'object') continue
+    if (st.type !== 'IfStatement') continue
+    if (!isEmptyListTest(st.test, name)) continue
+    if (!consequentHasThrow(st.consequent)) continue
+    return true
+  }
+  return false
+}
+
+/**
+ * Знаходить найближчий enclosing BlockStatement і statement всередині нього.
+ * @param {unknown[]} ancestors ancestors масив з walkAstWithAncestors
+ * @returns {{ block: unknown, index: number } | null}
+ */
+function findEnclosingBlockAndStatementIndex(ancestors) {
+  if (!Array.isArray(ancestors) || ancestors.length === 0) return null
+
+  // statement — перший зверху вузол, який лежить у block.body
+  // шукаємо пару (block, statement), де statement ∈ block.body
+  for (let i = ancestors.length - 1; i >= 1; i--) {
+    const maybeStatement = ancestors[i]
+    const maybeBlock = ancestors[i - 1]
+    if (!maybeBlock || typeof maybeBlock !== 'object' || maybeBlock.type !== 'BlockStatement') continue
+    if (!Array.isArray(maybeBlock.body)) continue
+    const idx = maybeBlock.body.indexOf(maybeStatement)
+    if (idx !== -1) return { block: maybeBlock, index: idx }
+  }
+  return null
+}
+
 /**
  * Чи це `new sql.ConnectionPool(...)` або `new mssql.ConnectionPool(...)`.
  * @param {unknown} node AST node
@@ -381,6 +488,47 @@ function collectInListUnparsedFromTemplate(node, content, declarators, out) {
   }
 }
 
+/**
+ * Збирає порушення для одного TemplateLiteral: якщо у `IN (${...})`:
+ * - `${...}` не є Identifier (значення не винесені у змінну);
+ * - або це Identifier, але перед запитом немає guard `if (empty) throw`.
+ *
+ * @param {Record<string, unknown>} node TemplateLiteral
+ * @param {unknown[]} ancestors ancestors від walkAstWithAncestors
+ * @param {string} content вихідний код
+ * @param {{ line: number, snippet: string, reason: 'not_var' | 'missing_guard', name?: string }[]} out буфер результатів
+ */
+function collectInListMissingEmptyGuardFromTemplate(node, ancestors, content, out) {
+  if (node.type !== 'TemplateLiteral') return
+  const quasis = node.quasis
+  const expressions = node.expressions
+  if (!Array.isArray(quasis) || !Array.isArray(expressions) || expressions.length === 0) return
+
+  for (const [i, expr] of expressions.entries()) {
+    if (!IN_PLACEHOLDER_END_RE.test(quasiRawText(quasis[i]))) continue
+    if (!expr || typeof expr !== 'object') continue
+
+    if (expr.type !== 'Identifier' || typeof expr.name !== 'string') {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        reason: 'not_var'
+      })
+      continue
+    }
+
+    const place = findEnclosingBlockAndStatementIndex(ancestors)
+    if (!place || !hasEmptyGuardBefore(place.block, place.index, expr.name)) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        reason: 'missing_guard',
+        name: expr.name
+      })
+    }
+  }
+}
+
 /**
  * Знаходить підстановки IN (вираз) у TemplateLiteral, де вираз не пройшов числовий парсер.
  *
@@ -410,6 +558,33 @@ export function findUnsafeMssqlInListUnparsedInText(content, virtualPath = 'scan
   return out
 }
 
+/**
+ * Знаходить підстановки списків у `IN (${...})`, які:
+ * - не винесені в окрему змінну (в `${...}` стоїть не Identifier);
+ * - або винесені, але перед запитом немає перевірки на пустоту з `throw`.
+ *
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору мови парсера (lang)
+ * @returns {{ line: number, snippet: string, reason: 'not_var' | 'missing_guard', name?: string }[]} список порушень
+ */
+export function findUnsafeMssqlInListMissingEmptyGuardInText(content, virtualPath = 'scan.ts') {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath, content, { lang, sourceType: 'module' })
+  } catch {
+    return []
+  }
+  if (result.errors?.length) return []
+
+  /** @type {{ line: number, snippet: string, reason: 'not_var' | 'missing_guard', name?: string }[]} */
+  const out = []
+  walkAstWithAncestors(result.program, [], (node, ancestors) =>
+    collectInListMissingEmptyGuardFromTemplate(node, ancestors, content, out)
+  )
+  return out
+}
+
 /**
  * Чи сканувати цей файл за розширенням (JS/TS-сім'я).
  * @param {string} relativePathPosix відносний шлях (posix)