@nitra/cursor 3.27.0 → 3.29.0

package/rules/js-lint/js/lint-findings.mjs

@@ -1,10 +1,4 @@
-/**
- * Нормалізація й класифікація lint-findings (oxlint + eslint) на introduced
- * (рядок у diff від HEAD) vs pre-existing (борг файлу) — беклог #6, варіант A.
- *
- * Формати: oxlint `--format=json` → `{ diagnostics:[{ filename, code, labels:[{span:{line}}] }] }`;
- * eslint `--format=json` → `[{ filePath, messages:[{ ruleId, line, message }] }]`. Шляхи абсолютні.
- */
+/** @see ./docs/lint-findings.md */
 import { isAbsolute, relative } from 'node:path'
 
 import { isIntroducedLine } from '../../../scripts/lib/diff-added-lines.mjs'

package/rules/js-lint/js/lint.mjs

@@ -1,13 +1,4 @@
-/**
- * Quick-крок lint правила js-lint: oxlint + eslint (з автофіксом).
- *
- * Викликається lint-оркестратором (`n-cursor lint` / `lint-ci`):
- *  - `files` = масив змінених файлів (quick) → лінтимо лише js-подібні з них і
- *    КЛАСИФІКУЄМО лишені findings на introduced (рядок у diff від HEAD) vs
- *    pre-existing (борг файлу) — беклог #6, варіант A (видимість; блокування без змін);
- *  - `files` = undefined (ci) → лінтимо весь проєкт (стрімінг, без класифікації).
- * Крос-файлові jscpd/knip — окреме правило js-lint-ci (фаза ci).
- */
+/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
 import { addedLinesByFile } from '../../../scripts/lib/diff-added-lines.mjs'

package/rules/js-lint/js/tooling.mjs

@@ -1,16 +1,4 @@
-/**
- * Перевіряє лінт JavaScript за правилом js-lint.mdc.
- *
- * Flat ESLint з getConfig і ignore для auto-imports,
- * `.oxlintrc.json` має збігатися з каноном oxlint у пакеті (`npm/rules/js-lint/js/data/tooling/oxlint-canonical.json`):
- * plugins, jsPlugins, categories, усі правила з канону (додаткові записи в `rules` дозволені), settings, env,
- * globals, ignorePatterns. Також перевіряє workspace `package.json` на `type: "module"`
- * і `engines`, workflow-дубль у `lint.yml`, `knip.json` autofill і застарілі `.eslintrc*`.
- *
- * Per-document вимоги (`lint-js`, `@nitra/eslint-config`, root `engines`, `.jscpd.json`,
- * `.vscode/extensions.json`, `lint-js.yml`) — у policy-пакетах `js_lint.*`.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { copyFile, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'

package/rules/js-lint/js/utils_imports.mjs

@@ -1,21 +1,4 @@
-/**
- * Перевіряє, що файли всередині будь-якого `utils/` каталогу не мають імпортів за межі
- * самого каталогу (relative-import з `..`). За правилом `js-lint.mdc` каталог `utils/` — це
- * generic helpers без бізнес-логіки і без залежностей від домену; якщо файлу потрібен
- * сусідній модуль, конфіг проєкту чи cross-rule helper — він має жити в `lib/`, а не в `utils/`.
- *
- * Перевіряються лише не-тестові `.mjs|.mts|.cjs|.cts|.js|.ts|.jsx|.tsx` під будь-яким
- * `utils/`-каталогом у monorepo-воркспейсах. Файли всередині `utils/tests/` (тести)
- * і будь-які `__fixtures__/` ігноруються — тести легально імпортують свій модуль через `../X`.
- *
- * Дозволені імпорти:
- *  - `./X`, `./sub/X` — same-dir чи глибше всередині самої `utils/`
- *  - bare-package (`oxc-parser`, `@scope/pkg`) — npm-залежність
- *  - `node:fs`, `fs` тощо — Node-builtin
- *
- * Заборонено:
- *  - будь-який `..`-шлях (`../X`, `../../X`) — це порушення granular `utils/`-кордону
- */
+/** @see ./docs/utils_imports.md */
 import { readdir, readFile } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
 

package/rules/js-lint-ci/js/lint.mjs

@@ -1,9 +1,4 @@
-/**
- * Ci-крок: jscpd (детектор клонів) + knip (невикористані експорти).
- *
- * Крос-файлові аналізатори — працюють лише по всьому репо, тож `files` ігнорується
- * (викликається лише у `lint-ci` з undefined). Per-file режиму ці інструменти не мають.
- */
+/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
 /**

package/rules/js-mssql/js/deps.mjs

@@ -1,13 +1,4 @@
-/**
- * Перевіряє правило js-mssql.mdc.
- *
- * Якщо в будь-якому `package.json` у репозиторії (включно з workspace-пакетами) в секції `dependencies`
- * присутній пакет `mssql`, його версія має бути не менше 12.5.0.
- *
- * Додатково, якщо `mssql` використовується в репозиторії, перевіряє що підключення
- * не створюється “на кожен запит”: `new sql.ConnectionPool(...)` не має знаходитись
- * всередині функцій. Пул має бути singleton (на рівні модуля) і повторно використовуватись.
- */
+/** @see ./docs/deps.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

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

@@ -1,40 +1,4 @@
-/**
- * Для кожного workspace-пакета перевіряє правило js-run.mdc.
- *
- * Покрито:
- *  - заборона `@nitra/bunyan` / `bunyan` як у залежностях `package.json`, так і в коді
- *    (`import` / `require` / динамічний `import()`); імпорти сканує AST через `oxc-parser`
- *    (див. `utils/bunyan-imports.mjs`);
- *  - наявність `OTEL_RESOURCE_ATTRIBUTES` зі значеннями `service.name=` та `service.namespace=`
- *    у `k8s/base/configmap.yaml`, якщо такий файл існує (відповідність імені ConfigMap імені
- *    Deployment перевіряється в `rules/k8s/fix.mjs`);
- *  - «Внутрішні аліаси» (`#conn/*`): імпорти `bun#SQL`, будь-який `mssql`, `@nitra/graphql-request#GraphQLClient`
- *    дозволені лише у каталозі conn (за замовчуванням `src/conn/`; за наявності
- *    `package.json#imports['#conn/*']` — у його цільовому каталозі); поза ним — порушення
- *    (див. `utils/conn-imports-scan.mjs`);
- *  - «Нейминг та експорти у `#conn/`»: всередині conn-каталогу basename файла має відповідати
- *    канону `ql-<id>` / `(pg|mysql|mssql)-(read|write)[-<id>]`; `export default` заборонений; має бути
- *    іменований експорт з імʼям, що дорівнює camelCase від basename файла (`pg-write-contract.js`
- *    → `export const pgWriteContract`); `index.*` як reexport-барель пропускаємо
- *    (див. `utils/conn-file-rules.mjs`);
- *  - «process.env / CheckEnv»: пряме `process.env.X` має бути замінено на `env` —
- *    з `@nitra/check-env` (для обов'язкових змінних, із `checkEnv([...])`) або з
- *    `node:process` (для опційних). Коли `env` імпортовано з `@nitra/check-env`,
- *    кожен `env.X` має бути закритий літеральним викликом `checkEnv(['X', ...])`
- *    у тому ж файлі або коментарем `// \@nitra/cursor ignore-next-line checkEnv`
- *    на попередньому рядку (див. `utils/check-env-scan.mjs`);
- *  - «Паузи через setTimeout»: `new Promise(resolve => setTimeout(resolve, ms))` (з/без `await`)
- *    треба замінити на `await setTimeout(ms)` з `node:timers/promises`
- *    (див. `utils/promise-settimeout-scan.mjs`);
- *  - «Temporal у Bun runtime»: identifier `Temporal` заборонений, бо поточний Bun runtime
- *    не має глобального Temporal API (див. `utils/temporal-scan.mjs`);
- *  - «jsconfig.json»: у backend-пакеті з каталогом `src/` у корені має бути `jsconfig.json`,
- *    вміст якого збігається з каноном js-run.mdc (NodeNext і include на дерево `src`).
- *
- * Per-document валідація `package.json` (bunyan, `node` у `scripts`) делегована rego-пакету
- * `js_run.package_json` у `npm/rules/js-run/policy/package_json/`; JS — cross-file (AST, FS).
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/runtime.md */
 import { existsSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-run/lib/docs/temporal-scan.md

@@ -0,0 +1,25 @@
+# temporal-scan.mjs
+
+## Огляд
+
+Цей файл є частиною системи, яка сканує код Bun workspace на наявність використання ключового слова `Temporal`. Він запобігає використанню `Temporal` у backend-коді, оскільки Bun 1.3.x ще не має глобального `Temporal`, та охоплює сценарії з імпортом та polyfill. Це забезпечує відповідність коду поточним вимогам Bun runtime щодо обробки часу.
+
+## Поведінка
+
+Знаходить використання identifier `Temporal` у тексті. Повертає список рядків та фрагментів коду, де зустрічається `Temporal`.
+Чи сканувати файл за розширенням (JS/TS-сім'я, виключно з `.d.ts`). Повертає `true`, якщо файл має відповідне розширення, і не є файлом `.d.ts`.
+
+## Публічний API
+
+- findTemporalUsageInText — Знаходить згадки про `Temporal` у тексті.
+- isTemporalScanSourceFile — Визначає, чи потрібно сканувати файл за розширенням (JavaScript/TypeScript або `.d.ts`).
+
+## Гарантії поведінки
+
+- Функція `findTemporalUsageInText` повертає `true` лише якщо знайде identifier `Temporal` у наданому тексті.
+- Функція `findTemporalUsageInText` повертає `false` якщо identifier `Temporal` не знайдено.
+- Функція `isTemporalScanSourceFile` повертає `true` якщо у файлі є identifier `Temporal`.
+- Функція `isTemporalScanSourceFile` повертає `false` якщо у файлі немає identifier `Temporal`.
+- Результат роботи `findTemporalUsageInText` не гарантує, що identifier `Temporal` використовується правильно.
+- Результат роботи `isTemporalScanSourceFile` не гарантує, що використання `Temporal` є допустимим.
+- Кеш не використовується.

package/rules/k8s/js/manifests.mjs

@@ -1,140 +1,4 @@
-/**
- * Перевіряє Kubernetes YAML у шляхах з сегментом `k8s` (див. k8s.mdc).
- *
- * Перший рядок `# 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'`**
- * (для **cpu** допускається число **`0.02`**). Поза base, якщо ще не підібрано власні
- * ліміти — орієнтир **`DEFAULT_CONTAINER_CPU_REQUEST`** = **`"0.5"`**, **`DEFAULT_CONTAINER_MEMORY_REQUEST`**
- * = **`"512Mi"`**. Поле **`imagePullPolicy`**
- * не перевіряється — діють типові правила Kubernetes (`:latest` або коли тег не вказано → **Always**,
- * інші теги → **IfNotPresent**). Якщо серед **`containers`** / **`initContainers`** є образ
- * **`hasura/graphql-engine`**, дозволено лише канонічний тег зі списку `allowed_hasura_images`
- * у rego-пакеті `k8s.manifest` (`policy/manifest/manifest.rego`) — пер-документна перевірка делегована rego.
- *
- * **Namespace і Kustomize:** YAML у **`…/k8s/base/`** (окрім імені **`kustomization.yaml`**)
- * завжди має **непорожній** **`metadata.namespace`** у відповідних документах (узгоджено з dev у репозиторії),
- * навіть якщо **`namespace:`** заданий у **`base/kustomization.yaml`**.
- * Поза **`k8s/base`**: для файлів, досяжних з kustomization через **`resources`**, **`bases`**, **`components`**,
- * **`crds`**, **`patches[].path`**, **`patchesStrategicMerge`**, **`metadata.namespace`** у маніфесті **не** додають;
- * файли **поза** цим графом — **непорожній** **`metadata.namespace`** (крім **кластерних** kind; див. k8s.mdc).
- *
- * **`kind: Ingress`** заборонено (потрібен перехід на Gateway API).
- * **`apiVersion: autoscaling/v1`** заборонено (мігруй **HorizontalPodAutoscaler** на **`autoscaling/v2`**).
- * Рядок **`apiVersion: batch/v1beta1`** (CronJob, Job) **автоматично** переписується на **`apiVersion: batch/v1`**
- * (окрім рядків-коментарів і рядків, де після значення йде наприклад `# …`).
- *
- * Файли під **`k8s`**, де всі YAML-документи — лише **`kind: BackendConfig`**, **видаляються** автоматично.
- * Якщо **BackendConfig** змішано з іншими ресурсами в одному файлі — перевірка завершується помилкою (розділи маніфести).
- *
- * У **`kind: Service`** у **`metadata.annotations`** не повинно бути ключів **`cloud.google.com/neg`**
- * та **`cloud.google.com/backend-config`** (див. k8s.mdc).
- *
- * Файли **`svc.yaml`** / **`svc-hl.yaml`** у **одному каталозі** (див. k8s.mdc): для кожного **`svc.yaml`**
- * поруч обов’язковий **`svc-hl.yaml`** (headless-копія: той самий селектор/порти, **`metadata.name`** з суфіксом **`-hl`**,
- * **`spec.clusterIP: None`**). У **`svc.yaml`** кожен **Service** має **`spec.type: ClusterIP`**. У **`svc-hl.yaml`**
- * кожен **Service** — **`spec.clusterIP: None`** та ім’я на **`-hl`**. У маршрутах **Gateway API**
- * (**`HTTPRoute`**, **`GRPCRoute`**, **`TCPRoute`**, **`TLSRoute`**, **`UDPRoute`**, група **`gateway.networking.k8s.io`**)
- * посилання **`backendRefs` / `backendRef`** на **Service** мають вказувати лише сервіси з суфіксом **`-hl`** у **`name`**.
- * Поле **`namespace`** у **`backendRef`**, що збігається з **`metadata.namespace`** самого маршруту, — надлишкове:
- * прибери його, бо за замовчуванням Gateway API визначає backend у тому ж namespace, що й маршрут (див. k8s.mdc).
- * **HealthCheckPolicy** (**`networking.gke.io/v1`**, GKE): **`spec.targetRef`** на **Service** — **`name`** з суфіксом **`-hl`** (див. k8s.mdc).
- * Якщо **`kustomization.yaml`** посилається на **`svc.yaml`** (**`resources`**, **`bases`**, **`components`**, **`crds`**,
- * **`patches[].path`**, **`patchesStrategicMerge`**), у **тому ж** файлі має бути посилання на відповідний **`svc-hl.yaml`**
- * в **тому ж каталозі**, що й **`svc.yaml`** (логіка збігається з **`pathsFromKustomizationObject`**).
- *
- * Структура **Kustomize** (див. k8s.mdc): заборона шляхів **`…/k8s/dev/…`**; у **`k8s/base/kustomization.yaml`**
- * завжди має бути непорожнє поле **`namespace:`** (перевірка, якщо файл існує). У **`apiVersion: kustomize.config.k8s.io/…`**, **`kind: Kustomization`**
- * перелік **`resources:`** (лише непорожні рядки) має бути відсортовано за алфавітом (**en**, `localeCompare`).
- *
- * **Структурний сорт `patches[]` у kustomization.yaml:** масив **`patches`** має бути відсортовано за tuple
- * **`[target.kind, target.name, target.namespace, path]`** (`localeCompare('en', base)`). Поля **`group`** / **`version`**
- * у tuple не входять — для них діє правило «patches[].target: лише kind і name». Додатково: вміст
- * **inline `patches[i].patch`** (literal block scalar — масив JSON6902-операцій) має бути відсортовано за **`path`**,
- * але **лише** якщо всі операції — **`add`** / **`replace`** і всі **`path`** попарно дизʼюнктні (жоден не префікс іншого).
- * Інакше порядок не чіпається — `move` / `copy` / `test` / `remove` чи спільні шляхи можуть бути семантично залежні (RFC 6902).
- *
- * **Inline JSON6902** у **`patches`** (і зовнішні файли з **`patches[].path`** під **`k8s`**, якщо вміст — масив JSON Patch): не допускається пара **`remove`** і **`add`**
- * на один і той самий **`path`** у межах одного фрагмента — потрібен **`op: replace`** (k8s.mdc). **check-k8s** це перевіряє.
- *
- * **Мішень patch:** у **`patches[].target`** і **`patchesJson6902[].target`** (без **labelSelector** / **annotationSelector**)
- * має існувати відповідний ресурс у зібраному з **`resources`**, **`bases`**, **`components`**, **`crds`** каталозі (рекурсивно для підкаталогів з **`kustomization.yaml`**).
- * Для **`patchesStrategicMerge`** і для **`patches[].path`** без **`target`** і без inline **`patch`** (зовнішній strategic-merge)
- * кожен YAML-документ з кореневим **`kind`** і **`metadata.name`** також звіряється з цим каталогом.
- *
- * **Зайві `group` / `version` у `patches[].target` / `patchesJson6902[].target`:** якщо в інвентарі **`resources`** /
- * **`bases`** / **`components`** / **`crds`** (рекурсивно) за **`kind`** + **`name`** немає колізії між різними
- * API-групами/версіями, поля **`group`** і **`version`** у **`target`** треба прибрати — Kustomize визначає ціль
- * за **GVK + name**, а зайві поля ламаються мовчки під час змін API (k8s.mdc «patches[].target: лише kind і name»).
- *
- * Явні винятки до загальної логіки yannh/datree — таблиця **`EXPLICIT_K8S_SCHEMAS`** (`Map`): ключ
- * **`apiVersion`, `kind`, `type`** (для CRD без поля `type` у маніфесті — зірочка **`*`** як третій
- * компонент). Спочатку шукається збіг за фактичним `type`, потім за **`*`**.
- * Dockerfile — правило docker.mdc, скрипт rules/docker/fix.mjs.
- *
- * **Структура `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). **Додаткові правила** поверх канону дозволені.
- *
- * **ConfigMap для Hasura-Deployment:** якщо в `k8s/base/` є `configmap.yaml` і поруч Deployment з образом
- * **`hasura/graphql-engine`**, то в `data` ConfigMap обов'язково має бути ключ
- * **`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`** зі значенням **`"true"`** (приймається булеве `true`
- * або рядок `"true"`, без регістрової залежності).
- *
- * **HPA / PDB / topologySpreadConstraints:** для кожного **`Deployment`** у шарі **`…/k8s/…/base/`**
- * (будь-який `.yaml` у цьому каталозі) обов'язкові канонічні **topologySpreadConstraints**, а HPA і PDB
- * живуть у sibling каталозі **`…/k8s/…/components/`** (Kustomize Component, фіксована назва каталогу `components`). У `base/`
- * заборонено тримати локальні `hpa.yaml` і `pdb.yaml` (file-existence error) і також у дереві
- * base-kustomize не повинно бути HPA/PDB через `resources` / `components` / `bases`.
- * **NetworkPolicy:** для кожного **`Deployment`**, **`StatefulSet`**, **`DaemonSet`**, **`Job`**, **`CronJob`** під `k8s`
- * обов'язковий канонічний NetworkPolicy у `networkpolicy.yaml` поруч з workload-маніфестом — у base
- * (`base/networkpolicy.yaml`, підключений через `base/kustomization.yaml` `resources:` — обмеження діють і на dev)
- * і у не-base overlay (опційно — overlay-specific override).
- * Egress: kube-dns; **TCP 80/443** на `0.0.0.0/0`; інші порти — `namespaceSelector: {}` (in-cluster / `*.svc`). Заборонено `egress: [{}]`.
- * Відсутні документи **`check k8s`** створює автоматично (multi-doc у одному файлі, якщо workload-ів кілька).
- * Структура `components/`: `kustomization.yaml` з `apiVersion: kustomize.config.k8s.io/v1alpha1`, `kind: Component`,
- * `resources` що містять `hpa.yaml` і `pdb.yaml`, `hpa.yaml` (валідний `autoscaling/v2`
- * HorizontalPodAutoscaler з `scaleTargetRef.name` = ім'я Deployment, dev-like `min=max=1`), `pdb.yaml` (валідний
- * `policy/v1` PodDisruptionBudget з `selector.matchLabels.app` = мітка `app` Deployment, dev-like `minAvailable=0`).
- * Overlays (`ua/`, прод-overlays) підключають `components: [- ../components]` і додають JSON6902-патчі для
- * прод-значень: `/spec/minReplicas`, `/spec/maxReplicas` (HPA), `/spec/minAvailable` (PDB). HPA поруч із Deployment
- * у не-base оверлеях — як раніше (див. k8s.mdc).
- * Env-залежні межі за сегментом після `/k8s/`: **dev-like** (`base`, `dev`, `*-qa`) — для HPA, що лишився після
- * збірки, `minReplicas === 1`, `maxReplicas === 1`, PDB `minAvailable === 0`; **прод** — `minReplicas >= 2`,
- * `maxReplicas >= 2`, `minAvailable >= 1`.
- *
- * **Прод-оверрайди в kustomization.yaml:** для прод overlays (не dev-like) у `patches[]` потрібні перевизначення
- * **`/spec/minReplicas`** і **`/spec/maxReplicas`** для **HorizontalPodAutoscaler** і **`/spec/minAvailable`** для
- * **PDB** — якщо overlay-tree (через `resources` / `components`) містить HPA / PDB (тобто overlay підключив
- * `…/k8s/…/components/`). Формат patch — JSON6902 або Strategic Merge; наявність шляхів —
- * `kustomizationPatchPathsByTargetKind`.
- *
- * **Існування шляхів у `kustomization.yaml`:** кожне локальне посилання (без `://`) з `resources` / `bases` /
- * `components` / `crds`, `patchesStrategicMerge`, `patches[].path`, `patchesJson6902[].path`, `configurations[]`,
- * `replacements[].path` має вказувати на наявний у репозиторії файл (`.yaml` / `.yml`) або каталог; інакше
- * помилка `check k8s` (k8s.mdc).
- *
- * **Images у Kustomize — `images:`, не patch:** для кожного `kustomization.yaml` автоматично:
- * (а) конвертує JSON6902 `op: replace` на `/spec/template/spec/containers/<N>/image` (target `kind: Deployment`) у
- * запис **`images:`** — `name` береться з оригінального `image:` у base (без тегу), `newName` — з patch.value (без тегу),
- * `newTag` — лише якщо тег у patch.value відрізняється від тега в base; якщо `patches[]` після цього порожній — ключ
- * прибирається; (б) чистить існуючий блок **`images:`** — зрізає `:tag` з `name` (digest `@…` не чіпає) і видаляє
- * `newTag`, який збігається з відрізаним тегом.
- *
- * **HPA / PDB заборонені у base-дереві Kustomize:** у дереві з `…/k8s/…/base/kustomization.yaml` не дозволяти
- * `HorizontalPodAutoscaler` / `PodDisruptionBudget` у `resources` / `bases` / `components` / `crds` (рекурсивно)
- * взагалі. Канон — HPA/PDB у sibling `…/k8s/…/components/` (Kustomize Component) і підключаються лише з overlay.
- * У `kustomization.yaml` overlay, який підключає каталог `…/k8s/…/base`, не додавай окремі YAML-файли з HPA / PDB,
- * поки в наслідуваному `base` у дереві не з'явиться такий Deployment (k8s.mdc).
- */
+/** @see ./docs/manifests.md */
 import { existsSync, readFileSync } from 'node:fs'
 import { readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'

package/rules/nginx-default-tpl/js/template.mjs

@@ -1,21 +1,4 @@
-/**
- * Перевіряє nginx-шаблон і супутні файли за правилом nginx-default-tpl.mdc.
- *
- * Якщо в дереві є **default.conf.template**: канонічні директиви (порт 8080, /healthz, gzip_static,
- * без proxy), поруч **\*.ini** (ключі з ini мають зустрічатися в шаблоні як **$KEY**), у будь-якому
- * Dockerfile — **find** + **gzip** для каталогу `/usr/share/nginx/html` та **envsubst** з
- * **default.conf.template**. Приклад **HTTPRoute** з правила — для рев’ю; автоматична перевірка
- * вимкнена (різні схеми маршрутизації). Функція **`httpRouteMatchesNginxDefaultTpl`** лишається для
- * тестів і майбутнього вузького застосування. VSCode: **extensions.json** та **settings.json** з
- * форматером nginx і **formatOnSave**.
- *
- * У дереві від **cwd** усі **default.tpl.conf** стають **default.conf.template**: перейменування, або
- * якщо **default.conf.template** уже є — він перезаписується вмістом **default.tpl.conf**, після чого
- * **default.tpl.conf** видаляється. Якщо після міграції шаблону немає — перевірка пропускається (0).
- *
- * Невалідна директива **`error_log off;`** (nginx трактує "off" як ім'я файлу `/etc/nginx/off` і падає під
- * readOnlyRootFilesystem) автоматично замінюється на **`error_log /dev/null crit;`** у кожному шаблоні.
- */
+/** @see ./docs/template.md */
 import { existsSync } from 'node:fs'
 import { readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative } from 'node:path'

package/rules/npm-module/js/docs/header_doc_pointer.md

@@ -0,0 +1,25 @@
+# header_doc_pointer.mjs
+
+## Огляд
+
+Концерн правила `npm-module`, що закріплює контракт між `docs/<stem>.md` і module-level JSDoc у скриптах правил і скілів. Якщо файл вже описано у `docs/<stem>.md` — наратив у заголовному коментарі файлу є дублюванням і заборонений. Якщо `docs` немає — header залишається єдиним джерелом опису поведінки і жодних обмежень немає.
+
+## Поведінка
+
+1. Сканує всі `.mjs`-файли (крім `.test.mjs`) у `npm/rules/*/js/` та `npm/skills/*/js/`.
+2. Для кожного файлу перевіряє наявність `docs/<stem>.md` поруч із `js/`.
+3. Якщо `docs/<stem>.md` **відсутній** — пропускає файл: перевірка не застосовується.
+4. Якщо `docs/<stem>.md` **присутній** — знаходить module-level JSDoc (перший `/** ... */` до першого `import`/`export` на початку рядка).
+5. Рахує непорожні змістовні рядки блоку (після зрізання відступу `*`). Більше одного → порушення.
+
+Допустимі форми при наявних docs:
+- відсутній module-level JSDoc (0 рядків)
+- `/** @see ./docs/<stem>.md */` (1 рядок)
+- `/** Контракт: ./docs/<stem>.md */` (1 рядок)
+
+## Гарантії поведінки
+
+- Файли без `docs/`-відповідника повністю ігноруються — перевірка не створює обмежень до того, як docgen запишеться.
+- Якщо у файлі немає жодного module-level JSDoc — перевірка проходить.
+- Тестові файли (`*.test.mjs`) не скануються.
+- Підкаталоги `tests/`, `data/`, `templates/` у `js/` не скануються (discovery бере лише `*.mjs` безпосередньо в `js/`, не рекурсивно).

package/rules/npm-module/js/header_doc_pointer.mjs

@@ -0,0 +1,82 @@
+/** Контракт: ./docs/header_doc_pointer.md */
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+
+/** Перший JSDoc-блок у файлі (не-жадібний). */
+const MODULE_JSDOC_RE = /\/\*\*[\s\S]*?\*\//
+
+/**
+ * `import` або `export` на початку рядка — межа між module-level і body.
+ * Regex, не AST: нас цікавить тільки текстова позиція, не семантика JS.
+ */
+const CODE_START_RE = /^(?:import|export)\b/m
+
+/** Кількість непорожніх рядків між `/**` і `*\/` (після зрізання `*`-відступу). */
+function contentLineCount(block) {
+  return block
+    .split('\n')
+    .slice(1, -1)
+    .filter(l => /\S/.test(l.replace(/^\s*\*\s?/, '')))
+    .length
+}
+
+/** Повертає module-level JSDoc або `null`, якщо його немає. */
+function moduleJsDoc(source) {
+  const codeStart = CODE_START_RE.exec(source)
+  const prefix = codeStart ? source.slice(0, codeStart.index) : source
+  const m = MODULE_JSDOC_RE.exec(prefix)
+  return m ? m[0] : null
+}
+
+/**
+ * Сканує `npm/rules/*\/js/*.mjs` і `npm/skills/*\/js/*.mjs`.
+ * Якщо поряд існує `docs/<stem>.md` — module-level JSDoc має бути pointer (≤1 рядок),
+ * а не наратив; якщо docs немає — без обмежень.
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export async function check(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+
+  for (const baseSegment of ['npm/rules', 'npm/skills']) {
+    const absBase = join(cwd, baseSegment)
+    if (!existsSync(absBase)) continue
+
+    for (const ruleEntry of await readdir(absBase, { withFileTypes: true })) {
+      if (!ruleEntry.isDirectory() || ruleEntry.name.startsWith('.')) continue
+
+      const jsDir = join(absBase, ruleEntry.name, 'js')
+      if (!existsSync(jsDir)) continue
+
+      for (const fileEntry of await readdir(jsDir, { withFileTypes: true })) {
+        if (
+          !fileEntry.isFile() ||
+          !fileEntry.name.endsWith('.mjs') ||
+          fileEntry.name.endsWith('.test.mjs')
+        )
+          continue
+
+        const stem = basename(fileEntry.name, '.mjs')
+        const docsPath = join(jsDir, 'docs', `${stem}.md`)
+        if (!existsSync(docsPath)) continue
+
+        const filePath = join(jsDir, fileEntry.name)
+        const source = await readFile(filePath, 'utf8')
+        const block = moduleJsDoc(source)
+        if (!block) continue
+
+        const count = contentLineCount(block)
+        if (count > 1) {
+          reporter.fail(
+            `${filePath.slice(cwd.length + 1)}: docs/${stem}.md вже описує поведінку — module-level JSDoc має бути pointer (≤1 рядок, зараз ${count})`
+          )
+        }
+      }
+    }
+  }
+
+  return reporter.getExitCode()
+}

package/rules/npm-module/js/package_structure.mjs

@@ -1,31 +1,4 @@
-/**
- * Перевіряє структуру npm-модуля в монорепо за правилом npm-module.mdc.
- *
- * Workspace `npm/`, `npm/package.json`, workflow `npm-publish.yml` з OIDC, `on.push.paths` з glob для каталогу npm.
- *
- * Якщо під `npm/src` є хоча б один файл `.js`, очікується канонічний layout: `types` → `./types/index.d.ts`,
- * згенерований `index.d.ts` у `npm/types/`, і hk з викликом `tsc` по файлах під `npm/src`.
- *
- * Якщо таких файлів немає — layout через `npm/tsconfig.emit-types.json`: поле `types` має вказувати на існуючий
- * файл під `./types/…`, у hk — `tsc -p tsconfig.emit-types.json`, у JSON-конфігу — потрібні compilerOptions для emit.
- *
- * Поля workflow перевіряються після **YAML parse**, щоб не плутати з коментарями.
- *
- * Компактність опублікованого пакета (cross-file / FS / AST частина):
- *  - Пер-документні структурні deny для `npm/package.json` (`files` whitelist обовʼязковий,
- *    без `devDependencies`) — у rego-пакеті `npm_module.npm_package_json` (Rego-authoritative).
- *  - Тут лишається лише `checkNoTestsInPublishedFiles`: walk шляхів з `"files"` (з урахуванням
- *    негативних glob-патернів) і скан test-style каталогів (`tests/`, `__tests__/`, `fixtures/`,
- *    `__fixtures__/`, `spec/`, `test/`), імен файлів (`*.test.*` / `*.spec.*`) і AST-імпортів
- *    test-фреймворків (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, `jest`, `ava`, …).
- *    Виняток: `*_test.rego` дозволені поруч з полісі — це конвенція conftest.
- *
- * Версія та CHANGELOG тут НЕ перевіряються: єдиний артефакт зміни — change-файл, а узгодженість
- * `version`/`CHANGELOG.md` (включно з drift від ручного bump) валідує `changelog/js/consistency.mjs`
- * за моделлю `n-changelog.mdc`. Інваріант «верхня секція CHANGELOG == package.json.version» істинний
- * лише post-release і його гарантує `n-cursor release` у CI — локально його не підтримують руками.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/package_structure.md */
 import { existsSync } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
 import { join, sep } from 'node:path'

package/rules/npm-module/js/rule_meta.mjs

@@ -1,13 +1,4 @@
-/**
- * Перевірка метаданих правил пакета `@nitra/cursor` (концерн правила npm-module).
- *
- * Кожен `npm/rules/<id>/` має містити валідний `meta.json`:
- *  - `auto` (якщо присутнє) — розпізнане `parseRuleAutoSpec` (завжди / масив / glob / predicate);
- *  - для `predicate` — імʼя є в реєстрі `RULE_PREDICATES`;
- *  - залишковий `auto.md` заборонено (міграція на meta.json завершена).
- *
- * Застосовний лише в репо пакета (де є `npm/rules/`); у споживача каталогу нема — пропуск.
- */
+/** @see ./docs/rule_meta.md */
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 

package/rules/npm-module/js/skill_meta.mjs

@@ -1,16 +1,4 @@
-/**
- * Перевірка метаданих скілів пакета `@nitra/cursor` (концерн правила npm-module).
- *
- * Кожен `npm/skills/<id>/` має містити валідний `meta.json`:
- *  - `worktree` присутнє і boolean;
- *  - `auto` (якщо присутнє) — розпізнане (`"завжди"` або непорожній масив рядків);
- *  - `requireRoot` (якщо присутнє) — boolean; не може бути `false` при `worktree:true`
- *    (worktree вже вимагає кореня — суперечність вводить в оману);
- *  - залишковий `auto.md` заборонено (міграція на meta.json завершена).
- *
- * Концерн застосовний лише в репо самого пакета (де є `npm/skills/`); у споживача
- * каталогу `npm/skills/` нема, тож перевірка мовчки проходить.
- */
+/** @see ./docs/skill_meta.md */
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 

package/rules/php/js/tooling.mjs

@@ -1,14 +1,4 @@
-/**
- * Перевіряє вимоги правила php.mdc для PHP-проєктів.
- *
- * **Що тут лишилося** (FS-existence — не покривається conftest):
- *  - наявність `composer.json` у корені;
- *  - наявність `.github/workflows/lint-php.yml`.
- *
- * **Що покрила Rego** (`npx \@nitra/cursor check`):
- *  - `npm/policy/php/package_json/` — наявність скрипта `lint-php` у `package.json`;
- *  - `npm/policy/php/lint_php_yml/` — крок `run: bun run lint-php` у workflow.
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'

package/rules/python/js/applies.mjs

@@ -1,11 +1,4 @@
-/**
- * Applies-гейт правила `python` (python.mdc): правило застосовне, лише якщо в корені є
- * `pyproject.toml`. Інакше CLI пропускає всі concerns (JS і policy) — інакше rego
- * `python/package_json` хибно вимагає `scripts.lint-python` навіть для не-Python репо.
- *
- * JS тут — гейт на наявність кореневого `pyproject.toml`. Подальші FS-перевірки
- * (`uv.lock`, `package.json`, `lint-python.yml`, заборона Poetry) — у `tooling.mjs`.
- */
+/** @see ./docs/applies.md */
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 

package/rules/python/js/tooling.mjs

@@ -1,24 +1,4 @@
-/**
- * Перевіряє FS-вимоги правила python.mdc для Python-проєктів на uv.
- *
- * **Що тут лишилося** (FS-existence — не покривається conftest):
- *  - наявність `uv.lock` поруч (uv-проєкт коммітить lock-файл);
- *  - наявність кореневого `package.json` (для `bun run lint-python`);
- *  - наявність `.github/workflows/lint-python.yml`;
- *  - заборона Poetry-артефактів `poetry.lock` / `poetry.toml` (міграція на uv).
- *
- * Гейт на `pyproject.toml` робить `applies.mjs` — CLI пропускає правило цілком
- * без нього. Захисний early-return лишається тут лише для прямого виклику
- * `check()` (тести/standalone) без `applies.mjs`-гейту.
- *
- * **Що покрила Rego** (`npx \@nitra/cursor fix python`):
- *  - `python/pyproject_toml/` — заборона `[tool.poetry]` + вимога PEP 621 `[project].name/version`;
- *  - `python/package_json/` — наявність скрипта `lint-python` у `package.json`;
- *  - `python/lint_python_yml/` — `uses`/`run`-кроки канонічного workflow.
- *
- * `.venv/` навмисно НЕ перевіряється: uv теж створює `.venv`, тож його наявність
- * не є ознакою Poetry й давала б хибні спрацювання.
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 

package/rules/rego/js/applies.mjs

@@ -1,14 +1,4 @@
-/**
- * Applies-гейт правила `rego` (rego.mdc): правило застосовне, лише якщо в репозиторії є
- * хоча б один `.rego`-файл (під типовими skip-ами і `.n-cursor.json:ignore`).
- *
- * Якщо `.rego` нема — CLI пропускає правило цілком (включно з polices `package_json`,
- * `vscode_extensions`, `vscode_settings`), бо вимоги rego-tooling неактуальні. Якщо є — CLI
- * прогонить policy-концерни через `target.json`-маніфести у `rules/rego/policy/<name>/`.
- *
- * JS тут лишається лише як cross-file гейт: walkDir не виразити декларативно через `target.json`.
- * Друк короткого pass-повідомлення з контекстом робить `check()` (необовʼязковий).
- */
+/** @see ./docs/applies.md */
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
 import { walkDir } from '../../../scripts/utils/walkDir.mjs'

package/rules/rust/js/applies.mjs

@@ -1,10 +1,4 @@
-/**
- * Applies-гейт правила rust: маркер — наявність `Cargo.toml` у `cwd` або
- * в будь-якому workspace-підкаталозі (рекурсивний пошук з пропуском
- * `node_modules`, `.git`, `.next`, `.turbo`). Якщо повертає `false` —
- * `runStandardRule` пропускає всі концерни (JS і policy) цього правила.
- * `check()` друкує тільки context-pass; реальна робота — у policy-концернах.
- */
+/** @see ./docs/applies.md */
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'