@nitra/cursor 1.28.8 → 1.29.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 Формат — [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.28.8",
+  "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']
+}