@nitra/cursor 12.9.0 → 12.10.0

package/rules/js/js/docs/utils_imports.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Модуль сканує монорепозиторій для пошуку каталогів `utils` та аналізу їхнього вмісту. Аналіз файлів JS/TS у цих каталогах здійснюється на відповідність шаблону забороненого відносного імпорту, що базується на конфігурації, визначеній у `.n-cursor.json`. При виявленні порушень, система генерує повідомлення, позначене як (js.mdc).
 
 ## Поведінка

package/rules/js/main.mdc

@@ -7,38 +7,7 @@ version: '1.30'
 
 **oxlint**, **ESLint**, **jscpd**, **knip**. Запуск — **`n-cursor lint js`** (локально; у CI — `--read-only`, без **`--fix`** для oxlint/eslint). Без **prettier** і **@nitra/prettier-config**.
 
-[js-file-extensions](./js/file-extensions.mdc)
-
-[js-package-json](./js/package-json.mdc)
-
-[js-eslint-config](./js/eslint-config.mdc)
-
-[js-oxlintrc](./js/oxlintrc.mdc)
-
-[js-extensions](./js/extensions.mdc)
-
-[js-jscpd](./js/jscpd.mdc)
-
-[js-knip](./js/knip.mdc)
-
-[js-dep-policy](./js/dep-policy.mdc)
-
-[js-lint-js-workflow](./js/lint-js-workflow.mdc)
-
-[js-utils-lib-structure](./js/utils-lib-structure.mdc)
-
-[js-for-in](./js/for-in.mdc)
-
-[js-tests](./js/tests.mdc)
-
 ## Швидкий gate через conftest
 
 Rego-пакети у `policy/` — запускаються `npx @nitra/cursor fix js` або `conftest`:
 
-[js-policy-package_json](./policy/package_json/package_json.mdc)
-
-[js-policy-jscpd](./policy/jscpd/jscpd.mdc)
-
-[js-policy-lint_js_yml](./policy/lint_js_yml/lint_js_yml.mdc)
-
-[js-policy-vscode_extensions](./policy/vscode_extensions/vscode_extensions.mdc)

package/rules/js-bun-db/docs/main.md

@@ -8,8 +8,6 @@ docgen:
   score: 90
 ---
 
-## Огляд
-
 Модуль виконує перевірку, застосовуючи правила та політики. При виклику публічної функції `run` він завантажує конфігурації, зокрема `meta.json`, застосовує білі списки та підбиває підсумки. Модуль є Read-only, тобто не пише у файлову систему чи базу даних. Під час роботи відбувається кешування даних у межах одного прогону. Результат перевірки визначає код виходу процесу.
 
 ## Поведінка

package/rules/js-bun-db/js/docs/safety.md

@@ -3,39 +3,34 @@ type: JS Module
 title: safety.mjs
 resource: npm/rules/js-bun-db/js/safety.mjs
 docgen:
-  crc: eaeb52bc
+  crc: e828ee4a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Огляд
+Модуль сканує репозиторій для валідації безпечності використання Bun SQL. Він шукає всі файли `package.json` та JS/TS джерела, щоб перевірити відповідність патернів Bun SQL правилам, визначеним у конфігурації, що спирається на `package.json`.
 
-Файл перевіряє шляхи до файлів та залежностей, пов'язаних з Bun SQL та бібліотекою `pg`. Файл збирає метадані про використання `pg` та механізми LISTEN/NOTIFY. (js-bun-db.mdc)
+Поведінка:
+
+- Перевіряє відповідність патернів Bun SQL встановленим правилам (js-bun-db.mdc).
 
 ## Поведінка
 
-1. Завантажити шляхи до файлів з коду
-2. Просканувати джерела за патернами Bun SQL
-3. Зібрати метадані про використання `pg` та LISTEN/NOTIFY
-4. Перевірити залежності `pg` та використання LISTEN/NOTIFY
-5. Перевірити імпорти `pg` та використання LISTEN/NOTIFY
-6. Перевірити наявність `package.json` для залежностей `pg`
-7. Перевірити використання `import { sql|SQL } from 'bun'`
-8. Перевірити відсутність створення `new SQL` всередині функцій
-9. Перевірити використання `sql.unsafe` без маркерів дозволу
-10. Перевірити використання `sql.unsafe` з template-літералами
-11. Перевірити використання `pg-leftover` викликів
-12. Перевірити використання `findBunSqlUnsafeBunSqlDynamicSqlListInText`
-13. Перевірити використання `findUnsafeBunSqlInListMissingEmptyGuardInText`
-14. Перевірити використання `findPgFormatShimDefinitionInText`
-15. Перевірити використання `findPgFormatLikeQueryWrapperInText`
-16. Перевірити наявність використання `import { sql } from 'bun'`
+1. Викликається `check` для початку перевірки.
+2. Перевіряється наявність `package.json` у корені репозиторію. Якщо відсутній, перевірка припиняється.
+3. Завантажуються конфігураційні шляхи, які ігноруються під час обходу.
+4. Знаходяться всі файли `package.json` у репозиторії. Якщо жоден не знайдено, перевірка припиняється.
+5. Знаходяться всі JS/TS джерела для сканування патернів Bun SQL. Якщо жоден не знайдено, перевірка припиняється.
+6. Скануються знайдені JS/TS джерела на небезпечні патерни Bun SQL. Збираються метадані про використання Bun SQL та про використання бібліотеки `pg` (LISTEN/NOTIFY).
+7. Перевіряється залежність `pg` у знайдених `package.json` на відповідність правилу: якщо `pg` є залежністю, у коді має бути хоча б одне використання LISTEN/NOTIFY.
+8. Перевіряється кожен файл, що імпортує `pg`. Якщо у ньому немає використання LISTEN/NOTIFY, реєструється порушення.
+9. Після завершення сканування та перевірок, реєструються всі знайдені порушення, пов'язані з Bun SQL (наприклад, створення `new SQL` всередині функцій, використання `sql.unsafe` без маркерів, проблеми з динамічними списками тощо).
+10. Якщо всі перевірки пройдені успішно, реєструється повідомлення про відповідність правилу `js-bun-db.mdc`.
 
 ## Публічний API
 
-check — Перевіряє відповідність проєкту правилу js-bun-db.mdc
+check — порівнює структуру проєкту з вимогами, описаними у js-bun-db.mdc
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/js-bun-db/js/safety.mjs

@@ -9,10 +9,12 @@ import {
   findBunSqlPgLeftoverCallInText,
   findBunSqlUnsafeUseWithoutAllowMarkerInText,
   findBunSqlUnsafeWithInterpolatedTemplateInText,
+  findJsonStringifyBeforeJsonbInText,
   findPgFormatLikeQueryWrapperInText,
   findPgFormatShimDefinitionInText,
   findPgLibImportInText,
   findPgListenNotifyUsageInText,
+  findSqlArrayWithoutTypeArgInText,
   findUnsafeBunSqlDynamicSqlListInText,
   findUnsafeBunSqlInListMissingEmptyGuardInText,
   isBunSqlScanSourceFile,
@@ -83,7 +85,9 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
     inListGuard: 0,
     pgLeftover: 0,
     pgFormatShim: 0,
-    queryWrapper: 0
+    queryWrapper: 0,
+    jsonStringifyJsonb: 0,
+    sqlArrayNoType: 0
   }
   let hasBunSqlImport = false
   /** @type {{ rel: string, imports: { line: number, snippet: string }[], listenNotify: { line: number, snippet: string, kind: string }[] }[]} */
@@ -127,7 +131,7 @@ function collectPgUsageForFile(content, rel, pgUsage) {
  * @param {string} content вміст файлу
  * @param {string} rel posix-шлях відносно `repoRoot`
  * @param {(msg: string) => void} fail callback при помилці
- * @param {{ perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number }} counts акумулятори
+ * @param {{ perRequest: number, unsafeCall: number, unsafeTemplateInterp: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number, jsonStringifyJsonb: number, sqlArrayNoType: number }} counts акумулятори
  * @returns {void}
  */
 function scanFileForBunSqlPatterns(content, rel, fail, counts) {
@@ -202,6 +206,22 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
         `sql\`...\${value}...\` (js-bun-db.mdc): ${v.snippet}`
     )
   }
+  for (const v of findJsonStringifyBeforeJsonbInText(content, rel)) {
+    counts.jsonStringifyJsonb++
+    fail(
+      `js-bun-db: ${rel}:${v.line} — JSON.stringify(...) перед ::jsonb зайвий: Bun SQL серіалізує ` +
+        `об'єкти/масиви у JSON автоматично, явний stringify призводить до подвійної серіалізації ` +
+        `(js-bun-db.mdc query-safety): ${v.snippet}`
+    )
+  }
+  for (const v of findSqlArrayWithoutTypeArgInText(content, rel)) {
+    counts.sqlArrayNoType++
+    fail(
+      `js-bun-db: ${rel}:${v.line} — sql.array(arr) без другого аргументу типу — ` +
+        `вкажи явний pg-тип: sql.array(arr, 'int8') / sql.array(arr, 'uuid') тощо ` +
+        `(js-bun-db.mdc sql-array): ${v.snippet}`
+    )
+  }
 }
 
 /**
@@ -338,7 +358,9 @@ export async function check(cwd = process.cwd()) {
     inListGuard,
     pgLeftover,
     pgFormatShim,
-    queryWrapper
+    queryWrapper,
+    jsonStringifyJsonb,
+    sqlArrayNoType
   } = await scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter)
 
   const { pgDepFails, pgImportFails, pgDepsFound, listenNotifyEvidence } = await checkPgDependencyAndUsage(
@@ -396,6 +418,12 @@ export async function check(cwd = process.cwd()) {
   if (queryWrapper === 0) {
     pass('js-bun-db: немає query(text, params)-обгорток над unsafe(...) у файлах з Bun SQL')
   }
+  if (jsonStringifyJsonb === 0) {
+    pass('js-bun-db: немає JSON.stringify(...) перед ::jsonb — Bun SQL серіалізує автоматично')
+  }
+  if (sqlArrayNoType === 0) {
+    pass('js-bun-db: усі sql.array() мають явний аргумент типу')
+  }
 
   return reporter.getExitCode()
 }

package/rules/js-bun-db/lib/bun-sql-scan.mjs

@@ -927,3 +927,126 @@ function kindFromListenNotifyMatch(text) {
 export function isBunSqlScanSourceFile(relativePathPosix) {
   return SOURCE_FILE_RE.test(relativePathPosix) && !relativePathPosix.endsWith('.d.ts')
 }
+
+// Імена відомих SQL-інстансів, для яких перевіряємо .array() без типу.
+const SQL_INSTANCE_NAMES = new Set(['sql', 'pgWrite', 'pgRead'])
+
+/**
+ * Чи це виклик `JSON.stringify(...)` (JSON.stringify через MemberExpression).
+ * @param {unknown} node AST node
+ * @returns {boolean}
+ */
+function isJsonStringifyCall(node) {
+  if (!node || typeof node !== 'object' || node.type !== 'CallExpression') return false
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return false
+  const obj = callee.object
+  const prop = callee.property
+  return (
+    !!obj &&
+    obj.type === 'Identifier' &&
+    obj.name === 'JSON' &&
+    !!prop &&
+    prop.type === 'Identifier' &&
+    prop.name === 'stringify'
+  )
+}
+
+/**
+ * Знаходить виклики `JSON.stringify(...)::jsonb` всередині SQL template literal-ів.
+ * Bun SQL серіалізує об'єкти/масиви у JSON автоматично — явний `JSON.stringify`
+ * перед `::jsonb` призводить до подвійної серіалізації (js-bun-db.mdc).
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору lang
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findJsonStringifyBeforeJsonbInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+
+  walkAstWithAncestors(program, [], node => {
+    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
+
+    const expressions = template.expressions
+    const quasis = template.quasis
+    if (!Array.isArray(expressions) || !Array.isArray(quasis)) return
+
+    for (const [i, expr] of expressions.entries()) {
+      // Перевіряємо прямий JSON.stringify(...) і JSON.stringify всередині sql.array(...)
+      const isDirectStringify = isJsonStringifyCall(expr)
+      // sql.array(batch.map(r => JSON.stringify(...)), 'jsonb')
+      const hasSqlArrayStringify =
+        !isDirectStringify &&
+        expr.type === 'CallExpression' &&
+        Array.isArray(expr.arguments) &&
+        expr.arguments.some(arg => {
+          if (isJsonStringifyCall(arg)) return true
+          // .map(r => JSON.stringify(...))
+          if (arg.type === 'CallExpression' && Array.isArray(arg.arguments)) {
+            const cb = arg.arguments[0]
+            if (!cb) return false
+            const body = cb.type === 'ArrowFunctionExpression' || cb.type === 'FunctionExpression' ? cb.body : null
+            if (body && isJsonStringifyCall(body)) return true
+          }
+          return false
+        })
+
+      if (!isDirectStringify && !hasSqlArrayStringify) continue
+
+      // Quasi після expr (quasi[i+1]) — текст одразу після закриваючого }
+      const nextQuasi = quasis[i + 1]
+      const rawAfter =
+        nextQuasi && typeof nextQuasi === 'object' && nextQuasi.value && typeof nextQuasi.value.raw === 'string'
+          ? nextQuasi.value.raw
+          : ''
+
+      if (/^\s*::jsonb/u.test(rawAfter) || hasSqlArrayStringify) {
+        out.push({
+          line: offsetToLine(content, expr.start),
+          snippet: normalizeSnippet(content.slice(expr.start, expr.end))
+        })
+      }
+    }
+  })
+  return out
+}
+
+/**
+ * Знаходить виклики `sql.array(arr)` / `pgWrite.array(arr)` / `pgRead.array(arr)` без
+ * обов'язкового другого аргументу (типу pg-елемента). Без типу Bun не може вивести
+ * pg-тип, що призводить до mismatch (js-bun-db.mdc).
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору lang
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findSqlArrayWithoutTypeArgInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+
+  walkAstWithAncestors(program, [], node => {
+    if (!node || node.type !== 'CallExpression') return
+    const callee = node.callee
+    if (!callee || callee.type !== 'MemberExpression' || callee.computed) return
+    const prop = callee.property
+    if (!prop || prop.type !== 'Identifier' || prop.name !== 'array') return
+    const obj = callee.object
+    if (!obj || obj.type !== 'Identifier' || !SQL_INSTANCE_NAMES.has(obj.name)) return
+    const args = node.arguments
+    if (!Array.isArray(args) || args.length !== 1) return
+
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}