@nitra/cursor 3.22.0 → 3.23.1

package/rules/hasura/hasura.mdc

@@ -26,3 +26,17 @@ HASURA_GRAPHQL_ENDPOINT=http://contract-h-hl.ua-contract.svc.abie-ua.internal:80
 Правило застосовується для проєктів **nitra** (у кореневому `package.json` `"repository": "https://github.com/nitra/*"`) і **abie** (`"repository": "https://github.com/abinbevefes/*"`); для інших репозиторіїв перевірка пропускається.
 
 Файл .env це (без імені) це виключення з цього правила, його змінювати не потрібно
+
+## Міграції: лише `up.sql`, без `down.sql`
+
+При створенні будь-якої нової директорії міграції у `hasura/migrations/` **не створювати файл `down.sql`**.
+У директорії міграції має бути **тільки `up.sql`**.
+
+Приклад коректної структури:
+
+```
+hasura/migrations/default/1781247030100_add_foo/
+└── up.sql   ✓
+```
+
+Файл `down.sql` у цьому проєкті **не використовується** і не повинен з'являтися.

package/rules/hasura/js/docs/internal_urls.md

@@ -0,0 +1,326 @@
+# internal_urls.mjs
+
+## Огляд
+
+Модуль `npm/rules/hasura/js/internal_urls.mjs` реалізує перевірку правила `hasura.mdc` для проєктів **nitra** та **abie**. Його єдина мета — гарантувати, що значення змінної середовища `HASURA_GRAPHQL_ENDPOINT`, заданої в будь-якому файлі `*.env` репозиторію, є **внутрішнім кластерним URL** (GKE/GCP DNS-суфікс `<cluster>.internal`), а не публічним доменом.
+
+Логіка активується лише за умови, що поле `repository` кореневого `package.json` вказує на одну з організацій:
+
+- `https://github.com/nitra/...`
+- `https://github.com/abinbevefes/...`
+
+Якщо ці маркери відсутні, перевірка пропускається без помилок (аналогічно до інших abie-перевірок).
+
+Очікуваний формат URL:
+
+```
+http://<service>.<namespace>.svc.<cluster>.internal:<port>
+```
+
+Приклад валідного значення:
+
+```
+http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080
+```
+
+Сегменти `<service>` та `<namespace>` за наявності YAML-файлів `hasura/k8s/base/svc-hl.yaml` (поле `metadata.name`, headless-сервіс із суфіксом `-h-hl`) та `hasura/k8s/base/namespace.yaml` (поле `metadata.name`) додатково звіряються з фактичними значеннями kubernetes-маніфестів.
+
+Скануються всі файли, що відповідають масці `*.env` (наприклад, `dev.env`, `production.env`). Файл з іменем рівно `.env` (локальний файл розробника) **виключається** з перевірки. Не обходяться службові каталоги: `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next` (відповідно до конфігурації `walkDir`).
+
+## Експорти / API
+
+Модуль є ES-модулем (`.mjs`) і експортує:
+
+| Експорт                       | Тип             | Призначення                                                                                       |
+| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------- |
+| `parseInternalHasuraEndpoint` | функція         | Розбирає URL-рядок на сегменти кластерної DNS-адреси (`service`, `namespace`, `cluster`, `port`). |
+| `isEnvFile`                   | функція         | Чи підлягає файл за відносним шляхом перевірці hasura.mdc.                                        |
+| `isNitraOrAbieRepository`     | функція         | Чи репозиторій належить організаціям nitra / abinbevefes.                                         |
+| `check`                       | функція (async) | Точка входу: запускає повну перевірку для cwd, повертає exit-код процесу.                         |
+
+Внутрішні (не експортовані) допоміжні функції: `readYamlMetadataName`, `collectEnvFiles`, `checkEnvFile`, `readRootRepositoryUrl`.
+
+Внутрішні константи:
+
+| Константа                     | Значення                            | Призначення                                                             |
+| ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------- |
+| `NITRA_REPOSITORY_URL_MARKER` | `'https://github.com/nitra/'`       | Маркер репозиторіїв організації nitra.                                  |
+| `ABIE_REPOSITORY_URL_MARKER`  | `'https://github.com/abinbevefes/'` | Маркер репозиторіїв організації abinbevefes (abie).                     |
+| `HASURA_BASE_DIR`             | `'hasura/k8s/base'`                 | Базовий каталог k8s-маніфестів Hasura.                                  |
+| `HASURA_SVC_HL_FILE`          | `'hasura/k8s/base/svc-hl.yaml'`     | Шлях до headless-сервіса.                                               |
+| `HASURA_NAMESPACE_FILE`       | `'hasura/k8s/base/namespace.yaml'`  | Шлях до namespace-маніфесту.                                            |
+| `ENV_FILE_RE`                 | `/\.env$/u`                         | Регулярка-маркер `*.env` файлів.                                        |
+| `HASURA_ENDPOINT_LINE_RE`     | (див. нижче)                        | Регулярка для знаходження рядка `HASURA_GRAPHQL_ENDPOINT=...` у `.env`. |
+| `INTERNAL_HASURA_URL_RE`      | (див. нижче)                        | Регулярка валідації внутрішнього кластерного URL.                       |
+| `INTERNAL_DNS_SUFFIX`         | `'.internal'`                       | DNS-суфікс GKE/GCP-кластера.                                            |
+
+Регулярні вирази:
+
+- `HASURA_ENDPOINT_LINE_RE = /^[ \t]*(?:export[ \t]+)?HASURA_GRAPHQL_ENDPOINT[ \t]*=[ \t]*['"]?([^'"\r\n#]+)/mu`
+  - Multiline, Unicode. Підтримує `export ` префікс, табуляції/пробіли навколо `=`, опційне обрамлення лапками (`'` або `"`). Капчурить значення до символа лапки, перенесення рядка або `#` (коментар).
+- `INTERNAL_HASURA_URL_RE = /^http:\/\/([^./]+)\.([^./]+)\.svc\.([^./:]+\.internal):(\d+)\/?$/u`
+  - Дозволяє лише схему `http://` (TLS усередині кластера зайвий).
+  - Капчурить чотири сегменти: `service`, `namespace`, DNS-суфікс (з обов'язковим `.internal`), `port`.
+  - Допускає необов'язковий завершальний слеш.
+
+## Функції
+
+### `parseInternalHasuraEndpoint(url)`
+
+**Сигнатура:**
+
+```js
+export function parseInternalHasuraEndpoint(url)
+```
+
+**Параметри:**
+
+- `url` (`string`) — значення `HASURA_GRAPHQL_ENDPOINT`, попередньо очищене від обрамляючих лапок (для надійності функція ще раз застосовує `.trim()`).
+
+**Повертає:**
+
+- При успіху: `{ ok: true, service: string, namespace: string, cluster: string, port: string }`. Поле `cluster` містить ім'я кластера **без** суфіксу `.internal` (наприклад, `abie-ua`).
+- При невідповідності формату: `{ ok: false }`.
+
+**Поведінка та особливості:**
+
+- Дозволяє виключно протокол `http://` і DNS-суфікс `<cluster>.internal` (GKE/GCP-конвенція).
+- Усі сегменти повертаються як рядки (включно з `port`, попри те що значення цифрове).
+- Side effects відсутні.
+
+### `readYamlMetadataName(absPath, kind)` (внутрішня)
+
+**Сигнатура:**
+
+```js
+async function readYamlMetadataName(absPath, kind)
+```
+
+**Параметри:**
+
+- `absPath` (`string`) — абсолютний шлях до YAML-файла.
+- `kind` (`string`) — очікуваний `kind` ресурсу (`'Service'`, `'Namespace'` тощо).
+
+**Повертає:** `Promise<string | null>` — значення `metadata.name` першого документа з відповідним `kind`, або `null`, якщо:
+
+- файл не існує;
+- парсинг YAML не вдався (`parseAllDocuments` кинув виключення);
+- жоден документ у файлі не має заданого `kind` або не має `metadata.name`.
+
+**Side effects:** одне читання з файлової системи (`readFile`); жодних винятків назовні не пропускає.
+
+### `isEnvFile(relPath)`
+
+**Сигнатура:**
+
+```js
+export function isEnvFile(relPath)
+```
+
+**Параметри:**
+
+- `relPath` (`string`) — posix-шлях файла відносно кореня репозиторію.
+
+**Повертає:** `boolean`.
+
+- `true` — для файлів, у яких є ім'я перед `.env`: `dev.env`, `nitra.env`, `production.env`.
+- `false` — для всіх інших, **зокрема** для файла рівно `.env` без імені (локальний файл розробника, виключений з правила hasura.mdc).
+
+**Side effects:** немає.
+
+### `collectEnvFiles(root, ignorePaths)` (внутрішня)
+
+**Сигнатура:**
+
+```js
+async function collectEnvFiles(root, ignorePaths)
+```
+
+**Параметри:**
+
+- `root` (`string`) — абсолютний шлях кореня репозиторію.
+- `ignorePaths` (`string[]`) — абсолютні шляхи каталогів, які слід повністю пропустити при обході (зчитуються з cursor-конфігу).
+
+**Повертає:** `Promise<string[]>` — відсортовані за `localeCompare` posix-шляхи `*.env` файлів відносно `root`.
+
+**Поведінка:**
+
+- Використовує `walkDir` з callback-фільтром.
+- Конвертує windows-роздільники `\` у posix-роздільники `/` перед перевіркою `isEnvFile`.
+- Працює дитерміновано завдяки сортуванню `toSorted`.
+
+**Side effects:** обхід файлової системи.
+
+### `checkEnvFile(relPath, cwd, expected, reporter)` (внутрішня)
+
+**Сигнатура:**
+
+```js
+async function checkEnvFile(relPath, cwd, expected, reporter)
+```
+
+**Параметри:**
+
+- `relPath` (`string`) — відносний posix-шлях файла (для повідомлень репортера).
+- `cwd` (`string`) — корінь репозиторію (для побудови абсолютного шляху).
+- `expected` (`{ service: string | null, namespace: string | null }`) — очікувані сегменти, прочитані з YAML-маніфестів; `null`-поля пропускаються.
+- `reporter` (`{ pass: (msg: string) => void, fail: (msg: string) => void }`) — обробник результатів (зазвичай з `createCheckReporter`).
+
+**Повертає:** `Promise<void>`. Результат комунікується через `reporter`.
+
+**Поведінка по гілках:**
+
+1. Якщо в файлі **немає** змінної `HASURA_GRAPHQL_ENDPOINT` — функція мовчки виходить без виклику `pass`/`fail`.
+2. Якщо значення не парситься як внутрішній кластерний URL — викликає `fail` з прикладом очікуваного формату (`https://<service>.<namespace>.svc.<cluster>.internal:<port>`).
+3. Якщо `expected.service` задане і не збігається — `fail` з посиланням на `hasura/k8s/base/svc-hl.yaml`.
+4. Якщо `expected.namespace` задане і не збігається — `fail` з посиланням на `hasura/k8s/base/namespace.yaml`.
+5. Інакше — `pass` з підтвердженням, що URL внутрішній кластерний.
+
+**Side effects:** читання файла, виклики методів `reporter`.
+
+**Примітка:** в `fail`-повідомленні приклад наведений зі схемою `https://`, хоча сама регулярка `INTERNAL_HASURA_URL_RE` дозволяє лише `http://` (так задумано — TLS усередині кластера зайвий).
+
+### `readRootRepositoryUrl(cwd)` (внутрішня)
+
+**Сигнатура:**
+
+```js
+async function readRootRepositoryUrl(cwd)
+```
+
+**Параметри:**
+
+- `cwd` (`string`) — корінь репозиторію.
+
+**Повертає:** `Promise<string | null>` — URL з поля `repository` (нормалізований через `getRepositoryUrl`) або `null`, якщо:
+
+- `package.json` не існує;
+- JSON не валідний;
+- поле `repository` відсутнє / нерозпізнаний формат.
+
+**Side effects:** одне читання `package.json`.
+
+### `isNitraOrAbieRepository(url)`
+
+**Сигнатура:**
+
+```js
+export function isNitraOrAbieRepository(url)
+```
+
+**Параметри:**
+
+- `url` (`string | null | undefined`) — URL репозиторію.
+
+**Повертає:** `boolean`.
+
+- `true`, якщо `url` — рядок і містить (case-insensitive) маркер `https://github.com/nitra/` або `https://github.com/abinbevefes/`.
+- `false` — у решті випадків (включно з `null`, `undefined`, не-рядковими значеннями).
+
+**Side effects:** немає.
+
+### `check(cwd?)`
+
+**Сигнатура:**
+
+```js
+export async function check(cwd = process.cwd())
+```
+
+**Параметри:**
+
+- `cwd` (`string`, опційний, за замовчуванням `process.cwd()`) — корінь репозиторію.
+
+**Повертає:** `Promise<number>` — exit-код процесу (`0` — OK або правило не застосовується, `1` — є хоча б одне порушення). Конкретне значення формує `reporter.getExitCode()`.
+
+**Поведінка (послідовно):**
+
+1. Створює репортер через `createCheckReporter()`.
+2. Зчитує URL репозиторію з `package.json`. Якщо це не nitra/abie — `pass('Пропущено: …')` і повертає exit-код (зазвичай `0`).
+3. Зчитує очікувані `service` і `namespace` з YAML-маніфестів (обидва можуть бути `null`).
+4. Завантажує `ignorePaths` з cursor-конфігу (`loadCursorIgnorePaths`).
+5. Збирає всі `*.env` файли. Якщо їх немає — `pass('Не знайдено жодного *.env файла — нічого перевіряти')` і повертає exit-код.
+6. Послідовно (без паралелізму) викликає `checkEnvFile` для кожного знайденого файла.
+7. Якщо після перевірок exit-код залишився `0` і **жоден** файл не мав `HASURA_GRAPHQL_ENDPOINT` (тобто не було ні `pass`, ні `fail` зі змістом перевірки), додає підсумкове `pass` з кількістю та іменами перевірених файлів.
+
+**Side effects:** читання файлів, обхід каталогів, виведення повідомлень репортера (зазвичай у stdout/stderr).
+
+## Залежності
+
+### Зовнішні модулі (npm)
+
+- `yaml` — функція `parseAllDocuments` для парсингу мульти-документних YAML-файлів kubernetes-маніфестів.
+
+### Node.js core
+
+- `node:fs` — `existsSync` для синхронної перевірки наявності `package.json` та YAML-файлів.
+- `node:fs/promises` — `readFile` для асинхронного читання файлів у UTF-8.
+- `node:path` — `basename`, `join`, `relative` для роботи зі шляхами.
+
+### Внутрішні модулі репозиторію
+
+- `../../../scripts/auto-rules.mjs` — `getRepositoryUrl` для нормалізації поля `repository` у `package.json` (підтримує і рядкову, і об'єктну форму).
+- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter` для уніфікованого механізму репортингу `pass`/`fail` та обчислення exit-коду.
+- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths` для отримання списку каталогів, виключених з обходу (повертає абсолютні шляхи).
+- `../../../scripts/utils/walkDir.mjs` — `walkDir` для рекурсивного обходу файлової системи з callback-логікою і набором default-ignore (`node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`).
+
+### Файли, що читаються в рантаймі
+
+- `<cwd>/package.json` — джерело поля `repository`.
+- `<cwd>/hasura/k8s/base/svc-hl.yaml` — джерело очікуваного `service` (якщо існує).
+- `<cwd>/hasura/k8s/base/namespace.yaml` — джерело очікуваного `namespace` (якщо існує).
+- `<cwd>/**/*.env` (без рівно `.env` і без ignore-каталогів) — файли, що перевіряються.
+
+## Потік виконання / Використання
+
+### Сценарій 1. Запуск як check-функції правила hasura.mdc
+
+Модуль очікувано викликається з єдиної точки входу `check()` через інфраструктуру `npm/rules`/`scripts`. Типове використання:
+
+```js
+import { check } from './internal_urls.mjs'
+
+const exitCode = await check(process.cwd())
+process.exitCode = exitCode
+```
+
+### Сценарій 2. Послідовність кроків при виконанні `check()`
+
+1. **Препроцесинг репозиторію.** Зчитується `package.json`. Якщо `repository` не вказує на nitra/abie — правило мовчки пропускається з повідомленням `pass`.
+2. **Підготовка очікуваних значень.** Зчитуються `metadata.name` з `svc-hl.yaml` (як `Service`) і `namespace.yaml` (як `Namespace`). Кожне поле може бути `null` (тоді відповідна перевірка для сегмента URL не виконується).
+3. **Збір кандидатів.** Через `walkDir` з ignore-списком з cursor-конфігу збираються усі `*.env` файли (відсортовано). Якщо колекція порожня — повідомляється `pass` і завершується.
+4. **Перевірка кожного файла.** Для кожного знайденого `*.env`:
+   - Якщо у файлі немає `HASURA_GRAPHQL_ENDPOINT` — пропуск без репортингу.
+   - Інакше значення розбирається `parseInternalHasuraEndpoint`. Якщо парсинг не вдався — `fail`.
+   - Якщо `expected.service` заданий і `parsed.service` не збігається — `fail`.
+   - Якщо `expected.namespace` заданий і `parsed.namespace` не збігається — `fail`.
+   - Інакше — `pass`.
+5. **Підсумок.** Якщо за результатом усіх перевірок exit-код залишився `0` (тобто жодного `fail` не було), додається підсумкове `pass` з переліком імен файлів. Це покриває кейс, коли всі `*.env` не містили змінної взагалі.
+6. **Exit-код.** Повертається через `reporter.getExitCode()`: `0` — успіх, `1` — є порушення.
+
+### Сценарій 3. Що вважається валідним URL
+
+Валідні приклади:
+
+- `http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080`
+- `http://hasura-h-hl.nitra-prod.svc.nitra-cluster.internal:8080/`
+
+Невалідні приклади (викличуть `fail`):
+
+- `https://my.public.domain:443` — публічний домен.
+- `http://hasura-h-hl.nitra-prod.svc.cluster.local:8080` — DNS-суфікс `.local`, а не `.internal`.
+- `http://hasura-h-hl.svc.abie-ua.internal:8080` — відсутній сегмент `namespace`.
+- `http://hasura-h-hl.nitra-prod.svc.abie-ua.internal` — відсутній port.
+- `http://hasura-h-hl.nitra-prod.svc.abie-ua.internal:8080/graphql` — є шлях після `/`.
+
+### Сценарій 4. Інтеграція в репортинг
+
+Для цілісного запуску модуль не виводить нічого сам — усі повідомлення (`pass`/`fail`) делегуються `createCheckReporter()`. Це означає, що формат логів, кольори та сумарний exit-код узгоджені з рештою rule-перевірок у `npm/rules`.
+
+### Сценарій 5. Граничні випадки
+
+- **Файл `.env`** (без імені, локальний розробницький) **пропускається** на рівні `isEnvFile`.
+- **Відсутнє `repository` в `package.json`** → правило пропускається з `pass`.
+- **YAML-файли відсутні / невалідні** → відповідне поле `expected` стане `null` і перевірка сегмента не виконується (але формат URL все одно валідується).
+- **`HASURA_GRAPHQL_ENDPOINT` у `.env` закоментований через `#` після значення** → регулярка зупиниться на `#`, повернувши значення до коментаря.
+- **Значення в подвійних/одинарних лапках** → лапки відкидаються регуляркою-капчуром.

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

@@ -0,0 +1,132 @@
+# `fix.mjs` — entry-point правила `image-avif`
+
+## Огляд
+
+Файл `npm/rules/image-avif/fix.mjs` — це **подвійний entry-point** одного з правил пакета `@nitra/cursor`. Він входить до інфраструктури «standard rules», де кожне правило живе в окремій теці (`npm/rules/<id>/`) і складається з:
+
+- `fix.mjs` — тонкий wrapper-orchestrator (цей файл);
+- `meta.json` — метадані (наприклад, `auto`-залежності, тут `{"auto": ["vue", "image-compress"]}`);
+- `<id>.mdc` — людино-зрозумілий опис правила для Cursor;
+- підтек `js/` (concerns на рівні JS-AST/тексту) і `policy/` (rego-policy).
+
+Конкретно цей файл виконує дві ролі:
+
+1. **Library-режим.** Експортує функцію `run(ctx)`, яку CLI-orchestrator вищого рівня (`@nitra/cursor fix`) імпортує й викликає для прогону правила в межах загального пайплайну (з кешем walk-обходу й спільним підсумком).
+2. **Standalone-режим.** Якщо файл запущено напряму (`bun npm/rules/image-avif/fix.mjs` або еквівалент), він самостійно піднімає повний CLI-цикл (`runRuleCli`) — з підвантаженням конфігурації, whitelist та виведенням підсумку — і завершує процес кодом 0/1.
+
+Сам файл **не містить** логіки перевірки контенту: уся робота делегується в `runStandardRule`, який послідовно проганяє чотири фази правила — `applies → JS-concerns → policy → mdc-refs`.
+
+## Експорти / 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, unicorn/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` лише оркеструє.