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

package/rules/js-bun-db/lib/docs/bun-sql-scan.md

@@ -0,0 +1,63 @@
+---
+type: JS Module
+title: bun-sql-scan.mjs
+resource: plugins/lang-js/rules/js-bun-db/lib/bun-sql-scan.mjs
+docgen:
+  crc: eed7dede
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+AST-сканер виявляє небезпечні патерни, пов'язані з використанням Bun SQL та PostgreSQL. Він перевіряє, чи не створюється пул з'єднань через `new SQL` всередині функції, що порушує принцип singleton на рівні модуля. Сканер також виявляє виклики `<obj>.unsafe` без відповідного маркера-коментаря `// allow-unsafe: <reason>`, що заборонено за замовчуванням для `sql.unsafe`. Крім того, він ідентифікує динамічні SQL-списки у tagged template `sql\`... IN (${arr.join}) ...\``, які не використовують параметризовані значення, а також шукає інші аномалії у використанні бібліотек `pg` (js-bun-db.mdc).
+
+## Поведінка
+
+findPgFormatShimDefinitionInText знаходить визначення pg-format-сумісних шимів у коді, що використовує Bun SQL.
+findPgFormatLikeQueryWrapperInText знаходить pg-сумісні обгортки запитів виду `{ query { ... unsafe ... } }` у коді, що використовує Bun SQL.
+findBunSqlPerRequestConnectionInText знаходить створення нового екземпляра `SQL` всередині функцій, що вказує на неоптимальне використання пулу.
+findBunSqlUnsafeUseWithoutAllowMarkerInText знаходить виклики `<obj>.unsafe` без відповідного маркера-коментаря.
+findBunSqlUnsafeWithInterpolatedTemplateInText знаходить виклики `<obj>.unsafe` з інтерпольованим шаблоном, що створює структурну вразливість.
+findBunSqlPgLeftoverCallInText знаходить виклики `<obj>.connect` або `<obj>.end` у файлах з Bun SQL без маркера-коментаря.
+findUnsafeBunSqlDynamicSqlListInText знаходить динамічні SQL-списки у tagged template, де використовується `.join` замість параметризації.
+findUnsafeBunSqlInListMissingEmptyGuardInText знаходить підстановки списків у `IN (...)`, де відсутня перевірка на пустоту з `throw`.
+textHasBunSqlImport визначає, чи містить текст джерела імпорт імені `sql` або `SQL` з `"bun"`.
+textHasPgLibImport визначає, чи імпортує файл npm-пакет `pg` за допомогою `import` або `require`.
+findPgLibImportInText знаходить конкретні місця імпорту пакета `pg` у коді.
+findPgListenNotifyUsageInText знаходить використання PostgreSQL LISTEN/NOTIFY у коді, що вимагає клієнта `pg`.
+isBunSqlScanSourceFile визначає, чи підходить файл за розширенням для AST-скану.
+findJsonStringifyBeforeJsonbInText знаходить виклики `JSON.stringify` перед використанням `::jsonb` у SQL template literal-ах, що призводить до подвійної серіалізації.
+findSqlArrayWithoutTypeArgInText знаходить виклики `sql.array` або аналогічні, де відсутній другий аргумент (тип).
+
+## Публічний API
+
+findPgFormatShimDefinitionInText — Виявляє визначення pg-format-сумісних шимів. Прапорує функції з іменами, що вказують на форматування (`format`, `pgFormat`, `sqlFormat`, `pgFmt`), якщо їхній вміст містить літерали або регулярні вирази з `%L`, `%I`, `%s`. Також виявляє pg-format-специфічні API (`quoteLiteral`, `quoteIdent`, `escapeLiteral`, `escapeIdent`), які не потрібні при використанні Bun SQL.
+
+findPgFormatLikeQueryWrapperInText — Виявляє pg-сумісні обгортки запитів, які маскують виклик `unsafe` під безпечне ім'я, повертаючи потенційну точку для SQL-ін'єкції.
+
+findBunSqlPerRequestConnectionInText — Виявляє створення нового об'єкта SQL (`new SQL`) всередині функцій-обробників запитів, замість використання єдиного екземпляра.
+
+findBunSqlUnsafeUseWithoutAllowMarkerInText — Виявляє виклики `unsafe` без відповідного маркера-коментаря. Забороняє використання `unsafe`, якщо значення не контролюється кодом (не вхідні дані користувача) і не є необхідним для підстановки назв таблиць/колонок або динамічного SQL/DDL.
+
+findBunSqlUnsafeWithInterpolatedTemplateInText — Виявляє використання `unsafe` з шаблонним літералом, що містить інтерполяцію (`${name}`). Попереджає, що шаблонна підстановка не екранує ідентифікатори та не прив'язує значення, створюючи ризик структурної ін'єкції.
+
+findBunSqlPgLeftoverCallInText — Виявляє виклики `connect` або `end` для pg-клієнта у файлах, що імпортують Bun SQL, без відповідного маркера-коментаря.
+
+findUnsafeBunSqlDynamicSqlListInText — Виявляє динамічні SQL-списки у контекстах `IN (...)` або `VALUES (...)`, де використовується метод `.join` серед виразів.
+
+findUnsafeBunSqlInListMissingEmptyGuardInText — Виявляє підстановки списків у `IN (...)`, які або не винесені в окрему змінну, або винесені, але перед запитом відсутня перевірка на порожній список.
+
+textHasBunSqlImport — Перевіряє, чи містить текст джерела імпорт імені `sql` або `SQL` з модуля `"bun"`. Реалізація живе в ядрі (`@7n/rules/scripts/lib/js-source-signals.mjs`, спільна з auto-rules) — тут ре-експорт.
+
+textHasPgLibImport — Перевіряє, чи імпортує файл бібліотеку `pg` (саме клієнт, а не `pg-format` чи `@types/pg`).
+
+findPgLibImportInText — Знаходить явний імпорт пакета `pg` у коді, повертаючи місце виявлення для точного відображення у повідомленнях про помилку.
+
+findPgListenNotifyUsageInText — Виявляє використання PostgreSQL команд `LISTEN`/`NOTIFY` у запитах або обробниках подій, оскільки Bun SQL поки не підтримує ці функції.
+
+findJsonStringifyBeforeJsonbInText — Знаходить виклики `JSON.stringify::jsonb` у SQL-шаблонах, що призводить до подвійної серіалізації даних.
+
+findSqlArrayWithoutTypeArgInText — Знаходить виклики функції для створення масиву (`sql.array` тощо) без вказання обов'язкового другого аргументу (типу pg-елемента), що може спричинити невідповідність типів.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/js-bun-db/lib/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/js-bun-db/lib
+resource: plugins/lang-js/rules/js-bun-db/lib/
+---
+
+# npm/rules/js-bun-db/lib
+
+| Файл                                | Тип       |
+| ----------------------------------- | --------- |
+| [bun-sql-scan.mjs](bun-sql-scan.md) | JS Module |

package/rules/js-bun-db/main.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "jsBunDbSignal" } }

package/rules/js-bun-db/main.mdc

@@ -0,0 +1,8 @@
+---
+description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
+globs: "**/package.json,**/src/conn/**"
+alwaysApply: false
+version: '1.15'
+---
+
+Правило забезпечує безпечне підключення й виконання запитів через Bun native SQL замість `pg` / `pg-format` / `mysql2`, із захистом від SQL injection, pg-leftover та небезпечних патернів `sql.unsafe`.

package/rules/js-bun-db/package_json/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "walkGlob": "**/package.json"
+    }
+  }
+}

package/rules/js-bun-db/package_json/package_json.mdc

@@ -0,0 +1,31 @@
+## Заборонені залежності у package.json
+
+Rego-пакет: `js_bun_db.package_json`
+
+Цільові файли: `**/package.json`
+
+Перевіряє поле `dependencies` на наявність пакетів із deny-списку [`package.json.deny.json`](./template/package.json.deny.json). Список керується даними (`--data`), тому розширюється без зміни rego-коду.
+
+Поточний deny-список:
+
+- `pg-format` — заміни на Bun native SQL (без ручного форматування)
+- `mysql2` — заміни на Bun native SQL
+
+`pg` у dependencies **не** є порушенням на рівні Rego — виняток для LISTEN/NOTIFY зважується у JS-сканері (`safety/main.mjs`, детальніше — `safety/safety.mdc`, секція «pg: виключення для LISTEN/NOTIFY»).
+
+✓ `{ "dependencies": { "pg": "^8.0.0" } }` — дозволено
+✗ `{ "dependencies": { "pg-format": "^1.0.0" } }` — `deny: dependencies.pg-format — заміни на Bun native SQL`
+
+### Перехід з `pg` / `mysql2` на Bun native SQL
+
+PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом, підключаємось як `mysql://`).
+
+Якщо в проєкті використовуються бібліотеки `pg`, `pg-format` або `mysql2`, їх потрібно замінити на Bun native SQL: <https://bun.com/docs/runtime/sql>.
+
+- Видалити з `dependencies`: `pg-pool`, `pg-native`, `pg-format`, `mysql`, `mysql2`.
+- Видалити з коду: усі `import` / `require` цих пакетів та власні обгортки над ними.
+- Замінити на `import { sql, SQL } from 'bun'` — Bun має вбудований клієнт із пулом, prepared statements та tagged templates.
+
+`pg-format` (unscoped) — це ручне форматування SQL через escape (`format('... %L ...', value)`); такі рядки легко поламати неправильним типом, locale-залежним escape або забутим `%L`. Tagged template Bun SQL параметризує значення нативно (``sql`... ${value} ...` ``) і не лишає простору для injection — окремий «форматер» **для значень** не потрібен.
+
+Виключення є **лише** для **динамічних identifiers** (назви схем / таблиць / колонок / індексів / ролей / БД) і whitelist-фрагментів типу `ASC`/`DESC`: Bun SQL їх параметризувати не вміє, тож тут дозволено окремий пакет **`@scaleleap/pg-format`** (scoped форк, не unscoped `pg-format`) — деталі й приклади у `pg_format_identifiers/pg_format_identifiers.mdc`.

package/rules/js-bun-db/package_json/package_json.rego

@@ -0,0 +1,15 @@
+# Перевірка `dependencies` (js-bun-db.mdc).
+#
+# Канон надходить через --data: { "template": { "deny": ... } }
+# Структура --data сформована з template/package.json.deny.json.
+# AST-скан коду (`new SQL(...)` у функціях, `unsafe()` без маркера, pg-leftover,
+# динамічні `IN (…)` через `.join(',')`) лишається у JS.
+package js_bun_db.package_json
+
+import rego.v1
+
+deny contains msg if {
+	some pkg, reason in data.template.deny.dependencies
+	pkg in object.keys(object.get(input, "dependencies", {}))
+	msg := sprintf("dependencies.%s — %s", [pkg, reason])
+}

package/rules/js-bun-db/package_json/template/package.json.deny.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "pg-format": "заміни на Bun native SQL — без ручного форматування (js-bun-db.mdc)",
+    "mysql2": "заміни на Bun native SQL (js-bun-db.mdc)"
+  }
+}

package/rules/js-bun-db/pg_format_identifiers/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/js-bun-db/pg_format_identifiers/pg_format_identifiers.mdc

@@ -0,0 +1,104 @@
+## Динамічна SQL-структура: `@scaleleap/pg-format` для identifiers
+
+Bun SQL **не вміє** параметризувати назви схем, таблиць, колонок, індексів, ролей, БД — а ``sql`SELECT * FROM ${table}` `` забіндив би це як значення і зламав би синтаксис. Для **динамічних identifiers** дозволено окремий пакет:
+
+```bash
+bun add @scaleleap/pg-format
+```
+
+⚠️ Це **scoped `@scaleleap/pg-format`**, а не unscoped `pg-format` (той у [deny-списку](../package_json/template/package.json.deny.json)). Беремо форк `@scaleleap` **тільки** заради `%I` / `%s`-можливостей; значення все одно проходять через Bun parameters, **не** через `%L`.
+
+### Дозволений патерн
+
+- **`%I`** — escape SQL identifier (schema / table / column / index / role / database).
+- **`%s`** — raw fragment, **тільки** для whitelist-значень (`ASC` / `DESC`, тип JOIN'у тощо).
+- Значення — позиційні параметри `$1, $2, …`, які передаються другим аргументом у `sql.unsafe(query, [bindParams])`.
+- На рядку виклику `sql.unsafe(...)` обов'язковий маркер `// allow-unsafe: <причина>` (див. `safety/safety.mdc`, секція «sql.unsafe(...) за замовчуванням заборонено»).
+
+```javascript
+import format from '@scaleleap/pg-format'
+import { sql } from 'bun'
+
+const allowedColumns = new Set(['created_at', 'email', 'name'])
+if (!allowedColumns.has(sortBy)) throw new Error('Invalid sort column')
+
+const direction = sortDir === 'asc' ? 'ASC' : 'DESC'
+
+const query = format(
+  'SELECT * FROM %I.%I ORDER BY %I %s LIMIT $1',
+  schemaName,
+  tableName,
+  sortBy,
+  direction
+)
+// allow-unsafe: динамічні schema/table/column; значення біндяться через $N
+const rows = await sql.unsafe(query, [limit])
+```
+
+Multi-row `INSERT` через `VALUES %L` теж типовий легітимний кейс, але передавай значення колонок як паралельні масиви через `unnest(...)` Bun SQL — `format('VALUES %L', rows)` лишай тільки коли альтернатива з `unnest` неможлива:
+
+```javascript
+const query = format(
+  /* sql */ `
+    INSERT INTO "order".delivery_status (order_id, status, changed_at)
+    SELECT v.order_id::uuid, v.status, v.changed_at::timestamptz
+    FROM (VALUES %L) AS v(order_id, status, changed_at)
+  `,
+  values
+)
+// allow-unsafe: multi-row VALUES для бекфілу; values формуються з валідованого input
+await sql.unsafe(query)
+```
+
+### Заборонено й після підключення `@scaleleap/pg-format`
+
+- **`%L` для user input** — це повернення `pg-format`-стилю. Завжди bind через Bun (``sql`... = ${value}` ``) або позиційний параметр `$N` + `sql.unsafe(query, [params])`.
+- Збирати весь `WHERE` через `format(...)` з `%L` — користуйся whitelist полів і ручним складанням `$N`-placeholder'ів (приклад нижче).
+- Власні функції `format` / `pgFormat` / `sqlFormat` / `pgFmt` з тілом, що містить `%L` / `%I` / `%s`, — `fail` сканера (це шим, а не імпорт з бібліотеки); детектор — `findPgFormatShimDefinitionInText` (`lib/bun-sql-scan.mjs`, підключений з `safety/main.mjs`).
+- Експортовані `quoteLiteral` / `quoteIdent` / `escapeLiteral` / `escapeIdent` — `fail` сканера (pg-format-специфічні API замість Bun parameters).
+
+### Dynamic `WHERE` — без `format(...)`, через whitelist + `$N`
+
+```javascript
+const conditions = []
+const values = []
+
+if (email) {
+  values.push(email)
+  conditions.push(`email = $${values.length}`)
+}
+if (status) {
+  values.push(status)
+  conditions.push(`status = $${values.length}`)
+}
+
+const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''
+const query = `SELECT * FROM users ${where}`
+// allow-unsafe: динамічний WHERE з whitelist-полів; значення біндяться через $N
+const rows = await sql.unsafe(query, values)
+```
+
+### Коротка таблиця рішень
+
+| Сценарій                          | Що використовувати                                   |
+| --------------------------------- | ---------------------------------------------------- |
+| `WHERE id = ${...}`               | Bun SQL tagged template                              |
+| `INSERT` одного рядка             | Bun SQL tagged template                              |
+| `INSERT` масиву (object/colset)   | Bun SQL helper `sql(rows, 'a', 'b')` або `unnest`    |
+| `UPDATE field = ${value}`         | Bun SQL tagged template                              |
+| Динамічна назва schema / table    | `@scaleleap/pg-format` `%I` + `sql.unsafe(q, [...])` |
+| Динамічна назва колонки           | `@scaleleap/pg-format` `%I` + bind                   |
+| Динамічний `ORDER BY column`      | whitelist + `%I`                                     |
+| `ASC` / `DESC`, тип JOIN'у        | whitelist + `%s`                                     |
+| Динамічний `WHERE` (полів багато) | whitelist + ручні `$N` + `sql.unsafe(text, vals)`    |
+| Сирий migration / DDL             | `sql.unsafe(text)` з `// allow-unsafe: <причина>`    |
+| User input як value               | **тільки** Bun parameters / `$N` bind                |
+| Масив значень у `unnest(...)`     | `sql.array(arr, type)` — обов'язково з типом         |
+
+Головне правило:
+
+- **SQL values** → Bun SQL parameters (tagged template `${value}` або `$N` + `sql.unsafe(text, values)`).
+- **SQL identifiers** → `@scaleleap/pg-format` `%I` (schema, table, column, index, role, database).
+- **SQL fragments** (`ASC`/`DESC` тощо) → whitelist + `%s`.
+
+Ніщо з цієї сторінки (правильність використання `%I`/`%s`, вибір `@scaleleap/pg-format` замість unscoped `pg-format` у коді, а не лише у `dependencies`) наразі не має власного AST-детектора — сканер (`lib/bun-sql-scan.mjs`) ловить лише симптоми: shim-реалізації (`findPgFormatShimDefinitionInText`), обгортки над `unsafe` (`findPgFormatLikeQueryWrapperInText`) та відсутність `allow-unsafe`-маркера. Тому ця сторінка лишається docs-only; unscoped `pg-format` як залежність вже заборонено окремо в `package_json/package_json.mdc` (Rego deny-list).

package/rules/js-bun-db/safety/concern.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": { "scope": "full", "glob": ["**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}", "**/package.json"] }
+}

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

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/js-bun-db/safety/main.mjs
+docgen:
+  crc: ce094cd3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Поведінка системи описує основну функціональність програми через публічну функцію `main`. Програма керується конфігураційними параметрами, визначеними в `package.json`. Уся взаємодія з базами даних здійснюється через механізм, що відповідає логіці, описаній у `js-bun-db.mdc`. Система працює виключно в режимі читання даних, і гарантії не включають механізм кешування.
+
+## Поведінка
+
+1. Викликається функція main.
+2. Система зчитує конфігураційні файли для ігнорування.
+3. Знаходяться всі файли package.json у репозиторії.
+4. Скануються JS/TS файли репозиторію на наявність небезпечних патернів Bun SQL.
+5. Збираються метадані щодо використання pg-модуля (`pg`) та сигналів LISTEN/NOTIFY у файлах.
+6. Перевіряється залежність `pg` у файлах package.json щодо наявності використання LISTEN/NOTIFY.
+7. Якщо Bun SQL використовується, перевіряється відповідність усіх патернів (наприклад, відсутність створення new SQL у функціях, використання `allow-unsafe` маркерів, правильне використання `sql.array`, відсутність зайвих `JSON.stringify` перед `::jsonb`).
+8. Усі результати перевірок реєструються за допомогою повідомлень з посиланням на (js-bun-db.mdc).
+
+## Публічний API
+
+main — перевіряє відповідність проєкту вимогам, викладеним у правилі js-bun-db.mdc.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).