@nitra/cursor 5.3.3 → 5.4.0

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

@@ -1,144 +1,24 @@
+---
+docgen:
+  source: npm/rules/js-lint-ci/js/lint.mjs
+  crc: 5d06673f
+  score: 100
+---
+
 # lint.mjs
 
 ## Огляд
 
-Файл `lint.mjs` — це CI-крок правила `js-lint-ci`, який реалізує крос-файлову статичну перевірку JavaScript-/TypeScript-кодової бази. Він послідовно запускає два інструменти, що працюють лише на рівні всього репозиторію (а не на рівні окремих файлів):
-
-1. **jscpd** — детектор дубльованого коду (copy-paste detector). Знаходить ідентичні або дуже схожі блоки коду між файлами.
-2. **knip** — детектор «мертвого» коду: невикористаних експортів, файлів, залежностей.
-
-Модуль експортує одну функцію `lint`, яка ігнорує переданий список файлів (через природу інструментів — вони сканують усе репо) і повертає ненульовий код виходу при першому ж порушенні. Це класичний «fail-fast» патерн: якщо `jscpd` знайшов клони — `knip` навіть не запускається, репорт першого інструмента залишається на stdout/stderr CI-логу.
-
-Файл є частиною контракту правил `n-cursor` для лінтингу: правило з суфіксом `-ci` означає, що воно виконується лише в `lint-ci`-фазі (на CI або при явному виклику), а не в інкрементальному per-file lint-сценарії.
-
-## Експорти / API
-
-| Експорт | Тип                       | Призначення                                                               |
-| ------- | ------------------------- | ------------------------------------------------------------------------- |
-| `lint`  | `function` (named export) | Єдина точка входу — виконує jscpd → knip і повертає підсумковий exit code |
-
-Default-експорту немає. Контракт named-експорту `lint` — обов'язковий для всіх файлів `rules/<rule>/js/lint.mjs` у системі правил `n-cursor`.
-
-## Функції
-
-### `lint(_files, cwd)`
-
-#### Сигнатура
-
-```js
-export function lint(_files, cwd = process.cwd()): Promise<number>
-```
-
-#### Параметри
-
-| Параметр | Тип                     | За замовчуванням | Опис                                                                                                                                                                                                                                                           |
-| -------- | ----------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_files` | `string[] \| undefined` | —                | Список файлів для перевірки. **Ігнорується** — і jscpd, і knip працюють лише по всьому репозиторію. Префікс `_` у назві сигналізує, що аргумент не використовується. Згідно з коментарем-шапкою, функція викликається лише з `lint-ci` і завжди з `undefined`. |
-| `cwd`    | `string`                | `process.cwd()`  | Корінь репозиторію — робоча директорія, з якої запускаються `bunx jscpd .` та `bunx knip`. Усі шляхи всередині інструментів резолвляться відносно `cwd`.                                                                                                       |
-
-#### Що повертає
-
-`Promise<number>` — резолвиться з exit code:
-
-- `0` — обидва інструменти завершилися успішно, порушень не знайдено.
-- Ненульове число (`jscpd.status` або `knip.status`) — перший інструмент, що завершився з помилкою, диктує підсумковий код виходу.
-- `1` — fallback, коли `spawnSync` не повернув числовий `status` (наприклад, процес було вбито сигналом і `.status` дорівнює `null`).
-
-Хоча функція синхронно виконує дочірні процеси через `spawnSync`, результат загорнуто у `Promise.resolve(...)` — це уніфікує контракт із асинхронними `lint`-функціями інших правил, де можуть використовуватись `spawn` чи інший асинхронний код.
-
-#### Логіка крок-за-кроком
-
-1. Запустити `bunx jscpd .` у директорії `cwd` з `stdio: 'inherit'` — увесь вивід інструмента йде безпосередньо в термінал/CI-лог.
-2. Нормалізувати `jscpd.status`: якщо це число — взяти як є; інакше — `1`.
-3. Якщо `jc !== 0` — **рано вийти** з цим кодом, не запускаючи knip.
-4. Інакше — запустити `bunx knip --no-config-hints` (прапор пригнічує підказки про конфіг, щоб лог був чистішим).
-5. Повернути `Promise.resolve(knip.status ?? 1)` за тим же правилом нормалізації.
-
-#### Side effects
-
-- **Запуск дочірніх процесів**: `spawnSync('bunx', ...)` блокує поточний потік до завершення процесу. Це навмисно — `lint` повинен дочекатися результату й повернути exit code.
-- **Запис у stdout/stderr**: завдяки `stdio: 'inherit'` весь вивід jscpd і knip потрапляє в термінал викликаючого процесу. Жодних буферизованих рядків `lint` не повертає.
-- **Файлова система — лише читання**: ні jscpd, ні knip із наведеними прапорами не модифікують код; вони генерують репорти в stdout (jscpd за замовчуванням також може писати HTML-репорт у `report/` директорію — це визначається його конфігом, не цим файлом).
-- **Залежності від оточення**: `bunx` повинен бути доступний у `PATH` процесу. Якщо `bunx` відсутній, `spawnSync` поверне `status: null` і `error` — функція віддасть `1`.
-
-## Залежності
-
-### Stdlib (Node.js / Bun)
-
-- `node:child_process` — використовується іменований імпорт `spawnSync`. Це синхронний варіант `spawn`, який повертає об'єкт із полями `status`, `signal`, `stdout`, `stderr`, `error` після завершення дочірнього процесу.
-
-### Зовнішні CLI-інструменти (запускаються через `bunx`)
-
-- **`jscpd`** — Copy/Paste Detector. Запускається з аргументом `.` (поточна директорія = `cwd`). Конфіг (правила обходу, пороги схожості, ігнор-патерни) інструмент шукає сам у `.jscpd.json`, `package.json#jscpd` тощо.
-- **`knip`** — Detect unused files, dependencies and exports. Запускається з прапором `--no-config-hints`, який вимикає підказки про відсутній/неоптимальний конфіг.
-
-### Runtime-залежності
-
-- **`bunx`** — раннер, що йде в комплекті з Bun і виконує бінарники з node_modules або тимчасово завантажує пакет, якщо його немає локально.
-
-### Не імпортується
-
-- Жодних інших модулів проекту цей файл не використовує — він свідомо мінімалістичний і не залежить від інфраструктури `n-cursor` (логерів, конфіг-парсерів, fs-хелперів).
-
-## Потік виконання / Використання
-
-### Контекст виклику
-
-Функція `lint` із цього файлу викликається механізмом правил `n-cursor` (зокрема, командою `lint-ci`). Конвенція така: для кожного правила `rules/<rule-id>/js/lint.mjs` рушій імпортує named export `lint(files, cwd)` і викликає його. Для правила `js-lint-ci` другий аргумент — корінь репо, а перший — завжди `undefined`, бо це крос-файловий аналіз.
-
-### Псевдокод виклику ззовні
-
-```js
-import { lint } from './npm/rules/js-lint-ci/js/lint.mjs'
-
-const code = await lint(undefined, '/path/to/repo')
-if (code !== 0) process.exit(code)
-```
-
-### Сценарій 1: усе чисто
-
-1. `bunx jscpd .` → exit 0, у логи виводиться репорт без знайдених клонів.
-2. `bunx knip --no-config-hints` → exit 0, у логи — порожній/чистий звіт.
-3. `lint` повертає `Promise.resolve(0)`.
-4. CI-крок проходить.
-
-### Сценарій 2: jscpd знайшов клони
-
-1. `bunx jscpd .` → exit ≠ 0, у логи — список клонованих блоків.
-2. `lint` рано виходить із цим кодом, **knip не запускається**.
-3. CI-крок падає. Розробник бачить лише репорт jscpd.
-
-### Сценарій 3: jscpd чистий, knip знайшов мертвий код
-
-1. `bunx jscpd .` → exit 0.
-2. `bunx knip --no-config-hints` → exit ≠ 0, у логи — список невикористаних експортів/файлів.
-3. `lint` повертає цей код.
-4. CI-крок падає з репортом knip.
-
-### Сценарій 4: інструмент крашнувся (сигнал, відсутній bunx)
-
-1. `spawnSync(...).status` повертає `null` (`signal` буде заповнений).
-2. Перевірка `typeof ... === 'number'` дає `false` → fallback `1`.
-3. `lint` повертає `1`. CI бачить generic-fail без чіткого репорту — це слабке місце, але навмисно зведене до мінімуму.
-
-### Чому ігнорується `_files`
-
-Файлово-орієнтовані аналізатори (eslint, stylelint, ...) працюють і per-file, і crosswise. Натомість `jscpd` і `knip` принципово міжфайлові: щоб знайти дубль або невикористаний експорт, треба бачити **всі** файли одночасно. Тому виконувати їх на підмножині не має сенсу — і per-file шлях для цього правила відсутній. Це підкреслено й у JSDoc, і в підкресленні `_` у назві аргумента.
-
-### Спостережувані виходи
+Інструмент виконує аналіз коду за допомогою jscpd та knip. Інструменти ініціюються для проведення перевірок. Результати перевірок фіксуються.
 
-- **Логи**: jscpd і knip пишуть напряму в stdio викликаючого процесу через `stdio: 'inherit'`. `lint` нічого не агрегує.
-- **Exit code**: єдиний канал зворотного зв'язку від `lint` до раннера — числовий код.
+## Поведінка
 
-## Rebuild Test
+1. Запуск інструменту jscpd для перевірки коду.
+2. Перевірка статусу виводу jscpd.
+3. Запуск інструменту knip для перевірки коду.
+4. Перевірка статусу виводу knip.
 
-Якщо реалізовувати файл наново за цією документацією, він має:
+## Гарантії поведінки
 
-1. Імпортувати `spawnSync` із `node:child_process`.
-2. Експортувати named function `lint(_files, cwd = process.cwd())`.
-3. Запустити `bunx jscpd .` синхронно з `cwd` і `stdio: 'inherit'`.
-4. Нормалізувати exit (`typeof status === 'number' ? status : 1`) і рано вийти при ≠ 0.
-5. Інакше — запустити `bunx knip --no-config-hints` за тим же протоколом і повернути нормалізований exit.
-6. Загорнути результат у `Promise.resolve(...)`.
-7. Ігнорувати перший аргумент (префікс `_`).
-8. Не імпортувати жодних інших модулів і не виконувати ніяких записів у файлову систему.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/js-mssql/docs/fix.md

@@ -1,137 +1,32 @@
 ---
 docgen:
   source: npm/rules/js-mssql/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# `npm/rules/js-mssql/fix.mjs`
+# fix.mjs
 
 ## Огляд
 
-Цей файл — точка входу правила `js-mssql` у бібліотеці правил пакета `@nitra/cursor`. Він має **дві ролі одночасно**:
+Виконує застосування JS-занепокоєних на наданому контексті прогону. Застосовує визначену політику та генерує посилання MDC. Повертає результат прогону.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку CLI-оркестратор (`bun n-cursor fix` / `bun n-cursor check`) імпортує разом з іншими правилами й послідовно викликає для одного спільного проходу по робочому дереву (з кешем `walkCache` тощо).
-2. **Standalone mode** — якщо файл запущено напряму (`bun rules/js-mssql/fix.mjs`), він самотужки виконує повний CLI-цикл правила (завантаження конфігу, whitelist, summary) — еквівалент `npx @nitra/cursor fix js-mssql`.
+## Поведінка
 
-Сама логіка перевірки/виправлення у файлі **не реалізується** — це лише тонкий «launcher», який делегує роботу у спільний оркестратор `runStandardRule`. Завдяки цьому всі правила-«standard» (applies → JS-concerns → policy → mdc-refs) мають єдиний, передбачуваний і кешований pipeline.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
-Каталог правила `npm/rules/js-mssql/` містить:
+## Публічний API
 
-- `fix.mjs` — цей файл (entry-point).
-- `js-mssql.mdc` — людиночитна специфікація правила.
-- `meta.json` — мета-інформація правила (id, version, тощо).
-- `js/` — JS-concerns: фіксери/чекери, що працюють на рівні окремих JS/MJS/TS-файлів.
-- `policy/` — policy-перевірки на рівні всього проєкту (зріз даних, агреговані інваріанти).
-- `lib/` — допоміжні модулі правила.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-## Експорти / API
+## Гарантії поведінки
 
-| Експорт | Тип                                  | Призначення                                                                                                               |
-| ------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function (ctx?) => Promise<number>` | Library-режим: одинична точка входу для зовнішнього оркестратора. Повертає exit-code правила (`0` — OK, `1` — порушення). |
-
-Окрім експорту, файл має **top-level side-effect** під CLI-режимом — див. секцію «Потік виконання».
-
-### `run(ctx)`
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` _(optional)_ — об’єкт контексту прогону, який передає CLI-оркестратор. Тип імпортується JSDoc-посиланням з `../../scripts/lib/run-standard-rule.mjs` (`RuleContext`). Зазвичай несе спільні кешовані ресурси між правилами (наприклад, `walkCache` — кеш обходу файлів), щоб не повторювати дорогі IO-операції для кожного правила окремо.
-- **Повертає:** `Promise<number>` — exit-code:
-  - `0` — порушень не знайдено;
-  - `1` — є порушення (правило фейлиться).
-- **Side effects:** залежать від `runStandardRule`: читання файлів проєкту, потенційні автофікси на диску (якщо правило підтримує fix-mode), запис у summary-репорти, оновлення кешів у `ctx`.
-- **Як визначається «корінь правила»:** через `import.meta.dirname` — повний шлях до директорії, де лежить цей `fix.mjs` (тобто `…/npm/rules/js-mssql/`). Саме цей шлях `runStandardRule` використовує, щоб знайти суміжні підтеки `js/`, `policy/`, файл `js-mssql.mdc` та `meta.json`.
-
-## Функції
-
-### `run(ctx)` — див. вище
-
-Єдина функція, оголошена в цьому файлі. Жодних інших публічних чи приватних функцій модуль не містить — уся доменна логіка винесена у бібліотеку `scripts/lib/`.
-
-## Залежності
-
-### Внутрішні (відносні імпорти)
-
-- `../../scripts/lib/run-rule-cli.mjs`
-  - `isRunAsCli(importMetaUrl): boolean` — детектує, чи запущено модуль як CLI-ентрі (а не імпортовано як бібліотеку). Порівнює `import.meta.url` поточного модуля з `process.argv[1]` (URL viewpoint).
-  - `runRuleCli(ruleDir): Promise<number>` — повний standalone-цикл одного правила: config-loading, whitelist, summary, повернення exit-коду.
-- `../../scripts/lib/run-standard-rule.mjs`
-  - `runStandardRule(ruleDir, ctx?): Promise<number>` — узагальнений «standard» pipeline правила: `applies → JS-concerns → policy → mdc-refs`. Використовує `ctx` (наприклад, спільний `walkCache`), коли його передає зовнішній оркестратор.
-  - Експортує JSDoc-тип `RuleContext`, на який посилається анотація `run`.
-
-### Зовнішні (npm)
-
-Прямих імпортів з npm у цьому файлі **немає**. Усі зовнішні залежності інкапсульовані в `scripts/lib/*`.
-
-### Платформенні / runtime
-
-- **Bun ≥ 1.x** (або Node.js з підтримкою `import.meta.dirname`) — використовується `import.meta.dirname` та `import.meta.url`.
-- **ESM** — файл написано як ES-модуль (`.mjs`), використовується `export` + top-level `await`.
-- `process.exit` — глобал Node/Bun, явно лінт-проігноровано для CLI-сценарію.
-
-## Потік виконання / Використання
-
-### Library mode (типовий шлях у CI/IDE)
-
-1. CLI `bun n-cursor fix` (або `check`) сканує `npm/rules/*/fix.mjs`.
-2. Для кожного правила робить `import('…/fix.mjs')` і викликає `mod.run(ctx)` з підготовленим спільним контекстом.
-3. Для `js-mssql`: `run(ctx)` робить **один-рядковий** делегат у `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule` усередині:
-   1. Читає `meta.json` і `*.mdc` поруч із `fix.mjs`.
-   2. Етап **applies** — визначає, чи правило взагалі застосовне до поточного дерева.
-   3. Етап **JS-concerns** — викликає всі чекери/фіксери з `./js/`.
-   4. Етап **policy** — викликає policy-перевірки з `./policy/` (агреговані інваріанти проєкту).
-   5. Етап **mdc-refs** — звіряє наявні зв’язки/посилання у `.mdc`-документі.
-5. Повертає `0` / `1`, оркестратор зводить це у спільний звіт.
-
-### Standalone mode (точкова перевірка людиною)
-
-1. Розробник запускає файл напряму, наприклад:
-   ```bash
-   bun npm/rules/js-mssql/fix.mjs
-   ```
-2. Перевірка `isRunAsCli(import.meta.url)` повертає `true`.
-3. Виконується top-level `await runRuleCli(import.meta.dirname)`:
-   - Завантажує конфіг проєкту.
-   - Застосовує whitelist (які файли/директорії перевіряти).
-   - Викликає той самий стандартний pipeline (під капотом — `runStandardRule`).
-   - Друкує людиночитний summary.
-4. Результат передається в `process.exit(...)` — потрібний для IDE-інтеграції та CI-pipeline’ів, щоб non-zero exit-code сигналізував про порушення.
-
-### Чому окремо `run` і CLI-блок
-
-Розділення на дві ролі дозволяє:
-
-- **уникати дубльованого I/O** у бібліотечному режимі (один обхід дерева, кеш у `ctx`);
-- **зберігати самодостатність** файлу для швидкого «прогнати правило одне, без всього іншого»;
-- **тримати entry-point незмінним** для CLI-оркестратора — той знає лише, що у файлі є експорт `run`.
-
-### Лінт-винятки
-
-Рядок `process.exit(await runRuleCli(import.meta.dirname))` має директивну «глушилку»:
-
-- `n/no-process-exit` (eslint-plugin-n) — за замовчуванням забороняє `process.exit`.
-- `unicorn/no-process-exit` (eslint-plugin-unicorn) — аналогічно.
-
-Обидва правила свідомо відключені **лише** для standalone entry-point: CLI/IDE очікують exit-код для рішення «зелено/червоно».
-
-## Rebuild Test
-
-З опису у цьому документі файл `fix.mjs` для правила `js-mssql` можна відтворити так:
-
-1. Створити ES-модуль `.mjs`.
-2. Імпортувати з `../../scripts/lib/run-rule-cli.mjs` дві іменовані функції: `isRunAsCli` та `runRuleCli`.
-3. Імпортувати з `../../scripts/lib/run-standard-rule.mjs` функцію `runStandardRule`.
-4. Оголосити іменований експорт `run(ctx)`, який повертає `runStandardRule(import.meta.dirname, ctx)`. JSDoc описує `ctx` як `RuleContext` (з того ж модуля) і повернення як `Promise<number>` (`0` — OK, `1` — порушення).
-5. Після експорту перевірити `isRunAsCli(import.meta.url)`; якщо `true` — виконати `process.exit(await runRuleCli(import.meta.dirname))`, попередньо вимкнувши коментарем правила `n/no-process-exit` та `unicorn/no-process-exit` для цього рядка (зі стислою причиною: standalone entry-point потребує exit-коду для CI/IDE).
-6. Не додавати жодних інших експортів і жодної доменної логіки — увесь pipeline `applies → JS-concerns → policy → mdc-refs` лишається в `runStandardRule`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.