@nitra/cursor 3.22.0 → 3.23.0

package/rules/test/js/docs/vitest-config-pool-forks.md

@@ -0,0 +1,174 @@
+# vitest-config-pool-forks.mjs
+
+## Огляд
+
+Модуль реалізує статичну перевірку конфігураційного файлу `vitest.config.js` у корені репозиторію: цей файл, якщо він присутній, повинен містити налаштування `pool: 'forks'`. Перевірка є частиною групи правил `test` (див. `test.mdc`, секція «Заборона `process.chdir` у тестах») і виконує роль **defense-in-depth** проти race-conditions у `process.cwd()` між паралельними test-файлами.
+
+Контекст і мотивація:
+
+- У `vitest` за замовчуванням використовується `pool: 'threads'`, де всі workers ділять один процес (Node.js worker_threads). Усі такі workers мають **спільний** `process.cwd()`. Якщо хоч один тест (або стороння залежність всередині нього) викликає `process.chdir(...)`, це впливає на всі інші тести, що виконуються паралельно — типовий race-bug.
+- Простої заборони `process.chdir(` у тестах недостатньо: third-party код у залежностях може робити `chdir` всередині vitest worker'а непомітно.
+- `pool: 'forks'` ізолює кожен test-файл у власному child-процесі, тож `process.cwd()` стає локальним для тесту.
+
+Алгоритм перевірки — навмисно простий: substring/regex-пошук у сирому тексті `vitest.config.js`. AST-парсинг свідомо не використовується, бо конфіг може бути в довільному форматі експорту (ESM default, named export, CommonJS, factory-функція тощо), а сам ключ `pool: 'forks'` достатньо унікальний, щоб ідентифікувати його без парсера.
+
+Скіп-семантика: якщо `vitest.config.js` відсутній — це означає, що в репозиторії немає налаштованого vitest, і правило **пропускається** (pass, не fail). Якщо файл є — `pool: 'forks'` обов'язковий.
+
+## Експорти / API
+
+| Експорт | Тип                             | Призначення                                                                              |
+| ------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `check` | `async function` (named export) | Точка входу для виконання перевірки конфігу. Повертає exit-code сумісний з CI-runner'ом. |
+
+Модуль не має default export. Регулярний вираз `POOL_FORKS_RE` оголошений на рівні модуля, але **не** експортується — це внутрішня деталь реалізації.
+
+## Функції
+
+### `check(cwdParam?)`
+
+Асинхронна перевірка наявності `pool: 'forks'` у `vitest.config.js`.
+
+**Сигнатура:**
+
+```js
+export async function check(cwdParam = process.cwd()): Promise<number>
+```
+
+**Параметри:**
+
+| Ім'я       | Тип      | За замовчуванням | Опис                                                                                                                                                    |
+| ---------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwdParam` | `string` | `process.cwd()`  | Абсолютний шлях до кореня репозиторію, в якому шукається `vitest.config.js`. Призначений насамперед для тестів (можна підставити фікстурну директорію). |
+
+**Повертає:** `Promise<number>` — exit-code з `reporter.getExitCode()`:
+
+- `0` — успіх (`pool: 'forks'` знайдено) **або** skip (`vitest.config.js` відсутній);
+- `1` — помилка (файл є, але не містить `pool: 'forks'`).
+
+**Side effects:**
+
+- Створює локальний reporter через `createCheckReporter()`. Reporter виводить повідомлення `pass(...)` / `fail(...)` у консоль (формат залежить від реалізації reporter'а).
+- Синхронно перевіряє існування файлу через `existsSync` (звернення до файлової системи).
+- Якщо файл існує — асинхронно читає його повністю в пам'ять через `readFile(..., 'utf8')`.
+- **Не** модифікує файлову систему та **не** мутує глобальний стан.
+
+**Сценарії виконання:**
+
+1. **`vitest.config.js` не існує** → `pass('vitest.config.js відсутній — pool-перевірку пропущено')` → повертає `0`.
+2. **Файл існує, regex `/pool\s*:\s*['"]forks['"]/u` матчить** → `pass("vitest.config.js містить pool: 'forks' (test.mdc)")` → повертає `0`.
+3. **Файл існує, але regex не матчить** → `fail("vitest.config.js має містити pool: 'forks' — defense-in-depth для race у process.cwd() між паралельними test files (test.mdc)")` → повертає `1`.
+
+**Деталі регексу `POOL_FORKS_RE`:**
+
+```js
+const POOL_FORKS_RE = /pool\s*:\s*['"]forks['"]/u
+```
+
+Регекс:
+
+- `pool` — буквальний ключ;
+- `\s*:\s*` — двокрапка з довільним whitespace навколо;
+- `['"]forks['"]` — значення `forks` у одинарних або подвійних лапках;
+- Прапор `u` — Unicode-мода для коректної семантики escape-послідовностей.
+
+Регекс свідомо **не** перевіряє, що лапки парні (`'forks"` теоретично матчить). На практиці це не проблема, бо у валідному JS такі змішані лапки не зустрінуться (parse-error до того). Whitespace між токенами дозволений, але переноси рядка між `pool` і двокрапкою — лише ті, що покриваються `\s*`.
+
+## Залежності
+
+**Стандартна бібліотека Node.js:**
+
+| Модуль             | Імпортовані символи | Використання                                                    |
+| ------------------ | ------------------- | --------------------------------------------------------------- |
+| `node:fs`          | `existsSync`        | Синхронна перевірка існування `vitest.config.js`.               |
+| `node:fs/promises` | `readFile`          | Асинхронне читання вмісту конфігу у utf-8.                      |
+| `node:path`        | `join`              | Побудова шляху `${cwdParam}/vitest.config.js` крос-платформово. |
+
+**Внутрішні модулі проєкту:**
+
+| Шлях                                      | Імпортовані символи   | Використання                                                                                                                          |
+| ----------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `../../../scripts/lib/check-reporter.mjs` | `createCheckReporter` | Фабрика репортера з методами `pass(msg)`, `fail(msg)` та `getExitCode()`. Уніфікує вивід для всіх `check-*.mjs` правил у репозиторії. |
+
+**Зовнішніх npm-залежностей не має.**
+
+## Потік виконання / Використання
+
+### Типовий потік виконання `check()`
+
+1. Створюється reporter: `const reporter = createCheckReporter()`.
+2. Деструктуризація методів: `const { pass, fail } = reporter`.
+3. Будується шлях до конфігу: `configPath = join(cwdParam, 'vitest.config.js')`.
+4. Перевіряється існування файлу через `existsSync(configPath)`:
+   - Якщо файла **немає** — викликається `pass(...)` з повідомленням про skip, і функція негайно повертає `reporter.getExitCode()`.
+5. Якщо файл є — він читається повністю: `body = await readFile(configPath, 'utf8')`.
+6. Виконується `POOL_FORKS_RE.test(body)`:
+   - `true` → `pass(...)` з підтвердженням;
+   - `false` → `fail(...)` з поясненням і покликанням на `test.mdc`.
+7. Повертається `reporter.getExitCode()` — `0` або `1` залежно від того, чи був хоч один `fail`.
+
+### Використання як npm/CI-перевірки
+
+Модуль слідує конвенції rule-checker'ів проєкту (правила в `npm/rules/<group>/<lang>/check-*.mjs` або тематичних файлах). Запускається або:
+
+- безпосередньо `node` як CLI-входу (якщо обгорнуто скриптом-раннером);
+- з агрегованого runner'а, який послідовно викликає `check()` для кожного правила і збирає exit-коди.
+
+Приклад прямого виклику з іншого модуля:
+
+```js
+import { check } from './vitest-config-pool-forks.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+Приклад виклику для нестандартного кореня (наприклад, у тесті):
+
+```js
+import { check } from './vitest-config-pool-forks.mjs'
+
+const exitCode = await check('/tmp/fixture-repo-with-vitest')
+// exitCode === 0 якщо у фікстурі є vitest.config.js з pool: 'forks',
+// 1 якщо файл є без потрібного pool, 0 якщо файла нема взагалі
+```
+
+### Приклад валідного `vitest.config.js`
+
+```js
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    pool: 'forks'
+    // ... інші опції
+  }
+})
+```
+
+### Приклад невалідного `vitest.config.js`
+
+```js
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    // pool не вказано → effective pool: 'threads' (default vitest) → race на process.cwd()
+  }
+})
+```
+
+або
+
+```js
+export default {
+  test: { pool: 'threads' } // явно threads — те саме, що default
+}
+```
+
+Обидва варіанти призведуть до `fail` і exit-code `1`.
+
+### Межі застосовності
+
+- Перевірка **не** валідовує JS-синтаксис конфігу. Якщо `vitest.config.js` синтаксично битий, але містить рядок `pool: 'forks'` у коментарі чи рядковому літералі, перевірка пройде. Це усвідомлений trade-off на користь простоти — реальні false-positive у проєкті малоймовірні.
+- Перевірка дивиться **тільки** на `vitest.config.js` у корені, переданому через `cwdParam`. Альтернативні імена (`vitest.config.ts`, `vitest.config.mjs`, `vite.config.js` зі вбудованою `test`-секцією) **не** обробляються — це окремі правила, якщо знадобляться.
+- Skip при відсутності файлу — поведінка дизайну: правило не «обов'язково додай vitest», а «якщо ти вже маєш vitest, налаштуй pool правильно».

package/rules/text/docs/fix.md

@@ -0,0 +1,118 @@
+# fix.mjs — entry-point правила `text`
+
+## Огляд
+
+Файл `npm/rules/text/fix.mjs` — це **подвійний entry-point** для правила `text` із пакета `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку імпортує зовнішня CLI-оркестрація (`npx @nitra/cursor fix text` або агрегований прогон усіх правил) для запуску стандартного fix-pipeline саме цього правила.
+2. **Standalone mode** — якщо модуль виконується безпосередньо (`bun npm/rules/text/fix.mjs`), він самостійно піднімає повний CLI-оркестратор (`runRuleCli`) із завантаженням конфігурації, whitelist-фільтрацією та підсумковим виводом, повертаючи коректний `exit-code` для CI/IDE.
+
+Сам файл не містить бізнес-логіки правила: він є **тонким адаптером** над двома утилітами (`runStandardRule` та `runRuleCli`) і покладається на конвенцію `import.meta.dirname` — тобто на те, що сусідні теки `lint/`, `policy/`, `js/` та файл `text.mdc` дають усю фактичну реалізацію (applies → JS-concerns → policy → mdc-refs).
+
+Шлях фізично розміщений у директорії конкретного правила `text`, але код **повністю однаковий** для всіх правил репозиторію — `import.meta.dirname` робить його контекстно-залежним без жодних хардкодів `id` правила.
+
+## Експорти / API
+
+| Експорт | Тип                                             | Призначення                                                                                                                        |
+| ------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function (ctx?: RuleContext): Promise<number>` | Іменований експорт для library mode. Викликається зовнішньою оркестрацією, повертає exit-code правила (`0` — OK, `1` — порушення). |
+
+Файл **не має** default-експорту. Усі інші конструкції модуля (`if (isRunAsCli(...))`) виконуються при імпорті як side-effect, але активуються лише коли модуль є entry-point процесу — для звичайного `import` standalone-блок не спрацьовує.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура**: `function run(ctx?: RuleContext): Promise<number>`
+- **Параметри**:
+  - `ctx` _(необов'язковий)_ — об'єкт контексту прогону типу `RuleContext`, описаний у JSDoc-import у `../../scripts/lib/run-standard-rule.mjs`. Передається оркестратором і зазвичай містить кешовані результати walk'у файлової системи (`walkCache`) та інші спільні для пакетного прогону структури, щоб уникнути повторного сканування репозиторію кожним правилом.
+- **Повертає**: `Promise<number>` — exit-code, який повертає `runStandardRule`. За конвенцією репозиторію:
+  - `0` — порушень не знайдено (правило пройшло);
+  - `1` — знайдено хоча б одне порушення (правило впало).
+- **Side effects**: усі побічні ефекти делеговані в `runStandardRule`. Це включає:
+  - читання файлів проєкту (без модифікацій);
+  - виконання сабмодулів `applies`, `JS-concerns`, `policy`, `mdc-refs` із сусідніх тек;
+  - друк діагностики у stdout/stderr (залежить від реалізації стандартного pipeline та `RuleContext`).
+- **Передача `import.meta.dirname`**: ключова деталь — як перший аргумент передається **директорія цього файлу** (`npm/rules/text/`). Саме за нею `runStandardRule` ідентифікує правило (`id = basename(dirname)`) та знаходить його артефакти (mdc, applies, policy).
+
+### Standalone-блок (top-level, не функція)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Призначення**: дозволяє запускати модуль як автономний скрипт — `bun npm/rules/text/fix.mjs`. У такому режимі він має дати **повний еквівалент** виклику `npx @nitra/cursor fix text`, включно з:
+  - завантаженням конфігурації проєкту;
+  - застосуванням whitelist (відсіюванням файлів, що не підпадають під правило);
+  - друком підсумку (summary) виконання.
+- **Параметри**: немає (CLI-аргументи парсяться всередині `runRuleCli`).
+- **Повертає / завершує**: `process.exit(n)` із `n`, який повернув `runRuleCli`. Це необхідно, щоб CI або IDE-інтеграція могли визначати успіх/невдачу за стандартним exit-code'ом.
+- **Side effects**:
+  - читання конфігурації пакета та проєкту;
+  - читання й аналіз файлів проєкту;
+  - вивід summary у stdout/stderr;
+  - **завершення процесу** через `process.exit` (це окремо помічено `eslint-disable` коментарем `n/no-process-exit, unicorn/no-process-exit`, оскільки правила лінтера за замовчуванням забороняють `process.exit` поза entry-point файлами).
+- **Перевірка `isRunAsCli`**: функція приймає `import.meta.url` і повертає `true` лише якщо саме цей файл — entry-point Node/Bun-процесу. Це класичний ідіоматичний еквівалент `if __name__ == "__main__"` із Python для ESM.
+
+## Залежності
+
+### Внутрішні (relative)
+
+| Імпорт            | Модуль                                    | Що дає                                                                                                                                              |
+| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: чи запущений модуль як CLI entry-point (порівняння `import.meta.url` з `process.argv[1]`).                                                |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Повний CLI-оркестратор одного правила: завантаження конфігурації, whitelist, виклик `run`, друк summary, повернення exit-code.                      |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний fix-pipeline правила: послідовно виконує етапи **applies → JS-concerns → policy → mdc-refs**. Знаходить артефакти за `dirname` правила. |
+
+Усі три імпорти — це shared-утиліти рівня `scripts/lib/`, спроєктовані саме для подвійного entry-point'у правил. Жодних зовнішніх npm-залежностей файл не імпортує напряму.
+
+### Неявні (контекст виконання)
+
+- **`import.meta.dirname`** — стандартне поле ESM (Node ≥ 20 / Bun): абсолютний шлях до директорії, що містить модуль. Використовується **двічі** і є ключовим для ідентифікації правила.
+- **`import.meta.url`** — стандартне поле ESM: URL-форма шляху до модуля; передається в `isRunAsCli` для порівняння з `process.argv[1]`.
+- **`process.exit`** — глобальний Node/Bun API; викликається лише у standalone-режимі.
+- **Сусідні теки правила** (`./lint`, `./policy`, `./js`, `./text.mdc`, `./meta.json`) — фактичні артефакти, які `runStandardRule` знаходить через переданий `import.meta.dirname`. Файл `fix.mjs` сам їх не імпортує, але pipeline без них не запрацює.
+
+## Потік виконання / Використання
+
+### Сценарій 1 — Library mode (typical)
+
+1. Зовнішній код (наприклад, агрегатор `npx @nitra/cursor fix`) робить `await import('npm/rules/text/fix.mjs')`.
+2. Перевірка `isRunAsCli(import.meta.url)` повертає `false` (бо entry-point процесу — інший файл), standalone-блок **не виконується**.
+3. Агрегатор викликає експортовану `run(ctx)`, передаючи спільний `ctx` (наприклад, з прогрітим `walkCache`).
+4. `run` делегує виклик у `runStandardRule(import.meta.dirname, ctx)`.
+5. `runStandardRule` ідентифікує правило за `basename(dirname)` = `text`, послідовно виконує етапи pipeline (applies → JS-concerns → policy → mdc-refs), читає сусідні артефакти, повертає exit-code.
+6. Агрегатор отримує `Promise<number>` і інтегрує його в загальний підсумок (наприклад, агрегує максимум по всіх правилах).
+
+### Сценарій 2 — Standalone mode
+
+1. Розробник або CI виконує `bun npm/rules/text/fix.mjs` (або через npm-script).
+2. Імпорти `isRunAsCli`, `runRuleCli`, `runStandardRule` зчитуються.
+3. Експорт `run` стає доступним, але **ніким не використовується** в цьому сценарії.
+4. `isRunAsCli(import.meta.url)` повертає `true`.
+5. Виконується `await runRuleCli(import.meta.dirname)` — повний CLI-цикл: парсинг аргументів, завантаження конфігурації, whitelist, виклик внутрішнього еквівалента `run`, друк summary.
+6. Результат передається в `process.exit(...)` — процес завершується із належним exit-code'ом для CI.
+
+### Чому саме така архітектура
+
+- **Однаковий код для всіх правил** — `fix.mjs` кожного правила в `npm/rules/<id>/` ідентичний; диференціація — виключно через директорію (`import.meta.dirname`) та артефакти в ній. Це усуває дублювання логіки entry-point'у та робить додавання нового правила механічним (скопіювати теку, поправити mdc/policy).
+- **Подвійна роль (library + standalone)** — дозволяє з одного файлу і дебажити правило локально (швидкий feedback `bun rules/text/fix.mjs`), і інтегрувати його у пакетний прогон агрегатора без зміни вихідного коду.
+- **`process.exit` лише в standalone-гілці** — у library-режимі повернення exit-code'у через `Promise<number>` дає агрегатору можливість зібрати всі результати й завершитися одним викликом, не давши окремому правилу обірвати процес передчасно.
+
+### Rebuild Test (інваріанти, які має зберегти будь-яка перебудова файлу)
+
+- Файл **має експортувати** функцію `run(ctx)`, що повертає `Promise<number>`.
+- `run` **має** передавати `import.meta.dirname` як перший аргумент у `runStandardRule` (без хардкоду шляху або `id`).
+- `run` **не повинна** викликати `process.exit` — лише повертати exit-code.
+- Standalone-гілка **має** бути захищена `isRunAsCli(import.meta.url)`, щоб не спрацьовувати при `import` із зовнішнього коду.
+- Standalone-гілка **має** використовувати `runRuleCli` (а не `runStandardRule` напряму), бо саме `runRuleCli` додає config-loading, whitelist та summary.
+- Standalone-гілка **має** завершуватися `process.exit(await runRuleCli(import.meta.dirname))` із поверненням коректного exit-code'у — інакше CI не зможе зловити порушення.
+- Файл **не повинен** містити власної логіки правила: вся специфіка `text` живе в сусідніх теках (`lint/`, `policy/`, `js/`) та `text.mdc`.

package/rules/text/js/docs/forbidden-prettier.md

@@ -0,0 +1,143 @@
+# forbidden-prettier.mjs
+
+## Огляд
+
+Модуль `forbidden-prettier.mjs` — це FS-перевірка (suspect FS-check) з категорії правил `text`, яка стежить за тим, щоб у корені проєкту не з'являвся жоден файл, який Prettier автоматично підхоплює як конфігурацію чи ignore-список.
+
+Правило `text.mdc` (див. однойменну категорію `.cursor/rules/`) повністю забороняє використання Prettier, пакета `@nitra/prettier-config` і будь-яких прив'язок до Prettier у проєкті — заміна Prettier у репозиторії — це форматер `oxfmt`. Перевірка package.json-сторони (поля `scripts`, `dependencies`, `devDependencies`) виконується Rego-полісі `text.package_json`, а ця перевірка доповнює її і ловить саме FS-сторону: фізично присутні у корені файли конфігів і `.prettierignore`, які runner Prettier зчитує автоматично.
+
+Список заборонених імен синхронізовано з документацією Prettier 3.x (https://prettier.io/docs/configuration). Якщо Prettier додасть новий формат конфігу — у константу треба додати відповідний рядок.
+
+Файл є ES-модулем (`.mjs`). Експортує єдину функцію `check`, яка повертає exit code (0 — успіх, 1 — провал), що дозволяє запустити її з CLI або іншого скрипта-агрегатора перевірок.
+
+## Експорти / API
+
+| Експорт       | Тип                         | Призначення                                                                                                     |
+| ------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `check(cwd?)` | `function(string=): number` | Іменований експорт. Запускає перевірку відсутності Prettier-артефактів у вказаному корені й повертає exit code. |
+
+Інших публічних експортів модуль не має. Константа `FORBIDDEN_PRETTIER_FILES` оголошена локально у модулі і назовні не експортується.
+
+## Функції
+
+### `check(cwd = process.cwd())`
+
+Сигнатура:
+
+```js
+export function check(cwd = process.cwd()): number
+```
+
+Параметри:
+
+- `cwd` — `string`, опційний. Абсолютний шлях до кореня репозиторію (або іншої теки), в якому потрібно шукати Prettier-артефакти. Якщо не передано, використовується поточна робоча тека процесу (`process.cwd()`).
+
+Повертає:
+
+- `number` — exit code, отриманий від `reporter.getExitCode()`. За контрактом `createCheckReporter`:
+  - `0` — у корені не знайдено жодного забороненого Prettier-файлу;
+  - `1` — знайдено хоча б один заборонений файл; кожен факт повідомлено окремим `fail(...)`-рядком.
+
+Side effects:
+
+- Виводить повідомлення про статус перевірки через репортер (`pass` / `fail`). Конкретний канал виводу й формат рядків визначає реалізація `createCheckReporter()` (як правило — `stdout`/`stderr` з префіксами).
+- Звертається до файлової системи: для кожного імені зі списку викликає `existsSync(join(cwd, file))`. Жодних читань вмісту файлів, жодних записів чи видалень не виконується — перевірка лише на факт існування шляху.
+- Не змінює змінні оточення, не модифікує `process` (крім читання `process.cwd()` як дефолтного значення параметра).
+
+Алгоритм:
+
+1. Створити репортер через `createCheckReporter()`; з нього взяти методи `pass` і `fail`.
+2. Ініціалізувати локальний прапорець `anyFound = false`.
+3. Для кожного імені `file` зі списку `FORBIDDEN_PRETTIER_FILES`:
+   - обчислити повний шлях `join(cwd, file)`;
+   - якщо `existsSync(...)` повертає `true` — викликати `fail` з повідомленням виду `"<file> заборонено — Prettier не використовуємо, перейди на oxfmt (text.mdc)"` і виставити `anyFound = true`. Цикл не переривається — перевіряємо всі імена, щоб репорт містив повний список знайдених порушень за один прогін.
+4. Якщо після циклу `anyFound === false` — викликати `pass('Prettier-конфігів і .prettierignore немає в корені')` (єдиний підсумковий success-рядок).
+5. Повернути `reporter.getExitCode()`.
+
+## Залежності
+
+### Зовнішні (стандартна бібліотека Node.js)
+
+- `node:fs` — імпортується `existsSync` для синхронної перевірки існування шляху.
+- `node:path` — імпортується `join` для безпечного склеювання `cwd` з іменем файлу (працює коректно на всіх ОС).
+
+### Внутрішні
+
+- `../../../scripts/lib/check-reporter.mjs` — модуль із фабрикою `createCheckReporter()`. Фабрика повертає об'єкт із принаймні полями:
+  - `pass(message: string): void` — повідомити про успіх;
+  - `fail(message: string): void` — повідомити про порушення;
+  - `getExitCode(): number` — підсумковий exit code (зазвичай 0 при відсутності `fail` і 1 — якщо `fail` був хоча б раз).
+
+  Контракт репортера спільний для всіх FS-перевірок у `npm/rules/`, тож формат повідомлень уніфіковано.
+
+### Дотичні правила
+
+- `text.mdc` (`.cursor/rules/n-text.mdc` у проєкті) — джерело заборони Prettier. У повідомленнях `fail` явно посилається користувача на цей файл.
+- Rego-полісі `text.package_json` — додаткова перевірка package.json-сторони (доповнює дану FS-перевірку, але не викликається з цього модуля).
+
+## Потік виконання / Використання
+
+Модуль розрахований на виклик із CLI-обгортки чи з агрегатора перевірок, який послідовно проганяє правила з категорії `text`.
+
+Типовий сценарій використання:
+
+1. Скрипт-агрегатор (або CLI на кшталт `n-cursor check` чи окремий runner) імпортує функцію:
+
+   ```js
+   import { check } from './npm/rules/text/js/forbidden-prettier.mjs'
+   ```
+
+2. Викликає `check()` без аргументів (тоді корінь = `process.cwd()` процесу-агрегатора) або з явним коренем, наприклад при перевірці іншого workspace:
+
+   ```js
+   const exitCode = check('/abs/path/to/repo/root')
+   ```
+
+3. Отриманий `exitCode` агрегатор підсумовує з іншими перевірками; на CI ненульовий код завалює job.
+
+Локальний запуск як standalone-скрипта (за бажанням, оскільки модуль не має блоку `if (import.meta.url === ...)`) можна організувати тонкою обгорткою або запустити `check` через `node -e`:
+
+```sh
+node --input-type=module -e "import('./npm/rules/text/js/forbidden-prettier.mjs').then(m => process.exit(m.check()))"
+```
+
+Семантика результату:
+
+- `0` — у корені немає жодного з 18 заборонених імен (різні формати `.prettierrc.*`, `prettier.config.*`, `.prettierignore`). Користувач бачить один success-рядок.
+- `1` — знайдено N ≥ 1 файлів. Користувач бачить N окремих fail-рядків (по одному на кожен знайдений артефакт) і нульових success-рядків. Це дозволяє за одним прогоном CI-перевірки одразу побачити повний список того, що треба прибрати.
+
+Чого функція **не** робить (важливо для контексту):
+
+- не зчитує вмісту конфігів — лише факт їх присутності;
+- не намагається автоматично видаляти знайдені файли (це задача користувача — мігрувати на `oxfmt` і прибрати артефакти);
+- не перевіряє вкладені теки/workspaces — рекурсивного обходу немає, контролюється лише корінь `cwd`;
+- не реагує на наявність полів `prettier` у `package.json` — це інша зона відповідальності (Rego `text.package_json`).
+
+## Константи
+
+### `FORBIDDEN_PRETTIER_FILES`
+
+Локальний `const`-масив рядків — повний перелік імен, які Prettier 3.x шукає у корені проєкту. На момент створення модуля містить такі імена (у порядку оригіналу):
+
+- `.prettierignore`
+- `.prettierrc`
+- `.prettierrc.json`
+- `.prettierrc.jsonc`
+- `.prettierrc.json5`
+- `.prettierrc.yaml`
+- `.prettierrc.yml`
+- `.prettierrc.toml`
+- `.prettierrc.js`
+- `.prettierrc.cjs`
+- `.prettierrc.mjs`
+- `.prettierrc.ts`
+- `.prettierrc.cts`
+- `.prettierrc.mts`
+- `prettier.config.js`
+- `prettier.config.cjs`
+- `prettier.config.mjs`
+- `prettier.config.ts`
+- `prettier.config.cts`
+- `prettier.config.mts`
+
+Поясняюча нотатка з коментаря у файлі: «Список синхронізовано з конфіг-форматами Prettier 3.x (https://prettier.io/docs/configuration). Якщо Prettier додасть новий формат — додай рядок.» — підтримка списку ручна; при апгрейді Prettier (як майбутньої версії) перевір документацію і за потреби розшир константу.