@7n/rules 1.7.0 → 1.7.1

package/rules/docker/main.mdc

@@ -1,14 +1,247 @@
 ---
 description: Dockerfile — lint-docker / hadolint; перевірка check-docker
-version: '1.12'
+version: '1.13'
 globs: "**/Dockerfile*"
 alwaysApply: false
 ---
 
 # Docker — hadolint
 
-Правило перевіряє Dockerfile / Containerfile: GCR-дзеркало замість Docker Hub, multistage build з дозволеними runtime-образами, компіляцію bun-проєктів у бінарник, виняток для нативних `.node`-аддонів, non-root у фінальному stage, nginx-специфічні вимоги та hadolint CI-workflow.
+Правило перевіряє Dockerfile / Containerfile: GCR-дзеркало замість Docker Hub, multistage build з дозволеними runtime-образами, компіляцію bun-проєктів у бінарник, виняток для нативних `.node`-аддонів, non-root у фінальному stage, nginx-специфічні вимоги та hadolint CI-workflow. Усі перевірки нижче — один прохід по кожному Dockerfile/Containerfile у **`npm/rules/docker/lint/main.mjs`** (`npx @7n/rules lint docker`).
 
 ## Активація
 
 Спрацьовує на всі файли `Dockerfile*`; `check docker` (`fix.mjs`) обробляє також `Containerfile` та `Containerfile.*`.
+
+## GCR-дзеркало замість Docker Hub
+
+Для образів з Docker Hub — **`oven/bun`**, **`alpine`**, **`nginx`**, **`nginxinc/nginx-unprivileged`**, **`node`** — у **`FROM`** треба вказувати дзеркало GCR, а не pull напряму з Hub:
+
+| Docker Hub | GCR-дзеркало |
+|---|---|
+| `oven/bun` | `mirror.gcr.io/oven/bun` |
+| `alpine` | `mirror.gcr.io/library/alpine` |
+| `nginx` | `mirror.gcr.io/library/nginx` |
+| `node` | `mirror.gcr.io/library/node` |
+| `nginxinc/nginx-unprivileged` | `mirror.gcr.io/nginxinc/nginx-unprivileged` |
+
+Перевіряє **`npm/rules/docker/lib/docker-mirror.mjs`** (через `getMirrorGcrHint`).
+
+## Multistage build і дозволені runtime-образи
+
+Dockerfile/Containerfile **має бути multistage build**: окремий build stage (залежності/компіляція) і окремий runtime stage. У фінальному stage дозволені лише мінімальні базові образи:
+
+- **backend (типово)**: `mirror.gcr.io/library/alpine:*`
+- **ультра-легкі (glibc / одна статична збірка)**: `scratch` — тільки як `FROM scratch` (офіційний порожній базовий шар), коли весь **runtime** уже в `COPY --from=…`
+- **glibc, Debian (slim)**: `mirror.gcr.io/library/debian:*` **лише** з тегом, у якому є `slim` (наприклад `bookworm-slim`, `trixie-slim`), а не `bookworm` без `slim`. Debian-slim виправданий **лише** коли потрібен саме glibc-рантайм (нативні glibc-залежності, prebuilds без musl-варіанта). **Non-root сам по собі не є підставою** переходити сюди: `mirror.gcr.io/oven/bun:alpine` уже має користувача `bun` (uid/gid 1000), тож `USER bun` дає non-root **без зміни бази**. Перехід Alpine→Debian заради лише non-root — **антипатерн** (більший образ + зайва musl→glibc міграція bun-бінарника)
+- **виняток (інтерпретовані стеки)**: `mirror.gcr.io/library/php:*` або `mirror.gcr.io/library/python:*` — якщо сервіс має крутитися в офіційному runtime PHP чи Python, а не як один бінарник на Alpine; інакше лишай **alpine** у фінальному stage
+- **frontend**: `mirror.gcr.io/nginxinc/nginx-unprivileged:*` або `mirror.gcr.io/openresty/openresty:*`
+
+Це стримує зайвий build tooling (Bun, **node_modules** зі збірки) у фінальному образі; для **alpine** / **nginx** / **openresty** у **runtime** лишаються лише відповідні вимоги, для **php** / **python** (виняток) — цільовий інтерпретований **stack**; **scratch** і **debian** з тегом **`*slim*`** — коли glibc і мінімальне оточення Debian важливіші за musl в **alpine**.
+
+Перевіряє `getMultistageAndRuntimeHint` у **`npm/rules/docker/lint/main.mjs`**.
+
+## Компіляція bun-проєкту в бінарник
+
+Якщо проект має `bun install` крок, та не є фронтенд проектом (тобто не має `bun build` крок без `--compile`), **і не має нативного `.node`-аддона з динамічним завантаженням** (див. розділ нижче про нативні аддони), то потрібно щоб була компіляція коду, і далі у фінальному образі був тільки бінарник. Цей образ не містить компілятора, npm, Bun — тільки runtime libs.
+
+Тригер перевірки:
+
+- у Dockerfile є крок `bun install` (або `bun i`);
+- фінальний FROM — `mirror.gcr.io/library/alpine:*` (тобто не nginx/openresty frontend).
+
+Очікування:
+
+- у build stage є `bun build --compile`;
+- у фінальному stage немає викликів `bun` (залишків build tooling).
+
+### Канон — компільований бінарник на alpine
+
+```dockerfile
+FROM mirror.gcr.io/oven/bun:alpine AS build-env
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY package.json .
+COPY bunfig.toml .
+
+RUN bun install --production
+
+COPY ./src ./src
+
+# Компілюємо в бінарник
+RUN bun build --compile --outfile app ./src/index.js
+
+FROM mirror.gcr.io/library/alpine:latest
+
+# (libstdc++ libgcc) для Bun runtime, (tzdata) для часового поясу
+RUN apk add --no-cache libstdc++ libgcc tzdata
+
+WORKDIR /app
+
+COPY --from=build-env /app/app ./app
+
+CMD ["./app"]
+```
+
+Перевіряє `getBunCompileHint` у **`npm/rules/docker/lint/main.mjs`**.
+
+## Виняток: нативний `.node`-аддон (sharp / @img/* / argon2)
+
+Якщо в `package.json#dependencies` є нативний `.node`-аддон, який вантажиться через **динамічний `require`** — передусім **`sharp`**; той самий клас — **`@img/*`**, **`argon2`** — його **не можна** пакувати через `bun build --compile`.
+
+`bun build --compile` не трейсить ``require(`@img/sharp-${platform}/sharp.node`)`` і не вшиває нативний біндинг → компільований бінарник падає в рантаймі: `Could not load the "sharp" module using the linuxmusl-arm64 runtime`. Доведено реальними docker-збірками (bun 1.3.14, sharp 0.34.5); відтворюється і на darwin-arm64 (тобто не musl/glibc-залежне). `apk add vips` **НЕ лікує** — він дає системний libvips, а бракує саме `sharp.node`.
+
+Канон — ship `node_modules` і запускати через `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (це легітимний виняток до правила «лише alpine/scratch у фінальному stage» — тут потрібен саме bun-рантайм). База `oven/bun` уже має non-root користувача `bun` (uid/gid 1000). Entry бери з наявного `--outfile`-таргета / `package.json#main` / `scripts.start`; якщо не визначити — лиши TODO-маркер, не вгадуй.
+
+Список нативних аддонів — розширювана константа `NATIVE_ADDON_PACKAGES` / `NATIVE_ADDON_SCOPES` у **`npm/rules/docker/lib/docker-native-addon.mjs`** (підключено в **`npm/rules/docker/lint/main.mjs`**).
+
+### Антипатерн (це правило ловить)
+
+```dockerfile
+RUN bun build --compile --outfile app ./src/index.js     # ← з sharp у deps
+FROM mirror.gcr.io/library/alpine:latest
+RUN apk add --no-cache ... vips                           # системний vips не рятує
+COPY --from=build-env --chown=app:app /app/app ./app
+USER app
+CMD ["./app"]
+```
+
+### Канон (привести до цього)
+
+```dockerfile
+FROM mirror.gcr.io/oven/bun:alpine AS build-env
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json .
+RUN bun install --production
+COPY ./src ./src
+
+FROM mirror.gcr.io/oven/bun:alpine
+RUN apk add --no-cache tzdata
+WORKDIR /app
+# база oven/bun має non-root користувача bun (uid/gid 1000)
+COPY --from=build-env --chown=bun:bun /app/node_modules ./node_modules
+COPY --from=build-env --chown=bun:bun /app/src ./src
+COPY --from=build-env --chown=bun:bun /app/package.json ./package.json
+USER bun
+CMD ["bun", "src/index.js"]
+```
+
+Для проєктів **без** нативних аддонів standalone-бінарник на alpine лишається каноном (див. розділ вище про компіляцію).
+
+## Non-root принцип у фінальному stage
+
+Для всіх образів потрібно щоб використовувся non-root принцип. **Спосіб** досягнення non-root залежить від **бази**, а не від зміни ОС — змінювати дистрибутив (Alpine→Debian) заради лише non-root **не треба**. Два шляхи:
+
+- **standalone-бінарник на `alpine:latest`** (секція компіляції) — у `alpine` немає готового non-root користувача, тож його створюємо явно: `addgroup -g 1000 app && adduser -D -u 1000 -G app app` + `COPY --chown=app:app` + `USER app` (приклад нижче);
+- **ship `node_modules` на `mirror.gcr.io/oven/bun:alpine`** (виняток: нативний `.node`-аддон) — користувач `bun` (uid/gid 1000) **уже в базі**, тож достатньо `COPY --chown=bun:bun …` + `USER bun`; базу на Debian-slim міняти **не треба** — це той самий антипатерн, що й у переліку фінальних образів.
+
+### Приклад для standalone-бінарника на alpine
+
+```dockerfile
+# Stage 1
+FROM oven/bun:alpine AS build-env
+WORKDIR /app
+COPY package.json bunfig.toml .
+RUN bun install --production
+COPY ./src ./src
+RUN bun build --compile --outfile app ./src/index.js
+
+# Stage 2
+FROM alpine:latest
+RUN apk add --no-cache libstdc++ libgcc tzdata
+
+# Додати non-root user
+RUN addgroup -g 1000 app && adduser -D -u 1000 -G app app
+
+WORKDIR /app
+
+# Змінити власника файлу
+COPY --from=build-env --chown=app:app /app/app ./app
+
+# Запускати як non-root
+USER app
+
+CMD ["./app"]
+```
+
+Перевіряє `getNonRootRuntimeHint` у **`npm/rules/docker/lint/main.mjs`**.
+
+> **Примітка:** для `nginxinc/nginx-unprivileged` канон відрізняється — дивись розділ нижче про nginx non-root.
+
+## Мінімальний тег для nginx-unprivileged
+
+Якщо використовується nginx, то **використовуй** `mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim` (і не `latest` / `alpine`).
+
+Тег `alpine-slim` є обов'язковим для всіх `FROM` з образом `nginxinc/nginx-unprivileged` — будь-який інший тег (включаючи без тега) прапорцюється як порушення.
+
+Перевіряє `getNginxAlpineSlimTagHint` у **`npm/rules/docker/lint/main.mjs`**.
+
+## nginx-unprivileged — без USER, із --chown
+
+Окрема гілка для фронтенду на базі **`nginxinc/nginx-unprivileged`** (будь-який тег, з/без `mirror.gcr.io/`-префікса). Цей образ **уже** оголошує `USER 101` і `EXPOSE 8080`, тож у фінальному stage **не потрібні** жодні явні `USER`-інструкції:
+
+- **жодного `USER root` / `USER 0`** для білд-кроків: він перезатирає успадкований `USER 101`, і якщо потім не повернути non-root — фінальний образ лишається root, а k8s із `runAsNonRoot: true` падає з `CreateContainerConfigError`;
+- **жодного switch-back** `USER 101` / `USER nginx` наприкінці stage — це лише симптом зайвого `USER root` на початку (повертати треба саме **числовим** UID, бо kubelet не підтверджує non-root за іменем `nginx`). Канон — взагалі не виходити з-під дефолтного 101;
+- **`COPY`/`ADD` лише з `--chown`** (канон — `--chown=nginx:nginx`): без нього файли копіюються власником root і дефолтний non-root користувач (uid=101) не зможе читати статику.
+
+Build-stage не чіпаємо — там root і tooling норма. Перевіряє **`npm/rules/docker/lib/docker-nginx-user.mjs`**.
+
+### Антипатерн (це правило ловить)
+
+```dockerfile
+FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
+USER root
+COPY ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist ./
+RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
+USER 101          # повернення назад — симптом того, що був зайвий USER root
+EXPOSE 8080
+```
+
+### Канон (привести до цього)
+
+```dockerfile
+FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
+
+COPY --chown=nginx:nginx ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
+
+WORKDIR /usr/share/nginx/html
+
+COPY --from=build --chown=nginx:nginx /app/dist ./
+
+RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
+```
+
+(без жодного `USER`, gzip під дефолтним користувачем 101; `EXPOSE 8080` теж зайвий — база вже його оголошує)
+
+## hadolint
+
+CLI **`hadolint`** приймає лише **явні шляхи** (`[DOCKERFILE...]` у **`hadolint --help`**); обхід репозиторію робить **`npm/rules/docker/lint/main.mjs`** (правило `npx @7n/rules lint docker`) — файли з іменем **`Dockerfile`**, **`*.Dockerfile`**, **`Containerfile`**, **`*.Containerfile`** (суфікс без урахування регістру), з тими самими пропусками каталогів, що й решта обходу репозиторію.
+
+Виклик **`hadolint`** як **нативного бінарника** через **`ensureTool`** (PATH → кеш → авто-install brew/scoop/GitHub Release; **без** `docker run`) — спільна логіка **`npm/rules/docker/lib/docker-hadolint.mjs`**. Для CI-workflow, що встановлює hadolint і викликає `npx @7n/rules lint docker`, дивись `npm/rules/docker/lint_docker_yml/lint_docker_yml.mdc` (там канонічний шаблон і rego-перевірка `.github/workflows/lint-docker.yml`).
+
+### Конфігурація hadolint
+
+Кореневий **`.hadolint.yaml`**: вимкнення правил, trusted registries — [документація](https://github.com/hadolint/hadolint#configure). Щоб не додавати **`# hadolint ignore=DL3007`** у кожному **`FROM`** з **`:latest`**, у корені проєкту-споживача можна задати глобально:
+
+```yaml title=".hadolint.yaml"
+ignored:
+  - DL3007
+  - DL3008
+  - DL3018
+```
+
+Де DL3007 — «Не використовуй тег latest у FROM»
+Де DL3018 — «Піни версії пакетів у apk add»
+
+### Запуск
+
+**`npx @7n/rules lint docker`** — виклик hadolint як у **`docker-hadolint.mjs`** (нативний бінарник через **`ensureTool`**; **без** `docker run`), разом з іншими docker-перевірками (mirror/multistage/compile/non-root/nginx) в одному проході по кожному Dockerfile/Containerfile.
+
+Якщо немає жодного Dockerfile/Containerfile у репозиторії — перевірка пропускається (exit 0).
+
+Винятки: **`# hadolint ignore=DL3008`** (або інший код) у Dockerfile, або **`ignored`** у **`.hadolint.yaml`** (наприклад **DL3007** для **`:latest`** — див. вище).

package/rules/image-avif/avif_generation/avif_generation.mdc

@@ -24,3 +24,17 @@ import welcomeImage from './assets/welcome.png.avif'
 Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image-avif` падає з помилкою на конкретний файл.
 
 AVIF-двійники **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).
+
+## Опт-аут для конкретного пакета
+
+У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл або публічний сайт без гарантованої AVIF-підтримки), додай у `package.json` цього пакета. Заборонений typo `disabled-avif` (канон — `disable-avif`): [package.json.deny.json](../package_json/template/package.json.deny.json).
+
+```json title="apps/site/package.json"
+{
+  "@nitra/minify-image": {
+    "disable-avif": true
+  }
+}
+```
+
+Тоді перевірка пропускає `.vue` файли цього пакета і не видаляє наявні `.avif` всередині як «сироти». У root-`package.json` опт-аут діє лише для файлів кореня (вкладені workspaces перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).

package/rules/js/check/check.mdc

@@ -0,0 +1,26 @@
+## `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: "deny"` у [oxlint-canonical.json](../tooling/data/tooling/oxlint-canonical.json)) лишається `guard-for-in` як часткова страховка (oxlint не підтримує `no-restricted-syntax`) — `checkOxlintRc` у `check/main.mjs` звіряє `.oxlintrc.json` проєкту з цим каноном.
+
+Замість цього обходь масив напряму, а об'єкт — через `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)
+}
+```

package/rules/js/file-extensions/concern.json

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

package/rules/js/file-extensions/file-extensions.mdc

@@ -0,0 +1,12 @@
+## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`
+
+**Нові** JS-файли створюй з явним розширенням модуля:
+
+- **`.mjs`** — для ESM (типовий випадок);
+- **`.cjs`** — для CommonJS, де він справді потрібен.
+
+Голий **`.js`** для нового файлу **заборонено**. Розширення `.js` інтерпретується як ESM чи CJS лише за полем `package.json#type`, тож той самий файл читається по-різному залежно від пакета. Явне `.mjs`/`.cjs` робить тип модуля однозначним **без читання `package.json`** — навіть якщо `type` зміниться або файл перемістять в інший пакет. Це доповнює вимогу `"type": "module"` у [package_json.mdc](../package_json/package_json.mdc): `type` лишається каноном для всього дерева, а розширення нового файлу прибирає залежність від нього.
+
+Стосується **backend і frontend** — будь-який новий вихідний файл: `src/`, тести `*.test.*`, `scripts/`, `src/conn/` тощо.
+
+**Існуючі `.js` лишаються як є** — масово перейменовувати не треба; це конвенція для нового коду. Автоматичної перевірки тут немає: stateless-скан не відрізнить новий файл від існуючого, тож `.js` нікого не фейлить.

package/rules/js/jscpd_config/jscpd_config.mdc

@@ -12,3 +12,31 @@ Rego-пакет: `js_lint.jscpd`
 - `minLines` — число, значення >= канонічного порогу (`25`); більше дозволено
 
 Канон-snippet: [.jscpd.json.snippet.json](./template/.jscpd.json.snippet.json)
+
+### Ігнорування `.claude/worktrees/`
+
+Каталог `.claude/worktrees/` (робочі копії, які Claude Code створює через **superpowers:using-git-worktrees**) має ігноруватися:
+
+- додай `.claude/worktrees/` у кореневий `.gitignore` (штатне місце для не-комітних робочих копій);
+- у `.jscpd.json` додай `.claude/worktrees/**` у `ignore` як страховку на випадок запуску без `gitignore: true`.
+
+Без цього jscpd сканує паралельну копію репо в worktree і фіксує самозбіги між дзеркальними файлами.
+
+```text title=".gitignore (фрагмент)"
+.claude/worktrees/
+```
+
+### Ігнорування `**/CHANGELOG.md`
+
+`**/CHANGELOG.md` у каноні `ignore`: release-журнали різних пакетів структурно повторюються (заголовки `## [x.y.z] - YYYY-MM-DD`, секції `### Added / Changed / Fixed` за Keep a Changelog), і `jscpd` за `minLines: 25` фіксує їх як клон — це false positive. Без цього в монорепо легко зловити критичний `bun run lint` на парі CHANGELOG-ів довжиною від ~25 рядків.
+
+### Рефакторинг vs конфіг
+
+Коли **jscpd** знаходить клони, спочатку зменшуй дублювання кодом, а не конфігом.
+
+- **Рефакторинг:** винеси спільні фрагменти в функції, модулі, утиліти, composables/hooks, спільні компоненти або базові типи — залежно від контексту.
+- **Структура:** якщо одна й та сама логіка розмазана між файлами чи пакетами, запропонуй зміну структури (наприклад, спільний модуль, `shared/`, внутрішній пакет у monorepo), щоб була **одна канонічна реалізація** і повторні місця лише викликали її.
+
+Розширення `ignore` чи завищення `minLines` лише щоб прибрати звіт — не заміна рефакторингу для справжніх клонів. Якщо збіг **семантично випадковий** (генерований код, формальні шаблони без спільної логіки), після оцінки допустимо точковий `ignore` або зміна порогу — з коротким обґрунтуванням.
+
+Перед рефакторингом перевір чи є тести на блоки які підлягають зміні (Bun.test для js, playwright для vue). Якщо тестів немає або вони не покривають — спочатку створи їх, перевір що вони відпрацьовують коректно, потім роби рефакторинг і ще раз запускай тести.

package/rules/js/knip/knip.mdc

@@ -0,0 +1,15 @@
+## `knip.json` — аналіз невикористаних залежностей та експортів
+
+Залежнісний аналіз (knip — невикористані залежності/експорти, `knip.json` канон) крос-файловий; запускається як частина `npx @7n/rules lint js`.
+
+У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@7n/rules` — файл [`knip-canonical.json`](../tooling/data/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 @7n/rules lint js` (концерн `js/check`) копіює канон у корінь проєкту як side effect детектора, ще до фази LLM-фіксів. Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
+
+Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.

package/rules/js/utils_imports/utils_imports.mdc

@@ -0,0 +1,15 @@
+## Структура спільних модулів: `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/`.
+
+### Автоматична перевірка імпортів у `utils/`
+
+`npx @7n/rules lint js` (концерн `utils_imports`) обходить кожен `utils/`-каталог у воркспейсах і падає, якщо знаходить relative-імпорт з `..` (вихід за межі каталогу) у будь-якому не-тестовому файлі. Це механічне втілення правила «utils не знає про домен»: тільки same-dir (`./X`), bare-пакети та `node:*` дозволені; cross-rule, конфіги проєкту чи sibling-utils — fail.
+
+Якщо потрібна domain-залежність — перенеси файл у `lib/`.

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

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

package/rules/js-bun-db/connection/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` не потрібно. Автоматична перевірка (`lib/bun-sql-scan.mjs`, `findBunSqlPerRequestConnectionInText`, підключена з `safety/main.mjs`) фейлить будь-який `new SQL(...)` усередині функції — це єдина частина цієї сторінки, яку лінтер справді перевіряє; сам singleton-паттерн (файл, іменування `pgWrite`/`pgRead`) — рекомендація без автоматичної перевірки.

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

@@ -11,7 +11,21 @@ Rego-пакет: `js_bun_db.package_json`
 - `pg-format` — заміни на Bun native SQL (без ручного форматування)
 - `mysql2` — заміни на Bun native SQL
 
-`pg` у dependencies **не** є порушенням на рівні Rego — виняток для LISTEN/NOTIFY зважується у JS-сканері (`js/safety.mjs`).
+`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/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).