@nitra/cursor 1.9.2 → 1.9.3

package/CHANGELOG.md

@@ -4,11 +4,17 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.9.3] - 2026-05-11
+
+### Fixed
+
+- **k8s — `pathHasK8sSegment` тепер відносно кореня репо; `.github/` явно поза скоупом:** функція `pathHasK8sSegment(filePath)` у `npm/scripts/check-k8s.mjs` та `npm/scripts/run-k8s.mjs` розбивала **абсолютний** шлях і шукала компонент `k8s`. У проєктах, де сам корінь репо називається `k8s/` (напр. `/Users/.../abie/k8s/`), сегмент `k8s` присутній в абсолютному шляху **усіх** файлів — і весь репозиторій, включно з `.github/workflows/*.yml`, потрапляв у `findK8sYamlFiles` як k8s-маніфести, після чого `checkK8sYamlFile` падав на «розширення .yml — перейменуй на .yaml» (територія `ga.mdc`, де канон протилежний). Виправлено: (1) сигнатура тепер `pathHasK8sSegment(filePath, root?)` — коли `root` передано, шлях спершу нормалізується через `node:path` `relative(root, filePath)`, і компоненти беруться **відносно кореня** (порожній relative — це сам root, повертає false); (2) `findK8sYamlFiles` у `check-k8s.mjs` і `check-abie.mjs`, а також `findK8sRoots` у `run-k8s.mjs` тепер передають `root` і додатково мають defense-in-depth ранній `return` для шляхів, що починаються з `.github/`; (3) `k8s.mdc` явно фіксує: правило стосується каталогів `k8s` відносно кореня; `.github/workflows/` і `.github/actions/` — поза скоупом (їх веде `ga.mdc`). Без `root` (юніт-тести з відносним шляхом) функція веде себе як раніше. Додано тести у `tests/check-k8s-schema.test.mjs` (worst-case з префіксом `/home/test/some/k8s/`) і `tests/run-k8s-roots.test.mjs` (інтеграційний — `findK8sRoots` у репі, корінь якого називається `k8s/`).
+
 ## [1.9.2] - 2026-05-11
 
 ### Changed
 
-- **k8s — modeline `$schema` тепер опційний; `file:…` заборонено як заглушку:** правило `k8s.mdc` уточнено — рядок `# yaml-language-server: $schema=…` обов'язковий **лише** коли для поєднання `apiVersion`/`kind` існує надійна публічна схема (kustomization / yannh / datree CRDs-catalog). Якщо публічної схеми немає, modeline **не додається зовсім** (раніше п. 5 розділу «Визначення схеми YAML» допускав `file:` за узгодженням — це створювало фальшиву видимість валідації, а автовиправлення n-fix залишало заглушковий `# yaml-language-server: $schema=file:.`). У `check-k8s.mjs`: (1) файли без modeline більше не падають як «перший рядок має бути коментарем», натомість `pass` із позначкою «без modeline — перевірка $schema пропущена»; (2) `$schema=file:…` тепер реєструється як помилка з підказкою прибрати modeline; (3) modeline нижче першого рядка все ще порушення; (4) `HttpBackendGroup` (Yandex ALB) як виняток без modeline залишається без змін. `lint-k8s` (kubeconform з прапорцем ignore-missing-schemas) продовжує покривати валідацію і для файлів без modeline. JSDoc на початку `check-k8s.mjs` оновлено.
+- **k8s — modeline `$schema` тепер опційний; `file:…` заборонено як плейсхолдер:** правило `k8s.mdc` уточнено — рядок `# yaml-language-server: $schema=…` обов'язковий **лише** коли для поєднання `apiVersion`/`kind` існує надійна публічна схема (kustomization / yannh / datree CRDs-catalog). Якщо публічної схеми немає, modeline **не додається зовсім** (раніше п. 5 розділу «Визначення схеми YAML» допускав `file:` за узгодженням — це створювало фальшиву видимість валідації, а автовиправлення n-fix залишало плейсхолдер `# yaml-language-server: $schema=file:.`). У `check-k8s.mjs`: (1) файли без modeline більше не падають як «перший рядок має бути коментарем», натомість `pass` із позначкою «без modeline — перевірка $schema пропущена»; (2) `$schema=file:…`тепер реєструється як помилка з підказкою прибрати modeline; (3) modeline нижче першого рядка все ще порушення; (4)`HttpBackendGroup`(Yandex ALB) як виняток без modeline залишається без змін.`lint-k8s`(kubeconform з прапорцем ignore-missing-schemas) продовжує покривати валідацію і для файлів без modeline. JSDoc на початку`check-k8s.mjs` оновлено.
 
 ## [1.9.1] - 2026-05-11
 

package/mdc/k8s.mdc

@@ -1,6 +1,6 @@
 ---
 description: K8s YAML — $schema (yaml-language-server); lint-k8s (kubeconform, kubescape); check-k8s
-version: '1.28'
+version: '1.29'
 globs: "**/k8s/**/*.yaml"
 alwaysApply: false
 ---
@@ -21,6 +21,8 @@ alwaysApply: false
 
 **Розширення:** усі маніфести під **`k8s`**, включно з **`kustomization.yaml`**, — лише **`.yaml`** (розширення **`.yml`** не використовуй).
 
+**Скоп — поза `.github/`:** правило стосується YAML-маніфестів у каталогах **`k8s`** (визначаються відносно кореня репо, не за абсолютним шляхом). Файли під **`.github/workflows/`** та **`.github/actions/`** ця перевірка **не** зачіпає — їхній скоп визначає **`ga.mdc`** (там канон — **`.yml`**). Це робить два правила несуперечливими навіть у проєктах, де сам корінь репо випадково має ім'я `k8s/` (тоді сегмент `k8s` присутній у абсолютному шляху всіх файлів, але **відносно кореня** його там немає).
+
 **Dockerfile / hadolint** — окреме правило **`docker.mdc`** і **`npx @nitra/cursor check docker`**.
 
 ## lint-k8s: kubeconform і kubescape

package/mdc/tauri.mdc

@@ -14,7 +14,6 @@ version: '1.0'
 }
 ```
 
-
 ## Перевірка
 
-`npx @nitra/cursor check tauri`
+`npx @nitra/cursor check tauri`

package/package.json

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

package/scripts/check-abie.mjs

@@ -323,7 +323,12 @@ async function findK8sYamlFiles(root, ignorePaths = []) {
   await walkDir(
     root,
     p => {
-      if (!pathHasK8sSegment(p)) {
+      const rel = relative(root, p).replaceAll('\\', '/')
+      // `.github/` належить `ga.mdc`; check-abie не зачіпає workflow-файли.
+      if (rel.startsWith('.github/')) {
+        return
+      }
+      if (!pathHasK8sSegment(p, root)) {
         return
       }
       if (!YAML_EXTENSION_RE.test(p)) {
@@ -760,9 +765,9 @@ async function collectDeploymentDirs(root, yamlAbs, fail) {
  * @param {string[]} yamlFilesAbs yaml під k8s
  * @param {(msg: string) => void} fail callback
  * @param {(msg: string) => void} passFn успішне повідомлення
- * @returns {Promise<void>}
+ * @returns {void}
  */
-async function ensureAbieBaseDeploymentPreemNodeSelector(root, yamlFilesAbs, fail, passFn) {
+function ensureAbieBaseDeploymentPreemNodeSelector(root, yamlFilesAbs, fail, passFn) {
   const baseFiles = yamlFilesAbs.filter(abs => isAbieK8sBaseYamlPath(relative(root, abs).replaceAll('\\', '/') || abs))
   if (baseFiles.length === 0) {
     passFn('Немає файлів у шляхах …/base/… — перевірку preem у base пропущено')
@@ -1425,9 +1430,9 @@ async function checkHttpRouteKustomization(abs, rel, mode, root, yamlFilesAbs, c
  * @param {string[]} yamlFilesAbs yaml під k8s
  * @param {(msg: string) => void} fail callback при помилці
  * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @returns {Promise<void>}
+ * @returns {void}
  */
-async function ensureAbieBaseHttpRouteHostnames(root, yamlFilesAbs, fail, passFn) {
+function ensureAbieBaseHttpRouteHostnames(root, yamlFilesAbs, fail, passFn) {
   const baseFiles = yamlFilesAbs.filter(abs => isAbieK8sBaseYamlPath(relative(root, abs).replaceAll('\\', '/') || abs))
   if (baseFiles.length === 0) {
     passFn('Немає файлів у шляхах …/k8s/base/… — перевірку HTTPRoute hostnames пропущено')
@@ -1531,8 +1536,9 @@ async function ensureNoFirebaseHostingArtifacts(root, passFn, failFn) {
  * @param {string} root корінь репозиторію
  * @param {(msg: string) => void} pass callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
  */
-async function checkCleanMergedBranch(root, pass, fail) {
+function checkCleanMergedBranch(root, pass, fail) {
   const cleanMergedPath = join(root, '.github/workflows/clean-merged-branch.yml')
   if (!existsSync(cleanMergedPath)) {
     fail(`Відсутній ${cleanMergedPath} — потрібен для ignore_branches (abie.mdc)`)

package/scripts/check-ga.mjs

@@ -365,9 +365,9 @@ const GA_PER_WORKFLOW_REGO_TARGETS = [
  * @param {string[]} ymlWorkflows відносні (від `wfDir`) імена файлів `*.yml`
  * @param {(msg: string) => void} pass callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
- * @returns {Promise<void>}
+ * @returns {void}
  */
-async function runAllGaRego(wfDir, ymlWorkflows, pass, fail) {
+function runAllGaRego(wfDir, ymlWorkflows, pass, fail) {
   for (const target of GA_PER_WORKFLOW_REGO_TARGETS) {
     if (!existsSync(target.workflow)) continue
     const violations = runConftestBatch({

package/scripts/check-k8s.mjs

@@ -349,11 +349,23 @@ const BATCH_V1BETA1_API_VERSION_LINE_RE = /^(\s*apiVersion:\s*)["']?batch\/v1bet
 
 /**
  * Чи містить шлях сегмент директорії `k8s` (рівно ця назва компонента).
- * @param {string} filePath шлях до файлу
- * @returns {boolean} true, якщо серед компонентів шляху є каталог `k8s`
- */
-export function pathHasK8sSegment(filePath) {
-  const parts = filePath.split(PATH_SPLIT_RE)
+ *
+ * Якщо передано `root`, перевірка ведеться **відносно** кореня репо — інакше випадає
+ * false-positive, коли сам корінь репо вже містить компонент `k8s` (напр.
+ * `/Users/.../abie/k8s/`): без relativize функція б повертала true для **усіх** файлів
+ * у проєкті, включно з `.github/workflows/*.yml`, які належать іншому правилу (`ga.mdc`).
+ *
+ * Без `root` (як у юніт-тестах або коли шлях уже відносний) спрацьовує старий шлях:
+ * розбиття за `/`/`\` і пошук компонента `k8s`.
+ * @param {string} filePath абсолютний або відносний шлях до файлу
+ * @param {string} [root] корінь репо для relativize (типово — без relativize)
+ * @returns {boolean} true, якщо серед компонентів шляху **відносно root** є каталог `k8s`
+ */
+export function pathHasK8sSegment(filePath, root) {
+  const target = root ? relative(root, filePath).replaceAll('\\', '/') : filePath
+  // Порожній relative означає сам root — у ньому компонента `k8s` відносно себе немає.
+  if (target === '') return false
+  const parts = target.split(PATH_SPLIT_RE)
   return parts.includes('k8s')
 }
 
@@ -1723,7 +1735,11 @@ async function findK8sYamlFiles(root, ignorePaths = []) {
   await walkDir(
     root,
     p => {
-      if (!pathHasK8sSegment(p)) return
+      const rel = relative(root, p).replaceAll('\\', '/')
+      // `.github/` належить правилу `ga.mdc` (там канон — `.yml`); не зачіпай тут навіть
+      // якщо `pathHasK8sSegment` колись зіб'ється на крайовому кейсі.
+      if (rel.startsWith('.github/')) return
+      if (!pathHasK8sSegment(p, root)) return
       if (!YAML_EXTENSION_RE.test(p)) return
       out.push(p)
     },
@@ -2890,18 +2906,11 @@ export function collectGatewayApiRouteBackendRefsWithRedundantNamespace(spec, ro
   return out
 }
 
-/**
- * Один документ: маршрут Gateway API має посилатися на **Service** з суфіксом **`-hl`**;
- * у **`backendRef`** не має дублюватися **`namespace`**, що збігається з **`metadata.namespace`** маршруту.
- * @param {string} rel відносний шлях до файлу
- * @param {number} docIndex 1-based індекс документа
- * @param {Record<string, unknown>} rec корінь маніфесту
- * @param {(msg: string) => void} fail callback помилки
- * @returns {void}
- */
 // Plan B: Gateway API маршрут backendRef з суфіксом `-hl` і redundant namespace —
 // у rego-пакеті `k8s.gateway`, виклик через `runAllK8sRego`. JS-функції
-// failIfGatewayRouteUsesNonHeadlessService, scanGatewayApiRouteBackendRefsInYamlBody видалено.
+// failIfGatewayRouteUsesNonHeadlessService, scanGatewayApiRouteBackendRefsInYamlBody видалено;
+// JSDoc-блок для них прибрано (eslint-plugin-jsdoc trip-ив на «orphan» JSDoc, який
+// прилипав до asPlainRecord як другий @returns).
 
 /**
  * Звузити `unknown` до `Record<string, unknown>` (`null`, масиви, примітиви → null).
@@ -3552,13 +3561,12 @@ function countSchemaModelines(lines) {
   return lines.filter(l => OXLINT_SCHEMA_MODELINE_RE.test(l.trim())).length
 }
 
-
 /**
  * Файл з першим документом **HttpBackendGroup** (ALB Yandex): без modeline **$schema**.
  * @param {string} rel відносний шлях
- * @param {string} baseLower basename
- * @param {string[]} lines рядки файлу
- * @param {(msg: string) => void} fail реєстрація помилки
+ * @param {string} _baseLower basename (лишений для уніфікованої сигнатури `checkK8sYamlFile*`)
+ * @param {string[]} _lines рядки файлу (лишені з тієї ж причини)
+ * @param {(msg: string) => void} _fail реєстрація помилки (rego гейтує per-document)
  * @param {(msg: string) => void} pass реєстрація успіху
  * @returns {void}
  */
@@ -3679,9 +3687,7 @@ async function checkK8sYamlFile(abs, root, fail, pass) {
     // Але `# yaml-language-server: $schema=…` дозволено **лише** у першому рядку — якщо він
     // зустрічається нижче, це порушення (yaml-language-server чекає на нього у заголовку файлу).
     if (countSchemaModelines(lines) > 0) {
-      fail(
-        `${rel}: рядок # yaml-language-server: $schema=… має бути першим у файлі (без префіксів перед #; k8s.mdc)`
-      )
+      fail(`${rel}: рядок # yaml-language-server: $schema=… має бути першим у файлі (без префіксів перед #; k8s.mdc)`)
       return
     }
     pass(`${rel}: без modeline — перевірка $schema пропущена (немає публічної схеми; k8s.mdc)`)
@@ -5965,6 +5971,10 @@ function runAllK8sRego(root, yamlFiles, fail) {
   }
 }
 
+/**
+ * Точка входу `check k8s`: повний набір перевірок маніфестів і структури `…/k8s` (див. JSDoc на початку файлу).
+ * @returns {Promise<number>} `process.exitCode`: 0 при успіху, 1 при будь-якому `fail(...)`
+ */
 export async function check() {
   const reporter = createCheckReporter()
   const { pass, fail } = reporter

package/scripts/run-k8s.mjs

@@ -13,7 +13,7 @@
  * Kubescape не має аналога цього прапорця; орієнтир цільового кластера — та сама лінія релізу (див. k8s.mdc).
  */
 import { spawnSync } from 'node:child_process'
-import { basename, dirname } from 'node:path'
+import { basename, dirname, relative } from 'node:path'
 
 import { isRunAsCli } from './cli-entry.mjs'
 import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
@@ -31,12 +31,19 @@ const DATREE_CRD_SCHEMA_LOCATION =
   'https://datreeio.github.io/CRDs-catalog/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json'
 
 /**
- * Чи містить шлях сегмент директорії `k8s`.
- * @param {string} filePath шлях до файлу
- * @returns {boolean} true, якщо серед компонентів шляху є каталог `k8s`
+ * Чи містить шлях сегмент директорії `k8s` (відносно `root`, якщо передано).
+ *
+ * Якщо корінь репо сам має компонент `k8s` (напр. `/Users/.../abie/k8s/`), без relativize
+ * функція повертала б true для **усіх** файлів проєкту — включно з `.github/workflows/*.yml`,
+ * які належать `ga.mdc`. Передавай `root` у викликах з walkDir щоб уникнути false-positive.
+ * @param {string} filePath абсолютний або відносний шлях до файлу
+ * @param {string} [root] корінь репо для relativize (типово — без relativize)
+ * @returns {boolean} true, якщо серед компонентів шляху **відносно root** є каталог `k8s`
  */
-export function pathHasK8sSegment(filePath) {
-  const parts = filePath.split(PATH_SEPARATOR_RE)
+export function pathHasK8sSegment(filePath, root) {
+  const target = root ? relative(root, filePath).replaceAll('\\', '/') : filePath
+  if (target === '') return false
+  const parts = target.split(PATH_SEPARATOR_RE)
   return parts.includes('k8s')
 }
 
@@ -68,7 +75,10 @@ export async function findK8sRoots(root, ignorePaths = []) {
   await walkDir(
     root,
     p => {
-      if (!pathHasK8sSegment(p)) return
+      const rel = relative(root, p).replaceAll('\\', '/')
+      // `.github/` належить `ga.mdc`; kubeconform/kubescape там не запускаємо.
+      if (rel.startsWith('.github/')) return
+      if (!pathHasK8sSegment(p, root)) return
       if (!YAML_EXT_RE.test(p)) return
       const k8sRoot = k8sRootFromFile(p)
       if (k8sRoot) roots.add(k8sRoot)

package/scripts/utils/run-conftest-batch.mjs

@@ -30,7 +30,7 @@ const POLICY_ROOT = join(PACKAGE_ROOT, 'policy')
 /**
  * Друкує install-hint для conftest і кидає виняток, щоб викликана `check-*`
  * команда ясно завершилась з кодом 1.
- * @returns {never}
+ * @returns {never} завжди кидає; для точки виклику — non-returning
  */
 function failConftestMissing() {
   throw new Error(
@@ -94,9 +94,7 @@ export function runConftestBatch(opts) {
   }
   // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
   if (result.status !== 0 && result.status !== 1) {
-    throw new Error(
-      `conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`
-    )
+    throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
   }
   /** @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>} */
   let parsed