@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,157 @@
+# run-dotenv-linter.mjs
+
+## Огляд
+
+Модуль `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`.

package/rules/text/lint/docs/run-shellcheck.md

@@ -0,0 +1,212 @@
+# run-shellcheck.mjs
+
+## Огляд
+
+Модуль `run-shellcheck.mjs` — частина ланцюжка `lint-text` для перевірки якості shell-скриптів (`*.sh`) у проєкті за допомогою зовнішнього інструменту **ShellCheck**. Скрипт виконує два етапи:
+
+1. **Авто-виправлення**: оскільки ShellCheck не має прапорця `--fix`, для кожного знайденого `*.sh` файла модуль запускає `shellcheck -f diff` і застосовує отриманий unified-diff через системну утиліту `patch -p1` у корені проєкту. Цикл повторюється до `MAX_FIX_ROUNDS_PER_FILE` (32) разів, поки залишаються авто-виправні зауваження.
+2. **Фінальний прогон**: звичайний `shellcheck` по всіх зібраних файлах. Будь-яке попередження чи помилка дають ненульовий код виходу.
+
+Модуль уміє працювати як **CLI** (через `isRunAsCli`) і як **бібліотека** (експортує функції). Шляхи скриптів збираються з `git ls-files` у git-репозиторії або через `globSync` (з виключенням `node_modules`) поза git-деревом.
+
+Якщо у системі немає `shellcheck` чи `patch`, у stderr друкуються підказки встановлення для macOS (Homebrew), Debian/Ubuntu (apt) та Arch (pacman), а скрипт завершується з кодом 1.
+
+## Експорти / API
+
+| Експорт                     | Тип            | Призначення                                                                        |
+| --------------------------- | -------------- | ---------------------------------------------------------------------------------- |
+| `listShellScriptPaths(cwd)` | named function | Зібрати відсортований унікальний список відносних шляхів до `*.sh` файлів у `cwd`. |
+| `runShellcheckText(cwd?)`   | named function | Запустити повний цикл: авто-фікси + фінальна перевірка. Повертає код виходу (0/1). |
+
+Модуль також виконується як CLI: якщо `import.meta.url` відповідає поточному запуску — викликається `runShellcheckText()` і її результат присвоюється `process.exitCode`.
+
+## Функції
+
+### `printShellcheckInstallHints()`
+
+- **Сигнатура**: `function printShellcheckInstallHints(): void`
+- **Параметри**: немає.
+- **Повертає**: `void`.
+- **Side effects**: пише у `process.stderr` повідомлення з інструкціями встановлення `shellcheck` для macOS, Debian/Ubuntu та Arch.
+
+### `printPatchInstallHints()`
+
+- **Сигнатура**: `function printPatchInstallHints(): void`
+- **Параметри**: немає.
+- **Повертає**: `void`.
+- **Side effects**: пише у `process.stderr` підказку про встановлення `patch` (на macOS зазвичай є; на Debian/Ubuntu — `sudo apt-get install -y patch`).
+
+### `listShellScriptPaths(cwd)` (export)
+
+- **Сигнатура**: `function listShellScriptPaths(cwd: string): string[]`
+- **Параметри**:
+  - `cwd` — абсолютний шлях до кореня проєкту (вже має бути нормалізований через `resolve`, якщо потрібно).
+- **Повертає**: відсортований масив унікальних відносних шляхів до `*.sh` файлів від `cwd`. Слеші уніфікуються в forward-slash (`'/'`).
+- **Side effects**: виконує `git rev-parse --is-inside-work-tree` і `git ls-files -z -- ':(glob)**/*.sh'` через `spawnSync`; у безгітовому контексті — викликає `globSync('**/*.sh')` з виключенням `node_modules`.
+- **Логіка**:
+  - Якщо `git` доступний і `cwd` — частина git-робочого дерева, читаються лише tracked файли (`ls-files` з NUL-розділенням, дублікати усуваються через `Set`).
+  - Якщо `git` доступний, але `ls-files` повертає ненульовий статус — повертається порожній масив.
+  - Інакше — `globSync` з `exclude`, який відкидає шляхи, що містять `node_modules` (на будь-якому рівні), і нормалізує бекслеші (`\\` → `/`).
+
+### `runShellcheckText(cwd = process.cwd())` (export)
+
+- **Сигнатура**: `function runShellcheckText(cwd?: string): number`
+- **Параметри**:
+  - `cwd` — необов'язковий робочий каталог. За замовчуванням — `process.cwd()`.
+- **Повертає**: `0` — все OK; `1` — помилка середовища (немає `shellcheck`/`patch`), помилка spawn, або залишкові зауваження ShellCheck після авто-фіксів.
+- **Side effects**:
+  - Можливий вивід підказок у `stderr` (якщо немає `shellcheck`/`patch`).
+  - Запис патчів у файли через `patch -p1` (модифікує source-файли).
+  - Друк звичайного звіту ShellCheck у `stdout`/`stderr` на фінальному кроці.
+- **Алгоритм**:
+  1. `root = resolve(cwd)`.
+  2. `shellcheck = resolveCmd('shellcheck')` → якщо немає, друк підказки та `return 1`.
+  3. `patchBin = resolveCmd('patch')` → якщо немає, друк підказки та `return 1`.
+  4. `files = listShellScriptPaths(root)` → якщо порожньо, `return 0`.
+  5. Для кожного `rel` із `files`: `autofixOneFile(...)`. Якщо ненульовий код — негайний `return`.
+  6. `return runFinalShellcheck(shellcheck, files, root)`.
+
+### `autofixOneFile(shellcheck, patchBin, root, rel)`
+
+- **Сигнатура**: `function autofixOneFile(shellcheck: string, patchBin: string, root: string, rel: string): number`
+- **Параметри**:
+  - `shellcheck` — абсолютний шлях до бінарника ShellCheck.
+  - `patchBin` — абсолютний шлях до бінарника `patch`.
+  - `root` — абсолютний `cwd` для spawn.
+  - `rel` — відносний шлях файла від `root`.
+- **Повертає**: `0` — більше нема чого фіксити (нормальне завершення циклу); `1` — помилка spawn чи помилка `patch`.
+- **Side effects**: до 32 викликів `spawnSync(shellcheck, ['-f', 'diff', rel])` і `applyShellcheckDiff(...)` на файл; модифікує сам файл через `patch`.
+- **Логіка**:
+  - У циклі `0..MAX_FIX_ROUNDS_PER_FILE-1`:
+    - Запускає `shellcheck -f diff <rel>` з `maxBuffer: 10MiB`.
+    - Якщо `diffResult.error` — друкує повідомлення і повертає 1.
+    - Якщо `shouldStopAutofixLoop(diffResult)` — повертає 0.
+    - Інакше — `applyShellcheckDiff(...)`. На помилку — повертає 1.
+  - Якщо досягнуто `MAX_FIX_ROUNDS_PER_FILE` — повертає 0 (захист від зациклення).
+
+### `shouldStopAutofixLoop(diffResult)`
+
+- **Сигнатура**: `function shouldStopAutofixLoop(diffResult: { status: number | null, stdout?: string | null, stderr?: string | null }): boolean`
+- **Параметри**:
+  - `diffResult` — об'єкт результату `spawnSync` (потрібні `status`, `stdout`, `stderr`).
+- **Повертає**: `true`, якщо подальші ітерації авто-фіксів не мають сенсу.
+- **Side effects**: немає (чиста перевірка).
+- **Логіка**: повертає `true`, якщо
+  - `status === 0` (ShellCheck не знайшов зауважень), **або**
+  - `stderr` містить підрядок `'none were auto-fixable'` (`NON_AUTOFIXABLE_HINT`), **або**
+  - `stdout` після `trim()` порожній (нема дифу для застосування).
+
+### `applyShellcheckDiff(patchBin, root, rel, diffStdout)`
+
+- **Сигнатура**: `function applyShellcheckDiff(patchBin: string, root: string, rel: string, diffStdout: string): number`
+- **Параметри**:
+  - `patchBin` — абсолютний шлях до `patch`.
+  - `root` — `cwd` для spawn (корінь проєкту).
+  - `rel` — відносний шлях файла, для якого формується diff (використовується тільки у повідомленні про помилку).
+  - `diffStdout` — вміст unified-diff, отриманий від `shellcheck -f diff`.
+- **Повертає**: `0` — патч застосовано; `1` — `patch` повернув ненульовий код.
+- **Side effects**:
+  - Запускає `patch -p1` із `diffStdout` через stdin.
+  - На помилку виливає `stderr` і `stdout` процесу `patch` у `process.stderr`, а також додає рядок `run-shellcheck-text: patch не застосував diff для ${rel}`.
+
+### `runFinalShellcheck(shellcheck, files, root)`
+
+- **Сигнатура**: `function runFinalShellcheck(shellcheck: string, files: string[], root: string): number`
+- **Параметри**:
+  - `shellcheck` — абсолютний шлях до ShellCheck.
+  - `files` — відносні шляхи усіх файлів для перевірки.
+  - `root` — `cwd` для spawn.
+- **Повертає**: `0` — звіт чистий; `1` — `spawnSync` віддав `error` або `status !== 0`.
+- **Side effects**:
+  - Виконує `shellcheck <files...>` без прапорця `-f diff`, з `maxBuffer: 10MiB` і `stdio: ['ignore', 'pipe', 'pipe']`.
+  - Якщо є помилка — друкує `error.message` у `stderr`.
+  - Якщо `status !== 0` — друкує `stdout` у `process.stdout` і `stderr` у `process.stderr`.
+
+## Константи
+
+| Ім'я                      | Значення                   | Призначення                                                                                            |
+| ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `NON_AUTOFIXABLE_HINT`    | `'none were auto-fixable'` | Маркер у stderr ShellCheck про відсутність авто-виправлень — критерій виходу з циклу `autofixOneFile`. |
+| `MAX_FIX_ROUNDS_PER_FILE` | `32`                       | Жорсткий ліміт ітерацій `diff`+`patch` на один файл для уникнення зациклення.                          |
+
+## Залежності
+
+### Node.js (built-in)
+
+- `node:child_process` → `spawnSync` — синхронний запуск `git`, `shellcheck`, `patch`.
+- `node:fs` → `globSync` — пошук `*.sh` поза git-деревом.
+- `node:path` → `resolve` — нормалізація `cwd` у абсолютний шлях.
+
+### Внутрішні модулі
+
+- `../../../scripts/cli-entry.mjs` → `isRunAsCli(import.meta.url)` — перевіряє, чи модуль запущено напряму як CLI (а не імпортовано).
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd(name)` — повертає абсолютний шлях до бінарника з PATH або `null`.
+
+### Зовнішні бінарники (runtime)
+
+- **shellcheck** — обов'язковий; без нього `runShellcheckText` повертає 1.
+- **patch** — обов'язковий для авто-фіксів; без нього `runShellcheckText` повертає 1.
+- **git** — необов'язковий: якщо доступний і ми у робочому дереві — використовується `git ls-files`; інакше — `globSync`.
+
+## Потік виконання / Використання
+
+### CLI
+
+Скрипт можна запустити напряму:
+
+```bash
+node npm/rules/text/lint/run-shellcheck.mjs
+```
+
+Логіка CLI-входу:
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = runShellcheckText()
+}
+```
+
+`process.exitCode` встановлюється у значення, повернуте `runShellcheckText()` (0 або 1).
+
+### Програмний виклик
+
+```js
+import { runShellcheckText, listShellScriptPaths } from './run-shellcheck.mjs'
+
+// Повний прогон у поточному каталозі:
+const code = runShellcheckText()
+
+// Тільки список *.sh файлів:
+const files = listShellScriptPaths(process.cwd())
+```
+
+### Високорівнева послідовність кроків `runShellcheckText`
+
+1. `resolve(cwd)` → абсолютний `root`.
+2. `resolveCmd('shellcheck')` → перевірка наявності бінарника. **Fail-fast**: підказка + `return 1`.
+3. `resolveCmd('patch')` → перевірка наявності бінарника. **Fail-fast**: підказка + `return 1`.
+4. `listShellScriptPaths(root)`:
+   - `git` доступний і ми в робочому дереві → `git ls-files -z -- ':(glob)**/*.sh'` (NUL-роздільник, унікальні, відсортовані).
+   - Інакше → `globSync('**/*.sh', { exclude: ... })` з виключенням `node_modules` (forward-slashes).
+5. Якщо файлів немає → `return 0` (no-op).
+6. Для кожного файла → `autofixOneFile(...)`:
+   - Цикл до 32 разів: `shellcheck -f diff <rel>` → `patch -p1` (через stdin).
+   - Виходить раніше, якщо `status === 0`, `none were auto-fixable`, або порожній diff.
+7. `runFinalShellcheck(shellcheck, files, root)`:
+   - `shellcheck <files...>` без формату diff.
+   - Будь-який ненульовий статус → друк stdout/stderr у консоль і `return 1`.
+
+### Коди виходу
+
+| Код | Причина                                                                                                                                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0` | Немає `*.sh` файлів, або всі пройшли фінальний `shellcheck` чисто (можливо, після авто-фіксів).                                                              |
+| `1` | Немає `shellcheck`/`patch` у PATH; помилка `spawnSync` (наприклад, `ENOENT`); `patch` не застосував diff; фінальний `shellcheck` повернув ненульовий статус. |
+
+### Ефекти на файлову систему
+
+Авто-фікси **модифікують сам source `.sh`-файл** через `patch -p1`. Запуск передбачає, що користувач готовий побачити змінений вміст (наприклад, виконує перевірку перед коммітом у CI або локально).
+
+### Контекст застосування
+
+Модуль використовується у складі `lint-text` ланцюжка (правила `npm/rules/text/lint/`) для перевірки текстової частини проєкту, де shell-скрипти підлягають аналізу ShellCheck. Це частина набору `rules/text/lint/*`, описаного у `n-text.mdc` і `n-js-lint.mdc`.

package/rules/text/lint/docs/run-v8r.md

@@ -0,0 +1,197 @@
+# run-v8r.mjs
+
+## Огляд
+
+Модуль `run-v8r.mjs` — це послідовний раннер CLI-валідатора схем `v8r` для всіх типів файлів, які він підтримує (`.json`, `.json5`, `.yml`, `.yaml`, `.toml`). Він є проміжним рівнем між кореневою командою `lint-text` та `bunx v8r`.
+
+Призначення модуля — обійти специфічну ваду `v8r`: якщо у єдиний виклик передати кілька glob-патернів і хоча б один із них не знаходить жодного файлу, процес `v8r` падає з кодом виходу `98`, тому решта розширень узагалі не перевіряється. Щоб уникнути цього, скрипт виконує **окремий** `bunx v8r` на **кожен** glob і толерантно ставиться до коду `98` (порожнє співпадіння — не помилка).
+
+Додатково модуль автоматично підставляє у виклик `v8r` параметр `-c <шлях до v8r-catalog.json>` — каталог схем пакета `@nitra/cursor`, який лежить у `npm/schemas/v8r-catalog.json` від кореня репозиторію. Завдяки цьому користувачі цього раннера не зобовʼязані пам’ятати про каталог схем.
+
+Поведінка щодо виводу:
+
+- Якщо v8r для конкретного glob завершився з кодом `0` (успіх) або `98` (порожнє співпадіння) — вивід **не друкується**, обхід продовжується.
+- Якщо v8r повернув будь-який інший код — `stdout` і `stderr` друкуються «як є», а сам раннер повертає той самий код виходу і **припиняє** подальший обхід glob-патернів.
+
+Файл одночасно є модулем (експортує API) і CLI-точкою входу: під час прямого запуску він читає glob-и з `process.argv` (починаючи з 3-го елемента) і виставляє `process.exitCode`.
+
+## Експорти / API
+
+Модуль експортує дві іменовані сутності:
+
+| Імʼя                | Тип        | Призначення                                                                                                        |
+| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `DEFAULT_V8R_GLOBS` | `string[]` | Список glob-патернів за замовчуванням для форматів, які підтримує `v8r`.                                           |
+| `V8R_CATALOG_PATH`  | `string`   | Абсолютний шлях до файлу `v8r-catalog.json` у каталозі `schemas` пакета `@nitra/cursor`.                           |
+| `runV8rWithGlobs`   | `function` | Послідовний запуск `bunx v8r` по списку glob-патернів; повертає числовий код виходу. Не змінює `process.exitCode`. |
+
+### `DEFAULT_V8R_GLOBS`
+
+Значення:
+
+```js
+;['**/*.json', '**/*.json5', '**/*.yml', '**/*.yaml', '**/*.toml']
+```
+
+Використовується як значення за замовчуванням для `runV8rWithGlobs`, а також як fallback у CLI-режимі, коли користувач не передав власних glob-аргументів.
+
+### `V8R_CATALOG_PATH`
+
+Обчислюється на момент завантаження модуля з `import.meta.url`:
+
+```js
+join(dirname(fileURLToPath(import.meta.url)), '../../../schemas/v8r-catalog.json')
+```
+
+З урахуванням розташування самого модуля (`npm/rules/text/lint/run-v8r.mjs`) три рівні `..` піднімають шлях до `npm/`, після чого додається `schemas/v8r-catalog.json`. Результат — абсолютний шлях, який не залежить від поточної робочої директорії процесу.
+
+### `runV8rWithGlobs(globs?)`
+
+Див. секцію [«Функції»](#функції).
+
+## Функції
+
+### `runV8rWithGlobs(globs = DEFAULT_V8R_GLOBS)`
+
+Сигнатура:
+
+```js
+/**
+ * @param {string[]} [globs] патерни; за замовчуванням DEFAULT_V8R_GLOBS
+ * @returns {number} 0 — OK, 1 — помилка spawn, 2 — немає каталогу схем, інше — код v8r
+ */
+export function runV8rWithGlobs(globs = DEFAULT_V8R_GLOBS)
+```
+
+#### Параметри
+
+- `globs` (`string[]`, опційно) — масив glob-патернів, які буде передано в `v8r` по черзі (по одному на виклик). За замовчуванням — `DEFAULT_V8R_GLOBS`.
+
+#### Повертає
+
+Числовий код виходу, який повинен стати `process.exitCode` у CLI-режимі:
+
+- `0` — усі glob-и оброблено успішно (або вони порожні);
+- `1` — `spawnSync` повернув `result.error` (наприклад, не вдалося запустити процес);
+- `2` — не знайдено файл `V8R_CATALOG_PATH` (відсутній каталог схем `npm/schemas/v8r-catalog.json`);
+- будь-яке інше число — реальний код виходу від `v8r` для першого glob-а, який не дав `0` або `98`.
+
+#### Side effects
+
+- Може писати в `process.stderr` повідомлення про відсутній каталог схем (код `2`) або текст помилки `spawnSync.error.message` (код `1`).
+- Для невдалого `v8r` (код, відмінний від `0`/`98`) друкує його `stdout` і `stderr` без змін.
+- **Не** мутує `process.exitCode` і **не** викликає `process.exit`. Цією операцією займається CLI-блок наприкінці файла.
+- Виконує синхронний `spawnSync` (`bun x v8r ...`) — блокуючий виклик на кожен glob.
+
+#### Алгоритм
+
+1. Перевіряє існування `V8R_CATALOG_PATH` через `existsSync`. Якщо файла немає — пише повідомлення в `stderr` і повертає `2`.
+2. Перебирає `globs` у тому ж порядку, у якому вони передані:
+   1. Резолвить `bun` через `resolveCmd('bun')`; якщо `bun` не знайдено в `PATH`, використовує `process.execPath` як fallback (тобто запустить поточний інтерпретатор, що збігається з шляхом до `node`/`bun`-runtime, який запустив скрипт).
+   2. Викликає `spawnSync(bunPath, ['x', 'v8r', pattern, '-c', V8R_CATALOG_PATH], { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024, shell: false, stdio: ['ignore', 'pipe', 'pipe'] })`.
+   3. Якщо `result.error` — пише `result.error.message` у `stderr` і повертає `1`.
+   4. Бере `result.status ?? 1` (якщо процес був вбитий сигналом, `status === null`, тоді трактує це як `1`).
+   5. Якщо код **не** `0` і **не** `98` — друкує накопичений `stdout`/`stderr` (якщо вони непорожні) і повертає цей код, **зупиняючи** подальший обхід.
+3. Якщо всі glob-и пройшли — повертає `0`.
+
+### CLI-блок (нижній рівень файла)
+
+Сигнатура (не функція, а side-effect блок):
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  const globs = process.argv.length > 2 ? process.argv.slice(2) : DEFAULT_V8R_GLOBS
+  process.exitCode = runV8rWithGlobs(globs)
+}
+```
+
+#### Поведінка
+
+- `isRunAsCli(import.meta.url)` повертає `true`, коли модуль викликано як точку входу (а не імпортовано).
+- Якщо передано хоча б один аргумент після назви скрипта (`process.argv.length > 2`) — усі аргументи (зрізані з індексу 2) використовуються як glob-патерни.
+- Інакше — `DEFAULT_V8R_GLOBS`.
+- Результат `runV8rWithGlobs(...)` записується у `process.exitCode`, що дозволяє завершити процес із потрібним кодом без переривання поточного call-stack.
+
+## Залежності
+
+### Внутрішні (Node.js core)
+
+- `node:child_process` → `spawnSync` — синхронний запуск зовнішнього процесу `bun x v8r ...`.
+- `node:fs` → `existsSync` — перевірка наявності файлу каталогу схем.
+- `node:path` → `dirname`, `join` — побудова шляху до `v8r-catalog.json`.
+- `node:url` → `fileURLToPath` — конвертація `import.meta.url` в абсолютний файловий шлях.
+
+### Внутрішні (`@nitra/cursor`)
+
+- `../../../scripts/cli-entry.mjs` → `isRunAsCli(metaUrl)` — детектор «запущено як CLI чи імпортовано як модуль».
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd(name)` — пошук абсолютного шляху до бінарника за `PATH`-у (з повним fallback-резолвером, на відміну від простого `which`).
+
+### Зовнішні (через `bunx`)
+
+- `v8r` — CLI-валідатор JSON/YAML/TOML за каталогом JSON-схем. Запускається через `bun x v8r ...`.
+- `bun` — runtime, через який запускається `v8r`. Якщо `bun` відсутній у `PATH`, використовується `process.execPath`.
+
+### Конфігурація / артефакти
+
+- `npm/schemas/v8r-catalog.json` (в межах пакета `@nitra/cursor`) — обовʼязковий файл-каталог відповідностей `glob → schemaURL`. Без нього раннер повертає код `2`.
+
+## Потік виконання / Використання
+
+### Як частина команди `lint-text`
+
+Раннер призначений для виклику з кореневої лінт-команди репозиторію (`lint-text` у `package.json`). Замість того, щоб запускати `v8r` чотирма (або п’ятьма) окремими командами в `package.json`, використовується один виклик цього модуля, який сам обходить усі типові glob-и:
+
+```bash
+node ./npm/rules/text/lint/run-v8r.mjs
+```
+
+Це еквівалентно послідовним викликам:
+
+```bash
+bunx v8r '**/*.json'   -c npm/schemas/v8r-catalog.json
+bunx v8r '**/*.json5'  -c npm/schemas/v8r-catalog.json
+bunx v8r '**/*.yml'    -c npm/schemas/v8r-catalog.json
+bunx v8r '**/*.yaml'   -c npm/schemas/v8r-catalog.json
+bunx v8r '**/*.toml'   -c npm/schemas/v8r-catalog.json
+```
+
+але без падіння на коді `98`, коли якесь розширення не зустрічається в проєкті.
+
+### Запуск з кастомними glob-ами
+
+```bash
+node ./npm/rules/text/lint/run-v8r.mjs '**/*.json' 'configs/*.yaml'
+```
+
+У цьому режимі `DEFAULT_V8R_GLOBS` ігноруються, обходяться лише передані патерни.
+
+### Імпорт як модуль
+
+```js
+import { runV8rWithGlobs, DEFAULT_V8R_GLOBS, V8R_CATALOG_PATH } from './run-v8r.mjs'
+
+const code = runV8rWithGlobs(['**/*.json'])
+if (code !== 0) {
+  // обробити збій валідації
+}
+```
+
+Корисно з тестів і інших скриптів, які мають потребу перевалідовувати лише підмножину файлів.
+
+### Семантика кодів виходу
+
+| Код  | Значення                                                                                                                     |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | Усі glob-и пройшли (валідно або порожньо).                                                                                   |
+| `1`  | Внутрішня помилка запуску процесу (`spawnSync.error`); зокрема, якщо ані `bun`, ані `process.execPath` не змогли стартувати. |
+| `2`  | Не знайдено каталог схем `npm/schemas/v8r-catalog.json` у пакеті `@nitra/cursor`.                                            |
+| `98` | **Не повертається**: внутрішньо трактується як «успіх для цього glob» і обхід триває далі.                                   |
+| інше | Дослівний код виходу від `v8r` для першого glob, на якому валідація провалилася.                                             |
+
+### Особливості реалізації, на які варто звернути увагу
+
+- `shell: false` запобігає інтерполяції glob-патернів shell-ом — їх обробляє безпосередньо `v8r`.
+- `maxBuffer: 50 * 1024 * 1024` (50 MiB) — захист від обрізання довгого виводу `v8r` на великих репозиторіях.
+- `stdio: ['ignore', 'pipe', 'pipe']` — `stdin` процесу не використовується; вивід буферизується й друкується лише при помилці.
+- Обхід «лінивий» по помилкам: на першому невдалому glob цикл завершується. Це навмисно — повертати треба перший реальний код помилки, а решта валідації не має сенсу до її усунення.
+- Раннер **не** мутує `process.exitCode` усередині `runV8rWithGlobs`, тому імпортери можуть безпечно викликати функцію кілька разів і самостійно вирішувати, що з кодом робити.