@7n/rules 1.7.0 → 1.7.1

package/rules/js-mssql/mssql-tvp/mssql-tvp.mdc

@@ -0,0 +1,77 @@
+## TVP (table-valued parameters) — рекомендований підхід для списків
+
+TVP дозволений і рекомендований для SQL Server 2019. Для списків значень та пар ключів **найкращий** шлях по безпеці/продуктивності — TVP.
+
+Позитивна практика без прямого AST-check: антипатерн (динамічний список через `.join(...)` у `IN (...)`/`VALUES (...)`) ловить `findUnsafeMssqlDynamicSqlListInText` (`lib/mssql-pool-scan.mjs`, див. `main.mdc`), а сам "правильний" спосіб побудови TVP код не сканує.
+
+### 1) `IN (...)` для кодів → `JOIN` на TVP
+
+Замість складання SQL-рядка:
+
+```javascript
+// ❌ НЕ МОЖНА: динамічний список у SQL
+await pool.request().query`
+  SELECT *
+  FROM promo.SomeTable t
+  WHERE t.ExternalCode IN (${codes.map(c => `'${c}'`).join(',')})
+`;
+```
+
+Роби TVP з 1 колонкою:
+
+- створити `new sql.Table()`
+- `columns.add('ExternalCode', sql.NVarChar(N))`
+- `rows.add(code)` після `trim()` + валідації
+- `request.input('codes', table)`
+- в SQL: `JOIN @codes c ON c.ExternalCode = t.ExternalCode`
+
+Плюси:
+
+- 0% SQL injection
+- текст SQL **не росте** від довжини масиву
+- SQL Server часто оптимізує `JOIN` краще, ніж гігантський `IN (...)`
+
+### 2) `DELETE ... VALUES (...)` / `MERGE ... VALUES (...)` → TVP з 2 колонками
+
+Замість генерації списку рядків `(...),(...),...` у SQL (навіть якщо воно "через tagged template"):
+
+- сформуй TVP-таблицю `@Pairs` з колонками:
+  - `PromoActivitiesId` (INT або BIGINT — як у схемі БД)
+  - `SupplierOutletId` (INT або BIGINT — як у схемі БД)
+
+Delete:
+
+```sql
+DELETE abi
+FROM promo.ActivitiesByOutlet abi
+JOIN @Pairs p
+  ON p.PromoActivitiesId = abi.PromoActivitiesId
+ AND p.SupplierOutletId = abi.SupplierOutletId;
+```
+
+Insert (без `MERGE`, простіше і безпечніше):
+
+```sql
+INSERT INTO promo.ActivitiesByOutlet (PromoActivitiesId, SupplierOutletId, Status)
+SELECT p.PromoActivitiesId, p.SupplierOutletId, 2
+FROM @Pairs p
+WHERE NOT EXISTS (
+  SELECT 1
+  FROM promo.ActivitiesByOutlet abi
+  WHERE abi.PromoActivitiesId = p.PromoActivitiesId
+    AND abi.SupplierOutletId = p.SupplierOutletId
+);
+```
+
+Плюси:
+
+- не збираєш SQL-рядок із даних
+- менше шансів упіймати edge-case `MERGE` (у SQL Server історично багато "сюрпризів")
+
+### Мінімальна валідація перед наповненням TVP
+
+Навіть з TVP потрібно:
+
+- `ExternalCode`: `typeof === 'string'`, `trim()`, довжина `<= N` (під схему), відкинути пусті.
+- ліміт на кількість елементів (наприклад 5k/10k — залежить від вашого потоку).
+- `supplierId`/ID: число/BigInt, валідне та скінченне.

package/rules/js-run/configmap/configmap.mdc

@@ -29,3 +29,9 @@ data:
 ```
 
 Ресурси типу `kind: Deployment` та інші non-ConfigMap — ігноруються.
+
+### Kustomize-оверлеї: `service.namespace` має відповідати namespace оверлею (не автоматизовано)
+
+Конвенція, **не** покрита автоматичною перевіркою — звіряй вручну під час рев'ю: у директоріях з kustomize-оверлеями значення `OTEL_RESOURCE_ATTRIBUTES` повинні бути перевизначені, і в них `service.namespace` повинен відповідати namespace, у якому знаходиться дана директорія оверлею (наприклад, `k8s/overlays/staging/` → `service.namespace=staging`).
+
+Rego-gate вище цього не звіряє — він лише перевіряє наявність обох substring-маркерів у кожному ConfigMap незалежно від директорії, тому розбіжність `service.namespace` між `base` і kustomize-оверлеями пройде перевірку мовчки. Кросс-файлова резолюція kustomize-дерева (`base` + `overlays`) — складніша задача, вже реалізована для інших k8s-перевірок у `npm/rules/k8s/manifests/main.mjs`; переносити цю логіку в `js-run` окремо не варто, поки немає підтвердженого запиту на автоматизацію саме цього кейсу.

package/rules/js-run/jsconfig/jsconfig.mdc

@@ -1,3 +1,26 @@
+## `jsconfig.json` (редактор / перевірка типів)
+
+Якщо в **backend** workspace-пакеті (без `vite` у `devDependencies`) є каталог **`src/`**, у **корені цього пакета** має бути **`jsconfig.json`**. Якщо файлу ще немає — створи його з таким вмістом (канон js-run):
+
+```json title="jsconfig.json"
+{
+  "compilerOptions": {
+    "lib": ["esnext"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "esnext",
+    "checkJs": false
+  },
+  "include": ["src/**/*"]
+}
+```
+
+Канон і повний перелік перевірених полів — див. розділ нижче **Rego-gate: jsconfig.json**, канонічний файл: [jsconfig.json.snippet.json](./template/jsconfig.json.snippet.json).
+
+Якщо пакет не слідує структурі з `src/` (наприклад, лише `scripts/` у корені) — ця вимога не застосовується; для типових сервісів із `src/` файл обов'язковий і має збігатися з каноном.
+
+Fs-existence створення `jsconfig.json`, коли його бракує, — T0-автофікс (`../runtime/fix-runtime.mjs`); структурну звірку канону виконує rego-gate нижче.
+
 ## Rego-gate: jsconfig.json
 
 Rego-пакет: `js-run.jsconfig`

package/rules/js-run/package_json/package_json.mdc

@@ -36,3 +36,9 @@ Rego-пакет: `js-run.package_json`
 ```
 
 Пакети з `vite` у `devDependencies` — frontend, поза областю js-run, перевірка scripts не застосовується.
+
+## Використання @nitra/pino для логування
+
+Проект використовує @nitra/pino для логування. Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API.
+
+Заборона `bunyan` / `@nitra/bunyan` у `dependencies` / `devDependencies` — rego-gate вище (канон: [package.json.deny.json](./template/package.json.deny.json)). Заборонені імпорти в коді (AST-сканер): `../lib/bunyan-imports.mjs` (перевірка запускається з `../runtime/main.mjs`).

package/rules/js-run/project-structure/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/js-run/project-structure/project-structure.mdc

@@ -0,0 +1,11 @@
+## Структура проекту
+
+Рекомендується використовувати таку структуру проекту:
+
+```
+k8s/ # тут всі файли для деплойменту в Kubernetes, включаючи kustomize
+src/ # тут всі файли необхідні для роботи проекту
+Dockerfile
+package.json
+readme.md
+```

package/rules/js-run/runtime/runtime.mdc

@@ -12,3 +12,173 @@
 Це **не** стосується поля `engines.node` (мінімальна версія Node для сумісності інструментів) і **не** стосується frontend-пакетів з `vite` у `devDependencies`.
 
 Канон заборонених патернів у `scripts`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json) (`scriptsForbidden`).
+
+## CheckEnv та заборона прямого `process.env`
+
+### CheckEnv
+
+Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми.
+
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.mjs"
+import { checkEnv, env } from '@nitra/check-env'
+import { SQL } from 'bun'
+
+checkEnv(['PG_CONN'])
+
+export const db = new SQL({ url: env.PG_CONN })
+
+```
+
+### process.env
+
+Прямий доступ до `process.env.X` у коді заборонений — його треба замінити на `env`:
+
+> Стосується лише backend-пакетів (див. **Область застосування**). У frontend-пакетах (`vite` у `devDependencies`) — **не змінюй** `process.env.*` і **не додавай** імпорт `node:process`.
+
+- **обов'язкова змінна** — `import { checkEnv, env } from '@nitra/check-env'` плюс `checkEnv(['X'])`
+  у тому ж файлі (приклад див. вище в розділі **CheckEnv**);
+- **опційна змінна** — `import { env } from 'node:process'`:
+
+```javascript title="Опційна змінна — env з node:process"
+import { env } from 'node:process'
+
+console.log(env.OPTIONAL_ENV_VAR)
+```
+
+Тимчасово приглушити перевірку для конкретного рядка можна коментарем
+`// @7n/rules ignore-next-line checkEnv` безпосередньо перед використанням
+(escape-hatch для legacy-коду, не для нових файлів).
+
+Перевірка (JS-сканер): `../lib/check-env-scan.mjs`.
+
+## Внутрішні аліаси для підключень до БД і GraphQL
+
+Якщо в проекті є підключення до баз даних, зовнішніх graphql на кшталт:
+
+```js
+import { SQL } from 'bun'
+
+// або
+
+import sql from 'mssql'
+
+// або
+
+import { GraphQLClient } from '@nitra/graphql-request'
+```
+
+то ці підключення повинні бути винесені в окремий файл, наприклад `/src/conn/pg.mjs`, в package.json повинні бути додано аліас:
+
+```json
+{
+  "imports": {
+    "#conn/*": "./src/conn/*"
+  },
+}
+
+```
+
+так виглядатиме підключення до PostgreSQL в коді:
+
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.mjs"
+import { checkEnv, env } from '@nitra/check-env'
+import { SQL } from 'bun'
+
+checkEnv(['PG_CONN'])
+
+export const db = new SQL({ url: env.PG_CONN })
+
+```
+
+а так до GraphQL:
+
+```js
+import { checkEnv, env } from '@nitra/check-env'
+import { GraphQLClient } from '@nitra/graphql-request'
+
+checkEnv(['QL', 'X_HASURA_ADMIN_SECRET'])
+
+export { gql } from '@nitra/graphql-request'
+
+export const graphQLClientSmart = new GraphQLClient(env.QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': env.X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+а в коді повинно бути використано:
+
+```js
+import { pool } from '#conn/pg.mjs'
+
+// або
+
+import { gql, graphQLClient } from '@nitra/graphql-request'
+```
+
+### Нейминг файлів у `src/conn/`
+
+Назва файла в `src/conn/` має одразу повідомляти, **до чого** підключаємось і **в якому режимі**:
+
+- **GraphQL** — префікс `ql-`, далі ідентифікатор endpoint:
+  - `src/conn/ql-contract.mjs`
+  - `src/conn/ql-smart.mjs`
+- **PostgreSQL** — префікс `pg-`, далі тип підключення (репліка vs мастер): `read` або `write`:
+  - `src/conn/pg-read.mjs`
+  - `src/conn/pg-write.mjs`
+- **PostgreSQL до кількох БД** — додатково ідентифікатор підключення після типу:
+  - `src/conn/pg-read-smart.mjs`
+  - `src/conn/pg-write-contract.mjs`
+- **MySQL** — префікс `mysql-` за тією ж схемою (`mysql-read.mjs`, `mysql-write-<id>.mjs` тощо).
+- **MSSQL** — префікс `mssql-` за тією ж схемою (`mssql-read.mjs`, `mssql-write-<id>.mjs` тощо). Хоча npm-пакет один (`mssql`), а драйвер MS SQL Server під капотом T-SQL — у файловій назві відрізняємо MS SQL Server від MySQL, бо це різні СУБД, різні діалекти, різні рантаймні залежності. Якщо проєкт історично використовує `mysql-…` для MSSQL-підключень — він валідний і далі (для backward-compat), але новий код пишемо з префіксом `mssql-`.
+
+Підключення до БД **обов'язково** має бути ідентифіковано як `read` (репліка) або `write` (мастер). Якщо з імені змінної оточення (наприклад, `env.PG_CONN`) це не очевидно — визнач режим за операціями в коді: якщо немає операцій зміни даних (`INSERT`/`UPDATE`/`DELETE`/DDL) — це `pg-read.mjs`, інакше `pg-write.mjs`.
+
+### Експорти у файлах `src/conn/`
+
+У файлах підключень **заборонений** `export default`. Експорт має бути **іменований** і збігатися з назвою файла в camelCase.
+
+Приклад — `src/conn/ql-smart.mjs`:
+
+```javascript title="❌ Так не можна"
+export default new GraphQLClient(env.SMART_QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': env.SMART_X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+```javascript title="✅ Канон: іменований експорт за іменем файла"
+export const qlSmart = new GraphQLClient(env.SMART_QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': env.SMART_X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+Відповідно: `pg-read.mjs` → `export const pgRead = …`, `pg-write-contract.mjs` → `export const pgWriteContract = …`, `ql-contract.mjs` → `export const qlContract = …`.
+
+Файли `index.*` у conn-каталозі пропускаються як можливий reexport-барель.
+
+Перевірка (JS-сканери): `../lib/conn-file-rules.mjs` (нейминг, експорти), `../lib/conn-imports-scan.mjs` (факторні імпорти поза `src/conn/`); декларація аліаса `imports["#conn/*"]` у `package.json` — `checkConnAliasDeclaration` у `main.mjs`.
+
+## Паузи через setTimeout
+
+Заборонено робити паузи через `await new Promise(resolve => setTimeout(resolve, ms))` — таку обгортку треба замінити на promise-варіант `setTimeout` з `node:timers/promises`:
+
+```javascript title="Замість new Promise + setTimeout"
+import { setTimeout } from 'node:timers/promises'
+
+await setTimeout(500)
+```
+
+Імпорт `setTimeout` з `node:timers/promises` затіняє глобальний таймер у файлі — якщо в тому ж файлі потрібен callback-варіант, імпортуй його під іншим іменем (наприклад, `import { setTimeout as setTimeoutCb } from 'node:timers'`).
+
+Перевірка (JS-сканер): `../lib/promise-settimeout-scan.mjs`.
+
+## Temporal API (заборона у Bun runtime)
+
+У backend/Bun runtime-коді **не використовуй `Temporal`** (`Temporal.Now`, `Temporal.Instant`, імпорти з polyfill тощо). Bun 1.3.x (діапазон версій репозиторію — `bun >= 1.3`) ще не має глобального `Temporal` (`typeof Temporal === "undefined"`), тому агентам треба лишатися на сумісному `Date` API або передавати timestamp у чисті функції через параметр.
+
+Перевірка `npx @7n/rules check` (AST-сканер `../lib/temporal-scan.mjs`) сканує JS/TS-код на identifier `Temporal` у backend workspace-коді.

package/rules/js-run/scope/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/js-run/scope/scope.mdc

@@ -0,0 +1,11 @@
+## Область застосування
+
+Правило стосується **виключно backend Node.js workspace-пакетів** (jobs, GraphQL/HTTP-сервери, CLI). **Не застосовується** до frontend-пакетів, які бандляться в браузер: маркер — наявність `vite` у `devDependencies` пакета (`site/`, мобільні Capacitor-пакети, будь-яка Vue/Quasar SPA).
+
+У браузерному середовищі:
+
+- немає `node:process` — імпорт `import { env } from 'node:process'` resolve'иться у `undefined`, і `env.X` падає з `TypeError: Cannot read properties of undefined`;
+- `process.env.X` у джерелах пакета відсутнє в рантаймі — Vite або взагалі не підставляє його, або підставляє лише `process.env.NODE_ENV`;
+- усі змінні оточення для frontend задаються через `VITE_*` і доступні як `import.meta.env.VITE_X` (типобезпечно через `vite-check-env`); режим — `import.meta.env.MODE` / `import.meta.env.PROD`.
+
+Тому **у frontend-пакетах не торкайся `process.env.*`** і **не додавай** `import { env } from 'node:process'`. Якщо натрапив на `process.env.NODE_ENV` у frontend-коді — заміна, якщо взагалі потрібна, лише на `import.meta.env.MODE`.

package/rules/k8s/hasura_configmap/hasura_configmap.mdc

@@ -18,3 +18,9 @@ Rego-пакет: `k8s.hasura_configmap`
 Семантика: `"true"`/`"false"` приймаються як boolean або рядок (case-insensitive); точний рядок — exact match.
 
 **Примітка:** відбір ConfigMap за сусідством із Hasura-Deployment — cross-file, у JS. Rego — пер-документна валідація полів `data`.
+
+## ConfigMap: ім'я збігається з Deployment
+
+Ця перевірка не обмежена Hasura — стосується **будь-якого** `configmap.yaml` під `k8s/base/`. Якщо в тому самому каталозі є **`configmap.yaml`** і **Deployment**, і цей Deployment посилається рівно на **один** ConfigMap (через `envFrom[*].configMapRef.name` або `volumes[*].configMap.name`) — `metadata.name` ConfigMap має збігатися з `metadata.name` Deployment.
+
+Перевірка — cross-file, у **`npm/rules/k8s/manifests/main.mjs`** (`validateConfigMapNameMatchesDeployment` / `validateSingleConfigMapNameMatch`). Якщо Deployment посилається на кілька ConfigMap або жодного — перевірка пропускається (немає однозначного відповідника).

package/rules/k8s/hpa_pdb/hpa_pdb.mdc

@@ -23,3 +23,137 @@ PDB (`kind: PodDisruptionBudget` або `apiVersion: policy/v1`):
 - `spec.selector.matchLabels` — присутній об'єкт
 
 **Примітка:** cross-file перевірки (відповідність `expectedDeployName`, `expectedAppLabel`, `isDevLike`-сегмент) лишаються у JS (`hpaManifestViolations`, `pdbManifestViolations`).
+
+## Канон `components/`, env-залежні межі, прод-оверрайди
+
+Структурні перевірки полів HPA/PDB вище — про **самі поля** (`apiVersion`, `kind`, `spec.metrics`, `spec.selector` тощо). Заборону локальних `hpa.yaml`/`pdb.yaml` у `base/` — див. **`base_kustomization.mdc`**. Цей розділ — про **env-залежні числові межі** і структуру sibling-каталогу **`components/`**.
+
+### Канонічна структура `<pkg>/k8s/components/`
+
+Для **кожного** `kind: Deployment` у `…/k8s/…/base/` обов'язковий sibling-каталог **`…/k8s/…/components/`** (Kustomize Component, фіксована назва каталогу — `components`) з HPA і PDB для цього Deployment:
+
+- **`kustomization.yaml`** — `apiVersion: kustomize.config.k8s.io/v1alpha1`, `kind: Component`, `resources: [hpa.yaml, pdb.yaml]` (як мінімум ці два).
+- **`hpa.yaml`** — `autoscaling/v2`, `HorizontalPodAutoscaler`, `spec.scaleTargetRef.name` **= `metadata.name`** Deployment, dev-like значення `minReplicas: 1`, `maxReplicas: 1`.
+- **`pdb.yaml`** — `policy/v1`, `PodDisruptionBudget`, `spec.selector.matchLabels.app` **= мітка `app`** Deployment, dev-like `minAvailable: 0`.
+
+**`kind: Component`** (не `kind: Kustomization`) — це **джерело** канонічних HPA/PDB для всіх overlays, а не overlay сам по собі; всередині самого Component prod-патчі не потрібні (env-неутральний).
+
+Перевірка — **`npm/rules/k8s/manifests/main.mjs`** (`validateComponentsForBaseDeployment`).
+
+### Env-залежні межі (за сегментом шляху після `/k8s/`)
+
+**Dev-like середовища** — сегмент `base`, `dev`, або з суфіксом `-qa` (наприклад `tr-qa`):
+
+- HPA: `minReplicas` — рівно **1**, `maxReplicas` — рівно **1**.
+- PDB: `minAvailable` — рівно **0**.
+
+**Прод-середовища** — усе інше:
+
+- HPA: `minReplicas` — мінімум **2**, `maxReplicas` — мінімум **2** (і `minReplicas <= maxReplicas`).
+- PDB: `minAvailable` — мінімум **1**.
+
+Перевірка — **`npm/rules/k8s/manifests/main.mjs`** (`hpaManifestViolations`, `pdbManifestViolations`; сегмент середовища визначає `isDevLikeK8sEnvSegment`).
+
+### Прод-оверрайди у `kustomization.yaml`
+
+Якщо прод-оверлей (сегмент не dev-like) успадковує HPA/PDB через `components: [- ../components]` (або інший kustomize-tree з HPA/PDB), у `patches[]` **обов'язкові** JSON6902-перевизначення прод-значень:
+
+- **`HorizontalPodAutoscaler`**: `/spec/minReplicas` і `/spec/maxReplicas` (мінімум 2).
+- **`PodDisruptionBudget`**: `/spec/minAvailable` (мінімум 1).
+
+```yaml title="k8s/prod/kustomization.yaml (фрагмент)"
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: prod
+resources:
+  - ../base
+components:
+  - ../components
+patches:
+  - target:
+      kind: HorizontalPodAutoscaler
+      name: backend-api
+    patch: |-
+      - op: replace
+        path: /spec/minReplicas
+        value: 2
+      - op: replace
+        path: /spec/maxReplicas
+        value: 10
+  - target:
+      kind: PodDisruptionBudget
+      name: backend-api
+    patch: |-
+      - op: replace
+        path: /spec/minAvailable
+        value: 1
+```
+
+Не застосовується до dev-like оточень. Перевірка — **`npm/rules/k8s/manifests/main.mjs`** (`prodOverlayHpaPdbOverrideNeeds`, `validateProdKustomizationOverrides`).
+
+### Приклад: `components/hpa.yaml` і `components/pdb.yaml`
+
+```yaml title="k8s/components/kustomization.yaml"
+apiVersion: kustomize.config.k8s.io/v1alpha1
+kind: Component
+resources:
+  - hpa.yaml
+  - pdb.yaml
+```
+
+```yaml title="k8s/components/hpa.yaml"
+# yaml-language-server: $schema=https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.33.9-standalone-strict/horizontalpodautoscaler-autoscaling-v2.json
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: backend-api
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: backend-api
+  minReplicas: 1 # прод overlay підіймає до >= 2
+  maxReplicas: 1 # прод overlay підіймає до >= 2
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+  behavior:
+    scaleUp:
+      stabilizationWindowSeconds: 15
+      policies:
+        - type: Percent
+          value: 100
+          periodSeconds: 30
+        - type: Pods
+          value: 4
+          periodSeconds: 30
+      selectPolicy: Max
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+        - type: Percent
+          value: 25
+          periodSeconds: 120
+      selectPolicy: Min
+```
+
+```yaml title="k8s/components/pdb.yaml"
+# yaml-language-server: $schema=https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.33.9-standalone-strict/poddisruptionbudget-policy-v1.json
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: backend-api
+spec:
+  minAvailable: 0 # прод overlay підіймає до >= 1
+  selector:
+    matchLabels:
+      app: backend-api
+```
+
+### Overlays без `components/`
+
+У **не-base** оверлеях, що не підключають sibling `components/`, поруч із `Deployment` лишається звична схема: окремі **`hpa.yaml`** і **`pdb.yaml`**, якщо такі потрібні для цього середовища (структурні поля — вище; env-залежні межі — як вище).

package/rules/k8s/kubeconform/kubeconform.mdc

@@ -0,0 +1,38 @@
+## lint-k8s: kubeconform і kubescape
+
+Окремо від modeline `$schema` у редакторі (**`main.mdc`**) варто ганяти CLI-лінтери (**kubeconform** і **kubescape**) по тих самих деревах **`…/k8s`**.
+
+**Залежності:** виконувані файли kubeconform, kubescape і kubectl у **PATH** (kustomize використовуємо як вшиту підкоманду **`kubectl kustomize`** — окремий бінарник `kustomize` не потрібен); не додавай їх у **devDependencies**.
+
+**Версія Kubernetes для kubeconform** — **`-kubernetes-version 1.33.9`** (semver без префікса `v`; набір схем **`v1.33.9-standalone-strict`**). Для CRD додатково підключається реєстр [datreeio/CRDs-catalog](https://github.com/datreeio/CRDs-catalog) другим **`-schema-location`**. Прапорець **`-ignore-missing-schemas`** увімкнено завжди. Реалізація — **`npm/rules/k8s/kubeconform/main.mjs`** (`runKubeconform` у **`npm/rules/k8s/manifests/main.mjs`**).
+
+**kubescape** — вхід через зібраний kustomize-маніфест: для кожного dir-у з `kustomization.yaml` (`kind: Kustomization`; **`kind: Component`** пропускається) лінт виконує **`kubectl kustomize <dir>`** і передає stdout у **`kubescape scan <tmp-file>`** з порогом **`--severity-threshold high`**. Маніфест проходить через тимчасовий файл, бо **`kubescape scan` у v4.x не читає stdin**. Якщо в дереві **`…/k8s`** немає жодного `kustomization.yaml` — fallback на dir-скан **`kubescape scan <каталог-k8s>`**. У kubescape немає прапорця **`-kubernetes-version`**. Реалізація — **`npm/rules/k8s/manifests/main.mjs`** (`runKubescape`, `scanKustomizeK8sDirs`, `scanRawK8sDir`).
+
+Лінт запускається через **`npx @7n/rules lint`** (per-file детектор `k8s/kubeconform`) і **`npx @7n/rules fix k8s`** (cross-file оркестрація kubescape, `k8s/manifests`). Окремий `package.json`-скрипт `lint-k8s` не потрібен.
+
+## Винятки kubescape: `.kubescape-exceptions.json`
+
+Якщо в **корені проєкту** є файл **`.kubescape-exceptions.json`** — лінт автоматично передає його в `kubescape scan` через **`--exceptions`** ([postureExceptionPolicy](https://github.com/kubescape/kubescape/blob/master/docs/exceptions.md); `buildKubescapeExceptionsArgs` у `npm/rules/k8s/manifests/main.mjs`).
+
+Канонічний кейс — **C-0012** (`Applications credentials in configuration files`, High): control тригериться на **ім'я** env, що містить підрядок `secret`/`password`/`key`/`token`, а **не** на значення. Точкове виключення для ConfigMap із цим env — приклад структури:
+
+```json
+[
+  {
+    "name": "hasura-jwt-public-config",
+    "policyType": "postureExceptionPolicy",
+    "actions": ["alertOnly"],
+    "resources": [
+      {
+        "designatorType": "Attributes",
+        "attributes": { "kind": "ConfigMap", "name": "hasura-config" }
+      }
+    ],
+    "posturePolicies": [{ "controlID": "C-0012" }]
+  }
+]
+```
+
+**Увага:** готовий snippet-файл цього прикладу (`js/templates/kubescape_exceptions/.kubescape-exceptions.json.snippet.json` до `da05f89d`) під час "combine concern" **не був перенесений** у жоден поточний concern-каталог і в репозиторії відсутній — знайти оригінал не вдалося; за потреби відтвори JSON вручну за прикладом вище.
+
+Виключай контрольно, а не глобально (не додавай винятки без `attributes.name`/`labels`).

package/rules/k8s/kustomization/kustomization.mdc

@@ -18,3 +18,76 @@ Rego-пакет: `k8s.kustomization`
 ✗ `op: remove` + `op: add` на один `path` в одному patch
 
 **Примітка:** резолюція kustomize-дерева, перевірка існування refs на диску, парність `svc.yaml`/`svc-hl.yaml` — JS (`rules/k8s/fix.mjs`).
+
+## Kustomize: структура каталогів (`base` / overlays)
+
+Трансформуй дерева **`**/k8s`**, щоб **винести спільне** через [Kustomize](https://kustomize.io/): один канонічний **`base`** і тонкі **overlays** для інших середовищ.
+
+### Джерело правди — середовище dev
+
+- За основу бери **все, що відповідає середовищу dev** (як воно має виглядати в кластері для dev).
+- У **такому вигляді** цей набір стає каталогом **`base`**: спільні маніфести без окремої директорії **`dev/`**.
+- Окремої директорії **`k8s/dev/`** **не повинно існувати**: за середовище **dev** відповідає **`base`**. `check k8s` падає на будь-якому шляху `…/k8s/dev/…` (`isForbiddenK8sDevPath` у `npm/rules/k8s/manifests/main.mjs`).
+
+### Overlays (не-dev)
+
+- У каталозі кожного іншого середовища (наприклад **`ua/`**, **`prod/`**) — мінімум файлів: типово лише **`kustomization.yaml`** і ресурси, **необхідні лише для цього overlay**.
+- Відмінності від dev вносяться **оверрайдами** (patches, `images`, `replicas`, `configMapGenerator` тощо), а не копіюванням повного дерева з `base`.
+
+### Рядки, що змінюються між середовищами
+
+У manifest-файлах у **`base`** для полів, які **будуть відрізнятися** в інших середовищах, на **тому самому рядку** додай коментар:
+
+```yaml
+image: my-app:dev-tag # буде замінено через kustomize
+```
+
+### Зміна image — через `images:`, не через `patches[]`
+
+Підміну image у Pod-шаблоні Deployment в overlay роби директивою `images:`, а не JSON6902-патчем `op: replace` на `/spec/template/spec/containers/<N>/image`.
+
+- У **`name`** — те, що **дослівно** стоїть у `image:` у base **без тегу**.
+- **`newName`** — кінцеве ім'я образу; **`newTag`** — тег для прода.
+- **`digest`** (`@sha256:…`) у `name` / `newName` не чіпай.
+
+```yaml title="k8s/prod/kustomization.yaml (фрагмент)"
+images:
+  - name: europe-west4-docker.pkg.dev/abie-ua/c/apply-on-invoice-discount
+    newName: europe-west4-docker.pkg.dev/abie-ua/c/apply-on-invoice-discount
+    newTag: v2025-04-29
+```
+
+**`check k8s` автоматично** для кожного `kustomization.yaml` (конвертація в `npm/rules/k8s/manifests/main.mjs`):
+
+1. конвертує кожну JSON6902-операцію `op: replace` на `/spec/template/spec/containers/<N>/image` у запис `images:`;
+2. чистить існуючий блок `images:` — зрізає `:tag` з `name` і видаляє `newTag`, який збігається з відрізаним тегом.
+
+### Міграція зі старої структури
+
+Після перенесення у **`base`** та overlays і перевірки (**`check k8s`**, **`lint-k8s`**) **видали** застарілі файли та директорії, що замінені новою схемою.
+
+### `patches[].target`: лише `kind` і `name`
+
+У `patches[].target` залишай **тільки** **`kind`** і **`name`** — поля **`group`** і **`version`** прибирай, якщо в інвентарі ресурсів немає колізії за цим `kind`+`name` між різними API-групами/версіями.
+
+```yaml
+# ❌ зайві group / version
+patches:
+  - target:
+      group: gateway.networking.k8s.io
+      version: v1beta1
+      kind: Gateway
+      name: gw
+
+# ✅
+patches:
+  - target:
+      kind: Gateway
+      name: gw
+```
+
+**Виняток:** залишай `group` / `version`, лише якщо в дереві overlay реально співіснують ресурси з однаковими `kind`+`name`, але різними API-групами/версіями.
+
+### Локальні шляхи в `kustomization.yaml`
+
+Кожен запис без `://` (remote) з `resources` / `bases` / `components` / `crds`, `patchesStrategicMerge`, `patches[].path`, `patchesJson6902[].path`, `configurations[]`, `replacements[].path` має вказувати на **існуючий** у репозиторії файл (`.yaml` / `.yml`) або **каталог**; биті посилання — помилка **`check k8s`**.