@nitra/cursor 1.8.147 → 1.8.151

package/bin/n-cursor.js

@@ -561,7 +561,7 @@ function buildClaudeLintParallelismSectionLines() {
     '## Лінт і ESLint (без паралельних запусків)',
     '',
     'Щоб не запускати **кілька** одночасних **`eslint`** (і не перевантажувати диск/CPU), **заборонено** стартувати `bun run lint` / `lint-js` / `eslint` **паралельно** в різних Bash-задачах, **фонових** shells чи **субагентах** (Task тощо). Має бути **один** послідовний прогон на сесію; команда **`/n-lint`** — **не** ділити на паралельні підзадачі. Деталі: `.cursor/skills/n-lint/SKILL.md`.',
-    '',
+    ''
   ]
 }
 

package/bin/rename-yaml-extensions.mjs

@@ -1,4 +1,3 @@
-
 /**
  * CLI для перейменування розширень YAML (k8s та `.github`). Бізнес-логіка — у **`scripts/rename-yaml-extensions.mjs`**.
  *

package/mdc/docker.mdc

@@ -189,8 +189,10 @@ jobs:
 ```yaml title=".hadolint.yaml"
 ignored:
   - DL3007
+  - DL3008
   - DL3018
 ```
+
 Де DL3007 - «Не використовуй тег latest у FROM»
 Де DL3018 - «Піни версії пакетів у apk add»
 

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
@@ -17,6 +17,7 @@ version: '1.2'
 ## Як виконувати запити (безпечно)
 
 tagged template треба викликати на request-обʼєкті цього пулу:
+
 ```javascript
 javascript// db.js
 import sql from 'mssql';
@@ -53,11 +54,29 @@ 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(\`...\`)`
 
 javascript// ❌ Це не tagged template — це конкатенація рядка перед викликом
+
 ```javascript
 await pool.request().query(`SELECT * FROM users WHERE id = ${userId}`);
 // ↑ круглі дужки замість бекті́ків = звичайна інтерполяція = SQL injection
@@ -164,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))
@@ -174,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/mdc/k8s.mdc

@@ -314,7 +314,7 @@ data:
 
 ### Прод-оверрайди у `kustomization.yaml`
 
-Оскільки `base/` (і dev-like середовища) тримають dev-значення (`1`/`1`/`0`), у **кожному** прод-накладенні `kustomization.yaml` у `patches[]` **обов'язково** має бути перевизначення:
+Оскільки `base/` (і dev-like середовища) тримають dev-значення (`1`/`1`/`0`), у **кожному** прод-накладенні `kustomization.yaml` у `patches[]` **обов'язково** має бути перевизначення **лише якщо** цей оверлей наслідує base-дерево, де є **Deployment** і **HPA/PDB** (тобто base реально дає dev-like HPA/PDB, які треба підняти в проді):
 
 - для `HorizontalPodAutoscaler`: `spec.minReplicas` **і** `spec.maxReplicas` (щоб у проді вийшло ≥2).
 - для `PodDisruptionBudget`: `spec.minAvailable` (щоб у проді вийшло ≥1).

package/package.json

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

package/scripts/check-capacitor.mjs

@@ -376,9 +376,7 @@ function extractNitraObjectBodySource(source) {
  * @returns {boolean} **true**, якщо в тілі є **iosCocoaPods**…**:** **true**
  */
 function nitraObjectBodyStringAllowsCocoaPodsExempt(objectBody) {
-  return (
-    RE_COCOAPODS_EXEMPT_SPM.test(objectBody) === true || RE_COCOAPODS_EXEMPT_ALLOW.test(objectBody) === true
-  )
+  return RE_COCOAPODS_EXEMPT_SPM.test(objectBody) === true || RE_COCOAPODS_EXEMPT_ALLOW.test(objectBody) === true
 }
 
 /**
@@ -443,7 +441,9 @@ export async function check() {
   const { byPath, anyCapacitor } = acc
 
   if (!isCapacitorRelevantForCheck(root, anyCapacitor)) {
-    pass('Capacitor не виявлено (без capacitor.config у корені, без @capacitor/ у package.json) — check capacitor пропущено')
+    pass(
+      'Capacitor не виявлено (без capacitor.config у корені, без @capacitor/ у package.json) — check capacitor пропущено'
+    )
     return getExitCode()
   }
 

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-lint.mjs

@@ -18,7 +18,11 @@ import { parseWorkflowYaml, verifyLintJsWorkflowStructure } from './utils/gha-wo
 import { createCheckReporter } from './utils/check-reporter.mjs'
 
 /** Шлях до канонічного oxlint JSON у цьому пакеті (для перевірки та тестів). */
-export const OXLINT_CANONICAL_JSON_PATH = join(dirname(fileURLToPath(import.meta.url)), 'utils', 'oxlint-canonical.json')
+export const OXLINT_CANONICAL_JSON_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  'utils',
+  'oxlint-canonical.json'
+)
 
 /** Очікуваний локальний скрипт. */
 export const CANONICAL_LINT_JS = 'bunx oxlint --fix && bunx eslint --fix . && bunx jscpd .'

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('/')
@@ -292,4 +311,3 @@ export async function check() {
 
   return reporter.getExitCode()
 }
-

package/scripts/check-k8s.mjs

@@ -4803,26 +4803,59 @@ function checkProdOverridesInKustomization(kust, rel, fail, passFn) {
   }
 }
 
+/**
+ * Чи прод-оверлей **реально потребує** overrides для HPA/PDB.
+ *
+ * Overrides потрібні лише якщо оверлей (non-dev-like) посилається на `…/k8s/…/base` і у **base**-дереві
+ * одночасно є:
+ * - `Deployment` (у шарі `…/k8s/…/base/`), і
+ * - `HorizontalPodAutoscaler` і/або `PodDisruptionBudget`.
+ *
+ * Тоді base зазвичай тримає dev-like значення (`1`/`1`/`0`), і прод-оверлей має їх підняти (див. k8s.mdc).
+ * @param {string} rootNorm нормалізований корінь репозиторію
+ * @param {string} kustAbs абсолютний шлях до kustomization.yaml
+ * @returns {Promise<boolean>} true якщо потрібні overrides, інакше false
+ */
+export async function prodOverlayNeedsHpaPdbOverrides(rootNorm, kustAbs) {
+  const rel = (relative(rootNorm, kustAbs) || kustAbs).replaceAll('\\', '/')
+  const segment = k8sEnvSegmentFromRelPath(rel)
+  if (segment === null || isDevLikeK8sEnvSegment(segment)) return false
+
+  const kust = await readFirstYamlObject(kustAbs)
+  if (kust === null) return false
+
+  const kustDir = dirname(kustAbs)
+  const pathRefs = resourcePathRefsFromKustomizationObject(kust)
+  const baseDirs = await k8sBaseDirsFromKustomizeResourcePathRefs(kustDir, pathRefs, rootNorm)
+  if (baseDirs.length === 0) return false
+
+  const flags = await Promise.all(
+    baseDirs.map(bd => kustomizeResourceTreeHpaPdbDeploymentFlags(join(bd, 'kustomization.yaml'), rootNorm))
+  )
+
+  return flags.some(f => f.hasDeployment && (f.hasHpa || f.hasPdb))
+}
+
 /**
  * Для прод kustomization.yaml вимагає patches, що перевизначають **`/spec/minReplicas`** і **`/spec/maxReplicas`**
- * на **HorizontalPodAutoscaler**, а також **`/spec/minAvailable`** на **PodDisruptionBudget**. Не застосовується
- * до dev-like (base / dev / *-qa) — там ці значення беруть з base (див. k8s.mdc).
+ * на **HorizontalPodAutoscaler**, а також **`/spec/minAvailable`** на **PodDisruptionBudget**.
+ *
+ * Не застосовується до dev-like (base / dev / *-qa).
+ *
+ * Також **не застосовується**, якщо оверлей не наслідує base з Deployment + HPA/PDB (див. `prodOverlayNeedsHpaPdbOverrides`).
  * @param {string} root корінь репозиторію
  * @param {string[]} yamlFilesAbs yaml під k8s
  * @param {(msg: string) => void} fail callback при помилці
  * @param {(msg: string) => void} passFn callback при успіху
  */
 async function validateProdKustomizationOverrides(root, yamlFilesAbs, fail, passFn) {
+  const rootNorm = resolve(root)
   const kustFiles = yamlFilesAbs.filter(abs => basename(abs) === 'kustomization.yaml')
   for (const kustAbs of kustFiles) {
-    const rel = relative(root, kustAbs).replaceAll('\\', '/')
-    const segment = k8sEnvSegmentFromRelPath(rel)
-    if (segment !== null && !isDevLikeK8sEnvSegment(segment)) {
-      const kust = await readFirstYamlObject(kustAbs)
-      if (kust !== null) {
-        checkProdOverridesInKustomization(kust, rel, fail, passFn)
-      }
-    }
+    const rel = (relative(rootNorm, kustAbs) || kustAbs).replaceAll('\\', '/')
+    if (!(await prodOverlayNeedsHpaPdbOverrides(rootNorm, kustAbs))) continue
+    const kust = await readFirstYamlObject(kustAbs)
+    if (kust !== null) checkProdOverridesInKustomization(kust, rel, fail, passFn)
   }
 }
 

package/scripts/check-php.mjs

@@ -77,4 +77,3 @@ export async function check() {
   await checkWorkflow(reporter)
   return reporter.getExitCode()
 }
-

package/scripts/check-text.mjs

@@ -40,7 +40,7 @@ const CSPELL_REQUIRED_IGNORE_PATHS = [
   '.vscode',
   'report',
   '*.svg',
-  '**/k8s/**/*.yaml',
+  '**/k8s/**/*.yaml'
 ]
 
 /**

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

@@ -0,0 +1,154 @@
+/**
+ * Спільні утиліти для AST-сканерів JS/TS на oxc-parser:
+ * вибір мови за розширенням, переклад зміщення в номер рядка, стиснення сніпета,
+ * обхід AST з предками, парсинг програми з безпечним поверненням `null`,
+ * розпізнавання типових вузлів (функцій, `*.join(...)`),
+ * робота з `TemplateLiteral` (текст quasis, контекст SQL-списку).
+ *
+ * Використовується файлами `bun-sql-scan.mjs`, `mssql-pool-scan.mjs` та іншими сканерами
+ * для уникнення дублювання boilerplate.
+ */
+import { parseSync } from 'oxc-parser'
+
+const SQL_LIST_CONTEXT_RE = /\b(in|values)\b\s*\(/iu
+
+/**
+ * Мова для Oxc за шляхом файлу (розширення).
+ * @param {string} filePath віртуальний або реальний шлях до файлу
+ * @returns {'js' | 'jsx' | 'ts' | 'tsx'} значення опції `lang` для `parseSync`
+ */
+export function langFromPath(filePath) {
+  const lower = filePath.toLowerCase()
+  if (lower.endsWith('.tsx')) return 'tsx'
+  if (lower.endsWith('.ts') || lower.endsWith('.mts') || lower.endsWith('.cts')) return 'ts'
+  if (lower.endsWith('.jsx')) return 'jsx'
+  return 'js'
+}
+
+/**
+ * Номер рядка (1-based) за зміщенням у буфері.
+ * @param {string} content повний текст файлу
+ * @param {number} offset байтове зміщення початку фрагмента
+ * @returns {number} номер рядка від 1
+ */
+export function offsetToLine(content, offset) {
+  let line = 1
+  const n = Math.min(offset, content.length)
+  for (let i = 0; i < n; i++) {
+    if (content.codePointAt(i) === 10) line++
+  }
+  return line
+}
+
+/**
+ * Стискає пробіли для повідомлення про порушення.
+ * @param {string} s фрагмент коду
+ * @returns {string} скорочений однорядковий рядок
+ */
+export function normalizeSnippet(s) {
+  return s.replaceAll(/\s+/gu, ' ').trim().slice(0, 180)
+}
+
+/**
+ * Чи є вузол функцією.
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це будь-який вузол-функція
+ */
+export function isFunctionNode(node) {
+  return (
+    !!node &&
+    typeof node === 'object' &&
+    typeof node.type === 'string' &&
+    (node.type === 'FunctionDeclaration' ||
+      node.type === 'FunctionExpression' ||
+      node.type === 'ArrowFunctionExpression')
+  )
+}
+
+/**
+ * Рекурсивний обхід AST з предками, щоб визначати контекст (всередині функції чи ні).
+ * @param {unknown} node поточний вузол
+ * @param {unknown[]} ancestors масив предків від кореня до parent
+ * @param {(n: Record<string, unknown>, ancestors: unknown[]) => void} visit відвідувач для вузлів з `type`
+ * @returns {void}
+ */
+export function walkAstWithAncestors(node, ancestors, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkAstWithAncestors(item, ancestors, visit)
+    return
+  }
+
+  const rec = /** @type {Record<string, unknown>} */ (node)
+  if (typeof rec.type === 'string') {
+    visit(rec, ancestors)
+    ancestors = [...ancestors, rec]
+  }
+
+  for (const key of Object.keys(node)) {
+    if (key === 'parent') continue
+    const v = rec[key]
+    if (v && typeof v === 'object') {
+      walkAstWithAncestors(v, ancestors, visit)
+    }
+  }
+}
+
+/**
+ * Парсить файл і повертає `program` або null, якщо є синтаксичні помилки чи виняток.
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
+ * @returns {unknown | null} `result.program` або null, якщо парсинг не вдався
+ */
+export function parseProgramOrNull(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 result.program
+}
+
+/**
+ * Чи це `.join(...)` виклик (типово для динамічних списків у SQL).
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це CallExpression `*.join(...)`
+ */
+export function isJoinCall(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 === 'join'
+}
+
+/**
+ * Текст quasis у TemplateLiteral (без expressions).
+ * @param {unknown} template TemplateLiteral
+ * @returns {string} обʼєднаний raw-текст
+ */
+export function templateQuasisText(template) {
+  if (!template || template.type !== 'TemplateLiteral') return ''
+  const quasis = template.quasis
+  if (!Array.isArray(quasis) || quasis.length === 0) return ''
+  let out = ''
+  for (const q of quasis) {
+    if (!q || typeof q !== 'object') continue
+    const value = q.value
+    if (!value || typeof value !== 'object') continue
+    if (typeof value.raw === 'string') out += value.raw
+  }
+  return out
+}
+
+/**
+ * Чи виглядає TemplateLiteral як SQL-контекст зі списком (IN/VALUES (...)).
+ * @param {unknown} template TemplateLiteral
+ * @returns {boolean} true, якщо текст містить `IN (` або `VALUES (`
+ */
+export function isSqlListContextTemplate(template) {
+  return SQL_LIST_CONTEXT_RE.test(templateQuasisText(template))
+}