@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,256 @@
+# `formatting.mjs` — перевірка текстового стека й форматування за правилом `text.mdc`
+
+## Огляд
+
+Модуль `formatting.mjs` реалізує **JS-частину** перевірки правила `n-text.mdc` / `npm/mdc/text.mdc` для пакета `@nitra/cursor`. Його роль — **доповнити** Rego-перевірки тими аспектами, які не вдається коректно описати декларативно: наявність файлів на файловій системі, вміст plain-text файлу `.v8rignore`, наявність абзацу про український апостроф у markdown-тексті правила, форма скрипта `lint-text` у `package.json` та виклик `bun run lint-text` у GitHub Actions workflow.
+
+Модуль експортує функцію `check(cwd)`, яка повертає код виходу процесу (`0` — все ок, `1` — є порушення). Усі повідомлення про успіх/провал агрегує `createCheckReporter()` зі спільної бібліотеки `scripts/lib/check-reporter.mjs`.
+
+Розподіл відповідальностей JS ↔ Rego (зафіксований у JSDoc-коментарі на початку файлу):
+
+- **JS (цей файл):**
+  - `.v8rignore` (текстовий формат, рядки шляхів);
+  - наявність FS-файлів `.oxfmtrc.json`, `.cspell.json`, `.markdownlint-cli2.jsonc`, `.vscode/extensions.json`, `.vscode/settings.json`, `package.json`;
+  - абзац про український апостроф у `.cursor/rules/n-text.mdc` / `npm/mdc/text.mdc` (markdown-текст);
+  - перевірка скрипта `lint-text` у `package.json`;
+  - наявність кроку `bun run lint-text` у workflow `lint-text.yml`.
+- **Rego (`npx @nitra/cursor check`):**
+  - `npm/policy/text/oxfmtrc/` — обовʼязкові ключі `.oxfmtrc.json` і канонічні значення (`semi`/`singleQuote`/`tabWidth`/`useTabs`/`printWidth`) + канонічні `ignorePatterns`;
+  - `npm/policy/text/cspell/` — `.cspell.json` (`version "0.2"`, `language`, імпорт `@nitra/cspell-dict`, заборона `@cspell/dict-*`, обовʼязкові `ignorePaths`);
+  - `npm/policy/text/markdownlint/` — `.markdownlint-cli2.jsonc` (`gitignore: true`, валідний JSON без коментарів);
+  - `npm/policy/text/package_json/` — заборона Prettier (`prettier` поле + `prettier`/`@nitra/prettier-config` у залежностях), `@nitra/cspell-dict ^2.0.0+` у `devDependencies`, заборона `markdownlint-cli2` у залежностях;
+  - `npm/policy/bun/package_json/` — у `devDependencies` лише пакети з `@nitra/*`;
+  - `text.vscode_extensions` / `text.vscode_settings` — вміст `.vscode/extensions.json` та `.vscode/settings.json`.
+
+## Експорти / API
+
+| Назва   | Тип                                 | Опис                                                                                                                               |
+| ------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `check` | `(cwd?: string) => Promise<number>` | Єдиний публічний експорт. Виконує всі перевірки текстового стека й повертає код виходу: `0` — порушень немає, `1` — є хоча б одне. |
+
+Решта функцій (`verifyUkApostropheRuleParagraph`, `checkV8rIgnore`, `checkTextConfigsExistence`, `checkPackageJsonText`, `checkLintTextScript`) — внутрішні, не експортуються.
+
+Також у файлі є модульна константа:
+
+| Назва                   | Значення                      | Призначення                                                                                          |
+| ----------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `UK_APOSTROPHE_HEADING` | `'**Український апостроф:**'` | Заголовок абзацу про апостроф у `text.mdc` / `n-text.mdc`, по якому ведеться пошук у вмісті правила. |
+
+## Функції
+
+### `verifyUkApostropheRuleParagraph(filePath, body, failFn, passFn)`
+
+**Сигнатура:** `(filePath: string, body: string, failFn: (msg: string) => void, passFn: (msg: string) => void) => void`
+
+**Параметри:**
+
+- `filePath` — шлях до файлу `.mdc`, використовується лише для повідомлень.
+- `body` — вміст `.mdc` у кодуванні UTF-8 (рядок).
+- `failFn` — callback, який реєструє порушення (фактично змушує `check()` повернути `1`).
+- `passFn` — callback успіху для звіту.
+
+**Повертає:** `void`. Чистих значень не повертає; вплив — виключно через callback-и.
+
+**Поведінка:**
+
+1. Якщо в тексті немає підрядка `**Український апостроф:**` — `failFn` з підказкою «додай абзац» і одразу `return`.
+2. Якщо немає згадки `U+0027` **або** `U+2019` — `failFn`, `return`.
+3. Якщо у вмісті немає символу `’` (типографська одинарна лапка U+2019) — `failFn`, `return`.
+4. Інакше — `passFn('… абзац про український апостроф на місці')`.
+
+**Side effects:** виклики `failFn` / `passFn` (запис у звіт `check-reporter`).
+
+---
+
+### `checkV8rIgnore(passFn, failFn, cwd)`
+
+**Сигнатура:** `async (passFn: (msg: string) => void, failFn: (msg: string) => void, cwd: string) => Promise<void>`
+
+**Параметри:**
+
+- `passFn`, `failFn` — callback-и звіту.
+- `cwd` — корінь репозиторію.
+
+**Повертає:** `Promise<void>`.
+
+**Поведінка:**
+
+1. Будує шлях `cwd + '.v8rignore'` через `path.join`.
+2. Якщо файлу немає (`existsSync` → `false`) — `failFn` з підказкою про мінімально потрібний вміст, `return`.
+3. Читає файл `readFile(..., 'utf8')`.
+4. Парсить рядки: розбиває за `\n`, обрізає пробіли (`trim`), відкидає порожні й коментарі (рядки, що починаються з `#`), кладе результат у `Set`.
+5. Для кожного з обовʼязкових шляхів `.vscode/extensions.json`, `.vscode/settings.json` перевіряє наявність у `Set`: знайдено → `passFn`, ні → `failFn` з підказкою додати рядок.
+
+**Side effects:** читання файлу `.v8rignore` з диска (`fs/promises.readFile`), виклики `failFn` / `passFn`.
+
+---
+
+### `checkTextConfigsExistence(passFn, failFn, cwd)`
+
+**Сигнатура:** `(passFn: (msg: string) => void, failFn: (msg: string) => void, cwd: string) => Promise<void>`
+
+Хоч JSDoc описує функцію як таку, що повертає `Promise<void>`, тіло функції — синхронне. Наприкінці явно повертається `Promise.resolve()` для збереження асинхронного контракту (можна `await`-ити без шкоди).
+
+**Параметри:**
+
+- `passFn`, `failFn` — callback-и звіту.
+- `cwd` — корінь репозиторію.
+
+**Повертає:** `Promise<void>`.
+
+**Поведінка:**
+
+Ітерується по фіксованому масиву пар `[path, mdcRef]`:
+
+| path                       | mdcRef (Rego-пакет із описом структури) |
+| -------------------------- | --------------------------------------- |
+| `.oxfmtrc.json`            | `text.oxfmtrc`                          |
+| `.cspell.json`             | `text.cspell`                           |
+| `.markdownlint-cli2.jsonc` | `text.markdownlint`                     |
+| `.vscode/extensions.json`  | `text.vscode_extensions`                |
+| `.vscode/settings.json`    | `text.vscode_settings`                  |
+
+Для кожної пари:
+
+- `existsSync(join(cwd, path))` → `passFn` із підказкою, що структуру перевіряє `npx @nitra/cursor fix` через відповідний Rego-пакет.
+- Файлу немає → `failFn('<path> не існує — створи згідно n-text.mdc')`.
+
+**Side effects:** `existsSync` (синхронне звернення до файлової системи), виклики callback-ів. Запис у файли не виконується.
+
+---
+
+### `checkPackageJsonText(passFn, failFn, cwd)`
+
+**Сигнатура:** `async (passFn: (msg: string) => void, failFn: (msg: string) => void, cwd: string) => Promise<void>`
+
+**Параметри:**
+
+- `passFn`, `failFn` — callback-и звіту.
+- `cwd` — корінь репозиторію.
+
+**Повертає:** `Promise<void>`.
+
+**Поведінка:**
+
+1. `pkgPath = join(cwd, 'package.json')`. Якщо файлу немає — мовчазний `return` (відсутність `package.json` — окремий concern, цей модуль його не валідує).
+2. `pkg = JSON.parse(await readFile(pkgPath, 'utf8'))` — кидає виключення, якщо JSON битий (свідома відмова: краще вибух у CI, ніж проковтнута помилка).
+3. Викликає `checkLintTextScript(pkg.scripts?.['lint-text'], passFn, failFn)` — валідація команди.
+4. `lintTextWf = join(cwd, '.github/workflows/lint-text.yml')`.
+   - Якщо workflow існує:
+     - читає YAML, парсить `parseWorkflowYaml(wf)`.
+     - якщо парсер повернув root — перевіряє `anyRunStepIncludes(root, 'bun run lint-text')`; якщо ні — fallback `wf.includes('bun run lint-text')`.
+     - результат: `passFn('lint-text.yml викликає bun run lint-text')` або `failFn('lint-text.yml має містити крок bun run lint-text')`.
+   - Якщо workflow немає — `failFn('.github/workflows/lint-text.yml не існує — створи згідно n-text.mdc')`.
+
+**Side effects:** читання `package.json` і потенційно `lint-text.yml`, виклики callback-ів, можливе виключення `JSON.parse` на пошкодженому `package.json`.
+
+---
+
+### `checkLintTextScript(lintText, passFn, failFn)`
+
+**Сигнатура:** `(lintText: unknown, passFn: (msg: string) => void, failFn: (msg: string) => void) => void`
+
+**Параметри:**
+
+- `lintText` — значення `scripts['lint-text']` із `package.json` (очікувано — рядок, але приймається `unknown` для безпечного narrowing).
+- `passFn`, `failFn` — callback-и звіту.
+
+**Повертає:** `void`.
+
+**Поведінка:**
+
+1. Якщо `typeof lintText === 'string'` — обрізає пробіли (`trim`), інакше `lt = ''`.
+2. Якщо `lt === 'n-cursor lint-text'` — `passFn('lint-text делегує CLI n-cursor lint-text (cspell + shellcheck + markdownlint + v8r)')`.
+3. Інакше — `failFn('package.json: lint-text має бути "n-cursor lint-text" — CLI пакета @nitra/cursor виконує cspell → shellcheck → markdownlint-cli2 → v8r (text.mdc)')`.
+
+Це канонічна форма: пакет `@nitra/cursor` CLI-командою `n-cursor lint-text` всередині запускає послідовність `cspell` → `runShellcheckText()` → `bunx markdownlint-cli2 --fix` → `runV8rWithGlobs()`. Дозволені тільки пробіли навколо команди — інші варіанти забороняються.
+
+**Side effects:** виклики callback-ів.
+
+---
+
+### `check(cwd = process.cwd())`
+
+**Сигнатура:** `async (cwd?: string) => Promise<number>`
+
+**Параметри:**
+
+- `cwd` — корінь репозиторію. За замовчуванням `process.cwd()` (звичайний кейс — запуск зі скрипта `npx @nitra/cursor`).
+
+**Повертає:** `Promise<number>` — `0`, якщо порушень немає; `1`, якщо є хоча б одне (значення обчислюється `reporter.getExitCode()`).
+
+**Поведінка (послідовність кроків):**
+
+1. `reporter = createCheckReporter()` — створює агрегатор звіту з полями `pass`, `fail`, `getExitCode`.
+2. `await checkV8rIgnore(pass, fail, cwd)` — перевірка `.v8rignore`.
+3. `await checkTextConfigsExistence(pass, fail, cwd)` — наявність FS-конфігів.
+4. Шукає `.cursor/rules/n-text.mdc` та `npm/mdc/text.mdc` (через `existsSync`):
+   - якщо жодного — нейтральний `pass('n-text.mdc / npm/mdc/text.mdc відсутні — перевірку абзацу про апостроф пропущено')`;
+   - якщо є — для кожного існуючого файлу читає вміст і викликає `verifyUkApostropheRuleParagraph(p, body, fail, pass)`.
+5. `await checkPackageJsonText(pass, fail, cwd)` — `lint-text` + workflow.
+6. Повертає `reporter.getExitCode()`.
+
+**Side effects:** читання файлів `.v8rignore`, `.cursor/rules/n-text.mdc`, `npm/mdc/text.mdc`, `package.json`, `.github/workflows/lint-text.yml`; `existsSync`-перевірки конфігів і файлів правил. Запис у файлову систему не виконується.
+
+Зверніть увагу: коментар у тілі функції `check` фіксує, що **Prettier-конфіги / ignore** — окремий concern, обробляється в `rules/text/js/forbidden-prettier.mjs`, тут не валідується.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:fs` → `existsSync` — синхронна перевірка наявності файлу.
+- `node:fs/promises` → `readFile` — асинхронне читання текстових файлів у UTF-8.
+- `node:path` → `join` — кросплатформенне склеювання шляхів від `cwd`.
+
+### Внутрішні модулі пакета `@nitra/cursor`
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика звіту з API `{ pass, fail, getExitCode }`.
+- `../../../scripts/lib/gha-workflow.mjs` → `anyRunStepIncludes`, `parseWorkflowYaml` — парсер GitHub Actions workflow YAML + утиліта пошуку фрагмента в командах `run:`.
+
+### Файли в репозиторії, які читає модуль
+
+- `.v8rignore` (text).
+- `.cursor/rules/n-text.mdc`, `npm/mdc/text.mdc` (markdown зі сторінки правила).
+- `package.json` (JSON.parse).
+- `.github/workflows/lint-text.yml` (YAML, парситься, з fallback на текстовий `includes`).
+
+### Файли, які лише перевіряються на існування
+
+- `.oxfmtrc.json`, `.cspell.json`, `.markdownlint-cli2.jsonc`, `.vscode/extensions.json`, `.vscode/settings.json`.
+
+## Потік виконання / Використання
+
+Файл — частина «JS-чек-пакета» правила `text` усередині CLI `@nitra/cursor`. Типовий запуск:
+
+1. CI / локально викликає кореневий скрипт пакета `@nitra/cursor`, який обходить `npm/rules/<rule>/js/*.mjs` і шукає експорт `check`.
+2. Для правила `text` серед інших підключається й `formatting.mjs`. CLI імпортує `check` і викликає `await check(repoRoot)`.
+3. Усередині `check`:
+   - Запускаються чотири блоки перевірок: `.v8rignore`, FS-існування конфігів, абзац про апостроф у `.mdc`, `package.json` + workflow.
+   - Кожна знахідка фіксується в `reporter` (через локально розпаковані `pass` / `fail`).
+   - Після всіх перевірок `reporter.getExitCode()` повертає `0` або `1`.
+4. CLI агрегує результати з усіх правил і виходить з відповідним кодом, який підхоплює GitHub Actions як статус кроку.
+
+Контракт із Rego-частиною: цей модуль **не дублює** контентну валідацію. Якщо файл `.oxfmtrc.json` / `.cspell.json` / `.markdownlint-cli2.jsonc` / `.vscode/*.json` існує, його структуру перевіряє відповідний Rego-пакет (див. таблицю в розділі «Огляд»). JS-модуль гарантує лише сам факт існування, формат `.v8rignore` (plain-text), markdown-абзац про апостроф та форму скрипта `lint-text` + наявність workflow-кроку.
+
+Розширення: щоб додати ще одну FS-перевірку — додай пару `[path, mdcRef]` у масив `checkTextConfigsExistence`. Щоб міняти канонічну команду — править `checkLintTextScript`. Більш складна валідація структурованих файлів повинна йти **в Rego**, а не в цей JS-модуль.
+
+## Rebuild Test
+
+Цей розділ — контрольний перелік фактів, за якими файл `formatting.mjs` має бути відновлюваним:
+
+- Експорт єдиний — `async function check(cwd = process.cwd()): Promise<number>`.
+- Імпорти: `existsSync` із `node:fs`; `readFile` із `node:fs/promises`; `join` із `node:path`; `createCheckReporter` із `../../../scripts/lib/check-reporter.mjs`; `anyRunStepIncludes`, `parseWorkflowYaml` із `../../../scripts/lib/gha-workflow.mjs`.
+- Константа `UK_APOSTROPHE_HEADING = '**Український апостроф:**'`.
+- `verifyUkApostropheRuleParagraph` — 4 кроки (heading → `U+0027` і `U+2019` → `’` → pass), кожен невдалий крок робить `failFn` і `return`.
+- `checkV8rIgnore` — обовʼязкові рядки `['.vscode/extensions.json', '.vscode/settings.json']`; парсинг: split `\n` → `trim` → відкинути порожні й `#`-коментарі → `Set`.
+- `checkTextConfigsExistence` — точна таблиця з 5 пар `[path, mdcRef]`; синхронне тіло; повертає `Promise.resolve()`.
+- `checkPackageJsonText` — silent return якщо `package.json` відсутній; `JSON.parse` без try/catch; передає `pkg.scripts?.['lint-text']` у `checkLintTextScript`; перевіряє `.github/workflows/lint-text.yml`, спочатку через `parseWorkflowYaml` + `anyRunStepIncludes(..., 'bun run lint-text')`, з fallback на `wf.includes('bun run lint-text')`, якщо парсер не повернув root.
+- `checkLintTextScript` — успіх **тільки** на `'n-cursor lint-text'` (після `trim`).
+- `check`:
+  1. `createCheckReporter()` → деструктуризація `{ pass, fail }`;
+  2. `await checkV8rIgnore(pass, fail, cwd)`;
+  3. `await checkTextConfigsExistence(pass, fail, cwd)`;
+  4. збір `textRulePaths` із `.cursor/rules/n-text.mdc` і `npm/mdc/text.mdc` через `existsSync` → якщо пусто, `pass('… пропущено')`; інакше `for…of` із `readFile` і `verifyUkApostropheRuleParagraph(p, body, fail, pass)`;
+  5. `await checkPackageJsonText(pass, fail, cwd)`;
+  6. `return reporter.getExitCode()`.
+- Коментар у тілі `check` явно фіксує, що `text.forbidden-prettier` живе в `rules/text/js/forbidden-prettier.mjs`.

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

@@ -0,0 +1,122 @@
+# lint.mjs
+
+## Огляд
+
+Модуль `lint.mjs` — це тонкий адаптер-обгортка, що реалізує CI-крок (контракт `lint(files)`) для правила `text` у складі n-cursor правил репозиторію. Його єдина роль — делегувати виконання у внутрішній CLI правила `text`, який знаходиться поряд у директорії `../lint/lint.mjs`.
+
+Особливості модуля:
+
+- Працює в режимі **whole-repo**: незалежно від того, які файли передає викликаюча сторона (наприклад, обгортка `lint-js` чи CI-оркестратор), аналіз виконується по всьому репозиторію цілком.
+- Per-file режиму **немає**: вхідний параметр `files` навмисно ігнорується (підкреслено префіксом `_` у назві аргумента).
+- Повертає числовий exit code (Promise), сумісний з конвенцією Unix-процесів: `0` — успіх, ненульовий — помилки лінту.
+- Модуль не містить власної логіки перевірки тексту: вся реальна робота (запуск пов’язаних інструментів типу `dotenv-linter`, `shellcheck`, `v8r` тощо) — у `../lint/lint.mjs`.
+
+Файл написаний у форматі **ES Modules** (`.mjs`) з JSDoc-анотаціями для статичної типізації без TypeScript-компіляції.
+
+## Експорти / API
+
+| Експорт | Тип                                                    | Призначення                                                            |
+| ------- | ------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `lint`  | `async function (files?: string[]) => Promise<number>` | CI-крок-делегат у `runLintTextCli`. Іменований експорт (named export). |
+
+Default-експорту немає. Сторонніх ефектів на рівні модуля (top-level side effects) також немає — лише імпорт залежності.
+
+### Сигнатура
+
+```js
+export async function lint(_files): Promise<number>
+```
+
+### Контракт CI-кроку
+
+Модуль реалізує загальний інтерфейс CI-крока правил n-cursor:
+
+- Назва експорту: `lint`.
+- Сигнатура приймає опціональний `files: string[] | undefined`.
+- Повертає `Promise<number>` — exit code.
+- Не кидає винятків у нормальному сценарії; помилки сигналізуються через ненульовий exit code, який повертає делегат `runLintTextCli`.
+
+## Функції
+
+### `lint(_files)`
+
+**Сигнатура:** `async function lint(_files: string[] | undefined): Promise<number>`
+
+**Параметри:**
+
+| Ім’я     | Тип                     | Опис                                                                                                                                                                                                                                                        |
+| -------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_files` | `string[] \| undefined` | Список файлів, які теоретично потрібно перевірити. **Ігнорується** — правило `text` працює у whole-repo режимі. Префікс `_` у назві аргументу — конвенція, що позначає невикористаний параметр (зокрема, щоб ESLint/lint-правила не лаялись на unused arg). |
+
+**Повертає:** `Promise<number>` — exit code, отриманий від виклику `runLintTextCli()`. Зазвичай `0` означає, що всі перевірки пройшли успішно, а будь-яке інше число — що знайдено порушення або сталася помилка інструмента.
+
+**Side effects:** Сам по собі `lint` додаткових ефектів не вносить. Усі побічні ефекти (запис у stdout/stderr, читання файлів, запуск зовнішніх процесів) виконуються всередині `runLintTextCli()`, на який делегується виклик.
+
+**Поведінка:**
+
+1. Викликає `runLintTextCli()` без аргументів.
+2. Повертає результат як є (через `await` неявно через `return await`-форму — `async`-функція автоматично «розгортає» Promise з тіла).
+
+Логіки трансформації параметрів, фільтрації, перевірки прапорців тощо — немає. Це навмисно мінімалістична функція-адаптер.
+
+## Залежності
+
+### Імпорти
+
+| Що               | Звідки             | Призначення                                                                                                                                                                                                       |
+| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runLintTextCli` | `../lint/lint.mjs` | Запускає реальний CLI-обробник правила `text`. Саме він агрегує запуски під-інструментів (наприклад, `run-dotenv-linter.mjs`, `run-shellcheck.mjs`, `run-v8r.mjs`, які лежать у тій самій директорії `../lint/`). |
+
+### Зовнішні (npm) залежності
+
+Прямих імпортів з npm у файлі немає. Усі npm-залежності (якщо такі є) приховані у транзитивній залежності — `../lint/lint.mjs`.
+
+### Структурний контекст
+
+Файл лежить у `npm/rules/text/js/lint.mjs`. У тій самій директорії розташовані інші CI-крокові модулі правила `text` (наприклад, `formatting.mjs`, `forbidden-prettier.mjs`). Усі вони — однотипні делегати, що реалізують контракт CI-крока.
+
+Бенефіціар:
+
+- `../lint/lint.mjs` — справжній CLI правила `text`, що містить runner-логіку (parsing аргументів, оркестрація під-інструментів, формування звіту, exit code).
+
+## Потік виконання / Використання
+
+### Сценарій 1: виклик через CI-оркестратор правил
+
+1. Оркестратор правил (наприклад, агрегований раннер у `lint-js` чи кореневий `bun run lint`) виявляє правило `text` і знаходить його CI-кроки в `npm/rules/text/js/*.mjs`.
+2. Для кожного CI-крока (зокрема `lint.mjs`) оркестратор імпортує named export `lint`.
+3. Викликає `await lint(filesArrayOrUndefined)`.
+4. Адаптер ігнорує `files`, делегує виклик у `runLintTextCli()`.
+5. Реальний CLI робить whole-repo аналіз: запускає `dotenv-linter`, `shellcheck`, `v8r` тощо (відповідно до того, що оголошено в `../lint/lint.mjs`).
+6. Повертає exit code.
+7. Оркестратор агрегує exit code-и всіх CI-кроків і приймає рішення про загальний успіх/невдачу.
+
+### Сценарій 2: пряме виконання з коду
+
+```js
+import { lint } from 'npm/rules/text/js/lint.mjs'
+
+const code = await lint()
+process.exit(code)
+```
+
+Передача аргументу `files` нічого не змінює (буде проігнорована):
+
+```js
+const code = await lint(['some/file.txt']) // _files ігнорується
+```
+
+### Чому per-file немає
+
+Правило `text` за своєю природою сканує весь репозиторій (наприклад, перевіряє `.env`-файли, shell-скрипти, JSON Schema-файли через v8r). Для нього передача обмеженого списку файлів від CI не має сенсу — обробляти треба весь робочий простір. Звідси й whole-repo режим, явно зафіксований у JSDoc-коментарі та підкреслений підкресленням у назві параметра.
+
+### Очікувані коди виходу
+
+| Code  | Значення                                                                                            |
+| ----- | --------------------------------------------------------------------------------------------------- |
+| `0`   | Усі під-перевірки правила `text` пройшли успішно.                                                   |
+| ≠ `0` | Знайдено порушення або помилка одного з інструментів. Конкретний код визначається `runLintTextCli`. |
+
+### Обробка помилок
+
+Адаптер не містить `try/catch`. Якщо `runLintTextCli` кине виняток (нештатна ситуація), він пробулькується нагору — до викликаючого. Це навмисний дизайн: оркестратор сам вирішує, як трактувати unhandled rejection.

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

@@ -0,0 +1,220 @@
+# `lint.mjs` — CLI-обгортка `lint-text`
+
+## Огляд
+
+Модуль `lint.mjs` — це CLI-обгортка над канонічним підкомандним конвеєром `lint-text` (правило `text.mdc`). Він призначений для запуску ланцюжка лінтерів текстових і конфігураційних артефактів проєкту з автоматичним передвстановленням залежностей та послідовним виконанням кроків з ранньою зупинкою на першій помилці.
+
+Що робить файл:
+
+1. Авто-встановлює зовнішні бінарники `shellcheck` і `dotenv-linter` через `ensureTool` (механізм brew/scoop/GitHub Release per-platform).
+2. Перевіряє наявність системного `patch` (необхідний для авто-фіксу `shellcheck`) і друкує install-hint, якщо `patch` відсутній.
+3. Послідовно запускає п'ять кроків лінтінгу:
+   - `cspell .` — перевірка правопису з використанням словника `@nitra/cspell-dict`;
+   - `runShellcheckText()` — авто-фікс і фінальна перевірка `*.sh` через `shellcheck`;
+   - `runDotenvLinter()` — авто-фікс і фінальна перевірка `.env*` через `dotenv-linter`;
+   - `bunx markdownlint-cli2 --fix "**/*.md" "**/*.mdc"` — авто-фікс Markdown;
+   - `runV8rWithGlobs()` — schema-валідація `json/json5/yaml/yml/toml` через `v8r`.
+4. Першу ненульову exit-код у ланцюжку повертає як код виходу всього прогону; наступні кроки не запускаються.
+
+Призначення preflight-блоку: без авто-встановлення локальний прогін може успішно пройти `cspell` і `markdownlint`, а CI на `ubuntu-latest` (де `shellcheck` є передвстановленим, але `dotenv-linter` — ні) падає на кроці `dotenv-linter` з неінформативним повідомленням. `ensureTool` збирає всі відсутні бінарники до запуску першого кроку.
+
+Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) описаний у `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
+
+## Експорти / API
+
+| Експорт          | Тип                     | Призначення                                                                                                                                                                                                                             |
+| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runLintTextCli` | `() => Promise<number>` | Публічна CLI-форма команди `lint-text`. Використовується з `bin/n-cursor.js` як підкоманда `lint-text`. Серіалізує виконання через `withLock('lint-text')` і додатково дедуплікує запуски за станом git-дерева через `runStandardLint`. |
+
+Інші ідентифікатори модуля (`PATCH_PREFLIGHT`, `resolvePreflightBin`, `printPreflightMissingMessage`, `preflight`, `runLintTextSteps`) — внутрішні; не експортуються і не призначені для зовнішнього використання.
+
+## Функції
+
+### `resolvePreflightBin(dep)`
+
+Шукає шлях до бінарника `dep.bin` у `PATH`. На Windows (`process.platform === 'win32'`) додатково перебирає альтернативні імена з `dep.winBins` (наприклад, для випадків з `.exe`/`.cmd` варіаціями).
+
+- Сигнатура: `function resolvePreflightBin(dep: PreflightDep): string | null`
+- Параметри:
+  - `dep` — опис залежності з canon-списку preflight-перевірок (тип `PreflightDep`).
+- Повертає: абсолютний шлях до знайденого бінарника або `null`, якщо бінарник не знайдено.
+- Side effects: відсутні (виклик `resolveCmd` лише читає `PATH`, не модифікує процес).
+
+### `printPreflightMissingMessage(dep)`
+
+Друкує stderr-повідомлення про відсутній бінарник: рядок-маркер з іменем, пояснення наслідків, install-команди і посилання на правило `text.mdc`.
+
+- Сигнатура: `function printPreflightMissingMessage(dep: PreflightDep): void`
+- Параметри:
+  - `dep` — опис залежності, джерело пояснення (`dep.explanation`) та install-команд (`dep.install`).
+- Повертає: нічого (`undefined`).
+- Side effects: виводить кілька рядків у `console.error` (stderr). Структура виводу:
+  - `❌ <bin> не знайдено в PATH.`
+  - відступний рядок з `dep.explanation`;
+  - заголовок `   Встанови:`;
+  - по рядку для кожного елемента `dep.install`;
+  - підказку `   Деталі: text.mdc → секція про lint-text.`
+
+### `preflight(dep)`
+
+Виконує preflight-перевірку наявності бінарника й сигналізує результат через консоль.
+
+- Сигнатура: `function preflight(dep: PreflightDep): boolean`
+- Параметри:
+  - `dep` — опис залежності для перевірки в `PATH`.
+- Повертає: `true`, якщо бінарник знайдено; `false`, якщо відсутній.
+- Side effects:
+  - На pass-шляху друкує `dep.successMsg` у `console.log`;
+  - На fail-шляху викликає `printPreflightMissingMessage(dep)` (вивід у `console.error`).
+
+### `runLintTextSteps()`
+
+Внутрішня функція, що послідовно прокручує всі кроки `lint-text` без захоплення локу (лок забезпечується зовнішньою обгорткою `runStandardLint`).
+
+- Сигнатура: `function runLintTextSteps(): number`
+- Параметри: немає.
+- Повертає: `0`, якщо всі кроки успішні; інакше — exit-код першого кроку, що повернув ненульове значення.
+- Алгоритм:
+  1. `ensureTool('shellcheck')` — авто-встановлення `shellcheck`; кидає виключення на провал (поширюється як exit `1` через зовнішній `runStandardLint`).
+  2. `ensureTool('dotenv-linter')` — те саме для `dotenv-linter`.
+  3. `preflight(PATCH_PREFLIGHT)` — hint-only перевірка `patch`; якщо `patch` відсутній — повертає `1` без подальших спроб.
+  4. `runLintStep('cspell', 'npx', ['cspell', '.'])` — `cspell .` через `npx`; ранній return при ненульовому коді.
+  5. Друк заголовку `▶ shellcheck (авто-фікс + фінальна перевірка *.sh)` і виклик `runShellcheckText()`; ранній return при ненульовому коді.
+  6. Друк заголовку `▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)` і виклик `runDotenvLinter()`; ранній return при ненульовому коді.
+  7. `runLintStep('markdownlint', 'bunx', ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc'])` — авто-фікс Markdown; ранній return при ненульовому коді.
+  8. Друк заголовку `▶ v8r (schema-валідація json/json5/yaml/yml/toml)` і повернення результату `runV8rWithGlobs()` як підсумкового exit-коду.
+- Side effects: записує лог-рядки у `stdout`; запускає дочірні процеси через `runLintStep` / `ensureTool` / спеціалізовані обгортки; модифікує файлову систему через авто-фікс-кроки (`shellcheck -f diff` + `patch -p1`, `dotenv-linter --fix`, `markdownlint-cli2 --fix`).
+
+### `runLintTextCli` (експорт)
+
+Публічна CLI-форма команди.
+
+- Сигнатура: `const runLintTextCli: () => Promise<number>`
+- Параметри: немає.
+- Повертає: `Promise<number>` — фінальний exit-код прогону (після lock + дедупу).
+- Реалізація: делегує до `runStandardLint(import.meta.dirname, () => runLintTextSteps())`, тобто:
+  - `runStandardLint` бере лок з ім'ям, похідним від директорії скрипту (`import.meta.dirname`);
+  - дедуплікує запуски за станом git-дерева (якщо нічого не змінилося з попереднього успішного прогону — повторного виконання не буде);
+  - всередині локу викликає `runLintTextSteps()`.
+- Side effects: лок-файл, лог-рядки, дочірні процеси (через внутрішній `runLintTextSteps`).
+
+## Типи
+
+### `PreflightDep`
+
+Опис однієї залежності preflight-блоку. Визначений локальним JSDoc `@typedef`-ом.
+
+| Поле          | Тип               | Опис                                                                         |
+| ------------- | ----------------- | ---------------------------------------------------------------------------- |
+| `bin`         | `string`          | Ім'я виконуваного файлу (POSIX-варіант).                                     |
+| `winBins`     | `string[]` (опц.) | Альтернативні імена бінарника на Windows.                                    |
+| `explanation` | `string`          | Наслідки відсутності бінарника (для людино-зрозумілого stderr-повідомлення). |
+| `install`     | `string[]`        | Команди встановлення, по одному рядку на спосіб/платформу.                   |
+| `successMsg`  | `string`          | Повідомлення для `console.log` на pass-шляху preflight.                      |
+
+## Константи
+
+### `PATCH_PREFLIGHT`
+
+Єдиний об'єкт типу `PreflightDep`, що описує системний `patch` як hint-only залежність:
+
+- `bin: 'patch'`;
+- `explanation: 'Без `patch` не застосуються авто-виправлення shellcheck (`shellcheck -f diff`+`patch -p1`).'` (зібраний через `[...].join('\n   ')` з одного елемента; результат — рівно одна логічна підказка з відступом сумісним з шаблоном виводу `printPreflightMissingMessage`);
+- `install`:
+  - `'macOS:         зазвичай уже є в системі'`;
+  - `'Debian/Ubuntu: sudo apt-get install -y patch'`;
+- `successMsg: '✅ patch знайдено в PATH — shellcheck auto-fix працюватиме'`.
+
+`winBins` не задано — на Windows для `patch` шукається лише власне ім'я.
+
+## Залежності
+
+### Зовнішні модулі (Node built-ins)
+
+- `node:process` — імпортується іменована змінна `platform` для детекції Windows у `resolvePreflightBin`.
+
+### Внутрішні модулі (відносні імпорти)
+
+| Модуль                                       | Що використовується                                                                                                                                        |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `../../../scripts/lib/run-lint-step.mjs`     | `runLintStep` — обгортка для запуску одного кроку лінту з префіксованим логом і нормалізованим exit-кодом. Використовується для `cspell` і `markdownlint`. |
+| `../../../scripts/utils/resolve-cmd.mjs`     | `resolveCmd` — пошук бінарника в `PATH`. Викликається з `resolvePreflightBin`.                                                                             |
+| `../../../scripts/lib/run-standard-lint.mjs` | `runStandardLint` — каноном обгортка `lint-*`: серіалізація через `withLock` + дедуп за станом git-дерева. Викликається з `runLintTextCli`.                |
+| `../../../scripts/lib/ensure-tool.mjs`       | `ensureTool` — авто-встановлення бінарників (brew/scoop/GitHub Release). Викликається для `shellcheck` і `dotenv-linter` на початку `runLintTextSteps`.    |
+| `./run-dotenv-linter.mjs`                    | `runDotenvLinter` — авто-фікс + фінальна перевірка `.env*`.                                                                                                |
+| `./run-shellcheck.mjs`                       | `runShellcheckText` — авто-фікс + фінальна перевірка `*.sh` через `shellcheck`.                                                                            |
+| `./run-v8r.mjs`                              | `runV8rWithGlobs` — schema-валідація `json/json5/yaml/yml/toml`.                                                                                           |
+
+### Зовнішні CLI-інструменти (запускаються як дочірні процеси)
+
+- `npx cspell .` — перевірка правопису (зі словником `@nitra/cspell-dict`).
+- `shellcheck` — статичний аналізатор `*.sh` (передвстановлюється `ensureTool`).
+- `dotenv-linter` — лінтер `.env*` (передвстановлюється `ensureTool`).
+- `patch` — потрібен для `shellcheck -f diff | patch -p1` (hint-only, не встановлюється авто).
+- `bunx markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` — авто-фікс Markdown.
+- `v8r` — schema-валідація конфігів (через `runV8rWithGlobs`).
+
+### Правила-довідники
+
+- `.cursor/rules/text.mdc` (`text.mdc`) — канонічний опис набору `lint-text`.
+- `.cursor/rules/scripts.mdc` — секція «Серіалізація важких CLI-команд», що описує патерн `runStandardLint`/`withLock`.
+
+## Потік виконання / Використання
+
+### Виклик з CLI
+
+Файл експортує `runLintTextCli`, який підключається з `bin/n-cursor.js` як підкоманда `lint-text`. Очікувана схема виклику:
+
+```bash
+n-cursor lint-text
+```
+
+Команда повертає exit-код процесу, рівний фінальному коду повернення з `runLintTextCli`.
+
+### Послідовність кроків (happy path)
+
+1. Зовнішній `runStandardLint` намагається взяти лок `lint-text`. Якщо лок вже зайнятий або стан git-дерева не змінився — прогон може дедуплікуватися або зачекати.
+2. Всередині локу викликається `runLintTextSteps()`:
+   1. `ensureTool('shellcheck')` — авто-встановлення (на CI/локально).
+   2. `ensureTool('dotenv-linter')` — те саме.
+   3. `preflight(PATCH_PREFLIGHT)` — друкує `✅ patch знайдено в PATH — shellcheck auto-fix працюватиме` або hint про встановлення.
+   4. `cspell .` — друк префіксованих логів через `runLintStep`.
+   5. `▶ shellcheck (авто-фікс + фінальна перевірка *.sh)` → `runShellcheckText()`.
+   6. `▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)` → `runDotenvLinter()`.
+   7. `markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` через `bunx`.
+   8. `▶ v8r (schema-валідація json/json5/yaml/yml/toml)` → `runV8rWithGlobs()`; повертає його результат.
+3. `runStandardLint` повертає підсумковий exit-код як `Promise<number>`.
+
+### Семантика помилок
+
+- Якщо `ensureTool` падає (не вдалося встановити `shellcheck` або `dotenv-linter`) — викидає виключення, яке поширюється з `runLintTextSteps` і обробляється на верхньому рівні (`runStandardLint`) як exit `1`.
+- Якщо `patch` відсутній — `preflight` повертає `false`, `runLintTextSteps` повертає `1` ще до запуску `cspell`.
+- Будь-який наступний крок (`cspell`, `shellcheck`, `dotenv-linter`, `markdownlint`, `v8r`), який повернув ненульовий код, припиняє ланцюжок: цей код повертається з `runLintTextSteps` і далі з `runLintTextCli`.
+
+### Приклад використання у скрипті (Node)
+
+```js
+import { runLintTextCli } from './lint.mjs'
+
+const code = await runLintTextCli()
+process.exit(code)
+```
+
+### Побічні ефекти на файлову систему
+
+Кроки `runShellcheckText`, `runDotenvLinter`, `markdownlint-cli2 --fix` і потенційно `v8r` можуть модифікувати файли (авто-фікс). Це штатна поведінка `lint-text` — після прогону можливі правки в робочому дереві.
+
+## Rebuild Test
+
+З цієї документації можна відновити поведінку модуля:
+
+- Один експорт — асинхронна функція `runLintTextCli()` без параметрів, повертає `Promise<number>` (exit-код).
+- Реалізація `runLintTextCli`: `() => runStandardLint(import.meta.dirname, () => runLintTextSteps())`.
+- `runLintTextSteps()` синхронно:
+  1. викликає `ensureTool('shellcheck')` і `ensureTool('dotenv-linter')`;
+  2. виконує `preflight(PATCH_PREFLIGHT)` і повертає `1`, якщо `patch` відсутній;
+  3. послідовно запускає кроки `cspell` → `runShellcheckText` → `runDotenvLinter` → `markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` → `runV8rWithGlobs`, друкуючи відповідні `▶`-заголовки перед shellcheck/dotenv/v8r;
+  4. ранній return на першому ненульовому коді; інакше повертає результат `runV8rWithGlobs()`.
+- Допоміжні функції: `resolvePreflightBin` (з підтримкою `winBins` на Windows), `printPreflightMissingMessage` (формат stderr-повідомлення), `preflight` (об'єднання resolve+print і друк `successMsg` на pass).
+- Константа `PATCH_PREFLIGHT` з полями `bin/explanation/install/successMsg` (без `winBins`).
+- Залежності: `node:process` (`platform`); локальні модулі `run-lint-step`, `resolve-cmd`, `run-standard-lint`, `ensure-tool`, `run-dotenv-linter`, `run-shellcheck`, `run-v8r`.