@7n/rules 1.0.0

package/rules/abie/lib/docs/kustomization-patches.md

@@ -0,0 +1,37 @@
+---
+type: JS Module
+title: kustomization-patches.mjs
+resource: npm/rules/abie/lib/kustomization-patches.mjs
+docgen:
+  crc: cc6c6707
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль відповідає за парсинг inline JSON6902-патчів у конфігурації `abie ua-kustomization`. Він спеціалізується на витягуванні даних із патчів `nodeSelector` для об'єктів `Deployment` (з умовою `preem: false`), а також на обробці патчів `HTTPRoute` для визначення хостнеймів, імен просторів імен `parentRefs` та `backendRefs`. (abie.mdc)
+
+Модуль забезпечує відмовостійкість, перехоплюючи потенційні помилки, що виникають під час парсингу, і не викликаючи винятків назовні. За певних умов помилок повертає `null` замість генерації винятку.
+
+## Поведінка
+
+Поведінка:
+kustomizationHasAbieDeploymentNodeSelectorPatch визначає, чи містить документ Kustomization відповідний inline patch на `Deployment` для режиму `ua`.
+getCombinedNginxRunPatchTextFromKustomization збирає всі inline JSON6902-фрагменти для `HTTPRoute` з усіх документів Kustomization у вигляді одного тексту.
+validateAbieNginxRunHttpRoutePatches перевіряє сукупний текст patch HTTPRoute на відповідність вимогам abie.mdc, зокрема щодо доменів, `parentRefs` namespace та кількості `backendRefs` для спільних сервісів, при цьому не перевіряє жодних внутрішніх прихованих змінних.
+
+## Публічний API
+
+kustomizationHasAbieDeploymentNodeSelectorPatch — Встановлює, чи містить файл `kustomization.yaml` коректний внутрішній патч для узгодження селектора нод у Deployment (українська версія).
+getCombinedNginxRunPatchTextFromKustomization — Збирає до одного тексту всі фрагменти JSON6902 HTTPRoute, які не є порожніми та містяться в `kustomization.yaml`.
+validateAbieNginxRunHttpRoutePatches — Порівнює зібраний текст патчів HTTPRoute з вимогами, зазначеними у файлі `abie.mdc`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/abie/lib/docs/overlay-paths.md

@@ -0,0 +1,42 @@
+---
+type: JS Module
+title: overlay-paths.mjs
+resource: npm/rules/abie/lib/overlay-paths.mjs
+docgen:
+  crc: 752f7012
+---
+
+Набір path-хелперів для перевірок правила abie, що працює з k8s-структурою пакетів монорепо. Розрізняє base-шар пакета та `ua/` overlay, виводить каталог пакета зі шляху overlay і визначає, які додаткові вимоги (HTTPRoute, Deployment) застосовуються до конкретного overlay. Усі хелпери — чисті обчислення над шляхами без побічних ефектів, окрім перевірок наявності файлів `vite.config.*` на диску.
+
+## Поведінка
+
+Очікувана структура пакета, з якою працює модуль:
+
+```
+<пакет>/
+  k8s/
+    base/...               ← base-шар
+    ua/
+      kustomization.yaml    ← abie overlay
+  vite.config.{js,mjs,ts}   ← опційно, ознака Vite-пакета
+```
+
+1. Розпізнавання overlay-маніфесту: шлях, що закінчується на `…/ua/kustomization.yaml`, вважається abie overlay. Перед матчингом backslash-роздільники нормалізуються в `/`, тож перевірка однакова на Windows і POSIX.
+
+2. Виведення каталогу пакета: для overlay вигляду `…/k8s/ua/kustomization.yaml` обчислюється абсолютний шлях до каталогу пакета (батько `k8s/`). Якщо шлях не відповідає цьому шаблону — повертається `null`, що сигналізує, що це не валідний overlay-маніфест abie-пакета.
+
+3. Gate на HTTPRoute за наявністю Vite: вимога HTTPRoute застосовується до overlay лише тоді, коли в каталозі пакета присутній один із `vite.config.js`, `vite.config.mjs` або `vite.config.ts`. Для не-Vite пакетів вимога не вмикається. Якщо каталог пакета вивести не вдалося — вимога теж не вмикається.
+
+4. Наявність Deployment у дереві пакета: перевіряється, чи серед заздалегідь зібраного набору каталогів із Deployment є хоча б один усередині `k8s/`-піддерева цього пакета (сам корінь `k8s/` або будь-який вкладений каталог). Набір каталогів передається ззовні — модуль сам файлову систему не сканує.
+
+5. Розрізнення base vs overlay для yaml-файлу:
+   - швидка ознака base-шару — наявність сегмента `base/` будь-де у шляху;
+   - точніша перевірка приналежності до base конкретного пакета — yaml має лежати під `<пакет>/k8s/`, але поза піддеревом `ua/`. Файли overlay (`ua/`) виключаються.
+
+## Гарантії поведінки
+
+- Хелпери read-only щодо вмісту файлів; єдина взаємодія з ФС — перевірка існування `vite.config.*`. Вони не читають, не пишуть і не модифікують файли.
+- Шляхи з `\` нормалізуються в `/` перед порівнянням, тож результати не залежать від ОС.
+- Якщо overlay-шлях не відповідає очікуваному шаблону `…/k8s/ua/kustomization.yaml`, обчислення каталогу пакета повертає `null`, а похідні від нього перевірки (HTTPRoute, Deployment) безпечно повертають `false` замість помилки.
+- Кінцевий слеш у переданому каталозі пакета ігнорується при перевірці приналежності yaml до base-шару.
+- Перевірка приналежності до `k8s/`-піддерева враховує точний збіг кореня й порівнює з межею `/`, тож не дає хибних спрацювань на сусідніх каталогах із подібним префіксом.

package/rules/abie/lib/docs/yaml.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: yaml.mjs
+resource: npm/rules/abie/lib/yaml.mjs
+docgen:
+  crc: 1b50e492
+---
+
+Спільний набір YAML-хелперів для перевірок правила `abie`. Інкапсулює читання й розбір YAML-файлів Kubernetes-маніфестів так, щоб усі abie-перевірки розбирали вміст однаково: з прибиранням BOM, ігноруванням службового modeline-рядка `# yaml-language-server: $schema=` і fail-safe-поведінкою при пошкоджених файлах.
+
+## Поведінка
+
+Читання й розбір YAML-документів з файлу:
+
+1. Намагається прочитати файл за абсолютним шляхом. Якщо читання не вдалося — викликає переданий обробник помилок із повідомленням, що включає відносний шлях і причину, і повертає `null`.
+2. Прибирає BOM на початку вмісту, якщо він є.
+3. Якщо перший рядок — це YAML-language-server modeline (`# yaml-language-server: $schema=...`), пропускає його перед розбором; решта вмісту парситься без нього. Інакше парситься весь вміст.
+4. Розбирає всі YAML-документи у файлі (мультидокументні файли з `---` підтримуються). При помилці розбору викликає обробник помилок із повідомленням і повертає `null`; інакше повертає масив розібраних документів.
+
+Окремо надає предикат розпізнавання маніфестів `Deployment`: документ вважається `Deployment`, лише якщо це звичайний об'єкт (не масив, не `null`) із полем `kind` рівним `'Deployment'`.
+
+Передбачено готовий «тихий» обробник помилок — для викликів, які мають мовчки повертати порожній результат при поганому вводі, бо пошкоджені файли діагностує окрема перевірка (`check-k8s`), а не abie.
+
+## Де використовується
+
+Хелпери імпортуються іншими модулями abie, що аналізують Kubernetes-маніфести, зокрема `lib/k8s-tree.mjs`, `lib/kustomization-patches.mjs`, `lib/http-route.mjs`, `lib/hc-yaml.mjs` та перевіркою `js/hc_pairing.mjs`.
+
+## Гарантії поведінки
+
+- Read-only: модуль лише читає й розбирає файли, не змінює їх.
+- Fail-safe: помилки читання чи розбору YAML не кидаються назовні — натомість викликається переданий обробник, а результатом стає `null`. Це дозволяє перевіркам пропускати биті файли замість падіння.
+- Розбір стійкий до BOM і до службового modeline-рядка `$schema` на першому рядку — вони не ламають парсинг і не потрапляють у результат.
+- Предикат розпізнавання `Deployment` безпечний для будь-якого вводу: повертає `false` для `null`, масивів і не-об'єктів, ніколи не кидає винятків.

package/rules/abie/lib/enabled.mjs

@@ -0,0 +1,37 @@
+/**
+ * Rule-level applies-гейт abie: чи `.n-rules.json:rules` (fallback — legacy `.n-cursor.json`) містить `abie`.
+ * Використовується `js/applies.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-rules.json'
+const LEGACY_CONFIG_FILE = '.n-cursor.json'
+
+/**
+ * Чи увімкнено правило **abie** у `.n-rules.json:rules`.
+ * @param {string} root корінь репозиторію (cwd)
+ * @returns {Promise<boolean>} `true` — `rules` містить `abie`; `false` — інакше
+ */
+export async function isAbieRuleEnabled(root) {
+  let p = join(root, CONFIG_FILE)
+  if (!existsSync(p)) p = join(root, LEGACY_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/lib/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(s)://<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 =
+  /\bhttps?:\/\/([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/lib/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/lib/http-route.mjs

@@ -0,0 +1,100 @@
+/**
+ * Cross-документна аналітика abie HTTPRoute: підрахунок `backendRefs` до спільних
+ * сервісів (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета (поза overlay `ua`).
+ * Використовується ua_http_route-концерном для синхронізації числа patch-ів namespace
+ * у overlay із кількістю base-reference.
+ */
+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)`)
+  }
+  if (brRec.port !== 8080) {
+    errors.push(`${rel}: HTTPRoute backendRefs до ${name} має містити port: 8080 (abie.mdc)`)
+  }
+  return 1
+}
+
+/**
+ * Збирає по HTTPRoute-документу кількість посилань на shared backends і порушення namespace.
+ * @param {unknown} obj корінь YAML
+ * @param {string} rel опис.
+ * @returns {{ refCount: number, errors: string[] }} статистика shared-backend посилань і порушення namespace
+ */
+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))) {
+      continue
+    }
+
+    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[] }>} агрегована статистика й помилки base-шару
+ */
+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) {
+            continue
+          }
+
+          const json = doc.toJSON()
+          const st = httpRouteDocSharedCrossNsBackendStats(json, rel)
+          refCount += st.refCount
+          baseErrors.push(...st.errors)
+        }
+      }
+    }
+  }
+  return { refCount, baseErrors }
+}

package/rules/abie/lib/k8s-tree.mjs

@@ -0,0 +1,110 @@
+/**
+ * Обхід k8s-дерева abie з кешуванням на час одного прогону:
+ *   - `findK8sYamlFiles(root, ignorePaths)` — yaml/yml файли під сегментом `k8s/`.
+ *   - `collectDeploymentDirs(root, yamlAbs)` — каталоги, де знайдено `kind: Deployment`.
+ *
+ * Кеш — module-level singleton, ключований за `(root, ignorePaths)`. Перший виклик
+ * платить за обхід; наступні концерни в межах того ж прогону отримують готове.
+ */
+import { dirname, relative } from 'node:path'
+
+import { pathHasK8sSegment } from '../../k8s/manifests/main.mjs'
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+import { isDeploymentDoc, readAndParseYamlDocs } from './yaml.mjs'
+
+const YAML_EXTENSION_RE = /\.ya?ml$/iu
+
+/** @type {Map<string, Promise<string[]>>} */
+const yamlCache = new Map()
+/** @type {Map<string, Promise<Set<string>>>} */
+const deploymentCache = new Map()
+
+/**
+ * Стабільний ключ кешу за (root, ignorePaths).
+ * @param {string} root опис.
+ * @param {string[]} ignorePaths опис.
+ * @returns {string} результат
+ */
+function cacheKey(root, ignorePaths) {
+  return `${root}|${[...ignorePaths].toSorted((a, b) => a.localeCompare(b)).join(':')}`
+}
+
+/**
+ * Збирає абсолютні шляхи до `.yaml`/`.yml` під деревом, де є сегмент `k8s/`.
+ * Каталог `.github/` свідомо пропускається (належить `ga.mdc`).
+ * @param {string} root корінь репозиторію
+ * @param {string[]} [ignorePaths] абсолютні шляхи каталогів-виключень
+ * @returns {Promise<string[]>} результат
+ */
+export function findK8sYamlFiles(root, ignorePaths = []) {
+  const key = cacheKey(root, ignorePaths)
+  const cached = yamlCache.get(key)
+  if (cached) return cached
+  const promise = (async () => {
+    /** @type {string[]} */
+    const out = []
+    await walkDir(
+      root,
+      p => {
+        const rel = relative(root, p).replaceAll('\\', '/')
+        if (rel.startsWith('.github/')) return
+        if (!pathHasK8sSegment(p, root)) return
+        if (!YAML_EXTENSION_RE.test(p)) return
+        out.push(p)
+      },
+      ignorePaths
+    )
+    return [...out].toSorted((a, b) => a.localeCompare(b))
+  })()
+  yamlCache.set(key, promise)
+  return promise
+}
+
+/**
+ * Каталоги, де є хоча б один `kind: Deployment` у YAML під `k8s/`.
+ * @param {string} root корінь репозиторію
+ * @param {string[]} yamlAbs абсолютні шляхи `.yaml`/`.yml` під `k8s/` (як з `findK8sYamlFiles`)
+ * @param {(msg: string) => void} [fail] репортер помилок парсингу (опц.)
+ * @returns {Promise<Set<string>>} абсолютні шляхи директорій
+ */
+/**
+ * No-op fail-handler за замовчуванням для `collectDeploymentDirs` — пошкоджені YAML
+ * під час cross-rule сканування мовчки пропускаються; формальний reporter передає сам caller.
+ * @param {string} _msg повідомлення про помилку (ігнорується)
+ */
+const silentFail = _msg => {
+  // noop
+}
+
+/**
+ * Знаходить унікальні каталоги, що містять Deployment-маніфести серед переданих YAML-файлів.
+ * Парсить документи через `readAndParseYamlDocs` і фільтрує лише ті, що є Deployment.
+ * Кешує результат за ключем `root|<sorted yamlAbs>`, щоб повторні виклики не робили I/O.
+ * @param {string} root абсолютний корінь репо для побудови relative-шляхів у повідомленнях
+ * @param {string[]} yamlAbs абсолютні шляхи до YAML-файлів для перевірки
+ * @param {(msg: string) => void} [fail] callback на помилку парсингу (за замовчуванням noop)
+ * @returns {Promise<Set<string>>} проміс із сетом абсолютних каталогів, де знайдено Deployment
+ */
+export function collectDeploymentDirs(root, yamlAbs, fail = silentFail) {
+  const key = `${root}|${[...yamlAbs].toSorted((a, b) => a.localeCompare(b)).join(':')}`
+  const cached = deploymentCache.get(key)
+  if (cached) return cached
+  const promise = (async () => {
+    /** @type {Set<string>} */
+    const dirs = new Set()
+    for (const abs of yamlAbs) {
+      const rel = relative(root, abs).replaceAll('\\', '/') || abs
+      const docs = await readAndParseYamlDocs(abs, rel, fail)
+      if (docs) {
+        for (const doc of docs) {
+          if (doc.errors.length === 0 && isDeploymentDoc(doc.toJSON())) {
+            dirs.add(dirname(abs))
+          }
+        }
+      }
+    }
+    return dirs
+  })()
+  deploymentCache.set(key, promise)
+  return promise
+}