@nitra/cursor 1.8.93 → 1.8.95

package/README.md

@@ -16,7 +16,7 @@
 {
   "$schema": "https://unpkg.com/@nitra/cursor/schemas/n-cursor.json",
   "rules": ["npm-module", "text"],
-  "skills": ["fix"]
+  "skills": ["fix", "lint"]
 }
 ```
 

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/package.json

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

package/scripts/check-abie.mjs

@@ -543,7 +543,7 @@ export function kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode) {
  * Чи YAML відносно кореня належить до **`${pkgRel}/k8s/**`** поза піддеревами **`ua/`** та **`ru/`** (base-шар abie).
  * @param {string} relFromRoot відносний шлях від кореня
  * @param {string} pkgRelFromRoot каталог пакета відносно кореня (без завершального слеша після імені пакета)
- * @returns {boolean}
+ * @returns {boolean} `true`, якщо шлях належить до base-шару abie
  */
 export function isK8sYamlInAbiePackageExcludingUaRuOverlays(relFromRoot, pkgRelFromRoot) {
   const normRel = relFromRoot.replaceAll('\\', '/')
@@ -560,7 +560,7 @@ export function isK8sYamlInAbiePackageExcludingUaRuOverlays(relFromRoot, pkgRelF
  * З HTTPRoute-документа рахує **`backendRefs`** до **`auth-run-hl`** / **`filelint-hl`** і порушення **`namespace: dev`**.
  * @param {unknown} obj корінь YAML
  * @param {string} rel відносний шлях (повідомлення)
- * @returns {{ refCount: number, errors: string[] }}
+ * @returns {{ refCount: number, errors: string[] }} кількість посилань і список порушень
  */
 function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
   /** @type {string[]} */
@@ -582,26 +582,22 @@ function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
   }
   let refCount = 0
   for (const rule of rules) {
-    if (rule === null || typeof rule !== 'object' || Array.isArray(rule)) {
-      continue
-    }
-    const brs = /** @type {Record<string, unknown>} */ (rule).backendRefs
-    if (!Array.isArray(brs)) {
-      continue
-    }
-    for (const br of brs) {
-      if (br === null || typeof br !== 'object' || Array.isArray(br)) {
-        continue
-      }
-      const brRec = /** @type {Record<string, unknown>} */ (br)
-      const name = brRec.name
-      if (typeof name !== 'string' || !ABIE_SHARED_CROSS_NS_BACKEND_SET.has(name)) {
-        continue
-      }
-      refCount++
-      const ns = brRec.namespace
-      if (typeof ns !== 'string' || ns !== 'dev') {
-        errors.push(`${rel}: HTTPRoute backendRefs до ${name} має містити namespace: dev (abie.mdc)`)
+    if (rule !== null && typeof rule === 'object' && !Array.isArray(rule)) {
+      const brs = /** @type {Record<string, unknown>} */ (rule).backendRefs
+      if (Array.isArray(brs)) {
+        for (const br of brs) {
+          if (br !== null && typeof br === 'object' && !Array.isArray(br)) {
+            const brRec = /** @type {Record<string, unknown>} */ (br)
+            const name = brRec.name
+            if (typeof name === 'string' && ABIE_SHARED_CROSS_NS_BACKEND_SET.has(name)) {
+              refCount++
+              const ns = brRec.namespace
+              if (typeof ns !== 'string' || ns !== 'dev') {
+                errors.push(`${rel}: HTTPRoute backendRefs до ${name} має містити namespace: dev (abie.mdc)`)
+              }
+            }
+          }
+        }
       }
     }
   }
@@ -613,7 +609,7 @@ function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
  * @param {string} root корінь репозиторію
  * @param {string} pkgAbs абсолютний шлях до каталогу пакета
  * @param {string[]} yamlFilesAbs усі **yaml** під **k8s** (як **findK8sYamlFiles**)
- * @returns {Promise<{ refCount: number, baseErrors: string[] }>}
+ * @returns {Promise<{ refCount: number, baseErrors: string[] }>} кількість посилань і базові помилки
  */
 export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yamlFilesAbs) {
   const pkgRel = relative(root, pkgAbs).replaceAll('\\', '/') || pkgAbs
@@ -622,34 +618,36 @@ export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yam
   const baseErrors = []
   for (const abs of yamlFilesAbs) {
     const rel = relative(root, abs).replaceAll('\\', '/') || abs
-    if (!isK8sYamlInAbiePackageExcludingUaRuOverlays(rel, pkgRel)) {
-      continue
-    }
-    let raw
-    try {
-      raw = await readFile(abs, 'utf8')
-    } catch {
-      continue
-    }
-    const body = stripBom(raw)
-    const lines = body.split(/\r?\n/u)
-    const first = lines[0] ?? ''
-    const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
-    /** @type {import('yaml').Document[]} */
-    let docs
-    try {
-      docs = parseAllDocuments(rest)
-    } catch {
-      continue
-    }
-    for (const doc of docs) {
-      if (doc.errors.length > 0) {
-        continue
+    if (isK8sYamlInAbiePackageExcludingUaRuOverlays(rel, pkgRel)) {
+      let raw
+      try {
+        raw = await readFile(abs, 'utf8')
+      } catch {
+        raw = undefined
+      }
+      if (raw !== undefined) {
+        const body = stripBom(raw)
+        const lines = body.split(/\r?\n/u)
+        const first = lines[0] ?? ''
+        const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
+        /** @type {import('yaml').Document[] | undefined} */
+        let docs
+        try {
+          docs = parseAllDocuments(rest)
+        } catch {
+          docs = undefined
+        }
+        if (docs !== undefined) {
+          for (const doc of docs) {
+            if (doc.errors.length === 0) {
+              const obj = doc.toJSON()
+              const st = httpRouteDocSharedCrossNsBackendStats(obj, rel)
+              refCount += st.refCount
+              baseErrors.push(...st.errors)
+            }
+          }
+        }
       }
-      const obj = doc.toJSON()
-      const st = httpRouteDocSharedCrossNsBackendStats(obj, rel)
-      refCount += st.refCount
-      baseErrors.push(...st.errors)
     }
   }
   return { refCount, baseErrors }
@@ -659,7 +657,7 @@ export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yam
  * Рахує операції JSON6902 з **`path`**: **`/spec/rules/…/backendRefs/…/namespace`** та **`value`** overlay.
  * @param {string} combined сукупний текст patch **HTTPRoute**
  * @param {'ua' | 'ru'} mode overlay
- * @returns {number}
+ * @returns {number} кількість знайдених патчів namespace
  */
 function countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode) {
   const re =
@@ -1073,8 +1071,8 @@ async function ensureUaRuAbieHttpRoutePatches(root, yamlFilesAbs, fail, passFn)
   /** @type {Map<string, Promise<{ refCount: number, baseErrors: string[] }>>} */
   const sharedBackendAnalysisByPkg = new Map()
   /**
-   * @param {string} pkgAbs
-   * @returns {Promise<{ refCount: number, baseErrors: string[] }>}
+   * @param {string} pkgAbs абсолютний шлях до каталогу пакета
+   * @returns {Promise<{ refCount: number, baseErrors: string[] }>} кількість посилань і базові помилки
    */
   const getSharedBackendAnalysis = pkgAbs => {
     let p = sharedBackendAnalysisByPkg.get(pkgAbs)

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-k8s.mjs

@@ -1152,7 +1152,6 @@ export function serviceSvcHlYamlHeadlessViolation(manifest) {
  *
  * Застосовується лише для **`apiVersion: networking.gke.io/v1`** і **`targetRef.kind: Service`** (або без **`kind`**).
  * Інші **`targetRef.kind`** скрипт не оцінює.
- *
  * @param {unknown} manifest корінь YAML-документа
  * @returns {string | null} текст порушення або null
  */
@@ -1182,7 +1181,6 @@ export function healthCheckPolicyTargetRefHeadlessServiceViolation(manifest) {
  * Чи об’єкт схожий на **backendRef** до **Kubernetes Service** у Gateway API.
  *
  * Вимагає числовий **`port`**, щоб не плутати з **`HTTPHeaderMatch`** тощо (там теж є **`name`**, але без **`port`**).
- *
  * @param {unknown} obj вузол у дереві **`spec`**
  * @returns {boolean} true, якщо враховуємо поле **`name`** як посилання на Service
  */

package/scripts/check-npm-module.mjs

@@ -33,7 +33,7 @@ const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
 
 /**
  * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
- * @returns {Promise<boolean>}
+ * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
  */
 async function npmSrcTreeHasJsFile() {
   const root = 'npm/src'
@@ -51,7 +51,7 @@ async function npmSrcTreeHasJsFile() {
 
 /**
  * Знаходить текстовий вміст конфігурації hk для перевірки npm-module.
- * @returns {Promise<{ path: string, text: string } | null>}
+ * @returns {Promise<{ path: string, text: string } | null>} знайдений файл або `null`
  */
 async function readHkConfig() {
   const candidates = ['hk.pkl', '.config/hk.pkl']
@@ -66,8 +66,8 @@ async function readHkConfig() {
 
 /**
  * Підрядки для hk при layout з каталогом `npm/src` і glob `src` + `.js` у команді (див. npm-module.mdc).
- * @param {string} hkText
- * @returns {string[]}
+ * @param {string} hkText текст конфігурації hk
+ * @returns {string[]} відсутні фрагменти
  */
 function missingHkSrcLayoutFragments(hkText) {
   const need = [
@@ -85,8 +85,8 @@ function missingHkSrcLayoutFragments(hkText) {
 
 /**
  * Підрядки для hk при layout з `tsconfig.emit-types.json` (див. npm-module.mdc).
- * @param {string} hkText
- * @returns {string[]}
+ * @param {string} hkText текст конфігурації hk
+ * @returns {string[]} відсутні фрагменти
  */
 function missingHkEmitTypesConfigFragments(hkText) {
   const need = ['["pre-commit"]', 'bunx -p typescript tsc', 'tsconfig.emit-types.json']
@@ -95,7 +95,7 @@ function missingHkEmitTypesConfigFragments(hkText) {
 
 /**
  * Перевіряє `npm/tsconfig.emit-types.json` на мінімальний набір опцій для `emitDeclarationOnly` у `types/`.
- * @param {unknown} parsed
+ * @param {unknown} parsed результат `JSON.parse` конфігурації
  * @returns {string[]} повідомлення про помилки (порожній — OK)
  */
 function emitTypesConfigIssues(parsed) {
@@ -128,8 +128,8 @@ function emitTypesConfigIssues(parsed) {
 
 /**
  * Шлях на дискі до файлу з поля `types` у `npm/package.json` (значення на кшталт `./types/bin/x.d.ts`).
- * @param {string} typesField
- * @returns {string | null}
+ * @param {string} typesField значення поля `types` з `package.json`
+ * @returns {string | null} абсолютний шлях або `null`
  */
 function npmTypesFileFromPackageField(typesField) {
   if (typeof typesField !== 'string' || !typesField.startsWith('./types/')) {

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)
+}

package/skills/lint/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: n-lint
+description: >-
+  Запустити кореневий bun run lint, виправити порушення й підтвердити чистий вихід
+---
+
+# n-lint — лінт проєкту через кореневий скрипт
+
+## Мета
+
+Один раз узгоджено прогнати весь ланцюжок **`lint`** з кореневого **`package.json`**, усунути помилки (авто- та вручну) і переконатися, що **`bun run lint`** завершується з кодом **`0`**.
+
+## Передумови
+
+- Поточна робоча директорія — **корінь репозиторію**, де є **`package.json`** зі скриптом **`lint`**.
+- Залежності встановлені (**`bun i`**) — якщо після правок змінювався **`package.json`** / lockfile, знову виконай **`bun i`** перед наступним запуском лінту.
+
+## Workflow
+
+1. **Запуск** — виконай повний лінт:
+
+```bash
+bun run lint
+```
+
+2. **Якщо exit code не 0** — проаналізуй вивід (останній упавший крок у ланцюжку **`lint`** часто видно з stderr / логів):
+   - Де скрипт уже робить **auto-fix** (**`--fix`**, **`markdownlint-cli2 --fix`**, **`oxfmt`** тощо) — перезапусти **`bun run lint`** після змін файлів.
+   - Де auto-fix **немає** (наприклад, **jscpd**, **cspell**, **zizmor**, перевірки без прапорця fix) — виправ код, конфіги або винятки **узгоджено з** `.cursor/rules/` (не розширюй ignore лише щоб приховати проблему без причини).
+
+3. **Цикл** — повторюй кроки 1–2, доки **`bun run lint`** не завершиться успішно. Після суттєвих правок за потреби ще раз **`bun run lint`**, щоб переконатися, що не зламав наступний крок у скрипті **`lint`**.
+
+4. **Верифікація** — фінальна перевірка (обов’язково з кодом **0**):
+
+```bash
+bun run lint
+```
+
+5. **Результат** — коротко опиши, що саме виправлено; якщо щось блокує нульовий exit code — залиш чітке пояснення й наступні кроки для людини.
+
+## Примітка
+
+Цей скіл **не** замінює **`npx @nitra/cursor check`**: **`lint`** перевіряє лінтери/формат у **`package.json`**, а **`check`** — програмні правила пакета **`@nitra/cursor`**. За потреби запускай обидва.

package/types/bin/n-cursor.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+export {}