@nitra/cursor 5.2.1 → 5.3.1

package/rules/js-run/js-run.mdc

@@ -2,7 +2,7 @@
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 globs: "**/package.json,**/jsconfig.json,**/src/**/*.{js,mjs,cjs,ts,tsx}"
 alwaysApply: false
-version: '1.11'
+version: '1.12'
 ---
 
 ## Область застосування
@@ -97,7 +97,7 @@ import sql from 'mssql'
 import { GraphQLClient } from '@nitra/graphql-request'
 ```
 
-то ці підключення повинні бути винесені в окремий файл, наприклад `/src/conn/pg.js`, в package.json повинні бути додано аліас:
+то ці підключення повинні бути винесені в окремий файл, наприклад `/src/conn/pg.mjs`, в package.json повинні бути додано аліас:
 
 ```json
 {
@@ -110,7 +110,7 @@ import { GraphQLClient } from '@nitra/graphql-request'
 
 так виглядатиме підключення до PostgreSQL в коді:
 
-```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.js"
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.mjs"
 import { checkEnv, env } from '@nitra/check-env'
 import { SQL } from 'bun'
 
@@ -140,7 +140,7 @@ export const graphQLClientSmart = new GraphQLClient(env.QL, {
 а в коді повинно бути використано:
 
 ```js
-import { pool } from '#conn/pg.js'
+import { pool } from '#conn/pg.mjs'
 
 // або
 
@@ -152,24 +152,24 @@ import { gql, graphQLClient } from '@nitra/graphql-request'
 Назва файла в `src/conn/` має одразу повідомляти, **до чого** підключаємось і **в якому режимі**:
 
 - **GraphQL** — префікс `ql-`, далі ідентифікатор endpoint:
-  - `src/conn/ql-contract.js`
-  - `src/conn/ql-smart.js`
+  - `src/conn/ql-contract.mjs`
+  - `src/conn/ql-smart.mjs`
 - **PostgreSQL** — префікс `pg-`, далі тип підключення (репліка vs мастер): `read` або `write`:
-  - `src/conn/pg-read.js`
-  - `src/conn/pg-write.js`
+  - `src/conn/pg-read.mjs`
+  - `src/conn/pg-write.mjs`
 - **PostgreSQL до кількох БД** — додатково ідентифікатор підключення після типу:
-  - `src/conn/pg-read-smart.js`
-  - `src/conn/pg-write-contract.js`
-- **MySQL** — префікс `mysql-` за тією ж схемою (`mysql-read.js`, `mysql-write-<id>.js` тощо).
-- **MSSQL** — префікс `mssql-` за тією ж схемою (`mssql-read.js`, `mssql-write-<id>.js` тощо). Хоча npm-пакет один (`mssql`), а драйвер MS SQL Server під капотом T-SQL — у файловій назві відрізняємо MS SQL Server від MySQL, бо це різні СУБД, різні діалекти, різні рантаймні залежності. Якщо проєкт історично використовує `mysql-…` для MSSQL-підключень — він валідний і далі (для backward-compat), але новий код пишемо з префіксом `mssql-`.
+  - `src/conn/pg-read-smart.mjs`
+  - `src/conn/pg-write-contract.mjs`
+- **MySQL** — префікс `mysql-` за тією ж схемою (`mysql-read.mjs`, `mysql-write-<id>.mjs` тощо).
+- **MSSQL** — префікс `mssql-` за тією ж схемою (`mssql-read.mjs`, `mssql-write-<id>.mjs` тощо). Хоча npm-пакет один (`mssql`), а драйвер MS SQL Server під капотом T-SQL — у файловій назві відрізняємо MS SQL Server від MySQL, бо це різні СУБД, різні діалекти, різні рантаймні залежності. Якщо проєкт історично використовує `mysql-…` для MSSQL-підключень — він валідний і далі (для backward-compat), але новий код пишемо з префіксом `mssql-`.
 
-Підключення до БД **обов'язково** має бути ідентифіковано як `read` (репліка) або `write` (мастер). Якщо з імені змінної оточення (наприклад, `env.PG_CONN`) це не очевидно — визнач режим за операціями в коді: якщо немає операцій зміни даних (`INSERT`/`UPDATE`/`DELETE`/DDL) — це `pg-read.js`, інакше `pg-write.js`.
+Підключення до БД **обов'язково** має бути ідентифіковано як `read` (репліка) або `write` (мастер). Якщо з імені змінної оточення (наприклад, `env.PG_CONN`) це не очевидно — визнач режим за операціями в коді: якщо немає операцій зміни даних (`INSERT`/`UPDATE`/`DELETE`/DDL) — це `pg-read.mjs`, інакше `pg-write.mjs`.
 
 ### Експорти у файлах `src/conn/`
 
 У файлах підключень **заборонений** `export default`. Експорт має бути **іменований** і збігатися з назвою файла в camelCase.
 
-Приклад — `src/conn/ql-smart.js`:
+Приклад — `src/conn/ql-smart.mjs`:
 
 ```javascript title="❌ Так не можна"
 export default new GraphQLClient(env.SMART_QL, {
@@ -187,13 +187,13 @@ export const qlSmart = new GraphQLClient(env.SMART_QL, {
 })
 ```
 
-Відповідно: `pg-read.js` → `export const pgRead = …`, `pg-write-contract.js` → `export const pgWriteContract = …`, `ql-contract.js` → `export const qlContract = …`.
+Відповідно: `pg-read.mjs` → `export const pgRead = …`, `pg-write-contract.mjs` → `export const pgWriteContract = …`, `ql-contract.mjs` → `export const qlContract = …`.
 
 ## CheckEnv
 
 Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми.
 
-```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.js"
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.mjs"
 import { checkEnv, env } from '@nitra/check-env'
 import { SQL } from 'bun'
 

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()

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

@@ -6,6 +6,77 @@ import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 import { parseRuleAutoSpec, parseRuleLintPhase, readRuleMetaRaw } from '../../../scripts/lib/rule-meta.mjs'
 import { RULE_PREDICATES } from '../../../scripts/lib/rule-predicates.mjs'
 
+/**
+ * Перевіряє поле `auto` у meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле валідне (або відсутнє)
+ */
+function checkAutoField(id, raw, reporter) {
+  if (raw.auto === undefined) return true
+  const spec = parseRuleAutoSpec(raw.auto)
+  if (spec === null) {
+    reporter.fail(`rules/${id}: meta.json.auto нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})`)
+    return false
+  }
+  if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
+    reporter.fail(`rules/${id}: невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Перевіряє поле `lint` у meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {string} ruleDir каталог правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле валідне (або відсутнє)
+ */
+function checkLintField(id, ruleDir, raw, reporter) {
+  if (raw.lint === undefined) return true
+  if (parseRuleLintPhase(raw.lint) === null) {
+    reporter.fail(`rules/${id}: meta.json.lint нерозпізнане (очікується "quick"|"ci")`)
+    return false
+  }
+  if (!existsSync(join(ruleDir, 'js', 'lint.mjs'))) {
+    reporter.fail(`rules/${id}: lint:"${raw.lint}" але немає js/lint.mjs`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Валідує meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {string} ruleDir каталог правила
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkRule(id, ruleDir, reporter) {
+  let ruleOk = true
+
+  if (existsSync(join(ruleDir, 'auto.md'))) {
+    reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+    ruleOk = false
+  }
+
+  const raw = readRuleMetaRaw(ruleDir)
+  if (!raw) {
+    reporter.fail(`rules/${id}: відсутній або невалідний meta.json`)
+    return
+  }
+
+  if (!checkAutoField(id, raw, reporter)) ruleOk = false
+  if (!checkLintField(id, ruleDir, raw, reporter)) ruleOk = false
+
+  if (ruleOk) {
+    reporter.pass(`rules/${id}: meta.json валідний`)
+  }
+}
+
 /**
  * Валідує всі `npm/rules/<id>/meta.json`.
  * @param {string} [cwd] корінь репозиторію
@@ -21,42 +92,7 @@ export function check(cwd = process.cwd()) {
 
   for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue
-    const id = entry.name
-    const ruleDir = join(rulesDir, id)
-    let ruleOk = true
-
-    if (existsSync(join(ruleDir, 'auto.md'))) {
-      reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
-      ruleOk = false
-    }
-
-    const raw = readRuleMetaRaw(ruleDir)
-    if (!raw) {
-      reporter.fail(`rules/${id}: відсутній або невалідний meta.json`)
-      continue
-    }
-    if (raw.auto !== undefined) {
-      const spec = parseRuleAutoSpec(raw.auto)
-      if (spec === null) {
-        reporter.fail(`rules/${id}: meta.json.auto нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})`)
-        ruleOk = false
-      } else if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
-        reporter.fail(`rules/${id}: невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
-        ruleOk = false
-      }
-    }
-    if (raw.lint !== undefined) {
-      if (parseRuleLintPhase(raw.lint) === null) {
-        reporter.fail(`rules/${id}: meta.json.lint нерозпізнане (очікується "quick"|"ci")`)
-        ruleOk = false
-      } else if (!existsSync(join(ruleDir, 'js', 'lint.mjs'))) {
-        reporter.fail(`rules/${id}: lint:"${raw.lint}" але немає js/lint.mjs`)
-        ruleOk = false
-      }
-    }
-    if (ruleOk) {
-      reporter.pass(`rules/${id}: meta.json валідний`)
-    }
+    checkRule(entry.name, join(rulesDir, entry.name), reporter)
   }
 
   return Promise.resolve(reporter.getExitCode())