@nitra/cursor 3.22.0 → 3.23.1

package/rules/js-mssql/lib/docs/mssql-pool-scan.md

@@ -0,0 +1,367 @@
+# mssql-pool-scan.mjs
+
+## Огляд
+
+Модуль `mssql-pool-scan.mjs` — це набір AST-сканерів, що шукають **небезпечні патерни використання драйвера `mssql`** (Microsoft SQL Server для Node.js) у вихідних файлах JavaScript / TypeScript. Сканери призначені для статичного аналізу й використовуються з правил `js-mssql` (див. `js-mssql.mdc`).
+
+Модуль виявляє п'ять класів проблем:
+
+1. **Створення `new sql.ConnectionPool(...)` / `new mssql.ConnectionPool(...)` всередині функції.** Це антипатерн: пул має бути singleton на рівні модуля, а не створюватися на кожен запит/виклик.
+2. **Небезпечний виклик `query(\`...\`)`** — звичайний `CallExpression` з `TemplateLiteral` як першим аргументом (не tagged template). Це може призвести до **SQL injection**, бо інтерполяція відбувається на рівні JS і в SQL потрапляє вже склеєний рядок.
+3. **Shared `Request`** — `export const request = pool.request()` (або `const request = pool.request()`), який не можна повторно використовувати між запитами в драйвері `mssql`.
+4. **Динамічні SQL-списки через `.join(...)`** у `TemplateLiteral` / `TaggedTemplateExpression` у контексті `IN (...)` або `VALUES (...)`. Навіть у tagged template це небезпечно, бо в запит підставляється готовий шматок SQL.
+5. **`IN (${...})` без числового парсера й/або без guard-перевірки на порожній список.** Навіть у безпечному tagged template значення треба явно приводити до Number/BigInt і відкидати NaN, а перед запитом — перевіряти, що список не порожній (`if (!ids.length) throw ...`).
+
+Парсинг виконується через **`oxc-parser`** (`parseSync`). Якщо файл не парситься або містить синтаксичні помилки — кожна функція повертає **порожній масив** (треба спочатку полагодити синтаксис і перезапустити сканування).
+
+Файл живе всередині `npm/rules/js-mssql/lib/` й експортує **6 публічних функцій** (5 сканерів + 1 фільтр розширень файлів). Допоміжні функції (перевірки AST-вузлів, трасування Identifier-ів) — приватні.
+
+---
+
+## Експорти / API
+
+| Експорт                                                               | Тип      | Призначення                                                                               |
+| --------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `findMssqlPerRequestConnectionInText(content, virtualPath?)`          | function | Знайти `new sql.ConnectionPool(...)` / `new mssql.ConnectionPool(...)` всередині функцій. |
+| `findUnsafeMssqlQueryTemplateCallInText(content, virtualPath?)`       | function | Знайти `obj.query(\`...\`)`— небезпечну інтерполяцію в`query(...)`.                       |
+| `findSharedMssqlRequestInText(content, virtualPath?)`                 | function | Знайти shared `Request`: `const request = something.request()`.                           |
+| `findUnsafeMssqlDynamicSqlListInText(content, virtualPath?)`          | function | Знайти `IN (...)` / `VALUES (...)` зі склеєним `.join(',')` у `${...}`.                   |
+| `findUnsafeMssqlInListUnparsedInText(content, virtualPath?)`          | function | Знайти `IN (${expr})`, де `expr` не пройшов числовий парсер.                              |
+| `findUnsafeMssqlInListMissingEmptyGuardInText(content, virtualPath?)` | function | Знайти `IN (${...})` без guard `if (empty) throw` (або без винесення у змінну).           |
+| `isMssqlScanSourceFile(relativePathPosix)`                            | function | Фільтр файлів для сканування за розширенням.                                              |
+
+### Загальна форма результату сканерів
+
+Усі сканери, окрім останнього missing-guard-сканера, повертають масив об'єктів виду:
+
+```
+{
+  line: number,    // 1-based номер рядка в content
+  snippet: string  // нормалізований фрагмент вихідного коду (через normalizeSnippet)
+}
+```
+
+Сканер `findUnsafeMssqlInListMissingEmptyGuardInText` додатково повертає поля `reason: 'not_var' | 'missing_guard'` та опційне `name: string` (імʼя Identifier-у, для якого не знайдено guard).
+
+`isMssqlScanSourceFile` повертає `boolean`.
+
+### Спільні параметри сканерів
+
+- `content: string` — повний вихідний код файлу.
+- `virtualPath: string` — необовʼязковий «віртуальний» шлях файлу (наприклад `pkg/src/db.ts`), потрібний `oxc-parser`, щоб обрати мову (`lang`) через `langFromPath`. За замовчуванням — `'scan.ts'`.
+
+---
+
+## Функції
+
+### Експортовані функції
+
+#### `findMssqlPerRequestConnectionInText(content, virtualPath = 'scan.ts')`
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string }[]`
+- **Параметри:**
+  - `content` — вихідний код для сканування.
+  - `virtualPath` — шлях для вибору мови парсера (`lang`).
+- **Повертає:** масив порушень `{ line, snippet }`. Порожній масив, якщо файл не парситься або немає порушень.
+- **Що шукає:** `NewExpression` виду `new sql.ConnectionPool(...)` або `new mssql.ConnectionPool(...)` (через `isNewConnectionPool`), і лише ті, що **знаходяться всередині будь-якої функції** (перевірка через `ancestors.some(isFunctionNode)`).
+- **Side effects:** немає (чиста функція). Не кидає винятків — парсинг обгорнуто в `try/catch`.
+
+#### `findUnsafeMssqlQueryTemplateCallInText(content, virtualPath = 'scan.ts')`
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string }[]`
+- **Параметри:**
+  - `content` — вихідний код.
+  - `virtualPath` — шлях файлу для вибору `lang`.
+- **Повертає:** масив `{ line, snippet }` для всіх `CallExpression`, що відповідають `<obj>.query(\`...\`)`(метод`.query`без квадратних дужок, перший аргумент —`TemplateLiteral`).
+- **Side effects:** немає.
+
+#### `findSharedMssqlRequestInText(content, virtualPath = 'scan.ts')`
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string }[]`
+- **Параметри:** як вище.
+- **Повертає:** масив `{ line, snippet }`. Включає `VariableDeclarator`, у яких:
+  - `id` — `Identifier` з імʼям рівно `request`;
+  - `init` — `CallExpression` виду `<obj>.request()` (через `isRequestFactoryCall`).
+- **Side effects:** немає.
+
+#### `findUnsafeMssqlDynamicSqlListInText(content, virtualPath = 'scan.ts')`
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string }[]`
+- **Параметри:** як вище.
+- **Повертає:** масив `{ line, snippet }`. Виявляє `TemplateLiteral` або `TaggedTemplateExpression` (через `.quasi`), які одночасно:
+  - Знаходяться в SQL-контексті списку `IN (...)` / `VALUES (...)` — через `isSqlListContextTemplate` (із `ast-scan-utils`).
+  - Містять у `template.expressions` хоча б одну `CallExpression` `.join(...)` — через `isJoinCall`.
+- `line`/`snippet` беруться по координатам `template.start` / `template.end`.
+- **Side effects:** немає.
+
+#### `findUnsafeMssqlInListUnparsedInText(content, virtualPath = 'scan.ts')`
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string }[]`
+- **Параметри:** як вище.
+- **Повертає:** масив `{ line, snippet }`. Виявляє `TemplateLiteral`, у яких:
+  - Quasi прямо перед `expressions[i]` закінчується на `IN (` (regex `IN_PLACEHOLDER_END_RE`, `/\bin\s*\(\s*$/iu`).
+  - Сам вираз `${...}` **не** є «безпечно числовим» за критеріями `isInListExpressionParsed` (літеральний масив чисел / піддерево з `parseInt|parseFloat|Number|BigInt|+x` / Identifier з безпечним `init`).
+  - Вираз — не `.join(...)` (це покривається окремим сканером `findUnsafeMssqlDynamicSqlListInText`).
+- Перед скануванням збирає всі `VariableDeclarator`-и в програмі через `collectVariableDeclarators` — щоб трасувати Identifier до його init у тому ж файлі.
+- `line` рахується по `expr.start` (або, якщо не визначено, по `node.start`); `snippet` — від `node.start` до `node.end`.
+- **Side effects:** немає.
+
+#### `findUnsafeMssqlInListMissingEmptyGuardInText(content, virtualPath = 'scan.ts')`
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string, reason: 'not_var' | 'missing_guard', name?: string }[]`
+- **Параметри:** як вище.
+- **Повертає:** масив порушень. На кожен `${expr}` у позиції `IN (...)`:
+  - Якщо `expr` — **не** `Identifier`, порушення з `reason: 'not_var'` (значення мали бути винесені у змінну, щоб мати точку для guard).
+  - Якщо `expr` — `Identifier` `name`, але в enclosing-блоці перед поточним statement немає guard `if (empty(name)) throw`, — порушення з `reason: 'missing_guard'` і `name: <identifier>`.
+  - Якщо guard є, порушення не додається.
+- `line`/`snippet` беруться по `node.start` / `node.end` всього `TemplateLiteral`.
+- **Side effects:** немає.
+
+#### `isMssqlScanSourceFile(relativePathPosix)`
+
+- **Сигнатура:** `(relativePathPosix: string) => boolean`
+- **Параметри:** `relativePathPosix` — відносний шлях файлу у posix-форматі.
+- **Повертає:** `true`, якщо файл має розширення `.js | .mjs | .cjs | .jsx | .ts | .mts | .cts | .tsx` (regex `SOURCE_FILE_RE` = `/\.([cm]?[jt]sx?)$/`) **і** не закінчується на `.d.ts` (декларації типів виключені).
+- **Side effects:** немає.
+
+### Приватні допоміжні функції
+
+#### Локалізація `IN (...)` і числові гарантії
+
+- `isZeroLiteral(node)` — `node` є літералом `0` (`NumericLiteral`/`Literal` зі значенням `0`).
+- `isLengthMemberOf(node, name)` — `node` — некомпʼютоване `MemberExpression` `name.length`.
+- `isEmptyListBinaryTest(test, name)` — `BinaryExpression` з оператором з `EMPTY_LIST_BINARY_OPERATORS` = `{ '===', '==', '<=', '<' }`, що порівнює `name.length` із літералом `0`. Для `===` і `==` (`EMPTY_LIST_REVERSED_OPERATORS`) дозволяється зворотний порядок (`0 === name.length`).
+- `isEmptyListTest(test, name)` — тест if-умови виду `!name.length` або `name.length {===,==,<=} 0`, або `name.length < 1`. **Зауваження:** `<` із порівнянням з `0` через `isEmptyListBinaryTest` дає вираз `name.length < 0` (завжди false), що рідко зустрічається на практиці; типовий `length < 1` теж покривається через оператор `<` з правою частиною `1` — але `isZeroLiteral` приймає лише `0`, тож насправді `< 1` **не** розпізнається. (Це поведінка реалізації.)
+- `consequentHasThrow(consequent)` — у consequent if-у (як один `ThrowStatement` або як `BlockStatement.body`) є `ThrowStatement`.
+- `hasEmptyGuardBefore(block, statementIndex, name)` — у `block.body[0..statementIndex-1]` є `IfStatement`, який одночасно перевіряє «список порожній» (`isEmptyListTest`) і кидає (`consequentHasThrow`).
+- `findEnclosingBlockAndStatementIndex(ancestors)` — у списку `ancestors` (зверху-вниз) знаходить найближчу пару `(BlockStatement, indexUnderItsBody)`, де statement з `ancestors[i]` входить у `block.body`.
+
+#### Розпізнавання AST-патернів
+
+- `isNewConnectionPool(node)` — `new {sql|mssql}.ConnectionPool(...)`.
+- `isUnsafeQueryCallWithTemplateLiteral(node)` — `<obj>.query(\`...\`)`: метод `query`(некомпʼютований), перший аргумент —`TemplateLiteral`.
+- `isRequestFactoryCall(node)` — `<obj>.request()`: будь-яке `CallExpression` з `.request` як методом (некомпʼютованим).
+
+#### Гарантії числовості значень для `IN (${...})`
+
+- `isLiteralNumericArrayExpression(node)` — `ArrayExpression`, всі елементи якого — `NumericLiteral`/`BigIntLiteral` або generic `Literal` зі значенням типу `number`/`bigint`. Масив має бути непорожнім.
+- `isNumericParseCallExpression(node)` — `CallExpression`, де `callee` — це `Identifier` з імʼям з `NUMERIC_PARSE_FN_NAMES` = `{ parseInt, parseFloat, Number, BigInt }`, або `MemberExpression` з властивістю з того ж списку (наприклад `Number.parseInt(...)`).
+- `subtreeHasNumericParseCall(node)` — рекурсивно обходить піддерево й повертає `true`, якщо знайшов `isNumericParseCallExpression` або `UnaryExpression` з оператором `+`. Поле `parent` пропускається, щоб уникнути нескінченних циклів.
+- `isInListExpressionParsed(expr, declarators, seen=Set)` — головний критерій «безпечно числовий вираз». Повертає `true`, якщо:
+  - `expr` — літеральний масив чисел;
+  - або в піддереві `expr` є числовий парсер / унарний `+`;
+  - або `expr` — `Identifier`, у якого знайдено `VariableDeclarator`-и у файлі, і **кожен** `init` цих декларацій рекурсивно проходить ту ж перевірку. `seen` — анти-цикл (Set уже трасованих імен). Якщо для Identifier немає видимого init (наприклад параметр функції чи import) — повертається `false`.
+
+#### Збирачі порушень для `IN (...)` сканерів
+
+- `collectVariableDeclarators(programNode)` — обхід AST і збір усіх `VariableDeclarator`-ів.
+- `quasiRawText(q)` — повертає `q.value.raw` або `''`, якщо структура `q` не підходить (захист від нестандартних AST-вузлів).
+- `collectInListUnparsedFromTemplate(node, content, declarators, out)` — для одного `TemplateLiteral`: для кожного `expressions[i]` перевіряє, що `quasis[i].value.raw` закінчується на `IN (` (`IN_PLACEHOLDER_END_RE`), й експресія не є `.join(...)` і не «парсована». Якщо так — додає `{ line, snippet }` у `out`.
+- `collectInListMissingEmptyGuardFromTemplate(node, ancestors, content, out)` — для одного `TemplateLiteral`: для кожного `expressions[i]` після `IN (`:
+  - якщо `expr` — не Identifier → порушення `not_var`;
+  - якщо `expr` — Identifier, але в enclosing-блоці немає guard перед поточним statement → порушення `missing_guard` з `name`.
+
+### Side effects по модулю в цілому
+
+Жодна функція не звертається до файлової системи / мережі та не мутує вхідні дані; усе — pure-функції над рядками й AST. Парсинг `parseSync` із `oxc-parser` — синхронний, його винятки ловляться, і у разі помилки повертається `[]`.
+
+---
+
+## Залежності
+
+### Зовнішні npm-залежності
+
+- **`oxc-parser`** — імпорт `parseSync`. Швидкий парсер JS/TS (Rust-based) для побудови AST з вибором мови за `lang` і `sourceType: 'module'`.
+
+### Внутрішні залежності проєкту
+
+Усі імпортуються з відносного шляху `../../../scripts/utils/ast-scan-utils.mjs`:
+
+- `isFunctionNode(node)` — чи `node` є функціональним AST-вузлом (FunctionDeclaration / FunctionExpression / ArrowFunctionExpression / тощо).
+- `isJoinCall(node)` — чи `node` — це `CallExpression` виду `<x>.join(<sep>)`.
+- `isSqlListContextTemplate(template)` — чи `TemplateLiteral` знаходиться у SQL-контексті списку (`IN (...)` / `VALUES (...)`).
+- `langFromPath(path)` — обчислює `lang` для парсера за розширенням файлу (наприклад `'js'`, `'ts'`, `'tsx'`).
+- `normalizeSnippet(text)` — нормалізує сирий фрагмент коду до однорядкового сніппета (підрізає пробіли/нові рядки).
+- `offsetToLine(content, offset)` — конвертує абсолютний offset у вихідному коді в 1-based номер рядка.
+- `walkAstWithAncestors(root, initialAncestors, visitor)` — обхід AST із трекінгом `ancestors` для кожного вузла.
+
+### Константи модуля
+
+- `SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/` — фільтр розширень сорсів.
+- `IN_PLACEHOLDER_END_RE = /\bin\s*\(\s*$/iu` — детекція `... IN ( ` у raw-тексті quasi.
+- `NUMERIC_PARSE_FN_NAMES = new Set(['parseInt', 'parseFloat', 'Number', 'BigInt'])` — імена-«парсери чисел».
+- `EMPTY_LIST_BINARY_OPERATORS = new Set(['===', '==', '<=', '<'])` — оператори у тесті `name.length OP 0`.
+- `EMPTY_LIST_REVERSED_OPERATORS = new Set(['===', '=='])` — оператори, для яких дозволено зворотний порядок `0 OP name.length`.
+
+---
+
+## Потік виконання / Використання
+
+### Спільна каркасна логіка сканера
+
+Усі сканери побудовані однаково:
+
+1. Викликати `langFromPath(virtualPath || 'scan.ts')` → отримати `lang`.
+2. Викликати `parseSync(virtualPath, content, { lang, sourceType: 'module' })` у `try/catch`. У `catch` → `return []`.
+3. Якщо `result.errors?.length` → `return []` (парсер повернув помилки).
+4. Викликати `walkAstWithAncestors(result.program, [], visitor)` з тим чи іншим visitor.
+5. Повернути накопичений масив `out`.
+
+### Особливості окремих сканерів
+
+- **`findMssqlPerRequestConnectionInText`** додатково перевіряє, що поточний вузол знаходиться всередині функції: `ancestors.some(isFunctionNode)`. Без цього global-declaration `const pool = new sql.ConnectionPool(...)` помилково попадало б у порушення (а це якраз бажаний патерн).
+- **`findUnsafeMssqlInListUnparsedInText`** перед обходом збирає всі `VariableDeclarator` (`collectVariableDeclarators`), щоб у `isInListExpressionParsed` мати можливість трасувати Identifier → init (рекурсивно). `seen` Set захищає від циклів виду `let a = b; let b = a;`.
+- **`findUnsafeMssqlInListMissingEmptyGuardInText`** використовує `ancestors` усередині visitor: `findEnclosingBlockAndStatementIndex(ancestors)` дає пару `(block, statementIndex)`, після чого `hasEmptyGuardBefore(block, statementIndex, name)` перевіряє наявність guard у тому ж блоці **до** statement, що містить запит.
+
+### Як викликати
+
+```javascript
+import {
+  findMssqlPerRequestConnectionInText,
+  findSharedMssqlRequestInText,
+  findUnsafeMssqlDynamicSqlListInText,
+  findUnsafeMssqlInListMissingEmptyGuardInText,
+  findUnsafeMssqlInListUnparsedInText,
+  findUnsafeMssqlQueryTemplateCallInText,
+  isMssqlScanSourceFile
+} from './mssql-pool-scan.mjs'
+
+import { readFileSync } from 'node:fs'
+
+const relPath = 'pkg/src/db.ts'
+if (!isMssqlScanSourceFile(relPath)) return
+
+const content = readFileSync(relPath, 'utf8')
+
+const violationsPool = findMssqlPerRequestConnectionInText(content, relPath)
+const violationsQuery = findUnsafeMssqlQueryTemplateCallInText(content, relPath)
+const violationsShared = findSharedMssqlRequestInText(content, relPath)
+const violationsJoin = findUnsafeMssqlDynamicSqlListInText(content, relPath)
+const violationsUnparsed = findUnsafeMssqlInListUnparsedInText(content, relPath)
+const violationsGuard = findUnsafeMssqlInListMissingEmptyGuardInText(content, relPath)
+
+// Кожен елемент:
+//   { line, snippet }  — для перших пʼяти
+//   { line, snippet, reason, name? } — для останнього
+```
+
+### Приклади того, що ловить кожен сканер
+
+#### `findMssqlPerRequestConnectionInText`
+
+Порушення:
+
+```javascript
+export async function handler() {
+  const pool = new sql.ConnectionPool(config) // створення на кожен запит
+  await pool.connect()
+}
+```
+
+Не порушення (модульний singleton):
+
+```javascript
+const pool = new sql.ConnectionPool(config) // на рівні модуля
+```
+
+#### `findUnsafeMssqlQueryTemplateCallInText`
+
+Порушення:
+
+```javascript
+await pool.request().query(`SELECT * FROM users WHERE id = ${userId}`)
+// це звичайний CallExpression з TemplateLiteral → SQL injection
+```
+
+Не порушення (tagged template):
+
+```javascript
+await pool.request().query`SELECT * FROM users WHERE id = ${userId}`
+```
+
+#### `findSharedMssqlRequestInText`
+
+Порушення:
+
+```javascript
+export const request = pool.request()
+// або
+const request = somePool.request()
+```
+
+#### `findUnsafeMssqlDynamicSqlListInText`
+
+Порушення:
+
+```javascript
+await sql.query`SELECT * FROM t WHERE id IN (${ids.join(',')})`
+// .join(',') у списку IN/VALUES
+```
+
+#### `findUnsafeMssqlInListUnparsedInText`
+
+Порушення:
+
+```javascript
+await sql.query`SELECT * FROM t WHERE id IN (${ids})`
+// expr=ids, init=ids не пройшов parseInt/Number/BigInt/+
+```
+
+Не порушення:
+
+```javascript
+const ids = rawIds.map(x => parseInt(x, 10)).filter(Number.isFinite)
+await sql.query`SELECT * FROM t WHERE id IN (${ids})`
+// у піддереві ids є parseInt → subtreeHasNumericParseCall === true
+```
+
+#### `findUnsafeMssqlInListMissingEmptyGuardInText`
+
+Порушення (`not_var` — вираз не Identifier):
+
+```javascript
+await sql.query`SELECT * FROM t WHERE id IN (${rawIds.map(Number)})`
+```
+
+Порушення (`missing_guard` — немає `if (!ids.length) throw`):
+
+```javascript
+async function load(ids) {
+  await sql.query`SELECT * FROM t WHERE id IN (${ids})`
+}
+```
+
+Не порушення:
+
+```javascript
+async function load(ids) {
+  if (!ids.length) throw new Error('empty')
+  await sql.query`SELECT * FROM t WHERE id IN (${ids})`
+}
+```
+
+### Контракти та обмеження
+
+- На синтаксично некоректному файлі **усі** сканери мовчки повертають `[]` — це навмисна стратегія, щоб не блокувати CI на парсинг-помилках (їх виявить лінт).
+- Імпорт-Identifier-и не вважаються «парсованими» (немає видимого `init`), тож `findUnsafeMssqlInListUnparsedInText` для `import { ids } from '...'` дасть порушення — це консервативна поведінка.
+- `isFunctionNode`/`isJoinCall`/`isSqlListContextTemplate` визначені у `ast-scan-utils.mjs`; зміни їхньої поведінки впливають на семантику цього модуля.
+- Параметр `virtualPath` керує тільки вибором мови парсера. Якщо передати `.tsx`, парсер прийме JSX/TSX-синтаксис; для `.js` — звичайний JS і так далі.
+
+### Точки розширення
+
+- Додати новий клас порушень → ще одна функція `findX...InText(content, virtualPath)` + один visitor для `walkAstWithAncestors`.
+- Розширити перелік числових парсерів → додати імʼя до `NUMERIC_PARSE_FN_NAMES`.
+- Розширити форми guard-у → доповнити `isEmptyListTest` / `EMPTY_LIST_BINARY_OPERATORS` (наприклад додати `length < 1` через спеціальну гілку, бо поточна реалізація з `isZeroLiteral` цей варіант не покриває).
+
+---
+
+## Rebuild Test
+
+Файл `mssql-pool-scan.mjs` можна повністю відтворити з цієї документації за такими опорними точками:
+
+- Модуль ESM (`.mjs`), імпортує `parseSync` із `oxc-parser` і 7 утиліт із `../../../scripts/utils/ast-scan-utils.mjs` (`isFunctionNode`, `isJoinCall`, `isSqlListContextTemplate`, `langFromPath`, `normalizeSnippet`, `offsetToLine`, `walkAstWithAncestors`).
+- Експортує 7 функцій (6 сканерів + `isMssqlScanSourceFile`) з підписами, описаними в розділі **Експорти / API** і **Функції**.
+- Внутрішні константи: `SOURCE_FILE_RE`, `IN_PLACEHOLDER_END_RE`, `NUMERIC_PARSE_FN_NAMES`, `EMPTY_LIST_BINARY_OPERATORS`, `EMPTY_LIST_REVERSED_OPERATORS` — з точними значеннями з розділу **Залежності → Константи модуля**.
+- Каркас сканера: `try { parseSync(...) } catch { return [] }`, далі `if (result.errors?.length) return []`, далі `walkAstWithAncestors(result.program, [], visitor)`, далі `return out`.
+- Семантика visitor-ів — як описано в розділі **Функції → Експортовані функції** та **Збирачі порушень для `IN (...)` сканерів**.
+- Допоміжні предикати (`isZeroLiteral`, `isLengthMemberOf`, `isEmptyListBinaryTest`, `isEmptyListTest`, `consequentHasThrow`, `hasEmptyGuardBefore`, `findEnclosingBlockAndStatementIndex`, `isNewConnectionPool`, `isUnsafeQueryCallWithTemplateLiteral`, `isRequestFactoryCall`, `isLiteralNumericArrayExpression`, `isNumericParseCallExpression`, `subtreeHasNumericParseCall`, `collectVariableDeclarators`, `quasiRawText`, `isInListExpressionParsed`, `collectInListUnparsedFromTemplate`, `collectInListMissingEmptyGuardFromTemplate`) — з контрактами, описаними в розділі **Приватні допоміжні функції**.

package/rules/js-run/docs/fix.md

@@ -0,0 +1,144 @@
+# fix.mjs — точка входу правила `js-run`
+
+## Огляд
+
+Файл `npm/rules/js-run/fix.mjs` — це **диспетчер правила** `js-run` у пакеті `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+1. **Library-режим** — експортує функцію `run(ctx)`, яку викликає зовнішній CLI-оркестратор (`npx @nitra/cursor fix <id>`) під час пакетного прогону всіх правил. У цьому режимі модуль не торкається `process.exit` і повертає `Promise<number>` із кодом виходу.
+2. **Standalone-режим** — якщо файл запущено напряму (`bun rules/js-run/fix.mjs`), він поводиться як повноцінний entry-point: завантажує конфіг, застосовує whitelist, друкує підсумок і завершує процес із відповідним exit-code.
+
+Усю фактичну логіку (визначення `applies`, JS-concerns, policy-перевірки, mdc-references) інкапсулює спільна функція `runStandardRule`. `fix.mjs` лише прокидає `import.meta.dirname` (директорія правила) до неї або до CLI-обгортки `runRuleCli`. Файл не містить власних доменних перевірок — він суто структурний і дотримується конвенції «двох ролей `fix.mjs`», прийнятої в `@nitra/cursor` для всіх стандартних правил.
+
+Назву правила (`js-run`) система визначає не з вмісту цього файлу, а з імені директорії, в якій він лежить (`npm/rules/js-run/`). Це дозволяє створювати ідентичні `fix.mjs` для багатьох правил, не дублюючи логіку.
+
+## Експорти / API
+
+| Експорт | Тип                                            | Призначення                                                                          |
+| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `run`   | `function(ctx?: RuleContext): Promise<number>` | Library entry-point правила — викликається зовнішнім оркестратором у тому ж процесі. |
+
+Додатково в модулі присутній **side-effect блок** на рівні модуля: якщо `isRunAsCli(import.meta.url)` повертає `true`, модуль виконує `await runRuleCli(...)` і завершує процес через `process.exit(...)`. Цей блок не є експортом, але є частиною публічної поведінки файлу.
+
+Файл не має default-експорту і не реекспортує нічого зі своїх залежностей.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
+- **Параметри:**
+  - `ctx` _(необовʼязковий)_ — обʼєкт контексту прогону. Тип імпортується з `../../scripts/lib/run-standard-rule.mjs` як `RuleContext`. Зазвичай містить розділяємий між правилами кеш обходу файлової системи (`walkCache`) та інші cross-rule артефакти, які дозволяють зекономити IO при батч-прогоні. Якщо аргумент не передано, `runStandardRule` створює локальний контекст самостійно.
+- **Повертає:** `Promise<number>` — exit-code прогону:
+  - `0` — порушень не знайдено (OK);
+  - `1` — знайдено хоча б одне порушення.
+- **Side effects:** делегуються в `runStandardRule`. Можливі: читання файлів проєкту, читання `meta.json` правила, друк діагностики у stdout/stderr, запис у спільні структури `ctx`. Сам `run` `process.exit` не викликає — це принципово для library-режиму, де декілька правил мають викликатись підряд в одному процесі.
+- **Алгоритм:** одна делегація — `runStandardRule(import.meta.dirname, ctx)`. `import.meta.dirname` — абсолютний шлях до директорії, в якій лежить `fix.mjs` (тобто `.../npm/rules/js-run/`). За цим шляхом `runStandardRule` знаходить `meta.json`, підправила в `js/`, `policy/`, а також `.mdc`-документ правила.
+
+### Top-level CLI-блок
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Умова активації:** `isRunAsCli(import.meta.url)` — повертає `true`, якщо файл запущено напряму як скрипт (`node`/`bun fix.mjs`), а не імпортовано як модуль. Конкретний механізм перевірки інкапсульований у `run-rule-cli.mjs`.
+- **Що робить:** очікує (`await`) завершення `runRuleCli(import.meta.dirname)`, який окрім логіки `runStandardRule` додатково:
+  - завантажує конфіг проєкту (whitelist, exclusions);
+  - вирівнює аргументи CLI;
+  - друкує summary в кінці прогону;
+  - повертає exit-code.
+- **Завершення:** `process.exit(<code>)` — обовʼязкове для standalone-режиму, бо CI/IDE очікують саме exit-code, а не повернене значення з `import()`.
+- **ESLint suppression:** коментар `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` свідомо вимикає правила, які забороняють `process.exit` у бібліотечному коді. Виключення виправдане роллю файлу як standalone-entry-point — це не лібра у вузькому сенсі.
+
+## Залежності
+
+Файл має рівно **дві** внутрішні залежності, обидві з `npm/scripts/lib/`:
+
+| Імпорт            | Звідки                                    | Що звідти використовується                                                                                                    |
+| ----------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: чи модуль запущено як CLI, а не імпортовано як бібліотека. Приймає `import.meta.url`.                               |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Повна CLI-обгортка над `runStandardRule`: конфіг + whitelist + summary + повернення exit-code. Приймає `import.meta.dirname`. |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Універсальний раннер «стандартного» правила: applies → JS-concerns → policy → mdc-refs. Приймає `(dirname, ctx?)`.            |
+
+Зовнішніх npm-залежностей файл не має. Опосередковано він залежить від:
+
+- структури директорії правила (`meta.json`, підтеки `js/`, `policy/`, `.mdc`-файл);
+- існування файлу `js-run.mdc` поруч (документ правила, на який спирається mdc-refs);
+- API-контракту `RuleContext`, який тримається в `run-standard-rule.mjs`.
+
+## Потік виконання / Використання
+
+### Library-режим (батч-прогон правил)
+
+```js
+// Десь у CLI-оркестраторі @nitra/cursor
+import { run as runJsRun } from '@nitra/cursor/rules/js-run/fix.mjs'
+
+const ctx = createSharedContext() // walkCache, тощо
+const code = await runJsRun(ctx) // 0 або 1
+if (code !== 0) failures.push('js-run')
+```
+
+Послідовність:
+
+1. Оркестратор створює спільний `ctx` (один на всі правила в прогоні).
+2. Імпортує `run` з `fix.mjs` потрібного правила.
+3. Викликає `run(ctx)` і чекає `Promise<number>`.
+4. `run` делегує в `runStandardRule(dirname, ctx)`, яка читає `meta.json`, виконує applies → JS-concerns → policy → mdc-refs.
+5. Результат — exit-code — повертається оркестратору, який агрегує всі коди й вирішує, з чим завершити сам процес.
+
+### Standalone-режим (локальний дебаг або CI per-rule)
+
+```bash
+bun npm/rules/js-run/fix.mjs
+# або
+node npm/rules/js-run/fix.mjs
+```
+
+Послідовність:
+
+1. Інтерпретатор завантажує модуль.
+2. Виконується top-level код: `isRunAsCli(import.meta.url)` повертає `true` (бо файл — entrypoint).
+3. Викликається `await runRuleCli(import.meta.dirname)`:
+   - читає конфіг проєкту і whitelist;
+   - усередині запускає еквівалент `runStandardRule(dirname, ctx)`;
+   - друкує summary у stdout.
+4. Повернений exit-code передається в `process.exit(...)`, який завершує процес з ним же.
+5. CI/IDE/Husky отримують exit-code і вирішують, чи фейлити крок.
+
+### Розширення / модифікація
+
+- Щоб **додати специфічну логіку** для `js-run` за межами «стандартної» воронки — не правити цей файл, а додати чек у `js/` або `policy/` директорію правила. `runStandardRule` сам їх підхопить.
+- Щоб **використати власний контекст** — передавати `ctx` із полем `walkCache: Map<string, FsEntry[]>` для шарингу обходу між правилами.
+- Щоб **тимчасово виключити правило з batch** — оркестратор просто не імпортує `run` цього файлу. Сам файл такої логіки не містить.
+
+### Інваріанти, які слід зберігати при змінах
+
+1. Library-функція `run` **ніколи не викликає** `process.exit` — інакше зламається батч-прогон.
+2. CLI-блок виконується **тільки** під охороною `isRunAsCli(import.meta.url)` — інакше імпорт зробить exit у чужому процесі.
+3. У `runStandardRule` і `runRuleCli` передається `import.meta.dirname`, а не `import.meta.url` — це шлях, а не URL. Підміна типу зламає резолвінг `meta.json` і підправил.
+4. Назва правила береться з імені директорії — не дублюй її рядком у цьому файлі.
+
+## Rebuild Test
+
+Виходячи з цього документа можна відновити еквівалентний файл `fix.mjs`:
+
+1. Імпортувати `isRunAsCli` і `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`.
+2. Імпортувати `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
+3. Експортувати функцію `run(ctx)`, яка повертає `runStandardRule(import.meta.dirname, ctx)`.
+4. Додати top-level `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }` з ESLint-suppression-коментарем для `n/no-process-exit` і `unicorn/no-process-exit`.
+5. JSDoc для `run`: параметр `ctx?: RuleContext` (тип із `run-standard-rule.mjs`), повертає `Promise<number>` (0 — OK, 1 — порушення).
+
+Поведінкові ознаки для перевірки відновленого файлу:
+
+- `import { run } from './fix.mjs'` працює без побічних ефектів (CLI-блок не активується).
+- `bun fix.mjs` запускає повний CLI-прогон і завершує процес із кодом `0` або `1`.
+- `run(ctx)` повертає `Promise`, який резолвиться у число.
+- Файл не містить більше ніяких експортів і ніяких власних доменних перевірок.