@nitra/cursor 1.9.23 → 1.11.0

package/rules/abie/js/env_dns/check.mjs

@@ -0,0 +1,53 @@
+/**
+ * Скан env-файлів abie (`*.dev.env`, `*.ua.env`): кожен внутрішньокластерний URL
+ * `http://<svc>.<ns>.svc.<dns>` має відповідати кластеру за іменем файла:
+ *   - `dev.env` → `abie-dev.internal` + `dev-*` namespace
+ *   - `ua.env`  → `abie-ua.internal` + `ua-*` namespace
+ *
+ * Файл `.env` без імені (локальний для розробника) — виключено.
+ */
+import { readFile } from 'node:fs/promises'
+import { basename, relative } from 'node:path'
+
+import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-config.mjs'
+
+import { abieEnvNameFromBasename, collectAbieEnvFiles, validateAbieEnvInternalUrls } from '../../utils/env-dns.mjs'
+
+/**
+ * @returns {Promise<number>}
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const root = process.cwd()
+
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const envFiles = await collectAbieEnvFiles(root, ignorePaths)
+  if (envFiles.length === 0) {
+    pass('Не знайдено dev.env / ua.env у репозиторії — перевірку env→cluster DNS пропущено (abie.mdc)')
+    return reporter.getExitCode()
+  }
+
+  for (const abs of envFiles) {
+    const rel = relative(root, abs).replaceAll('\\', '/') || abs
+    const envName = abieEnvNameFromBasename(basename(abs))
+    if (envName === null) continue
+    let raw
+    try {
+      raw = await readFile(abs, 'utf8')
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      fail(`${rel}: не вдалося прочитати (${msg})`)
+      continue
+    }
+    const errors = validateAbieEnvInternalUrls(raw, envName)
+    if (errors.length === 0) {
+      pass(`${rel}: усі внутрішні URL відповідають env "${envName}" (abie.mdc)`)
+    } else {
+      for (const err of errors) fail(`${rel}: ${err} (abie.mdc)`)
+    }
+  }
+
+  return reporter.getExitCode()
+}

package/rules/abie/js/firebase_hosting/check.mjs

@@ -0,0 +1,49 @@
+/**
+ * Перевірка abie: у **підкаталогах першого рівня** (без `.git`/`node_modules`) не має бути
+ * `.firebaserc`, `firebase.json`, `.firebase/` (abie.mdc — Firebase Hosting заборонено).
+ * У самому корені репозиторію ці імена не перевіряються (можуть бути від суміжних проєктів).
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mjs'
+
+const SKIP_TOP_DIR_NAMES = new Set(['.git', 'node_modules'])
+
+/**
+ * @returns {Promise<number>}
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const root = process.cwd()
+
+  let entries
+  try {
+    entries = await readdir(root, { withFileTypes: true })
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    fail(`Не вдалося прочитати ${root} для перевірки Firebase Hosting: ${msg} (abie.mdc)`)
+    return reporter.getExitCode()
+  }
+  const topDirs = entries.filter(e => e.isDirectory() && !SKIP_TOP_DIR_NAMES.has(e.name))
+  let hasViolation = false
+  for (const e of topDirs) {
+    for (const name of ['.firebaserc', 'firebase.json']) {
+      const rel = join(e.name, name).replaceAll('\\', '/')
+      if (existsSync(join(root, e.name, name))) {
+        fail(`Знайдено заборонений файл Firebase Hosting: ${rel} — видали його (abie.mdc)`)
+        hasViolation = true
+      }
+    }
+    if (existsSync(join(root, e.name, '.firebase'))) {
+      fail(`Знайдено заборонену директорію: ${e.name}/.firebase/ — видали її (abie.mdc)`)
+      hasViolation = true
+    }
+  }
+  if (!hasViolation) {
+    pass('Підкаталоги кореня (1-й рівень, без .git/node_modules): артефактів Firebase Hosting не знайдено (abie.mdc)')
+  }
+  return reporter.getExitCode()
+}

package/rules/abie/js/hc_pairing/check.mjs

@@ -0,0 +1,58 @@
+/**
+ * Перевірка abie: для кожного каталогу з `kind: Deployment` під `k8s/` поруч має бути `hc.yaml`
+ * з коректним modeline (yaml-language-server $schema).
+ *
+ * Це JS-частина (FS-парність + modeline). Структурну валідацію `HealthCheckPolicy`
+ * (apiVersion, requestPath, port, targetRef з суфіксом `-hl`) робить CLI через
+ * `policy/health_check_policy/target.json` (walkGlob по hc.yaml у k8s-дереві).
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+
+import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-config.mjs'
+
+import { validateAbieHcModeline } from '../../utils/hc-yaml.mjs'
+import { collectDeploymentDirs, findK8sYamlFiles } from '../../utils/k8s-tree.mjs'
+
+/**
+ * @returns {Promise<number>}
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const root = process.cwd()
+
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const yamls = await findK8sYamlFiles(root, ignorePaths)
+  const deploymentDirs = await collectDeploymentDirs(root, yamls, fail)
+
+  if (deploymentDirs.size === 0) {
+    pass('Немає Deployment у дереві k8s — перевірку hc.yaml пропущено')
+    return reporter.getExitCode()
+  }
+  pass(`Знайдено Deployment у ${deploymentDirs.size} директорія(ї/й) k8s — перевіряємо hc.yaml поруч`)
+
+  for (const dir of [...deploymentDirs].toSorted((a, b) => a.localeCompare(b))) {
+    const hcAbs = `${dir}/hc.yaml`
+    const relHc = relative(root, hcAbs).replaceAll('\\', '/') || 'hc.yaml'
+    if (!existsSync(hcAbs)) {
+      fail(`${relative(root, dir) || dir}: є Deployment, але немає hc.yaml поруч — додай HealthCheckPolicy (abie.mdc)`)
+      continue
+    }
+    let hcRaw
+    try {
+      hcRaw = await readFile(hcAbs, 'utf8')
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      fail(`${relHc}: не вдалося прочитати (${msg})`)
+      continue
+    }
+    const modelineErr = validateAbieHcModeline(hcRaw, relHc)
+    if (modelineErr !== null) fail(modelineErr)
+    else pass(`${relHc}: modeline OK`)
+  }
+
+  return reporter.getExitCode()
+}

package/rules/abie/js/ua_http_route/check.mjs

@@ -0,0 +1,86 @@
+/**
+ * Якщо в каталозі пакета (батько `k8s/`) є `vite.config.{js,mjs,ts}`, у `ua/kustomization.yaml`
+ * має бути inline-patch HTTPRoute (непорожній `target.name`): `/spec/hostnames` (домени abie),
+ * `/spec/parentRefs/0/namespace` (`ua` або `ua-*`).
+ *
+ * Для спільних сервісів (`auth-run-hl`, `file-link-hl`) у base-HTTPRoute пакета — кожен `backendRef`
+ * має `namespace: dev`; в overlay patch — JSON6902 на `/spec/rules/…/backendRefs/…/namespace` зі
+ * `value: ua`. Кількість patch-ів = кількість таких посилань у base.
+ */
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+
+import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-config.mjs'
+
+import { analyzeAbieSharedBackendRefsInPackageK8s } from '../../utils/http-route.mjs'
+import { findK8sYamlFiles } from '../../utils/k8s-tree.mjs'
+import {
+  getCombinedNginxRunPatchTextFromKustomization,
+  validateAbieNginxRunHttpRoutePatches
+} from '../../utils/kustomization-patches.mjs'
+import {
+  abiePackageDirFromK8sOverlay,
+  abieOverlayRequiresHttpRouteByVite,
+  isUaKustomizationPath
+} from '../../utils/overlay-paths.mjs'
+
+/**
+ * @returns {Promise<number>}
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const root = process.cwd()
+
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const yamls = await findK8sYamlFiles(root, ignorePaths)
+
+  const uaAbsList = yamls.filter(abs => isUaKustomizationPath(relative(root, abs).replaceAll('\\', '/') || abs))
+  if (uaAbsList.length === 0) {
+    pass('Немає ua/kustomization.yaml у дереві k8s — patch HTTPRoute (ua) не вимагається (abie.mdc, лише Vite-пакети)')
+    return reporter.getExitCode()
+  }
+
+  /** @type {Map<string, Promise<{ refCount: number, baseErrors: string[] }>>} */
+  const cache = new Map()
+
+  for (const abs of uaAbsList) {
+    const rel = relative(root, abs).replaceAll('\\', '/') || abs
+    if (!abieOverlayRequiresHttpRouteByVite(root, abs)) {
+      pass(`${rel}: HTTPRoute patch (ua) не застосовується — немає vite.config.{js,mjs,ts} у пакеті (abie)`)
+      continue
+    }
+    const pkgAbs = abiePackageDirFromK8sOverlay(root, abs)
+    if (!pkgAbs) {
+      fail(`${rel}: внутрішня помилка abie overlay (немає каталогу пакета)`)
+      continue
+    }
+    let p = cache.get(pkgAbs)
+    if (!p) {
+      p = analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yamls)
+      cache.set(pkgAbs, p)
+    }
+    const sharedAnalysis = await p
+    let hasBaseError = false
+    for (const err of sharedAnalysis.baseErrors) {
+      fail(err)
+      hasBaseError = true
+    }
+    if (hasBaseError) continue
+    let raw
+    try {
+      raw = await readFile(abs, 'utf8')
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      fail(`${rel}: не вдалося прочитати (${msg})`)
+      continue
+    }
+    const combined = getCombinedNginxRunPatchTextFromKustomization(raw)
+    const v = validateAbieNginxRunHttpRoutePatches(combined, 'ua', raw, sharedAnalysis.refCount)
+    if (v !== null) fail(`${rel}: ${v}`)
+    else pass(`${rel}: HTTPRoute patch (ua) відповідає abie.mdc`)
+  }
+
+  return reporter.getExitCode()
+}

package/rules/abie/js/ua_node_selector/check.mjs

@@ -0,0 +1,65 @@
+/**
+ * Якщо в дереві `k8s/` пакета є `Deployment`, у `ua/kustomization.yaml` має бути inline-patch
+ * на `Deployment` з `path /spec/template/spec/nodeSelector` і `preem: false` (abie.mdc).
+ *
+ * Структурні обмеження JSON6902 (заборона `remove + add` на той самий path) перевіряє k8s.mdc /
+ * `k8s.kustomization` rego — тут лише abie-специфічне.
+ */
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+
+import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-config.mjs'
+
+import { collectDeploymentDirs, findK8sYamlFiles } from '../../utils/k8s-tree.mjs'
+import { kustomizationHasAbieDeploymentNodeSelectorPatch } from '../../utils/kustomization-patches.mjs'
+import { abieOverlayK8sTreeHasDeployment, isUaKustomizationPath } from '../../utils/overlay-paths.mjs'
+
+/**
+ * @returns {Promise<number>}
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const root = process.cwd()
+
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const yamls = await findK8sYamlFiles(root, ignorePaths)
+  const deploymentDirs = await collectDeploymentDirs(root, yamls, fail)
+
+  if (deploymentDirs.size === 0) {
+    pass('Немає Deployment у дереві k8s — patch nodeSelector (ua) не вимагається')
+    return reporter.getExitCode()
+  }
+
+  const uaAbsList = yamls.filter(abs => isUaKustomizationPath(relative(root, abs).replaceAll('\\', '/') || abs))
+  if (uaAbsList.length === 0) {
+    fail(
+      'Є Deployment у k8s — додай ua/kustomization.yaml з patch на Deployment: path /spec/template/spec/nodeSelector, preem false (abie.mdc)'
+    )
+    return reporter.getExitCode()
+  }
+
+  for (const abs of uaAbsList) {
+    const rel = relative(root, abs).replaceAll('\\', '/') || abs
+    if (!abieOverlayK8sTreeHasDeployment(deploymentDirs, root, abs)) {
+      pass(`${rel}: nodeSelector patch (ua) не застосовується — немає Deployment у дереві k8s цього пакета (abie)`)
+      continue
+    }
+    let raw
+    try {
+      raw = await readFile(abs, 'utf8')
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      fail(`${rel}: не вдалося прочитати (${msg})`)
+      continue
+    }
+    if (!kustomizationHasAbieDeploymentNodeSelectorPatch(raw, 'ua')) {
+      fail(`${rel}: потрібен patch target kind Deployment: path /spec/template/spec/nodeSelector та preem: false (abie.mdc)`)
+      continue
+    }
+    pass(`${rel}: nodeSelector patch (ua) відповідає abie.mdc`)
+  }
+
+  return reporter.getExitCode()
+}

package/rules/abie/policy/base_deployment_preem/target.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": {
+    "walkGlob": [
+      "**/k8s/**/base/**/*.yaml",
+      "**/k8s/**/base/**/*.yml",
+      "!**/k8s/**/base/**/kustomization.yaml"
+    ]
+  }
+}

package/rules/abie/policy/clean_merged_ignore_branches/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": ".github/workflows/clean-merged-branch.yml" }
+}

package/rules/abie/policy/health_check_policy/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "walkGlob": "**/k8s/**/hc.yaml" }
+}

package/rules/abie/policy/http_route_base/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "walkGlob": "**/k8s/**/base/**/hr.yaml" }
+}

package/rules/abie/utils/enabled.mjs

@@ -0,0 +1,35 @@
+/**
+ * Rule-level applies-гейт abie: чи `.n-cursor.json:rules` містить `abie`.
+ * Використовується `js/applies/check.mjs` як `applies()`-експорт — якщо false,
+ * CLI пропускає всі концерни правила (включно з policy).
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const CONFIG_FILE = '.n-cursor.json'
+
+/**
+ * Чи увімкнено правило **abie** у `.n-cursor.json:rules`.
+ * @param {string} root корінь репозиторію (cwd)
+ * @returns {Promise<boolean>}
+ */
+export async function isAbieRuleEnabled(root) {
+  const p = join(root, CONFIG_FILE)
+  if (!existsSync(p)) return false
+  let raw
+  try {
+    raw = await readFile(p, 'utf8')
+  } catch {
+    return false
+  }
+  let cfg
+  try {
+    cfg = JSON.parse(raw)
+  } catch {
+    return false
+  }
+  const rules = cfg?.rules
+  if (!Array.isArray(rules)) return false
+  return rules.some(r => String(r).trim().toLowerCase() === 'abie')
+}

package/rules/abie/utils/env-dns.mjs

@@ -0,0 +1,81 @@
+/**
+ * Перевірка кластерного DNS у abie env-файлах (`*.dev.env`, `*.ua.env`).
+ *
+ * abie живе у двох GKE-кластерах (`abie-dev.internal`, `abie-ua.internal`); внутрішньокластерні
+ * URL у env-файлі мусять відповідати кластеру за іменем файла. `validateAbieEnvInternalUrls`
+ * сканує всі URL виду `http://<svc>.<ns>.svc.<dns>` і вимагає коректний `<dns>` + namespace-префікс.
+ * Файл `.env` без імені (локальний для розробника) виключено.
+ */
+import { basename } from 'node:path'
+
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+
+const ABIE_ENV_FILE_BASENAME_RE = /^\.?(dev|ua)\.env$/u
+
+const ABIE_INTERNAL_URL_GLOBAL_RE =
+  /\bhttp:\/\/([a-z0-9][a-z0-9-]*)\.([a-z0-9][a-z0-9-]*)\.svc\.([a-z0-9][a-z0-9-]*\.internal)(?::\d+)?(?:\/[^\s"'`]*)?/giu
+
+const ABIE_ENV_CLUSTER_DNS_MAP = Object.freeze({
+  dev: Object.freeze({ clusterDns: 'abie-dev.internal', namespacePrefix: 'dev-' }),
+  ua: Object.freeze({ clusterDns: 'abie-ua.internal', namespacePrefix: 'ua-' })
+})
+
+/**
+ * Дістає `dev` / `ua` з basename env-файлу abie.
+ * Не-abie env-файли (`production.env`, `.env` без імені) → null.
+ * @param {string} basenameOfEnvFile
+ * @returns {('dev' | 'ua') | null}
+ */
+export function abieEnvNameFromBasename(basenameOfEnvFile) {
+  const m = basenameOfEnvFile.match(ABIE_ENV_FILE_BASENAME_RE)
+  return m ? /** @type {'dev' | 'ua'} */ (m[1]) : null
+}
+
+/**
+ * Сканує вміст env-файла, повертає помилки невідповідності кластерного DNS / namespace
+ * для кожного internal URL (один URL у двох змінних = дві окремі помилки).
+ * @param {string} content вміст env-файла (UTF-8)
+ * @param {'dev' | 'ua'} envName
+ * @returns {string[]} порожній масив, якщо все OK
+ */
+export function validateAbieEnvInternalUrls(content, envName) {
+  const expected = ABIE_ENV_CLUSTER_DNS_MAP[envName]
+  if (!expected) return []
+  /** @type {string[]} */
+  const errors = []
+  for (const match of content.matchAll(ABIE_INTERNAL_URL_GLOBAL_RE)) {
+    const [fullUrl, , namespace, clusterDns] = match
+    if (clusterDns !== expected.clusterDns) {
+      errors.push(
+        `${fullUrl}: кластерний DNS "${clusterDns}" не відповідає env "${envName}" (очікується "${expected.clusterDns}")`
+      )
+    }
+    if (!namespace.startsWith(expected.namespacePrefix)) {
+      errors.push(
+        `${fullUrl}: namespace "${namespace}" не починається з "${expected.namespacePrefix}" (env "${envName}")`
+      )
+    }
+  }
+  return errors
+}
+
+/**
+ * Збирає `*.env` файли, які є abie env (`dev.env`/`ua.env`, опц. з провідною крапкою).
+ * @param {string} root корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів-виключень
+ * @returns {Promise<string[]>}
+ */
+export async function collectAbieEnvFiles(root, ignorePaths) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(
+    root,
+    absPath => {
+      if (abieEnvNameFromBasename(basename(absPath)) !== null) {
+        out.push(absPath)
+      }
+    },
+    ignorePaths
+  )
+  return out.toSorted((a, b) => a.localeCompare(b))
+}

package/rules/abie/utils/hc-yaml.mjs

@@ -0,0 +1,27 @@
+/**
+ * Валідація modeline у `hc.yaml` для abie.
+ * Per-document структурна валідація `HealthCheckPolicy` живе у
+ * `policy/health_check_policy/health_check_policy.rego` (CLI прогонить через target.json).
+ */
+import { LINE_SPLIT_RE, MODELINE_RE, stripBom } from './yaml.mjs'
+
+/** Очікуваний URL `$schema` для **hc.yaml** (abie.mdc). */
+export const ABIE_HC_SCHEMA_URL = 'https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json'
+
+/**
+ * Перевіряє modeline (`# yaml-language-server: $schema=...`) у `hc.yaml`.
+ * @param {string} raw вміст файла
+ * @param {string} relPath відносний шлях (для повідомлень)
+ * @returns {string | null} текст помилки або null, якщо OK
+ */
+export function validateAbieHcModeline(raw, relPath) {
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  if (lines.length === 0 || lines[0].trim() === '') {
+    return `${relPath}: перший рядок порожній — потрібен # yaml-language-server: $schema=… (abie.mdc)`
+  }
+  const m = lines[0].match(MODELINE_RE)
+  if (!m) return `${relPath}: перший рядок має бути modeline $schema (abie.mdc)`
+  if (m[1] !== ABIE_HC_SCHEMA_URL) return `${relPath}: $schema має бути\n     ${ABIE_HC_SCHEMA_URL}\n     (abie.mdc)`
+  return null
+}

package/rules/abie/utils/http-route.mjs

@@ -0,0 +1,93 @@
+/**
+ * Cross-документна аналітика abie HTTPRoute: підрахунок `backendRefs` до спільних
+ * сервісів (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета (поза overlay `ua`).
+ * Використовується ua_http_route-концерном для синхронізації числа patch-ів namespace
+ * у overlay із кількістю base-referencе.
+ */
+import { relative } from 'node:path'
+
+import { isK8sYamlInAbiePackageExcludingUaOverlay } from './overlay-paths.mjs'
+import { readAndParseYamlDocs, silentFail } from './yaml.mjs'
+
+export const ABIE_SHARED_CROSS_NS_BACKEND_NAMES = Object.freeze(['auth-run-hl', 'file-link-hl'])
+const ABIE_SHARED_CROSS_NS_BACKEND_SET = new Set(ABIE_SHARED_CROSS_NS_BACKEND_NAMES)
+
+/**
+ * Перевіряє один `backendRef`: якщо це спільний `-hl` сервіс, має бути `namespace: dev`.
+ * @param {unknown} br
+ * @param {string} rel rel-шлях файла
+ * @param {string[]} errors мутабельний список помилок
+ * @returns {number} 1 — це shared backend, 0 — інакше
+ */
+function checkSharedBackendRef(br, rel, errors) {
+  if (br === null || typeof br !== 'object' || Array.isArray(br)) return 0
+  const brRec = /** @type {Record<string, unknown>} */ (br)
+  const name = brRec.name
+  if (typeof name !== 'string' || !ABIE_SHARED_CROSS_NS_BACKEND_SET.has(name)) return 0
+  if (typeof brRec.namespace !== 'string' || brRec.namespace !== 'dev') {
+    errors.push(`${rel}: HTTPRoute backendRefs до ${name} має містити namespace: dev (abie.mdc)`)
+  }
+  return 1
+}
+
+/**
+ * Збирає по HTTPRoute-документу кількість посилань на shared backends і порушення namespace.
+ * @param {unknown} obj корінь YAML
+ * @param {string} rel
+ * @returns {{ refCount: number, errors: string[] }}
+ */
+function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
+  /** @type {string[]} */
+  const errors = []
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return { refCount: 0, errors }
+  const rec = /** @type {Record<string, unknown>} */ (obj)
+  if (rec.kind !== 'HTTPRoute') return { refCount: 0, errors }
+  const spec = rec.spec
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) return { refCount: 0, errors }
+  const rules = /** @type {Record<string, unknown>} */ (spec).rules
+  if (!Array.isArray(rules)) return { refCount: 0, errors }
+  let refCount = 0
+  for (const rule of rules) {
+    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) {
+          refCount += checkSharedBackendRef(br, rel, errors)
+        }
+      }
+    }
+  }
+  return { refCount, errors }
+}
+
+/**
+ * Збирає по yaml-файлах пакета (поза overlay ua) кількість shared-`-hl` `backendRefs`
+ * і базові помилки (без `namespace: dev`).
+ * @param {string} root корінь репозиторію
+ * @param {string} pkgAbs абсолютний шлях каталогу пакета
+ * @param {string[]} yamlFilesAbs усі yaml під k8s
+ * @returns {Promise<{ refCount: number, baseErrors: string[] }>}
+ */
+export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yamlFilesAbs) {
+  const pkgRel = relative(root, pkgAbs).replaceAll('\\', '/') || pkgAbs
+  let refCount = 0
+  /** @type {string[]} */
+  const baseErrors = []
+  for (const abs of yamlFilesAbs) {
+    const rel = relative(root, abs).replaceAll('\\', '/') || abs
+    if (isK8sYamlInAbiePackageExcludingUaOverlay(rel, pkgRel)) {
+      const docs = await readAndParseYamlDocs(abs, rel, silentFail)
+      if (docs) {
+        for (const doc of docs) {
+          if (doc.errors.length === 0) {
+            const json = doc.toJSON()
+            const st = httpRouteDocSharedCrossNsBackendStats(json, rel)
+            refCount += st.refCount
+            baseErrors.push(...st.errors)
+          }
+        }
+      }
+    }
+  }
+  return { refCount, baseErrors }
+}