@nitra/cursor 1.8.192 → 1.8.197

package/CHANGELOG.md

@@ -4,6 +4,46 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.197] - 2026-05-07
+
+### Changed
+
+- `image` правило розщеплене на два самостійні: **`image-compress`** (валідація `lint-image` / `.gitignore` / залежностей — стиснення raster/SVG через `@nitra/minify-image`) і **`image-avif`** (генерація AVIF-двійників, переписування raster-посилань у `.vue`/`.html` на `.avif`, прибирання AVIF-сиріт). Це дозволяє тримати компресію всюди, а AVIF — лише там, де його підтримка гарантована (адмінки), вимикаючи його для публічних сайтів через `disable-rules: ["image-avif"]` у `.n-cursor.json` чи опт-аут на рівні пакета (`"@nitra/minify-image": { "disable-avif": true }` у `package.json` сайту).
+- `auto-rules.md` / `auto-rules.mjs`: автодетект `image-compress - [bun]` (всюди, де є `package.json`), `image-avif - [vue, image-compress]` (лише для проєктів з `.vue`-файлами і вже активним `image-compress`).
+- Видалено `npm/scripts/check-image.mjs` і `npm/mdc/image.mdc` — їх замінили `check-image-compress.mjs` + `check-image-avif.mjs` і `image-compress.mdc` + `image-avif.mdc`.
+- Канонічний `lint-image` залишається без `--avif` (його перевіряє `image-compress`); `npx @nitra/cursor check image-avif` тепер є самостійною командою для AVIF-pipeline.
+
+### Added
+
+- `tests/auto-rules.test.mjs`: тест на `disable-rules: ["image-compress"]` → `image-avif` теж не додається (транзитивна залежність).
+
+## [1.8.194] - 2026-05-07
+
+### Fixed
+
+- `check-image.mjs`: резолвер `resolveImagePath` був інлайн-наївний (`/path` → `<cwd>/<path>`, голий шлях → `null`), що в реальних Quasar/Vite-проєктах давало 0 rewrite-ів і помилковий ріст `failedRefs`. Замінено на `resolveImageCandidates`, який повертає **впорядкований список кандидатів**:
+  - `./x.png` / `../x.png` → відносно файла-джерела;
+  - `/x.png` → `<packageRoot>/public/x.png`, потім `<packageRoot>/x.png`, потім `<cwd>/x.png` (legacy fallback);
+  - голий шлях з принаймні одним `/` (`assets/img.png`, `start-page-ua/logo.png`) → відносно файла-джерела + `<packageRoot>/public/<path>` (Quasar-конвенція);
+  - bare без `/` → alias resolver невідомий, посилання тихо пропускаємо (без fail).
+- `check-image.mjs`: `cleanupOrphanAvifs` тепер пропускає `.avif` у каталогах артефактів збірки (`build`, `android`, `ios`, `.output`, `.nuxt`, `.cache`) — раніше cleanup міг затирати продукт `bun run build` чи Capacitor sync.
+
+### Added
+
+- `tests/check-image.test.mjs`: 4 нових кейси — Quasar-style `src="/api-page/1.png"` через `<pkg>/public/`; `<img src="assets/images/x.png">` у `.html` через relative-to-source; `src="start-page-ua/logo.png"` у `.vue` через `<pkg>/public/`; cleanup не чіпає AVIF у `build/`/`android/`/`ios/`/`.output/`/`.nuxt/`/`.cache/`.
+
+## [1.8.193] - 2026-05-07
+
+### Fixed
+
+- `check-image.mjs`: cleanup AVIF-сиріт більше не зачіпає `.avif` файли всередині пакетів з опт-аутом (`"@nitra/minify-image": { "disable-avif": true }`). Раніше: пакет з опт-аутом не сканувався на refs → його `.avif` потрапляли у список «сиріт» і видалялись, навіть якщо насправді використовувалися через alias / runtime-обчислений шлях. Тепер `checkVueAvifImports` повертає список абсолютних коренів opt-out пакетів, а `cleanupOrphanAvifs` пропускає `.avif` під ними.
+- `check-image.mjs`: запис у `.vue`/`.html` тепер строго послідовний з cleanup (write-then-cleanup): перший виконує `checkVueAvifImports` (per-file `writeFile` після обробки), і тільки після цього `cleanupOrphanAvifs` читає вже оновлені `usedAvifAbs` і видаляє лише дійсних сиріт.
+- `check-image.mjs`: введено агреговані лічильники `RewriteStats` (`rewrittenRefs` / `rewrittenFiles` / `failedRefs`) і єдиний фінальний рядок-підсумок `image: rewrote N references in M files; deleted K orphan AVIFs; failed to rewrite L references` — раніше підсумок дублювався per-package і не виокремлював orphan-cleanup vs failed-rewrites.
+
+### Added
+
+- `tests/check-image.test.mjs`: 5 нових кейсів — статичний `<img src="a.png">` авто-переписується (за наявності `a.png` і `a.png.avif`); реактивне `:src="dyn"` залишається незмінним і orphan AVIF видаляється; змішані форми у одному файлі (статичний + import + реактивний + `data-src=`) — переписуються лише покривані; opt-out пакет — AVIF всередині не вважається сиротою; ідемпотентність повторного `check image` на чистому стані.
+
 ## [1.8.192] - 2026-05-07
 
 ### Added

package/bin/auto-rules.md

@@ -22,7 +22,9 @@ graphql - якщо хоч в одному js або vue файлі присут
 
 hasura - якщо в директорії присутній config.yaml, який містить рядок `metadata_directory: metadata`
 
-image - [vue]
+image-compress - [bun]
+
+image-avif - [vue, image-compress]
 
 js-lint - якщо присутній хоч один js файл
 

package/mdc/image-avif.mdc

@@ -0,0 +1,55 @@
+---
+description: AVIF-двійники для raster-зображень з ув'язуванням у .vue/.html
+alwaysApply: true
+version: '1.0'
+---
+
+AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor check image-avif` — у `lint-image` прапорець `--avif` заборонений (це валідує правило `image-compress`). Перевірка робить три кроки в порядку:
+
+1. Запускає `npx @nitra/minify-image --src=. --write --avif` — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF.
+2. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
+   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
+   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
+3. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости».
+
+```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-і).
+
+## Коли НЕ вмикати правило
+
+AVIF ще не підтримується **усіма** браузерами: для публічного сайту, де серед користувачів можуть бути старі/нестандартні браузери, конвертація raster → AVIF як основного джерела ризикована. Для адмінок (де користувачі — співробітники з сучасними браузерами) AVIF безпечний.
+
+У монорепо з адмінкою + публічним сайтом стандартна стратегія така: правило `image-avif` присутнє у `.n-cursor.json`, але для пакета-сайту вмикається опт-аут (нижче).
+
+## Опт-аут для конкретного пакета
+
+У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл або публічний сайт без гарантованої AVIF-підтримки), додай у `package.json` цього пакета:
+
+```json title="apps/site/package.json"
+{
+  "@nitra/minify-image": {
+    "disable-avif": true
+  }
+}
+```
+
+Тоді перевірка пропускає `.vue` файли цього пакета і не видаляє наявні `.avif` всередині як «сироти». У root-`package.json` опт-аут діє лише для файлів кореня (вкладені workspaces перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).
+
+`image-compress` (раніший крок: lint-image, кеш, заборонені залежності) при цьому продовжує працювати — стиснення raster-зображень виконується незалежно від AVIF.
+
+## Перевірка
+
+`npx @nitra/cursor check image-avif` (запуск AVIF-генерації + авто-заміна raster-посилань на `.avif` у `.vue`/`.html` кожного workspace-пакета + прибирання AVIF-сиріт; пакети з `"@nitra/minify-image": { "disable-avif": true }` пропускаються).

package/mdc/image-compress.mdc

@@ -0,0 +1,56 @@
+---
+description: Оптимізація raster/SVG через @nitra/minify-image у локальному lint
+alwaysApply: true
+version: '1.0'
+---
+
+CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (≥ **3.2.0**) запускається через `npx` (як `markdownlint-cli2` у text.mdc) і **не** додається в `dependencies` / `devDependencies`. Канонічний `lint-image` — авто-оптимізація з прапорцем `--write`: стискає raster/SVG на місці. **AVIF-генерація (`--avif`) у `lint-image` заборонена** — її виконує окреме правило `image-avif` (`npx @nitra/cursor check image-avif`), яке заодно прибирає AVIF-сироти. Split-cache робить повторні прогони дешевими — і локально, і після `git clone`.
+
+Перевірка лише локальна — у CI `lint-image` не запускаємо (sharp/svgo тягнуть бінарні залежності, цінність на ubuntu-runner-ах нижча за час прогону). Окремий workflow `lint-image.yml` створювати не треба.
+
+## `package.json`
+
+```json title="package.json"
+{
+  "scripts": {
+    "lint": "bun run lint-js && bun run lint-text && bun run lint-ga && bun run lint-image && oxfmt .",
+    "lint-image": "npx @nitra/minify-image --src=. --write"
+  }
+}
+```
+
+Якщо в `package.json` уже є агрегований `lint`, додай у його ланцюжок `bun run lint-image` (як `bun run lint-text`, `bun run lint-js`, `bun run lint-ga`). Так розробник, що локально гонить `bun run lint`, перед фіксацією одразу бачить, чи зросли зображення.
+
+## Split-cache
+
+Починаючи з `@nitra/minify-image` **3.2.0** кеш розбитий на два файли з різною семантикою:
+
+### `.n-minify-image.tsv` — source of truth у git
+
+У корені сканованого каталогу. Формат: `<rel-path>\t<sha1-hex>\t<originalSize>\t<size>`.
+
+Slow-path і джерело даних для `Project lifetime savings`. **Має бути в git** — після `git clone` чи `git checkout` (mtime скидається на час checkout-у) CLI читає файл, рахує SHA-1 і порівнює зі збереженим у TSV хешем; на match локальний mtime-кеш зігрівається без reprocess. Рядки відсортовані алфавітно, hash і size змінюються лише при реальній зміні контенту — diff чистий.
+
+### `node_modules/.cache/@nitra/minify-image/mtime.tsv` — локальний fast-path
+
+Формат: `<rel-path>\t<mtime>\t<size>`. При збігу `(size, mtime)` CLI пропускає файл без читання — константа per-file.
+
+Лежить під `node_modules/`, тож **авто-gitignored** за конвенцією JS-tooling-у (так кешуються ESLint, Babel, webpack, Turbo). Окремий рядок у `.gitignore` не потрібен. `rm -rf node_modules` зносить — наступний запуск відновлює його через slow-path проти `.n-minify-image.tsv`, без reprocess.
+
+### Міграція з versions < 3.2
+
+Старий єдиний `.minify-image-cache.tsv` (4 колонки `path\tmtime\toriginalSize\tsize`, зазвичай у `.gitignore`) автоматично читається при першому запуску для seed-у `originalSize` у `.n-minify-image.tsv` (lifetime savings не скидається). Після цього старий файл видаляють вручну:
+
+```bash
+git rm --cached .minify-image-cache.tsv 2>/dev/null || true
+rm -f .minify-image-cache.tsv
+# прибери відповідний рядок з .gitignore, якщо був
+```
+
+## Заборонені залежності
+
+`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` кореневого `package.json` — CLI запускається лише через `npx` (так само, як `markdownlint-cli2` у text.mdc). Якщо потрібен явний пін — закладай діапазон версій npm у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
+
+## Перевірка
+
+`npx @nitra/cursor check image-compress` (охоплює `lint-image` з обовʼязковими `--src=.`, `--write` і **забороненим** `--avif`; агрегований `lint`; заборону `@nitra/minify-image` у залежностях; `.n-minify-image.tsv` НЕ в `.gitignore` — має бути в git; відсутність застарілого `.minify-image-cache.tsv` у корені).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.192",
+  "version": "1.8.197",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/scripts/auto-rules.mjs

@@ -31,7 +31,8 @@ export const AUTO_RULE_ORDER = Object.freeze([
   'ga',
   'graphql',
   'hasura',
-  'image',
+  'image-avif',
+  'image-compress',
   'js-lint',
   'js-mssql',
   'js-bun-db',
@@ -56,7 +57,8 @@ export const AUTO_SKILL_ORDER = Object.freeze(['abie-kustomize', 'fix', 'lint'])
 export const AUTO_RULE_DEPENDENCIES = Object.freeze(
   /** @type {Record<string, readonly string[]>} */ ({
     changelog: Object.freeze(['bun']),
-    image: Object.freeze(['vue'])
+    'image-avif': Object.freeze(['vue', 'image-compress']),
+    'image-compress': Object.freeze(['bun'])
   })
 )
 

package/scripts/check-image-avif.mjs

@@ -0,0 +1,394 @@
+/**
+ * Перевіряє відповідність репозиторію правилу `image-avif.mdc`: AVIF-генерацію та
+ * ув'язування `.avif`-двійників з посиланнями у `.vue`/`.html`.
+ *
+ * Дії під час `check image-avif`:
+ * 1. `npx @nitra/minify-image --src=. --write --avif` — генерує AVIF-двійники.
+ * 2. У кожному workspace-пакеті переписує raster-посилання у `.vue`/`.html` на `.avif`
+ *    (де AVIF-двійник реально існує на диску). Pakety з `"@nitra/minify-image": {
+ *    "disable-avif": true }` у `package.json` пропускаються.
+ * 3. Прибирає AVIF-сироти — `<name>.<ext>.avif`, на які не лишилось жодного посилання
+ *    у `.vue`/`.html` репозиторію, видаляються (умова правила: «AVIF лишається лише
+ *    там, де заміна вдалася»).
+ *
+ * Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу
+ * нема на диску → `.avif` теж не згенерувався) — фейл на конкретний файл.
+ *
+ * Правило самостійне від `image-compress`: AVIF можна вмикати лише в адмінках (де AVIF
+ * підтримується сучасними браузерами) і не вмикати в публічних сайтах. Перевірка скрипта
+ * `lint-image` (заборона `--avif` у ньому) залишається у `image-compress` — тут вона не
+ * дублюється.
+ */
+import { existsSync } from 'node:fs'
+import { readFile, unlink, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { env } from 'node:process'
+
+import { createCheckReporter } from './utils/check-reporter.mjs'
+import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
+import { walkDir } from './utils/walkDir.mjs'
+import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
+
+/** Імʼя CLI-пакета, який генерує AVIF. */
+const MINIFY_PACKAGE_NAME = '@nitra/minify-image'
+
+/** Поле в `package.json` для конфігу @nitra/minify-image (наприклад, `disable-avif`). */
+const PKG_CONFIG_FIELD = '@nitra/minify-image'
+
+/**
+ * Імена каталогів, які `cleanupOrphanAvifs` не зачіпає, бо це артефакти збірки/нативні
+ * платформи — `.avif` всередині — це продукт попереднього `bun run build`/Capacitor sync,
+ * а не кандидати на видалення. `walkDir` уже скіпає `node_modules`, `.git`, `dist`,
+ * `coverage`, `.turbo`, `.next` — додатково для cleanup ігноруємо ще ці.
+ */
+const CLEANUP_EXTRA_IGNORE_DIR_NAMES = new Set(['build', 'android', 'ios', '.output', '.nuxt', '.cache'])
+
+/**
+ * Регексп для імпортів raster-зображень у `.vue` файлах.
+ * Захоплює `import name from '...ext'` (як default, так і type-only форми не потрібні —
+ * type-imports asset-ів не існує). Захоплюється повний шлях у групі 1.
+ */
+const VUE_RASTER_IMPORT_RE = /import\s+\w[\w$]*\s+from\s+['"]([^'"\n]+\.(?:png|jpe?g|gif))['"]/giu
+
+/**
+ * Регексп для прямих посилань на raster-зображення у HTML-атрибуті `src="..."` шаблона `.vue`
+ * (наприклад `<img src="./hero.png" />`). Vite перетворює такі шляхи на asset-імпорти на етапі
+ * збірки, тож для них теж діє вимога вживати AVIF-двійник.
+ *
+ * Лукбехайнд `(?<![:\-_.])` виключає реактивне `:src="..."` (там JS-вираз — змінна або виклик,
+ * перевіряється через імпорт), `data-src="..."` і `obj.src=...` у `<script>`.
+ */
+const VUE_RASTER_STATIC_SRC_RE = /(?<![:\-_.])\bsrc\s*=\s*['"]([^'"\s]+\.(?:png|jpe?g|gif))['"]/giu
+
+/**
+ * Регексп для готових AVIF-посилань у `.vue`/`.html` (як `import x from '...png.avif'`,
+ * так і `<img src="....png.avif" />`). Потрібен лише для збору множини «живих» AVIF —
+ * щоб після авто-заміни знати, які `<...>.avif` файли ще на щось посилаються, а які
+ * є сиротами і підлягають видаленню.
+ */
+const VUE_AVIF_REF_RE = /['"]([^'"\s]+\.(?:png|jpe?g|gif)\.avif)['"]/giu
+
+/**
+ * Чи у `package.json` пакета вимкнено avif-перевірку Vue-імпортів.
+ * Очікувана форма: `"@nitra/minify-image": { "disable-avif": true }`.
+ * @param {Record<string, unknown>} pkg розібраний package.json пакета
+ * @returns {boolean} true, якщо опт-аут активовано
+ */
+function packageHasAvifDisabled(pkg) {
+  const cfg = pkg[PKG_CONFIG_FIELD]
+  return Boolean(
+    cfg && typeof cfg === 'object' && /** @type {Record<string, unknown>} */ (cfg)['disable-avif'] === true
+  )
+}
+
+/**
+ * Будує впорядкований список кандидатів-абсолютних шляхів, по яких треба перевіряти
+ * наявність зображення для даного посилання у `.vue`/`.html`. Caller перевіряє кожен
+ * кандидат на існування `<candidate>.avif` (для rewrite) або `<candidate>` (для збору
+ * вже-вживаного `.avif`) і обирає перший, що існує.
+ *
+ * Підтримувані форми:
+ * - `./x.png`, `../x.png` — відносно файла-джерела (ES-import / asset-relative).
+ * - `/x.png` — у Vite/Quasar-конвенції це `<packageRoot>/public/x.png`. Спочатку пробуємо
+ *   `public/`, потім сам корінь пакета (на випадок mono-репо без `public/`), нарешті
+ *   `<cwd>/x.png` як legacy fallback (щоб не зламати проєкти з кореневими ассетами).
+ * - голий шлях з принаймні одним `/` (`assets/img.png`, `start-page-ua/logo.png`) — у
+ *   HTML/Vue браузер резолвить його відносно документа, тому повертаємо relative-to-source
+ *   та `<packageRoot>/public/<path>` як другий кандидат (Quasar-проєкти кладуть public-assets
+ *   саме туди).
+ * - bare без `/` (`foo`) — ймовірно alias resolver (Vite/Webpack), резолвити не вміємо,
+ *   повертаємо порожній список → caller просто пропускає посилання, не звітує fail.
+ * @param {string} importPath шлях з `import x from '...'` або `src="..."`
+ * @param {string} sourceAbsPath абсолютний шлях файла-джерела
+ * @param {string|null} packageRootAbs абсолютний корінь workspace-пакета, у якому лежить
+ * `sourceAbsPath` (для резолвера `/path` як `<root>/public<path>`); `null`, якщо невідомо
+ * @returns {string[]} впорядкований список абсолютних шляхів-кандидатів
+ */
+function resolveImageCandidates(importPath, sourceAbsPath, packageRootAbs) {
+  if (importPath.startsWith('.')) {
+    return [join(sourceAbsPath, '..', importPath)]
+  }
+  if (importPath.startsWith('/')) {
+    /** @type {string[]} */
+    const candidates = []
+    if (packageRootAbs) {
+      candidates.push(join(packageRootAbs, 'public', importPath))
+      candidates.push(join(packageRootAbs, importPath))
+    }
+    candidates.push(join(process.cwd(), importPath))
+    return candidates
+  }
+  if (importPath.includes('/')) {
+    /** @type {string[]} */
+    const candidates = [join(sourceAbsPath, '..', importPath)]
+    if (packageRootAbs) {
+      candidates.push(join(packageRootAbs, 'public', importPath))
+    }
+    return candidates
+  }
+  return []
+}
+
+/**
+ * Аґреговані лічильники по проходу `check image-avif`:
+ *   - `rewrittenRefs` — скільки конкретних посилань (по одному на match) переписано на `.avif`;
+ *   - `rewrittenFiles` — у скількох `.vue`/`.html` файлах хоч одне посилання змінилося;
+ *   - `failedRefs` — скільки конкретних посилань не вдалося переписати (`.avif` не існував).
+ * @typedef {object} RewriteStats
+ * @property {number} rewrittenRefs скільки конкретних посилань переписано на `.avif`
+ * @property {number} rewrittenFiles у скількох `.vue`/`.html` файлах хоч одне посилання змінилося
+ * @property {number} failedRefs скільки конкретних посилань не вдалося переписати (`.avif` не існував)
+ */
+
+/**
+ * Сканує `.vue` і `.html` файли одного workspace-пакета: де можемо, переписує raster-посилання
+ * на `<path>.avif`, де не можемо — фейлимо. Доповнює `usedAvifAbs` шляхами AVIF-двійників, на
+ * які лишилось живе посилання, і `stats` лічильниками rewrite/fail для глобального підсумку.
+ *
+ * Заміна виконується ТІЛЬКИ якщо AVIF-двійник реально існує на диску. Якщо AVIF немає
+ * (наприклад, оригіналу теж немає, тож `--avif` його не згенерував) — фейл, як раніше.
+ * Запис файла відбувається ОДРАЗУ після обробки одного файла (write-then-fail): провал на
+ * наступному файлі НЕ відкочує вже записані зміни попередніх.
+ *
+ * Файли, що належать іншим workspace-пакетам, ігноруються — кожен пакет перевіряється рівно
+ * один раз (інакше при обході кореня `.` ми б повторно зайшли в `demo/` і подвоїли звіти).
+ * @param {string} packageRoot відносний шлях до кореня пакета (наприклад `'.'` або `'demo'`)
+ * @param {string[]} otherRootsAbs абсолютні шляхи інших workspace-коренів — їх піддерева пропускаємо
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @param {Set<string>} usedAvifAbs мутабельна множина абсолютних шляхів `.avif`, що мають
+ * хоч одне посилання у `.vue`/`.html` (доповнюється у цій функції)
+ * @param {RewriteStats} stats глобальні лічильники, що мутуються тут
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>} резолвиться по завершенню перевірки одного пакета
+ */
+async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePaths, usedAvifAbs, stats, fail) {
+  const absRoot = join(process.cwd(), packageRoot)
+  const label = packageRoot === '.' ? 'корінь' : packageRoot
+  /** @type {string[]} */
+  const targetFiles = []
+  await walkDir(
+    absRoot,
+    absPath => {
+      if (!absPath.endsWith('.vue') && !absPath.endsWith('.html')) return
+      if (otherRootsAbs.some(other => absPath.startsWith(`${other}/`))) return
+      targetFiles.push(absPath)
+    },
+    ignorePaths
+  )
+  if (targetFiles.length === 0) return
+
+  for (const absPath of targetFiles) {
+    const rel = relative(process.cwd(), absPath).split('\\').join('/')
+    const original = await readFile(absPath, 'utf8')
+    let updated = original
+
+    /**
+     * @param {RegExp} regex з групою 1 = шлях до зображення
+     * @param {(srcPath: string) => string} renderFailure повідомлення помилки
+     */
+    const processMatches = (regex, renderFailure) => {
+      updated = updated.replaceAll(regex, (full, importPath) => {
+        const candidates = resolveImageCandidates(importPath, absPath, absRoot)
+        if (candidates.length === 0) {
+          // Bare alias (наприклад, '@/assets/x.png' без `/` — впізнаваний alias у Vite/WP);
+          // резолвера тут нема, тому посилання не чіпаємо і не звітуємо як fail.
+          return full
+        }
+        const newImportPath = `${importPath}.avif`
+        const replaced = full.replace(importPath, newImportPath)
+        const found = candidates.find(c => existsSync(`${c}.avif`))
+        if (found) {
+          stats.rewrittenRefs++
+          usedAvifAbs.add(`${found}.avif`)
+          return replaced
+        }
+        stats.failedRefs++
+        fail(renderFailure(importPath))
+        return full
+      })
+    }
+
+    processMatches(
+      VUE_RASTER_IMPORT_RE,
+      importPath =>
+        `[${label}] ${rel}: import з '${importPath}' має посилатись на AVIF-двійник '${importPath}.avif' ` +
+        `(\`npx @nitra/cursor check image-avif\` створює його поряд, якщо оригінал є на диску). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
+    )
+    processMatches(
+      VUE_RASTER_STATIC_SRC_RE,
+      srcPath =>
+        `[${label}] ${rel}: пряме \`src="${srcPath}"\` у шаблоні має використовувати AVIF-двійник \`src="${srcPath}.avif"\` ` +
+        `(або винеси у import + \`:src="..."\`). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
+    )
+
+    for (const match of updated.matchAll(VUE_AVIF_REF_RE)) {
+      const avifPath = match[1]
+      const candidates = resolveImageCandidates(avifPath, absPath, absRoot)
+      for (const cand of candidates) {
+        if (existsSync(cand)) usedAvifAbs.add(cand)
+      }
+    }
+
+    if (updated !== original) {
+      await writeFile(absPath, updated, 'utf8')
+      stats.rewrittenFiles++
+    }
+  }
+}
+
+/**
+ * Сканує всі workspace-пакети: для кожного перевіряє opt-out і за потреби викликає
+ * перевірку Vue-imports. Перевірка пропускається, якщо в репозиторії немає workspaces
+ * або немає `.vue`-файлів — тоді `image-avif` правило не для цього проєкту.
+ *
+ * Повертає список абсолютних коренів пакетів, у яких ввімкнено opt-out (`disable-avif: true`).
+ * Це окремий результат, бо AVIF всередині такого пакета НЕ можна вважати «сиротою» лише
+ * на підставі відсутності посилань у його `.vue`/`.html` (ми взагалі не сканували його
+ * шаблони) — інакше cleanup помилково затирав би AVIF, що використовуються через alias /
+ * runtime-обчислений шлях / зовнішні посилання, які тут не видно.
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @param {Set<string>} usedAvifAbs мутабельна множина абсолютних шляхів `.avif`-двійників,
+ * на які лишилось хоча б одне посилання у `.vue`/`.html` (заповнюється у викликаних функціях)
+ * @param {RewriteStats} stats глобальні лічильники rewrite/fail (мутуються нижче)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<string[]>} абсолютні шляхи коренів пакетів з активним opt-out
+ */
+async function checkVueAvifImports(ignorePaths, usedAvifAbs, stats, pass, fail) {
+  const roots = await getMonorepoPackageRootDirs()
+  const absRootsByRel = new Map(roots.map(r => [r, join(process.cwd(), r)]))
+  /** @type {string[]} */
+  const optedOutAbs = []
+  for (const root of roots) {
+    const pkgPath = join(root, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+    if (packageHasAvifDisabled(pkg)) {
+      pass(
+        `[${root === '.' ? 'корінь' : root}] avif-import enforcement вимкнено через "@nitra/minify-image.disable-avif"`
+      )
+      optedOutAbs.push(absRootsByRel.get(root) ?? join(process.cwd(), root))
+      continue
+    }
+    const otherRootsAbs = roots.filter(r => r !== root && r !== '.').map(r => absRootsByRel.get(r) ?? '')
+    await checkVueAvifImportsInPackage(root, otherRootsAbs, ignorePaths, usedAvifAbs, stats, fail)
+  }
+  return optedOutAbs
+}
+
+/**
+ * Чи є в репозиторії хоч один raster-файл, який мав би сенс конвертувати у AVIF.
+ * Якщо немає — `npx @nitra/minify-image` нема що робити, тож зайвий запуск пропускаємо
+ * (важливо у тестах: фікстурні `.png`-імпорти посилаються на неіснуючі файли, тож
+ * minify-image все одно нічого не згенерує — а зайвий npx-спавн повільний і робить шум).
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<boolean>} `true`, якщо знайдено принаймні один `.png/.jpe?g/.gif`
+ */
+async function hasAnyRasterImage(ignorePaths) {
+  let found = false
+  await walkDir(
+    process.cwd(),
+    absPath => {
+      if (found) return
+      if (/\.(?:png|jpe?g|gif)$/iu.test(absPath)) found = true
+    },
+    ignorePaths
+  )
+  return found
+}
+
+/**
+ * Запускає `npx @nitra/minify-image --src=. --write --avif` для генерації AVIF-двійників.
+ *
+ * Виклик best-effort: якщо мережа/кеш недоступні чи бінарника нема — лог-варн без падіння
+ * перевірки (валідації package.json і vue-refs все одно прогоняться, vue-refs на
+ * відсутні `.avif` фейлять окремо). У тестах та інших ізольованих середовищах npx
+ * можна вимкнути через `NITRA_CURSOR_NO_AVIF_RUN=1` — тоді ця функція no-op.
+ * @returns {void}
+ */
+function runAvifGeneration() {
+  if (env.NITRA_CURSOR_NO_AVIF_RUN === '1') return
+  const result = spawnSync('npx', [MINIFY_PACKAGE_NAME, '--src=.', '--write', '--avif'], {
+    stdio: 'inherit',
+    env
+  })
+  if (result.error) {
+    console.log(
+      `  ⚠️  не вдалося запустити \`npx ${MINIFY_PACKAGE_NAME} --avif\`: ${result.error.message} — vue/html-перевірка покаже файли, для яких не вистачає .avif`
+    )
+    return
+  }
+  if (typeof result.status === 'number' && result.status !== 0) {
+    console.log(
+      `  ⚠️  \`npx ${MINIFY_PACKAGE_NAME} --avif\` завершився з кодом ${result.status} — vue/html-перевірка покаже файли, для яких не вистачає .avif`
+    )
+  }
+}
+
+/**
+ * Видаляє AVIF-сироти — `<...>.avif` файли, на які не лишилось жодного посилання
+ * у `.vue`/`.html` репозиторію. Реалізує умову правила: «AVIF лишається лише там,
+ * де заміна реально вдалася».
+ *
+ * AVIF файли всередині opt-out пакетів (`disable-avif: true`) пропускаються — ми не
+ * сканували їх шаблони, тож не маємо права вважати їх AVIF сиротами. Це гарантує
+ * ідемпотентність повторного `check image-avif` для пакетів, що навмисно вимкнули правило
+ * (наприклад, мобільний бандл, де AVIF підтримка не гарантована).
+ * @param {Set<string>} usedAvifAbs абсолютні шляхи `.avif`, що мають живі посилання
+ * @param {string[]} optedOutAbs абсолютні шляхи коренів пакетів з опт-аутом —
+ * `.avif` під ними не вважаємо сиротами і не видаляємо
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<number>} кількість видалених сиріт
+ */
+async function cleanupOrphanAvifs(usedAvifAbs, optedOutAbs, ignorePaths) {
+  /** @type {string[]} */
+  const orphans = []
+  await walkDir(
+    process.cwd(),
+    absPath => {
+      if (!absPath.endsWith('.avif')) return
+      if (usedAvifAbs.has(absPath)) return
+      if (optedOutAbs.some(root => absPath === root || absPath.startsWith(`${root}/`))) return
+      const segments = absPath.split('/')
+      if (segments.some(seg => CLEANUP_EXTRA_IGNORE_DIR_NAMES.has(seg))) return
+      orphans.push(absPath)
+    },
+    ignorePaths
+  )
+  for (const absPath of orphans) {
+    await unlink(absPath)
+  }
+  return orphans.length
+}
+
+/**
+ * Виконує AVIF-етап: запуск AVIF-генерації, авто-заміна raster-посилань у `.vue`/`.html`,
+ * видалення AVIF-сиріт. Не валідує `package.json`/`lint-image` — це вже у `image-compress`.
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  const ignorePaths = await loadCursorIgnorePaths(process.cwd())
+
+  if (await hasAnyRasterImage(ignorePaths)) {
+    runAvifGeneration()
+  }
+
+  /** @type {Set<string>} */
+  const usedAvifAbs = new Set()
+  /** @type {RewriteStats} */
+  const stats = { rewrittenRefs: 0, rewrittenFiles: 0, failedRefs: 0 }
+  const optedOutAbs = await checkVueAvifImports(ignorePaths, usedAvifAbs, stats, pass, fail)
+  const orphansDeleted = await cleanupOrphanAvifs(usedAvifAbs, optedOutAbs, ignorePaths)
+
+  pass(
+    `image-avif: rewrote ${stats.rewrittenRefs} reference${stats.rewrittenRefs === 1 ? '' : 's'} in ${stats.rewrittenFiles} file${stats.rewrittenFiles === 1 ? '' : 's'}; ` +
+      `deleted ${orphansDeleted} orphan AVIF${orphansDeleted === 1 ? '' : 's'}; ` +
+      `failed to rewrite ${stats.failedRefs} reference${stats.failedRefs === 1 ? '' : 's'}`
+  )
+
+  return reporter.getExitCode()
+}