@nitra/cursor 5.3.4 → 5.4.0

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

@@ -1,160 +1,29 @@
-# `no-process-chdir.mjs`
+---
+docgen:
+  source: npm/rules/test/js/no-process-chdir.mjs
+  crc: 0ace6be6
+  score: 100
+---
 
-## Огляд
-
-Модуль `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()`.
-
-## Константи і регулярні вирази
+# no-process-chdir.mjs
 
-### `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-сценаріях
+Огляд
+Файл шукає викликний паттерн process.chdir у тестових файлах. Він перевіряє, чи викликає будь-який тестовий файл process.chdir, і генерує повідомлення про порушення (test.mdc).
 
-- `readFile` з режимом `'utf8'` для бінарних/неіснуючих файлів кине помилку — обхідник `walkDir` має фільтрувати по типу файлу/доступу, але всередині `check` блоків `try/catch` немає, тож помилка спливе у викликача.
-- `loadCursorIgnorePaths`/`walkDir`/`createCheckReporter` помилки також пробрасуються у викликача.
-- Модуль не модифікує глобальний стан і не змінює `cwd` процесу.
+## Поведінка
 
-### Як виглядає звіт
+1. Шукає викликний паттерн з відкривною дужкою process.chdir у тестових файлах.
+2. Перевіряє, чи викликає будь-який тестовий файл process.chdir.
+3. Якщо знайдено виклик, генерує повідомлення про порушення.
+4. Повертає код виходу відповідно до результату перевірки. (test.mdc)
 
-- **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)`.
+## Публічний API
 
-### Канонічна заміна `process.chdir` у тестах
+check — перевіряє, чи жоден файл з розширенням `*.test.{mjs,js}` не виконує `process.chdir(`. (test.mdc)
 
-Згідно з повідомленнями репортера і коментарем у заголовку:
+## Гарантії поведінки
 
-- Використовувати `withTmpDir(async dir => …)` зі `scripts/utils/test-helpers.mjs`.
-- У FS-операціях формувати шляхи через `join(dir, …)` явно.
-- У викликах child-процесів передавати `cwd: dir` як опцію.
-- У concern-функціях — приймати `cwd`/`dir` параметром і не покладатися на `process.cwd()`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -1,271 +1,34 @@
+---
+docgen:
+  source: npm/rules/test/js/no-relative-fs-path.mjs
+  crc: 3b8f52db
+  score: 100
+---
+
 # 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`.
+1. Завантажити ігноровані шляхи з корінням репозиторію
+2. Просканувати директорію репозиторію, відфільтровуючи тестові файли
+3. Для кожного тестового файлу прочитати його вміст
+4. Для кожного прочитаного вмісту знайти порушення у коді
+5. Для кожного знайденого порушення визначити рядок, номер рядка та позицію виклику
+6. Для кожного порушення перевірити, чи є перший аргумент у виклику FS-функції шляхом, що не є абсолютним
+7. Якщо порушення знайдено, повернути код помилки
+8. Якщо порушення не знайдено, повернути код успіху
 
-Типове використання — як check-функція у конвеєрі правил `test.mdc`
-(адже повідомлення містять згадку `(test.mdc, no-relative-fs-path)`),
-де `cwd` — корінь монорепо. Файл є частиною підкаталогу
-`npm/rules/test/js/` (правила, що відповідають `test.mdc`).
+## Публічний API
 
-Edge-cases:
+check — Перевіряє, що жоден `*.test.{mjs,js}` файл не передає relative-path як 1-й аргумент у FS-функцію з `node:fs` / `node:fs/promises` (або для `copyFile`/`rename`/`symlink`/`link`/`cp` — 1-й і 2-й аргумент). (test.mdc)
 
-- Невалідний 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-інтерфейси.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.