@nitra/cursor 1.8.180 → 1.8.185

package/CHANGELOG.md

@@ -4,6 +4,49 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.185] - 2026-05-06
+
+### Changed
+
+- `image` (mdc v1.4 → v1.5): прапорець `--avif` у `lint-image` тепер **заборонений** (інакше `bun run lint` плодив би `.avif` для зображень, що ніде не вживаються); канонічний `lint-image` — `npx @nitra/minify-image --src=. --write`. AVIF-генерацію виконує **виключно** `npx @nitra/cursor check image`. Секцію «AVIF-імпорти у `.vue`» переписано: тепер вона документує триетапну логіку `check image` — (1) запуск `npx @nitra/minify-image --src=. --write --avif`, (2) авто-заміна raster-посилань у `.vue`/`.html` на `.avif` у кожному workspace-пакеті, (3) прибирання AVIF-сиріт (файли `.avif` без жодного посилання у `.vue`/`.html` видаляються — AVIF лишається лише там, де заміна реально вдалася).
+- `check-image.mjs`: `checkLintImageScript` більше не вимагає `--avif`, натомість фейлить за його наявністю; додано `runAvifGeneration` (best-effort `npx ... --avif`, опт-аут через `NITRA_CURSOR_NO_AVIF_RUN=1` для тестів), `cleanupOrphanAvifs` (видаляє `<...>.avif` без живого посилання), `hasAnyRasterImage`, `resolveImagePath`. `checkVueAvifImportsInPackage` тепер не лише валідує, а й переписує raster-посилання на `.avif` (коли AVIF-двійник реально існує на диску); якщо `.avif` нема — фейл, як раніше. Сканування поширено на `.html` файли (раніше було тільки `.vue`).
+- `tests/check-image.test.mjs`: `CANONICAL_LINT_IMAGE` без `--avif`; кейс «без `--avif`» перейменовано/перекинуто на «з забороненим `--avif`»; додано тести на orphan-cleanup (`.avif` без посилань видаляється) та авто-заміну raster-імпорту, коли `.avif`-сусід реально існує.
+
+## [1.8.184] - 2026-05-06
+
+### Added
+
+- `check-js-run.mjs`: програмна перевірка нового правила «depcheck у GitHub Actions з path-фільтром». Для кожного backend workspace-пакета сканується `.github/workflows/*.yml`; якщо `on.push.paths` або `on.pull_request.paths` містить glob, що починається з `<rootDir>/`, у job очікується крок `npx depcheck` з `working-directory: <rootDir>` і `--ignores`, що містить мінімум `graphql,bun` (інші значення допустимі). Логіка — у новому `scripts/utils/depcheck-workflow.mjs` (парсинг `--ignores="…"` з підтримкою single/double-quote і unquoted формату; класифікація `missing` / `wrong-cwd` / `missing-ignores`).
+- `check-js-run-fixture.test.mjs`: 9 нових кейсів — нема `.github/workflows/`, глобальні paths без скоупу пакета, scoped-paths без depcheck (fail), depcheck з неправильним `working-directory` (fail), без `--ignores` (fail), `--ignores` без `bun` (fail), валідний з extra-ignores (pass), вкладений `cron-jobs/foo/src/**` як scope (pass).
+- `.github/workflows/npm-publish.yml`: додано власний крок `npx depcheck --ignores="graphql,bun,bun:test,@nitra/cursor"` з `working-directory: npm`, щоб репо `@nitra/cursor` саме відповідало новому правилу js-run (`paths: ['npm/**']` обмежено пакетом `npm`); extra-ignores потрібні для self-reference `@nitra/cursor` у devDependencies та для `bun:test` як bun-built-in.
+
+## [1.8.183] - 2026-05-06
+
+### Changed
+
+- `ga` (mdc v1.6 → v1.7): додано **універсальну** вимогу — кожен workflow у `.github/workflows/*.yml` обов'язково містить блок `concurrency` з `group: ${{ github.ref }}-${{ github.workflow }}` і `cancel-in-progress: true`. Без винятків — scheduled cleanup-воркфлоу, `pull_request: types: [closed]`, publish-воркфлоу теж. Канонічні приклади у правилі (`clean-ga-workflows.yml`, `clean-merged-branch.yml`, `git-ai.yml`) оновлено й тепер містять цей блок.
+- `check-ga.mjs`: нова перевірка `verifyConcurrencyBlock` — запускається на кожному `*.yml` у `.github/workflows/` і структурно перевіряє рівно два поля (`concurrency.group` дорівнює канонічному рядку, `concurrency.cancel-in-progress === true`); відсутність блоку, інший `group` або `cancel-in-progress: false` — fail. Спільний `validateConcurrencyOnRoot` додано в усі канонічні структурні валідатори (clean-ga-workflows, clean-merged-branch, lint-ga, git-ai), щоб ці workflow перевірялися й через шаблонну, і через універсальну логіку.
+
+## [1.8.182] - 2026-05-06
+
+### Changed
+
+- `js-run` (mdc v1.2 → v1.3): додано секцію **«depcheck у GitHub Actions з path-фільтром»** — якщо в `.github/workflows/*.yml` тригер `paths:` обмежено каталогом одного backend-пакета (наприклад `cron-jobs/refund-loyalty-points/**`), у job має бути крок `npx depcheck --ignores="graphql,bun"` з `working-directory`, що вказує на той самий каталог. Список `--ignores` обов'язково містить мінімум `graphql,bun` (peer-залежність GraphQL та рантайм Bun, які depcheck не розпізнає коректно), але може бути розширений значеннями через кому без пробілів. Не застосовується до глобальних workflow без `paths:` або з кореневими `**/*.js` патернами.
+
+## [1.8.181] - 2026-05-06
+
+### Changed
+
+- `scripts/utils/find-package-json-paths.mjs`: винесено спільну `findAllPackageJsonPaths(repoRoot, ignorePaths)` з `check-js-bun-db.mjs` і `check-js-mssql.mjs`, щоб усунути jscpd-дублювання. Самі check-скрипти тепер імпортують її, як інші утиліти з `utils/`.
+- `scripts/utils/walkDir.mjs` / `scripts/utils/load-cursor-config.mjs`: trimming trailing-slash переписано з регулярки `/\\/+$/` на `while (s.endsWith('/'))`, щоб уникнути попередження `sonarjs/slow-regex` (потенційний backtracking) — поведінка не змінилась.
+- `scripts/check-k8s.mjs`: `failIfExplicitPatchTargetsHaveRedundantGroupVersion` рефакторено — логіка одного запису винесена в новий хелпер `describePatchTargetRedundancy`, основна функція тепер просто будує повідомлення з результату (зменшено sonarjs/cognitive-complexity 24→<15, поведінка не змінилась).
+- `scripts/claude-stop-hook.mjs`: `readStdin` і `runStopHookCli` переписані з `new Promise(resolve => …)` на `events.once(stream, 'end' | 'exit')` — підказка `eslint-plugin-promise/avoid-new`, поведінка не змінилась.
+
+### Fixed
+
+- `scripts/utils/bun-sql-scan.mjs`: у JSDoc `findBunSqlUnsafeUseWithoutAllowMarkerInText` прибрано вкладений приклад із backslash-backtick (`sql\\`...\\${value}...\\``), який ламав парсер коментарів oxlint і призводив до false-positive `eslint-plugin-jsdoc(require-param)`/`(require-returns)` на функції з валідним JSDoc — текст переписано без екранованих backtick-ів.
+- Десятки `eslint-plugin-jsdoc` правил у `npm/scripts/**` та `npm/tests/**`: додано відсутні описи `@param` / `@returns` (включно зі спільним `ignorePaths`-аргументом у нових сигнатурах walkDir-обгорток), прибрано неприпустимі дефолтні значення в JSDoc (`[name=...]`) — без зміни поведінки.
+
 ## [1.8.180] - 2026-05-05
 
 ### Changed
@@ -55,9 +98,6 @@
 ### Added
 
 - Нове правило `changelog` (`mdc/changelog.mdc` + `scripts/check-changelog.mjs`): для «звичайних» Bun-монорепо проєктів вимагає, щоб у кожному workspace, який змінився відносно базової гілки `dev`, у поточному PR було підвищено `version` у `<ws>/package.json` і додано запис `## [version] - YYYY-MM-DD` у `<ws>/CHANGELOG.md` (Keep a Changelog 1.1.0). Перевірка PR-scoped: на самій гілці `dev` пропускається; на feature-гілці bump і запис достатньо зробити **один раз — як суму по всьому PR**, без бамп-шуму в проміжних комітах. Воркспейс `npm/` пропускається — його CHANGELOG покриває окреме правило `npm-module`. У `auto-rules.md` / `auto-rules.mjs` `changelog` додано до автодетекту з умовою «у корені є `package.json`» і до `AUTO_RULE_ORDER` між `capacitor` і `docker`.
-
-### Added
-
 - `.n-cursor.json` поле `ignore` (`schemas/n-cursor.json`): тепер не лише сигнал для AI, а й керує обходом усіх `check-*.mjs` / `run-*.mjs` — перелічені каталоги повністю виключаються з `walkDir`, як `node_modules` чи `.git`. Дозволяє безпечно тримати vendored Helm-чарти, генеровані маніфести, legacy-дерева у репо без false-positive’ів від check-скриптів. Розширено опис у схемі (стандартні виключення додавати не треба) і README отримав секцію «Виключення цілих дерев».
 - `scripts/utils/load-cursor-config.mjs`: нова утиліта `loadCursorIgnorePaths(root)` — читає поле `ignore` з `.n-cursor.json` і нормалізує до абсолютних posix-шляхів без trailing-slash; пропускає не-рядки та порожні елементи; повертає `[]`, якщо файлу/поля нема або JSON невалідний.
 - `scripts/utils/walkDir.mjs`: третій аргумент `ignorePaths` (за замовчуванням `[]`) — каталоги, які пропускаються разом з усім вмістом. Збіг — за повним шляхом (точний або з префіксом `/`), а не за basename, тож `postgres-master-test/` не пропускається коли в ignore лише `postgres-master/`. Стандартні пропуски (`node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`) працюють як раніше.
@@ -154,8 +194,8 @@
 
 ### Changed
 
-- `js-bun-db.mdc` (v1.4): `sql.unsafe(...)` тепер заборонено за замовчуванням — допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням; інакше переробляємо на tagged template `sql\`...${value}...\``. Кожен легітимний виклик має супроводжуватись маркером `// allow-unsafe: <причина>` на тому ж рядку або рядком вище.
-- `check-js-bun-db.mjs`: замість вузької перевірки `sql.unsafe(\`...${expr}...\`)` тепер сканер `findBunSqlUnsafeUseWithoutAllowMarkerInText` падає на будь-якому `<obj>.unsafe(...)` без маркера-коментаря з непорожньою причиною (line- або block-коментар на тому ж рядку чи безпосередньо перед викликом).
+- `js-bun-db.mdc` (v1.4): `sql.unsafe(...)` тепер заборонено за замовчуванням — допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням; інакше переробляємо на tagged template `sql\`...${value}...\``. Кожен легітимний виклик має супроводжуватись маркером`// allow-unsafe: <причина>` на тому ж рядку або рядком вище.
+- `check-js-bun-db.mjs`: замість вузької перевірки `sql.unsafe` із tagged-template і інтерполяцією тепер сканер `findBunSqlUnsafeUseWithoutAllowMarkerInText` падає на будь-якому `obj.unsafe(...)` без маркера-коментаря з непорожньою причиною (line- або block-коментар на тому ж рядку чи безпосередньо перед викликом).
 - `ast-scan-utils.mjs`: додано `parseProgramAndCommentsOrNull` — окремий вхід для перевірок, яким потрібні коментарі поряд з AST.
 
 ## [1.8.159] - 2026-05-01

package/mdc/ga.mdc

@@ -1,11 +1,21 @@
 ---
 description: Правила форматів для .github/workflows
 alwaysApply: true
-version: '1.6'
+version: '1.7'
 ---
 
 У `.github/workflows/` лише **`.yml`**. Мають бути **`clean-ga-workflows.yml`**, **`clean-merged-branch.yml`**, **`lint-ga.yml`**, **`git-ai.yml`**. Якщо є **`apply-k8s.yml`** / **`apply-nats-consumer.yml`** — paths у тригері як у фрагментах.
 
+**Кожен** workflow у `.github/workflows/*.yml` **обов'язково** містить блок `concurrency` з фіксованим `group` та `cancel-in-progress: true`:
+
+```yaml
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+```
+
+Без винятків — у scheduled cleanup-воркфлоу, у `pull_request: types: [closed]`, у publish-воркфлоу теж. Це уникає паралельних запусків того самого workflow на тій самій ref і скасовує попередні в чергу нових.
+
 Повинен бути файл .github/workflows/clean-ga-workflows.yml, зі змістом:
 
 ```yaml
@@ -18,6 +28,10 @@ on:
   # Allow workflow to be manually run from the GitHub UI
   workflow_dispatch: {}
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   cleanup_old_workflows:
     runs-on: ubuntu-latest
@@ -47,6 +61,10 @@ on:
   # Allow workflow to be manually run from the GitHub UI
   workflow_dispatch: {}
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   cleanup_old_branches:
     runs-on: ubuntu-latest
@@ -119,6 +137,10 @@ on:
   pull_request:
     types: [closed]
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   git-ai:
     if: github.event.pull_request.merged == true

package/mdc/image.mdc

@@ -1,10 +1,10 @@
 ---
 description: Оптимізація зображень через @nitra/minify-image у локальному lint
 alwaysApply: true
-version: '1.4'
+version: '1.5'
 ---
 
-CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (≥ **3.2.0**) запускається через `npx` (як `markdownlint-cli2` у text.mdc) і **не** додається в `dependencies` / `devDependencies`. Канонічний `lint-image` — авто-оптимізація з прапорцями `--write --avif`: стискає raster/SVG на місці й створює AVIF-двійники (`<name>.<ext>.avif`) поряд з кожним PNG/JPEG/GIF. Split-cache робить повторні прогони дешевими — і локально, і після `git clone`.
+CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (≥ **3.2.0**) запускається через `npx` (як `markdownlint-cli2` у text.mdc) і **не** додається в `dependencies` / `devDependencies`. Канонічний `lint-image` — авто-оптимізація з прапорцем `--write`: стискає raster/SVG на місці. **AVIF-генерація (`--avif`) у `lint-image` заборонена** — її виконує лише `npx @nitra/cursor check image`, який заодно прибирає AVIF-сироти (див. секцію «AVIF-імпорти у `.vue`»). Split-cache робить повторні прогони дешевими — і локально, і після `git clone`.
 
 Перевірка лише локальна — у CI `lint-image` не запускаємо (sharp/svgo тягнуть бінарні залежності, цінність на ubuntu-runner-ах нижча за час прогону). Окремий workflow `lint-image.yml` створювати не треба.
 
@@ -14,12 +14,12 @@ CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (
 {
   "scripts": {
     "lint": "bun run lint-js && bun run lint-text && bun run lint-ga && bun run lint-image && oxfmt .",
-    "lint-image": "npx @nitra/minify-image --src=. --write --avif"
+    "lint-image": "npx @nitra/minify-image --src=. --write"
   }
 }
 ```
 
-Якщо в `package.json` уже є агрегований `lint`, додай у його ланцюжок `bun run lint-image` (як `bun run lint-text`, `bun run lint-js`, `bun run lint-ga`). Так розробник, що локально гонить `bun run lint`, перед фіксацією одразу бачить, чи зросли зображення, і отримує свіжі AVIF-двійники.
+Якщо в `package.json` уже є агрегований `lint`, додай у його ланцюжок `bun run lint-image` (як `bun run lint-text`, `bun run lint-js`, `bun run lint-ga`). Так розробник, що локально гонить `bun run lint`, перед фіксацією одразу бачить, чи зросли зображення.
 
 ## Split-cache
 
@@ -47,13 +47,19 @@ rm -f .minify-image-cache.tsv
 # прибери відповідний рядок з .gitignore, якщо був
 ```
 
-AVIF-двійники (`<name>.<ext>.avif`) **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від `--avif` втрачається на чистому checkout-і).
+AVIF-двійники (`<name>.<ext>.avif`) **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).
 
 ## AVIF-імпорти у `.vue`
 
-Раз `--avif` гарантує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF, у `.vue` файлах потрібно посилатись саме на AVIF-двійник, а не на оригінал:
+AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor check image` — у `lint-image` прапорець `--avif` заборонений (інакше `bun run lint` плодить непотрібні `.avif` для зображень, що ніде не використовуються). Перевірка робить три кроки в порядку:
 
-```vue title="App.vue (правильно)"
+1. Запускає `npx @nitra/minify-image --src=. --write --avif` — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF.
+2. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
+   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
+   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
+3. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости».
+
+```vue title="App.vue (після check image)"
 <script setup>
 import welcomeImage from './assets/welcome.png.avif'
 </script>
@@ -63,19 +69,10 @@ import welcomeImage from './assets/welcome.png.avif'
 </template>
 ```
 
-```vue title="App.vue (неправильно — втрачає AVIF)"
-<script setup>
-import welcomeImage from './assets/welcome.png'
-</script>
-```
-
-Перевірка `check image` сканує `.vue` файли в кожному workspace-пакеті (root + workspaces) і вимагає AVIF-двійник для двох форм:
-
-1. **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні).
-2. **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
-
 Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
 
+Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image` падає з помилкою на конкретний файл, як раніше.
+
 ### Опт-аут для конкретного пакета
 
 У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл, де AVIF-підтримка не гарантована), додай у `package.json` цього пакета:
@@ -92,8 +89,8 @@ import welcomeImage from './assets/welcome.png'
 
 ## Заборонені залежності
 
-`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` кореневого `package.json` — CLI запускається лише через `npx` (так само, як `markdownlint-cli2` у text.mdc). Якщо потрібен явний пін — закладай діапазон версій npm у самому виклику (`npx @nitra/minify-image@^3 --src=. --write --avif`).
+`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` кореневого `package.json` — CLI запускається лише через `npx` (так само, як `markdownlint-cli2` у text.mdc). Якщо потрібен явний пін — закладай діапазон версій npm у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
 
 ## Перевірка
 
-`npx @nitra/cursor check image` (охоплює `lint-image` з обовʼязковими `--src=.`, `--write`, `--avif`, агрегований `lint`, `.n-minify-image.tsv` НЕ в `.gitignore` (має бути в git), відсутність застарілого `.minify-image-cache.tsv` у корені, AVIF-імпорти у `.vue` файлах кожного workspace-пакета).
+`npx @nitra/cursor check image` (охоплює `lint-image` з обовʼязковими `--src=.`, `--write` і **забороненим** `--avif`; агрегований `lint`; `.n-minify-image.tsv` НЕ в `.gitignore` — має бути в git; відсутність застарілого `.minify-image-cache.tsv` у корені; запуск AVIF-генерації + авто-заміна raster-посилань на `.avif` у `.vue`/`.html` кожного workspace-пакета + прибирання AVIF-сиріт).

package/mdc/js-run.mdc

@@ -1,7 +1,7 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.2'
+version: '1.3'
 ---
 
 ## Область застосування
@@ -136,6 +136,26 @@ console.log(env.OPTIONAL_ENV_VAR)
 `// @nitra/cursor ignore-next-line checkEnv` безпосередньо перед використанням
 (escape-hatch для legacy-коду, не для нових файлів).
 
+## depcheck у GitHub Actions з path-фільтром
+
+Якщо в `.github/workflows/*.yml` є тригер з `paths:`, який обмежує запуск workflow змінами в каталозі конкретного backend-пакета, в job цього workflow має бути крок `npx depcheck` з `working-directory`, який вказує на той самий каталог пакета. Це гарантує, що декларація залежностей у `package.json` пакета відповідає реальним імпортам — інакше можна випадково зламати білд після видалення «зайвої» залежності, яка насправді використовується через побічний імпорт.
+
+Список `--ignores` **обов'язково** містить як мінімум `graphql,bun` (це ті, які `depcheck` не вміє коректно розпізнавати: `graphql` — peer-залежність, що часто використовується без прямого імпорту в коді; `bun` — рантайм, не npm-пакет). За потреби список можна розширити іншими модулями, специфічними для пакета — список значень розділяється комою без пробілів.
+
+```yaml title="Приклад: workflow для cron-jobs/refund-loyalty-points"
+on:
+  push:
+    paths:
+      - 'cron-jobs/refund-loyalty-points/**'
+
+# …
+
+      - run: npx depcheck --ignores="graphql,bun"
+        working-directory: cron-jobs/refund-loyalty-points
+```
+
+Правило не застосовується до workflow без `paths:` або з `paths:`, який не звужує тригер до одного backend-пакета (наприклад, кореневі `lint-*.yml` з глобальними `**/*.js`).
+
 ## Перевірка
 
 `npx @nitra/cursor check js-run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.180",
+  "version": "1.8.185",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -44,11 +44,11 @@
     "oxc-parser": "^0.128.0",
     "yaml": "^2.8.3"
   },
+  "devDependencies": {
+    "@nitra/cursor": "^1.8.170"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=25"
-  },
-  "devDependencies": {
-    "@nitra/cursor": "^1.8.170"
   }
 }

package/scripts/check-abie.mjs

@@ -384,6 +384,7 @@ export function ignoreBranchesIncludesRequired(ignoreBranches, required) {
 /**
  * Збирає абсолютні шляхи до **.yaml** / **.yml** під деревом, де є сегмент **k8s**.
  * @param {string} root корінь репозиторію
+ * @param {string[]} [ignorePaths] абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані шляхи
  */
 async function findK8sYamlFiles(root, ignorePaths = []) {

package/scripts/check-changelog.mjs

@@ -41,7 +41,7 @@ const NPM_VIEW_TIMEOUT_MS = 10_000
 /**
  * Тихо запускає `git` і повертає stdout або `null` при будь-якій помилці.
  * @param {string[]} args аргументи `git`
- * @returns {Promise<string | null>}
+ * @returns {Promise<string | null>} stdout процесу або `null` при будь-якій помилці виконання
  */
 async function gitOrNull(args) {
   try {
@@ -54,7 +54,7 @@ async function gitOrNull(args) {
 
 /**
  * Чи робочий каталог — git-репозиторій.
- * @returns {Promise<boolean>}
+ * @returns {Promise<boolean>} `true`, якщо `git rev-parse --is-inside-work-tree` повернув `true`
  */
 async function isInsideGitRepo() {
   const out = await gitOrNull(['rev-parse', '--is-inside-work-tree'])
@@ -63,7 +63,7 @@ async function isInsideGitRepo() {
 
 /**
  * Назва поточної гілки (або `HEAD` для detached state).
- * @returns {Promise<string | null>}
+ * @returns {Promise<string | null>} назва гілки чи `'HEAD'`, або `null` (поза git / помилка)
  */
 async function currentBranchName() {
   const out = await gitOrNull(['rev-parse', '--abbrev-ref', 'HEAD'])
@@ -73,7 +73,7 @@ async function currentBranchName() {
 /**
  * Знаходить ref для базової гілки. Перевага локальному `dev`, далі `origin/dev`. Повертає `null`,
  * якщо жоден не існує.
- * @returns {Promise<string | null>}
+ * @returns {Promise<string | null>} назва ref-а (`dev` чи `origin/dev`) або `null`, якщо жоден не знайдено
  */
 async function resolveBaseRef() {
   for (const ref of [BASE_BRANCH, `origin/${BASE_BRANCH}`]) {
@@ -88,8 +88,8 @@ async function resolveBaseRef() {
 /**
  * Точка розгалуження поточної гілки від `baseRef`. На feature-гілці = коли вона відгалузилась;
  * на `main` після merge `dev → main` = поточний `dev`. Повертає `null`, якщо merge-base нема.
- * @param {string} baseRef
- * @returns {Promise<string | null>}
+ * @param {string} baseRef SHA або ref-name бази (зазвичай `dev` / `origin/dev`)
+ * @returns {Promise<string | null>} SHA точки розгалуження або `null`, якщо merge-base нема
  */
 async function resolveMergeBase(baseRef) {
   const out = await gitOrNull(['merge-base', baseRef, 'HEAD'])
@@ -104,9 +104,9 @@ async function resolveMergeBase(baseRef) {
  * Для кореня `.` — це точка плюс magic-виключення кожного підворкспейсу через `:(exclude)<sub>/`,
  * щоб зміни всередині sub-workspace не вважалися змінами кореня.
  * Для звичайного воркспейсу — просто `<ws>/`.
- * @param {string} ws
- * @param {string[]} subWorkspaces
- * @returns {string[]}
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня, інакше — відносний шлях, як у `workspaces`)
+ * @param {string[]} subWorkspaces усі під-воркспейси (зокрема для `'.'` потрібно виключити їх)
+ * @returns {string[]} pathspec для git: масив, що передається після `--`
  */
 function pathspecForWorkspace(ws, subWorkspaces) {
   if (ws !== '.') return [`${ws}/`]
@@ -119,9 +119,9 @@ function pathspecForWorkspace(ws, subWorkspaces) {
  * `git diff --quiet <baseRef> -- <pathspec>` ловить committed-зміни на цій гілці й незбережені
  * правки tracked-файлів. Untracked-файли — `git ls-files --others --exclude-standard`.
  * @param {string} baseRef SHA або ref-name (зокрема merge-base)
- * @param {string} ws
- * @param {string[]} subWorkspaces
- * @returns {Promise<boolean>}
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {string[]} subWorkspaces усі під-воркспейси для коректного формування pathspec кореня
+ * @returns {Promise<boolean>} `true`, якщо в межах воркспейсу є будь-які зміни (committed або untracked)
  */
 async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
   const pathspec = pathspecForWorkspace(ws, subWorkspaces)
@@ -129,8 +129,7 @@ async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
     await execFileAsync('git', ['diff', '--quiet', baseRef, '--', ...pathspec])
   } catch (error) {
     const code = /** @type {{ code?: number }} */ (error).code
-    if (code === 1) return true
-    return false
+    return code === 1
   }
   const untracked = await gitOrNull(['ls-files', '--others', '--exclude-standard', '--', ...pathspec])
   return typeof untracked === 'string' && untracked.trim().length > 0
@@ -138,9 +137,9 @@ async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
 
 /**
  * Версія з `<ws>/package.json` на `baseRef` або `null`.
- * @param {string} baseRef
- * @param {string} ws
- * @returns {Promise<string | null>}
+ * @param {string} baseRef SHA або ref-name (зазвичай merge-base) для `git show`
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @returns {Promise<string | null>} значення поля `version` або `null`, якщо файла нема / JSON некоректний
  */
 async function readBaseVersion(baseRef, ws) {
   const wsPath = ws === '.' ? 'package.json' : `${ws}/package.json`
@@ -156,9 +155,9 @@ async function readBaseVersion(baseRef, ws) {
 
 /**
  * Чи містить текст `CHANGELOG.md` запис `## [version]` (з опційним `- YYYY-MM-DD`).
- * @param {string} text
- * @param {string} version
- * @returns {boolean}
+ * @param {string} text вміст CHANGELOG.md
+ * @param {string} version версія, яку шукаємо у форматі Keep a Changelog
+ * @returns {boolean} `true`, якщо запис для `version` знайдено
  */
 function changelogHasVersionEntry(text, version) {
   const escaped = version.replaceAll(/[.+*?^$()[\]{}|\\]/g, String.raw`\$&`)
@@ -168,8 +167,8 @@ function changelogHasVersionEntry(text, version) {
 
 /**
  * Зчитує `<ws>/package.json`. `null`, якщо файл відсутній або JSON некоректний.
- * @param {string} ws
- * @returns {Promise<Record<string, unknown> | null>}
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @returns {Promise<Record<string, unknown> | null>} розпарсений `package.json` або `null`
  */
 async function readPackageJsonOrNull(ws) {
   const path = join(ws, 'package.json')
@@ -186,8 +185,8 @@ async function readPackageJsonOrNull(ws) {
 
 /**
  * Воркспейс публікується в npm: має непорожній `name`, не `private: true`, і має масив `files`.
- * @param {Record<string, unknown> | null} pkg
- * @returns {boolean}
+ * @param {Record<string, unknown> | null} pkg розпарсений `package.json` (або `null`)
+ * @returns {boolean} `true`, якщо пакет придатний для публікації в npm
  */
 function isNpmPublishable(pkg) {
   if (!pkg) return false
@@ -199,8 +198,8 @@ function isNpmPublishable(pkg) {
 /**
  * Опублікована версія пакета в npm-реєстрі. `null` — пакет не знайдено / нема мережі / помилка.
  * Дефолтна імплементація — `npm view <name> version` із таймаутом, щоб не блокуватись офлайн.
- * @param {string} name
- * @returns {Promise<string | null>}
+ * @param {string} name повна назва пакета (включно зі скоупом)
+ * @returns {Promise<string | null>} опублікована версія або `null` (нема пакета / офлайн)
  */
 async function defaultGetPublishedVersion(name) {
   try {
@@ -214,10 +213,10 @@ async function defaultGetPublishedVersion(name) {
 
 /**
  * Перевіряє масив `files` у `<ws>/package.json`: якщо оголошено — має містити `"CHANGELOG.md"`.
- * @param {Record<string, unknown> | null} pkg
- * @param {string} ws
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {Record<string, unknown> | null} pkg розпарсений `package.json` воркспейсу
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  */
 function checkFilesArrayContainsChangelog(pkg, ws, pass, fail) {
   if (!pkg || !Array.isArray(pkg.files)) return
@@ -231,10 +230,10 @@ function checkFilesArrayContainsChangelog(pkg, ws, pass, fail) {
 
 /**
  * Перевіряє наявність запису у `<ws>/CHANGELOG.md` для версії `version`.
- * @param {string} ws
- * @param {string} version
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {string} version версія, для якої очікується запис
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<boolean>} `false`, якщо файл відсутній або немає запису
  */
 async function verifyChangelogEntry(ws, version, pass, fail) {
@@ -257,11 +256,11 @@ async function verifyChangelogEntry(ws, version, pass, fail) {
  * npm-published режим: порівнює локальну `version` з опублікованою в реєстрі. Якщо вони
  * відрізняються — вимагає запис у CHANGELOG і `"CHANGELOG.md"` у `files`. Якщо реєстр недосяжний,
  * правило fail-safe пасує (щоб офлайн-розробка не блокувалась).
- * @param {string} ws
- * @param {Record<string, unknown>} pkg
- * @param {(name: string) => Promise<string | null>} getPublishedVersion
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {Record<string, unknown>} pkg розпарсений `package.json` воркспейсу
+ * @param {(name: string) => Promise<string | null>} getPublishedVersion стаб/реальна функція отримання опублікованої версії
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  */
 async function checkPublishedWorkspace(ws, pkg, getPublishedVersion, pass, fail) {
   const label = ws === '.' ? '<root>' : ws
@@ -289,10 +288,10 @@ async function checkPublishedWorkspace(ws, pkg, getPublishedVersion, pass, fail)
  * local-only режим: PR-scoped перевірка проти `dev` через `git merge-base`. Викликається лише
  * для воркспейсів, де є реальні зміни щодо merge-base.
  * @param {string} mergeBase SHA точки розгалуження
- * @param {string} ws
- * @param {Record<string, unknown> | null} pkg
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {Record<string, unknown> | null} pkg розпарсений `package.json` воркспейсу (або `null`)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  */
 async function checkLocalOnlyChangedWorkspace(mergeBase, ws, pkg, pass, fail) {
   const label = ws === '.' ? '<root>' : ws
@@ -315,12 +314,12 @@ async function checkLocalOnlyChangedWorkspace(mergeBase, ws, pkg, pass, fail) {
 
 /**
  * Виконує local-only перевірку для всіх workspace-ів, у яких немає npm-published режиму.
- * @param {string[]} localOnlyWorkspaces
- * @param {Map<string, Record<string, unknown> | null>} pkgByWs
- * @param {string[]} subWorkspaces
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
- * @returns {Promise<void>}
+ * @param {string[]} localOnlyWorkspaces список шляхів local-only воркспейсів
+ * @param {Map<string, Record<string, unknown> | null>} pkgByWs мапа: шлях воркспейсу → розпарсений `package.json` (або `null`)
+ * @param {string[]} subWorkspaces усі під-воркспейси (для коректного pathspec кореня)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>} резолвиться по завершенню перевірок усіх local-only воркспейсів
  */
 async function runLocalOnlyChecks(localOnlyWorkspaces, pkgByWs, subWorkspaces, pass, fail) {
   if (localOnlyWorkspaces.length === 0) return
@@ -358,7 +357,7 @@ async function runLocalOnlyChecks(localOnlyWorkspaces, pkgByWs, subWorkspaces, p
 
 /**
  * Перевіряє відповідність проєкту правилу changelog.mdc.
- * @param {object} [opts]
+ * @param {object} [opts] опції перевірки
  * @param {(name: string) => Promise<string | null>} [opts.getPublishedVersion] перевизначення для тестів
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
  */