@nitra/cursor 5.3.4 → 5.4.0

package/rules/graphql/docs/fix.md

@@ -1,135 +1,39 @@
 ---
 docgen:
   source: npm/rules/graphql/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# `npm/rules/graphql/fix.mjs`
+# fix.mjs
 
 ## Огляд
 
-Файл є точкою входу до правила `graphql` у складі CLI-інструмента `@nitra/cursor`. Він поєднує дві ролі:
+Виконує обробку JS-занепокоєних та політики на вхідному контексті прогону, генеруючи посилання MDC та повертаючи результат.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку зовнішня CLI-оркестрація викликає через `import + run(ctx)` як частину пакетного прогону всіх правил.
-2. **Standalone mode** — якщо файл запущено напряму (`bun rules/graphql/fix.mjs`), виконується повний еквівалент команди `npx @nitra/cursor fix graphql` із завантаженням конфігурації, whitelist та підсумком (summary).
+Виконується як автономний скрипт для виконання повного еквіваленту команди `npx @nitra/cursor fix <id>` та перевірки результату прогону.
 
-Сама логіка перевірки винесена у спільний helper `runStandardRule`, тобто `fix.mjs` для правила `graphql` — це тонкий wrapper, який лише прив'язує спільну механіку до конкретної директорії правила (через `import.meta.dirname`). Послідовність перевірки, що виконується в результаті: `applies → JS-concerns → policy → mdc-refs`.
+## Поведінка
 
-Файл є частиною стандартизованої конвенції правил `npm/rules/<id>/fix.mjs`, де `<id>` — ідентифікатор правила (тут `graphql`).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
-## Експорти / API
+2. Запуск у режимі CLI.
+    *   Виконується як автономний скрипт.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Перевіряє результат прогону для встановлення коду виходу.
 
-| Експорт | Тип                               | Призначення                                                                                                 |
-| ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?): Promise<number>` | Named export — library entry-point правила. Викликається оркестратором, який пакетно запускає набір правил. |
+## Публічний API
 
-Default export відсутній. Інших named-експортів файл не визначає.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-Окремий top-level `if`-блок наприкінці файла активує standalone-режим — він не є експортом, а виконується як side-effect модуля при прямому запуску.
+## Гарантії поведінки
 
-## Функції
-
-### `run(ctx)`
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-**Призначення.** Library-обгортка над `runStandardRule`, що запускає стандартний пайплайн правила `graphql`: `applies → JS-concerns → policy → mdc-refs`. Конкретні фази (підбір файлів, перевірка JS, policy-правила, перевірка mdc-посилань) реалізовані у спільному helper; `fix.mjs` тільки повідомляє, _яке саме_ правило виконувати, — через шлях до своєї директорії (`import.meta.dirname`), де лежать `meta.json`, `*.mdc`, підтеки `js/`, `policy/`, `lib/` тощо.
-
-**Параметри.**
-
-| Параметр | Тип                                                         | Обов'язковий | Опис                                                                                                                                                                                                                                                                            |
-| -------- | ----------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx`    | `RuleContext` (з `../../scripts/lib/run-standard-rule.mjs`) | Ні           | Контекст прогону. Передається оркестратором для перевикористання ресурсів між правилами (наприклад, `walkCache` — кеш обходу файлової системи, аби не сканувати дерево заново для кожного правила). Якщо `ctx` не передано, `runStandardRule` працює зі своїм дефолтним станом. |
-
-**Повертає.** `Promise<number>` — exit-code прогону правила:
-
-- `0` — правило пройшло без порушень (OK).
-- `1` — виявлено порушення (правило фейлиться).
-
-**Side effects.** Сам по собі `run` не має побічних ефектів у файлі — повертає `Promise`, отриманий від `runStandardRule`. Усі реальні ефекти (читання FS, друк діагностики у stdout/stderr, оновлення кешу в `ctx`) інкапсульовані в `runStandardRule`. Зокрема, у library-режимі функція **не** викликає `process.exit` — управління exit-кодом лежить на оркестраторі.
-
-### Standalone-блок (top-level `if`)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-Це не функція, а top-level side-effect модуля. Виконується одноразово при завантаженні.
-
-**Умова активації.** `isRunAsCli(import.meta.url)` повертає `true`, коли модуль завантажений як точка входу (тобто шлях файла збігається з тим, що передано Node/Bun у `process.argv`), а не імпортований як бібліотека.
-
-**Дія.** Викликає `runRuleCli(import.meta.dirname)` — повний CLI-флоу одного правила (config-loading, whitelist, summary) — і завершує процес його exit-кодом через `process.exit`. Це робить файл прямим аналогом виклику `npx @nitra/cursor fix graphql`.
-
-**Чому `process.exit` явний.** Standalone entry-point має повернути коректний exit-code для CI/IDE-інтеграції, тому два правила ESLint (`n/no-process-exit`, `unicorn/no-process-exit`) свідомо вимкнено для цього рядка коментарем-обґрунтуванням.
-
-**Чому `await` на top-level.** Файл використовує top-level `await` — це валідно для ESM-модулів. `runRuleCli` повертає `Promise<number>`, і його результат потрібен синхронно як аргумент `process.exit`.
-
-## Залежності
-
-### Внутрішні (відносні)
-
-| Модуль                                    | Імпорт                     | Роль                                                                                                      |
-| ----------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Інфраструктура standalone-режиму: визначення, чи файл запущено як CLI, та повний CLI-флоу одного правила. |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний пайплайн правила (`applies → JS-concerns → policy → mdc-refs`) і тип `RuleContext`.           |
-
-Імпорти відносні, бо `fix.mjs` лежить у `npm/rules/graphql/`, а спільні helpers — у `npm/scripts/lib/`. Два рівні `..` піднімають із `rules/graphql/` до `npm/` і потім спускають у `scripts/lib/`.
-
-### Зовнішні
-
-Прямих зовнішніх (npm) залежностей файл не оголошує. Будь-які зовнішні пакети підтягуються транзитивно через `runStandardRule` / `runRuleCli`.
-
-### Платформенні / рантайм
-
-- **ES Modules** — файл використовує синтаксис ESM (`import`, `export`), top-level `await`, `import.meta.url`, `import.meta.dirname`.
-- **`import.meta.dirname`** — доступне у сучасних Node.js (>= 20.11) та Bun. Повертає абсолютний шлях до директорії модуля; використовується як ідентифікатор правила для helpers.
-- **`process.exit`** — Node.js/Bun API; завершує процес із заданим exit-кодом.
-
-## Потік виконання / Використання
-
-### Library mode (оркестрація)
-
-1. Зовнішній код (CLI-оркестратор `@nitra/cursor`) робить `import { run } from '<...>/rules/graphql/fix.mjs'`.
-2. Оркестратор готує `ctx` (наприклад, спільний `walkCache`) і викликає `await run(ctx)`.
-3. `run` делегує виклик у `runStandardRule(import.meta.dirname, ctx)`. Helper, маючи шлях до директорії правила, читає її `meta.json`, `*.mdc`, підтеки `js/`, `policy/` і виконує стандартний пайплайн.
-4. Повертається `0` або `1`. Оркестратор агрегує коди всіх правил у фінальний exit-status.
-
-У цьому режимі `process.exit` **не** викликається — модуль не завершує процес самостійно.
-
-### Standalone mode (пряма CLI)
-
-1. Користувач запускає `bun npm/rules/graphql/fix.mjs` (або шлях через рантайм).
-2. ESM-модуль завантажується. Виконується `isRunAsCli(import.meta.url)` — повертає `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)` — повний CLI-флоу (config, whitelist, summary).
-4. `process.exit(<code>)` завершує процес. Code приходить у CI/IDE як результат прогону правила.
-
-Цей режим повністю еквівалентний `npx @nitra/cursor fix graphql` і існує, щоб правило можна було запустити ізольовано — для дебагу або інтеграції з IDE-таском без участі оркестратора.
-
-### Дві ролі в одному файлі
-
-Подвійна роль (library `run` + standalone `main`) дозволяє:
-
-- **Перевикористовувати** код пайплайна — і оркестратор, і пряма CLI йдуть через однакову логіку `runStandardRule` / `runRuleCli`.
-- **Дотримуватися конвенції** `npm/rules/<id>/fix.mjs`: усі правила мають однакову структуру entry-файла, тому інструменти (IDE-завдання, скрипти scaffold) можуть запускати будь-яке правило за єдиним шляхом.
-
-### Розширення
-
-Щоб додати своєрідну поведінку правила `graphql`, не треба змінювати `fix.mjs` — достатньо покласти відповідні файли в директорію правила:
-
-- `meta.json` — метадані (id, опис).
-- `graphql.mdc` — людиночитна частина правила.
-- `js/` — JS-перевірки (фаза JS-concerns).
-- `policy/` — policy-перевірки.
-- `lib/` — спільний код правила.
-
-`runStandardRule` сам підбере й виконає те, що знайде в директорії. `fix.mjs` залишається тонким wrapper-ом.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/hasura/docs/fix.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/hasura/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
   score: 100
 ---
 
@@ -9,16 +9,30 @@ docgen:
 
 ## Огляд
 
-Цей файл ініціює застосування правил. Він запускає процес, що включає перевірку JS-занепокоєнь та політик. При самостійному запуску скрипт завантажує конфігурацію та вайтлістинг, а також надає звіт про виконання.
+Виконує застосування політики JS-занепокоєних на наданому контексті прогону, генеруючи посилання на MDC та повертаючи результат.
+
+Виконується при запуску через командний рядок, виконуючи повний еквівалент команди `npx @nitra/cursor fix <id>`, завантажуючи конфігурацію, перевіряючи дозволи, генеруючи підсумок та визначаючи код виходу.
 
 ## Поведінка
 
-1. Викликати функцію `run` для виконання правила. Це ініціює процес застосування правил, включаючи перевірку JS-занепокоєнь, політик та посилань MDC.
-2. Якщо скрипт виконується як окрема утиліта (standalone), викликати механізм оркестрації для виконання правила. Це забезпечує повну функціональність, включаючи завантаження конфігурації, вайтлістинг та підсумок.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання на MDC.
+    *   Повертає результат прогону.
+2. Запуск правила у режимі CLI.
+    *   Виконується при запуску через CLI.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації.
+    *   Виконує перевірку дозволів.
+    *   Генерує підсумок.
+    *   Визначає код виходу.
 
 ## Публічний API
 
-run — виконує послідовність дій: застосовує правила, обробляє JavaScript-занепокоєння, перевіряє політику та посилання MDC.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
 ## Гарантії поведінки
 

package/rules/hasura/js/docs/internal_urls.md

@@ -1,326 +1,53 @@
+---
+docgen:
+  source: npm/rules/hasura/js/internal_urls.mjs
+  crc: 83abefa3
+  score: 90
+---
+
 # internal_urls.mjs
 
 ## Огляд
 
-Модуль `npm/rules/hasura/js/internal_urls.mjs` реалізує перевірку правила `hasura.mdc` для проєктів **nitra** та **abie**. Його єдина мета — гарантувати, що значення змінної середовища `HASURA_GRAPHQL_ENDPOINT`, заданої в будь-якому файлі `*.env` репозиторію, є **внутрішнім кластерним URL** (GKE/GCP DNS-суфікс `<cluster>.internal`), а не публічним доменом.
-
-Логіка активується лише за умови, що поле `repository` кореневого `package.json` вказує на одну з організацій:
-
-- `https://github.com/nitra/...`
-- `https://github.com/abinbevefes/...`
-
-Якщо ці маркери відсутні, перевірка пропускається без помилок (аналогічно до інших abie-перевірок).
-
-Очікуваний формат URL:
-
-```
-http://<service>.<namespace>.svc.<cluster>.internal:<port>
-```
-
-Приклад валідного значення:
-
-```
-http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080
-```
-
-Сегменти `<service>` та `<namespace>` за наявності YAML-файлів `hasura/k8s/base/svc-hl.yaml` (поле `metadata.name`, headless-сервіс із суфіксом `-h-hl`) та `hasura/k8s/base/namespace.yaml` (поле `metadata.name`) додатково звіряються з фактичними значеннями kubernetes-маніфестів.
-
-Скануються всі файли, що відповідають масці `*.env` (наприклад, `dev.env`, `production.env`). Файл з іменем рівно `.env` (локальний файл розробника) **виключається** з перевірки. Не обходяться службові каталоги: `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next` (відповідно до конфігурації `walkDir`).
-
-## Експорти / API
-
-Модуль є ES-модулем (`.mjs`) і експортує:
-
-| Експорт                       | Тип             | Призначення                                                                                       |
-| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------- |
-| `parseInternalHasuraEndpoint` | функція         | Розбирає URL-рядок на сегменти кластерної DNS-адреси (`service`, `namespace`, `cluster`, `port`). |
-| `isEnvFile`                   | функція         | Чи підлягає файл за відносним шляхом перевірці hasura.mdc.                                        |
-| `isNitraOrAbieRepository`     | функція         | Чи репозиторій належить організаціям nitra / abinbevefes.                                         |
-| `check`                       | функція (async) | Точка входу: запускає повну перевірку для cwd, повертає exit-код процесу.                         |
-
-Внутрішні (не експортовані) допоміжні функції: `readYamlMetadataName`, `collectEnvFiles`, `checkEnvFile`, `readRootRepositoryUrl`.
-
-Внутрішні константи:
-
-| Константа                     | Значення                            | Призначення                                                             |
-| ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------- |
-| `NITRA_REPOSITORY_URL_MARKER` | `'https://github.com/nitra/'`       | Маркер репозиторіїв організації nitra.                                  |
-| `ABIE_REPOSITORY_URL_MARKER`  | `'https://github.com/abinbevefes/'` | Маркер репозиторіїв організації abinbevefes (abie).                     |
-| `HASURA_BASE_DIR`             | `'hasura/k8s/base'`                 | Базовий каталог k8s-маніфестів Hasura.                                  |
-| `HASURA_SVC_HL_FILE`          | `'hasura/k8s/base/svc-hl.yaml'`     | Шлях до headless-сервіса.                                               |
-| `HASURA_NAMESPACE_FILE`       | `'hasura/k8s/base/namespace.yaml'`  | Шлях до namespace-маніфесту.                                            |
-| `ENV_FILE_RE`                 | `/\.env$/u`                         | Регулярка-маркер `*.env` файлів.                                        |
-| `HASURA_ENDPOINT_LINE_RE`     | (див. нижче)                        | Регулярка для знаходження рядка `HASURA_GRAPHQL_ENDPOINT=...` у `.env`. |
-| `INTERNAL_HASURA_URL_RE`      | (див. нижче)                        | Регулярка валідації внутрішнього кластерного URL.                       |
-| `INTERNAL_DNS_SUFFIX`         | `'.internal'`                       | DNS-суфікс GKE/GCP-кластера.                                            |
-
-Регулярні вирази:
-
-- `HASURA_ENDPOINT_LINE_RE = /^[ \t]*(?:export[ \t]+)?HASURA_GRAPHQL_ENDPOINT[ \t]*=[ \t]*['"]?([^'"\r\n#]+)/mu`
-  - Multiline, Unicode. Підтримує `export ` префікс, табуляції/пробіли навколо `=`, опційне обрамлення лапками (`'` або `"`). Капчурить значення до символа лапки, перенесення рядка або `#` (коментар).
-- `INTERNAL_HASURA_URL_RE = /^http:\/\/([^./]+)\.([^./]+)\.svc\.([^./:]+\.internal):(\d+)\/?$/u`
-  - Дозволяє лише схему `http://` (TLS усередині кластера зайвий).
-  - Капчурить чотири сегменти: `service`, `namespace`, DNS-суфікс (з обов'язковим `.internal`), `port`.
-  - Допускає необов'язковий завершальний слеш.
-
-## Функції
-
-### `parseInternalHasuraEndpoint(url)`
-
-**Сигнатура:**
-
-```js
-export function parseInternalHasuraEndpoint(url)
-```
-
-**Параметри:**
-
-- `url` (`string`) — значення `HASURA_GRAPHQL_ENDPOINT`, попередньо очищене від обрамляючих лапок (для надійності функція ще раз застосовує `.trim()`).
-
-**Повертає:**
-
-- При успіху: `{ ok: true, service: string, namespace: string, cluster: string, port: string }`. Поле `cluster` містить ім'я кластера **без** суфіксу `.internal` (наприклад, `abie-ua`).
-- При невідповідності формату: `{ ok: false }`.
-
-**Поведінка та особливості:**
-
-- Дозволяє виключно протокол `http://` і DNS-суфікс `<cluster>.internal` (GKE/GCP-конвенція).
-- Усі сегменти повертаються як рядки (включно з `port`, попри те що значення цифрове).
-- Side effects відсутні.
-
-### `readYamlMetadataName(absPath, kind)` (внутрішня)
-
-**Сигнатура:**
-
-```js
-async function readYamlMetadataName(absPath, kind)
-```
-
-**Параметри:**
-
-- `absPath` (`string`) — абсолютний шлях до YAML-файла.
-- `kind` (`string`) — очікуваний `kind` ресурсу (`'Service'`, `'Namespace'` тощо).
-
-**Повертає:** `Promise<string | null>` — значення `metadata.name` першого документа з відповідним `kind`, або `null`, якщо:
-
-- файл не існує;
-- парсинг YAML не вдався (`parseAllDocuments` кинув виключення);
-- жоден документ у файлі не має заданого `kind` або не має `metadata.name`.
-
-**Side effects:** одне читання з файлової системи (`readFile`); жодних винятків назовні не пропускає.
-
-### `isEnvFile(relPath)`
-
-**Сигнатура:**
-
-```js
-export function isEnvFile(relPath)
-```
-
-**Параметри:**
-
-- `relPath` (`string`) — posix-шлях файла відносно кореня репозиторію.
-
-**Повертає:** `boolean`.
-
-- `true` — для файлів, у яких є ім'я перед `.env`: `dev.env`, `nitra.env`, `production.env`.
-- `false` — для всіх інших, **зокрема** для файла рівно `.env` без імені (локальний файл розробника, виключений з правила hasura.mdc).
-
-**Side effects:** немає.
-
-### `collectEnvFiles(root, ignorePaths)` (внутрішня)
-
-**Сигнатура:**
-
-```js
-async function collectEnvFiles(root, ignorePaths)
-```
-
-**Параметри:**
-
-- `root` (`string`) — абсолютний шлях кореня репозиторію.
-- `ignorePaths` (`string[]`) — абсолютні шляхи каталогів, які слід повністю пропустити при обході (зчитуються з cursor-конфігу).
-
-**Повертає:** `Promise<string[]>` — відсортовані за `localeCompare` posix-шляхи `*.env` файлів відносно `root`.
-
-**Поведінка:**
-
-- Використовує `walkDir` з callback-фільтром.
-- Конвертує windows-роздільники `\` у posix-роздільники `/` перед перевіркою `isEnvFile`.
-- Працює дитерміновано завдяки сортуванню `toSorted`.
-
-**Side effects:** обхід файлової системи.
-
-### `checkEnvFile(relPath, cwd, expected, reporter)` (внутрішня)
-
-**Сигнатура:**
-
-```js
-async function checkEnvFile(relPath, cwd, expected, reporter)
-```
-
-**Параметри:**
-
-- `relPath` (`string`) — відносний posix-шлях файла (для повідомлень репортера).
-- `cwd` (`string`) — корінь репозиторію (для побудови абсолютного шляху).
-- `expected` (`{ service: string | null, namespace: string | null }`) — очікувані сегменти, прочитані з YAML-маніфестів; `null`-поля пропускаються.
-- `reporter` (`{ pass: (msg: string) => void, fail: (msg: string) => void }`) — обробник результатів (зазвичай з `createCheckReporter`).
-
-**Повертає:** `Promise<void>`. Результат комунікується через `reporter`.
-
-**Поведінка по гілках:**
-
-1. Якщо в файлі **немає** змінної `HASURA_GRAPHQL_ENDPOINT` — функція мовчки виходить без виклику `pass`/`fail`.
-2. Якщо значення не парситься як внутрішній кластерний URL — викликає `fail` з прикладом очікуваного формату (`https://<service>.<namespace>.svc.<cluster>.internal:<port>`).
-3. Якщо `expected.service` задане і не збігається — `fail` з посиланням на `hasura/k8s/base/svc-hl.yaml`.
-4. Якщо `expected.namespace` задане і не збігається — `fail` з посиланням на `hasura/k8s/base/namespace.yaml`.
-5. Інакше — `pass` з підтвердженням, що URL внутрішній кластерний.
-
-**Side effects:** читання файла, виклики методів `reporter`.
-
-**Примітка:** в `fail`-повідомленні приклад наведений зі схемою `https://`, хоча сама регулярка `INTERNAL_HASURA_URL_RE` дозволяє лише `http://` (так задумано — TLS усередині кластера зайвий).
-
-### `readRootRepositoryUrl(cwd)` (внутрішня)
-
-**Сигнатура:**
-
-```js
-async function readRootRepositoryUrl(cwd)
-```
-
-**Параметри:**
-
-- `cwd` (`string`) — корінь репозиторію.
-
-**Повертає:** `Promise<string | null>` — URL з поля `repository` (нормалізований через `getRepositoryUrl`) або `null`, якщо:
-
-- `package.json` не існує;
-- JSON не валідний;
-- поле `repository` відсутнє / нерозпізнаний формат.
-
-**Side effects:** одне читання `package.json`.
-
-### `isNitraOrAbieRepository(url)`
-
-**Сигнатура:**
-
-```js
-export function isNitraOrAbieRepository(url)
-```
-
-**Параметри:**
-
-- `url` (`string | null | undefined`) — URL репозиторію.
-
-**Повертає:** `boolean`.
-
-- `true`, якщо `url` — рядок і містить (case-insensitive) маркер `https://github.com/nitra/` або `https://github.com/abinbevefes/`.
-- `false` — у решті випадків (включно з `null`, `undefined`, не-рядковими значеннями).
-
-**Side effects:** немає.
-
-### `check(cwd?)`
-
-**Сигнатура:**
-
-```js
-export async function check(cwd = process.cwd())
-```
-
-**Параметри:**
-
-- `cwd` (`string`, опційний, за замовчуванням `process.cwd()`) — корінь репозиторію.
-
-**Повертає:** `Promise<number>` — exit-код процесу (`0` — OK або правило не застосовується, `1` — є хоча б одне порушення). Конкретне значення формує `reporter.getExitCode()`.
-
-**Поведінка (послідовно):**
-
-1. Створює репортер через `createCheckReporter()`.
-2. Зчитує URL репозиторію з `package.json`. Якщо це не nitra/abie — `pass('Пропущено: …')` і повертає exit-код (зазвичай `0`).
-3. Зчитує очікувані `service` і `namespace` з YAML-маніфестів (обидва можуть бути `null`).
-4. Завантажує `ignorePaths` з cursor-конфігу (`loadCursorIgnorePaths`).
-5. Збирає всі `*.env` файли. Якщо їх немає — `pass('Не знайдено жодного *.env файла — нічого перевіряти')` і повертає exit-код.
-6. Послідовно (без паралелізму) викликає `checkEnvFile` для кожного знайденого файла.
-7. Якщо після перевірок exit-код залишився `0` і **жоден** файл не мав `HASURA_GRAPHQL_ENDPOINT` (тобто не було ні `pass`, ні `fail` зі змістом перевірки), додає підсумкове `pass` з кількістю та іменами перевірених файлів.
-
-**Side effects:** читання файлів, обхід каталогів, виведення повідомлень репортера (зазвичай у stdout/stderr).
-
-## Залежності
-
-### Зовнішні модулі (npm)
-
-- `yaml` — функція `parseAllDocuments` для парсингу мульти-документних YAML-файлів kubernetes-маніфестів.
-
-### Node.js core
-
-- `node:fs` — `existsSync` для синхронної перевірки наявності `package.json` та YAML-файлів.
-- `node:fs/promises` — `readFile` для асинхронного читання файлів у UTF-8.
-- `node:path` — `basename`, `join`, `relative` для роботи зі шляхами.
-
-### Внутрішні модулі репозиторію
-
-- `../../../scripts/auto-rules.mjs` — `getRepositoryUrl` для нормалізації поля `repository` у `package.json` (підтримує і рядкову, і об'єктну форму).
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter` для уніфікованого механізму репортингу `pass`/`fail` та обчислення exit-коду.
-- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths` для отримання списку каталогів, виключених з обходу (повертає абсолютні шляхи).
-- `../../../scripts/utils/walkDir.mjs` — `walkDir` для рекурсивного обходу файлової системи з callback-логікою і набором default-ignore (`node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`).
-
-### Файли, що читаються в рантаймі
-
-- `<cwd>/package.json` — джерело поля `repository`.
-- `<cwd>/hasura/k8s/base/svc-hl.yaml` — джерело очікуваного `service` (якщо існує).
-- `<cwd>/hasura/k8s/base/namespace.yaml` — джерело очікуваного `namespace` (якщо існує).
-- `<cwd>/**/*.env` (без рівно `.env` і без ignore-каталогів) — файли, що перевіряються.
-
-## Потік виконання / Використання
+parseInternalHasuraEndpoint
+Витягує значення HASURA_GRAPHQL_ENDPOINT з конфігурації для формування внутрішнього кластерного URL
 
-### Сценарій 1. Запуск як check-функції правила hasura.mdc
+isEnvFile
+Перевіряє, чи файл має розширення .env і не є локальним файлом розробника
 
-Модуль очікувано викликається з єдиної точки входу `check()` через інфраструктуру `npm/rules`/`scripts`. Типове використання:
+isNitraOrAbieRepository
+Перевіряє, чи URL репозиторію містить маркери nitra або abie
 
-```js
-import { check } from './internal_urls.mjs'
+check
+Перевіряє коректність HASURA_GRAPHQL_ENDPOINT у файлах .env відповідно до конфігурації з package.json та YAML файлів
 
-const exitCode = await check(process.cwd())
-process.exitCode = exitCode
-```
+## Поведінка
 
-### Сценарій 2. Послідовність кроків при виконанні `check()`
+parseInternalHasuraEndpoint
+Розбирає значення HASURA_GRAPHQL_ENDPOINT як внутрішній кластерний URL
 
-1. **Препроцесинг репозиторію.** Зчитується `package.json`. Якщо `repository` не вказує на nitra/abie — правило мовчки пропускається з повідомленням `pass`.
-2. **Підготовка очікуваних значень.** Зчитуються `metadata.name` з `svc-hl.yaml` (як `Service`) і `namespace.yaml` (як `Namespace`). Кожне поле може бути `null` (тоді відповідна перевірка для сегмента URL не виконується).
-3. **Збір кандидатів.** Через `walkDir` з ignore-списком з cursor-конфігу збираються усі `*.env` файли (відсортовано). Якщо колекція порожня — повідомляється `pass` і завершується.
-4. **Перевірка кожного файла.** Для кожного знайденого `*.env`:
-   - Якщо у файлі немає `HASURA_GRAPHQL_ENDPOINT` — пропуск без репортингу.
-   - Інакше значення розбирається `parseInternalHasuraEndpoint`. Якщо парсинг не вдався — `fail`.
-   - Якщо `expected.service` заданий і `parsed.service` не збігається — `fail`.
-   - Якщо `expected.namespace` заданий і `parsed.namespace` не збігається — `fail`.
-   - Інакше — `pass`.
-5. **Підсумок.** Якщо за результатом усіх перевірок exit-код залишився `0` (тобто жодного `fail` не було), додається підсумкове `pass` з переліком імен файлів. Це покриває кейс, коли всі `*.env` не містили змінної взагалі.
-6. **Exit-код.** Повертається через `reporter.getExitCode()`: `0` — успіх, `1` — є порушення.
+isEnvFile
+Перевіряє, чи файл має розширення .env і не є локальним файлом розробника
 
-### Сценарій 3. Що вважається валідним URL
+isNitraOrAbieRepository
+Перевіряє, чи URL репозиторію містить маркери nitra або abie
 
-Валідні приклади:
+check
+Перевіряє коректність HASURA_GRAPHQL_ENDPOINT у файлах .env відповідно до конфігурації з package.json та YAML файлів
 
-- `http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080`
-- `http://hasura-h-hl.nitra-prod.svc.nitra-cluster.internal:8080/`
+## Публічний API
 
-Невалідні приклади (викличуть `fail`):
+parseInternalHasuraEndpoint — розбиває значення `HASURA_GRAPHQL_ENDPOINT` на внутрішній URL кластера. Дозволяє `http://` та DNS-суфікс `<cluster>.internal` (GKE/GCP). Поле `cluster` містить ім'я кластера без `.internal` (наприклад `abie-ua`). Повертає сегменти або `{ ok: false }` при невідповідності формату внутрішнього кластерного URL.
 
-- `https://my.public.domain:443` — публічний домен.
-- `http://hasura-h-hl.nitra-prod.svc.cluster.local:8080` — DNS-суфікс `.local`, а не `.internal`.
-- `http://hasura-h-hl.svc.abie-ua.internal:8080` — відсутній сегмент `namespace`.
-- `http://hasura-h-hl.nitra-prod.svc.abie-ua.internal` — відсутній port.
-- `http://hasura-h-hl.nitra-prod.svc.abie-ua.internal:8080/graphql` — є шлях після `/`.
+isEnvFile — визначає, чи відносний шлях закінчується на `*.env`, який необхідно перевіряти (hasura.mdc). Файл з іменем `.env` повертається як виняток (false).
 
-### Сценарій 4. Інтеграція в репортинг
+isNitraOrAbieRepository — перевіряє, чи URL репозиторію вказує на `nitra` або `abie` (за маркерами hasura.mdc).
 
-Для цілісного запуску модуль не виводить нічого сам — усі повідомлення (`pass`/`fail`) делегуються `createCheckReporter()`. Це означає, що формат логів, кольори та сумарний exit-код узгоджені з рештою rule-перевірок у `npm/rules`.
+check — виконує перевірку hasura.mdc для поточного робочого каталогу.
 
-### Сценарій 5. Граничні випадки
+## Гарантії поведінки
 
-- **Файл `.env`** (без імені, локальний розробницький) **пропускається** на рівні `isEnvFile`.
-- **Відсутнє `repository` в `package.json`** → правило пропускається з `pass`.
-- **YAML-файли відсутні / невалідні** → відповідне поле `expected` стане `null` і перевірка сегмента не виконується (але формат URL все одно валідується).
-- **`HASURA_GRAPHQL_ENDPOINT` у `.env` закоментований через `#` після значення** → регулярка зупиниться на `#`, повернувши значення до коментаря.
-- **Значення в подвійних/одинарних лапках** → лапки відкидаються регуляркою-капчуром.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.