@nitra/cursor 1.30.0 → 1.32.0

package/CHANGELOG.md

@@ -3,7 +3,42 @@
 Усі помітні зміни цього модуля документуються тут.
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
-# [1.30.0] - 2026-05-29
+
+## [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/package.json

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

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])
+}