@7n/rules-lang-js 0.3.1 → 0.4.1

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

@@ -0,0 +1,1047 @@
+/**
+ * AST-сканер небезпечних патернів Bun SQL (`import { sql, SQL } from 'bun'`).
+ *
+ * Знаходить:
+ * - `new SQL(...)` всередині функції — пул має бути singleton на рівні модуля,
+ *   а не на кожен виклик handler-а.
+ * - Будь-який виклик `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ *   на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
+ *   тільки якщо значення контролюється кодом (не user input) і потрібно підставити
+ *   назву таблиці/колонки або dynamic SQL/DDL. Інакше — переробити на tagged template
+ *   `sql\`...\${value}...\``. Маркер фіксує цю причину для ревʼюера.
+ * - Динамічні SQL-списки у tagged template `sql\`... IN (${arr.join(',')}) ...\``:
+ *   навіть «через tagged template» у запит потрапляє готовий шматок SQL замість
+ *   параметризованих значень — треба `sql([...])`.
+ *
+ * Семантика — через **oxc-parser**, без regex по тексту коду.
+ * Якщо файл не парситься / містить синтаксичні помилки — повертаємо порожній
+ * результат: спочатку треба полагодити синтаксис, потім перезапустити перевірку.
+ */
+import {
+  isFunctionNode,
+  isJoinCall,
+  isSqlListContextTemplate,
+  normalizeSnippet,
+  offsetToLine,
+  parseProgramAndCommentsOrNull,
+  parseProgramOrNull,
+  templateQuasisText,
+  walkAstWithAncestors
+} from '@7n/rules/scripts/utils/ast-scan-utils.mjs'
+
+// Текстовий сигнал bun-sql живе в ядрі (потрібен auto-rules для fact-збору); ре-експорт зберігає API lib-а
+export { textHasBunSqlImport } from '@7n/rules/scripts/lib/js-source-signals.mjs'
+import { textHasBunSqlImport } from '@7n/rules/scripts/lib/js-source-signals.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+// Імпорт із npm-пакета `pg` — будь-яка з форм: default, named, namespace, side-effect,
+// а також `require('pg')`. `pg-format`/`pg-pool` свідомо НЕ матчаться: на них діє
+// окрема заборона (denylist) і свої повідомлення. Виключення для LISTEN/NOTIFY
+// стосується лише самого клієнта `pg`.
+const PG_LIB_IMPORT_RE = /(?:\bimport\b[\s\S]*?\bfrom\s*["']pg["']|\brequire\s*\(\s*["']pg["']\s*\))/u
+// Першоквазі-рядок або string literal, що починається з LISTEN / UNLISTEN / NOTIFY
+// (case-insensitive), з опційним leading whitespace. Сигнал, що в коді запит
+// `LISTEN ch` / `NOTIFY ch, 'msg'` / `UNLISTEN *` — це функціонал, якого Bun SQL
+// поки не має, тож у проекті лишається легітимна потреба у клієнті `pg`.
+const PG_LISTEN_NOTIFY_SQL_RE = /^\s*(LISTEN|UNLISTEN|NOTIFY)\b/iu
+const IN_PLACEHOLDER_END_RE = /\bin\s*(\(\s*)?$/iu
+// `// allow-unsafe: <reason>` — `allow-unsafe`, двокрапка, **непорожня** причина.
+// Без причини маркер не приймається: ціль — лишити слід для ревʼюера, а не «німий» прапорець.
+const ALLOW_UNSAFE_MARKER_RE = /\ballow-unsafe\s*:\s*\S+/u
+// `// allow-pg-leftover: <reason>` — opt-in для виправданих `.connect()` / `.end()`
+// у файлах з Bun SQL (наприклад, `sql.end()` у graceful shutdown або `.connect()`
+// на сторонньому об'єкті, що випадково ділить імʼя методу з `pg`).
+const ALLOW_PG_LEFTOVER_MARKER_RE = /\ballow-pg-leftover\s*:\s*\S+/u
+// pg-API, які не потрібні з Bun SQL: pool/client життєвий цикл вручну.
+// `release` не входить — Bun SQL такого методу не має, а `.connect()` / `.end()`
+// формально існують і там, тому опт-аут маркером лишається доречним.
+const PG_LEFTOVER_METHOD_NAMES = new Set(['connect', 'end'])
+
+// pg-format placeholders — `%L` (literal), `%I` (identifier), `%s` (raw string).
+// Якщо у тілі функції з підозрілим іменем зустрічається такий літерал/regex —
+// це pg-format-сумісний шим (drop-in замінник pg-format поверх Bun SQL).
+const PG_FORMAT_PLACEHOLDER_RE = /%[LIs]/u
+// Імена функцій-кандидатів на pg-format-шим. Спрацьовує лише у поєднанні
+// з наявністю `%L` / `%I` / `%s` у тілі — щоб не плутати з невинним `format(date)`.
+const PG_FORMAT_SHIM_FUNC_NAMES = new Set(['format', 'pgFormat', 'sqlFormat', 'pgFmt'])
+// Імена quote/escape-хелперів — самі по собі сильний сигнал pg-format-шиму,
+// без додаткової перевірки тіла. Це pg-format-специфічні API, нерідко публікуються
+// як named export з модуля-обгортки.
+const QUOTE_HELPER_NAMES = new Set(['quoteLiteral', 'quoteIdent', 'escapeLiteral', 'escapeIdent'])
+
+// Імена першого параметра pg-style query-обгортки (`function query(text, params)` тощо).
+const PG_QUERY_FIRST_PARAM_RE = /^(text|sql|query)$/u
+
+/**
+ * @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`).
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо це `new SQL(...)`
+ */
+function isNewSqlConstructor(node) {
+  if (!node || node.type !== 'NewExpression') return false
+  const callee = node.callee
+  return !!callee && callee.type === 'Identifier' && callee.name === 'SQL'
+}
+
+/**
+ * Чи це виклик `<obj>.unsafe(...)` (будь-який обʼєкт, не тільки `sql`).
+ * Файл сканується лише якщо є `import { sql|SQL } from 'bun'`, тож у практиці це
+ * або `sql.unsafe`, або `tx.unsafe` всередині `sql.begin(async tx => ...)` —
+ * обидва однаково небезпечні, тому розрізняти імʼя обʼєкта не треба.
+ * @param {unknown} node AST node
+ * @returns {boolean} true для будь-якого `<obj>.unsafe(...)`
+ */
+function isUnsafeCall(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 === 'unsafe'
+}
+
+/**
+ * Чи є біля виклику маркер-коментар, що матчиться на `markerRe`, на тому ж рядку,
+ * що й початок виклику, або на рядку, що передує початку виклику. Це навмисно строга
+ * суміжність: відірваний коментар через порожній рядок не зараховується — щоб маркер
+ * стояв саме біля виклику, а не «загубився десь вище».
+ *
+ * Використовується для opt-in маркерів типу `// allow-unsafe: ...` і `// allow-pg-leftover: ...`.
+ * @param {{ start: number }} callNode виклик
+ * @param {{ type: 'Line' | 'Block', value: string, start: number, end: number }[]} comments коментарі з парсера
+ * @param {string} content вихідний код
+ * @param {RegExp} markerRe регекс, що валідує текст маркера в `comment.value`
+ * @returns {boolean} true, якщо маркер знайдено
+ */
+function hasMarkerCommentNear(callNode, comments, content, markerRe) {
+  const callStartLine = offsetToLine(content, callNode.start)
+  for (const c of comments) {
+    if (!c || (c.type !== 'Line' && c.type !== 'Block')) continue
+    if (typeof c.value !== 'string' || !markerRe.test(c.value)) continue
+    const startLine = offsetToLine(content, c.start)
+    // trailing-коментар на тому ж рядку (`<call> // marker: ...`)
+    if (startLine === callStartLine) return true
+    // коментар на рядку, що безпосередньо передує виклику — для блокових
+    // коментарів важливим є саме `endLine`, бо block може займати кілька рядків.
+    const endLine = offsetToLine(content, c.end)
+    if (endLine === callStartLine - 1) return true
+  }
+  return false
+}
+
+/**
+ * Чи це pg-leftover виклик: `<obj>.connect(...)` або `<obj>.end(...)`. Bun SQL пулом
+ * керує сам — і `.connect()`, і `.end()` у файлах з Bun SQL зазвичай зайві, тож такі
+ * виклики прапоруються (з opt-in маркером для рідкісних легітимних випадків).
+ * @param {unknown} node AST node
+ * @returns {{ name: 'connect' | 'end' } | null} ім'я pg-leftover методу або null
+ */
+function asPgLeftoverCall(node) {
+  if (!node || node.type !== 'CallExpression') return null
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return null
+  const prop = callee.property
+  if (!prop || prop.type !== 'Identifier' || typeof prop.name !== 'string') return null
+  if (!PG_LEFTOVER_METHOD_NAMES.has(prop.name)) return null
+  return { name: /** @type {'connect' | 'end'} */ (prop.name) }
+}
+
+// Локальний alias на `isUnsafeCall` — щоб у nodeContainsUnsafeCall (під query-шимом)
+// був семантично-говорящий call-site, але без дубля логіки з основним сканом.
+const isUnsafeCallNode = isUnsafeCall
+
+/**
+ * Витягує ім'я ключа з AST `Property.key`. Підтримує `Identifier` (`{ foo: … }`)
+ * та `Literal` (`{ 'foo': … }` / `{ 5: … }`); інші форми (computed expression тощо) — `null`.
+ * @param {unknown} key AST `Property.key`
+ * @returns {string | number | null} ім'я ключа або null
+ */
+function propertyKeyName(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' || typeof key.value === 'number')) return key.value
+  return null
+}
+
+/**
+ * Чи містить піддерево вузла рядковий або regex-літерал з `%L` / `%I` / `%s`.
+ * Покриває:
+ * - `Literal` зі строковим `value`,
+ * - `StringLiteral` (oxc),
+ * - `TemplateLiteral` (через текст quasis),
+ * - `RegExpLiteral` / `Literal` з `regex.pattern`.
+ * @param {unknown} root корінь піддерева (зазвичай тіло функції)
+ * @returns {boolean} true, якщо знайдено pg-format-плейсхолдер
+ */
+function nodeContainsPgFormatPlaceholder(root) {
+  let found = false
+  walkAstWithAncestors(root, [], n => {
+    if (found) return
+    const t = n.type
+    if (t === 'Literal' || t === 'StringLiteral') {
+      if (typeof n.value === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(n.value)) {
+        found = true
+        return
+      }
+      const regex = n.regex
+      if (regex && typeof regex.pattern === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(regex.pattern)) {
+        found = true
+        return
+      }
+    }
+    if (t === 'RegExpLiteral' && typeof n.pattern === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(n.pattern)) {
+      found = true
+      return
+    }
+    if (t === 'TemplateLiteral' && PG_FORMAT_PLACEHOLDER_RE.test(templateQuasisText(n))) {
+      found = true
+    }
+  })
+  return found
+}
+
+/**
+ * Витягає (name, body) з вузла, що оголошує функцію верхнього рівня:
+ * - `function format(...) {...}`,
+ * - `const format = (...) => {...}` / `= function(...) {...}`.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {{ name: string, body: unknown } | null} ім'я та тіло, або null
+ */
+function asNamedFunctionDecl(node) {
+  if (node.type === 'FunctionDeclaration' && node.id?.type === 'Identifier') {
+    return { name: node.id.name, body: node.body }
+  }
+  if (node.type === 'VariableDeclarator' && node.id?.type === 'Identifier') {
+    const init = node.init
+    if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+      return { name: node.id.name, body: init.body }
+    }
+  }
+  return null
+}
+
+/**
+ * Знаходить визначення pg-format-сумісних шимів у джерелі. Прапорує:
+ * - функції з іменами `format` / `pgFormat` / `sqlFormat` / `pgFmt`, у тілі яких
+ *   зустрічається літерал/regex з `%L` / `%I` / `%s` — це drop-in pg-format;
+ * - функції з іменами `quoteLiteral` / `quoteIdent` / `escapeLiteral` / `escapeIdent`
+ *   незалежно від тіла — це pg-format-специфічні API, не потрібні з Bun SQL.
+ *
+ * Скан запускається лише в файлах, де є `import { sql|SQL } from 'bun'`, щоб
+ * не плутати, наприклад, форматер дат чи URL-escape з SQL-шимом.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, kind: 'format_function' | 'quote_helper', name: string }[]} список порушень
+ */
+export function findPgFormatShimDefinitionInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string, kind: 'format_function' | 'quote_helper', name: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    const decl = asNamedFunctionDecl(node)
+    if (!decl) return
+    /** @type {'format_function' | 'quote_helper' | null} */
+    let kind = null
+    if (QUOTE_HELPER_NAMES.has(decl.name)) {
+      kind = 'quote_helper'
+    } else if (PG_FORMAT_SHIM_FUNC_NAMES.has(decl.name) && nodeContainsPgFormatPlaceholder(decl.body)) {
+      kind = 'format_function'
+    }
+    if (!kind) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, Math.min(node.end, node.start + 240))),
+      kind,
+      name: decl.name
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить pg-сумісні query-обгортки виду
+ * `{ query(text, params) { return <sql>.unsafe(text, params) } }`
+ * у файлах, що імпортують Bun SQL. Така обгортка маскує `unsafe` під
+ * «безпечним» ім'ям і повертає injection-поверхню в код.
+ *
+ * Спрацьовує, коли всі умови виконані:
+ * - вузол — `Property` з `key.name === 'query'` всередині `ObjectExpression`;
+ * - значення — функція з 1–2 параметрами, перший — Identifier з типовим
+ *   pg-іменем (`text` / `sql` / `query`);
+ * - у тілі функції є виклик `<obj>.unsafe(...)`.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findPgFormatLikeQueryWrapperInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (node.type !== 'ObjectExpression' || !Array.isArray(node.properties)) return
+    for (const prop of node.properties) {
+      const queryProp = asPgFormatLikeQueryProp(prop)
+      if (!queryProp) continue
+      out.push({
+        line: offsetToLine(content, queryProp.start),
+        snippet: normalizeSnippet(content.slice(queryProp.start, queryProp.end))
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * Чи є цей вузол `Property` тим самим pg-сумісним `{ query(text, params) { … unsafe … } }`?
+ * Повертає сам `prop` (для зручного `start`/`end`) або `null`.
+ * @param {unknown} prop AST вузол `Property`
+ * @returns {{ start: number, end: number } | null} `prop` як власний рекорд або `null`
+ */
+function asPgFormatLikeQueryProp(prop) {
+  if (!prop || typeof prop !== 'object' || prop.type !== 'Property') return null
+  if (propertyKeyName(prop.key) !== 'query') return null
+  const value = prop.value
+  if (!value || (value.type !== 'FunctionExpression' && value.type !== 'ArrowFunctionExpression')) return null
+  if (!hasPgQuerySignature(value.params)) return null
+  if (!nodeContainsUnsafeCall(value.body)) return null
+  return { start: prop.start, end: prop.end }
+}
+
+/**
+ * Чи виглядає сигнатура функції як pg-style `query(text, params?)`: 1–2 параметри,
+ * перший — Identifier з типовим pg-іменем (`text` / `sql` / `query`).
+ * @param {unknown} params AST `params` (масив)
+ * @returns {boolean} true, якщо схоже на pg-обгортку
+ */
+function hasPgQuerySignature(params) {
+  if (!Array.isArray(params) || params.length < 1 || params.length > 2) return false
+  const first = params[0]
+  if (!first || first.type !== 'Identifier' || typeof first.name !== 'string') return false
+  return PG_QUERY_FIRST_PARAM_RE.test(first.name)
+}
+
+/**
+ * Чи є у піддереві виклик `<obj>.unsafe(...)`.
+ * @param {unknown} root корінь піддерева
+ * @returns {boolean} true, якщо знайдено
+ */
+function nodeContainsUnsafeCall(root) {
+  let found = false
+  walkAstWithAncestors(root, [], n => {
+    if (found) return
+    if (isUnsafeCallNode(n)) found = true
+  })
+  return found
+}
+
+/**
+ * Знаходить `new SQL(...)` всередині функцій (handler на кожен запит замість singleton).
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findBunSqlPerRequestConnectionInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], (node, ancestors) => {
+    if (!isNewSqlConstructor(node)) return
+    const insideFunction = ancestors.some(n => isFunctionNode(n))
+    if (!insideFunction) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить виклики `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ * на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
+ * лише коли значення контролюється кодом (не user input) і потрібно підставити те, що
+ * не можна параметризувати — назву таблиці/колонки або dynamic SQL/DDL. У всіх інших
+ * випадках — переробити на tagged template виду `sql` із інтерполяцією значень.
+ * Маркер-коментар фіксує причину для ревʼюера й одночасно слугує opt-in: без нього
+ * перевірка падає, навіть якщо у `unsafe` лежить статичний рядок без інтерполяції.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findBunSqlUnsafeUseWithoutAllowMarkerInText(content, virtualPath = 'scan.ts') {
+  const parsed = parseProgramAndCommentsOrNull(content, virtualPath)
+  if (!parsed) return []
+  const { program, comments } = parsed
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (!isUnsafeCall(node)) return
+    if (hasMarkerCommentNear(node, comments, content, ALLOW_UNSAFE_MARKER_RE)) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить `<obj>.unsafe(template_literal_with_interpolation)` — навіть із маркером
+ * `// allow-unsafe`. Шаблонна підстановка `${name}` у `sql.unsafe`-рядок **не екранує**
+ * identifier'ів (reserved words, спецсимволи) і ніяк не біндить значення — це
+ * структурна injection-поверхня, яку легко не помітити в ревʼю. Канон — побудувати
+ * `text` через `@scaleleap/pg-format` `format('%I', name)` (для identifiers) або
+ * звичайні позиційні `$N`-placeholder'и (для values), і передати в `sql.unsafe(text, [params])`.
+ *
+ * Прапорує саме `TemplateLiteral` з `expressions.length > 0`; статичні рядки
+ * (`Literal`, `StringLiteral`, `TemplateLiteral` без `${...}`) і виклики з готовим
+ * `text` як змінною — не зачіпає (для них діє основна перевірка allow-unsafe).
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findBunSqlUnsafeWithInterpolatedTemplateInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (!isUnsafeCall(node)) return
+    const args = node.arguments
+    if (!Array.isArray(args) || args.length === 0) return
+    const first = args[0]
+    if (!first || first.type !== 'TemplateLiteral') return
+    const expressions = first.expressions
+    if (!Array.isArray(expressions) || expressions.length === 0) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить pg-leftover виклики `<obj>.connect(...)` / `<obj>.end(...)` без маркера
+ * `// allow-pg-leftover: <reason>` у файлах, де **в цьому ж файлі** є `import { sql|SQL } from 'bun'`.
+ *
+ * Скоп навмисно вузький: ці метод-імена занадто загальні (WebSocket, Stream, інші бібліотеки),
+ * тож сканер обмежений файлами, що вже використовують Bun SQL — там pg-залишок є явним
+ * багом міграції. У не-Bun-SQL файлах прапоратися не буде, навіть якщо проєкт у цілому
+ * мігрував.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, methodName: 'connect' | 'end' }[]} список порушень
+ */
+export function findBunSqlPgLeftoverCallInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const parsed = parseProgramAndCommentsOrNull(content, virtualPath)
+  if (!parsed) return []
+  const { program, comments } = parsed
+
+  /** @type {{ line: number, snippet: string, methodName: 'connect' | 'end' }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    const m = asPgLeftoverCall(node)
+    if (!m) return
+    if (hasMarkerCommentNear(node, comments, content, ALLOW_PG_LEFTOVER_MARKER_RE)) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end)),
+      methodName: m.name
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить динамічні SQL-списки у TaggedTemplateExpression / TemplateLiteral в контексті
+ * `IN (...)` або `VALUES (...)`, де серед expressions є виклик `.join(...)`.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findUnsafeBunSqlDynamicSqlListInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    /** @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
+    const expressions = template.expressions
+    if (!Array.isArray(expressions) || expressions.length === 0) return
+    if (expressions.every(expr => !isJoinCall(expr))) return
+    out.push({
+      line: offsetToLine(content, template.start),
+      snippet: normalizeSnippet(content.slice(template.start, template.end))
+    })
+  })
+  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
+  if (!Array.isArray(expressions) || expressions.length === 0) return
+  const quasis = template.quasis
+  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
+}
+
+/**
+ * Чи імпортує файл npm-пакет `pg` (`import ... from 'pg'` або `require('pg')`).
+ * Текстова перевірка — без AST, дешевий pre-filter; для строгої локалізації
+ * (рядок/snippet) використай `findPgLibImportInText`. Не матчить `pg-format`,
+ * `pg-pool`, `@types/pg` — лише сам клієнт.
+ * @param {string} content вміст файлу
+ * @returns {boolean} true, якщо у файлі є імпорт `'pg'`
+ */
+export function textHasPgLibImport(content) {
+  return PG_LIB_IMPORT_RE.test(content)
+}
+
+/**
+ * Знаходить ImportDeclaration / CallExpression `require('pg')` для пакета `pg`
+ * (саме точна назва, не `pg-format` тощо). Повертає рядок і snippet — щоб у
+ * повідомленнях `fail` показати конкретне місце.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список місць, де імпортується `pg`
+ */
+export function findPgLibImportInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (node.type === 'ImportDeclaration' && getStringLiteralValue(node.source) === 'pg') {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end))
+      })
+      return
+    }
+    if (node.type === 'CallExpression' && isRequireOfModule(node, 'pg')) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end))
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * Знаходить використання PostgreSQL LISTEN/NOTIFY у коді — сигнал, що проект
+ * потребує `pg` як виняток (Bun SQL поки не реалізує LISTEN/NOTIFY). Прапорує:
+ * - `<obj>.query(...)` / `<obj>.queryArray(...)` / `<obj>.queryStream(...)`, де
+ *   перший аргумент — string literal або template literal, що починається з
+ *   `LISTEN ` / `UNLISTEN ` / `NOTIFY ` (case-insensitive);
+ * - `<obj>.on('notification', ...)` — pg-listener notification-подій (другий
+ *   аргумент — функція; перший — точно рядок `'notification'`);
+ * - TaggedTemplateExpression виду sql tagged template з LISTEN/UNLISTEN/NOTIFY
+ *   на початку першого quasi — на випадок, якщо хтось використовує Bun
+ *   SQL-tagged-template, а LISTEN/NOTIFY все одно лишається у тексті запиту
+ *   (це не запрацює у Bun SQL, але як сигнал — приймаємо).
+ *
+ * Регістр SQL-слів не важливий, провідні пробіли допускаються.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, kind: 'listen_sql' | 'notify_sql' | 'unlisten_sql' | 'notification_listener' }[]} список знахідок
+ */
+export function findPgListenNotifyUsageInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string, kind: 'listen_sql' | 'notify_sql' | 'unlisten_sql' | 'notification_listener' }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    const fromCall = listenNotifyFromCallExpression(node)
+    if (fromCall) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        kind: fromCall
+      })
+      return
+    }
+    const fromTagged = listenNotifyFromTaggedTemplate(node)
+    if (fromTagged) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        kind: fromTagged
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * @param {Record<string, unknown>} node ImportDeclaration.source або CallExpression.arguments[0]
+ * @returns {string | null} значення string literal або null
+ */
+function getStringLiteralValue(node) {
+  if (!node || typeof node !== 'object') return null
+  if ((node.type === 'Literal' || node.type === 'StringLiteral') && typeof node.value === 'string') {
+    return node.value
+  }
+  return null
+}
+
+/**
+ * Чи це `require('<moduleName>')` — CallExpression з callee Identifier `require`
+ * і єдиним string-літералом-аргументом.
+ * @param {Record<string, unknown>} node CallExpression
+ * @param {string} moduleName очікувана назва модуля (точне співпадіння)
+ * @returns {boolean} true, якщо це саме require цього модуля
+ */
+function isRequireOfModule(node, moduleName) {
+  const callee = node.callee
+  if (!callee || callee.type !== 'Identifier' || callee.name !== 'require') return false
+  const args = node.arguments
+  if (!Array.isArray(args) || args.length !== 1) return false
+  return getStringLiteralValue(args[0]) === moduleName
+}
+
+/**
+ * Аналізує CallExpression на предмет pg-style LISTEN/NOTIFY-запиту або listener'а
+ * подій `'notification'`. Повертає тип сигналу або `null`.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | 'notification_listener' | null} kind знахідки
+ */
+function listenNotifyFromCallExpression(node) {
+  if (!node || node.type !== 'CallExpression') return null
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return null
+  const prop = callee.property
+  if (!prop || prop.type !== 'Identifier' || typeof prop.name !== 'string') return null
+  const args = node.arguments
+  if (!Array.isArray(args) || args.length === 0) return null
+
+  if (prop.name === 'on') {
+    return getStringLiteralValue(args[0]) === 'notification' ? 'notification_listener' : null
+  }
+  if (prop.name === 'query' || prop.name === 'queryArray' || prop.name === 'queryStream') {
+    return sqlStringStartsWithListenNotify(args[0])
+  }
+  return null
+}
+
+/**
+ * Аналізує TaggedTemplateExpression: якщо перший quasi починається з
+ * LISTEN/UNLISTEN/NOTIFY — повертає відповідний kind.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | null} kind знахідки
+ */
+function listenNotifyFromTaggedTemplate(node) {
+  if (!node || node.type !== 'TaggedTemplateExpression') return null
+  const quasi = node.quasi
+  if (!quasi || quasi.type !== 'TemplateLiteral') return null
+  const text = templateQuasisText(quasi)
+  return kindFromListenNotifyMatch(text)
+}
+
+/**
+ * Перший аргумент виклику `.query(...)` — це string literal або template literal,
+ * текст якого починається з LISTEN / UNLISTEN / NOTIFY (case-insensitive)?
+ * @param {unknown} arg AST node першого аргумента
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | null} kind знахідки або null
+ */
+function sqlStringStartsWithListenNotify(arg) {
+  if (!arg || typeof arg !== 'object') return null
+  if ((arg.type === 'Literal' || arg.type === 'StringLiteral') && typeof arg.value === 'string') {
+    return kindFromListenNotifyMatch(arg.value)
+  }
+  if (arg.type === 'TemplateLiteral') {
+    return kindFromListenNotifyMatch(templateQuasisText(arg))
+  }
+  return null
+}
+
+/**
+ * Перетворює текст SQL-рядка у kind знахідки (`listen_sql` / `notify_sql` /
+ * `unlisten_sql`) або `null`, якщо рядок не починається з ключового слова.
+ * @param {string} text SQL-текст
+ * @returns {'listen_sql' | 'notify_sql' | 'unlisten_sql' | null} kind знахідки
+ */
+function kindFromListenNotifyMatch(text) {
+  const m = PG_LISTEN_NOTIFY_SQL_RE.exec(text)
+  if (!m) return null
+  const keyword = m[1].toUpperCase()
+  if (keyword === 'LISTEN') return 'listen_sql'
+  if (keyword === 'NOTIFY') return 'notify_sql'
+  return 'unlisten_sql'
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сімʼя, без `.d.ts`).
+ * @param {string} relativePathPosix відносний шлях (posix)
+ * @returns {boolean} true, якщо розширення підходить для AST-скану
+ */
+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'])
+
+// Текст одразу після ${...} починається з `::jsonb`-касту.
+const JSONB_CAST_RE = /^\s*::jsonb/u
+
+/**
+ * Чи це виклик `JSON.stringify(...)` (JSON.stringify через MemberExpression).
+ * @param {unknown} node AST node
+ * @returns {boolean} true, якщо node — виклик `JSON.stringify(...)`.
+ */
+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 (JSONB_CAST_RE.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
+}