@nitra/cursor 1.8.156 → 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

@@ -11,7 +11,7 @@
  *     (порядок не важливий, кілька викликів зливаються в один список).
  *
  * Обидва контракти можна точково «приглушити» коментарем-маркером
- * `// @nitra/cursor ignore-next-line checkEnv` на рядку безпосередньо перед
+ * `// \@nitra/cursor ignore-next-line checkEnv` на рядку безпосередньо перед
  * порушенням — це залишається сумісним escape-hatch для legacy-коду.
  *
  * Семантика береться з **oxc-parser** через `parseProgramOrNull`: regex по тілу
@@ -129,7 +129,7 @@ function hasCheckEnvImport(programNode) {
 }
 
 /**
- * Чи закритий рядок ignore-коментарем `// @nitra/cursor ignore-next-line checkEnv`.
+ * Чи закритий рядок ignore-коментарем `// \@nitra/cursor ignore-next-line checkEnv`.
  * @param {string[]} lines рядки файлу (split за \n, без CR)
  * @param {number} oneBasedLine 1-based номер рядка з порушенням
  * @returns {boolean} true, якщо попередній рядок містить маркер
@@ -161,6 +161,51 @@ function isEnvIdentifierMember(node) {
  * }} 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)
+  )
+}
+
 /**
  * Перебирає AST і для кожного знайденого доступу до `process.env` чи `env`
  * (де `env` — імпорт з `@nitra/check-env`) реєструє порушення відповідного типу.
@@ -191,34 +236,42 @@ function collectViolations(program, content, lines, checkedNames, envFromCheckEn
     out.push({ kind, name, line })
   }
 
-  walkAstWithAncestors(program, [], (node, ancestors) => {
-    // 1. process.env.X — завжди порушення (рекомендуємо замінити на env)
-    if (isProcessEnvAccess(node)) {
-      const parent = ancestors[ancestors.length - 1]
-      if (parent && typeof parent === 'object' && parent.type === 'MemberExpression' && parent.object === node) {
-        const envName = envNameFromMember(parent)
-        if (envName) report('process-env', envName, offsetToLine(content, parent.start))
-      }
-      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) {
-          const name = staticPropertyName(p)
-          if (name) report('process-env', name, offsetToLine(content, p.start ?? parent.start))
-        }
-      }
-      return
+  /**
+   * Реєструє порушення для всіх статичних ключів 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))
     }
+  }
 
-    // 2. env.X — порушення лише якщо env імпортовано з @nitra/check-env і немає checkEnv
-    if (!envFromCheckEnv) return
+  /**
+   * Обробка `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)) {
@@ -226,24 +279,17 @@ function collectViolations(program, content, lines, checkedNames, envFromCheckEn
       }
       return
     }
+    if (isEnvObjectPatternDeclarator(node)) {
+      reportObjectPatternKeys(node, 'check-env-missing-checkEnv', name => checkedNames.has(name))
+    }
+  }
 
-    // const { X, Y } = env — теж потребує checkEnv для кожного імені
-    if (
-      node.type === 'VariableDeclarator' &&
-      node.init &&
-      node.init.type === 'Identifier' &&
-      node.init.name === 'env' &&
-      node.id &&
-      node.id.type === 'ObjectPattern' &&
-      Array.isArray(node.id.properties)
-    ) {
-      for (const p of node.id.properties) {
-        const name = staticPropertyName(p)
-        if (name && !checkedNames.has(name)) {
-          report('check-env-missing-checkEnv', name, offsetToLine(content, p.start ?? node.start))
-        }
-      }
+  walkAstWithAncestors(program, [], (node, ancestors) => {
+    if (isProcessEnvAccess(node)) {
+      handleProcessEnv(node, ancestors)
+      return
     }
+    if (envFromCheckEnv) handleCheckEnvAccess(node)
   })
 
   return out
@@ -266,7 +312,6 @@ function staticPropertyName(property) {
 
 /**
  * Знаходить порушення правила «process.env / CheckEnv» у файлі.
- *
  * @param {string} content вихідний код
  * @param {string} [virtualPath] шлях для вибору `lang` парсера
  * @returns {EnvViolation[]} список порушень із типом, іменем змінної та рядком

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 }[]} список порушень