@nitra/cursor 5.3.3 → 5.4.0

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

@@ -1,263 +1,40 @@
-# deps.mjs — перевірка правила js-mssql.mdc
+---
+docgen:
+  source: npm/rules/js-mssql/js/deps.mjs
+  crc: d5bc32ba
+  score: 100
+---
 
-## Огляд
-
-Модуль `npm/rules/js-mssql/js/deps.mjs` — це автоматичний `check`-скрипт для правила `js-mssql.mdc`. Він виконує дві логічно різні перевірки на корені репозиторію:
-
-1. **Версійний аудит** усіх `package.json` (у тому числі workspace-пакетів): якщо в секції `dependencies` присутній пакет `mssql`, його semver-діапазон має давати ефективну версію не нижче `12.5.0`.
-2. **Статичний аналіз вихідного коду** (JS/TS) на безпечне використання драйвера `mssql`:
-   - заборона створення `new sql.ConnectionPool(...)` всередині функцій (пул має бути singleton на рівні модуля);
-   - заборона спільного (shared) `Request`, наприклад `export const request = pool.request()`;
-   - заборона викликів `query(\`...\`)`як звичайної функції — потрібен tagged template`query\`...\``;
-   - заборона динамічних SQL-списків через `.join(',')` у конструкціях `IN (...)` / `VALUES (...)` (треба TVP, `sql.Table`);
-   - вимога числового парсингу значень у `IN (${...})` (`parseInt` / `Number` / `BigInt` / `parseFloat` + фільтр від `NaN`);
-   - вимога винести значення для `IN (${...})` в окрему змінну і додати guard на пустоту з `throw`.
-
-Скрипт використовує спільну інфраструктуру репорту (`createCheckReporter`) і повертає числовий exit code, придатний для CI. Усі повідомлення префіксовані `js-mssql:` для зручної фільтрації.
-
-Файл є ESM-модулем (`.mjs`), без top-level side effects: експортується лише асинхронна функція `check()`, яка ініціює виконання.
-
-## Експорти / API
-
-| Символ  | Тип                                 | Призначення                                                                                                                                     |
-| ------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `check` | `async function(): Promise<number>` | Єдиний публічний експорт. Виконує повну перевірку правила `js-mssql.mdc` у поточному `process.cwd()` і повертає `0` (OK) або `1` (є порушення). |
-
-Інші функції в модулі (`findAllSourcePathsForMssqlScan`, `asObject`, `getMssqlDependencyRange`, `parseLeadingSemver`, `semverGte`, `auditMssqlVersionInPackageJson`, `aggregateMssqlVersionsAcrossPackages`, `scanMssqlOneSourceFile`, `reportZeroMssqlSourceViolations`, `auditMssqlSources`) є **внутрішніми** — не експортуються і призначені лише для декомпозиції логіки `check()`.
-
-### Константи
-
-| Константа           | Значення                            | Опис                                                                                                         |
-| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `VERSION_PREFIX_RE` | `/^[\^~>=<]+\s*/u`                  | Регулярка для відрізання префіксів semver-діапазону (`^`, `~`, `>`, `=`, `<` та комбінацій) перед парсингом. |
-| `SEMVER_RE`         | `/^(\d+)\.(\d+)\.(\d+)/u`           | Регулярка для захоплення першої semver-трійки `major.minor.patch` після очищення префіксу.                   |
-| `MIN_MSSQL_VERSION` | `{ major: 12, minor: 5, patch: 0 }` | Мінімально дозволена версія `mssql`, як її задає правило `js-mssql.mdc`.                                     |
-
-## Функції
-
-### `findAllSourcePathsForMssqlScan(repoRoot, ignorePaths)`
-
-Внутрішня. Збирає абсолютні шляхи всіх JS/TS-файлів-кандидатів для скану `mssql`.
-
-- **Сигнатура:** `async function findAllSourcePathsForMssqlScan(repoRoot: string, ignorePaths: string[]): Promise<string[]>`
-- **Параметри:**
-  - `repoRoot` — абсолютний шлях до кореня репозиторію;
-  - `ignorePaths` — масив абсолютних шляхів каталогів, які повністю виключаються з обходу (зчитується з `.cursorignore`).
-- **Повертає:** масив абсолютних шляхів файлів, відсортований за відносним шляхом (`localeCompare`), щоб порядок звітів був детермінованим.
-- **Side effects:** читає файлову систему через `walkDir`; нормалізує windows-роздільники `\` у POSIX `/` перед перевіркою `isMssqlScanSourceFile`.
-
-### `asObject(v)`
-
-Внутрішня. Безпечне приведення невідомого значення до plain-object.
-
-- **Сигнатура:** `function asObject(v: unknown): Record<string, unknown>`
-- **Логіка:** повертає `{}`, якщо `v` falsy, не `object`, або масив; інакше повертає сам `v` як `Record<string, unknown>` (через JSDoc-cast).
-- **Side effects:** немає.
-
-### `getMssqlDependencyRange(deps)`
-
-Внутрішня. Витягає рядок версії `dependencies.mssql`.
-
-- **Сигнатура:** `function getMssqlDependencyRange(deps: unknown): string | null`
-- **Параметри:** `deps` — значення поля `dependencies` з `package.json` (може бути будь-чим).
-- **Повертає:** триманий (`trim`) рядок версії, або `null`, якщо ключ відсутній / значення не є непорожнім рядком.
-- **Side effects:** немає.
-
-### `parseLeadingSemver(range)`
-
-Внутрішня. Парсить першу semver-трійку з діапазону виду `"^12.5.0"`, `">=12.5.0"`, `"12.5.0"`.
-
-- **Сигнатура:** `function parseLeadingSemver(range: string): { major: number, minor: number, patch: number } | null`
-- **Параметри:** `range` — версійний діапазон у синтаксисі npm.
-- **Повертає:** об'єкт `{ major, minor, patch }` або `null`, якщо не вдалось розпарсити (або будь-який компонент — `NaN`).
-- **Алгоритм:**
-  1. `String(range).trim()` → видалення префіксів через `VERSION_PREFIX_RE`;
-  2. `match(SEMVER_RE)` → захоплення трьох чисел;
-  3. конвертація через `Number`, перевірка `Number.isNaN`.
-- **Side effects:** немає.
-
-### `semverGte(a, b)`
-
-Внутрішня. Порівняння semver "більше або дорівнює".
-
-- **Сигнатура:** `function semverGte(a: SemverObj, b: SemverObj): boolean`
-- **Параметри:** обидві трійки `{ major, minor, patch }`.
-- **Повертає:** `true`, якщо `a >= b` за лексикографічним порядком `(major, minor, patch)`.
-- **Side effects:** немає.
-
-### `auditMssqlVersionInPackageJson(rel, parsed, pass, fail)`
-
-Внутрішня. Аудит одного `package.json` на `dependencies.mssql`.
-
-- **Сигнатура:** `function auditMssqlVersionInPackageJson(rel: string, parsed: unknown, pass: (msg: string) => void, fail: (msg: string) => void): { found: 0 | 1, bad: 0 | 1 }`
-- **Параметри:**
-  - `rel` — людино-читабельний шлях (відносний, з `/` як роздільник);
-  - `parsed` — розпарсений JSON `package.json`;
-  - `pass`, `fail` — колбеки звіту з `createCheckReporter`.
-- **Повертає:** інкремент лічильників:
-  - `found` — `1`, якщо в `dependencies` знайдено ключ `mssql`, інакше `0`;
-  - `bad` — `1`, якщо знайдено, але версія нечитабельна або менша за `MIN_MSSQL_VERSION`.
-- **Side effects:** виклики `pass(...)` / `fail(...)` з конкретними повідомленнями (формат `js-mssql: <rel>: ... (js-mssql.mdc)`).
+# deps.mjs
 
-### `aggregateMssqlVersionsAcrossPackages(repoRoot, pkgJsonPaths, pass, fail)`
-
-Внутрішня. Прогін усіх `package.json` із підсумками.
-
-- **Сигнатура:** `async function aggregateMssqlVersionsAcrossPackages(repoRoot: string, pkgJsonPaths: string[], pass: (msg: string) => void, fail: (msg: string) => void): Promise<{ found: number, bad: number }>`
-- **Параметри:**
-  - `repoRoot` — корінь репозиторію;
-  - `pkgJsonPaths` — абсолютні шляхи до всіх знайдених `package.json`.
-- **Повертає:** сукупні лічильники `{ found, bad }` по всіх файлах.
-- **Side effects:**
-  - читає кожен `package.json` через `readFile`;
-  - якщо файл — невалідний JSON, викликає `fail('js-mssql: <rel> — невалідний JSON')` і пропускає його (`continue`);
-  - акумулює інкременти з `auditMssqlVersionInPackageJson`.
-
-### `scanMssqlOneSourceFile(rel, content, counters, fail)`
-
-Внутрішня. Прогін **одного** JS/TS-файлу через шість сканерів з `../lib/mssql-pool-scan.mjs`.
-
-- **Сигнатура:** `function scanMssqlOneSourceFile(rel: string, content: string, counters: Record<string, number>, fail: (msg: string) => void): void`
-- **Параметри:**
-  - `rel` — relative-шлях файлу (для повідомлень);
-  - `content` — повний вихідний код файлу;
-  - `counters` — мутабельний агрегатор лічильників (див. нижче);
-  - `fail` — колбек звіту про порушення.
-- **Лічильники в `counters` (інкрементуються по одному за порушення):**
-  - `violations` — `new sql.ConnectionPool(...)` всередині функції;
-  - `sharedRequestViolations` — shared `Request` (наприклад `export const request = pool.request()`);
-  - `unsafeQueryCalls` — `query(\`...\`)` як виклик функції замість tagged template;
-  - `unsafeDynamicSqlLists` — динамічні SQL-списки через `.join(',')` у `IN/VALUES`;
-  - `unparsedInLists` — `IN (${...})` без числового парсера значень;
-  - `inListGuardViolations` — відсутній або неправильно розташований guard на пустоту IN-списку (розгалуження за `v.reason === 'missing_guard'` дає різні тексти повідомлень).
-- **Side effects:** виклики `fail(...)` з конкретним `:line` та `snippet` для кожного знайденого порушення; мутує `counters`.
-
-### `reportZeroMssqlSourceViolations(counters, pass)`
-
-Внутрішня. Для кожного лічильника, що залишився `0`, дає один `pass`-рядок.
-
-- **Сигнатура:** `function reportZeroMssqlSourceViolations(counters: Record<string, number>, pass: (msg: string) => void): void`
-- **Семантика:** перетворює "відсутність порушень" на явні позитивні рядки звіту — щоб у вихідному логу було видно, які саме інваріанти виконано (а не лише сумарний `OK`).
-- **Side effects:** виклики `pass(...)` (від 0 до 6, залежно від лічильників).
-
-### `auditMssqlSources(repoRoot, ignorePaths, pass, fail)`
-
-Внутрішня. Повний аудит усіх JS/TS-джерел репо щодо безпечного використання `mssql`.
-
-- **Сигнатура:** `async function auditMssqlSources(repoRoot: string, ignorePaths: string[], pass: (msg: string) => void, fail: (msg: string) => void): Promise<void>`
-- **Алгоритм:**
-  1. збирає список файлів через `findAllSourcePathsForMssqlScan`;
-  2. якщо файлів немає — один `pass`-рядок `'js-mssql: немає JS/TS файлів для скану singleton ConnectionPool'` і `return`;
-  3. ініціалізує `counters` нулями (`violations`, `sharedRequestViolations`, `unsafeQueryCalls`, `unsafeDynamicSqlLists`, `unparsedInLists`, `inListGuardViolations`);
-  4. послідовно читає кожен файл через `readFile(absPath, 'utf8')`, нормалізує `rel` і викликає `scanMssqlOneSourceFile`;
-  5. в кінці викликає `reportZeroMssqlSourceViolations(counters, pass)`.
-- **Side effects:** I/O (читання файлів); виклики `pass` / `fail`.
-
-### `check()` _(export)_
-
-Публічна. Виконує повну перевірку правила.
-
-- **Сигнатура:** `export async function check(): Promise<number>`
-- **Параметри:** немає (працює відносно `process.cwd()`).
-- **Повертає:** `number` — exit code від `reporter.getExitCode()` (`0` — OK, `1` — є проблеми).
-- **Алгоритм:**
-  1. створює репортер: `createCheckReporter()` → деструктурує `{ pass, fail }`;
-  2. `repoRoot = process.cwd()`;
-  3. **early-return**: якщо в корені немає `package.json` (`existsSync`), записує `pass('js-mssql: package.json у корені відсутній — перевірку пропущено')` і повертає поточний exit code;
-  4. зчитує `ignorePaths` через `loadCursorIgnorePaths(repoRoot)`;
-  5. збирає всі `package.json` у репозиторії через `findAllPackageJsonPaths(repoRoot, ignorePaths)`;
-  6. **early-return**: якщо `package.json` не знайдено зовсім — `pass('js-mssql: package.json не знайдено — перевірку пропущено')` + повернення exit code;
-  7. виконує `aggregateMssqlVersionsAcrossPackages(...)` → `{ found, bad }`;
-  8. **early-return**: якщо `found === 0`, `pass('js-mssql: пакет mssql не знайдено в dependencies жодного package.json')` + повернення exit code (статичний аналіз не запускається, бо `mssql` у проєкті не використовується);
-  9. якщо `bad === 0` — `pass('js-mssql: всі знайдені dependencies.mssql відповідають мінімальній версії 12.5.0 (<found>)')`;
-  10. виконує `auditMssqlSources(repoRoot, ignorePaths, pass, fail)`;
-  11. повертає `reporter.getExitCode()`.
-- **Side effects:** I/O (читання FS), звітування через `pass`/`fail` репортера.
-
-## Залежності
-
-### Стандартні модулі Node.js
-
-| Імпорт             | Звідки             | Використання                                                                       |
-| ------------------ | ------------------ | ---------------------------------------------------------------------------------- |
-| `existsSync`       | `node:fs`          | Перевірка наявності `package.json` у корені (швидкий синхронний guard).            |
-| `readFile`         | `node:fs/promises` | Асинхронне читання `package.json` та джерельних файлів у UTF-8.                    |
-| `join`, `relative` | `node:path`        | Побудова шляху до `package.json` та нормалізація відносних шляхів для повідомлень. |
-
-### Внутрішні модулі репозиторію
-
-| Імпорт                                         | Звідки                                               | Призначення                                                                                        |
-| ---------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `createCheckReporter`                          | `../../../scripts/lib/check-reporter.mjs`            | Уніфікований репортер для всіх `check`-скриптів: накопичує `pass`/`fail` рядки і формує exit code. |
-| `findAllPackageJsonPaths`                      | `../../../scripts/utils/find-package-json-paths.mjs` | Рекурсивний пошук усіх `package.json` (моно-репо/workspaces) з урахуванням ignore-шляхів.          |
-| `findMssqlPerRequestConnectionInText`          | `../lib/mssql-pool-scan.mjs`                         | Пошук `new sql.ConnectionPool(...)` всередині функцій.                                             |
-| `findSharedMssqlRequestInText`                 | `../lib/mssql-pool-scan.mjs`                         | Пошук shared `Request` (наприклад `export const request = pool.request()`).                        |
-| `findUnsafeMssqlQueryTemplateCallInText`       | `../lib/mssql-pool-scan.mjs`                         | Пошук `query(\`...\`)` як звичайного виклику замість tagged template.                              |
-| `findUnsafeMssqlDynamicSqlListInText`          | `../lib/mssql-pool-scan.mjs`                         | Пошук динамічних SQL-списків через `.join(',')` у `IN/VALUES`.                                     |
-| `findUnsafeMssqlInListUnparsedInText`          | `../lib/mssql-pool-scan.mjs`                         | Пошук `IN (${...})` без числового парсингу значень.                                                |
-| `findUnsafeMssqlInListMissingEmptyGuardInText` | `../lib/mssql-pool-scan.mjs`                         | Пошук IN-списків без guard'у на пустоту з `throw`.                                                 |
-| `isMssqlScanSourceFile`                        | `../lib/mssql-pool-scan.mjs`                         | Фільтр-предикат: чи треба сканувати файл за його relative-шляхом.                                  |
-| `loadCursorIgnorePaths`                        | `../../../scripts/lib/load-cursor-config.mjs`        | Завантаження `.cursorignore` → масив абсолютних ignore-шляхів.                                     |
-| `walkDir`                                      | `../../../scripts/utils/walkDir.mjs`                 | Рекурсивний обхід файлової системи з callback на кожен файл і ignore-каталогами.                   |
-
-### Очікувана форма колбеків репортера
-
-```js
-const reporter = createCheckReporter()
-// reporter: { pass(msg: string): void, fail(msg: string): void, getExitCode(): number }
-```
-
-`pass` додає позитивне повідомлення (не впливає на exit code), `fail` — фіксує порушення і змушує `getExitCode()` повернути `1`.
-
-## Потік виконання / Використання
-
-### Сценарій інтеграції
-
-Модуль є частиною інфраструктури `n-cursor` правил `npm/rules/js-mssql/`. Він викликається універсальним runner'ом правил (наприклад через `bun run` або `n-cursor` CLI), який імпортує `check` і використовує її exit code як підсумок.
-
-Типове використання:
-
-```js
-import { check } from './deps.mjs'
+## Огляд
 
-const exitCode = await check()
-process.exit(exitCode)
-```
+request
+Витягує рядок версії `dependencies.mssql` з `package.json` (js-mssql.mdc)
 
-### Послідовність дій усередині `check()`
+check
+Перевіряє використання `mssql` у джерелах коду та порівнює його версію з версією у `package.json` (package.json)
 
-1. **Ініціалізація репортера.** Створюється локальний `reporter` через `createCheckReporter()`.
-2. **Guard 1 — кореневий `package.json`.** Якщо в `process.cwd()` немає `package.json`, перевірка вважається непридатною; виставляється `pass` і повертається exit code (зазвичай `0`).
-3. **Завантаження ignore-шляхів.** Зчитуються через `loadCursorIgnorePaths(repoRoot)`.
-4. **Збір усіх `package.json`.** `findAllPackageJsonPaths(repoRoot, ignorePaths)` повертає масив абсолютних шляхів усіх `package.json` репозиторію (з урахуванням workspace-пакетів і ignore).
-5. **Guard 2 — порожній список.** Якщо `package.json` зовсім немає — пропуск перевірки з відповідним `pass`.
-6. **Версійний аудит.** `aggregateMssqlVersionsAcrossPackages` обходить кожен `package.json`, парсить JSON, для кожного знайденого `dependencies.mssql` запускає `auditMssqlVersionInPackageJson`. Підсумок — `{ found, bad }`.
-7. **Guard 3 — `mssql` не використовується.** Якщо `found === 0`, фіксується позитивний рядок `'js-mssql: пакет mssql не знайдено в dependencies жодного package.json'` і виконання завершується — статичний аналіз джерел **не запускається** (немає сенсу шукати порушення для пакета, якого немає в залежностях).
-8. **Підсумковий pass про версії.** Якщо `bad === 0` (всі версії OK), додається підсумковий `pass` з кількістю знайдених.
-9. **Аудит джерел.** `auditMssqlSources` сканує всі JS/TS-файли (через `walkDir` + `isMssqlScanSourceFile`), застосовує шість сканерів безпеки і фіксує кожне порушення через `fail`. Відсутність порушень за кожним типом конвертується у явний `pass` через `reportZeroMssqlSourceViolations`.
-10. **Повернення exit code.** `reporter.getExitCode()` → `0` якщо жодного `fail` не було, інакше `1`.
+## Поведінка
 
-### Формати повідомлень
+request
+Витягує рядок версії `dependencies.mssql` з package.json
 
-Усі повідомлення мають префікс `js-mssql:` і додатково цитують правило `js-mssql.mdc` у негативних випадках. Приклади:
+request
+Витягує рядок версії `dependencies.mssql` з package.json
 
-- **Версія OK:** `js-mssql: package.json: dependencies.mssql "^12.5.0" (>=12.5.0)`
-- **Версія нижче мінімуму:** `js-mssql: package.json: dependencies.mssql "^11.0.0" — має бути >=12.5.0 (js-mssql.mdc)`
-- **Невалідний JSON:** `js-mssql: package.json — невалідний JSON`
-- **Per-request pool:** `js-mssql: src/db.js:42 — не створюй new sql.ConnectionPool(...) на кожен запит; використовуй singleton sql.ConnectionPool: <snippet>`
-- **Відсутній guard для IN:** `js-mssql: src/db.js:58 — перед IN-списком "ids" потрібна перевірка на пустоту з throw (наприклад if (!ids.length) throw ...), інакше можливі некоректні запити (js-mssql.mdc): <snippet>`
+check
+Аудитує використання mssql у джерелах коду та перевіряє відповідність версії mssql у package.json
 
-### Платформо-незалежна нормалізація шляхів
+## Публічний API
 
-У всіх місцях, де формується `rel`, послідовно застосовується `relative(repoRoot, absPath).split('\\').join('/')`. Це робить повідомлення стабільними на Windows і POSIX одночасно й узгодженими з шаблонами `isMssqlScanSourceFile`.
+request: Створює запит для бази даних
+request: Формує запит для бази даних
+check: Перевіряє відповідність проєкту правилу js-mssql.mdc
 
-### Корнер-кейси
+## Гарантії поведінки
 
-- **Відсутній `package.json` у корені** — перевірка повністю пропускається з позитивним `pass`.
-- **Жодного `package.json`** (наприклад, у нестандартному репо без npm) — перевірка пропускається.
-- **`dependencies` відсутній або не object** — `getMssqlDependencyRange` повертає `null` через `asObject`, лічильник не збільшується.
-- **Нечитабельна версія** (наприклад `"latest"`, `"workspace:*"`, `"git+..."` без чистого `MAJOR.MINOR.PATCH`) — `parseLeadingSemver` повертає `null`, фіксується `fail` "має нечитабельну версію".
-- **Версія дорівнює мінімуму** — `semverGte(parsedVer, MIN_MSSQL_VERSION)` дає `true`, фіксується `pass`.
-- **`mssql` відсутній у всіх `package.json`** — статичний аналіз не запускається (оптимізація для проєктів, які не використовують MSSQL).
-- **Файл — невалідний JSON** — фіксується `fail`, обхід продовжується (`continue`).
-- **Жодного JS/TS-файлу** у репо для скану — фіксується позитивний `pass`, виконання продовжується нормально.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -1,153 +1,38 @@
 ---
 docgen:
   source: npm/rules/js-run/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# fix.mjs — точка входу правила `js-run`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/js-run/fix.mjs` — це **диспетчер правила** `js-run` у пакеті `@nitra/cursor`. Він виконує дві ролі одночасно:
+Виконує застосування політики JS-занепокоєних до mdc-refs на вхідному контексті прогону та повертає результат.
 
-1. **Library-режим** — експортує функцію `run(ctx)`, яку викликає зовнішній CLI-оркестратор (`npx @nitra/cursor fix <id>`) під час пакетного прогону всіх правил. У цьому режимі модуль не торкається `process.exit` і повертає `Promise<number>` із кодом виходу.
-2. **Standalone-режим** — якщо файл запущено напряму (`bun rules/js-run/fix.mjs`), він поводиться як повноцінний entry-point: завантажує конфіг, застосовує whitelist, друкує підсумок і завершує процес із відповідним exit-code.
+Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`, завантажує конфігурацію, перевіряє дозволені елементи та повертає код виходу.
 
-Усю фактичну логіку (визначення `applies`, JS-concerns, policy-перевірки, mdc-references) інкапсулює спільна функція `runStandardRule`. `fix.mjs` лише прокидає `import.meta.dirname` (директорія правила) до неї або до CLI-обгортки `runRuleCli`. Файл не містить власних доменних перевірок — він суто структурний і дотримується конвенції «двох ролей `fix.mjs`», прийнятої в `@nitra/cursor` для всіх стандартних правил.
+## Поведінка
 
-Назву правила (`js-run`) система визначає не з вмісту цього файлу, а з імені директорії, в якій він лежить (`npm/rules/js-run/`). Це дозволяє створювати ідентичні `fix.mjs` для багатьох правил, не дублюючи логіку.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних до політики до mdc-refs.
+    *   Повертає результат прогону.
+2. Запуск правила у режимі CLI.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації.
+    *   Виконує перевірку дозволених елементів.
+    *   Виконує підбиття підсумків.
+    *   Повертає код виходу.
 
-## Експорти / API
+## Публічний API
 
-| Експорт | Тип                                            | Призначення                                                                          |
-| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `run`   | `function(ctx?: RuleContext): Promise<number>` | Library entry-point правила — викликається зовнішнім оркестратором у тому ж процесі. |
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-Додатково в модулі присутній **side-effect блок** на рівні модуля: якщо `isRunAsCli(import.meta.url)` повертає `true`, модуль виконує `await runRuleCli(...)` і завершує процес через `process.exit(...)`. Цей блок не є експортом, але є частиною публічної поведінки файлу.
+## Гарантії поведінки
 
-Файл не має default-експорту і не реекспортує нічого зі своїх залежностей.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` _(необовʼязковий)_ — обʼєкт контексту прогону. Тип імпортується з `../../scripts/lib/run-standard-rule.mjs` як `RuleContext`. Зазвичай містить розділяємий між правилами кеш обходу файлової системи (`walkCache`) та інші cross-rule артефакти, які дозволяють зекономити IO при батч-прогоні. Якщо аргумент не передано, `runStandardRule` створює локальний контекст самостійно.
-- **Повертає:** `Promise<number>` — exit-code прогону:
-  - `0` — порушень не знайдено (OK);
-  - `1` — знайдено хоча б одне порушення.
-- **Side effects:** делегуються в `runStandardRule`. Можливі: читання файлів проєкту, читання `meta.json` правила, друк діагностики у stdout/stderr, запис у спільні структури `ctx`. Сам `run` `process.exit` не викликає — це принципово для library-режиму, де декілька правил мають викликатись підряд в одному процесі.
-- **Алгоритм:** одна делегація — `runStandardRule(import.meta.dirname, ctx)`. `import.meta.dirname` — абсолютний шлях до директорії, в якій лежить `fix.mjs` (тобто `.../npm/rules/js-run/`). За цим шляхом `runStandardRule` знаходить `meta.json`, підправила в `js/`, `policy/`, а також `.mdc`-документ правила.
-
-### Top-level CLI-блок
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Умова активації:** `isRunAsCli(import.meta.url)` — повертає `true`, якщо файл запущено напряму як скрипт (`node`/`bun fix.mjs`), а не імпортовано як модуль. Конкретний механізм перевірки інкапсульований у `run-rule-cli.mjs`.
-- **Що робить:** очікує (`await`) завершення `runRuleCli(import.meta.dirname)`, який окрім логіки `runStandardRule` додатково:
-  - завантажує конфіг проєкту (whitelist, exclusions);
-  - вирівнює аргументи CLI;
-  - друкує summary в кінці прогону;
-  - повертає exit-code.
-- **Завершення:** `process.exit(<code>)` — обовʼязкове для standalone-режиму, бо CI/IDE очікують саме exit-code, а не повернене значення з `import()`.
-- **ESLint suppression:** коментар `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` свідомо вимикає правила, які забороняють `process.exit` у бібліотечному коді. Виключення виправдане роллю файлу як standalone-entry-point — це не лібра у вузькому сенсі.
-
-## Залежності
-
-Файл має рівно **дві** внутрішні залежності, обидві з `npm/scripts/lib/`:
-
-| Імпорт            | Звідки                                    | Що звідти використовується                                                                                                    |
-| ----------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: чи модуль запущено як CLI, а не імпортовано як бібліотека. Приймає `import.meta.url`.                               |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Повна CLI-обгортка над `runStandardRule`: конфіг + whitelist + summary + повернення exit-code. Приймає `import.meta.dirname`. |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Універсальний раннер «стандартного» правила: applies → JS-concerns → policy → mdc-refs. Приймає `(dirname, ctx?)`.            |
-
-Зовнішніх npm-залежностей файл не має. Опосередковано він залежить від:
-
-- структури директорії правила (`meta.json`, підтеки `js/`, `policy/`, `.mdc`-файл);
-- існування файлу `js-run.mdc` поруч (документ правила, на який спирається mdc-refs);
-- API-контракту `RuleContext`, який тримається в `run-standard-rule.mjs`.
-
-## Потік виконання / Використання
-
-### Library-режим (батч-прогон правил)
-
-```js
-// Десь у CLI-оркестраторі @nitra/cursor
-import { run as runJsRun } from '@nitra/cursor/rules/js-run/fix.mjs'
-
-const ctx = createSharedContext() // walkCache, тощо
-const code = await runJsRun(ctx) // 0 або 1
-if (code !== 0) failures.push('js-run')
-```
-
-Послідовність:
-
-1. Оркестратор створює спільний `ctx` (один на всі правила в прогоні).
-2. Імпортує `run` з `fix.mjs` потрібного правила.
-3. Викликає `run(ctx)` і чекає `Promise<number>`.
-4. `run` делегує в `runStandardRule(dirname, ctx)`, яка читає `meta.json`, виконує applies → JS-concerns → policy → mdc-refs.
-5. Результат — exit-code — повертається оркестратору, який агрегує всі коди й вирішує, з чим завершити сам процес.
-
-### Standalone-режим (локальний дебаг або CI per-rule)
-
-```bash
-bun npm/rules/js-run/fix.mjs
-# або
-node npm/rules/js-run/fix.mjs
-```
-
-Послідовність:
-
-1. Інтерпретатор завантажує модуль.
-2. Виконується top-level код: `isRunAsCli(import.meta.url)` повертає `true` (бо файл — entrypoint).
-3. Викликається `await runRuleCli(import.meta.dirname)`:
-   - читає конфіг проєкту і whitelist;
-   - усередині запускає еквівалент `runStandardRule(dirname, ctx)`;
-   - друкує summary у stdout.
-4. Повернений exit-code передається в `process.exit(...)`, який завершує процес з ним же.
-5. CI/IDE/Husky отримують exit-code і вирішують, чи фейлити крок.
-
-### Розширення / модифікація
-
-- Щоб **додати специфічну логіку** для `js-run` за межами «стандартної» воронки — не правити цей файл, а додати чек у `js/` або `policy/` директорію правила. `runStandardRule` сам їх підхопить.
-- Щоб **використати власний контекст** — передавати `ctx` із полем `walkCache: Map<string, FsEntry[]>` для шарингу обходу між правилами.
-- Щоб **тимчасово виключити правило з batch** — оркестратор просто не імпортує `run` цього файлу. Сам файл такої логіки не містить.
-
-### Інваріанти, які слід зберігати при змінах
-
-1. Library-функція `run` **ніколи не викликає** `process.exit` — інакше зламається батч-прогон.
-2. CLI-блок виконується **тільки** під охороною `isRunAsCli(import.meta.url)` — інакше імпорт зробить exit у чужому процесі.
-3. У `runStandardRule` і `runRuleCli` передається `import.meta.dirname`, а не `import.meta.url` — це шлях, а не URL. Підміна типу зламає резолвінг `meta.json` і підправил.
-4. Назва правила береться з імені директорії — не дублюй її рядком у цьому файлі.
-
-## Rebuild Test
-
-Виходячи з цього документа можна відновити еквівалентний файл `fix.mjs`:
-
-1. Імпортувати `isRunAsCli` і `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`.
-2. Імпортувати `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
-3. Експортувати функцію `run(ctx)`, яка повертає `runStandardRule(import.meta.dirname, ctx)`.
-4. Додати top-level `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }` з ESLint-suppression-коментарем для `n/no-process-exit` і `unicorn/no-process-exit`.
-5. JSDoc для `run`: параметр `ctx?: RuleContext` (тип із `run-standard-rule.mjs`), повертає `Promise<number>` (0 — OK, 1 — порушення).
-
-Поведінкові ознаки для перевірки відновленого файлу:
-
-- `import { run } from './fix.mjs'` працює без побічних ефектів (CLI-блок не активується).
-- `bun fix.mjs` запускає повний CLI-прогон і завершує процес із кодом `0` або `1`.
-- `run(ctx)` повертає `Promise`, який резолвиться у число.
-- Файл не містить більше ніяких експортів і ніяких власних доменних перевірок.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.