@nitra/cursor 1.28.7 → 1.29.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.29.0] - 2026-05-28
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 2.0 → 2.1) — додано секцію **«Зв'язок із `.cursor/rules`»**: архітектурна документація у `docs/` не дублює зміст `.cursor/rules/*.mdc` (операційні правила лінту, тестів, CHANGELOG, версіонування), а посилається на потрібне правило через його ім'я у бектиках (наприклад, `див. **`changelog`**`). Дублікати розходяться з оригіналом і ламають automatic-перевірки `npx @nitra/cursor fix`/`check`; правки робляться в одному місці — у самому `.mdc`.
+
+
+## [1.28.8] - 2026-05-28
+
+### Added
+
+- **`rules/test/js/data/stryker_config/stryker-vue-macros-ignorer.mjs`** — новий локальний Stryker `Ignore`-плагін `vue-macros`. `shouldIgnore(path)` повертає non-empty message для `CallExpression`, де `callee` — `Identifier` з ім'ям у наборі Vue `<script setup>`-макросів: `defineProps`, `defineEmits`, `defineModel`, `defineSlots`, `defineExpose`, `defineOptions`. Експортує `strykerPlugins: [{kind: 'Ignore', name: 'vue-macros', value: {shouldIgnore}}]` — це формат, який очікує stryker-core plugin-loader (`module.strykerPlugins`); без імпорту `@stryker-mutator/api`.
+- **`rules/test/js/data/stryker_config/stryker.config.vue.baseline.mjs`** — vue-варіант baseline `stryker.config.mjs`: дефолтні поля + `plugins: ['@stryker-mutator/vitest-runner', './stryker-vue-macros-ignorer.mjs']` і `ignorers: ['vue-macros']` (поряд із vitest-runner тепер треба явно вказати runner, бо ручний `plugins` затирає Stryker default).
+- **`rules/test/js/stryker_config.mjs`** — концерн `stryker_config` тепер детектить `.vue` файли під `<jsRoot>/src/**` (skip `node_modules`/`dist`/`reports`) і у JS-roots із SFC ставить vue-варіант baseline + копіює `stryker-vue-macros-ignorer.mjs` поряд із конфігом. Backward-compat: jsRoot без `.vue` отримує дефолтний baseline без `plugins`/`ignorers`. Обидва файли копіюються через `ensureBaselineFile` — idempotent, ручні модифікації не перетираються. Tests: `+5` сценаріїв у `rules/test/js/tests/stryker_config.test.mjs` (vue-detection happy path, no-vue → дефолт, mixed monorepo, `.vue` лише у node_modules — НЕ vue, idempotency для vue-файлів) + новий `rules/test/js/tests/stryker-vue-macros-ignorer.test.mjs` (всі 6 макросів, non-macro callee, non-CallExpression, MemberExpression callee, anonymous callee).
+- **`rules/test/test.mdc`** (`version` 2.5 → 2.6) і дзеркало `.cursor/rules/n-test.mdc` — нова підсекція "Vue SFC (`<script setup>` macros)" у "Налаштування mutation-testing" з описом коли тригериться vue-варіант, які макроси скіпаються, чому без плагіна `@vue/compiler-sfc` падає на coverage-тернарнику Stryker. Мотивація — інакше boilerplate `// Stryker disable next-line` потрібен у кожному SFC.
+
 ## [1.28.7] - 2026-05-28
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.28.7",
+  "version": "1.29.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; MkDocs Material як viewer з collapsible engineer-блоками для змішаної аудиторії
 alwaysApply: true
-version: '2.0'
+version: '2.1'
 ---
 
 Архітектурна документація проєкту живе у Markdown поряд із кодом. Це не довідник «для людей із порталу архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops).
@@ -319,6 +319,12 @@ ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-про
 
 Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». MkDocs Material рендерить це з collapsible-блоками, тому менеджер бачить прозу, інженер провалюється в деталі.
 
+## Зв'язок із `.cursor/rules`
+
+`.cursor/rules/*.mdc` — джерело правди для **операційних правил** проєкту: як запускати лінт і тести, як оформлювати CHANGELOG, як версіонувати модулі, які прапорці передавати інструментам тощо. Архітектурна документація у `docs/` **не дублює** ці правила і не переказує їх своїми словами. Дублікат миттєво розходиться з оригіналом, ламає механіку automatic-перевірок (`npx @nitra/cursor fix`/`check`) і вимагає двох правок при кожній зміні — одна з них неминуче пропускається.
+
+Замість дублювання — **відсилка** на конкретне правило через його ім'я у бектиках: «див. правило **`changelog`**», «див. **`n-lint`**», «деталі формату — у правилі **`adr`**». Відсилка веде читача (людину чи LLM-агента) до єдиного джерела істини; коли правило еволюціонує, документація лишається коректною без правки. Якщо `.cursor/rule` потребує доповнення або уточнення — оновлюй сам `.mdc`, а не копіюй його зміст у `docs/`.
+
 ## Інструменти
 
 - **Claude Code** як runner — slash-команда `/regen-docs` або post-commit hook на зміни `docs/adr/**`

package/rules/test/js/data/stryker_config/stryker-vue-macros-ignorer.mjs

@@ -0,0 +1,47 @@
+/**
+ * Stryker `Ignore`-plugin: пропускає мутації виклику Vue `<script setup>`-макросів
+ * (`defineProps`, `defineEmits`, `defineModel`, `defineSlots`, `defineExpose`,
+ * `defineOptions`). Без цього Stryker обгортає аргументи макроса у тернарний
+ * coverage-вираз (`stryMutAct_9fa48(...) ? {} : (stryCov_9fa48(...), {...})`),
+ * а `@vue/compiler-sfc` падає з помилкою:
+ *
+ *   defineProps() in <script setup> cannot reference locally declared variables
+ *
+ * бо макроси повинні бути статично-аналізованими на етапі compile-sfc.
+ *
+ * Стандартний Stryker plugin-loader (див. `@stryker-mutator/core/.../plugin-loader.js`)
+ * чекає експорт `strykerPlugins: Plugin[]`. У `stryker.config.mjs` файл цього
+ * плагіна додається у `plugins: ['./stryker-vue-macros-ignorer.mjs']`, а в
+ * `ignorers: ['vue-macros']` активується конкретно цей ignorer по імені.
+ */
+
+const VUE_SETUP_MACROS = new Set([
+  'defineProps',
+  'defineEmits',
+  'defineModel',
+  'defineSlots',
+  'defineExpose',
+  'defineOptions'
+])
+
+const IGNORE_MESSAGE = 'Vue <script setup> macro call cannot be mutated (defineProps/defineEmits/etc. must be statically analyzable for @vue/compiler-sfc).'
+
+/**
+ * @param {{isCallExpression: () => boolean, node: {callee: {type: string, name?: string}}}} path babel NodePath, переданий Stryker-instrumenter
+ * @returns {string | undefined} non-empty message — пропустити мутацію піддерева; undefined — продовжити
+ */
+export function shouldIgnore(path) {
+  if (!path.isCallExpression()) return
+  const callee = path.node.callee
+  if (callee.type !== 'Identifier') return
+  if (!VUE_SETUP_MACROS.has(callee.name)) return
+  return IGNORE_MESSAGE
+}
+
+export const strykerPlugins = [
+  {
+    kind: 'Ignore',
+    name: 'vue-macros',
+    value: { shouldIgnore }
+  }
+]

package/rules/test/js/data/stryker_config/stryker.config.vue.baseline.mjs

@@ -0,0 +1,23 @@
+/** @type {import('@stryker-mutator/core').PartialStrykerOptions} */
+export default {
+  testRunner: 'vitest',
+  vitest: { configFile: 'vitest.config.js' },
+  // perTest: Stryker запускає лише тести, що покривають мутовану лінію — головний приріст
+  // швидкості проти command runner (де треба було б ганяти ввесь test-suite на кожен мутант).
+  coverageAnalysis: 'perTest',
+  // concurrency: за замовч. Stryker обирає os.cpus().length - 1.
+  // inPlace більше не потрібен — vitest-runner ізолює мутантів у пам'яті через AST-patching,
+  // без копіювання node_modules у sandbox (стара проблема command runner у Bun monorepo).
+  tempDirName: 'reports/stryker/.tmp',
+  reporters: ['json', 'clear-text'],
+  jsonReporter: { fileName: 'reports/stryker/mutation.json' },
+  // incremental: зберігає результати між запусками, відновлює після краш/kill.
+  // Дає ~262× прискорення на noop-прогонах (див. benchmarks/runner-comparison/SPIKE.md).
+  incremental: true,
+  incrementalFile: 'reports/stryker/incremental.json',
+  // Local plugin: пропускає мутацію Vue <script setup>-макросів (defineProps/Emits/Model/
+  // Slots/Expose/Options). Інакше Stryker огортає аргументи у coverage-тернарник, який
+  // @vue/compiler-sfc не може статично проаналізувати і падає при компіляції SFC.
+  plugins: ['@stryker-mutator/vitest-runner', './stryker-vue-macros-ignorer.mjs'],
+  ignorers: ['vue-macros']
+}

package/rules/test/js/stryker_config.mjs

@@ -4,6 +4,12 @@
  * (всі workspaces з package.json, або cwd у single-package) і копіює canonical
  * baseline `stryker.config.mjs` + `vitest.config.js` у кожен root, де файлу немає.
  *
+ * Для JS-roots із `.vue` файлами (Vue 3 + `<script setup>`) копіюється vue-варіант
+ * baseline, який реєструє локальний Ignore-плагін `vue-macros` — інакше Stryker
+ * огортає виклики `defineProps`/`defineEmits`/... у coverage-тернарник і
+ * `@vue/compiler-sfc` падає при компіляції SFC. Плагін копіюється у той самий
+ * jsRoot як `stryker-vue-macros-ignorer.mjs`.
+ *
  * Self-gating: концерн silently skips коли `js-lint` не enabled — це навмисно,
  * щоб не шуміти у single-language проєктах без JS coverage tooling.
  *
@@ -11,7 +17,7 @@
  * лишаються на Stryker defaults (`src/**\/*.{js,mjs,ts,jsx,tsx,cjs}`).
  */
 import { existsSync } from 'node:fs'
-import { copyFile } from 'node:fs/promises'
+import { copyFile, glob } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -22,6 +28,9 @@ import { resolveAllJsRoots } from '../../../scripts/utils/resolve-js-root.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const STRYKER_BASELINE_PATH = join(HERE, 'data', 'stryker_config', 'stryker.config.baseline.mjs')
+const STRYKER_VUE_BASELINE_PATH = join(HERE, 'data', 'stryker_config', 'stryker.config.vue.baseline.mjs')
+const STRYKER_VUE_PLUGIN_PATH = join(HERE, 'data', 'stryker_config', 'stryker-vue-macros-ignorer.mjs')
+const STRYKER_VUE_PLUGIN_FILENAME = 'stryker-vue-macros-ignorer.mjs'
 const VITEST_BASELINE_PATH = join(HERE, 'data', 'vitest_config', 'vitest.config.baseline.js')
 
 // Stryker-output патерн для .gitignore: увесь каталог reports/stryker/ — це
@@ -30,6 +39,23 @@ const VITEST_BASELINE_PATH = join(HERE, 'data', 'vitest_config', 'vitest.config.
 // перелічування під-патернів. Подвійний-зірочка-префікс — для monorepo workspaces.
 const STRYKER_GITIGNORE_ENTRIES = ['**/reports/stryker/']
 
+// .vue detection: scope — `<jsRoot>/src/**/*.vue` (як і Stryker mutate defaults для src/);
+// skip build-артефактів і чужих node_modules, щоб не вмикати vue-варіант через transitive deps.
+const VUE_GLOB_PATTERN = 'src/**/*.vue'
+const VUE_GLOB_IGNORE = ['**/node_modules/**', '**/dist/**', '**/reports/**']
+
+/**
+ * Чи містить jsRoot хоч один `.vue` файл під `src/` (skipping node_modules/dist/reports).
+ * @param {string} jsRoot абсолютний шлях до workspace-каталогу
+ * @returns {Promise<boolean>} true якщо знайдено хоча б один `.vue`
+ */
+async function hasVueFiles(jsRoot) {
+  for await (const _rel of glob(VUE_GLOB_PATTERN, { cwd: jsRoot, exclude: VUE_GLOB_IGNORE })) {
+    return true
+  }
+  return false
+}
+
 /**
  * Копіює baseline у target, якщо target ще не існує. Idempotent.
  * @param {ReturnType<typeof createCheckReporter>} reporter check-reporter для логу pass/fail
@@ -67,7 +93,12 @@ export async function check() {
     return reporter.getExitCode()
   }
 
-  for (const baselinePath of [STRYKER_BASELINE_PATH, VITEST_BASELINE_PATH]) {
+  for (const baselinePath of [
+    STRYKER_BASELINE_PATH,
+    STRYKER_VUE_BASELINE_PATH,
+    STRYKER_VUE_PLUGIN_PATH,
+    VITEST_BASELINE_PATH
+  ]) {
     if (!existsSync(baselinePath)) {
       reporter.fail(`canonical baseline не знайдено (${baselinePath}) — перевстанови @nitra/cursor`)
       return reporter.getExitCode()
@@ -75,13 +106,24 @@ export async function check() {
   }
 
   for (const jsRoot of jsRoots) {
+    const isVueRoot = await hasVueFiles(jsRoot)
+    const strykerBaseline = isVueRoot ? STRYKER_VUE_BASELINE_PATH : STRYKER_BASELINE_PATH
     await ensureBaselineFile(
       reporter,
       cwd,
-      STRYKER_BASELINE_PATH,
+      strykerBaseline,
       join(jsRoot, 'stryker.config.mjs'),
       'stryker.config.mjs'
     )
+    if (isVueRoot) {
+      await ensureBaselineFile(
+        reporter,
+        cwd,
+        STRYKER_VUE_PLUGIN_PATH,
+        join(jsRoot, STRYKER_VUE_PLUGIN_FILENAME),
+        STRYKER_VUE_PLUGIN_FILENAME
+      )
+    }
     await ensureBaselineFile(reporter, cwd, VITEST_BASELINE_PATH, join(jsRoot, 'vitest.config.js'), 'vitest.config.js')
   }
 

package/rules/test/test.mdc

@@ -1,6 +1,6 @@
 ---
 description: JS-тести (*.test.mjs) живуть у tests/. Правило `test` керує stryker.config.mjs + vitest.config.js (якщо js-lint enabled) і .cargo/mutants.toml (якщо rust enabled).
-version: '2.5'
+version: '2.6'
 globs: "**/{.n-cursor.json,package.json,Cargo.toml,stryker.config.mjs,vitest.config.js,.cargo/mutants.toml},**/*.test.mjs"
 alwaysApply: false
 ---
@@ -101,6 +101,14 @@ Canonical `vitest.config.js` (для довідки — `pool: 'forks'` + `inclu
 
 Канон Stryker config (Vitest runner + perTest): [stryker.config.baseline.mjs](./js/data/stryker_config/stryker.config.baseline.mjs)
 
+### Vue SFC (`<script setup>` macros)
+
+Якщо у JS-root знайдено бодай один `.vue` під `src/` (skip `node_modules`/`dist`/`reports`) — концерн ставить **vue-варіант** baseline ([`stryker.config.vue.baseline.mjs`](./js/data/stryker_config/stryker.config.vue.baseline.mjs)) замість звичайного і додатково копіює локальний Stryker `Ignore`-плагін [`stryker-vue-macros-ignorer.mjs`](./js/data/stryker_config/stryker-vue-macros-ignorer.mjs) поряд із конфігом.
+
+Плагін реєструється як `plugins: ['@stryker-mutator/vitest-runner', './stryker-vue-macros-ignorer.mjs']` + `ignorers: ['vue-macros']` і виключає з мутацій виклики `<script setup>`-макросів: **`defineProps`**, **`defineEmits`**, **`defineModel`**, **`defineSlots`**, **`defineExpose`**, **`defineOptions`**. Без плагіна Stryker огортає аргументи макроса у coverage-тернарник (`stryMutAct_9fa48(...) ? {} : (stryCov_9fa48(...), {...})`), а `@vue/compiler-sfc` падає з `defineProps() in <script setup> cannot reference locally declared variables` — макроси мають бути статично-аналізованими на етапі compile-sfc. Альтернатива з boilerplate `// Stryker disable next-line` у кожному SFC не масштабується.
+
+JS-root без `.vue` отримує дефолтний baseline без `plugins`/`ignorers` (backward-compatible). Обидва файли копіюються idempotent — наявний `stryker.config.mjs` / `stryker-vue-macros-ignorer.mjs` не перетирається.
+
 ### Vitest baseline та `package.json#scripts`
 
 Поряд зі Stryker концерн `stryker_config` без дублювання копіює `vitest.config.js` (теж тільки якщо файлу немає). Canonical: [vitest.config.baseline.js](./js/data/vitest_config/vitest.config.baseline.js) — `environment: 'node'`, `coverage.provider: 'v8'` з lcov+text-summary репортами, `include: ['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}']` (підхоплює обидві розкладки — тести у `tests/`-піддиректоріях і top-level integration suites у `<root>/tests/`).