@7n/rules 1.0.0

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

@@ -0,0 +1,226 @@
+---
+type: JS Module
+title: graphql-gql-scan.mjs
+resource: npm/rules/graphql/lib/graphql-gql-scan.mjs
+docgen:
+  crc: 3743391b
+---
+
+Модуль `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/graphql/lib/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/graphql/lib
+resource: npm/rules/graphql/lib/
+---
+
+# npm/rules/graphql/lib
+
+| Файл                                        | Тип       |
+| ------------------------------------------- | --------- |
+| [graphql-gql-scan.mjs](graphql-gql-scan.md) | JS Module |

package/rules/graphql/lib/graphql-gql-scan.mjs

@@ -0,0 +1,146 @@
+/**
+ * Пошук tagged template **`gql\`…\``** у джерелах для правила graphql.mdc.
+ *
+ * Для **`.vue`** береться лише вміст `<script>` / `<script setup>` (паралельна реалізація екстрактора;
+ * аналог у `rules/vue/js/packages/vue-forbidden-imports.mjs` — модулі не діляться кодом, щоб уникати
+ * cross-rule імпортів і тримати кожне правило самодостатнім).
+ * Семантику визначає **oxc-parser** (`program`): рекурсивний обхід AST, збіг лише для **Identifier** з іменем **`gql`** як тега шаблону.
+ */
+import { parseSync } from 'oxc-parser'
+
+const VUE_EXTENSION_RE = /\.vue$/u
+const SOURCE_FILE_RE = /\.(vue|[cm]?[jt]sx?)$/u
+const VUE_SCRIPT_BLOCK_RE = /<script\b[^>]*>([\s\S]*?)<\/script>/gi
+
+/**
+ * Витягує з SFC лише код усередині `<script>` блоків, ігноруючи `<template>` і `<style>`.
+ * @param {string} sfc вміст .vue файлу
+ * @returns {string} конкатенований текст усіх блоків `<script>` (через подвійний переклад рядка)
+ */
+function extractVueScriptBlocks(sfc) {
+  const chunks = []
+  VUE_SCRIPT_BLOCK_RE.lastIndex = 0
+  let m = VUE_SCRIPT_BLOCK_RE.exec(sfc)
+  while (m) {
+    chunks.push(m[1])
+    m = VUE_SCRIPT_BLOCK_RE.exec(sfc)
+  }
+  return chunks.join('\n\n')
+}
+
+/**
+ * Підбирає текст для сканування: для .vue — лише script-блоки, інакше — увесь вміст.
+ * @param {string} content сирий вміст файлу
+ * @param {string} filePath відносний шлях (для вибору режиму)
+ * @returns {string} текст для `parseSync`
+ */
+function contentForGqlScan(content, filePath) {
+  if (filePath.endsWith('.vue')) {
+    return extractVueScriptBlocks(content)
+  }
+  return content
+}
+
+/**
+ * Мова для Oxc за шляхом файлу (розширення).
+ * @param {string} filePath віртуальний або реальний шлях
+ * @returns {'js' | 'jsx' | 'ts' | 'tsx'} мова для Oxc парсера
+ */
+function langFromPath(filePath) {
+  const lower = filePath.toLowerCase()
+  if (lower.endsWith('.tsx')) {
+    return 'tsx'
+  }
+  if (lower.endsWith('.ts') || lower.endsWith('.mts') || lower.endsWith('.cts')) {
+    return 'ts'
+  }
+  if (lower.endsWith('.jsx')) {
+    return 'jsx'
+  }
+  return 'js'
+}
+
+/**
+ * Віртуальний шлях для парсера: SFC розбираємо як TypeScript.
+ * @param {string} relativePath відносний шлях до файлу
+ * @returns {string} шлях із заміненим розширенням для SFC
+ */
+function virtualPathForParse(relativePath) {
+  if (relativePath.endsWith('.vue')) {
+    return relativePath.replace(VUE_EXTENSION_RE, '.ts')
+  }
+  return relativePath
+}
+
+/**
+ * Чи містить AST хоча б один `gql` tagged template.
+ * @param {unknown} node корінь або вузол AST
+ * @returns {boolean} true якщо знайдено тег gql
+ */
+function astContainsGqlTag(node) {
+  if (node === null || node === undefined) {
+    return false
+  }
+  if (typeof node !== 'object') {
+    return false
+  }
+  if (Array.isArray(node)) {
+    return node.some(n => astContainsGqlTag(n))
+  }
+  if (node.type === 'TaggedTemplateExpression') {
+    const tag = node.tag
+    if (tag?.type === 'Identifier' && tag.name === 'gql') {
+      return true
+    }
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key !== 'loc' && key !== 'range' && astContainsGqlTag(value)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Перевіряє один файл: є у скрипті (або у всьому не-vue) tagged template з тегом **`gql`**.
+ * @param {string} content сирий вміст файлу
+ * @param {string} relativePath відносний шлях (posix)
+ * @returns {boolean} true, якщо знайдено `gql`…``
+ */
+export function sourceFileHasGqlTaggedTemplate(content, relativePath) {
+  const scan = contentForGqlScan(content, relativePath)
+  const pathForLang = virtualPathForParse(relativePath)
+  const lang = langFromPath(pathForLang)
+  try {
+    const result = parseSync(pathForLang, scan, { lang, sourceType: 'module' })
+    if (result.errors?.length) {
+      return false
+    }
+    return astContainsGqlTag(result.program)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Чи підлягає файл скануванню за розширенням (`.vue`, `.[cm]?[jt]sx?`).
+ * @param {string} relativePath відносний шлях
+ * @returns {boolean} true якщо файл підлягає скануванню
+ */
+export function isGqlScanSourceFile(relativePath) {
+  return SOURCE_FILE_RE.test(relativePath)
+}
+
+/**
+ * Чи пропустити файл (декларації, auto-imports/components.d.ts) — типові generated-файли,
+ * у яких немає авторського коду з gql-тегами.
+ * @param {string} relativePosix шлях з posix-слешами
+ * @returns {boolean} true якщо файл потрібно пропустити
+ */
+export function shouldSkipFileForGqlScan(relativePosix) {
+  const base = relativePosix.split('/').pop() || ''
+  if (base === 'auto-imports.d.ts' || base === 'components.d.ts') {
+    return true
+  }
+  return Boolean(relativePosix.endsWith('.d.ts'))
+}

package/rules/graphql/main.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "gqlTaggedTemplate" } }

package/rules/graphql/main.mdc

@@ -0,0 +1,8 @@
+---
+description: GraphQL у коді (tagged template `gql`) — GraphQL Config і розширення VS Code
+version: '1.1'
+globs: "**/*.{vue,js,mjs,cjs,ts,tsx,jsx}"
+alwaysApply: false
+---
+
+Якщо у `.vue` або JavaScript / TypeScript джерелах зустрічається **tagged template literal** з тегом **`gql`**, у корені репозиторію мають бути `.graphqlrc.yml` та запис `graphql.vscode-graphql` у `.vscode/extensions.json`.

package/rules/graphql/tooling/concern.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": {
+    "scope": "full",
+    "glob": ["**/*.{vue,js,jsx,mjs,cjs,ts,tsx,mts,cts}", ".graphqlrc.yml", ".vscode/extensions.json"]
+  }
+}

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

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/graphql/tooling/main.mjs
+docgen:
+  crc: b165a889
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл відповідає за перевірку наявності необхідних умов для використання GraphQL у проєкті. Він констатує, чи існує файл конфігурації за визначенням константи `GRAPHQL_RC_FILENAME` (".graphqlrc.yml"), і перевіряє, чи встановлене у VS Code необхідне розширення з ідентифікатором `REQUIRED_GRAPHQL_VSCODE_EXTENSION` ("graphql.vscode-graphql"), спираючись на конфігурацію `extensions.json`. При виявленні відсутності цих елементів, код ініціює повідомлення відповідно до маркерів (graphql.mdc), щоб повідомити про необхідність налаштування.
+
+## Поведінка
+
+GRAPHQL_RC_FILENAME: Позначає очікуваний файл конфігурації GraphQL у корені проєкту.
+REQUIRED_GRAPHQL_VSCODE_EXTENSION: Вказує необхідне розширення VS Code для підтримки GraphQL.
+main: Виконує повну перевірку конфігурації GraphQL, скануючи джерела на наявність GraphQL tagged template та валідуючи відповідність конфігурацій.
+
+Поведінка:
+GRAPHQL_RC_FILENAME — Позначає очікуваний файл конфігурації GraphQL у корені проєкту.
+REQUIRED_GRAPHQL_VSCODE_EXTENSION — Вказує необхідне розширення VS Code для підтримки GraphQL.
+main — Виконує повну перевірку конфігурації GraphQL, скануючи джерела на наявність GraphQL tagged template та валідуючи відповідність конфігурацій. При виявленні GraphQL tagged template повідомляє про необхідність наявності `.graphqlrc.yml` та перевіряє конфігурацію `extensions.json` відповідно до `graphql.mdc`.
+
+## Публічний API
+
+- GRAPHQL_RC_FILENAME — Вказує на очікуваний конфігураційний файл GraphQL у корені проєкту.
+- REQUIRED_GRAPHQL_VSCODE_EXTENSION — Визначає необхідне розширення VS Code для роботи з GraphQL.
+- main — Перевіряє наявність конфігурації `.graphqlrc.yml` та розширення `graphql.vscode-graphql`, якщо в коді є шаблони, марковані `gql`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/graphql/tooling/main.mjs

@@ -0,0 +1,129 @@
+/** @see ./docs/tooling.md */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import {
+  isGqlScanSourceFile,
+  shouldSkipFileForGqlScan,
+  sourceFileHasGqlTaggedTemplate
+} from '../lib/graphql-gql-scan.mjs'
+import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
+import { runConftestBatch } from '../../../scripts/lib/run-conftest-batch.mjs'
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+
+/** Очікуваний файл GraphQL Config у корені (graphql.mdc). */
+export const GRAPHQL_RC_FILENAME = '.graphqlrc.yml'
+
+/** Розширення VS Code з graphql.mdc. */
+export const REQUIRED_GRAPHQL_VSCODE_EXTENSION = 'graphql.vscode-graphql'
+
+/**
+ * Збирає абсолютні шляхи source-файлів, які підлягають скануванню на gql templates.
+ * @param {string} root абсолютний шлях кореня
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<string[]>} список кандидатів
+ */
+async function collectScanCandidates(root, ignorePaths) {
+  /** @type {string[]} */
+  const candidates = []
+  await walkDir(
+    root,
+    absPath => {
+      const rel = relative(root, absPath).split('\\').join('/')
+      if (shouldSkipFileForGqlScan(rel) || !isGqlScanSourceFile(rel)) {
+        return
+      }
+      candidates.push(absPath)
+    },
+    ignorePaths
+  )
+  return candidates
+}
+
+/**
+ * Повертає відносні шляхи файлів, де знайдено gql tagged template.
+ * @param {string} root абсолютний шлях кореня
+ * @param {string[]} candidates абсолютні шляхи файлів-кандидатів
+ * @returns {Promise<string[]>} відносні шляхи файлів зі збігами
+ */
+async function collectGqlHits(root, candidates) {
+  /** @type {string[]} */
+  const hits = []
+  for (const absPath of candidates) {
+    const rel = relative(root, absPath).split('\\').join('/')
+    const content = await readFile(absPath, 'utf8')
+    if (sourceFileHasGqlTaggedTemplate(content, rel)) {
+      hits.push(rel)
+    }
+  }
+  return hits
+}
+
+/**
+ * Делегує валідацію `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions`
+ * через `runConftestBatch`. Викликається лише після того, як JS виявив `gql` у дереві
+ * (умовне правило — без gql цей крок не запускається).
+ * @param {(msg: string) => void} pass success-репортер
+ * @param {(msg: string) => void} fail fail-репортер
+ * @returns {void}
+ * @param {string} cwd корінь репозиторію
+ */
+function checkExtensionsRecommendation(pass, fail, cwd) {
+  const pathRel = '.vscode/extensions.json'
+  const pathAbs = join(cwd, pathRel)
+  if (!existsSync(pathAbs)) {
+    fail(
+      `${pathRel} не існує — створи файл і додай у recommendations ${REQUIRED_GRAPHQL_VSCODE_EXTENSION} (graphql.mdc)`
+    )
+    return
+  }
+  const violations = runConftestBatch({
+    policyDirRel: 'graphql/vscode_extensions',
+    namespace: 'graphql.vscode_extensions',
+    files: [pathAbs]
+  })
+  if (violations.length === 0) {
+    pass(`${pathRel} відповідає graphql.vscode_extensions (rego)`)
+    return
+  }
+  for (const v of violations) fail(v.message)
+}
+
+/**
+ * Перевіряє graphql.mdc: умовна вимога .graphqlrc.yml і graphql.vscode-graphql
+ * за наявності gql tagged templates.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст lint-прогону (cwd тощо)
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат зі зібраними violations
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+
+  const root = ctx.cwd
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const candidates = await collectScanCandidates(root, ignorePaths)
+  const hits = await collectGqlHits(root, candidates)
+
+  if (hits.length === 0) {
+    pass(
+      `Немає tagged template з тегом gql у .vue / JS / TS джерелах (переглянуто ${candidates.length} файлів) — .graphqlrc.yml не вимагається`
+    )
+    return reporter.result()
+  }
+
+  pass(`Знайдено gql\`…\` у ${hits.length} файлі(ах): ${hits.slice(0, 5).join(', ')}${hits.length > 5 ? '…' : ''}`)
+
+  if (existsSync(join(root, GRAPHQL_RC_FILENAME))) {
+    pass(`${GRAPHQL_RC_FILENAME} існує`)
+  } else {
+    fail(
+      `Відсутній ${GRAPHQL_RC_FILENAME} у корені — додай GraphQL Config (graphql.mdc), бо в проєкті є gql template literals`
+    )
+  }
+
+  checkExtensionsRecommendation(pass, fail, root)
+
+  return reporter.result()
+}

package/rules/graphql/tooling/tooling.mdc

@@ -0,0 +1,13 @@
+## Умовна вимога `.graphqlrc.yml`
+
+Якщо у `.vue` або в JavaScript / TypeScript джерелах (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.jsx` тощо) зустрічається **tagged template literal** з тегом **`gql`** (типово `gql\`query …\``для GraphQL-запиту), у **корені репозиторію** має бути файл **`.graphqlrc.yml`** ([GraphQL Config](https://the-guild.dev/graphql/config/docs)).
+
+Перевірка є **умовною**: якщо жодного `gql\`…\`` у дереві не знайдено — `.graphqlrc.yml` не вимагається.
+
+Підстав свої шляхи до схеми та до файлів з операціями; приклад орієнтиру:
+
+```yaml title=".graphqlrc.yml"
+schema: node_modules/@nitra/efes-shared/schema/maya.graphql
+documents:
+  - '**/*.{vue,js,ts,tsx}'
+```

package/rules/graphql/vscode_extensions/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "engine": "rego",
+    "files": { "single": ".vscode/extensions.json", "required": true },
+    "missingMessage": ".vscode/extensions.json не існує — додай рекомендовані розширення (graphql.mdc)"
+  }
+}

package/rules/graphql/vscode_extensions/docs/fix-vscode_extensions.md

@@ -0,0 +1,24 @@
+---
+type: JS Module
+title: fix-vscode_extensions.mjs
+resource: npm/rules/graphql/vscode_extensions/fix-vscode_extensions.mjs
+docgen:
+  crc: 3353fe17
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 80
+  issues: short-behavior,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Використовується для генерації шаблонів, які забезпечують уніфіковану структуру для корекції інцидентів у розширеннях VS Code. Це гарантує послідовність підходу до обробки помилок, що підвищує передбачуваність процесу виправлення.
+
+## Поведінка
+
+1. Додає шаблони для виправлення VS Code Extensions.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/graphql/vscode_extensions/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/graphql/vscode_extensions
+resource: npm/rules/graphql/vscode_extensions/
+---
+
+# npm/rules/graphql/vscode_extensions
+
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [fix-vscode_extensions.mjs](fix-vscode_extensions.md) | JS Module |

package/rules/graphql/vscode_extensions/fix-vscode_extensions.mjs

@@ -0,0 +1 @@
+export { patterns } from '../../../scripts/lib/fix/vscode-ext-add.mjs'