@nitra/cursor 5.3.4 → 5.4.0

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

@@ -1,166 +1,30 @@
 ---
 docgen:
   source: npm/rules/test/js/data/stryker_config/stryker.config.vue.baseline.mjs
-  crc: a1405dc2
+  crc: 579865c3
+  score: 95
 ---
 
 # 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.
+Файл запускає тестування за допомогою фреймворку vitest. Використовує конфігурацію vitest з файлом mutation.json. Налаштовує аналіз покриття для запуску лише на мутовані лінії кожного тесту. Визначає директорію тимчасових файлів за допомогою tempDirName. Генерує звіти у форматах json та clear-text за допомогою reporters. Конфігурує jsonReporter для збереження результатів у файлі reports/stryker/mutation.json. Увімкнено incremental для збереження результатів між запусками та відновлення після збою. Використовує incrementalFile для збереження стану для інкрементального запуску. Ігнорує мутації Vue `<script setup>`-макросів за допомогою плагінів. Ігнорує Vue-макроси за допомогою плагінів.
 
-Файл є простим ES-модулем без логіки: він експортує об'єкт конфігурації за замовчуванням (`export default`). Цей об'єкт повністю описує параметри запуску Stryker mutator-а для Vue-стека (Vitest як test runner, кастомний ignorer для Vue-макросів, increment-кешування, JSON-репортер).
+## Поведінка
 
-Контекст використання:
+1. Запуск тестування з використанням фреймворку vitest.
+2. Використання конфігурації vitest з файлом vitest.config.mjs.
+3. Налаштування аналізу покриття для запуску лише на мутовані лінії кожного тесту.
+4. Використання назви tempDirName для визначення директорії тимчасових файлів.
+5. Використання reporters для генерації звітів у форматах json та clear-text.
+6. Налаштування jsonReporter для збереження результатів у файлі reports/stryker/mutation.json.
+7. Увімкнення incremental для збереження результатів між запусками та відновлення після збою.
+8. Використання incrementalFile для збереження стану для інкрементального запуску.
+9. Використання плагінів для ігнорування мутації Vue <script setup>-макросів.
+10. Використання плагінів для ігнорування Vue-макросів.
 
-- як **очікуваний 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-коментарями у вихідному файлі — відображено в розділах "Архітектурні рішення" та "Залежності".
-
-Документація сумісна з вмістом файла і не містить вигаданих фактів.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/test/js/docs/cargo_mutants_config.md

@@ -1,173 +1,33 @@
+---
+docgen:
+  source: npm/rules/test/js/cargo_mutants_config.mjs
+  crc: 4078e955
+  score: 100
+---
+
 # cargo_mutants_config.mjs
 
 ## Огляд
 
-Файл реалізує концерн `cargo_mutants_config` правила `test` (відповідає правилу
-`test.mdc`) для пакета `@nitra/cursor`. Призначення концерну — забезпечити, що
-у кожному Cargo-крейті проєкту присутній файл `.cargo/mutants.toml` із
-канонічним baseline-вмістом, який потрібен інструменту
-[`cargo-mutants`](https://mutants.rs/) для запуску мутаційного тестування Rust.
-
-Логіка self-gating: концерн виконується тільки якщо в `.n-cursor.json` правило
-`rust` присутнє у списку `rules` і не присутнє у списку `disable-rules`. Якщо
-правило `rust` вимкнене — функція мовчки повертає успіх. Якщо правило
-ввімкнене, але в проєкті ще немає жодного `Cargo.toml` (наприклад, манифест
-з'явиться пізніше) — функція теж мовчки повертає успіх, не вважаючи це
-порушенням.
-
-У разі, якщо canonical baseline-файл `data/cargo_mutants_config/mutants.toml.baseline`
-відсутній у дистрибутиві `@nitra/cursor` (наприклад, через зламану інсталяцію),
-концерн фейлить із вказівкою перевстановити пакет.
-
-Для кожного знайденого `Cargo.toml` (cwd, всі workspace-члени, включно з
-Tauri-патерном `src-tauri/Cargo.toml`) концерн перевіряє наявність файлу
-`.cargo/mutants.toml` у відповідному каталозі манифеста. Якщо файл існує —
-позначає його як pass і йде далі. Якщо не існує — створює каталог `.cargo/`
-(`recursive: true`) та копіює canonical baseline у `.cargo/mutants.toml`.
-
-Baseline-файл — порожній з коментарем; у `cargo-mutants` працюють робочі
-defaults, тож фактичні налаштування не потрібні.
-
-## Експорти / API
-
-| Експорт | Тип                                             | Опис                                                                                             |
-| ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `check` | `async function(cwd?: string): Promise<number>` | Основна точка входу концерну. Повертає exit-код: `0` — OK або silently skipped, `1` — порушення. |
-
-Інших експортів модуль не має. Константи `HERE` та `BASELINE_PATH` —
-внутрішні, не експортуються.
-
-## Функції
-
-### `check(cwd = process.cwd())`
-
-Асинхронна функція, що виконує перевірку та (за потреби) копіювання canonical
-baseline `.cargo/mutants.toml` у кожен Cargo-крейт проєкту.
-
-**Сигнатура:**
-
-```js
-export async function check(cwd = process.cwd()): Promise<number>
-```
-
-**Параметри:**
-
-- `cwd` — `string`, необов'язковий. Корінь проєкту, у якому шукати
-  `.n-cursor.json` та `Cargo.toml`. За замовчуванням — `process.cwd()`
-  (підтримка CLI-сценарію виклику).
-
-**Повертає:**
-
-- `Promise<number>` — exit-код, який повертає `reporter.getExitCode()`:
-  - `0` — концерн пройшов успішно (включно з випадками silently skip:
-    rust не enabled або немає жодного Cargo.toml).
-  - `1` — concer зафейлив (наприклад, відсутній canonical baseline у
-    дистрибутиві `@nitra/cursor`).
-
-**Алгоритм:**
-
-1. Створює `reporter` через `createCheckReporter()`.
-2. Читає `.n-cursor.json` через `readNCursorConfigLite(cwd)`, отримує
-   `config.rules` і `config.disableRules`.
-3. Self-gate: якщо `rust` не у `config.rules` або є у `config.disableRules` —
-   повертає `reporter.getExitCode()` без жодних повідомлень.
-4. Резолвить усі `Cargo.toml` у проєкті через
-   `resolveAllCargoManifests(cwd)` (cwd, workspaces, Tauri-патерн).
-5. Якщо манифестів немає — silently skip, повертає `reporter.getExitCode()`.
-6. Перевіряє існування canonical baseline за шляхом `BASELINE_PATH`. Якщо
-   файлу немає — `reporter.fail()` із рекомендацією перевстановити
-   `@nitra/cursor` і повертає `reporter.getExitCode()`.
-7. Ітерує по кожному `manifestPath`:
-   - Обчислює `cargoDir = dirname(manifestPath)`.
-   - Обчислює `target = join(cargoDir, '.cargo', 'mutants.toml')`.
-   - Якщо `target` існує — `reporter.pass()` з повідомленням
-     `.cargo/mutants.toml існує (<relative-path>)`, переходить до наступного
-     манифеста.
-   - Інакше — створює каталог `dirname(target)` (тобто `.cargo/`) із
-     прапорцем `{ recursive: true }`, копіює `BASELINE_PATH` у `target`,
-     повідомляє `reporter.pass()` з повідомленням
-     `.cargo/mutants.toml створено з canonical baseline (<relative-path>) (test.mdc)`.
-8. Повертає `reporter.getExitCode()`.
-
-**Side effects:**
-
-- Читання файлової системи: `.n-cursor.json` (через
-  `readNCursorConfigLite`), `Cargo.toml` (через `resolveAllCargoManifests`),
-  перевірка існування `BASELINE_PATH` і `target` (через `existsSync`).
-- Запис у файлову систему:
-  - Створення каталогу `.cargo/` у кожному cargo-крейті, де ще нема
-    `.cargo/mutants.toml` (`mkdir` з `recursive: true`).
-  - Копіювання `BASELINE_PATH` у `.cargo/mutants.toml` (`copyFile`).
-- Виклики reporter (`pass` / `fail`) — у stdout/stderr формат залежить
-  від реалізації `createCheckReporter`.
-
-## Залежності
-
-### Стандартна бібліотека Node.js
-
-- `node:fs` — `existsSync`.
-- `node:fs/promises` — `copyFile`, `mkdir`.
-- `node:path` — `dirname`, `join`, `relative`.
-- `node:url` — `fileURLToPath` (для обчислення абсолютного шляху до
-  baseline через `import.meta.url`).
-
-### Внутрішні модулі проєкту
-
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter()`,
-  фабрика репортера; об'єкт із методами `pass(msg)`, `fail(msg)`,
-  `getExitCode()`.
-- `../../../scripts/lib/read-n-cursor-config-lite.mjs` —
-  `readNCursorConfigLite(cwd)`, читає `.n-cursor.json` і повертає об'єкт із
-  полями `rules: string[]` і `disableRules: string[]`.
-- `../../../scripts/utils/resolve-cargo-manifest.mjs` —
-  `resolveAllCargoManifests(cwd)`, повертає масив абсолютних шляхів до всіх
-  `Cargo.toml` у проєкті (cwd, workspace-члени, Tauri-патерн
-  `src-tauri/Cargo.toml`).
-
-### Файлові ресурси
-
-- `data/cargo_mutants_config/mutants.toml.baseline` (відносно теки модуля,
-  обчислюється через `HERE`) — canonical baseline `.cargo/mutants.toml`.
-  Має бути частиною дистрибутиву `@nitra/cursor`. Порожній файл з
-  коментарем, `cargo-mutants` використовує робочі defaults.
-
-## Потік виконання / Використання
-
-### Як викликається
-
-Модуль експортує `check(cwd)`, яку диспетчер правила `test` (через
-`test.mdc` / контрактний раннер `@nitra/cursor`) викликає під час перевірки
-правил у проєкті. Можлива також CLI-сумісність — функція приймає
-необов'язковий `cwd` і за замовчуванням використовує `process.cwd()`.
-
-### Типовий сценарій
-
-1. Користувач додає у `.n-cursor.json` правило `rust` (поза `disable-rules`).
-2. Раннер виконує концерн `cargo_mutants_config` (через `check(cwd)`).
-3. Концерн читає конфіг, проходить self-gate.
-4. Концерн через `resolveAllCargoManifests` знаходить усі `Cargo.toml`
-   (cwd, workspace-члени, `src-tauri/Cargo.toml` для Tauri-проєктів).
-5. Для кожного манифеста, що не має `.cargo/mutants.toml`, файл
-   створюється з canonical baseline; для тих, що вже мають — pass.
-6. Раннер отримує exit-код `0` або `1` і агрегує його з рештою концернів.
-
-### Сценарії silently skip
+Огляд
 
-- `rust` не у `rules` — концерн не релевантний, скіп.
-- `rust` у `disable-rules` — користувач свідомо вимкнув, скіп.
-- Жодного `Cargo.toml` у проєкті — манифест ще не створено, скіп
-  (не помилка).
+Файл отримує робочий каталог, читає конфігурацію курсора та перевіряє налаштування проєкту. Перевіряється наявність правил rust або їх вимкнення, маніфестів Cargo та файлу canonical baseline. Якщо знайдено файл mutants.toml, процес створення файлу mutants.toml пропускається. У випадку наявності mutants.toml, створюється директорія для цільового файлу, копіюється canonical baseline у цей файл та повідомляється про створення файлу mutants.toml (test.mdc).
 
-### Сценарій порушення (`exit 1`)
+## Поведінка
 
-- canonical baseline `data/cargo_mutants_config/mutants.toml.baseline`
-  відсутній у дистрибутиві `@nitra/cursor` — інсталяція пакета зламана,
-  потрібно перевстановити.
+1. Отримати корінь проєкту або використовувати поточний робочий каталог
+2. Зчитати конфігурацію курсора
+3. Перевірити наявність правила rust або його вимкнення
+4. Звернути увагу, якщо не знайдено маніфестів Cargo
+5. Перевірити наявність файлу canonical baseline
+6. Ітерувати по всіх знайдених маніфестах
+7. Для кожного маніфеста визначити директорію цільового файлу
+8. Перевірити наявність файлу mutants.toml
+9. Якщо файл mutants.toml існує, пропустити
+10. Створити директорію для цільового файлу
+11. Скопіювати canonical baseline у цільовий файл
+12. Повідомити про створення файлу mutants.toml з canonical baseline (test.mdc)
 
-### Внутрішні константи
+## Гарантії поведінки
 
-- `HERE = dirname(fileURLToPath(import.meta.url))` — абсолютний шлях до
-  теки, де лежить цей `.mjs`.
-- `BASELINE_PATH = join(HERE, 'data', 'cargo_mutants_config', 'mutants.toml.baseline')` —
-  абсолютний шлях до canonical baseline. Шлях відраховується від
-  розташування самого модуля, тому стабільний незалежно від `cwd`.
+- Не звертається до мережі.

package/rules/test/js/docs/location.md

@@ -1,136 +1,34 @@
+---
+docgen:
+  source: npm/rules/test/js/location.mjs
+  crc: 9ea5f9b8
+  score: 100
+---
+
 # location.mjs
 
 ## Огляд
 
-Модуль реалізує перевірку правила `test.mdc` щодо **розміщення тестових файлів** у JS-кодовій базі.
-
-Конвенція: усі файли з суфіксом `.test.mjs` повинні лежати у каталозі `tests/`, що розташований поряд із джерельним файлом. Тобто для джерела `dir/foo.mjs` правильне розташування тесту — `dir/tests/foo.test.mjs`, а не `dir/foo.test.mjs`.
-
-Особливості:
-
-- Виключено `*_test.rego` — Rego unit-тести, за конвенцією OPA community, лежать поряд із полісі.
-- Обхід дерева через `walkDir` автоматично пропускає `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv`.
-- Додатково ігноруються шляхи з `.n-cursor.json:ignore` (через `loadCursorIgnorePaths`).
-
-Файл експортує асинхронну функцію `check`, яка призначена для запуску з кореня репозиторію (зазвичай через runner правил у `npm/rules/`). Повертає exit-код (0 — успіх, 1 — порушення), формуючи звіт через `createCheckReporter`.
-
-## Експорти / API
-
-| Експорт | Тип                                      | Опис                                                         |
-| ------- | ---------------------------------------- | ------------------------------------------------------------ |
-| `check` | `(cwdParam?: string) => Promise<number>` | Запуск перевірки розміщення `*.test.mjs`. Повертає exit-код. |
-
-Внутрішні (не експортовані) допоміжні функції:
-
-- `isTestFile(absPath: string): boolean`
-- `isInsideTestsDir(absPath: string): boolean`
-
-Внутрішня константа:
-
-- `TESTS_DIR_NAME = 'tests'` — канонічна назва каталогу для тестів.
-
-## Функції
-
-### `isTestFile(absPath)`
-
-- **Сигнатура:** `function isTestFile(absPath: string): boolean`
-- **Параметри:**
-  - `absPath` — абсолютний (або відносний — функція не залежить від форми) шлях до файла.
-- **Повертає:** `true`, якщо `basename(absPath)` закінчується на `.test.mjs`, інакше `false`.
-- **Side effects:** немає; функція чиста.
-- **Використання:** фільтрує лише JS-тести; інші розширення (`.test.ts`, `_test.rego` тощо) ігноруються.
-
-### `isInsideTestsDir(absPath)`
-
-- **Сигнатура:** `function isInsideTestsDir(absPath: string): boolean`
-- **Параметри:**
-  - `absPath` — шлях до тестового файла.
-- **Повертає:** `true`, якщо басенейм безпосередньої батьківської директорії дорівнює `tests` (значення `TESTS_DIR_NAME`).
-- **Side effects:** немає; функція чиста.
-- **Зауваження:** перевіряється саме безпосередній батько (`basename(dirname(absPath))`), а не наявність `tests/` будь-де у шляху. Тобто `pkg/tests/sub/foo.test.mjs` буде вважатися **поза** `tests/` (батько — `sub`, а не `tests`).
-
-### `check(cwdParam = process.cwd())`
-
-- **Сигнатура:** `export async function check(cwdParam?: string): Promise<number>`
-- **Параметри:**
-  - `cwdParam` _(опціонально)_ — корінь репозиторію, з якого починається обхід. За замовчуванням — `process.cwd()`.
-- **Повертає:** `Promise<number>` — exit-код від `reporter.getExitCode()`. За домовленістю з `createCheckReporter`: `0` — порушень немає, `1` — є порушення.
-- **Side effects:**
-  - Читання файлової системи: обхід дерева від `cwd` через `walkDir`.
-  - Читання конфігурації: `.n-cursor.json` через `loadCursorIgnorePaths`.
-  - Запис у `stdout` / `stderr`: повідомлення про `pass` / `fail` через `createCheckReporter` (формат повідомлень визначається репортером).
-- **Алгоритм:**
-  1. Створити репортер: `const reporter = createCheckReporter()`, дістати `pass` і `fail`.
-  2. Завантажити список ігнорованих шляхів: `ignorePaths = await loadCursorIgnorePaths(cwd)`.
-  3. Ініціалізувати лічильник `totalTests = 0` та масив `offenders: string[]`.
-  4. Обійти дерево `walkDir(cwd, visitor, ignorePaths)`. Для кожного файла:
-     - Якщо `!isTestFile(absPath)` — пропустити.
-     - Інакше `totalTests++`.
-     - Якщо `!isInsideTestsDir(absPath)` — додати **відносний** до `cwd` шлях у `offenders` (через `relative(cwd, absPath)`).
-  5. Якщо `offenders.length === 0` — викликати `pass('Всі ${totalTests} файлів *.test.mjs у каталозі tests/ (test.mdc)')` і повернути `reporter.getExitCode()`.
-  6. Інакше — для кожного `offenderPath`:
-     - Обчислити `parentDir = dirname(offenderPath)` і `base = basename(offenderPath)`.
-     - Викликати `fail` з повідомленням-підказкою: тест має лежати у `tests/` — рекомендований шлях `${parentDir}/tests/${base}` (з посиланням на правило `test.mdc`).
-  7. Повернути `reporter.getExitCode()`.
-
-## Залежності
-
-### Стандартна бібліотека Node.js
-
-- `node:path` — функції `basename`, `dirname`, `relative`.
-
-### Внутрішні модулі репозиторію (відносні шляхи від `npm/rules/test/js/location.mjs`)
-
-- `../../../scripts/lib/check-reporter.mjs` — фабрика репортерів `createCheckReporter()`, що повертає об'єкт з методами `pass(msg)`, `fail(msg)` та `getExitCode()`.
-- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths(cwd)`: повертає список глобів/шляхів, які слід пропустити при обході (зчитується з `.n-cursor.json`, ключ `ignore`).
-- `../../../scripts/utils/walkDir.mjs` — асинхронний рекурсивний обхід дерева: `walkDir(rootDir, visitor, ignorePaths)`; за замовчуванням пропускає `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv`.
-
-### Зовнішні правила (концептуальні залежності)
-
-- `test.mdc` — правило, що формалізує конвенцію розміщення тестів і на яке посилаються повідомлення `pass`/`fail`.
-
-## Потік виконання / Використання
-
-### Типове використання як перевірка правила
-
-Файл є частиною системи перевірок (`npm/rules/test/js/`). Зазвичай викликається runner'ом, який знає про expor `check`:
-
-```js
-import { check } from './location.mjs'
-
-process.exit(await check())
-```
-
-або з явним коренем:
-
-```js
-const code = await check('/path/to/repo')
-```
-
-### Послідовність виконання
+Файл перевіряє структуру директорій для ідентифікації та визначення тестів. Він призначений для перегляду шляхів та формування інструкцій щодо коректного розміщення тестів. (test.mdc)
 
-1. Виклик `check()` (опційно з `cwdParam`).
-2. Створення репортера → завантаження `ignorePaths`.
-3. Однопрохідний обхід дерева від `cwd`:
-   - на кожному кроці фільтр `isTestFile`,
-   - інкремент `totalTests`,
-   - перевірка `isInsideTestsDir`, накопичення `offenders`.
-4. Звіт:
-   - якщо `offenders.length === 0` — один `pass` з підсумком `totalTests`;
-   - інакше — `fail` для кожного порушника з підказкою куди перенести.
-5. Повернення exit-коду (`0` або `1`).
+## Поведінка
 
-### Граничні випадки
+1. Початок перевірки.
+2. Завантаження конфігурації ігнорованих шляхів.
+3. Початок обходу директорій.
+4. Перевірка кожного файлу.
+5. Якщо файл не має суфікса `.test.mjs`, пропускається.
+6. Якщо файл має суфікс `.test.mjs`, збільшується лічильник тестів.
+7. Якщо файл не знаходиться у каталозі з іменем `tests/`, записується шлях до порушення.
+8. Якщо жодного порушення не знайдено, повертається код успіху.
+9. Якщо знайдено порушення, для кожного порушення генерується повідомлення про необхідність переміщення тесту у (test.mdc).
+10. Повернення коду звітного генератора.
 
-- **Немає жодного `*.test.mjs`:** `totalTests === 0`, `offenders === []` — буде успішний `pass('Всі 0 файлів *.test.mjs у каталозі tests/ (test.mdc)')`.
-- **Тест у вкладеному каталозі `tests/`:** наприклад, `dir/tests/sub/foo.test.mjs` — буде вважатися порушенням, бо безпосередній батько — `sub`, а не `tests`.
-- **Файли з частковим суфіксом:** `foo.test.mjs.bak` — не вважається тестом (не закінчується на `.test.mjs`).
-- **Шляхи з `.n-cursor.json:ignore`** не відвідуються `walkDir` і не впливають на лічильники.
+## Публічний API
 
-### Rebuild Test
+check — перевіряє, чи знаходяться тестові файли у каталозі `tests/` (test.mdc).
 
-Для верифікації коректності документації — мисленний rebuild:
+## Гарантії поведінки
 
-- Дано: дерево з файлами `a/foo.test.mjs`, `a/tests/bar.test.mjs`, `b/baz.test.mjs`.
-- Очікувано: `totalTests === 3`; `offenders === ['a/foo.test.mjs', 'b/baz.test.mjs']`; два виклики `fail`; exit-код `1`.
-- Повідомлення `fail` для `a/foo.test.mjs` міститимуть підказку: `a/foo.test.mjs: тест має лежати у tests/ — перенеси у a/tests/foo.test.mjs (test.mdc)`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.