@7n/rules 1.0.0

package/rules/abie/firebase_hosting/firebase_hosting.mdc

@@ -0,0 +1,3 @@
+## Firebase Hosting
+
+У **кожному** підкаталозі, що лежить **безпосередньо** в корені репозиторію, не тримати конфіг і кеш **Firebase Hosting**: у таких каталогах не повинно бути **`.firebaserc`**, **`firebase.json`** та каталогу **`.firebase/`** (у **самому** корені репозиторію ці імена перевіркою abie **не** розглядаються; `node_modules` / `.git` зі скану вилучаються).

package/rules/abie/firebase_hosting/main.mjs

@@ -0,0 +1,46 @@
+/** @see ./docs/firebase_hosting.md */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+const SKIP_TOP_DIR_NAMES = new Set(['.git', 'node_modules'])
+
+/**
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту.
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат із порушеннями.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+  const root = ctx.cwd
+
+  let entries
+  try {
+    entries = await readdir(root, { withFileTypes: true })
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    fail(`Не вдалося прочитати ${root} для перевірки Firebase Hosting: ${msg} (abie.mdc)`)
+    return reporter.result()
+  }
+  const topDirs = entries.filter(e => e.isDirectory() && !SKIP_TOP_DIR_NAMES.has(e.name))
+  let hasViolation = false
+  for (const e of topDirs) {
+    for (const name of ['.firebaserc', 'firebase.json']) {
+      const rel = join(e.name, name).replaceAll('\\', '/')
+      if (existsSync(join(root, e.name, name))) {
+        fail(`Знайдено заборонений файл Firebase Hosting: ${rel} — видали його (abie.mdc)`)
+        hasViolation = true
+      }
+    }
+    if (existsSync(join(root, e.name, '.firebase'))) {
+      fail(`Знайдено заборонену директорію: ${e.name}/.firebase/ — видали її (abie.mdc)`)
+      hasViolation = true
+    }
+  }
+  if (!hasViolation) {
+    pass('Підкаталоги кореня (1-й рівень, без .git/node_modules): артефактів Firebase Hosting не знайдено (abie.mdc)')
+  }
+  return reporter.result()
+}

package/rules/abie/hc_pairing/concern.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": { "scope": "full", "glob": ["**/k8s/**/*.{yaml,yml}"] }
+}

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

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/abie/hc_pairing/main.mjs
+docgen:
+  crc: 8aa393da
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Функція `lint` аналізує каталоги, що містять конфігураційні файли для анімованих деплоїв. Вона перевіряє наявність файлу `hc.yaml` у кожному такому каталозі та валідацію його вмісту відповідно до структури `abieHcModeline`. Результати перевірки надаються у виводі, вказуючи на відповідність або деталізуючи знайдені порушення. Функція є read-only і не виконує операцій з файловою системою чи базами даних. Вона забезпечує fail-safe поведінку, перехоплюючи всі потенційні помилки замість того, щоб викидати винятки, і не використовує механізму кешування. У поведінці обов'язково згадуються маркери повідомлень відповідно до `abie.mdc`.
+
+## Поведінка
+
+Поведінка:
+1. Визначає кореневу директорію для аналізу.
+2. Збирає списки директорій з анімованими деплойментами та відповідних YAML-файлів, ігноруючи закриті шляхи, визначені в конфігурації.
+3. Якщо деплойменти не знайдено, повідомляє про пропуск перевірки `hc.yaml` та завершує роботу.
+4. Для кожної знайденої директорії деплоймента виконує наступне:
+    а. Визначає повний та відносний шлях до файлу `hc.yaml`.
+    б. Перевіряє, чи існує файл `hc.yaml` поруч із деплойментом. Якщо ні, фіксує порушення та рекомендує додати `HealthCheckPolicy` (abie.mdc).
+    в. Намагається прочитати вміст `hc.yaml`. У разі невдачі з читанням, фіксує це як порушення.
+    г. Якщо файл прочитано успішно, валідує його вміст на відповідність моделі `abieHcModeline`. У разі успішної валідації, підтверджує відповідність. У разі виявлення помилки, фіксує це порушення.
+5. Повертає зведений результат усіх перевірок.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/abie/hc_pairing/hc_pairing.mdc

@@ -0,0 +1,23 @@
+## k8s: `hc.yaml` поруч із Deployment
+
+Якщо під **`k8s`** є **Deployment**, у **тій самій директорії** має бути **`hc.yaml`** з **HealthCheckPolicy** (**`networking.gke.io/v1`**): коректний modeline **`$schema`**, **`httpHealthCheck.requestPath`** — непорожній шлях від кореня (рядок, що починається з **`/`**: канонічно **`/healthz`**, але також допустимі **`/IsAlive`**, **`/api/live`** тощо — узгоджується з реальним endpoint сервісу), порт **8080**, **`targetRef.name`** — **headless** **Service** з суфіксом **`-hl`** (узгоджено з парою **`svc.yaml`** / **`svc-hl.yaml`** у **k8s.mdc**): або **`${metadata.name}-hl`**, або те саме ім'я, якщо **`metadata.name`** уже з **`-hl`**.
+
+```yaml title="hc.yaml"
+# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
+apiVersion: networking.gke.io/v1
+kind: HealthCheckPolicy
+metadata:
+  name: СЕРВІС
+  namespace: dev # kustomize overlay
+spec:
+  default:
+    config:
+      type: HTTP
+      httpHealthCheck:
+        requestPath: /healthz
+        port: 8080
+  targetRef:
+    group: ''
+    kind: Service
+    name: СЕРВІС-hl
+```

package/rules/abie/hc_pairing/main.mjs

@@ -0,0 +1,52 @@
+/** @see ./docs/hc_pairing.md */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
+
+import { validateAbieHcModeline } from '../lib/hc-yaml.mjs'
+import { collectDeploymentDirs, findK8sYamlFiles } from '../lib/k8s-tree.mjs'
+
+/**
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx Контекст лінту (cwd, перелік файлів тощо).
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} Результат лінту з переліком порушень.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+  const root = ctx.cwd
+
+  const ignorePaths = await loadCursorIgnorePaths(root)
+  const yamls = await findK8sYamlFiles(root, ignorePaths)
+  const deploymentDirs = await collectDeploymentDirs(root, yamls, fail)
+
+  if (deploymentDirs.size === 0) {
+    pass('Немає Deployment у дереві k8s — перевірку hc.yaml пропущено')
+    return reporter.result()
+  }
+  pass(`Знайдено Deployment у ${deploymentDirs.size} директорія(ї/й) k8s — перевіряємо hc.yaml поруч`)
+
+  for (const dir of [...deploymentDirs].toSorted((a, b) => a.localeCompare(b))) {
+    const hcAbs = `${dir}/hc.yaml`
+    const relHc = relative(root, hcAbs).replaceAll('\\', '/') || 'hc.yaml'
+    if (!existsSync(hcAbs)) {
+      fail(`${relative(root, dir) || dir}: є Deployment, але немає hc.yaml поруч — додай HealthCheckPolicy (abie.mdc)`)
+      continue
+    }
+    let hcRaw
+    try {
+      hcRaw = await readFile(hcAbs, 'utf8')
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      fail(`${relHc}: не вдалося прочитати (${msg})`)
+      continue
+    }
+    const modelineErr = validateAbieHcModeline(hcRaw, relHc)
+    if (modelineErr === null) pass(`${relHc}: modeline OK`)
+    else fail(modelineErr)
+  }
+
+  return reporter.result()
+}

package/rules/abie/health_check_policy/concern.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "policy": {
+    "files": {
+      "walkGlob": "**/k8s/**/hc.yaml"
+    }
+  }
+}

package/rules/abie/health_check_policy/health_check_policy.mdc

@@ -0,0 +1,19 @@
+## Rego: структура `HealthCheckPolicy` у `hc.yaml`
+
+Rego-пакет: `abie.health_check_policy`
+
+Цільові файли: `…/k8s/.../hc.yaml`.
+
+Перевіряє для `kind: HealthCheckPolicy` (з `apiVersion` що починається на `networking.gke.io/`):
+
+- `apiVersion` — точно `networking.gke.io/v1`;
+- `metadata.name` — непорожній рядок;
+- `metadata.namespace` — `dev`;
+- `spec.default.config.type` — `HTTP`;
+- `spec.default.config.httpHealthCheck.requestPath` — непорожній, починається з `/`;
+- `spec.default.config.httpHealthCheck.port` — `8080` (обов'язковий, відсутність теж помилка);
+- `spec.targetRef.kind` — `Service`;
+- `spec.targetRef.group` — порожній рядок `''` (якщо поле присутнє);
+- `spec.targetRef.name` — `<metadata.name>-hl` (якщо `metadata.name` вже закінчується на `-hl` — використовується як є).
+
+FS-парність HCP↔Deployment та modeline `$schema` у `hc.yaml` — поза Rego, у `js/hc_pairing.mjs`. JS-опис структури та приклад — у `js/hc_pairing.mdc`.

package/rules/abie/health_check_policy/health_check_policy.rego

@@ -0,0 +1,172 @@
+# Структурна перевірка `HealthCheckPolicy` (abie.mdc).
+#
+# Запуск (локально):
+#   conftest test path/to/k8s/.../hc.yaml \
+#     -p npm/rules/abie/policy/health_check_policy \
+#     --namespace abie.health_check_policy
+#
+# Перевіряє для `kind: HealthCheckPolicy`:
+#  - `apiVersion: networking.gke.io/v1` (точна відповідність);
+#  - `metadata.name` — непорожній рядок;
+#  - `spec.default.config.type: HTTP`;
+#  - `spec.default.config.httpHealthCheck.requestPath` — непорожній і
+#    починається з `/`;
+#  - `spec.default.config.httpHealthCheck.port: 8080`;
+#  - `spec.targetRef.kind: Service`;
+#  - `spec.targetRef.name` — `<hcp.metadata.name>-hl` (exact, з нормалізацією
+#    суфікса).
+#
+# Cross-file gating: glob по `hc.yaml` у k8s-дереві — у
+# `policy/health_check_policy/target.json`. FS-парність HCP↔Deployment та
+# modeline `hc.yaml` — `js/hc_pairing.mjs`. Rule-level applies-гейт —
+# `js/applies.mjs`.
+#
+# Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
+# Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`
+# (.cursor/rules/conftest.mdc). Лінт — `bun run lint-rego` (regal).
+package abie.health_check_policy
+
+import rego.v1
+
+expected_api_version := "networking.gke.io/v1"
+
+req_path_starts_with_slash_template := concat(" ", [
+	"HealthCheckPolicy: requestPath має починатись з `/`",
+	"(зараз %q) (abie.mdc)",
+])
+
+target_ref_name_template := concat(" ", [
+	"HealthCheckPolicy: targetRef.name має посилатися на headless Service",
+	"(очікується %q, суфікс -hl) (зараз %q) (abie.mdc)",
+])
+
+# ── deny: apiVersion / kind ───────────────────────────────────────────────
+
+deny contains msg if {
+	input.kind == "HealthCheckPolicy"
+	api_version := object.get(input, "apiVersion", "")
+	api_version != expected_api_version
+	msg := sprintf(
+		"HealthCheckPolicy: apiVersion має бути %q (зараз %q) (abie.mdc)",
+		[expected_api_version, api_version],
+	)
+}
+
+# ── deny: metadata.name ───────────────────────────────────────────────────
+
+deny contains "HealthCheckPolicy: metadata.name має бути непорожнім рядком (abie.mdc)" if {
+	input.kind == "HealthCheckPolicy"
+	startswith(object.get(input, "apiVersion", ""), "networking.gke.io/")
+	name := object.get(object.get(input, "metadata", {}), "name", "")
+	trim_space(name) == ""
+}
+
+# ── deny: metadata.namespace ──────────────────────────────────────────────
+
+deny contains msg if {
+	is_health_check_policy
+	ns := object.get(object.get(input, "metadata", {}), "namespace", "")
+	ns != "dev"
+	msg := sprintf("HealthCheckPolicy: metadata.namespace має бути dev (зараз %q) (abie.mdc)", [ns])
+}
+
+# ── deny: spec.default.config.type ────────────────────────────────────────
+
+deny contains "HealthCheckPolicy: spec.default.config.type має бути HTTP (abie.mdc)" if {
+	is_health_check_policy
+	is_object(default_config)
+	object.get(default_config, "type", "") != "HTTP"
+}
+
+# ── deny: requestPath ─────────────────────────────────────────────────────
+
+deny contains "HealthCheckPolicy: spec.default.config.httpHealthCheck.requestPath має бути непорожнім (abie.mdc)" if {
+	is_health_check_policy
+	is_object(http_health_check)
+	req_path == ""
+}
+
+deny contains msg if {
+	is_health_check_policy
+	is_object(http_health_check)
+	req_path != ""
+	not startswith(req_path, "/")
+	msg := sprintf(req_path_starts_with_slash_template, [req_path])
+}
+
+# ── deny: port == 8080 ────────────────────────────────────────────────────
+
+deny contains "HealthCheckPolicy: spec.default.config.httpHealthCheck.port має бути 8080 (abie.mdc)" if {
+	is_health_check_policy
+	is_object(http_health_check)
+	object.get(http_health_check, "port", null) == null
+}
+
+deny contains msg if {
+	is_health_check_policy
+	is_object(http_health_check)
+	port := object.get(http_health_check, "port", null)
+	port != null
+	port != 8080
+	msg := sprintf("HealthCheckPolicy: port має бути 8080 (зараз %v) (abie.mdc)", [port])
+}
+
+# ── deny: targetRef.kind == Service ──────────────────────────────────────
+
+deny contains msg if {
+	is_health_check_policy
+	target_ref := object.get(object.get(input, "spec", {}), "targetRef", null)
+	is_object(target_ref)
+	kind := object.get(target_ref, "kind", "")
+	kind != ""
+	kind != "Service"
+	msg := sprintf("HealthCheckPolicy: targetRef.kind має бути Service (зараз %q) (abie.mdc)", [kind])
+}
+
+# ── deny: targetRef.group == '' ───────────────────────────────────────────
+
+deny contains msg if {
+	is_health_check_policy
+	target_ref := object.get(object.get(input, "spec", {}), "targetRef", {})
+	is_object(target_ref)
+	group := object.get(target_ref, "group", null)
+	group != null
+	group != ""
+	msg := sprintf("HealthCheckPolicy: targetRef.group має бути порожнім рядком '' (зараз %q) (abie.mdc)", [group])
+}
+
+# ── deny: targetRef.name = `<hcp.metadata.name>-hl` (exact, з нормалізацією)
+
+deny contains msg if {
+	is_health_check_policy
+	hcp_name := object.get(object.get(input, "metadata", {}), "name", "")
+	hcp_name != ""
+	target_name := object.get(object.get(object.get(input, "spec", {}), "targetRef", {}), "name", "")
+	target_name != ""
+	expected_hl := expected_target_ref_name(hcp_name)
+	target_name != expected_hl
+	msg := sprintf(target_ref_name_template, [expected_hl, target_name])
+}
+
+# Нормалізація: якщо `metadata.name` уже закінчується на `-hl` — використовуємо
+# як є; інакше додаємо суфікс.
+expected_target_ref_name(name) := name if {
+	endswith(name, "-hl")
+} else := concat("", [name, "-hl"])
+
+# ── helpers ───────────────────────────────────────────────────────────────
+
+is_health_check_policy if {
+	input.kind == "HealthCheckPolicy"
+	startswith(object.get(input, "apiVersion", ""), "networking.gke.io/")
+}
+
+default_config := object.get(
+	object.get(object.get(input, "spec", {}), "default", {}),
+	"config",
+	{},
+)
+
+http_health_check := object.get(default_config, "httpHealthCheck", {})
+
+req_path := object.get(http_health_check, "requestPath", "")

package/rules/abie/http_route_base/concern.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "policy": {
+    "files": {
+      "walkGlob": "**/k8s/**/base/**/hr.yaml"
+    }
+  }
+}

package/rules/abie/http_route_base/http_route_base.mdc

@@ -0,0 +1,9 @@
+## Rego: `HTTPRoute` у base-шарі — домени `aiml.live`
+
+Rego-пакет: `abie.http_route_base`
+
+Цільові файли: `…/k8s/.../base/.../*.yaml` типу HTTPRoute.
+
+Перевіряє, що кожен hostname у `spec.hostnames` належить до домену `aiml.live`: точна відповідність `aiml.live`, wildcard `*.aiml.live` або будь-який піддомен `*.aiml.live`. Перевірка case-insensitive. Не є HTTPRoute — пакет не діє.
+
+JS-частина (cross-file аналіз ua-overlay, backendRefs, тощо) — у `js/ua_http_route.mjs`. Людинозрозумілий опис + приклади — у `js/http_route_base.mdc`.

package/rules/abie/http_route_base/http_route_base.rego

@@ -0,0 +1,45 @@
+# Перевірка `HTTPRoute` у шарі `…/k8s/.../base/...` (abie.mdc): дозволені лише
+# hostnames з домену `aiml.live` (включно з піддоменами та `*.aiml.live`).
+#
+# Запуск (локально):
+#   conftest test path/to/k8s/base/hr.yaml \
+#     -p npm/rules/abie/policy/http_route_base \
+#     --namespace abie.http_route_base
+#
+# Cross-file gating (саме шлях `…/k8s/.../base/...` визначає, чи застосовувати
+# правило) задає glob у `policy/http_route_base/target.json`. Тут — лише
+# валідація вмісту `spec.hostnames`. Rule-level applies-гейт — `js/applies.mjs`.
+#
+# Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
+# Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`
+# (.cursor/rules/conftest.mdc). Лінт — `bun run lint-rego` (regal).
+package abie.http_route_base
+
+import rego.v1
+
+allowed_apex := "aiml.live"
+
+deny contains msg if {
+	input.kind == "HTTPRoute"
+	some host in object.get(object.get(input, "spec", {}), "hostnames", [])
+	is_string(host)
+	not host_matches_aiml_live(host)
+	msg := sprintf("HTTPRoute (base): %q має бути в домені aiml.live (abie.mdc)", [host])
+}
+
+# Чи hostname належить до aiml.live (точна відповідність, піддомен `*.aiml.live`
+# або довільний субдомен `*.aiml.live`).
+host_matches_aiml_live(host) if {
+	host_lower := lower(host)
+	host_lower == allowed_apex
+}
+
+host_matches_aiml_live(host) if {
+	host_lower := lower(host)
+	endswith(host_lower, sprintf(".%s", [allowed_apex]))
+}
+
+host_matches_aiml_live(host) if {
+	host_lower := lower(host)
+	host_lower == sprintf("*.%s", [allowed_apex])
+}

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

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: enabled.mjs
+resource: npm/rules/abie/lib/enabled.mjs
+docgen:
+  crc: 3dfdd318
+---
+
+Файл керує активацією правил на рівні гейта. Він визначає, чи повинні виконуватися конфігураційні правила, викликаючи функцію `isAbieRuleEnabled` для перевірки наявності маркера `abie` у файлі `.n-rules.json:rules`. Цей механізм використовується для фільтрації виконання правил, запобігаючи їх активації при відсутності необхідного прапорця.
+
+## Поведінка
+
+1. Створення шляху до конфігураційного файлу `.n-rules.json`
+
+2. Перевірка наявності файлу. Якщо файл відсутній, повертається `false`.
+
+3. Читання вмісту файлу. У разі помилки читання, повертається `false`.
+
+4. Парсинг вмісту у формат JSON. У разі помилки парсингу, повертається `false`.
+
+5. Витягнення масиву правил з конфігурації.
+
+6. Перевірка типу витягнутого масиву. Якщо дані не є масивом, повертається `false`.
+
+7. Ітерація по масиву правил. Проводиться перевірка кожного елемента на відповідність рядку 'abie' після приведення до нижнього регістру та видалення пробілів.
+
+8. Повернення результату. Якщо знайдено правило 'abie', повертається `true`. У іншому випадку повертається `false`.
+
+## Публічний API
+
+isAbieRuleEnabled — перевіряє статус увімкненості правила abie у файлі `.n-rules.json:rules`.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Не звертається до мережі.

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

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: env-dns.mjs
+resource: npm/rules/abie/lib/env-dns.mjs
+docgen:
+  crc: 6ffce198
+---
+
+Файл перевіряє конфігураційні файли середовища (`*.dev.env`, `*.ua.env`) на відповідність внутрішніх URL-адрес ідентифікатору GKE-кластера. Функція `validateAbieEnvInternalUrls` сканує URL-адреси формату `http(s)://<svc>.<ns>.svc.<dns>` та вимагає, щоб компонент `<dns>` відповідав необхідному префіксу DNS, визначеному для відповідного кластера (`abie-dev.internal` або `abie-ua.internal`).
+
+## Поведінка
+
+abieEnvNameFromBasename
+Дістає тип середовища dev або ua з імени файлу. Файл без імені повертає null.
+
+validateAbieEnvInternalUrls
+Сканує вміст файлу на наявність внутрішніх URL. Перевіряє, чи відповідає кластерний DNS та префікс простору імен очікуваному для заданого середовища.
+
+collectAbieEnvFiles
+Збирає файли середовища abie, які відповідають правилам іменування. Виключає файли без імені.
+
+## Публічний API
+
+- abieEnvNameFromBasename — Витягує `dev` або `ua` з імені env-файлу.
+- validateAbieEnvInternalUrls — Виявляє розбіжності кластерного DNS/namespace у внутрішніх URL-адресах.
+- collectAbieEnvFiles — Збирає `.env` файли, що відповідають формату abie env (dev.env, ua.env, з провідною крапкою).
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: hc-yaml.mjs
+resource: npm/rules/abie/lib/hc-yaml.mjs
+docgen:
+  crc: e9aba7c8
+---
+
+Файл виконує структурну валідацію конфігурації `modeline` у файлах `hc.yaml`. Функція `validateAbieHcModeline` перевіряє відповідність конфігурації визначеному контракту. Валідація проводиться порівнянням конфігурації з визначеною схемою, доступною за посиланням https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json. Цей процес забезпечує коректність конфігурації для ідентифікації (abie.mdc). Експортована константа ABIE_HC_SCHEMA_URL використовується для посилання на цю схему.
+
+## Поведінка
+
+validateAbieHcModeline перевіряє modeline у файлі `hc.yaml`.
+
+Перевіряє, чи перший рядок не порожній. Повертає повідомлення про необхідність наявності modeline `# yaml-language-server: $schema=… (abie.mdc)`.
+
+Перевіряє, чи перший рядок містить необхідний modeline. Повертає повідомлення про відсутність modeline $schema (abie.mdc).
+
+Перевіряє, чи значення $schema відповідає очікуваному URL. Повертає повідомлення про неправильне значення $schema, включаючи необхідний URL: https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json (abie.mdc).
+
+Повертає null у разі успішної валідації.
+
+## Публічний API
+
+ABIE_HC_SCHEMA_URL — Зберігає референтний URL `$schema` для файлу `hc.yaml` (abie.mdc).
+
+validateAbieHcModeline — Перевіряє формат modeline (`# yaml-language-server: $schema=...`) у файлі `hc.yaml`.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Не звертається до мережі.

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

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: http-route.mjs
+resource: npm/rules/abie/lib/http-route.mjs
+docgen:
+  crc: c3626280
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл здійснює крос-документну аналітику HTTPRoute, використовуючи `ABIE_SHARED_CROSS_NS_BACKEND_NAMES` та `analyzeAbieSharedBackendRefsInPackageK8s`. Він підраховує кількість посилань на спільні сервіси (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета, ігноруючи overlay `ua`. Мета полягає у синхронізації числа `patch`-ів namespace в overlay з кількістю base-reference, що гарантує узгодженість конфігурації (abie.mdc).
+
+## Поведінка
+
+Поведінка:
+ABIE_SHARED_CROSS_NS_BACKEND_NAMES: Надає список назв спільних сервісів (`auth-run-hl`, `file-link-hl`), до яких здійснюється аналіз.
+analyzeAbieSharedBackendRefsInPackageK8s: Підраховує кількість посилань на спільні сервіси (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета, що знаходяться поза overlay `ua`, і виявляє порушення вимог конфігурації, використовуючи маркер (abie.mdc).
+
+## Публічний API
+
+ABIE_SHARED_CROSS_NS_BACKEND_NAMES — Список імен бекендів, які знаходяться в загальному просторі імен (cross-namespace) для спільного використання.
+analyzeAbieSharedBackendRefsInPackageK8s — Підраховує у YAML-файлах пакета (за винятком overlay ua) кількість посилань на shared-hl backendRefs та виявляє базові помилки (за винятком namespace: dev).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,18 @@
+---
+type: Directory Index
+title: npm/rules/abie/lib
+resource: npm/rules/abie/lib/
+---
+
+# npm/rules/abie/lib
+
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [enabled.mjs](enabled.md)                             | JS Module |
+| [env-dns.mjs](env-dns.md)                             | JS Module |
+| [hc-yaml.mjs](hc-yaml.md)                             | JS Module |
+| [http-route.mjs](http-route.md)                       | JS Module |
+| [k8s-tree.mjs](k8s-tree.md)                           | JS Module |
+| [kustomization-patches.mjs](kustomization-patches.md) | JS Module |
+| [overlay-paths.mjs](overlay-paths.md)                 | JS Module |
+| [yaml.mjs](yaml.md)                                   | JS Module |

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

@@ -0,0 +1,44 @@
+---
+type: JS Module
+title: k8s-tree.mjs
+resource: npm/rules/abie/lib/k8s-tree.mjs
+docgen:
+  crc: d8a34507
+---
+
+Модуль обходить дерево репозиторію й постачає правилу `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 про них просто мовчиться.
+- Кеш діє в межах життя процесу й не має інвалідації: у межах одного прогону файлова система вважається незмінною, а між прогонами процес стартує заново.