@nitra/cursor 1.9.0 → 1.9.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.9.1] - 2026-05-11
+
+### Added
+
+- **rego `k8s.base_kustomization` — defense-in-depth deny на HPA/PDB у `base/kustomization.yaml::resources:`:** додано пер-документне правило, що відмовляє, якщо `resources:` локально містить запис із basename `hpa.yaml`/`pdb.yaml`/`hpa.yml`/`pdb.yml` (у будь-якому підкаталозі). Канон k8s.mdc — HPA/PDB у sibling `components/` (Kustomize Component) і підключаються з overlay. Рекурсивний обхід дерева `resources:`/`components:`/`bases:` (із зануренням у вкладені kustomization.yaml) лишається у JS-оркестраторі `verifyK8sBaseKustomizeHasNoHpaPdb` (потребує fs-доступу). Rego-deny ловить найпоширеніший локальний випадок навіть якщо JS-крок упаде з винятку раніше. 5 нових rego-тестів (`hpa.yaml`/`pdb.yaml`/`hpa.yml` у `resources:`, чистий `resources:`, lookalike basename `myhpa.yaml`); `opa test` зелений (10/10).
+
+### Fixed
+
+- **`check-k8s.mjs`:** додано константу `GATEWAY_API_GROUP_PREFIX = 'gateway.networking.k8s.io/'`. Її відсутність кидала `ReferenceError` у `indexOneK8sYamlForHasuraCanon` (на лінії з `av.startsWith(GATEWAY_API_GROUP_PREFIX)`), яку ловив outer try/catch у `bin/n-cursor.js` і **тихо пропускав** усі наступні JS-валідатори в `check-k8s.mjs::check()` — серед них `validateKustomizeHpaPdbOnlyWithBaseDeployment`, `validateConfigMapNameMatchesDeployment`, `validateDeploymentHpaPdbAndTopology`, `validateProdKustomizationOverrides`. Наслідок у репах споживачів: правило «HPA/PDB заборонені у `k8s/base/`» не спрацьовувало (хоча `verifyK8sBaseKustomizeHasNoHpaPdb` логіку містив правильну), бо exception вилітав раніше за чергу JS-кроків. Rego-крок (`runAllK8sRego`) ішов **до** crash-точки й тому продовжував працювати — пер-документні перевірки залишалися активними, а cross-file JS — ні.
+
 ## [1.9.0] - 2026-05-11
 
 ### Changed

package/mdc/ci4.mdc

@@ -15,6 +15,54 @@ C4-діаграми проєкту живуть у Markdown поряд із ко
 тримати знання разом із кодом — версійно, в одному PR і доступно для агентів. Якщо щось
 важливе про систему існує лише у Confluence/Notion/месенджері — для проєкту цього **немає**.
 
+## Специфікація як джерело істини (Spec-as-Source)
+
+У AI-native розробці первинним артефактом, який підтримують інженери, є **специфікація**, а не
+кодова база. Код — похідний артефакт, «будівельне риштування», яке агент генерує, верифікує або
+повністю відновлює зі специфікації. Якщо поведінка системи має змінитися — **спочатку оновлюємо
+специфікацію (C4/ADR/опис компонента), і лише потім** агент генерує відповідний код. Зворотний
+порядок («код вже написаний, доку напишемо потім») перетворює специфікацію на декорацію.
+
+## Тест на повне відтворення (Rebuild Test)
+
+Документація вважається повною лише тоді, коли проходить бінарний тест: якщо видалити теку
+`src/`, відкрити нову LLM-сесію з чистим контекстом і дати агенту доступ лише до `.md`-файлів —
+агент має **відтворити робочу кодову базу**. Архітектурні збої (агент не знає структуру тек),
+інтеграційні (неописані міжсервісні контракти), падіння юніт-тестів (неописана бізнес-логіка) —
+це не «складність задачі», а **прогалини документації**, які треба заповнити у тому ж PR.
+
+## Ефективність токенів і чистий Markdown
+
+Вікно контексту LLM обмежене, а якість міркування деградує в міру його заповнення (ефект
+«Lost in the Middle»). Тому документація **очищається від HTML-розмітки, CSS-класів,
+навігаційних обгорток** і всього, що не несе семантичного навантаження. Чистий Markdown замість
+HTML економить 80–90 % токенів (≈16 000 → 1 600 на сторінку), що прямо впливає на точність
+згенерованого коду і знижує вартість API. Жодних `<div>`/`<span>`/класів у тілі `.md`/`.mdc`.
+
+## Контекстна незалежність розділів
+
+RAG витягує **фрагменти**, не цілі документи. Тому кожен розділ має сенс **без сусіднього
+тексту**. Заборонено: «як було згадано вище», «ця змінна», «попередній метод», «той самий
+сервіс». Замість цього — щоразу явно повторюємо назву сутності: «автентифікація OAuth 2.0»,
+«функція `calculateTotal()`», «контейнер `api-gateway`». Коли агент отримає лише цей фрагмент,
+у нього має бути повний словник для коректної генерації.
+
+## Docs-as-Code
+
+Документація живе у Git поруч із кодом, проходить **той самий Code Review**, версіонується і
+автоматично перевіряється у CI (лінтери Markdown, валідатори посилань, `npx @nitra/cursor
+check`). Биті посилання й документація, що «не компілюється», — **блокуючий баг**, не
+косметика. Це продовження принципу «оновлення синхронно зі змінами» нижче: один PR — код +
+схема + ADR + тести.
+
+## Трасування як документація недетермінованої поведінки
+
+Для компонентів, де рішення приймає нейромережа або складна евристика, класичної форми
+«вхід X → вихід Y» **недостатньо** — поведінка недетермінована. Джерелом істини стає
+**пайплайн логування й трасування**: які інструменти використав агент, який контекст мав,
+чому ухвалив це рішення. У C4-компоненті такого типу — посилання на дашборд/storage трасувань
+обов'язкове нарівні з посиланнями на тести.
+
 ## Розташування
 
 C4-діаграми проєкту живуть у теці `docs/ci4/` — це **канонічне місце** для всіх рівнів

package/package.json

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

package/policy/k8s/base_kustomization/base_kustomization.rego

@@ -34,7 +34,37 @@ deny contains base_namespace_required_msg if {
 	trim_space(ns) == ""
 }
 
+# HPA/PDB у base заборонені — канон k8s.mdc: тримати у sibling каталозі `components/`
+# і підключати з overlay (`components: [- ../components]`). Цей deny — швидкий gate
+# на *локальний* `resources:` base/kustomization.yaml (точне ім'я `hpa.yaml`/`pdb.yaml`,
+# у будь-якому підкаталозі). Рекурсивний обхід `resources:`/`components:`/`bases:`
+# (із зануренням у вкладені kustomization.yaml) — JS-оркестратор
+# `verifyK8sBaseKustomizeHasNoHpaPdb` у `check-k8s.mjs` (потребує fs-доступу). Цей
+# rego-deny — defense-in-depth: спрацює навіть якщо JS-крок упаде з винятку раніше.
+deny contains hpa_pdb_in_base_resources_msg(r) if {
+	is_kustomization
+	some r in object.get(input, "resources", [])
+	is_string(r)
+	is_hpa_or_pdb_filename(r)
+}
+
+hpa_pdb_in_base_resources_msg(file) := sprintf(
+	concat("", [
+		"у base/kustomization.yaml `resources:` містить '%v' — HPA/PDB заборонені у base, ",
+		"перенесіть у sibling каталог components/ і підключайте з overlay (k8s.mdc)",
+	]),
+	[file],
+)
+
 is_kustomization if {
 	input.kind == "Kustomization"
 	startswith(object.get(input, "apiVersion", ""), "kustomize.config.k8s.io/")
 }
+
+is_hpa_or_pdb_filename(p) if {
+	basename(p) in {"hpa.yaml", "pdb.yaml", "hpa.yml", "pdb.yml"}
+}
+
+basename(p) := parts[count(parts) - 1] if {
+	parts := split(p, "/")
+}

package/policy/k8s/base_kustomization/base_kustomization_test.rego

@@ -34,3 +34,40 @@ test_allow_non_kustomization if {
 		"metadata": {"name": "cm"},
 	}
 }
+
+base_kust_ok := object.union(base_kust, {"namespace": "dev"})
+
+test_deny_hpa_yaml_in_resources if {
+	count(base_kustomization.deny) > 0 with input as object.union(
+		base_kust_ok,
+		{"resources": ["deployment.yaml", "hpa.yaml"]},
+	)
+}
+
+test_deny_pdb_yaml_in_resources if {
+	count(base_kustomization.deny) > 0 with input as object.union(
+		base_kust_ok,
+		{"resources": ["pdb.yaml"]},
+	)
+}
+
+test_deny_hpa_yml_in_subdir if {
+	count(base_kustomization.deny) > 0 with input as object.union(
+		base_kust_ok,
+		{"resources": ["nested/dir/hpa.yml"]},
+	)
+}
+
+test_allow_resources_without_hpa_pdb if {
+	count(base_kustomization.deny) == 0 with input as object.union(
+		base_kust_ok,
+		{"resources": ["deployment.yaml", "service.yaml", "configmap.yaml"]},
+	)
+}
+
+test_allow_lookalike_basename if {
+	count(base_kustomization.deny) == 0 with input as object.union(
+		base_kust_ok,
+		{"resources": ["myhpa.yaml", "pdb-extra.yaml"]},
+	)
+}

package/scripts/check-k8s.mjs

@@ -309,6 +309,8 @@ const YANNH_GROUPS = new Set([
   'storagemigration.k8s.io'
 ])
 
+const GATEWAY_API_GROUP_PREFIX = 'gateway.networking.k8s.io/'
+
 const MODELINE_RE = /^#\s*yaml-language-server:\s*\$schema=(\S+)\s*$/
 const PATH_SPLIT_RE = /[/\\]/u
 const YAML_EXTENSION_RE = /\.ya?ml$/iu