@nitra/cursor 3.22.0 → 3.23.1

package/rules/ga/lint/docs/lint.md

@@ -0,0 +1,209 @@
+# `npm/rules/ga/lint/lint.mjs`
+
+## Огляд
+
+Модуль `lint.mjs` — це **CLI-обгортка над канонічним `lint-ga`** (правило `ga.mdc`), яка виконує комплексну перевірку GitHub Actions workflow-файлів проєкту. Модуль не є самостійним перевіряльником: він агрегує кілька стадій external-tools і делегує JS/Rego-частину перевірок в `rules/ga/fix.mjs::check()`.
+
+Ключові зони відповідальності:
+
+1. **Авто-встановлення обов'язкових бінарників** — `shellcheck` і `conftest` через `ensureTool` (підбирається менеджер пакетів per-platform: `brew`/`scoop`/GitHub Release).
+2. **Preflight для `uv`** — м'яка перевірка, що `uv` (а отже `uvx`) є в `PATH`; інакше друкується hint з командами встановлення й функція повертає `1` без авто-install.
+3. **Послідовний запуск трьох стадій перевірки** workflow-ів:
+   - `bunx github-actionlint` — синтаксис/семантика GH Actions, включно з вбудованим `shellcheck` у `run:` блоках (звідси preflight на `shellcheck`).
+   - `uvx zizmor --offline --collect=workflows .` — second-stage security-аудит workflow на ризики (через `uv`/`uvx`).
+   - `rules/ga/fix.mjs::check()` — Rego-полісі (батч `conftest` для `npm/policy/ga/`) **плюс** JS cross-file перевірки правил `ga.mdc`. Це та сама перевірка, що й `npx @nitra/cursor check ga`, тож `lint-ga` є суперсетом цієї підкоманди.
+4. **Серіалізація запуску** через `runStandardLint(import.meta.dirname, steps)` згідно з каноном патерну `lint-*` (див. `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд») — без прямого `withLock`.
+
+Plan B-патерн (rego-authoritative): сама Rego-полісі `npm/policy/ga/` запускає `rules/ga/fix.mjs::check()` як перший крок — `lint.mjs` про це не знає. Раніше `lint.mjs` сам спавнив `conftest` per-workflow для `ga.<name>` і `ga.workflow_common` (PoC); тепер уся логіка централізована в `rules/ga/fix.mjs`, тому одне джерело істини без дублювання між `lint-ga` і `npx @nitra/cursor check ga`.
+
+Чому preflight на `shellcheck` обов'язковий: без нього `bunx github-actionlint` **мовчки** пропускає shell-перевірки у `run:` блоках; локально `bun lint-ga` лишається зеленим, а CI на `ubuntu-latest` (де `shellcheck` передвстановлений) падає. `ensureTool('shellcheck')` усуває цю різницю.
+
+Чому `uv` — окремо й лише як hint: бінарник `uv` не входить у реєстр `ensureTool` для авто-install у цьому проєкті, тому модуль обмежується інформативною підказкою з командами встановлення (brew / curl / pip), щоб користувач не отримав неінформативну помилку від `uvx zizmor`.
+
+Модуль експортує одну іменовану стрілкову функцію `runLintGaCli`, яку імпортує `bin/n-cursor.js` як обробник підкоманди `lint-ga`.
+
+## Експорти / API
+
+| Символ         | Тип                             | Експорт                | Опис                                                                                                                                                                   |
+| -------------- | ------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runLintGaCli` | `() => Promise<number>` (arrow) | `export const` (named) | Точка входу CLI-команди `lint-ga`. Обгортає `runLintGaSteps` у `runStandardLint(import.meta.dirname, ...)` — серіалізація + стандартні timing/exit-code/log конвенції. |
+
+Жодних інших експортів модуль не надає: усі допоміжні функції (`resolvePreflightBin`, `printPreflightMissingMessage`, `preflight`, `runLintGaSteps`) і константа `UV_PREFLIGHT` — внутрішні.
+
+JSDoc-typedef `PreflightDep` описує форму внутрішніх preflight-конфігів і не експортується.
+
+## Функції
+
+### `resolvePreflightBin(dep)`
+
+```
+function resolvePreflightBin(dep: PreflightDep): string | null
+```
+
+- **Параметри:**
+  - `dep: PreflightDep` — опис preflight-залежності з полями `bin`, `winBins`, `explanation`, `install`, `successMsg`.
+- **Повертає:** `string | null` — абсолютний шлях до бінарника або `null`, якщо нічого не знайдено в `PATH`.
+- **Поведінка:**
+  - Якщо `platform === 'win32'` (з `node:process`), спершу ітерує `dep.winBins` (наприклад, `['uv.exe']`) і повертає перший резолвлений шлях.
+  - Якщо жоден `winBins` не знайдено або платформа не Windows — фолбек на `resolveCmd(dep.bin)`.
+- **Side effects:** немає (читання `PATH` через `resolveCmd` — pure-resolve).
+
+### `printPreflightMissingMessage(dep)`
+
+```
+function printPreflightMissingMessage(dep: PreflightDep): void
+```
+
+- **Параметри:** `dep: PreflightDep`.
+- **Повертає:** `void`.
+- **Поведінка:** друкує у `stderr` блок із кількох рядків:
+  1. `❌ <bin> не знайдено в PATH.` (червоний хрестик у вигляді емодзі).
+  2. Пояснення з `dep.explanation` (одинарний відступ на 3 пробіли).
+  3. Заголовок `Встанови:` і список команд із `dep.install` з відступом на 5 пробілів.
+  4. Фінальний рядок-вказівка: `Деталі: ga.mdc → секція про lint-ga.`
+- **Side effects:** запис у `process.stderr` через `console.error`. Жодних винятків не кидає.
+
+### `preflight(dep)`
+
+```
+function preflight(dep: PreflightDep): boolean
+```
+
+- **Параметри:** `dep: PreflightDep`.
+- **Повертає:** `boolean` — `true`, якщо бінарник знайдено в `PATH`; `false`, якщо ні.
+- **Поведінка:**
+  - Викликає `resolvePreflightBin(dep)`.
+  - На pass: друкує `dep.successMsg` через `console.log` і повертає `true`.
+  - На fail: викликає `printPreflightMissingMessage(dep)` і повертає `false`.
+- **Side effects:** запис у `stdout` (success) або `stderr` (fail) через `console.log`/`console.error`.
+
+### `runLintGaSteps()`
+
+```
+async function runLintGaSteps(): Promise<number>
+```
+
+- **Параметри:** немає.
+- **Повертає:** `Promise<number>` — `0`, якщо всі кроки успішні; інакше — exit-code першого кроку, що впав.
+- **Поведінка (послідовно):**
+  1. `ensureTool('shellcheck')` — авто-install або hard-fail (кидає виняток, який підхоплює `runStandardLint` і конвертує в `exit 1`).
+  2. `ensureTool('conftest')` — те саме.
+  3. `preflight(UV_PREFLIGHT)` — якщо `uv` не знайдено, повертає `1` без падіння (hint-only).
+  4. `runLintStep('actionlint', 'bunx', ['github-actionlint'])` → якщо код ≠ 0, повертає його.
+  5. `runLintStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])` → якщо код ≠ 0, повертає його.
+  6. Друкує заголовок `▶ check-ga (rego-полісі npm/policy/ga/ + JS cross-file перевірки)` і повертає `await checkGa()` (з `../js/workflows.mjs`).
+- **Side effects:**
+  - Можлива інсталяція пакетів через `ensureTool` (мутує систему: brew/scoop/завантаження бінарників).
+  - Спавн процесів `bunx`, `uvx` через `runLintStep`.
+  - Виклик `conftest` (батчем) і JS-перевірки всередині `checkGa()`.
+  - Запис у `stdout`/`stderr`.
+
+### `runLintGaCli` (експортовано)
+
+```
+export const runLintGaCli: () => Promise<number>
+```
+
+- **Параметри:** немає.
+- **Повертає:** `Promise<number>` — результат `runStandardLint(...)`, тобто фінальний exit-code лінт-команди.
+- **Поведінка:** обгортає `runLintGaSteps` у `runStandardLint(import.meta.dirname, runLintGaSteps)`. `import.meta.dirname` визначає каталог `npm/rules/ga/lint/`, що використовується для лок-файлу серіалізації та для службових логів.
+- **Side effects:** успадковуються від `runStandardLint` (lock-файл / cleanup) і `runLintGaSteps`.
+
+## Внутрішні дані
+
+### `UV_PREFLIGHT`
+
+```
+const UV_PREFLIGHT: PreflightDep
+```
+
+Конфігурація preflight для `uv`:
+
+- `bin: 'uv'`
+- `winBins: ['uv.exe']`
+- `explanation`: двохрядкове пояснення про те, що без `uv`/`uvx` не запуститься `uvx zizmor` (second-stage аудит workflow на ризики GitHub Actions).
+- `install`:
+  - `'macOS:        brew install uv'`
+  - `'Universal:    curl -LsSf https://astral.sh/uv/install.sh | sh'`
+  - `'pip:          pip install uv'`
+- `successMsg: '✅ uv знайдено в PATH — uvx zizmor запуститься'`
+
+### `PreflightDep` (JSDoc typedef)
+
+Структура опису однієї preflight-залежності:
+
+| Поле          | Тип        | Опис                                                                                           |
+| ------------- | ---------- | ---------------------------------------------------------------------------------------------- |
+| `bin`         | `string`   | Базове ім'я виконуваного файлу (на Windows додається `.exe` за потреби — через `winBins`).     |
+| `winBins`     | `string[]` | Альтернативні імена на Windows (наприклад, `shellcheck.exe`); якщо порожньо — фолбек на `bin`. |
+| `explanation` | `string`   | 1–2 рядки, що пояснюють наслідки відсутності бінарника.                                        |
+| `install`     | `string[]` | Список рядків з командами встановлення (друкуються «як є», з відступом).                       |
+| `successMsg`  | `string`   | Повідомлення, яке друкується на pass-шлях preflight-у.                                         |
+
+## Залежності
+
+### Зовнішні (Node.js core)
+
+- `node:process` — імпортується `platform` (рядок типу `'darwin' | 'linux' | 'win32' | ...`) для гілки Windows у `resolvePreflightBin`.
+
+### Внутрішні (проєктні)
+
+- `../js/workflows.mjs` — імпорт `check as checkGa`. Виконує Rego-полісі (батч `conftest` для `npm/policy/ga/`) і JS cross-file перевірки правил `ga.mdc`. Це фінальний крок `runLintGaSteps`.
+- `../../../scripts/utils/resolve-cmd.mjs` — `resolveCmd(name): string | null`. Pure-resolve бінарника у `PATH` (без спавну).
+- `../../../scripts/lib/run-lint-step.mjs` — `runLintStep(label, cmd, args): number`. Стандартизований обгортковий спавн одного кроку lint-у з консистентним логом і exit-code-семантикою.
+- `../../../scripts/lib/run-standard-lint.mjs` — `runStandardLint(dirname, fn): Promise<number>`. Канонічна серіалізація lint-команди (lock-файл, тривалість, sentry-style cleanup). Згідно з `.cursor/rules/scripts.mdc` (секція «Серіалізація важких CLI-команд»), цей хелпер заміняє прямий `withLock` у lint-обгортках.
+- `../../../scripts/lib/ensure-tool.mjs` — `ensureTool(name): void`. Перевіряє наявність бінарника в `PATH` і автоматично встановлює його через відповідний менеджер пакетів per-platform (brew/scoop/GitHub Release). Кидає виняток на нездатність встановити.
+
+### Зовнішні CLI-інструменти (запускаються в рантаймі)
+
+- `shellcheck` — авто-install через `ensureTool`. Потрібен для shell-перевірок у `run:` блоках, які виконує `actionlint`.
+- `conftest` — авто-install через `ensureTool`. Використовується **всередині** `checkGa()` для виконання Rego-полісі з `npm/policy/ga/`.
+- `uv` / `uvx` — hint-only preflight. Потрібен для запуску `uvx zizmor`.
+- `bunx` / `github-actionlint` — виконується через `runLintStep('actionlint', 'bunx', ['github-actionlint'])`.
+- `uvx` / `zizmor` — виконується через `runLintStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])`.
+
+## Потік виконання / Використання
+
+### Інтеграція в CLI
+
+Модуль експортує `runLintGaCli`, яку імпортує `bin/n-cursor.js` як обробник підкоманди:
+
+```
+npx @nitra/cursor lint-ga
+# або
+bun lint-ga
+```
+
+### Сценарій типового запуску (happy path)
+
+1. `runLintGaCli()` → викликає `runStandardLint(import.meta.dirname, runLintGaSteps)` — отримується lock на `npm/rules/ga/lint/`, починається timing.
+2. Усередині `runLintGaSteps`:
+   - `ensureTool('shellcheck')` — якщо нема, авто-встановлення (brew/scoop/release).
+   - `ensureTool('conftest')` — те саме.
+   - `preflight(UV_PREFLIGHT)` — друкує `✅ uv знайдено в PATH — uvx zizmor запуститься`.
+   - `runLintStep('actionlint', 'bunx', ['github-actionlint'])` — exit `0`.
+   - `runLintStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])` — exit `0`.
+   - Лог `▶ check-ga (rego-полісі npm/policy/ga/ + JS cross-file перевірки)`.
+   - `await checkGa()` — повертає `0`.
+3. `runStandardLint` логує загальну тривалість, знімає lock і повертає `0`.
+
+### Сценарії з falure
+
+- `shellcheck` або `conftest` не встановлено й `ensureTool` не зміг встановити — виняток пробивається крізь `runLintGaSteps`, `runStandardLint` ловить його та конвертує у `exit 1`.
+- `uv` відсутній — `preflight(UV_PREFLIGHT)` друкує hint, `runLintGaSteps` повертає `1`, наступні кроки не виконуються.
+- `actionlint` повертає не-нульовий код — `runLintGaSteps` повертає цей код, `zizmor` і `checkGa()` не запускаються.
+- `zizmor` повертає не-нульовий код — те саме: одразу повертається його exit-code.
+- `checkGa()` повертає не-нульовий код — він і є фінальним результатом `runLintGaCli`.
+
+### Контракт «суперсет `check ga`»
+
+Оскільки фінальний крок `runLintGaSteps` — `checkGa()` (та сама `check`-функція з `../js/workflows.mjs`, що використовується підкомандою `npx @nitra/cursor check ga`), `lint-ga` є суперсетом цієї перевірки: він додає `actionlint` (синтаксис) і `zizmor` (security-аудит) перед `check`. Це усуває потребу запускати `check ga` окремо в pipeline-ах, що вже виконують `lint-ga`.
+
+### Канон патерну `lint-*`
+
+Файл сповідує канон патерну `lint-*` із `.cursor/rules/scripts.mdc` (секція «Серіалізація важких CLI-команд»):
+
+- Серіалізація — через `runStandardLint`, **не** через прямий `withLock`.
+- Кожна стадія — через `runLintStep` (узгоджений лог-формат, semantic exit-codes).
+- Експортована функція має назву `run<Name>Cli` (тут — `runLintGaCli`).
+- Фінальна делегація бізнес-частини — у відповідний `rules/<name>/fix.mjs::check()`, щоб бути одним джерелом істини з `npx @nitra/cursor check <name>`.

package/rules/ga/policy/clean_merged_branch/clean_merged_branch.rego

@@ -96,9 +96,9 @@ deny contains msg if {
 }
 
 # YAML 1.1 quirk: `dry_run: no` парситься як boolean false у Go-yaml (conftest).
-# Template (від `yaml` npm) теж нормалізовано до false у фікстурі.
+# Template (від `yaml` npm) читає `no` як рядок, тому нормалізуємо обидві форми.
 deny contains msg if {
-	step0.with.dry_run != expected_step0.with.dry_run # noqa: rules-style-no-equality-with-false
+	normalize_dry_run(step0.with.dry_run) != normalize_dry_run(expected_step0.with.dry_run) # noqa: rules-style-no-equality-with-false
 	msg := "clean-merged-branch.yml: with.dry_run має бути no (ga.mdc)"
 }
 
@@ -139,3 +139,12 @@ echo_deleted_branches if {
 	contains(step1.run, "Deleted branches:")
 	contains(step1.run, "${DELETED_BRANCHES}")
 }
+
+normalize_dry_run(false) := false
+
+normalize_dry_run(value) := false if lower(sprintf("%v", [value])) == "no"
+
+normalize_dry_run(value) := value if {
+	value != false # noqa: equals-pattern-matching
+	lower(sprintf("%v", [value])) != "no"
+}

package/rules/ga/policy/clean_merged_branch/template/clean-merged-branch.yml.snippet.yml

@@ -26,10 +26,9 @@ jobs:
           github_token: ${{ github.token }}
           last_commit_age_days: 90
           ignore_branches: main,dev
-          # `no` у workflow → Go-yaml парсить як bool false; тут пишемо явно false,
-          # бо template читає `yaml` (YAML 1.2), де `no` лишається рядком — а нам
-          # потрібна семантична відповідність runtime-парсингу conftest.
-          dry_run: false
+          # Action CLI accepts only yes/no. Go-yaml in conftest parses `no` as
+          # boolean false, so the Rego policy normalizes both forms.
+          dry_run: no
 
       - name: Get output
         env:

package/rules/graphql/docs/fix.md

@@ -0,0 +1,126 @@
+# `npm/rules/graphql/fix.mjs`
+
+## Огляд
+
+Файл є точкою входу до правила `graphql` у складі CLI-інструмента `@nitra/cursor`. Він поєднує дві ролі:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку зовнішня CLI-оркестрація викликає через `import + run(ctx)` як частину пакетного прогону всіх правил.
+2. **Standalone mode** — якщо файл запущено напряму (`bun rules/graphql/fix.mjs`), виконується повний еквівалент команди `npx @nitra/cursor fix graphql` із завантаженням конфігурації, whitelist та підсумком (summary).
+
+Сама логіка перевірки винесена у спільний helper `runStandardRule`, тобто `fix.mjs` для правила `graphql` — це тонкий wrapper, який лише прив'язує спільну механіку до конкретної директорії правила (через `import.meta.dirname`). Послідовність перевірки, що виконується в результаті: `applies → JS-concerns → policy → mdc-refs`.
+
+Файл є частиною стандартизованої конвенції правил `npm/rules/<id>/fix.mjs`, де `<id>` — ідентифікатор правила (тут `graphql`).
+
+## Експорти / API
+
+| Експорт | Тип                               | Призначення                                                                                                 |
+| ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?): Promise<number>` | Named export — library entry-point правила. Викликається оркестратором, який пакетно запускає набір правил. |
+
+Default export відсутній. Інших named-експортів файл не визначає.
+
+Окремий top-level `if`-блок наприкінці файла активує standalone-режим — він не є експортом, а виконується як side-effect модуля при прямому запуску.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+**Призначення.** Library-обгортка над `runStandardRule`, що запускає стандартний пайплайн правила `graphql`: `applies → JS-concerns → policy → mdc-refs`. Конкретні фази (підбір файлів, перевірка JS, policy-правила, перевірка mdc-посилань) реалізовані у спільному helper; `fix.mjs` тільки повідомляє, _яке саме_ правило виконувати, — через шлях до своєї директорії (`import.meta.dirname`), де лежать `meta.json`, `*.mdc`, підтеки `js/`, `policy/`, `lib/` тощо.
+
+**Параметри.**
+
+| Параметр | Тип                                                         | Обов'язковий | Опис                                                                                                                                                                                                                                                                            |
+| -------- | ----------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx`    | `RuleContext` (з `../../scripts/lib/run-standard-rule.mjs`) | Ні           | Контекст прогону. Передається оркестратором для перевикористання ресурсів між правилами (наприклад, `walkCache` — кеш обходу файлової системи, аби не сканувати дерево заново для кожного правила). Якщо `ctx` не передано, `runStandardRule` працює зі своїм дефолтним станом. |
+
+**Повертає.** `Promise<number>` — exit-code прогону правила:
+
+- `0` — правило пройшло без порушень (OK).
+- `1` — виявлено порушення (правило фейлиться).
+
+**Side effects.** Сам по собі `run` не має побічних ефектів у файлі — повертає `Promise`, отриманий від `runStandardRule`. Усі реальні ефекти (читання FS, друк діагностики у stdout/stderr, оновлення кешу в `ctx`) інкапсульовані в `runStandardRule`. Зокрема, у library-режимі функція **не** викликає `process.exit` — управління exit-кодом лежить на оркестраторі.
+
+### Standalone-блок (top-level `if`)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+Це не функція, а top-level side-effect модуля. Виконується одноразово при завантаженні.
+
+**Умова активації.** `isRunAsCli(import.meta.url)` повертає `true`, коли модуль завантажений як точка входу (тобто шлях файла збігається з тим, що передано Node/Bun у `process.argv`), а не імпортований як бібліотека.
+
+**Дія.** Викликає `runRuleCli(import.meta.dirname)` — повний CLI-флоу одного правила (config-loading, whitelist, summary) — і завершує процес його exit-кодом через `process.exit`. Це робить файл прямим аналогом виклику `npx @nitra/cursor fix graphql`.
+
+**Чому `process.exit` явний.** Standalone entry-point має повернути коректний exit-code для CI/IDE-інтеграції, тому два правила ESLint (`n/no-process-exit`, `unicorn/no-process-exit`) свідомо вимкнено для цього рядка коментарем-обґрунтуванням.
+
+**Чому `await` на top-level.** Файл використовує top-level `await` — це валідно для ESM-модулів. `runRuleCli` повертає `Promise<number>`, і його результат потрібен синхронно як аргумент `process.exit`.
+
+## Залежності
+
+### Внутрішні (відносні)
+
+| Модуль                                    | Імпорт                     | Роль                                                                                                      |
+| ----------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Інфраструктура standalone-режиму: визначення, чи файл запущено як CLI, та повний CLI-флоу одного правила. |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний пайплайн правила (`applies → JS-concerns → policy → mdc-refs`) і тип `RuleContext`.           |
+
+Імпорти відносні, бо `fix.mjs` лежить у `npm/rules/graphql/`, а спільні helpers — у `npm/scripts/lib/`. Два рівні `..` піднімають із `rules/graphql/` до `npm/` і потім спускають у `scripts/lib/`.
+
+### Зовнішні
+
+Прямих зовнішніх (npm) залежностей файл не оголошує. Будь-які зовнішні пакети підтягуються транзитивно через `runStandardRule` / `runRuleCli`.
+
+### Платформенні / рантайм
+
+- **ES Modules** — файл використовує синтаксис ESM (`import`, `export`), top-level `await`, `import.meta.url`, `import.meta.dirname`.
+- **`import.meta.dirname`** — доступне у сучасних Node.js (>= 20.11) та Bun. Повертає абсолютний шлях до директорії модуля; використовується як ідентифікатор правила для helpers.
+- **`process.exit`** — Node.js/Bun API; завершує процес із заданим exit-кодом.
+
+## Потік виконання / Використання
+
+### Library mode (оркестрація)
+
+1. Зовнішній код (CLI-оркестратор `@nitra/cursor`) робить `import { run } from '<...>/rules/graphql/fix.mjs'`.
+2. Оркестратор готує `ctx` (наприклад, спільний `walkCache`) і викликає `await run(ctx)`.
+3. `run` делегує виклик у `runStandardRule(import.meta.dirname, ctx)`. Helper, маючи шлях до директорії правила, читає її `meta.json`, `*.mdc`, підтеки `js/`, `policy/` і виконує стандартний пайплайн.
+4. Повертається `0` або `1`. Оркестратор агрегує коди всіх правил у фінальний exit-status.
+
+У цьому режимі `process.exit` **не** викликається — модуль не завершує процес самостійно.
+
+### Standalone mode (пряма CLI)
+
+1. Користувач запускає `bun npm/rules/graphql/fix.mjs` (або шлях через рантайм).
+2. ESM-модуль завантажується. Виконується `isRunAsCli(import.meta.url)` — повертає `true`.
+3. Викликається `await runRuleCli(import.meta.dirname)` — повний CLI-флоу (config, whitelist, summary).
+4. `process.exit(<code>)` завершує процес. Code приходить у CI/IDE як результат прогону правила.
+
+Цей режим повністю еквівалентний `npx @nitra/cursor fix graphql` і існує, щоб правило можна було запустити ізольовано — для дебагу або інтеграції з IDE-таском без участі оркестратора.
+
+### Дві ролі в одному файлі
+
+Подвійна роль (library `run` + standalone `main`) дозволяє:
+
+- **Перевикористовувати** код пайплайна — і оркестратор, і пряма CLI йдуть через однакову логіку `runStandardRule` / `runRuleCli`.
+- **Дотримуватися конвенції** `npm/rules/<id>/fix.mjs`: усі правила мають однакову структуру entry-файла, тому інструменти (IDE-завдання, скрипти scaffold) можуть запускати будь-яке правило за єдиним шляхом.
+
+### Розширення
+
+Щоб додати своєрідну поведінку правила `graphql`, не треба змінювати `fix.mjs` — достатньо покласти відповідні файли в директорію правила:
+
+- `meta.json` — метадані (id, опис).
+- `graphql.mdc` — людиночитна частина правила.
+- `js/` — JS-перевірки (фаза JS-concerns).
+- `policy/` — policy-перевірки.
+- `lib/` — спільний код правила.
+
+`runStandardRule` сам підбере й виконає те, що знайде в директорії. `fix.mjs` залишається тонким wrapper-ом.