@nitra/cursor 5.3.4 → 5.4.0

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

@@ -1,122 +1,25 @@
+---
+docgen:
+  source: npm/rules/text/js/lint.mjs
+  crc: 4ee054a0
+  score: 100
+---
+
 # 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-коментарі та підкреслений підкресленням у назві параметра.
+Файл надає функцію lint, яка делегує завдання CLI правилам. Функція не підтримує режим per-file, і параметр files ігнорується. Функція повертає Promise з кодом виходу.
 
-### Очікувані коди виходу
+## Поведінка
 
-| Code  | Значення                                                                                            |
-| ----- | --------------------------------------------------------------------------------------------------- |
-| `0`   | Усі під-перевірки правила `text` пройшли успішно.                                                   |
-| ≠ `0` | Знайдено порушення або помилка одного з інструментів. Конкретний код визначається `runLintTextCli`. |
+1. Викликається функція lint з аргументом files.
+2. Функція lint делегує виконання у CLI правила.
+3. Режим per-file не підтримується.
+4. Параметр files ігнорується.
+5. Функція повертає Promise з кодом виходу.
 
-### Обробка помилок
+## Гарантії поведінки
 
-Адаптер не містить `try/catch`. Якщо `runLintTextCli` кине виняток (нештатна ситуація), він пробулькується нагору — до викликаючого. Це навмисний дизайн: оркестратор сам вирішує, як трактувати unhandled rejection.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/vue/docs/fix.md

@@ -1,127 +1,34 @@
-# fix.mjs — entry-point правила `vue`
+---
+docgen:
+  source: npm/rules/vue/fix.mjs
+  crc: 38cf876b
+  score: 90
+---
 
-## Огляд
-
-Файл `npm/rules/vue/fix.mjs` — це **точка входу** (entry-point) для правила `vue` у системі `@nitra/cursor`. Файл одночасно виконує дві ролі:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає зовнішній оркестратор (CLI `@nitra/cursor`, інші правила, тести) з підготовленим контекстом прогону.
-2. **Standalone mode** — якщо файл запущено напряму (наприклад, `bun npm/rules/vue/fix.mjs`), він самостійно піднімає повноцінний CLI-цикл, еквівалентний `npx @nitra/cursor fix vue`.
-
-Сам файл не містить специфічної для Vue логіки правил. Уся логіка делегується у спільні бібліотеки `runStandardRule` (виконання стандартних фаз правила) і `runRuleCli` (підготовка CLI-середовища). Завдяки цьому `fix.mjs` у директорії правила `vue` залишається тонким shim-файлом, який лише підставляє свою директорію як ідентифікатор правила.
-
-Стандартний пайплайн, який під цим запускається (через `runStandardRule`), складається з фаз:
-
-- `applies` — детекція файлів/області застосування правила,
-- `JS-concerns` — перевірки JS/JSX/TS-аспектів коду,
-- `policy` — застосування policy-чеків (warn/error),
-- `mdc-refs` — узгодженість MDC-документації та посилань.
-
-## Експорти / API
-
-| Назва | Тип        | Опис                                                                                            |
-| ----- | ---------- | ----------------------------------------------------------------------------------------------- |
-| `run` | `function` | Named export. Library-точка входу правила. Приймає опційний `ctx` і повертає `Promise<number>`. |
-
-**Side-effect експорт:** при виконанні модуля під CLI (умова `isRunAsCli(import.meta.url)`) модуль вмикає standalone-режим і завершує процес викликом `process.exit(...)` з exit-кодом, отриманим від `runRuleCli`. Цей побічний ефект виконується на верхньому рівні модуля (top-level `await`), тому імпорт файлу як ESM-модуля з іншого файлу **не** активує standalone-гілку — її активує лише пряме виконання інтерпретатором.
-
-## Функції
-
-### `run(ctx)`
-
-Library-функція правила. Делегує виконання у спільну реалізацію `runStandardRule`, передаючи їй власну директорію модуля (`import.meta.dirname`) як ідентифікатор правила та переданий контекст.
-
-- **Сигнатура:** `function run(ctx): Promise<number>`
-- **Параметри:**
-  - `ctx` _(optional)_ — об'єкт типу `RuleContext` із модуля `../../scripts/lib/run-standard-rule.mjs`. У ньому, серед іншого, передається `walkCache` для уникнення повторного обходу файлової системи між послідовно запущеними правилами. Якщо `ctx` не передано, `runStandardRule` створює його самостійно.
-- **Повертає:** `Promise<number>` — exit-код прогону правила:
-  - `0` — порушень немає (OK);
-  - `1` — знайдено порушення (rule violations).
-- **Side effects:** усі побічні ефекти ховаються всередині `runStandardRule` (читання файлів проєкту, можливі автоматичні фікси, виведення summary в stdout/stderr). Сам `run` додаткових side-effects не має, поза тим, що значення повернення завжди є `Promise`, навіть якщо `runStandardRule` поверне синхронно — це гарантує контракт async-pipeline для оркестратора.
-- **Помилки:** функція не обгортає виняткові ситуації — будь-яка помилка з `runStandardRule` пробрасується нагору (rejection промісу) і має оброблятись на рівні CLI/орхестратора.
-
-### Top-level standalone-блок
-
-Не функція, а top-level гілка модуля:
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
+# fix.mjs
 
-- **Семантика:** `isRunAsCli(import.meta.url)` повертає `true`, коли поточний модуль є entry-point процесу (тобто Node/Bun запустив саме цей файл, а не імпортував його). У такому разі викликається `runRuleCli` з директорією поточного правила; її exit-код передається у `process.exit(...)`, щоб CI/IDE отримали коректний статус.
-- **Side effects:**
-  - синхронне завершення процесу через `process.exit`;
-  - усе, що робить `runRuleCli` (завантаження конфігу, whitelist, summary).
-- **ESLint-винятки:** standalone-entry-point має право робити `process.exit`, тому над цим викликом стоять директиви `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit`. Це штатна практика для двороле́вих fix.mjs.
-
-## Залежності
-
-Імпорти модуля:
-
-- `isRunAsCli` — з `../../scripts/lib/run-rule-cli.mjs`. Утиліта-детектор: чи поточний модуль є entry-point (CLI mode), чи його імпортнули як бібліотеку.
-- `runRuleCli` — з `../../scripts/lib/run-rule-cli.mjs`. Виконує повну CLI-оркестрацію для одного правила: завантажує конфіг, формує whitelist, друкує summary та повертає exit-код. Використовується тільки у standalone-гілці.
-- `runStandardRule` — з `../../scripts/lib/run-standard-rule.mjs`. Виконує стандартний пайплайн правила: `applies → JS-concerns → policy → mdc-refs`. JSDoc-типи `RuleContext` теж приходять із цього модуля (через `@param`-import).
-
-Неявні залежності:
-
-- Структура директорії правила (`npm/rules/vue/`) має містити очікувані `runStandardRule` під-директорії/файли: `js/`, `lib/`, `policy/`, `meta.json`, `vue.mdc` тощо. Сам `fix.mjs` не звертається до них напряму — він лише підставляє свій `import.meta.dirname`, а решту виявляє shared-runner.
-- ESM-середовище (Node.js ≥ 20 / Bun) з підтримкою `import.meta.url` та `import.meta.dirname`.
-
-## Потік виконання / Використання
-
-### Library mode (виклик з оркестратора)
-
-```js
-import { run } from './npm/rules/vue/fix.mjs'
-
-const exitCode = await run(ctx) // ctx — спільний RuleContext із walkCache
-if (exitCode !== 0) {
-  // у правилі vue знайдено порушення → обробляємо
-}
-```
-
-Послідовність:
-
-1. Оркестратор імпортує `fix.mjs`. Гілка `if (isRunAsCli(...))` не виконується, бо `import.meta.url` не є entry-point.
-2. Оркестратор викликає `run(ctx)`.
-3. `run` передає `import.meta.dirname` (= `…/npm/rules/vue`) і `ctx` у `runStandardRule`.
-4. `runStandardRule` виконує фази `applies → JS-concerns → policy → mdc-refs` для правила `vue`, використовуючи кеші з `ctx` (наприклад, `walkCache`).
-5. Повертається exit-код (`0` або `1`), який оркестратор інтегрує у свій агрегований підсумок.
-
-### Standalone mode (пряме виконання)
-
-```bash
-bun npm/rules/vue/fix.mjs
-# або
-node npm/rules/vue/fix.mjs
-```
-
-Послідовність:
-
-1. Інтерпретатор завантажує модуль; виконуються імпорти.
-2. Виконується top-level код: `isRunAsCli(import.meta.url)` повертає `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)` — це повний еквівалент `npx @nitra/cursor fix vue`:
-   - читає конфіг,
-   - застосовує whitelist,
-   - усередині піднімає той самий `runStandardRule`-цикл (або сумісний з ним),
-   - друкує summary.
-4. Отриманий exit-код передається у `process.exit(...)`, процес завершується з відповідним кодом для CI/IDE.
+## Огляд
 
-### Чому існують дві ролі
+Файл застосовує правило `runStandardRule` до наданого контексту прогону через функцію `runStandardRule` і повертає отриманий результат. У режимі CLI він виконує команду `npx @nitra/cursor fix <id>` та визначає вихідний код процесу на основі отриманого результату.
 
-Подвійна реалізація (`run` + standalone) дозволяє:
+## Поведінка
 
-- викликати правило **разом з іншими** з єдиного оркестратора без зайвого spawn-у процесів і без втрати спільних кешів (бібліотечний шлях);
-- запускати правило **окремо** з командного рядка під час локальної розробки/дебагу, маючи повноцінний CLI-вивід (standalone-шлях).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Використовує runStandardRule для застосування політики.
+    *   Повертає результат прогону.
+2. Запуск у режимі CLI.
+    *   Викликається через `import + run`.
+    *   Виконує повний еквівалент `npx @nitra/cursor fix <id>`.
+    *   Визначає вихідний код процесу на основі результату.
 
-## Rebuild Test
+## Публічний API
 
-Можна повністю відтворити поведінку цього файлу з опису вище:
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-- Імпортуються тільки два символи з двох сусідніх бібліотек: `isRunAsCli`, `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs` та `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
-- Експортується одна named-функція `run(ctx)`, яка повертає результат `runStandardRule(import.meta.dirname, ctx)` — отже, є async (повертає `Promise<number>`).
-- На рівні модуля стоїть умова `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }` з відповідними ESLint-disable-коментарями для `n/no-process-exit` та `unicorn/no-process-exit`.
-- Жодних додаткових іменованих експортів, default-експортів, констант чи побічних викликів у файлі немає.
+## Гарантії поведінки
 
-Цього достатньо, щоб переписати файл байт-у-байт еквівалентно (з точністю до коментарів/форматування), не звертаючись до оригіналу.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.