---
docgen:
  source: npm/rules/abie/lib/k8s-tree.mjs
  crc: 077f3478
---

# k8s-tree

## Огляд

Модуль обходить дерево репозиторію й постачає правилу `abie` два набори даних про Kubernetes-маніфести: усі YAML-файли під сегментом `k8s/` та каталоги, що містять `Deployment`. Результати кешуються на час одного прогону (module-level singleton), тож кілька перевірок у межах однієї сесії перевикористовують єдиний обхід замість повторного I/O.

## Поведінка

Пошук YAML-файлів під `k8s/`:

1. Рекурсивно обходить дерево від кореня репозиторію, поважаючи передані шляхи-виключення.
2. Каталог `.github/` свідомо пропускається — він належить іншому правилу (`ga.mdc`).
3. До результату потрапляє файл лише якщо його шлях містить сегмент `k8s/` і має розширення `.yaml` чи `.yml`.
4. Повертає абсолютні шляхи, відсортовані за алфавітом (детермінований вивід).

Пошук каталогів із `Deployment`:

1. Приймає набір абсолютних шляхів до YAML-файлів (зазвичай результат попереднього кроку).
2. Кожен файл читається й розбивається на окремі YAML-документи.
3. Документ враховується лише якщо розпарсився без помилок і є маніфестом `kind: Deployment`.
4. Каталог кожного такого файлу додається до результуючого набору унікальних каталогів.
5. Пошкоджені або непарсабельні YAML за замовчуванням мовчки пропускаються; формальний reporter помилок caller може передати окремо.

## Публічний API

- `findK8sYamlFiles` — повертає відсортований список абсолютних шляхів до YAML-файлів під `k8s/`, з урахуванням виключень і пропуском `.github/`.
- `collectDeploymentDirs` — за набором YAML-файлів повертає множину абсолютних каталогів, де знайдено хоча б один `Deployment`-маніфест.

Обидві точки повертають Promise. Результат кожної кешується за стабільним ключем (для пошуку файлів — за коренем і набором виключень; для пошуку каталогів — за коренем і набором YAML-шляхів), тож повторний виклик із тими самими аргументами не виконує повторного обходу чи читання. У кеші зберігається сам Promise, тому конкурентні виклики з однаковим ключем склеюються в один реальний обхід файлової системи.

## Де використовується

Допоміжний модуль правила `abie` (`npm/rules/abie/`), що постачає спільні дані про Kubernetes-деплойменти для його перевірок.

## Гарантії поведінки

- Read-only: модуль лише читає файлову систему, нічого не змінює.
- Детермінований вивід: списки результатів і ключі кешу сортуються, тож результат не залежить від порядку обходу чи порядку переданих аргументів.
- Fail-safe щодо вмісту: документи з помилками парсингу ігноруються, а пошкоджені YAML за замовчуванням не зривають обхід — без переданого reporter про них просто мовчиться.
- Кеш діє в межах життя процесу й не має інвалідації: у межах одного прогону файлова система вважається незмінною, а між прогонами процес стартує заново.
