@nitra/cursor 12.6.1 → 12.8.0

package/rules/security/fix.mjs

@@ -1,18 +0,0 @@
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * Library mode: викликається CLI orchestration через `import + run(ctx)`.
- * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
- * @returns {Promise<number>} 0 — OK, 1 — порушення
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
-  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  process.exitCode = await runRuleCli(import.meta.dirname)
-}

package/rules/security/js/docs/lint.md

@@ -1,175 +0,0 @@
----
-type: JS Module
-title: lint.mjs
-resource: npm/rules/security/js/lint.mjs
-docgen:
-  crc: f3265f82
----
-
-Файл `npm/rules/security/js/lint.mjs` реалізує CI-крок правила **security** для пошуку секретів у репозиторії. Це обгортка над зовнішнім інструментом [TruffleHog](https://github.com/trufflesecurity/trufflehog), яка запускає сканування всього робочого дерева (`filesystem` mode) і повертає його exit-код як результат лінтингу.
-
-Особливості:
-
-- **Repo-wide, а не per-file.** Модуль свідомо ігнорує перший аргумент `_files` — TruffleHog у режимі `filesystem` обробляє кореневу теку цілком і завжди сканує однаковий набір шляхів, незалежно від того, які саме файли передає рушій правил. Тому пер-файлового різновиду немає; результат однаковий для будь-якого підмножина файлів.
-- **Один прохід на сесію.** Сканер виконується синхронно через `spawnSync`, що відповідає правилу «без паралельних лінт-запусків» у монорепо.
-- **Контрактний інтерфейс.** Експорт `lint(files, cwd)` сумісний із загальним контрактом per-rule lint-функцій (`(files?, cwd?) => Promise<number>`), що дозволяє інтегрувати security-правило в загальний раннер однаково з іншими.
-
-Файл не має побічних ефектів на момент імпорту: запуск зовнішнього процесу відбувається лише при виклику `lint()`.
-
-## Експорти / API
-
-| Експорт | Тип                       | Призначення                                                                                             |
-| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `lint`  | `function` (named export) | Запускає TruffleHog filesystem-скан із кореня `cwd` і повертає `Promise<number>` із exit-кодом процесу. |
-
-Default-експорту немає. Імпорт відбувається у вигляді:
-
-```js
-import { lint } from './lint.mjs'
-```
-
-## Функції
-
-### `lint(_files, cwd?)`
-
-**Сигнатура:**
-
-```js
-export function lint(_files, cwd = process.cwd()) => Promise<number>
-```
-
-**Параметри:**
-
-| Параметр | Тип                     | Обовʼязковий | За замовчанням  | Опис                                                                                                                                                             |
-| -------- | ----------------------- | ------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_files` | `string[] \| undefined` | ні           | —               | Список файлів від рушія правил. **Ігнорується**: TruffleHog у `filesystem`-режимі сканує дерево цілком. Префікс `_` у JSDoc сигналізує про навмисне ігнорування. |
-| `cwd`    | `string`                | ні           | `process.cwd()` | Робоча тека, у якій запускається TruffleHog. Сканування `.` виконуватиметься відносно неї.                                                                       |
-
-**Повертає:**
-
-`Promise<number>` — exit-код процесу TruffleHog:
-
-- `0` — секретів не знайдено (успіх).
-- Будь-яке інше число — або знайдено секрети, що відповідають критеріям `--results=verified,unknown` (через флаг `--fail`), або TruffleHog не зміг запуститись/упав.
-- `1` — fallback, який повертається, якщо `r.status` не є числом (наприклад, процес було вбито сигналом і `status === null`).
-
-**Side effects:**
-
-1. Запускає синхронний дочірній процес `trufflehog` через `node:child_process#spawnSync`.
-2. `stdio: 'inherit'` — stdout/stderr/stdin успадковуються з батьківського процесу; вивід TruffleHog потрапляє безпосередньо в консоль CI-runner.
-3. Блокує event loop до завершення процесу (`spawnSync` синхронний; результат лише обгортається у `Promise.resolve`).
-4. Не записує файли, не модифікує env, не змінює стан модуля.
-
-**Внутрішня механіка:**
-
-Викликається TruffleHog із набором аргументів:
-
-| Аргумент                     | Значення                                                                                                                         |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| Команда                      | `trufflehog` (резолвиться через `PATH`)                                                                                          |
-| Subcommand                   | `filesystem`                                                                                                                     |
-| Шлях                         | `.` (відносно `cwd`)                                                                                                             |
-| `--no-update`                | Не намагатися автооновити сам TruffleHog у CI.                                                                                   |
-| `--exclude-paths`            | `.trufflehog-exclude` — файл зі шляхами/патернами, які виключити зі сканування. Має лежати в `cwd`.                              |
-| `--results=verified,unknown` | Звітувати лише **верифіковані** секрети та секрети **невідомого** статусу верифікації (відсікти `unverified`, щоб зменшити шум). |
-| `--fail`                     | Завершуватись із ненульовим exit-кодом, якщо знайдено результати, що відповідають фільтру вище.                                  |
-
-Параметри `spawnSync`:
-
-- `cwd` — переданий або `process.cwd()`.
-- `stdio: 'inherit'` — прямий проброс I/O.
-
-Після завершення:
-
-```js
-return Promise.resolve(typeof r.status === 'number' ? r.status : 1)
-```
-
-— безпечна нормалізація: якщо `status` відсутній (наприклад, процес перерваний сигналом → `r.status === null`, `r.signal === 'SIGTERM'`), функція повертає `1` як індикатор помилки.
-
-**Контрактні нотатки:**
-
-- Функція **не кидає виключення** для звичайних випадків (TruffleHog знайшов секрети або не запустився) — все нормалізується в exit-код через `Promise.resolve`. Якщо `spawnSync` сам кине синхронне виключення (наприклад, ENOENT через відсутність бінарника та некоректну поведінку runtime), воно пробʼється вгору — але стандартна поведінка Node для відсутнього виконуваного файлу — повернути `r.error`, а `r.status === null`, тому функція дасть `1`.
-- Поверне `Promise`, навіть якщо все відбулось синхронно — це потрібно для уніфікованого `await` у виклику з рушія правил.
-
-## Залежності
-
-### Зовнішні (npm) бібліотеки
-
-Жодних — модуль не імпортує сторонні пакети.
-
-### Стандартна бібліотека Node.js
-
-- **`node:child_process`** — використовується `spawnSync` для синхронного запуску `trufflehog`. Імпорт із префіксом `node:` обовʼязковий за правилами проекту.
-
-### Системні залежності
-
-- **`trufflehog`** (бінарник) — має бути доступний у `PATH` середовища, де запускається CI-крок. Інакше `spawnSync` поверне об'єкт із `error` (ENOENT) та `status === null`, і функція віддасть `1`.
-- **Файл `.trufflehog-exclude`** — очікується у корені `cwd`. Це plaintext-файл із патернами шляхів для виключення (формат TruffleHog `--exclude-paths`). Якщо файл відсутній, TruffleHog може завершитись із ненульовим кодом — це теж буде повернуто як exit-код.
-
-### Внутрішні модулі
-
-- Зовнішніх внутрішньопроєктних імпортів модуль не має. Він самодостатній і викликається рушієм правил security (`npm/rules/security/...`), який інтегрує його у загальний lint-пайплайн.
-
-## Потік виконання / Використання
-
-### Загальний потік
-
-1. Рушій правил (npm-пакет, що оркеструє лінтери) виявляє правило `security` для активного workspace.
-2. Викликає `lint(files, cwd)` із `files` (списком змінених/вибраних файлів) та `cwd` (коренем workspace або репо).
-3. `lint`:
-   - Ігнорує `files`.
-   - Викликає `spawnSync('trufflehog', [...], { cwd, stdio: 'inherit' })`.
-   - Користувач/CI бачить весь stdout/stderr TruffleHog у реальному часі.
-   - Після завершення процесу повертає `Promise<exitCode>`.
-4. Рушій правил агрегує exit-коди всіх лінтерів і визначає загальний результат (зазвичай: будь-яке ненульове значення = провал CI).
-
-### Типовий виклик з коду
-
-```js
-import { lint } from './lint.mjs'
-
-const exitCode = await lint(undefined, process.cwd())
-if (exitCode !== 0) {
-  console.error('[security] TruffleHog знайшов секрети або не зміг виконатись')
-  process.exitCode = exitCode
-}
-```
-
-### CI-сценарій
-
-1. CI-runner клонує репозиторій і встановлює бінарник `trufflehog` (через apt/brew/curl/прекомпільований release).
-2. Запускається `n-cursor lint` (або еквівалент), який обходить правила.
-3. Для правила `security` рушій кличе цю `lint`-функцію.
-4. TruffleHog рекурсивно сканує всі файли під `cwd`, окрім перелічених у `.trufflehog-exclude`.
-5. Якщо знайдено **верифіковані** або **unknown**-секрети — повертається ненульовий exit-код, флаг `--fail` гарантує цю поведінку.
-6. CI завершується із помилкою, кроки нижче не виконуються.
-
-### Граничні випадки
-
-| Ситуація                        | Поведінка                                                                                                                                                                   |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `trufflehog` відсутній у `PATH` | `spawnSync` повертає `r.status === null`, функція віддає `1`. У stderr (через `inherit`) може зʼявитись повідомлення Node про відсутність бінарника, залежно від платформи. |
-| `.trufflehog-exclude` відсутній | TruffleHog зазвичай помиляється з ненульовим кодом — функція поверне його як є.                                                                                             |
-| Процес вбито сигналом           | `r.status === null` → повертається `1`.                                                                                                                                     |
-| Секретів немає                  | TruffleHog повертає `0` → функція повертає `0`.                                                                                                                             |
-| Передано `files=[...]`          | Аргумент проігноровано; сканування все одно зачіпає всю теку `cwd`.                                                                                                         |
-| `cwd` не вказано                | Використовується `process.cwd()` поточного Node-процесу.                                                                                                                    |
-
-### Конфігураційні «крутилки»
-
-Самі прапори зашиті в код і не параметризуються через аргументи функції. Якщо потрібно змінити поведінку (інший шлях `--exclude-paths`, інші типи результатів, увімкнути `--update`), правки робляться безпосередньо в `lint.mjs` — це навмисно, щоб уніфіковано тримати security-політику для всього монорепо.
-
-## Rebuild Test
-
-Перевірка контракту (для майбутніх refactor-ів — поведінка має зберігатись):
-
-1. **Експорт** named `lint` присутній; default-експорту немає.
-2. **Сигнатура** `lint(_files, cwd = process.cwd())` повертає `Promise<number>`.
-3. **Викликана команда** — рівно `trufflehog` із аргументами у точному порядку:
-   `filesystem`, `.`, `--no-update`, `--exclude-paths`, `.trufflehog-exclude`, `--results=verified,unknown`, `--fail`.
-4. **Options** для `spawnSync`: `{ cwd, stdio: 'inherit' }`.
-5. **Нормалізація exit-коду**: число → пробрасується; не число → `1`.
-6. **`_files` ігнорується** — наявність/відсутність/вміст не змінює викликаних аргументів TruffleHog.
-7. **Імпорт `child_process`** — лише через `node:`-префікс.
-8. **Жодних побічних ефектів на імпорті** — `lint` запускає процес лише при виклику.

package/rules/security/js/lint.mjs

@@ -1,26 +0,0 @@
-/**
- * Ci-крок security: trufflehog filesystem скан усього репо (per-file немає).
- */
-import { spawnSync } from 'node:child_process'
-
-/**
- * @param {string[] | undefined} _files ігнорується
- * @param {string} [cwd] корінь
- * @returns {Promise<number>} exit code
- */
-export function lint(_files, cwd = process.cwd()) {
-  const r = spawnSync(
-    'trufflehog',
-    [
-      'filesystem',
-      '.',
-      '--no-update',
-      '--exclude-paths',
-      '.trufflehog-exclude',
-      '--results=verified,unknown',
-      '--fail'
-    ],
-    { cwd, stdio: 'inherit' }
-  )
-  return Promise.resolve(typeof r.status === 'number' ? r.status : 1)
-}

package/rules/style-lint/fix.mjs

@@ -1,18 +0,0 @@
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * Library mode: викликається CLI orchestration через `import + run(ctx)`.
- * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
- * @returns {Promise<number>} 0 — OK, 1 — порушення
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
-  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  process.exitCode = await runRuleCli(import.meta.dirname)
-}

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

@@ -1,31 +0,0 @@
----
-type: JS Module
-title: lint.mjs
-resource: npm/rules/style-lint/js/lint.mjs
-docgen:
-  crc: 2013a66b
-  score: 100
----
-
-filterStyleFiles
-Вибирає файли, що мають розширення .css, .scss або .vue.
-
-lint
-Запускає команду stylelint з опцією --fix для перевірки та виправлення стилів.
-
-## Поведінка
-
-filterStyleFiles
-фільтрує список файлів, повертаючи лише ті, що закінчуються на .css, .scss або .vue
-
-lint
-запускає команду stylelint з опцією --fix для перевірки та виправлення стилів
-
-## Публічний API
-
-filterStyleFiles відбирає файли за стилем
-
-## Гарантії поведінки
-
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.

package/rules/tauri/fix.mjs

@@ -1,18 +0,0 @@
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * Library mode: викликається CLI orchestration через `import + run(ctx)`.
- * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
- * @returns {Promise<number>} 0 — OK, 1 — порушення
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
-  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  process.exitCode = await runRuleCli(import.meta.dirname)
-}

package/rules/test/fix.mjs

@@ -1,18 +0,0 @@
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * Library mode: викликається CLI orchestration через `import + run(ctx)`.
- * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
- * @returns {Promise<number>} 0 — OK, 1 — порушення
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
-  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  process.exitCode = await runRuleCli(import.meta.dirname)
-}

package/rules/text/fix.mjs

@@ -1,18 +0,0 @@
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * Library mode: викликається CLI orchestration через `import + run(ctx)`.
- * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
- * @returns {Promise<number>} 0 — OK, 1 — порушення
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
-  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  process.exitCode = await runRuleCli(import.meta.dirname)
-}

package/rules/text/js/docs/lint.md

@@ -1,23 +0,0 @@
----
-type: JS Module
-title: lint.mjs
-resource: npm/rules/text/js/lint.mjs
-docgen:
-  crc: eca3c531
-  score: 100
----
-
-Файл надає функцію lint, яка делегує завдання CLI правилам. Функція не підтримує режим per-file, і параметр files ігнорується. Функція повертає Promise з кодом виходу.
-
-## Поведінка
-
-1. Викликається функція lint з аргументом files.
-2. Функція lint делегує виконання у CLI правила.
-3. Режим per-file не підтримується.
-4. Параметр files ігнорується.
-5. Функція повертає Promise з кодом виходу.
-
-## Гарантії поведінки
-
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.

package/rules/text/js/lint.mjs

@@ -1,15 +0,0 @@
-/**
- * Крок text: делегує у наявний CLI правила (per-file режиму немає — `files` ігнорується).
- */
-import { runLintTextCli } from '../lint/lint.mjs'
-
-/**
- * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
- * @param {string} [_cwd] корінь (ігнорується — CLI працює від process.cwd())
- * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу (нуль мутацій);
- *   llmFix → opt-in omlx-класифікація cspell (з `meta.json: llmFix:true`)
- * @returns {Promise<number>} exit code
- */
-export function lint(_files, _cwd, opts = {}) {
-  return runLintTextCli({ readOnly: opts.readOnly === true, llmFix: opts.llmFix === true })
-}

package/rules/text/lint/docs/cspell-fix.md

@@ -1,32 +0,0 @@
----
-type: JS Module
-title: cspell-fix.mjs
-resource: npm/rules/text/lint/cspell-fix.mjs
-docgen:
-  crc: 7b40e8f9
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 95
-  issues: anchor-miss:meta.json,judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Цей модуль інтегрує cspell у ланцюжок lint-text для класифікації невідомих слів згідно зі схемою omlx. Він витягує невідомі слова, класифікує їх за допомогою LLM (detect $\rightarrow$ omlx-класифікація) та автоматично дописує валідні терміни до словника `.cspell.json`. Нерозкласифіковані та ймовірні одруки залишаються для ручного рев'ю. Процес є read-only, оскільки він лише класифікує знахідки, а не переписує файли.
-
-## Поведінка
-
-unknownWords витягує унікальні невідомі слова з виводу cspell.
-appendWordsToDict дописує класифіковані валідні слова до файлу .cspell.json, оновлюючи словник.
-runCspellText запускає cspell, класифікує знахідки за допомогою LLM (якщо увімкнено) та повторно перевіряє код, повертаючи 0 при чистоті або 1 при знахідках.
-
-## Публічний API
-
-unknownWords — Збирає унікальні слова, які не були знайдені у словнику cspell.
-appendWordsToDict — Додає зібрані слова до файлу `.cspell.json#words` у відсортованому та унікальному вигляді для перегляду у Git.
-runCspellText — Виконує перевірку тексту за допомогою cspell, класифікуючи слова та оновлюючи словник за новою схемою.
-
-## Гарантії поведінки
-
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/text/lint/docs/index.md

@@ -1,15 +0,0 @@
----
-type: Directory Index
-title: npm/rules/text/lint
-resource: npm/rules/text/lint/
----
-
-# npm/rules/text/lint
-
-| Файл | Тип |
-|---|---|
-| [cspell-fix.mjs](cspell-fix.md) | JS Module |
-| [lint.mjs](lint.md) | JS Module |
-| [run-dotenv-linter.mjs](run-dotenv-linter.md) | JS Module |
-| [run-shellcheck.mjs](run-shellcheck.md) | JS Module |
-| [run-v8r.mjs](run-v8r.md) | JS Module |

package/rules/text/lint/docs/lint.md

@@ -1,36 +0,0 @@
----
-type: JS Module
-title: lint.mjs
-resource: npm/rules/text/lint/lint.mjs
-docgen:
-  crc: 02550273
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
----
-
-runLintTextCli надає внутрішню обгортку для послідовного лінтингу текстових файлів (text.mdc). Обгортка автоматично встановлює необхідні інструменти (`shellcheck`, `dotenv-linter`) через `ensureTool` перед виконанням ланцюжка перевірок. Ланцюжок включає: перевірку правопису (`cspell`), аналіз скриптів (`shellcheck`), перевірку конфігураційних файлів (`dotenv-linter`), форматування Markdown (`markdownlint-cli2`) та валідацію схем (`v8r`). При виявленні першого ненульового коду в ланцюжку, цей код повертається як код виходу, і подальші кроки не виконуються. Зовнішня точка входу правила — `n-cursor lint text`.
-
-## Поведінка
-
-1. Викликається `runLintTextCli` для запуску процесу лінтингу.
-2. Якщо передано опцію для режиму лише перевірки, всі кроки виконуються без автоматичного виправлення.
-3. Перед виконанням лінтингу автоматично встановлюються необхідні інструменти (`shellcheck`, `dotenv-linter`).
-4. Перевіряється наявність інструменту `patch` для можливого автоматичного виправлення помилок `shellcheck`.
-5. Виконується перевірка правопису за допомогою `cspell`.
-6. Виконується автоматичне виправлення та фінальна перевірка скриптів `.sh` за допомогою `shellcheck`.
-7. Виконується автоматичне виправлення та фінальна перевірка файлів `.env*` за допомогою `dotenv-linter`.
-8. Виконується автоматичне виправлення файлів Markdown (`.md`, `.mdc`) за допомогою `markdownlint-cli2`.
-9. Виконується валідація схем для файлів JSON, JSON5, YAML, YML, TOML за допомогою `v8r`.
-10. Якщо будь-який крок повертає ненульовий код, виконання зупиняється, і повертається код цього першого невдалого кроку.
-11. У разі успішного виконання всіх кроків повертається код 0.
-12. У разі відсутності необхідних бінарників, `runLintTextCli` виводить повідомлення про помилку з інструкціями щодо встановлення (text.mdc).
-
-## Публічний API
-
-runLintTextCli — Виконує лінтинг тексту через командний інтерфейс, синхронізуючи доступ за допомогою блокування та усуваючи дублікати на основі стану Git-дерева. (text.mdc)
-
-## Гарантії поведінки
-
-- Read-only: файл не виконує операцій запису у файлову систему.
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.

package/rules/text/lint/docs/run-dotenv-linter.md

@@ -1,161 +0,0 @@
----
-type: JS Module
-title: run-dotenv-linter.mjs
-resource: npm/rules/text/lint/run-dotenv-linter.mjs
-docgen:
-  crc: 4719ac66
----
-
-Модуль `run-dotenv-linter.mjs` інкапсулює інтеграцію зовнішнього інструмента **dotenv-linter** у ланцюжок `lint-text` правила `text` (тека `npm/rules/text/lint/`). Він виконує дві послідовні фази:
-
-1. **Авто-фікс** — `dotenv-linter fix -r --no-backup --quiet . --exclude …`. dotenv-linter сам застосовує всі підтримувані виправлення на місці (на відміну від shellcheck, який лише пропонує diff).
-2. **Фінальна перевірка** — `dotenv-linter check -r --quiet . --exclude …`. Якщо лишаються порушення, їх вивід ретранслюється у `stdout`/`stderr`, а функція повертає код `1`.
-
-`dotenv-linter` — швидкий лінтер для `.env`-файлів, що ловить правила на кшталт `LowercaseKey`, `DuplicatedKey`, `IncorrectDelimiter`, `UnorderedKey` тощо. Він **очікується у `PATH`** і **не** додається в `dependencies` / `devDependencies` проєкту (та сама модель, що й `shellcheck`). Якщо бінарника немає, користувач отримує підказки встановлення (`brew`, `curl`, `cargo`), а функція повертає `1`.
-
-Файли модуль не перераховує самостійно — це робить сам `dotenv-linter` у режимі `-r` (рекурсивний обхід дерева проєкту). З обходу виключаються `node_modules` (стороння кодова база) та `.envrc` (синтаксис direnv shell, не `key=value`). Резервні `.bak`-файли інструмент ігнорує самостійно. За відсутності `.env*`-файлів `dotenv-linter` повертає `0` ("Nothing to check").
-
-Файл одночасно є **бібліотечним модулем** (експортує функцію `runDotenvLinter`) та **CLI-точкою входу**: за прямого запуску (`node run-dotenv-linter.mjs`) він викликає функцію та виставляє `process.exitCode` у її результат.
-
-## Експорти / API
-
-| Експорт                 | Тип            | Призначення                                                                                                          |
-| ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `runDotenvLinter(cwd?)` | named function | Запуск двофазного циклу `fix` + `check` для `.env`-файлів у дереві `cwd`. Повертає числовий exit-code (`0` або `1`). |
-
-Інші ідентифікатори модуля (`EXCLUDED_PATHS`, `printDotenvLinterInstallHints`, `buildExcludeArgs`) — внутрішні, **не** експортуються.
-
-## Функції
-
-### `runDotenvLinter(cwd?)`
-
-Публічний експорт; основна логіка модуля.
-
-- **Сигнатура:** `export function runDotenvLinter(cwd = process.cwd()): number`
-- **Параметри:**
-  - `cwd` _(string, optional)_ — кореневий каталог для рекурсивного сканування. За замовчуванням — `process.cwd()`. Перед використанням нормалізується через `node:path#resolve` в абсолютний шлях.
-- **Повертає:** `number`
-  - `0` — `dotenv-linter check` завершився без порушень (включно з ситуацією "Nothing to check").
-  - `1` — будь-яка з наступних умов:
-    - бінарник `dotenv-linter` не знайдено у `PATH` (`resolveCmd` повернув falsy);
-    - `spawnSync` для фази `fix` повернув `error` (наприклад, помилка спавну процесу);
-    - `spawnSync` для фази `check` повернув `error`;
-    - `check`-прогон завершився з ненульовим `status` (виявлені залишкові порушення).
-- **Побічні ефекти:**
-  - Викликає `spawnSync` із зовнішнім бінарником `dotenv-linter` — два окремих процеси (`fix`, потім `check`).
-  - Може модифікувати файли `.env*` у дереві `cwd` (фаза `fix`). Прапорець `--no-backup` гарантує, що `.bak`-файли не створюються.
-  - Записує підказки встановлення у `process.stderr`, якщо бінарника немає.
-  - Записує повідомлення про помилку `spawnSync` у `process.stderr` (поле `.error.message`), якщо процес не вдалося запустити.
-  - На фазі `check`: при ненульовому `status` ретранслює зібрані `stdout`/`stderr` дочірнього процесу в `process.stdout` / `process.stderr` (захищено `?.length`).
-  - Не змінює глобального стану модуля; чистий exit-code-based контракт.
-- **Контракт виклику дочірніх процесів:**
-  - Аргументи fix: `['fix', '-r', '--no-backup', '--quiet', ...exclude, '.']`.
-  - Аргументи check: `['check', '-r', '--quiet', ...exclude, '.']`.
-  - `cwd` — нормалізований `root`.
-  - `encoding: 'utf8'`, `env: process.env`, `stdio: ['ignore', 'pipe', 'pipe']` (stdin закритий, stdout/stderr захоплюються в буфер).
-
-### `printDotenvLinterInstallHints()` _(internal)_
-
-- **Сигнатура:** `function printDotenvLinterInstallHints(): void`
-- **Параметри:** немає.
-- **Повертає:** `void`.
-- **Побічні ефекти:** Пише у `process.stderr` багаторядкове повідомлення з трьома варіантами встановлення (`brew`, `curl … sh`, `cargo install`) та заголовком `❌ dotenv-linter не знайдено в PATH.`. Завершується порожнім рядком (зручне відокремлення в логах).
-
-### `buildExcludeArgs()` _(internal)_
-
-- **Сигнатура:** `function buildExcludeArgs(): string[]`
-- **Параметри:** немає.
-- **Повертає:** плоский масив аргументів CLI у форматі, який очікує `dotenv-linter`: `['--exclude', 'node_modules', '--exclude', '.envrc']`. Формується через `EXCLUDED_PATHS.flatMap(p => ['--exclude', p])`, тож додавання нового елемента в `EXCLUDED_PATHS` автоматично продовжує перелік прапорців.
-- **Побічні ефекти:** немає (чиста функція).
-
-## Константи
-
-### `EXCLUDED_PATHS`
-
-- **Тип:** `string[]`
-- **Значення:** `['node_modules', '.envrc']`
-- **Призначення:** Перелік каталогів/файлів, які виключаються з рекурсивного сканування `dotenv-linter -r`. Семантика:
-  - `node_modules` — стороння кодова база, її `.env*` не наша зона відповідальності.
-  - `.envrc` — файл direnv із shell-синтаксисом (`export FOO=bar`, `source_up` тощо), формально не key=value `.env`, лінтер на ньому давав би false positives.
-
-## Залежності
-
-### Стандартна бібліотека Node.js
-
-- `node:child_process` — функція `spawnSync` для синхронного запуску дочірніх процесів `dotenv-linter`.
-- `node:path` — функція `resolve` для нормалізації `cwd` в абсолютний шлях.
-
-### Внутрішні модулі проєкту
-
-- `../../../scripts/cli-entry.mjs` — функція `isRunAsCli(import.meta.url)`. Детектує, чи модуль запущений як CLI (а не імпортований). При `true` виставляється `process.exitCode`.
-- `../../../scripts/utils/resolve-cmd.mjs` — функція `resolveCmd(name)`. Шукає виконуваний файл у `PATH`; повертає абсолютний шлях або falsy-значення, якщо бінарника немає.
-
-### Зовнішній інструмент
-
-- **`dotenv-linter`** — нативний бінарник, очікується у `PATH`. **Не** є npm-залежністю проєкту. Встановлюється окремо командами:
-  - macOS: `brew install dotenv-linter`
-  - Linux: `curl -sSfL https://git.io/JLbXn | sh -s -- -b /usr/local/bin`
-  - cargo: `cargo install dotenv-linter`
-
-## Потік виконання / Використання
-
-### Як CLI
-
-Файл містить хвостовий блок:
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exitCode = runDotenvLinter()
-}
-```
-
-Тобто прямий запуск виставить exit-code процесу у `0` (успіх) або `1` (помилка/порушення). Виклик:
-
-```sh
-node npm/rules/text/lint/run-dotenv-linter.mjs
-```
-
-`cwd` при цьому — поточний робочий каталог процесу (`process.cwd()`).
-
-### Як бібліотечний модуль
-
-Імпортується з оркестратора `lint-text`:
-
-```js
-import { runDotenvLinter } from './run-dotenv-linter.mjs'
-
-const code = runDotenvLinter('/abs/path/to/project')
-if (code !== 0) process.exit(code)
-```
-
-### Покроковий потік
-
-1. **Нормалізація `cwd`.** `resolve(cwd)` → абсолютний `root`.
-2. **Резолв бінарника.** `resolveCmd('dotenv-linter')` шукає виконуваний файл у `PATH`.
-   - Якщо `null`/`undefined`/порожній рядок → виклик `printDotenvLinterInstallHints()` → повернення `1`. Подальші кроки не виконуються.
-3. **Підготовка списку виключень.** `buildExcludeArgs()` → `['--exclude', 'node_modules', '--exclude', '.envrc']`.
-4. **Фаза fix.** `spawnSync(bin, ['fix', '-r', '--no-backup', '--quiet', '--exclude', 'node_modules', '--exclude', '.envrc', '.'], { cwd: root, encoding: 'utf8', env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })`.
-   - Якщо `fixRun.error` (наприклад, EACCES/ENOENT при спавні) → запис `fixRun.error.message` у `stderr` → повернення `1`.
-   - `status` фази `fix` **не** перевіряється — інструмент може повертати ненульовий код, якщо лишилися ще не виправлені порушення; це штатно, бо далі йде фінальний `check`.
-5. **Фаза check.** `spawnSync(bin, ['check', '-r', '--quiet', '--exclude', 'node_modules', '--exclude', '.envrc', '.'], …)` з тими самими опціями оточення.
-   - Якщо `checkRun.error` → запис `checkRun.error.message` у `stderr` → повернення `1`.
-   - Якщо `checkRun.status === 0` → повернення `0` (успіх).
-   - Інакше: за наявності `checkRun.stdout` пишемо його у `process.stdout`, за наявності `checkRun.stderr` — у `process.stderr`, повертаємо `1`.
-
-### Контракт побічних ефектів
-
-| Подія                          | Куди пишеться    | Коли                                     |
-| ------------------------------ | ---------------- | ---------------------------------------- |
-| Підказки встановлення          | `process.stderr` | бінарника немає у `PATH`                 |
-| `error.message` зі `spawnSync` | `process.stderr` | помилка спавну `fix` або `check`         |
-| `stdout` дочірнього `check`    | `process.stdout` | `check.status !== 0` та буфер непорожній |
-| `stderr` дочірнього `check`    | `process.stderr` | `check.status !== 0` та буфер непорожній |
-| Модифікація `.env*`-файлів     | дерево `cwd`     | фаза `fix` (без `.bak`)                  |
-
-### Інтеграція в `lint-text`
-
-Модуль викликається сусіднім оркестратором `lint.mjs` тієї ж теки разом із `run-shellcheck.mjs` і `run-v8r.mjs`. Кожен раннер повертає `0` / `1`, оркестратор агрегує коди для фінального exit-status команди `lint-text`. Кожна перевірка ізольована — падіння одного раннера не блокує запуск інших, якщо це визначено архітектурою оркестратора.
-
-### Тестування
-
-Поруч у теці є `tests/`, що містить юніт-тести для раннерів `lint-`. Модуль навмисно структуровано так, щоб тестам було легко мокати `spawnSync` і `resolveCmd`: усі гілки повернення (`bin not found`, `fix error`, `check error`, `check non-zero`, `check ok`) відокремлені й деталі поведінки видимі через `process.stdout`/`process.stderr`.