@nitra/cursor 1.8.155 → 1.8.157

package/scripts/check-npm-module.mjs

@@ -9,6 +9,9 @@
  * Якщо таких файлів немає — layout через `npm/tsconfig.emit-types.json`: поле `types` має вказувати на існуючий
  * файл під `./types/…`, у hk — `tsc -p tsconfig.emit-types.json`, у JSON-конфігу — потрібні compilerOptions для emit.
  *
+ * Окремо перевіряється `npm/CHANGELOG.md`: файл існує, є в `files` у `npm/package.json` і містить запис
+ * для поточної версії (формат `## [X.Y.Z] - YYYY-MM-DD`, Keep a Changelog).
+ *
  * Поля workflow перевіряються після **YAML parse**, щоб не плутати з коментарями.
  */
 import { existsSync } from 'node:fs'
@@ -33,6 +36,9 @@ const TYPES_INDEX = './types/index.d.ts'
 /** Файл проєкту TypeScript для emit без каталогу `src` (див. npm-module.mdc) */
 const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
 
+/** Шлях до `CHANGELOG.md` в каталозі npm-модуля */
+const CHANGELOG_PATH = 'npm/CHANGELOG.md'
+
 /**
  * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
  * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
@@ -194,6 +200,53 @@ async function checkNpmPackageJson(useSrcJsLayout, passFn, failFn) {
   }
 }
 
+/**
+ * Чи містить текст `CHANGELOG.md` запис заголовка для конкретної версії
+ * у форматі Keep a Changelog: `## [X.Y.Z]` (з опційним `- YYYY-MM-DD`).
+ * @param {string} text вміст `CHANGELOG.md`
+ * @param {string} version номер версії з `npm/package.json`
+ * @returns {boolean} `true`, якщо знайдено заголовок версії
+ */
+function changelogHasVersionEntry(text, version) {
+  const escaped = version.replaceAll(/[.+*?^$()[\]{}|\\]/g, String.raw`\$&`)
+  const re = new RegExp(String.raw`^##\s+\[${escaped}\]`, 'm')
+  return re.test(text)
+}
+
+/**
+ * Перевіряє наявність і вміст `npm/CHANGELOG.md`, а також що він є в `files` у `npm/package.json`.
+ * @param {(msg: string) => void} passFn callback при успішній перевірці
+ * @param {(msg: string) => void} failFn callback при помилці
+ */
+async function checkChangelog(passFn, failFn) {
+  if (!existsSync(CHANGELOG_PATH)) {
+    failFn(`Відсутній ${CHANGELOG_PATH} (npm-module.mdc: CHANGELOG)`)
+    return
+  }
+  passFn(`${CHANGELOG_PATH} існує`)
+
+  if (existsSync('npm/package.json')) {
+    const npmPkg = JSON.parse(await readFile('npm/package.json', 'utf8'))
+    if (Array.isArray(npmPkg.files) && npmPkg.files.includes('CHANGELOG.md')) {
+      passFn('npm/package.json: files містить "CHANGELOG.md"')
+    } else {
+      failFn('npm/package.json: масив files має містити "CHANGELOG.md"')
+    }
+
+    const version = typeof npmPkg.version === 'string' ? npmPkg.version : null
+    if (version) {
+      const text = await readFile(CHANGELOG_PATH, 'utf8')
+      if (changelogHasVersionEntry(text, version)) {
+        passFn(`${CHANGELOG_PATH}: знайдено запис для версії ${version}`)
+      } else {
+        failFn(
+          `${CHANGELOG_PATH}: відсутній запис для поточної версії ${version} (формат Keep a Changelog: "## [${version}] - YYYY-MM-DD")`
+        )
+      }
+    }
+  }
+}
+
 /**
  * Перевіряє npm/tsconfig.emit-types.json.
  * @param {(msg: string) => void} passFn callback при успішній перевірці
@@ -338,6 +391,8 @@ export async function check() {
 
   await checkNpmPackageJson(useSrcJsLayout, pass, fail)
 
+  await checkChangelog(pass, fail)
+
   if (!useSrcJsLayout) {
     await checkEmitTypesConfig(pass, fail)
   }

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

@@ -116,7 +116,8 @@ function isEmptyListTest(test, name) {
     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
+    if (isZeroNumberLiteral(left) && isLengthMember(right, name) && (operator === '===' || operator === '=='))
+      return true
   }
 
   return false
@@ -307,7 +308,9 @@ function collectInListGuardViolationsFromTemplate(template, ancestors, content,
   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 : ''
+      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)

package/scripts/utils/check-env-scan.mjs

@@ -1,23 +1,32 @@
 /**
- * AST-сканер для правила CheckEnv (js-run.mdc).
+ * AST-сканер правила «process.env / CheckEnv» (js-run.mdc).
  *
- * Кожне використання `process.env.X` у JS/TS-коді має бути «закрите» одним з двох способів:
- *  - перед використанням у тому ж файлі викликано `checkEnv(['X', ...])` з пакету `@nitra/check-env`;
- *  - на рядку безпосередньо перед `process.env.X` стоїть коментар-маркер
- *    `// @nitra/cursor ignore-next-line checkEnv` (роздільники пробілів довільні; саме слово
- *    `checkEnv` чутливе до регістру, як в усіх прикладах документа).
+ * Правило в .mdc формулює два контракти:
+ *  1. Прямий доступ до `process.env.X` має бути замінено на `env` — з пакета
+ *     `@nitra/check-env` (для обов'язкових змінних, із викликом `checkEnv([...])`)
+ *     або з `node:process` (для опційних). Тому будь-яке `process.env.X` сканер
+ *     завжди реєструє як порушення з порадою про конкретну заміну.
+ *  2. Якщо у файл імпортовано `env` саме з `@nitra/check-env`, то кожне `env.X`
+ *     має бути закрите літеральним викликом `checkEnv(['X', ...])` у тому ж файлі
+ *     (порядок не важливий, кілька викликів зливаються в один список).
  *
- * Семантика береться з **oxc-parser** через `parseProgramOrNull`: regex по тілу файлу не
- * використовується, лише сирий текст рядка з коментарем перевіряється на маркер. Якщо
- * файл не парситься — повертаємо порожній результат, спочатку треба полагодити синтаксис.
+ * Обидва контракти можна точково «приглушити» коментарем-маркером
+ * `// \@nitra/cursor ignore-next-line checkEnv` на рядку безпосередньо перед
+ * порушенням — це залишається сумісним escape-hatch для legacy-коду.
  *
- * Покриті форми доступу до `process.env`:
- *  - `process.env.X` (звичайний MemberExpression);
- *  - `process.env['X']` (computed з рядковим літералом);
- *  - `const { X, Y } = process.env` (ObjectPattern; ім'я з ключа);
- *  - `const { X: alias } = process.env` (ім'я з ключа, не з alias).
+ * Семантика береться з **oxc-parser** через `parseProgramOrNull`: regex по тілу
+ * файлу не використовується, лише сирий текст рядка з коментарем перевіряється
+ * на маркер. Якщо файл не парситься — повертаємо порожній результат, спочатку
+ * треба полагодити синтаксис.
  *
- * Якщо ключ обчислюваний (наприклад, `process.env[varName]`) — пропускаємо без помилки,
+ * Покриті форми доступу:
+ *  - `process.env.X` / `process.env['X']` (як MemberExpression);
+ *  - `const { X, Y } = process.env` (ObjectPattern; ім'я з ключа, не з alias);
+ *  - аналогічно для `env.X` / `env['X']` / `const { X } = env`,
+ *    де `env` має бути імпортований з `@nitra/check-env` (інакше ігноруємо —
+ *    це може бути локальна змінна чи `env` з `node:process`).
+ *
+ * Якщо ключ обчислюваний (`process.env[varName]`) — пропускаємо без помилки,
  * бо за статичним AST неможливо встановити, яка саме змінна оточення використовується.
  */
 import { offsetToLine, parseProgramOrNull, walkAstWithAncestors } from './ast-scan-utils.mjs'
@@ -25,6 +34,8 @@ import { offsetToLine, parseProgramOrNull, walkAstWithAncestors } from './ast-sc
 const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
 const IGNORE_DIRECTIVE_RE = /\/\/\s*@nitra\/cursor\s+ignore-next-line\s+checkEnv\b/u
 
+const CHECK_ENV_PACKAGE = '@nitra/check-env'
+
 /**
  * Чи є цей вузол виразом `process.env`.
  * @param {unknown} node AST вузол
@@ -46,8 +57,8 @@ function isProcessEnvAccess(node) {
 }
 
 /**
- * Витягує ім'я ENV з MemberExpression-вузла `process.env.X` або `process.env['X']`.
- * @param {Record<string, unknown>} node MemberExpression, чий object — `process.env`
+ * Витягує ім'я ENV з MemberExpression `obj.X` або `obj['X']`.
+ * @param {Record<string, unknown>} node MemberExpression, чий object — `process.env` або `env`
  * @returns {string | null} ім'я змінної оточення або null, якщо ключ не статичний
  */
 function envNameFromMember(node) {
@@ -88,9 +99,39 @@ function collectCheckedEnvNames(programNode) {
 }
 
 /**
- * Чи закритий рядок ignore-коментарем `// @nitra/cursor ignore-next-line checkEnv`.
+ * Чи імпортовано локальний ідентифікатор `env` саме з `@nitra/check-env`.
+ * Перевіряє ImportDeclaration на specifier {imported.name === 'env', local.name === 'env'}.
+ * Aliased-варіанти (`{ env as x }`) свідомо не підтримуються — у наших правилах
+ * приклади завжди використовують канонічне ім'я `env`.
+ * @param {unknown} programNode корінь AST
+ * @returns {boolean} true, якщо у файлі є `import { env } from '@nitra/check-env'`
+ */
+function hasCheckEnvImport(programNode) {
+  let found = false
+  walkAstWithAncestors(programNode, [], node => {
+    if (found) return
+    if (node.type !== 'ImportDeclaration') return
+    const source = node.source
+    if (!source || typeof source !== 'object' || source.value !== CHECK_ENV_PACKAGE) return
+    const specifiers = node.specifiers
+    if (!Array.isArray(specifiers)) return
+    for (const s of specifiers) {
+      if (!s || typeof s !== 'object' || s.type !== 'ImportSpecifier') continue
+      const imported = s.imported
+      const local = s.local
+      if (!imported || imported.name !== 'env') continue
+      if (!local || local.name !== 'env') continue
+      found = true
+      return
+    }
+  })
+  return found
+}
+
+/**
+ * Чи закритий рядок ignore-коментарем `// \@nitra/cursor ignore-next-line checkEnv`.
  * @param {string[]} lines рядки файлу (split за \n, без CR)
- * @param {number} oneBasedLine 1-based номер рядка з `process.env.X`
+ * @param {number} oneBasedLine 1-based номер рядка з порушенням
  * @returns {boolean} true, якщо попередній рядок містить маркер
  */
 function hasIgnoreDirective(lines, oneBasedLine) {
@@ -100,75 +141,192 @@ function hasIgnoreDirective(lines, oneBasedLine) {
 }
 
 /**
- * Знаходить всі доступи до `process.env.<NAME>`, які не покриті ні літеральним
- * `checkEnv([...])` у тому ж файлі, ні коментарем-маркером безпосередньо перед.
- *
- * @param {string} content вихідний код
- * @param {string} [virtualPath] шлях для вибору `lang` парсера
- * @returns {{ line: number, name: string }[]} список порушень
+ * Чи є вузол MemberExpression виду `env.X` / `env['X']`, де `env` — Identifier
+ * (в AST oxc-parser globals і локальні імпорти не розрізняються — фільтр джерела
+ * робиться на рівні `hasCheckEnvImport`).
+ * @param {unknown} node AST вузол
+ * @returns {boolean} true, якщо це `env.<...>`
  */
-export function findUncheckedProcessEnvInText(content, virtualPath = 'scan.ts') {
-  const program = parseProgramOrNull(content, virtualPath)
-  if (!program) return []
+function isEnvIdentifierMember(node) {
+  if (!node || typeof node !== 'object' || node.type !== 'MemberExpression') return false
+  const obj = node.object
+  return !!obj && obj.type === 'Identifier' && obj.name === 'env'
+}
 
-  const checked = collectCheckedEnvNames(program)
-  const lines = content.split('\n').map(s => (s.endsWith('\r') ? s.slice(0, -1) : s))
+/**
+ * @typedef {{
+ *   line: number,
+ *   name: string,
+ *   kind: 'process-env' | 'check-env-missing-checkEnv'
+ * }} EnvViolation
+ */
+
+/**
+ * Чи parent — це MemberExpression, у якому `node` (process.env) є об'єктом доступу.
+ * @param {unknown} parent ancestor вузла
+ * @param {unknown} node перевіряємий вузол `process.env`
+ * @returns {boolean} true для `process.env.X` / `process.env['X']`
+ */
+function isParentEnvMember(parent, node) {
+  return !!parent && typeof parent === 'object' && parent.type === 'MemberExpression' && parent.object === node
+}
+
+/**
+ * Чи parent — це VariableDeclarator виду `const { ... } = <node>`.
+ * @param {unknown} parent ancestor вузла
+ * @param {unknown} node перевіряємий вузол (process.env або Identifier `env`)
+ * @returns {boolean} true для `const { ... } = node`
+ */
+function isParentObjectPatternDeclarator(parent, node) {
+  return (
+    !!parent &&
+    typeof parent === 'object' &&
+    parent.type === 'VariableDeclarator' &&
+    parent.init === node &&
+    !!parent.id &&
+    parent.id.type === 'ObjectPattern' &&
+    Array.isArray(parent.id.properties)
+  )
+}
+
+/**
+ * Чи node — це VariableDeclarator виду `const { ... } = env`, де `env` — Identifier.
+ * @param {Record<string, unknown>} node AST-вузол
+ * @returns {boolean} true для `const { ... } = env`
+ */
+function isEnvObjectPatternDeclarator(node) {
+  return (
+    node.type === 'VariableDeclarator' &&
+    !!node.init &&
+    node.init.type === 'Identifier' &&
+    node.init.name === 'env' &&
+    !!node.id &&
+    node.id.type === 'ObjectPattern' &&
+    Array.isArray(node.id.properties)
+  )
+}
 
-  /** @type {{ line: number, name: string }[]} */
+/**
+ * Перебирає AST і для кожного знайденого доступу до `process.env` чи `env`
+ * (де `env` — імпорт з `@nitra/check-env`) реєструє порушення відповідного типу.
+ * @param {unknown} program корінь AST
+ * @param {string} content вихідний код (для offset → line)
+ * @param {string[]} lines split-рядки content (для ignore-маркера)
+ * @param {Set<string>} checkedNames імена, закриті літеральним `checkEnv([...])`
+ * @param {boolean} envFromCheckEnv чи імпортовано `env` саме з `@nitra/check-env`
+ * @returns {EnvViolation[]} список порушень (відсортований за порядком зустрічі в AST)
+ */
+function collectViolations(program, content, lines, checkedNames, envFromCheckEnv) {
+  /** @type {EnvViolation[]} */
   const out = []
   /** @type {Set<string>} */
   const reported = new Set()
 
   /**
-   * Реєструє порушення з дедуплікацією за «name@line».
+   * Реєструє порушення з дедуплікацією за «kind|name|line» і урахуванням ignore-маркера.
+   * @param {'process-env' | 'check-env-missing-checkEnv'} kind тип порушення
    * @param {string} name ім'я ENV
    * @param {number} line 1-based рядок
    */
-  function report(name, line) {
-    if (checked.has(name)) return
+  function report(kind, name, line) {
     if (hasIgnoreDirective(lines, line)) return
-    const key = `${name}@${line}`
+    const key = `${kind}|${name}|${line}`
     if (reported.has(key)) return
     reported.add(key)
-    out.push({ name, line })
+    out.push({ kind, name, line })
+  }
+
+  /**
+   * Реєструє порушення для всіх статичних ключів ObjectPattern (`const { A, B } = …`).
+   * @param {Record<string, unknown>} declarator VariableDeclarator з ObjectPattern у `id`
+   * @param {'process-env' | 'check-env-missing-checkEnv'} kind тип порушення
+   * @param {(name: string) => boolean} skipName предикат «пропустити це ім'я» (наприклад, вже у checkEnv)
+   */
+  function reportObjectPatternKeys(declarator, kind, skipName) {
+    const fallbackOffset = declarator.start
+    for (const p of declarator.id.properties) {
+      const name = staticPropertyName(p)
+      if (!name || skipName(name)) continue
+      report(kind, name, offsetToLine(content, p.start ?? fallbackOffset))
+    }
+  }
+
+  /**
+   * Обробка `process.env`-доступу: і `parent.X`, і деструктуризація.
+   * @param {unknown} node AST-вузол `process.env`
+   * @param {unknown[]} ancestors стек предків з walkAstWithAncestors
+   */
+  function handleProcessEnv(node, ancestors) {
+    const parent = ancestors.at(-1)
+    if (isParentEnvMember(parent, node)) {
+      const envName = envNameFromMember(parent)
+      if (envName) report('process-env', envName, offsetToLine(content, parent.start))
+    }
+    if (isParentObjectPatternDeclarator(parent, node)) {
+      reportObjectPatternKeys(parent, 'process-env', () => false)
+    }
+  }
+
+  /**
+   * Обробка вузлів, що стосуються `env` з `@nitra/check-env`.
+   * @param {Record<string, unknown>} node AST-вузол
+   */
+  function handleCheckEnvAccess(node) {
+    if (isEnvIdentifierMember(node)) {
+      const envName = envNameFromMember(node)
+      if (envName && !checkedNames.has(envName)) {
+        report('check-env-missing-checkEnv', envName, offsetToLine(content, node.start))
+      }
+      return
+    }
+    if (isEnvObjectPatternDeclarator(node)) {
+      reportObjectPatternKeys(node, 'check-env-missing-checkEnv', name => checkedNames.has(name))
+    }
   }
 
   walkAstWithAncestors(program, [], (node, ancestors) => {
     if (isProcessEnvAccess(node)) {
-      const parent = ancestors[ancestors.length - 1]
-      // process.env.X / process.env['X']
-      if (parent && typeof parent === 'object' && parent.type === 'MemberExpression' && parent.object === node) {
-        const envName = envNameFromMember(parent)
-        if (envName) report(envName, offsetToLine(content, parent.start))
-      }
-      // const { X, Y } = process.env  → беремо імена з ObjectPattern
-      if (
-        parent &&
-        typeof parent === 'object' &&
-        parent.type === 'VariableDeclarator' &&
-        parent.init === node &&
-        parent.id &&
-        parent.id.type === 'ObjectPattern' &&
-        Array.isArray(parent.id.properties)
-      ) {
-        for (const p of parent.id.properties) {
-          if (!p || typeof p !== 'object' || p.type !== 'Property') continue
-          if (p.computed) continue
-          const key = p.key
-          if (!key || typeof key !== 'object') continue
-          /** @type {string | null} */
-          let name = null
-          if (key.type === 'Identifier' && typeof key.name === 'string') name = key.name
-          else if (key.type === 'Literal' && typeof key.value === 'string') name = key.value
-          if (name) report(name, offsetToLine(content, p.start ?? parent.start))
-        }
-      }
+      handleProcessEnv(node, ancestors)
+      return
     }
+    if (envFromCheckEnv) handleCheckEnvAccess(node)
   })
 
   return out
 }
 
+/**
+ * Витягує статичне ім'я з вузла Property у ObjectPattern.
+ * @param {unknown} property AST-вузол ObjectPattern.properties[i]
+ * @returns {string | null} ім'я ключа або null
+ */
+function staticPropertyName(property) {
+  if (!property || typeof property !== 'object' || property.type !== 'Property') return null
+  if (property.computed) return null
+  const key = property.key
+  if (!key || typeof key !== 'object') return null
+  if (key.type === 'Identifier' && typeof key.name === 'string') return key.name
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value
+  return null
+}
+
+/**
+ * Знаходить порушення правила «process.env / CheckEnv» у файлі.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` парсера
+ * @returns {EnvViolation[]} список порушень із типом, іменем змінної та рядком
+ */
+export function findUncheckedProcessEnvInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  const checked = collectCheckedEnvNames(program)
+  const envFromCheckEnv = hasCheckEnvImport(program)
+  const lines = content.split('\n').map(s => (s.endsWith('\r') ? s.slice(0, -1) : s))
+
+  return collectViolations(program, content, lines, checked, envFromCheckEnv)
+}
+
 /**
  * Чи сканувати цей файл за розширенням (JS/TS-сім'я, без `.d.ts`).
  * @param {string} relativePathPosix відносний шлях (posix)

package/scripts/utils/conn-imports-scan.mjs

@@ -20,7 +20,17 @@ import { langFromPath, normalizeSnippet, offsetToLine } from './ast-scan-utils.m
 import { parseSync } from 'oxc-parser'
 
 const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
-const TRAILING_SLASH_RE = /\/+$/u
+
+/**
+ * Прибирає хвостові `/` зі шляху без використання regex (щоб не тригерити slow-regex попередження).
+ * @param {string} s рядок зі шляхом
+ * @returns {string} `s` без хвостових `/`
+ */
+function stripTrailingSlashes(s) {
+  let end = s.length
+  while (end > 0 && s.codePointAt(end - 1) === 47) end--
+  return end === s.length ? s : s.slice(0, end)
+}
 
 /**
  * Нормалізує шлях до posix без хвостових слешів.
@@ -30,7 +40,7 @@ const TRAILING_SLASH_RE = /\/+$/u
 function toPosixDir(p) {
   let s = String(p).replaceAll('\\', '/').trim()
   if (s.startsWith('./')) s = s.slice(2)
-  return s.replace(TRAILING_SLASH_RE, '')
+  return stripTrailingSlashes(s)
 }
 
 /**
@@ -57,7 +67,7 @@ export function resolveConnDirFromPackageJson(pkgJson) {
   // Прибираємо хвіст `*`, потім слеші
   let s = toPosixDir(raw)
   if (s.endsWith('/*')) s = s.slice(0, -2)
-  return s.replace(TRAILING_SLASH_RE, '') || fallback
+  return stripTrailingSlashes(s) || fallback
 }
 
 /**

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

@@ -36,60 +36,81 @@ 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'])
 
+/**
+ * Чи є вузол літералом числа `0` (як NumericLiteral, так і generic Literal).
+ * @param {unknown} node AST-вузол
+ * @returns {boolean} true для `0`
+ */
+function isZeroLiteral(node) {
+  return (
+    !!node &&
+    typeof node === 'object' &&
+    ((node.type === 'NumericLiteral' && node.value === 0) || (node.type === 'Literal' && node.value === 0))
+  )
+}
+
+/**
+ * Чи `node` — це MemberExpression `name.length` (некомп'ютерований Identifier.Identifier).
+ * @param {unknown} node AST-вузол
+ * @param {string} name очікуване імʼя змінної-власника
+ * @returns {boolean} true для `<name>.length`
+ */
+function isLengthMemberOf(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'
+  )
+}
+
+const EMPTY_LIST_BINARY_OPERATORS = new Set(['===', '==', '<=', '<'])
+const EMPTY_LIST_REVERSED_OPERATORS = new Set(['===', '=='])
+
+/**
+ * Чи `BinaryExpression`-тест з оператором з {@link EMPTY_LIST_BINARY_OPERATORS}
+ * порівнює `<name>.length` з літералом `0` (у будь-якому порядку для `===`/`==`).
+ * @param {Record<string, unknown>} test BinaryExpression вузол
+ * @param {string} name імʼя змінної списку
+ * @returns {boolean} true для умов виду `name.length === 0`, `name.length <= 0`, `0 === name.length` тощо
+ */
+function isEmptyListBinaryTest(test, name) {
+  const { left, right, operator } = test
+  if (!EMPTY_LIST_BINARY_OPERATORS.has(operator)) return false
+  if (isLengthMemberOf(left, name) && isZeroLiteral(right)) return true
+  return EMPTY_LIST_REVERSED_OPERATORS.has(operator) && isZeroLiteral(left) && isLengthMemberOf(right, name)
+}
+
 /**
  * Чи містить тест if-умови перевірку “список порожній”.
  * Підтримує базові форми:
  * - `if (!ids.length) ...`
  * - `if (ids.length === 0) ...` / `<= 0` / `< 1`
- *
  * @param {unknown} test IfStatement.test
  * @param {string} name імʼя змінної списку
- * @returns {boolean}
+ * @returns {boolean} true, якщо тест перевіряє, що `name` — порожній масив
  */
 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'
-    }
+    return isLengthMemberOf(test.argument, name)
   }
-
   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 isEmptyListBinaryTest(test, name)
   }
-
   return false
 }
 
 /**
  * Чи є в consequent (або в його BlockStatement) ThrowStatement.
  * @param {unknown} consequent IfStatement.consequent
- * @returns {boolean}
+ * @returns {boolean} true, якщо гілка consequent містить `throw`
  */
 function consequentHasThrow(consequent) {
   if (!consequent || typeof consequent !== 'object') return false
@@ -105,7 +126,7 @@ function consequentHasThrow(consequent) {
  * @param {unknown} block BlockStatement
  * @param {number} statementIndex індекс statement, перед яким шукаємо guard
  * @param {string} name імʼя змінної списку
- * @returns {boolean}
+ * @returns {boolean} true, якщо знайдено guard `if (empty(name)) throw` до statementIndex
  */
 function hasEmptyGuardBefore(block, statementIndex, name) {
   if (!block || typeof block !== 'object' || block.type !== 'BlockStatement') return false
@@ -125,7 +146,7 @@ function hasEmptyGuardBefore(block, statementIndex, name) {
 /**
  * Знаходить найближчий enclosing BlockStatement і statement всередині нього.
  * @param {unknown[]} ancestors ancestors масив з walkAstWithAncestors
- * @returns {{ block: unknown, index: number } | null}
+ * @returns {{ block: unknown, index: number } | null} пара (BlockStatement, індекс statement) або null
  */
 function findEnclosingBlockAndStatementIndex(ancestors) {
   if (!Array.isArray(ancestors) || ancestors.length === 0) return null
@@ -492,7 +513,6 @@ 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 вихідний код
@@ -562,7 +582,6 @@ export function findUnsafeMssqlInListUnparsedInText(content, virtualPath = 'scan
  * Знаходить підстановки списків у `IN (${...})`, які:
  * - не винесені в окрему змінну (в `${...}` стоїть не Identifier);
  * - або винесені, але перед запитом немає перевірки на пустоту з `throw`.
- *
  * @param {string} content вихідний код
  * @param {string} [virtualPath] шлях для вибору мови парсера (lang)
  * @returns {{ line: number, snippet: string, reason: 'not_var' | 'missing_guard', name?: string }[]} список порушень