@nitra/cursor 1.11.3 → 1.11.6

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.11.6] - 2026-05-15
+
+### Changed
+
+- **`npm/rules/npm-module/npm-module.mdc`** — переформульовано вимогу про тести й фікстури. Раніше правило вимагало тримати їх **поза** будь-яким шляхом з `"files"` (канонічно — у `npm/tests/`). Тепер тести/фікстури можуть лежати **поруч з кодом** усередині `"files"`-шляхів, але `"files"` обовʼязково має містити **негативні glob-патерни**, що виключають їх із tarball (`!**/*.test.*`, `!**/*.spec.*`, `!**/test-helpers.*`, `!**/fixtures/**`, `!**/__tests__/**`, опційно `!**/*_test.rego`). Це краще відповідає реальному layout пакета (co-located test-файли у `rules/<id>/js/<concern>/`) і прибирає роз'їзд правила з фактичним `npm/package.json`. Версію `.mdc` піднято до `1.12`.
+- **`npm/rules/npm-module/js/package_structure/check.mjs::checkNoTestsInPublishedFiles`** — текст fail-повідомлення тепер однозначно радить додати негативний glob у `"files"`, без альтернативи «винеси за межі шляхів з "files"». Логіка перевірки (walk positive ∖ negative + класифікація test-style) не змінилась — пере-кваліфіковано лише підказку для агента й людини.
+
+## [1.11.5] - 2026-05-15
+
+### Added
+
+- **`npm/bin/n-cursor.js`** — підкоманди `lint-rego`, `lint-k8s`, `lint-docker`, `lint-text` (раніше був лише `lint-ga`). Споживчі `package.json` тепер можуть використовувати уніфіковану форму `n-cursor lint-X` замість прямих посилань на файли `bun ./npm/scripts/*.mjs`, які після phase 2 концерн-сплету переїхали у `npm/rules/<id>/js/`. `lint-text` — композитний: послідовно `cspell .` → `runShellcheckText()` → `bunx markdownlint-cli2 --fix "**/*.md" "**/*.mdc"` → `runV8rWithGlobs()`.
+- **`npm/rules/text/js/lint.mjs`** — новий ентрі-модуль для канонічного `lint-text`.
+- **`npm/scripts/utils/run-lint-step.mjs`** — спільний хелпер `runLintStep(title, cmd, args)` для CLI-обгорток `lint-<rule>` (раніше дублювалося у `rules/ga/js/lint.mjs` і новому `rules/text/js/lint.mjs` — jscpd-clone).
+
+### Changed
+
+- **`npm/rules/k8s/js/run.mjs`**, **`npm/rules/docker/js/run.mjs`** — `main()` перейменовано і експортовано як `runLintK8s` / `runLintDocker` для виклику з CLI-маршрутизатора. `isRunAsCli()`-гілка прямого запуску збережена для зворотної сумісності.
+- **`npm/rules/rego/js/lint.mjs`** — авто-виклик `runLintRego()` тепер обгорнуто `if (isRunAsCli())`, інакше імпорт модуля з CLI запускав би лінт як side-effect.
+- **`npm/rules/rego/policy/package_json/`** — канонічне значення `scripts.lint-rego` змінено на `"n-cursor lint-rego"` (раніше `"bun ./npm/scripts/lint-rego.mjs"`). Аналогічно `npm/rules/docker/policy/package_json/` — на `"n-cursor lint-docker"`.
+- **`npm/rules/text/js/formatting/check.mjs`** — `checkLintTextScript()` тепер вимагає рівно `"n-cursor lint-text"` замість попередньої складної валідації багатоступеневого ланцюжка (`cspell` → `run-shellcheck-text.mjs` → `markdownlint-cli2` → `run-v8r.mjs`). Канонічна форма — одне посилання на CLI, а зміст ланцюжка живе у `npm/rules/text/js/lint.mjs`.
+- **`npm/package.json#files`** — додано негативний glob `"!**/*_test.rego"` (раніше були лише `*.test.mjs`, `test-helpers.mjs`, `fixtures/**`). 33 rego-юніт-тестових файли (`<policy>_test.rego`) більше не потрапляють у tarball — їх виконує лише `conftest verify` у dev-репо.
+
+## [1.11.4] - 2026-05-15
+
+### Fixed
+
+- **`npm/rules/nginx-default-tpl/js/template/check.mjs`** — `findDefaultConfTemplatePaths` пропускає тестові `fixtures/` за будь-яким сегментом шляху, не лише `tests/fixtures/`. Після concern-split (фази 1-4) fixtures лежать у `rules/<rule>/js/<concern>/fixtures/`, і старий патерн пропускав їх повз → check шукав Dockerfile поруч із тестовим шаблоном і фалс-фейлив.
+
 ## [1.11.3] - 2026-05-15
 
 ### Fixed
@@ -55,7 +84,7 @@
 - **Інкрементальна міграція правил на `target.json`** (декларативні маніфести поруч із кожним `<concern>.rego`):
   - **Single-file правила** (11): `bun`, `text`, `style-lint`, `php`, `docker`, `npm-module`, `js-lint`, `image-compress`, `capacitor`, `hasura`, `adr` — `target.json` з `single` для кожного канонічного конфіг-файлу. Сумарно 27 нових маніфестів. `bun.bunfig`, `text.cspell`, `npm_module.npm_publish_yml` тощо тепер прогоняються через CLI `check <id>` без додаткового `bun run lint-conftest`.
   - **Walk-glob правила** (6): `js-mssql`, `js-bun-db`, `js-bun-redis`, `js-run` (package_json + configmap), `vue`, `image-avif` — `walkGlob: "**/package.json"` або відповідний патерн.
-  - **k8s.* концерни** (8): `manifest`, `gateway`, `hpa_pdb`, `kustomization`, `svc_yaml`, `svc_hl_yaml`, `base_kustomization`, `base_manifest` — `walkGlob` по YAML під сегментом `k8s/`; `base_manifest` використовує негативний glob для виключення `kustomization.yaml`.
+  - **k8s.\* концерни** (8): `manifest`, `gateway`, `hpa_pdb`, `kustomization`, `svc_yaml`, `svc_hl_yaml`, `base_kustomization`, `base_manifest` — `walkGlob` по YAML під сегментом `k8s/`; `base_manifest` використовує негативний glob для виключення `kustomization.yaml`.
   - **abie концерни** (4): `clean_merged_ignore_branches` (single), `health_check_policy` (walkGlob `**/k8s/**/hc.yaml`), `http_route_base` (walkGlob `**/k8s/**/base/**/hr.yaml`), `base_deployment_preem` (walkGlob `**/k8s/**/base/**/*.{yaml,yml}` з виключенням `kustomization.yaml`).
 - **`capture-decisions.sh` тепер пише чернетки напряму в `docs/adr/<timestamp>-<sid>.md`** (раніше — у `docs/adr/_inbox/`). Сам каталог `_inbox/` більше не створюється, але `normalize-decisions.sh` бачить його рекурсивно — старі чернетки з `_inbox/` поступово розчищаються нормалізацією. Можна також одноразово `git mv docs/adr/_inbox/*.md docs/adr/` і прибрати порожній каталог.
 - **Правило `adr` (`npm/rules/adr/adr.mdc`)**: повне переписування під дві фази (capture + normalize). Видалено згадки `_inbox/`. Версія `version: '2.0'`.
@@ -77,14 +106,14 @@
 
 ### Fixed
 
-- `npm/package.json#files`: додано негативні glob-патерни `!**/*.test.mjs`, `!**/test-helpers.mjs`, `!**/fixtures/**`, щоб після переїзду тестів у `rules/<rule>/js/`, `scripts/`, `scripts/utils/` вони не потрапляли в опубліковану npm-таrball (вимагає правило `npm-module`).
+- `npm/package.json#files`: додано негативні glob-патерни `!**/*.test.mjs`, `!**/test-helpers.mjs`, `!**/fixtures/**`, щоб після переїзду тестів у `rules/<rule>/js/`, `scripts/`, `scripts/utils/` вони не потрапляли в опубліковану npm-tarball (вимагає правило `npm-module`).
 - `npm/package.json#devDependencies`: додано `@nitra/cursor: ^1.9.22` (auto-fill від `ensure-nitra-cursor-dev-dependencies.mjs`).
 
 ## [1.9.22] - 2026-05-14
 
 ### Changed
 
-- **Rule-centric структура пакета.** Кожне правило тепер живе в одній директорії `npm/rules/{rule}/` з усіма своїми артефактами: `{rule}.mdc`, `auto.md` (умова автоактивації), `policy/` (rego-поліси), `js/` (check.mjs + опційні run/lint + co-located *.test.mjs + fixtures/). Видалив каталог правила — правило зникло без слідів у `bin/auto-rules.md`, `npm/policy/`, `npm/scripts/`. Дзеркальна структура для скілів у `npm/skills/{skill}/` (SKILL.md + auto.md + js/).
+- **Rule-centric структура пакета.** Кожне правило тепер живе в одній директорії `npm/rules/{rule}/` з усіма своїми артефактами: `{rule}.mdc`, `auto.md` (умова автоактивації), `policy/` (rego-поліси), `js/` (check.mjs + опційні run/lint + co-located \*.test.mjs + fixtures/). Видалив каталог правила — правило зникло без слідів у `bin/auto-rules.md`, `npm/policy/`, `npm/scripts/`. Дзеркальна структура для скілів у `npm/skills/{skill}/` (SKILL.md + auto.md + js/).
 - **Тести співрозташовуються з джерелами.** ~50 файлів з `npm/tests/` переїхали в `npm/rules/{rule}/js/*.test.mjs` (тести правил), `npm/scripts/*.test.mjs` (тести інфраструктури), `npm/scripts/utils/*.test.mjs` (тести утиліт). `tests/helpers.mjs` → `scripts/utils/test-helpers.mjs`. `npm/tests/` залишається тільки для 3 крос-правильних інтеграційних тестів.
 - **`bin/n-cursor.js`**: `BUNDLED_MDC_DIR` → `BUNDLED_RULES_DIR`. `discoverBundledRuleNames` і `discoverCheckScripts` тепер обходять підкаталоги `rules/` замість файлів у `mdc/` чи `check-*.mjs` у `scripts/`. Резолвер check-скриптів: `rules/{rule}/js/check.mjs`. `readBundledRuleContent` читає `rules/{rule}/{rule}.mdc`.
 - **`scripts/utils/run-conftest-batch.mjs` та `scripts/lint-conftest.mjs`**: шляхи до rego-полісі — `rules/{rule}/policy/{name}/` (замість `policy/{rule}/{name}/`). Snake_case `policyDirRel` у JS-call sites замінено на kebab-case.

package/bin/n-cursor.js

@@ -13,6 +13,12 @@
  *                                     інакше викликає `check`); прописується автоматично в `.claude/settings.json`
  *   `npx \@nitra/cursor lint-ga`     — канонічний lint-ga (ga.mdc): preflight на `shellcheck` →
  *                                     `bunx github-actionlint` → `uvx zizmor --offline --collect=workflows .`
+ *   `npx \@nitra/cursor lint-rego`   — канонічний lint-rego (conftest.mdc + rego.mdc):
+ *                                     preflight на `opa`/`regal` → `opa check --strict` → `regal lint` → опц. `conftest verify`
+ *   `npx \@nitra/cursor lint-k8s`    — канонічний lint-k8s (k8s.mdc): `kubeconform` + `kubescape` по `…/k8s/*.yaml`
+ *   `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)
  *
  * Claude Code інтеграція: під час синку, окрім `.cursor/rules` і `.claude/commands` (з skills), CLI ще раз
  * синхронізує `.claude/settings.json` (hooks + permissions; merge — користувацькі поля зберігаються),
@@ -68,7 +74,11 @@ import { detectAutoSkills } from '../scripts/auto-skills.mjs'
 import { runStopHookCli } from '../scripts/claude-stop-hook.mjs'
 import { discoverCheckableRules } from '../scripts/utils/discover-checkable-rules.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { runLintDocker } from '../rules/docker/js/run.mjs'
 import { runLintGaCli } from '../rules/ga/js/lint.mjs'
+import { runLintK8s } from '../rules/k8s/js/run.mjs'
+import { runLintRego } from '../rules/rego/js/lint.mjs'
+import { runLintTextCli } from '../rules/text/js/lint.mjs'
 import { runRule } from '../scripts/utils/run-rule.mjs'
 import { syncClaudeConfig } from '../scripts/sync-claude-config.mjs'
 import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
@@ -88,7 +98,6 @@ const RULE_PREFIX = 'n-'
 
 const binDir = dirname(fileURLToPath(import.meta.url))
 const BUNDLED_RULES_DIR = join(binDir, '..', 'rules')
-const BUNDLED_SCRIPTS_DIR = join(binDir, '..', 'scripts')
 const BUNDLED_SKILLS_DIR = join(binDir, '..', 'skills')
 const BUNDLED_AGENTS_TEMPLATE_PATH = join(binDir, '..', AGENTS_TEMPLATE_FILE)
 /** Корінь установленого пакету (каталог з `rules/`, `github-actions/`, …) */
@@ -266,8 +275,9 @@ async function readConfig(paths = {}) {
     // правило, додане вручну (напр. `adr` без auto.md-умови), не активувало б залежні
     // скіли (`adr-normalize`).
     const disableRulesSet = new Set(disableRules)
-    const effectiveRulesForSkills = [...new Set([...normalizeIdList(parsedConfig.rules), ...autoDetectedRules.rules])]
-      .filter(id => !disableRulesSet.has(id))
+    const effectiveRulesForSkills = [
+      ...new Set([...normalizeIdList(parsedConfig.rules), ...autoDetectedRules.rules])
+    ].filter(id => !disableRulesSet.has(id))
     const autoDetectedSkills = detectAutoSkills({
       availableSkills,
       detectedRules: effectiveRulesForSkills,
@@ -999,9 +1009,9 @@ function logRemovedManagedItems(title, basePath, names) {
  * (плюс legacy `rules/<id>/js/check.mjs` як концерн `legacy`) або policy-концерн у
  * `rules/<id>/policy/<concern>/target.json`. Делегує у `discoverCheckableRules` —
  * див. `scripts/utils/discover-checkable-rules.mjs`.
- * @returns {Promise<import('../scripts/utils/discover-checkable-rules.mjs').CheckableRule[]>} опис правил у алфавітному порядку
+ * @returns {import('../scripts/utils/discover-checkable-rules.mjs').CheckableRule[]} опис правил у алфавітному порядку
  */
-async function discoverCheckScripts() {
+function discoverCheckScripts() {
   return discoverCheckableRules(BUNDLED_RULES_DIR)
 }
 
@@ -1347,6 +1357,30 @@ try {
 
       break
     }
+    case 'lint-rego': {
+      // Канонічний lint-rego: preflight opa/regal → opa check --strict → regal lint → conftest verify (опц.).
+      process.exitCode = runLintRego()
+
+      break
+    }
+    case 'lint-k8s': {
+      // Канонічний lint-k8s: kubeconform + kubescape по знайдених деревах `…/k8s/*.yaml`.
+      process.exitCode = await runLintK8s()
+
+      break
+    }
+    case 'lint-docker': {
+      // Канонічний lint-docker: hadolint по Dockerfile та *.Dockerfile (docker.mdc).
+      process.exitCode = await runLintDocker()
+
+      break
+    }
+    case 'lint-text': {
+      // Канонічний lint-text: cspell → run-shellcheck → markdownlint-cli2 --fix → run-v8r (text.mdc).
+      process.exitCode = runLintTextCli()
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1356,7 +1390,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, stop-hook, lint-ga`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, stop-hook, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.11.3",
+  "version": "1.11.6",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -34,6 +34,7 @@
     "AGENTS.template.md",
     "CHANGELOG.md",
     "!**/*.test.mjs",
+    "!**/*_test.rego",
     "!**/test-helpers.mjs",
     "!**/fixtures/**"
   ],

package/rules/abie/js/applies/check.mjs

@@ -8,16 +8,16 @@ import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mj
 import { isAbieRuleEnabled } from '../../utils/enabled.mjs'
 
 /**
- * @returns {Promise<boolean>}
+ * @returns {Promise<boolean>} `true` — правило застосовне; `false` — пропустити
  */
-export async function applies() {
+export function applies() {
   return isAbieRuleEnabled(process.cwd())
 }
 
 /**
- * @returns {Promise<number>}
+ * @returns {number} exit-код (0 — OK, 1 — порушення)
  */
-export async function check() {
+export function check() {
   const reporter = createCheckReporter()
   reporter.pass('Правило abie увімкнено — виконуємо перевірки')
   return reporter.getExitCode()

package/rules/abie/js/env_dns/check.mjs

@@ -15,7 +15,7 @@ import { loadCursorIgnorePaths } from '../../../../scripts/utils/load-cursor-con
 import { abieEnvNameFromBasename, collectAbieEnvFiles, validateAbieEnvInternalUrls } from '../../utils/env-dns.mjs'
 
 /**
- * @returns {Promise<number>}
+ * @returns {Promise<number>} результат
  */
 export async function check() {
   const reporter = createCheckReporter()

package/rules/abie/js/firebase_hosting/check.mjs

@@ -12,7 +12,7 @@ import { createCheckReporter } from '../../../../scripts/utils/check-reporter.mj
 const SKIP_TOP_DIR_NAMES = new Set(['.git', 'node_modules'])
 
 /**
- * @returns {Promise<number>}
+ * @returns {Promise<number>} результат
  */
 export async function check() {
   const reporter = createCheckReporter()

package/rules/abie/js/hc_pairing/check.mjs

@@ -17,7 +17,7 @@ import { validateAbieHcModeline } from '../../utils/hc-yaml.mjs'
 import { collectDeploymentDirs, findK8sYamlFiles } from '../../utils/k8s-tree.mjs'
 
 /**
- * @returns {Promise<number>}
+ * @returns {Promise<number>} результат
  */
 export async function check() {
   const reporter = createCheckReporter()
@@ -50,8 +50,8 @@ export async function check() {
       continue
     }
     const modelineErr = validateAbieHcModeline(hcRaw, relHc)
-    if (modelineErr !== null) fail(modelineErr)
-    else pass(`${relHc}: modeline OK`)
+    if (modelineErr === null) pass(`${relHc}: modeline OK`)
+    else fail(modelineErr)
   }
 
   return reporter.getExitCode()

package/rules/abie/js/ua_http_route/check.mjs

@@ -26,7 +26,7 @@ import {
 } from '../../utils/overlay-paths.mjs'
 
 /**
- * @returns {Promise<number>}
+ * @returns {Promise<number>} результат
  */
 export async function check() {
   const reporter = createCheckReporter()
@@ -78,8 +78,8 @@ export async function check() {
     }
     const combined = getCombinedNginxRunPatchTextFromKustomization(raw)
     const v = validateAbieNginxRunHttpRoutePatches(combined, 'ua', raw, sharedAnalysis.refCount)
-    if (v !== null) fail(`${rel}: ${v}`)
-    else pass(`${rel}: HTTPRoute patch (ua) відповідає abie.mdc`)
+    if (v === null) pass(`${rel}: HTTPRoute patch (ua) відповідає abie.mdc`)
+    else fail(`${rel}: ${v}`)
   }
 
   return reporter.getExitCode()

package/rules/abie/js/ua_node_selector/check.mjs

@@ -16,7 +16,7 @@ import { kustomizationHasAbieDeploymentNodeSelectorPatch } from '../../utils/kus
 import { abieOverlayK8sTreeHasDeployment, isUaKustomizationPath } from '../../utils/overlay-paths.mjs'
 
 /**
- * @returns {Promise<number>}
+ * @returns {Promise<number>} результат
  */
 export async function check() {
   const reporter = createCheckReporter()
@@ -55,7 +55,9 @@ export async function check() {
       continue
     }
     if (!kustomizationHasAbieDeploymentNodeSelectorPatch(raw, 'ua')) {
-      fail(`${rel}: потрібен patch target kind Deployment: path /spec/template/spec/nodeSelector та preem: false (abie.mdc)`)
+      fail(
+        `${rel}: потрібен patch target kind Deployment: path /spec/template/spec/nodeSelector та preem: false (abie.mdc)`
+      )
       continue
     }
     pass(`${rel}: nodeSelector patch (ua) відповідає abie.mdc`)

package/rules/abie/policy/base_deployment_preem/target.json

@@ -1,10 +1,6 @@
 {
   "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
   "files": {
-    "walkGlob": [
-      "**/k8s/**/base/**/*.yaml",
-      "**/k8s/**/base/**/*.yml",
-      "!**/k8s/**/base/**/kustomization.yaml"
-    ]
+    "walkGlob": ["**/k8s/**/base/**/*.yaml", "**/k8s/**/base/**/*.yml", "!**/k8s/**/base/**/kustomization.yaml"]
   }
 }

package/rules/abie/utils/enabled.mjs

@@ -12,7 +12,7 @@ const CONFIG_FILE = '.n-cursor.json'
 /**
  * Чи увімкнено правило **abie** у `.n-cursor.json:rules`.
  * @param {string} root корінь репозиторію (cwd)
- * @returns {Promise<boolean>}
+ * @returns {Promise<boolean>} `true` — `rules` містить `abie`; `false` — інакше
  */
 export async function isAbieRuleEnabled(root) {
   const p = join(root, CONFIG_FILE)

package/rules/abie/utils/env-dns.mjs

@@ -23,8 +23,8 @@ const ABIE_ENV_CLUSTER_DNS_MAP = Object.freeze({
 /**
  * Дістає `dev` / `ua` з basename env-файлу abie.
  * Не-abie env-файли (`production.env`, `.env` без імені) → null.
- * @param {string} basenameOfEnvFile
- * @returns {('dev' | 'ua') | null}
+ * @param {string} basenameOfEnvFile опис.
+ * @returns {('dev' | 'ua') | null} результат
  */
 export function abieEnvNameFromBasename(basenameOfEnvFile) {
   const m = basenameOfEnvFile.match(ABIE_ENV_FILE_BASENAME_RE)
@@ -35,7 +35,7 @@ export function abieEnvNameFromBasename(basenameOfEnvFile) {
  * Сканує вміст env-файла, повертає помилки невідповідності кластерного DNS / namespace
  * для кожного internal URL (один URL у двох змінних = дві окремі помилки).
  * @param {string} content вміст env-файла (UTF-8)
- * @param {'dev' | 'ua'} envName
+ * @param {'dev' | 'ua'} envName опис.
  * @returns {string[]} порожній масив, якщо все OK
  */
 export function validateAbieEnvInternalUrls(content, envName) {
@@ -63,7 +63,7 @@ export function validateAbieEnvInternalUrls(content, envName) {
  * Збирає `*.env` файли, які є abie env (`dev.env`/`ua.env`, опц. з провідною крапкою).
  * @param {string} root корінь репозиторію
  * @param {string[]} ignorePaths абсолютні шляхи каталогів-виключень
- * @returns {Promise<string[]>}
+ * @returns {Promise<string[]>} результат
  */
 export async function collectAbieEnvFiles(root, ignorePaths) {
   /** @type {string[]} */

package/rules/abie/utils/http-route.mjs

@@ -2,7 +2,7 @@
  * Cross-документна аналітика abie HTTPRoute: підрахунок `backendRefs` до спільних
  * сервісів (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета (поза overlay `ua`).
  * Використовується ua_http_route-концерном для синхронізації числа patch-ів namespace
- * у overlay із кількістю base-referencе.
+ * у overlay із кількістю base-reference.
  */
 import { relative } from 'node:path'
 
@@ -14,7 +14,7 @@ const ABIE_SHARED_CROSS_NS_BACKEND_SET = new Set(ABIE_SHARED_CROSS_NS_BACKEND_NA
 
 /**
  * Перевіряє один `backendRef`: якщо це спільний `-hl` сервіс, має бути `namespace: dev`.
- * @param {unknown} br
+ * @param {unknown} br опис.
  * @param {string} rel rel-шлях файла
  * @param {string[]} errors мутабельний список помилок
  * @returns {number} 1 — це shared backend, 0 — інакше
@@ -33,8 +33,8 @@ function checkSharedBackendRef(br, rel, errors) {
 /**
  * Збирає по HTTPRoute-документу кількість посилань на shared backends і порушення namespace.
  * @param {unknown} obj корінь YAML
- * @param {string} rel
- * @returns {{ refCount: number, errors: string[] }}
+ * @param {string} rel опис.
+ * @returns {{ refCount: number, errors: string[] }} статистика shared-backend посилань і порушення namespace
  */
 function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
   /** @type {string[]} */
@@ -66,7 +66,7 @@ function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
  * @param {string} root корінь репозиторію
  * @param {string} pkgAbs абсолютний шлях каталогу пакета
  * @param {string[]} yamlFilesAbs усі yaml під k8s
- * @returns {Promise<{ refCount: number, baseErrors: string[] }>}
+ * @returns {Promise<{ refCount: number, baseErrors: string[] }>} агрегована статистика й помилки base-шару
  */
 export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yamlFilesAbs) {
   const pkgRel = relative(root, pkgAbs).replaceAll('\\', '/') || pkgAbs

package/rules/abie/utils/k8s-tree.mjs

@@ -5,7 +5,6 @@
  *
  * Кеш — module-level singleton, ключований за `(root, ignorePaths)`. Перший виклик
  * платить за обхід; наступні концерни в межах того ж прогону отримують готове.
- * Для тестів — `resetAbieK8sTreeCache()` (інакше withTmpCwd-фікстури злипатимуться).
  */
 import { dirname, relative } from 'node:path'
 
@@ -20,20 +19,11 @@ const yamlCache = new Map()
 /** @type {Map<string, Promise<Set<string>>>} */
 const deploymentCache = new Map()
 
-/**
- * Скидає кеш — тести мусять викликати між фікстурами.
- * @returns {void}
- */
-export function resetAbieK8sTreeCache() {
-  yamlCache.clear()
-  deploymentCache.clear()
-}
-
 /**
  * Стабільний ключ кешу за (root, ignorePaths).
- * @param {string} root
- * @param {string[]} ignorePaths
- * @returns {string}
+ * @param {string} root опис.
+ * @param {string[]} ignorePaths опис.
+ * @returns {string} результат
  */
 function cacheKey(root, ignorePaths) {
   return `${root}|${[...ignorePaths].toSorted((a, b) => a.localeCompare(b)).join(':')}`
@@ -44,7 +34,7 @@ function cacheKey(root, ignorePaths) {
  * Каталог `.github/` свідомо пропускається (належить `ga.mdc`).
  * @param {string} root корінь репозиторію
  * @param {string[]} [ignorePaths] абсолютні шляхи каталогів-виключень
- * @returns {Promise<string[]>}
+ * @returns {Promise<string[]>} результат
  */
 export function findK8sYamlFiles(root, ignorePaths = []) {
   const key = cacheKey(root, ignorePaths)
@@ -77,7 +67,25 @@ export function findK8sYamlFiles(root, ignorePaths = []) {
  * @param {(msg: string) => void} [fail] репортер помилок парсингу (опц.)
  * @returns {Promise<Set<string>>} абсолютні шляхи директорій
  */
-export function collectDeploymentDirs(root, yamlAbs, fail = () => {}) {
+/**
+ * No-op fail-handler за замовчуванням для `collectDeploymentDirs` — пошкоджені YAML
+ * під час cross-rule сканування мовчки пропускаються; формальний reporter передає сам caller.
+ * @param {string} _msg повідомлення про помилку (ігнорується)
+ */
+const silentFail = _msg => {
+  // noop
+}
+
+/**
+ * Знаходить унікальні каталоги, що містять Deployment-маніфести серед переданих YAML-файлів.
+ * Парсить документи через `readAndParseYamlDocs` і фільтрує лише ті, що є Deployment.
+ * Кешує результат за ключем `root|<sorted yamlAbs>`, щоб повторні виклики не робили I/O.
+ * @param {string} root абсолютний корінь репо для побудови relative-шляхів у повідомленнях
+ * @param {string[]} yamlAbs абсолютні шляхи до YAML-файлів для перевірки
+ * @param {(msg: string) => void} [fail] callback на помилку парсингу (за замовчуванням noop)
+ * @returns {Promise<Set<string>>} проміс із сетом абсолютних каталогів, де знайдено Deployment
+ */
+export function collectDeploymentDirs(root, yamlAbs, fail = silentFail) {
   const key = `${root}|${[...yamlAbs].toSorted((a, b) => a.localeCompare(b)).join(':')}`
   const cached = deploymentCache.get(key)
   if (cached) return cached

package/rules/abie/utils/kustomization-patches.mjs

@@ -24,8 +24,8 @@ const ABIE_UA_HTTPROUTE_HOST_MARKERS = ['abie.app', 'vybeerai.com.ua', '*.abie.a
 
 /**
  * Чи patch-рядок містить очікуваний ua nodeSelector (preem: false).
- * @param {string} patchText
- * @returns {boolean}
+ * @param {string} patchText опис.
+ * @returns {boolean} результат
  */
 function jsonPatchTextHasUaDeploymentNodeSelector(patchText) {
   if (typeof patchText !== 'string' || patchText.trim() === '') return false
@@ -36,9 +36,9 @@ function jsonPatchTextHasUaDeploymentNodeSelector(patchText) {
 
 /**
  * Чи один елемент `patches` відповідає abie nodeSelector для `mode`.
- * @param {unknown} p
- * @param {'ua'} mode
- * @returns {boolean}
+ * @param {unknown} p опис.
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
  */
 function inlineKustomizationPatchMatchesAbieMode(p, mode) {
   if (p === null || typeof p !== 'object' || Array.isArray(p)) return false
@@ -55,9 +55,9 @@ function inlineKustomizationPatchMatchesAbieMode(p, mode) {
 
 /**
  * Чи документ Kustomization містить відповідний inline patch на Deployment.
- * @param {import('yaml').Document} doc
- * @param {'ua'} mode
- * @returns {boolean}
+ * @param {import('yaml').Document} doc опис.
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
  */
 function kustomizationDocumentHasAbieDeploymentNodeSelectorPatch(doc, mode) {
   if (doc.errors.length > 0) return false
@@ -76,8 +76,8 @@ function kustomizationDocumentHasAbieDeploymentNodeSelectorPatch(doc, mode) {
 /**
  * Чи `kustomization.yaml` містить валідні inline patch для Deployment nodeSelector (ua).
  * @param {string} raw повний текст файла
- * @param {'ua'} mode
- * @returns {boolean}
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
  */
 export function kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode) {
   const body = stripBom(raw)
@@ -100,8 +100,8 @@ export function kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode) {
 // ── HTTPRoute (ua) ────────────────────────────────────────────────────────
 
 /**
- * @param {unknown} p
- * @returns {string | null}
+ * @param {unknown} p опис.
+ * @returns {string | null} результат
  */
 function extractHttpRoutePatchString(p) {
   if (p === null || typeof p !== 'object' || Array.isArray(p)) return null
@@ -116,8 +116,8 @@ function extractHttpRoutePatchString(p) {
 
 /**
  * Збирає inline `patch`-рядки для HTTPRoute (непорожній `target.name`) з одного Kustomization-документа.
- * @param {import('yaml').Document} doc
- * @returns {string[]}
+ * @param {import('yaml').Document} doc опис.
+ * @returns {string[]} результат
  */
 function collectAbieHttpRoutePatchStringsFromKustomizationDoc(doc) {
   if (doc.errors.length > 0) return []
@@ -137,7 +137,7 @@ function collectAbieHttpRoutePatchStringsFromKustomizationDoc(doc) {
 /**
  * Збирає всі inline JSON6902-фрагменти HTTPRoute (непорожній `target.name`) у kustomization.yaml.
  * @param {string} raw повний текст файла
- * @returns {string}
+ * @returns {string} результат
  */
 export function getCombinedNginxRunPatchTextFromKustomization(raw) {
   const body = stripBom(raw)
@@ -162,8 +162,8 @@ export function getCombinedNginxRunPatchTextFromKustomization(raw) {
 /**
  * Рахує операції JSON6902 з `path: /spec/rules/.../backendRefs/.../namespace` і `value: ua[-…]`.
  * @param {string} combined сукупний текст patch
- * @param {'ua'} mode
- * @returns {number}
+ * @param {'ua'} mode опис.
+ * @returns {number} результат
  */
 function countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode) {
   if (mode !== 'ua') return 0
@@ -175,7 +175,7 @@ function countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode)
 /**
  * Перевіряє сукупний текст patch(ів) HTTPRoute на відповідність abie.mdc.
  * @param {string} combined сукупний текст patch
- * @param {'ua'} mode
+ * @param {'ua'} mode опис.
  * @param {string} [_fullKustomizationRaw] зберігається для API-сумісності, не використовується
  * @param {number} [sharedCrossNsBackendRefCount] кількість `auth-run-hl`/`file-link-hl` у base HTTPRoute
  * @returns {string | null} повідомлення про помилку або null
@@ -215,8 +215,8 @@ export function validateAbieNginxRunHttpRoutePatches(
 /**
  * Чи kustomization містить валідні patch для HTTPRoute (ua).
  * @param {string} raw повний текст kustomization.yaml
- * @param {'ua'} mode
- * @returns {boolean}
+ * @param {'ua'} mode опис.
+ * @returns {boolean} результат
  */
 export function kustomizationHasAbieNginxRunHttpRoutePatch(raw, mode) {
   const combined = getCombinedNginxRunPatchTextFromKustomization(raw)

package/rules/abie/utils/overlay-paths.mjs

@@ -16,8 +16,8 @@ const TRAILING_SLASH_RE = /\/$/u
 
 /**
  * Чи `rel` — це `…/ua/kustomization.yaml` (abie overlay).
- * @param {string} rel посі від кореня репозиторію
- * @returns {boolean}
+ * @param {string} rel posix-шлях від кореня репозиторію
+ * @returns {boolean} результат
  */
 export function isUaKustomizationPath(rel) {
   const norm = rel.replaceAll('\\', '/')
@@ -28,7 +28,7 @@ export function isUaKustomizationPath(rel) {
  * Каталог пакета (батько `k8s/`) для overlay `…/k8s/ua/kustomization.yaml`.
  * @param {string} root корінь репозиторію
  * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
- * @returns {string | null}
+ * @returns {string | null} результат
  */
 export function abiePackageDirFromK8sOverlay(root, kustomizationAbs) {
   const rel = relative(root, kustomizationAbs).replaceAll('\\', '/') || kustomizationAbs
@@ -41,7 +41,7 @@ export function abiePackageDirFromK8sOverlay(root, kustomizationAbs) {
  * застосовується лише до Vite-пакетів.
  * @param {string} root корінь репозиторію
  * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
- * @returns {boolean}
+ * @returns {boolean} результат
  */
 export function abieOverlayRequiresHttpRouteByVite(root, kustomizationAbs) {
   const pkg = abiePackageDirFromK8sOverlay(root, kustomizationAbs)
@@ -58,7 +58,7 @@ export function abieOverlayRequiresHttpRouteByVite(root, kustomizationAbs) {
  * @param {Set<string>} deploymentDirs абсолютні каталоги з Deployment
  * @param {string} root корінь репозиторію
  * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
- * @returns {boolean}
+ * @returns {boolean} результат
  */
 export function abieOverlayK8sTreeHasDeployment(deploymentDirs, root, kustomizationAbs) {
   const pkg = abiePackageDirFromK8sOverlay(root, kustomizationAbs)
@@ -73,8 +73,8 @@ export function abieOverlayK8sTreeHasDeployment(deploymentDirs, root, kustomizat
 
 /**
  * Чи rel-шлях `…/k8s/base/…` (base-шар abie, не overlay).
- * @param {string} rel
- * @returns {boolean}
+ * @param {string} rel опис.
+ * @returns {boolean} результат
  */
 export function isAbieK8sBaseYamlPath(rel) {
   const norm = rel.replaceAll('\\', '/')
@@ -85,7 +85,7 @@ export function isAbieK8sBaseYamlPath(rel) {
  * Чи yaml належить до `<pkgRel>/k8s/**` поза `ua/` піддеревом (base-шар abie).
  * @param {string} relFromRoot шлях від кореня
  * @param {string} pkgRelFromRoot каталог пакета від кореня
- * @returns {boolean}
+ * @returns {boolean} результат
  */
 export function isK8sYamlInAbiePackageExcludingUaOverlay(relFromRoot, pkgRelFromRoot) {
   const normRel = relFromRoot.replaceAll('\\', '/')

package/rules/abie/utils/yaml.mjs

@@ -12,7 +12,7 @@ export const LINE_SPLIT_RE = /\r?\n/u
 /**
  * Прибирає BOM на початку файлу.
  * @param {string} s вміст
- * @returns {string}
+ * @returns {string} результат
  */
 export function stripBom(s) {
   return s.startsWith('') ? s.slice(1) : s
@@ -21,7 +21,7 @@ export function stripBom(s) {
 /**
  * Чи YAML-документ — це `kind: Deployment`.
  * @param {unknown} obj корінь YAML-документа
- * @returns {boolean}
+ * @returns {boolean} результат
  */
 export function isDeploymentDoc(obj) {
   return (
@@ -46,8 +46,8 @@ export const silentFail = _msg => {
  * викликає `failFn` і повертає `null`.
  * @param {string} abs абсолютний шлях
  * @param {string} rel відносний (для повідомлень)
- * @param {(msg: string) => void} failFn
- * @returns {Promise<import('yaml').Document[] | null>}
+ * @param {(msg: string) => void} failFn опис.
+ * @returns {Promise<import('yaml').Document[] | null>} результат
  */
 export async function readAndParseYamlDocs(abs, rel, failFn) {
   let raw