@nitra/cursor 12.8.6 → 12.8.7

package/rules/js-run/js/conn-aliases.mdc

@@ -0,0 +1,109 @@
+## Внутрішні аліаси для підключень до БД і 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-барель.

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

@@ -0,0 +1,20 @@
+## `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/**/*"]
+}
+```
+
+Канон: [jsconfig.json.snippet.json](./policy/jsconfig/template/jsconfig.json.snippet.json)
+
+Якщо пакет не слідує структурі з `src/` (наприклад, лише `scripts/` у корені) — ця вимога не застосовується; для типових сервісів із `src/` файл обов'язковий і має збігатися з каноном.

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

@@ -0,0 +1,6 @@
+## OTEL ConfigMap (k8s)
+
+В **/k8s/base/configmap.yaml** повинен бути заданий `OTEL_RESOURCE_ATTRIBUTES: 'service.name=<project_name>,service.namespace=<project_namespace>'`
+а в директоріях з kustomize повинні бути перевизначені значення `OTEL_RESOURCE_ATTRIBUTES` і в них `service.namespace` повинен відповідати namespace, в якому знаходиться дана директорія.
+
+Канон обовʼязкових substring у `data.OTEL_RESOURCE_ATTRIBUTES` (`service.name=`, `service.namespace=`): [configmap.yaml.contains.yml](./policy/configmap/template/configmap.yaml.contains.yml)

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

@@ -0,0 +1,6 @@
+## Використання @nitra/pino для логування
+
+Проект використовує @nitra/pino для логування.
+Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API.
+
+Канон заборонених `dependencies` / `devDependencies` (`bunyan`, `@nitra/bunyan`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json)

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

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

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

@@ -0,0 +1,14 @@
+## Runtime у `package.json#scripts`
+
+У **backend**-пакетах (без `vite` у `devDependencies`) код запускають через **Bun**, не через бінарник **`node`** у значеннях `scripts`:
+
+- `"start": "node src/index.js"` → `"start": "bun src/index.js"` (або `bun run …`, якщо так прийнято в репо);
+- `node --watch app.js` → `bun --watch app.js`;
+- `NODE_OPTIONS=… node app.js` → `NODE_OPTIONS=… bun app.js`.
+- `env $(cat .env .env.local) bun src/index.js` → `bun --env-file=.env --env-file=.env.local src/index.js` (нативне завантаження env у Bun, без `env`/`cat`).
+
+Заборонено викликати **`node`** у ланцюжках (`&&`, `;`, `|`). Заборонено обгортку **`env $(cat …) bun`** — файли з `cat` перелічуй у **`--env-file=`** (по одному прапорцю на файл, порядок як у `cat`). Допустимо: `bun`, `bunx`, `npx` (див. **bun.mdc**), інші CLI, якщо вони не підміняють рантайм на `node`.
+
+Це **не** стосується поля `engines.node` (мінімальна версія Node для сумісності інструментів) і **не** стосується frontend-пакетів з `vite` у `devDependencies`.
+
+Канон заборонених патернів у `scripts`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json) (`scriptsForbidden`).

package/rules/js-run/js/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/js-run/js/settimeout.mdc

@@ -0,0 +1,11 @@
+## Паузи через 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'`).

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

@@ -0,0 +1,5 @@
+## Temporal API (заборона у Bun runtime)
+
+У backend/Bun runtime-коді **не використовуй `Temporal`** (`Temporal.Now`, `Temporal.Instant`, імпорти з polyfill тощо). Поточний Bun runtime ще не має глобального `Temporal` (`typeof Temporal === "undefined"`), тому агентам треба лишатися на сумісному `Date` API або передавати timestamp у чисті функції через параметр.
+
+Перевірка `npx @nitra/cursor fix js-run` сканує JS/TS AST і падає на identifier `Temporal` у backend workspace-коді.

package/rules/js-run/main.mdc

@@ -5,234 +5,32 @@ alwaysApply: false
 version: '1.12'
 ---
 
-## Область застосування
+Правило охоплює backend Node.js workspace-пакети (jobs, GraphQL/HTTP-сервери, CLI) — визначення меж застосування, вимоги до runtime, структуру проекту, конфігурацію, логування, підключення до БД/GraphQL і безпечне використання env-змінних.
 
-Правило стосується **виключно backend Node.js workspace-пакетів** (jobs, GraphQL/HTTP-сервери, CLI). **Не застосовується** до frontend-пакетів, які бандляться в браузер: маркер — наявність `vite` у `devDependencies` пакета (`site/`, мобільні Capacitor-пакети, будь-яка Vue/Quasar SPA).
+[js-run-scope](./js/scope.mdc)
 
-У браузерному середовищі:
+[js-run-runtime](./js/runtime.mdc)
 
-- немає `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`.
+[js-run-temporal](./js/temporal.mdc)
 
-Тому **у frontend-пакетах не торкайся `process.env.*`** і **не додавай** `import { env } from 'node:process'`. Якщо натрапив на `process.env.NODE_ENV` у frontend-коді — заміна, якщо взагалі потрібна, лише на `import.meta.env.MODE`.
+[js-run-project-structure](./js/project-structure.mdc)
 
-## Runtime у `package.json#scripts`
+[js-run-jsconfig](./js/jsconfig.mdc)
 
-У **backend**-пакетах (без `vite` у `devDependencies`) код запускають через **Bun**, не через бінарник **`node`** у значеннях `scripts`:
+[js-run-pino](./js/pino.mdc)
 
-- `"start": "node src/index.js"` → `"start": "bun src/index.js"` (або `bun run …`, якщо так прийнято в репо);
-- `node --watch app.js` → `bun --watch app.js`;
-- `NODE_OPTIONS=… node app.js` → `NODE_OPTIONS=… bun app.js`.
-- `env $(cat .env .env.local) bun src/index.js` → `bun --env-file=.env --env-file=.env.local src/index.js` (нативне завантаження env у Bun, без `env`/`cat`).
+[js-run-otel-configmap](./js/otel-configmap.mdc)
 
-Заборонено викликати **`node`** у ланцюжках (`&&`, `;`, `|`). Заборонено обгортку **`env $(cat …) bun`** — файли з `cat` перелічуй у **`--env-file=`** (по одному прапорцю на файл, порядок як у `cat`). Допустимо: `bun`, `bunx`, `npx` (див. **bun.mdc**), інші CLI, якщо вони не підміняють рантайм на `node`.
+[js-run-conn-aliases](./js/conn-aliases.mdc)
 
-Це **не** стосується поля `engines.node` (мінімальна версія Node для сумісності інструментів) і **не** стосується frontend-пакетів з `vite` у `devDependencies`.
+[js-run-check-env](./js/check-env.mdc)
 
-## Temporal API
+[js-run-settimeout](./js/settimeout.mdc)
 
-У backend/Bun runtime-коді **не використовуй `Temporal`** (`Temporal.Now`, `Temporal.Instant`, імпорти з polyfill тощо). Поточний Bun runtime ще не має глобального `Temporal` (`typeof Temporal === "undefined"`), тому агентам треба лишатися на сумісному `Date` API або передавати timestamp у чисті функції через параметр.
+## Швидкий gate через conftest
 
-Перевірка `npx @nitra/cursor fix js-run` сканує JS/TS AST і падає на identifier `Temporal` у backend workspace-коді.
+Rego-пакети, які запускає `npx @nitra/cursor fix js-run` / `npx @nitra/cursor check`:
 
-Канон заборонених патернів у `scripts`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json) (`scriptsForbidden`).
-
-## Структура проекту
-
-Рекомендується використовувати таку структуру проекту:
-
-```
-k8s/ # тут всі файли для деплойменту в Kubernetes, включаючи kustomize
-src/ # тут всі файли необхідні для роботи проекту
-Dockerfile
-package.json
-readme.md
-```
-
-## `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/**/*"]
-}
-```
-
-Канон: [jsconfig.json.snippet.json](./policy/jsconfig/template/jsconfig.json.snippet.json)
-
-Якщо пакет не слідує структурі з `src/` (наприклад, лише `scripts/` у корені) — ця вимога не застосовується; для типових сервісів із `src/` файл обов’язковий і має збігатися з каноном.
-
-## Використання @nitra/pino
-
-Проект використовує @nitra/pino для логування.
-Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API. Канон заборонених `dependencies` / `devDependencies` (`bunyan`, `@nitra/bunyan`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
-
-В **/k8s/base/configmap.yaml повинен бути заданий OTEL_RESOURCE_ATTRIBUTES: 'service.name=<project_name>,service.namespace=<project_namespace>'
-а в директоріях з kustomize повинні бути перевизначені значення OTEL_RESOURCE_ATTRIBUTES і в них service.namespace повинен відповідати namespace, в якому знаходиться дана директорія.
-
-Канон обовʼязкових substring у `data.OTEL_RESOURCE_ATTRIBUTES` (`service.name=`, `service.namespace=`): [configmap.yaml.contains.yml](./policy/configmap/template/configmap.yaml.contains.yml)
-
-## Внутрішні аліаси
-
-Якщо в проекті є підключення до баз даних, зовнішніх 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 = …`.
-
-## 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)
-```
-
-Тимчасово приглушити перевірку для конкретного рядка можна коментарем
-`// @nitra/cursor ignore-next-line checkEnv` безпосередньо перед використанням
-(escape-hatch для legacy-коду, не для нових файлів).
-
-## Паузи через 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'`).
-
-Файли `index.*` у conn-каталозі пропускаються як можливий reexport-барель.
+- `js_run.package_json` — заборонені `dependencies`/`devDependencies` (`bunyan`, `@nitra/bunyan`) і заборонені патерни у `scripts` (`node`, `env $(cat …) bun`)
+- `js_run.jsconfig` — відповідність `jsconfig.json` канону (`NodeNext`, `include: src/**/*`)
+- `js_run.configmap` — наявність `service.name=` і `service.namespace=` у `OTEL_RESOURCE_ATTRIBUTES` в `k8s/base/configmap.yaml`

package/rules/k8s/js/configmap.mdc

@@ -0,0 +1,41 @@
+## ConfigMap: ім'я збігається з Deployment
+
+Якщо в `k8s/base/` є **`configmap.yaml`** і **Deployment**, і цей Deployment посилається рівно на **один** ConfigMap — `metadata.name` ConfigMap має збігатися з `metadata.name` Deployment. Точні умови перевірки — **`rules/k8s/fix.mjs`**.
+
+## ConfigMap для Hasura-Deployment
+
+Якщо в `k8s/base/` поруч із **`configmap.yaml`** є **Deployment** з образом **`hasura/graphql-engine`**, у `data` ConfigMap **обов'язково** мають бути env-ключі:
+
+- **`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`** зі значенням **`"true"`**;
+- **`HASURA_GRAPHQL_ENABLE_RELAY`** зі значенням **`"false"`**;
+- **`HASURA_GRAPHQL_ENABLE_TELEMETRY`** зі значенням **`"false"`**;
+- **`HASURA_GRAPHQL_ENABLED_LOG_TYPES`** зі значенням **`"startup,http-log"`** (точний рядок);
+- **`HASURA_GRAPHQL_ENABLED_APIS`** зі значенням **`"metadata,graphql,pgdump"`** (точний рядок) — **значення для base/dev**;
+- **`HASURA_GRAPHQL_DISABLE_EVENTING`** — ключ обов'язковий, значення довільне (за замовчуванням **`"true"`**).
+
+Точні умови перевірки — rego-пакет **`k8s.hasura_configmap`** (cross-file прив'язка ConfigMap↔Deployment — у `rules/k8s/js/manifests.mjs`).
+
+```yaml
+data:
+  HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS: 'true'
+  HASURA_GRAPHQL_ENABLE_RELAY: 'false'
+  HASURA_GRAPHQL_ENABLE_TELEMETRY: 'false'
+  HASURA_GRAPHQL_ENABLED_LOG_TYPES: 'startup,http-log'
+  HASURA_GRAPHQL_ENABLED_APIS: 'metadata,graphql,pgdump'
+  HASURA_GRAPHQL_DISABLE_EVENTING: 'true'
+```
+
+### `HASURA_GRAPHQL_ENABLED_APIS` поза base/dev
+
+`pgdump` дозволено **лише** для **base**/**dev**. Кожен **не-base** overlay (`k8s/<env>/`, де `<env>` ≠ `base`/`dev`), що успадковує Hasura-base, **зобов'язаний** у своєму **`kustomization.yaml`** перевизначити `HASURA_GRAPHQL_ENABLED_APIS` до **`"metadata,graphql"`** (без `pgdump`) — патчем JSON6902 або Strategic Merge на ціль **ConfigMap**. Перевірка — cross-file у `rules/k8s/js/manifests.mjs` (`validateHasuraOverlayEnabledApisOverride`); `kind: Component` пропускається.
+
+```yaml title="k8s/prod/kustomization.yaml"
+patches:
+  - target:
+      kind: ConfigMap
+      name: db-h
+    patch: |
+      - op: replace
+        path: /data/HASURA_GRAPHQL_ENABLED_APIS
+        value: metadata,graphql
+```

package/rules/k8s/js/deployment_resources.mdc

@@ -0,0 +1,49 @@
+## Deployment: `resources.requests` (CPU і memory)
+
+У кожному контейнері **`Deployment`** обов'язкові **`resources.requests.cpu`** і **`resources.requests.memory`** (непорожні скаляри Kubernetes Quantity).
+
+### Шар **`…/k8s/…/base/…`** (dev / щільний packing)
+
+У **всіх** `Deployment` у файлах під **`…/k8s/…/base/…`** значення **жорстко фіксовані** (для **cpu** допускається число **`0.02`** у YAML):
+
+```yaml
+resources:
+  requests:
+    cpu: '0.02'
+    memory: '128Mi'
+```
+
+**HPA і PDB у base не тримаємо**: ні локальних `hpa.yaml` / `pdb.yaml` поруч із workload-manifest-файлами, ні через `resources` / `components` / `bases`. Канон — sibling каталог **`components/`** (Kustomize Component) поруч з `base/`, який підключають лише прод-overlays. **NetworkPolicy** — навпаки: **обов'язковий і у `base/`**, у вигляді `base/networkpolicy.yaml` підключений через `base/kustomization.yaml` `resources:`.
+
+### Поза base (оверлеї, окремі каталоги)
+
+Якщо ще не підібрано власні ліміти під сервіс, орієнтир для **`requests`**:
+
+```yaml
+resources:
+  requests:
+    cpu: '0.5'
+    memory: '512Mi'
+```
+
+У прод-оверлеях підіймай **`cpu` / `memory`** до реального споживання через **`patches`**. **`check k8s`** не вимагає саме **`0.5` / `512Mi`** поза base — лише непорожні **`requests.cpu`** і **`requests.memory`**.
+
+```yaml title="k8s/prod/kustomization.yaml (фрагмент)"
+patches:
+  - target:
+      kind: Deployment
+      name: backend-api
+    patch: |-
+      - op: replace
+        path: /spec/template/spec/containers/0/resources/requests/cpu
+        value: '500m'
+      - op: replace
+        path: /spec/template/spec/containers/0/resources/requests/memory
+        value: 1Gi
+```
+
+### Образ `hasura/graphql-engine`
+
+Образ **`hasura/graphql-engine`**: дозволений лише канонічний тег зі списку **`allowed_hasura_images`** у rego-пакеті **`k8s.manifest`** (`policy/manifest/manifest.rego` — єдине джерело істини; допускається префікс **`docker.io/`**); решта — помилка **check k8s**.
+
+Поле **`imagePullPolicy`** скрипт **не** перевіряє.

package/rules/k8s/js/hasura_httproute.mdc

@@ -0,0 +1,91 @@
+## HTTPRoute для Deployment з `hasura/graphql-engine`
+
+**Прив'язка:** **check k8s** вважає **HTTPRoute** Hasura-маршрутом, якщо в **тому самому каталозі** є **`Deployment`** з образом **`hasura/graphql-engine`**, а його **`metadata.name`** збігається з **`metadata.name`** цього **`HTTPRoute`**.
+
+**Префікс параметризовано:** **`<prefix>`** — рядок перед **`/ql`** у першому Hasura-правилі (**`Exact <prefix>/ql`**). Може бути порожнім (**`<prefix>`** = **``**, шлях **`/ql`**) або непорожнім (наприклад **`<prefix>`** = **`/notify`**, шлях **`/notify/ql`**). Усі інші Hasura-правила цього **HTTPRoute** мають містити той самий **`<prefix>`**.
+
+**Канон — 4 правила у цьому порядку** (додаткові правила поверх канону дозволені):
+
+1. **`Exact <prefix>/ql`** → **`RequestRedirect`** **`ReplaceFullPath <prefix>/ql/console`** **`statusCode: 302`**.
+2. **`Exact <prefix>/ql/`** → те саме (редирект на **`<prefix>/ql/console`** 302).
+3. **`PathPrefix <prefix>/ql`** → **`URLRewrite`** **`ReplacePrefixMatch /`**, один **`backendRef`** на headless **Service** (**`-hl`**).
+4. **WebSocket:** **`PathPrefix <prefix>/ql`** + header **`Upgrade: websocket`** → **`URLRewrite`** **`ReplacePrefixMatch /`** + **`RequestHeaderModifier`** **`remove: [Authorization]`** (авторизація для WebSocket іде всередині messages). Той самий **`backendRef`**.
+
+**`parentRefs`**, **`hostnames`**, **`metadata.namespace`** / **`name`** підлаштуй під середовище. У **`backendRefs.name`** вказуй **headless** **Service** з суфіксом **`-hl`**; у прикладі **`db-h-hl`** заміни на фактичне ім'я.
+
+```yaml
+# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/gateway.networking.k8s.io/httproute_v1beta1.json
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: db-h
+  namespace: dev
+spec:
+  parentRefs:
+    - group: gateway.networking.k8s.io
+      kind: Gateway
+      name: gw
+      namespace: dev
+      sectionName: https
+  hostnames:
+    - aiml.live
+  rules:
+    - matches:
+        - path:
+            type: Exact
+            value: /ql
+      filters:
+        - type: RequestRedirect
+          requestRedirect:
+            path:
+              type: ReplaceFullPath
+              replaceFullPath: /ql/console
+            statusCode: 302
+    - matches:
+        - path:
+            type: Exact
+            value: /ql/
+      filters:
+        - type: RequestRedirect
+          requestRedirect:
+            path:
+              type: ReplaceFullPath
+              replaceFullPath: /ql/console
+            statusCode: 302
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /ql
+      filters:
+        - type: URLRewrite
+          urlRewrite:
+            path:
+              type: ReplacePrefixMatch
+              replacePrefixMatch: /
+      backendRefs:
+        - name: db-h-hl
+          port: 8080
+    # у websocket авторизація йде всередині messages
+    # Той самий URLRewrite, що й для HTTP: інакше бекенд бачить /ql/v1/graphql замість /v1/graphql
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /ql
+          headers:
+            - type: Exact
+              name: Upgrade
+              value: websocket
+      filters:
+        - type: URLRewrite
+          urlRewrite:
+            path:
+              type: ReplacePrefixMatch
+              replacePrefixMatch: /
+        - type: RequestHeaderModifier
+          requestHeaderModifier:
+            remove:
+              - Authorization
+      backendRefs:
+        - name: db-h-hl
+          port: 8080
+```