@nitra/cursor 5.3.0 → 5.3.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [5.3.2] - 2026-06-11
+
+### Changed
+
+- release: @nitra/cursor@5.3.1
+
+## [5.3.1] - 2026-06-11
+
+### Fixed
+
+- lint: усунено eslint/oxlint-помилки (24) — ігнор кореневого `.worktrees/` в eslint.config, GENERIC_RE→масив дрібних patternів (sonarjs/regex-complexity), Array#sort→toSorted; cspell: додано `ollama` у словник
+
 ## [5.3.0] - 2026-06-11
 
 ### Added

package/bin/n-cursor.js

@@ -1243,7 +1243,73 @@ function logRemovedManagedItems(title, basePath, names) {
 }
 
 /**
- * Spawn-wrapper для `npx @nitra/cursor fix [<rule>...]`. Один шлях у коді: для кожного правила
+ * Визначає список правил для fix: явно задані (з валідацією проти available) або
+ * discovery з `.cursor/rules/*.mdc`. Друкує діагностику й кидає на невідомих правилах.
+ * @param {string[]} requestedRules запитані правила (порожній → discovery)
+ * @param {string[]} available доступні в пакеті rule-id
+ * @param {boolean} json json-режим (впливає на early-return вивід при порожньому discovery)
+ * @returns {Promise<string[]|null>} список id або null — нічого запускати (вивід уже зроблено)
+ */
+async function resolveFixRuleIds(requestedRules, available, json) {
+  if (requestedRules.length > 0) {
+    const unknown = requestedRules.filter(id => !available.includes(id))
+    if (unknown.length > 0) {
+      console.error(`❌ Невідомі правила: ${unknown.join(', ')}`)
+      console.log(`   Доступні: ${available.join(', ')}`)
+      throw new Error(`Unknown rules: ${unknown.join(', ')}`)
+    }
+    return requestedRules
+  }
+
+  const mdcFiles = await listProjectRulesMdcFiles()
+  if (mdcFiles.length === 0) {
+    throw new Error(
+      `Немає файлів *.mdc у ${RULES_DIR}/. Запустіть \`npx ${PACKAGE_NAME}\` або вкажіть правила: \`npx ${PACKAGE_NAME} fix bun ga\``
+    )
+  }
+  const idsToRun = discoverCheckRulesFromCursorRules(available, mdcFiles)
+  if (idsToRun.length === 0) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ total: 0, failed: 0, rules: [] })}\n`)
+      return null
+    }
+    console.log(
+      `\n🔍 ${PACKAGE_NAME} fix — у ${RULES_DIR}/ немає правил з programmatic перевіркою ` +
+        `(відповідного fix.mjs у пакеті). Нічого не запущено.\n`
+    )
+    return null
+  }
+  return idsToRun
+}
+
+/**
+ * Прогоняє `fix.mjs` кожного правила окремим процесом; збирає timings і (для json) per-rule output.
+ * @param {string[]} idsToRun правила до запуску
+ * @param {boolean} json json-режим — захоплює stdout/stderr у структуру замість inherit у термінал
+ * @returns {{ totalFailed: number, timings: {id:string, ms:number, ok:boolean}[], ruleResults: {ruleId:string, ok:boolean, output:string}[] }} підсумок прогону
+ */
+function runRuleFixProcesses(idsToRun, json) {
+  let totalFailed = 0
+  const timings = []
+  const ruleResults = []
+  for (const id of idsToRun) {
+    const fixPath = join(BUNDLED_RULES_DIR, id, 'fix.mjs')
+    const startedAt = Date.now()
+    const result = json
+      ? spawnSync('bun', [fixPath], { encoding: 'utf8' })
+      : spawnSync('bun', [fixPath], { stdio: 'inherit' })
+    const ok = result.status === 0
+    timings.push({ id: `fix-${id}`, ms: Date.now() - startedAt, ok })
+    if (json) {
+      ruleResults.push({ ruleId: id, ok, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() })
+    }
+    if (!ok) totalFailed++
+  }
+  return { totalFailed, timings, ruleResults }
+}
+
+/**
+ * Spawn-wrapper для `npx \@nitra/cursor fix [<rule>...]`. Один шлях у коді: для кожного правила
  * робить `bun rules/<id>/fix.mjs` як окремий процес. Сам `fix.mjs` читає `.n-cursor.json`,
  * перевіряє whitelist (`runRuleCli`) і друкує per-rule summary.
  *
@@ -1272,56 +1338,12 @@ async function runFixCommand(requestedRules, opts = {}) {
     throw new Error('No rules found')
   }
 
-  let idsToRun
-  if (requestedRules.length > 0) {
-    const unknown = requestedRules.filter(id => !available.includes(id))
-    if (unknown.length > 0) {
-      console.error(`❌ Невідомі правила: ${unknown.join(', ')}`)
-      console.log(`   Доступні: ${available.join(', ')}`)
-      throw new Error(`Unknown rules: ${unknown.join(', ')}`)
-    }
-    idsToRun = requestedRules
-  } else {
-    const mdcFiles = await listProjectRulesMdcFiles()
-    if (mdcFiles.length === 0) {
-      throw new Error(
-        `Немає файлів *.mdc у ${RULES_DIR}/. Запустіть \`npx ${PACKAGE_NAME}\` або вкажіть правила: \`npx ${PACKAGE_NAME} fix bun ga\``
-      )
-    }
-    idsToRun = discoverCheckRulesFromCursorRules(available, mdcFiles)
-    if (idsToRun.length === 0) {
-      if (json) {
-        process.stdout.write(`${JSON.stringify({ total: 0, failed: 0, rules: [] })}\n`)
-        return
-      }
-      console.log(
-        `\n🔍 ${PACKAGE_NAME} fix — у ${RULES_DIR}/ немає правил з programmatic перевіркою ` +
-          `(відповідного fix.mjs у пакеті). Нічого не запущено.\n`
-      )
-      return
-    }
-  }
+  // json-режим: захоплюємо stdout/stderr правила у структуру (а не inherit у термінал),
+  // щоб віддати агенту згруповано {ruleId, ok, output} і він читав лише впалі.
+  const idsToRun = await resolveFixRuleIds(requestedRules, available, json)
+  if (idsToRun === null) return
 
-  let totalFailed = 0
-  /** @type {{ id: string, ms: number, ok: boolean }[]} */
-  const timings = []
-  /** @type {{ ruleId: string, ok: boolean, output: string }[]} */
-  const ruleResults = []
-  for (const id of idsToRun) {
-    const fixPath = join(BUNDLED_RULES_DIR, id, 'fix.mjs')
-    const startedAt = Date.now()
-    // json-режим: захоплюємо stdout/stderr правила у структуру (а не inherit у термінал),
-    // щоб віддати агенту згруповано {ruleId, ok, output} і він читав лише впалі.
-    const result = json
-      ? spawnSync('bun', [fixPath], { encoding: 'utf8' })
-      : spawnSync('bun', [fixPath], { stdio: 'inherit' })
-    const ok = result.status === 0
-    timings.push({ id: `fix-${id}`, ms: Date.now() - startedAt, ok })
-    if (json) {
-      ruleResults.push({ ruleId: id, ok, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() })
-    }
-    if (!ok) totalFailed++
-  }
+  const { totalFailed, timings, ruleResults } = runRuleFixProcesses(idsToRun, json)
 
   if (json) {
     process.stdout.write(`${JSON.stringify({ total: idsToRun.length, failed: totalFailed, rules: ruleResults })}\n`)

package/lib/models.mjs

@@ -14,7 +14,7 @@
  *
  * ## Бекенд за префіксом model-id
  *
- * model-id з префіксом `omlx/...` маршрутизується прямим HTTP до локального
+ * model-id з префіксом `omlx/...` іде прямим HTTP до локального
  * omlx-сервера (`npm/lib/omlx.mjs`), минаючи pi; решта (`openai/...`,
  * `ollama/...`, '') — через pi CLI. Тому локальні тири варто задавати у форматі
  * `omlx/<model>`, аби local-inference йшов напряму, а pi лишався шаром для хмари

package/package.json

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

package/rules/k8s/js/manifests.mjs

@@ -3942,7 +3942,7 @@ export function loadSnippetSpec(snippetName) {
   const url = NETWORK_POLICY_SNIPPET_URLS[snippetName]
   if (!url) throw new Error(`Unknown NetworkPolicy snippet: ${snippetName}`)
   const raw = readFileSync(fileURLToPath(url), 'utf8')
-  _snippetCache[snippetName] = /** @type {any} */ (parseDocument(raw).toJS()).spec
+  _snippetCache[snippetName] = /** @type {{ spec: Record<string, unknown> }} */ (parseDocument(raw).toJS()).spec
   return _snippetCache[snippetName]
 }
 
@@ -3981,7 +3981,7 @@ const noopFail = msg => msg
 /**
  * `from`-peers для HTTPRoute-aware ingress-правила (GCP HC global + Envoy data-plane / proxy-only subnet).
  * Порядок зафіксовано детерміністичним (HC-global → 10.0.0.0/8). Див. розділ «HTTPRoute → NetworkPolicy ingress» у k8s.mdc.
- * @type {ReadonlyArray<{ ipBlock: { cidr: string } }>}
+ * @type {readonly { ipBlock: { cidr: string } }[]}
  */
 const NETWORK_POLICY_GCLB_INGRESS_FROM = Object.freeze([
   // eslint-disable-next-line sonarjs/no-hardcoded-ip
@@ -4061,45 +4061,7 @@ export async function collectHttpRouteIngressForWorkload(dir, appLabel, fail) {
   const servicesByName = new Map()
 
   for (const abs of yamlFiles) {
-    let raw
-    try {
-      raw = await readFile(abs, 'utf8')
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error)
-      fail(`${abs}: не вдалося прочитати для GCLB ingress (HTTPRoute → NetworkPolicy mapping; k8s.mdc): ${msg}`)
-      continue
-    }
-    const lines = toLines(raw)
-    const body = lines.length > 0 && MODELINE_RE.test(lines[0]) ? yamlBodyAfterModeline(lines) : lines.join('\n')
-    /** @type {import('yaml').Document[]} */
-    let docs
-    try {
-      docs = parseAllDocuments(body)
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error)
-      fail(`${abs}: не вдалося розібрати YAML для GCLB ingress (HTTPRoute → NetworkPolicy mapping; k8s.mdc): ${msg}`)
-      continue
-    }
-    for (const doc of docs) {
-      if (doc.errors.length > 0) {
-        fail(
-          `${abs}: YAML містить помилки для GCLB ingress (HTTPRoute → NetworkPolicy mapping; k8s.mdc): ${doc.errors[0].message}`
-        )
-        continue
-      }
-      const rec = asPlainRecord(doc.toJSON())
-      if (rec === null) continue
-      const av = rec.apiVersion
-      if (rec.kind === 'HTTPRoute' && typeof av === 'string' && av.startsWith(GATEWAY_API_GROUP_PREFIX)) {
-        collectHttpRouteBackendRefsInto(rec.spec, allBackendRefs)
-      } else if (rec.kind === 'Service') {
-        const name = manifestMetadataName(rec)
-        if (name !== null) {
-          const app = serviceSelectorAppLabel(rec.spec)
-          if (app !== null) servicesByName.set(name, app)
-        }
-      }
-    }
+    await collectHttpRouteFileInto(abs, allBackendRefs, servicesByName, fail)
   }
 
   /** @type {Set<number>} */
@@ -4112,6 +4074,68 @@ export async function collectHttpRouteIngressForWorkload(dir, appLabel, fail) {
   return { ports: [...ports].toSorted((a, b) => a - b) }
 }
 
+/**
+ * Читає й парсить один YAML-файл і акумулює HTTPRoute-backendRefs та Service `app`-мітки.
+ * Read/parse/doc-помилки репортяться через `fail` і не зупиняють обхід (як у оригінальному циклі).
+ * @param {string} abs абсолютний шлях до YAML-файлу
+ * @param {Array<{ name: string, port: number }>} allBackendRefs акумулятор backendRefs
+ * @param {Map<string, string>} servicesByName акумулятор Service name → app-label
+ * @param {(msg: string) => void} fail callback при read/parse-помилці
+ * @returns {Promise<void>} результат
+ */
+async function collectHttpRouteFileInto(abs, allBackendRefs, servicesByName, fail) {
+  let raw
+  try {
+    raw = await readFile(abs, 'utf8')
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    fail(`${abs}: не вдалося прочитати для GCLB ingress (HTTPRoute → NetworkPolicy mapping; k8s.mdc): ${msg}`)
+    return
+  }
+  const lines = toLines(raw)
+  const body = lines.length > 0 && MODELINE_RE.test(lines[0]) ? yamlBodyAfterModeline(lines) : lines.join('\n')
+  /** @type {import('yaml').Document[]} */
+  let docs
+  try {
+    docs = parseAllDocuments(body)
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    fail(`${abs}: не вдалося розібрати YAML для GCLB ingress (HTTPRoute → NetworkPolicy mapping; k8s.mdc): ${msg}`)
+    return
+  }
+  for (const doc of docs) {
+    if (doc.errors.length > 0) {
+      fail(
+        `${abs}: YAML містить помилки для GCLB ingress (HTTPRoute → NetworkPolicy mapping; k8s.mdc): ${doc.errors[0].message}`
+      )
+      continue
+    }
+    collectHttpRouteDocInto(doc.toJSON(), allBackendRefs, servicesByName)
+  }
+}
+
+/**
+ * Класифікує один YAML-документ (HTTPRoute / Service) і акумулює backendRefs / Service `app`-мітку.
+ * @param {unknown} json розпарсений документ
+ * @param {Array<{ name: string, port: number }>} allBackendRefs акумулятор backendRefs
+ * @param {Map<string, string>} servicesByName акумулятор Service name → app-label
+ * @returns {void} результат
+ */
+function collectHttpRouteDocInto(json, allBackendRefs, servicesByName) {
+  const rec = asPlainRecord(json)
+  if (rec === null) return
+  const av = rec.apiVersion
+  if (rec.kind === 'HTTPRoute' && typeof av === 'string' && av.startsWith(GATEWAY_API_GROUP_PREFIX)) {
+    collectHttpRouteBackendRefsInto(rec.spec, allBackendRefs)
+  } else if (rec.kind === 'Service') {
+    const name = manifestMetadataName(rec)
+    if (name !== null) {
+      const app = serviceSelectorAppLabel(rec.spec)
+      if (app !== null) servicesByName.set(name, app)
+    }
+  }
+}
+
 /**
  * Витягує мітку `app` з `Service.spec.selector.app` (плоский селектор, без `matchLabels`).
  * Окремий helper від `appLabelFromSpecSelector` (той — для Deployment/StatefulSet, де `selector.matchLabels.app`).
@@ -4824,39 +4848,46 @@ export async function kustomizationTreeHasHasuraDeployment(kustAbs, rootNorm) {
 }
 
 /**
- * Значення, яке inline-`patch` присвоює `data.HASURA_GRAPHQL_ENABLED_APIS`. Підтримка двох форматів:
- * **JSON6902** (`op` add/replace на `/data/HASURA_GRAPHQL_ENABLED_APIS`) і **Strategic Merge**
- * (`data.HASURA_GRAPHQL_ENABLED_APIS`). Зовнішні patch-файли (`patches[].path`) не охоплені — Plan B trade-off.
- * @param {string} patchText вміст поля `patch`
- * @returns {string | null} присвоєне значення (рядок) або null, якщо patch не чіпає цей ключ
+ * Парсить `patchText` як YAML і повертає JSON першого документа без помилок (або undefined).
+ * @param {string} patchText непорожній trimmed-текст patch
+ * @returns {unknown} JSON першого валідного документа або undefined
  */
-export function enabledApisValueFromPatchText(patchText) {
-  const t = typeof patchText === 'string' ? patchText.trim() : ''
-  if (t === '') return null
-  let parsed
+function firstValidYamlJsonFromPatchText(patchText) {
   try {
-    for (const d of parseAllDocuments(t)) {
-      if (d.errors.length === 0) {
-        parsed = d.toJSON()
-        break
-      }
+    for (const d of parseAllDocuments(patchText)) {
+      if (d.errors.length === 0) return d.toJSON()
     }
   } catch {
-    return null
+    return undefined
   }
-  if (Array.isArray(parsed)) {
-    for (const item of parsed) {
-      if (item === null || typeof item !== 'object' || Array.isArray(item)) continue
-      const rec = /** @type {Record<string, unknown>} */ (item)
-      const op = typeof rec.op === 'string' ? rec.op.trim().toLowerCase() : ''
-      const path = typeof rec.path === 'string' ? normalizeJsonPatchPath(rec.path) : ''
-      if ((op === 'add' || op === 'replace') && path === HASURA_ENABLED_APIS_DATA_POINTER) {
-        return typeof rec.value === 'string' ? rec.value : JSON.stringify(rec.value)
-      }
+  return undefined
+}
+
+/**
+ * Значення `data.HASURA_GRAPHQL_ENABLED_APIS` з JSON6902-патчу (масив операцій).
+ * Повертає значення першої `add`/`replace`-операції на `/data/HASURA_GRAPHQL_ENABLED_APIS`.
+ * @param {unknown[]} ops масив JSON6902-операцій
+ * @returns {string | null} присвоєне значення (рядок) або null
+ */
+function enabledApisValueFromJson6902(ops) {
+  for (const item of ops) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) continue
+    const rec = /** @type {Record<string, unknown>} */ (item)
+    const op = typeof rec.op === 'string' ? rec.op.trim().toLowerCase() : ''
+    const path = typeof rec.path === 'string' ? normalizeJsonPatchPath(rec.path) : ''
+    if ((op === 'add' || op === 'replace') && path === HASURA_ENABLED_APIS_DATA_POINTER) {
+      return typeof rec.value === 'string' ? rec.value : JSON.stringify(rec.value)
     }
-    return null
   }
-  if (parsed === null || typeof parsed !== 'object') return null
+  return null
+}
+
+/**
+ * Значення `data.HASURA_GRAPHQL_ENABLED_APIS` зі Strategic-Merge-патчу (об'єкт із `data`).
+ * @param {object} parsed розпарсений об'єкт patch
+ * @returns {string | null} присвоєне значення (рядок) або null
+ */
+function enabledApisValueFromStrategicMerge(parsed) {
   const data = /** @type {Record<string, unknown>} */ (parsed).data
   if (data === null || typeof data !== 'object' || Array.isArray(data)) return null
   const d = /** @type {Record<string, unknown>} */ (data)
@@ -4865,6 +4896,22 @@ export function enabledApisValueFromPatchText(patchText) {
   return typeof v === 'string' ? v : JSON.stringify(v)
 }
 
+/**
+ * Значення, яке inline-`patch` присвоює `data.HASURA_GRAPHQL_ENABLED_APIS`. Підтримка двох форматів:
+ * **JSON6902** (`op` add/replace на `/data/HASURA_GRAPHQL_ENABLED_APIS`) і **Strategic Merge**
+ * (`data.HASURA_GRAPHQL_ENABLED_APIS`). Зовнішні patch-файли (`patches[].path`) не охоплені — Plan B trade-off.
+ * @param {string} patchText вміст поля `patch`
+ * @returns {string | null} присвоєне значення (рядок) або null, якщо patch не чіпає цей ключ
+ */
+export function enabledApisValueFromPatchText(patchText) {
+  const t = typeof patchText === 'string' ? patchText.trim() : ''
+  if (t === '') return null
+  const parsed = firstValidYamlJsonFromPatchText(t)
+  if (Array.isArray(parsed)) return enabledApisValueFromJson6902(parsed)
+  if (parsed === null || typeof parsed !== 'object') return null
+  return enabledApisValueFromStrategicMerge(parsed)
+}
+
 /**
  * Значення, яке `patches[]` kustomization присвоюють `data.HASURA_GRAPHQL_ENABLED_APIS` на цілі **ConfigMap**.
  * Повертає значення першого patch-а, що чіпає цей ключ, або null, якщо такого немає.
@@ -6307,6 +6354,34 @@ function networkPolicyPodSelectorAppLabel(spec) {
   return typeof app === 'string' ? app : ''
 }
 
+/**
+ * Витягує `kind` workload з анотації `nitra.dev/workload-kind` у `metadata.annotations`
+ * NetworkPolicy-документа; дефолт `'Deployment'`, якщо анотації немає або вона порожня.
+ * @param {Record<string, unknown>} docRec корінь NetworkPolicy-документа
+ * @returns {string} workload-kind
+ */
+function legacyNetworkPolicyWorkloadKind(docRec) {
+  const meta = getNestedObject(docRec, 'metadata')
+  const annotations = meta === null ? null : getNestedObject(meta, 'annotations')
+  const rawKind = annotations === null ? null : annotations['nitra.dev/workload-kind']
+  return typeof rawKind === 'string' && rawKind !== '' ? rawKind : 'Deployment'
+}
+
+/**
+ * Будує `{ name, appLabel, kind }` для regenerate-канону з одного legacy NetworkPolicy-документа,
+ * або `null`, якщо `name`/`appLabel` неповні (документ пропускається).
+ * @param {unknown} doc розпарсений NetworkPolicy-документ
+ * @returns {{ name: string, appLabel: string, kind: string } | null} spec або null
+ */
+function legacyNetworkPolicySpecFromDoc(doc) {
+  const name = manifestMetadataName(doc)
+  const docRec = /** @type {Record<string, unknown>} */ (doc)
+  const appLabel = networkPolicyPodSelectorAppLabel(docRec.spec)
+  const kind = legacyNetworkPolicyWorkloadKind(docRec)
+  if (typeof name === 'string' && name !== '' && appLabel !== '') return { name, appLabel, kind }
+  return null
+}
+
 /**
  * Migrate legacy `networkpolicy.yaml`: якщо хоч один документ має catch-all in-cluster egress —
  * перезаписати **всі** документи у файлі через `buildNetworkPolicyYaml(name, appLabel, kind, gclbPorts)`.
@@ -6327,21 +6402,8 @@ export async function regenerateLegacyNetworkPolicyDocsInFile(npAbs, fail) {
    */
   const specs = []
   for (const doc of docs) {
-    const name = manifestMetadataName(doc)
-    const docRec = /** @type {Record<string, unknown>} */ (doc)
-    const spec = docRec.spec
-    const appLabel = networkPolicyPodSelectorAppLabel(spec)
-    const meta = docRec.metadata
-    const annotations =
-      meta !== null && typeof meta === 'object' && !Array.isArray(meta)
-        ? /** @type {Record<string, unknown>} */ (meta).annotations
-        : null
-    const rawKind =
-      annotations !== null && typeof annotations === 'object' && !Array.isArray(annotations)
-        ? /** @type {Record<string, unknown>} */ (annotations)['nitra.dev/workload-kind']
-        : null
-    const kind = typeof rawKind === 'string' && rawKind !== '' ? rawKind : 'Deployment'
-    if (typeof name === 'string' && name !== '' && appLabel !== '') specs.push({ name, appLabel, kind })
+    const spec = legacyNetworkPolicySpecFromDoc(doc)
+    if (spec !== null) specs.push(spec)
   }
   if (specs.length === 0) return false
   const dir = dirname(npAbs)

package/rules/npm-module/js/header_doc_pointer.mjs

@@ -41,6 +41,77 @@ function moduleJsDoc(source) {
   return m ? m[0] : null
 }
 
+/**
+ * Чи `.mjs`-файл, що не є тестом (`*.test.mjs`).
+ * @param {import('node:fs').Dirent} fileEntry запис каталогу
+ * @returns {boolean} true для звичайних source-файлів
+ */
+function isSourceMjs(fileEntry) {
+  return (
+    fileEntry.isFile() && fileEntry.name.endsWith('.mjs') && !fileEntry.name.endsWith('.test.mjs')
+  )
+}
+
+/**
+ * Перевіряє один source-файл: якщо поряд є `docs/<stem>.md` і module-level JSDoc
+ * містить >1 непорожній рядок — репортить порушення.
+ * @param {string} jsDir каталог `js/`
+ * @param {import('node:fs').Dirent} fileEntry запис файлу
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkSourceFile(jsDir, fileEntry, cwd, reporter) {
+  const stem = basename(fileEntry.name, '.mjs')
+  const docsPath = join(jsDir, 'docs', `${stem}.md`)
+  if (!existsSync(docsPath)) return
+
+  const filePath = join(jsDir, fileEntry.name)
+  const source = await readFile(filePath, 'utf8')
+  const block = moduleJsDoc(source)
+  if (!block) return
+
+  const count = contentLineCount(block)
+  if (count > 1) {
+    reporter.fail(
+      `${filePath.slice(cwd.length + 1)}: docs/${stem}.md вже описує поведінку — module-level JSDoc має бути pointer (≤1 рядок, зараз ${count})`
+    )
+  }
+}
+
+/**
+ * Перевіряє всі source-файли в одному `js/`-каталозі правила/скіла.
+ * @param {string} jsDir каталог `js/`
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkJsDir(jsDir, cwd, reporter) {
+  for (const fileEntry of await readdir(jsDir, { withFileTypes: true })) {
+    if (!isSourceMjs(fileEntry)) continue
+    await checkSourceFile(jsDir, fileEntry, cwd, reporter)
+  }
+}
+
+/**
+ * Перевіряє один base-сегмент (`npm/rules` чи `npm/skills`): обходить піддиректорії
+ * правил/скілів і їхні `js/`-каталоги.
+ * @param {string} absBase абсолютний шлях до base-сегмента
+ * @param {string} cwd корінь репозиторію
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {Promise<void>}
+ */
+async function checkBaseSegment(absBase, cwd, reporter) {
+  for (const ruleEntry of await readdir(absBase, { withFileTypes: true })) {
+    if (!ruleEntry.isDirectory() || ruleEntry.name.startsWith('.')) continue
+
+    const jsDir = join(absBase, ruleEntry.name, 'js')
+    if (!existsSync(jsDir)) continue
+
+    await checkJsDir(jsDir, cwd, reporter)
+  }
+}
+
 /**
  * Сканує `npm/rules/*\/js/*.mjs` і `npm/skills/*\/js/*.mjs`.
  * Якщо поряд існує `docs/<stem>.md` — module-level JSDoc має бути pointer (≤1 рядок),
@@ -54,33 +125,7 @@ export async function check(cwd = process.cwd()) {
   for (const baseSegment of ['npm/rules', 'npm/skills']) {
     const absBase = join(cwd, baseSegment)
     if (!existsSync(absBase)) continue
-
-    for (const ruleEntry of await readdir(absBase, { withFileTypes: true })) {
-      if (!ruleEntry.isDirectory() || ruleEntry.name.startsWith('.')) continue
-
-      const jsDir = join(absBase, ruleEntry.name, 'js')
-      if (!existsSync(jsDir)) continue
-
-      for (const fileEntry of await readdir(jsDir, { withFileTypes: true })) {
-        if (!fileEntry.isFile() || !fileEntry.name.endsWith('.mjs') || fileEntry.name.endsWith('.test.mjs')) continue
-
-        const stem = basename(fileEntry.name, '.mjs')
-        const docsPath = join(jsDir, 'docs', `${stem}.md`)
-        if (!existsSync(docsPath)) continue
-
-        const filePath = join(jsDir, fileEntry.name)
-        const source = await readFile(filePath, 'utf8')
-        const block = moduleJsDoc(source)
-        if (!block) continue
-
-        const count = contentLineCount(block)
-        if (count > 1) {
-          reporter.fail(
-            `${filePath.slice(cwd.length + 1)}: docs/${stem}.md вже описує поведінку — module-level JSDoc має бути pointer (≤1 рядок, зараз ${count})`
-          )
-        }
-      }
-    }
+    await checkBaseSegment(absBase, cwd, reporter)
   }
 
   return reporter.getExitCode()