@nitra/cursor 12.6.0 → 12.7.0

package/rules/ga/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/ga/main.mjs
+docgen:
+  crc: f6b5f0b3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+## Огляд
+
+Цей модуль є CLI-обгорткою над канонічним `lint-ga` (ga.mdc). Він автоматично встановлює `shellcheck` та `conftest` через `ensureTool` (використовуючи brew/scoop/GitHub Release залежно від платформи), перевіряє наявність `uv` (для `uvx zizmor`), а потім послідовно виконує `bunx github-actionlint`, `uvx zizmor --offline --collect=workflows .` та делегує до `rules/ga/check.mjs::check`. Функція `lint` викликає `runLintGaCli`, який є частиною оркестраторного адаптера `n-cursor lint ga`. При відсутності `uv`, користувачеві надається підказка з командою встановлення, наприклад, https://astral.sh/uv/install.sh, оскільки `uv` не в реєстрі `ensureTool`.
+
+## Поведінка
+
+run виконує стандартну перевірку правила, застосовуючи логіку, описану в `mdc-refs`.
+runLintGaCli виконує повний канонічний процес `lint-ga`: автоматично встановлює `shellcheck` та `conftest`, перевіряє наявність `uv`, а потім послідовно запускає `github-actionlint`, `zizmor` та перевірку Rego-полісі через `rules/ga/check.mjs`.
+lint делегує виконання повного канонічного процесу `lint-ga` через `runLintGaCli`.
+
+## Публічний API
+
+run — виконує основну перевірку, яка охоплює логіку застосування до JS-задач, політики та посилання на mdc-референси.
+runLintGaCli — виконує лінтинг з використанням інструментів actionlint/zizmor та перевірку ga.
+lint — керує процесом лінтингу, делегуючи виконання `runLintGaCli`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/ga/{lint/lint.mjs → main.mjs}

@@ -2,13 +2,13 @@
  * CLI-обгортка над канонічним `lint-ga` (ga.mdc): авто-встановлює `shellcheck` і `conftest`
  * через `ensureTool` (brew/scoop/GitHub Release per-platform), перевіряє наявність `uv` (для `uvx`),
  * тоді послідовно виконує `bunx github-actionlint`, `uvx zizmor --offline --collect=workflows .` і
- * делегує до `rules/ga/fix.mjs::check()` — там і Rego-частина (через `runConftestBatch`),
+ * делегує до `rules/ga/check.mjs::check()` — там і Rego-частина (через `runConftestBatch`),
  * і JS cross-file перевірки правил `ga.mdc`.
  *
  * Plan B-патерн (rego-authoritative): Rego-полісі (`npm/policy/ga/`) запускає вже сам
- * `rules/ga/fix.mjs::check()` як перший крок — `lint-ga.mjs` про це не знає. Раніше `lint-ga.mjs` сам
+ * `rules/ga/check.mjs::check()` як перший крок — `lint-ga.mjs` про це не знає. Раніше `lint-ga.mjs` сам
  * спавнив conftest для `ga.<name>` per-workflow і `ga.workflow_common` (PoC); тепер ця логіка
- * централізована у `rules/ga/fix.mjs`, тож одне джерело істини, без дублювання між
+ * централізована у `rules/ga/check.mjs`, тож одне джерело істини, без дублювання між
  * `lint-ga` і `npx \@nitra/cursor check ga`.
  *
  * Без preflight `actionlint` (через `bunx github-actionlint`) мовчки пропускає shell-перевірки в
@@ -18,18 +18,30 @@
  * `uv` потрібен для `uvx zizmor`. Якщо його нема — `uvx zizmor` падає неінформативно; підказка
  * з командою встановлення коротша й корисніша. `uv` не в реєстрі ensureTool → hint-only.
  *
- * Експортовано окремо `runLintGaCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-ga`.
+ * Експортовано окремо `runLintGaCli` — викликається через `n-cursor lint ga` (оркестраторний адаптер `lint()` делегує сюди); окремої bin-підкоманди `lint-ga` немає.
  *
  * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
  * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { platform } from 'node:process'
 
-import { check as checkGa } from '../js/workflows.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { runLintStep } from '../../../scripts/lib/run-lint-step.mjs'
-import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
-import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
+import { check as checkGa } from './js/workflows.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { runLintStep } from '../../scripts/lib/run-lint-step.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { ensureTool } from '../../scripts/lib/ensure-tool.mjs'
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (actionlint/zizmor + check-ga), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 /**
  * Опис залежності preflight-ом: бінарник, для чого потрібен, і команди встановлення.
@@ -109,7 +121,7 @@ function preflight(dep) {
  * 2) preflight: `uv` (для `uvx zizmor`) — hint-only, без авто-install;
  * 3) `bunx github-actionlint`;
  * 4) `uvx zizmor --offline --collect=workflows .`;
- * 5) `rules/ga/fix.mjs::check()` — Rego-полісі (батч conftest з `npm/policy/ga/`) + JS cross-file
+ * 5) `rules/ga/check.mjs::check()` — Rego-полісі (батч conftest з `npm/policy/ga/`) + JS cross-file
  *    перевірки правил `ga.mdc`. Це **те саме**, що робить `npx \@nitra/cursor check ga`, тож
  *    `lint-ga` тепер є суперсетом перевірки правила: external-tools + check.
  * @returns {Promise<number>} 0 — все OK, інакше — код першого кроку, що впав
@@ -133,3 +145,17 @@ async function runLintGaSteps() {
 }
 
 export const runLintGaCli = () => runStandardLint(import.meta.dirname, runLintGaSteps)
+
+/**
+ * Оркестраторний адаптер `n-cursor lint ga`: делегує у `runLintGaCli`.
+ * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files) {
+  return runLintGaCli()
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/ga/main.mjs — повний еквівалент `npx @nitra/cursor check ga`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/graphql/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/graphql/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/graphql/docs/main.md

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/graphql/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль валідує дані на відповідність політикам, використовуючи конфігурації з meta.json, логіку визначення зацікавленості та контекст. При виконанні як CLI, він завантажує конфігурації, перевіряє білий список, агрегує стан валідації та завершує роботу відповідним кодом.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання перевірки застосовує:
+    * Конфігурації, визначені у `meta.json`.
+    * Логіку, пов'язану з JS-зацікавленістю.
+    * Політику, визначену в контексті.
+    * Посилання на MDC.
+3. Якщо скрипт виконується як окремий інструмент (CLI), виконується повний цикл правил:
+    * Завантаження конфігурацій.
+    * Перевірка білого списку.
+    * Зведення результатів.
+    * Вихід із кодом, що інформує про успіх чи порушення.
+
+## Публічний API
+
+run — єдиний вхідний пункт правила, який виконує послідовність перевірок: застосовує логіку, обробляє JS-специфічні моменти, перевіряє політику та посилання на MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/graphql/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/hasura/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/hasura/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/hasura/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/hasura/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує логіку, визначену у конфігурації `meta.json`. Він валідує дані відповідно до правил, застосовує визначену політику та збирає посилання до MDC. При запуску через публічну функцію `run` ініціюється виконання правила. Модуль є read-only і не виконує операцій запису у файлову систему чи бази даних.
+
+## Поведінка
+
+1. Викликається публічна функція `run`.
+2. Виконується перевірка на відповідність конфігурації, що описується у `meta.json`.
+3. Виконується застосування політики, що визначається в конфігурації.
+4. Здійснюється збір посилань до MDC.
+5. Якщо код виконується як окрема утиліта (CLI), викликається механізм виконання правила.
+
+## Публічний API
+
+run — виконує повний цикл перевірки: застосовує логіку, аналізує JS-залежності, перевіряє політику та посилання на MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/hasura/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

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

@@ -9,3 +9,4 @@ resource: npm/rules/image-avif/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

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

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/image-avif/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку на основі логіки правил, використовуючи конфігурації з meta.json, політики та посилання на MDC. При запуску як окрема утиліта, він завантажує конфігурації, застосовує білі списки для фільтрації та формує зведений звіт. Результат виконання визначає код виходу процесу. Кешування відбувається у межах прогону. Модуль є Read-only, тобто не здійснює записів у файлову систему чи бази даних.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання `run` застосовує логіку правила, включаючи обробку конфігурацій, перевірку політик та посилання на MDC.
+3. Якщо код виконується як окрема утиліта (CLI), ініціюється повний запуск правила.
+4. Запуск правила як утиліта включає завантаження конфігурацій, застосування білих списків та формування зведеного звіту.
+5. Результат виконання визначає код виходу процесу.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки до коду, аналізує аспекти JavaScript та застосовує політику, використовуючи посилання на метадані.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

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

@@ -3,244 +3,31 @@ type: JS Module
 title: avif_generation.mjs
 resource: npm/rules/image-avif/js/avif_generation.mjs
 docgen:
-  crc: 101bb0dd
+  crc: 3f00d274
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль реалізує перевірку правила `image-avif.mdc`: генерацію AVIF-двійників растрових зображень і ув'язування цих двійників із посиланнями у `.vue`- та `.html`-файлах монорепо. Експортує функцію `check`, яку викликає CLI `n-cursor` для команди `check image-avif` / `fix image-avif`.
+Модуль трансформує посилання на растрові зображення у шаблонах `.vue` та `.html` у workspace-пакетах, замінюючи їх на формат AVIF. Процес залежить від конфігурацій, визначених у package.json. Модуль оновлює всі посилання на зображення, якщо перевірка AVIF не вимкнена, створюючи AVIF-двійники. Також він видаляє посилання на 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 лишається лише там, де заміна вдалася».
+1. Перевіряється, чи містить репозиторій посилання на raster-зображення у файлах `.vue` або `.html` у workspace-пакетах, які не мають вимкненої перевірки AVIF. Якщо посилань немає, процес AVIF-генерації та очищення пропускається.
+2. Запускається генерація AVIF-двійників за допомогою зовнішнього інструменту.
+3. Скануються workspace-пакети:
+    а. Визначається, чи вимкнено примусове застосування AVIF у пакеті через конфігурацію `package.json`. Якщо так, пакет пропускається для подальшої перевірки шаблонів.
+    б. Для пакетів, де AVIF не вимкнено, скануються файли `.vue` та `.html`.
+    в. У знайдених посиланнях на raster-зображення, якщо відповідний AVIF-двійник існує, посилання замінюється на `.avif`.
+    г. Якщо AVIF-двійник не існує, фіксується помилка.
+    д. Після обробки файлу, він записується з новими змінами.
+    е. Збирається список абсолютних шляхів AVIF-двійників, на які залишилося живе посилання.
+4. Видаляються AVIF-сироти — файли `.avif`, які не були відмічені як вжиті у кроці 3.б.
+5. Повертається код виходу, що відображає успішність виконання всіх етапів.
 
-Модуль свідомо не дублює перевірки cache/dependency policy з правила `image-compress`. Правило `image-avif` самостійне й вмикається лише там, де AVIF підтримується (адмінки), а не у публічних сайтах.
+## Публічний API
 
-## Експорти / API
+check — генерує AVIF-зображення, автоматично замінює посилання на растрові зображення у `.vue`/`.html` файлах та очищає від неіснуючих AVIF-файлів.
 
-| Експорт       | Тип              | Призначення                                                                         |
-| ------------- | ---------------- | ----------------------------------------------------------------------------------- |
-| `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-avif/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

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

@@ -9,3 +9,4 @@ resource: npm/rules/image-compress/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

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

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/image-compress/main.mjs
+docgen:
+  crc: abe40746
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+## Огляд
+
+Модуль забезпечує механізми для виконання та валідації контенту відповідно до визначених правил. Функція `run` виконує перевірку відповідності контенту визначеним критеріям у межах поточного контексту прогону. Функція `lint` виконує виявлення або стиснення зображень залежно від режиму `readOnly`.
+
+## Поведінка
+
+run виконує стандартну перевірку, використовуючи контекст прогону.
+lint виконує перевірку або стиснення зображень, залежно від опцій: якщо `readOnly` встановлено, виконується лише детект, інакше виконується стиснення.
+
+## Публічний API
+
+run — головна точка входу для виконання правил, де відбувається перевірка на відповідність вимогам (JS-занепокоєння $\rightarrow$ політика $\rightarrow$ посилання MDC).
+lint — перевірка зображень за допомогою `@nitra/minify-image`, що може працювати у режимі лише читання або з можливістю автоматичного виправлення.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.