@nitra/cursor 3.22.0 → 3.23.0

package/bin/docs/rename-yaml-extensions.md

@@ -0,0 +1,207 @@
+# `rename-yaml-extensions.mjs`
+
+## Огляд
+
+Файл `npm/bin/rename-yaml-extensions.mjs` — це **тонкий CLI-адаптер** (bin-обгортка) для перейменування розширень YAML-файлів у двох конвенціях:
+
+- у каталозі `k8s` — файли `.yml` перейменовуються на `.yaml`;
+- у каталозі `.github` — файли `.yaml` перейменовуються на `.yml`.
+
+Сама **бізнес-логіка** перейменування реалізована окремо у `../scripts/rename-yaml-extensions.mjs` (звідти імпортуються `parseRenameYamlArgs` і `renameYamlExtensions`). Файл `npm/bin/rename-yaml-extensions.mjs` лише:
+
+1. парсить аргументи командного рядка;
+2. викликає функцію бізнес-логіки `renameYamlExtensions`;
+3. форматує вивід у консоль (список перейменувань, повідомлення про відсутність змін, помилки);
+4. повертає код виходу (`0` — успіх, `1` — були помилки).
+
+Файл є **модулем для головного CLI пакета `n-cursor`** (через `bin/n-cursor.js`). Публічна точка входу для користувача — підкоманда головного CLI:
+
+- `npx @nitra/cursor rename-yaml-extensions [опції]`
+- або у репозиторії пакета: `bun ./bin/n-cursor.js rename-yaml-extensions`.
+
+Прямий запуск `node ./bin/rename-yaml-extensions.mjs` підтримується, але вважається режимом для розробки/тестів — у production-сценарії використовується диспетчер `n-cursor.js`.
+
+Підтримувані опції:
+
+- `--dry-run` — лише вивести список запланованих перейменувань, нічого не змінюючи у файловій системі;
+- `--root=<шлях>` — корінь обходу (за замовчуванням — `process.cwd()`).
+
+## Експорти / API
+
+Файл `npm/bin/rename-yaml-extensions.mjs` експортує одну функцію:
+
+### `runRenameYamlExtensionsCli(argv)`
+
+- **Тип**: `async function (argv: string[]): Promise<number>`
+- **Призначення**: запустити перейменування YAML-розширень із форматованим виводом у консоль.
+- **Параметри**:
+  - `argv: string[]` — масив аргументів **без імені команди**. Тобто це все, що йде після `rename-yaml-extensions` при виклику через `n-cursor`, або `process.argv.slice(2)` при прямому запуску.
+- **Повертає**: `Promise<number>` — код виходу:
+  - `0` — успіх (немає помилок, незалежно від кількості перейменованих файлів);
+  - `1` — у процесі трапилися помилки (наприклад, цільовий файл уже існує).
+
+Експорт — **named export** (`export async function`). За замовчуванням (`default`) нічого не експортується.
+
+## Функції
+
+### `runRenameYamlExtensionsCli(argv)` (експортна)
+
+Алгоритм виконання:
+
+1. **Парсинг аргументів**.
+   - Викликається `parseRenameYamlArgs(argv)`, яка повертає об'єкт `{ dryRun, root }`:
+     - `dryRun: boolean` — чи це режим симуляції;
+     - `root: string` — абсолютний/відносний корінь обходу файлів.
+2. **Префікс для виводу**.
+   - Якщо `dryRun === true`, рядки логу починаються з `[dry-run] `; інакше — з порожнього префіксу.
+3. **Виклик бізнес-логіки**.
+   - Викликається `renameYamlExtensions(root, { dryRun })`, яка повертає об'єкт `{ renamed, errors }`:
+     - `renamed: Array<{ relFrom: string, relTo: string }>` — успішні (або заплановані у dry-run) перейменування з відносними шляхами;
+     - `errors: string[]` — повідомлення про помилки (наприклад, конфлікт існуючого цільового файлу).
+4. **Вивід результатів**.
+   - Для кожного елемента `renamed` друкується рядок виду `${label}${relFrom} → ${relTo}` (у `stdout`).
+   - Якщо `renamed.length === 0` **і** `errors.length === 0` — друкується повідомлення `Немає файлів для перейменування (k8s + .yml → .yaml; .github + .yaml → .yml).` з префіксом `label`.
+   - Для кожного елемента `errors` друкується рядок `  ❌ ${err}` у `stderr` (через `console.error`).
+5. **Повернення коду**.
+   - Якщо `errors.length > 0` — повертається `1`; інакше — `0`.
+
+Функція **не кидає** виключень самостійно: помилки бізнес-логіки повертаються як масив `errors` і виводяться у `stderr`. Якщо `renameYamlExtensions` чи `parseRenameYamlArgs` кинуть exception, він пробрасується вище — і у блоці `if (isRunAsCli(...))` приведе до необробленого reject промісу.
+
+### Топ-рівневий блок CLI
+
+Не є функцією, але є виконуваним кодом на верхньому рівні модуля:
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  const code = await runRenameYamlExtensionsCli(process.argv.slice(2))
+  if (code !== 0) {
+    process.exitCode = 1
+  }
+}
+```
+
+Логіка:
+
+- Перевіряється, чи цей модуль запущений як CLI (а не імпортований як бібліотека) через `isRunAsCli(import.meta.url)`.
+- Якщо так — викликається `runRenameYamlExtensionsCli` з `process.argv.slice(2)` (аргументи без `node` та шляху до скрипту).
+- Якщо код виходу не нульовий — встановлюється `process.exitCode = 1`. **Зауваження**: тут використано `process.exitCode = 1`, а **не** `process.exit(1)` — це дозволяє Node.js завершити поточний event loop коректно й уникнути обриву флешу `stdout`/`stderr`.
+
+При імпорті модуля (як це робить `bin/n-cursor.js`) цей блок **не виконується**, бо `isRunAsCli` поверне `false`.
+
+## Залежності
+
+### Внутрішні (з цього ж пакета)
+
+- `../scripts/cli-entry.mjs` — імпорт **`isRunAsCli`**.
+  - Призначення: визначає, чи поточний модуль запущено як CLI напряму (через `node ./bin/rename-yaml-extensions.mjs`) або імпортовано іншим модулем.
+  - Параметр: `import.meta.url` поточного модуля.
+- `../scripts/rename-yaml-extensions.mjs` — імпорт **`parseRenameYamlArgs`** і **`renameYamlExtensions`**.
+  - `parseRenameYamlArgs(argv)` — розбирає прапорці `--dry-run` і `--root=<шлях>`, повертає `{ dryRun, root }`.
+  - `renameYamlExtensions(root, options)` — виконує фактичний обхід `k8s` та `.github` і перейменування файлів. Опція `{ dryRun }` керує тим, чи лише симулювати дію.
+
+### Зовнішні
+
+Жодних `npm`-залежностей цей файл напряму не використовує. Усе, що потрібно, — це вбудовані Node.js глобали:
+
+- `process` — для читання `process.argv` і встановлення `process.exitCode`;
+- `console` — для `console.log` (успіх) і `console.error` (помилки);
+- `import.meta.url` — для перевірки режиму запуску через `isRunAsCli`.
+
+### Зв'язки в інший бік (хто використовує цей файл)
+
+- `npm/bin/n-cursor.js` — головний CLI пакета. Імпортує `runRenameYamlExtensionsCli` і викликає її для підкоманди `rename-yaml-extensions`.
+
+## Потік виконання / Використання
+
+### Сценарій 1. Запуск як підкоманда `n-cursor` (типовий випадок)
+
+```bash
+npx @nitra/cursor rename-yaml-extensions
+npx @nitra/cursor rename-yaml-extensions --dry-run
+npx @nitra/cursor rename-yaml-extensions --root=./packages/my-app
+```
+
+Послідовність:
+
+1. `n-cursor.js` отримує `process.argv`, визначає підкоманду `rename-yaml-extensions`.
+2. `n-cursor.js` імпортує `runRenameYamlExtensionsCli` з `./rename-yaml-extensions.mjs`.
+3. Викликає `runRenameYamlExtensionsCli(argvBezKomandy)`, де `argvBezKomandy` — усі аргументи **після** `rename-yaml-extensions`.
+4. Функція парсить опції, викликає бізнес-логіку, друкує результат, повертає код.
+5. `n-cursor.js` встановлює `process.exitCode` відповідно до повернутого коду.
+
+### Сценарій 2. Прямий запуск (розробка/тести)
+
+```bash
+node ./bin/rename-yaml-extensions.mjs
+node ./bin/rename-yaml-extensions.mjs --dry-run
+node ./bin/rename-yaml-extensions.mjs --root=/abs/path
+```
+
+Послідовність:
+
+1. Node.js завантажує модуль.
+2. Імпортуються `isRunAsCli`, `parseRenameYamlArgs`, `renameYamlExtensions`.
+3. Експортується `runRenameYamlExtensionsCli`.
+4. Виконується топ-рівневий блок `if (isRunAsCli(import.meta.url)) { ... }`.
+5. У ньому викликається `runRenameYamlExtensionsCli(process.argv.slice(2))`.
+6. За результатом встановлюється `process.exitCode = 1`, якщо є помилки.
+
+### Сценарій 3. Імпорт як бібліотеки
+
+```js
+import { runRenameYamlExtensionsCli } from '@nitra/cursor/bin/rename-yaml-extensions.mjs'
+
+const code = await runRenameYamlExtensionsCli(['--dry-run', '--root=./tmp'])
+// code === 0 → успіх; code === 1 → були помилки
+```
+
+У цьому випадку:
+
+- `isRunAsCli(import.meta.url)` повертає `false` (бо модуль завантажено через `import`, а не як точку входу Node.js);
+- топ-рівневий блок CLI **не виконується**;
+- викликач сам обробляє повернутий код.
+
+### Приклади виводу
+
+**Успішне перейменування**:
+
+```
+k8s/deployment.yml → k8s/deployment.yaml
+.github/workflows/ci.yaml → .github/workflows/ci.yml
+```
+
+**Режим `--dry-run`**:
+
+```
+[dry-run] k8s/deployment.yml → k8s/deployment.yaml
+[dry-run] .github/workflows/ci.yaml → .github/workflows/ci.yml
+```
+
+**Нічого не потрібно міняти**:
+
+```
+Немає файлів для перейменування (k8s + .yml → .yaml; .github + .yaml → .yml).
+```
+
+**Помилка** (наприклад, цільовий файл уже існує):
+
+```
+  ❌ k8s/deployment.yaml вже існує — пропускаю k8s/deployment.yml
+```
+
+(І процес завершиться з кодом виходу `1`.)
+
+### Коди виходу
+
+| Код | Значення                                                                 |
+| --- | ------------------------------------------------------------------------ |
+| `0` | Успіх. Усі заплановані перейменування виконано (або нічого не потрібно). |
+| `1` | Виникли помилки (масив `errors` непорожній).                             |
+
+### Архітектурні нотатки
+
+- Файл свідомо тонкий: уся **алгоритмічна** робота (обхід директорій `k8s` та `.github`, перевірка існуючих файлів, фактичне `fs.rename`) — у `../scripts/rename-yaml-extensions.mjs`. Це дає змогу:
+  - **тестувати** бізнес-логіку без процесу-обгортки;
+  - **підключати** цю ж логіку до інших точок входу (наприклад, до підкоманд `n-cursor`).
+- Використання `process.exitCode` замість `process.exit(N)` — best practice для CLI, що працюють із асинхронним I/O: дозволяє коректно дочекатися флешу потоків перед завершенням.
+- Перевірка `isRunAsCli(import.meta.url)` — стандартний у цьому пакеті патерн dual-mode модулів (одночасно і CLI, і imported lib). Реалізація — у `../scripts/cli-entry.mjs`.

package/bin/n-cursor.js

@@ -24,7 +24,7 @@
  *   `npx \@nitra/cursor lint-docker` — канонічний lint-docker (docker.mdc): `hadolint` по `Dockerfile`/`*.Dockerfile`
  *   `npx \@nitra/cursor lint-text`   — канонічний lint-text (text.mdc): `cspell` → `shellcheck` (з auto-fix) →
  *                                     `markdownlint-cli2 --fix` → `v8r` (json/json5/yaml/yml/toml)
- *   `npx \@nitra/cursor docgen scan`    — детермінований JSON-лістинг кодових файлів для скілу docgen (тека `docs/` поряд із джерелом)
+ *   `npx \@nitra/cursor docgen scan`    — детермінований JSON-лістинг кодових файлів для скілу docgen (відносні `sourcePath`; ignore-glob snippet у `npm/skills/docgen/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом)
  *   `npx \@nitra/cursor docgen modules` — детермінований JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу docgen
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
@@ -1154,7 +1154,7 @@ async function captureOutput(action) {
   process.stdout.write = (...args) => {
     const [chunk] = args
     buffer.push(typeof chunk === 'string' ? chunk : chunk.toString())
-    const cb = args.find((arg) => typeof arg === 'function')
+    const cb = args.find(arg => typeof arg === 'function')
     if (cb) cb()
     return true
   }
@@ -1652,6 +1652,33 @@ try {
 
       break
     }
+    case 'coverage-fix': {
+      // n-cursor coverage-fix index|slice — read-only витяг вцілілих мутантів із
+      // COVERAGE.md для скілу n-coverage-fix. Важкий парсинг несе скрипт (0 LLM-
+      // токенів); агент отримує лише компактний index або зріз під один файл.
+      const { runCoverageFixCli } = await import('../scripts/coverage-fix-extract.mjs')
+      process.exitCode = await runCoverageFixCli(args)
+
+      break
+    }
+    case 'taze': {
+      // n-cursor taze diff — read-only semver-diff package.json ↔ package.json.taze-bak
+      // (root + воркспейси) для скілу n-taze: скрипт класифікує major-оновлення,
+      // агент отримує готовий список замість ручного порівняння бекапів.
+      const { runTazeCli } = await import('../skills/taze/js/diff.mjs')
+      process.exitCode = await runTazeCli(args)
+
+      break
+    }
+    case 'start-check': {
+      // n-cursor start-check scan|run — детермінована частина smoke-перевірки для
+      // скілу n-start-check: scan виявляє воркспейси зі start і їх тип, run запускає
+      // один із grace-таймаутом і класифікує OK/FAIL. Агент лишається з діагностикою.
+      const { runStartCheckCli } = await import('../skills/start-check/js/check.mjs')
+      process.exitCode = await runStartCheckCli(args)
+
+      break
+    }
     case 'change': {
       const { runChangeCli } = await import('../rules/release/change.mjs')
       process.exitCode = await runChangeCli(args)
@@ -1723,7 +1750,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree, lint-ci, flow, trace, graph, docgen`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, lint-ci, flow, trace, graph, docgen`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "3.22.0",
+  "version": "3.23.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/abie/docs/fix.md

@@ -0,0 +1,18 @@
+# fix.mjs
+
+## Огляд
+
+Точка входу правила `abie` для перевірки/виправлення проєкту. Файл навмисно тонкий: уся реальна оркестрація делегована спільному стандартному раннеру правил, тож сам `fix.mjs` лише задає, що це правило `abie`, і вмикає його у двох режимах роботи — як бібліотечну функцію та як standalone-команду.
+
+## Поведінка
+
+1. Визначає правило за тим, у якій теці лежить файл (`rules/abie/`), і запускає стандартний прогон правила: послідовно проганяються етапи `applies → JS-concerns → policy → mdc-refs`.
+2. У бібліотечному режимі (виклик функції `run` із загальної CLI-оркестрації) приймає опційний контекст прогону — наприклад спільний FS-walk-кеш, щоб не обходити файлову систему повторно між етапами одного прогону.
+3. Якщо файл запущено напряму як команду (`bun rules/abie/fix.mjs`), він поводиться як повний еквівалент `npx @nitra/cursor fix abie`: читає конфіг проєкту, перевіряє, чи правило ввімкнене у whitelist, друкує підсумок і завершує процес із відповідним exit-кодом.
+4. Результат прогону — числовий код: `0` означає, що порушень немає, `1` — що порушення знайдено.
+
+## Гарантії поведінки
+
+- Локальної логіки перевірки в цьому файлі немає: будь-яка зміна поведінки правила відбувається через спільний раннер чи передані опції контексту, а не через правки тут. Це утримує всі правила однотипними.
+- Завершення процесу з exit-кодом відбувається лише у standalone-режимі (запуск напряму); при виклику як бібліотеки процес не завершується — повертається лише код результату, придатний для агрегації в загальному прогоні.
+- Standalone-режим коректно обробляє випадок, коли правило не ввімкнене в конфізі: прогін просто пропускається з нейтральним (успішним) результатом замість помилки.

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

@@ -0,0 +1,26 @@
+# applies.mjs
+
+## Огляд
+
+Applies-гейт правила `abie` на рівні всього правила. Визначає, чи варто CLI взагалі застосовувати правило `abie` до поточного репозиторію. Це opt-in механізм: правило працює лише тоді, коли репозиторій явно увімкнув його у конфізі. Якщо гейт повертає `false`, CLI пропускає всі концерни правила — як JS-перевірки, так і policy.
+
+## Поведінка
+
+1. Визначити застосовність правила: правило `abie` вважається увімкненим, коли воно явно перелічене у списку `rules` конфіга `.n-cursor.json` у корені репозиторію.
+2. Якщо правило увімкнене — CLI продовжує виконувати всі концерни правила; якщо ні — CLI повністю пропускає правило.
+3. Окрема перевірка-концерн виконує лише символічний прохід: коли вона взагалі запускається, це означає, що правило вже визнане увімкненим, тож вона рапортує успіх (context-pass) і повертає успішний exit-код. Справжню роботу виконують інші концерни правила, а не цей файл.
+
+Приклад конфіга, який вмикає правило:
+
+```json
+{
+  "rules": ["abie"]
+}
+```
+
+## Гарантії поведінки
+
+- Read-only: гейт лише читає конфіг репозиторію і нічого не змінює.
+- Fail-safe за замовчуванням: за відсутності файла `.n-cursor.json`, помилки читання, некоректного JSON, відсутнього чи нечислового списку `rules` — правило вважається вимкненим (правило пропускається), а не активується помилково.
+- Зіставлення назви правила толерантне до регістру й пробілів навколо значення.
+- Символічний прохід-концерн не кидає винятків і завжди повертає успішний exit-код.

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

@@ -0,0 +1,32 @@
+# env_dns.mjs
+
+## Огляд
+
+Перевірка-чек правила `abie.mdc`: сканує env-файли abie й гарантує, що внутрішньокластерні URL у них вказують на правильний GKE-кластер відповідно до імені файла. Це захист від типової помилки, коли `dev`-конфіг випадково посилається на `ua`-кластер (або навпаки). Якщо в репозиторії немає abie env-файлів, перевірка мовчки проходить.
+
+## Поведінка
+
+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`, якщо порушень немає, інакше ненульовий. Це стандартна точка інтеграції чек-механізму правил.
+
+## Гарантії поведінки
+
+- Read-only: файли лише читаються, нічого не змінюється й не створюється.
+- Fail-safe за відсутності даних: репозиторій без abie env-файлів — це успіх, а не помилка.
+- Нечитабельний файл не валить весь прогон: він стає окремою скаргою, решта файлів перевіряються далі.
+- Файли без розпізнаного імені кластера пропускаються без помилки.
+- Файли обробляються в детермінованому (відсортованому) порядку, тож вивід стабільний між запусками.

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

@@ -0,0 +1,23 @@
+# firebase_hosting.mjs
+
+## Огляд
+
+Перевірка правила `abie`: забороняє артефакти Firebase Hosting у підкаталогах репозиторію. За `abie.mdc` Firebase Hosting у проєкті не дозволено, тож наявність його конфігураційних файлів вважається порушенням. Перевірка лише читає файлову систему й рапортує — нічого не змінює.
+
+## Поведінка
+
+1. Зчитується вміст кореня репозиторію (за замовчуванням — поточний робочий каталог).
+2. Якщо корінь не вдалося прочитати — фіксується помилка з поясненням і перевірка завершується невдало.
+3. Відбираються лише підкаталоги **першого рівня**, окрім службових `.git` та `node_modules`. Сам корінь репозиторію навмисно не перевіряється: однойменні файли там можуть належати суміжним проєктам і не є порушенням.
+4. У кожному відібраному підкаталозі шукаються заборонені артефакти Firebase Hosting:
+   - файли `.firebaserc` та `firebase.json`;
+   - директорія `.firebase/`.
+5. На кожен знайдений артефакт видається повідомлення про порушення з відносним шляхом і вимогою його видалити (шлях нормалізується до `/`-роздільників). Обхід не переривається на першій знахідці — повідомляються всі порушення.
+6. Якщо у жодному підкаталозі артефактів не знайдено — видається підтвердження успіху.
+
+## Гарантії поведінки
+
+- Read-only: перевірка лише читає каталоги й перевіряє наявність файлів, нічого не створює й не видаляє.
+- Fail-safe щодо помилок читання кореня: замість винятку повертається ненульовий код виходу з діагностичним повідомленням.
+- Повертає `0`, якщо порушень немає, і `1`, якщо знайдено хоча б один заборонений артефакт (або корінь не прочитався).
+- Сканується лише перший рівень вкладеності: глибші підкаталоги та сам корінь не перевіряються (рекурсивного обходу немає).

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

@@ -0,0 +1,35 @@
+# 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 і тут не дублюється.
+
+## Поведінка
+
+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-код; його викликає механізм запуску перевірок для кореня репозиторію.
+
+## Гарантії поведінки
+
+- Read-only: модуль лише читає файлову систему й нічого не змінює.
+- Fail-safe для порожнього дерева: відсутність Deployment-маніфестів трактується як успіх, а не помилка.
+- Помилка читання конкретного `hc.yaml` не зупиняє прогон — вона фіксується як окремий fail, а перевірка решти каталогів триває.
+- Каталог `.github/` свідомо виключений зі збору YAML (належить іншому правилу), як і шляхи з cursor-ignore.
+- Зіставлення modeline точне: будь-яке відхилення URL чи формату першого рядка дає зрозуміле повідомлення з посиланням на `abie.mdc`.

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

@@ -0,0 +1,28 @@
+# ua_http_route
+
+## Огляд
+
+Перевірка правила `abie.mdc`, що валідує наявність і коректність inline-patch `HTTPRoute` для `ua`-overlay у Vite-пакетах Kubernetes-маніфестів. Спрацьовує лише для пакетів, які мають `vite.config.{js,mjs,ts}` — для решти перевірка нейтральна (passthrough). Запускається як CLI-check і повертає код виходу для CI.
+
+## Поведінка
+
+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`-модулі правил.
+
+## Гарантії поведінки
+
+- Read-only: лише читає маніфести й конфіги, нічого не змінює у файловій системі.
+- За відсутності `ua/kustomization.yaml` чи `vite.config` перевірка не вимагає patch і фіксує успіх (opt-in за Vite-пакетом).
+- Помилка читання `ua/kustomization.yaml` не зупиняє обхід інших overlay — повідомляється як окремий fail, цикл продовжується.
+- Помилки в base-`HTTPRoute` блокують лише overlay свого пакета, не впливаючи на інші пакети.
+- Результат — агрегований код виходу (0 за умови всіх pass), придатний для використання в CI.

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

@@ -0,0 +1,28 @@
+# ua_node_selector
+
+## Огляд
+
+Check-правило `abie`, яке гарантує: якщо в дереві `k8s/` пакета присутній `Deployment`, то в `ua`-оверлеї (`ua/kustomization.yaml`) обовʼязково має бути inline-patch на цей `Deployment` зі шляхом `/spec/template/spec/nodeSelector` і `preem: false`. Так продакшн-навантаження (`ua`-оверлей) закріплюється за непреемптивними (стабільними) нодами. Перевіряється лише abie-специфічна вимога; структурні обмеження формату JSON6902-патчів (наприклад, заборона `remove + add` на той самий path) перевіряє окреме правило k8s і тут не дублюються.
+
+## Поведінка
+
+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` і інтерпретує повернутий код виходу як результат лінту репозиторію.
+
+## Гарантії поведінки
+
+- Read-only: жодних файлів не змінює, лише читає YAML-конфігурації; мережу не використовує.
+- Fail-safe для відсутніх ресурсів: відсутність `Deployment` у дереві трактується як легітимний прохід, а не помилка.
+- Помилка читання окремого `ua/kustomization.yaml` не зупиняє перевірку — фіксується як провал для конкретного файлу, решта файлів продовжує оброблятися.
+- Кожен `ua`-файл оцінюється незалежно; результат правила агрегує всі окремі pass/fail.
+- Шляхи у звітах нормалізуються до відносних із прямими слешами, тож вивід стабільний і коректний незалежно від платформи (POSIX/Windows).

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

@@ -0,0 +1,29 @@
+# enabled.mjs
+
+## Огляд
+
+Модуль-предикат, який визначає, чи увімкнено правило **abie** у конфігурації репозиторію. Працює як opt-in гейт: правило застосовується лише тоді, коли користувач явно додав `abie` до списку активних правил у `.n-cursor.json`. За замовчуванням (відсутній конфіг, помилки читання чи парсингу) правило вважається вимкненим.
+
+## Поведінка
+
+1. Шукає файл `.n-cursor.json` у корені репозиторію.
+2. Якщо файл відсутній — повертає «вимкнено».
+3. Читає та парсить вміст як JSON. Будь-яка помилка читання чи невалідний JSON трактується як «вимкнено».
+4. Бере поле `rules`. Якщо це не масив — повертає «вимкнено».
+5. Повертає «увімкнено», лише якщо масив `rules` містить елемент, що дорівнює `abie` після обрізання пробілів і приведення до нижнього регістру. Записи `"abie"`, `" ABIE "`, `"Abie"` усі вмикають правило. Щоб вимкнути — прибрати ім'я з `rules` (або видалити поле чи файл).
+
+Приклад конфігурації, що вмикає правило:
+
+```json
+{ "rules": ["abie"] }
+```
+
+## Де використовується
+
+Підключається до applies-механізму правила `abie` (`npm/rules/abie/js/applies.mjs`) як рішення «чи запускати правило». Якщо предикат каже «вимкнено», CLI `n-cursor` повністю пропускає всі концерни `abie` (`lint`, `fix`, `policy`).
+
+## Гарантії поведінки
+
+- Read-only: модуль лише читає конфігураційний файл, нічого не змінює й не звертається до мережі.
+- Fail-safe: за будь-якої проблеми (немає файлу, недоступний для читання, битий JSON, `rules` не масив) повертає «вимкнено» замість винятку — правило тихо вимикається, а не ламає прогін CLI.
+- Толерантний матчинг назви: зайві пробіли та регістр у назві `abie` не заважають розпізнаванню; нерядкові елементи `rules` безпечно ігноруються.

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

@@ -0,0 +1,35 @@
+# env-dns
+
+## Огляд
+
+Бібліотека чистих функцій для перевірки кластерного DNS у env-файлах abie. abie розгорнуто у двох GKE-кластерах (`abie-dev.internal` та `abie-ua.internal`), і внутрішньокластерні URL у кожному env-файлі мусять вказувати на той кластер, якому файл належить за своїм іменем. Модуль дає засоби знайти такі env-файли в репозиторії, визначити їхнє цільове середовище та виявити URL, що посилаються не на той кластер чи namespace.
+
+## Поведінка
+
+1. **Класифікація env-файла за іменем.** Файл вважається abie env-файлом, якщо його basename — `dev.env` або `ua.env` (опціонально з провідною крапкою: `.dev.env`, `.ua.env`). Із такого імені витягується середовище — `dev` або `ua`. Будь-який інший файл (наприклад `production.env` чи безіменний `.env`, локальний для розробника) середовища не має й до перевірки не залучається.
+
+2. **Зіставлення середовища з очікуваннями.** Кожному середовищу відповідає фіксована пара — очікуваний кластерний DNS і обов'язковий префікс namespace:
+   - `dev` → DNS `abie-dev.internal`, namespace має починатися з `dev-`
+   - `ua` → DNS `abie-ua.internal`, namespace має починатися з `ua-`
+
+3. **Сканування внутрішніх URL.** У вмісті env-файла шукаються всі URL виду `http://<svc>.<ns>.svc.<dns>` (з опціональними портом і шляхом). Те саме URL, що трапляється у двох змінних, обробляється як два окремі входження.
+
+4. **Звітування про невідповідності.** Для кожного знайденого URL формується помилка, якщо:
+   - його кластерний DNS не дорівнює очікуваному для цього середовища;
+   - його namespace не починається з очікуваного префікса.
+     Один URL може дати дві окремі помилки (і за DNS, і за namespace). Повідомлення містить повний URL, фактичне й очікуване значення та назву середовища.
+
+5. **Збір файлів для перевірки.** Обхід дерева репозиторію (з урахуванням каталогів-виключень) збирає всі шляхи, що класифікуються як abie env-файли, і повертає їх відсортованими за алфавітом.
+
+Приклад невідповідності: у файлі `app.dev.env` рядок `http://api.ua-core.svc.abie-ua.internal` дасть дві помилки — DNS `abie-ua.internal` не відповідає env `dev` (очікується `abie-dev.internal`), а namespace `ua-core` не починається з `dev-`.
+
+## Де використовується
+
+Функції модуля викликає чек abie у `npm/rules/abie/js/env_dns.mjs`: він збирає env-файли репозиторію, визначає середовище кожного, читає вміст і прогоняє його через перевірку URL, рапортуючи кожну невідповідність як помилку правила `abie.mdc`. Якщо abie env-файлів у репозиторії немає, чек повідомляє про пропуск.
+
+## Гарантії поведінки
+
+- Функції перевірки вмісту чисті й read-only щодо переданого тексту: вони не звертаються до файлової системи й не мутують вхідні дані.
+- Перевірка вмісту не кидає винятків: для невідомого середовища або вмісту без внутрішніх URL повертається порожній список помилок (трактується як «усе гаразд»).
+- Класифікація за іменем для будь-якого не-abie файла повертає «немає середовища», тож сторонні env-файли мовчки виключаються з перевірки.
+- Збір файлів повертає детермінований, відсортований за алфавітом перелік; читання файлів та обробку помилок доступу виконує сам чек-споживач, а не цей модуль.

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

@@ -0,0 +1,33 @@
+# hc-yaml.mjs
+
+## Огляд
+
+Модуль валідує перший рядок-modeline у файлах `hc.yaml` для правила abie. Мета — гарантувати, що файл декларує очікувану `$schema` Kubernetes-ресурсу `HealthCheckPolicy`, аби редактор давав коректні автодоповнення й валідацію за CRD-каталогом. Структурна (per-document) перевірка самого вмісту політики виконується окремо в Rego-політиці `policy/health_check_policy/health_check_policy.rego`, не тут.
+
+## Поведінка
+
+1. З вмісту файла прибирається BOM, текст розбивається на рядки.
+2. Перевіряється лише перший рядок:
+   - якщо файл порожній або перший рядок порожній — повертається помилка про відсутній modeline;
+   - якщо перший рядок не відповідає формату modeline `# yaml-language-server: $schema=…` — повертається помилка про обов'язковий modeline;
+   - якщо modeline присутній, але URL `$schema` не збігається з очікуваним — повертається помилка з правильним URL для підказки.
+3. Якщо перший рядок коректний — повертається `null` (валідація пройдена).
+
+Очікуваний перший рядок файла `hc.yaml`:
+
+```yaml
+# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
+```
+
+Кожне повідомлення про помилку починається з відносного шляху до файла й завершується маркером `(abie.mdc)`.
+
+## Де використовується
+
+Викликається в `npm/rules/abie/js/hc_pairing.mjs`: для кожного знайденого `hc.yaml` перевіряється modeline і репортиться `modeline OK` при `null` або відповідний текст помилки інакше. Константа з очікуваним URL також слугує єдиним джерелом істини для тестів і повідомлень.
+
+## Гарантії поведінки
+
+- Read-only: аналізує лише переданий рядок-вміст, не виконує жодного I/O й не змінює вхідних даних.
+- Не кидає винятків на штатних рядкових даних; на порожньому чи некоректному вмісті повертає описову помилку замість збою.
+- Працює з сирим текстом без повного YAML-парсингу — перевіряється виключно перший рядок.
+- Результат завжди детермінований: або точний текст помилки, або `null`.