@nitra/cursor 1.8.106 → 1.8.108

package/mdc/js-pino.mdc

@@ -1,11 +1,11 @@
 ---
 description: Використання @nitra/pino
 alwaysApply: true
-version: '1.0'
+version: '1.1'
 ---
 
 Проект використовує @nitra/pino для логування.
-Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino.
+Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API.
 
 В **/k8s/base/configmap.yaml повинен бути заданий OTEL_RESOURCE_ATTRIBUTES: 'service.name=<project_name>,service.namespace=<project_namespace>'
 а в директоріях з kustomize повинні бути перевизначені значення OTEL_RESOURCE_ATTRIBUTES і в них service.namespace повинен відповідати namespace, в якому знаходиться дана директорія.

package/mdc/k8s.mdc

@@ -110,7 +110,16 @@ resources: {}
 
 ### HTTPRoute для Deployment з `hasura/graphql-engine`
 
-Якщо для такого **Deployment** описано **`HTTPRoute`**, **`spec.rules`** мають відповідати канону нижче: редірект **`/ql`** та **`/ql/`** на **`/ql/console`** (**`302`**), правило з **`PathPrefix` `/ql`**, **`URLRewrite`** префікса на **`/`**, окреме правило для **WebSocket** (**`Upgrade: websocket`**) з **`RequestHeaderModifier`** (прибрати **`Authorization`** — авторизація для WebSocket іде всередині messages), далі **`PathPrefix` `/`** на той самий backend.
+**Прив'язка:** **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`** (див. розділ **«Service: `svc.yaml` і `svc-hl.yaml`»**); у прикладі **`db-h-hl`** заміни на фактичне ім’я.
 
@@ -278,7 +287,7 @@ patches:
 
 **`npx @nitra/cursor check k8s`** — програмні критерії в **JSDoc на початку** **`npm/scripts/check-k8s.mjs`**. Якщо під **`k8s`** немає **`*.yaml`** — крок пропущено. Канон **`$schema`** для редактора — розділ **«Визначення схеми YAML`** нижче.
 
-**Не входить у check k8s:** наприклад повна структура **`HTTPRoute`** для **Hasura** (канон — у розділі про **`hasura/graphql-engine`**), **kubeconform** / **kubescape** — це **`bun run lint-k8s`**.
+**Не входить у check k8s:** **kubeconform** / **kubescape** — це **`bun run lint-k8s`**.
 
 ## Коли застосовувати (агентам)
 

package/mdc/text.mdc

@@ -120,7 +120,7 @@ version: '1.25'
     "lint-text": "npx cspell . && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
   },
   "devDependencies": {
-    "@nitra/cspell-dict": "^2.0.0"
+    "@nitra/cspell-dict": "^2.1.0"
   }
 }
 ```
@@ -235,7 +235,7 @@ jobs:
     "lint-text": "npx cspell . && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
   },
   "devDependencies": {
-    "@nitra/cspell-dict": "^2.0.0"
+    "@nitra/cspell-dict": "^2.1.0"
   }
 }
 ```
@@ -252,7 +252,7 @@ jobs:
     "lint-text": "npx cspell . && bunx markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdc\" && bun ./npm/scripts/run-v8r.mjs"
   },
   "devDependencies": {
-    "@nitra/cspell-dict": "^2.0.0"
+    "@nitra/cspell-dict": "^2.1.0"
   }
 }
 ```

package/package.json

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

package/scripts/check-js-pino.mjs

@@ -1,16 +1,56 @@
 /**
  * Для кожного workspace-пакета перевіряє правило js-pino.mdc.
  *
- * Заборона bunyan на користь pino та наявність `OTEL_RESOURCE_ATTRIBUTES` у `k8s/base/configmap.yaml`,
- * якщо такий файл існує.
+ * Заборона `@nitra/bunyan` / `bunyan` як у залежностях `package.json`, так і в коді
+ * (`import` / `require` / динамічний `import()`); наявність `OTEL_RESOURCE_ATTRIBUTES`
+ * у `k8s/base/configmap.yaml`, якщо такий файл існує.
+ *
+ * Імпорти в джерелах сканує AST через `oxc-parser` (див. `utils/bunyan-imports.mjs`),
+ * щоб виявити випадки на кшталт `import log from '@nitra/bunyan'`, які лишаються в коді
+ * після підміни залежності.
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
+import {
+  findBunyanImportsInText,
+  isBunyanScanSourceFile,
+  shouldSkipFileForBunyanScan
+} from './utils/bunyan-imports.mjs'
 import { createCheckReporter } from './utils/check-reporter.mjs'
+import { walkDir } from './utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 
+/**
+ * Сканує джерела пакета на заборонені імпорти `@nitra/bunyan` / `bunyan`.
+ * @param {string} absPackageRoot абсолютний шлях до кореня пакета
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість знайдених порушень
+ */
+async function checkBunyanImports(absPackageRoot, label, fail) {
+  /** @type {string[]} */
+  const sourcePaths = []
+  await walkDir(absPackageRoot, absPath => {
+    const rel = relative(absPackageRoot, absPath).split('\\').join('/')
+    if (!shouldSkipFileForBunyanScan(rel) && isBunyanScanSourceFile(rel)) {
+      sourcePaths.push(absPath)
+    }
+  })
+
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relative(absPackageRoot, absPath).split('\\').join('/')
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findBunyanImportsInText(content, rel)) {
+      violations++
+      fail(`${label}${rel}:${v.line} — заміни '${v.module}' на '@nitra/pino': ${v.snippet}`)
+    }
+  }
+  return violations
+}
+
 /**
  * Перевіряє відповідність правилам js-pino.mdc для одного workspace-пакета.
  * @param {string} rootDir відносний шлях workspace (не `'.'`)
@@ -33,6 +73,11 @@ async function checkWorkspacePackage(rootDir, fail, passFn) {
     }
   }
 
+  const importViolations = await checkBunyanImports(join(process.cwd(), rootDir), label, fail)
+  if (importViolations === 0) {
+    passFn(`${label}немає імпортів '@nitra/bunyan' / 'bunyan' у джерелах`)
+  }
+
   const configmapPath = join(rootDir, 'k8s/base/configmap.yaml')
   if (existsSync(configmapPath)) {
     const content = await readFile(configmapPath, 'utf8')

package/scripts/check-k8s.mjs

@@ -55,7 +55,7 @@
  * компонент). Спочатку шукається збіг за фактичним `type`, потім за **`*`**.
  * Dockerfile — правило docker.mdc, скрипт check-docker.mjs.
  *
- * Структура **`HTTPRoute`** для **Deployment** з образом **`hasura/graphql-engine`** (редиректи **`/ql`**, **WebSocket**, **`URLRewrite`**) — лише в **k8s.mdc**, автоматично не звіряється.
+ * **Структура `HTTPRoute` для Hasura-Deployment:** звіряється канон 4 правил у **`spec.rules`** (редиректи **`<prefix>/ql`** і **`<prefix>/ql/`** на **`<prefix>/ql/console`** 302, **`PathPrefix <prefix>/ql`** + **URLRewrite** на **`/`**, окреме WebSocket-правило з **`RequestHeaderModifier`** remove **`Authorization`**). **Префікс параметризовано** (рядок перед **`/ql`** у першому Hasura-правилі). **Прив'язка** — за **`metadata.name`** у тому ж каталозі, що й **Deployment** з образом **`hasura/graphql-engine`** (див. k8s.mdc). **Додаткові правила** поверх канону дозволені.
  */
 import { existsSync } from 'node:fs'
 import { readFile, stat, unlink } from 'node:fs/promises'
@@ -1924,6 +1924,41 @@ export function deploymentHasuraGraphqlEngineImageViolation(manifest) {
   return hasuraGraphqlEngineViolationInContainerList('initContainers', podSpec.initContainers)
 }
 
+/**
+ * Чи у списку контейнерів є хоча б один з образом **hasura/graphql-engine** (будь-який тег).
+ * @param {unknown} containers значення **containers** / **initContainers** із podSpec
+ * @returns {boolean} true — якщо знайдено хоча б один контейнер з образом Hasura
+ */
+function containerListHasHasuraImage(containers) {
+  if (!Array.isArray(containers)) return false
+  for (const c of containers) {
+    if (c !== null && typeof c === 'object' && !Array.isArray(c)) {
+      const image = /** @type {Record<string, unknown>} */ (c).image
+      if (typeof image === 'string' && image !== '' && isHasuraGraphqlEngineImageRef(image)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Чи **Deployment** використовує образ **hasura/graphql-engine** у будь-якому контейнері (маркер для прив'язки HTTPRoute-канона).
+ * @param {unknown} manifest корінь YAML-документа
+ * @returns {boolean} true — для Deployment з Hasura-контейнером у containers / initContainers
+ */
+export function isHasuraDeploymentManifest(manifest) {
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) return false
+  const rec = /** @type {Record<string, unknown>} */ (manifest)
+  if (rec.kind !== 'Deployment') return false
+  const spec = rec.spec
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) return false
+  const template = /** @type {Record<string, unknown>} */ (spec).template
+  if (template === null || typeof template !== 'object' || Array.isArray(template)) return false
+  const podSpec = /** @type {Record<string, unknown>} */ (template).spec
+  if (podSpec === null || typeof podSpec !== 'object' || Array.isArray(podSpec)) return false
+  const p = /** @type {Record<string, unknown>} */ (podSpec)
+  return containerListHasHasuraImage(p.containers) || containerListHasHasuraImage(p.initContainers)
+}
+
 /**
  * Чи **Service** містить заборонені анотації GKE у **`metadata.annotations`** (k8s.mdc).
  * @param {unknown} manifest корінь YAML-документа
@@ -2154,6 +2189,247 @@ function scanGatewayApiRouteBackendRefsInYamlBody(rel, body, fail) {
   }
 }
 
+/**
+ * Звузити `unknown` до `Record<string, unknown>` (`null`, масиви, примітиви → null).
+ * @param {unknown} node довільний вузол YAML-документа
+ * @returns {Record<string, unknown> | null} plain-об'єкт або null, якщо це не plain-запис
+ */
+function asPlainRecord(node) {
+  if (node === null || node === undefined || typeof node !== 'object' || Array.isArray(node)) return null
+  return /** @type {Record<string, unknown>} */ (node)
+}
+
+/**
+ * Чи `match` — рівно один шлях заданого типу з потрібним значенням, **без** `headers`.
+ * @param {unknown} rule одне правило `HTTPRoute`
+ * @param {'Exact' | 'PathPrefix'} pathType очікуваний `path.type`
+ * @param {string} pathValue очікуваний `path.value`
+ * @returns {boolean} true — якщо `matches` рівно один і відповідає критерію
+ */
+function hasuraRuleMatchesSinglePathNoHeaders(rule, pathType, pathValue) {
+  const r = asPlainRecord(rule)
+  if (r === null) return false
+  const matches = r.matches
+  if (!Array.isArray(matches) || matches.length !== 1) return false
+  const m = asPlainRecord(matches[0])
+  if (m === null) return false
+  if (m.headers !== undefined) return false
+  const p = asPlainRecord(m.path)
+  if (p === null) return false
+  return p.type === pathType && p.value === pathValue
+}
+
+/**
+ * Чи **filters** — рівно один `RequestRedirect` з `ReplaceFullPath` на `toPath` і `statusCode: 302`.
+ * @param {unknown} rule одне правило `HTTPRoute`
+ * @param {string} toPath очікуваний `requestRedirect.path.replaceFullPath`
+ * @returns {boolean} true — якщо filters відповідають канону редиректу
+ */
+function hasuraRuleHasExactRedirect(rule, toPath) {
+  const r = asPlainRecord(rule)
+  if (r === null) return false
+  const filters = r.filters
+  if (!Array.isArray(filters) || filters.length !== 1) return false
+  const f = asPlainRecord(filters[0])
+  if (f === null || f.type !== 'RequestRedirect') return false
+  const rr = asPlainRecord(f.requestRedirect)
+  if (rr === null || rr.statusCode !== 302) return false
+  const p = asPlainRecord(rr.path)
+  return p !== null && p.type === 'ReplaceFullPath' && p.replaceFullPath === toPath
+}
+
+/**
+ * Чи серед **filters** є `URLRewrite` з `ReplacePrefixMatch: /`.
+ * @param {unknown[]} filters масив filters з одного правила `HTTPRoute`
+ * @returns {boolean} true — якщо фільтр `URLRewrite` має `ReplacePrefixMatch: /`
+ */
+function hasuraFiltersIncludeUrlRewriteToSlash(filters) {
+  for (const f of filters) {
+    const fr = asPlainRecord(f)
+    if (fr !== null && fr.type === 'URLRewrite') {
+      const rw = asPlainRecord(fr.urlRewrite)
+      if (rw === null) return false
+      const p = asPlainRecord(rw.path)
+      return p !== null && p.type === 'ReplacePrefixMatch' && p.replacePrefixMatch === '/'
+    }
+  }
+  return false
+}
+
+/**
+ * Чи серед **filters** є `RequestHeaderModifier` з `remove: [Authorization]`.
+ * @param {unknown[]} filters масив filters з одного правила `HTTPRoute`
+ * @returns {boolean} true — якщо фільтр `RequestHeaderModifier` видаляє саме `Authorization`
+ */
+function hasuraFiltersRemoveAuthorization(filters) {
+  for (const f of filters) {
+    const fr = asPlainRecord(f)
+    if (fr !== null && fr.type === 'RequestHeaderModifier') {
+      const mod = asPlainRecord(fr.requestHeaderModifier)
+      if (mod === null) return false
+      const remove = mod.remove
+      if (!Array.isArray(remove) || remove.length !== 1) return false
+      return remove[0] === 'Authorization'
+    }
+  }
+  return false
+}
+
+/**
+ * Ім'я єдиного `backendRef` у правилі (або null, якщо backend-ів не рівно один).
+ * @param {unknown} rule одне правило `HTTPRoute`
+ * @returns {string | null} `backendRefs[0].name` або null, якщо backend-ів не рівно один
+ */
+function hasuraRuleSingleBackendName(rule) {
+  const r = asPlainRecord(rule)
+  if (r === null) return null
+  const refs = r.backendRefs
+  if (!Array.isArray(refs) || refs.length !== 1) return null
+  const b = asPlainRecord(refs[0])
+  if (b === null || typeof b.name !== 'string') return null
+  return b.name
+}
+
+/**
+ * Правило 3: `PathPrefix <qlPath>` + **filters** = 1 × `URLRewrite(ReplacePrefixMatch: /)`.
+ * @param {unknown} rule одне правило `HTTPRoute`
+ * @param {string} qlPath очікуваний `path.value` (`<prefix>/ql`)
+ * @returns {boolean} true — якщо правило відповідає канону пункту 3
+ */
+function hasuraRuleIsQlUrlRewrite(rule, qlPath) {
+  if (!hasuraRuleMatchesSinglePathNoHeaders(rule, 'PathPrefix', qlPath)) return false
+  const r = asPlainRecord(rule)
+  if (r === null) return false
+  const filters = r.filters
+  if (!Array.isArray(filters) || filters.length !== 1) return false
+  return hasuraFiltersIncludeUrlRewriteToSlash(filters)
+}
+
+/**
+ * Правило 4: WebSocket — `PathPrefix <qlPath>` + `Upgrade: websocket`, **filters** = `URLRewrite` + `RequestHeaderModifier(remove Authorization)`.
+ * @param {unknown} rule одне правило `HTTPRoute`
+ * @param {string} qlPath очікуваний `path.value` (`<prefix>/ql`)
+ * @returns {boolean} true — якщо правило відповідає канону пункту 4 (WebSocket)
+ */
+function hasuraRuleIsWebsocket(rule, qlPath) {
+  const r = asPlainRecord(rule)
+  if (r === null) return false
+  const matches = r.matches
+  if (!Array.isArray(matches) || matches.length !== 1) return false
+  const m = asPlainRecord(matches[0])
+  if (m === null) return false
+  const p = asPlainRecord(m.path)
+  if (p === null || p.type !== 'PathPrefix' || p.value !== qlPath) return false
+  const headers = m.headers
+  if (!Array.isArray(headers) || headers.length !== 1) return false
+  const h = asPlainRecord(headers[0])
+  if (h === null || h.type !== 'Exact' || h.name !== 'Upgrade' || h.value !== 'websocket') return false
+  const filters = r.filters
+  if (!Array.isArray(filters) || filters.length !== 2) return false
+  return hasuraFiltersIncludeUrlRewriteToSlash(filters) && hasuraFiltersRemoveAuthorization(filters)
+}
+
+/**
+ * Знаходить перше правило з **`matches`** = `[{ path: { type: 'Exact', value: '<prefix>/ql' } }]` (без headers),
+ * повертає `<prefix>` (може бути порожнім) і позицію правила 1.
+ * @param {unknown[]} rules вміст `spec.rules` HTTPRoute
+ * @returns {{ prefix: string, startIndex: number } | null} виявлений префікс і позиція правила 1 або null
+ */
+function findHasuraCanonStart(rules) {
+  for (let i = 0; i < rules.length; i++) {
+    const r = asPlainRecord(rules[i])
+    const matches = r === null ? null : r.matches
+    if (!Array.isArray(matches) || matches.length !== 1) {
+      // наступне правило
+    } else {
+      const m = asPlainRecord(matches[0])
+      const p = m === null || m.headers !== undefined ? null : asPlainRecord(m.path)
+      if (
+        p !== null &&
+        p.type === 'Exact' &&
+        typeof p.value === 'string' &&
+        p.value.endsWith('/ql')
+      ) {
+        return { prefix: p.value.slice(0, -'/ql'.length), startIndex: i }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Знаходить перше правило за індексом ≥ `from`, що задовольняє `predicate`. Повертає індекс або -1.
+ * @param {unknown[]} rules вміст `spec.rules` HTTPRoute
+ * @param {number} from мінімальний індекс, з якого починати пошук
+ * @param {(rule: unknown) => boolean} predicate предикат на одне правило
+ * @returns {number} індекс знайденого правила або -1
+ */
+function findHasuraRule(rules, from, predicate) {
+  for (let i = from; i < rules.length; i++) {
+    if (predicate(rules[i])) return i
+  }
+  return -1
+}
+
+/**
+ * Чи **`HTTPRoute`** порушує канон 4 правил Hasura (див. k8s.mdc).
+ * Повертає текст порушення або null, якщо канон витримано. Додаткові правила поверх канону допускаються.
+ * @param {unknown} manifest корінь YAML-документа
+ * @returns {string | null} текст порушення або null, якщо канон витримано
+ */
+export function httpRouteHasuraCanonViolation(manifest) {
+  const rec = asPlainRecord(manifest)
+  if (rec === null) return null
+  const spec = asPlainRecord(rec.spec)
+  if (spec === null) return 'HTTPRoute без spec — канон Hasura вимагає 4 правил (див. k8s.mdc)'
+  const rules = spec.rules
+  if (!Array.isArray(rules) || rules.length === 0) {
+    return 'spec.rules порожній — канон Hasura вимагає 4 правил у порядку (див. k8s.mdc)'
+  }
+  const start = findHasuraCanonStart(rules)
+  if (start === null) {
+    return 'не знайдено правило 1 Hasura-канона: Exact "<prefix>/ql" + RequestRedirect ReplaceFullPath "<prefix>/ql/console" statusCode 302 (див. k8s.mdc)'
+  }
+  const { prefix, startIndex } = start
+  const qlPath = `${prefix}/ql`
+  const qlSlashPath = `${prefix}/ql/`
+  const consolePath = `${prefix}/ql/console`
+
+  if (!hasuraRuleHasExactRedirect(rules[startIndex], consolePath)) {
+    return `правило 1 Hasura-канона (rules[${startIndex}], prefix «${prefix}»): Exact "${qlPath}" має мати RequestRedirect ReplaceFullPath "${consolePath}" statusCode 302 (див. k8s.mdc)`
+  }
+
+  const i2 = findHasuraRule(
+    rules,
+    startIndex + 1,
+    r => hasuraRuleMatchesSinglePathNoHeaders(r, 'Exact', qlSlashPath) && hasuraRuleHasExactRedirect(r, consolePath)
+  )
+  if (i2 === -1) {
+    return `правило 2 Hasura-канона: після правила 1 має бути Exact "${qlSlashPath}" + RequestRedirect ReplaceFullPath "${consolePath}" statusCode 302 (див. k8s.mdc)`
+  }
+
+  const i3 = findHasuraRule(
+    rules,
+    i2 + 1,
+    r => hasuraRuleIsQlUrlRewrite(r, qlPath) && hasuraRuleSingleBackendName(r) !== null
+  )
+  if (i3 === -1) {
+    return `правило 3 Hasura-канона: після правила 2 має бути PathPrefix "${qlPath}" + URLRewrite ReplacePrefixMatch "/" + один backendRef на headless Service (див. k8s.mdc)`
+  }
+  const backendName = /** @type {string} */ (hasuraRuleSingleBackendName(rules[i3]))
+
+  const i4 = findHasuraRule(
+    rules,
+    i3 + 1,
+    r => hasuraRuleIsWebsocket(r, qlPath) && hasuraRuleSingleBackendName(r) === backendName
+  )
+  if (i4 === -1) {
+    return `правило 4 Hasura-канона (WebSocket): після правила 3 має бути PathPrefix "${qlPath}" + header "Upgrade: websocket" + URLRewrite ReplacePrefixMatch "/" + RequestHeaderModifier remove [Authorization] + backendRef «${backendName}» (див. k8s.mdc)`
+  }
+
+  return null
+}
+
 /**
  * Збирає **`metadata.name`** для **kind: Service** у коренях документів; при помилці викликає **fail** і повертає false.
  * @param {Record<string, unknown>[]} roots корені YAML-документів
@@ -2300,6 +2576,113 @@ async function validateSvcYamlAndSvcHlPairs(root, yamlFiles, fail) {
   }
 }
 
+/**
+ * Індексує Hasura-Deployment-и за каталогом (ключ — абсолютний шлях каталогу, значення — множина `metadata.name`).
+ * Паралельно збирає всі `kind: HTTPRoute` Gateway API (`gateway.networking.k8s.io/*`) із doc-індексом.
+ * @param {string[]} yamlFiles абсолютні шляхи до `*.yaml` під `k8s`
+ * @returns {Promise<{
+ *   hasuraByDir: Map<string, Set<string>>,
+ *   httpRoutes: { abs: string, dir: string, docIndex: number, obj: Record<string, unknown> }[]
+ * }>} індекс Hasura-Deployment-ів за каталогом і список HTTPRoute-документів
+ */
+async function collectHasuraDeploymentsAndHttpRoutes(yamlFiles) {
+  /** @type {Map<string, Set<string>>} */
+  const hasuraByDir = new Map()
+  /** @type {{ abs: string, dir: string, docIndex: number, obj: Record<string, unknown> }[]} */
+  const httpRoutes = []
+
+  for (const abs of yamlFiles) {
+    await indexOneK8sYamlForHasuraCanon(abs, hasuraByDir, httpRoutes)
+  }
+
+  return { hasuraByDir, httpRoutes }
+}
+
+/**
+ * Читає один YAML і додає Hasura-Deployment-и / HTTPRoute-документи до відповідних колекцій (нещасливі читання ігнорує).
+ * @param {string} abs абсолютний шлях до файлу
+ * @param {Map<string, Set<string>>} hasuraByDir індекс Hasura Deployment-ів за каталогом
+ * @param {{ abs: string, dir: string, docIndex: number, obj: Record<string, unknown> }[]} httpRoutes колектор HTTPRoute-документів
+ * @returns {Promise<void>}
+ */
+async function indexOneK8sYamlForHasuraCanon(abs, hasuraByDir, httpRoutes) {
+  let raw
+  try {
+    raw = await readFile(abs, 'utf8')
+  } catch {
+    return
+  }
+  const lines = toLines(raw)
+  const body = lines.length > 0 && MODELINE_RE.test(lines[0]) ? yamlBodyAfterModeline(lines) : lines.join('\n')
+  /** @type {import('yaml').Document[]} */
+  let docs
+  try {
+    docs = parseAllDocuments(body)
+  } catch {
+    return
+  }
+  const dir = dirname(abs)
+
+  for (const [di, doc] of docs.entries()) {
+    if (doc.errors.length === 0) {
+      const rec = asPlainRecord(doc.toJSON())
+      if (rec !== null) {
+        recordHasuraDeploymentName(rec, dir, hasuraByDir)
+        const av = rec.apiVersion
+        if (rec.kind === 'HTTPRoute' && typeof av === 'string' && av.startsWith(GATEWAY_API_GROUP_PREFIX)) {
+          httpRoutes.push({ abs, dir, docIndex: di + 1, obj: rec })
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Якщо документ — Hasura-Deployment із непорожнім `metadata.name`, додає ім'я до індексу за каталогом.
+ * @param {Record<string, unknown>} rec корінь YAML-документа
+ * @param {string} dir абсолютний шлях до каталогу файлу
+ * @param {Map<string, Set<string>>} hasuraByDir індекс Hasura Deployment-ів за каталогом (мутується)
+ * @returns {void}
+ */
+function recordHasuraDeploymentName(rec, dir, hasuraByDir) {
+  if (!isHasuraDeploymentManifest(rec)) return
+  const meta = asPlainRecord(rec.metadata)
+  const name = meta === null ? undefined : meta.name
+  if (typeof name !== 'string' || name === '') return
+  let set = hasuraByDir.get(dir)
+  if (set === undefined) {
+    set = new Set()
+    hasuraByDir.set(dir, set)
+  }
+  set.add(name)
+}
+
+/**
+ * Для кожного `kind: HTTPRoute`, що прив'язаний до **Hasura-Deployment** у тому самому каталозі за **`metadata.name`**,
+ * звіряє канон 4 правил (див. `httpRouteHasuraCanonViolation` і k8s.mdc).
+ * @param {string} root корінь репозиторію
+ * @param {string[]} yamlFiles абсолютні шляхи до `*.yaml` під `k8s`
+ * @param {(msg: string) => void} fail callback реєстрації помилки
+ * @returns {Promise<void>}
+ */
+async function validateHasuraHttpRouteCanon(root, yamlFiles, fail) {
+  const { hasuraByDir, httpRoutes } = await collectHasuraDeploymentsAndHttpRoutes(yamlFiles)
+  if (hasuraByDir.size === 0 || httpRoutes.length === 0) return
+
+  for (const hr of httpRoutes) {
+    const meta = asPlainRecord(hr.obj.metadata)
+    const name = meta === null ? undefined : meta.name
+    const set = typeof name === 'string' && name !== '' ? hasuraByDir.get(hr.dir) : undefined
+    if (set !== undefined && typeof name === 'string' && set.has(name)) {
+      const v = httpRouteHasuraCanonViolation(hr.obj)
+      if (v !== null) {
+        const rel = (relative(root, hr.abs) || hr.abs).replaceAll('\\', '/')
+        fail(`${rel}: HTTPRoute «${name}» (документ ${hr.docIndex}; прив'язано до Hasura-Deployment у тому ж каталозі): ${v}`)
+      }
+    }
+  }
+}
+
 /**
  * Для маніфестів, **підключених** до Kustomize (шлях у `resources` / `patches` / …), **metadata.namespace** не додають.
  * @param {unknown} manifest корінь YAML-документа
@@ -2811,6 +3194,8 @@ export async function check() {
 
   await validateSvcYamlAndSvcHlPairs(root, yamlFiles, fail)
 
+  await validateHasuraHttpRouteCanon(root, yamlFiles, fail)
+
   await validateKustomizationIncludesSvcHlWithSvc(root, yamlFiles, fail)
 
   await validateKustomizationJson6902NoRemoveAddSamePath(root, yamlFiles, fail)

package/scripts/utils/bunyan-imports.mjs

@@ -0,0 +1,182 @@
+/**
+ * Знаходить імпорти з `@nitra/bunyan` (і застарілого `bunyan`) у джерелах — їх треба замінити
+ * на `@nitra/pino` згідно з js-pino.mdc.
+ *
+ * Семантика береться з **oxc-parser** (`module.staticImports`) — без regex по тілу файлу.
+ * Додатково по AST програми ловимо `require('@nitra/bunyan')` і динамічний `import('@nitra/bunyan')`,
+ * щоб правило працювало й у CommonJS/інлайн-завантаженні.
+ *
+ * Сканер не вимагає, щоб файл компілювався: при синтаксичних помилках повертається порожній
+ * результат — спочатку треба полагодити синтаксис, потім перезапустити перевірку.
+ */
+import { parseSync } from 'oxc-parser'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/
+const FORBIDDEN_MODULES = new Set(['@nitra/bunyan', 'bunyan'])
+
+/**
+ * Мова для Oxc за шляхом файлу (розширення).
+ * @param {string} filePath віртуальний або реальний шлях до файлу
+ * @returns {'js' | 'jsx' | 'ts' | 'tsx'} значення опції `lang` для `parseSync`
+ */
+function langFromPath(filePath) {
+  const lower = filePath.toLowerCase()
+  if (lower.endsWith('.tsx')) {
+    return 'tsx'
+  }
+  if (lower.endsWith('.ts') || lower.endsWith('.mts') || lower.endsWith('.cts')) {
+    return 'ts'
+  }
+  if (lower.endsWith('.jsx')) {
+    return 'jsx'
+  }
+  return 'js'
+}
+
+/**
+ * Номер рядка (1-based) за зміщенням у буфері.
+ * @param {string} content повний текст файлу
+ * @param {number} offset байтове зміщення початку фрагмента
+ * @returns {number} номер рядка від 1
+ */
+function offsetToLine(content, offset) {
+  let line = 1
+  const n = Math.min(offset, content.length)
+  for (let i = 0; i < n; i++) {
+    if (content.codePointAt(i) === 10) {
+      line++
+    }
+  }
+  return line
+}
+
+/**
+ * Стискає пробіли для повідомлення про порушення.
+ * @param {string} s фрагмент коду
+ * @returns {string} скорочений однорядковий рядок
+ */
+function normalizeSnippet(s) {
+  return s.replaceAll(/\s+/g, ' ').trim().slice(0, 160)
+}
+
+/**
+ * Перевіряє, чи це виклик `require('<module>')` з рядковим аргументом.
+ * @param {any} node вузол AST
+ * @returns {string | null} ім'я модуля з аргументу, інакше `null`
+ */
+function requireCallModule(node) {
+  if (!node || node.type !== 'CallExpression') return null
+  const callee = node.callee
+  if (!callee || callee.type !== 'Identifier' || callee.name !== 'require') return null
+  const arg = node.arguments?.[0]
+  if (!arg || arg.type !== 'Literal' || typeof arg.value !== 'string') return null
+  return arg.value
+}
+
+/**
+ * Перевіряє, чи це динамічний `import('<module>')` з рядковим аргументом.
+ * @param {any} node вузол AST
+ * @returns {string | null} ім'я модуля, інакше `null`
+ */
+function dynamicImportModule(node) {
+  if (!node || node.type !== 'ImportExpression') return null
+  const src = node.source
+  if (!src || src.type !== 'Literal' || typeof src.value !== 'string') return null
+  return src.value
+}
+
+/**
+ * Простий рекурсивний обхід AST: заходимо в усі об'єкти/масиви, щоб знайти require/import-вузли.
+ * @param {any} node корінь або під-вузол AST
+ * @param {(n: any) => void} visit виклик для кожного об'єкта-вузла
+ * @returns {void}
+ */
+function walkAst(node, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkAst(item, visit)
+    return
+  }
+  if (typeof node.type === 'string') {
+    visit(node)
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'parent') continue
+    const v = node[key]
+    if (v && typeof v === 'object') walkAst(v, visit)
+  }
+}
+
+/**
+ * Знаходить заборонені імпорти/require з `@nitra/bunyan` у тексті.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/foo.ts`)
+ * @returns {{ line: number, snippet: string, module: string }[]} список порушень
+ */
+export function findBunyanImportsInText(content, virtualPath = 'scan.ts') {
+  const pathForLang = virtualPath || 'scan.ts'
+  const lang = langFromPath(pathForLang)
+  let result
+  try {
+    result = parseSync(pathForLang, content, { lang, sourceType: 'module' })
+  } catch {
+    return []
+  }
+  if (result.errors?.length) {
+    return []
+  }
+
+  /** @type {{ line: number, snippet: string, module: string }[]} */
+  const out = []
+
+  for (const imp of result.module?.staticImports ?? []) {
+    const mod = imp.moduleRequest?.value
+    if (mod && FORBIDDEN_MODULES.has(mod)) {
+      out.push({
+        line: offsetToLine(content, imp.start),
+        snippet: normalizeSnippet(content.slice(imp.start, imp.end)),
+        module: mod
+      })
+    }
+  }
+
+  walkAst(result.program, node => {
+    const reqMod = requireCallModule(node)
+    if (reqMod && FORBIDDEN_MODULES.has(reqMod)) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        module: reqMod
+      })
+      return
+    }
+    const dynMod = dynamicImportModule(node)
+    if (dynMod && FORBIDDEN_MODULES.has(dynMod)) {
+      out.push({
+        line: offsetToLine(content, node.start),
+        snippet: normalizeSnippet(content.slice(node.start, node.end)),
+        module: dynMod
+      })
+    }
+  })
+
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я).
+ * @param {string} relativePath відносний шлях до файлу
+ * @returns {boolean} `true`, якщо розширення підходить для пошуку імпорту
+ */
+export function isBunyanScanSourceFile(relativePath) {
+  return SOURCE_FILE_RE.test(relativePath)
+}
+
+/**
+ * Чи слід пропустити файл під час обходу пакета (декларації типів).
+ * @param {string} relativePosix шлях з posix-слешами
+ * @returns {boolean} `true`, якщо файл не сканувати
+ */
+export function shouldSkipFileForBunyanScan(relativePosix) {
+  return relativePosix.endsWith('.d.ts')
+}