@nitra/cursor 5.3.4 → 5.4.0

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

@@ -1,164 +1,30 @@
 ---
 docgen:
   source: npm/rules/style-lint/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# fix.mjs — точка входу правила `style-lint`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/style-lint/fix.mjs` — це точка входу (entry-point) правила з ідентифікатором `style-lint` у системі `@nitra/cursor`. Він виконує дві ролі одночасно:
+Файл застосовує визначене правило до вхідного контексту прогону. Застосовує правило та повертає отриманий результат.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку зовнішній CLI-оркестратор (`npx @nitra/cursor fix <id>` чи внутрішній диспетчер правил) імпортує й запускає в межах загального прогону пакета правил.
-2. **Standalone mode** — якщо файл запущено напряму через `bun rules/style-lint/fix.mjs`, він самостійно ініціалізує конфіг, whitelist, summary та повертає exit-code, повністю еквівалентний виклику `npx @nitra/cursor fix style-lint`.
+## Поведінка
 
-Сам файл навмисно тонкий: вся логіка перевірок винесена у спільні утиліти `runStandardRule` (стандартний пайплайн правила: `applies → JS-concerns → policy → mdc-refs`) і `runRuleCli` (обгортка для standalone-запуску). Це канонічна форма entry-point для будь-якого правила в монорепо `@nitra/cursor`, що дозволяє додавати нові правила, не дублюючи orchestration-код.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує правило.
+    *   Повертає результат.
 
-Правило `style-lint` оперує над стилями (Style/CSS-частина) — деталі його перевірок мешкають у сусідніх теках (`js/`, `policy/`, `style-lint.mdc`), але сам цей файл їх не імпортує: пайплайн виявляє їх автоматично за конвенцією директорії `import.meta.dirname`.
+## Публічний API
 
-## Експорти / API
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-| Експорт | Тип                                               | Призначення                                                                                                   |
-| ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function (ctx?: RuleContext) => Promise<number>` | Запускає стандартний пайплайн правила `style-lint`. Повертає `0` за відсутності порушень, `1` — за наявності. |
+## Гарантії поведінки
 
-Експорт `run` — це **публічний контракт правила**. Будь-який оркестратор, що знає лише шлях до директорії правила, може динамічно імпортувати `fix.mjs` і викликати `run(ctx)`.
-
-Жодних інших іменованих експортів, default-експорту, констант чи класів файл не надає.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` (необов'язковий) — об'єкт контексту прогону типу `RuleContext` (визначений у `../../scripts/lib/run-standard-rule.mjs`). Містить, зокрема, `walkCache` — кеш обходу файлової системи, який оркестратор переюзує між правилами, щоб не сканувати дерево повторно. Якщо `ctx` не передано — `runStandardRule` створить дефолтний контекст самостійно.
-- **Повертає:** `Promise<number>` — exit-code:
-  - `0` — правило виконано, порушень не знайдено;
-  - `1` — знайдено порушення (CI має зафейлити збірку).
-- **Side effects:**
-  - Звертається до файлової системи через `runStandardRule` (читає файли проєкту, що підпадають під `applies`-фільтр правила).
-  - Може писати у stdout/stderr (summary, помилки) через утиліти всередині `runStandardRule`.
-  - Сам по собі функція **не** мутує жодного файлу — навіть для правил із суфіксом `fix.mjs` пайплайн у режимі звичайного прогону є read-only (модифікації виконуються в окремих fix-режимах, які тут не задіяні).
-- **Як працює:** делегує всю роботу `runStandardRule`, передаючи їй власну директорію (`import.meta.dirname` = абсолютний шлях до `npm/rules/style-lint/`). Пайплайн всередині послідовно прогонить чотири фази:
-  1. **applies** — визначення, які файли проєкту підпадають під дію правила;
-  2. **JS-concerns** — JS/MJS-перевірки (логіка з `js/`);
-  3. **policy** — Rego/політики (логіка з `policy/`);
-  4. **mdc-refs** — звірення посилань у `style-lint.mdc` (актуальність документації).
-
-### Standalone-блок (top-level `if`)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Не функція**, а top-level guard, що виконується лише коли файл стартує безпосередньо як CLI-точка (а не імпортується іншим модулем).
-- **Детект:** `isRunAsCli(import.meta.url)` повертає `true`, коли `import.meta.url` відповідає аргументу запуску процесу (тобто `bun npm/rules/style-lint/fix.mjs` чи `node npm/rules/style-lint/fix.mjs`).
-- **Дія:** викликає `runRuleCli(import.meta.dirname)`, яка проганяє повний цикл CLI (config-loading, whitelist, summary, exit-code) і завершує процес через `process.exit` зі здобутим кодом.
-- **Чому `await` на верхньому рівні:** файл — ES-модуль `.mjs`, top-level `await` дозволений.
-- **Eslint-винятки:** `n/no-process-exit` та `unicorn/no-process-exit` навмисно відключені рядковим коментарем, бо для standalone entry-point явний `process.exit` — єдиний коректний спосіб віддати exit-code CI/IDE.
-
-## Залежності
-
-### Внутрішні (relative imports)
-
-| Модуль                                    | Що з нього імпортовано     | Роль                                                                                                                           |
-| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Утиліти standalone-режиму: детект CLI-запуску та повний CLI-цикл (config + whitelist + summary).                               |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний пайплайн правила (applies → JS-concerns → policy → mdc-refs). Також надає тип `RuleContext` (через JSDoc-typedef). |
-
-Шляхи `../../scripts/lib/...` обчислюються відносно `npm/rules/style-lint/` і вказують на `npm/scripts/lib/`.
-
-### Зовнішні
-
-- **Жодних** npm-пакетів файл напряму не імпортує. Усі залежності — внутрішні.
-- **Runtime:** Node.js / Bun з підтримкою ESM, `import.meta.url`, `import.meta.dirname` та top-level `await`.
-
-### Сусідні артефакти правила (не імпортуються тут, але задіяні через пайплайн)
-
-- `npm/rules/style-lint/meta.json` — метадані правила (id, applies-патерни тощо), читається `runStandardRule`/`runRuleCli`.
-- `npm/rules/style-lint/style-lint.mdc` — людиночитна специфікація правила (target для mdc-refs-фази).
-- `npm/rules/style-lint/js/` — JS-частина перевірок (підвантажується JS-concerns-фазою).
-- `npm/rules/style-lint/policy/` — Rego-політики (підвантажуються policy-фазою).
-
-## Потік виконання / Використання
-
-### Сценарій A — імпорт оркестратором (library mode)
-
-```text
-@nitra/cursor CLI (або інший runner)
-        │
-        │ dynamic import('npm/rules/style-lint/fix.mjs')
-        ▼
-fix.mjs → export run(ctx)
-        │
-        │ runStandardRule(import.meta.dirname, ctx)
-        ▼
-run-standard-rule.mjs
-        │
-        ├── applies-фаза (фільтр файлів)
-        ├── JS-concerns-фаза (js/)
-        ├── policy-фаза (policy/)
-        └── mdc-refs-фаза (style-lint.mdc)
-        │
-        ▼
-        return 0 | 1
-```
-
-Оркестратор зазвичай передає `ctx` із попередньо побудованим `walkCache`, щоб уникнути повторного обходу файлового дерева між десятками правил.
-
-### Сценарій B — пряма CLI-точка (standalone mode)
-
-```text
-$ bun npm/rules/style-lint/fix.mjs
-        │
-        │ Node/Bun завантажує fix.mjs як головний модуль
-        ▼
-import-блок виконано → run експортовано
-        │
-        ▼
-top-level if (isRunAsCli(import.meta.url))   // true
-        │
-        │ await runRuleCli(import.meta.dirname)
-        ▼
-run-rule-cli.mjs
-        │
-        ├── завантажує конфіг проєкту
-        ├── застосовує whitelist
-        ├── викликає внутрішньо аналог run(ctx)
-        ├── друкує summary
-        └── повертає number (exit-code)
-        │
-        ▼
-process.exit(<exit-code>)
-```
-
-Цей режим використовується розробником локально (`bun npm/rules/style-lint/fix.mjs`) або IDE-інтеграцією, що очікує POSIX exit-code.
-
-### Інваріанти та контракт
-
-- Файл — **stateless**: жодних модульних змінних, кешів, синглтонів. Усе передається через `ctx`.
-- Функція `run` **ідемпотентна** щодо файлової системи (read-only прогон).
-- `run` **завжди** повертає `Promise<number>` зі значенням `0` або `1` — оркестратор не повинен очікувати інших значень чи кидків.
-- Standalone-блок виконується **виключно** коли файл — головний модуль; при `import` із іншого коду блок мовчазно пропускається завдяки `isRunAsCli`.
-
-### Як додати аналогічний entry-point для нового правила
-
-1. Створити теку `npm/rules/<new-rule-id>/`.
-2. Скопіювати цей `fix.mjs` без змін (шляхи відносні до `npm/rules/<id>/` ідентичні).
-3. Покласти поруч `meta.json`, `<new-rule-id>.mdc`, `js/`, `policy/` за потреби.
-4. Пайплайн `runStandardRule` підхопить нове правило автоматично, без правок самого `fix.mjs`.
-
-Це і є цінність «тонкого» entry-point: правила додаються декларативно, без дублювання orchestration-логіки.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,184 +1,33 @@
+---
+docgen:
+  source: npm/rules/style-lint/js/lint.mjs
+  crc: 94e067b3
+  score: 100
+---
+
 # 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».
+filterStyleFiles
+Вибирає файли, що мають розширення .css, .scss або .vue.
 
-### Як вписується в загальну архітектуру
+lint
+Запускає команду stylelint з опцією --fix для перевірки та виправлення стилів.
 
-Цей файл — реалізаційна одиниця «quick» кроку правила `style-lint`. Правило в монорепо має дві площини запуску:
+## Поведінка
 
-- **quick** (швидкий) — викликається після зміни файлів локально, працює тільки по зміненому списку для мінімального часу відгуку.
-- **ci** — викликається в неперервній інтеграції, проганяє по всьому glob-у щоб гарантовано перевірити весь репозиторій.
+filterStyleFiles
+фільтрує список файлів, повертаючи лише ті, що закінчуються на .css, .scss або .vue
 
-Файл `lint.mjs` уніфікує обидва режими в одній функції, де перемикач режиму — це `files === undefined` (ci) vs `files: string[]` (quick).
+lint
+запускає команду stylelint з опцією --fix для перевірки та виправлення стилів
 
-### Контракти й гарантії
+## Публічний API
 
-- Функція `lint` **синхронно** виконує дочірній процес, але повертає `Promise<number>` — це навмисно, щоб уніфікувати інтерфейс з іншими «крок-функціями» в системі правил, які можуть бути по-справжньому асинхронні. Caller завжди робить `await lint(...)`.
-- `lint` не кидає виключень: будь-який збій `npx` (включаючи відсутній бінарник) перетвориться в exit-код `1` через гілку `typeof r.status === 'number' ? r.status : 1`. Це робить функцію передбачуваною для оркестратора, який оперує тільки числовими кодами.
-- `filterStyleFiles` — стабільна чиста функція, придатна для незалежного юніт-тестування (саме тому винесена як окремий експорт).
+filterStyleFiles відбирає файли за стилем
 
-## Rebuild Test
+## Гарантії поведінки
 
-Документація відповідає коду версії на момент написання: 35 рядків, два експорти (`filterStyleFiles`, `lint`), одна приватна регулярка (`STYLE_EXT_RE`), одна імпортована функція з `node:child_process` (`spawnSync`). Якщо файл буде переписано (наприклад, додасться третій експорт, зміниться сигнатура `lint`, з'явиться нова гілка для `--config`, або `spawnSync` буде замінено на асинхронний `spawn`), цей документ потребує перегенерації.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -1,194 +1,29 @@
-# 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-код, а викликаюча сторона сама вирішує, як його використати.
-
+---
+docgen:
+  source: npm/rules/style-lint/js/tooling.mjs
+  crc: 631f5de8
+  score: 80
 ---
 
-### `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)
-```
+# tooling.mjs
 
-Або через CLI-обгортку:
+## Огляд
 
-```bash
-npx @nitra/cursor check
-```
+Файл виконує перевірку конфігурації stylelint та файлів, пов'язаних з лінтуванням. Перевірка включає наявність конфігурації stylelint у `package.json` або зовнішньому файлі, файлів конфігу stylelint у директорії, файлів ігнорування stylelint та файлу workflow для лінтування.
 
-(CLI сам знайде цей модуль за конвенцією `npm/rules/<rule>/js/tooling.mjs` і викличе `check()` без аргументів, тож буде використано `process.cwd()`.)
+## Поведінка
 
-### Гарантії та межі відповідальності
+1. Перевірити наявність конфігурації stylelint у package.json або зовнішньому файлі
+2. Перевірити наявність файлів конфігу stylelint у директорії
+3. Перевірити наявність файлів ігнорування stylelint
+4. Перевірити наявність файлу workflow для лінтування
 
-- Модуль **не змінює** файли (немає `fix`-режиму) — він тільки **репортує**.
-- Він **не дублює** перевірок, які вже робить Rego. Розділення: FS / cross-file → JS (тут); формат / структура одного файлу → Rego.
-- Виклик `check` із `cwd`, де немає `package.json`, — валідний сценарій: перевірка конфігу stylelint буде пропущена (мовчки), решта перевірок (`.stylelintignore`, workflow) — виконається.
-- Якщо `package.json` містить невалідний JSON — функція впаде з `SyntaxError` (це не пере́хоплюється навмисно: гнилий JSON — це самостійна проблема, яку треба чути одразу).
+## Публічний API
 
-## Rebuild Test
+check — Перевіряє відповідність проєкту правилам style-lint.mdc
 
-З цього документа можна повністю відновити поведінку файлу:
+## Гарантії поведінки
 
-- Знаючи список перевірок (конфіг stylelint, `.stylelintignore`, `lint-style.yml`), повідомлення `pass`/`fail` і допустимі імена файлів-конфігів — реалізація відтворюється 1:1.
-- Деталі контракту функцій (типи параметрів, тип повернення, side effects, поведінка за відсутності `package.json`) описані явно.
-- Експорти та їх кількість (єдиний експорт `check`) зафіксовано.
-- Імпорти Node-модулів і внутрішні залежності перераховано вичерпно.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.