@nitra/cursor 12.6.1 → 12.8.0

package/rules/docker/lib/docker-hadolint.mjs

@@ -4,7 +4,7 @@
  * Відносні шляхи з прямими слешами; hadolint резолвиться через `ensureTool`
  * (PATH → кеш → авто-install brew/scoop/GitHub Release per-platform). Docker-fallback
  * прибрано — hadolint ставиться як **нативний бінарник**, без `docker run`.
- * Використовується `./check.mjs` (check-docker) та `../../lint/lint.mjs` (run-docker).
+ * Використовується `../js/lint.mjs` (правило `n-cursor lint docker` / check-docker).
  */
 import { spawnSync } from 'node:child_process'
 import { relative, sep } from 'node:path'

package/rules/docker/lib/docs/docker-hadolint.md

@@ -3,186 +3,29 @@ type: JS Module
 title: docker-hadolint.mjs
 resource: npm/rules/docker/lib/docker-hadolint.mjs
 docgen:
-  crc: b97701f3
+  crc: ebab2135
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-Модуль `docker-hadolint.mjs` інкапсулює спільну логіку запуску статичного аналізатора `hadolint` для перевірки `Dockerfile`-ів у межах правила `docker` (див. `.cursor/rules/docker.mdc` / `n-docker`). Він є тонким адаптером поверх системного бінарника `hadolint` та надає двом викликачам — `check.mjs` (skill `check-docker`) і `../../lint/lint.mjs` (skill `run-docker`) — єдину функцію перевірки одного `Dockerfile` плюс утиліту нормалізації шляхів.
+## Огляд
 
-Ключові архітектурні рішення:
+Спільна логіка виклику hadolint для шляхів до Dockerfile. Модуль створює стандартизовані відносні шляхи з прямими слешами. Він ініціює перевірку Dockerfile, використовуючи hadolint як нативний бінарник, який резолвиться через `ensureTool` (PATH → кеш → авто-install brew/scoop/GitHub Release per-platform). Для отримання інформації про встановлення можна звертатися до https://github.com/hadolint/hadolint/releases. Публічна функція `lintDockerfileWithHadolint` виконує перевірку за правилом `n-cursor lint docker` / check-docker.
 
-- `hadolint` запускається **виключно як нативний бінарник**. Будь-який Docker-fallback (наприклад, `docker run hadolint/hadolint`) свідомо прибраний, тож модуль не залежить від запущеного Docker Engine.
-- Розв’язання шляху до бінарника делеговано в `ensureTool('hadolint')`, який реалізує ланцюжок `PATH → локальний кеш інструментів → авто-install` через `brew` / `scoop` / GitHub Release, відповідно до платформи.
-- Якщо `ensureTool` падає (інструмент відсутній і авто-install вимкнено через `N_CURSOR_NO_AUTO_INSTALL` або фізично не вдався), модуль **не кидає виняток назовні**, а повертає структурований результат `{ ok: false, stderr: <інструкція з установки> }`. Це дозволяє викликачам однаково обробляти і реальні порушення hadolint, і відсутність інструмента.
-- Шляхи у виводі нормалізуються через `posixRel` (відносно `root`, з прямими слешами `/`), щоб лог і повідомлення про помилки були стабільними між macOS / Linux / Windows.
+## Поведінка
 
-## Експорти / API
+posixRel
+Створює відносний шлях від кореня з використанням прямих слешів.
 
-Модуль є ESM (`.mjs`) і має два іменовані експорти:
+lintDockerfileWithHadolint
+Запускає hadolint як нативний бінарник для перевірки Dockerfile. Якщо не вдається знайти hadolint, повертає помилку з інструкцією для встановлення (наприклад, https://github.com/hadolint/hadolint/releases).
 
-| Експорт                                     | Тип      | Призначення                                                                        |
-| ------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
-| `posixRel(root, absPath)`                   | function | Перетворити абсолютний шлях на відносний від `root` з прямими слешами.             |
-| `lintDockerfileWithHadolint(root, absPath)` | function | Запустити `hadolint` для одного `Dockerfile` і повернути структурований результат. |
+## Публічний API
 
-Default-експорту немає. Глобальних побічних ефектів на рівні модуля немає — імпорт лише підтягує `ensureTool`, не виконуючи його.
+- posixRel — Генерує абсолютний шлях від кореня з використанням лише слешів, забезпечуючи стабільність незалежно від операційної системи.
+- lintDockerfileWithHadolint — Запускає інструмент hadolint для аналізу Dockerfile. Якщо інструмент не знайдено у системних шляхах, він намагається встановити його. У разі невдачі встановлення або відключення автоматичного встановлення, повертає помилку, надаючи користувачеві підказку для ручного запуску (детальніше про інструмент можна знайти на https://github.com/hadolint/hadolint/releases).
 
-## Функції
+## Гарантії поведінки
 
-### `posixRel(root, absPath)`
-
-Утиліта нормалізації шляхів для стабільного логування й передачі в `hadolint`.
-
-**Сигнатура:**
-
-```js
-export function posixRel(root: string, absPath: string): string
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію (або будь-якого опорного каталогу), відносно якого треба отримати шлях.
-- `absPath` — абсолютний шлях до файлу, який треба представити відносно `root`.
-
-**Повертає:**
-
-- Рядок із відносним шляхом, де всі системні розділювачі (`path.sep`) замінено на прямий слеш `/`. На POSIX-системах результат фактично збігається з `path.relative`, на Windows — конвертує `\` на `/`.
-
-**Алгоритм:**
-
-1. Викликає `relative(root, absPath)` з `node:path` для обчислення відносного шляху.
-2. Розбиває результат за поточним `sep` (`path.sep`) і склеює знову через `'/'`.
-
-**Side effects:** немає; функція чиста й детермінована.
-
-**Примітка:** функція не валідовує, чи `absPath` справді абсолютний і чи він знаходиться під `root` — у такому випадку `relative` поверне відносний шлях із `..`, що теж буде нормалізовано до прямих слешів.
-
----
-
-### `lintDockerfileWithHadolint(root, absPath)`
-
-Основна точка входу модуля: виконує `hadolint` для одного `Dockerfile` і повертає уніфікований результат.
-
-**Сигнатура:**
-
-```js
-export function lintDockerfileWithHadolint(
-  root: string,
-  absPath: string
-): {
-  ok: boolean,
-  stdout: string,
-  stderr: string,
-  via: string
-}
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію. Використовується одночасно як `cwd` для дочірнього процесу і як база для `posixRel`.
-- `absPath` — абсолютний шлях до конкретного `Dockerfile` (або файлу, який треба перевірити hadolint’ом).
-
-**Повертає об’єкт із полями:**
-
-- `ok` — `true`, якщо `hadolint` завершився з кодом виходу `0` (порушень немає). `false` — у будь-якому іншому випадку: інструмент знайшов проблеми, не запустився, або не зміг бути встановленим/знайденим.
-- `stdout` — stdout процесу hadolint як рядок (UTF-8). При помилці отримання інструмента — порожній рядок.
-- `stderr` — stderr процесу hadolint як рядок. Якщо інструмент не вдалося отримати, тут міститься українська інструкція з установки (`brew install hadolint` / `scoop install hadolint` / посилання на GitHub Releases) разом із повідомленням оригінальної помилки.
-- `via` — завжди константа `'hadolint'`. Поле залишене для зворотної сумісності з API, де раніше міг бути ще варіант на кшталт `'docker'`; зараз інших значень не повертається.
-
-**Алгоритм:**
-
-1. Обчислює відносний шлях `rel = posixRel(root, absPath)`.
-2. Намагається отримати шлях до бінарника через `hadolintPath = ensureTool('hadolint')`.
-   - Якщо `ensureTool` кидає виняток, функція **перехоплює** його і повертає об’єкт з `ok: false`, порожнім `stdout`, інструктивним `stderr` (текст помилки + поради з установки) і `via: 'hadolint'`. На цьому виконання завершується.
-3. Викликає `spawnSync(hadolintPath, [rel], { cwd: root, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 })`:
-   - `cwd: root` — щоб hadolint бачив правильну робочу директорію і `rel` коректно резолвився.
-   - `encoding: 'utf8'` — `stdout`/`stderr` одразу приходять як рядки, а не `Buffer`.
-   - `maxBuffer: 10 МіБ` — захист від великих обсягів виводу при множинних попередженнях.
-4. Формує результат: `ok = local.status === 0`, `stdout`/`stderr` приходять з процесу (з фолбеком на порожній рядок через `??`), `via: 'hadolint'`.
-
-**Side effects:**
-
-- Може ініціювати **авто-install** `hadolint` через `ensureTool` (мережа, brew/scoop/завантаження GitHub Release, запис у локальний кеш інструментів), якщо інструмент відсутній і авто-install не вимкнено `N_CURSOR_NO_AUTO_INSTALL`.
-- Синхронно запускає дочірній процес `hadolint`, що блокує цикл подій Node.js до завершення (через `spawnSync`).
-- Не пише в stdout/stderr поточного процесу самостійно — увесь вивід hadolint повертає викликачу.
-- Не змінює `process.cwd()` поточного процесу (тільки `cwd` дочірнього).
-
-**Обробка помилок:**
-
-- Виняток від `ensureTool` ловиться і конвертується у м’який `ok: false` з підказкою.
-- Помилки запуску `spawnSync` (наприклад, права доступу) **не обгортаються окремо**: у такому разі `spawnSync` повертає об’єкт з `status: null` і `error`-полем, відповідно `ok` буде `false`, а `stdout`/`stderr` — порожніми (через `??`). Поле `error` об’єкта `spawnSync` у результат не транслюється.
-- Ненульовий `status` від самого `hadolint` (тобто знайдені порушення) трактується як `ok: false`, але `stderr`/`stdout` несуть звіт hadolint для подальшого парсингу/виводу користувачу.
-
-## Залежності
-
-### Node.js (стандартні)
-
-- `node:child_process` — імпортується `spawnSync` для синхронного запуску `hadolint`.
-- `node:path` — імпортуються `relative` і `sep` для побудови відносного шляху з нормалізацією роздільників.
-
-### Внутрішні (моноpепо)
-
-- `../../../scripts/lib/ensure-tool.mjs` — функція `ensureTool(name)`, яка:
-  - повертає абсолютний шлях до бінарника;
-  - намагається знайти його у `PATH`, у локальному кеші інструментів;
-  - за потреби виконує авто-install через `brew` (macOS), `scoop` (Windows) чи GitHub Release (Linux);
-  - кидає виняток, якщо інструмент недоступний і авто-install неможливий / вимкнено `N_CURSOR_NO_AUTO_INSTALL`.
-
-### Зовнішні (runtime)
-
-- Бінарник `hadolint` (нативний; брати з `brew`, `scoop`, GitHub Release). **Не** використовується `docker run hadolint/hadolint` — Docker-fallback явно прибраний.
-
-### Імпорт-споживачі (всередині правила `docker`)
-
-- `./check.mjs` — скіл `check-docker`: разова перевірка обраних `Dockerfile`-ів.
-- `../../lint/lint.mjs` — скіл `run-docker`: інтеграція в загальний `lint`-конвеєр.
-
-## Потік виконання / Використання
-
-Типовий сценарій використання модуля викликачем:
-
-1. Викликач (наприклад, `check-docker` або `run-docker`) визначає `root` репозиторію і список абсолютних шляхів до `Dockerfile`-ів.
-2. Для кожного шляху викликається `lintDockerfileWithHadolint(root, absPath)`.
-3. Модуль:
-   - нормалізує шлях у POSIX-форму (`posixRel`);
-   - резолвить `hadolint` через `ensureTool` (можливо з авто-install);
-   - синхронно запускає `hadolint <rel>` у `cwd = root`;
-   - повертає `{ ok, stdout, stderr, via }`.
-4. Викликач інтерпретує результат:
-   - `ok === true` → файл чистий, нічого не виводити (або вивести позитивний статус);
-   - `ok === false` → показати `stdout`/`stderr` користувачу, зарахувати як порушення; якщо `stderr` містить інструкцію з установки — повідомити користувача, як отримати інструмент.
-
-### Приклад використання
-
-```js
-import { lintDockerfileWithHadolint, posixRel } from './docker-hadolint.mjs'
-
-const root = process.cwd()
-const absPath = '/abs/path/to/repo/services/api/Dockerfile'
-
-const result = lintDockerfileWithHadolint(root, absPath)
-
-if (!result.ok) {
-  console.error(`hadolint failed for ${posixRel(root, absPath)} (via=${result.via})`)
-  if (result.stdout) console.error(result.stdout)
-  if (result.stderr) console.error(result.stderr)
-  process.exitCode = 1
-}
-```
-
-### Поведінка за відсутності `hadolint`
-
-- Якщо `hadolint` відсутній і `N_CURSOR_NO_AUTO_INSTALL` **не** виставлена, `ensureTool` спробує встановити бінарник автоматично (за платформою).
-- Якщо `N_CURSOR_NO_AUTO_INSTALL` виставлена або авто-install не вдався, `lintDockerfileWithHadolint` повертає:
-  - `ok: false`,
-  - `stdout: ''`,
-  - `stderr: 'Не вдалося отримати hadolint (<повідомлення>). Встанови: brew install hadolint (macOS) / scoop install hadolint (Windows) / https://github.com/hadolint/hadolint/releases (Linux).'`,
-  - `via: 'hadolint'`.
-- Завдяки м’якій обробці викликач може коректно показати інструкцію користувачу замість аварійного завершення.
-
-### Особливості та обмеження
-
-- **Синхронність**: усі виклики блокуючі (`spawnSync`). Для пакетної перевірки сотень файлів варіант — викликати модуль із зовнішнього оркестратора, який сам керує паралелізмом (з урахуванням обмежень середовища).
-- **Один файл за виклик**: функція передає у `hadolint` рівно один аргумент `rel`. Для масової перевірки слід викликати функцію в циклі — це свідомий вибір, щоб уніфікувати результат і прив’язку до конкретного файлу.
-- **Розмір буфера**: `maxBuffer = 10 МіБ` достатньо для звичайних `Dockerfile`-звітів; для аномально великих виводів значення доведеться змінювати на рівні форку модуля.
-- **`via` константно `'hadolint'`**: поле залишене для майбутньої сумісності, але наразі ніколи не приймає інших значень.
-- **Стабільність шляхів**: завдяки `posixRel` повідомлення про порушення містять однакові шляхи з прямими слешами на всіх ОС — це важливо для дифу логів у CI.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/docker/lib/docs/index.md

@@ -6,9 +6,9 @@ resource: npm/rules/docker/lib/
 
 # npm/rules/docker/lib
 
-| Файл | Тип |
-|---|---|
-| [docker-hadolint.mjs](docker-hadolint.md) | JS Module |
-| [docker-mirror.mjs](docker-mirror.md) | JS Module |
+| Файл                                              | Тип       |
+| ------------------------------------------------- | --------- |
+| [docker-hadolint.mjs](docker-hadolint.md)         | JS Module |
+| [docker-mirror.mjs](docker-mirror.md)             | JS Module |
 | [docker-native-addon.mjs](docker-native-addon.md) | JS Module |
-| [docker-nginx-user.mjs](docker-nginx-user.md) | JS Module |
+| [docker-nginx-user.mjs](docker-nginx-user.md)     | JS Module |

package/rules/docker/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. `lint()` — lint-поверхня; важка реалізація лишається
+ * у js/-хелпері `js/lint.mjs` (main.mjs тонкий — лише re-export).
+ * @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)
+}
+
+export { lint } from './js/lint.mjs'
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/efes/docs/fix.md

@@ -14,16 +14,16 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 
 2. Запуск у режимі CLI.
-    *   Виконується при запуску через CLI.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Повертає код виходу.
+   - Виконується при запуску через CLI.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Повертає код виходу.
 
 ## Публічний API
 

package/rules/efes/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/efes/
 
 # npm/rules/efes
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/efes/docs/main.md

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

package/rules/efes/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/feedback/docs/fix.md

@@ -12,11 +12,11 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 
 ## Публічний API
 

package/rules/feedback/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/feedback/
 
 # npm/rules/feedback
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/feedback/docs/main.md

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

package/rules/feedback/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/ga/docs/fix.md

@@ -12,11 +12,11 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 
 ## Публічний API
 

package/rules/ga/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/ga/
 
 # npm/rules/ga
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

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/js/docs/index.md

@@ -6,7 +6,7 @@ resource: npm/rules/ga/js/
 
 # npm/rules/ga/js
 
-| Файл | Тип |
-|---|---|
-| [lint.mjs](lint.md) | JS Module |
+| Файл                          | Тип       |
+| ----------------------------- | --------- |
+| [lint.mjs](lint.md)           | JS Module |
 | [workflows.mjs](workflows.md) | JS Module |

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/fix.md

@@ -14,16 +14,16 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 
 2. Запуск у режимі CLI.
-    *   Виконується як автономний скрипт.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Перевіряє результат прогону для встановлення коду виходу.
+   - Виконується як автономний скрипт.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Перевіряє результат прогону для встановлення коду виходу.
 
 ## Публічний API
 

package/rules/graphql/docs/index.md

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