@nitra/cursor 5.1.0 → 5.2.1

package/rules/abie/js/docs/applies.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/js/applies.mjs
+  crc: f5b6777a
+---
+
 # applies.mjs
 
 ## Огляд

package/rules/abie/js/docs/env_dns.md

@@ -1,32 +1,35 @@
+---
+docgen:
+  source: npm/rules/abie/js/env_dns.mjs
+  crc: f2aff16b
+  score: 100
+---
+
 # env_dns.mjs
 
 ## Огляд
 
-Перевірка-чек правила `abie.mdc`: сканує env-файли abie й гарантує, що внутрішньокластерні URL у них вказують на правильний GKE-кластер відповідно до імені файла. Це захист від типової помилки, коли `dev`-конфіг випадково посилається на `ua`-кластер (або навпаки). Якщо в репозиторії немає abie env-файлів, перевірка мовчки проходить.
+Функція check виконує перевірку відповідності вхідних даних визначеному контракту. Вона забезпечує ізоляцію логіки перевірки, перевіряючи виконання необхідних умов перед подальшою обробкою. Результати перевірки передаються через маркер (abie.mdc). Функція гарантує, що помилки не будуть прокидані назовні.
 
 ## Поведінка
 
-1. Завантажує перелік ігнорованих шляхів із cursor-конфігу й збирає всі abie env-файли в репозиторії. abie env-файлом вважається файл із basename `dev.env` або `ua.env` (опційно з провідною крапкою — `.dev.env`, `.ua.env`).
-2. Локальний `.env` без імені кластера (файл розробника) та інші env-файли (наприклад `production.env`) під перевірку не підпадають.
-3. Якщо жодного abie env-файла не знайдено — фіксує `pass` із поясненням, що перевірку пропущено, і завершується успішно.
-4. Для кожного знайденого файла визначає очікуваний кластер за іменем:
-   - `dev.env` → кластер `abie-dev.internal`, namespace мусить починатися з `dev-`.
-   - `ua.env` → кластер `abie-ua.internal`, namespace мусить починатися з `ua-`.
-5. Читає вміст файла. Якщо файл не читається — фіксує `fail` із текстом помилки й переходить до наступного.
-6. У вмісті шукає всі URL виду `http://<svc>.<ns>.svc.<dns>` (з опційним портом і шляхом) і для кожного перевіряє: частина `<dns>` збігається з очікуваним DNS кластера, а namespace `<ns>` починається з очікуваного префікса.
-7. Один невідповідний URL може дати дві окремі скарги (невірний DNS і невірний namespace). Той самий URL, що трапився у двох змінних, рахується двічі.
-8. Якщо у файлі немає невідповідностей — `pass`; інакше кожне порушення стає окремим `fail` із зазначенням файла, проблемного URL і очікуваного значення.
-
-Приклад порушення для `dev.env`: URL `http://api.ua-core.svc.abie-ua.internal` дасть скарги, бо очікувався DNS `abie-dev.internal` і namespace-префікс `dev-`.
-
-## Публічний API
-
-`check(cwd)` — запускає перевірку від кореня репозиторію (за замовчуванням поточна робоча директорія) і повертає код виходу: `0`, якщо порушень немає, інакше ненульовий. Це стандартна точка інтеграції чек-механізму правил.
+Алгоритм перевірки конфігурації середовища.
+
+1. Ініціалізація механізму звітування.
+2. Завантаження шляхів для ігнорування.
+3. Збір файлів конфігурації середовища.
+4. Перевірка наявності файлів. Якщо файлів не знайдено, перевірка пропущено.
+5. Ітерація по кожному знайденому файлу конфігурації.
+6. Для кожного файлу обчислюється відносний шлях.
+7. Визначається назва середовища на основі імені файлу.
+8. Зчитується вміст файлу. У разі помилки читання вмісту, генерується помилка та перевірка переходить до наступного файлу.
+9. Вміст файлу підлягає валідації внутрішніх посилань.
+10. Якщо валідація повертає помилки, генерується помилка, що вказує на невідповідність внутрішніх URL для визначеного середовища (abie.mdc).
+11. Якщо валідація успішна, генерується повідомлення про успішну перевірку.
+12. Повернення фінального коду виходу звіту.
 
 ## Гарантії поведінки
 
-- Read-only: файли лише читаються, нічого не змінюється й не створюється.
-- Fail-safe за відсутності даних: репозиторій без abie env-файлів — це успіх, а не помилка.
-- Нечитабельний файл не валить весь прогон: він стає окремою скаргою, решта файлів перевіряються далі.
-- Файли без розпізнаного імені кластера пропускаються без помилки.
-- Файли обробляються в детермінованому (відсортованому) порядку, тож вивід стабільний між запусками.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

package/rules/abie/js/docs/firebase_hosting.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/js/firebase_hosting.mjs
+  crc: 3b2459a8
+---
+
 # firebase_hosting.mjs
 
 ## Огляд

package/rules/abie/js/docs/hc_pairing.md

@@ -1,35 +1,31 @@
+---
+docgen:
+  source: npm/rules/abie/js/hc_pairing.mjs
+  crc: 5627bda6
+  score: 100
+---
+
 # hc_pairing.mjs
 
 ## Огляд
 
-Перевірка правила abie: для кожного каталогу в дереві `k8s/`, що містить маніфест `kind: Deployment`, поруч обовʼязково має лежати файл `hc.yaml` із коректним modeline `$schema`. Файл — JS-частина правила: він відповідає лише за FS-парність (Deployment ↔ hc.yaml) та перший рядок-modeline. Структурну валідацію самого `HealthCheckPolicy` (apiVersion, requestPath, port, targetRef із суфіксом `-hl`) виконує окремий Rego-механізм через CLI і тут не дублюється.
+Модуль забезпечує валідацію даних відповідно до визначеного контракту. Функція check є публічною і є Read-only. Модуль гарантує внутрішню цілісність стану системи через механізм fail-safe, який запобігає виходу з ладу при помилках. Робота модуля стосується даних, визначених у (abie.mdc).
 
 ## Поведінка
 
-1. Завантажує перелік ігнорованих шляхів із конфігурації cursor і збирає всі `.yaml`/`.yml` файли під сегментом `k8s/`.
-2. Визначає множину каталогів, де серед цих файлів зустрічається хоча б один `kind: Deployment`.
-3. Якщо Deployment-каталогів немає — перевірку повністю пропускає з повідомленням-pass і завершується успішно.
-4. Інакше для кожного Deployment-каталогу (у відсортованому порядку) перевіряє сусідній `hc.yaml`:
-   - файлу немає поруч → fail з вимогою додати `HealthCheckPolicy`;
-   - файл не вдалося прочитати → fail із текстом помилки читання;
-   - файл є → перевіряє його modeline.
-5. Modeline валідний лише тоді, коли перший рядок файлу — `# yaml-language-server: $schema=…` із точним очікуваним URL CRD-схеми (`networking.gke.io/healthcheckpolicy_v1.json`). Порожній перший рядок, відсутність modeline або інший URL → fail.
-6. Підсумковий exit-код формується з накопичених pass/fail: 0, якщо всіх правил дотримано.
-
-Очікуваний перший рядок `hc.yaml`:
-
-```
-# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
-```
-
-## Де використовується
-
-Це check-модуль правила abie (`abie.mdc`) у складі lint-набору cursor. Точка інтеграції — асинхронний `check(cwd)`, який повертає exit-код; його викликає механізм запуску перевірок для кореня репозиторію.
+1.  Запускається перевірка.
+2.  Завантажується конфігурація пропусків шляхів.
+3.  Зводяться всього список файлів Kubernetes YAML.
+4.  Збираються директорії розгортань на основі знайдених YAML файлів.
+5.  Перевіряється, чи існує хоча б одна директорія розгортань. Якщо директорій немає, видається повідомлення про пропуск перевірки.
+6.  Якщо директорії розгортань знайдені, видається повідомлення про успішне знаходження директорій для подальшої перевірки.
+7.  Для кожної знайденої директорії перевіряється наявність файлу hc.yaml у відповідній директорії. Якщо файл відсутній, видається повідомлення про помилку, і перевірка для цього елемента пропускається.
+8.  Для кожного знайденого файлу hc.yaml відбувається спроба прочитати його вміст. У разі помилки читання, видається повідомлення про невдачу.
+9.  Проводиться валідація прочитаного вмісту відповідно до моделіне (abie.mdc). У разі успішної валідації, видається повідомлення про успіх. У разі невдачі, видається повідомлення про помилку валідації.
+10. Повертається код виходу перевірки.
 
 ## Гарантії поведінки
 
-- Read-only: модуль лише читає файлову систему й нічого не змінює.
-- Fail-safe для порожнього дерева: відсутність Deployment-маніфестів трактується як успіх, а не помилка.
-- Помилка читання конкретного `hc.yaml` не зупиняє прогон — вона фіксується як окремий fail, а перевірка решти каталогів триває.
-- Каталог `.github/` свідомо виключений зі збору YAML (належить іншому правилу), як і шляхи з cursor-ignore.
-- Зіставлення modeline точне: будь-яке відхилення URL чи формату першого рядка дає зрозуміле повідомлення з посиланням на `abie.mdc`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

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

@@ -1,28 +1,36 @@
-# ua_http_route
+---
+docgen:
+  source: npm/rules/abie/js/ua_http_route.mjs
+  crc: d86624c8
+  score: 100
+---
+
+# ua_http_route.mjs
 
 ## Огляд
 
-Перевірка правила `abie.mdc`, що валідує наявність і коректність inline-patch `HTTPRoute` для `ua`-overlay у Vite-пакетах Kubernetes-маніфестів. Спрацьовує лише для пакетів, які мають `vite.config.{js,mjs,ts}` — для решти перевірка нейтральна (passthrough). Запускається як CLI-check і повертає код виходу для CI.
+Файл надає публічний інструмент `check` для перевірки внутрішнього стану даних. Функція працює у режимі fail-safe, перехоплюючи помилки виконання на рівні системи, щоб запобігти аварійним зупинкам. Функція використовує кешування даних у межах поточного прогону.
 
 ## Поведінка
 
-1. Завантажує перелік ігнорованих шляхів з cursor-конфігу та обходить дерево `k8s/` репозиторію, збираючи всі YAML-маніфести.
-2. Відбирає серед них файли `ua/kustomization.yaml`. Якщо таких немає — фіксує успіх із поясненням, що patch `HTTPRoute (ua)` не вимагається, і завершується.
-3. Для кожного знайденого `ua/kustomization.yaml`:
-   - Якщо в каталозі пакета (батьківському щодо `k8s/`) немає `vite.config.{js,mjs,ts}` — перевірка для цього overlay пропускається з відміткою «не застосовується» (gate за Vite-пакетом).
-   - Інакше визначає каталог пакета. Якщо його не вдається встановити — фіксує внутрішню помилку overlay.
-4. Аналізує base-`HTTPRoute` пакета на наявність посилань на спільні сервіси (`auth-run-hl`, `file-link-hl`). У base кожен такий `backendRef` має містити `namespace: dev`; помилки в base-маніфесті повідомляються як fail, і за наявності таких помилок overlay далі не перевіряється. Результат аналізу кешується на рівні пакета, щоб не повторювати його для кількох overlay одного пакета.
-5. Читає вміст `ua/kustomization.yaml`. При помилці читання — fail із текстом помилки.
-6. Витягує об'єднаний текст nginx-run patch-ів з kustomization і перевіряє, що inline-patch `HTTPRoute` для namespace `ua` відповідає `abie.mdc`: непорожній `target.name`, перепис `/spec/hostnames` (домени abie), `/spec/parentRefs/0/namespace` (`ua` або `ua-*`), а також JSON6902-patch-и на `/spec/rules/…/backendRefs/…/namespace` зі `value: ua`. Очікувана кількість таких patch-ів дорівнює кількості посилань на спільні сервіси в base. Невідповідність повідомляється як fail, відповідність — як pass.
-
-## Де використовується
-
-Частина набору перевірок правила `abie` (`npm/rules/abie`). Викликається як check-функція з кореня репозиторію; типово запускається інфраструктурою лінту/CI, що збирає та запускає `check`-модулі правил.
+1. Зчитується корінь репозиторію.
+2. Завантажуються ігноровані шляхи.
+3. Знаходять YAML-файли Kubernetes у репозиторії.
+4. Фільтрується список YAML-файлів для визначення лише тих, що відповідають шляхам `ua/kustomization.yaml`.
+5. Якщо список таких шляхів порожній, функція повертає успішне завершення, оскільки перевірка патчів HTTPRoute (ua) не вимагається.
+6. Ітерується по кожному шляху, що відповідає критеріям.
+7. Перевіряється, чи вимагає пакет наявності патчу HTTPRoute (ua) на основі наявності файлів Vite у пакеті. Якщо ні, перевірка пропускається.
+8. Визначається каталог пакета. Якщо каталог не знайдено, функція повертає помилку внутрішньої невідповідності.
+9. Для кожного пакета виконується аналіз спільних референсів. Якщо аналіз відсутній, він виконується, і результат зберігається у кеш.
+10. Перевіряються базові помилки, отримані під час аналізу. Якщо помилки присутні, перевірка пропускається.
+11. Спроба читання вмісту файлу. У разі невдачі читання, функція повертає помилку.
+12. Об'єднутий текст з конфігурації використовується для валідації патчів.
+13. Виконується валідація патчів. Якщо валідація повертає `null`, перевірка вважається успішною. В іншому випадку, функція повертає помилку, вказуючи на результат валідації.
+14. Повертається код виходу репортера.
 
 ## Гарантії поведінки
 
-- Read-only: лише читає маніфести й конфіги, нічого не змінює у файловій системі.
-- За відсутності `ua/kustomization.yaml` чи `vite.config` перевірка не вимагає patch і фіксує успіх (opt-in за Vite-пакетом).
-- Помилка читання `ua/kustomization.yaml` не зупиняє обхід інших overlay — повідомляється як окремий fail, цикл продовжується.
-- Помилки в base-`HTTPRoute` блокують лише overlay свого пакета, не впливаючи на інші пакети.
-- Результат — агрегований код виходу (0 за умови всіх pass), придатний для використання в CI.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/abie/js/docs/ua_node_selector.md

@@ -1,28 +1,33 @@
-# ua_node_selector
+---
+docgen:
+  source: npm/rules/abie/js/ua_node_selector.mjs
+  crc: 6cde9837
+  score: 100
+---
+
+# ua_node_selector.mjs
 
 ## Огляд
 
-Check-правило `abie`, яке гарантує: якщо в дереві `k8s/` пакета присутній `Deployment`, то в `ua`-оверлеї (`ua/kustomization.yaml`) обовʼязково має бути inline-patch на цей `Deployment` зі шляхом `/spec/template/spec/nodeSelector` і `preem: false`. Так продакшн-навантаження (`ua`-оверлей) закріплюється за непреемптивними (стабільними) нодами. Перевіряється лише abie-специфічна вимога; структурні обмеження формату JSON6902-патчів (наприклад, заборона `remove + add` на той самий path) перевіряє окреме правило k8s і тут не дублюються.
+Модуль надає публічну функцію `check` для валідації поточного стану вхідних даних. Функція виконує перевірку відповідності даних визначеним критеріям. Результат перевірки повертається у вигляді булевого значення. (abie.mdc)
 
 ## Поведінка
 
-1. Зчитує перелік шляхів-винятків (cursor-ignore) і збирає всі k8s YAML-файли в межах кореня репозиторію.
-2. Визначає директорії, де оголошено `Deployment`. Якщо `Deployment` у дереві немає — правило проходить (pass) із поясненням, що patch `nodeSelector` для `ua` не вимагається, і завершується.
-3. Серед знайдених YAML відбирає файли, що є `ua/kustomization.yaml`. Якщо `Deployment` є, але жодного `ua`-kustomization не знайдено — це провал (fail) з вказівкою додати `ua/kustomization.yaml` із потрібним patch.
-4. Для кожного знайденого `ua/kustomization.yaml`:
-   - Якщо в дереві k8s саме того пакета, до якого належить цей оверлей, немає `Deployment` — patch не вимагається, правило проходить для цього файлу.
-   - Інакше читає вміст файлу. Якщо файл не вдалося прочитати — фіксує провал із текстом помилки й переходить до наступного.
-   - Перевіряє наявність коректного patch на target kind `Deployment` зі шляхом `/spec/template/spec/nodeSelector` та `preem: false`. За відсутності — провал; за наявності — прохід.
-5. Підсумковий код виходу формується з накопичених pass/fail: нуль, якщо жодного провалу не зафіксовано.
-
-## Де використовується
-
-Файл — один із check-модулів набору правил `abie` (`npm/rules/abie/js/`). Запускається інфраструктурою перевірок правил, яка викликає експортовану функцію `check` і інтерпретує повернутий код виходу як результат лінту репозиторію.
+1. Запуск перевірки. Створюється звітність для фіксації результатів.
+2. Завантаження ігнорованих шляхів з конфігурації.
+3. Пошук файлів Kubernetes YAML у вказаному корені репозиторію.
+4. Збір директорій Deployment на основі знайдених YAML файлів.
+5. Перевірка наявності Deployment. Якщо Deployment не знайдено, повертається результат про успішне проходження.
+6. Фільтрація YAML файлів для визначення шляхів, що відповідають конфігурації ua.
+7. Перевірка наявності шляхів ua. Якщо шляхів немає, повертається результат про необхідність застосувати патч на Deployment: шлях /spec/template/spec/nodeSelector та preem false (abie.mdc).
+8. Ітерація по шляхах ua.
+9. Перевірка наявності Deployment у дереві Kubernetes для кожного шляху. Якщо Deployment відсутній, повертається результат про те, що патч nodeSelector (ua) не застосовується — немає Deployment у дереві k8s цього пакета (abie).
+10. Зчитування вмісту YAML файлу. У разі помилки читання, повертається результат про невдалий доступ.
+11. Перевірка вмісту YAML файлу на наявність необхідного патча. Якщо патч відсутній, повертається результат про необхідність застосувати патч target kind Deployment: шлях /spec/template/spec/nodeSelector та preem false (abie.mdc).
+12. Фіксація успішного проходження для кожного шляху.
 
 ## Гарантії поведінки
 
-- Read-only: жодних файлів не змінює, лише читає YAML-конфігурації; мережу не використовує.
-- Fail-safe для відсутніх ресурсів: відсутність `Deployment` у дереві трактується як легітимний прохід, а не помилка.
-- Помилка читання окремого `ua/kustomization.yaml` не зупиняє перевірку — фіксується як провал для конкретного файлу, решта файлів продовжує оброблятися.
-- Кожен `ua`-файл оцінюється незалежно; результат правила агрегує всі окремі pass/fail.
-- Шляхи у звітах нормалізуються до відносних із прямими слешами, тож вивід стабільний і коректний незалежно від платформи (POSIX/Windows).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/enabled.mjs
+  crc: 6b02ea18
+---
+
 # enabled.mjs
 
 ## Огляд
@@ -8,19 +14,19 @@
 
 1. Створення шляху до конфігураційного файлу `.n-cursor.json`
 
-2.  Перевірка наявності файлу. Якщо файл відсутній, повертається `false`.
+2. Перевірка наявності файлу. Якщо файл відсутній, повертається `false`.
 
-3.  Читання вмісту файлу. У разі помилки читання, повертається `false`.
+3. Читання вмісту файлу. У разі помилки читання, повертається `false`.
 
-4.  Парсинг вмісту у формат JSON. У разі помилки парсингу, повертається `false`.
+4. Парсинг вмісту у формат JSON. У разі помилки парсингу, повертається `false`.
 
-5.  Витягнення масиву правил з конфігурації.
+5. Витягнення масиву правил з конфігурації.
 
-6.  Перевірка типу витягнутого масиву. Якщо дані не є масивом, повертається `false`.
+6. Перевірка типу витягнутого масиву. Якщо дані не є масивом, повертається `false`.
 
-7.  Ітерація по масиву правил. Проводиться перевірка кожного елемента на відповідність рядку 'abie' після приведення до нижнього регістру та видалення пробілів.
+7. Ітерація по масиву правил. Проводиться перевірка кожного елемента на відповідність рядку 'abie' після приведення до нижнього регістру та видалення пробілів.
 
-8.  Повернення результату. Якщо знайдено правило 'abie', повертається `true`. У іншому випадку повертається `false`.
+8. Повернення результату. Якщо знайдено правило 'abie', повертається `true`. У іншому випадку повертається `false`.
 
 ## Публічний API
 

package/rules/abie/lib/docs/env-dns.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/env-dns.mjs
+  crc: 91aa8ee4
+---
+
 # env-dns.mjs
 
 ## Огляд
@@ -17,9 +23,9 @@ collectAbieEnvFiles
 
 ## Публічний API
 
-* abieEnvNameFromBasename — Витягує `dev` або `ua` з імені env-файлу.
-* validateAbieEnvInternalUrls — Виявляє розбіжності кластерного DNS/namespace у внутрішніх URL-адресах.
-* collectAbieEnvFiles — Збирає `.env` файли, що відповідають формату abie env (dev.env, ua.env, з провідною крапкою).
+- abieEnvNameFromBasename — Витягує `dev` або `ua` з імені env-файлу.
+- validateAbieEnvInternalUrls — Виявляє розбіжності кластерного DNS/namespace у внутрішніх URL-адресах.
+- collectAbieEnvFiles — Збирає `.env` файли, що відповідають формату abie env (dev.env, ua.env, з провідною крапкою).
 
 ## Гарантії поведінки
 

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/hc-yaml.mjs
+  crc: e9aba7c8
+---
+
 # hc-yaml.mjs
 
 ## Огляд

package/rules/abie/lib/docs/http-route.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/http-route.mjs
+  crc: 3ec544d6
+---
+
 # http-route.mjs
 
 ## Огляд

package/rules/abie/lib/docs/k8s-tree.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/k8s-tree.mjs
+  crc: 077f3478
+---
+
 # k8s-tree
 
 ## Огляд

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/kustomization-patches.mjs
+  crc: 1dd36b33
+---
+
 # kustomization-patches.mjs
 
 ## Огляд

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/overlay-paths.mjs
+  crc: 752f7012
+---
+
 # overlay-paths
 
 ## Огляд

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/lib/yaml.mjs
+  crc: 1b50e492
+---
+
 # yaml.mjs
 
 ## Огляд

package/rules/adr/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/adr/fix.mjs
+  crc: b46c541a
+---
+
 # `npm/rules/adr/fix.mjs`
 
 ## Огляд