@nitra/cursor 3.27.0 → 3.29.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [3.29.0] - 2026-06-07
+
+### Added
+
+- resolveModel(tier) — прозорий каскадний fallback local→cloud для всіх 3 тирів (min/avg/max)
+
+## [3.28.0] - 2026-06-06
+
+### Added
+
+- lib/models.mjs: global model tier classification (LOCAL_MIN/AVG/MAX, CLOUD_MIN/AVG/MAX) via N_*_MODEL env vars; fix llm-worker uses CLOUD_MIN/AVG by default
+
+### Changed
+
+- fix orchestrator: concise output — single line when clean, details only when issues occur
+- llm-worker: rename MODEL_HAIKU/SONNET → MODEL/MODEL_HEAVY, helpful error when pi has no API key for provider
+
 ## [3.27.0] - 2026-06-06
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "3.27.0",
+  "version": "3.29.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -51,8 +51,6 @@
     "rename-yaml-extensions": "bun ./bin/n-cursor.js rename-yaml-extensions"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.0",
-    "@anthropic-ai/sdk": "^0.100.1",
     "oxc-parser": "^0.128.0",
     "picomatch": "^4.0.4",
     "smol-toml": "^1.6.1",

package/rules/abie/js/applies.mjs

@@ -1,8 +1,4 @@
-/**
- * Applies-гейт правила abie: rule-level через `isAbieRuleEnabled` (поле `rules` у `.n-cursor.json`).
- * Якщо повертає `false` — CLI пропускає всі концерни (JS і policy) цього правила.
- * `check()` друкує тільки context-pass; решта концернів роблять справжню роботу.
- */
+/** @see ./docs/applies.md */
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 
 import { isAbieRuleEnabled } from '../lib/enabled.mjs'

package/rules/abie/js/env_dns.mjs

@@ -1,12 +1,4 @@
-/**
- * Скан env-файлів abie (`*.dev.env`, `*.ua.env`): кожен внутрішньокластерний URL
- * `http://<svc>.<ns>.svc.<dns>` має відповідати кластеру за іменем файла:
- *   - `dev.env` → `abie-dev.internal` + `dev-*` namespace
- *   - `ua.env`  → `abie-ua.internal` + `ua-*` namespace
- *
- * Файл `.env` без імені (локальний для розробника) — виключено.
- * @param {string} [cwd] корінь репозиторію
- */
+/** @see ./docs/env_dns.md */
 import { readFile } from 'node:fs/promises'
 import { basename, relative } from 'node:path'
 

package/rules/abie/js/firebase_hosting.mjs

@@ -1,8 +1,4 @@
-/**
- * Перевірка abie: у **підкаталогах першого рівня** (без `.git`/`node_modules`) не має бути
- * `.firebaserc`, `firebase.json`, `.firebase/` (abie.mdc — Firebase Hosting заборонено).
- * У самому корені репозиторію ці імена не перевіряються (можуть бути від суміжних проєктів).
- */
+/** @see ./docs/firebase_hosting.md */
 import { existsSync } from 'node:fs'
 import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/abie/js/hc_pairing.mjs

@@ -1,11 +1,4 @@
-/**
- * Перевірка abie: для кожного каталогу з `kind: Deployment` під `k8s/` поруч має бути `hc.yaml`
- * з коректним modeline (yaml-language-server $schema).
- *
- * Це JS-частина (FS-парність + modeline). Структурну валідацію `HealthCheckPolicy`
- * (apiVersion, requestPath, port, targetRef з суфіксом `-hl`) робить CLI через
- * `policy/health_check_policy/target.json` (walkGlob по hc.yaml у k8s-дереві).
- */
+/** @see ./docs/hc_pairing.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'

package/rules/abie/js/ua_http_route.mjs

@@ -1,13 +1,4 @@
-/**
- * Якщо в каталозі пакета (батько `k8s/`) є `vite.config.{js,mjs,ts}`, у `ua/kustomization.yaml`
- * має бути inline-patch HTTPRoute (непорожній `target.name`): `/spec/hostnames` (домени abie),
- * `/spec/parentRefs/0/namespace` (`ua` або `ua-*`).
- *
- * Для спільних сервісів (`auth-run-hl`, `file-link-hl`) у base-HTTPRoute пакета — кожен `backendRef`
- * має `namespace: dev`; в overlay patch — JSON6902 на `/spec/rules/…/backendRefs/…/namespace` зі
- * `value: ua`. Кількість patch-ів = кількість таких посилань у base.
- * @param {string} [cwd] корінь репозиторію
- */
+/** @see ./docs/ua_http_route.md */
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 

package/rules/abie/js/ua_node_selector.mjs

@@ -1,11 +1,4 @@
-/**
- * Якщо в дереві `k8s/` пакета є `Deployment`, у `ua/kustomization.yaml` має бути inline-patch
- * на `Deployment` з `path /spec/template/spec/nodeSelector` і `preem: false` (abie.mdc).
- *
- * Структурні обмеження JSON6902 (заборона `remove + add` на той самий path) перевіряє k8s.mdc /
- * `k8s.kustomization` rego — тут лише abie-специфічне.
- * @param {string} [cwd] корінь репозиторію
- */
+/** @see ./docs/ua_node_selector.md */
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 

package/rules/adr/js/hooks.mjs

@@ -1,23 +1,4 @@
-/**
- * Перевіряє вимоги правила adr.mdc: ADR Stop-hook'и `capture-decisions.sh` і
- * `normalize-decisions.sh` у Claude Code.
- *
- * Очікування:
- * - `.claude/hooks/capture-decisions.sh` та `.claude/hooks/normalize-decisions.sh`
- *   існують і байт-у-байт збігаються з канонічними `.claude-template/hooks/*`
- *   пакета (sync керує файлами повністю).
- * - `.claude/settings.json` (project-shared) має managed-групи у `hooks.Stop` для
- *   обох скриптів (маркери у `command` — самі шляхи до скриптів).
- * - `.cursor/hooks.json` має managed entries у `hooks.stop` для обох скриптів, щоб
- *   Cursor Agent теж запускав ADR capture/normalize після завершення відповіді.
- * - `.claude/settings.local.json` (якщо існує) НЕ має дублів цих managed-груп —
- *   після переходу на project-shared такі записи створили б два запуски на одну подію.
- * - `.gitignore` у корені містить шаблон, який покриває
- *   `.claude/hooks/capture-decisions.log` і `.claude/hooks/normalize-decisions.log`.
- *
- * LLM CLI (`claude` або `cursor-agent`) у `PATH` — інформативна перевірка: якщо жодного
- * немає, скрипт працює, але мовчки виходить, тому це warning, а не fail.
- */
+/** @see ./docs/hooks.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { delimiter, dirname, join } from 'node:path'

package/rules/bun/js/layout.mjs

@@ -1,22 +1,4 @@
-/**
- * Перевіряє відповідність репозиторію правилам Bun (bun.mdc).
- *
- * **Що тут лишилося** (FS / cross-file — не покривається conftest):
- *  - наявність `bun.lock`, `bunfig.toml`, `package.json` у корені (FS-existence);
- *  - заборонені lockfile та артефакти yarn/pnpm (`package-lock.json`, `yarn.lock`,
- *    `pnpm-lock.yaml`, `.yarnrc.yml`, директорія `.yarn/`);
- *  - двосторонній зв'язок `.n-cursor.json:rules` ↔ `package.json:scripts` для правил із
- *    `lint-<id>` (`docker`, `k8s`): rule увімкнено → скрипт мусить існувати; rule
- *    відсутнє (або в `disable-rules`) → скрипту та згадки `bun run lint-<id>` у
- *    агрегованому `scripts.lint` бути **не може** (інакше `bun run lint` падатиме
- *    на правилі, яке у конфізі вимкнено).
- *
- * **Що покрила Rego** (`npx \@nitra/cursor check`):
- *  - `npm/policy/bun/bunfig/` — `[install].linker == "hoisted"` у `bunfig.toml`;
- *  - `npm/policy/bun/package_json/` — відсутність `packageManager` / `dependencies`
- *    у кореневому `package.json`, у `devDependencies` лише `@nitra/*`, агрегований
- *    `lint`-скрипт покриває всі `lint-*` через `bun run` і завершується `&& oxfmt .`.
- */
+/** @see ./docs/layout.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/capacitor/js/platforms.mjs

@@ -1,26 +1,4 @@
-/**
- * Перевіряє відповідність проєкту правилам capacitor.mdc для застосунків **Capacitor**.
- *
- * Якщо у репозиторії **немає** ознак Capacitor (див. наведене) — вихід **0**, перевірка не застосовується.
- *
- * **Ознака Capacitor:** наявні **`capacitor.config.json`**, **`capacitor.config.ts`**, **`capacitor.config.mjs`**
- * (у корені) **або** у будь-якому `package.json` (рекурсивно, з пропуском типових каталогів) оголошено
- * хоча б одну залежність **`@capacitor/…`** (у **`dependencies`**, **`devDependencies`**, опційно
- * **`optionalDependencies`**, **`peerDependencies`**).
- *
- * **Версія мінімум 8:** у кожному `package.json`, де вказано **`@capacitor/core`**, діапазон версії
- * мусить допускати лише **Capacitor 8+** (оцінка мінімального **major** з рядка діапазону npm, зокрема
- * `||` і діапазонів через `-` у спрощеному вигляді). **`*`**, **latest** та нерозпізнані випадки — **порушення**:
- * варто задати явний діапазон, наприклад **`^8.0.0`**. Якщо оголошено `capacitor.config.*` без жодного
- * **`@capacitor/core`** у дереві `package.json` — також помилка.
- *
- * **iOS:** зазвичай **без** **Podfile** поза **Pods** (тільки **SPM**). **@nitra/**-плагіни за політикою **SPM** —
- * їх **не** перелічуємо й **не** перевіряємо. Якщо **Podfile** є, його можна зареєструвати як **виняток**
- * (див. **capacitor.mdc**): у кореневому **`package.json`** або
- * **`capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`**, об’єкт **nitra** з
- * **`iosCocoaPodsBecausePluginsLackSpm: true`** (або **`iosCocoaPodsAllowed: true`**); тоді **Podfile** **не** fail.
- * Якщо **`ios/`** **немає** — iOS-умови не застосовуються.
- */
+/** @see ./docs/platforms.md */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/changelog/js/consistency.mjs

@@ -1,32 +1,4 @@
-/**
- * Перевіряє, що кожен workspace із релізно-релевантними змінами зафіксував їх через
- * change-файл `<ws>/.changes/*.md` — єдиний дозволений артефакт зміни. Bump `version`
- * і генерацію `CHANGELOG.md` робить виключно `n-cursor release` у CI на `main`.
- *
- * Інваріант (на будь-якій гілці): `version` у дереві не має **випереджати** базу. Лише
- * drift **уперед** (`version` > опублікованої в реєстрі / > git-бази) — ручний bump поза
- * CI — завалює перевірку, навіть із change-файлом. Version **позаду** бази (локаль відстала
- * від уже опублікованого CI-релізу, ще не зроблено `git pull`) — НЕ порушення: це не ручний
- * bump, а git і так не дасть запушити non-fast-forward. Pass лише коли є change-файл, а
- * version не випереджає базу; зміни без change-файлу — fail.
- *
- * Дві моделі бази — на рівні воркспейсу (див. n-changelog.mdc):
- *
- * 1) **registry-published** (npm: `name` + `files`, не `private`; Python: `project.name` +
- *    статична `project.version`): база = опублікована версія в npm / PyPI.
- * 2) **local-only** (приватні npm без `files`, Python без імені/версії для реєстру):
- *    feature-гілка — `merge-base` з `dev`, інакше з `main`; на `main` — diff від
- *    `origin/main` (або `HEAD~1` без remote).
- *
- * Усі `git` і зовнішні виклики — через `execFile` / `fetch`, без shell-інтерполяції.
- *
- * **Autofix-режим** (env `N_CURSOR_CHANGELOG_AUTOFIX=1`, виставляється лише кроком
- * `npm-changelog` у `hk.pkl` для pre-commit): замість `fail` на відсутній change-файл
- * правило саме створює його через `writeChange()` з дефолтами (`bump=patch`,
- * `section=Changed`, `message` = subject останнього коміту) і ставить у git-індекс, щоб
- * коміт не падав. Поза хуком (CI, ручний `fix`/`check`, read-only review) режим вимкнено —
- * поведінка лишається fail-on-missing, тож CI не плодить артефактів.
- */
+/** @see ./docs/consistency.md */
 import { execFile } from 'node:child_process'
 import { join } from 'node:path'
 import { promisify } from 'node:util'

package/rules/ci4/js/marksman_config.mjs

@@ -1,22 +1,4 @@
-/**
- * Концерн `marksman_config` правила ci4 (ci4.mdc): копіює canonical
- * `.marksman.toml` baseline у корінь cwd, якщо файлу ще немає.
- *
- * Marksman LSP читає `.marksman.toml` для визначення workspace-роота,
- * GLFM-флага (GitHub-Flavored Markdown), стилю wiki-links і code actions.
- * Дефолти marksman не вмикають GLFM і використовують `title-slug-ref` —
- * але portable subset з ci4.mdc вимагає GLFM (alerts/таблиці/todo) +
- * `file-stem` (ADR slug == ім'я файла). Без явного конфіга частина
- * marksman-функцій працює інакше, ніж задокументовано у правилі.
- *
- * Idempotent: якщо `.marksman.toml` вже існує (навіть з кастомним вмістом)
- * — не перетирається, тільки рапортується факт існування. Ручні правки
- * користувача зберігаються між прогонами.
- *
- * Файл скопійовано в `cwd`, бо marksman визначає workspace-root за
- * розташуванням свого `.marksman.toml`. У корені репо марксман бачить
- * і docs/, і README.md усіх workspaces одним workspace-ом.
- */
+/** @see ./docs/marksman_config.md */
 import { existsSync } from 'node:fs'
 import { copyFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'

package/rules/docker/js/lint.mjs

@@ -1,37 +1,4 @@
-/**
- * Запускає hadolint для Dockerfile / Containerfile у всьому репозиторії (див. docker.mdc).
- *
- * Додатково переконуються, що образи `oven/bun`, `alpine`, `nginx`, `node` з Docker Hub
- * вказуються через `mirror.gcr.io` (див. `./docker-mirror.mjs`).
- *
- * Також перевіряє, що Dockerfile/Containerfile має **multistage build** і що фінальний stage
- * використовує дозволений runtime-образ (див. docker.mdc):
- * - backend: `mirror.gcr.io/library/alpine:*`, `scratch`, `mirror.gcr.io/library/debian:` з тегом, що
- *   містить `slim` (не повний `debian:bookworm`), за винятком PHP/Python — `mirror.gcr.io/library/php:*` або
- *   `mirror.gcr.io/library/python:*`
- * - frontend: `mirror.gcr.io/nginxinc/nginx-unprivileged:*`, `mirror.gcr.io/openresty/openresty:*`
- *
- * Якщо в Dockerfile є крок `bun install` і це не frontend-образ (фінальний stage — alpine),
- * то очікується компіляція в один бінарник через `bun build --compile` у build stage, а у
- * фінальному stage не повинно залишатися build tooling (Bun/Node).
- *
- * Виняток — проєкти з нативним `.node`-аддоном (sharp/@img/argon2), який вантажиться через
- * динамічний `require`: їх НЕ можна компілювати (`bun build --compile` не вшиває нативний
- * біндинг → краш у рантаймі). Для них канон — node_modules + `bun <entry>` на базі
- * `mirror.gcr.io/oven/bun:alpine` (див. `../lib/docker-native-addon.mjs`).
- *
- * Мета — щоб у фінальному образі не було build tooling (Bun/Node та залежностей), а лише
- * дозволений runtime (alpine, scratch, debian slim, за потреби php/python, nginx або openresty).
- *
- * Для nginx-образів (`mirror.gcr.io/nginxinc/nginx-unprivileged`) у будь-якому `FROM` очікується
- * тег `alpine-slim` (docker.mdc: мінімальні образи), не `latest` /
- * `alpine` / інші. `nginx-unprivileged` запускається від не-root користувача (uid=101) без явного
- * `USER` у Dockerfile — перевірка non-root для нього пропускається.
- *
- * Знаходить Dockerfile, Dockerfile.*, Containerfile, Containerfile.*; пропускає node_modules, .git
- * тощо. hadolint — нативний бінарник через `ensureTool` (PATH/кеш/авто-install; без docker run).
- * Кореневий .hadolint.yaml підхоплюється hadolint автоматично.
- */
+/** @see ./docs/lint.md */
 import { readFile } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 

package/rules/ga/docs/fix.md

@@ -19,7 +19,7 @@
 
 ## Гарантії поведінки
 
-*   Запускає процес.
-*   Кеш зберігає результати попередніх прогонів.
-*   Результат залежить від попередніх прогонів.
-*   Немає взаємодії з мережею.
+- Запускає процес.
+- Кеш зберігає результати попередніх прогонів.
+- Результат залежить від попередніх прогонів.
+- Немає взаємодії з мережею.

package/rules/ga/js/docs/lint.md

@@ -14,6 +14,6 @@
 
 ## Гарантії поведінки
 
-*   Делегує правила до існуючого CLI.
-*   Не враховує `files` в режимі per-file.
-*   Не має кешування.
+- Делегує правила до існуючого CLI.
+- Не враховує `files` в режимі per-file.
+- Не має кешування.

package/rules/ga/js/docs/workflows.md

@@ -6,10 +6,10 @@
 
 ## Поведінка
 
-*   `checkShellcheckInstalled`: Перевіряє наявність бінарника `shellcheck` в системному PATH.
-*   `checkGaWorkflowFiles`: Перевіряє наявність workflow-файлів з розширенням `.yml` та відсутність інших розширень.
-*   `runAllGaRego`: Запускає Rego-перевірки для всіх workflow-файлів, використовуючи `conftest` для аналізу.
-*   `check`: Координує всі перевірки, включаючи Rego-аналіз, перевірку workflow-структури та перевірку наявність файлів.
+- `checkShellcheckInstalled`: Перевіряє наявність бінарника `shellcheck` в системному PATH.
+- `checkGaWorkflowFiles`: Перевіряє наявність workflow-файлів з розширенням `.yml` та відсутність інших розширень.
+- `runAllGaRego`: Запускає Rego-перевірки для всіх workflow-файлів, використовуючи `conftest` для аналізу.
+- `check`: Координує всі перевірки, включаючи Rego-аналіз, перевірку workflow-структури та перевірку наявність файлів.
 
 ## Публічний API
 
@@ -20,13 +20,13 @@
 
 ## Гарантії поведінки
 
-*   Гарантується наявність файлів `package.json`, `.vscode/*` та `.github/zizmor.yml`.
-*   Гарантується, що workflow використовує `actions/checkout@v6` перед локальними операціями.
-*   Гарантується, що workflow використовує composite action `action.yml` з `npx @nitra/cursor`.
-*   Гарантується, що workflow містить `clean-ga-workflows.yml`, `clean-merged-branch.yml`, `lint-ga.yml` та `git-ai.yml`.
-*   Гарантується, що workflow використовує `concurrency` для паралельного виконання.
-*   Гарантується, що workflow не містить `oven-sh/setup-bun`, `actions/cache`, `bun install` у `uses` або `run`.
-*   Гарантується, що workflow не використовує shell-продовження `\` у `run`.
-*   Гарантується, що workflow використовує `shellcheck` локально.
-*   Гарантується, що workflow перевіряє наявність файлів за допомогою `git ls-files :(glob)` та `on.*.paths`.
-*   Гарантується, що workflow перевіряє наявність файлів, що залишилися від MegaLinter.
+- Гарантується наявність файлів `package.json`, `.vscode/*` та `.github/zizmor.yml`.
+- Гарантується, що workflow використовує `actions/checkout@v6` перед локальними операціями.
+- Гарантується, що workflow використовує composite action `action.yml` з `npx @nitra/cursor`.
+- Гарантується, що workflow містить `clean-ga-workflows.yml`, `clean-merged-branch.yml`, `lint-ga.yml` та `git-ai.yml`.
+- Гарантується, що workflow використовує `concurrency` для паралельного виконання.
+- Гарантується, що workflow не містить `oven-sh/setup-bun`, `actions/cache`, `bun install` у `uses` або `run`.
+- Гарантується, що workflow не використовує shell-продовження `\` у `run`.
+- Гарантується, що workflow використовує `shellcheck` локально.
+- Гарантується, що workflow перевіряє наявність файлів за допомогою `git ls-files :(glob)` та `on.*.paths`.
+- Гарантується, що workflow перевіряє наявність файлів, що залишилися від MegaLinter.

package/rules/ga/js/workflows.mjs

@@ -1,19 +1,4 @@
-/**
- * Перевіряє GitHub Actions за правилом ga.mdc.
- *
- * Workflows лише з розширенням `.yml`, наявність clean/lint workflow,
- * відсутність MegaLinter, виклик у `lint-ga.yml`,
- * наявність composite `.github/actions/setup-bun-deps/action.yml` (його записує npx `\@nitra/cursor`),
- *
- * Структурні поля 4 канонічних workflow (`clean-ga-workflows.yml`, `clean-merged-branch.yml`,
- * `lint-ga.yml`, `git-ai.yml`) і УНІВЕРСАЛЬНІ перевірки для всіх `.github/workflows/*.yml`
- * (`concurrency`, заборонені `oven-sh/setup-bun` / `actions/cache` / `bun install` у `uses`/`run`,
- * shell-продовження `\` у `run`, обов'язковий `actions/checkout@v6` перед локальним
- * `setup-bun-deps`), а також `package.json`, `.vscode/*` і `.github/zizmor.yml` —
- * у Rego-полісі під `npm/policy/ga/`. Тут лишилися FS/git/tooling перевірки:
- * наявність файлів, MegaLinter leftovers, `on.*.paths` через `git ls-files :(glob)`,
- * і локальний `shellcheck`.
- */
+/** @see ./docs/workflows.md */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { execFileSync } from 'node:child_process'

package/rules/ga/lint/docs/lint.md

@@ -2,7 +2,7 @@
 
 ## Огляд
 
-Файл надає CLI-обгортку для інструменту `lint-ga`, який автоматично встановлює необхідні інструменти, такі як `shellcheck` та `conftest`, для перевірки коду. Він послідовно виконує перевірку коду за допомогою Rego та JavaScript, забезпечуючи узгодженість з правилами `ga.mdc`.  Цей файл служить централізованим джерелом для виконання та налаштування процесу linting, що спрощує інтеграцію в CI/CD.
+Файл надає CLI-обгортку для інструменту `lint-ga`, який автоматично встановлює необхідні інструменти, такі як `shellcheck` та `conftest`, для перевірки коду. Він послідовно виконує перевірку коду за допомогою Rego та JavaScript, забезпечуючи узгодженість з правилами `ga.mdc`. Цей файл служить централізованим джерелом для виконання та налаштування процесу linting, що спрощує інтеграцію в CI/CD.
 
 ## Поведінка
 
@@ -17,11 +17,11 @@
 
 ## Гарантії поведінки
 
-*   `ensureTool` встановлює `shellcheck` та `conftest` згідно з обраним методом встановлення (brew, scoop, GitHub Release).
-*   Якщо `uv` не встановлено, `uvx zizmor` завершується з помилкою.
-*   `bunx github-actionlint` пропускає shell-перевірки в `run:` блоках, якщо `shellcheck` не вказаний у PATH.
-*   `runLintGaCli` повертає `false` або `null` при помилках, не викликаючи виняток.
-*   Не використовується кешування.
-*   `uvx zizmor` вимагає наявності `uv`.
-*   Логіка встановлення та запуску перевірок централізована у `rules/ga/fix.mjs`.
-*   `runLintGaCli` використовується як підкоманда `lint-ga`.
+- `ensureTool` встановлює `shellcheck` та `conftest` згідно з обраним методом встановлення (brew, scoop, GitHub Release).
+- Якщо `uv` не встановлено, `uvx zizmor` завершується з помилкою.
+- `bunx github-actionlint` пропускає shell-перевірки в `run:` блоках, якщо `shellcheck` не вказаний у PATH.
+- `runLintGaCli` повертає `false` або `null` при помилках, не викликаючи виняток.
+- Не використовується кешування.
+- `uvx zizmor` вимагає наявності `uv`.
+- Логіка встановлення та запуску перевірок централізована у `rules/ga/fix.mjs`.
+- `runLintGaCli` використовується як підкоманда `lint-ga`.

package/rules/graphql/js/tooling.mjs

@@ -1,12 +1,4 @@
-/**
- * Перевіряє правило graphql.mdc: наявність **`.graphqlrc.yml`** і рекомендації
- * **`graphql.vscode-graphql`**, якщо у дереві є **`gql\`…\``**.
- *
- * Обхід репозиторію — **`walkDir`** від **`process.cwd()`** (пропуски як у інших check). Кандидати — **`.vue`** та **`.js`/`.ts`/`.jsx`/`.tsx`** тощо; пропуск **`.d.ts`**, **auto-imports.d.ts** тощо — **`shouldSkipFileForGqlScan`**.
- *
- * Виявлення **`gql`** — **oxc-parser** після витягування `<script>` з SFC (**`graphql-gql-scan.mjs`**). Якщо збігів немає — перевірка завершується успішно без вимог до конфігів.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/hasura/js/internal_urls.mjs

@@ -1,27 +1,4 @@
-/**
- * Перевіряє правило hasura.mdc для проєктів **nitra** і **abie**: значення
- * `HASURA_GRAPHQL_ENDPOINT` у `*.env` має бути **внутрішнім** кластерним URL,
- * а не публічним доменом.
- *
- * Запускається лише якщо в кореневому `package.json` поле `repository`
- * вказує на `https://github.com/nitra/...` або `https://github.com/abinbevefes/...`
- * (інші репозиторії пропускаються без помилок — як у abie-перевірках).
- *
- * Очікуваний формат URL — кластерний DNS-суфікс `<cluster>.internal`:
- *  - GKE / GCP: `http://<service>.<namespace>.svc.<cluster>.internal:<port>`
- *    приклад: `http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080`
- *
- * Сегменти беруться з `hasura/k8s/base/svc-hl.yaml` (`metadata.name` —
- * headless, має закінчуватись на `-h-hl`; див. `hasura.svc_hl` / k8s.svc_hl_yaml) і
- * `hasura/k8s/base/namespace.yaml`
- * (`metadata.name` — namespace). Якщо ці YAML є в репозиторії, у URL додатково
- * звіряються конкретні `<service>` і `<namespace>` з ними.
- *
- * Скануються всі файли `*.env` (наприклад `dev.env`, `production.env`); файл
- * `.env` без імені — виключення з правила (локальний файл розробника), його
- * не перевіряємо. Пропускаються `node_modules`, `.git`, `dist`, `coverage`,
- * `.turbo`, `.next` (як у `walkDir`).
- */
+/** @see ./docs/internal_urls.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'

package/rules/image-avif/js/avif_generation.mjs

@@ -1,30 +1,4 @@
-/**
- * Перевіряє відповідність репозиторію правилу `image-avif.mdc`: AVIF-генерацію та
- * ув'язування `.avif`-двійників з посиланнями у `.vue`/`.html`.
- *
- * Дії під час `check image-avif`:
- * 1. **Pre-scan**: знайти в `.vue`/`.html` хоча б одне raster-посилання, яке потенційно
- *    можна переписати на AVIF-двійник (через `import x from '...png'` або
- *    `<img src="...png" />`). Пакети з opt-out `disable-avif: true` пропускаються.
- *    Якщо жодного raster-посилання не знайдено → exit 0 одразу (`npx --avif` не запускаємо,
- *    rewrite/cleanup-пасс теж пропускаємо — нічого не змінилось би).
- * 2. `npx \@nitra/minify-image --src=. --write --avif` — генерує AVIF-двійники.
- * 3. У кожному workspace-пакеті переписує raster-посилання у `.vue`/`.html` на `.avif`
- *    (де AVIF-двійник реально існує на диску). Pakety з `"\@nitra/minify-image": {
- *    "disable-avif": true }` у `package.json` пропускаються.
- * 4. Прибирає AVIF-сироти — `<name>.<ext>.avif`, на які не лишилось жодного посилання
- *    у `.vue`/`.html` репозиторію, видаляються (умова правила: «AVIF лишається лише
- *    там, де заміна вдалася»).
- *
- * Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу
- * нема на диску → `.avif` теж не згенерувався) — фейл на конкретний файл.
- *
- * Правило самостійне від `image-compress`: AVIF можна вмикати лише в адмінках (де AVIF
- * підтримується сучасними браузерами) і не вмикати в публічних сайтах. Перевірка скрипта
- * `lint-image` (заборона `--avif` у ньому) залишається у `image-compress` — тут вона не
- * дублюється.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/avif_generation.md */
 import { existsSync } from 'node:fs'
 import { readFile, unlink, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/image-compress/js/package_setup.mjs

@@ -1,21 +1,4 @@
-/**
- * Перевіряє вимоги правила `image-compress.mdc` для оптимізації raster/SVG через
- * `@nitra/minify-image` ≥ 3.2.0 (локально).
- *
- * **Що тут лишилося** (FS / cross-file):
- *  - наявність `package.json` у корені;
- *  - `.n-minify-image.tsv` (committed source of truth з sha1/originalSize/size) НЕ
- *    в `.gitignore` — він має бути в git;
- *  - застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений з кореня та
- *    з `.gitignore`.
- *
- * **Що покрила Rego** (`npx \@nitra/cursor fix`,
- * `npm/rules/image-compress/policy/package_json/`):
- *  - `scripts.lint-image` викликає `npx \@nitra/minify-image --src=. --write`
- *    без `--avif` (AVIF — окреме правило `image-avif`);
- *  - агрегований `lint` (якщо є) містить `bun run lint-image`;
- *  - `@nitra/minify-image` НЕ у `dependencies` / `devDependencies` (через `npx`).
- */
+/** @see ./docs/package_setup.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/js-bun-db/js/safety.mjs

@@ -1,34 +1,4 @@
-/**
- * Перевіряє правило js-bun-db.mdc.
- *
- * 1) У жодному `package.json` (включно з workspace-пакетами) у `dependencies` не повинно
- *    бути `pg-format` чи `mysql2` — їх треба замінити на Bun native SQL
- *    (`import { sql, SQL } from 'bun'`, https://bun.com/docs/runtime/sql). `pg-format` —
- *    ручне форматування SQL через escape; tagged template Bun SQL параметризує значення
- *    нативно і не лишає простору для injection. Перевірка цих двох — у Rego-полісі
- *    `npm/policy/js_bun_db/package_json/`.
- *
- * 2) Для `pg` діє виключення: Bun SQL поки не реалізує LISTEN/NOTIFY, тож якщо у
- *    проекті знайдено реальне використання `LISTEN ...` / `NOTIFY ...` / `UNLISTEN ...`
- *    або listener'а `.on('notification', ...)`, dependency `pg` дозволено. Інакше
- *    `pg` лишається забороненим — fail з підказкою про виключення. Додатково — per-file:
- *    кожен файл з `import ... from 'pg'` повинен сам містити LISTEN/NOTIFY-патерн;
- *    звичайні SELECT/INSERT/UPDATE через `pg` (replace на Bun SQL!) не дозволені.
- *
- * 3) Якщо в коді використовується Bun SQL (імпорт `sql`/`SQL` з `'bun'`), додатково
- *    перевіряє небезпечні патерни:
- *    - `new SQL(...)` всередині функції (пул має бути singleton на рівні модуля).
- *    - Будь-який `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
- *      на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено;
- *      допустимий лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL,
- *      коли значення контролюється кодом (не user input) — в інших випадках
- *      переробляємо на tagged template `sql\`...\${value}...\``.
- *    - pg-leftover виклики `<obj>.connect(...)` / `<obj>.end(...)` у файлах, що
- *      імпортують Bun SQL: пулом керує Bun, життєвий цикл вручну не потрібен.
- *      Opt-out — маркер `// allow-pg-leftover: <reason>`.
- *    - Динамічні SQL-списки через `.join(',')` у `IN (...)` / `VALUES (...)`
- *      (треба `sql([...])`).
- */
+/** @see ./docs/safety.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-bun-redis/js/imports.mjs

@@ -1,15 +1,4 @@
-/**
- * Перевіряє правило `js-bun-redis.mdc`.
- *
- * Заборонено в JS/TS-джерелах будь-який `import` / `require` / динамічний `import()` пакетів
- * `ioredis`, `node-redis`, `redis` (та підпакетів `@redis/*`, підшляхів `ioredis/...` /
- * `redis/...`). Замість них треба використовувати Bun native Redis:
- * `import { redis } from 'bun'` (<https://bun.com/docs/runtime/redis>).
- *
- * Перевірку `dependencies` (заборона `ioredis` / `node-redis` / `redis` / `@redis/*` у будь-якому
- * `package.json`) винесено в Rego-полісі `npm/policy/js_bun_redis/package_json/`; її запускає
- * `npx \@nitra/cursor check`. Тут лишився AST-скан коду через `oxc-parser`.
- */
+/** @see ./docs/imports.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-lint/js/docs/lint-findings.md

@@ -0,0 +1,30 @@
+# lint-findings.mjs
+
+## Огляд
+
+Цей файл обробляє результати аналізу коду, отримані з інструментів oXlint та eslint, для визначення, чи є знайдені проблеми нові (в diff) чи існують у файлі з самого початку. Він класифікує ці результати, надаючи інформацію про файл та рядок, де проблема виявлена, що допомагає у відстеженні та вирішенні помилок. Це частина системи беклогу #6, яка автоматизує процес класифікації lint-findings.
+
+## Поведінка
+
+parseOxlint: аналізує JSON-вихід `oxlint --format=json` та повертає список findings з інформацією про файл, рядок, правило та повідомлення.
+parseEslint: аналізує JSON-вихід `eslint --format=json` та повертає список findings з інформацією про файл, рядок, правило та повідомлення.
+classifyFindings: класифікує findings як introduced або pre-existing на основі доданих рядків, використовуючи Map.
+renderFindings: генерує текстовий звіт з розділенням findings на introduced та pre-existing, використовуючи формат `🆕 introduced` та `🗄 pre-existing`.
+
+## Публічний API
+
+- parseOxlint — Перетворює JSON з результатів інструменту Oxlint на внутрішній об'єкт.
+- parseEslint — Перетворює JSON з результатів інструменту ESLint на внутрішній об'єкт.
+- classifyFindings — Розподіляє знайдені проблеми на нові (introduced) та існуючі (pre-existing).
+- renderFindings — Створює звіт, об'єднуючи нові та існуючі проблеми.
+
+## Гарантії поведінки
+
+- Функція `parseOxlint` повертає JSON-об'єкт, що містить список діагностик, або `null` у разі помилки парсингу.
+- Функція `parseEslint` повертає масив об'єктів, що містять повідомлення про помилки, або `null` у разі помилки парсингу.
+- Функція `classifyFindings` повертає масив об'єктів, що представляють класифіковані результати, або `null` у разі помилки класифікації.
+- Функція `renderFindings` повертає рядок, що містить представлення результатів, або `null` у разі помилки рендерингу.
+- У разі невдачі будь-якої з функцій, повертається `false`.
+- Функції не кидають винятків.
+- Шляхи файлів, що передаються вхідним функціям, є абсолютними.
+- Результати функцій не кешуються.