@nitra/cursor 5.3.4 → 6.0.0

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

@@ -1,141 +1,30 @@
 ---
 docgen:
   source: npm/rules/image-avif/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# `fix.mjs` — entry-point правила `image-avif`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/image-avif/fix.mjs` — це **подвійний entry-point** одного з правил пакета `@nitra/cursor`. Він входить до інфраструктури «standard rules», де кожне правило живе в окремій теці (`npm/rules/<id>/`) і складається з:
+Обробляє JS-занепокоєні до політики для MDC-референсів на основі наданого контексту прогону та повертає результат
 
-- `fix.mjs` — тонкий wrapper-orchestrator (цей файл);
-- `meta.json` — метадані (наприклад, `auto`-залежності, тут `{"auto": ["vue", "image-compress"]}`);
-- `<id>.mdc` — людино-зрозумілий опис правила для Cursor;
-- підтек `js/` (concerns на рівні JS-AST/тексту) і `policy/` (rego-policy).
+## Поведінка
 
-Конкретно цей файл виконує дві ролі:
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних до політики до MDC-референсів.
+    *   Повертає результат.
 
-1. **Library-режим.** Експортує функцію `run(ctx)`, яку CLI-orchestrator вищого рівня (`@nitra/cursor fix`) імпортує й викликає для прогону правила в межах загального пайплайну (з кешем walk-обходу й спільним підсумком).
-2. **Standalone-режим.** Якщо файл запущено напряму (`bun npm/rules/image-avif/fix.mjs` або еквівалент), він самостійно піднімає повний CLI-цикл (`runRuleCli`) — з підвантаженням конфігурації, whitelist та виведенням підсумку — і завершує процес кодом 0/1.
+## Публічний API
 
-Сам файл **не містить** логіки перевірки контенту: уся робота делегується в `runStandardRule`, який послідовно проганяє чотири фази правила — `applies → JS-concerns → policy → mdc-refs`.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-## Експорти / API
+## Гарантії поведінки
 
-| Експорт | Тип                                               | Призначення                                                                                                                                     |
-| ------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function (ctx?: RuleContext) => Promise<number>` | Library-точка входу правила. Викликається CLI-orchestratorом для запуску правила `image-avif`. Повертає exit-код (`0` — OK, `1` — є порушення). |
-
-Інших іменованих чи default-експортів файл не має.
-
-Окрім експорту, у файлі є **top-level side-effect**: блок `if (isRunAsCli(import.meta.url)) { … process.exit(await runRuleCli(...)) }`. Він спрацьовує **лише** коли цей `.mjs` запущено як CLI-entry (а не імпортовано як модуль), і завершує процес кодом, який повернув `runRuleCli`.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`.
-- **Параметри:**
-  - `ctx` — необов'язковий контекст прогону (`RuleContext`), імпортується з `../../scripts/lib/run-standard-rule.mjs`. У документації самого файла зазначено, що в `ctx` передається, наприклад, `walkCache` — спільний кеш обходу файлової системи, щоб не повторювати walk між правилами в межах одного CLI-прогону. Якщо `ctx` не передано, `runStandardRule` сам ініціалізує необхідне.
-- **Повертає:** `Promise<number>` — числовий exit-код:
-  - `0` — правило виконано без порушень;
-  - `1` — знайдені порушення (несумісність із `image-avif`).
-- **Що робить усередині:** єдиним викликом делегує всю роботу в `runStandardRule(dir, ctx)`. Перший аргумент — `import.meta.dirname`, тобто **абсолютний шлях до теки `npm/rules/image-avif/`** на диску. Саме цей шлях `runStandardRule` використовує, щоб знайти сусідні `meta.json`, теку `js/` (JS-concerns) та теку `policy/` (rego-policy) і прогнати їх по конвеєру.
-- **Side effects:** прямих side-effects сама функція не виконує. Усі ефекти (читання файлів, виклик `opa`, форматування звіту) інкапсульовано в `runStandardRule`. Функція асинхронна (повертає `Promise`), бо `runStandardRule` повертає `Promise`.
-
-### Top-level CLI-блок (не функція, але важливий side-effect)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Умова входу:** `isRunAsCli(import.meta.url)` повертає `true`, лише якщо файл стартовано напряму як скрипт (Node.js/Bun), а не імпортовано як модуль. Це класичний `__main__`-патерн для ESM.
-- **Що робить:** викликає `runRuleCli(import.meta.dirname)` — повноцінний CLI-обгортувач, який, на відміну від `runStandardRule`, додатково підтягує конфігурацію проєкту, застосовує whitelist і друкує summary (як коментар у файлі: «повний еквівалент `npx @nitra/cursor fix <id>`»). Результатом є `Promise<number>` із exit-кодом.
-- **Завершення:** `process.exit(...)` примусово завершує процес із отриманим exit-кодом. Це навмисно — для CI/IDE інтеграцій, які зчитують exit-код. Через це поряд стоять директиви `eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` із поясненням («standalone entry-point має повертати exit-code для CI/IDE»).
-- **`await` на top-level:** доступний завдяки тому, що файл є ESM-модулем (`.mjs`) і виконується в середовищі з підтримкою top-level await (Node.js ≥ 14.8 / Bun).
-
-## Залежності
-
-### Імпорти з сусідніх модулів пакета
-
-| Імпорт            | Звідки                                    | Призначення                                                                                                                                                          |
-| ----------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: чи поточний модуль виконано напряму як CLI (порівнює `import.meta.url` зі скриптом, який стартував процес).                                                |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Standalone CLI-обгортка: завантажує конфігурацію, формує whitelist, прогоняє правило (через той самий `runStandardRule` усередині) і повертає exit-код.              |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний пайплайн правила: послідовно виконує фази **applies → JS-concerns → policy → mdc-refs**, базуючись на структурі теки правила (передано через `dirname`). |
-
-Шляхи відносні: `../../scripts/lib/...` означає `npm/scripts/lib/...` (з огляду на розташування файла в `npm/rules/image-avif/`).
-
-### JSDoc-залежності типів
-
-У JSDoc вказано тип `import('../../scripts/lib/run-standard-rule.mjs').RuleContext` для параметра `ctx`. Це **type-only** імпорт: на runtime він не існує, лише підказує IDE/типчекеру форму об'єкта контексту.
-
-### Сусідні артефакти правила (не імпортуються тут, але необхідні `runStandardRule`)
-
-- `npm/rules/image-avif/meta.json` — `{ "auto": ["vue", "image-compress"] }`. Поле `auto` декларує, які інші правила автоматично «тягнуться» разом із `image-avif`.
-- `npm/rules/image-avif/js/` — каталог JS-concerns (тек з функціями перевірки/трансформації).
-- `npm/rules/image-avif/policy/` — каталог rego-policy для фази `policy`.
-- `npm/rules/image-avif/image-avif.mdc` — людинозрозумілий опис правила (для Cursor) — використовується у фазі `mdc-refs`.
-
-### Зовнішні залежності
-
-Прямих імпортів зовнішніх npm-пакетів у файлі немає. Усі залежності — внутрішні до пакета `@nitra/cursor`.
-
-## Потік виконання / Використання
-
-### Сценарій 1. Library-режим (через CLI-orchestrator)
-
-Коли користувач запускає `npx @nitra/cursor fix` (або відповідну скіл-команду на кшталт `/n-fix`), верхньорівневий orchestrator:
-
-1. Обходить теку `npm/rules/`, знаходить правило `image-avif`.
-2. Динамічно імпортує `npm/rules/image-avif/fix.mjs` як ESM-модуль. У цей момент top-level `if (isRunAsCli(...))` повертає `false` (файл не запущено напряму), тож `process.exit` **не** викликається.
-3. Викликає `run(ctx)`, передаючи спільний контекст (наприклад, із заздалегідь побудованим `walkCache`).
-4. Усередині `run` делегує в `runStandardRule(import.meta.dirname, ctx)`, який послідовно проходить чотири фази:
-   - **applies** — визначає, до яких файлів проєкту правило взагалі застосовне;
-   - **JS-concerns** — запускає функції з теки `js/` для AST/текстових перевірок;
-   - **policy** — викликає `opa` з rego-файлами з `policy/`;
-   - **mdc-refs** — звіряє посилання у `.mdc`.
-5. Отримує `0`/`1`, передає назад orchestratorу, який агрегує результати всіх правил у спільний summary.
-
-### Сценарій 2. Standalone-режим (для дебагу/CI)
-
-Користувач (або IDE/CI) запускає файл напряму:
-
-```bash
-bun npm/rules/image-avif/fix.mjs
-```
-
-1. Бунт/Node стартує файл як ESM-скрипт. Виконуються імпорти.
-2. Експорт `run` зареєстровано, але **не викликається** — поза CLI-orchestratorом нікому його смикати.
-3. Виконується top-level `if`: `isRunAsCli(import.meta.url)` повертає `true`.
-4. Викликається `await runRuleCli(import.meta.dirname)` — повний еквівалент `npx @nitra/cursor fix image-avif`: завантаження конфігурації проєкту, whitelist, прогін правила (через той самий `runStandardRule` усередині `runRuleCli`), друк summary.
-5. `process.exit(<exitCode>)` завершує процес із кодом, який бачить CI/IDE.
-
-### Дизайн-патерн: dual-role entry-point
-
-У коментарі автор файла прямо називає цей патерн: «Дві ролі fix.mjs: library (run) + standalone (main)». Це повторюваний патерн для всіх правил пакета — кожне правило має свій `fix.mjs` із такою ж двоїстою структурою. Завдяки цьому:
-
-- CLI-orchestrator може **переюзати** ту саму функцію `run`, не дублюючи виклик `process.exit`;
-- розробник може **локально дебажити** одне правило, запустивши його `fix.mjs` напряму;
-- логіка пайплайну живе в одному місці (`runStandardRule`), а entry-point залишається тонким.
-
-### Що цей файл **не** робить
-
-- Не визначає, **які саме** файли проєкту порушують `image-avif` — це робить тека `js/` і `policy/`.
-- Не парсить аргументи CLI — це робить `runRuleCli`.
-- Не пише в stdout/stderr напряму — увесь вивід формує `runStandardRule`/`runRuleCli`.
-- Не модифікує файли проєкту — назва `fix` тут історична (контракт стандартного правила); фактична семантика — це check + (потенційно) auto-fix усередині concerns, але сам `fix.mjs` лише оркеструє.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,150 +1,29 @@
-# fix.mjs — entry-point правила `image-compress`
+---
+docgen:
+  source: npm/rules/image-compress/fix.mjs
+  crc: 38cf876b
+  score: 100
+---
 
-## Огляд
-
-Файл `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`).
+# fix.mjs
 
-**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-блок). Тобто цей файл — фактично шаблонний адаптер між конкретним правилом і спільною бібліотекою прогону.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Повертає результат прогону.
 
-### Rebuild Test (відтворюваність документації)
+## Публічний API
 
-За цією документацією без перегляду початкового коду можна відновити поведінку файлу:
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-- Експортує лише функцію `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`.
-- Жодних інших експортів, констант чи побічних дій верхнього рівня.
+## Гарантії поведінки
 
-Цього достатньо, щоб точно відтворити структуру та контракт оригінального файлу.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,191 +1,31 @@
-# `package_setup.mjs` — перевірка вимог правила `image-compress.mdc`
+---
+docgen:
+  source: npm/rules/image-compress/js/package_setup.mjs
+  crc: 13f6d8f3
+  score: 95
+---
 
-## Огляд
-
-Модуль `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?)`
+# package_setup.mjs
 
-Експортована публічна функція — точка входу для агрегатора правил `@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()`.
+## Огляд
 
-### Типові сценарії результату
+Файл виконує перевірку наявності та видалення кешу. Він зчитує рядки з `.gitignore`, перевіряє наявність кешу `HASH_CACHE_FILENAME` та видаляє застарілий кеш `LEGACY_CACHE_FILENAME`. Код перевіряє відповідність правилу, визначеного в (image-compress.mdc).
 
-- **Свіжий проєкт без зображень.** `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
+1. Зчитування рядків з `.gitignore`
+2. Перевірка наявності кешу `HASH_CACHE_FILENAME` у `.gitignore`
+3. Перевірка видалення застарілого кешу `LEGACY_CACHE_FILENAME`
+4. Перевірка відповідності правилу `image-compress.mdc`
 
-| Перевірка                                                   | Де реалізована                |
-| ----------------------------------------------------------- | ----------------------------- |
-| Наявність `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/`) |
+## Публічний API
 
-## Rebuild Test
+check — Перевіряє, чи відсутній у `.gitignore` файл `.n-minify-image.tsv` та чи видалено `.minify-image-cache.tsv`. Вказує, що CI-workflow для image не потрібен, оскільки лінтування зображень відбувається лише локально. (image-compress.mdc)
 
-Якщо файл `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`, щоб користувач у звіті бачив джерело вимоги.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`.
+- Не звертається до мережі.