@nitra/cursor 3.22.0 → 3.23.1

package/rules/image-avif/js/docs/avif_generation.md

@@ -0,0 +1,241 @@
+# avif_generation.mjs
+
+## Огляд
+
+Модуль реалізує перевірку правила `image-avif.mdc`: генерацію AVIF-двійників растрових зображень і ув'язування цих двійників із посиланнями у `.vue`- та `.html`-файлах монорепо. Експортує функцію `check`, яку викликає CLI `n-cursor` для команди `check image-avif` / `fix image-avif`.
+
+Загальний сценарій роботи `check`:
+
+1. **Pre-scan** — шукає у `.vue`/`.html` хоча б одне raster-посилання (через `import x from '...png'` або `<img src="...png" />`), яке потенційно треба переписати на AVIF-двійник. Пакети з opt-out `"@nitra/minify-image": { "disable-avif": true }` у `package.json` пропускаються. Якщо жодного raster-посилання не знайдено — модуль одразу повертає успіх і не запускає ні `npx`, ні rewrite, ні cleanup-пасс.
+2. **AVIF-генерація** — викликає `npx @nitra/minify-image --src=. --write --avif`, який створює AVIF-двійники поряд з оригіналами.
+3. **Rewrite-пасс** — для кожного workspace-пакета (без opt-out) переписує raster-посилання у `.vue`/`.html` на `<...>.avif`, якщо двійник реально існує на диску. Якщо двійника немає (наприклад, оригіналу теж нема) — фейлить конкретне посилання.
+4. **Cleanup-пасс** — видаляє AVIF-сироти (`<...>.avif`, на які не лишилось жодного посилання у `.vue`/`.html` репозиторію), реалізуючи умову «AVIF лишається лише там, де заміна вдалася».
+
+Модуль свідомо не дублює перевірки скрипта `lint-image` (заборона `--avif` у ньому) — це залишається у правилі `image-compress`. Правило `image-avif` самостійне й вмикається лише там, де AVIF підтримується (адмінки), а не у публічних сайтах.
+
+## Експорти / API
+
+| Експорт       | Тип              | Призначення                                                                         |
+| ------------- | ---------------- | ----------------------------------------------------------------------------------- |
+| `check(cwd?)` | `async function` | Точка входу перевірки `image-avif`; повертає exit-код (`0` — OK, `1` — є проблеми). |
+
+Інші функції у модулі (`packageHasAvifDisabled`, `resolveImageCandidates`, `checkVueAvifImportsInPackage`, `checkVueAvifImports`, `hasAnyVueRasterReference`, `runAvifGeneration`, `cleanupOrphanAvifs`) — внутрішні, не експортуються.
+
+## Константи
+
+| Константа                        | Значення / форма                                                            | Призначення                                                                                                                                                                                                                                                                       |
+| -------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MINIFY_PACKAGE_NAME`            | `'@nitra/minify-image'`                                                     | Імʼя CLI-пакета, який генерує AVIF (викликається через `npx`).                                                                                                                                                                                                                    |
+| `PKG_CONFIG_FIELD`               | `'@nitra/minify-image'`                                                     | Поле у `package.json` для конфігу `@nitra/minify-image` (`disable-avif: true` тощо).                                                                                                                                                                                              |
+| `CLEANUP_EXTRA_IGNORE_DIR_NAMES` | `Set` з `'build'`, `'android'`, `'ios'`, `'.output'`, `'.nuxt'`, `'.cache'` | Імена каталогів, які cleanup-пасс ігнорує додатково до стандартних (`node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`, які вже скіпає `walkDir`). Це артефакти збірки / нативних платформ — AVIF всередині є продуктом попереднього `bun run build` / Capacitor sync. |
+| `VUE_RASTER_IMPORT_RE`           | `/import\s+\w[\w$]\*\s+from\s+['"]([^'"\n]+\.(?:png                         | jpe?g                                                                                                                                                                                                                                                                             | gif))['"]/giu`       | Регексп для `import name from '...ext'` у `.vue`/`.html`; група 1 — повний шлях до зображення.                                                                                 |
+| `VUE_RASTER_STATIC_SRC_RE`       | `/(?<![:-_.])\bsrc\s*=\s*['"]([^'"\s]+\.(?:png                              | jpe?g                                                                                                                                                                                                                                                                             | gif))['"]/giu`       | Регексп для статичних `<img src="...png" />` у шаблоні `.vue`. Lookbehind `(?<![:\-_.])` виключає `:src="..."` (реактивний JS-вираз), `data-src="..."` і `obj.src=...`.        |
+| `VUE_AVIF_REF_RE`                | `/['"]([^'"\s]+\.(?:png                                                     | jpe?g                                                                                                                                                                                                                                                                             | gif)\.avif)['"]/giu` | Регексп для готових AVIF-посилань у `.vue`/`.html`. Використовується тільки для збору множини «живих» AVIF — щоб після rewrite знати, які `<...>.avif` ще на щось посилаються. |
+
+## Типи
+
+### `RewriteStats`
+
+```text
+{
+  rewrittenRefs: number   // скільки конкретних посилань переписано на .avif
+  rewrittenFiles: number  // у скількох .vue/.html файлах хоч одне посилання змінилося
+  failedRefs: number      // скільки конкретних посилань не вдалося переписати (.avif не існував)
+}
+```
+
+Аґреговані лічильники по проходу `check image-avif`, мутуються `checkVueAvifImportsInPackage`, потрапляють у фінальний `pass`-меседж.
+
+## Функції
+
+### `packageHasAvifDisabled(pkg)`
+
+- **Сигнатура:** `(pkg: Record<string, unknown>) => boolean`
+- **Параметри:**
+  - `pkg` — розібраний обʼєкт `package.json` пакета.
+- **Повертає:** `true`, якщо у `package.json` встановлено `"@nitra/minify-image": { "disable-avif": true }`, інакше `false`.
+- **Side effects:** немає.
+
+### `resolveImageCandidates(importPath, sourceAbsPath, packageRootAbs)`
+
+- **Сигнатура:** `(importPath: string, sourceAbsPath: string, packageRootAbs: string | null) => string[]`
+- **Параметри:**
+  - `importPath` — шлях з `import x from '...'` або `src="..."`.
+  - `sourceAbsPath` — абсолютний шлях файла-джерела (`.vue`/`.html`).
+  - `packageRootAbs` — абсолютний корінь workspace-пакета, у якому лежить джерело (для резолвера `/path` як `<root>/public<path>`); `null`, якщо невідомо.
+- **Повертає:** впорядкований список абсолютних шляхів-кандидатів, по яких caller перевіряє існування `<candidate>` або `<candidate>.avif`.
+- **Правила резолва:**
+  - `./x.png`, `../x.png` — відносно файла-джерела.
+  - `/x.png` (Vite/Quasar-конвенція) — спочатку `<packageRoot>/public/x.png`, потім `<packageRoot>/x.png`, нарешті `<cwd>/x.png` як legacy fallback.
+  - голий шлях з принаймні одним `/` (наприклад `assets/img.png`) — relative-to-source, плюс `<packageRoot>/public/<path>` як другий кандидат.
+  - bare-шлях без `/` (наприклад `foo`) — ймовірно alias-resolver Vite/Webpack; повертається порожній список → caller просто пропускає посилання, не звітує fail.
+- **Side effects:** немає; шляхи будуються через `path.join`, файли не зачіпаються.
+
+### `checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, ignorePaths, usedAvifAbs, stats, fail, cwd)`
+
+- **Сигнатура:** `async (packageRoot: string, otherRootsAbs: string[], ignorePaths: string[], usedAvifAbs: Set<string>, stats: RewriteStats, fail: (msg: string) => void, cwd: string) => Promise<void>`
+- **Параметри:**
+  - `packageRoot` — відносний шлях до кореня workspace-пакета (`'.'` або `'demo'`, тощо).
+  - `otherRootsAbs` — абсолютні шляхи інших workspace-коренів; їхні піддерева пропускаються, щоб не сканувати один файл двічі.
+  - `ignorePaths` — абсолютні шляхи каталогів, повністю виключених з обходу (зі `.cursorignore` тощо).
+  - `usedAvifAbs` — мутабельна множина абсолютних шляхів `.avif`, що мають хоч одне посилання у `.vue`/`.html`; функція доповнює її.
+  - `stats` — глобальні лічильники `RewriteStats`, мутуються тут.
+  - `fail` — callback для звіту про помилку.
+  - `cwd` — корінь репозиторію.
+- **Повертає:** `Promise<void>`, який резолвиться по завершенню обробки пакета.
+- **Side effects:**
+  - Читає всі `.vue`/`.html` файли пакета через `walkDir`.
+  - Перезаписує файли, у яких хоч одне посилання вдалось переписати (write-then-fail: запис відбувається ОДРАЗУ після обробки одного файла; провал на наступному файлі не відкочує вже записані зміни попередніх).
+  - Мутує `usedAvifAbs` і `stats`.
+  - Викликає `fail(msg)` для кожного raster-посилання, для якого AVIF-двійника немає на диску.
+- **Логіка:**
+  - Збирає `targetFiles` — лише `.vue`/`.html` у `absRoot`, що не належать іншим workspace-кореням.
+  - Для кожного файла застосовує `processMatches` із двома регекспами: `VUE_RASTER_IMPORT_RE` і `VUE_RASTER_STATIC_SRC_RE`. У `replaceAll` для кожного матчу резолвить кандидатів через `resolveImageCandidates`; якщо `existsSync(c + '.avif')` знаходить двійник — переписує посилання на `<importPath>.avif`, інкрементує `rewrittenRefs`, додає до `usedAvifAbs`; якщо ні — інкрементує `failedRefs` і викликає `fail`. Bare-alias (порожній список кандидатів) — пропускається без fail.
+  - Окремо проходить `VUE_AVIF_REF_RE` по оновленому контенту й додає до `usedAvifAbs` усі AVIF-кандидати, які існують на диску (це треба, щоб cleanup-пасс не видалив AVIF, на який є посилання поза rewrite-патернами).
+  - Якщо контент змінився — записує файл і інкрементує `rewrittenFiles`.
+
+### `checkVueAvifImports(ignorePaths, usedAvifAbs, stats, pass, fail, cwd)`
+
+- **Сигнатура:** `async (ignorePaths: string[], usedAvifAbs: Set<string>, stats: RewriteStats, pass: (msg: string) => void, fail: (msg: string) => void, cwd: string) => Promise<string[]>`
+- **Параметри:**
+  - `ignorePaths` — абсолютні шляхи каталогів, повністю виключених з обходу.
+  - `usedAvifAbs` — мутабельна множина абсолютних шляхів `.avif`, що мають живі посилання (заповнюється у викликаних функціях).
+  - `stats` — глобальні лічильники `RewriteStats`, мутуються нижче.
+  - `pass` — callback при успішній перевірці пакета.
+  - `fail` — callback при помилці.
+  - `cwd` — корінь репозиторію.
+- **Повертає:** `Promise<string[]>` — абсолютні шляхи коренів пакетів з активним opt-out (`disable-avif: true`).
+- **Side effects:**
+  - Читає кожен `package.json` workspace-пакета.
+  - Для пакетів з opt-out — викликає `pass` з повідомленням про вимикач і додає корінь до `optedOutAbs`.
+  - Для решти — викликає `checkVueAvifImportsInPackage`, який може писати у файли.
+- **Призначення `optedOutAbs`:** AVIF всередині opt-out пакета НЕ можна вважати сиротою лише на підставі відсутності посилань у його `.vue`/`.html` (ми взагалі не сканували його шаблони) — інакше cleanup помилково затирав би AVIF, що використовуються через alias / runtime-обчислений шлях / зовнішні посилання.
+
+### `hasAnyVueRasterReference(ignorePaths, cwd)`
+
+- **Сигнатура:** `async (ignorePaths: string[], cwd: string) => Promise<boolean>`
+- **Параметри:**
+  - `ignorePaths` — абсолютні шляхи каталогів, виключених з обходу.
+  - `cwd` — корінь репозиторію.
+- **Повертає:** `true`, якщо у `.vue`/`.html` пакетів без opt-out знайдено принаймні одне raster-посилання (`VUE_RASTER_IMPORT_RE` або `VUE_RASTER_STATIC_SRC_RE`); `false` — інакше.
+- **Side effects:** немає (тільки читання файлів).
+- **Призначення:** дешевий pre-scan, що дозволяє пропустити дорогий `npx @nitra/minify-image --avif` і rewrite/cleanup у проєктах, де AVIF не вживається.
+- **Нюанс:** перед кожним `test`/`replaceAll` функція скидає `lastIndex` регекспа на `0`, оскільки регекспи з прапором `g` тримають стан між викликами.
+
+### `runAvifGeneration(cwd)`
+
+- **Сигнатура:** `(cwd: string) => void`
+- **Параметри:**
+  - `cwd` — корінь репозиторію, у якому запускається `npx`.
+- **Повертає:** `void`.
+- **Side effects:**
+  - Викликає `spawnSync(npxPath, ['@nitra/minify-image', '--src=.', '--write', '--avif'], { stdio: 'inherit', cwd, env })`, який генерує AVIF-двійники.
+  - Логує попередження (`console.log`) при відсутності `npx` у PATH, помилці спавна або ненульовому коді виходу — без падіння перевірки.
+- **Best-effort семантика:** якщо мережа/кеш недоступні чи бінарника нема — лог-варн без винятку; перевірка vue/html все одно виявить файли, для яких не вистачає `.avif`.
+- **Опт-аут запуску:** якщо `process.env.NITRA_CURSOR_NO_AVIF_RUN === '1'` — функція no-op (потрібно для тестів та ізольованих середовищ).
+- **Resolver `npx`:** `resolveCmd('npx')` повертає повний шлях; якщо `null` — функція друкує попередження і виходить.
+
+### `cleanupOrphanAvifs(usedAvifAbs, optedOutAbs, ignorePaths, cwd)`
+
+- **Сигнатура:** `async (usedAvifAbs: Set<string>, optedOutAbs: string[], ignorePaths: string[], cwd: string) => Promise<number>`
+- **Параметри:**
+  - `usedAvifAbs` — абсолютні шляхи `.avif`, що мають живі посилання (їх не чіпаємо).
+  - `optedOutAbs` — абсолютні шляхи коренів opt-out пакетів; AVIF під ними не вважаємо сиротами.
+  - `ignorePaths` — абсолютні шляхи каталогів, виключених з обходу.
+  - `cwd` — корінь репозиторію.
+- **Повертає:** `Promise<number>` — кількість видалених сиріт.
+- **Side effects:** видаляє `.avif` файли через `unlink`.
+- **Фільтр кандидатів:**
+  - файл закінчується на `.avif`;
+  - не присутній у `usedAvifAbs`;
+  - не лежить під жодним з `optedOutAbs`;
+  - жоден сегмент шляху не входить у `CLEANUP_EXTRA_IGNORE_DIR_NAMES` (`build`, `android`, `ios`, `.output`, `.nuxt`, `.cache`).
+- **Ідемпотентність:** opt-out гарантує, що повторний `check image-avif` не починає циклічно видаляти AVIF в пакетах, що вимкнули правило (наприклад, мобільний бандл).
+
+### `check(cwd = process.cwd())` — експортована точка входу
+
+- **Сигнатура:** `async (cwd?: string) => Promise<number>`
+- **Параметри:**
+  - `cwd` — корінь репозиторію; за замовчуванням `process.cwd()`.
+- **Повертає:** `Promise<number>` — exit-код (`0` — OK, `1` — є проблеми), отриманий з `reporter.getExitCode()`.
+- **Side effects:**
+  - Створює `createCheckReporter()` для агрегації pass/fail-меседжів.
+  - Завантажує `ignorePaths` через `loadCursorIgnorePaths(cwd)`.
+  - Якщо `hasAnyVueRasterReference` повернула `false` — викликає `pass(...)` з відповідним повідомленням і одразу повертає exit-код (без AVIF-генерації, rewrite, cleanup).
+  - Інакше: викликає `runAvifGeneration(cwd)`, потім `checkVueAvifImports(...)` (rewrite + збір usedAvifAbs + список optedOutAbs), потім `cleanupOrphanAvifs(...)`, фіксує підсумкове `pass(...)` з кількістю переписаних посилань, файлів, видалених сиріт і фейлів. Фейли всередині rewrite-пасу йдуть через `fail(...)` і впливають на exit-код.
+
+## Залежності
+
+### Node.js builtins
+
+- `node:fs` — `existsSync` (синхронна перевірка наявності файла, бо викликається у тісному `replaceAll`-циклі).
+- `node:fs/promises` — `readFile`, `writeFile`, `unlink`.
+- `node:path` — `join`, `relative`.
+- `node:child_process` — `spawnSync` для запуску `npx @nitra/minify-image`.
+- `node:process` — `env` (для опт-ауту `NITRA_CURSOR_NO_AVIF_RUN=1`); також глобально використовується `process.cwd()` у `resolveImageCandidates` і дефолтному параметрі `check`.
+
+### Внутрішні модулі (n-cursor)
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика обʼєкта зі `pass`/`fail`/`getExitCode`.
+- `../../../scripts/lib/load-cursor-config.mjs` → `loadCursorIgnorePaths` — завантажує абсолютні шляхи каталогів, які треба ігнорувати при обході.
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd` — резолвить абсолютний шлях до CLI-бінарника у `PATH`.
+- `../../../scripts/utils/walkDir.mjs` → `walkDir` — рекурсивний обхід директорії з вбудованим скіпом `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next` та користувацьким callback.
+- `../../../scripts/lib/workspaces.mjs` → `getMonorepoPackageRootDirs` — повертає відносні шляхи коренів workspace-пакетів монорепо.
+
+### Зовнішні CLI
+
+- `npx` — резолвиться через `resolveCmd`; запускає `@nitra/minify-image` через `npx`.
+- `@nitra/minify-image` — окремий npm-пакет, який і генерує AVIF-двійники (`--src=. --write --avif`).
+
+## Потік виконання / Використання
+
+### Виклик з CLI
+
+Модуль викликається з реєстру правил `n-cursor` як check-функція правила `image-avif`. Очікувана крапка входу:
+
+```js
+import { check } from './npm/rules/image-avif/js/avif_generation.mjs'
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+### Послідовність кроків у `check(cwd)`
+
+1. Створюється reporter (`createCheckReporter`).
+2. Завантажується `ignorePaths` через `loadCursorIgnorePaths(cwd)`.
+3. **Pre-scan**: `hasAnyVueRasterReference(ignorePaths, cwd)` обходить пакети без opt-out, шукає raster-посилання. Якщо нема — `pass(...)` і ранній вихід.
+4. **AVIF-генерація**: `runAvifGeneration(cwd)` — викликає `npx @nitra/minify-image --src=. --write --avif`, який створює AVIF-двійники. Опціонально вимикається через `NITRA_CURSOR_NO_AVIF_RUN=1`.
+5. **Rewrite-пасс**: `checkVueAvifImports(...)` обходить кожен workspace-пакет:
+   - Якщо `package.json` має `disable-avif: true` — `pass(...)` і додає корінь у `optedOutAbs`.
+   - Інакше — `checkVueAvifImportsInPackage(...)` обробляє кожен `.vue`/`.html` у пакеті: переписує raster-посилання на `.avif` (якщо двійник існує), фейлить ті, для яких двійника нема, збирає `usedAvifAbs`.
+6. **Cleanup-пасс**: `cleanupOrphanAvifs(usedAvifAbs, optedOutAbs, ignorePaths, cwd)` видаляє `.avif`, на які не лишилось живих посилань, з врахуванням opt-out і списку артефактів збірки.
+7. Фінальний `pass(...)` з підсумком: скільки посилань переписано, у скількох файлах, скільки сиріт видалено, скільки фейлів rewrite.
+8. Повертається `reporter.getExitCode()` — `1`, якщо був хоч один `fail`, інакше `0`.
+
+### Опт-аут на рівні пакета
+
+Щоб вимкнути AVIF-перевірку у конкретному workspace-пакеті, у його `package.json` додається:
+
+```json
+{
+  "@nitra/minify-image": {
+    "disable-avif": true
+  }
+}
+```
+
+Наслідки:
+
+- pre-scan ігнорує цей пакет (його raster-посилання не провокують запуск `npx --avif`);
+- rewrite-пасс не сканує і не змінює його `.vue`/`.html`;
+- cleanup-пасс не видаляє `.avif` під його коренем (бо ми не зібрали `usedAvifAbs` для нього).
+
+### Опт-аут запуску `npx`
+
+Змінна середовища `NITRA_CURSOR_NO_AVIF_RUN=1` повністю вимикає виклик `npx @nitra/minify-image --avif`. Pre-scan, rewrite і cleanup при цьому працюють як зазвичай — потрібно для юніт-тестів і ізольованих CI-середовищ.
+
+### Семантика помилок
+
+- **Бракує `.avif`-двійника** — fail на конкретний `.vue`/`.html`-файл і конкретний `importPath` з підказкою про `npx @nitra/cursor fix image-avif` та локальний opt-out.
+- **`npx` недоступний / падає** — лише warn у `console.log`, без переривання перевірки; fail прийде пізніше від rewrite-пасу, якщо `.avif` так і не з'явилися.
+- **Bare alias** (`'foo'` без `/`) — резолвера нема, посилання пропускається без fail.

package/rules/image-compress/docs/fix.md

@@ -0,0 +1,150 @@
+# fix.mjs — entry-point правила `image-compress`
+
+## Огляд
+
+Файл `npm/rules/image-compress/fix.mjs` — це уніфікована точка входу (entry-point) для правила `image-compress` із набору правил `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор `@nitra/cursor` (через динамічний `import` модуля та виклик `run(ctx)`) разом з іншими правилами в межах одного загального прогону (з конфіг-завантаженням, whitelist та підсумковим звітом).
+2. **Standalone mode** — якщо файл запущено напряму через `bun rules/image-compress/fix.mjs` (тобто є точкою входу процесу), він самостійно піднімає повний CLI-оркестратор для цього єдиного правила і завершує процес кодом виходу, придатним для CI/IDE.
+
+Уся логіка правила (виявлення `applies`, перевірка JS-concerns, policy, валідація mdc-refs) делегується у `runStandardRule` зі спільної бібліотеки `scripts/lib/run-standard-rule.mjs`. Тобто сам `fix.mjs` правила `image-compress` не містить власної бізнес-логіки — він лише прив’язує спільний “стандартний” пайплайн правил до конкретної директорії цього правила через `import.meta.dirname`.
+
+Правило `image-compress` належить до родини стандартних правил `@nitra/cursor`, де кожне правило живе у власній теці `npm/rules/<id>/` і має однаковий каркас: `fix.mjs` (цей файл), `check-*.mjs` (детектори порушень), `*.mdc` (людинозрозумілий опис правила) та інші артефакти, які `runStandardRule` автоматично знаходить за домовленостями про шляхи.
+
+## Експорти / API
+
+Модуль має один іменований експорт.
+
+### `run(ctx?) → Promise<number>`
+
+Function, що повертає `Promise<number>` — exit-code прогону правила:
+
+- `0` — правило відпрацювало без порушень (OK).
+- `1` — знайдено порушення політики/перевірок правила.
+
+Параметри:
+
+- `ctx` (необов’язковий) — об’єкт `RuleContext` з `scripts/lib/run-standard-rule.mjs`. Використовується для спільного стану між правилами в межах одного прогону, зокрема для кешу обходу файлової системи (`walkCache`) та інших оркестраційних метаданих. Якщо не передано — `runStandardRule` сам ініціалізує внутрішній контекст.
+
+Призначення: викликається CLI-оркестратором `@nitra/cursor` як library API. Зовнішній код виконує `import { run } from '<абсолютний шлях>/npm/rules/image-compress/fix.mjs'` і потім `await run(ctx)`. Це дозволяє запускати багато правил в одному процесі з єдиним конфіг-завантаженням і єдиним звітом.
+
+Модуль не має `export default`, не експортує жодних інших символів, констант чи типів.
+
+## Функції
+
+### `run(ctx)`
+
+**Сигнатура:**
+
+```js
+export function run(ctx)
+```
+
+**JSDoc-тип (як у вихідному файлі):**
+
+- `@param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx]` — контекст прогону (наприклад, `walkCache`); параметр опціональний.
+- `@returns {Promise<number>}` — `0` означає OK, `1` — порушення.
+
+**Параметри:**
+
+- `ctx?: RuleContext` — необов’язковий контекст із зовнішнього оркестратора; пробрасується далі без модифікації.
+
+**Що робить:**
+
+1. Звертається до `import.meta.dirname` — це абсолютний шлях до директорії, у якій лежить сам `fix.mjs` (тобто до `npm/rules/image-compress/`).
+2. Викликає `runStandardRule(import.meta.dirname, ctx)` — стандартну реалізацію пайплайну правила: applies → JS-concerns → policy → mdc-refs.
+3. Повертає `Promise<number>`, який вирішить exit-code від `runStandardRule`.
+
+**Повертає:** `Promise<number>` — exit-code пайплайна (`0` або `1`).
+
+**Side effects:** прямих сайд-ефектів у самій функції немає; усі сайд-ефекти (читання файлів проєкту, виведення в `stdout`/`stderr`, формування підсумків звіту тощо) інкапсульовані всередині `runStandardRule`. Сама `run` лише делегує виклик.
+
+### Standalone-блок (не функція, а top-level код)
+
+**Сигнатура:**
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+**Що робить:**
+
+1. `isRunAsCli(import.meta.url)` повертає `true`, якщо поточний модуль завантажено як точку входу процесу (а не як імпортовану бібліотеку). Це стандартний для Node/Bun спосіб розпізнати, що файл стартував напряму.
+2. Якщо так — викликає `runRuleCli(import.meta.dirname)`, який реалізує повний CLI-оркестратор саме для цього правила: завантаження конфігу, обчислення whitelist, виконання правила, друк підсумків. Він повертає `Promise<number>` — exit-code.
+3. `await` чекає виконання promise. Це — top-level `await`, що дозволено в ES-модулях.
+4. `process.exit(<code>)` передає отриманий exit-code операційній системі / CI / IDE. ESLint-правила `n/no-process-exit` і `unicorn/no-process-exit` тут свідомо вимкнено коментарем, оскільки standalone entry-point правомірно завершує процес явним кодом.
+
+**Параметри / повертає:** немає (це side-effect блок верхнього рівня модуля).
+
+**Side effects:**
+
+- Якщо файл імпортовано як бібліотеку — гілка не виконується, бо `isRunAsCli` поверне `false`.
+- Якщо файл запущено напряму — повний CLI-оркестратор виконує власні I/O (читання конфігу, обхід проєкту, друк звіту) і потім завершує процес через `process.exit`.
+
+## Залежності
+
+### Внутрішні модулі проєкту
+
+- `../../scripts/lib/run-rule-cli.mjs` — постачає:
+  - `isRunAsCli(metaUrl)` — детектор, чи модуль є entry-point процесу (за `import.meta.url`).
+  - `runRuleCli(ruleDirname)` — standalone CLI-оркестратор для одного правила: конфіг + whitelist + summary + exit-code. Аналогічний за поведінкою до `npx @nitra/cursor fix <id>`.
+- `../../scripts/lib/run-standard-rule.mjs` — постачає:
+  - `runStandardRule(ruleDirname, ctx?)` — стандартний пайплайн правила: applies → JS-concerns → policy → mdc-refs.
+  - Тип `RuleContext` (через JSDoc-`import('...')`), який описує спільний контекст прогону (зокрема `walkCache`).
+
+Шляхи відносні: `../../scripts/lib/...` з директорії `npm/rules/image-compress/` веде до `npm/scripts/lib/...`.
+
+### Платформенні API
+
+- `import.meta.dirname` — стандартна властивість ES-модулів у сучасних рантаймах (Node.js та Bun), містить абсолютну директорію поточного модуля.
+- `import.meta.url` — стандартна властивість ES-модулів; URL-форма шляху поточного модуля; використовується для розпізнавання запуску як CLI.
+- `process.exit(code)` — глобальний Node/Bun API завершення процесу з кодом виходу.
+- Top-level `await` — підтримується в ESM.
+
+### Зовнішні npm-пакети
+
+Прямих імпортів зовнішніх npm-пакетів у файлі немає. Уся залежність на зовнішнє API проходить транзитивно через `run-rule-cli.mjs` та `run-standard-rule.mjs`.
+
+### ESLint-директиви
+
+У файлі присутній один inline-disable: `n/no-process-exit, unicorn/no-process-exit` навколо `process.exit(...)`. Він локалізований лише до одного рядка і обґрунтований у коментарі: standalone entry-point має повертати exit-code для CI/IDE.
+
+## Потік виконання / Використання
+
+### Сценарій A: library-режим (через CLI `@nitra/cursor`)
+
+1. CLI `@nitra/cursor` (наприклад, `npx @nitra/cursor fix` без аргументу-id) збирає список правил, серед яких є `image-compress`.
+2. Оркестратор робить `import` модуля `npm/rules/image-compress/fix.mjs` і отримує іменований експорт `run`.
+3. Викликає `await run(ctx)`, передаючи спільний `RuleContext` (з `walkCache` тощо).
+4. `run` делегує виконання в `runStandardRule(import.meta.dirname, ctx)`, який виконує стандартний пайплайн правила (applies → JS-concerns → policy → mdc-refs) для теки `npm/rules/image-compress/`.
+5. `run` повертає `Promise<number>`; оркестратор агрегує exit-коди всіх правил у загальний підсумок.
+
+У цьому сценарії гілка `if (isRunAsCli(...))` НЕ виконується — `process.exit` не викликається, оскільки модуль завантажено як бібліотеку, а не як entry-point процесу.
+
+### Сценарій B: standalone-режим (`bun rules/image-compress/fix.mjs`)
+
+1. Користувач/CI запускає файл напряму: `bun rules/image-compress/fix.mjs` (або еквівалентна команда рантайму).
+2. Виконується top-level код модуля, у тому числі гілка `if (isRunAsCli(import.meta.url))`.
+3. Оскільки модуль — entry-point процесу, `isRunAsCli` повертає `true`.
+4. Викликається `await runRuleCli(import.meta.dirname)`, який повністю відтворює оркестрацію `@nitra/cursor fix <id>` для саме цього правила: завантажує конфіг, обчислює whitelist, прогонить правило, друкує summary, повертає exit-code.
+5. `process.exit(<code>)` завершує процес із цим кодом — придатним для CI-пайплайнів та IDE-інтеграцій.
+
+Експорт `run` у цьому сценарії існує, але не викликається з самого файлу — він залишається доступним для зовнішніх імпортів.
+
+### Як файл вписаний у репозиторій
+
+- Тека `npm/rules/image-compress/` — це “контейнер” правила: разом із `fix.mjs` тут (за конвенцією родини стандартних правил) лежать `check-*.mjs` детектори, `.mdc`-опис та інші артефакти, які `runStandardRule` зчитує за відомими шаблонами імен.
+- Усі стандартні правила пакета `@nitra/cursor` мають однаковий каркас `fix.mjs` із цим самим патерном (експорт `run` + standalone-блок). Тобто цей файл — фактично шаблонний адаптер між конкретним правилом і спільною бібліотекою прогону.
+
+### Rebuild Test (відтворюваність документації)
+
+За цією документацією без перегляду початкового коду можна відновити поведінку файлу:
+
+- Експортує лише функцію `run(ctx?)` з делегуванням у `runStandardRule(import.meta.dirname, ctx)` і поверненням `Promise<number>` (`0|1`).
+- Standalone-гілка: `if (isRunAsCli(import.meta.url)) process.exit(await runRuleCli(import.meta.dirname))` — з inline-disable для `n/no-process-exit, unicorn/no-process-exit`.
+- Імпортує `isRunAsCli` та `runRuleCli` зі `../../scripts/lib/run-rule-cli.mjs`, і `runStandardRule` зі `../../scripts/lib/run-standard-rule.mjs`.
+- Жодних інших експортів, констант чи побічних дій верхнього рівня.
+
+Цього достатньо, щоб точно відтворити структуру та контракт оригінального файлу.

package/rules/image-compress/js/docs/package_setup.md

@@ -0,0 +1,191 @@
+# `package_setup.mjs` — перевірка вимог правила `image-compress.mdc`
+
+## Огляд
+
+Модуль `package_setup.mjs` реалізує `check`-функцію для правила `image-compress.mdc`. Правило вимагає, щоб у проєкті була налаштована оптимізація raster/SVG-зображень через CLI `@nitra/minify-image` ≥ 3.2.0 (запускається локально через `npx`).
+
+У цьому файлі лишилися лише **FS / cross-file**-перевірки, які важко або незручно виразити декларативно у Rego:
+
+- наявність `package.json` у корені репозиторію;
+- `.n-minify-image.tsv` (committed source of truth split-cache 3.2.0 з полями sha1 / originalSize / size) **не** перебуває у `.gitignore` — файл має жити в git;
+- застарілий `.minify-image-cache.tsv` (4-колонковий кеш з `@nitra/minify-image` < 3.2) видалений як з диска, так і з `.gitignore`.
+
+Структурні вимоги до `package.json` (наявність `scripts.lint-image` з правильним викликом `npx @nitra/minify-image --src=. --write` без `--avif`, включення `bun run lint-image` в агрегований `lint`, відсутність `@nitra/minify-image` у `dependencies`/`devDependencies`) перевіряються Rego-політикою у `npm/rules/image-compress/policy/package_json/` і автофіксяться через `npx @nitra/cursor fix`.
+
+CI-workflow для image-лінту правилом **не** вимагається — оптимізація відбувається лише локально перед комітом.
+
+## Експорти / API
+
+| Експорт       | Тип              | Призначення                                                                                                                                           |
+| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check(cwd?)` | `async function` | Публічна точка входу. Виконує перевірки правила `image-compress.mdc` для вказаного робочого каталогу й повертає exit-код (`0` — OK, `1` — є помилки). |
+
+Модуль використовує ES Modules (`.mjs`), іменований експорт `check`. Default-експорту немає.
+
+## Функції
+
+### `readGitignoreLines(cwd)`
+
+Приватна допоміжна функція для читання змістовних рядків `.gitignore`.
+
+- **Сигнатура:** `async function readGitignoreLines(cwd: string): Promise<string[] | null>`
+- **Параметри:**
+  - `cwd` — абсолютний шлях до кореня репозиторію, де очікується `.gitignore`.
+- **Повертає:**
+  - `null`, якщо файл `.gitignore` відсутній;
+  - масив рядків (`string[]`), кожен з яких уже `trim`-нутий, не порожній і не починається з `#`.
+- **Side effects:** один синхронний `existsSync` і один асинхронний `readFile` (UTF-8) у файловій системі. Не пише нічого.
+- **Поведінкові деталі:** коментарі визначаються лише за префіксом `#` на початку trim-нутого рядка; in-line коментарі (після `#` всередині рядка) не вирізаються.
+
+### `checkHashCacheNotIgnored(pass, fail, cwd)`
+
+Перевіряє, що файл `.n-minify-image.tsv` **не** перерахований у `.gitignore`. Файл є закомічуваним source of truth для split-cache 3.2.0 (зберігає sha1 + originalSize + size для slow-path і метрики lifetime savings), тому має потрапляти в git.
+
+- **Сигнатура:** `async function checkHashCacheNotIgnored(pass: (msg: string) => void, fail: (msg: string) => void, cwd: string): Promise<void>`
+- **Параметри:**
+  - `pass` — callback, що викликається при успіху з людиночитаним повідомленням;
+  - `fail` — callback, що викликається при провалі з повідомленням і вказівкою на дію;
+  - `cwd` — корінь репозиторію.
+- **Повертає:** `Promise<void>`. Реєстрація результату здійснюється через `pass`/`fail` (зовнішній reporter).
+- **Side effects:** одне читання `.gitignore` через `readGitignoreLines`.
+- **Логіка:**
+  - якщо `.gitignore` є й містить точний рядок `.n-minify-image.tsv` → `fail` з вимогою прибрати рядок;
+  - інакше (файл відсутній або рядка немає) → `pass`.
+- **Важливо:** сам факт існування `.n-minify-image.tsv` не вимагається. На новому проєкті без обробки зображень файла ще немає — і це нормально.
+
+### `checkLegacyCacheRemoved(pass, fail, cwd)`
+
+Перевіряє, що застарілий 4-колонковий кеш `.minify-image-cache.tsv` (з `@nitra/minify-image` < 3.2) повністю видалений з проєкту.
+
+- **Сигнатура:** `async function checkLegacyCacheRemoved(pass: (msg: string) => void, fail: (msg: string) => void, cwd: string): Promise<void>`
+- **Параметри:**
+  - `pass` — callback для успішного звіту;
+  - `fail` — callback для помилки;
+  - `cwd` — корінь репозиторію.
+- **Повертає:** `Promise<void>`.
+- **Side effects:** один `existsSync` на файл у корені; за умови, що файла нема, додатково читає `.gitignore`.
+- **Логіка (виконується послідовно з `early return`):**
+  1. Якщо `<cwd>/.minify-image-cache.tsv` **існує на диску** → `fail` з готовим bash-snippet для повного видалення (`git rm --cached … && rm -f …`) і нагадуванням прибрати рядок з `.gitignore`. Подальші перевірки в цій функції пропускаються.
+  2. Інакше читає `.gitignore`; якщо там є точний рядок `.minify-image-cache.tsv` → `fail` з вимогою прибрати застарілий ігнор.
+  3. Інакше → `pass` («міграція на split-cache завершена»).
+
+### `check(cwd?)`
+
+Експортована публічна функція — точка входу для агрегатора правил `@nitra/cursor`.
+
+- **Сигнатура:** `export async function check(cwd: string = process.cwd()): Promise<number>`
+- **Параметри:**
+  - `cwd` — необов’язковий шлях до кореня репозиторію; за замовчуванням `process.cwd()`.
+- **Повертає:** exit-код як `number` (`0` — все ок; `1` — є хоча б один `fail`). Значення формує `reporter.getExitCode()` з `createCheckReporter`.
+- **Side effects:**
+  - друк звіту в stdout/stderr через reporter (формат залежить від `createCheckReporter`);
+  - читання файлів `package.json`, `.gitignore`, `.minify-image-cache.tsv` у `cwd`. Жодного запису на диск.
+- **Поведінкові деталі:**
+  1. Створює локальний `reporter` через `createCheckReporter()` і дістає з нього `pass`/`fail`.
+  2. **Guard:** якщо в корені нема `package.json` — друкує `fail` із підказкою додати файл і **негайно повертає** `reporter.getExitCode()` (≈ `1`). Інші перевірки в цій ітерації не виконуються.
+  3. Якщо `package.json` є — `pass` з нагадуванням, що структуру `scripts` перевіряє Rego через `npx @nitra/cursor fix → image_compress.package_json`.
+  4. Виконує `checkHashCacheNotIgnored` (await).
+  5. Виконує `checkLegacyCacheRemoved` (await).
+  6. Повертає `reporter.getExitCode()`.
+
+## Залежності
+
+### Зовнішні (Node.js core)
+
+- `node:fs`
+  - `existsSync` — синхронна перевірка існування `package.json`, `.gitignore`, застарілого кешу;
+- `node:fs/promises`
+  - `readFile` — асинхронне читання `.gitignore` у кодуванні UTF-8;
+- `node:path`
+  - `join` — кросплатформена побудова шляхів від кореня репозиторію.
+
+### Внутрішні
+
+- `../../../scripts/lib/check-reporter.mjs`
+  - `createCheckReporter()` — створює об’єкт із методами `pass(msg)`, `fail(msg)` і `getExitCode()`. Інкапсулює формат друку результатів і агрегацію статусу.
+
+### Файли проєкту, з якими взаємодіє
+
+- `<cwd>/package.json` — лише перевірка існування;
+- `<cwd>/.gitignore` — читання й пошук рядків `.n-minify-image.tsv`, `.minify-image-cache.tsv`;
+- `<cwd>/.minify-image-cache.tsv` — лише перевірка існування (legacy-файл, який має бути відсутній);
+- `<cwd>/.n-minify-image.tsv` — **не** перевіряється напряму на диску, лише на присутність у `.gitignore`.
+
+### Зовнішня політика
+
+- `npm/rules/image-compress/policy/package_json/` — Rego-правила, які перевіряють і автофіксять структуру `package.json` (script `lint-image`, агрегований `lint`, відсутність залежності `@nitra/minify-image`).
+
+## Потік виконання / Використання
+
+### Як викликається
+
+`check(cwd)` запускається оркестратором `@nitra/cursor` як одна з перевірок правила `image-compress.mdc`. У типовому сценарії команда `npx @nitra/cursor check` або `npx @nitra/cursor fix` обходить активні правила, для кожного імпортує його `check` і збирає звіт.
+
+Можливий також прямий ESM-імпорт:
+
+```js
+import { check } from '@nitra/cursor/npm/rules/image-compress/js/package_setup.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+### Послідовність кроків усередині `check`
+
+1. Створюється `reporter`, з нього дістаються `pass`/`fail`.
+2. Перевірка наявності `package.json` (guard з early return при відсутності).
+3. `await checkHashCacheNotIgnored(pass, fail, cwd)` — гарантує, що split-cache не виключений із git.
+4. `await checkLegacyCacheRemoved(pass, fail, cwd)` — гарантує, що legacy-кеш не висить ні на диску, ні в `.gitignore`.
+5. Повертається `reporter.getExitCode()`.
+
+### Типові сценарії результату
+
+- **Свіжий проєкт без зображень.** `package.json` є, `.gitignore` не містить ні `.n-minify-image.tsv`, ні `.minify-image-cache.tsv`, файлів на диску немає → три `pass`, exit-код `0`.
+- **Проєкт з обробленими зображеннями (3.2+).** На диску є закомічений `.n-minify-image.tsv`, у `.gitignore` його немає, legacy-файла немає → exit-код `0`.
+- **Незавершена міграція з 3.1 → 3.2.** На диску ще лежить `.minify-image-cache.tsv` → `fail` з готовим bash-snippet для очищення; exit-код `1`.
+- **Помилково додано split-cache в `.gitignore`.** `.gitignore` містить `.n-minify-image.tsv` → `fail` з вимогою прибрати рядок; exit-код `1`.
+- **Немає `package.json`.** Перша ж перевірка повертає `fail` і виконання обривається на guard-у; жодних інших перевірок не запускається; exit-код `1`.
+
+### Розподіл відповідальності з Rego
+
+| Перевірка                                                   | Де реалізована                |
+| ----------------------------------------------------------- | ----------------------------- |
+| Наявність `package.json`                                    | `package_setup.mjs`           |
+| `.n-minify-image.tsv` не в `.gitignore`                     | `package_setup.mjs`           |
+| `.minify-image-cache.tsv` відсутній (диск + `.gitignore`)   | `package_setup.mjs`           |
+| `scripts.lint-image` коректний (без `--avif`)               | Rego (`policy/package_json/`) |
+| `bun run lint-image` в агрегованому `lint`                  | Rego (`policy/package_json/`) |
+| `@nitra/minify-image` не в `dependencies`/`devDependencies` | Rego (`policy/package_json/`) |
+
+## Rebuild Test
+
+Якщо файл `package_setup.mjs` втрачено, відтворіть його за такою специфікацією:
+
+1. **Розташування:** `npm/rules/image-compress/js/package_setup.mjs` (ESM, розширення `.mjs`).
+2. **Імпорти:**
+   - `existsSync` з `node:fs`;
+   - `readFile` з `node:fs/promises`;
+   - `join` з `node:path`;
+   - `createCheckReporter` з `../../../scripts/lib/check-reporter.mjs`.
+3. **Константи модульного рівня:**
+   - `HASH_CACHE_FILENAME = '.n-minify-image.tsv'`;
+   - `LEGACY_CACHE_FILENAME = '.minify-image-cache.tsv'`.
+4. **Приватна `readGitignoreLines(cwd)`:** будує шлях `<cwd>/.gitignore`; якщо файла нема — `return null`; інакше читає UTF-8, розбиває по `\n`, `trim` кожного рядка, фільтрує порожні й ті, що починаються з `#`; повертає масив.
+5. **Приватна `checkHashCacheNotIgnored(pass, fail, cwd)`:** читає рядки `.gitignore`; якщо вони є й містять `HASH_CACHE_FILENAME` — `fail` (з підказкою прибрати рядок), інакше `pass` («не в .gitignore — має бути в git»).
+6. **Приватна `checkLegacyCacheRemoved(pass, fail, cwd)`:**
+   - якщо `<cwd>/<LEGACY_CACHE_FILENAME>` існує на диску — `fail` з готовим bash-snippet (`git rm --cached … 2>/dev/null || true && rm -f …`) і нагадуванням про `.gitignore`, потім `return`;
+   - інакше читає `.gitignore`; якщо містить `LEGACY_CACHE_FILENAME` — `fail` (прибрати застарілий ігнор), потім `return`;
+   - інакше `pass` («міграція на split-cache завершена»).
+7. **Експортована `check(cwd = process.cwd())`:**
+   - `const reporter = createCheckReporter()`; деструктурує `{ pass, fail }`;
+   - якщо `<cwd>/package.json` не існує — `fail` («додай — image-compress.mdc») і одразу `return reporter.getExitCode()`;
+   - інакше `pass` («package.json є; структуру перевіряє npx @nitra/cursor fix → image_compress.package_json»);
+   - `await checkHashCacheNotIgnored(pass, fail, cwd)`;
+   - `await checkLegacyCacheRemoved(pass, fail, cwd)`;
+   - `return reporter.getExitCode()`.
+8. **Інваріанти:**
+   - модуль не пише на диск нічого;
+   - `pass`/`fail` приймають лише `string` і викликаються рівно один раз на гілку логіки;
+   - функція `check` завжди повертає `number`, навіть на guard-шляху;
+   - усі шляхи будуються через `join(cwd, ...)`, ніяких рядкових конкатенацій.
+9. **Текст повідомлень** містить посилання на правило `image-compress.mdc` і термін `split-cache 3.2.0`, щоб користувач у звіті бачив джерело вимоги.