@nitra/cursor 3.21.1 → 3.23.0

package/rules/test/js/docs/no-process-chdir.md

@@ -0,0 +1,160 @@
+# `no-process-chdir.mjs`
+
+## Огляд
+
+Модуль `no-process-chdir.mjs` — concern-перевірка (check) з набору правил `test.mdc`, яка **забороняє виклик `process.chdir(...)` у тестових файлах** (`*.test.js`, `*.test.mjs`) проєкту.
+
+Мотивація закладена у заголовному JSDoc файлу та повторена в повідомленнях звіту:
+
+- `process.chdir` — це **process-wide мутація** робочого каталогу.
+- Vitest за замовчуванням використовує `pool: 'threads'`, у якому workers ділять **один процес**. Це означає, що паралельний `test file` може перехопити `cwd` сусіда посеред FS- або `git`-операції.
+- Зафіксований реальний інцидент: `git init` + `git commit` із tmp-фікстури `withTmpCwd` потрапили у реальний робочий репозиторій і створили rogue-commit з автором `test <test@test>`.
+- Канонічна заміна: `withTmpDir(async dir => …)` зі `scripts/utils/test-helpers.mjs` (без `chdir`), плюс **явні** `cwd: dir` у child-процесах та `await check(dir)` для concern-функцій.
+
+Перевірка реалізована як один експортований асинхронний `check(cwd)`, придатний для запуску з runner-а check-репортера. Вона рекурсивно знаходить тестові файли (через `walkDir`), читає їх вміст і шукає викликний паттерн `process.chdir(`. На збігах формується список offenders, для кожного з яких репортер видає `fail`-повідомлення з шляхом і номером рядка; за відсутності збігів видається одне `pass`.
+
+Регулярний вираз навмисно вимагає **відкривну дужку**, тому згадки `process.chdir` у коментарях/документації (наприклад, фраза «не використовуй `process.chdir`») **не тригерять** падіння.
+
+## Експорти / API
+
+| Експорт | Тип                                            | Призначення                                                                                                                                                    |
+| ------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check` | `async (cwdParam?: string) => Promise<number>` | Іменований експорт. Виконує перевірку всіх тестових файлів у заданому корені й повертає exit-код для CI: `0` — чисто, `1` — знайдено `process.chdir(` у тесті. |
+
+Інших публічних експортів файл не містить. Модуль використовує ESM (`import`/`export`).
+
+Окрім експорту, у модулі визначені **внутрішні** елементи (не експортуються):
+
+- Константа `CHDIR_CALL_RE` — `RegExp`.
+- Функція `isTestFile(absPath)` — допоміжна (file-private).
+
+## Функції
+
+### `isTestFile(absPath)`
+
+Внутрішня (не експортована) функція-предикат.
+
+- **Сигнатура:** `function isTestFile(absPath: string): boolean`
+- **Параметри:**
+  - `absPath` (`string`) — абсолютний шлях до файлу-кандидата (передається з `walkDir`).
+- **Повертає:** `boolean` — `true`, якщо `basename(absPath)` закінчується на `.test.mjs` або `.test.js`; інакше `false`.
+- **Side effects:** немає (чиста функція; читає лише вхідний рядок через `basename` з `node:path`).
+- **Логіка:**
+  1. Бере `basename(absPath)` через `node:path`.
+  2. Перевіряє суфікси `.test.mjs` і `.test.js` через `String.prototype.endsWith`.
+  3. Повертає диз'юнкцію цих перевірок.
+
+### `check(cwdParam = process.cwd())`
+
+Головна (і єдина) експортована функція concern-у.
+
+- **Сигнатура:** `async function check(cwdParam?: string): Promise<number>`
+- **Параметри:**
+  - `cwdParam` (`string`, опціональний) — корінь репозиторію/проєкту, який потрібно перевіряти. Якщо не передано — використовується `process.cwd()`. У документації заголовка та в повідомленнях про інцидент рекомендується **завжди передавати явний `dir`** з тестового середовища (через `await check(dir)`), щоб не залежати від фактичного `process.cwd()` процесу-runner-а.
+- **Повертає:** `Promise<number>` — exit-код, отриманий від `reporter.getExitCode()`:
+  - `0` — у жодному тестовому файлі не знайдено виклику `process.chdir(`.
+  - `1` — знайдено хоча б один виклик; усі offenders повідомлені як `fail`.
+- **Side effects:**
+  - Звертається до файлової системи: рекурсивний обхід через `walkDir` та `readFile` для кожного знайденого тестового файлу.
+  - Викликає функції `pass`/`fail` репортера (`createCheckReporter`), які типово друкують повідомлення у `stdout`/`stderr` (поведінка інкапсульована у `check-reporter`).
+  - Читає `.n-cursor.json` (через `loadCursorIgnorePaths`) для отримання списку ігнорованих шляхів.
+  - Не змінює файлову систему й не змінює `cwd` процесу.
+- **Алгоритм:**
+  1. Створює репортер: `const reporter = createCheckReporter()`; деструктурує `pass` і `fail`.
+  2. Зберігає `cwd = cwdParam` (локально, без побічних ефектів на процес).
+  3. Завантажує список ignore-шляхів: `ignorePaths = await loadCursorIgnorePaths(cwd)`.
+  4. Готує локальний акумулятор `testFiles: string[]` і викликає `walkDir(cwd, callback, ignorePaths)`. У callback-у — якщо `isTestFile(absPath)`, додає шлях у масив.
+  5. Готує акумулятор `offenders: Array<{file: string, line: number}>`.
+  6. Для кожного `absPath` із `testFiles`:
+     - Читає вміст: `body = await readFile(absPath, 'utf8')`.
+     - Якщо у тілі немає збігу з `CHDIR_CALL_RE` — `continue` (швидкий вихід без побудови `lines`).
+     - Інакше розбиває тіло на рядки `body.split('\n')` і для кожного рядка `(i, line)` перевіряє `CHDIR_CALL_RE.test(line)`. На збігу — `offenders.push({ file: relative(cwd, absPath), line: i + 1 })` (номер рядка — 1-базований).
+  7. Якщо `offenders.length === 0` — викликає `pass(`Жоден з ${testFiles.length} тестових файлів не викликає process.chdir() (test.mdc)`)` і повертає `reporter.getExitCode()`.
+  8. Інакше — для кожного offender викликає `fail` з повідомленням формату `${file}:${line}: process.chdir() у тесті заборонений — використовуй withTmpDir(async dir => …) + явні join(dir, …) + cwd: dir (test.mdc)` і у фіналі повертає `reporter.getExitCode()`.
+
+## Константи і регулярні вирази
+
+### `CHDIR_CALL_RE`
+
+```js
+const CHDIR_CALL_RE = /process\.chdir\s*\(/u
+```
+
+- **Призначення:** виявити **викликний** паттерн `process.chdir(`.
+- **Семантика:**
+  - `process\.chdir` — буквальне ім'я виклику (крапка екранована).
+  - `\s*` — допускає будь-яку кількість пробільних символів між ідентифікатором і дужкою.
+  - `\(` — обов'язкова відкривна дужка; саме вона відрізняє виклик від згадки в коментарі/документації.
+  - Прапор `u` — Unicode-режим.
+- **Наслідки дизайну:**
+  - Згадки `process.chdir` у JSDoc/коментарях без `(` **не** дають збігу (це навмисно і задокументовано).
+  - Регулярка лінійна, без backtracking-ризиків; виконується спочатку проти всього `body` (швидкий short-circuit), потім — порядково для локалізації номера рядка.
+
+## Залежності
+
+### Зовнішні (стандартна бібліотека Node)
+
+- `node:fs/promises` → іменований імпорт `readFile` — асинхронне читання тестових файлів у режимі `'utf8'`.
+- `node:path` → іменовані імпорти:
+  - `basename` — у `isTestFile` для перевірки суфікса.
+  - `relative` — для перетворення абсолютного шляху offender-а в шлях, відносний до `cwd`, перед публікацією у `fail`-повідомленні.
+
+### Внутрішні (репозиторій)
+
+Усі — відносні шляхи від `npm/rules/test/js/no-process-chdir.mjs`:
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера; повертає об'єкт з методами `pass`, `fail` і `getExitCode()`. Інкапсулює формат виведення й підрахунок exit-коду.
+- `../../../scripts/lib/load-cursor-config.mjs` → `loadCursorIgnorePaths` — повертає список ігнорованих шляхів із `.n-cursor.json` (поле `ignore`), які треба передати у `walkDir` як другий рівень фільтрації (на додаток до вбудованих скіпів самого `walkDir`).
+- `../../../scripts/utils/walkDir.mjs` → `walkDir` — рекурсивний обхід дерева; за заголовним коментарем модуля вбудовано пропускає `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv`. Викликає callback з абсолютним шляхом для кожного відвіданого файлу.
+
+## Потік виконання / Використання
+
+### Запуск як частина check-набору
+
+Модуль не виконується автоматично при імпорті — це **бібліотечний** файл concern-а: він експортує `check`, який має бути викликаний runner-ом (наприклад, агрегатором правил `test.mdc`). Типовий виклик:
+
+```js
+import { check } from './npm/rules/test/js/no-process-chdir.mjs'
+
+const code = await check(process.cwd())
+process.exit(code)
+```
+
+Або з явним коренем (як рекомендовано у заголовному JSDoc — для concern-функцій передавати `dir`, а не покладатися на process-wide `cwd`):
+
+```js
+await check(dir) // dir отриманий з withTmpDir або з runner-а
+```
+
+### Послідовність кроків під час одного виклику
+
+1. `createCheckReporter()` створює пристрій для накопичення pass/fail повідомлень.
+2. `loadCursorIgnorePaths(cwd)` читає `.n-cursor.json` (поле `ignore`) у корені проєкту.
+3. `walkDir(cwd, callback, ignorePaths)` обходить дерево, пропускаючи стандартні теки (`node_modules`, `.git`, `dist`, `build`, `.venv`, `venv`) і шляхи з ignore-списку. Колбек збирає шляхи, що задовольняють `isTestFile`.
+4. Для кожного зібраного тестового файлу:
+   - Швидкий тест регуляркою проти повного тексту — для більшості файлів ціна перевірки = `O(N)` без подальшої роботи.
+   - Якщо є збіг, файл розбивається на рядки, і для кожного рядка з виявленим паттерном до `offenders` додається `{file, line}` (шлях нормалізовано через `relative(cwd, absPath)`, номер рядка — 1-базований).
+5. Формування результату:
+   - Порожній `offenders` → одна `pass`-нотатка з кількістю просканованих файлів.
+   - Непорожній — окремий `fail` на кожен `{file, line}` з підказкою про канонічну заміну.
+6. Повертається `reporter.getExitCode()` — `0` або `1`.
+
+### Поведінка у crash-/inconsistent-сценаріях
+
+- `readFile` з режимом `'utf8'` для бінарних/неіснуючих файлів кине помилку — обхідник `walkDir` має фільтрувати по типу файлу/доступу, але всередині `check` блоків `try/catch` немає, тож помилка спливе у викликача.
+- `loadCursorIgnorePaths`/`walkDir`/`createCheckReporter` помилки також пробрасуються у викликача.
+- Модуль не модифікує глобальний стан і не змінює `cwd` процесу.
+
+### Як виглядає звіт
+
+- **Pass:** `Жоден з N тестових файлів не викликає process.chdir() (test.mdc)` (де `N` — кількість просканованих тест-файлів).
+- **Fail** (по одному рядку на кожен збіг): `path/to/file.test.mjs:123: process.chdir() у тесті заборонений — використовуй withTmpDir(async dir => …) + явні join(dir, …) + cwd: dir (test.mdc)`.
+
+### Канонічна заміна `process.chdir` у тестах
+
+Згідно з повідомленнями репортера і коментарем у заголовку:
+
+- Використовувати `withTmpDir(async dir => …)` зі `scripts/utils/test-helpers.mjs`.
+- У FS-операціях формувати шляхи через `join(dir, …)` явно.
+- У викликах child-процесів передавати `cwd: dir` як опцію.
+- У concern-функціях — приймати `cwd`/`dir` параметром і не покладатися на `process.cwd()`.

package/rules/test/js/docs/no-relative-fs-path.md

@@ -0,0 +1,271 @@
+# no-relative-fs-path.mjs
+
+## Огляд
+
+Модуль реалізує AST-based перевірку, яка забороняє передавати **relative-path**
+аргументи у функції модулів `node:fs` / `node:fs/promises` (а також у тестові
+helper-функції, що вимагають абсолютних шляхів) усередині JS-тестів
+(`*.test.mjs` / `*.test.js`).
+
+Мотивація задокументована у самому файлі та у правилі `test.mdc`, секція
+«Заборона `process.chdir` у тестах»: після видалення хелпера `withTmpCwd` усі
+тести отримують `dir` параметром і повинні будувати **абсолютні** шляхи через
+`join(dir, …)`. Якщо хтось забуде префікс і напише, наприклад,
+`writeFile('foo.json', …)` або `copyFile(src, 'foo.json')`, relative-path
+зарезолвиться у `process.cwd()` (= `npm/`), що призведе до запису тестової
+фікстури у production tree. Реальний інцидент v1.28.0
+(`tests/check-rule-fixtures.test.mjs` із викликами
+`copyFile(src, 'values-dev.ini')` та
+`copyFile(src, 'default.conf.template')`) створив файли `npm/values-dev.ini` і
+`npm/default.conf.template` поза `dir`.
+
+Сканер парсить кожен тестовий файл через `oxc-parser` (через утиліту
+`parseProgramOrNull`), обходить AST і шукає `CallExpression`, де callee
+збігається з відомою FS-функцією, а path-аргумент є **string literal** (або
+template literal без виразів), що НЕ починається з:
+
+- `/`, `\\` — POSIX/Windows absolute;
+- `file:`, `http:`, `https:`, `data:` — URL-схема (для `new URL(...)`);
+- Windows drive letter `C:\…` або `C:/…`;
+- та НЕ є template literal зі вставленим виразом `${…}` (такі вважаються
+  обчисленими через `join`/`resolve` і пропускаються).
+
+Виклики, у яких path-аргумент НЕ literal (наприклад, `join(...)`,
+`BinaryExpression`, `Identifier`, `MemberExpression`), пропускаються —
+припускається, що це абсолютний шлях.
+
+Перевіряються лише файли, що відповідають `**/*.test.{js,mjs}`. Обхід дерева
+використовує загальний `walkDir` з його скіп-правилами та користувацькими
+`ignore`-шляхами з `.n-cursor.json`.
+
+## Експорти / API
+
+| Експорт            | Тип              | Призначення                                                                                                      |
+| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `check(cwdParam?)` | `async function` | Точка входу перевірки. Сканує `*.test.{mjs,js}` під `cwd`, повертає exit code `0` (чисто) або `1` (є порушення). |
+
+Усі решта функцій (`extractRelativeLiteralPath`, `isRelativeString`,
+`extractFsFunctionName`, `isTestFile`, `findOffendersInBody`,
+`computeLineOffsets`, `offsetToLineFromCache`) та константи
+(`FS_PATH_ARG_POSITIONS`, `ABSOLUTE_PREFIXES`) — module-private, не
+експортуються.
+
+## Функції
+
+### `extractRelativeLiteralPath(arg)`
+
+- **Сигнатура:** `(arg: object) => string | null`
+- **Параметри:**
+  - `arg` — AST node аргументу виклику (Literal, TemplateLiteral тощо) або
+    `undefined`.
+- **Повертає:** значення relative-path (рядок) — якщо аргумент є
+  string-літералом або template literal без виразів і його значення є
+  відносним; `null` — якщо аргумент відсутній, обчислюваний або абсолютний.
+- **Логіка:**
+  - `arg.type === 'Literal' && typeof arg.value === 'string'` →
+    `isRelativeString(arg.value) ? arg.value : null`.
+  - `arg.type === 'TemplateLiteral' && expressions.length === 0` →
+    конкатенує `quasis[i].value.cooked` і так само перевіряє через
+    `isRelativeString`.
+  - Будь-який інший вузол → `null` (не аналізується).
+- **Side effects:** немає.
+
+### `isRelativeString(s)`
+
+- **Сигнатура:** `(s: string) => boolean`
+- **Параметри:** `s` — рядок-шлях.
+- **Повертає:** `true` — якщо рядок виглядає як relative path; `false` — якщо
+  абсолютний, URL, Windows-drive-letter або порожній.
+- **Логіка:**
+  - Порожній рядок → `false` (не path).
+  - Якщо починається з будь-якого з `ABSOLUTE_PREFIXES`
+    (`/`, `\\`, `file:`, `http:`, `https:`, `data:`) → `false`.
+  - Якщо відповідає `^[A-Za-z]:[\\/]/u` (наприклад, `C:\foo`, `C:/foo`) →
+    `false`.
+  - Інакше → `true`.
+- **Side effects:** немає.
+
+### `extractFsFunctionName(callee)`
+
+- **Сигнатура:** `(callee: object) => string | null`
+- **Параметри:** `callee` — AST callee node (Identifier або MemberExpression).
+- **Повертає:** ім'я FS-функції з `FS_PATH_ARG_POSITIONS`, якщо callee
+  розпізнано; інакше `null`.
+- **Логіка:**
+  - `Identifier` → перевіряє `callee.name` у `FS_PATH_ARG_POSITIONS`.
+  - `MemberExpression`, не `computed`, `property.type === 'Identifier'` →
+    бере `callee.property.name` (це покриває `fs.writeFile`, `fsp.writeFile`,
+    `fs.promises.writeFile` тощо) і перевіряє у мапі.
+  - Інакше → `null`.
+- **Side effects:** немає.
+
+### `isTestFile(absPath)`
+
+- **Сигнатура:** `(absPath: string) => boolean`
+- **Параметри:** `absPath` — абсолютний шлях файлу.
+- **Повертає:** `true`, якщо `basename(absPath)` закінчується на
+  `.test.mjs` або `.test.js`; інакше `false`.
+- **Side effects:** немає.
+
+### `findOffendersInBody(body)`
+
+- **Сигнатура:**
+  `(body: string) => Array<{ line: number, fn: string, path: string, argPos: number }>`
+- **Параметри:** `body` — вміст тестового файлу (UTF-8).
+- **Повертає:** масив порушень: `{ line, fn, path, argPos }`, де:
+  - `line` — 1-індексований рядок початку аргументу (або виклику, якщо у
+    аргументу немає `.start`);
+  - `fn` — ім'я FS-функції;
+  - `path` — фактичне значення relative-літералу;
+  - `argPos` — 0-індексована позиція проблемного аргументу.
+- **Логіка:**
+  1. `parseProgramOrNull(body, 'test.mjs')` — парс через oxc-parser із
+     використанням віртуального імені; якщо парс не вдався, повертає `[]`.
+  2. Кешує newline-offsets через `computeLineOffsets`.
+  3. `walkAstWithAncestors(program, [], cb)` — обходить усі вузли.
+     Для кожного `CallExpression`:
+     - визначає `fnName = extractFsFunctionName(node.callee)`; якщо `null` —
+       пропускає;
+     - для кожної позиції з `FS_PATH_ARG_POSITIONS.get(fnName)` бере
+       `node.arguments[pos]`, перевіряє через `extractRelativeLiteralPath`;
+     - якщо `relPath !== null` — обчислює `line` через
+       `offsetToLineFromCache(lineOffsets, arg?.start ?? node.start ?? 0)` і
+       додає об'єкт у `offenders`.
+- **Side effects:** немає. Парсинг через `parseProgramOrNull` сам по собі
+  чистий.
+
+### `computeLineOffsets(body)`
+
+- **Сигнатура:** `(body: string) => number[]`
+- **Параметри:** `body` — джерельний рядок.
+- **Повертає:** масив 0-індексованих offset-ів початків рядків
+  (елемент `0` — позиція `0`, далі позиція кожного символу після `\n`).
+- **Логіка:** лінійний прохід по символах; на кожному `\n` додає `pos + 1`.
+- **Side effects:** немає.
+
+### `offsetToLineFromCache(offsets, offset)`
+
+- **Сигнатура:** `(offsets: number[], offset: number) => number`
+- **Параметри:**
+  - `offsets` — кеш із `computeLineOffsets`;
+  - `offset` — 0-індекс символу у source.
+- **Повертає:** 1-індексований номер рядка, що містить цей offset.
+- **Логіка:** бінарний пошук правого діапазону (`lo`/`hi` із кроком
+  `mid = floor((lo + hi + 1) / 2)`); кінцевий `lo + 1` — номер рядка.
+- **Side effects:** немає.
+
+### `check(cwdParam = process.cwd())`
+
+- **Сигнатура:** `async (cwdParam?: string) => Promise<number>`
+- **Параметри:** `cwdParam` — корінь репозиторію (за замовчуванням
+  `process.cwd()`).
+- **Повертає:** `0` — порушень немає; `1` — є хоча б одне порушення
+  (через `reporter.getExitCode()`).
+- **Логіка:**
+  1. Створює репортер: `createCheckReporter()`, дістає `pass` і `fail`.
+  2. Завантажує користувацькі ignore-шляхи через `loadCursorIgnorePaths(cwd)`
+     (читає `.n-cursor.json#ignore`).
+  3. Через `walkDir(cwd, cb, ignorePaths)` збирає у масив `testFiles` усі
+     `absPath`, для яких `isTestFile(absPath) === true`.
+  4. Для кожного тестового файлу: читає через
+     `readFile(absPath, 'utf8')`, запускає `findOffendersInBody(body)`, до
+     кожного знахідки додає `file: relative(cwd, absPath)`.
+  5. Якщо `offenders.length === 0` — викликає
+     `pass(\`Жоден з ${testFiles.length} тестових файлів не передає relative-path у FS-функції (test.mdc)\`)`і повертає`reporter.getExitCode()`.
+  6. Інакше — для кожного порушення викликає `fail(...)` із повідомленням
+     виду `${file}:${line}: ${fn}() — ${which} '${path}' relative; використовуй join(dir, …) (test.mdc, no-relative-fs-path)`,
+     де `which` = `'1-й аргумент'` для `argPos === 0` і
+     `'${argPos + 1}-й аргумент'` для решти.
+- **Side effects:**
+  - Читає файли з диска (через `readFile` та `walkDir`).
+  - Пише у stdout/stderr через репортер (`pass`/`fail`).
+  - Не змінює файли.
+
+## Константи
+
+### `FS_PATH_ARG_POSITIONS`
+
+`Map<string, number[]>` — імена FS-функцій → масив 0-індексованих позицій
+path-аргументів. Включає:
+
+- з одним path-аргументом (`[0]`): `writeFile`, `writeFileSync`, `readFile`,
+  `readFileSync`, `appendFile`, `appendFileSync`, `mkdir`, `mkdirSync`,
+  `rmdir`, `rmdirSync`, `rm`, `rmSync`, `unlink`, `unlinkSync`, `access`,
+  `accessSync`, `stat`, `statSync`, `lstat`, `lstatSync`, `chmod`,
+  `chmodSync`, `chown`, `chownSync`, `truncate`, `truncateSync`,
+  `existsSync`, `readdir`, `readdirSync`;
+- з двома path-аргументами (`[0, 1]`): `copyFile`, `copyFileSync`, `rename`,
+  `renameSync`, `symlink`, `symlinkSync`, `link`, `linkSync`, `cp`, `cpSync`;
+- тестові-хелпери (зайвий захист, тільки 1-й): `writeJson`, `ensureDir`.
+
+### `ABSOLUTE_PREFIXES`
+
+`string[]` зі значенням `['/', '\\', 'file:', 'http:', 'https:', 'data:']` —
+префікси, які вважаються «явно абсолютним або URL-шляхом» і виключають
+рядок зі списку relative-path.
+
+## Залежності
+
+Зовнішні / стандартні модулі:
+
+- `node:fs/promises` → `readFile` — читання тестових файлів.
+- `node:path` → `basename`, `relative` — визначення імені файлу та шляху
+  відносно `cwd` для повідомлень.
+
+Внутрішні модулі (відносні шляхи у репозиторії):
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — стандартний
+  репортер перевірок (методи `pass`, `fail`, `getExitCode`).
+- `../../../scripts/lib/load-cursor-config.mjs` → `loadCursorIgnorePaths` —
+  читає `.n-cursor.json#ignore` для виключення шляхів.
+- `../../../scripts/utils/ast-scan-utils.mjs` → `parseProgramOrNull`,
+  `walkAstWithAncestors` — обгортка над oxc-parser і AST-обхід з
+  трекінгом ancestors (тут ancestors не використовуються — `[]`).
+- `../../../scripts/utils/walkDir.mjs` → `walkDir` — рекурсивний обхід
+  директорії із загальними skip-правилами та підтримкою `ignorePaths`.
+
+## Потік виконання / Використання
+
+Файл реалізує одну з перевірок з папки `npm/rules/test/js/`, що
+викликається через загальний механізм запуску правил (зазвичай
+`bun n-cursor rules` або еквівалентну команду). Загальний потік виклику
+`check(cwd)`:
+
+1. Створення `reporter` через `createCheckReporter()`.
+2. Завантаження `ignorePaths` з `.n-cursor.json`.
+3. `walkDir(cwd, ..., ignorePaths)` рекурсивно проходить дерево;
+   collector-callback відбирає лише файли, що задовольняють `isTestFile`.
+4. Для кожного тестового файлу:
+   - читається вміст;
+   - `parseProgramOrNull` намагається спарсити; при невдачі файл
+     мовчазно пропускається (`return []`);
+   - `walkAstWithAncestors` обходить AST і кожен `CallExpression`
+     перевіряється проти `FS_PATH_ARG_POSITIONS`;
+   - кожен виявлений relative-path-літерал перетворюється на запис
+     `offender` з `file`/`line`/`fn`/`path`/`argPos`.
+5. Якщо порушень немає — викликається `pass(...)` і
+   повертається `reporter.getExitCode()` (зазвичай `0`).
+6. Якщо є — кожне порушення емітиться через `fail(...)` із заздалегідь
+   сформатованим повідомленням; підсумковий exit code — `1`.
+
+Типове використання — як check-функція у конвеєрі правил `test.mdc`
+(адже повідомлення містять згадку `(test.mdc, no-relative-fs-path)`),
+де `cwd` — корінь монорепо. Файл є частиною підкаталогу
+`npm/rules/test/js/` (правила, що відповідають `test.mdc`).
+
+Edge-cases:
+
+- Невалідний JS → `parseProgramOrNull` повертає `null` → файл пропускається
+  без помилки.
+- Шлях обчислюється через `join`/`resolve` → пропускається (припускається
+  абсолютний).
+- Template literal зі вставленим виразом (`expressions.length > 0`) →
+  пропускається.
+- `existsSync` та інші sync-варіанти аналізуються нарівні з async.
+- Виклики через `fs.promises.X` — обробляються коректно, бо
+  `extractFsFunctionName` бере `callee.property.name` і не залежить від
+  глибини доступу.
+
+Інтеграція з CI: повертає ненульовий код у разі порушень → провалює
+відповідний крок CI; формат повідомлень містить `file:line: …`, що
+розпізнають IDE/CI-інтерфейси.

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

@@ -0,0 +1,152 @@
+# stryker_config.mjs
+
+## Огляд
+
+Модуль `stryker_config` — це концерн (check) правила `test` (відповідає правилу `test.mdc` із набору `.cursor/rules/`). Його роль — гарантувати, що в усіх JS-roots проєкту присутні canonical baseline-файли конфігурації для mutation testing (Stryker) і unit-test runner-а (Vitest), а також що тестові артефакти не потрапляють у git.
+
+Концерн виконує такі задачі:
+
+- Self-gating: якщо в `.n-cursor.json` правило `js-lint` не включене або явно вимкнене (`disable-rules`), концерн нічого не робить і тихо повертає успіх.
+- Визначення всіх JS-roots проєкту — кожен workspace із `package.json` у monorepo, або сам `cwd` у single-package режимі.
+- Для кожного JS-root перевіряє наявність файлу `stryker.config.mjs`; якщо його немає — копіює canonical baseline з пакета. Для roots із Vue 3 SFC-файлами (`<script setup>`) використовує спеціальний vue-варіант baseline і додатково копіює локальний Stryker-плагін `stryker-vue-macros-ignorer.mjs`.
+- Аналогічно для `vitest.config.js`.
+- Додає в кореневий `.gitignore` патерни `**/reports/stryker/` і `**/coverage/`, щоб тестові артефакти не комітилися.
+
+Файл є idempotent: повторні запуски на тому ж дереві не змінюють вже існуючі конфіги і не дублюють `.gitignore`-патерни.
+
+## Експорти / API
+
+Модуль експортує одну іменовану асинхронну функцію:
+
+- `check(cwd?: string): Promise<number>` — entry-point концерна. Повертає exit code: `0` (успіх або silently skipped), `1` (порушення).
+
+Інші функції модуля (`hasVueFiles`, `ensureBaselineFile`) є внутрішніми і не експортуються.
+
+## Функції
+
+### `hasVueFiles(jsRoot)`
+
+```js
+async function hasVueFiles(jsRoot)
+```
+
+- **Параметри:**
+  - `jsRoot` (`string`) — абсолютний шлях до workspace-каталогу (JS-root).
+- **Повертає:** `Promise<boolean>` — `true`, якщо в межах `<jsRoot>/src/**/*.vue` (виключаючи `node_modules`, `dist`, `reports`) знайдено хоча б один `.vue`-файл; інакше `false`.
+- **Поведінка:** використовує `node:fs/promises#glob` із patterns `VUE_GLOB_PATTERN = 'src/**/*.vue'` і ignore-списком `VUE_GLOB_IGNORE = ['**/node_modules/**', '**/dist/**', '**/reports/**']`. Як тільки знаходить перший збіг — миттєво повертає `true` через `return` у тілі циклу `for await…of`, тому повний обхід директорії не виконується.
+- **Side effects:** немає (read-only filesystem операція).
+
+### `ensureBaselineFile(reporter, cwd, baselinePath, target, label)`
+
+```js
+async function ensureBaselineFile(reporter, cwd, baselinePath, target, label)
+```
+
+- **Параметри:**
+  - `reporter` (`ReturnType<typeof createCheckReporter>`) — check-reporter для логування статусів pass/fail.
+  - `cwd` (`string`) — корінь проєкту, використовується для побудови relative-шляхів у повідомленнях.
+  - `baselinePath` (`string`) — абсолютний шлях до canonical baseline-файла у пакеті.
+  - `target` (`string`) — абсолютний шлях, куди копіювати baseline.
+  - `label` (`string`) — людиночитна мітка для логу (наприклад, `"stryker.config.mjs"` чи `"vitest.config.js"`).
+- **Повертає:** `Promise<void>`.
+- **Поведінка:** якщо `target` вже існує (`existsSync`) — логує `reporter.pass` із позначкою "існує" і виходить. Якщо ні — копіює `baselinePath` у `target` через `copyFile` і логує `reporter.pass` із поміткою "створено з canonical baseline ... (test.mdc)".
+- **Side effects:** запис файлу через `copyFile` (тільки якщо target був відсутній); запис у reporter.
+- **Idempotent:** так — повторний виклик на існуючому target не перезаписує файл.
+
+### `check(cwd = process.cwd())`
+
+```js
+export async function check(cwd = process.cwd())
+```
+
+- **Параметри:**
+  - `cwd` (`string`, опціональний) — корінь проєкту. За замовчуванням `process.cwd()` для CLI-сумісності.
+- **Повертає:** `Promise<number>` — exit code (`0` — OK або silently skipped, `1` — порушення).
+- **Side effects:**
+  - Читає `.n-cursor.json` через `readNCursorConfigLite`.
+  - Викликає `resolveAllJsRoots` для отримання списку JS-roots.
+  - Перевіряє існування canonical baseline-файлів у самому пакеті.
+  - Копіює `stryker.config.mjs` (canonical або vue-варіант), `vitest.config.js`, а для Vue-roots — `stryker-vue-macros-ignorer.mjs` у кожен JS-root, де відповідний файл відсутній.
+  - Додає у кореневий `.gitignore` патерни `**/reports/stryker/` і `**/coverage/`, якщо їх там немає, через `ensureGitignoreEntries` із коментарем-секцією `"Test artifacts: Stryker + coverage (test.mdc)"`.
+  - Накопичує статуси у reporter і повертає його exit code.
+
+## Залежності
+
+Стандартні модулі Node.js:
+
+- `node:fs` — `existsSync` (синхронна перевірка наявності файла).
+- `node:fs/promises` — `copyFile` (копіювання baseline у target), `glob` (пошук `.vue` файлів).
+- `node:path` — `dirname`, `join`, `relative` (побудова абсолютних і relative шляхів).
+- `node:url` — `fileURLToPath` (конвертація `import.meta.url` у POSIX-шлях для `dirname`).
+
+Внутрішні залежності пакета:
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика reporter-а з API `pass(msg)`, `fail(msg)`, `getExitCode()`.
+- `../../../scripts/lib/read-n-cursor-config-lite.mjs` → `readNCursorConfigLite` — читання `.n-cursor.json`, повертає об'єкт із полями `rules: string[]`, `disableRules: string[]`.
+- `../../../scripts/utils/ensure-gitignore-entries.mjs` → `ensureGitignoreEntries(cwd, entries, sectionLabel)` — idempotent додавання патернів у кореневий `.gitignore`. Повертає `{ added: string[] }`.
+- `../../../scripts/utils/resolve-js-root.mjs` → `resolveAllJsRoots(cwd)` — повертає масив абсолютних шляхів до всіх JS-roots: усі workspaces із `package.json` у monorepo, або `[cwd]` у single-package.
+
+Зовнішні дані-файли (canonical baseline у пакеті `@nitra/cursor`):
+
+- `data/stryker_config/stryker.config.baseline.mjs` — стандартний baseline Stryker (vitest-runner + perTest, mutate-патерни на Stryker defaults `src/**/*.{js,mjs,ts,jsx,tsx,cjs}`).
+- `data/stryker_config/stryker.config.vue.baseline.mjs` — vue-варіант baseline; реєструє локальний Ignore-плагін `vue-macros`, щоб Stryker не загортав `defineProps`/`defineEmits`/... у coverage-тернарник (інакше `@vue/compiler-sfc` падає при компіляції SFC).
+- `data/stryker_config/stryker-vue-macros-ignorer.mjs` — сам Stryker-плагін, який копіюється поруч із vue-варіантом baseline і реєструється з нього.
+- `data/vitest_config/vitest.config.baseline.js` — мінімальний baseline Vitest для runner-а.
+
+## Константи модуля
+
+- `HERE` — каталог самого `stryker_config.mjs` (`dirname(fileURLToPath(import.meta.url))`).
+- `STRYKER_BASELINE_PATH` — абсолютний шлях до стандартного `stryker.config.baseline.mjs`.
+- `STRYKER_VUE_BASELINE_PATH` — абсолютний шлях до vue-варіанта baseline.
+- `STRYKER_VUE_PLUGIN_PATH` — абсолютний шлях до `stryker-vue-macros-ignorer.mjs` у пакеті.
+- `STRYKER_VUE_PLUGIN_FILENAME = 'stryker-vue-macros-ignorer.mjs'` — ім'я файлу, під яким плагін копіюється у jsRoot.
+- `VITEST_BASELINE_PATH` — абсолютний шлях до canonical `vitest.config.baseline.js`.
+- `TEST_GITIGNORE_ENTRIES = ['**/reports/stryker/', '**/coverage/']` — патерни, які додаються в корений `.gitignore`. Подвійний-зірочка-префікс `**/` забезпечує покриття всіх workspaces у monorepo (єдиний root `.gitignore`).
+- `VUE_GLOB_PATTERN = 'src/**/*.vue'` — scope пошуку `.vue` файлів (відповідає Stryker mutate defaults для `src/`).
+- `VUE_GLOB_IGNORE = ['**/node_modules/**', '**/dist/**', '**/reports/**']` — пропускаються build-артефакти і чужі `node_modules`, щоб не активувати vue-варіант через transitive-deps.
+
+## Потік виконання / Використання
+
+Концерн запускається або через CLI пакета `@nitra/cursor` (як один із checks правила `test`), або імпортно з іншого скрипта.
+
+Алгоритм `check(cwd)` крок за кроком:
+
+1. Створює `reporter` через `createCheckReporter()`.
+2. Читає конфіг `.n-cursor.json` через `readNCursorConfigLite(cwd)`.
+3. **Self-gate:** якщо `js-lint` відсутнє в `config.rules`, або присутнє в `config.disableRules` — повертає `reporter.getExitCode()` без жодних повідомлень (silently skipped). Це навмисна поведінка, щоб не шуміти у проєктах без JS coverage tooling.
+4. Викликає `resolveAllJsRoots(cwd)`. Якщо повернувся порожній масив — це аномалія (`js-lint` enabled, але немає `package.json`); `reporter.fail` із повідомленням `'test: js-lint enabled, але кореневий package.json не знайдено (test.mdc)'` і повернення exit code.
+5. Перевіряє існування всіх чотирьох canonical baseline-файлів у пакеті (`STRYKER_BASELINE_PATH`, `STRYKER_VUE_BASELINE_PATH`, `STRYKER_VUE_PLUGIN_PATH`, `VITEST_BASELINE_PATH`). Якщо будь-якого з них немає — `reporter.fail` із вимогою перевстановити `@nitra/cursor` і early-return.
+6. Для кожного `jsRoot` із `jsRoots`:
+   - Визначає `isVueRoot = await hasVueFiles(jsRoot)`.
+   - Обирає `strykerBaseline = isVueRoot ? STRYKER_VUE_BASELINE_PATH : STRYKER_BASELINE_PATH`.
+   - Через `ensureBaselineFile` копіює `strykerBaseline` у `<jsRoot>/stryker.config.mjs` (якщо відсутній).
+   - Якщо `isVueRoot` — додатково через `ensureBaselineFile` копіює `STRYKER_VUE_PLUGIN_PATH` у `<jsRoot>/stryker-vue-macros-ignorer.mjs`.
+   - Через `ensureBaselineFile` копіює `VITEST_BASELINE_PATH` у `<jsRoot>/vitest.config.js`.
+7. Викликає `ensureGitignoreEntries(cwd, TEST_GITIGNORE_ENTRIES, 'Test artifacts: Stryker + coverage (test.mdc)')` — додає в кореневий `.gitignore` патерни `**/reports/stryker/` і `**/coverage/` (якщо їх там немає). Якщо щось дійсно було додане (`added.length > 0`) — `reporter.pass` із перелічуванням доданих патернів.
+8. Повертає `reporter.getExitCode()` — `0`, якщо жодного `fail` не було, інакше `1`.
+
+### Приклад використання
+
+```js
+import { check } from '@nitra/cursor/rules/test/js/stryker_config.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+Зазвичай безпосередній виклик не потрібен — концерн запускається диспетчером правила `test` (`test.mdc`) у складі команди `n-cursor fix` / `n-cursor check`.
+
+### Спостережувані ефекти у файловій системі
+
+Після успішного прогону в кожному JS-root з'являються:
+
+- `stryker.config.mjs` (стандартний або vue-варіант, залежно від наявності `.vue` у `src/`).
+- `vitest.config.js`.
+- `stryker-vue-macros-ignorer.mjs` — тільки для Vue-roots.
+
+У кореневому `.gitignore` гарантовано присутні:
+
+- `**/reports/stryker/`
+- `**/coverage/`
+
+Якщо файл уже існував — він не перезаписується, що дозволяє користувачу безпечно кастомізувати baseline під специфіку проєкту.