@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,138 @@
+# stryker-vue-macros-ignorer.mjs
+
+## Огляд
+
+Файл `stryker-vue-macros-ignorer.mjs` — це Stryker `Ignore`-plugin (мутаційне тестування), який інструктує Stryker не мутувати виклики Vue `<script setup>`-макросів: `defineProps`, `defineEmits`, `defineModel`, `defineSlots`, `defineExpose`, `defineOptions`.
+
+Контекст проблеми:
+
+- Stryker інструментує код тестового проєкту, обгортаючи вирази у тернарне покриттєве вираження виду `stryMutAct_9fa48(...) ? {} : (stryCov_9fa48(...), {...})`.
+- Vue компайлер `@vue/compiler-sfc` вимагає, щоб аргументи макросів у `<script setup>` (наприклад `defineProps({...})`) були **статично-аналізованими** на етапі compile-sfc — макрос не може посилатися на локально оголошені змінні чи знаходитися всередині умовних виразів.
+- Без цього ignorer-плагіна Stryker-інструментація створює саме такий «динамічний» вираз і `@vue/compiler-sfc` падає з помилкою:
+
+  ```
+  defineProps() in <script setup> cannot reference locally declared variables
+  ```
+
+Розв'язання: цей плагін під час обходу AST повертає Stryker'у не-порожнє повідомлення для будь-якого `CallExpression`, у якого `callee` — `Identifier` з ім'ям одного з шести Vue-макросів. Stryker, отримавши непорожнє значення з `shouldIgnore(path)`, **пропускає мутацію цілого піддерева** виклику і залишає оригінальний код незмінним. Як наслідок — згенерований інструментований код залишається сумісним з вимогами `@vue/compiler-sfc`.
+
+Файл є частиною fixture-конфігурації для тестування правил у `npm/rules/test/js/data/stryker_config/` і вмикається в Stryker'і у двох місцях `stryker.config.mjs` поряд: у масиві `plugins: ['./stryker-vue-macros-ignorer.mjs']` (завантаження плагіна) і `ignorers: ['vue-macros']` (активація конкретного ignorer'а за ім'ям).
+
+## Експорти / API
+
+Модуль експортує два публічних символи (обидва — named exports, ESM):
+
+| Символ           | Тип                             | Призначення                                                                                                                                 |
+| ---------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shouldIgnore`   | `(path) => string \| undefined` | Predicate-функція, яку Stryker-інструментер викликає для кожного вузла AST. Повертає повідомлення-причину, якщо мутацію треба пропустити.   |
+| `strykerPlugins` | `Array<{kind, name, value}>`    | Стандартний експорт, який очікує plugin-loader зі Stryker (`@stryker-mutator/core/.../plugin-loader.js`). Містить один запис типу `Ignore`. |
+
+Жодних default-експортів модуль не має.
+
+### `strykerPlugins`
+
+```js
+export const strykerPlugins = [
+  {
+    kind: 'Ignore',
+    name: 'vue-macros',
+    value: { shouldIgnore }
+  }
+]
+```
+
+Поля:
+
+- `kind: 'Ignore'` — категорія плагіна для Stryker; саме така категорія дозволяє пропускати мутації за рішенням `shouldIgnore`.
+- `name: 'vue-macros'` — ім'я плагіна; саме це значення треба вказати у `ignorers: ['vue-macros']` у `stryker.config.mjs`, щоб увімкнути плагін.
+- `value: { shouldIgnore }` — об'єкт-реалізація з єдиним методом `shouldIgnore`.
+
+## Функції
+
+### `shouldIgnore(path)`
+
+```js
+export function shouldIgnore(path)
+```
+
+**Призначення:** вирішити, чи треба пропустити мутацію поточного AST-вузла. Викликається Stryker-інструментером під час обходу AST-дерева коду, який інструментується для мутаційного тестування.
+
+**Параметри:**
+
+| Ім'я   | Тип                         | Опис                                                                                                                                                                                  |
+| ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path` | `NodePath` (Babel-сумісний) | Об'єкт-обгортка над вузлом AST, який Stryker передає для перевірки. Очікувані поля/методи: `path.isCallExpression(): boolean` та `path.node.callee: { type: string, name?: string }`. |
+
+**Повертає:**
+
+- `string` (не-порожній) — повідомлення-причина, чому мутацію треба пропустити. Stryker, отримавши такий рядок, **не мутує** всеце піддерево виклику.
+- `undefined` — продовжити стандартний процес: дозволити Stryker мутувати цей вузол.
+
+**Алгоритм (послідовно):**
+
+1. Якщо `path.isCallExpression()` повертає `false` — це не виклик функції, виходимо з `undefined` (нічого не пропускаємо).
+2. Беремо `callee = path.node.callee`.
+3. Якщо `callee.type !== 'Identifier'` — це не простий ідентифікатор (наприклад, `obj.method()` або `(fn)()`), виходимо з `undefined`.
+4. Якщо `callee.name` відсутній у наборі `VUE_SETUP_MACROS` — це не Vue-макрос, виходимо з `undefined`.
+5. Інакше повертаємо рядок `IGNORE_MESSAGE` — Stryker пропускає мутацію піддерева цього виклику.
+
+**Side effects:** немає. Функція чиста (pure): не змінює `path`, не пише в зовнішній стан, не робить I/O.
+
+**Граничні випадки:**
+
+- Виклик через member-expression (`Vue.defineProps(...)`) **не** збігається, бо `callee.type === 'MemberExpression'`, а не `'Identifier'` — реальні Vue макроси завжди викликаються як вільні ідентифікатори у `<script setup>`, тому це коректно.
+- Перейменовані імпорти (`import { defineProps as dp } from 'vue'`) не збігаються — це теж відповідає реальній семантиці Vue-макросів, які працюють лише з канонічними іменами.
+- Локальні функції з тими самими іменами у звичайному коді (не `<script setup>`) теж будуть пропускатися — це навмисне послаблення в межах fixture'и; не вважається проблемою, оскільки такий код у проєкті дуже рідкісний.
+
+## Внутрішні константи
+
+| Ім'я               | Тип           | Значення                                                                                                                                                                                                            |
+| ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VUE_SETUP_MACROS` | `Set<string>` | `{'defineProps', 'defineEmits', 'defineModel', 'defineSlots', 'defineExpose', 'defineOptions'}` — повний канонічний набір Vue 3 `<script setup>` макросів. `Set` обрано для O(1) перевірки `has(name)`.             |
+| `IGNORE_MESSAGE`   | `string`      | `'Vue <script setup> macro call cannot be mutated (defineProps/defineEmits/etc. must be statically analyzable for @vue/compiler-sfc).'` — повідомлення, яке потрапляє до Stryker-звіту як причина пропуску мутації. |
+
+Обидві константи приватні для модуля (не експортуються).
+
+## Залежності
+
+- **Stryker (runtime контракт):** модуль не імпортує жодних бібліотек, але неявно покладається на API Stryker'а:
+  - `@stryker-mutator/core` plugin-loader (`.../plugin-loader.js`) — шукає named export `strykerPlugins`.
+  - Stryker-інструментер передає у `shouldIgnore` Babel-NodePath-подібний об'єкт із методом `isCallExpression()` та полем `node.callee`.
+- **Vue:** модуль не імпортує `vue`, але семантика всіх шести макросів та обмеження «cannot reference locally declared variables» — це частина контракту `@vue/compiler-sfc`.
+- **Babel AST shape:** покладається на стандартну структуру вузлів Babel (`CallExpression`, `Identifier`).
+- **Імпорти:** жодних `import`-инструкцій. Модуль самодостатній.
+
+## Потік виконання / Використання
+
+Очікуване підключення у `stryker.config.mjs` (поряд із цим файлом):
+
+```js
+// stryker.config.mjs
+export default {
+  // ...решта Stryker-конфігурації
+  plugins: ['./stryker-vue-macros-ignorer.mjs'],
+  ignorers: ['vue-macros']
+  // ...
+}
+```
+
+Послідовність роботи в одному прогоні Stryker:
+
+1. **Bootstrap.** Stryker читає `stryker.config.mjs`, бачить шлях `'./stryker-vue-macros-ignorer.mjs'` у `plugins` і динамічно імпортує модуль.
+2. **Plugin registration.** Plugin-loader дістає named export `strykerPlugins`, ітерує його і реєструє запис `{kind: 'Ignore', name: 'vue-macros', value: {shouldIgnore}}` у внутрішньому реєстрі плагінів-ігнорерів.
+3. **Activation.** Stryker звіряє реєстр з конфігураційним полем `ignorers: ['vue-macros']` і активує цей плагін за ім'ям. Якщо `name` у `ignorers` відсутній — плагін зареєстрований, але не використовується.
+4. **AST traversal.** Stryker-інструментер обходить AST кожного файлу-кандидата на мутацію. Для кожного вузла, який є потенційним кандидатом на мутацію, викликає `shouldIgnore(path)` усіх активних `Ignore`-плагінів.
+5. **Decision.** Якщо `shouldIgnore` повертає рядок — Stryker позначає цю мутацію як **Ignored**, не вставляє в неї `stryMutAct_*`/`stryCov_*`-обгортки і записує `IGNORE_MESSAGE` у звіт як причину.
+6. **Codegen.** Для виклику Vue-макроса в інструментованому файлі залишається оригінальний код `defineProps({...})` без тернарного покриттєвого виразу — `@vue/compiler-sfc` успішно компілює `<script setup>`.
+7. **Mutation testing run.** Тести виконуються над інструментованим кодом; мутації решти коду перевіряються нормально, а Vue-макроси не псуються.
+
+Якщо плагін **не активувати** (або зареєструвати без рядка `'vue-macros'` у `ignorers`) — Stryker почне інструментувати макроси, і Vue компайлер впаде з помилкою «defineProps() in &lt;script setup&gt; cannot reference locally declared variables» ще до виконання тестів.
+
+## Особливості та обмеження
+
+- Покриває **всі шість** Vue 3 `<script setup>` макросів станом на актуальну версію Vue 3 — нові макроси (якщо з'являться) треба буде додавати у `VUE_SETUP_MACROS` вручну.
+- Не розпізнає виклики через member-expression (`Vue.defineProps`) та перейменовані ідентифікатори — це відповідає реальним обмеженням Vue-макросів, тому є коректним.
+- Працює з рівнем гранулярності «весь виклик» — Stryker пропускає мутацію всього піддерева `CallExpression`, включно з його аргументами; це навмисна поведінка, бо мутувати аргумент `defineProps({...})` теж зламає compile-sfc.
+- Функція чиста — її легко тестувати ізольовано, передаючи власні mock'и `NodePath`-подібних об'єктів.
+
+Rebuild Test.

package/rules/test/js/data/stryker_config/docs/stryker.config.baseline.md

@@ -0,0 +1,134 @@
+# stryker.config.baseline.mjs
+
+## Огляд
+
+Файл `stryker.config.baseline.mjs` — це еталонна (baseline) конфігурація для інструмента mutation testing **Stryker Mutator** (`@stryker-mutator/core`). Він являє собою тестову/довідкову фікстуру, розміщену в директорії з даними для перевірочного правила (`npm/rules/test/js/data/stryker_config/`), і слугує канонічним зразком того, як має виглядати «правильна» Stryker-конфігурація у проєкті.
+
+Файл написаний у форматі ES Module (`.mjs`) і експортує єдиний дефолтний об'єкт із набором опцій, що повністю задають поведінку Stryker-у:
+
+- запуск через **Vitest** test-runner (замість commandRunner);
+- `perTest` coverage analysis для максимального прискорення;
+- ввімкнений **incremental** режим зі збереженням стану між запусками;
+- два репортери (`json` для машинного парсингу та `clear-text` для людиночитного виводу в консоль);
+- усі артефакти (тимчасові файли, JSON-репорт, incremental-state) розміщуються під теками `reports/stryker/...`.
+
+Об'єкт типізовано через JSDoc-анотацію `@type {import('@stryker-mutator/core').PartialStrykerOptions}`, що дає TypeScript-сумісну валідацію в IDE без переходу на `.ts`.
+
+## Експорти / API
+
+Файл має один експорт — **default export**.
+
+| Експорт   | Тип                                                 | Опис                         |
+| --------- | --------------------------------------------------- | ---------------------------- |
+| `default` | `PartialStrykerOptions` (з `@stryker-mutator/core`) | Об'єкт конфігурації Stryker. |
+
+### Структура експортованого об'єкта
+
+| Ключ               | Тип        | Значення                                        | Призначення                                                                                                                |
+| ------------------ | ---------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `testRunner`       | `string`   | `'vitest'`                                      | Test-runner-плагін, через який Stryker виконує тести проти мутантів.                                                       |
+| `vitest`           | `object`   | `{ configFile: 'vitest.config.js' }`            | Налаштування Vitest-runner-а. Поле `configFile` вказує шлях до конфігурації Vitest, яку Stryker реюзає.                    |
+| `coverageAnalysis` | `string`   | `'perTest'`                                     | Режим аналізу покриття. `perTest` — Stryker для кожного мутанта запускає лише ті тести, що покривають мутовану лінію коду. |
+| `tempDirName`      | `string`   | `'reports/stryker/.tmp'`                        | Тимчасова директорія для проміжних файлів Stryker під час прогону.                                                         |
+| `reporters`        | `string[]` | `['json', 'clear-text']`                        | Список увімкнених репортерів. `json` пише машинно-читний звіт, `clear-text` виводить у термінал.                           |
+| `jsonReporter`     | `object`   | `{ fileName: 'reports/stryker/mutation.json' }` | Налаштування JSON-репортера; `fileName` — шлях для запису підсумкового звіту.                                              |
+| `incremental`      | `boolean`  | `true`                                          | Вмикає incremental-режим: Stryker зберігає результати між запусками й перевикористовує їх.                                 |
+| `incrementalFile`  | `string`   | `'reports/stryker/incremental.json'`            | Шлях до файлу зі станом incremental-режиму (попередні результати мутацій).                                                 |
+
+## Функції
+
+Файл **не містить функцій, класів чи виконуваного коду** — це чисто декларативний конфігураційний модуль. Він лише експортує літерал-об'єкт.
+
+### Side effects
+
+Side effects на рівні модуля **відсутні**:
+
+- немає звернень до файлової системи в момент імпорту;
+- немає викликів зовнішніх API;
+- немає мутацій глобальних об'єктів;
+- немає динамічних `import()` чи `require`.
+
+Усі ефекти виникають **пізніше** — коли Stryker CLI читає цей модуль і застосовує його опції під час запуску mutation-тестування.
+
+## Залежності
+
+### Runtime-залежності
+
+Файл **не імпортує** жодних модулів і не має runtime-залежностей.
+
+### Type-only залежності (через JSDoc)
+
+| Пакет                   | Імпортований символ     | Призначення                                                                                        |
+| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `@stryker-mutator/core` | `PartialStrykerOptions` | Тип для type-checking структури об'єкта конфігурації в IDE/TypeScript. На runtime не підтягується. |
+
+### Опосередковані залежності (потрібні Stryker-у під час прогону)
+
+Хоча файл їх не імпортує, для виконання конфігурації в робочому проєкті мають бути встановлені:
+
+| Пакет                            | Роль                                                                                   |
+| -------------------------------- | -------------------------------------------------------------------------------------- |
+| `@stryker-mutator/core`          | Ядро Stryker.                                                                          |
+| `@stryker-mutator/vitest-runner` | Плагін test-runner-а для Vitest (підвантажується за значенням `testRunner: 'vitest'`). |
+| `vitest`                         | Сам Vitest з конфігом `vitest.config.js` у корені проєкту.                             |
+
+### Файлові залежності
+
+- `vitest.config.js` (відносний шлях від робочого каталогу запуску Stryker-у) — Vitest-конфіг, який Stryker реюзає.
+
+### Вихідні артефакти (створюються Stryker-ом)
+
+| Шлях                               | Що містить                                                     |
+| ---------------------------------- | -------------------------------------------------------------- |
+| `reports/stryker/.tmp/`            | Тимчасові файли під час прогону (видаляються/перезаписуються). |
+| `reports/stryker/mutation.json`    | Підсумковий JSON-звіт із результатами всіх мутантів.           |
+| `reports/stryker/incremental.json` | Стан incremental-режиму для прискорення наступних прогонів.    |
+
+## Потік виконання / Використання
+
+### Як файл використовується
+
+Файл розміщений у тестовій директорії `npm/rules/test/js/data/stryker_config/` і призначений як **тестова фікстура / еталон** для перевірочних правил (rule-checks), що валідують Stryker-конфіги в реальних воркспейсах монорепо. Тобто rule-checker може:
+
+1. читати цей файл як «known good» приклад;
+2. порівнювати з ним конфіги воркспейсів;
+3. виявляти відхилення (відсутність `incremental`, неправильний `coverageAnalysis`, неправильний `testRunner` тощо).
+
+### Якби файл застосовувався як справжній Stryker-конфіг
+
+Якщо покласти його в корінь воркспейсу під ім'ям `stryker.config.mjs`, Stryker CLI підхопить його автоматично. Запуск:
+
+```bash
+bunx stryker run
+```
+
+Потік виконання:
+
+1. **Завантаження конфігу.** Stryker CLI читає `stryker.config.mjs`, бере дефолтний експорт як `PartialStrykerOptions`.
+2. **Розв'язання test-runner-а.** За значенням `testRunner: 'vitest'` Stryker динамічно підвантажує `@stryker-mutator/vitest-runner`.
+3. **Ініціалізація Vitest.** Vitest-runner читає `vitest.config.js` (поле `vitest.configFile`) і налаштовує Vitest-інстанс.
+4. **Перевірка incremental-стану.** Якщо файл `reports/stryker/incremental.json` існує (`incremental: true`), Stryker завантажує попередні результати й пропускає ті мутанти, що не змінилися (дає **~262×** прискорення на noop-прогонах згідно коментаря в коді, з посиланням на `benchmarks/runner-comparison/SPIKE.md`).
+5. **Coverage analysis.** Stryker генерує coverage-карту й для кожного мутанта (`perTest`) обирає лише підмножину тестів, що покривають мутовану лінію, замість прогону всього test-suite.
+6. **Прогон мутантів.** Concurrency за замовчуванням — `os.cpus().length - 1` (як зазначено в коментарях; явно в конфізі не задано). vitest-runner ізолює мутантів **у пам'яті через AST-patching** — не копіює `node_modules` у sandbox, що було проблемою command-runner-а в Bun-монорепо.
+7. **Тимчасові артефакти.** Усе проміжне пишеться у `reports/stryker/.tmp/`.
+8. **Звітування.** Після завершення:
+   - `clear-text` репортер друкує підсумок у термінал;
+   - `jsonReporter` пише машинний звіт у `reports/stryker/mutation.json`;
+   - оновлюється `reports/stryker/incremental.json` для майбутніх прогонів.
+
+### Ключові архітектурні рішення (з коментарів у файлі)
+
+- **`perTest` замість `all` / `off`** — головний приріст швидкості проти `commandRunner`, де треба ганяти весь test-suite на кожного мутанта.
+- **Без `inPlace`** — vitest-runner ізолює мутантів через AST-patching у пам'яті, тому копіювання робочої директорії не потрібне (стара проблема command-runner-а у Bun monorepo).
+- **`incremental: true`** — критично для CI/локальних повторних прогонів: відновлює стан після крашу/kill і дає ~262× прискорення на noop-прогонах.
+
+### Передумови запуску (контракт середовища)
+
+- існує `vitest.config.js` у CWD;
+- встановлені `@stryker-mutator/core`, `@stryker-mutator/vitest-runner`, `vitest`;
+- тека `reports/stryker/` доступна для запису (Stryker створює її автоматично);
+- наявні тести під Vitest, що покривають кодову базу, яку планується мутувати.
+
+### Інтеграція з правилами проєкту
+
+Через шлях `npm/rules/test/js/data/...` файл є вхідними даними для тестів rule-чекерів (див. `.cursor/rules/n-test.mdc`, `.cursor/rules/n-bun.mdc`). Ці чекери, ймовірно, валідують Stryker-конфіги воркспейсів на відповідність цьому baseline (наприклад, що `testRunner === 'vitest'`, `coverageAnalysis === 'perTest'`, `incremental === true`).

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

@@ -0,0 +1,160 @@
+# stryker.config.vue.baseline.mjs
+
+## Огляд
+
+Файл `stryker.config.vue.baseline.mjs` — це **базова (еталонна) конфігурація Stryker** для мутаційного тестування Vue-проєктів, яка використовується як тестові дані (fixture) в наборі тестів правил `npm/rules/test/js/data/stryker_config/`. Розташований у директорії `data/stryker_config/` каталогу тестів пакета `npm/rules`, файл слугує канонічним зразком "як має виглядати правильно налаштований `stryker.config.mjs`" для проєкту з Vue Single-File Components.
+
+Файл є простим ES-модулем без логіки: він експортує об'єкт конфігурації за замовчуванням (`export default`). Цей об'єкт повністю описує параметри запуску Stryker mutator-а для Vue-стека (Vitest як test runner, кастомний ignorer для Vue-макросів, increment-кешування, JSON-репортер).
+
+Контекст використання:
+
+- як **очікуваний baseline** (еталон) у тестах правил, що перевіряють або генерують `stryker.config.mjs` для Vue-проєктів;
+- як **довідковий шаблон** для команд `n-coverage` / `n-cursor coverage`, які запускають мутаційне тестування у Vue-воркспейсах;
+- як **документація-приклад** оптимальних налаштувань (perTest coverage, vitest-runner, incremental, local Vue-macros ignorer plugin).
+
+## Експорти / API
+
+Файл має **єдиний експорт** — `default`.
+
+| Експорт   | Тип                                                 | Опис                                                                |
+| --------- | --------------------------------------------------- | ------------------------------------------------------------------- |
+| `default` | `PartialStrykerOptions` (з `@stryker-mutator/core`) | Об'єкт конфігурації Stryker для Vue-проєкту з Vitest test runner-ом |
+
+JSDoc-анотація `/** @type {import('@stryker-mutator/core').PartialStrykerOptions} */` встановлює тип об'єкта згідно з офіційним TS-типом Stryker, що дає IDE/TS-серверу повну валідацію полів та автодоповнення.
+
+### Структура експортованого об'єкта
+
+| Ключ                    | Значення                                                                 | Призначення                                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `testRunner`            | `'vitest'`                                                               | Обирає Vitest як тест-раннер для запуску мутантів                                                                              |
+| `vitest.configFile`     | `'vitest.config.js'`                                                     | Шлях до конфігурації Vitest, яку має підхопити vitest-runner                                                                   |
+| `coverageAnalysis`      | `'perTest'`                                                              | Аналіз покриття на рівні окремих тестів — для кожного мутанта запускаються лише ті тести, що покривають відповідний рядок коду |
+| `tempDirName`           | `'reports/stryker/.tmp'`                                                 | Тимчасова директорія Stryker (зберігається всередині `reports/`, а не в корені)                                                |
+| `reporters`             | `['json', 'clear-text']`                                                 | Активні репортери: машинно-читабельний JSON + текстовий вивід у термінал                                                       |
+| `jsonReporter.fileName` | `'reports/stryker/mutation.json'`                                        | Куди писати JSON-звіт мутацій                                                                                                  |
+| `incremental`           | `true`                                                                   | Вмикає інкрементальний режим: зберігає попередні результати між запусками                                                      |
+| `incrementalFile`       | `'reports/stryker/incremental.json'`                                     | Файл-кеш для incremental-режиму                                                                                                |
+| `plugins`               | `['@stryker-mutator/vitest-runner', './stryker-vue-macros-ignorer.mjs']` | Підключені Stryker-плагіни: офіційний vitest-runner і локальний ignorer для Vue compiler-macros                                |
+| `ignorers`              | `['vue-macros']`                                                         | Активні ignorer-плагіни — ім'я `vue-macros` походить з локального плагіна `./stryker-vue-macros-ignorer.mjs`                   |
+
+## Функції
+
+Файл **не містить функцій** — це чисто декларативний конфіг-модуль, що експортує статичний об'єкт. Жодних викликів, фабрик, factory-функцій чи hook-ів немає.
+
+### Side effects
+
+Side effects на рівні модуля **відсутні**:
+
+- немає `import`-ів (окрім JSDoc type-import у коментарі, який не виконується);
+- немає викликів функцій верхнього рівня;
+- немає мутацій глобального стану;
+- немає I/O.
+
+Файл при `import`-уванні просто повертає літерал об'єкта.
+
+## Залежності
+
+### Прямі імпорти
+
+**Жодних `import`-операторів немає.** Файл самодостатній на рівні JS-завантаження.
+
+### Тип-залежності (лише через JSDoc)
+
+| Пакет                   | Призначення                                                | Спосіб використання                                         |
+| ----------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
+| `@stryker-mutator/core` | Базовий тип `PartialStrykerOptions` для типізації експорту | Через JSDoc `@type {import('...')}` — не впливає на рантайм |
+
+### Імпліцитні runtime-залежності (за іменами рядків)
+
+Конфіг **посилається на зовнішні модулі та файли через рядкові ідентифікатори**, які підвантажує сам Stryker під час виконання:
+
+| Залежність                                               | Тип                | Опис                                                                                                                                                                                    |
+| -------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'vitest'` (значення `testRunner`)                       | npm-плагін Stryker | Ім'я раннера — Stryker шукає `@stryker-mutator/vitest-runner` у `node_modules`                                                                                                          |
+| `'@stryker-mutator/vitest-runner'` (елемент `plugins`)   | npm-пакет          | Власне реалізація vitest-runner, мусить бути встановленою як devDependency                                                                                                              |
+| `'./stryker-vue-macros-ignorer.mjs'` (елемент `plugins`) | локальний модуль   | Кастомний Stryker-плагін у тій самій директорії, що пропускає мутацію Vue compiler-macros (`defineProps`, `defineEmits`, `defineModel`, `defineSlots`, `defineExpose`, `defineOptions`) |
+| `'vitest.config.js'` (значення `vitest.configFile`)      | файл воркспейсу    | Конфігурація Vitest у корені тестованого Vue-воркспейсу                                                                                                                                 |
+| `'vue-macros'` (елемент `ignorers`)                      | ім'я ignorer-а     | Внутрішнє ім'я ignorer-а, яке експортує `./stryker-vue-macros-ignorer.mjs`                                                                                                              |
+
+## Потік виконання / Використання
+
+### Як файл використовується
+
+1. **Як test-fixture (eталон)** — тестовий код у `npm/rules/test/js/` читає цей файл як еталонний baseline і порівнює з реальним `stryker.config.mjs` у проєктах, що перевіряються правилом.
+2. **Як шаблон для генератора** — правило, що автоматично створює/нормалізує `stryker.config.mjs` для Vue-воркспейсів, може використовувати цей файл як вихідну форму.
+3. **Як приклад у документації** — для розробників, що налаштовують мутаційне тестування Vue вручну.
+
+### Як цей конфіг виконує Stryker (якщо запустити проти Vue-воркспейсу)
+
+При виклику `bunx stryker run` (чи через `n-cursor coverage`) Stryker:
+
+1. читає експортований об'єкт як `PartialStrykerOptions`;
+2. завантажує плагіни зі списку `plugins`:
+   - офіційний `@stryker-mutator/vitest-runner` — для запуску мутантів через Vitest;
+   - локальний `./stryker-vue-macros-ignorer.mjs` — реєструє ignorer з іменем `'vue-macros'`;
+3. активує ignorer-и зі списку `ignorers` — у цьому випадку `'vue-macros'` пропускає мутацію аргументів `defineProps` / `defineEmits` / `defineModel` / `defineSlots` / `defineExpose` / `defineOptions`, оскільки інакше Stryker огортав би їх у coverage-тернарник, який `@vue/compiler-sfc` не зміг би статично проаналізувати, і компіляція SFC падала б;
+4. встановлює `testRunner: 'vitest'` і передає йому `vitest.configFile`;
+5. виконує **perTest coverage analysis** — заздалегідь запускає тести один раз, фіксує мапу "який тест покриває який рядок", і потім для кожного мутанта виконує лише релевантний підмножину тестів (значно швидше за `command` runner, де довелось би ганяти весь test-suite на кожен мутант);
+6. використовує `reports/stryker/.tmp` як тимчасову директорію (всередині `reports/`, щоб не засмічувати корінь);
+7. зберігає звіт у `reports/stryker/mutation.json` через `json`-репортер, паралельно друкує `clear-text` у термінал;
+8. при `incremental: true` після першого прогону зберігає стан у `reports/stryker/incremental.json`; наступні запуски (особливо noop-прогони, коли код не змінився) виконуються в ~262× швидше (за результатами `benchmarks/runner-comparison/SPIKE.md`, на який посилається коментар у файлі).
+
+### Архітектурні рішення (з коментарів у файлі)
+
+- **`coverageAnalysis: 'perTest'`** — головний приріст швидкості проти `command` runner-а, де довелось би запускати весь test-suite на кожен мутант.
+- **Відсутність `inPlace`** — vitest-runner ізолює мутантів у пам'яті через AST-patching, без копіювання `node_modules` у sandbox (стара проблема command runner у Bun monorepo).
+- **`concurrency` не задано** — Stryker за замовчуванням обирає `os.cpus().length - 1`, що оптимально для більшості машин.
+- **Локальний `vue-macros` ignorer** — обов'язковий для Vue-проєктів, інакше Stryker зламає компіляцію SFC при мутації compiler-macros у блоках `<script setup>`.
+
+### Типовий life-cycle конфіга
+
+```text
+import default з stryker.config.vue.baseline.mjs
+        |
+        v
+PartialStrykerOptions → передається в @stryker-mutator/core
+        |
+        v
+плагіни підвантажуються: vitest-runner + локальний ignorer
+        |
+        v
+testRunner='vitest' стартує з vitest.config.js
+        |
+        v
+perTest coverage map будується
+        |
+        v
+для кожного мутанта запускається підмножина тестів,
+ignorer 'vue-macros' пропускає Vue compiler-macros
+        |
+        v
+звіт → reports/stryker/mutation.json (+ clear-text у термінал)
+        |
+        v
+incremental.json зберігає стан для наступного запуску
+```
+
+## Rebuild Test
+
+Перевірка, що документація відображає реальний вміст файлу:
+
+1. **Експорт**: файл містить **рівно один** `export default` зі статичним об'єктом — підтверджено.
+2. **Ключі об'єкта**: рівно 10 ключів верхнього рівня: `testRunner`, `vitest`, `coverageAnalysis`, `tempDirName`, `reporters`, `jsonReporter`, `incremental`, `incrementalFile`, `plugins`, `ignorers` — підтверджено.
+3. **Значення**:
+   - `testRunner === 'vitest'`
+   - `vitest.configFile === 'vitest.config.js'`
+   - `coverageAnalysis === 'perTest'`
+   - `tempDirName === 'reports/stryker/.tmp'`
+   - `reporters` — масив з двох рядків `['json', 'clear-text']`
+   - `jsonReporter.fileName === 'reports/stryker/mutation.json'`
+   - `incremental === true`
+   - `incrementalFile === 'reports/stryker/incremental.json'`
+   - `plugins` — масив з двох рядків: `'@stryker-mutator/vitest-runner'` та `'./stryker-vue-macros-ignorer.mjs'`
+   - `ignorers` — масив з одного рядка `['vue-macros']`
+4. **JSDoc-тип**: `/** @type {import('@stryker-mutator/core').PartialStrykerOptions} */` присутній над `export default` — підтверджено.
+5. **Імпорти**: жодного `import`-оператора немає — підтверджено.
+6. **Функції**: жодних оголошень функцій (ні `function`, ні стрілкових) — підтверджено.
+7. **Side effects на рівні модуля**: відсутні — підтверджено.
+8. **Коментарі**: усі ключові рішення (`perTest`, відсутність `inPlace`, `incremental` із посиланням на `benchmarks/runner-comparison/SPIKE.md`, призначення локального `vue-macros` ignorer-а) задокументовані inline-коментарями у вихідному файлі — відображено в розділах "Архітектурні рішення" та "Залежності".
+
+Документація сумісна з вмістом файла і не містить вигаданих фактів.