@nitra/cursor 1.8.94 → 1.8.96

package/mdc/graphql.mdc

@@ -0,0 +1,33 @@
+---
+description: GraphQL у коді (tagged template `gql`) — GraphQL Config і розширення VS Code
+alwaysApply: true
+version: '1.0'
+---
+
+Якщо в **`.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)), а в **`.vscode/extensions.json`** у масиві **`recommendations`** — запис **`graphql.vscode-graphql`**, щоб підсвітка, навігація до схеми й діагностика працювали в редакторі.
+
+Деталі виявлення `gql` у скриптах (у т.ч. лише `<script>` у SFC) — **`npm/scripts/check-graphql.mjs`** / **`npm/scripts/utils/graphql-gql-scan.mjs`**.
+
+## `.graphqlrc.yml`
+
+Підстав свої шляхи до схеми та до файлів з операціями; приклад орієнтиру:
+
+```yaml title=".graphqlrc.yml"
+schema: schema.graphql
+documents:
+  - '**/*.{vue,js,ts,tsx}'
+```
+
+## `.vscode/extensions.json`
+
+Додай **`graphql.vscode-graphql`** до наявного списку **`recommendations`** (не замінюй інші записи):
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["graphql.vscode-graphql"]
+}
+```
+
+## Перевірка
+
+`npx @nitra/cursor check graphql`

package/mdc/js-lint.mdc

@@ -1,10 +1,10 @@
 ---
 description: Перевірка JavaScript коду
 alwaysApply: true
-version: '1.11'
+version: '1.13'
 ---
 
-**oxlint**, **ESLint**, **jscpd**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. Достатньо **`@nitra/eslint-config`** у devDependencies; пакети oxlint/eslint/jscpd не додавай без потреби монорепо.
+**oxlint**, **ESLint**, **jscpd**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config` мінімум `^3.5.0`** (з ним транзитивно йде **`@e18e/eslint-plugin`** для oxlint); пакет **`@e18e/eslint-plugin`** окремо не додавай. Пакети oxlint/eslint/jscpd не додавай без потреби монорепо.
 
 ```json title=".vscode/extensions.json"
 {
@@ -22,7 +22,7 @@ version: '1.11'
     "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd ."
   },
   "devDependencies": {
-    "@nitra/eslint-config": "^3.4.0"
+    "@nitra/eslint-config": "^3.5.0"
   },
   "engines": {
     "node": ">=24"
@@ -30,6 +30,17 @@ version: '1.11'
 }
 ```
 
+У корені має бути **`.oxlintrc.json`** з підключенням **`@e18e/eslint-plugin`** через **`jsPlugins`** і правилом **`e18e/prefer-includes`** зі значенням **`error`**. Модуль **`@e18e/eslint-plugin`** не оголошуй окремо в **`package.json`** — він уже в залежностях **`@nitra/eslint-config`** (з **3.5.0**), oxlint резолвить його з **`node_modules`**.
+
+```json title=".oxlintrc.json (фрагмент)"
+{
+  "jsPlugins": ["@e18e/eslint-plugin"],
+  "rules": {
+    "e18e/prefer-includes": "error"
+  }
+}
+```
+
 У корені проєкту має бути `.jscpd.json`. Мінімум: увімкнути облік `.gitignore`, ненульовий код виходу при знаходженні клонів, консольний звіт. За потреби додай `ignore` (дзеркальні каталоги, шаблони) та `minLines`, щоб відсікти дрібні збіги:
 
 ```json title=".jscpd.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.94",
+  "version": "1.8.96",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/scripts/check-graphql.mjs

@@ -0,0 +1,97 @@
+/**
+ * Перевіряє правило graphql.mdc: наявність **`.graphqlrc.yml`** і рекомендації **`graphql.vscode-graphql`**, якщо у дереві є **`gql\`…\``**.
+ *
+ * Обхід репозиторію — **`walkDir`** від **`process.cwd()`** (пропуски як у інших check). Кандидати — **`.vue`** та **`.js`/`.ts`/`.jsx`/`.tsx`** тощо; ігнор **`.d.ts`**, **auto-imports.d.ts** тощо — **`shouldSkipFileForGqlScan`**.
+ *
+ * Виявлення **`gql`** — **oxc-parser** після витягування `<script>` з SFC (**`graphql-gql-scan.mjs`**). Якщо збігів немає — перевірка завершується успішно без вимог до конфігів.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+
+import { createCheckReporter } from './utils/check-reporter.mjs'
+import {
+  isGqlScanSourceFile,
+  shouldSkipFileForGqlScan,
+  sourceFileHasGqlTaggedTemplate
+} from './utils/graphql-gql-scan.mjs'
+import { walkDir } from './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'
+
+/**
+ * Перевіряє graphql.mdc: умовна вимога `.graphqlrc.yml` і `graphql.vscode-graphql` за наявності `gql`…``.
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  const root = process.cwd()
+  /** @type {string[]} */
+  const candidates = []
+  await walkDir(root, absPath => {
+    const rel = relative(root, absPath).split('\\').join('/')
+    if (shouldSkipFileForGqlScan(rel) || !isGqlScanSourceFile(rel)) {
+      return
+    }
+    candidates.push(absPath)
+  })
+
+  /** @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)
+    }
+  }
+
+  if (hits.length === 0) {
+    pass(`Немає tagged template з тегом gql у .vue / JS / TS джерелах (переглянуто ${candidates.length} файлів) — .graphqlrc.yml не вимагається`)
+    return reporter.getExitCode()
+  }
+
+  pass(`Знайдено gql\`…\` у ${hits.length} файлі(ах): ${hits.slice(0, 5).join(', ')}${hits.length > 5 ? '…' : ''}`)
+
+  if (!existsSync(GRAPHQL_RC_FILENAME)) {
+    fail(
+      `Відсутній ${GRAPHQL_RC_FILENAME} у корені — додай GraphQL Config (graphql.mdc), бо в проєкті є gql template literals`
+    )
+  } else {
+    pass(`${GRAPHQL_RC_FILENAME} існує`)
+  }
+
+  if (!existsSync('.vscode/extensions.json')) {
+    fail(
+      '.vscode/extensions.json не існує — створи файл і додай у recommendations graphql.vscode-graphql (graphql.mdc)'
+    )
+  } else {
+    let ext
+    try {
+      ext = JSON.parse(await readFile('.vscode/extensions.json', 'utf8'))
+    } catch {
+      fail('.vscode/extensions.json не є валідним JSON')
+      ext = null
+    }
+    if (ext) {
+      const rec = ext.recommendations
+      if (!Array.isArray(rec)) {
+        fail('.vscode/extensions.json: поле recommendations має бути масивом')
+      } else if (!rec.includes(REQUIRED_GRAPHQL_VSCODE_EXTENSION)) {
+        fail(
+          `.vscode/extensions.json: додай у recommendations "${REQUIRED_GRAPHQL_VSCODE_EXTENSION}" (graphql.mdc)`
+        )
+      } else {
+        pass(`.vscode/extensions.json: є ${REQUIRED_GRAPHQL_VSCODE_EXTENSION}`)
+      }
+    }
+  }
+
+  return reporter.getExitCode()
+}

package/scripts/check-js-lint.mjs

@@ -2,9 +2,10 @@
  * Перевіряє лінт JavaScript за правилом js-lint.mdc.
  *
  * Канонічний `lint-js`, flat ESLint з getConfig і ignore для auto-imports, рекомендації VSCode,
- * `.jscpd.json` (gitignore, exitCode, reporters, minLines), workflow `lint-js.yml` (checkout@v6,
- * setup-bun-deps, bunx без --fix), без prettier, `engines.node` >= 24. Дубль перевірки JS у `lint.yml` —
- * заборонено.
+ * `.oxlintrc.json` з `jsPlugins` (`@e18e/eslint-plugin`) і правилом `e18e/prefer-includes: error`,
+ * `@nitra/eslint-config` у devDependencies мінімум **3.5.0** (транзитивний `@e18e/eslint-plugin` для oxlint), `.jscpd.json`
+ * (gitignore, exitCode, reporters, minLines), workflow `lint-js.yml` (checkout@v6, setup-bun-deps,
+ * bunx без --fix), без prettier, `engines.node` >= 24. Дубль перевірки JS у `lint.yml` — заборонено.
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -36,6 +37,55 @@ export function isCanonicalLintJs(script) {
   return normalizeLintJsScript(script) === CANONICAL_LINT_JS
 }
 
+/**
+ * Чи діапазон `@nitra/eslint-config` у `package.json` передбачає версію з транзитивним `@e18e/eslint-plugin` (>=3.5.0).
+ *
+ * @param {unknown} versionSpec значення `devDependencies['@nitra/eslint-config']`
+ * @returns {boolean} true для `workspace:*` або першої semver у рядку >= 3.5.0
+ */
+export function nitraEslintConfigDeclaresE18eTransitive(versionSpec) {
+  const s = String(versionSpec).trim()
+  if (s.startsWith('workspace:')) {
+    return true
+  }
+  const m = s.match(/(\d+)\.(\d+)\.(\d+)/u)
+  if (!m) {
+    return false
+  }
+  const major = Number(m[1])
+  const minor = Number(m[2])
+  const patch = Number(m[3])
+  return major > 3 || (major === 3 && minor > 5) || (major === 3 && minor === 5 && patch >= 0)
+}
+
+/**
+ * Перевіряє обов’язкові поля `.oxlintrc.json` для плагіна e18e (js-lint.mdc).
+ *
+ * @param {unknown} cfg корінь JSON-конфігурації oxlint
+ * @returns {{ ok: boolean, failures: string[] }} `ok` і перелік повідомлень для `fail`
+ */
+export function verifyOxlintRcE18e(cfg) {
+  const failures = []
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {
+    return { ok: false, failures: ['.oxlintrc.json: корінь має бути об’єктом'] }
+  }
+  const o = /** @type {Record<string, unknown>} */ (cfg)
+  const jsPlugins = o.jsPlugins
+  if (!Array.isArray(jsPlugins) || !jsPlugins.includes('@e18e/eslint-plugin')) {
+    failures.push('.oxlintrc.json: jsPlugins має містити "@e18e/eslint-plugin"')
+  }
+  const rules = o.rules
+  if (!rules || typeof rules !== 'object' || Array.isArray(rules)) {
+    failures.push('.oxlintrc.json: поле rules має бути об’єктом')
+  } else {
+    const r = /** @type {Record<string, unknown>} */ (rules)
+    if (r['e18e/prefer-includes'] !== 'error') {
+      failures.push('.oxlintrc.json: у rules має бути "e18e/prefer-includes": "error"')
+    }
+  }
+  return { ok: failures.length === 0, failures }
+}
+
 /**
  * Перевіряє відповідність проєкту правилам js-lint.mdc
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
@@ -103,8 +153,16 @@ export async function check() {
       pass('package.json не містить @nitra/prettier-config')
     }
 
-    if (pkg.devDependencies?.['@nitra/eslint-config']) {
+    const nitraEslint = pkg.devDependencies?.['@nitra/eslint-config']
+    if (nitraEslint) {
       pass('@nitra/eslint-config є в devDependencies')
+      if (nitraEslintConfigDeclaresE18eTransitive(nitraEslint)) {
+        pass('@nitra/eslint-config: мінімум 3.5.0 (транзитивний @e18e/eslint-plugin для oxlint jsPlugins, js-lint.mdc)')
+      } else {
+        fail(
+          '@nitra/eslint-config: онови до мінімум "^3.5.0" — з цієї версії постачається @e18e/eslint-plugin для .oxlintrc.json (js-lint.mdc)'
+        )
+      }
     } else {
       fail('@nitra/eslint-config відсутній в devDependencies — додай: bun add -d @nitra/eslint-config')
     }
@@ -122,6 +180,29 @@ export async function check() {
     }
   }
 
+  if (existsSync('.oxlintrc.json')) {
+    let oxCfg
+    try {
+      oxCfg = JSON.parse(await readFile('.oxlintrc.json', 'utf8'))
+    } catch {
+      fail('.oxlintrc.json не є валідним JSON')
+      oxCfg = null
+    }
+    if (oxCfg !== null) {
+      pass('.oxlintrc.json існує')
+      const oxV = verifyOxlintRcE18e(oxCfg)
+      if (oxV.ok) {
+        pass('.oxlintrc.json: jsPlugins з @e18e/eslint-plugin і e18e/prefer-includes: error')
+      } else {
+        for (const msg of oxV.failures) {
+          fail(msg)
+        }
+      }
+    }
+  } else {
+    fail('.oxlintrc.json не існує — додай конфіг oxlint (js-lint.mdc)')
+  }
+
   if (existsSync('.vscode/extensions.json')) {
     let ext
     try {

package/scripts/utils/graphql-gql-scan.mjs

@@ -0,0 +1,115 @@
+/**
+ * Пошук tagged template **`gql\`…\``** у джерелах для правила graphql.mdc.
+ *
+ * Для **`.vue`** береться лише вміст `<script>` / `<script setup>` (спільна логіка з **vue-forbidden-imports**).
+ * Семантику визначає **oxc-parser** (`program`): рекурсивний обхід AST, збіг лише для **Identifier** з іменем **`gql`** як тега шаблону.
+ */
+import { parseSync } from 'oxc-parser'
+
+import {
+  contentForVueImportScan,
+  isVueImportScanSourceFile,
+  shouldSkipFileForVueImportScan
+} from './vue-forbidden-imports.mjs'
+
+/**
+ * Мова для Oxc за шляхом файлу (розширення).
+ * @param {string} filePath віртуальний або реальний шлях
+ * @returns {'js' | 'jsx' | 'ts' | 'tsx'}
+ */
+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}
+ */
+function virtualPathForParse(relativePath) {
+  if (relativePath.endsWith('.vue')) {
+    return relativePath.replace(/\.vue$/u, '.ts')
+  }
+  return relativePath
+}
+
+/**
+ * Чи містить AST хоча б один `gql` tagged template.
+ * @param {unknown} node корінь або вузол AST
+ * @returns {boolean}
+ */
+function astContainsGqlTag(node) {
+  if (node === null || node === undefined) {
+    return false
+  }
+  if (typeof node !== 'object') {
+    return false
+  }
+  if (Array.isArray(node)) {
+    return node.some(astContainsGqlTag)
+  }
+  if (node.type === 'TaggedTemplateExpression') {
+    const tag = node.tag
+    if (tag?.type === 'Identifier' && tag.name === 'gql') {
+      return true
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'loc' || key === 'range') {
+      continue
+    }
+    if (astContainsGqlTag(node[key])) {
+      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 = contentForVueImportScan(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-import scan).
+ * @param {string} relativePath відносний шлях
+ * @returns {boolean}
+ */
+export function isGqlScanSourceFile(relativePath) {
+  return isVueImportScanSourceFile(relativePath)
+}
+
+/**
+ * Чи пропустити файл (декларації, auto-imports) — ті самі критерії, що для vue-import scan.
+ * @param {string} relativePosix шлях з posix-слешами
+ * @returns {boolean}
+ */
+export function shouldSkipFileForGqlScan(relativePosix) {
+  return shouldSkipFileForVueImportScan(relativePosix)
+}