@nitra/cursor 12.8.6 → 12.8.7

package/rules/ga/main.mdc

@@ -5,137 +5,29 @@ globs: ".github/workflows/*.yml"
 alwaysApply: false
 ---
 
-У `.github/workflows/` лише **`.yml`**. Мають бути **`clean-ga-workflows.yml`**, **`clean-merged-branch.yml`**, **`lint-ga.yml`**, **`git-ai.yml`**. Якщо є **`apply-k8s.yml`** / **`apply-nats-consumer.yml`** — paths у тригері як у фрагментах.
+Правило **ga** перевіряє структуру `.github/workflows/`, наявність обов'язкових workflow-файлів і їх відповідність канонам, а також налаштування VS Code та zizmor для роботи з GitHub Actions.
 
-**Кожен** workflow у `.github/workflows/*.yml` **обов'язково** містить блок `concurrency` з фіксованим `group` та `cancel-in-progress: true`:
+[ga-workflows](./js/workflows.mdc)
 
-```yaml
-concurrency:
-  group: ${{ github.ref }}-${{ github.workflow }}
-  cancel-in-progress: true
-```
+[ga-workflow_common](./js/workflow_common.mdc)
 
-Без винятків — у scheduled cleanup-воркфлоу, у `pull_request: types: [closed]`, у publish-воркфлоу теж. Це уникає паралельних запусків того самого workflow на тій самій ref і скасовує попередні в чергу нових.
+[ga-required_workflows](./js/required_workflows.mdc)
 
-Повинен бути файл `.github/workflows/clean-ga-workflows.yml`:
+[ga-vscode](./js/vscode.mdc)
 
-- Канон: [clean-ga-workflows.yml.snippet.yml](./policy/clean_ga_workflows/template/clean-ga-workflows.yml.snippet.yml)
+[ga-zizmor](./js/zizmor.mdc)
 
-Повинен бути файл `.github/workflows/clean-merged-branch.yml`:
+[ga-lint_toolchain](./js/lint_toolchain.mdc)
 
-- Канон: [clean-merged-branch.yml.snippet.yml](./policy/clean_merged_branch/template/clean-merged-branch.yml.snippet.yml)
+## Швидкий gate через conftest
 
-Інші гілки в `ignore_branches` — допустимо.
+Rego-пакети (namespace → що перевіряє):
 
-Повинен бути файл `.github/workflows/lint-ga.yml`:
-
-- Канон: [lint-ga.yml.snippet.yml](./policy/lint_ga/template/lint-ga.yml.snippet.yml)
-
-Повинен бути файл `.github/workflows/git-ai.yml`:
-
-- Канон: [git-ai.yml.snippet.yml](./policy/git_ai/template/git-ai.yml.snippet.yml)
-
-**Мінімальні версії marketplace actions** у `uses:` (перевіряє `ga.workflow_common`):
-
-- `actions/checkout` — **не нижче major `v6`** (`@v6`, `@v6.0.2` тощо дозволені; `@v5` — ні);
-- `Infisical/secrets-action` — **не нижче `v1.0.16`** (Node 24; нижчі теги лишаються на Node 20, deprecated з червня 2026).
-
-Канон: [uses-min-versions.snippet.json](./policy/workflow_common/template/uses-min-versions.snippet.json). SHA-pin (40 hex) semver-політику не застосовує. Для checkout рекомендується **`v6.0.2+`** (Node 24 у action), але мінімум політики — лише major **6**.
-
-**Локальний composite** (`uses: ./.github/actions/setup-bun-deps` або `./npm/github-actions/setup-bun-deps`): **спочатку** обов’язковий крок **`actions/checkout@v6`** (`persist-credentials: false`), інакше runner не знайде `action.yml`. Сам composite: **`actions/setup-node@v6`** (**Node 24**), **Bun**, **`actions/cache@v5`**, **`bun install --frozen-lockfile`**.
-
-**ЗАБОРОНЕНО** дублювати кроки встановлення Bun та кешування безпосередньо у workflow файлах. Завжди використовуй локальний composite action.
-
-**Кроки `run`:** не розбивай команду shell-продовженням через зворотний сліш у кінці рядка (`… \` у `run: |`). Замість багаторядкового буквального блока з `\\` оформ довгу одну shell-команду як **folded block** `>-` (рядки з’єднаються в один рядок із пробілами).
-
-**Читабельність `run: >-` з циклам/умовами:** оскільки `>-` **згортає рядки в один shell-рядок**, відступи потрібні **лише для читабельності** й не впливають на виконання. Але для конструкцій bash на кшталт `while …; do … done` та `if …; then … fi` **обовʼязково**:
-
-- став явні роздільники команд **`;`** або **`&&`** там, де при згортанні рядків інакше “злипнуться” токени (`do`/`then`/`fi`/`done` з наступною командою);
-- тримай `do` і `then` в одному логічному рядку як `…; do` / `…; then`, щоб після згортання це гарантовано лишалось валідним bash;
-- додавай відступи всередині `do/then/else` блоків, навіть якщо це один рядок після згортання — так workflow лишається читабельним у diff.
-
-### Приклад (ПРАВИЛЬНО — читабельно, `run: >-`, з `while`/`if`)
-
-```yaml
-      - name: Apply changes
-        shell: bash
-        run: >-
-          echo "$FILES" |
-          while read -r FILE; do
-            [ -z "$FILE" ] && continue;
-            dirname "$FILE";
-          done |
-          sort -u |
-          while read -r DIR; do
-            (
-              if [ -f "$DIR/kustomization.yaml" ]; then
-                printf 'Applying %s\n' "$DIR" &&
-                cd "$DIR" &&
-                kubectl apply -k .;
-              else
-                echo "Skip $DIR - no kustomization.yaml";
-              fi
-            );
-          done
-```
-
-### Приклад run (НЕПРАВИЛЬНО — `\\` на кінцях)
-
-```yaml
-      - run: |
-          docker build \
-          --push \
-          --build-arg BRANCH=${{ github.ref_name }}
-```
-
-### Приклад run (ПРАВИЛЬНО — `>-`)
-
-```yaml
-      - run: >-
-          docker build
-          --push
-          --build-arg BRANCH=${{ github.ref_name }}
-```
-
-### Приклад (НЕПРАВИЛЬНО)
-
-```yaml
-    steps:
-      - uses: actions/checkout@v6
-      - uses: oven-sh/setup-bun@v2
-      - uses: actions/cache@v5
-        # ... багато рядків кешування ...
-      - run: bun install --frozen-lockfile
-```
-
-### Приклад (ПРАВИЛЬНО)
-
-```yaml
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - uses: ./.github/actions/setup-bun-deps
-```
-
-**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Запуск — через **`n-cursor lint ga`** (CI — `--read-only`; бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`. Окремого `package.json`-скрипта немає.
-
-> Виклик через bin-ім’я `n-cursor` (а **не** `npx @nitra/cursor`): `bun x`/`npx` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання, тому в CI-кроці `run:` використовуй саме `n-cursor lint <rule>`.
-
-CLI робить preflight на `shellcheck` і `uv` (`uvx`) у `PATH`, потім запускає `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
-
-**`.github/zizmor.yml`:** для [unpinned-uses](https://docs.zizmor.sh/audits/#unpinned-uses) — політика **`ref-pin`**, якщо в `uses:` семантичні теги. За потреби вимкни [template-injection](https://docs.zizmor.sh/audits/#template-injection):
-
-- Канон `.github/zizmor.yml`: [zizmor.yml.snippet.yml](./policy/zizmor_yml/template/zizmor.yml.snippet.yml)
-
-**`.vscode/extensions.json`** має рекомендувати `github.vscode-github-actions`:
-
-- Канон: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
-
-**`.vscode/settings.json`** для мови `github-actions-workflow` має `editor.defaultFormatter = "oxc.oxc-vscode"`:
-
-- Канон: [settings.json.snippet.json](./policy/vscode_settings/template/settings.json.snippet.json)
-
-**MegaLinter:** не використовувати; прибрати workflow, конфіги (`.mega-linter.yml`, `.megalinter.yaml`, `.mega-linter.yaml`), залежності та згадки в CI / pre-commit / документації.
-
-**`depcheck`:** не використовувати у `.github/workflows/*.yml` — мігровано на `knip` (див. `js.mdc`). Перевірка невикористаних залежностей виконується разом з рештою лінтерів у `lint-js`, окремий крок `npx depcheck` у workflow не потрібен і блокується полісі `ga.workflow_common`.
+- `ga.workflow_common` — усі `*.yml`: concurrency, composite setup-bun-deps, run:>-, мінімальні версії actions, заборона depcheck
+- `ga.clean_ga_workflows` — структура `clean-ga-workflows.yml` (cron, permissions, cleanup step)
+- `ga.clean_merged_branch` — структура `clean-merged-branch.yml` (cron, permissions, ignore_branches, dry_run)
+- `ga.lint_ga` — структура `lint-ga.yml` (triggers, conftest install, n-cursor lint ga --read-only)
+- `ga.git_ai` — структура `git-ai.yml` (pr closed trigger, git-ai install + run)
+- `ga.vscode_extensions` — `.vscode/extensions.json`: рекомендація `github.vscode-github-actions`
+- `ga.vscode_settings` — `.vscode/settings.json`: `editor.defaultFormatter` для github-actions-workflow
+- `ga.zizmor_yml` — `.github/zizmor.yml`: `rules.unpinned-uses.config.policies["*"]`

package/rules/graphql/js/tooling.mdc

@@ -0,0 +1,13 @@
+## Умовна вимога `.graphqlrc.yml`
+
+Якщо у `.vue` або в JavaScript / TypeScript джерелах (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.jsx` тощо) зустрічається **tagged template literal** з тегом **`gql`** (типово `gql\`query …\`` для GraphQL-запиту), у **корені репозиторію** має бути файл **`.graphqlrc.yml`** ([GraphQL Config](https://the-guild.dev/graphql/config/docs)).
+
+Перевірка є **умовною**: якщо жодного `gql\`…\`` у дереві не знайдено — `.graphqlrc.yml` не вимагається.
+
+Підстав свої шляхи до схеми та до файлів з операціями; приклад орієнтиру:
+
+```yaml title=".graphqlrc.yml"
+schema: node_modules/@nitra/efes-shared/schema/maya.graphql
+documents:
+  - '**/*.{vue,js,ts,tsx}'
+```

package/rules/graphql/js/vscode_extensions.mdc

@@ -0,0 +1,13 @@
+## Розширення VS Code для GraphQL
+
+Якщо у проєкті є `gql\`…\`` tagged template literals, у **`.vscode/extensions.json`** в масиві **`recommendations`** має бути запис **`graphql.vscode-graphql`**.
+
+Канон задає мінімум — інші записи (від markdownlint, oxc тощо) дозволені. Перевірка виконується Rego-пакетом `graphql.vscode_extensions` через `conftest` і запускається лише після того, як JS-сканер виявив `gql` у дереві.
+
+Додай `graphql.vscode-graphql` до наявного списку `recommendations` (не замінюй інші записи):
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["graphql.vscode-graphql"]
+}
+```

package/rules/graphql/main.mdc

@@ -5,27 +5,8 @@ globs: "**/*.{vue,js,mjs,cjs,ts,tsx,jsx}"
 alwaysApply: false
 ---
 
-Якщо в **`.vue`** або в **JavaScript / TypeScript** джерелах (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.jsx` тощо) зустрічається **tagged template literal** з тегом **`gql`** (типово `gql\`query …\`` для GraphQL-запиту), у **корені репозиторію** мають бути:
+Якщо у `.vue` або JavaScript / TypeScript джерелах зустрічається **tagged template literal** з тегом **`gql`**, у корені репозиторію мають бути `.graphqlrc.yml` та запис `graphql.vscode-graphql` у `.vscode/extensions.json`.
 
-- файл **`.graphqlrc.yml`** ([GraphQL Config](https://the-guild.dev/graphql/config/docs));
-- у **`.vscode/extensions.json`** в масиві **`recommendations`** — запис **`graphql.vscode-graphql`**.
+[graphql-tooling](./js/tooling.mdc)
 
-## `.graphqlrc.yml`
-
-Підстав свої шляхи до схеми та до файлів з операціями; приклад орієнтиру:
-
-```yaml title=".graphqlrc.yml"
-schema: node_modules/@nitra/efes-shared/schema/maya.graphql
-documents:
-  - '**/*.{vue,js,ts,tsx}'
-```
-
-## `.vscode/extensions.json`
-
-Додай **`graphql.vscode-graphql`** до наявного списку **`recommendations`** (не замінюй інші записи):
-
-```json title=".vscode/extensions.json"
-{
-  "recommendations": ["graphql.vscode-graphql"]
-}
-```
+[graphql-vscode-extensions](./js/vscode_extensions.mdc)

package/rules/hasura/js/internal_urls.mdc

@@ -0,0 +1,27 @@
+## Внутрішній кластерний URL для HASURA_GRAPHQL_ENDPOINT
+
+У `*.env` для атрибута `HASURA_GRAPHQL_ENDPOINT` підключення має бути **усередині кластера**, а не через публічний домен — інакше CI кладе метадані через зовнішній бекенд і ламає перевипуск/міграції.
+
+Правило застосовується лише до проєктів **nitra** (у кореневому `package.json` `"repository": "https://github.com/nitra/*"`) і **abie** (`"repository": "https://github.com/abinbevefes/*"`); для інших репозиторіїв перевірка пропускається.
+
+Файл `.env` (без імені) — виключення з цього правила, його змінювати не потрібно.
+
+Приклад **неправильного** значення:
+
+```env
+HASURA_GRAPHQL_ENDPOINT=https://vybeerai.com.ua/contract/ql
+```
+
+Правильне значення:
+
+```env
+HASURA_GRAPHQL_ENDPOINT=http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080
+```
+
+де `contract-h-hl` — це `metadata.name` headless Service з `hasura/k8s/base/svc-hl.yaml` (пара з clusterIP `contract-h` у `svc.yaml`, якщо є; узгоджено з k8s: суфікс `-hl` на базі `-h`), а `ua-contract` — `metadata.name` namespace з `hasura/k8s/base/namespace.yaml`.
+
+Формат URL: `http://<service>.<namespace>.svc.<cluster>.internal:<port>`
+
+- `http://` обов'язковий (TLS усередині кластера зайвий)
+- DNS-суфікс — `<cluster>.internal` (GKE/GCP)
+- Сервіс і namespace звіряються з `hasura/k8s/base/svc-hl.yaml` та `hasura/k8s/base/namespace.yaml`

package/rules/hasura/js/migrations.mdc

@@ -0,0 +1,13 @@
+## Міграції: лише `up.sql`, без `down.sql`
+
+При створенні будь-якої нової директорії міграції у `hasura/migrations/` **не створювати файл `down.sql`**.
+У директорії міграції має бути **тільки `up.sql`**.
+
+Приклад коректної структури:
+
+```
+hasura/migrations/default/1781247030100_add_foo/
+└── up.sql   ✓
+```
+
+Файл `down.sql` у цьому проєкті **не використовується** і не повинен з'являтися.

package/rules/hasura/js/svc_hl.mdc

@@ -0,0 +1,17 @@
+## Іменування headless та clusterIP Service у hasura/k8s/base
+
+Hasura-конвенція іменування Service у `hasura/k8s/base/svc.yaml` та `svc-hl.yaml`:
+
+- **clusterIP Service** (`svc.yaml`) — базовий сегмент закінчується на **`-h`** (наприклад, `contract-h`)
+- **Headless Service** (`svc-hl.yaml`) — закінчується на **`-h-hl`** (наприклад, `contract-h-hl`)
+
+Пара: `contract-h` (clusterIP) + `contract-h-hl` (headless) — обидва імені мають бути узгоджені між собою та з `HASURA_GRAPHQL_ENDPOINT` у `*.env`.
+
+Перевірка виконується Rego-полісі `hasura.svc_hl` (package `hasura.svc_hl`):
+
+```
+conftest test hasura/k8s/base/svc-hl.yaml -p npm/rules/hasura/policy/svc_hl \
+  --namespace hasura.svc_hl
+```
+
+Cross-file перевірку (узгодженість `HASURA_GRAPHQL_ENDPOINT` ↔ YAML) виконує `js/internal_urls.mjs`.

package/rules/hasura/main.mdc

@@ -5,38 +5,16 @@ globs: "**/hasura/**,**/*.env"
 alwaysApply: false
 ---
 
-## Підключення для оновлення метаданих у CI (Nitra та Abinbevefes)
+Правило охоплює: коректність підключення Hasura у CI-середовищі (внутрішній URL кластера), конвенцію іменування k8s-сервісів та структуру директорій міграцій.
 
-У `*.env` для атрибута `HASURA_GRAPHQL_ENDPOINT` підключення має бути **усередині кластера**, а не через публічний домен — інакше CI кладе метадані через зовнішній бекенд і ламає перевипуск/міграції.
+[hasura-internal_urls](./js/internal_urls.mdc)
 
-Приклад **неправильного** значення:
+[hasura-svc_hl](./js/svc_hl.mdc)
 
-```env
-HASURA_GRAPHQL_ENDPOINT=https://vybeerai.com.ua/contract/ql
-```
+[hasura-migrations](./js/migrations.mdc)
 
-Правильне значення:
+## Швидкий gate через conftest
 
-```env
-HASURA_GRAPHQL_ENDPOINT=http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080
-```
-
-де `contract-h-hl` — це `metadata.name` headless Service з `hasura/k8s/base/svc-hl.yaml` (пара з clusterIP `contract-h` у `svc.yaml`, якщо є; узгоджено з k8s: суфікс `-hl` на базі `-h`), а `ua-contract` — `metadata.name` namespace з `hasura/k8s/base/namespace.yaml`.
-
-Правило застосовується для проєктів **nitra** (у кореневому `package.json` `"repository": "https://github.com/nitra/*"`) і **abie** (`"repository": "https://github.com/abinbevefes/*"`); для інших репозиторіїв перевірка пропускається.
-
-Файл .env це (без імені) це виключення з цього правила, його змінювати не потрібно
-
-## Міграції: лише `up.sql`, без `down.sql`
-
-При створенні будь-якої нової директорії міграції у `hasura/migrations/` **не створювати файл `down.sql`**.
-У директорії міграції має бути **тільки `up.sql`**.
-
-Приклад коректної структури:
-
-```
-hasura/migrations/default/1781247030100_add_foo/
-└── up.sql   ✓
-```
-
-Файл `down.sql` у цьому проєкті **не використовується** і не повинен з'являтися.
+| Пакет | Файл | Що перевіряє |
+|---|---|---|
+| `hasura.svc_hl` | `policy/svc_hl/svc_hl.rego` | Іменування headless/clusterIP Service: суфікси `-h-hl` та `-h` |

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

@@ -0,0 +1,26 @@
+## Чотирикроковий пайплайн генерації AVIF-двійників
+
+AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor fix image-avif`. Правило `image-compress` відповідає лише за стиснення початкових raster/SVG-файлів через `@nitra/minify-image`, а AVIF лишається окремим правилом. Перевірка виконує чотири кроки в порядку:
+
+1. **Pre-scan**: шукає у `.vue`/`.html` хоча б одне raster-посилання, яке потенційно треба переписати на AVIF-двійник (`import x from '...png'` або `<img src="...png" />`). Пакети з opt-out `disable-avif: true` пропускаються. **Якщо жодного raster-посилання не знайдено — `check image-avif` завершується успіхом одразу: ні `npx --avif`, ні rewrite, ні cleanup-сиріт не виконуються** (нічого було б змінювати). Так уникаємо дорогого `npx @nitra/minify-image` у проєктах, де AVIF не вживається.
+2. Запускає `npx @nitra/minify-image --src=. --write --avif` (≥ **3.3.1**) — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF. CLI порівнює sha1 кожного raster-сорсу зі збереженим у `.n-minify-image.tsv` і перезаписує `<source>.avif` при зміні оригіналу.
+3. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
+   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
+   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
+4. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости». **Зауваж**: cleanup виконується ЛИШЕ якщо pre-scan на кроці 1 знайшов хоча б одне raster-посилання — інакше осиротілі `.avif` залишаються недоторканими (видаляться вже наступним прогоном, коли в `.vue`/`.html` зʼявиться raster для конвертації).
+
+```vue title="App.vue (після check image-avif)"
+<script setup>
+import welcomeImage from './assets/welcome.png.avif'
+</script>
+
+<template>
+  <img :src="welcomeImage" alt="Welcome" />
+</template>
+```
+
+Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
+
+Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image-avif` падає з помилкою на конкретний файл.
+
+AVIF-двійники **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).

package/rules/image-avif/js/package_json_optout.mdc

@@ -0,0 +1,21 @@
+## Опт-аут для конкретного пакета
+
+У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл або публічний сайт без гарантованої AVIF-підтримки), додай у `package.json` цього пакета. Заборонений typo `disabled-avif` (канон — `disable-avif`): [package.json.deny.json](./policy/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.json через conftest (Rego)
+
+Rego-пакет `image_avif.package_json` перевіряє коректність конфігурації опт-ауту у `package.json`:
+
+- Поле `"@nitra/minify-image"` має бути обʼєктом (якщо задано).
+- Ключ `"disable-avif"` має бути `boolean`.
+- Забороняє typo-ключі (наприклад, `"disabled-avif"`) через deny-template із [`package.json.deny.json`](./policy/package_json/template/package.json.deny.json).

package/rules/image-avif/main.mdc

@@ -5,41 +5,14 @@ globs: "**/*.{png,jpg,jpeg,gif,avif,vue,html}"
 alwaysApply: false
 ---
 
-AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor fix image-avif`. Правило `image-compress` відповідає лише за стиснення початкових raster/SVG-файлів через `@nitra/minify-image`, а AVIF лишається окремим правилом. Перевірка робить чотири кроки в порядку:
+Правило забезпечує, що кожне raster-зображення (`png`, `jpg`, `jpeg`, `gif`), на яке посилаються `.vue`/`.html` файли, має AVIF-двійник і що посилання переписані на нього. Генерація, rewrite і cleanup AVIF-сиріт виконуються автоматично через `npx @nitra/cursor fix image-avif`.
 
-1. **Pre-scan**: шукає у `.vue`/`.html` хоча б одне raster-посилання, яке потенційно треба переписати на AVIF-двійник (`import x from '...png'` або `<img src="...png" />`). Пакети з opt-out `disable-avif: true` пропускаються. **Якщо жодного raster-посилання не знайдено — `check image-avif` завершується успіхом одразу: ні `npx --avif`, ні rewrite, ні cleanup-сиріт не виконуються** (нічого було б змінювати). Так уникаємо дорогого `npx @nitra/minify-image` у проєктах, де AVIF не вживається.
-2. Запускає `npx @nitra/minify-image --src=. --write --avif` (≥ **3.3.1**) — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF. CLI порівнює sha1 кожного raster-сорсу зі збереженим у `.n-minify-image.tsv` і перезаписує `<source>.avif` при зміні оригіналу.
-3. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
-   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
-   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
-4. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости». **Зауваж**: cleanup виконується ЛИШЕ якщо pre-scan на кроці 1 знайшов хоча б одне raster-посилання — інакше осиротілі `.avif` залишаються недоторканими (видаляться вже наступним прогоном, коли в `.vue`/`.html` зʼявиться raster для конвертації).
+[image-avif-avif_generation](./js/avif_generation.mdc)
 
-```vue title="App.vue (після check image-avif)"
-<script setup>
-import welcomeImage from './assets/welcome.png.avif'
-</script>
+[image-avif-package_json_optout](./js/package_json_optout.mdc)
 
-<template>
-  <img :src="welcomeImage" alt="Welcome" />
-</template>
-```
+## Швидкий gate через conftest
 
-Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
-
-Якщо 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](./policy/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 перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).
+| Rego-пакет | Що перевіряє |
+|---|---|
+| `image_avif.package_json` | typo-ключі, тип поля та тип `disable-avif` в опт-аут конфігу `package.json` |

package/rules/image-compress/js/package_json.mdc

@@ -0,0 +1,7 @@
+## Заборонені залежності у `package.json`
+
+`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` — CLI запускається лише через `npx`. Якщо потрібен явний пін — у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
+
+Перевіряється через Rego-пакет `image_compress.package_json`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
+
+Окремий `package.json`-скрипт `lint-image` не потрібен і не перевіряється — єдина точка входу `n-cursor lint image-compress`.

package/rules/image-compress/js/package_setup.mdc

@@ -0,0 +1,13 @@
+## Кеш-файли: що зберігати в git
+
+**`.n-minify-image.tsv`** у корені сканованого каталогу — **має бути в git** (source of truth для sha1-перевірок і lifetime savings). У `.gitignore` його не додавай.
+
+**`node_modules/.cache/@nitra/minify-image/mtime.tsv`** — локальний fast-path; авто-gitignored через `node_modules/`.
+
+Застарілий **`.minify-image-cache.tsv`** у корені (з версій `@nitra/minify-image` < 3.2) — видали після міграції на split-cache:
+
+```sh
+git rm --cached .minify-image-cache.tsv 2>/dev/null || true && rm -f .minify-image-cache.tsv
+```
+
+Також прибери відповідний рядок з `.gitignore`, якщо є.

package/rules/image-compress/main.mdc

@@ -9,18 +9,10 @@ CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (
 
 Окремий workflow `lint-image.yml` створювати не треба; якщо потрібен CI-gate для зображень, використовуй `n-cursor lint image-compress --read-only`.
 
-## `package.json`
+[image-compress-package_setup](./js/package_setup.mdc)
 
-- Заборонені залежності `@nitra/minify-image` у deps/devDeps: [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
+[image-compress-package_json](./js/package_json.mdc)
 
-Окремий `package.json`-скрипт `lint-image` не потрібен і не перевіряється — єдина точка входу `n-cursor lint image-compress`.
+## Швидкий gate через conftest
 
-## Кеш
-
-- **`.n-minify-image.tsv`** у корені сканованого каталогу — **має бути в git** (source of truth для sha1-перевірок і lifetime savings). У `.gitignore` його не додавай.
-- **`node_modules/.cache/@nitra/minify-image/mtime.tsv`** — локальний fast-path; авто-gitignored через `node_modules/`.
-- Застарілий `.minify-image-cache.tsv` у корені — видали (`git rm --cached`, прибери рядок з `.gitignore`).
-
-## Заборонені залежності
-
-`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` — CLI запускається лише через `npx`. Якщо потрібен явний пін — у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
+- `image_compress.package_json` — забороняє `@nitra/minify-image` у `dependencies`/`devDependencies` проєкту

package/rules/js/docs/index.md

@@ -6,7 +6,7 @@ resource: npm/rules/js/
 
 # npm/rules/js
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
 | [main.mjs](main.md) | JS Module |

package/rules/js/js/dep-policy.mdc

@@ -0,0 +1,17 @@
+## Залежнісна політика (що не додавати)
+
+`@e18e/eslint-plugin` окремо не додавай — він уже в залежностях `@nitra/eslint-config` (з **3.8.0**), oxlint підвантажує його з `node_modules`. Пакети `oxlint`/`eslint`/`jscpd`/`knip` теж не додавай у `devDependencies` без потреби монорепо — `bunx` тягне їх ad-hoc.
+
+### Заборона `@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'
+```

package/rules/js/js/eslint-config.mdc

@@ -0,0 +1,28 @@
+## ESLint flat config — `eslint.config.js`
+
+У корені проєкту має бути `eslint.config.js` (або `eslint.config.mjs`) з flat config на основі `getConfig` з `@nitra/eslint-config`.
+
+```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`.
+
+Обов'язкові умови:
+- файл `eslint.config.js` або `eslint.config.mjs` існує;
+- містить виклик `getConfig`;
+- імпортує з `@nitra/eslint-config`;
+- у `ignores` є запис `**/auto-imports.d.ts`.
+
+Застарілі конфіги (`.eslintrc`, `.eslintrc.js`, `.eslintrc.json`, `.eslintrc.yml`) — **видали**, вони несумісні з flat config.
+
+З версії `@nitra/eslint-config` **3.9.2** `getConfig` вбудовує ignore для `**/adr/**` — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно.

package/rules/js/js/extensions.mdc

@@ -0,0 +1,8 @@
+## `.vscode/extensions.json` — рекомендовані розширення
+
+У `.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)

package/rules/js/js/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`: `type` лишається каноном для всього дерева, а розширення нового файлу прибирає залежність від нього.
+
+Стосується **backend і frontend** — будь-який новий вихідний файл: `src/`, тести `*.test.*`, `scripts/`, `src/conn/` тощо.
+
+**Існуючі `.js` лишаються як є** — масово перейменовувати не треба; це конвенція для нового коду. Автоматичної перевірки тут немає: stateless-скан не відрізнить новий файл від існуючого, тож `.js` нікого не фейлить.

package/rules/js/js/for-in.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` як часткова страховка (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)
+}
+```