@nitra/cursor 3.26.0 → 3.28.0

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'
 

package/rules/security/js/sample_secret.mjs

@@ -1,31 +1,4 @@
-/**
- * FS-частина правила `security`: concern `sample_secret`.
- *
- * Перевіряє, що фейкові credential-значення у *прикладних* файлах записані як
- * канонічний placeholder `sample-secret`, а не як bare `secret`.
- *
- * `sample-secret` містить підрядок `sample`, який є у вшитому списку
- * `DefaultFalsePositives` TruffleHog — таке значення сканер відсіює
- * гарантовано й незалежно від версії. Bare `secret` наразі не фіксується сканером
- * лише тому, що випадково присутнє у словнику `fp_words.txt`; це крихка поведінка,
- * що залежить від версії інструмента, на яку не варто покладатися.
- *
- * Прикладними вважаються файли, чий basename має суфікс `.example` / `.sample`
- * / `.template` / `.dist` або infix `.example.` / `.sample.` / `.template.`, а
- * також будь-які файли всередині каталогів `fixtures` / `fixture` /
- * `__fixtures__`. Решта файлів не сканується — там `secret` майже завжди
- * частина реального коду, а не placeholder.
- *
- * Порушенням є лише `secret` у *позиції значення* — одразу після `=`, `:` чи
- * `=>` (з опційними лапками). Імена ключів (`client_secret`, `JWT_SECRET`) не
- * чіпаються: матч прив'язаний до значення, не до ключа.
- *
- * Чому regex, а не AST: прикладні файли — різнорідні конфіги (`.env`, YAML,
- * JSON, TOML, plain `.dist`), єдиного AST для них немає, тож скан порядковий.
- * Чому JS, а не Rego: щоб знайти прикладні файли, треба обійти дерево
- * (`readdir`), а вміст — неструктурований текст (conftest парсить лише
- * структуровані документи).
- */
+/** @see ./docs/sample_secret.md */
 import { readFile } from 'node:fs/promises'
 import { relative, sep } from 'node:path'
 

package/rules/security/js/trufflehog.mjs

@@ -1,11 +1,4 @@
-/**
- * FS-частина правила `security`.
- *
- * Перевіряє:
- *  - наявність `package.json` (структуру валідує policy security.package_json);
- *  - наявність `.trufflehog-exclude` у корені та subset канонічних patterns
- *    (text-subset, бо `.trufflehog-exclude` — plain text, не структурований).
- */
+/** @see ./docs/trufflehog.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'

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

@@ -1,8 +1,4 @@
-/**
- * Quick-крок lint правила style-lint: stylelint --fix по css/scss/vue.
- *
- * `files` (quick) → лише style-файли з них; undefined (ci) → весь glob `**\/*.{css,scss,vue}`.
- */
+/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
 const STYLE_EXT_RE = /\.(?:css|scss|vue)$/u

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

@@ -1,22 +1,4 @@
-/**
- * Перевіряє CSS/SCSS лінт за правилом style-lint.mdc.
- *
- * **Що тут лишилося** (FS / cross-file — не покривається conftest):
- *  - наявність зовнішнього файлу конфігу stylelint (`.stylelintrc.*`,
- *    `stylelint.config.js`) як альтернатива полю `stylelint` у `package.json`
- *    (cross-file: треба знати, чи є поле, чи немає);
- *  - `.stylelintignore` у корені.
- *
- * **Що покрила Rego** (`npx \@nitra/cursor check`):
- *  - `npm/policy/style_lint/package_json/` — скрипт `lint-style` через `npx stylelint`,
- *    `@nitra/stylelint-config` у `devDependencies`, поле `stylelint.extends`;
- *  - `npm/policy/style_lint/lint_style_yml/` — `npx stylelint` у `run` workflow;
- *  - `npm/policy/style_lint/vscode_extensions/` — `stylelint.vscode-stylelint`
- *    у `recommendations` `.vscode/extensions.json`;
- *  - `npm/policy/style_lint/vscode_settings/` — `css.validate`/`scss.validate`/
- *    `less.validate: false` у `.vscode/settings.json`.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/tauri/js/cargo_mutants_config.mjs

@@ -1,23 +1,4 @@
-/**
- * Концерн `cargo_mutants_config` правила tauri (tauri.mdc): для кожного
- * `<workspace>/src-tauri/Cargo.toml` без дублювання гарантує наявність
- * Tauri-specific cargo-mutants налаштувань у `<workspace>/src-tauri/.cargo/mutants.toml`.
- *
- * Семантика (фіксована між Tauri-проєктами):
- *   - `src/main.rs` — binary shell entrypoint (smoke/e2e, не mutation unit);
- *   - `src/**\/{android,ios,mobile}.rs` — mobile plugin bridge / platform glue;
- *   - `src/**\/{macos,windows,linux,desktop}.rs` — desktop platform bridge / OS integration glue.
- *
- * Self-gating: silently skip, якщо в monorepo не знайдено жодного
- * `<ws>/src-tauri/Cargo.toml` (test rule сам створить нейтральний baseline там,
- * де потрібно).
- *
- * Ідемпотентність:
- *   - якщо файл відсутній — створює з Tauri-canonical baseline;
- *   - якщо файл існує і всі канонічні ключі вже є — `manual cargo-mutants config preserved`;
- *   - якщо файл існує, але якихось канонічних top-level ключів немає — додає
- *     лише відсутні ключі окремим блоком у кінці; існуючих значень не торкається.
- */
+/** @see ./docs/cargo_mutants_config.md */
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'

package/rules/tauri/js/tooling.mjs

@@ -1,24 +1,4 @@
-/**
- * Перевіряє інструментарій Tauri (tauri.mdc): VSCode `extensions.json` для
- * проєктів, у яких є маркер Tauri.
- *
- * Cross-file gating (JS):
- *   1. Tauri-маркер визначаємо обходом усіх workspace-пакетів через
- *      `getMonorepoPackageRootDirs()` (корінь + workspaces). Кожен workspace
- *      перевіряється за **будь-яким** з:
- *      - існує каталог `<ws>/src-tauri/`;
- *      - існує файл `<ws>/src-tauri/Cargo.toml`;
- *      - існує файл `<ws>/src-tauri/tauri.conf.json`;
- *      - існує файл `<ws>/tauri.conf.json` (legacy flat-layout);
- *      - `<ws>/package.json#dependencies` чи `devDependencies` містить ключ
- *        з префіксом `@tauri-apps/`.
- *   2. Якщо маркера немає — пропустити перевірку (tauri-tooling не вимагається).
- *   3. Інакше — для `.vscode/extensions.json` зробити FS-existence + делегувати
- *      content `rego.tauri.vscode_extensions` через `runConftestBatch`.
- *
- * Rego-полісі глобально без `target.json` поруч (не auto-discoverable через `n-cursor fix`) — це conditional
- * правило. Plan B: Rego-authoritative + JS-orchestrator з `runConftestBatch`.
- */
+/** @see ./docs/tooling.md */
 import { existsSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/test/js/cargo_mutants_config.mjs

@@ -1,15 +1,4 @@
-/**
- * Концерн `cargo_mutants_config` правила test (test.mdc): якщо `rust` присутнє
- * в `.n-cursor.json#rules` і не у `disable-rules` — визначає ВСІ Cargo.toml
- * (cwd і всі workspaces, з підтримкою Tauri-патерну) і копіює canonical
- * baseline `.cargo/mutants.toml` у каталог кожного manifest'а, якщо файлу немає.
- *
- * Self-gating: концерн silently skips коли `rust` не enabled.
- * Якщо `rust` enabled, але жодного Cargo.toml не знайдено — теж silently skip
- * (manifest може з'явитися пізніше; це не помилка).
- *
- * Baseline — порожній файл з коментарем; cargo-mutants має робочі defaults.
- */
+/** @see ./docs/cargo_mutants_config.md */
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'

package/rules/test/js/location.mjs

@@ -1,12 +1,4 @@
-/**
- * Перевіряє, що всі `*.test.mjs` лежать у каталозі `tests/` (а не поряд із джерельним файлом).
- *
- * Конвенція (test.mdc): `dir/foo.mjs` → тест у `dir/tests/foo.test.mjs`.
- * `*_test.rego` виключені: Rego unit-тести живуть поряд із полісі (OPA community convention).
- *
- * Пропускає: `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv` (через `walkDir`)
- * і шляхи з `.n-cursor.json:ignore`.
- */
+/** @see ./docs/location.md */
 import { basename, dirname, relative } from 'node:path'
 
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'