@nitra/cursor 3.22.0 → 3.23.0

package/rules/test/js/data/vitest_config/docs/vitest.config.baseline.md

@@ -0,0 +1,195 @@
+# vitest.config.baseline.js
+
+## Огляд
+
+Файл `vitest.config.baseline.js` — це **еталонна (baseline) конфігурація Vitest**, яка використовується як test-data fixture у правилі `test` пакета `npm/rules`. Він задає мінімальний, але достатній набір опцій Vitest, що відповідає внутрішнім конвенціям проєкту: розкладку тестових файлів, exclude-патерни для штучних artefact-директорій (наприклад, sandbox-копій Stryker), середовище виконання та модель ізоляції паралельних воркерів.
+
+Файл одночасно виконує дві ролі:
+
+1. **Робоча конфігурація Vitest** — повністю валідний модуль, який можна передати в `vitest run` чи `vitest --config <path>`. Vitest імпортує `default`-export і використовує його як свої налаштування.
+2. **Канонічний приклад (baseline) для перевірок rule `test`** — зберігається у `data/vitest_config/`, де `data/` — стандартна тека fixture-даних для правил у `npm/rules`. Інші конфіги в цьому проєкті (або їхні фрагменти) можуть порівнюватися з цим baseline, щоб гарантувати єдиний стиль.
+
+Ключове технічне рішення, зафіксоване у файлі через коментарі, — використання `pool: 'forks'` замість дефолтного `pool: 'threads'` для уникнення гонок навколо `process.chdir()` у тестових фікстурах (детально див. ## Функції / Конфігурація).
+
+## Експорти / API
+
+Модуль має один **default export** — об'єкт-конфігурація Vitest, обгорнутий у `defineConfig()`:
+
+```js
+export default defineConfig({
+  test: {
+    /* ... */
+  }
+})
+```
+
+| Експорт   | Тип                       | Призначення                                                                                                                                                                                 |
+| --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default` | `UserConfig` (тип Vitest) | Об'єкт конфігурації для команди `vitest`. Підхоплюється автоматично, якщо файл лежить за дефолтним ім'ям `vitest.config.{js,mjs,ts}` у корені проєкту, або задається явно через `--config`. |
+
+Іменованих експортів немає.
+
+### Структура default-export
+
+Об'єкт містить єдиний верхньорівневий ключ `test`, всередині якого:
+
+| Ключ               | Тип        | Значення                                                        | Призначення                                                             |
+| ------------------ | ---------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `test.include`     | `string[]` | `['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}']`            | Glob-патерни файлів, які Vitest вважає тестами.                         |
+| `test.exclude`     | `string[]` | `['**/node_modules/**', '**/dist/**', '**/reports/stryker/**']` | Glob-патерни, виключені зі сканування.                                  |
+| `test.environment` | `string`   | `'node'`                                                        | Тестове середовище — Node.js (без jsdom/happy-dom).                     |
+| `test.pool`        | `string`   | `'forks'`                                                       | Модель ізоляції воркерів — окремі процеси на тест-файл.                 |
+| `test.coverage`    | `object`   | `{ provider: 'v8', reporter: ['lcov', 'text-summary'] }`        | Налаштування покриття: V8-провайдер, репортери `lcov` + `text-summary`. |
+
+## Функції
+
+Файл **не містить власних функцій** — це чисто декларативний конфігураційний модуль. Єдиний виклик — `defineConfig(...)`, імпортований з `vitest/config`.
+
+### `defineConfig(config)`
+
+| Атрибут      | Значення                                                                                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| Походження   | Імпортується з пакета `vitest/config` (named export).                                                                                                   |
+| Сигнатура    | `defineConfig(config: UserConfig                                                                                                                        | UserConfigFn): UserConfig` |
+| Параметри    | `config` — об'єкт конфігурації Vitest або функція, що повертає такий об'єкт (підтримується async-варіант). У цьому файлі передається статичний літерал. |
+| Повертає     | Той самий об'єкт (identity для runtime), але з повною TypeScript-типізацією — без `defineConfig` IDE не підказувала б ключі.                            |
+| Side effects | Немає. Функція — idempotent type-helper.                                                                                                                |
+
+### Конфігурація — поле за полем
+
+**`test.include`**
+
+- Значення: `['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}']`.
+- Семантика: підхоплюються **обидві основні розкладки** тестів, прийняті в монорепо:
+  - Тести **поряд із кодом** у піддиректоріях `tests/` (test.mdc-конвенція пакета `npm/rules` — кожне правило тримає свої тести у `<rule>/tests/`).
+  - Top-level **integration suites** у `<root>/tests/`.
+- Glob-патерн `**/*.test.{js,mjs}` рекурсивно охоплює обидва випадки; другий патерн `tests/**/*.test.{js,mjs}` залишений як надлишково-явна декларація для читабельності та узгодженості з документацією.
+
+**`test.exclude`**
+
+- Значення: `['**/node_modules/**', '**/dist/**', '**/reports/stryker/**']`.
+- Перші два патерни — стандартні для Node-проєктів (vendor-залежності та build-артефакти).
+- **Критичний патерн** `**/reports/stryker/**` виключає sandbox-копії тестів, які Stryker (mutation testing) залишає у `reports/stryker/.tmp/` після incremental- або aborted-runs. Без цього exclude команда `vitest run --coverage` підхоплює ці копії і вони **фейляться**, бо стартують поза реальним repo root. Детальна мотивація фіксована inline-коментарем.
+
+**`test.environment`**
+
+- Значення: `'node'`.
+- Тести виконуються у звичайному Node.js-середовищі: без DOM-стабів, без `window`/`document`. Це коректний вибір для CLI- та rule-логіки, що становить основну масу коду в `npm/rules`.
+
+**`test.pool`**
+
+- Значення: `'forks'` (замість дефолтного `'threads'`).
+- **Defense-in-depth ізоляція процесів** між тест-файлами. Мотивація:
+  - У дефолтному `pool: 'threads'` усі воркери ділять **один спільний процес Node.js** → кожен `process.chdir(dir)` всередині фікстури **перехоплює cwd сусіда** посеред його FS- або `git`-операції.
+  - Зафіксований реальний інцидент: `git init` + `git commit` із tmp-фікстури **потрапив у реальний робочий репозиторій**, бо cwd змінився в момент виклику Git.
+  - `pool: 'forks'` дає кожному файлу окремий процес → `process.chdir` локальний, ізоляція гарантована.
+  - Канонічний патерн тестів, прийнятий у проєкті, — `withTmpDir(async dir => ...)` (зафіксований у `test.mdc`).
+
+**`test.coverage`**
+
+- Значення: `{ provider: 'v8', reporter: ['lcov', 'text-summary'] }`.
+- `provider: 'v8'` — нативне покриття від V8 engine (без інструментації Istanbul) — швидше та точніше для сучасного Node.
+- `reporter`:
+  - `'lcov'` — машиночитний формат (`lcov.info`) для імпорту в CI / SonarQube / Codecov.
+  - `'text-summary'` — компактний текстовий звіт у stdout для локального запуску й логів CI.
+
+### Side effects модуля
+
+Side effects відсутні. Файл — pure declarative module: на import-time не відбувається мутації глобального стану, відкриття дескрипторів чи мережевих з'єднань. Vitest сам інтерпретує об'єкт у власному lifecycle.
+
+## Залежності
+
+### Зовнішні (npm)
+
+| Пакет           | Імпорт                                         | Призначення                                                                                                                                                                |
+| --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vitest/config` | `import { defineConfig } from 'vitest/config'` | Сабпакет основного пакета `vitest`. Експортує `defineConfig` — type-helper, що дає TypeScript-/IDE-підказки для об'єкта конфігурації. Має бути доступним як devDependency. |
+
+### Внутрішні залежності проєкту
+
+Жодних internal-імпортів — файл є кінцевим листком тестового data-fixture.
+
+### Транзитивні / runtime
+
+На етапі реального тестового виконання задіюються (поза цим файлом):
+
+- `vitest` — раннер, який споживає об'єкт конфігурації.
+- `@vitest/coverage-v8` — окремий пакет coverage-провайдера V8, потрібен, якщо запускати з `--coverage` (іноді постачається як peer-dependency).
+
+## Потік виконання / Використання
+
+### Як baseline-fixture для правила `test`
+
+Файл лежить у `npm/rules/test/js/data/vitest_config/` — типовій теці `data/`, де правила пакета `npm/rules` зберігають **референсні приклади (fixtures)** для:
+
+- snapshot-порівнянь з конфігами користувацьких проєктів,
+- pattern-matching у перевірках (наприклад, чи містить чужий `vitest.config.js` необхідні ключі),
+- авто-генерації / migration-кроків (rule може запропонувати оновити чужий конфіг до baseline).
+
+Конкретний механізм споживання baseline залежить від реалізації check-функцій правила (`check-*.mjs`), але типова схема така:
+
+1. Rule отримує цільовий `vitest.config.{js,mjs,ts}` проєкту.
+2. Парсить його (через AST або динамічний import у sandbox) та зіставляє з baseline.
+3. Емітить попередження / автофікс, якщо ключові поля (`pool`, `exclude`, `coverage.provider`) відхиляються від baseline.
+
+### Як робоча конфігурація Vitest
+
+Файл повністю придатний до прямого використання Vitest-CLI:
+
+```bash
+vitest run --config npm/rules/test/js/data/vitest_config/vitest.config.baseline.js
+```
+
+або копіюванням у корінь споживчого проєкту під ім'ям `vitest.config.js`.
+
+Lifecycle:
+
+1. Vitest CLI завантажує модуль через ESM-loader Node.
+2. `defineConfig` повертає той самий об'єкт; default-export потрапляє у Vitest internals.
+3. Vitest застосовує `test.include`/`test.exclude` для discovery, потім ініціалізує `forks`-pool, для кожного знайденого файлу спавнить child-process з `environment: 'node'`.
+4. Якщо запуск із `--coverage` — після проходу збирається V8-coverage і пишеться `lcov.info` + текстовий summary.
+
+### Інваріанти, що треба зберігати при правках
+
+- **Не змінювати `pool: 'forks'` на `'threads'`** без явного перегляду всіх тестів на `process.chdir` — це регрес з ризиком пошкодження реального репозиторію.
+- **Не видаляти `**/reports/stryker/**`з`exclude`** — інакше coverage-run починає підхоплювати mutation-sandbox-копії.
+- **Не додавати `test.environment: 'jsdom'`** без потреби — це повільніше і неактуально для текстової/CLI-логіки `npm/rules`.
+
+## Rebuild Test
+
+Файл — конфігурація без власної логіки, тому ребілд-тест зводиться до перевірки структурної відповідності default-export очікуваним полям. Орієнтовний smoke-тест на Vitest (псевдокод):
+
+```js
+import { describe, it, expect } from 'vitest'
+import config from './vitest.config.baseline.js'
+
+describe('vitest.config.baseline.js', () => {
+  it('експортує об`єкт із секцією test', () => {
+    expect(config).toBeTypeOf('object')
+    expect(config.test).toBeTypeOf('object')
+  })
+
+  it('include охоплює дві канонічні розкладки', () => {
+    expect(config.test.include).toEqual(['**/*.test.{js,mjs}', 'tests/**/*.test.{js,mjs}'])
+  })
+
+  it('exclude містить stryker-sandbox', () => {
+    expect(config.test.exclude).toContain('**/reports/stryker/**')
+  })
+
+  it('environment === node', () => {
+    expect(config.test.environment).toBe('node')
+  })
+
+  it('pool === forks (захист від chdir-гонок)', () => {
+    expect(config.test.pool).toBe('forks')
+  })
+
+  it('coverage: v8 + lcov + text-summary', () => {
+    expect(config.test.coverage.provider).toBe('v8')
+    expect(config.test.coverage.reporter).toEqual(['lcov', 'text-summary'])
+  })
+})
+```
+
+Цього достатньо, щоб зафіксувати baseline як invariant — будь-яка спроба змінити критичні поля без узгодження впаде на smoke-тесті.

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

@@ -0,0 +1,173 @@
+# 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` у проєкті — манифест ще не створено, скіп
+  (не помилка).
+
+### Сценарій порушення (`exit 1`)
+
+- canonical baseline `data/cargo_mutants_config/mutants.toml.baseline`
+  відсутній у дистрибутиві `@nitra/cursor` — інсталяція пакета зламана,
+  потрібно перевстановити.
+
+### Внутрішні константи
+
+- `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

@@ -0,0 +1,136 @@
+# 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')
+```
+
+### Послідовність виконання
+
+1. Виклик `check()` (опційно з `cwdParam`).
+2. Створення репортера → завантаження `ignorePaths`.
+3. Однопрохідний обхід дерева від `cwd`:
+   - на кожному кроці фільтр `isTestFile`,
+   - інкремент `totalTests`,
+   - перевірка `isInsideTestsDir`, накопичення `offenders`.
+4. Звіт:
+   - якщо `offenders.length === 0` — один `pass` з підсумком `totalTests`;
+   - інакше — `fail` для кожного порушника з підказкою куди перенести.
+5. Повернення exit-коду (`0` або `1`).
+
+### Граничні випадки
+
+- **Немає жодного `*.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` і не впливають на лічильники.
+
+### Rebuild Test
+
+Для верифікації коректності документації — мисленний 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)`.