@nitra/cursor 12.6.1 → 12.7.0

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`.

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

@@ -1,216 +0,0 @@
----
-type: JS Module
-title: run-shellcheck.mjs
-resource: npm/rules/text/lint/run-shellcheck.mjs
-docgen:
-  crc: 6b2daaa8
----
-
-Модуль `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`.