@nitra/cursor 3.22.0 → 3.23.0

package/rules/style-lint/js/docs/lint.md

@@ -0,0 +1,184 @@
+# lint.mjs
+
+## Огляд
+
+Модуль `lint.mjs` — це «quick-крок» (швидкий етап) правила `style-lint`, який запускає `stylelint --fix` по стильових файлах проєкту: `*.css`, `*.scss`, `*.vue`. Модуль виконує дві окремі задачі:
+
+1. Фільтрує довільний список шляхів, лишаючи з нього тільки файли зі стильовими розширеннями (`.css`, `.scss`, `.vue`).
+2. Запускає виконуваний бінарник `stylelint` через `npx` з прапорцем `--fix` — або по точному списку файлів (режим «quick»), або по всьому glob-патерну `**/*.{css,scss,vue}` (режим «ci»).
+
+Модуль написаний як ES-модуль (`.mjs`), не має побічних ефектів на рівні імпорту (не запускає `stylelint` під час завантаження модуля) і експортує дві функції: `filterStyleFiles` та `lint`.
+
+Призначений для використання в інфраструктурі лінтінгу монорепо: викликається з оркестратора правил (наприклад, `tooling.mjs` сусіднього модуля), який передає або конкретний набір змінених файлів (швидкий цикл локального розробника), або `undefined` (повний прогін в CI).
+
+## Експорти / API
+
+Модуль має два іменованих експорти:
+
+| Експорт            | Тип        | Призначення                                                                |
+| ------------------ | ---------- | -------------------------------------------------------------------------- |
+| `filterStyleFiles` | `function` | Чистий фільтр: з масиву шляхів повертає тільки `.css` / `.scss` / `.vue`.  |
+| `lint`             | `function` | Запускає `stylelint --fix` через `npx`, повертає `Promise<number>` (exit). |
+
+Дефолтного експорту немає.
+
+Окрім експортів, у модулі визначена константа модульного рівня `STYLE_EXT_RE` — приватна (не експортується) регулярка `/\.(?:css|scss|vue)$/u`, яка матчить лише суфікс імені файлу.
+
+## Функції
+
+### `filterStyleFiles(files)`
+
+**Сигнатура.**
+
+```js
+export function filterStyleFiles(files: string[]): string[]
+```
+
+**Параметри.**
+
+- `files` — масив рядків-шляхів (відносних або абсолютних — функція не розрізняє). Жодних обмежень на роздільник шляху чи на регістр розширення регулярка не накладає, окрім того що розширення має бути в нижньому регістрі (`.css`, `.scss`, `.vue`).
+
+**Повертає.**
+
+- `string[]` — новий масив, що містить лише ті елементи `files`, у яких суфікс задовольняє регулярку `STYLE_EXT_RE` (`.css` / `.scss` / `.vue` в кінці рядка). Порядок збережено.
+
+**Side effects.**
+
+- Немає. Функція чиста: не змінює вхідний масив, не звертається до файлової системи, не пише в stdout/stderr, не залежить від процесового стану. Імпорт `node:child_process` тут не задіяний.
+
+**Поведінкові деталі.**
+
+- Якщо `files` — порожній масив, повертається порожній масив.
+- Якщо в `files` немає жодного стильового файлу, повертається порожній масив.
+- Файли з розширеннями `.CSS`, `.Vue` тощо (з великими літерами) **не** будуть включені, бо регулярка не має прапора `i`.
+- Регулярка прив'язана до кінця рядка (`$`), тому шляхи на кшталт `foo.css.bak` не пройдуть.
+- Прапор `u` (Unicode) у регулярці дозволяє коректно обробляти шляхи з Unicode-символами.
+
+### `lint(files, cwd = process.cwd())`
+
+**Сигнатура.**
+
+```js
+export function lint(
+  files: string[] | undefined,
+  cwd?: string
+): Promise<number>
+```
+
+**Параметри.**
+
+- `files` — або масив шляхів (тоді функція працює в режимі «quick»: фільтрує його через `filterStyleFiles` і запускає `stylelint` тільки по відфільтрованих файлах), або `undefined` (режим «ci»: запускає `stylelint` по glob-патерну `**/*.{css,scss,vue}` від кореня `cwd`).
+- `cwd` — корінь, у якому запускатиметься `npx`. За замовчуванням — поточна робоча директорія процесу (`process.cwd()`).
+
+**Повертає.**
+
+- `Promise<number>` — обіцянка з exit-кодом:
+  - `0` — якщо `files` — масив, але після фільтрації не лишилось жодного стильового файлу (швидкий вихід без запуску `stylelint`).
+  - Числовий exit-код процесу `npx stylelint ...`, отриманий з поля `r.status` синхронного результату `spawnSync`.
+  - `1` — якщо `r.status` не є числом (наприклад, процес був завершений сигналом, не зміг запуститися або інша «нештатна» ситуація).
+- Хоча всередині немає `async` й `await`, повертається явно `Promise.resolve(...)`, тож сигнатура асинхронна і викликати функцію можна через `await`.
+
+**Side effects.**
+
+- Запускає **зовнішній процес** `npx stylelint --fix ...` через `spawnSync` з `stdio: 'inherit'`. Це означає:
+  - `stdout`, `stderr`, `stdin` дочірнього процесу наслідуються від батьківського — весь вивід `stylelint` йде безпосередньо в консоль користувача (або в логи CI).
+  - Функція **блокує** event-loop поточного процесу до завершення `stylelint` (попри асинхронний інтерфейс).
+  - `stylelint --fix` **модифікує файли на диску** там, де він здатен автоматично виправити порушення стилю.
+- Запис у файлову систему здійснюється самим `stylelint`, а не цим модулем напряму.
+- Модуль не намагається інсталювати `stylelint` — він повинен бути доступний через `npx` (зазвичай через `package.json` залежність, локальний `node_modules/.bin` або глобально).
+
+**Поведінкові деталі.**
+
+- Аргументи `npx` будуються в масив `args`: завжди починається з `['stylelint', '--fix']`, далі або додається один елемент-glob `**/*.{css,scss,vue}`, або розпаковується список відфільтрованих файлів через spread.
+- Glob-патерн `**/*.{css,scss,vue}` передається без екранування — його **розкриває сам `stylelint`** (а не shell), оскільки `spawnSync` викликається без `shell: true`. Тобто це не shell-glob, а аргумент, який `stylelint` парсить як glob-патерн.
+- У режимі «quick» з порожнім результатом фільтрації функція не викликає `npx` взагалі — це оптимізація для випадків, коли в наборі змінених файлів немає жодного стильового файлу (типово для PR, що зачіпає тільки JS/TS-код).
+
+## Залежності
+
+### Зовнішні npm-пакети
+
+Прямих імпортів з npm немає.
+
+### Node.js вбудовані модулі
+
+- `node:child_process` — імпорт `{ spawnSync }`. Використовується для синхронного запуску `npx stylelint ...`.
+
+### Зовнішні бінарники / системні залежності
+
+- `npx` — має бути в `PATH`. Це стандартний компаньйон `npm` / `bun` / `pnpm`.
+- `stylelint` — має бути запускний через `npx` (через локальний `node_modules` або глобально). Конкретна версія й конфіг (`.stylelintrc*`) знаходяться поза межами цього модуля й керуються рівнем монорепо.
+
+### Внутрішні модульні зв'язки
+
+Сам файл нічого не імпортує з інших файлів проєкту. Натомість його імпортують:
+
+- сусідній `tooling.mjs` (оркестратор правила `style-lint`),
+- та/або тести в підтеці `tests/`.
+
+## Потік виконання / Використання
+
+### Типовий сценарій 1: quick-режим (локальний розробник)
+
+```js
+import { lint } from './lint.mjs'
+
+const changed = ['src/components/Button.vue', 'src/utils/dom.ts', 'src/styles/main.scss']
+
+const code = await lint(changed)
+process.exit(code)
+```
+
+Що відбудеться:
+
+1. `filterStyleFiles(changed)` поверне `['src/components/Button.vue', 'src/styles/main.scss']`.
+2. Сформується команда `npx stylelint --fix src/components/Button.vue src/styles/main.scss`.
+3. `spawnSync` запустить `npx`, `stylelint` обробить тільки ці два файли, виправить що зможе, лог піде в консоль.
+4. Функція поверне promise з exit-кодом `stylelint` (`0` — все добре; ненульовий — лишилися невиправні порушення або помилка конфігу).
+
+### Типовий сценарій 2: ci-режим (повний прогін)
+
+```js
+import { lint } from './lint.mjs'
+
+const code = await lint(undefined, process.cwd())
+process.exit(code)
+```
+
+Що відбудеться:
+
+1. `files === undefined`, тому в `args` додається літерал `**/*.{css,scss,vue}`.
+2. Сформується команда `npx stylelint --fix '**/*.{css,scss,vue}'` (без shell-escaping — це аргумент).
+3. `stylelint` сам розкриває glob від `cwd` і обходить весь проєкт.
+4. Функція повертає його exit-код.
+
+### Сценарій 3: quick-режим без жодного стильового файлу
+
+```js
+const code = await lint(['README.md', 'src/index.ts'])
+// code === 0, npx навіть не запускався
+```
+
+Що відбудеться:
+
+1. `filterStyleFiles` поверне `[]`.
+2. Гілка `if (style.length === 0) return Promise.resolve(0)` поверне `0` миттєво.
+3. Жодного дочірнього процесу не створюється — це швидкий «no-op».
+
+### Як вписується в загальну архітектуру
+
+Цей файл — реалізаційна одиниця «quick» кроку правила `style-lint`. Правило в монорепо має дві площини запуску:
+
+- **quick** (швидкий) — викликається після зміни файлів локально, працює тільки по зміненому списку для мінімального часу відгуку.
+- **ci** — викликається в неперервній інтеграції, проганяє по всьому glob-у щоб гарантовано перевірити весь репозиторій.
+
+Файл `lint.mjs` уніфікує обидва режими в одній функції, де перемикач режиму — це `files === undefined` (ci) vs `files: string[]` (quick).
+
+### Контракти й гарантії
+
+- Функція `lint` **синхронно** виконує дочірній процес, але повертає `Promise<number>` — це навмисно, щоб уніфікувати інтерфейс з іншими «крок-функціями» в системі правил, які можуть бути по-справжньому асинхронні. Caller завжди робить `await lint(...)`.
+- `lint` не кидає виключень: будь-який збій `npx` (включаючи відсутній бінарник) перетвориться в exit-код `1` через гілку `typeof r.status === 'number' ? r.status : 1`. Це робить функцію передбачуваною для оркестратора, який оперує тільки числовими кодами.
+- `filterStyleFiles` — стабільна чиста функція, придатна для незалежного юніт-тестування (саме тому винесена як окремий експорт).
+
+## Rebuild Test
+
+Документація відповідає коду версії на момент написання: 35 рядків, два експорти (`filterStyleFiles`, `lint`), одна приватна регулярка (`STYLE_EXT_RE`), одна імпортована функція з `node:child_process` (`spawnSync`). Якщо файл буде переписано (наприклад, додасться третій експорт, зміниться сигнатура `lint`, з'явиться нова гілка для `--config`, або `spawnSync` буде замінено на асинхронний `spawn`), цей документ потребує перегенерації.

package/rules/style-lint/js/docs/tooling.md

@@ -0,0 +1,194 @@
+# tooling.mjs
+
+## Огляд
+
+Модуль `tooling.mjs` реалізує **JS-частину перевірки правила `style-lint.mdc`** — тобто тих аспектів CSS/SCSS-лінтингу через `stylelint`, які **не вкриваються** Rego-політиками (`npx @nitra/cursor check`) і які потребують **файлової системи / cross-file** знання.
+
+Конкретно перевіряє:
+
+1. Наявність **конфігу stylelint** — або як поле `stylelint` у `package.json`, або як зовнішній файл (`.stylelintrc.json`, `.stylelintrc.js`, `stylelint.config.js`). Ця перевірка cross-file: треба порівняти, чи поле є, і якщо нема — чи є зовнішній файл.
+2. Наявність файлу `.stylelintignore` у корені репозиторію.
+3. Наявність workflow-файлу `.github/workflows/lint-style.yml` (структуру окремо валідовує rego-пакет `style_lint.lint_style_yml`).
+
+Що **вже** покрила Rego (тому тут НЕ повторюється):
+
+- `npm/policy/style_lint/package_json/` — наявність скрипта `lint-style` через `npx stylelint`, `@nitra/stylelint-config` у `devDependencies`, поле `stylelint.extends`.
+- `npm/policy/style_lint/lint_style_yml/` — рядок `npx stylelint` у `run` workflow-файлу.
+- `npm/policy/style_lint/vscode_extensions/` — `stylelint.vscode-stylelint` у `recommendations` файлу `.vscode/extensions.json`.
+- `npm/policy/style_lint/vscode_settings/` — `css.validate`/`scss.validate`/`less.validate: false` у `.vscode/settings.json`.
+
+JS-копії перевірок VS Code було **видалено**, щоб не було двох джерел істини — все, що може Rego, лишається тільки у Rego.
+
+## Експорти / API
+
+| Експорт | Тип                                                | Призначення                                                                                                                                     |
+| ------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `check` | `async function (cwd?: string) => Promise<number>` | Основна точка входу: запускає всі перевірки конфігурації stylelint у заданому корені репозиторію та повертає exit-код (0 — OK, 1 — є проблеми). |
+
+Внутрішня (НЕ експортується) функція:
+
+| Функція                                       | Призначення                                                                            |
+| --------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `checkStylelintConfigPresence(reporter, cwd)` | Перевіряє наявність конфігурації stylelint (поле в `package.json` або зовнішній файл). |
+
+## Функції
+
+### `check(cwd?)`
+
+**Сигнатура:**
+
+```js
+export async function check(cwd = process.cwd()): Promise<number>
+```
+
+**Параметри:**
+
+- `cwd` (`string`, опціональний) — абсолютний шлях до кореня репозиторію, який треба перевірити. За замовчуванням використовується `process.cwd()` (поточна робоча директорія процесу).
+
+**Повертає:**
+
+- `Promise<number>` — exit-код процесу:
+  - `0` — усі перевірки пройдено (відсутні `fail`-події у репортера);
+  - `1` — хоч одна перевірка зафейлилась.
+
+Конкретне значення береться з виклику `reporter.getExitCode()`, який інкапсульований у `createCheckReporter()`.
+
+**Що робить:**
+
+1. Створює репортер через `createCheckReporter()` — він збирає події `pass`/`fail` і виводить їх у консоль під час виконання.
+2. Викликає `checkStylelintConfigPresence(reporter, cwd)` — перевірка №1 (конфіг stylelint).
+3. Перевіряє наявність файлу `.stylelintignore` у корені:
+   - якщо є — звітує `pass('.stylelintignore існує')`;
+   - якщо нема — `fail('.stylelintignore не існує — створи з вмістом: dist/')`.
+4. Перевіряє наявність workflow-файлу `.github/workflows/lint-style.yml`:
+   - якщо є — `pass` із зауваженням, що структуру файлу валідовує `npx @nitra/cursor fix → style_lint.lint_style_yml`;
+   - якщо нема — `fail` із вимогою його створити.
+5. Повертає `reporter.getExitCode()`.
+
+**Side effects:**
+
+- Виконує **синхронні** виклики `existsSync` (читає файлову систему).
+- Через репортер пише у консоль (stdout/stderr) повідомлення `pass`/`fail` (поведінка інкапсульована у `check-reporter.mjs`).
+- Не змінює файли. Не виконує мережевих запитів. Не змінює стану процесу (не викликає `process.exit`) — повертає exit-код, а викликаюча сторона сама вирішує, як його використати.
+
+---
+
+### `checkStylelintConfigPresence(reporter, cwd)` _(внутрішня)_
+
+**Сигнатура:**
+
+```js
+async function checkStylelintConfigPresence(
+  reporter: CheckReporter,
+  cwd: string,
+): Promise<void>
+```
+
+**Параметри:**
+
+- `reporter` (`CheckReporter`) — об'єкт-репортер, створений `createCheckReporter()`, з полями `{ pass, fail, getExitCode }`. У функції використовуються лише `pass` і `fail`.
+- `cwd` (`string`) — корінь репозиторію.
+
+**Повертає:**
+
+- `Promise<void>` — нічого не повертає; результат виражається через виклики `reporter.pass(...)` / `reporter.fail(...)`.
+
+**Логіка:**
+
+1. Будує шлях до `package.json` через `join(cwd, 'package.json')`.
+2. Якщо `package.json` **немає** — мовчки повертається з функції (`return`). Це означає: для тек без `package.json` перевірка пропускається (вона нерелевантна).
+3. Читає `package.json` через `readFile(pkgPath, 'utf8')` і парсить як JSON.
+4. Перевіряє `hasField` — `pkg.stylelint && typeof pkg.stylelint === 'object'` (саме поле-об'єкт; формат `extends: "@nitra/stylelint-config"` валідовує Rego).
+5. Перевіряє `hasExternalCfg` — наявність хоча б одного з файлів:
+   - `.stylelintrc.json`
+   - `.stylelintrc.js`
+   - `stylelint.config.js`
+6. Якщо `hasField || hasExternalCfg` — `pass('Конфіг stylelint є — у package.json або окремим файлом')`.
+7. Інакше — `fail('Немає конфігу stylelint — додай "stylelint": { "extends": "@nitra/stylelint-config" } до package.json')`.
+
+**Side effects:**
+
+- Синхронно: `existsSync` для `package.json` та для трьох можливих зовнішніх конфіг-файлів.
+- Асинхронно: `readFile` для `package.json`.
+- Через репортер пише до консолі результат.
+- Може кинути виняток, якщо `package.json` існує, але містить невалідний JSON (`JSON.parse` кине `SyntaxError`) — функція **не** обробляє цю помилку.
+
+**Зауваження щодо файлів-конфігів:**
+
+Список перевірюваних зовнішніх конфігів **не** охоплює всі можливі формати, які підтримує stylelint (наприклад, `.stylelintrc`, `.stylelintrc.yaml`, `.stylelintrc.yml`, `.stylelintrc.cjs`). Перевіряються лише три найпопулярніші: `.stylelintrc.json`, `.stylelintrc.js`, `stylelint.config.js`.
+
+## Залежності
+
+### Імпорти із Node.js
+
+| Модуль             | Що використовується                                 |
+| ------------------ | --------------------------------------------------- |
+| `node:fs`          | `existsSync` — синхронна перевірка існування файлу. |
+| `node:fs/promises` | `readFile` — асинхронне читання файлу як рядка.     |
+| `node:path`        | `join` — крос-платформне склеювання шляхів.         |
+
+### Внутрішні імпорти
+
+| Шлях                                      | Що дає                                                                                                                                                                                                                      |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `../../../scripts/lib/check-reporter.mjs` | `createCheckReporter()` — фабрика репортера, який має методи `pass(msg)`, `fail(msg)` та `getExitCode()`. Тип `CheckReporter` тягнеться JSDoc-посиланням `import('../../../scripts/lib/check-reporter.mjs').CheckReporter`. |
+
+### Зв'язані артефакти (НЕ імпортуються, але важливі контекстно)
+
+- `npm/rules/style-lint/style-lint.mdc` — людино-зрозуміле формулювання правила.
+- `npm/policy/style_lint/package_json/` — Rego-пакет, що покриває валідацію формату полів `package.json`.
+- `npm/policy/style_lint/lint_style_yml/` — Rego-пакет, що валідовує вміст workflow-файлу.
+- `npm/policy/style_lint/vscode_extensions/` — Rego для `.vscode/extensions.json`.
+- `npm/policy/style_lint/vscode_settings/` — Rego для `.vscode/settings.json`.
+
+## Потік виконання / Використання
+
+### Контекст виклику
+
+Модуль є частиною ланцюжка перевірок правил `@nitra/cursor`. Експортована функція `check` викликається диспетчером перевірок (зазвичай через CLI `npx @nitra/cursor check`), який ітерує rule-теки і для кожної шукає файл `js/tooling.mjs` з експортованим `check`.
+
+### Послідовність дій усередині `check`
+
+1. **Створення репортера:**
+   ```js
+   const reporter = createCheckReporter()
+   const { pass, fail } = reporter
+   ```
+   (`pass`/`fail` деструктуруються, але в `check` напряму не використовуються — лише як алії; всередині `checkStylelintConfigPresence` вони беруться зі свого деструктурування.)
+2. **Перевірка конфігу stylelint** — `await checkStylelintConfigPresence(reporter, cwd)`.
+3. **Перевірка `.stylelintignore`** — `existsSync(join(cwd, '.stylelintignore'))`.
+4. **Перевірка workflow `lint-style.yml`** — `existsSync(join(cwd, '.github/workflows/lint-style.yml'))`.
+5. **Повернення exit-коду** — `return reporter.getExitCode()`.
+
+### Приклад використання
+
+```js
+import { check } from '@nitra/cursor/rules/style-lint/js/tooling.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+Або через CLI-обгортку:
+
+```bash
+npx @nitra/cursor check
+```
+
+(CLI сам знайде цей модуль за конвенцією `npm/rules/<rule>/js/tooling.mjs` і викличе `check()` без аргументів, тож буде використано `process.cwd()`.)
+
+### Гарантії та межі відповідальності
+
+- Модуль **не змінює** файли (немає `fix`-режиму) — він тільки **репортує**.
+- Він **не дублює** перевірок, які вже робить Rego. Розділення: FS / cross-file → JS (тут); формат / структура одного файлу → Rego.
+- Виклик `check` із `cwd`, де немає `package.json`, — валідний сценарій: перевірка конфігу stylelint буде пропущена (мовчки), решта перевірок (`.stylelintignore`, workflow) — виконається.
+- Якщо `package.json` містить невалідний JSON — функція впаде з `SyntaxError` (це не пере́хоплюється навмисно: гнилий JSON — це самостійна проблема, яку треба чути одразу).
+
+## Rebuild Test
+
+З цього документа можна повністю відновити поведінку файлу:
+
+- Знаючи список перевірок (конфіг stylelint, `.stylelintignore`, `lint-style.yml`), повідомлення `pass`/`fail` і допустимі імена файлів-конфігів — реалізація відтворюється 1:1.
+- Деталі контракту функцій (типи параметрів, тип повернення, side effects, поведінка за відсутності `package.json`) описані явно.
+- Експорти та їх кількість (єдиний експорт `check`) зафіксовано.
+- Імпорти Node-модулів і внутрішні залежності перераховано вичерпно.

package/rules/tauri/docs/fix.md

@@ -0,0 +1,158 @@
+# fix.mjs — entry-point правила `tauri`
+
+## Огляд
+
+Файл `npm/rules/tauri/fix.mjs` — це тонкий **entry-point** (точка входу) правила `tauri` у системі правил `@nitra/cursor`. Файл виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку оркестратор CLI (`@nitra/cursor`) викликає через динамічний `import`, передаючи спільний контекст прогону (`RuleContext`, наприклад, `walkCache` для повторного використання обходу файлової системи між правилами).
+2. **Standalone mode** — якщо файл запущено напряму через `bun npm/rules/tauri/fix.mjs`, виконується повний еквівалент команди `npx @nitra/cursor fix tauri` (з підвантаженням конфігу, обробкою whitelist та виведенням summary), а процес завершується з відповідним exit-code для CI/IDE.
+
+Сам файл **не містить жодної доменної логіки правила** `tauri` — уся робота (steps `applies → JS-concerns → policy → mdc-refs`) делегується у бібліотечну функцію `runStandardRule()`. Цей файл лише підключає стандартний раннер до конкретної директорії правила (`import.meta.dirname`) і опціонально запускає CLI-обгортку.
+
+Файл є **типовим шаблоном `fix.mjs`** для будь-якого правила в `npm/rules/<id>/`: майже всі правила в цій директорії мають ідентичний за структурою `fix.mjs`, що відрізняється лише доменом (`tauri`, `vue`, `python` тощо), який неявно визначається через шлях `import.meta.dirname`.
+
+## Експорти / API
+
+| Експорт | Тип                                      | Опис                                                                                                                                                                                                                                          |
+| ------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `(ctx?: RuleContext) => Promise<number>` | Іменований експорт. Запускає стандартний пайплайн правила (`applies → JS-concerns → policy → mdc-refs`) для директорії, у якій знаходиться `fix.mjs`. Повертає `0` при відсутності порушень і `1` (або інший ненульовий код) у разі порушень. |
+
+Файл **не має** `default`-експорту. Side-effect на верхньому рівні: якщо модуль завантажено як CLI-entry (`isRunAsCli(import.meta.url) === true`), виконується `await runRuleCli(...)` і `process.exit(...)`.
+
+### Тип `RuleContext`
+
+Тип параметра `ctx` імпортується (через JSDoc `@typedef`) з `../../scripts/lib/run-standard-rule.mjs`. Зазвичай містить:
+
+- `walkCache` — кеш обходу файлової системи, щоб не сканувати дерево повторно для кожного правила.
+- Інші поля, специфічні для оркестрації (логер, прапорці `dryRun`, тощо).
+
+Параметр `ctx` опціональний: якщо файл запущено окремо (standalone), `ctx` буде `undefined`, і `runStandardRule()` сам створить локальний контекст.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура:** `function run(ctx?: RuleContext): Promise<number>`
+- **Параметри:**
+  - `ctx` _(опціональний, `RuleContext`)_ — контекст прогону, який зазвичай передає оркестратор `@nitra/cursor`. У ньому, серед іншого, може бути `walkCache` для уникнення повторного сканування файлової системи між різними правилами.
+- **Повертає:** `Promise<number>` — асинхронний код виходу:
+  - `0` — правило відпрацювало без порушень (OK);
+  - `1` (або інший ненульовий код, який повертає `runStandardRule`) — знайдено порушення.
+- **Side effects:**
+  - Викликає `runStandardRule()`, яка послідовно виконує етапи `applies → JS-concerns → policy → mdc-refs`. Ці етапи можуть:
+    - читати файли у репозиторії;
+    - запускати JS-перевірки (наприклад, статичні правила з директорії `js/`);
+    - виконувати policy-перевірки (наприклад, `policy/`-перевірки правила `tauri`);
+    - порівнювати посилання у `.mdc`-файлах (`mdc-refs`).
+  - Сам по собі `run()` **не змінює** файли (правило `fix`-типу може здійснювати автозаміни всередині `runStandardRule`, якщо це закладено у бібліотеці; у самому `fix.mjs` цієї логіки немає).
+- **Як використовується:** оркестратор CLI імпортує `fix.mjs` правила і викликає `await run(ctx)`. Результат складається у загальний summary прогону.
+
+### Standalone-блок (top-level)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Призначення:** дозволяє запускати правило напряму, без проходження через головний CLI `@nitra/cursor`. Команда `bun npm/rules/tauri/fix.mjs` стає повним еквівалентом `npx @nitra/cursor fix tauri`.
+- **Логіка:**
+  - `isRunAsCli(import.meta.url)` повертає `true`, якщо поточний модуль є точкою входу процесу (а не imported-модулем). Це класична перевірка ESM-еквівалента `require.main === module`.
+  - Якщо `true`, викликається `runRuleCli(import.meta.dirname)`, яка обгортає `runStandardRule` додатковою CLI-логікою: завантаження конфігу проєкту, обробка whitelist (виключень), виведення summary у консоль.
+  - `process.exit(...)` із цим кодом — обов’язковий для CI/IDE: процес має повернути ненульовий код у разі порушень, щоб pipeline (наприклад, у `n-cursor` чи у GitHub Actions) міг це задетектити. Тому ESLint-правила `n/no-process-exit` і `unicorn/no-process-exit` навмисно вимкнено через inline-коментар.
+- **Side effects:**
+  - Може писати у `stdout`/`stderr` (summary, помилки).
+  - Завершує процес викликом `process.exit(...)` — після цього рядка код не виконується.
+  - **Не виконується** у library mode (коли файл імпортовано іншим скриптом).
+
+## Залежності
+
+### Внутрішні (relative imports)
+
+| Імпорт            | Шлях                                      | Призначення                                                                                                |
+| ----------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Утиліта-перевірка: чи запущено файл як головний модуль (entry-point), а не як `import`.                    |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Standalone-обгортка над `runStandardRule`: завантаження конфігу, whitelist, summary, exit-code.            |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Бібліотечна функція, що виконує стандартний пайплайн правила: `applies → JS-concerns → policy → mdc-refs`. |
+
+Усі шляхи відносні: `../../scripts/lib/` → `npm/scripts/lib/`.
+
+### Зовнішні
+
+Файл **не має** прямих залежностей від npm-пакетів. Усі npm-залежності, якщо такі є, прихилені всередині бібліотечних функцій (`runStandardRule`, `runRuleCli`).
+
+### Контекст домену
+
+Директорія `npm/rules/tauri/` містить також:
+
+- `tauri.mdc` — людиночитна специфікація правила (формат Cursor `.mdc`);
+- `meta.json` — метадані правила (наприклад, прапорці `worktree`, опис);
+- `js/` — JS-частина перевірок правила (запускається на етапі JS-concerns);
+- `policy/` — policy-перевірки (rego/інші) на етапі policy.
+
+`runStandardRule` неявно «знає», як обробити кожен з цих артефактів, через переданий `import.meta.dirname`.
+
+## Потік виконання / Використання
+
+### Library mode (типовий, через оркестратор)
+
+1. Користувач запускає `npx @nitra/cursor fix` (або підкоманду, що зачіпає правило `tauri`).
+2. Оркестратор `@nitra/cursor`:
+   1. Знаходить директорію `npm/rules/tauri/`.
+   2. Виконує `const mod = await import('npm/rules/tauri/fix.mjs')`.
+   3. Перевірка `isRunAsCli(import.meta.url)` повертає `false` (бо це import, а не entry-point) — standalone-блок **не виконується**.
+   4. Викликає `await mod.run(ctx)`, передаючи спільний контекст (з `walkCache` тощо).
+3. `run(ctx)` → `runStandardRule(import.meta.dirname, ctx)` → послідовно виконуються етапи:
+   - **applies** — фільтрація: чи правило взагалі застосовне до поточного репозиторію/файлів.
+   - **JS-concerns** — JS-перевірки з директорії `js/` правила.
+   - **policy** — policy-перевірки з директорії `policy/` правила.
+   - **mdc-refs** — перевірка посилань у `.mdc` файлах правила.
+4. Повертається `Promise<number>` із кодом виходу для цього правила, який оркестратор агрегує у summary всіх правил.
+
+### Standalone mode (debug / прямий запуск)
+
+```bash
+bun npm/rules/tauri/fix.mjs
+```
+
+1. Bun завантажує файл як головний модуль.
+2. `import { isRunAsCli, runRuleCli, runStandardRule }` — підвантажуються залежності.
+3. Експорт `run` стає доступним (але ніхто його не викликає у цьому режимі).
+4. Виконується top-level `if (isRunAsCli(import.meta.url))`:
+   - `isRunAsCli(...) === true`.
+   - `await runRuleCli(import.meta.dirname)`:
+     - завантажує конфіг проєкту;
+     - застосовує whitelist;
+     - всередині викликає `runStandardRule(dir, ctx)` (з локально-створеним контекстом);
+     - виводить summary у консоль.
+   - `process.exit(<code>)` — процес завершується з кодом `0` (OK) або `1` (порушення).
+
+### Дві ролі одного файлу
+
+Архітектурний прийом — **«library + main» в одному файлі** — закладений у коментарі коду:
+
+> Дві ролі fix.mjs: library (run) + standalone (main).
+
+Це дозволяє:
+
+- розробнику швидко налагоджувати правило окремо (`bun rules/tauri/fix.mjs`);
+- оркестратору повторно використовувати кеш обходу (`walkCache`) між правилами під час масового прогону.
+
+## Rebuild Test
+
+Файл є **тонким адаптером** і не містить доменної логіки — його можна повністю відтворити за цією документацією. Структура:
+
+1. Два іменовані імпорти з `../../scripts/lib/run-rule-cli.mjs`: `isRunAsCli`, `runRuleCli`.
+2. Один іменований імпорт з `../../scripts/lib/run-standard-rule.mjs`: `runStandardRule`.
+3. JSDoc-блок із описом, типом параметра `ctx` (через `@param {import('...')...}`) і типом результату (`Promise<number>`).
+4. `export function run(ctx) { return runStandardRule(import.meta.dirname, ctx) }`.
+5. Top-level `if (isRunAsCli(import.meta.url))` з викликом `process.exit(await runRuleCli(import.meta.dirname))` і inline-коментарем-вимкненням ESLint-правил `n/no-process-exit` та `unicorn/no-process-exit`.
+
+Жодних інших артефактів (інших експортів, констант, побічних `console.log`, мутації глобального стану) у файлі немає.