@nitra/cursor 5.2.0 → 5.2.1

package/rules/feedback/docs/fix.md

@@ -1,140 +1,30 @@
-# `npm/rules/feedback/fix.mjs`
+---
+docgen:
+  source: npm/rules/feedback/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл є точкою входу (entry-point) для правила `feedback` у CLI-наборі `@nitra/cursor`. Він реалізує дві паралельні ролі того ж самого модуля:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликають інші частини оркестратора (наприклад, агрегований `fix`/`lint`-прогін, де всі правила запускаються послідовно з шарінгом кешу обходу файлів `walkCache`).
-2. **Standalone mode** — якщо файл стартує безпосередньо як CLI-скрипт (`bun rules/feedback/fix.mjs`), він виконується як повний аналог команди `npx @nitra/cursor fix feedback` із завантаженням конфігу, застосуванням whitelist та підсумком.
-
-Сам файл логіки правила не містить — він є тонким адаптером, що делегує роботу до спільного раннера `runStandardRule`. Стандартний потік правила, який запускається через цей адаптер: `applies → JS-concerns → policy → mdc-refs` (тобто перевіряється застосовність до проєкту, далі — JS-специфічні перевірки, далі — policy-шар, наприкінці — синхронізація посилань у відповідному `.mdc`-файлі).
-
-Модуль використовує `import.meta.dirname`, тому він повністю прив'язаний до місця свого розташування: каталог правила (`npm/rules/feedback/`) автоматично стає коренем, у якому раннер шукає `meta.json`, `feedback.mdc` та інші артефакти.
-
-## Експорти / API
-
-| Експорт | Тип                               | Призначення                                                                                          |
-| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?): Promise<number>` | Library-точка входу правила. Викликається оркестратором; повертає exit-code (0 — OK, 1 — порушення). |
-
-Side-експортів немає. Default-експорту немає.
-
-Поведінка при прямому запуску файлу як CLI (через `process.exit(await runRuleCli(...))`) — це не експорт, а top-level side-effect, активний лише коли `isRunAsCli(import.meta.url)` повертає `true`.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Призначення:** запустити правило `feedback` у library-режимі. Делегує всю роботу до `runStandardRule`, передаючи каталог поточного файлу як ідентифікатор правила.
-- **Параметри:**
-  - `ctx` — `RuleContext | undefined`. Опціональний контекст прогону. Тип імпортується через JSDoc-посилання `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`. Зокрема, контекст несе спільні структури між правилами (наприклад, `walkCache` — кеш обходу файлової системи, щоб не сканувати дерево кілька разів у разі прогону кількох правил поспіль). Якщо `ctx` не переданий, `runStandardRule` створює власний внутрішній контекст.
-- **Повертає:** `Promise<number>` — exit-code:
-  - `0` — правило застосовне і порушень не знайдено, або правило не застосовне до поточного проєкту (`applies` повернув `false`);
-  - `1` — знайдені порушення (policy / JS-concerns / mdc-refs).
-- **Side effects:** жодних прямих у цій функції. Опосередковано через `runStandardRule` можливі: читання файлів проєкту, читання `meta.json` і `feedback.mdc`, лог у stdout/stderr, мутація переданого `walkCache`.
-- **Винятки:** функція сама не кидає; будь-яка помилка приходить як rejected promise від `runStandardRule`.
-
-### Top-level standalone-блок
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Призначення:** перетворити цей же модуль на CLI-скрипт. Якщо файл був запущений напряму (а не імпортований), виконується повний CLI-цикл правила — еквівалент `npx @nitra/cursor fix feedback`.
-- **Виклик:** `runRuleCli(import.meta.dirname)` отримує абсолютний шлях до каталогу правила; всередині раннера це задає, який саме `meta.json`/`*.mdc` і `applies/policy/...`-функції підтягуються.
-- **Повертає / завершення:** результат `runRuleCli` (число) йде в `process.exit(...)`, тобто процес одразу завершується з відповідним exit-code. Це навмисно: standalone entry-point має повернути код виходу для CI/IDE-інтеграцій.
-- **Спеціальні маркери:**
-  - `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` — свідома відмова від загальної заборони `process.exit` саме тут, бо це standalone-точка входу.
-- **Side effects:** завершує процес Node/Bun.
-
-## Залежності
+# fix.mjs
 
-Файл імпортує два внутрішні модулі (relative-шляхи, без зовнішніх npm-пакетів):
-
-| Імпорт            | З файлу                                   | Що використовується                     | Роль                                                                                                                                                   |
-| ----------------- | ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Функція-предикат                        | Визначає, чи цей `.mjs`-файл був запущений напряму як CLI (через `import.meta.url`), а не імпортований як модуль.                                      |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Async-функція                           | Виконує повний CLI-цикл правила: завантаження конфігу, whitelist-фільтрацію, прогін стандартного раннера, форматування підсумку, повернення exit-code. |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Async-функція + JSDoc-тип `RuleContext` | Стандартний раннер для правил: `applies → JS-concerns → policy → mdc-refs`. Шукає артефакти у переданому каталозі.                                     |
-
-Глобали з рантайму:
-
-- `import.meta.dirname` — абсолютний шлях каталогу поточного `.mjs`-файлу (Bun / Node ≥ 20.11). Використовується як «корінь правила».
-- `import.meta.url` — file-URL модуля; передається в `isRunAsCli` для надійного порівняння з `process.argv[1]`.
-- `process.exit` — викликається лише у standalone-гілці.
-
-Зовнішні пакети не імпортуються.
-
-## Потік виконання / Використання
-
-### Сценарій A — імпорт як library
-
-```js
-import { run } from './npm/rules/feedback/fix.mjs'
-
-const code = await run(/* ctx */)
-if (code !== 0) {
-  // правило знайшло порушення
-}
-```
-
-Послідовність всередині:
-
-1. Викликається `run(ctx)`.
-2. `run` повертає `runStandardRule(import.meta.dirname, ctx)`.
-3. Усередині `runStandardRule`:
-   - перевіряє `applies` (чи правило застосовне до проєкту);
-   - проганяє JS-concerns (lint/structure);
-   - проганяє policy-перевірки;
-   - звіряє `mdc-refs` (узгодженість посилань між кодом і `feedback.mdc`).
-4. Повертається `0` або `1`.
-
-Top-level `if (isRunAsCli(...))` у цьому випадку не спрацьовує — `isRunAsCli(import.meta.url)` повертає `false`, бо стартова точка процесу — інший файл.
-
-### Сценарій B — прямий запуск як CLI
-
-```bash
-bun npm/rules/feedback/fix.mjs
-# або еквівалент:
-npx @nitra/cursor fix feedback
-```
-
-Послідовність:
-
-1. Node/Bun завантажує модуль; виконуються `import`-и.
-2. Перевіряється `isRunAsCli(import.meta.url)` → `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)`. Цей раннер:
-   - завантажує загальний конфіг проєкту;
-   - застосовує whitelist (якщо в конфізі обмежений набір правил);
-   - всередині все одно проганяє ту ж саму `runStandardRule`-логіку;
-   - друкує форматований summary;
-   - повертає exit-code.
-4. `process.exit(code)` миттєво завершує процес із отриманим кодом, який потім читає CI/IDE.
-
-### Чому дві ролі в одному файлі
+## Огляд
 
-Конвенція в `npm/rules/<id>/fix.mjs` дозволяє:
+Модуль виконує задану перевірку, ініціалізуючи її з локального файлу конфігурації. При запуску як окрема програма, він завантажує конфігурацію, перевіряє білий список та надає звіт про результати виконання. Результат виконання правила повертається як код виходу.
 
-- оркестратору проганяти всі правила одним процесом, шарячи `walkCache` (швидко, для batch-режимів);
-- розробнику запустити **одне** правило точково з шелла без обгорток і отримати CI-сумісний exit-code.
+## Поведінка
 
-Жодного дублювання логіки немає — обидві гілки в кінцевому рахунку викликають один і той самий `runStandardRule`, просто standalone-гілка додає шар CLI-обгортки (`runRuleCli`).
+1. Викликається функція `run` для виконання правила.
+2. Виконання правила відбувається шляхом ініціалізації стандартного правила з директорії цього файлу.
+3. Якщо код виконується як окрема утиліта (standalone), ініціюється повний запуск правила.
+4. Запуск правила як окремої утиліти включає завантаження конфігурації, перевірку білого списку та підведення підсумків.
+5. Результат цього запуску повертається як код виходу.
 
-## Rebuild Test
+## Публічний API
 
-Чи можна за цим документом без доступу до файлу відтворити модуль еквівалентної поведінки? Так:
+run — виконує послідовність перевірок: застосовує правила, аналізує JS-занепокоєння, порівнює з політикою та перевіряє посилання MDC.
 
-- ім'я експорту: `run`, сигнатура `(ctx) => Promise<number>`;
-- тіло: `return runStandardRule(import.meta.dirname, ctx)`;
-- top-level `if`: `isRunAsCli(import.meta.url)` → `process.exit(await runRuleCli(import.meta.dirname))`;
-- два імпорти з точно вказаних шляхів (`../../scripts/lib/run-rule-cli.mjs` для `isRunAsCli`/`runRuleCli`, `../../scripts/lib/run-standard-rule.mjs` для `runStandardRule`);
-- ESLint-disable коментар над `process.exit` для `n/no-process-exit` і `unicorn/no-process-exit`;
-- JSDoc-блок над `run` із посиланням на тип `RuleContext` через `import('...')`-нотацію.
+## Гарантії поведінки
 
-Усі ці елементи описані вище — реконструкція еквівалентного файлу можлива.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/ga/docs/fix.md

@@ -1,25 +1,27 @@
+---
+docgen:
+  source: npm/rules/ga/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
+
 # fix.mjs
 
 ## Огляд
 
-Цей файл запускає процес перевірки наявності та стану необхідних системних ресурсів. Він забезпечує швидку оцінку готовності системи до подальшої роботи, використовуючи кешовані дані для прискорення процесу. Результати перевірки використовуються для прийняття рішень щодо подальших дій.
+Модуль відповідає за запуск механізму виконання стандартного правила. Він шукає та застосовує правила, використовуючи поточний каталог як джерело. При запуску як окрема програма, він ініціює виконання команди, необхідної для застосування цього правила.
 
 ## Поведінка
 
-1.  Ініціалізує контекст прогону.
-2.  Викликає стандартне правило, використовуючи контекст.
-3.  Якщо код виконується як окремий CLI-скрипт, то:
-    1.  Викликає оркестрацію правил.
-    2.  Повертає код завершення процесу.
+1. Викликає механізм виконання стандартного правила, використовуючи поточний каталог як джерело правил.
+2. Якщо скрипт виконується як окрема програма, запускає оркестрацію командного рядка для виконання правила.
 
 ## Публічний API
 
-- run — Запускає стандартне правило, враховуючи контекст та перетворюючи його на JS-коду, політику та посилання на MDC.
-- Library mode — Викликається через CLI-оркестрацію за допомогою імпорту та функції `run`.
+run — виконує послідовність дій: застосовує правила, обробляє JS-занепокоєння, перевіряє політику та посилання MDC.
 
 ## Гарантії поведінки
 
-- Запускає процес.
-- Кеш зберігає результати попередніх прогонів.
-- Результат залежить від попередніх прогонів.
-- Немає взаємодії з мережею.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,19 +1,22 @@
+---
+docgen:
+  source: npm/rules/ga/js/lint.mjs
+  crc: 428bf482
+  score: 100
+---
+
 # lint.mjs
 
 ## Огляд
 
-Файл `lint` делегує перевірку коду інструменту, який запускається з командного рядка. Він використовується для автоматизованої перевірки коду на відповідність певним правилам. Це забезпечує консистентність та якість коду в проєкті.
+Делегує застосування правил зовнішньому інструменту командного рядка. Параметр `files` ігнорується, оскільки режим перевірки на рівні окремих файлів відсутній. Публічна функція `lint` повертає код виходу інструменту, який визначає успішність або невдачу перевірки.
 
 ## Поведінка
 
-1.  Запускає наявний CLI для перевірки правил.
-2.  Проводить аналіз всього репозиторію, ігноруючи вказаний список файлів.
-3.  Повертає код завершення процесу.
-4.  Не використовує кеш результатів.
-5.  Не здійснює взаємодії з мережею.
+1. Викликає зовнішній інструмент для перевірки коду.
+2. Повертає код виходу цього інструменту.
 
 ## Гарантії поведінки
 
-- Делегує правила до існуючого CLI.
-- Не враховує `files` в режимі per-file.
-- Не має кешування.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/ga/js/docs/workflows.md

@@ -1,32 +1,33 @@
+---
+docgen:
+  source: npm/rules/ga/js/workflows.mjs
+  crc: a9296cf1
+  score: 100
+---
+
 # workflows.mjs
 
 ## Огляд
 
-Файл перевіряє GitHub Actions workflows на відповідність певним правилам та стандартам. Він забезпечує консистентність та якість workflow, виявляючи потенційні проблеми, такі як відсутність clean/lint workflow або використання непідтримуваних інструментів. Це частина автоматизованого процесу забезпечення дотримання найкращих практик при розробці GitHub Actions.
+Модуль виявляє наявність інструменту `shellcheck` та підтверджує відповідність конфігурації проєкту правилам ga.mdc. Він перевіряє відповідність workflow-файлів Rego-полісі, наявність обов'язкових компонентів та коректність шляхів тригерів GitHub Actions. Модуль свідомо пропускає шляхи `.github` та `.git` під час перевірки.
 
 ## Поведінка
 
-- `checkShellcheckInstalled`: Перевіряє наявність бінарника `shellcheck` в системному PATH.
-- `checkGaWorkflowFiles`: Перевіряє наявність workflow-файлів з розширенням `.yml` та відсутність інших розширень.
-- `runAllGaRego`: Запускає Rego-перевірки для всіх workflow-файлів, використовуючи `conftest` для аналізу.
-- `check`: Координує всі перевірки, включаючи Rego-аналіз, перевірку workflow-структури та перевірку наявність файлів.
+checkShellcheckInstalled перевіряє наявність бінарника `shellcheck` у системному шляху, щоб забезпечити узгодженість локальних та CI-перевірок (ga.mdc).
+check виконує комплексну валідацію конфігурації проєкту щодо правил ga.mdc, включаючи структурну перевірку workflow-файлів за допомогою Rego-полісі, перевірку наявності обов'язкових компонентів, валідацію шляхів тригерів GitHub Actions, пошук залишків MegaLinter та перевірку наявності `shellcheck` (ga.mdc). При цьому ігнорує директорії `.github` та `.git`.
 
 ## Публічний API
 
-- checkShellcheckInstalled — Перевіряє наявність `shellcheck` у системі та зупиняє workflow, якщо його немає.
-- check — Перевіряє відповідність проєкту правилам валідації.
-- runAllGaRego — Запускає Rego-перевірку правил, як перший етап валідації.
-- lint-ga — Запускає перевірку `bun lint-ga` з використанням `actionlint` та `zizmor`.
+checkShellcheckInstalled — визначає, чи встановлено `shellcheck` у системному шляху. Це дозволяє `actionlint` запускати перевірки скриптів лише тоді, коли інструмент доступний локально.
+
+check — порівнює структуру проєкту з вимогами, визначеними у правилах (ga.mdc).
+
+Plan B-патерн — виконує первинну перевірку структури робочого процесу за допомогою Rego-полісі. Потім виконує перевірки на рівні JavaScript, включаючи пошук файлів та конфігурацій. Команда `bun run lint-ga` повторно викликає цю ж перевірку, використовуючи зовнішні інструменти.
 
 ## Гарантії поведінки
 
-- Гарантується наявність файлів `package.json`, `.vscode/*` та `.github/zizmor.yml`.
-- Гарантується, що workflow використовує `actions/checkout@v6` перед локальними операціями.
-- Гарантується, що workflow використовує composite action `action.yml` з `npx @nitra/cursor`.
-- Гарантується, що workflow містить `clean-ga-workflows.yml`, `clean-merged-branch.yml`, `lint-ga.yml` та `git-ai.yml`.
-- Гарантується, що workflow використовує `concurrency` для паралельного виконання.
-- Гарантується, що workflow не містить `oven-sh/setup-bun`, `actions/cache`, `bun install` у `uses` або `run`.
-- Гарантується, що workflow не використовує shell-продовження `\` у `run`.
-- Гарантується, що workflow використовує `shellcheck` локально.
-- Гарантується, що workflow перевіряє наявність файлів за допомогою `git ls-files :(glob)` та `on.*.paths`.
-- Гарантується, що workflow перевіряє наявність файлів, що залишилися від MegaLinter.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.

package/rules/graphql/js/docs/tooling.md

@@ -1,264 +1,29 @@
-# tooling.mjs
-
-## Огляд
-
-Модуль `npm/rules/graphql/js/tooling.mjs` — це **check-скрипт правила `graphql.mdc`**, який перевіряє, що репозиторій налаштований для роботи з GraphQL за наявності у коді tagged template literals `gql\`...\``.
-
-Логіка перевірки **умовна**:
-
-1. Скрипт рекурсивно обходить дерево проєкту з кореня (`process.cwd()` за замовчуванням) і збирає файли-кандидати (`.vue`, `.js`, `.ts`, `.jsx`, `.tsx` тощо) — пропускаючи службові артефакти типу `.d.ts`, `auto-imports.d.ts` тощо.
-2. Для кожного кандидата виконує AST-сканування (oxc-parser; для `.vue` — після витягування блоку `<script>`) у пошуках `gql` tagged template literal.
-3. Якщо **жодного збігу не знайдено** — перевірка завершується успішно й нічого більше не вимагає.
-4. Якщо `gql\`…\`` **знайдено хоча б в одному файлі** — модуль вимагає:
-   - наявність файлу `.graphqlrc.yml` у корені репозиторію (GraphQL Config);
-   - відповідність `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions` (тобто рекомендацію розширення VS Code `graphql.vscode-graphql`).
-
-Модуль є частиною інфраструктури `n-cursor` для перевірок правил `.mdc` і дотримується контракту check-скрипта: повертає exit code `0` при успіху й `1` при порушенні.
-
-## Експорти / API
-
-| Експорт                             | Тип                                        | Призначення                                                                             |
-| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `GRAPHQL_RC_FILENAME`               | `string` (const, `.graphqlrc.yml`)         | Очікувана назва файлу GraphQL Config у корені проєкту (з `graphql.mdc`).                |
-| `REQUIRED_GRAPHQL_VSCODE_EXTENSION` | `string` (const, `graphql.vscode-graphql`) | Ідентифікатор обов'язкового розширення VS Code, яке має бути в `recommendations`.       |
-| `check(cwd?)`                       | `async function`                           | Основна точка входу — виконує всю перевірку правила `graphql.mdc` і повертає exit code. |
-
-Внутрішні (не експортовані) хелпери:
-
-- `collectScanCandidates(root, ignorePaths)` — збір абсолютних шляхів файлів для сканування.
-- `collectGqlHits(root, candidates)` — фільтрація кандидатів за наявністю `gql` tagged template.
-- `checkExtensionsRecommendation(pass, fail, cwd)` — делегування перевірки `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions` через `conftest`.
-
-## Функції
-
-### `collectScanCandidates(root, ignorePaths)`
-
-**Сигнатура:**
-
-```js
-async function collectScanCandidates(root: string, ignorePaths: string[]): Promise<string[]>
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію, з якого починається обхід.
-- `ignorePaths` — масив абсолютних шляхів каталогів, які повністю виключаються з обходу (формується через `loadCursorIgnorePaths`).
-
-**Що робить:**
-
-- Викликає `walkDir(root, visitor, ignorePaths)` (рекурсивний обхід файлової системи).
-- Для кожного відвіданого файлу обчислює відносний шлях від `root`, нормалізує роздільники (Windows `\` → POSIX `/`).
-- Застосовує два фільтри:
-  - `shouldSkipFileForGqlScan(rel)` — пропуск службових файлів (`.d.ts`, `auto-imports.d.ts` тощо).
-  - `isGqlScanSourceFile(rel)` — допуск лише відповідних розширень (Vue/JS/TS-сімейство).
-- Накопичує **абсолютні** шляхи прийнятих файлів у масив `candidates`.
-
-**Повертає:** `Promise<string[]>` — список абсолютних шляхів файлів-кандидатів.
-
-**Side effects:** читає метадані файлової системи (через `walkDir`); записів не робить.
-
 ---
-
-### `collectGqlHits(root, candidates)`
-
-**Сигнатура:**
-
-```js
-async function collectGqlHits(root: string, candidates: string[]): Promise<string[]>
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня (для обчислення відносних шляхів у результаті).
-- `candidates` — список абсолютних шляхів файлів, отриманих від `collectScanCandidates`.
-
-**Що робить:**
-
-- Послідовно (`for-of` + `await`) для кожного абсолютного шляху:
-  - обчислює відносний шлях і нормалізує роздільники до `/`;
-  - читає вміст файлу через `readFile(absPath, 'utf8')`;
-  - викликає `sourceFileHasGqlTaggedTemplate(content, rel)` — парсер AST oxc, що враховує особливості `.vue` (витягування `<script>`);
-  - якщо результат `true` — додає **відносний** шлях до результуючого масиву `hits`.
-
-**Повертає:** `Promise<string[]>` — відносні шляхи файлів, у яких знайдено хоча б одне `gql` tagged template.
-
-**Side effects:** читання вмісту файлів з диска. Запис відсутній.
-
+docgen:
+  source: npm/rules/graphql/js/tooling.mjs
+  crc: eb6b4713
+  score: 100
 ---
 
-### `checkExtensionsRecommendation(pass, fail, cwd)`
-
-**Сигнатура:**
-
-```js
-function checkExtensionsRecommendation(
-  pass: (msg: string) => void,
-  fail: (msg: string) => void,
-  cwd: string
-): void
-```
-
-**Параметри:**
-
-- `pass` — функція-репортер «успішно» (отримана з `createCheckReporter()`).
-- `fail` — функція-репортер «порушення».
-- `cwd` — абсолютний корінь репозиторію.
-
-**Що робить:**
-
-1. Формує відносний (`.vscode/extensions.json`) і абсолютний шляхи до файлу VS Code-конфігу.
-2. Якщо файл **не існує** (`existsSync`) — викликає `fail(...)` з повідомленням про те, що треба створити файл і додати `graphql.vscode-graphql` у `recommendations`, посилаючись на `graphql.mdc`. Виходить.
-3. Інакше викликає `runConftestBatch({ policyDirRel: 'graphql/vscode_extensions', namespace: 'graphql.vscode_extensions', files: [pathAbs] })` — делегує перевірку rego-пакету conftest-у.
-4. Якщо `violations.length === 0` — викликає `pass(...)` з повідомленням про відповідність. Інакше — для кожного порушення `v` викликає `fail(v.message)`.
-
-**Повертає:** нічого (`void`). Результати фіксуються через `pass` / `fail`.
-
-**Side effects:**
-
-- читання `.vscode/extensions.json` через зовнішній conftest-процес;
-- виклик `conftest` (binary) усередині `runConftestBatch`;
-- зміна стану внутрішнього reporter-у (накопичення успіхів/порушень).
-
-**Виклик умовний:** виконується лише після того, як основна функція `check` виявила `gql` у дереві.
-
----
-
-### `check(cwd = process.cwd())`
-
-**Сигнатура:**
-
-```js
-export async function check(cwd?: string): Promise<number>
-```
-
-**Параметри:**
-
-- `cwd` — _необов'язковий_ абсолютний шлях до кореня репозиторію. За замовчуванням `process.cwd()`.
-
-**Що робить (потік):**
-
-1. Створює репортер `createCheckReporter()` і деструктурує з нього `pass`, `fail`.
-2. Завантажує список ігнорованих шляхів через `loadCursorIgnorePaths(root)`.
-3. Викликає `collectScanCandidates(root, ignorePaths)` — отримує список файлів-кандидатів.
-4. Викликає `collectGqlHits(root, candidates)` — отримує файли з `gql`.
-5. **Розгалуження:**
-   - Якщо `hits.length === 0` — викликає `pass(...)` з повідомленням «немає `gql\`…\``у джерелах, переглянуто N файлів —`.graphqlrc.yml`не вимагається» і **повертає**`reporter.getExitCode()`(зазвичай`0`).
-   - Інакше викликає `pass(...)` зі звітом про N файлів (з перших 5 з суфіксом `…` якщо більше).
-6. Перевіряє наявність `GRAPHQL_RC_FILENAME` (`.graphqlrc.yml`) у корені через `existsSync`:
-   - Існує → `pass('.graphqlrc.yml існує')`.
-   - Не існує → `fail(...)` з вимогою додати GraphQL Config (з посиланням на `graphql.mdc`).
-7. Викликає `checkExtensionsRecommendation(pass, fail, root)` для перевірки `.vscode/extensions.json`.
-8. Повертає `reporter.getExitCode()`: `0` — усі перевірки пройдені, `1` — є хоча б одне порушення.
-
-**Повертає:** `Promise<number>` — exit code (`0` — OK, `1` — порушення).
-
-**Side effects:**
-
-- читання файлової системи (метадані + вміст файлів кандидатів);
-- читання `.cursor/...` ignore-конфігу;
-- читання `.vscode/extensions.json` (опосередковано через conftest);
-- запуск процесу `conftest` через `runConftestBatch`;
-- мутація стану внутрішнього reporter-у (накопичення pass/fail-повідомлень).
-
-## Залежності
-
-### Node.js builtins
-
-| Модуль             | Що використовується | Призначення                                                                  |
-| ------------------ | ------------------- | ---------------------------------------------------------------------------- |
-| `node:fs`          | `existsSync`        | Синхронна перевірка наявності `.graphqlrc.yml` та `.vscode/extensions.json`. |
-| `node:fs/promises` | `readFile`          | Асинхронне читання вмісту файлів-кандидатів.                                 |
-| `node:path`        | `join`, `relative`  | Збирання абсолютних шляхів і обчислення відносних шляхів від кореня.         |
-
-### Внутрішні модулі репозиторію
-
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter`: фабрика репортера зі стандартним інтерфейсом `pass` / `fail` / `getExitCode()`.
-- `../lib/graphql-gql-scan.mjs`:
-  - `isGqlScanSourceFile(rel)` — предикат «це source-файл, який потенційно містить `gql`» (за розширенням);
-  - `shouldSkipFileForGqlScan(rel)` — предикат «цей файл слід ігнорувати при скануванні» (`.d.ts`, `auto-imports.d.ts` тощо);
-  - `sourceFileHasGqlTaggedTemplate(content, rel)` — AST-перевірка на наявність `gql\`...\``(через oxc-parser; для`.vue`— після витягування`<script>`).
-- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths(root)`: повертає абсолютні шляхи каталогів, повністю виключених з обходу (узгоджено з іншими check-скриптами).
-- `../../../scripts/lib/run-conftest-batch.mjs` — `runConftestBatch({ policyDirRel, namespace, files })`: запускає `conftest` з rego-пакетом і повертає масив `violations` (об'єкти з `.message`).
-- `../../../scripts/utils/walkDir.mjs` — `walkDir(root, visitor, ignorePaths)`: рекурсивний обхід файлової системи з підтримкою списку ігнорування.
-
-### Зовнішні артефакти (не імпортуються, але потрібні в runtime)
-
-- **`conftest`** як CLI-binary (запускається з `runConftestBatch`).
-- **Rego-політика** в `graphql/vscode_extensions` з namespace `graphql.vscode_extensions` (перевіряє `.vscode/extensions.json`).
-- **`.cursor/ignore`-конфіг** у корені (читається `loadCursorIgnorePaths`).
-- **`graphql.mdc`** — правило, яке цей check реалізує.
-
-## Потік виконання / Використання
-
-### Запуск як check
-
-Модуль використовується з єдиною експортованою функцією `check`:
-
-```js
-import { check } from 'npm/rules/graphql/js/tooling.mjs'
-
-const exitCode = await check() // або await check('/absolute/path/to/repo')
-process.exit(exitCode)
-```
-
-Типово викликається диспетчером check-скриптів інфраструктури `n-cursor` (наприклад, із `npm/scripts/...`), який отримує exit code й агрегує результати по всіх правилах `.mdc`.
+# tooling.mjs
 
-### Послідовність дій усередині `check`
+## Огляд
 
-```
-process.cwd() (або переданий cwd)
-        │
-        ▼
-createCheckReporter() ──► { pass, fail, getExitCode }
-        │
-        ▼
-loadCursorIgnorePaths(root) ──► ignorePaths
-        │
-        ▼
-collectScanCandidates(root, ignorePaths)
-        │   walkDir(root, visitor, ignorePaths)
-        │     filter: !shouldSkipFileForGqlScan && isGqlScanSourceFile
-        ▼
-candidates: string[]
-        │
-        ▼
-collectGqlHits(root, candidates)
-        │   for each: readFile + sourceFileHasGqlTaggedTemplate (oxc-parser AST)
-        ▼
-hits: string[]
-        │
-        ├── hits.length === 0 ──► pass("немає gql у джерелах") ──► return 0
-        │
-        └── hits.length > 0
-              │
-              ├── pass("Знайдено gql у N файлі(ах): ...")
-              │
-              ├── existsSync(.graphqlrc.yml)
-              │     ├── true  ──► pass(".graphqlrc.yml існує")
-              │     └── false ──► fail("Відсутній .graphqlrc.yml ...")
-              │
-              ├── checkExtensionsRecommendation(pass, fail, root)
-              │     ├── !existsSync(.vscode/extensions.json) ──► fail(...)
-              │     └── runConftestBatch(graphql/vscode_extensions)
-              │           ├── violations.length === 0 ──► pass(...)
-              │           └── for v of violations: fail(v.message)
-              │
-              └── return reporter.getExitCode() (0 або 1)
-```
+Визначає ім'я файлу конфігурації (`GRAPHQL_RC_FILENAME` = ".graphqlrc.yml") та обов'язкове розширення VS Code (`REQUIRED_GRAPHQL_VSCODE_EXTENSION` = "graphql.vscode-graphql"). Перевіряє наявність конфігурації в `extensions.json` (конфігурація, на яку спирається код) та підтверджує необхідність розширення для роботи з GraphQL (graphql.mdc).
 
-### Семантика повідомлень
+## Поведінка
 
-- `pass` — інформативне повідомлення про успішну перевірку (логнеться як OK, не впливає на exit code).
-- `fail` — повідомлення про порушення; навіть одне `fail` робить `getExitCode()` рівним `1`.
+GRAPHQL_RC_FILENAME: Повертає ім'я файлу конфігурації GraphQL.
+REQUIRED_GRAPHQL_VSCODE_EXTENSION: Повертає ім'я розширення VS Code, необхідне для GraphQL.
+check: Перевіряє наявність `gql` tagged template у джерелах. Якщо знайдено, вимагає наявності `.graphqlrc.yml` та валідує `.vscode/extensions.json` щодо `graphql.vscode-graphql` (graphql.mdc).
 
-### Чому перевірка умовна
+## Публічний API
 
-`graphql.mdc` вимагає `.graphqlrc.yml` і VS Code-розширення `graphql.vscode-graphql` **лише** для проєктів, де реально використовуються `gql` tagged template literals. У монорепо це дозволяє не «спамити» правилом workspace-и, що не торкаються GraphQL — check спочатку доводить релевантність (`hits.length > 0`), і лише потім вимагає інфраструктуру.
+GRAPHQL_RC_FILENAME — вказує на файл конфігурації GraphQL у корені проєкту (graphql.mdc).
+REQUIRED_GRAPHQL_VSCODE_EXTENSION — вимагає встановлення розширення `graphql.vscode-graphql` для роботи з graphql.mdc.
+check — перевіряє наявність файлу `.graphqlrc.yml` та розширення `graphql.vscode-graphql` при використанні тегів GraphQL.
 
-### Обмеження та особливості
+## Гарантії поведінки
 
-- Шляхи в `hits` та в попередженнях завжди **відносні** до `root`, з POSIX-роздільниками `/` (навіть на Windows).
-- Перші 5 файлів-збігів показуються у повідомленні `pass`; решта приховується за суфіксом `…`.
-- Якщо `gql` знайдено, але `.vscode/extensions.json` відсутній — це порушення, незалежне від rego-перевірки (тобто `fail` без виклику conftest).
-- `collectGqlHits` читає файли **послідовно** (без `Promise.all`) — це навмисно, щоб не перевантажувати I/O при великих репозиторіях.
-- Виявлення `gql` — на рівні AST (oxc-parser), а не регулярних виразів; рядкові збіги типу `// gql\`...\`` у коментарі не дають false-positive.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.