@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,168 @@
+# cargo_mutants_config.mjs
+
+## Огляд
+
+Модуль реалізує концерн `cargo_mutants_config` правила `tauri.mdc`. Його завдання — гарантувати, що для кожного workspace-пакета монорепо, у якому існує `<workspace>/src-tauri/Cargo.toml`, поряд лежить канонічний Tauri-специфічний конфіг `cargo-mutants` за шляхом `<workspace>/src-tauri/.cargo/mutants.toml`. Конфіг забороняє повторну збірку бінарників (`--bins`) і doc-tests (`--doc`) під кожного мутанта (це перетворює секунди на хвилини) і виключає з mutation-testing platform-bridge файли, які тестуються smoke/e2e, а не unit-тестами.
+
+Семантика виключень фіксована для всіх Tauri-проєктів:
+
+- `src/main.rs` — binary shell entrypoint (smoke/e2e, не mutation unit);
+- `src/lib.rs` — Tauri `pub fn run`, runtime entrypoint, який запускає увесь app shell (один мутант там тримає увесь Tauri runtime і ділить sandbox-fail з `src/main.rs`);
+- `src/**/{android,ios,mobile}.rs` — mobile plugin bridge / platform glue;
+- `src/**/{macos,windows,linux,desktop}.rs` — desktop platform bridge / OS integration glue.
+
+Файл побудований за патерном concern-checker у репо: експортує одну функцію `check(cwd)`, яка:
+
+- self-gates (тихо пропускає, якщо у монорепо немає жодного `src-tauri/Cargo.toml` — нейтральний baseline за потреби створить test rule);
+- ідемпотентна — створює файл лише за відсутності, інакше дописує лише ті top-level ключі, яких бракує, не змінюючи існуючих значень користувача;
+- репортує результат через спільний `createCheckReporter` і повертає process exit code (`0` — OK або skip, `1` — порушення).
+
+## Експорти / API
+
+| Експорт       | Тип              | Опис                                                                                                                                                     |
+| ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check(cwd?)` | `async function` | Єдиний публічний експорт. Запускає концерн над переданим або поточним коренем проєкту. Повертає `Promise<number>` — exit code, сумісний з CLI-обгорткою. |
+
+Внутрішні (не експортуються) допоміжні функції: `findSrcTauriDirs`, `detectMissingKeys`, `buildAppended`, `buildBaseline`, `processOneSrcTauri`.
+
+Внутрішні константи модульного рівня:
+
+- `TAURI_BASELINE_HEADER` — рядковий заголовок (коментар) для нового файла з посиланням на `tauri.mdc` і поясненням, чому виключаються `--bins` та `--doc`.
+- `TAURI_KEY_SNIPPETS` — заморожений (`Object.freeze`) словник `{ ключ → канонічний TOML-сніпет з блоковими коментарями }` для двох канонічних top-level ключів: `additional_cargo_test_args` і `exclude_globs`.
+- `TAURI_CANONICAL_KEYS` — заморожений масив ключів `TAURI_KEY_SNIPPETS` зі збереженим порядком (`Object.keys(TAURI_KEY_SNIPPETS)`); використовується для впорядкованого детектування відсутніх ключів і генерації baseline.
+
+Канонічний вміст сніпетів:
+
+- `additional_cargo_test_args = ["--lib", "--tests"]` — `cargo mutants` під час прогону тестів обмежується library + integration tests, без бінарників і doc-tests.
+- `exclude_globs = [...]` — список glob-патернів, які виключаються з mutation-testing (див. розділ «Огляд»).
+
+## Функції
+
+### `check(cwd = process.cwd())`
+
+- **Сигнатура:** `async function check(cwd?: string): Promise<number>`.
+- **Параметри:**
+  - `cwd` _(string, опційний, default `process.cwd()`)_ — абсолютний шлях до кореня монорепо. Дефолт забезпечує CLI-сумісність (виклик без аргументів з-під будь-якого `bin`).
+- **Повертає:** `Promise<number>` — exit code від `reporter.getExitCode()` (`0` — успіх або self-skip, `1` — є зафіксовані `reporter.fail(...)`).
+- **Алгоритм:**
+  1. Створює інстанс репортера через `createCheckReporter()`.
+  2. Знаходить усі `src-tauri/` директорії через `findSrcTauriDirs(cwd)`.
+  3. Якщо їх немає — повертає `reporter.getExitCode()` без жодних змін (self-gate / silent skip).
+  4. Інакше — послідовно обробляє кожен каталог через `processOneSrcTauri(dir, cwd, reporter)`.
+  5. Повертає підсумковий exit code від репортера.
+- **Side effects:** може створювати теку `<src-tauri>/.cargo/` і записувати в `<src-tauri>/.cargo/mutants.toml`; пише повідомлення (`pass`/`fail`) у спільний репортер.
+
+### `findSrcTauriDirs(cwd)`
+
+- **Сигнатура:** `async function findSrcTauriDirs(cwd: string): Promise<string[]>`.
+- **Параметри:** `cwd` — корінь проєкту.
+- **Повертає:** масив абсолютних шляхів до `src-tauri/` каталогів, які мають власний `Cargo.toml`.
+- **Алгоритм:**
+  1. Запитує всі workspace-пакети через `getMonorepoPackageRootDirs(cwd)` (включно з самим коренем).
+  2. Для кожного `root` перевіряє наявність `join(cwd, root, 'src-tauri', 'Cargo.toml')` через `existsSync`.
+  3. Якщо файл існує — додає `join(cwd, root, 'src-tauri')` до результату.
+- **Side effects:** немає (read-only через `existsSync` і виклик util-функції монорепо-обходу).
+
+### `detectMissingKeys(targetPath)`
+
+- **Сигнатура:** `async function detectMissingKeys(targetPath: string): Promise<string[]>`.
+- **Параметри:** `targetPath` — абсолютний шлях до існуючого `.cargo/mutants.toml`.
+- **Повертає:** масив канонічних ключів (з `TAURI_CANONICAL_KEYS`), яких немає на top-level у вже існуючому TOML, зі збереженим порядком.
+- **Алгоритм:**
+  1. Читає файл як UTF-8.
+  2. Парсить його через `parseToml` зі `smol-toml`.
+  3. Фільтрує `TAURI_CANONICAL_KEYS`, лишаючи лише ті, яких немає в розпарсеному об'єкті (`!(k in parsed)`).
+- **Side effects:** read-only (читання файла).
+
+### `buildAppended(existing, missingKeys)`
+
+- **Сигнатура:** `function buildAppended(existing: string, missingKeys: string[]): string`.
+- **Параметри:**
+  - `existing` — поточний текстовий вміст `.cargo/mutants.toml`;
+  - `missingKeys` — ключі, які треба дописати.
+- **Повертає:** новий вміст файла (`string`) — оригінал + хвостовий блок з коментарем-маркером `# Tauri canonical cargo-mutants additions (tauri.mdc)` і конкатенованими TOML-сніпетами для всіх `missingKeys` у порядку, наданому викликачем.
+- **Алгоритм:**
+  1. Нормалізує хвіст оригіналу: гарантує trailing `\n`.
+  2. Будує блок: порожній рядок-розділювач, заголовок-коментар, далі для кожного ключа з `missingKeys` — відповідний сніпет з `TAURI_KEY_SNIPPETS[key]`.
+  3. Конкатенує хвіст з блоком.
+- **Side effects:** немає (чиста функція).
+
+### `buildBaseline()`
+
+- **Сигнатура:** `function buildBaseline(): string`.
+- **Параметри:** немає.
+- **Повертає:** повний текст канонічного `.cargo/mutants.toml` — `TAURI_BASELINE_HEADER`, після нього сніпети всіх `TAURI_CANONICAL_KEYS` (`additional_cargo_test_args`, `exclude_globs`), з'єднані через `'\n'`.
+- **Side effects:** немає (чиста функція).
+
+### `processOneSrcTauri(srcTauriDir, cwd, reporter)`
+
+- **Сигнатура:** `async function processOneSrcTauri(srcTauriDir: string, cwd: string, reporter: { pass(msg): void, fail(msg): void }): Promise<void>`.
+- **Параметри:**
+  - `srcTauriDir` — абсолютний шлях до `src-tauri/` каталогу;
+  - `cwd` — корінь проєкту (потрібен для красивого relative-шляху в репорт-повідомленнях);
+  - `reporter` — інстанс репортера з методами `pass(msg)`/`fail(msg)`.
+- **Повертає:** `Promise<void>`.
+- **Алгоритм / гілки:**
+  1. Формує `target = join(srcTauriDir, '.cargo', 'mutants.toml')` і `rel = relative(cwd, target)`.
+  2. **Файла немає:** створює директорію `<src-tauri>/.cargo/` (`mkdir … { recursive: true }`), записує повний `buildBaseline()`, репортує `pass`: `.cargo/mutants.toml створено з Tauri canonical baseline (<rel>) (tauri.mdc)`; вихід.
+  3. **Файл є:** викликає `detectMissingKeys(target)`.
+     - Якщо `missing.length === 0` — репортує `pass`: `.cargo/mutants.toml: manual cargo-mutants config preserved (<rel>)`; вихід.
+     - Інакше — читає поточний вміст, обчислює новий через `buildAppended(existing, missing)`, записує файл, репортує `pass`: `.cargo/mutants.toml: додано відсутні Tauri-ключі [<key1>, <key2>] (<rel>) (tauri.mdc)`.
+- **Side effects:** створює директорії, записує/перезаписує файл `mutants.toml`, додає `pass`-повідомлення в репортер. У поточній реалізації функція не викликає `reporter.fail` — концерн є строго ідемпотентно-fix-овим (немає сценарію «порушення»).
+
+## Залежності
+
+### Node.js core (вбудовані)
+
+- `node:fs` — `existsSync` для check'у наявності `Cargo.toml` / `mutants.toml`;
+- `node:fs/promises` — `mkdir`, `readFile`, `writeFile` (промісована I/O для запису конфіга);
+- `node:path` — `dirname`, `join`, `relative` (побудова цільового шляху та relative-вивід у репорт).
+
+### External
+
+- `smol-toml` (іменований імпорт `parse as parseToml`) — лояльний TOML-парсер для детекції наявних top-level ключів у існуючому `mutants.toml`.
+
+### Internal (workspace utilities)
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter()` — спільний reporter pass/fail/exit-code для concern-checker'ів.
+- `../../../scripts/lib/workspaces.mjs` → `getMonorepoPackageRootDirs(cwd)` — повертає корінь + усі workspace-пакети монорепо.
+
+## Потік виконання / Використання
+
+### Типовий виклик з CLI / rule-runner
+
+Модуль — частина правила `tauri.mdc`, його `check`-функцію викликає rule-runner (як один з концернів). Приблизний псевдо-виклик:
+
+```js
+import { check } from './cargo_mutants_config.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+### Послідовність дій усередині одного запуску
+
+1. `check(cwd)` створює репортер.
+2. `findSrcTauriDirs(cwd)` обходить пакети монорепо й збирає всі `src-tauri/` з `Cargo.toml`.
+3. Якщо пусто — `return reporter.getExitCode()` (тихий skip, нічого не пишемо).
+4. Для кожного знайденого `src-tauri/`:
+   - якщо `.cargo/mutants.toml` відсутній → `mkdir -p` + запис canonical baseline;
+   - якщо файл існує + усі канонічні ключі присутні → нічого не змінює, репорт `manual cargo-mutants config preserved`;
+   - якщо файл існує, але деякі канонічні ключі відсутні → дописує лише відсутні ключі окремим блоком у кінці файла.
+5. Повертає підсумковий exit code.
+
+### Гарантії
+
+- **Self-gating:** концерн нічого не робить, якщо в репо немає Tauri-пакетів — це не помилка.
+- **Ідемпотентність:** повторні прогони на чистому/повному canonical файлі не змінюють вмісту.
+- **Non-destructive:** ані наявні значення `additional_cargo_test_args`/`exclude_globs`, ані сторонні top-level ключі користувача не перезаписуються — додавання відсутніх ключів відбувається окремим append-блоком в кінці файла з коментарем-маркером.
+- **Read-once-write-once на один каталог:** при append-сценарії файл читається повторно (один раз для парсу через `detectMissingKeys`, ще раз як текст для конкатенації), що гарантує запис рівно одного фінального вмісту.
+
+### Точки розширення
+
+- Додати новий канонічний top-level ключ: додати пару `key → snippet\n` у `TAURI_KEY_SNIPPETS`; `TAURI_CANONICAL_KEYS` та логіка `buildBaseline`/`buildAppended`/`detectMissingKeys` підхоплять його автоматично, зі збереженим порядком вставки.
+- Змінити список platform-bridge файлів: відредагувати `exclude_globs` сніпет у `TAURI_KEY_SNIPPETS`.
+
+### Rebuild Test
+
+Файл містить достатню інформацію, щоб реконструювати правило з нуля: визначені вхідні точки виявлення Tauri-пакетів, перелік канонічних top-level ключів конфіга, форма заголовка/коментарів у згенерованому файлі, точні повідомлення репортера, гарантії ідемпотентності та non-destructive append, повний контракт експортованої функції `check(cwd)` (включно з дефолтом і поверненим типом).

package/rules/tauri/js/docs/tooling.md

@@ -0,0 +1,228 @@
+# tooling.mjs — перевірка інструментарію Tauri
+
+## Огляд
+
+Модуль `npm/rules/tauri/js/tooling.mjs` реалізує JS-orchestrator для правила `tauri.mdc`. Його єдина мета — перевірити, чи правильно налаштовано VSCode-конфіг `.vscode/extensions.json` у проєктах, де є Tauri.
+
+Особливості:
+
+- **Cross-file gating**. Перевірка вмикається лише за наявності маркера Tauri у проєкті. Якщо проєкт не використовує Tauri — модуль одразу повертає успіх і нічого не валідує.
+- **Маркер Tauri** шукається в усіх workspace-пакетах монорепо (включно з кореневим) через `getMonorepoPackageRootDirs()` за п'ятьма ознаками: наявність каталогу `src-tauri/`, файлів `src-tauri/Cargo.toml`, `src-tauri/tauri.conf.json`, `tauri.conf.json` (legacy flat-layout) або префікса `@tauri-apps/` у `dependencies`/`devDependencies` файла `package.json`.
+- **Plan B архітектура**. Це conditional-правило: Rego-полісі лежить глобально без `target.json` поруч і **не** є auto-discoverable через `n-cursor fix`. Тому JS-orchestrator робить FS-існування файла самостійно, а content-валідацію делегує в Rego через `runConftestBatch` (namespace `tauri.vscode_extensions`).
+- **Звітування** іде через `createCheckReporter` — стандартний reporter з `pass`/`fail` повідомленнями та `getExitCode()` (0 — OK, 1 — є порушення).
+
+## Експорти / API
+
+| Символ  | Тип                     | Опис                                                                                                                                                       |
+| ------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check` | `() => Promise<number>` | **Єдиний публічний експорт.** Запускає перевірку правил `tauri.mdc` і повертає exit-код процесу: `0` — все добре або Tauri-маркера немає, `1` — порушення. |
+
+Внутрішні (не експортовані) функції модуля:
+
+- `packageHasTauriDep(pkg)` — детектор `@tauri-apps/*` залежностей у `package.json`.
+- `workspaceHasTauriMarker(cwd, ws)` — перевірка одного workspace-пакета на ознаки Tauri.
+- `projectHasTauriMarker()` — обхід усіх workspaces для агрегованого результату.
+
+## Функції
+
+### `packageHasTauriDep(pkg)`
+
+**Сигнатура.**
+
+```js
+function packageHasTauriDep(pkg: Record<string, unknown> | null | undefined): boolean
+```
+
+**Параметри.**
+
+- `pkg` — розпарсений вміст `package.json`. Допускає `null`, `undefined` або не-об'єктне значення — у цих випадках повертається `false`.
+
+**Повертає.**
+
+- `boolean` — `true`, якщо серед ключів `pkg.dependencies` або `pkg.devDependencies` знайдено хоча б один ключ із префіксом `@tauri-apps/`. Інакше — `false`.
+
+**Логіка.**
+
+1. Якщо `pkg` falsy або не object — `false`.
+2. Перебирає два поля: `'dependencies'` і `'devDependencies'`.
+3. Для кожного, якщо поле є object — ітерує `Object.keys()` і перевіряє `name.startsWith('@tauri-apps/')`.
+4. Перший збіг → негайне `true` (early return).
+
+**Side effects.** Немає — чиста функція. Працює лише з вхідним об'єктом.
+
+---
+
+### `workspaceHasTauriMarker(cwd, ws)`
+
+**Сигнатура.**
+
+```js
+async function workspaceHasTauriMarker(cwd: string, ws: string): Promise<boolean>
+```
+
+**Параметри.**
+
+- `cwd` — абсолютний шлях до кореня репо (зазвичай `process.cwd()`).
+- `ws` — відносний шлях workspace-пакета від кореня. Спеціальне значення `'.'` означає сам корінь (тоді `base = cwd`); для решти — `base = join(cwd, ws)`.
+
+**Повертає.**
+
+- `Promise<boolean>` — `true`, якщо в зазначеному workspace знайдено будь-який з маркерів Tauri:
+  1. Існує каталог `<base>/src-tauri/` (`existsSync` + `statSync(...).isDirectory()`).
+  2. Існує файл `<base>/src-tauri/Cargo.toml`.
+  3. Існує файл `<base>/src-tauri/tauri.conf.json`.
+  4. Існує файл `<base>/tauri.conf.json` (legacy flat-layout).
+  5. `<base>/package.json` існує, парситься як JSON і `packageHasTauriDep(pkg)` повертає `true`.
+
+Якщо `package.json` не існує — повертає `false` (умова `if (!existsSync(pkgPath)) return false`).
+
+**Side effects.**
+
+- Синхронні FS-виклики `existsSync`, `statSync` для каталогів і файлів.
+- Асинхронне читання файла `readFile(pkgPath, 'utf8')`.
+- `JSON.parse` — кидає виключення на некоректному JSON у `package.json` (без явного `try/catch` всередині). Викидається вгору як rejected promise.
+
+---
+
+### `projectHasTauriMarker()`
+
+**Сигнатура.**
+
+```js
+async function projectHasTauriMarker(): Promise<boolean>
+```
+
+**Параметри.** Немає.
+
+**Повертає.**
+
+- `Promise<boolean>` — `true`, якщо хоча б один workspace (включаючи корінь) має маркер Tauri.
+
+**Логіка.**
+
+1. Бере `cwd = process.cwd()`.
+2. Викликає `getMonorepoPackageRootDirs(cwd)` — отримує масив workspace-шляхів (корінь `'.'` + всі workspaces з `package.json#workspaces`).
+3. Послідовно (через `for...of`) перевіряє кожен workspace через `workspaceHasTauriMarker`. На першому `true` — короткозамикає й повертає `true`.
+4. Якщо жоден workspace не має маркера — повертає `false`.
+
+**Side effects.** Опосередковано — через FS-виклики у `workspaceHasTauriMarker` та `getMonorepoPackageRootDirs`.
+
+---
+
+### `check()` — публічний експорт
+
+**Сигнатура.**
+
+```js
+export async function check(): Promise<number>
+```
+
+**Параметри.** Немає.
+
+**Повертає.**
+
+- `Promise<number>` — exit-код перевірки, отриманий через `reporter.getExitCode()`:
+  - `0` — успіх (немає маркера Tauri, або всі канонічні конфіги відповідають правилам).
+  - `1` — є помилки (наприклад, `.vscode/extensions.json` не існує або не пройшов Rego-валідацію).
+
+**Логіка покроково.**
+
+1. Створює reporter: `const reporter = createCheckReporter()` і виймає шорткати `{ pass, fail }`.
+2. Викликає `projectHasTauriMarker()`. Якщо маркера немає:
+   - Записує `pass('Немає маркера Tauri (src-tauri/, tauri.conf.json, @tauri-apps/*) — tauri-tooling не вимагається')`.
+   - Повертає `reporter.getExitCode()` — зазвичай `0` (бо тільки `pass`).
+3. Якщо маркер є — записує `pass('Знайдено маркер Tauri — перевіряємо канонічні конфіги tauri.mdc')` і починає валідацію `.vscode/extensions.json`.
+4. Перевіряє існування файла `.vscode/extensions.json` (відносний шлях від CWD):
+   - Якщо файла немає — `fail(...)` з повідомленням, що треба створити з `recommendations "tauri-apps.tauri-vscode"`, і повертає `reporter.getExitCode()` (тут уже буде `1`).
+5. Якщо файл існує — викликає `runConftestBatch({ policyDirRel: 'tauri/vscode_extensions', namespace: 'tauri.vscode_extensions', files: ['.vscode/extensions.json'] })`. Отримує масив `violations`.
+6. Залежно від результату:
+   - `violations.length === 0` → `pass(`${extPath} відповідає tauri.vscode_extensions (rego)`)`.
+   - Інакше — для кожного `v` із `violations` викликає `fail(v.message)`.
+7. Повертає `reporter.getExitCode()` — `0` або `1` залежно від накопичених `fail`-викликів.
+
+**Side effects.**
+
+- Читає `process.cwd()` (через залежні функції).
+- FS-доступ: `existsSync`, `statSync`, `readFile` (через детектори маркера) і `existsSync` для `.vscode/extensions.json`.
+- Запускає зовнішній двійковий процес `conftest` (опосередковано через `runConftestBatch`).
+- Накопичує повідомлення в reporter (stdout / накопичувач залежить від реалізації `createCheckReporter`).
+
+## Залежності
+
+Імпорти модуля:
+
+- **Стандартна бібліотека Node.js:**
+  - `existsSync`, `statSync` із `node:fs` — синхронні FS-перевірки існування файлів/каталогів і типу запису.
+  - `readFile` із `node:fs/promises` — асинхронне читання `package.json`.
+  - `join` із `node:path` — побудова шляхів.
+- **Локальні утиліти (з `../../../scripts/lib/`):**
+  - `createCheckReporter` із `check-reporter.mjs` — фабрика звітувача з `pass`/`fail`/`getExitCode`.
+  - `runConftestBatch` із `run-conftest-batch.mjs` — синхронний (за використанням у коді) виклик `conftest` для batch-валідації набору файлів проти Rego-полісі.
+  - `getMonorepoPackageRootDirs` із `workspaces.mjs` — асинхронне отримання шляхів усіх workspace-пакетів монорепо (включаючи корінь `'.'`).
+
+Зовнішні runtime-передумови:
+
+- Виконуваний `conftest` має бути доступний у `PATH` (інакше `runConftestBatch` зафейлиться).
+- Rego-полісі для namespace `tauri.vscode_extensions` має бути зареєстрований у глобальній теці полісі (без `target.json` поруч — це conditional-правило).
+
+## Потік виконання / Використання
+
+**Типове призначення.** Модуль викликається CLI-агрегатором правил (наприклад, `n-cursor` чи аналогом) у режимі перевірки. Він — один із багатьох `check()`-модулів, кожен з яких відповідає одному `.mdc`-правилу. `tooling.mjs` відповідає за частину `tauri.mdc`, що стосується VSCode tooling.
+
+**Приклад прямого виклику:**
+
+```js
+import { check } from './npm/rules/tauri/js/tooling.mjs'
+
+const code = await check()
+process.exit(code)
+```
+
+**Послідовність виконання `check()`:**
+
+1. **Ініціалізація reporter** → готовий до накопичення `pass`/`fail`.
+2. **Gating (cross-file)** → `projectHasTauriMarker()`:
+   - `getMonorepoPackageRootDirs(cwd)` повертає шляхи всіх workspaces.
+   - Для кожного workspace перевіряємо 5 ознак (каталог `src-tauri/`, `Cargo.toml`, `tauri.conf.json` у двох локаціях, `@tauri-apps/*` у `package.json`).
+   - Перший знайдений маркер → переходимо до валідації; інакше — `pass` + exit `0`.
+3. **FS-існування** `.vscode/extensions.json` — якщо немає, `fail` з підказкою про канонічний контент і exit `1`.
+4. **Делегування в Rego** через `runConftestBatch`:
+   - `policyDirRel: 'tauri/vscode_extensions'` — відносний шлях до полісі.
+   - `namespace: 'tauri.vscode_extensions'` — Rego-namespace для оцінки.
+   - `files: ['.vscode/extensions.json']` — вхідні файли для batch-валідації.
+5. **Звіт** — `pass` за нуль порушень, `fail(v.message)` для кожного `violation`.
+6. **Повернення exit-коду** через `reporter.getExitCode()`.
+
+**Поведінка при помилках.**
+
+- Якщо `package.json` у якомусь workspace містить невалідний JSON — `JSON.parse` кине виключення; `projectHasTauriMarker` (і відповідно `check`) поверне rejected promise. Обробку покладено на викликальника.
+- Якщо `conftest` не встановлено — помилку викине `runConftestBatch` (поведінка залежить від його реалізації).
+
+**Інтеграційні зв'язки.**
+
+- Правило в `.mdc`-форматі (зміст для людини) — `npm/rules/tauri/tauri.mdc` (або аналог; шукати в репо).
+- Rego-полісі — десь у глобальній теці полісі під `tauri/vscode_extensions/` (адресовано через `policyDirRel`).
+- Це conditional-правило: воно **не** реєструється автоматично в `n-cursor fix` як target-discoverable; орchestrator `tooling.mjs` сам гейтить виконання й сам викликає `conftest`.
+
+## Rebuild Test
+
+Опис достатній, щоб відтворити модуль з нуля:
+
+1. Створити файл `tooling.mjs` з JSDoc-преамбулою, що описує мету та cross-file gating (5 ознак Tauri-маркера).
+2. Імпортувати:
+   - `existsSync`, `statSync` із `node:fs`;
+   - `readFile` із `node:fs/promises`;
+   - `join` із `node:path`;
+   - `createCheckReporter` з `../../../scripts/lib/check-reporter.mjs`;
+   - `runConftestBatch` з `../../../scripts/lib/run-conftest-batch.mjs`;
+   - `getMonorepoPackageRootDirs` з `../../../scripts/lib/workspaces.mjs`.
+3. Реалізувати `packageHasTauriDep(pkg)` — defensive guard + цикл по `['dependencies', 'devDependencies']` + перевірка `name.startsWith('@tauri-apps/')`.
+4. Реалізувати `workspaceHasTauriMarker(cwd, ws)` — `base = ws === '.' ? cwd : join(cwd, ws)`, послідовні `existsSync`/`statSync` для каталогу `src-tauri/`, файлів `src-tauri/Cargo.toml`, `src-tauri/tauri.conf.json`, `tauri.conf.json`; fallback на `readFile(<base>/package.json)` + `JSON.parse` + `packageHasTauriDep`.
+5. Реалізувати `projectHasTauriMarker()` — `process.cwd()`, `await getMonorepoPackageRootDirs(cwd)`, `for...of` з раннім `return true`.
+6. Експортувати `async function check()`:
+   - Створити reporter, дістати `pass`/`fail`.
+   - Перевірити маркер; якщо немає — `pass(...)` + `return reporter.getExitCode()`.
+   - Якщо є — `pass(...)`, потім гейт `.vscode/extensions.json`: відсутній → `fail(...)` + return.
+   - Викликати `runConftestBatch({ policyDirRel: 'tauri/vscode_extensions', namespace: 'tauri.vscode_extensions', files: [extPath] })`.
+   - На порожньому масиві порушень — `pass(...)`; інакше — цикл `fail(v.message)`.
+   - Повернути `reporter.getExitCode()`.

package/rules/test/coverage/coverage.mjs

@@ -75,7 +75,7 @@ export function formatScore({ caught, total }) {
 /**
  * Рендерить таблицю покриття + мутаційного тестування як Markdown.
  * Якщо будь-який рядок містить непустий `survived`, додає секцію
- * `## Вцілілі мутанти` з JSON-блоком для `/n-fix-tests`.
+ * `## Вцілілі мутанти` з JSON-блоком для `/n-coverage-fix`.
  * Якщо `allowedGaps` непустий, додає секцію `## Allowed gaps` з таблицею
  * verdict/confidence/reason для кожного LLM-класифікованого мутанта.
  * Без timestamp, щоб git diff рухався лише при зміні метрик.
@@ -130,10 +130,22 @@ export function renderMarkdown(rows, allowedGaps = []) {
       gapsByFile.get(gap.file).push(gap)
     }
 
-    lines.push('', '## Allowed gaps', '', `> LLM-класифікатор виключив ${allowedGaps.length} survived мутант(ів) зі знаменника mutation score.`, '> Категорії: equivalent (поведінково еквівалентний), defensive (impossible state), glue/wrapper (integration test покриває).')
+    lines.push(
+      '',
+      '## Allowed gaps',
+      '',
+      `> LLM-класифікатор виключив ${allowedGaps.length} survived мутант(ів) зі знаменника mutation score.`,
+      '> Категорії: equivalent (поведінково еквівалентний), defensive (impossible state), glue/wrapper (integration test покриває).'
+    )
 
     for (const [file, gaps] of gapsByFile) {
-      lines.push('', `### ${file}`, '', '| Line | Mutant | Verdict | Confidence | Reason |', '| --- | --- | --- | --- | --- |')
+      lines.push(
+        '',
+        `### ${file}`,
+        '',
+        '| Line | Mutant | Verdict | Confidence | Reason |',
+        '| --- | --- | --- | --- | --- |'
+      )
       for (const { mutant, verdict } of gaps) {
         const sanitizedReason = verdict.reason.replaceAll('|', String.raw`\|`).replaceAll('\n', ' ')
         lines.push(

package/rules/test/docs/fix.md

@@ -0,0 +1,132 @@
+# fix.mjs — правило `test`
+
+## Огляд
+
+Файл `npm/rules/test/fix.mjs` — це точка входу правила з ідентифікатором `test` у системі правил `@nitra/cursor`. Файл одночасно виконує дві ролі:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор `@nitra/cursor` коли пакет використовується як бібліотека (наприклад, через `npx @nitra/cursor fix test` або через композицію з іншими правилами).
+2. **Standalone mode** — якщо файл запущено напряму (`bun npm/rules/test/fix.mjs`), він самостійно виконує повний еквівалент CLI-команди `npx @nitra/cursor fix test`: підвантажує конфіг, застосовує whitelist, друкує підсумок і повертає коректний exit-code для CI/IDE.
+
+Обидва режими делегують усю важку роботу спільному оркестратору `runStandardRule`, який реалізує стандартизований пайплайн правила: **applies → JS-concerns → policy → mdc-refs**. Тобто конкретно цей файл не містить власної бізнес-логіки правила — він є лише декларативним «шаблонним» entry-point, який «прив'язує» директорію правила (`import.meta.dirname`) до стандартного процесу виконання.
+
+Такий патерн (тонкий `fix.mjs` + важка логіка в `scripts/lib/`) — конвенція проєкту: кожне правило має ідентичний скелет, а конкретна перевірка зберігається в `check-{id}.mjs` / `mdc-refs.json` / supporting файлах у тій же директорії.
+
+## Експорти / API
+
+| Експорт | Тип                                      | Опис                                                                                          |
+| ------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-функція запуску правила. Повертає exit-code: `0` — порушень немає, `1` — є порушення. |
+
+Файл **не має default-експорту**. Іменований експорт `run` — це публічний контракт, який CLI-оркестратор `@nitra/cursor` очікує знайти у кожному `fix.mjs`.
+
+### Тип `RuleContext`
+
+Декларується у `../../scripts/lib/run-standard-rule.mjs` і реекспортується через JSDoc. Найважливіше поле:
+
+- `walkCache` — спільний кеш обходу файлової системи, який орекстратор передає між правилами в одному прогоні, щоб не сканувати дерево повторно.
+
+Контекст є **необов'язковим**: при standalone-запуску `runRuleCli` сам створює свіжий контекст; при library-запуску ctx підставляє зовнішній orchestrator.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
+- **Параметри:**
+  - `ctx` _(опціональний)_ — `RuleContext`, контекст прогону. Може містити `walkCache` та інші поля, які стандартний пайплайн використовує для оптимізацій і передачі стану між правилами в межах однієї CLI-сесії.
+- **Повертає:** `Promise<number>` — exit-code:
+  - `0` — правило відпрацювало без порушень;
+  - `1` — виявлено порушення (хоча б на одному з кроків applies/JS-concerns/policy/mdc-refs).
+- **Side effects:** усі побічні ефекти делеговані `runStandardRule`. Зокрема: читання файлової системи (через walker), друк звіту в stdout/stderr, можливі правки файлів (якщо правило підтримує auto-fix), оновлення `walkCache`.
+- **Ідентифікація правила:** правило ідентифікується **директорією** через `import.meta.dirname` — тобто абсолютним шляхом до теки `npm/rules/test/`. Зміна шляху чи переіменування директорії змінить ідентичність правила.
+
+### Top-level standalone-блок
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Тип:** не функція, а top-level `if`-блок із top-level `await`.
+- **Умова входу:** `isRunAsCli(import.meta.url)` — повертає `true`, лише якщо цей модуль запущено як головний скрипт (а не імпортовано як залежність). Реалізація утиліти живе в `../../scripts/lib/run-rule-cli.mjs`.
+- **Дія:** викликає `runRuleCli(import.meta.dirname)` — повний CLI-флоу одного правила (config-loading, whitelist, summary), очікує його `Promise<number>` і передає результат у `process.exit(...)`.
+- **Side effects:** **завершує процес** через `process.exit(...)`. Тому інклюди коментарі-disable для ESLint-правил `n/no-process-exit` та `unicorn/no-process-exit` — це свідомий виняток для standalone entry-point.
+- **Чому `await` дозволено на top-level:** файл є ESM-модулем (`.mjs`), а ESM підтримує top-level `await` нативно.
+
+## Залежності
+
+### Внутрішні модулі (relative imports)
+
+| Шлях                                      | Імпортовані сутності       | Призначення                                                                                                                             |
+| ----------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Standalone CLI-обгортка: детект `import.meta.url === entry` і запуск повного CLI-флоу з config/whitelist/summary.                       |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний пайплайн правила: послідовно прогоняє кроки `applies` → `JS-concerns` → `policy` → `mdc-refs`. Експортує тип `RuleContext`. |
+
+Шляхи `../../scripts/lib/...` ведуть із `npm/rules/test/` у `npm/scripts/lib/` — тобто до **спільної інфраструктури правил** усередині пакета `@nitra/cursor`.
+
+### Зовнішні залежності
+
+Прямих імпортів зовнішніх npm-пакетів немає. Усі зовнішні залежності (наприклад, file-walker, glob-matcher, ESLint-utils) інкапсульовані всередині `runStandardRule` / `runRuleCli`.
+
+### Платформенні API
+
+- `import.meta.dirname` — Node.js/Bun-фіча ESM, що повертає абсолютний шлях до теки поточного модуля. Доступна в Node.js ≥ 20.11 та сучасних версіях Bun.
+- `import.meta.url` — стандартний ESM-атрибут, URL поточного модуля (використовується для CLI-детекту).
+- `process.exit(code)` — глобальний Node.js/Bun API.
+- Top-level `await` — стандарт ESM (ES2022).
+
+## Потік виконання / Використання
+
+### Сценарій 1: Library mode (виклик з оркестратора)
+
+1. Зовнішній CLI (`npx @nitra/cursor fix` або композитний прогон) визначає список активних правил.
+2. Для правила `test` він `import`-ить `npm/rules/test/fix.mjs`.
+3. Top-level `if (isRunAsCli(...))` повертає `false` (бо модуль імпортовано, а не запущено напряму) — standalone-гілка пропускається, процес не завершується.
+4. Оркестратор викликає `run(ctx)` із підготовленим контекстом (`walkCache` тощо).
+5. `run` делегує виклик `runStandardRule(import.meta.dirname, ctx)`.
+6. `runStandardRule` послідовно виконує кроки пайплайна правила, читаючи допоміжні файли з директорії правила.
+7. Результат (`Promise<number>`) повертається в оркестратор, який агрегує exit-коди усіх правил.
+
+### Сценарій 2: Standalone mode (пряме виконання)
+
+Команда: `bun npm/rules/test/fix.mjs` (або `node npm/rules/test/fix.mjs` за умови підтримки `import.meta.dirname`).
+
+1. Bun/Node запускає модуль як головний.
+2. Виконується top-level код: `isRunAsCli(import.meta.url)` → `true`.
+3. Викликається `runRuleCli(import.meta.dirname)`:
+   - підвантажується конфіг проєкту,
+   - застосовується whitelist (якщо є),
+   - запускається пайплайн правила (фактично — той самий `runStandardRule` під капотом, але обгорнутий у CLI-логіку: парсинг прапорців, друк summary, обробка помилок),
+   - повертається `Promise<number>` із exit-code.
+4. `await` чекає завершення Promise.
+5. `process.exit(code)` завершує процес із отриманим кодом — це робить файл придатним для CI/pre-commit/IDE-інтеграцій, які покладаються саме на exit-code.
+
+### Сценарій 3: Через `npx @nitra/cursor fix test`
+
+Це **гібридний** сценарій:
+
+1. CLI пакета `@nitra/cursor` запускається користувачем.
+2. Він знаходить директорію правила за id (`test`) і динамічно імпортує `fix.mjs`.
+3. CLI викликає експортовану функцію `run(ctx)` — тобто це Library mode (Сценарій 1), просто ініційований CLI-командою верхнього рівня. Standalone-гілка в самому `fix.mjs` при цьому **не активується**.
+
+### Інваріанти та контракти
+
+- `run` **мусить** повертати `Promise<number>` із значенням `0` або `1` — інакше CLI-оркестратор може некоректно агрегувати результати.
+- Файл **не повинен** містити власної логіки правила: усе делегується `runStandardRule`. Конкретна перевірка живе у супутніх файлах директорії (`check-test.mjs`, `mdc-refs.json`, тощо — згідно конвенції проєкту).
+- Top-level `await` дозволено лише в standalone-блоці й лише тому, що модуль ESM (`.mjs`).
+- `process.exit` викликається **лише** в standalone-режимі — у library-режимі (Сценарій 1) виклик `process.exit` був би порушенням (тому існує `isRunAsCli`-guard і ESLint-disable коментар із обґрунтуванням).
+
+### Розширення та модифікація
+
+Файл є **темплейтним** і свідомо мінімальним. Щоб змінити поведінку правила `test`, **не редагуйте `fix.mjs`** — замість цього:
+
+- логіку перевірок змінюйте у `check-*.mjs` тієї ж директорії;
+- посилання на правила Cursor оновлюйте в `mdc-refs.json`;
+- спільні зміни пайплайна вносьте в `npm/scripts/lib/run-standard-rule.mjs` (тоді вони застосуються до **всіх** правил одночасно).