@nitra/cursor 12.8.6 → 12.8.8

package/rules/js/main.mdc

@@ -5,232 +5,40 @@ alwaysApply: false
 version: '1.30'
 ---
 
-**oxlint**, **ESLint**, **jscpd**, **knip**. Запуск — **`n-cursor lint js`** (локально; у CI — `--read-only`, без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політика CI-етапу: `@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати.
+**oxlint**, **ESLint**, **jscpd**, **knip**. Запуск — **`n-cursor lint js`** (локально; у CI — `--read-only`, без **`--fix`** для oxlint/eslint). Без **prettier** і **@nitra/prettier-config**.
 
-У кожному **`package.json`** проєкту (корінь і всі workspace-пакети) має бути **`"type": "module"`** — весь код у ESM.
+[js-file-extensions](./js/file-extensions.mdc)
 
-```json title="package.json"
-{
-  "type": "module",
-  "devDependencies": {
-    "@nitra/eslint-config": "^3.10.0"
-  }
-}
-```
+[js-package-json](./js/package-json.mdc)
 
-Канон `type` і мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`): [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json). Окремого `lint-js` скрипта немає — лінт через **`n-cursor lint js`** (CI — `--read-only`).
+[js-eslint-config](./js/eslint-config.mdc)
 
-## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`
+[js-oxlintrc](./js/oxlintrc.mdc)
 
-**Нові** JS-файли створюй з явним розширенням модуля:
+[js-extensions](./js/extensions.mdc)
 
-- **`.mjs`** — для ESM (типовий випадок);
-- **`.cjs`** — для CommonJS, де він справді потрібен.
+[js-jscpd](./js/jscpd.mdc)
 
-Голий **`.js`** для нового файлу **заборонено**. Розширення `.js` інтерпретується як ESM чи CJS лише за полем `package.json#type`, тож той самий файл читається по-різному залежно від пакета. Явне `.mjs`/`.cjs` робить тип модуля однозначним **без читання `package.json`** — навіть якщо `type` зміниться або файл перемістять в інший пакет. Це доповнює вимогу `"type": "module"` вище: `type` лишається каноном для всього дерева, а розширення нового файлу прибирає залежність від нього.
+[js-knip](./js/knip.mdc)
 
-Стосується **backend і frontend** — будь-який новий вихідний файл: `src/`, тести `*.test.*`, `scripts/`, `src/conn/` тощо.
+[js-dep-policy](./js/dep-policy.mdc)
 
-**Існуючі `.js` лишаються як є** — масово перейменовувати не треба; це конвенція для нового коду. Автоматичної перевірки тут немає: stateless-скан не відрізнить новий файл від існуючого, тож `.js` нікого не фейлить.
+[js-lint-js-workflow](./js/lint-js-workflow.mdc)
 
-У `.vscode/extensions.json` `recommendations` мають містити `dbaeumer.vscode-eslint`, `github.vscode-github-actions`, `oxc.oxc-vscode`: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
+[js-utils-lib-structure](./js/utils-lib-structure.mdc)
 
-У корені має бути **`.oxlintrc.json`**, який **збігається з каноном** oxlint з пакета **`@nitra/cursor`**: файл **`npm/rules/js/js/data/tooling/oxlint-canonical.json`** (plugins, jsPlugins з **`@e18e/eslint-plugin`**, categories, повний набір **rules** із канону — додаткові записи в **`rules`** дозволені; також **`settings`**, **`env`**, **`globals`**). Поле **`ignorePatterns`** працює як **`rules`**: канонічні патерни з **`oxlint-canonical.json`** (наразі **`**/schema.graphql`**, **`**/auto-imports.d.ts`**) мають бути присутні, додаткові локальні glob-и дозволені. Канон **`oxlint-canonical.json`** — source-of-truth, редагується напряму; у споживачі оновлюється копіюванням файлу з репозиторію пакета. Модуль **`@e18e/eslint-plugin`** не оголошуй окремо в **`package.json`** — він уже в залежностях **`@nitra/eslint-config`** (з **3.8.0**), oxlint підвантажує його з **`node_modules`**.
+[js-for-in](./js/for-in.mdc)
 
-Мінімум для розуміння структури (реальний корінь конфігу має збігатися з каноном повністю):
+[js-tests](./js/tests.mdc)
 
-```json title=".oxlintrc.json (фрагмент)"
-{
-  "jsPlugins": ["@e18e/eslint-plugin"],
-  "rules": {
-    "e18e/prefer-includes": "error"
-  }
-}
-```
+## Швидкий gate через conftest
 
-У корені проєкту має бути `.jscpd.json`. Мінімум: увімкнути облік `.gitignore`, ненульовий код виходу при знаходженні клонів, консольний звіт. За потреби додай `ignore` (дзеркальні каталоги, шаблони) та `minLines`, щоб відсікти дрібні збіги.
+Rego-пакети у `policy/` — запускаються `npx @nitra/cursor fix js` або `conftest`:
 
-Каталог `.claude/worktrees/` (робочі копії, які Claude Code створює через **superpowers:using-git-worktrees**) має ігноруватися: додай його у кореневий `.gitignore` (це штатне місце для не-комітних робочих копій), а в `.jscpd.json` додай `.claude/worktrees/**` у `ignore` як страховку на випадок запуску без `gitignore: true`. Без цього jscpd сканує паралельну копію репо в worktree і фіксує самозбіги між дзеркальними файлами.
+[js-policy-package_json](./policy/package_json/package_json.mdc)
 
-`**/CHANGELOG.md` теж у каноні `ignore`: release-журнали різних пакетів структурно повторюються (заголовки `## [x.y.z] - YYYY-MM-DD`, секції `### Added` / `### Changed` / `### Fixed` за Keep a Changelog), і `jscpd` за `minLines: 25` фіксує їх як клон, хоч це false positive — кожен `CHANGELOG.md` веде свій per-package журнал за каноном `n-changelog`, спільної історії не існує. Без цього в монорепо легко зловити критичне `bun run lint` на парі CHANGELOG-ів довжиною від ~25 рядків.
+[js-policy-jscpd](./policy/jscpd/jscpd.mdc)
 
-```json title=".jscpd.json"
-{
-  "gitignore": true,
-  "exitCode": 1,
-  "reporters": ["console"],
-  "minLines": 25,
-  "ignore": [".claude/worktrees/**", "**/dist/**", "**/CHANGELOG.md"]
-}
-```
+[js-policy-lint_js_yml](./policy/lint_js_yml/lint_js_yml.mdc)
 
-Канон ключів `.jscpd.json` (`gitignore`, `exitCode`, `reporters`, `minLines`, `ignore` як subset-of): [.jscpd.json.snippet.json](./policy/jscpd/template/.jscpd.json.snippet.json)
-
-```text title=".gitignore (фрагмент)"
-.claude/worktrees/
-```
-
-## Залежнісна політика (що не додавати)
-
-`@e18e/eslint-plugin` окремо не додавай — він уже в залежностях `@nitra/eslint-config` (з **3.8.0**), oxlint підвантажує його з `node_modules`. Пакети oxlint/eslint/jscpd/knip теж не додавай у `devDependencies` без потреби монорепо — `bunx` тягне їх ad-hoc.
-
-## knip
-
-Залежнісний аналіз (knip — невикористані залежності/експорти, `knip.json` канон) крос-файловий; запускається автоматично у `lint --full` разом з jscpd.
-
-У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@nitra/cursor` — файл [`npm/rules/js/js/tooling/knip-canonical.json`](./js/tooling/knip-canonical.json). Він покриває типові false-positives для наших правил: `entry` зі CLI-конфігами (eslint, stylelint, oxlint, jscpd, markdownlint-cli2, `commitlint`), `project` для `**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}`, `ignore` для `**/__fixtures__/**`, `ignoreDependencies` для пакетів, посилання на які є лише в не-JS-конфігах (`@nitra/cspell-dict`, `/@cspell\/dict-.+/`, `graphql`), і `ignoreBinaries` для CLI, які канон вимагає викликати через `npx`/`bunx` і яких заборонено додавати в `devDependencies` (`actionlint`, `cspell`, `eslint`, `git-ai`, `jscpd`, `markdownlint-cli2`, `oxfmt`, `oxlint`, `shellcheck`, `uvx`, `v8r`, `zizmor`).
-
-Якщо `knip.json` відсутній — `npx @nitra/cursor fix js` копіює канон у корінь проєкту (side effect). Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
-
-Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.
-
-## Заборона `@nitra/as-integrations-fastify`
-
-Пакет **`@nitra/as-integrations-fastify`** заборонений у **`dependencies`**, **`peerDependencies`** та в import-specifier-ах. Це чистий републіш upstream, застряглий на peer `@apollo/server: "^4.0.0"`, тож на Apollo 5 `bun install` дає `warn: incorrect peer dependency`. Заміна — upstream **`@as-integrations/fastify`** (**`^3.1.0`**): peer `@apollo/server: "^4.0.0 || ^5.0.0"` + `fastify: "^5.3.0"`.
-
-Міграція — лише specifier у трьох місцях: залежність у `package.json`, `import`, та `vi.mock(...)` / `await import(...)` у тестах. **Код не міняється**, експорти ті самі: `default` → `fastifyApollo`, named → `fastifyApolloDrainPlugin`.
-
-```javascript title="❌ до"
-import fastifyApollo, { fastifyApolloDrainPlugin } from '@nitra/as-integrations-fastify'
-```
-
-```javascript title="✅ після"
-import fastifyApollo, { fastifyApolloDrainPlugin } from '@as-integrations/fastify'
-```
-
-## jscpd: рефакторинг і структура
-
-Коли **jscpd** знаходить клони, спочатку зменшуй дублювання кодом, а не конфігом.
-
-- **Рефакторинг:** винеси спільні фрагменти в функції, модулі, утиліти, composables/hooks, спільні компоненти або базові типи — залежно від контексту.
-- **Структура:** якщо одна й та сама логіка розмазана між файлами чи пакетами, запропонуй зміну структури (наприклад, спільний модуль, `shared/`, внутрішній пакет у monorepo), щоб була **одна канонічна реалізація** і повторні місця лише викликали її.
-
-Так ти уникаєш **хибних обходів** перевірки: розширення `ignore` чи завищення `minLines` лише щоб прибрати звіт — не заміна рефакторингу для справжніх клонів. Якщо збіг **семантично випадковий** (генерований код, формальні шаблони без спільної логіки), після оцінки допустимо точковий `ignore` або зміна порогу — з коротким обґрунтуванням.
-
-Але обов'язково перед рефакторингом перевір чи є тести на блоки які підлягають зміні, а саме Bun.test для js та playwright для vue. Якщо є, то перевір чи вони покривають блоки які підлягають зміні. Якщо не покривають або тестів немає — спочатку створи їх, перевір що вони покривають і відпрацьовують коректно, а потім роби рефакторинг і ще раз запускай тести, але якщо тести не відпрацьовують коректно після рефакторингу, то не роби рефакторинг.
-
-## Структура спільних модулів: `utils/` vs `lib/`
-
-Коли спільні методи виносяться з кількох JS-файлів в окремий каталог — назву каталога обирай за призначенням модулів усередині.
-
-- **`utils/`** — низькорівневі, чисті, generic helpers без бізнес-логіки і без залежностей від домену проєкту. Те, що могло б жити в окремому npm-пакеті. Приклади: `formatDate()`, `chunk(array, size)`, `retry(fn, opts)`, `deepMerge()`, `parseDuration('5m')`, `sleep(ms)`.
-
-- **`lib/`** — внутрішні модулі / підсистеми проєкту, які знають про домен. Більші за `utils/`, часто з власним state, конфігом або side effects. Приклади: `lib/gmail-client.js`, `lib/circuit-breaker.js`, `lib/skill-loader.js`, `lib/safety/dry-run.js`.
-
-Швидкий тест: якщо файл завтра можна опублікувати окремим npm-пакетом без переписування — це `utils/`; якщо він тримає domain-state, читає конфіг проєкту або викликає зовнішні сервіси/файли — це `lib/`. Не плутай із чужими каталогами на кшталт `shared/` чи `common/`: канонічні назви — лише `utils/` і `lib/`.
-
-Автоматично гарантується: `npx @nitra/cursor fix js` (концерн `utils_imports`) обходить кожен `utils/`-каталог у воркспейсах і падає, якщо знаходить relative-імпорт з `..` (вихід за межі каталогу) у будь-якому не-тестовому файлі. Це механічне втілення правила «utils не знає про домен»: тільки same-dir (`./X`), bare-пакети та `node:*` дозволені; cross-rule, конфіги проєкту чи sibling-utils — fail. Якщо потрібна domain-залежність — перенеси файл у `lib/`.
-
-Додай workflow:
-
-```yaml title=".github/workflows/lint-js.yml"
-name: Lint JS
-
-on:
-  push:
-    branches:
-      - dev
-      - main
-    paths:
-      - '**/*.js'
-      - '**/*.mjs'
-      - '**/*.cjs'
-      - '**/*.jsx'
-      - '**/*.ts'
-      - '**/*.tsx'
-      - '**/*.vue'
-      - '**/eslint.config.*'
-
-  pull_request:
-    branches:
-      - dev
-      - main
-
-concurrency:
-  group: ${{ github.ref }}-${{ github.workflow }}
-  cancel-in-progress: true
-
-jobs:
-  eslint:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - uses: ./.github/actions/setup-bun-deps
-
-      - name: Eslint
-        run: |
-          bunx oxlint
-          bunx eslint .
-          bunx jscpd .
-          bunx knip --no-config-hints
-```
-
-Канон workflow `.github/workflows/lint-js.yml`: [lint-js.yml.snippet.yml](./policy/lint_js_yml/template/lint-js.yml.snippet.yml)
-
-Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
-
-Один workflow на лінт JS; зайвий `lint.yml` з тими самими кроками — прибери.
-
-```javascript title="eslint.config.js"
-import { getConfig } from '@nitra/eslint-config'
-
-export default [
-  {
-    ignores: ['**/auto-imports.d.ts']
-  },
-  ...getConfig({
-    node: ['npm']
-  })
-]
-```
-
-У монорепо пакети з Vite (frontend) вкажи в секції `vue`, решту — у секції `node` у виклику `getConfig`.
-
-## Додаткові js правила
-
-Завжди додавай до package.json що підтримується 24+ версія node і Bun 1.3+:
-
-```json title="package.json"
-"engines": {
-  "node": ">=24",
-  "bun": ">=1.3"
-}
-```
-
-## `for...in` заборонено — рефакторити на `for...of`
-
-Конструкція `for (const k in obj)` обходить успадковані ключі прототипу, тому майже завжди тягне `Object.hasOwn(obj, k)`-guard. Заборонена у `@nitra/eslint-config` через `no-restricted-syntax` для `ForInStatement` (з версії **3.8.0**). У каноні oxlint лишається `guard-for-in` як часткова страховка (oxlint не підтримує `no-restricted-syntax`). Замість цього обходь масив напряму, а обʼєкт — через `Object.entries` / `Object.keys` / `Object.values`. У такому коді guard за `Object.hasOwn` стає непотрібним і має зникнути разом із `for...in`.
-
-```javascript title="❌ до"
-for (const k in obj) {
-  if (!Object.hasOwn(obj, k)) continue
-  use(k, obj[k])
-}
-
-for (const i in arr) {
-  use(arr[i])
-}
-```
-
-```javascript title="✅ після"
-for (const [k, v] of Object.entries(obj)) {
-  use(k, v)
-}
-
-for (const item of arr) {
-  use(item)
-}
-```
-
-## Тести
-
-Проєкт має бути покритий unit-тестами (**Bun test**). Код: синтаксис Node **24+**, **top level await** (узгоджено з `engines.node` у `package.json`).
-
-## Покриття + мутаційне тестування JS
-
-Покриття + мутаційне тестування JS постачаються через `n-cursor coverage` (правило `test.mdc`). Реалізація провайдера — у `npm/rules/js/coverage/coverage.mjs`: `bun test --coverage --coverage-reporter=lcov` + `bunx stryker run`. Stryker конфігурується в `stryker.config.mjs` у JS-корені (single-package або `workspaces[0]`).
+[js-policy-vscode_extensions](./policy/vscode_extensions/vscode_extensions.mdc)

package/rules/js/policy/jscpd/jscpd.mdc

@@ -0,0 +1,14 @@
+## Rego-gate `.jscpd.json`
+
+Rego-пакет: `js_lint.jscpd`
+
+Цільовий файл: `.jscpd.json` у корені проєкту.
+
+Що перевіряється:
+
+- `gitignore` — точна відповідність (`true`)
+- `exitCode` — точна відповідність (`1`)
+- `reporters` — subset-of: масив має містити всі елементи з канону (`["console"]`)
+- `minLines` — число, значення >= канонічного порогу (`25`); більше дозволено
+
+Канон-snippet: [.jscpd.json.snippet.json](./template/.jscpd.json.snippet.json)

package/rules/js/policy/lint_js_yml/lint_js_yml.mdc

@@ -0,0 +1,14 @@
+## Rego-gate `.github/workflows/lint-js.yml`
+
+Rego-пакет: `js_lint.lint_js_yml`
+
+Цільовий файл: `.github/workflows/lint-js.yml`.
+
+Що перевіряється:
+
+- Наявність усіх `uses:`-кроків з канону (subset-of по `jobs.eslint.steps`)
+- Наявність усіх рядків `run:` з канону (substring-match по всіх кроках)
+- `actions/checkout@v6` має мати `with.persist-credentials: false` (inverse-check)
+- Заборона `--fix` у CI: `bunx oxlint ... --fix` або `eslint --fix` у будь-якому `run:` → deny
+
+Канон-snippet: [lint-js.yml.snippet.yml](./template/lint-js.yml.snippet.yml)

package/rules/js/policy/package_json/package_json.mdc

@@ -0,0 +1,15 @@
+## Rego-gate `package.json`
+
+Rego-пакет: `js_lint.package_json`
+
+Цільовий файл: `package.json` (корінь і workspace-пакети).
+
+Що перевіряється:
+
+- `"type"` — точна відповідність `"module"` (з канон-snippet)
+- `scripts.lint-js` — нормалізована точна відповідність (collapse whitespace)
+- `engines.node` — semver-парсинг: major >= 24 (inverse, без template)
+- `engines.bun` — semver-парсинг: >= 1.3 (inverse, без template)
+- `devDependencies["@nitra/eslint-config"]` — наявність ключа + semver >= порогу зі snippet (`^3.10.0`); `workspace:*` завжди проходить
+
+Канон-snippet: [package.json.snippet.json](./template/package.json.snippet.json)

package/rules/js/policy/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,11 @@
+## Rego-gate `.vscode/extensions.json`
+
+Rego-пакет: `js_lint.vscode_extensions`
+
+Цільовий файл: `.vscode/extensions.json`.
+
+Що перевіряється:
+
+- `recommendations` — subset-of: масив має містити всі три канонічні розширення (`dbaeumer.vscode-eslint`, `github.vscode-github-actions`, `oxc.oxc-vscode`)
+
+Канон-snippet: [extensions.json.snippet.json](./template/extensions.json.snippet.json)

package/rules/js-bun-db/js/bun-sql-migration.mdc

@@ -0,0 +1,15 @@
+## Перехід з `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.
+
+Канон заборонених `dependencies` (`pg-format`, `mysql2`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json). Сам `pg` із денилисту прибрано — він має одне легітимне виключення (LISTEN/NOTIFY), яке зважує AST-сканер; деталі — у `js/pg-listen-notify.mdc`.
+
+`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`) — деталі й приклади у `js/pg-format-identifiers.mdc`.

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

@@ -0,0 +1,42 @@
+## Підключення (singleton + env)
+
+Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
+
+Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.mjs` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
+
+```javascript
+// src/conn/db.mjs
+import { SQL } from 'bun'
+
+export const pgWrite = new SQL({
+  url: process.env.DATABASE_URL,
+  max: 20,
+  idleTimeout: 30,
+  connectionTimeout: 10
+})
+
+export const pgRead = new SQL({
+  url: process.env.PG_CONN_READ ?? process.env.DATABASE_URL,
+  max: 10,
+  idleTimeout: 30,
+  connectionTimeout: 10
+})
+```
+
+Connection string обирає адаптер автоматично:
+
+- `postgres://...` / `postgresql://...` → PostgreSQL
+- `mysql://...` / `mysql2://...` → MySQL/MariaDB
+- `sqlite://...` / `file://...` / `:memory:` → SQLite
+
+### Не створювати підключення на кожен запит
+
+```javascript
+// ❌ нове підключення/інстанс на кожен виклик
+function getUser(id) {
+  const pgWrite = new SQL(process.env.DATABASE_URL)
+  return pgWrite`SELECT * FROM users WHERE id = ${id}`
+}
+```
+
+`new SQL(...)` має створюватись **один раз** на рівні модуля. Bun сам тримає пул (`max`, `idleTimeout`, `maxLifetime`) — окремих `Pool`/`Client` як у `pg` не потрібно.

package/rules/js-bun-db/js/pg-format-identifiers.mdc

@@ -0,0 +1,102 @@
+## Динамічна 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-списку](./policy/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: <причина>` (div. `js/unsafe.mdc`).
+
+```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` сканера (це шим, а не імпорт з бібліотеки).
+- Експортовані `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`.

package/rules/js-bun-db/js/pg-format-shim.mdc

@@ -0,0 +1,99 @@
+## `pg-format`: повне видалення, без шимів
+
+Міграція з `pg-format` — це **зміна стилю запитів**, а не збереження API. У проєкті після переходу на Bun SQL **заборонено** залишати:
+
+- функцію з іменем `format` (чи `pgFormat`, `sqlFormat`, `pgFmt`), що приймає шаблон з `%L` / `%I` / `%s` і значення;
+- допоміжні `quoteLiteral`, `quoteIdent`, `escapeLiteral`, `escapeIdent` як публічні експорти модуля;
+- обгортки `pgRead.query(text, params)` / `pgWrite.query(text, params)` / `db.query(text, params)`, які складають SQL-рядок (з або без `format`) і викликають `sql.unsafe(text, params)` — це повертає injection-поверхню, від якої ми йдемо, тільки під «зручним» іменем.
+
+Замість цього всі точки використання потрібно перевести на tagged template `sql\`...\${value}...\``. Кожне `${value}` стає окремим параметром bind, без рядкового екранування.
+
+### Типові ідіоми `pg-format` → Bun SQL
+
+| Було (`pg-format`)                                 | Стало (Bun SQL)                                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `format('... WHERE id = %L', id)`                  | `sql\`... WHERE id = ${id}\``                                                                    |
+| `format('... IN (%L)', ids)`                       | `sql\`... IN ${sql(ids)}\`` (з guard на пустоту перед запитом)                                   |
+| `format('INSERT ... VALUES %L', [row])` (1 рядок)  | `sql\`INSERT ... VALUES (${a}, ${b}, ...)\``                                                     |
+| `format('INSERT ... VALUES %L', rows)` (N рядків)  | `sql\`INSERT INTO t ${sql(rows, 'a', 'b')}\`` або `unnest($1::T[], $2::T[]) AS t(a, b)`          |
+| `format('MERGE ... USING (VALUES %L) AS d(...)')`  | `sql\`MERGE ... USING (SELECT * FROM unnest(${arrA}::A[], ${arrB}::B[]) AS t(a, b)) AS d\``      |
+| `format('... %I ...', tableName)` (whitelist)      | `@scaleleap/pg-format`: `format('%I', name)` + `sql.unsafe(text, [params])` з маркером           |
+
+Для multi-row `VALUES` у `MERGE` / `INSERT` з конкретними типами — паралельні масиви по колонках і `unnest($1::TYPE[], $2::TYPE[], ...) AS t(col1, col2, ...)`. Кожна колонка передається одним параметром-масивом; типи задаються кастом масиву (`::uuid[]`, `::bigint[]`, `::numeric[]`, `::text[]`, …).
+
+#### Приклад: MERGE з UNNEST і динамічними колонками
+
+```javascript
+// ❌ format + pgWrite.unsafe — N×7 окремих значень, план змінюється при кожному batch.length
+const valuesSql = batch
+  .map(row => format('(%L::int, %L::date, %L::jsonb)', row.id, row.date, JSON.stringify(row.data)))
+  .join(',')
+const sql = format(`MERGE INTO t USING (VALUES %s) AS s(id, date, data) ON ...`, valuesSql)
+await pgWrite.unsafe(sql)
+
+// ✅ UNNEST — 3 параметри незалежно від розміру batch; план стабільний і може кешуватись
+await pgWrite`
+  WITH s(id, date, data) AS (
+    SELECT * FROM unnest(
+      ${pgWrite.array(col(batch, 'id'),   'int4')},
+      ${pgWrite.array(col(batch, 'date'), 'date')},
+      ${pgWrite.array(col(batch, 'data'), 'jsonb')}
+    )
+  )
+  MERGE INTO my_table AS t
+  USING s ON t.id = s.id
+  WHEN MATCHED THEN
+    UPDATE SET date = s.date, data = s.data
+  WHEN NOT MATCHED THEN
+    INSERT (id, date, data) VALUES (s.id, s.date, s.data)
+`
+```
+
+Якщо частина колонок у SET/INSERT залежить від параметра (plan/fact, тип тощо) — динамічні імена колонок не можна параметризувати через `${value}`; використовуй умовні Bun SQL фрагменти:
+
+```javascript
+// ✅ умовні фрагменти для динамічних ідентифікаторів колонок
+const colFrag  = isPlan ? pgWrite`plan_value`  : pgWrite`fact_value`
+const hashFrag = isPlan ? pgWrite`hash = s.hash,` : pgWrite``
+
+await pgWrite`
+  ...
+  WHEN MATCHED THEN
+    UPDATE SET
+      ${colFrag} = s.value,
+      ${hashFrag}
+      updated_by = s.updated_by
+  WHEN NOT MATCHED THEN
+    INSERT (id, ${colFrag}, updated_by)
+    VALUES (s.id, s.value, s.updated_by)
+`
+```
+
+### Заборонений «drop-in» шим
+
+```javascript
+// ❌ pg-format-сумісний шим, що ховає `unsafe` під «безпечним» іменем
+export function format(fmt, ...args) {
+  let i = 0
+  return fmt.replaceAll(/%[LIs]/g, () => quoteLiteral(args[i++]))
+}
+
+// ❌ і його типовий call-site — той самий injection-вектор, що і прямий sql.unsafe із конкатенацією
+await sql.unsafe(format('... WHERE id = %L', userId))
+```
+
+```javascript
+// ❌ pg-сумісна обгортка над Bun SQL — ще один прихований `unsafe`
+export const pgWrite = {
+  query(text, params) {
+    return sql.unsafe(text, params)
+  }
+}
+```
+
+```javascript
+// ✅ напряму tagged template — параметризація через wire-protocol bind
+await sql`... WHERE id = ${userId}`
+```
+
+Виняток для шиму `format()` під час поетапної міграції допускається **тільки** в окремому commit'і з TODO-маркером і дедлайном; готовий код у main з таким шимом — `fail` правила (детектори: `pg-format shim`, `query wrapper over unsafe`).

package/rules/js-bun-db/js/pg-leftover.mdc

@@ -0,0 +1,27 @@
+## Прибирати pg-leftover виклики (`.connect()`, `.end()`)
+
+У файлах з Bun SQL (`import { sql, SQL } from 'bun'`) залишки від `pg` — `pool.connect()`, `client.end()`, `pool.end()` — мають бути видалені. Bun SQL пулом керує сам: на першому запиті підключається, idle/lifetime закриває за конфігом — окремий життєвий цикл вручну не потрібен.
+
+```javascript
+// ❌ pg-leftover: ручний lifecycle, який Bun SQL робить за тебе
+const client = await pool.connect()
+try {
+  await client.query('...')
+} finally {
+  await client.end()
+}
+
+// ✅ Bun SQL — без явних .connect()/.end()
+await sql`...`
+```
+
+Якщо виклик дійсно потрібен (наприклад, `sql.end()` у graceful shutdown або `.connect()` на сторонньому об'єкті, що випадково ділить імʼя методу), додай маркер `// allow-pg-leftover: <причина>` на тому ж рядку (trailing) або на рядку безпосередньо перед викликом:
+
+```javascript
+// allow-pg-leftover: graceful shutdown — закриваємо пул перед exit
+await sql.end()
+
+ws.connect(url) // allow-pg-leftover: WebSocket, не pg
+```
+
+Формат маркера: `allow-pg-leftover: <непорожня причина>` у line- або block-коментарі. Без маркера й без причини — **fail** перевірки.