@nitra/cursor 1.30.0 → 1.34.1

package/CHANGELOG.md

@@ -1,9 +1,73 @@
 # Changelog
 
+## [1.34.1] - 2026-05-30
+
+### Added
+
+- Нові тест-файли (10 файлів, 108+ тестів): rules/abie/js/tests/ (firebase_hosting, env_dns, hc_pairing, ua_node_selector, ua_http_route), rules/abie/lib/tests/hc-yaml.test.mjs, rules/abie/lib/tests/k8s-tree.test.mjs, rules/docker/lib/tests/docker-hadolint.test.mjs, rules/docker/lint/tests/lint.test.mjs, scripts/tests/coverage-fix.test.mjs; розширено scripts/tests/upgrade-nitra-cursor-and-install.test.mjs. Lines coverage: 77.62% → 78.80%, Functions: 84.47% → 86.13%.
+
+### Changed
+
+- coverage: не додавати підсумковий рядок "Разом" коли провайдер один (дублював би єдиний рядок)
+
 Усі помітні зміни цього модуля документуються тут.
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
-# [1.30.0] - 2026-05-29
+
+## [1.34.0] - 2026-05-30
+
+### Added
+
+- Тести для `bun-sql-scan.mjs`: `findPgFormatShimDefinitionInText`, `findPgFormatLikeQueryWrapperInText`, `findUnsafeBunSqlInListMissingEmptyGuardInText`, `findPgListenNotifyUsageInText`
+- Тести для `capacitor/platforms.mjs`: semver edge-cases, `recordCapacitorFromOnePackageJson`, `collectCapacitorDataFromAllPackageJson`, nitra-exceptions via config files
+- Тести для `ga/workflows.mjs`: no .github/workflows dir, .yaml extension, MegaLinter detection, apply-k8s paths trigger
+- Тести для `nginx-default-tpl/template.mjs` і `vue/packages.mjs` через check-rule-fixtures.test.mjs
+
+## [1.33.0] - 2026-05-30
+
+### Added
+
+- `n-cursor change` / `n-cursor release` — change-файли `<ws>/.changes/*.md` замість ручного bump/CHANGELOG; реліз агрегує їх у CI, ставить git-тег `<name>@<version>`. Підтримка npm і Python workspace.
+
+### Changed
+
+- `n-changelog.mdc` v3.0: feature-флоу кладе change-файл; `fix changelog` приймає change-файл або ручний bump.
+
+## [1.32.0] - 2026-05-30
+
+### Added
+
+- **`rules/ci4/js/marksman_config.mjs`** + **`rules/ci4/js/data/marksman_config/marksman.baseline.toml`** — новий JS-концерн `marksman_config` за зразком `test.stryker_config`: при `npx @nitra/cursor fix ci4` копіює canonical `.marksman.toml` baseline у корінь cwd, якщо файлу ще немає. Idempotent через паттерн `ensureBaselineFile` (existsSync → pass+skip vs copyFile → pass+create) — ручні правки користувача між прогонами зберігаються, повторний прогон не перетирає. Baseline містить три ключові опції: `[core] markdown.glfm = true` (GLFM-фічі portable subset — alerts/таблиці/todo), `[completion] wiki.style = "file-stem"` (ADR slug == ім'я файла; стабільний ідентифікатор у AUTOGEN `sources`/manifest/валідаторі — заголовок міняється, посилання не ламається), `[code_action] toc.enable = true` (Insert/Update TOC code action для довгих arc42-сторінок). Дефолти marksman (`title-slug-ref` + вимкнений GLFM) ламали б частину задокументованої навігації. Розміщення в `cwd` (корені репо) робить весь монорепо одним marksman-workspace — README.md і docs/ перехресно навігуються. Тести: `+4` сценарії у `rules/ci4/js/tests/marksman_config.test.mjs` через `withTmpDir` (порожній cwd → файл створюється; idempotency — кастомний контент не перетирається; валідні TOML-секції `[core]`/`[completion]`/`[code_action]`; exit 0 у обох сценаріях). 4/4 PASS через `bunx vitest run rules/ci4/js/tests/marksman_config.test.mjs`.
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 3.1 → 3.2) — у секцію «Viewer/editor: Zed + marksman LSP» додано параграф про авто-створення `.marksman.toml` правилом ci4 з посиланням на canonical baseline і поясненням кожної з трьох ключових опцій (glfm/wiki.style/toc.enable). У frontmatter `description` додано пункт про `.marksman.toml`. Дзеркало `.cursor/rules/n-ci4.mdc` синхронізується наступним прогоном `npx @nitra/cursor`.
+
+## [1.31.0] - 2026-05-30
+
+### Added
+
+- **`rules/ci4/policy/vscode_extensions/`** — нова policy за зразком text/style-lint/rego/ga/js-lint/graphql/nginx-default-tpl/rust/tauri: `vscode_extensions.rego` (deny якщо рекомендація з template-snippet відсутня в `.vscode/extensions.json`) + `vscode_extensions_test.rego` (5 сценаріїв: canonical, missing marksman, empty recommendations, extra recommendations пропускаються, drift-test що канон керується через `data.template`) + `template/extensions.json.snippet.json` (`{"recommendations": ["arr.marksman"]}`) + `target.json` (single `.vscode/extensions.json`). Призначення — контрибʼютори, що працюють у VSCode/Cursor замість Zed, отримують той самий шар marksman-навігації (cmd+click по `[link](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування заголовків) через офіційне розширення marksman LSP. Дзеркальна правка у репо: `.vscode/extensions.json` отримав `arr.marksman` у `recommendations`. Тести: 5/5 PASS через `opa test npm/rules/ci4/policy/vscode_extensions/`.
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 3.0 → 3.1) — у секцію «Viewer/editor: Zed + marksman LSP» додано підсекцію **«VSCode-альтернатива»** з канонічним JSON-блоком `.vscode/extensions.json` (`recommendations: ["arr.marksman"]`) і посиланням на snippet-файл policy (за стилем `text.mdc`); також згадка про marksman-сумісні редактори (Neovim, Helix, Emacs). У frontmatter `description` додано пункт про VSCode-розширення. Дзеркало `.cursor/rules/n-ci4.mdc` синхронізується наступним прогоном `npx @nitra/cursor`.
+
+### Fixed
+
+- **`vitest.config.js`** — git-залежні тести (`rules/changelog/check.test.mjs`, `rules/ga/workflows.test.mjs`) масово таймаутили локально (`23 failed | 13 passed`, 187s; усі фейли — `Test timed out in 5000ms`, не assertion), хоча в CI зелені. Першопричина: глобальний `~/.gitconfig` тестової машини має `trace2.eventtarget=af_unix:stream:~/.git-ai/.../trace2.sock` (tooling `git-ai`), який успадковується tmp-репо в тестах → кожна git-команда під'єднується до Unix-сокета даемона; коли даемон деградований, запис у сокет блокується (~1s/команда не на CPU), а під `pool: 'forks'` десятки паралельних git-операцій × латентність > 5000ms `testTimeout`. Фікс: `env: { GIT_TRACE2_EVENT: '0' }` прибирає trace2-залежність із гарячого шляху тестового git (root-cause), плюс `testTimeout: 20000` як defence-in-depth проти будь-якої залишкової локальної I/O-латентності. Після фіксу `bun run vitest run rules/changelog/` → `36 passed` за ~7s (відтворювано); повний suite — `1248 passed | 2 skipped`. CI не зачеплено (там немає trace2-таргета).
+
+## [1.30.1] - 2026-05-29
+
+### Added
+
+- **`rules/test/coverage/tests/coverage.test.mjs`** — три нові тести `/n-coverage-fix`-ітерації, що вбивають усі чотири вцілілі мутанти на `rules/test/coverage/coverage.mjs`. (1) `opts.fix=false → fixSurvivedMutants НЕ викликається` і (2) `opts.fix=true → fixSurvivedMutants викликається` фіксують умовну гілку `if (opts.fix)` (L189) через лог `'✓ Всі мутанти вбиті — доповнення тестів не потрібне'`, який друкує `fixSurvivedMutants` для порожнього `survived[]`. (3) `source 2-ї стрілки містить fix:false` перевіряє джерело захопленої callback-стрілки 2-го `withLock` через `Function.prototype.toString()`: токени `fix` і `false` мають бути присутні, а `fix: true` — заборонений; це поведінково невловимо (`{}` і `{ fix: false }` дають однаковий falsy `opts.fix`), тому інваріант на рівні джерела.
+
+### Fixed
+
+- **`CHANGELOG.md`** — заголовок секції `[1.30.0]` піднято з `#` на `##` (Keep a Changelog vN.M.M вимагає H2 для версій). Чек `npm-module.mdc` зчитував h1 як «без версії», знаходив `[1.29.5]` першою і скаржився на розбіжність із `package.json#version "1.30.0"`.
+
+## [1.30.0] - 2026-05-29
 
 ### Changed
 

package/bin/n-cursor.js

@@ -1501,6 +1501,18 @@ try {
 
       break
     }
+    case 'change': {
+      const { runChangeCli } = await import('../rules/release/change.mjs')
+      process.exitCode = await runChangeCli(args)
+
+      break
+    }
+    case 'release': {
+      const { runReleaseCli } = await import('../rules/release/release.mjs')
+      process.exitCode = await runReleaseCli(args)
+
+      break
+    }
     case 'skill': {
       process.exitCode = runSkillsCli(args)
 
@@ -1515,7 +1527,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, skill`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill`
       )
       process.exitCode = 1
     }

package/github-actions/release/action.yml

@@ -0,0 +1,9 @@
+name: n-cursor release
+description: Aggregate .changes/* into version bump + CHANGELOG, tag <name>@<version>, commit back
+
+runs:
+  using: composite
+  steps:
+    - name: Release (bump + CHANGELOG + tag)
+      shell: bash
+      run: npx @nitra/cursor release

package/package.json

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

package/rules/changelog/changelog.mdc

@@ -1,6 +1,6 @@
 ---
 description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння (npm і Python)
-version: '2.6'
+version: '3.0'
 alwaysApply: true
 ---
 
@@ -8,9 +8,11 @@ alwaysApply: true
 
 > **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
 
-1. **`version`** у `<ws>/package.json` (або `[project].version` у `pyproject.toml`) → **patch +1** відносно `git show HEAD:<ws>/package.json`, якщо ще не піднято.
-2. **`CHANGELOG.md`** того workspace → **нова** секція `## [версія] - YYYY-MM-DD` **зверху** (не bullet-и в стару версію).
-3. **`npx @nitra/cursor fix changelog`** (у репо `@nitra/cursor`: `bun ./npm/bin/n-cursor.js check changelog`) → exit **`0`**.
+1. **Поклади change-файл** `<ws>/.changes/<timestamp>-<rand>.md` з frontmatter `bump:` (`major|minor|patch`) + `section:` (`Added|Changed|Fixed|Removed`) і текстом опису. Команда: `npx @nitra/cursor change --bump <…> --section <…> --message "<…>" [--ws <шлях>]`.
+2. **Не** редагуй `version` і `CHANGELOG.md` вручну — їх формує `n-cursor release` у CI на `main` (агрегує change-файли, ставить git-тег `<name>@<version>`).
+3. **`npx @nitra/cursor fix changelog`** → exit **`0`** (м'яка перевірка: достатньо наявності change-файлу **або** вже піднятого `version`).
+
+**Legacy / hotfix:** ручний bump `version` + новий запис у `CHANGELOG.md` усе ще приймається перевіркою як альтернатива change-файлу.
 
 **Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
 

package/rules/changelog/js/consistency.mjs

@@ -29,6 +29,7 @@ import {
   parsePyprojectFields,
   readPackageManifest
 } from '../lib/package-manifest.mjs'
+import { readChangeFiles } from '../../release/lib/change-file.mjs'
 
 const execFileAsync = promisify(execFile)
 
@@ -395,6 +396,17 @@ function workspaceLabel(manifest) {
   return manifest.ws === '.' ? '<root>' : manifest.ws
 }
 
+/**
+ * Чи має workspace незрелізні change-файли (намір зафіксовано — bump зробить CI).
+ * @param {string} ws workspace
+ * @param {string} cwd корінь
+ * @returns {Promise<boolean>} результат
+ */
+async function hasPendingChangeFiles(ws, cwd) {
+  const files = await readChangeFiles(ws, cwd)
+  return files.length > 0
+}
+
 /**
  * @param {import('../lib/package-manifest.mjs').PackageManifest} manifest параметр
  * @param {string} Vcurrent параметр
@@ -407,6 +419,10 @@ function workspaceLabel(manifest) {
 async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subWorkspaces, pass, fail, cwd) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
+  if (await hasPendingChangeFiles(manifest.ws, cwd)) {
+    pass(`${label}: є change-файл(и) у .changes/ — bump зробить CI (n-changelog.mdc)`)
+    return
+  }
   if (!(await isInsideGitRepo(cwd))) {
     return
   }
@@ -502,6 +518,10 @@ async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVers
 async function checkLocalOnlyChangedWorkspace(comparisonRef, manifest, baseLabel, pass, fail, cwd) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
+  if (await hasPendingChangeFiles(manifest.ws, cwd)) {
+    pass(`${label}: є change-файл(и) у .changes/ — bump зробить CI (n-changelog.mdc)`)
+    return
+  }
   const Vcurrent = manifest.version
   if (!Vcurrent) {
     fail(`${label}: у ${mf} відсутнє поле version (потрібне для запису в CHANGELOG)`)

package/rules/ci4/ci4.mdc

@@ -1,7 +1,7 @@
 ---
-description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; Zed + marksman LSP як viewer без site-generator-а, portable subset (CommonMark + GFM + Mermaid + KaTeX), collapsible engineer-блоки через нативний `<details>`
+description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; Zed + marksman LSP як viewer без site-generator-а, portable subset (CommonMark + GFM + Mermaid + KaTeX), collapsible engineer-блоки через нативний `<details>`; рекомендоване VSCode-розширення `arr.marksman` для контрибʼюторів поза Zed; `.marksman.toml` авто-створюється у корені проєкту з canonical baseline
 alwaysApply: true
-version: '3.0'
+version: '3.2'
 ---
 
 Архітектурна документація проєкту живе у Markdown поряд із кодом. Це не довідник «для людей із порталу архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops).
@@ -208,6 +208,18 @@ User Service відповідає за автентифікацію та про
 }
 ```
 
+**`.marksman.toml`** у корені проєкту авто-створюється правилом ci4 при першому `npx @nitra/cursor fix ci4` із canonical baseline ([data/marksman_config/marksman.baseline.toml](./js/data/marksman_config/marksman.baseline.toml)). Ключові опції — `markdown.glfm = true` (потрібен для GFM-alerts/таблиць/todo з portable subset), `[completion] wiki.style = "file-stem"` (ADR slug == ім'я файла, стабільний ідентифікатор у AUTOGEN `sources`/manifest/валідаторі — заголовок змінюється, посилання не ламається), `[code_action] toc.enable = true` (TOC code action для довгих arc42-сторінок). Без явного конфіга marksman використовує `title-slug-ref` і вимкнений GLFM — частина задокументованої навігації працювала б інакше. Ручні правки конфіга не перетираються — `ensureBaselineFile` ідемпотентний.
+
+**VSCode-альтернатива.** Контрибʼютори, що працюють у VSCode/Cursor замість Zed, отримують той самий шар навігації через офіційне розширення marksman LSP. Канонічний запис у `.vscode/extensions.json`:
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["arr.marksman"]
+}
+```
+
+Канон `recommendations` (substring requirement): [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json). Інші marksman-сумісні редактори (Neovim, Helix, Emacs) налаштовують `marksman` як LSP-сервер за документацією свого редактора — поведінка ідентична (cmd+click по `[link](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування).
+
 **Portable-only синтаксис.** Усе, що пишемо в `docs/`, обмежене **CommonMark + GFM + Mermaid у fenced code (` ```mermaid `) + KaTeX (`$...$`) + нативний HTML5 `<details>`**. Заборонено:
 
 - pymdownx admonitions (`!!! note`, `??? engineer`, `=== "tab"`)

package/rules/ci4/js/data/marksman_config/marksman.baseline.toml

@@ -0,0 +1,27 @@
+# Workspace-маркер marksman LSP. У корені репо робить весь монорепо одним
+# marksman-workspace — README.md і docs/ перехресно навігуються через
+# [text](file.md) і [[wiki-link]]. Файли .mdc не індексуються — marksman
+# дивиться лише на розширення нижче.
+#
+# Створюється правилом ci4 (npx @nitra/cursor fix ci4) із canonical baseline.
+# Ручні правки не перетираються: повторні прогони ідемпотентні (no-op).
+
+[core]
+markdown.file_extensions = ["md", "markdown"]
+
+# GitHub-Flavored Markdown (таблиці, todo, alerts, math) — наш portable subset.
+markdown.glfm = true
+
+[completion]
+# Стиль резолву [[wiki-link]]:
+#   "file-stem"      → [[oidc-pkce-flow]] резолвиться у docs/adr/oidc-pkce-flow.md
+#   "title-slug-ref" → резолв за slugified H1 заголовком
+# Беремо file-stem: ADR-slug == ім'я файла, стабільний ідентифікатор у
+# AUTOGEN sources, manifest, валідаторі. Заголовок може мінятися — посилання
+# не ламається.
+wiki.style = "file-stem"
+
+[code_action]
+# Code action "Insert/Update TOC" — корисно для довгих arc42-сторінок
+# (architecture.md з 12 розділами).
+toc.enable = true

package/rules/ci4/js/marksman_config.mjs

@@ -0,0 +1,52 @@
+/**
+ * Концерн `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-ом.
+ */
+import { existsSync } from 'node:fs'
+import { copyFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const MARKSMAN_BASELINE_PATH = join(HERE, 'data', 'marksman_config', 'marksman.baseline.toml')
+const MARKSMAN_TARGET_FILENAME = '.marksman.toml'
+
+/**
+ * @param {string} [cwd] корінь проєкту (default: `process.cwd()` — CLI-сумісність)
+ * @returns {Promise<number>} 0 — OK (створено або вже існує), 1 — baseline-файл пакета зламаний
+ */
+export async function check(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+
+  if (!existsSync(MARKSMAN_BASELINE_PATH)) {
+    reporter.fail(`canonical baseline не знайдено (${MARKSMAN_BASELINE_PATH}) — перевстанови @nitra/cursor`)
+    return reporter.getExitCode()
+  }
+
+  const target = join(cwd, MARKSMAN_TARGET_FILENAME)
+  if (existsSync(target)) {
+    reporter.pass(`${MARKSMAN_TARGET_FILENAME} існує (${relative(cwd, target)})`)
+    return reporter.getExitCode()
+  }
+
+  await copyFile(MARKSMAN_BASELINE_PATH, target)
+  reporter.pass(`${MARKSMAN_TARGET_FILENAME} створено з canonical baseline (${relative(cwd, target)}) (ci4.mdc)`)
+  return reporter.getExitCode()
+}

package/rules/ci4/policy/vscode_extensions/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": ".vscode/extensions.json" }
+}

package/rules/ci4/policy/vscode_extensions/template/extensions.json.snippet.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["arr.marksman"]
+}

package/rules/ci4/policy/vscode_extensions/vscode_extensions.rego

@@ -0,0 +1,12 @@
+# Перевірка `.vscode/extensions.json` для ci4 (ci4.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+package ci4.vscode_extensions
+
+import rego.v1
+
+deny contains msg if {
+	some rec in data.template.snippet.recommendations
+	not rec in {r | some r in object.get(input, "recommendations", [])}
+	msg := sprintf(".vscode/extensions.json: recommendations має містити %q (ci4.mdc)", [rec])
+}

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

@@ -359,6 +359,7 @@ async function checkDockerfiles(root, ignorePaths, passFn, failFn) {
  * `default.conf.template` (умовне правило — без шаблона цей крок не запускається).
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
+ * @param {string} cwd корінь репозиторію
  * @returns {void}
  */
 function checkVscodeNginx(passFn, failFn, cwd) {

package/rules/release/change.mjs

@@ -0,0 +1,57 @@
+/**
+ * `n-cursor change` — пише один change-файл `<ws>/.changes/<timestamp>-<rand>.md`.
+ * Замінює ручне редагування CHANGELOG у feature-флоу (n-changelog.mdc v3.0).
+ */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { CHANGES_DIR, newChangeFileName, parseChangeFile, serializeChangeFile } from './lib/change-file.mjs'
+
+/**
+ * @param {object} params параметри
+ * @param {string} params.bump `major|minor|patch`
+ * @param {string} params.section `Added|Changed|Fixed|Removed`
+ * @param {string} params.message опис
+ * @param {string} [params.ws] workspace (за замовчуванням `.`)
+ * @param {string} [params.cwd] корінь
+ * @returns {Promise<string>} відносний шлях створеного файлу (від ws)
+ */
+export async function writeChange({ bump, section, message, ws = '.', cwd = process.cwd() }) {
+  const description = (message ?? '').trim()
+  const content = serializeChangeFile({ bump, section, description })
+  // Валідація полів: parseChangeFile кидає зрозумілу помилку на невалідних bump/section/порожньому описі.
+  parseChangeFile(content)
+
+  const dir = join(cwd, ws, CHANGES_DIR)
+  await mkdir(dir, { recursive: true })
+  const name = newChangeFileName()
+  await writeFile(join(dir, name), content)
+  return join(CHANGES_DIR, name)
+}
+
+/**
+ * @param {string[]} args аргументи CLI (`--bump`, `--section`, `--message`, `--ws`)
+ * @returns {Promise<number>} exit-код
+ */
+export async function runChangeCli(args) {
+  const get = flag => {
+    const i = args.indexOf(flag)
+    return i !== -1 && i + 1 < args.length ? args[i + 1] : undefined
+  }
+  const bump = get('--bump')
+  const section = get('--section')
+  const message = get('--message')
+  const ws = get('--ws') ?? '.'
+  if (!bump || !section || !message) {
+    console.error('❌ Використання: n-cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]')
+    return 1
+  }
+  try {
+    const rel = await writeChange({ bump, section, message, ws })
+    console.log(`✅ ${join(ws, rel)}`)
+    return 0
+  } catch (error) {
+    console.error(`❌ ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/rules/release/fix.mjs

@@ -0,0 +1,17 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  process.exit(await runRuleCli(import.meta.dirname))
+}

package/rules/release/lib/aggregate.mjs

@@ -0,0 +1,82 @@
+/**
+ * Агрегація change-файлів одного workspace у version-bump + секцію CHANGELOG
+ * (Keep a Changelog 1.1.0, новіше зверху). Без побічних ефектів — лише обчислення/рендер;
+ * запис на диск і git — у release.mjs.
+ */
+import { VALID_BUMPS, VALID_SECTIONS } from './change-file.mjs'
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/
+const CHANGELOG_HEADER = '# Changelog'
+
+/**
+ * @param {string} version `x.y.z`
+ * @param {string} bump `major|minor|patch`
+ * @returns {string} нова версія
+ */
+export function bumpVersion(version, bump) {
+  const m = SEMVER_RE.exec(version)
+  if (!m) throw new Error(`aggregate: невалідний semver «${version}»`)
+  const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])]
+  if (bump === 'major') return `${major + 1}.0.0`
+  if (bump === 'minor') return `${major}.${minor + 1}.0`
+  return `${major}.${minor}.${patch + 1}`
+}
+
+/**
+ * @param {string[]} bumps непорожній список
+ * @returns {string} найвищий bump (major > minor > patch)
+ */
+export function maxBump(bumps) {
+  return VALID_BUMPS.find(level => bumps.includes(level)) ?? 'patch'
+}
+
+/**
+ * @param {string} version нова версія
+ * @param {string} date `YYYY-MM-DD`
+ * @param {Array<{ section: string, description: string }>} entries записи change-файлів
+ * @returns {string} markdown-блок секції
+ */
+export function renderChangelogSection(version, date, entries) {
+  let out = `## [${version}] - ${date}\n`
+  for (const section of VALID_SECTIONS) {
+    const bullets = entries.filter(e => e.section === section)
+    if (bullets.length === 0) continue
+    const bulletLines = bullets.map(b => '- ' + b.description).join('\n')
+    out += `\n### ${section}\n\n${bulletLines}\n`
+  }
+  return out
+}
+
+/**
+ * @param {string} existingText наявний CHANGELOG.md (може бути порожнім)
+ * @param {string} sectionBlock новий блок версії
+ * @returns {string} CHANGELOG із секцією зверху
+ */
+export function prependChangelogSection(existingText, sectionBlock) {
+  const text = existingText.trimStart()
+  if (!text.startsWith(CHANGELOG_HEADER)) {
+    return `${CHANGELOG_HEADER}\n\n${sectionBlock}`
+  }
+  const nl = text.indexOf('\n')
+  const head = text.slice(0, nl === -1 ? text.length : nl)
+  const rest = nl === -1 ? '' : text.slice(nl + 1).trimStart()
+  return `${head}\n\n${sectionBlock}\n${rest}`
+}
+
+/**
+ * @param {object} params параметри
+ * @param {string} params.currentVersion поточна version маніфесту
+ * @param {Array<{ file: string, entry: { bump: string, section: string, description: string } }>} params.changeFiles change-файли workspace
+ * @param {string} params.date `YYYY-MM-DD`
+ * @returns {{ newVersion: string, sectionBlock: string, consumedFiles: string[] } | null} результат або null, якщо змін нема
+ */
+export function aggregateWorkspace({ currentVersion, changeFiles, date }) {
+  if (changeFiles.length === 0) return null
+  const newVersion = bumpVersion(currentVersion, maxBump(changeFiles.map(c => c.entry.bump)))
+  const sectionBlock = renderChangelogSection(
+    newVersion,
+    date,
+    changeFiles.map(c => c.entry)
+  )
+  return { newVersion, sectionBlock, consumedFiles: changeFiles.map(c => c.file) }
+}

package/rules/release/lib/change-file.mjs

@@ -0,0 +1,99 @@
+/**
+ * Один change-файл `<ws>/.changes/<timestamp>-<rand>.md`: YAML-подібний frontmatter
+ * із двома ключами (`bump`, `section`) + текст опису. Парсер мінімальний — лише ці два
+ * ключі, без зовнішніх залежностей.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Дозволені semver-бампи, від найбільшого до найменшого (порядок використовується для max). */
+export const VALID_BUMPS = Object.freeze(['major', 'minor', 'patch'])
+
+/** Дозволені Keep a Changelog секції (заголовок `### {section}`). */
+export const VALID_SECTIONS = Object.freeze(['Added', 'Changed', 'Fixed', 'Removed'])
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/
+
+/**
+ * @param {string} block тіло frontmatter (між `---`)
+ * @returns {Record<string, string>} пари ключ→значення
+ */
+function parseFrontmatterBlock(block) {
+  /** @type {Record<string, string>} */
+  const out = {}
+  for (const line of block.split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    out[line.slice(0, idx).trim()] = line.slice(idx + 1).trim()
+  }
+  return out
+}
+
+/**
+ * @param {string} text вміст change-файлу
+ * @returns {{ bump: string, section: string, description: string }} розпарсений запис
+ */
+export function parseChangeFile(text) {
+  const m = FRONTMATTER_RE.exec(text)
+  if (!m) throw new Error('change-файл: відсутній frontmatter `---`')
+  const fm = parseFrontmatterBlock(m[1])
+  const description = m[2].trim()
+  if (!VALID_BUMPS.includes(fm.bump)) {
+    throw new Error(`change-файл: bump має бути одним із ${VALID_BUMPS.join('|')} (отримано «${fm.bump ?? ''}»)`)
+  }
+  if (!VALID_SECTIONS.includes(fm.section)) {
+    throw new Error(`change-файл: section має бути одним із ${VALID_SECTIONS.join('|')} (отримано «${fm.section ?? ''}»)`)
+  }
+  if (!description) throw new Error('change-файл: порожній опис')
+  return { bump: fm.bump, section: fm.section, description }
+}
+
+/**
+ * @param {{ bump: string, section: string, description: string }} entry запис
+ * @returns {string} вміст change-файлу
+ */
+export function serializeChangeFile(entry) {
+  return `---\nbump: ${entry.bump}\nsection: ${entry.section}\n---\n${entry.description}\n`
+}
+
+/** Підкаталог зі change-файлами всередині workspace. */
+export const CHANGES_DIR = '.changes'
+
+/**
+ * @param {number} timestamp `Date.now()`
+ * @param {string} suffix короткий випадковий суфікс (hex)
+ * @returns {string} `<timestamp>-<suffix>.md`
+ */
+export function changeFileName(timestamp, suffix) {
+  return `${timestamp}-${suffix}.md`
+}
+
+/**
+ * Унікальне ім'я для нового change-файлу: timestamp (порядок) + rand (анти-колізія
+ * для паралельних агентів у різних worktree, що пишуть у ту саму мілісекунду).
+ * @returns {string} результат
+ */
+export function newChangeFileName() {
+  return changeFileName(Date.now(), randomBytes(3).toString('hex'))
+}
+
+/**
+ * @param {string} ws шлях workspace (відносно `cwd`)
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {Promise<Array<{ file: string, entry: { bump: string, section: string, description: string } }>>} розпарсені change-файли
+ */
+export async function readChangeFiles(ws, cwd = process.cwd()) {
+  const dir = join(cwd, ws, CHANGES_DIR)
+  if (!existsSync(dir)) return []
+  const entries = await readdir(dir)
+  const names = entries.filter(n => n.endsWith('.md')).toSorted()
+  const result = []
+  for (const file of names) {
+    const text = await readFile(join(dir, file), 'utf8')
+    result.push({ file, entry: parseChangeFile(text) })
+  }
+  return result
+}

package/rules/release/lib/fallback.mjs

@@ -0,0 +1,48 @@
+/**
+ * Fallback (n-cursor-release-design рішення 3): коли в workspace є релевантні зміни,
+ * але жодного change-файлу — синтезуємо один запис із commit-subjects від останнього
+ * релізного тегу `<name>@*`. Усі git-виклики через `runGit` (ін'єкція для тестів).
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * @param {string} cwd робочий каталог
+ * @returns {(args: string[]) => Promise<string | null>} тихий git-раннер (null при помилці)
+ */
+export function defaultRunGit(cwd) {
+  return async args => {
+    try {
+      const { stdout } = await execFileAsync('git', args, { cwd })
+      return stdout
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * @param {string} name ім'я пакета (для тегу `<name>@*`)
+ * @param {string} ws workspace (pathspec для `git log`; `.` → без обмеження шляху)
+ * @param {object} [opts] опції
+ * @param {(args: string[]) => Promise<string | null>} [opts.runGit] git-раннер
+ * @returns {Promise<{ bump: string, section: string, description: string } | null>} синтезований запис або null
+ */
+export async function synthesizeChangeFromCommits(name, ws, opts = {}) {
+  const runGit = opts.runGit ?? defaultRunGit(process.cwd())
+  const lastTagRaw = await runGit(['describe', '--tags', '--abbrev=0', '--match', `${name}@*`, 'HEAD'])
+  const lastTag = lastTagRaw?.trim()
+  // Bootstrap: якщо жодного попереднього тегу немає — перший реліз зроблено вручну;
+  // fallback-синтез не запускаємо, щоб не подвоїти bump.
+  if (!lastTag) return null
+  const pathspec = ws === '.' ? [] : ['--', `${ws}/`]
+  const logRaw = await runGit(['log', '--no-merges', '--format=%s', `${lastTag}..HEAD`, ...pathspec])
+  const subjects = (logRaw ?? '')
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
+  if (subjects.length === 0) return null
+  return { bump: 'patch', section: 'Changed', description: subjects.join('; ') }
+}

package/rules/release/release.mjs

@@ -0,0 +1,135 @@
+/**
+ * `n-cursor release` — агрегує per-workspace change-файли у version-bump + CHANGELOG,
+ * комітить, ставить тег `<name>@<version>`, видаляє use-up change-файли. Запускається
+ * у CI на `main` (n-cursor-release-design, варіант A). Сам нічого не публікує.
+ */
+import { existsSync } from 'node:fs'
+import { readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { getMonorepoProjectRootDirs, readPackageManifest } from '../changelog/lib/package-manifest.mjs'
+import { aggregateWorkspace, prependChangelogSection } from './lib/aggregate.mjs'
+import { CHANGES_DIR, readChangeFiles } from './lib/change-file.mjs'
+import { defaultRunGit, synthesizeChangeFromCommits } from './lib/fallback.mjs'
+
+const SEMVER_LINE_RE = /("version"\s*:\s*")[^"]*(")/
+const PY_VERSION_LINE_RE = /^(version\s*=\s*")[^"]*(")/m
+
+/**
+ * Записує нову version у маніфест, зберігаючи форматування файлу.
+ * @param {string} cwd корінь
+ * @param {import('../changelog/lib/package-manifest.mjs').PackageManifest} manifest маніфест
+ * @param {string} newVersion нова версія
+ * @returns {Promise<void>} результат
+ */
+async function writeManifestVersion(cwd, manifest, newVersion) {
+  const path = join(cwd, manifest.ws === '.' ? manifest.manifestRel : `${manifest.ws}/${manifest.manifestRel}`)
+  const text = await readFile(path, 'utf8')
+  const re = manifest.kind === 'npm' ? SEMVER_LINE_RE : PY_VERSION_LINE_RE
+  const replaced = text.replace(re, `$1${newVersion}$2`)
+  if (replaced === text) {
+    throw new Error(`release: не вдалося оновити version у ${manifest.ws}/${manifest.manifestRel} — патерн version не знайдено`)
+  }
+  await writeFile(path, replaced)
+}
+
+/**
+ * @param {string} cwd корінь
+ * @param {string} ws workspace
+ * @param {string} sectionBlock новий блок CHANGELOG
+ * @returns {Promise<void>} результат
+ */
+async function prependWorkspaceChangelog(cwd, ws, sectionBlock) {
+  const path = join(cwd, ws, 'CHANGELOG.md')
+  const existing = existsSync(path) ? await readFile(path, 'utf8') : ''
+  await writeFile(path, prependChangelogSection(existing, sectionBlock))
+}
+
+/**
+ * Зібрати change-файли workspace (явні + fallback-синтез, якщо явних нема, але є коміти).
+ * @param {string} cwd корінь
+ * @param {import('../changelog/lib/package-manifest.mjs').PackageManifest} manifest маніфест
+ * @param {(args: string[]) => Promise<string | null>} runGit git-раннер
+ * @returns {Promise<Array<{ file: string | null, entry: { bump: string, section: string, description: string } }>>} change-файли
+ */
+async function collectChangeFiles(cwd, manifest, runGit) {
+  const explicit = await readChangeFiles(manifest.ws, cwd)
+  if (explicit.length > 0) return explicit
+  if (!manifest.name) return []
+  const synthesized = await synthesizeChangeFromCommits(manifest.name, manifest.ws, { runGit })
+  if (!synthesized) return []
+  console.warn(`⚠️  ${manifest.ws}: немає change-файлів — синтезовано запис із комітів (fallback)`)
+  return [{ file: null, entry: synthesized }]
+}
+
+/**
+ * @param {object} [opts] опції
+ * @param {string} [opts.cwd] корінь
+ * @param {string} [opts.date] `YYYY-MM-DD` (за замовчуванням сьогодні)
+ * @param {(args: string[]) => Promise<string | null>} [opts.runGit] git-раннер
+ * @returns {Promise<Array<{ ws: string, name: string | null, newVersion: string }>>} зрелізовані пакети
+ */
+export async function release(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const date = opts.date ?? new Date().toISOString().slice(0, 10)
+  const runGit = opts.runGit ?? defaultRunGit(cwd)
+
+  const workspaces = await getMonorepoProjectRootDirs(cwd)
+  const subWorkspaces = workspaces.filter(w => w !== '.')
+  const isMonorepoRoot = subWorkspaces.length > 0
+
+  /** @type {Array<{ ws: string, name: string | null, newVersion: string }>} */
+  const released = []
+  const tags = []
+
+  for (const ws of workspaces) {
+    if (ws === '.' && isMonorepoRoot) continue
+    const manifest = await readPackageManifest(ws, cwd)
+    if (!manifest || !manifest.version) continue
+
+    const changeFiles = await collectChangeFiles(cwd, manifest, runGit)
+    const agg = aggregateWorkspace({ currentVersion: manifest.version, changeFiles, date })
+    if (!agg) continue
+
+    await writeManifestVersion(cwd, manifest, agg.newVersion)
+    await prependWorkspaceChangelog(cwd, ws, agg.sectionBlock)
+    for (const file of agg.consumedFiles.filter(Boolean)) {
+      await rm(join(cwd, ws, CHANGES_DIR, file))
+    }
+    released.push({ ws, name: manifest.name, newVersion: agg.newVersion })
+    if (manifest.name) tags.push(`${manifest.name}@${agg.newVersion}`)
+  }
+
+  if (released.length > 0) {
+    const subject = tags.length > 0 ? tags.join(', ') : released.map(r => `${r.ws}@${r.newVersion}`).join(', ')
+    await runGit(['add', '-A'])
+    const committed = await runGit(['commit', '-m', `release: ${subject}`])
+    if (committed === null) {
+      throw new Error('release: git commit не вдався — теги та push скасовано')
+    }
+    for (const tag of tags) {
+      await runGit(['tag', tag])
+    }
+    await runGit(['push', '--follow-tags'])
+  }
+  return released
+}
+
+/**
+ * @param {string[]} _args аргументи CLI (наразі без опцій)
+ * @returns {Promise<number>} exit-код
+ */
+export async function runReleaseCli(_args) {
+  try {
+    const released = await release()
+    if (released.length === 0) {
+      console.log('release: немає змін для релізу')
+    } else {
+      for (const r of released) console.log(`✅ ${r.name ?? r.ws}@${r.newVersion}`)
+    }
+    return 0
+  } catch (error) {
+    console.error(`❌ ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/rules/test/coverage/coverage.mjs

@@ -180,7 +180,9 @@ export async function runCoverageSteps(opts = {}) {
     return 1
   }
 
-  rows.push(buildTotalsRow(rows))
+  // Підсумок «Разом» має сенс лише коли провайдерів ≥2; для єдиного рядка він
+  // дублює його значення, тож не додаємо.
+  if (rows.length > 1) rows.push(buildTotalsRow(rows))
   const md = renderMarkdown(rows)
   // Stryker disable next-line StringLiteral: equivalent – writeFile(path, str, '') behaves identically to 'utf8' in Node/Bun
   await writeFile(join(cwd, 'COVERAGE.md'), md, 'utf8')

package/rules/test/js/no-relative-fs-path.mjs

@@ -145,7 +145,7 @@ function extractFsFunctionName(callee) {
 /**
  * Чи файл — JS-тест (`*.test.mjs` / `*.test.js`).
  * @param {string} absPath абсолютний шлях
- * @returns {boolean}
+ * @returns {boolean} true якщо файл є тестом
  */
 function isTestFile(absPath) {
   const name = basename(absPath)
@@ -187,7 +187,7 @@ function findOffendersInBody(body) {
  */
 function computeLineOffsets(body) {
   const offsets = [0]
-  for (let i = 0; i < body.length; i += 1) {
+  for (let i = 0; i < body.length; i++) {
     if (body[i] === '\n') offsets.push(i + 1)
   }
   return offsets
@@ -202,7 +202,7 @@ function offsetToLineFromCache(offsets, offset) {
   let lo = 0
   let hi = offsets.length - 1
   while (lo < hi) {
-    const mid = (lo + hi + 1) >>> 1
+    const mid = Math.floor((lo + hi + 1) / 2)
     if (offsets[mid] <= offset) lo = mid
     else hi = mid - 1
   }