@7n/rules 1.0.0

package/rules/abie/lib/kustomization-patches.mjs

@@ -0,0 +1,211 @@
+/**
+ * Парсинг inline JSON6902-патчів у abie ua-kustomization:
+ *   - **nodeSelector** patch на `Deployment` (preem: false);
+ *   - **HTTPRoute** patch (hostnames, parentRefs namespace, backendRefs namespace).
+ *
+ * Regex використовуються, бо `patch:` — це YAML-string з вкладеним JSON6902, який ми не парсимо
+ * вдруге; підрядки на кшталт `path: /spec/hostnames` і `value: ua` достатньо інформативні.
+ */
+import { parseAllDocuments } from 'yaml'
+
+import { LINE_SPLIT_RE, MODELINE_RE, stripBom } from './yaml.mjs'
+
+const PATCH_NODE_SELECTOR_PATH_RE = /path:\s*\/spec\/template\/spec\/nodeSelector\b/u
+const PATCH_PREEM_FALSE_RE = /\bpreem:\s*['"]?false['"]?\b/u
+const PATCH_HOSTNAMES_PATH_RE = /path:\s*\/spec\/hostnames\b/mu
+// Overlay namespaces: дозволено `ua` і `ua-*` (наприклад `ua-b2b`).
+const PATCH_PARENT_REF_NS_UA_RE =
+  /path:\s*\/spec\/parentRefs\/0\/namespace\b[\s\S]{0,200}?value:\s*['"]?ua(?:-[a-z0-9][a-z0-9-]*)?['"]?(?:\s|$)/imu
+
+/** Домени `hostnames` для overlay `ua` (підрядки у JSON6902-тексті patch). */
+const ABIE_UA_HTTPROUTE_HOST_MARKERS = ['abie.app', 'vybeerai.com.ua', '*.abie.app', '*.vybeerai.com.ua']
+
+// ── nodeSelector (ua) ─────────────────────────────────────────────────────
+
+/**
+ * Чи patch-рядок містить очікуваний ua nodeSelector (preem: false).
+ * @param {string} patchText опис.
+ * @returns {boolean} результат
+ */
+function jsonPatchTextHasUaDeploymentNodeSelector(patchText) {
+  if (typeof patchText !== 'string' || patchText.trim() === '') return false
+  if (!PATCH_NODE_SELECTOR_PATH_RE.test(patchText)) return false
+  return !!PATCH_PREEM_FALSE_RE.test(patchText)
+}
+
+/**
+ * Чи один елемент `patches` відповідає abie nodeSelector для `mode`.
+ * @param {unknown} p опис.
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
+ */
+function inlineKustomizationPatchMatchesAbieMode(p, mode) {
+  if (p === null || typeof p !== 'object' || Array.isArray(p)) return false
+  const pr = /** @type {Record<string, unknown>} */ (p)
+  const target = pr.target
+  if (target === null || typeof target !== 'object' || Array.isArray(target)) return false
+  const tg = /** @type {Record<string, unknown>} */ (target)
+  if (tg.kind !== 'Deployment') return false
+  const patchStr = pr.patch
+  if (typeof patchStr !== 'string') return false
+  return Boolean(mode === 'ua' && jsonPatchTextHasUaDeploymentNodeSelector(patchStr))
+}
+
+/**
+ * Чи документ Kustomization містить відповідний inline patch на Deployment.
+ * @param {import('yaml').Document} doc опис.
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
+ */
+function kustomizationDocumentHasAbieDeploymentNodeSelectorPatch(doc, mode) {
+  if (doc.errors.length > 0) return false
+  const root = doc.toJSON()
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) return false
+  const rec = /** @type {Record<string, unknown>} */ (root)
+  if (rec.kind !== 'Kustomization') return false
+  const patches = rec.patches
+  if (!Array.isArray(patches)) return false
+  for (const p of patches) {
+    if (inlineKustomizationPatchMatchesAbieMode(p, mode)) return true
+  }
+  return false
+}
+
+/**
+ * Чи `kustomization.yaml` містить валідні inline patch для Deployment nodeSelector (ua).
+ * @param {string} raw повний текст файла
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
+ */
+export function kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode) {
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  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 {
+    return false
+  }
+  for (const doc of docs) {
+    if (kustomizationDocumentHasAbieDeploymentNodeSelectorPatch(doc, mode)) return true
+  }
+  return false
+}
+
+// ── HTTPRoute (ua) ────────────────────────────────────────────────────────
+
+/**
+ * @param {unknown} p опис.
+ * @returns {string | null} результат
+ */
+function extractHttpRoutePatchString(p) {
+  if (p === null || typeof p !== 'object' || Array.isArray(p)) return null
+  const pr = /** @type {Record<string, unknown>} */ (p)
+  const target = pr.target
+  if (target === null || typeof target !== 'object' || Array.isArray(target)) return null
+  const tg = /** @type {Record<string, unknown>} */ (target)
+  if (tg.kind !== 'HTTPRoute' || typeof tg.name !== 'string' || tg.name.trim() === '') return null
+  const patchStr = pr.patch
+  return typeof patchStr === 'string' && patchStr.trim() !== '' ? patchStr : null
+}
+
+/**
+ * Збирає inline `patch`-рядки для HTTPRoute (непорожній `target.name`) з одного Kustomization-документа.
+ * @param {import('yaml').Document} doc опис.
+ * @returns {string[]} результат
+ */
+function collectAbieHttpRoutePatchStringsFromKustomizationDoc(doc) {
+  if (doc.errors.length > 0) return []
+  const root = doc.toJSON()
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) return []
+  const rec = /** @type {Record<string, unknown>} */ (root)
+  if (rec.kind !== 'Kustomization' || !Array.isArray(rec.patches)) return []
+  /** @type {string[]} */
+  const out = []
+  for (const p of rec.patches) {
+    const s = extractHttpRoutePatchString(p)
+    if (s !== null) out.push(s)
+  }
+  return out
+}
+
+/**
+ * Збирає всі inline JSON6902-фрагменти HTTPRoute (непорожній `target.name`) у kustomization.yaml.
+ * @param {string} raw повний текст файла
+ * @returns {string} результат
+ */
+export function getCombinedNginxRunPatchTextFromKustomization(raw) {
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  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 {
+    return ''
+  }
+  /** @type {string[]} */
+  const chunks = []
+  for (const doc of docs) {
+    chunks.push(...collectAbieHttpRoutePatchStringsFromKustomizationDoc(doc))
+  }
+  return chunks.join('\n')
+}
+
+/**
+ * Рахує операції JSON6902 з `path: /spec/rules/.../backendRefs/.../namespace` і `value: ua[-…]`.
+ * @param {string} combined сукупний текст patch
+ * @param {'ua'} mode опис.
+ * @returns {number} результат
+ */
+function countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode) {
+  if (mode !== 'ua') return 0
+  const re =
+    /path:\s*\/spec\/rules\/\d+\/backendRefs\/\d+\/namespace\b[\s\S]{0,200}?value:\s*['"]?ua(?:-[a-z0-9][a-z0-9-]*)?['"]?(?:\s|$)/gimu
+  return combined.matchAll(re).toArray().length
+}
+
+/**
+ * Перевіряє сукупний текст patch(ів) HTTPRoute на відповідність abie.mdc.
+ * @param {string} combined сукупний текст patch
+ * @param {'ua'} mode опис.
+ * @param {string} [_fullKustomizationRaw] зберігається для API-сумісності, не використовується
+ * @param {number} [sharedCrossNsBackendRefCount] кількість `auth-run-hl`/`file-link-hl` у base HTTPRoute
+ * @returns {string | null} повідомлення про помилку або null
+ */
+export function validateAbieNginxRunHttpRoutePatches(
+  combined,
+  mode,
+  _fullKustomizationRaw,
+  sharedCrossNsBackendRefCount = 0
+) {
+  if (typeof combined !== 'string' || combined.trim() === '') {
+    return `очікується patch target kind HTTPRoute з непорожнім target.name (hostnames, parentRefs namespace ${mode}) — abie.mdc`
+  }
+  if (!PATCH_HOSTNAMES_PATH_RE.test(combined)) {
+    return 'HTTPRoute: потрібен path /spec/hostnames у patch (abie.mdc)'
+  }
+  const markers = ABIE_UA_HTTPROUTE_HOST_MARKERS
+  if (markers.every(m => !combined.includes(m))) {
+    return `HTTPRoute: у value для /spec/hostnames має бути один із доменів abie (${markers.join(', ')}) — abie.mdc`
+  }
+  if (!PATCH_PARENT_REF_NS_UA_RE.test(combined)) {
+    return `HTTPRoute: потрібен path /spec/parentRefs/0/namespace з value ${mode} (abie.mdc)`
+  }
+  const sharedCount =
+    typeof sharedCrossNsBackendRefCount === 'number' && Number.isFinite(sharedCrossNsBackendRefCount)
+      ? Math.max(0, Math.floor(sharedCrossNsBackendRefCount))
+      : 0
+  if (sharedCount > 0) {
+    const patchHits = countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode)
+    if (patchHits < sharedCount) {
+      return `HTTPRoute: для backendRefs до спільних сервісів auth-run-hl, file-link-hl очікується ${sharedCount} JSON6902 patch(ів) з path /spec/rules/…/backendRefs/…/namespace та value ${mode} (зараз ${patchHits}) — abie.mdc`
+    }
+  }
+  return null
+}

package/rules/abie/lib/overlay-paths.mjs

@@ -0,0 +1,97 @@
+/**
+ * Path-хелпери для overlay-перевірок abie:
+ *   - класифікація шляхів (`isUaKustomizationPath`, `isAbieK8sBaseYamlPath`),
+ *   - вилучення каталогу пакета з overlay-шляху (`abiePackageDirFromK8sOverlay`),
+ *   - умовний gate для HTTPRoute через наявність `vite.config.*` (`abieOverlayRequiresHttpRouteByVite`),
+ *   - перевірка наявності `Deployment` у дереві пакета (`abieOverlayK8sTreeHasDeployment`),
+ *   - чи yaml належить base-шару пакета (`isK8sYamlInAbiePackageExcludingUaOverlay`).
+ */
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const UA_KUSTOMIZATION_PATH_RE = /(^|\/)ua\/kustomization\.yaml$/u
+const OVERLAY_PACKAGE_DIR_RE = /^(.+)\/k8s\/ua\/kustomization\.yaml$/u
+const BASE_SEGMENT_RE = /(^|\/)base\//u
+const TRAILING_SLASH_RE = /\/$/u
+
+/**
+ * Чи `rel` — це `…/ua/kustomization.yaml` (abie overlay).
+ * @param {string} rel posix-шлях від кореня репозиторію
+ * @returns {boolean} результат
+ */
+export function isUaKustomizationPath(rel) {
+  const norm = rel.replaceAll('\\', '/')
+  return UA_KUSTOMIZATION_PATH_RE.test(norm)
+}
+
+/**
+ * Каталог пакета (батько `k8s/`) для overlay `…/k8s/ua/kustomization.yaml`.
+ * @param {string} root корінь репозиторію
+ * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
+ * @returns {string | null} результат
+ */
+export function abiePackageDirFromK8sOverlay(root, kustomizationAbs) {
+  const rel = relative(root, kustomizationAbs).replaceAll('\\', '/') || kustomizationAbs
+  const m = rel.match(OVERLAY_PACKAGE_DIR_RE)
+  return m ? join(root, m[1]) : null
+}
+
+/**
+ * Чи у каталозі пакета (батько `k8s/`) є `vite.config.{js,mjs,ts}` — HTTPRoute-вимога abie
+ * застосовується лише до Vite-пакетів.
+ * @param {string} root корінь репозиторію
+ * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
+ * @returns {boolean} результат
+ */
+export function abieOverlayRequiresHttpRouteByVite(root, kustomizationAbs) {
+  const pkg = abiePackageDirFromK8sOverlay(root, kustomizationAbs)
+  if (!pkg) return false
+  return (
+    existsSync(join(pkg, 'vite.config.js')) ||
+    existsSync(join(pkg, 'vite.config.mjs')) ||
+    existsSync(join(pkg, 'vite.config.ts'))
+  )
+}
+
+/**
+ * Чи у дереві `k8s/` пакета є `Deployment` (за каталогами з `collectDeploymentDirs`).
+ * @param {Set<string>} deploymentDirs абсолютні каталоги з Deployment
+ * @param {string} root корінь репозиторію
+ * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
+ * @returns {boolean} результат
+ */
+export function abieOverlayK8sTreeHasDeployment(deploymentDirs, root, kustomizationAbs) {
+  const pkg = abiePackageDirFromK8sOverlay(root, kustomizationAbs)
+  if (!pkg) return false
+  const k8sRoot = join(pkg, 'k8s').replaceAll('\\', '/')
+  for (const dir of deploymentDirs) {
+    const norm = dir.replaceAll('\\', '/')
+    if (norm === k8sRoot || norm.startsWith(`${k8sRoot}/`)) return true
+  }
+  return false
+}
+
+/**
+ * Чи rel-шлях `…/k8s/base/…` (base-шар abie, не overlay).
+ * @param {string} rel опис.
+ * @returns {boolean} результат
+ */
+export function isAbieK8sBaseYamlPath(rel) {
+  const norm = rel.replaceAll('\\', '/')
+  return BASE_SEGMENT_RE.test(norm)
+}
+
+/**
+ * Чи yaml належить до `<pkgRel>/k8s/**` поза `ua/` піддеревом (base-шар abie).
+ * @param {string} relFromRoot шлях від кореня
+ * @param {string} pkgRelFromRoot каталог пакета від кореня
+ * @returns {boolean} результат
+ */
+export function isK8sYamlInAbiePackageExcludingUaOverlay(relFromRoot, pkgRelFromRoot) {
+  const normRel = relFromRoot.replaceAll('\\', '/')
+  const pkg = pkgRelFromRoot.replaceAll('\\', '/').replace(TRAILING_SLASH_RE, '')
+  const prefix = `${pkg}/k8s/`
+  if (!normRel.startsWith(prefix)) return false
+  const after = normRel.slice(prefix.length)
+  return !after.startsWith('ua/')
+}

package/rules/abie/lib/yaml.mjs

@@ -0,0 +1,72 @@
+/**
+ * Спільні YAML-хелпери для abie-перевірок: парсинг документів з опційним modeline,
+ * BOM-strip, regex для `# yaml-language-server: $schema=` і поділу на рядки.
+ */
+import { readFile } from 'node:fs/promises'
+
+import { parseAllDocuments } from 'yaml'
+
+export const MODELINE_RE = /^#\s*yaml-language-server:\s*\$schema=(\S+)\s*$/
+export const LINE_SPLIT_RE = /\r?\n/u
+
+/**
+ * Прибирає BOM на початку файлу.
+ * @param {string} s вміст
+ * @returns {string} результат
+ */
+export function stripBom(s) {
+  return s.startsWith('') ? s.slice(1) : s
+}
+
+/**
+ * Чи YAML-документ — це `kind: Deployment`.
+ * @param {unknown} obj корінь YAML-документа
+ * @returns {boolean} результат
+ */
+export function isDeploymentDoc(obj) {
+  return (
+    obj !== null &&
+    typeof obj === 'object' &&
+    !Array.isArray(obj) &&
+    /** @type {Record<string, unknown>} */ (obj).kind === 'Deployment'
+  )
+}
+
+/**
+ * No-op fail-handler для функцій, що мовчки повертають null/[] при помилці парсингу.
+ * @param {string} _msg ігнорується
+ */
+export const silentFail = _msg => {
+  /* silent — пошкоджені файли ловить check-k8s */
+}
+
+/**
+ * Зчитує і парсить YAML-документи з файлу. BOM і modeline (перший рядок `$schema`)
+ * автоматично прибираються перед `parseAllDocuments`. При помилці читання/парсингу
+ * викликає `failFn` і повертає `null`.
+ * @param {string} abs абсолютний шлях
+ * @param {string} rel відносний (для повідомлень)
+ * @param {(msg: string) => void} failFn опис.
+ * @returns {Promise<import('yaml').Document[] | null>} результат
+ */
+export async function readAndParseYamlDocs(abs, rel, failFn) {
+  let raw
+  try {
+    raw = await readFile(abs, 'utf8')
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    failFn(`${rel}: не вдалося прочитати (${msg})`)
+    return null
+  }
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  const first = lines[0] ?? ''
+  const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
+  try {
+    return parseAllDocuments(rest)
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    failFn(`${rel}: YAML (${msg})`)
+    return null
+  }
+}

package/rules/abie/main.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "repoUrlMarker", "arg": "https://github.com/abinbevefes/" } }

package/rules/abie/main.mdc

@@ -0,0 +1,47 @@
+---
+description: Правила для проєктів AbInBev Efes
+alwaysApply: true
+version: '1.22'
+---
+
+Правило **abie** для споживачів **@7n/rules**: **k8s** (Deployment + **HealthCheckPolicy** у **`hc.yaml`**, overlay **ua** — **nodeSelector**, **HTTPRoute** (будь-який непорожній **`target.name`**, для спільних сервісів **`auth-run-hl`** / **`file-link-hl`** — **`namespace: dev`** у base та patch **`…/backendRefs/…/namespace`** у **ua**)), гілки **dev**, **ua** у **clean-merged-branch**, а також заборона тримати артефакти **Firebase Hosting** у **підкаталогах першого рівня** (безпосередні діти кореня репозиторію; у самому корені ці імена не вимагаються до видалення).
+
+## Активація
+
+Правило активується через **`.n-rules.json`** у корені репозиторію:
+
+```json
+{ "rules": ["abie"] }
+```
+
+Без цього запису `@7n/rules` пропускає всі abie-перевірки (JS-концерни та rego-полісі).
+
+## `@nitra/abie-shared` у `devDependencies`
+
+У кореневому **`package.json`** abie-проєкту в **`devDependencies`** має бути **`@nitra/abie-shared`** — пакет зі спільними abie-ресурсами: канонічні GraphQL-схеми, скіли, типи (наприклад, шляхи `node_modules/@nitra/abie-shared/schema/...` для імпорту схем). Версію правило не фіксує — лише presence. Додати:
+
+```bash
+bun add -d @nitra/abie-shared
+```
+
+## Git branches
+
+У **`.github/workflows/clean-merged-branch.yml`** у кроці **`phpdocker-io/github-actions-delete-abandoned-branches`** значення **`with.ignore_branches`** має містити **dev** та **ua** (разом з іншими гілками, якщо потрібно):
+
+- abie-specific канон (action marker + required ignore_branches tokens): [clean-merged-branch.yml.snippet.yml](./clean_merged_ignore_branches/template/clean-merged-branch.yml.snippet.yml)
+
+## Швидкий gate через conftest (Rego)
+
+Підмножину пер-документних правил продубльовано як rego-полісі у **`npm/rules/abie/policy/`** (запускається через **`bun run lint-rego`** для `*_test.rego` юніт-тестів і через **`npx @7n/rules fix abie`** для прогону по реальних YAML — деталі в **conftest.mdc** / **n-rego.mdc**). JS у **`js/<concern>.mjs`** authoritative — rego тільки швидкий gate для одиничного маніфеста (зокрема через IDE-розширення `tsandall.opa`).
+
+Пакети (директорія в **`npm/policy/abie/`** → namespace → що перевіряє):
+
+Cross-file / FS-логіка лишається у JS-частинах (`js/<concern>.mjs`) — Rego не читає файлову систему й не робить cross-document резолюцію:
+
+- парність HCP↔Deployment у каталозі та modeline `hc.yaml` — `js/hc_pairing.mjs`;
+- валідація ua-overlay JSON6902 patches на HTTPRoute + аналіз cross-namespace `backendRefs` у пакетах — `js/ua_http_route.mjs`;
+- ua-overlay JSON6902 patch на `Deployment.nodeSelector` (`preem: false`) — `js/ua_node_selector.mjs`;
+- env→cluster DNS (`*.dev.env` / `*.ua.env`) — `js/env_dns.mjs`;
+- скан артефактів Firebase Hosting у підкаталогах першого рівня — `js/firebase_hosting.mjs`.
+
+Точна звірка `targetRef.name` HealthCheckPolicy з суфіксом `-hl` обчислюється з `hcp.metadata.name` і живе у Rego (`abie.health_check_policy`); за конвенцією `hcp.metadata.name` дорівнює `<deployment.name>`, тому окремий cross-file lookup до маніфесту Deployment не потрібен.

package/rules/abie/package_json_shared/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": "package.json",
+      "required": true
+    },
+    "missingMessage": "package.json не існує — створи його, додай devDependencies['@nitra/abie-shared'] (abie.mdc)"
+  }
+}

package/rules/abie/package_json_shared/package_json_shared.mdc

@@ -0,0 +1,17 @@
+## Rego: `@nitra/abie-shared` у `devDependencies`
+
+Rego-пакет: `abie.package_json_shared`
+
+Цільовий файл: `package.json` (кореневий).
+
+Перевіряє presence-only: `devDependencies` має містити ключ `@nitra/abie-shared`. Версію не фіксує. Якщо ключ є лише у `dependencies` (не `devDependencies`) — deny.
+
+JS-опис та інструкція встановлення — у секції «`@nitra/abie-shared` у `devDependencies`» в `main.mdc`.
+
+```json title="package.json (фрагмент)"
+{
+  "devDependencies": {
+    "@nitra/abie-shared": "^1.0.0"   // ✓
+  }
+}
+```

package/rules/abie/package_json_shared/package_json_shared.rego

@@ -0,0 +1,16 @@
+# Перевірка кореневого `package.json` abie-проєкту: у `devDependencies` має бути
+# `@nitra/abie-shared` (контракти/схеми/скіли abie-сервісів — наприклад
+# `node_modules/@nitra/abie-shared/...`). Версію не фіксуємо — лише presence.
+#
+# Inverse-presence перевірка — лишається inline у rego (як `@nitra/cspell-dict`
+# у `text.package_json`), бо у template/ зберігаємо позитивні snippet/deny канони,
+# а не одиничний required-ключ.
+package abie.package_json_shared
+
+import rego.v1
+
+deny contains msg if {
+	dev := object.get(input, "devDependencies", {})
+	not "@nitra/abie-shared" in object.keys(dev)
+	msg := "package.json: devDependencies має містити @nitra/abie-shared — bun add -d @nitra/abie-shared (abie.mdc)"
+}

package/rules/abie/ua_http_route/concern.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": { "scope": "full", "glob": ["**/k8s/**/*.{yaml,yml}"] }
+}

package/rules/abie/ua_http_route/docs/main.md

@@ -0,0 +1,44 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/abie/ua_http_route/main.mjs
+docgen:
+  crc: 1e0f205a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Огляд: Цей компонент забезпечує функціональність аналізу, що реалізована через публічну функцію `lint`. Він виконує операції з кешуванням у межах одного прогону та обробляє помилки у режимі fail-safe, що гарантує відсутність винятків у зовнішньому середовищі.
+
+## Поведінка
+
+1. Ініціалізує звіт про порушення.
+2. Зчитує списки шляхів, які слід ігнорувати.
+3. Знаходить усі файли YAML в каталозі.
+4. Фільтрує знайдені YAML-файли, щоб визначити ті, що стосуються конфігурації UA Kustomization.
+5. Якщо таких файлів немає, завершує роботу з успіхом, оскільки патч HTTPRoute (ua) не потрібен.
+6. Для кожного релевантного YAML-файлу:
+    а. Визначає відповідний каталог пакета abie.
+    б. Якщо пакет не вимагає патчу HTTPRoute за допомогою Vite, пропускає цей файл з успішним повідомленням.
+    в. Аналізує посилання на загальні бекенди у пакеті, кешуючи результат.
+    г. Зчитує вміст YAML-файлу.
+    д. Комбінує вміст для формування патча Nginx Run.
+    е. Валідує отриманий патч.
+    ж. Якщо валідація успішна, фіксує успіх.
+    з. Якщо виникають будь-які помилки (не вдалося прочитати, внутрішні помилки, відхилення валідації), фіксує це як порушення.
+7. Повертає фінальний результат лінту, що містить усі зафіксовані порушення.
+
+## Публічний API
+
+lint — перевіряє дотримання правил для UA HTTP-route overlay concern-а abie.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.

package/rules/abie/ua_http_route/main.mjs

@@ -0,0 +1,80 @@
+/** @see ./docs/ua_http_route.md */
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
+
+import { analyzeAbieSharedBackendRefsInPackageK8s } from '../lib/http-route.mjs'
+import { findK8sYamlFiles } from '../lib/k8s-tree.mjs'
+import {
+  getCombinedNginxRunPatchTextFromKustomization,
+  validateAbieNginxRunHttpRoutePatches
+} from '../lib/kustomization-patches.mjs'
+import {
+  abiePackageDirFromK8sOverlay,
+  abieOverlayRequiresHttpRouteByVite,
+  isUaKustomizationPath
+} from '../lib/overlay-paths.mjs'
+
+/**
+ * Лінтить UA HTTP-route overlay concern-а abie.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx Контекст лінту (`cwd` тощо).
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} Результат лінту зі списком violations.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+  const root = ctx.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.result()
+  }
+
+  /** @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) pass(`${rel}: HTTPRoute patch (ua) відповідає abie.mdc`)
+    else fail(`${rel}: ${v}`)
+  }
+
+  return reporter.result()
+}

package/rules/abie/ua_http_route/ua_http_route.mdc

@@ -0,0 +1,47 @@
+## k8s: overlay **HTTPRoute** (**ua**)
+
+За наявності **Deployment** під **k8s** і наявності **Vite** (**`vite.config.js`**, **`vite.config.mjs`** або **`vite.config.ts`** у каталозі пакета) у **`ua/kustomization.yaml`** цього пакета потрібні **inline JSON6902** у **`patches`**: **target** **`kind: HTTPRoute`**, **непорожній `name`** (як у маніфесті маршруту). Мають бути зміни **`/spec/hostnames`** (хоча б один з доменів: **`abie.app`**, **`vybeerai.com.ua`**, **`*.abie.app`**, **`*.vybeerai.com.ua`**) та **`/spec/parentRefs/0/namespace`** (**`ua`**, також дозволені префікси **`ua-*`**, наприклад **`ua-b2b`**). Як обирати **`op`** (**add** / **replace** тощо) у patch — **k8s.mdc** (розділ про JSON patch у kustomization).
+
+### HTTPRoute: спільні сервіси **`auth-run-hl`**, **`file-link-hl`**
+
+У **HTTPRoute** у шляху з **`…/k8s/base/…`** у **`spec.hostnames`** дозволені лише **`aiml.live`**, **`*.aiml.live`** та інші піддомени **aiml.live** (перевірка — Rego-пакет **`abie.http_route_base`**, див. розділ нижче).
+
+Ці **Service** (headless **`-hl`**) живуть у **базовому** неймспейсі **`dev`**. У маніфесті **HTTPRoute** під **`k8s`** (шар без **`ua/`** — наприклад **`…/k8s/base/hr.yaml`**) для кожного **`backendRefs`** до такого сервісу явно вкажи **`namespace: dev`** і порт **8080**:
+
+```yaml title="…/k8s/base/hr.yaml (фрагмент)"
+spec:
+  rules:
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /
+      backendRefs:
+        - name: auth-run-hl
+          namespace: dev
+          port: 8080
+        - name: file-link-hl
+          namespace: dev
+          port: 8080
+```
+
+У **`ua/kustomization.yaml`** додай до того самого **inline** patch на **`HTTPRoute`** (той самий **`target.name`**) операції **JSON6902** з **`path`**: **`/spec/rules/<i>/backendRefs/<j>/namespace`**, де **`<i>`** / **`<j>`** — індекси відповідно до порядку **`spec.rules`** та **`backendRefs`** у base-файлі; **`value`**: **`ua`** (також дозволені **`ua-*`**). Якщо кілька таких **`backendRefs`**, потрібна окрема операція для кожного.
+
+```yaml title="…/ua/kustomization.yaml (фрагмент)"
+  - target:
+      kind: HTTPRoute
+      name: my-httproute
+    patch: |-
+      - op: replace
+        path: /spec/hostnames
+        value:
+          - "abie.app" # зокрема vybeerai.com.ua, *.vybeerai.com.ua, *.abie.app
+      - op: replace
+        path: /spec/parentRefs/0/namespace
+        value: ua
+      - op: replace
+        path: /spec/rules/0/backendRefs/0/namespace
+        value: ua
+      - op: replace
+        path: /spec/rules/0/backendRefs/1/namespace
+        value: ua
+```