---
docgen:
  source: npm/rules/abie/lib/overlay-paths.mjs
  crc: 752f7012
---

# overlay-paths

## Огляд

Набір 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/`-піддерева враховує точний збіг кореня й порівнює з межею `/`, тож не дає хибних спрацювань на сусідніх каталогах із подібним префіксом.
