@nitra/cursor 1.9.0 → 1.9.2

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.9.2] - 2026-05-11
+
+### Changed
+
+- **k8s — modeline `$schema` тепер опційний; `file:…` заборонено як заглушку:** правило `k8s.mdc` уточнено — рядок `# yaml-language-server: $schema=…` обов'язковий **лише** коли для поєднання `apiVersion`/`kind` існує надійна публічна схема (kustomization / yannh / datree CRDs-catalog). Якщо публічної схеми немає, modeline **не додається зовсім** (раніше п. 5 розділу «Визначення схеми YAML» допускав `file:` за узгодженням — це створювало фальшиву видимість валідації, а автовиправлення n-fix залишало заглушковий `# yaml-language-server: $schema=file:.`). У `check-k8s.mjs`: (1) файли без modeline більше не падають як «перший рядок має бути коментарем», натомість `pass` із позначкою «без modeline — перевірка $schema пропущена»; (2) `$schema=file:…` тепер реєструється як помилка з підказкою прибрати modeline; (3) modeline нижче першого рядка все ще порушення; (4) `HttpBackendGroup` (Yandex ALB) як виняток без modeline залишається без змін. `lint-k8s` (kubeconform з прапорцем ignore-missing-schemas) продовжує покривати валідацію і для файлів без modeline. JSDoc на початку `check-k8s.mjs` оновлено.
+
+## [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/mdc/k8s.mdc

@@ -1,13 +1,13 @@
 ---
 description: K8s YAML — $schema (yaml-language-server); lint-k8s (kubeconform, kubescape); check-k8s
-version: '1.27'
+version: '1.28'
 globs: "**/k8s/**/*.yaml"
 alwaysApply: false
 ---
 
 # Kubernetes YAML у шляхах з `k8s`
 
-Для кожного файлу `*.yaml`, у шляху якого є сегмент директорії **`k8s`** (наприклад `site/k8s/base/deployment.yaml`), **перший рядок** — коментар-директива для [YAML Language Server](https://github.com/redhat-developer/yaml-language-server):
+Для кожного файлу `*.yaml`, у шляху якого є сегмент директорії **`k8s`** (наприклад `site/k8s/base/deployment.yaml`), якщо існує **публічна** схема (kustomization / yannh / datree CRDs-catalog — див. «Визначення схеми YAML»), **перший рядок** — коментар-директива для [YAML Language Server](https://github.com/redhat-developer/yaml-language-server) з URL за `https://`:
 
 ```yaml
 # yaml-language-server: $schema=https://...
@@ -15,7 +15,9 @@ alwaysApply: false
 
 Далі — вміст маніфесту. Зайвий порожній рядок між коментарем і YAML не додавай, якщо в проєкті не прийнято інше.
 
-**Виняток — без modeline:** `apiVersion: alb.yc.io/v1alpha1`, `kind: HttpBackendGroup` (Yandex ALB) — рядка **`# yaml-language-server: $schema=…`** у файлі **не** має бути (ні в першому рядку, ні далі). Перший рядок — одразу YAML (`apiVersion:` тощо). Перевірка — **`check-k8s.mjs`**.
+**Modeline — опційний:** якщо для конкретного поєднання `apiVersion`/`kind` **немає** надійної публічної схеми (yannh/datree/schemastore не покривають), залиш файл **без** рядка `# yaml-language-server: $schema=…`. **Заборонено** ставити `$schema=file:…` як заглушку — це створює видимість валідації без неї. Без modeline `check-k8s` не валідує URL, але **`lint-k8s`** (kubeconform/kubescape) продовжить роботу. Якщо modeline присутній — він обов'язково перший рядок і **тільки** `https://` URL, який відповідає очікуваному за `apiVersion`/`kind`.
+
+**Виняток — modeline заборонено:** `apiVersion: alb.yc.io/v1alpha1`, `kind: HttpBackendGroup` (Yandex ALB) — рядка **`# yaml-language-server: $schema=…`** у файлі **не** має бути (ні в першому рядку, ні далі). Перший рядок — одразу YAML (`apiVersion:` тощо). Перевірка — **`check-k8s.mjs`**.
 
 **Розширення:** усі маніфести під **`k8s`**, включно з **`kustomization.yaml`**, — лише **`.yaml`** (розширення **`.yml`** не використовуй).
 
@@ -695,7 +697,7 @@ patch: |-
    # yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
    ```
 
-5. **Немає надійного публічного URL** — не вигадуй: залиш коректний `$schema` або `file:` за узгодженням.
+5. **Немає надійного публічного URL** — не вигадуй URL і **не** використовуй `$schema=file:…` як заглушку (фальшива валідація). Залиш файл **без** рядка `# yaml-language-server: $schema=…` зовсім — `check-k8s` пропустить перевірку URL для таких файлів, а `lint-k8s` (kubeconform з `-ignore-missing-schemas`) усе ще покриє валідацію.
 
 ## Багатодокументні YAML
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "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

@@ -1,11 +1,16 @@
 /**
  * Перевіряє Kubernetes YAML у шляхах з сегментом `k8s` (див. k8s.mdc).
  *
- * Перший рядок `# yaml-language-server: $schema=…`, без дублікатів, розширення `.yaml`
+ * Перший рядок `# yaml-language-server: $schema=…` (URL за `https://`), без дублікатів, розширення `.yaml`
  * (окрім `kustomization.yaml`); URL схеми за першим документом — kustomization / yannh / datree
  * (**виняток:** `apiVersion: alb.yc.io/v1alpha1`, `kind: HttpBackendGroup` — рядка `# yaml-language-server:` у файлі бути не має).
  * (datree за замовчуванням: GitHub Pages `https://datreeio.github.io/CRDs-catalog/…`).
  *
+ * Modeline **опційний**: якщо публічної схеми немає (yannh/datree/schemastore не покривають це поєднання
+ * apiVersion/kind), залиш файл **без** рядка `# yaml-language-server: $schema=…` — `check-k8s` пропустить
+ * перевірку URL. **Заборонено** ставити `$schema=file:…` як заглушку (це фальшива валідація). Якщо modeline
+ * присутній, він має бути **першим рядком** і містити `https://` URL, що відповідає очікуваному за apiVersion/kind.
+ *
  * Додатково: у кожному YAML-документі з **`kind: Deployment`** у кожного контейнера
  * **`spec.template.spec.containers[]`** має бути **`resources.requests.cpu`** і **`resources.requests.memory`**
  * (непорожні скаляри). У шарі **`…/k8s/…/base/…`** значення жорстко **`cpu: '0.02'`**, **`memory: '128Mi'`**
@@ -309,6 +314,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
@@ -3591,8 +3598,13 @@ function checkK8sYamlFileWithSchemaModeline(abs, rel, baseLower, lines, fail, pa
   // topologySpread, HCP, svc/svc-hl) — делегована rego, виконано у `runAllK8sRego` вище.
 
   if (schemaUrl.startsWith('file:')) {
-    pass(`${rel}: локальна схема (file:) — перевірка URL за apiVersion/kind пропущена`)
-  } else if (HTTPS_SCHEMA_RE.test(schemaUrl)) {
+    fail(
+      `${rel}: $schema=file:… заборонено (фальшива валідація без публічної схеми). ` +
+        `Якщо публічної схеми для цього apiVersion/kind немає — прибери modeline зовсім (k8s.mdc)`
+    )
+    return
+  }
+  if (HTTPS_SCHEMA_RE.test(schemaUrl)) {
     const doc = firstYamlDocument(body)
     const { expected, reason } = expectedSchemaUrl(abs, doc)
 
@@ -3608,7 +3620,9 @@ function checkK8sYamlFileWithSchemaModeline(abs, rel, baseLower, lines, fail, pa
 
     pass(`${rel}: $schema узгоджено (${reason})`)
   } else {
-    fail(`${rel}: $schema має бути https URL або file: (див. k8s.mdc)`)
+    fail(
+      `${rel}: $schema має бути https URL (file: і інші схеми заборонені — якщо публічної схеми немає, прибери modeline; k8s.mdc)`
+    )
   }
 }
 
@@ -3639,12 +3653,7 @@ async function checkK8sYamlFile(abs, root, fail, pass) {
   }
 
   const lines = toLines(raw)
-  if (lines.length === 0 || lines[0].trim() === '') {
-    fail(`${rel}: перший рядок порожній — потрібен # yaml-language-server: $schema=…`)
-    return
-  }
-
-  const firstLineIsModeline = MODELINE_RE.test(lines[0])
+  const firstLineIsModeline = lines.length > 0 && MODELINE_RE.test(lines[0])
   const bodyForFirstDoc = k8sYamlBodyForDocumentParse(lines)
   const isAlbHttpBackendGroup = k8sYamlFirstDocIsAlbYcHttpBackendGroup(bodyForFirstDoc)
 
@@ -3666,7 +3675,16 @@ async function checkK8sYamlFile(abs, root, fail, pass) {
   }
 
   if (!firstLineIsModeline) {
-    fail(`${rel}: перший рядок має бути коментарем # yaml-language-server: $schema=<url> (без префіксів перед #)`)
+    // Modeline опційний: дозволено, якщо публічної схеми для apiVersion/kind немає (k8s.mdc).
+    // Але `# yaml-language-server: $schema=…` дозволено **лише** у першому рядку — якщо він
+    // зустрічається нижче, це порушення (yaml-language-server чекає на нього у заголовку файлу).
+    if (countSchemaModelines(lines) > 0) {
+      fail(
+        `${rel}: рядок # yaml-language-server: $schema=… має бути першим у файлі (без префіксів перед #; k8s.mdc)`
+      )
+      return
+    }
+    pass(`${rel}: без modeline — перевірка $schema пропущена (немає публічної схеми; k8s.mdc)`)
     return
   }