@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,264 @@
+# 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:** читання вмісту файлів з диска. Запис відсутній.
+
+---
+
+### `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`.
+
+### Послідовність дій усередині `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)
+```
+
+### Семантика повідомлень
+
+- `pass` — інформативне повідомлення про успішну перевірку (логнеться як OK, не впливає на exit code).
+- `fail` — повідомлення про порушення; навіть одне `fail` робить `getExitCode()` рівним `1`.
+
+### Чому перевірка умовна
+
+`graphql.mdc` вимагає `.graphqlrc.yml` і VS Code-розширення `graphql.vscode-graphql` **лише** для проєктів, де реально використовуються `gql` tagged template literals. У монорепо це дозволяє не «спамити» правилом workspace-и, що не торкаються GraphQL — check спочатку доводить релевантність (`hits.length > 0`), і лише потім вимагає інфраструктуру.
+
+### Обмеження та особливості
+
+- Шляхи в `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.

package/rules/graphql/lib/docs/graphql-gql-scan.md

@@ -0,0 +1,219 @@
+# graphql-gql-scan.mjs
+
+## Огляд
+
+Модуль `graphql-gql-scan.mjs` — це сканер сирцевих файлів проєкту, який визначає, чи містить файл tagged template літерал із тегом `gql` (тобто конструкцію виду `` gql`…` ``). Сканер призначений для роботи разом із правилом `graphql.mdc` і використовується інфраструктурою лінту/правил для виявлення місць, де описано GraphQL-запити у форматі вкладених шаблонних рядків.
+
+Ключові властивості:
+
+- **Підтримує** файли з розширеннями `.vue`, `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`.
+- Для **`.vue`** (Single File Component) бере **лише** вміст блоків `<script>` / `<script setup>`, ігноруючи `<template>` і `<style>`.
+- Для парсингу використовує **`oxc-parser`** (`parseSync`) — отримує повний AST і виконує **рекурсивний обхід**, шукаючи вузли `TaggedTemplateExpression` із тегом-`Identifier` з ім'ям `gql`.
+- Дозволяє пропускати типові generated-файли (`*.d.ts`, `auto-imports.d.ts`, `components.d.ts`).
+- Реалізований як **самодостатній модуль**: не імпортує функцій з інших правил (наприклад, із паралельного `vue-forbidden-imports.mjs` — там екстрактор `<script>` реалізовано окремо), щоб уникати cross-rule імпортів.
+
+Файл експортує три чисті функції: одна виконує перевірку наявності `gql`-тега, дві допоміжні класифікують шлях файлу (чи варто сканувати, чи варто пропустити).
+
+## Експорти / API
+
+Файл є ES-модулем (`.mjs`). Має такі іменовані експорти:
+
+| Експорт                          | Тип                                  | Призначення                                                               |
+| -------------------------------- | ------------------------------------ | ------------------------------------------------------------------------- |
+| `sourceFileHasGqlTaggedTemplate` | `(content, relativePath) => boolean` | Парсить вміст і повертає `true`, якщо знайдено `` gql`…` ``.              |
+| `isGqlScanSourceFile`            | `(relativePath) => boolean`          | `true` якщо файл за розширенням підлягає скануванню.                      |
+| `shouldSkipFileForGqlScan`       | `(relativePosix) => boolean`         | `true` якщо файл — типовий generated/declaration і його треба пропустити. |
+
+Default-експорту **немає**. Усі допоміжні функції (`extractVueScriptBlocks`, `contentForGqlScan`, `langFromPath`, `virtualPathForParse`, `astContainsGqlTag`) — приватні (module-scope), назовні не експонуються.
+
+## Функції
+
+### `extractVueScriptBlocks(sfc)` _(приватна)_
+
+- **Сигнатура**: `(sfc: string) => string`
+- **Параметри**:
+  - `sfc` — сирий вміст `.vue` файлу як рядок.
+- **Повертає**: рядок-конкатенацію вмісту **усіх** блоків `<script>` (включно з `<script setup>`), з'єднаних подвійним `\n\n`. Якщо `<script>` блоків немає — повертає порожній рядок.
+- **Side effects**: жодних мутацій зовнішнього стану; перед роботою примусово скидає `VUE_SCRIPT_BLOCK_RE.lastIndex = 0` (модуль-локальний `RegExp` з прапором `g` має stateful `lastIndex`), щоб попередні виклики не вплинули на новий парсинг.
+- **Алгоритм**: цикл `RegExp.exec` по глобальному регулярному виразу `VUE_SCRIPT_BLOCK_RE` — `/<script\b[^>]*>([\s\S]*?)<\/script>/gi`. Перша захопна група містить тіло блоку без обгортки.
+
+### `contentForGqlScan(content, filePath)` _(приватна)_
+
+- **Сигнатура**: `(content: string, filePath: string) => string`
+- **Параметри**:
+  - `content` — сирий вміст файлу.
+  - `filePath` — відносний шлях; використовується **лише** для перевірки розширення.
+- **Повертає**: якщо `filePath` закінчується на `.vue`, повертає результат `extractVueScriptBlocks(content)`; інакше — без змін `content`.
+- **Side effects**: немає.
+
+### `langFromPath(filePath)` _(приватна)_
+
+- **Сигнатура**: `(filePath: string) => 'js' | 'jsx' | 'ts' | 'tsx'`
+- **Параметри**:
+  - `filePath` — реальний або віртуальний шлях.
+- **Повертає** мову для `parseSync` із `oxc-parser` за пріоритетом перевірок (на lowercased рядку):
+  1. `.tsx` → `'tsx'`
+  2. `.ts` / `.mts` / `.cts` → `'ts'`
+  3. `.jsx` → `'jsx'`
+  4. усе інше → `'js'`
+- **Side effects**: немає.
+
+### `virtualPathForParse(relativePath)` _(приватна)_
+
+- **Сигнатура**: `(relativePath: string) => string`
+- **Параметри**:
+  - `relativePath` — відносний шлях до сирцевого файлу.
+- **Повертає**: для `.vue` — той самий шлях із розширенням, заміненим на `.ts` (через `VUE_EXTENSION_RE = /\.vue$/u`). Для всіх інших — повертає `relativePath` як є. Зроблено, щоб `oxc-parser` парсив SFC як TypeScript-код (бо `<script setup>` найчастіше TS).
+- **Side effects**: немає.
+
+### `astContainsGqlTag(node)` _(приватна)_
+
+- **Сигнатура**: `(node: unknown) => boolean`
+- **Параметри**:
+  - `node` — будь-який вузол AST або корінь `program`, отриманий від `parseSync`.
+- **Повертає**: `true`, якщо в дереві (поточному або будь-якому нащадку) знайдено вузол `TaggedTemplateExpression`, у якого `tag.type === 'Identifier'` **та** `tag.name === 'gql'`. Інакше — `false`.
+- **Алгоритм** (рекурсивний DFS):
+  1. Якщо `node` — `null`/`undefined` → `false`.
+  2. Якщо `typeof node !== 'object'` (примітив) → `false`.
+  3. Якщо масив — `Array.prototype.some` з рекурсивним викликом.
+  4. Якщо `node.type === 'TaggedTemplateExpression'` і його `tag` — `Identifier` з ім'ям `gql` → `true`.
+  5. Інакше — ітерація по `Object.keys(node)`, **пропускаючи** ключі `loc` та `range` (це позиційна метаінформація без AST-вузлів) і рекурсивно перевіряючи кожне значення.
+- **Side effects**: немає; функція чиста.
+
+### `sourceFileHasGqlTaggedTemplate(content, relativePath)` _(експорт)_
+
+- **Сигнатура**: `(content: string, relativePath: string) => boolean`
+- **Параметри**:
+  - `content` — сирий вміст файлу.
+  - `relativePath` — відносний posix-шлях (використовується для вибору режиму парсингу й мови).
+- **Повертає**: `true`, якщо у файлі знайдено `gql`-tagged template; `false` — в усіх інших випадках, включно з помилками парсингу та винятками.
+- **Алгоритм**:
+  1. Отримати текст для сканування: `contentForGqlScan(content, relativePath)`.
+  2. Обчислити шлях для парсера: `virtualPathForParse(relativePath)` (для SFC — `.ts`).
+  3. Визначити мову: `langFromPath(pathForLang)`.
+  4. Викликати `parseSync(pathForLang, scan, { lang, sourceType: 'module' })` всередині `try…catch`.
+  5. Якщо `result.errors?.length` істинне (парсер повернув помилки, але не кинув виняток) — повернути `false`.
+  6. Інакше — `astContainsGqlTag(result.program)`.
+  7. Будь-який `throw` від `parseSync` ловиться `catch {}` і повертається `false`.
+- **Side effects**:
+  - Викликає синхронний `parseSync` з `oxc-parser` — CPU-bound операція над текстом.
+  - **Не** мутує переданих аргументів і не модифікує жодного зовнішнього стану.
+  - Помилки парсера не пробкидаються нагору — інтерпретація: «якщо не парситься, то й `gql` ми достеменно не знаємо, тому не сигналізуємо».
+
+### `isGqlScanSourceFile(relativePath)` _(експорт)_
+
+- **Сигнатура**: `(relativePath: string) => boolean`
+- **Параметри**:
+  - `relativePath` — відносний шлях.
+- **Повертає**: `true`, якщо шлях відповідає `SOURCE_FILE_RE = /\.(vue|[cm]?[jt]sx?)$/u`, тобто закінчується на одне з: `.vue`, `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`. Інакше — `false`.
+- **Side effects**: немає.
+
+### `shouldSkipFileForGqlScan(relativePosix)` _(експорт)_
+
+- **Сигнатура**: `(relativePosix: string) => boolean`
+- **Параметри**:
+  - `relativePosix` — шлях у форматі posix (`/` як роздільник).
+- **Повертає**: `true`, якщо файл — typical generated/declaration і його не варто сканувати:
+  - Базове ім'я (останній сегмент після `/`) дорівнює `auto-imports.d.ts` **або** `components.d.ts`; **або**
+  - Шлях закінчується на `.d.ts`.
+- В інших випадках — `false`.
+- **Side effects**: немає.
+
+### Огляд приватних констант
+
+| Константа             | Значення                                  | Призначення                                                       |
+| --------------------- | ----------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
+| `VUE_EXTENSION_RE`    | `/\.vue$/u`                               | Перевірка/заміна розширення `.vue` на `.ts` у віртуальному шляху. |
+| `SOURCE_FILE_RE`      | `/\.(vue                                  | [cm]?[jt]sx?)$/u`                                                 | Класифікатор «це сирцевий файл, що підлягає скануванню». |
+| `VUE_SCRIPT_BLOCK_RE` | `/<script\b[^>]*>([\s\S]*?)<\/script>/gi` | Глобальний матч блоків `<script>` у `.vue` файлі.                 |
+
+## Залежності
+
+### Зовнішні (`import`)
+
+- **`oxc-parser`** — JavaScript-парсер на Rust (через native-bindings); експортує `parseSync(filePath, sourceCode, options)`. У цьому модулі використовується для побудови AST і визначає семантику `gql` як **tag identifier** (а не звичайного виклику функції чи стрічкового збігу).
+  - Виклик: `parseSync(pathForLang, scan, { lang, sourceType: 'module' })`.
+  - Очікувана відповідь — об'єкт `{ program, errors? }`, де `program` — корінь ESTree-сумісного AST.
+
+### Внутрішні
+
+- Цей модуль **не** імпортує жодних інших модулів проєкту. Це усвідомлене рішення: правила в `npm/rules/<rule>/` тримаються самодостатніми, щоб уникати cross-rule імпортів. Аналогічний (паралельний) екстрактор `<script>` блоків існує в `rules/vue/js/packages/vue-forbidden-imports.mjs` — модулі не діляться кодом.
+
+### Зовнішні споживачі (де модуль використовується)
+
+Експортовані функції призначені для виклику з шарів інтеграції правила `graphql.mdc` (наприклад, скриптів-перевірок `check-*.mjs` у правилі `graphql`). Конкретний caller у цьому файлі не описаний — він зовнішній відносно модуля.
+
+## Потік виконання / Використання
+
+### Типовий потік для одного файлу
+
+1. Caller обходить файли проєкту (наприклад, через `git ls-files`).
+2. Для кожного шляху викликає `isGqlScanSourceFile(relativePath)`. Якщо `false` — пропустити.
+3. Викликає `shouldSkipFileForGqlScan(relativePosix)`. Якщо `true` (наприклад, це `*.d.ts` або `auto-imports.d.ts`/`components.d.ts`) — пропустити.
+4. Читає вміст файлу з диска (як рядок UTF-8) — це робить caller, не цей модуль.
+5. Викликає `sourceFileHasGqlTaggedTemplate(content, relativePath)`:
+   - Для `.vue` — вирізаються блоки `<script>`/`<script setup>`, склеюються через `\n\n`, парсяться як TypeScript.
+   - Для решти — парситься увесь вміст з мовою, виведеною з розширення.
+   - Помилки парсера (як у `result.errors`, так і у вигляді винятків) тихо повертають `false`.
+6. Якщо повернулось `true` — caller знає, що у файлі є `` gql`…` ``-літерал, і може застосувати свою логіку правила (наприклад, обов'язково винести запит у `.gql`/`.graphql` файл, або навпаки — це очікувано і допустимо).
+
+### Приклад (псевдокод використання)
+
+```js
+import { isGqlScanSourceFile, shouldSkipFileForGqlScan, sourceFileHasGqlTaggedTemplate } from './graphql-gql-scan.mjs'
+import { readFile } from 'node:fs/promises'
+
+async function findFilesWithGqlTag(relativePaths) {
+  const hits = []
+  for (const rel of relativePaths) {
+    if (!isGqlScanSourceFile(rel)) continue
+    if (shouldSkipFileForGqlScan(rel)) continue
+    const content = await readFile(rel, 'utf8')
+    if (sourceFileHasGqlTaggedTemplate(content, rel)) {
+      hits.push(rel)
+    }
+  }
+  return hits
+}
+```
+
+### Семантичні гарантії
+
+- **Тільки `Identifier` з ім'ям `gql`**: вираз виду `gql.foo\`…\``(MemberExpression як tag) **не** буде матчитися, тому що перевіряється`tag.type === 'Identifier'`. Це навмисно — правило ловить канонічну форму `` gql`…` ``.
+- **Імпорт `gql`**: модуль не аналізує імпорти й не вимагає, щоб ідентифікатор `gql` був реально визначений у файлі — достатньо, що він використаний як тег. Перевірка походження тега — це справа окремих правил/перевірок (наприклад, `@apollo/client` vs `graphql-tag`).
+- **`.vue` без `<script>`**: SFC без скриптових блоків матиме порожній вхід для парсера → `parseSync` поверне валідний порожній AST → `astContainsGqlTag` → `false`.
+- **Невалідний код**: повертає `false` (як helpers `result.errors?.length`, так і try/catch). Це консервативна поведінка: краще пропустити, ніж дати false-positive.
+
+## Rebuild Test
+
+Цю секцію можна використати як «специфікацію»: за наведеним нижче переліком сигнатур, констант та поведінкових тверджень файл `graphql-gql-scan.mjs` можна перевідтворити з нуля.
+
+**Імпорти**:
+
+- Іменований імпорт `parseSync` з `'oxc-parser'`.
+
+**Module-scope константи**:
+
+- `VUE_EXTENSION_RE = /\.vue$/u`
+- `SOURCE_FILE_RE = /\.(vue|[cm]?[jt]sx?)$/u`
+- `VUE_SCRIPT_BLOCK_RE = /<script\b[^>]*>([\s\S]*?)<\/script>/gi`
+
+**Функції (порядок як у файлі)**:
+
+1. `function extractVueScriptBlocks(sfc)` — приватна. Скидає `VUE_SCRIPT_BLOCK_RE.lastIndex = 0`; у циклі `while` викликає `VUE_SCRIPT_BLOCK_RE.exec(sfc)`; складає захоплення `m[1]` у масив `chunks`; повертає `chunks.join('\n\n')`.
+2. `function contentForGqlScan(content, filePath)` — приватна. Якщо `filePath.endsWith('.vue')` → `extractVueScriptBlocks(content)`; інакше → `content`.
+3. `function langFromPath(filePath)` — приватна. `lower = filePath.toLowerCase()`; повертає `'tsx' | 'ts' | 'jsx' | 'js'` за пріоритетом `.tsx`, `.ts|.mts|.cts`, `.jsx`, інакше `js`.
+4. `function virtualPathForParse(relativePath)` — приватна. Якщо `.vue` → `replace(VUE_EXTENSION_RE, '.ts')`; інакше — без змін.
+5. `function astContainsGqlTag(node)` — приватна, рекурсивна. Послідовність перевірок: `null`/`undefined` → `false`; не object → `false`; масив → `some` рекурсивно; `node.type === 'TaggedTemplateExpression'` і `node.tag?.type === 'Identifier'` і `node.tag.name === 'gql'` → `true`; інакше для кожного `key` з `Object.keys(node)`, окрім `loc` і `range`, рекурсивна перевірка; за замовчуванням → `false`.
+6. `export function sourceFileHasGqlTaggedTemplate(content, relativePath)` — головна перевірка: `scan = contentForGqlScan(content, relativePath)`; `pathForLang = virtualPathForParse(relativePath)`; `lang = langFromPath(pathForLang)`; в `try`: `result = parseSync(pathForLang, scan, { lang, sourceType: 'module' })`, якщо `result.errors?.length` → `false`, інакше `astContainsGqlTag(result.program)`; у `catch` → `false`.
+7. `export function isGqlScanSourceFile(relativePath)` — повертає `SOURCE_FILE_RE.test(relativePath)`.
+8. `export function shouldSkipFileForGqlScan(relativePosix)` — обчислює `base = relativePosix.split('/').pop() || ''`; якщо `base === 'auto-imports.d.ts'` або `base === 'components.d.ts'` → `true`; якщо `relativePosix.endsWith('.d.ts')` → `true`; інакше `false`.
+
+**Експортується** саме три функції: `sourceFileHasGqlTaggedTemplate`, `isGqlScanSourceFile`, `shouldSkipFileForGqlScan`. Default-експорту немає.
+
+**Поведінкові інваріанти**:
+
+- Чисті функції (без I/O і без глобальних мутацій), окрім обережного скидання `lastIndex` на `VUE_SCRIPT_BLOCK_RE` перед `exec`-циклом.
+- Будь-яка помилка парсера (як `errors` у відповіді, так і виняток) → результат `false`.
+- Збіг лише на `Identifier`-тег з ім'ям `gql`; `gql.x\`…\`` **не** збігається.
+- Ключі `loc` і `range` ігноруються при обході AST, інакше — обходяться всі property values.

package/rules/hasura/docs/fix.md

@@ -0,0 +1,120 @@
+# fix.mjs — entry-point правила `hasura`
+
+## Огляд
+
+Файл `npm/rules/hasura/fix.mjs` — тонкий entry-point для правила з ідентифікатором `hasura` у складі CLI-пакета `@nitra/cursor`. Виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яка викликається з оркестратора CLI (наприклад, з `runRuleCli` або з агрегаторів типу `n-fix`), що дозволяє запускати правило в межах загального прогону всіх правил без породження окремого процесу.
+2. **Standalone mode** — якщо файл виконується безпосередньо (через `bun rules/<id>/fix.mjs` або `node rules/<id>/fix.mjs`), він виступає самостійним CLI-входом, повністю еквівалентним `npx @nitra/cursor fix hasura`: підвантажує config, застосовує whitelist, друкує summary та повертає процесний exit-code.
+
+Уся фактична логіка правила (послідовність кроків `applies → JS-concerns → policy → mdc-refs`) винесена в спільну реалізацію `runStandardRule` із бібліотечного шару `scripts/lib/`. Файл-обгортка несе лише прив'язку правила до власної директорії (через `import.meta.dirname`) та dispatch між двома режимами запуску.
+
+Відповідає конвенції двороль­ового `fix.mjs`, ухваленій для всіх «стандартних» правил у `npm/rules/*/`, тож має мінімальну поверхню коду й не містить специфіки `hasura`: тип правила, скоупи, перевірки та поліcі описуються деінде (`meta.json`, `hasura.mdc`, `js/`, `policy/`).
+
+## Експорти / API
+
+| Експорт | Тип                                      | Призначення                                                                                                                      |
+| ------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-mode прогін правила в спільному CLI orchestration. Повертає `0` при відсутності порушень або `1` при наявності порушень. |
+
+Файл не має `default`-експорту й не експортує жодних інших символів.
+
+Поведінка при безпосередньому запуску файлу як скрипта — побічний ефект (top-level `await runRuleCli(...)` + `process.exit(...)`) і не є частиною програмного API.
+
+## Функції
+
+### `run(ctx)`
+
+Сигнатура: `export function run(ctx)`.
+
+- **Параметри:**
+  - `ctx` (`RuleContext`, опційний) — контекст прогону, що передається з оркестратора. Тип імпортовано (через JSDoc-tag `@param`) з `../../scripts/lib/run-standard-rule.mjs`. Очікувані поля контексту (за конвенцією `runStandardRule`) — спільні для всіх правил, серед них зокрема `walkCache` (кеш обходу файлової системи, щоб не повторювати walk між кількома правилами в одному прогоні). Якщо `ctx` не передано (`undefined`), `runStandardRule` сам ініціалізує мінімально необхідний контекст.
+- **Повертає:** `Promise<number>` — exit-code правила:
+  - `0` — застосовні файли пройшли всі етапи (`applies → JS-concerns → policy → mdc-refs`) без виявлених порушень.
+  - `1` — знайдено принаймні одне порушення (або зафіксована помилка валідації, що інтерпретується як failure).
+- **Side effects:**
+  - Делегує всю роботу `runStandardRule(import.meta.dirname, ctx)`, який, своєю чергою, читає файли правила (`meta.json`, `*.mdc`, `js/*.mjs`, `policy/*.rego`) із директорії, обходить цільові файли проєкту, друкує діагностичні повідомлення у stdout/stderr та повертає підсумкове число порушень. Сам `run` стану не модифікує.
+  - Прив'язує правило до своєї директорії саме через `import.meta.dirname`, тож при переміщенні файлу `fix.mjs` правило автоматично «переїде» разом із його артефактами (без хардкоду шляхів).
+
+### Безіменна процедура top-level (standalone-блок)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Тип:** виконується один раз під час завантаження модуля.
+- **Параметри:** немає (CLI-аргументи зчитуються всередині `runRuleCli` через `process.argv`).
+- **Повертає:** нічого (виконує `process.exit`).
+- **Side effects:**
+  - `isRunAsCli(import.meta.url)` визначає, чи модуль завантажено як прямий entry-point (а не як `import`).
+  - У випадку прямого запуску викликає `runRuleCli(import.meta.dirname)`, який повертає числовий exit-code, і негайно завершує процес із цим кодом через `process.exit`.
+  - Через `process.exit` подальші асинхронні задачі (мікротаски, відкриті ресурси) можуть бути обірвані — це свідомо: standalone entry-point повинен повертати чіткий код для CI/IDE-інтеграцій.
+- **Локальні правила лінту:**
+  - Поряд із викликом стоїть прагма `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE`, оскільки за загальним правилом `process.exit` заборонений, але для CLI-входів дозволений.
+
+## Залежності
+
+### Внутрішні (відносні імпорти)
+
+- `../../scripts/lib/run-rule-cli.mjs`
+  - `isRunAsCli(metaUrl: string): boolean` — детектор «чи запущено модуль як скрипт». Зазвичай порівнює `import.meta.url` із URL виконуваного скрипта (`process.argv[1]`), щоб розрізнити `import` та прямий запуск.
+  - `runRuleCli(ruleDir: string): Promise<number>` — повноцінний CLI-runner: парсить аргументи, читає глобальний config (whitelist, severity, опції), запускає правило з директорії `ruleDir` і друкує summary. Повертає exit-code.
+- `../../scripts/lib/run-standard-rule.mjs`
+  - `runStandardRule(ruleDir: string, ctx?: RuleContext): Promise<number>` — стандартна послідовність кроків для «звичайного» правила: `applies → JS-concerns → policy → mdc-refs`. Це публічне ядро правил-обгорток на кшталт `fix.mjs`.
+  - `RuleContext` (тип) — імпортовано лише в JSDoc для типізації параметра `run`.
+
+### Зовнішні
+
+Прямих залежностей від npm-пакетів файл не має. Усі сторонні бібліотеки, які можуть знадобитися (наприклад, walker, парсер `.mdc`, OPA-обгортки тощо), використовуються транзитивно через `run-standard-rule.mjs` та `run-rule-cli.mjs`.
+
+### Залежність від файлів-побратимів у директорії правила
+
+Хоча `fix.mjs` сам нічого з них не читає, `runStandardRule(import.meta.dirname)` спирається на сусідні артефакти у тій же директорії правила `hasura/`:
+
+- `meta.json` — метадані правила (id, scope, опції тощо);
+- `hasura.mdc` — людинозрозумілий опис правила у форматі Cursor `.mdc`;
+- `js/` — JS-перевірки правила (`check-*.mjs`, fix-helpers);
+- `policy/` — Rego-полісі для OPA-кроку.
+
+Тож структурно файл `fix.mjs` має сенс лише як частина повної папки правила.
+
+## Потік виконання / Використання
+
+### Сценарій A — Library mode (з оркестратора)
+
+1. Оркестратор (`n-cursor` CLI, агрегатор скілів, тести) робить `import { run } from '<path>/npm/rules/hasura/fix.mjs'`.
+2. Викликає `await run(ctx)`, передаючи контекст із попередньо побудованим `walkCache` та іншими опціями.
+3. `run` синхронно повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`.
+4. `runStandardRule`:
+   - читає `meta.json` із директорії правила;
+   - проганяє послідовність `applies` (фільтр цільових файлів) → JS-concerns (динамічно підвантажені `js/check-*.mjs`) → policy (OPA з `policy/*.rego`) → mdc-refs (валідація `.mdc`-посилань);
+   - агрегує знахідки й повертає кількість порушень як exit-code (`0`/`1`).
+5. Оркестратор підсумовує exit-коди всіх правил.
+
+### Сценарій B — Standalone CLI
+
+1. Користувач/CI виконує `bun npm/rules/hasura/fix.mjs [args...]`.
+2. На завантаженні модуля Node/Bun обчислює `isRunAsCli(import.meta.url)` — для прямого запуску результат `true`.
+3. Виконується `await runRuleCli(import.meta.dirname)`:
+   - парсинг CLI-аргументів (`--whitelist`, `--severity`, прапори `-q`/`-v` тощо — деталі в `run-rule-cli.mjs`);
+   - підвантаження конфіг-файлу пакета;
+   - застосування whitelist;
+   - виклик внутрішнього еквівалента `runStandardRule` для цієї ж директорії;
+   - друк summary-таблиці результатів.
+4. `process.exit(<exit-code>)` миттєво завершує процес зі значенням, яке повернув `runRuleCli`.
+
+### Типові випадки використання
+
+- **CI:** `bun npm/rules/hasura/fix.mjs` як standalone-крок у пайплайні; ненульовий exit-code зриває build.
+- **Локально:** `npx @nitra/cursor fix hasura` запускає той самий entry-point через диспетчер CLI пакета (а не напряму).
+- **Інтеграція в IDE:** редактор може імпортувати `run` і викликати його в окремому процесі для отримання структурованого результату по правилу `hasura` (наприклад, через виклик `bun -e "import('...fix.mjs').then(m => m.run())"`).
+- **Агрегатори скілів** (наприклад, `n-fix`): паралельно або послідовно імпортують `run` із усіх правил `npm/rules/*/fix.mjs`, передають спільний `ctx` із `walkCache`, щоб уникнути повторного обходу файлової системи.
+
+### Технічні зауваження щодо реалізації
+
+- `import.meta.dirname` (Node ≥ 20.11 / Bun) повертає абсолютний шлях до директорії модуля без потреби в `fileURLToPath(import.meta.url)`. Це поточний рекомендований спосіб локалізації власної директорії в ESM-модулях.
+- Прапор `await` у `process.exit(await runRuleCli(...))` працює завдяки top-level await у ESM — додаткової `main()`-обгортки не потрібно.
+- Свідомо обираний `process.exit` (а не «м'який» вихід через `process.exitCode = ...`) гарантує детермінований код повернення для CI/IDE навіть якщо хтось у фоновому таску щось «недописав».
+- Файл нейтральний щодо помилок: `runStandardRule` та `runRuleCli` самі вирішують, чи виносити exception у консоль і конвертувати її в exit-code; `fix.mjs` не обгортає виклики в `try/catch`.