@nitra/cursor 5.3.4 → 5.4.0

package/rules/js-bun-redis/js/docs/imports.md

@@ -1,176 +1,28 @@
+---
+docgen:
+  source: npm/rules/js-bun-redis/js/imports.mjs
+  crc: 678c233c
+  score: 100
+---
+
 # imports.mjs
 
 ## Огляд
 
-Модуль реалізує AST/текстову перевірку правила `js-bun-redis.mdc` для JavaScript/TypeScript-джерел проєкту. Його завдання — гарантувати, що в усіх JS/TS-файлах репозиторію відсутні заборонені статичні чи динамічні імпорти (а також CommonJS `require`) Redis-клієнтів `ioredis`, `node-redis`, `redis` і підпакетів `@redis/*` / підшляхів `ioredis/...` / `redis/...`. Замість них код повинен використовувати Bun native Redis API: `import { redis } from 'bun'` (див. <https://bun.com/docs/runtime/redis>).
-
-Модуль експортує одну головну функцію `check()`, яка:
-
-1. Перевіряє наявність `package.json` у корені репозиторію (інакше перевірка пропускається як неактуальна).
-2. Завантажує список ігнорованих шляхів через cursor-конфіг.
-3. Обходить дерево репозиторію, збираючи JS/TS-джерела, придатні для скану.
-4. Сканує кожне зібране джерело шукачем заборонених імпортів і генерує звіт через стандартний check-reporter.
-
-Перевірка `package.json` (заборона залежностей `ioredis` / `node-redis` / `redis` / `@redis/*`) реалізована окремо — у Rego-полісі `npm/policy/js_bun_redis/package_json/`, яку запускає `npx @nitra/cursor check`. Поточний файл відповідає виключно за AST/текстовий скан коду.
-
-## Експорти / API
-
-| Експорт | Тип                                 | Призначення                                                                                                                                                        |
-| ------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `check` | `async function(): Promise<number>` | Головна точка входу check-скрипта правила `js-bun-redis`. Повертає код виходу: `0` — порушень немає, `1` — є порушення або є інша помилка, зафіксована репортером. |
-
-Інші функції (`findAllSourcePathsForRedisScan`, `scanSourcesForRedisImports`) є приватними допоміжними і не експортуються.
-
-## Функції
-
-### `findAllSourcePathsForRedisScan(repoRoot, ignorePaths)`
-
-Збирає список абсолютних шляхів JS/TS-джерел, які треба просканувати на заборонені redis-імпорти.
-
-- Сигнатура: `async function findAllSourcePathsForRedisScan(repoRoot: string, ignorePaths: string[]): Promise<string[]>`
-- Параметри:
-  - `repoRoot` — абсолютний шлях до кореня репозиторію, від якого формуються відносні шляхи.
-  - `ignorePaths` — масив абсолютних шляхів каталогів, повністю виключених з обходу `walkDir`.
-- Повертає: `Promise<string[]>` — абсолютні шляхи знайдених файлів, відсортовані за їх відносним шляхом (локалекомпаратор за `relative(repoRoot, ...)`).
-- Поведінка / логіка:
-  1. Створює локальний масив `paths`.
-  2. Викликає `walkDir(repoRoot, callback, ignorePaths)`. Для кожного абсолютного шляху callback:
-     - Будує відносний шлях `relative(repoRoot, absPath)` і нормалізує сепаратори (Windows `\\` → `/`).
-     - Якщо `isRedisScanSourceFile(rel)` повертає `true` (тобто це JS/TS-подібне джерело, цільове для скану) і `shouldSkipFileForRedisScan(rel)` повертає `false` — додає `absPath` у `paths`.
-  3. Сортує `paths` за відносним шляхом через `String.prototype.localeCompare`.
-- Side effects: лише читання структури директорій через `walkDir` (синхронні чи асинхронні `stat`/`readdir` за реалізацією утиліти). Файли не читаються на цьому етапі.
-
-### `scanSourcesForRedisImports(sourcePaths, repoRoot, fail)`
-
-Сканує текстовий вміст кожного з переданих файлів на заборонені redis-імпорти та звітує про порушення.
-
-- Сигнатура: `async function scanSourcesForRedisImports(sourcePaths: string[], repoRoot: string, fail: (msg: string) => void): Promise<number>`
-- Параметри:
-  - `sourcePaths` — абсолютні шляхи джерел, отримані з `findAllSourcePathsForRedisScan`.
-  - `repoRoot` — абсолютний шлях до кореня репозиторію (для нормалізації відносного шляху у повідомленнях).
-  - `fail` — callback репортера, який треба викликати з повідомленням про кожне порушення; саме він контролює exitCode.
-- Повертає: `Promise<number>` — загальну кількість виявлених порушень (`violations`).
-- Поведінка / логіка:
-  1. Ініціалізує лічильник `violations = 0`.
-  2. Для кожного `absPath` зі `sourcePaths`:
-     - Обчислює `rel = relative(repoRoot, absPath)` з нормалізацією `\\` → `/`.
-     - Читає файл `await readFile(absPath, 'utf8')`.
-     - Викликає `findRedisImportsInText(content, rel)` і ітерує його результат `v` (об’єкти з полями `line`, `module`, `snippet`).
-     - Для кожного `v` інкрементує `violations` і викликає `fail(...)` з форматованим повідомленням:
-       `js-bun-redis: <rel>:<line> — заміни '<module>' на Bun native Redis (import { redis } from 'bun', https://bun.com/docs/runtime/redis): <snippet>`.
-  3. Повертає підсумкову `violations`.
-- Side effects:
-  - Читання файлів з диска (`readFile`) — потенційно великий I/O залежно від розміру репозиторію.
-  - Виклик `fail` має побічний ефект: змінює внутрішній стан репортера так, що його `getExitCode()` поверне ненульовий код.
-
-### `check()` (експортована)
-
-Головна точка входу check-скрипта правила `js-bun-redis`.
-
-- Сигнатура: `export async function check(): Promise<number>`
-- Параметри: відсутні. Робочий каталог визначається через `process.cwd()`.
-- Повертає: `Promise<number>` — фінальний код виходу: `0` — все гаразд, `1` (або інший ненульовий за реалізацією репортера) — є порушення або інші зафіксовані помилки.
-- Поведінка / логіка:
-  1. Створює репортер `reporter = createCheckReporter()` і деструктурує з нього `pass`, `fail`.
-  2. Визначає `repoRoot = process.cwd()`.
-  3. Перевіряє наявність `package.json`: якщо `existsSync(join(repoRoot, 'package.json'))` повертає `false` — викликає `pass('js-bun-redis: package.json у корені відсутній — перевірку пропущено')` і повертає `reporter.getExitCode()` (рання гілка).
-  4. Завантажує `ignorePaths` через `await loadCursorIgnorePaths(repoRoot)`.
-  5. Збирає `sourcePaths = await findAllSourcePathsForRedisScan(repoRoot, ignorePaths)`.
-  6. Якщо `sourcePaths.length === 0` — викликає `pass('js-bun-redis: немає JS/TS файлів для скану імпортів ioredis / node-redis / redis')` і повертає `reporter.getExitCode()`.
-  7. Інакше викликає `violations = await scanSourcesForRedisImports(sourcePaths, repoRoot, fail)`.
-  8. Якщо `violations === 0` — викликає `pass('js-bun-redis: немає імпортів \'ioredis\' / \'node-redis\' / \'redis\' / \'@redis/*\' у джерелах (використовується Bun native Redis або redis взагалі не задіяно)')`.
-  9. Повертає `reporter.getExitCode()`.
-- Side effects:
-  - Читання файлової системи (`existsSync`, `walkDir`, `readFile`).
-  - Виведення повідомлень через репортер (через `pass`/`fail` — у консоль або інше призначене місце, що визначається реалізацією `createCheckReporter`).
-  - Залежить від поточного робочого каталогу процесу (`process.cwd()`).
-
-## Залежності
-
-### Зовнішні (node:\* / runtime)
-
-- `node:fs`
-  - `existsSync` — синхронна перевірка наявності `package.json` у корені.
-- `node:fs/promises`
-  - `readFile` — асинхронне читання вмісту кожного JS/TS-файлу у кодуванні `utf8`.
-- `node:path`
-  - `join` — побудова шляху до `package.json`.
-  - `relative` — обчислення відносних шляхів для логування та сортування.
-
-### Внутрішні (проєктні)
-
-- `../../../scripts/lib/check-reporter.mjs`
-  - `createCheckReporter` — фабрика стандартного репортера для check-скриптів правил. Дає API `{ pass, fail, getExitCode }`.
-- `../../../scripts/lib/load-cursor-config.mjs`
-  - `loadCursorIgnorePaths` — завантажує абсолютні шляхи, які слід виключити з обходу (з cursor-конфігу/ignore-файлів).
-- `../lib/redis-imports.mjs`
-  - `findRedisImportsInText(text, relPath)` — шукає у тексті заборонені redis-імпорти/`require`/динамічні `import()`; повертає масив порушень з полями `line`, `module`, `snippet`.
-  - `isRedisScanSourceFile(relPath)` — предикат: чи цей відносний шлях належить до набору JS/TS-джерел, придатних для скану.
-  - `shouldSkipFileForRedisScan(relPath)` — предикат: чи слід пропустити конкретний файл (наприклад, тестові фікстури, генеровані файли тощо).
-- `../../../scripts/utils/walkDir.mjs`
-  - `walkDir(rootAbs, visit, ignorePaths)` — асинхронний обхід директорії з викликом `visit(absPath)` для кожного файлу та пропуском заданих `ignorePaths`.
-
-## Потік виконання / Використання
-
-Файл є частиною інфраструктури check-скриптів правил Cursor для проєкту. Очікувано він викликається оркестратором, який імпортує `check` із цього модуля і запускає її з робочою директорією, що дорівнює кореню репозиторію.
-
-Узагальнений потік виконання `check()`:
-
-1. Інстанціювання репортера `createCheckReporter()`.
-2. Гілка раннього виходу: відсутній кореневий `package.json` → `pass(...)` → `return reporter.getExitCode()`.
-3. Завантаження `ignorePaths` через `loadCursorIgnorePaths(repoRoot)`.
-4. Збір кандидатів через `findAllSourcePathsForRedisScan(repoRoot, ignorePaths)`:
-   - Обхід `walkDir` з відсіюванням за `isRedisScanSourceFile` і `shouldSkipFileForRedisScan`.
-   - Детермінований порядок через `localeCompare` за відносним шляхом.
-5. Гілка раннього виходу: порожній список кандидатів → `pass(...)` → `return reporter.getExitCode()`.
-6. Скан кожного джерела через `scanSourcesForRedisImports`:
-   - Читання `readFile(..., 'utf8')`.
-   - Виклик `findRedisImportsInText(content, rel)`.
-   - На кожне порушення — `fail('js-bun-redis: <rel>:<line> — заміни \'<module>\' на Bun native Redis (...): <snippet>')` та `violations++`.
-7. Якщо `violations === 0` — повідомлення про успіх через `pass(...)`.
-8. Фінальне повернення `reporter.getExitCode()`:
-   - `0` — лише `pass`/нуль порушень.
-   - Ненульове значення — щонайменше один `fail`.
-
-Приклад типового підключення з оркестратора правил (схематично):
-
-```js
-import { check } from './imports.mjs'
-
-const code = await check()
-process.exit(code)
-```
+Файл виконує збір та перевірку джерел коду. Він завантажує конфігурації пропущених шляхів з `package.json`, збирає абсолютні шляхи джерел та перевіряє їх на наявність заборонених імпортів пакетів. Перевірка проводиться відповідно до правила, визначеного у https://bun.com/docs/runtime/redis.
 
-Команда `npx @nitra/cursor check` запускає цей скрипт у пайплайні разом із Rego-полісом `npm/policy/js_bun_redis/package_json/`, який перевіряє відсутність заборонених redis-пакетів у `dependencies`/`devDependencies`/`peerDependencies` будь-якого `package.json` у репозиторії. Цей файл доповнює полісі рівнем скану реальних імпортів у коді, бо самих лише обмежень у `package.json` недостатньо: пакет може бути транзитивно встановлений або підвантажений з підшляху.
+## Поведінка
 
-Особливості та граничні випадки:
+1. Завантажити конфігурації пропущених шляхів з `package.json`
+2. Зібрати абсолютні шляхи JS/TS джерел у репозиторії
+3. Просканувати джерела на заборонені імпорти пакетів `ioredis` / `node-redis` / `redis`
+4. Перевірити відповідність проєкту правилу `js-bun-redis.mdc`
 
-- Шляхи нормалізуються до прямих слешів (`/`) перед тим як прогнатись через предикати, щоб логіка `isRedisScanSourceFile` / `shouldSkipFileForRedisScan` працювала однаково на Linux/macOS і Windows.
-- Сортування результатів `findAllSourcePathsForRedisScan` забезпечує стабільний детермінований порядок виводу повідомлень про порушення, що корисно для CI-діффів.
-- Якщо у файлі знайдено кілька порушень — кожне репортується окремим повідомленням, але сумарний `violations` повертається з усієї пробіжки.
-- `check()` свідомо не кидає винятків самостійно: усі помилки оформлюються як `fail(...)` для коректного коду виходу через `reporter.getExitCode()`. Винятки від `readFile`/`walkDir` будуть проксі через `await` і призведуть до rejected promise (це залишається на відповідальності оркестратора).
+## Публічний API
 
-## Rebuild Test
+check — перевіряє відповідність проєкту правилу `js-bun-redis.mdc`.
 
-Якщо за цією документацією треба відновити модуль, він повинен:
+## Гарантії поведінки
 
-1. Імпортувати з `node:fs` — `existsSync`; з `node:fs/promises` — `readFile`; з `node:path` — `join`, `relative`.
-2. Імпортувати з `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter`.
-3. Імпортувати з `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths`.
-4. Імпортувати з `../lib/redis-imports.mjs` — `findRedisImportsInText`, `isRedisScanSourceFile`, `shouldSkipFileForRedisScan`.
-5. Імпортувати з `../../../scripts/utils/walkDir.mjs` — `walkDir`.
-6. Оголосити приватну `findAllSourcePathsForRedisScan(repoRoot, ignorePaths)`, що:
-   - обходить `walkDir(repoRoot, cb, ignorePaths)`;
-   - усередині callback нормалізує `relative(repoRoot, absPath)` до прямих слешів, фільтрує через `isRedisScanSourceFile && !shouldSkipFileForRedisScan` і пушить у локальний масив;
-   - сортує масив за `relative(repoRoot, x).localeCompare(...)`;
-   - повертає його.
-7. Оголосити приватну `scanSourcesForRedisImports(sourcePaths, repoRoot, fail)`, що:
-   - ітерує `sourcePaths`, для кожного читає `readFile(..., 'utf8')`, нормалізує `rel`, прогоняє `findRedisImportsInText` і на кожне порушення інкрементує лічильник + викликає `fail(...)` з повідомленням формату `js-bun-redis: <rel>:<line> — заміни '<module>' на Bun native Redis (import { redis } from 'bun', https://bun.com/docs/runtime/redis): <snippet>`;
-   - повертає кількість порушень.
-8. Експортувати `async function check()`, що:
-   - створює `reporter = createCheckReporter()`, бере `pass`/`fail` з нього;
-   - якщо `package.json` у `process.cwd()` відсутній — `pass('... перевірку пропущено')` і повертає `reporter.getExitCode()`;
-   - завантажує `ignorePaths` через `loadCursorIgnorePaths(repoRoot)`;
-   - збирає `sourcePaths`, якщо порожньо — `pass('... немає JS/TS файлів для скану ...')` і вихід;
-   - інакше викликає `scanSourcesForRedisImports`, на нуль порушень — `pass('... немає імпортів ioredis / node-redis / redis / @redis/* ...')`;
-   - повертає `reporter.getExitCode()`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -1,117 +1,39 @@
-# fix.mjs — точка входу правила `js-lint`
+---
+docgen:
+  source: npm/rules/js-lint/fix.mjs
+  crc: 38cf876b
+  score: 90
+---
 
-## Огляд
-
-Файл `npm/rules/js-lint/fix.mjs` — це тонкий ентрі-поінт (entry-point) правила з ідентифікатором `js-lint` для CLI `@nitra/cursor`. Він не містить власної логіки перевірок: уся механіка прогону правила інкапсульована у бібліотечних модулях `run-standard-rule.mjs` (стандартний пайплайн правил) та `run-rule-cli.mjs` (CLI-обгортка).
-
-Модуль виконує **подвійну роль**:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку імпортують інші частини оркестратора правил. У цьому режимі правило виконується в межах єдиного процесу, отримує контекст (`ctx`) із кешем обходу файлової системи (`walkCache`) та інших спільних структур, і повертає exit-код як значення Promise.
-2. **Standalone mode** — якщо файл запущено напряму як CLI (`bun rules/js-lint/fix.mjs`), виконується повноцінний CLI-цикл: завантаження конфігурації, застосування whitelist-фільтрів, виведення підсумків і завершення процесу з відповідним exit-кодом (повний еквівалент команди `npx @nitra/cursor fix js-lint`).
-
-Стандартний пайплайн, який стоїть за `runStandardRule`, складається з чотирьох послідовних фаз: `applies` (визначення цільових файлів) → `JS-concerns` (специфічні для правила перевірки/фікси) → `policy` (агрегування політик) → `mdc-refs` (узгодження з `.mdc`-метаописами правил).
-
-## Експорти / API
-
-| Символ | Тип                               | Призначення                                                                                                                                                                         |
-| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run`  | `function(ctx?): Promise<number>` | Library-API: запускає правило `js-lint` в межах поточного процесу, повертає exit-код (0 — OK, 1 — порушення). Експортується як іменований експорт через `export function run(ctx)`. |
-
-Default-експорт відсутній. Інших іменованих експортів немає.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` (необовʼязковий) — обʼєкт контексту прогону правила типу `RuleContext` (визначений у `../../scripts/lib/run-standard-rule.mjs`). Зазвичай містить кешовані структури на кшталт `walkCache` (кеш обходу файлової системи), що дозволяє оркестратору перевикористовувати дані між послідовними правилами без повторного обходу диску. Якщо аргумент відсутній — кеші ініціалізуються всередині `runStandardRule`.
-- **Повертає:** `Promise<number>` — exit-код прогону правила:
-  - `0` — правило не знайшло порушень або всі знайдені порушення були автоматично виправлені;
-  - `1` — присутні порушення, які залишилися після фази fix (тобто потрібне ручне втручання або правило в режимі lint-only).
-- **Реалізація:** повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`. Перший аргумент `import.meta.dirname` — абсолютний шлях до директорії, у якій лежить `fix.mjs` (тобто `.../npm/rules/js-lint`). Саме за цим шляхом `runStandardRule` знаходить решту артефактів правила (наприклад, `applies.mjs`, `policy.mjs`, `mdc`-довідники, та власне fix-логіку).
-- **Side effects:** делегуються до `runStandardRule`. Стандартно включають читання вихідних файлів проєкту, можливе перезаписування файлів коду під час фази fix, читання конфігурації правил, а також виведення прогресу/підсумків у stdout/stderr (залежить від конкретної реалізації стандартного пайплайна).
+# fix.mjs
 
-### Standalone-блок (top-level)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Сигнатура:** не є функцією — це top-level умовний блок, який виконується один раз при завантаженні модуля.
-- **Логіка:**
-  1. `isRunAsCli(import.meta.url)` визначає, чи файл запущено як головний модуль (через `bun fix.mjs` / `node fix.mjs`) або імпортовано як бібліотеку. Стандартна ідіома: порівнює `import.meta.url` із URL процесу запуску.
-  2. Якщо запуск standalone — виконується `await runRuleCli(import.meta.dirname)`, який повертає exit-код. Цей виклик інкапсулює CLI-обвʼязки: парсинг аргументів, завантаження користувацької/проєктної конфігурації, застосування whitelist (фільтра шляхів), виклик `run(ctx)` під капотом і друк фінального підсумку.
-  3. `process.exit(...)` гарантовано завершує процес із отриманим exit-кодом — це необхідно для коректної інтеграції з CI-системами та IDE, які орієнтуються на код виходу.
-- **Side effects:** завершення процесу Node/Bun. У standalone-режимі правило ніколи не повертає керування викликачу — замість return-у виконується `process.exit`.
-- **Зауваження по лінтерам:** перед викликом `process.exit` стоїть директива `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE` — це свідомий виняток із загальної заборони на `process.exit` для standalone entry-point-ів.
-
-## Залежності
-
-### Внутрішні (модулі репозиторію)
-
-- `../../scripts/lib/run-rule-cli.mjs` — імпортуються:
-  - `isRunAsCli` — детектор режиму запуску (CLI vs library).
-  - `runRuleCli` — повноцінна CLI-обгортка для правила: парсинг аргументів, конфіг, whitelist, виклик `run`, друк summary; повертає `Promise<number>` (exit-код).
-- `../../scripts/lib/run-standard-rule.mjs` — імпортується:
-  - `runStandardRule` — стандартний пайплайн правил у чотири фази (`applies` → `JS-concerns` → `policy` → `mdc-refs`), приймає шлях до директорії правила та опційний контекст; повертає `Promise<number>`.
-  - Також звідси типізовано `RuleContext` (через JSDoc-тип `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`).
-
-### Зовнішні / runtime
-
-- `import.meta.dirname` — Node/Bun runtime API (стабільний з Node 20.11). Повертає абсолютний шлях до директорії модуля. Використовується як «адреса» правила для оркестратора.
-- `import.meta.url` — URL поточного модуля; передається у `isRunAsCli` для розрізнення CLI-запуску й import-режиму.
-- `process.exit` — Node/Bun global, термінує процес із заданим exit-кодом.
-- Top-level `await` — використовується для `await runRuleCli(...)`; вимагає ES-modules (`.mjs`) і середовища з підтримкою top-level await.
-
-Жодних npm-пакетів модуль напряму не імпортує.
-
-## Потік виконання / Використання
-
-### Сценарій 1: запуск як CLI (standalone)
-
-```bash
-bun npm/rules/js-lint/fix.mjs
-# або еквівалент через головний CLI:
-npx @nitra/cursor fix js-lint
-```
+## Огляд
 
-1. ES-модуль завантажується, виконуються імпорти `isRunAsCli`, `runRuleCli`, `runStandardRule`.
-2. Оголошується експорт `run` (але одразу не викликається).
-3. Виконується top-level `if (isRunAsCli(import.meta.url))`. У standalone це `true`.
-4. Викликається `await runRuleCli(import.meta.dirname)`:
-   - читається конфігурація проєкту (whitelist, exclude, опції правил);
-   - визначається область дії (які файли потрапляють у правило `js-lint`);
-   - усередині викликається `run(ctx)` із підготовленим контекстом;
-   - друкується підсумок (порушення, виправлення, час).
-5. `process.exit(<код>)` завершує процес. CI-система отримує `0` (успіх) або `1` (є порушення).
+Файл застосовує визначене правило до вхідного контексту. Виконання відбувається через оркестрацію CLI, яка використовує імпорт та функцію `run`. Для роботи у режимі standalone використовується `runRuleCli` для визначення коду виходу та виконує еквівалент команди `npx @nitra/cursor fix <id>`.
 
-### Сценарій 2: виклик як бібліотеки (library mode)
+## Поведінка
 
-```js
-import { run } from './npm/rules/js-lint/fix.mjs'
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Повертає результат прогону.
+2. Виконання правила.
+    *   Викликає стандартне правило.
+    *   Використовує директорію модуля для прогону.
+3. Режим бібліотеки.
+    *   Викликається через оркестрацію CLI.
+    *   Використовує імпорт та функцію `run`.
+4. Режим standalone.
+    *   Викликається через CLI.
+    *   Використовує `runRuleCli` для визначення коду виходу.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
 
-const ctx = { walkCache: /* спільний кеш */, /* ... */ }
-const exitCode = await run(ctx)
-if (exitCode !== 0) {
-  // обробка порушень: повторний прогін, escalation у CI тощо
-}
-```
+## Публічний API
 
-1. Сторонній модуль (зазвичай головний оркестратор `@nitra/cursor`) імпортує `run`.
-2. `isRunAsCli(import.meta.url)` для `fix.mjs` поверне `false` (бо `import.meta.url` модуля не збігається з URL процесу) — standalone-блок не виконується, `process.exit` не викликається.
-3. Викликач передає у `run(ctx)` готовий контекст із попередньо побудованими кешами.
-4. `run` делегує у `runStandardRule(import.meta.dirname, ctx)`, який виконує чотирифазний пайплайн правила і повертає exit-код.
-5. Викликач сам вирішує, що робити з кодом (агрегувати з іншими правилами, ескалувати, друкувати тощо). Завершення процесу — на боці викликача.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-### Інтеграція в загальну архітектуру правил
+## Гарантії поведінки
 
-- Кожне правило в каталозі `npm/rules/<id>/` має власний `fix.mjs` за **однаковим шаблоном**: експортує `run(ctx)`, що делегує у `runStandardRule(import.meta.dirname, ctx)`, плюс standalone-блок із `runRuleCli`. Конкретні перевірки/фікси правила лежать у сусідніх файлах директорії (`applies.mjs`, `policy.mjs`, `check-*.mjs` тощо) і автоматично підхоплюються стандартним пайплайном за конвенцією шляхів.
-- Для правила `js-lint` стандартний пайплайн виконує: відбір JS/TS/Vue-файлів (фаза `applies`) → специфічні JS-перевірки (фаза `JS-concerns`, реалізована в інших файлах цієї ж директорії) → агрегування політик (`policy`) → крос-перевірку з `.mdc`-описом правила (`mdc-refs`).
-- Контракт «`fix.mjs` = тонка обгортка» уніфікує всі правила: уся складність захована за `runStandardRule` і `runRuleCli`. Завдяки цьому файл `fix.mjs` будь-якого правила залишається маленьким (одиниці рядків коду) і легко піддається ревʼю/документації.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,30 +1,50 @@
+---
+docgen:
+  source: npm/rules/js-lint/js/lint-findings.mjs
+  crc: bee587da
+  score: 100
+---
+
 # lint-findings.mjs
 
 ## Огляд
 
-Цей файл обробляє результати аналізу коду, отримані з інструментів oXlint та eslint, для визначення, чи є знайдені проблеми нові (в diff) чи існують у файлі з самого початку. Він класифікує ці результати, надаючи інформацію про файл та рядок, де проблема виявлена, що допомагає у відстеженні та вирішенні помилок. Це частина системи беклогу #6, яка автоматизує процес класифікації lint-findings.
+parseOxlint
+Парсить текст у вивід oxlint
+
+parseEslint
+Парсить текст у вивід eslint
+
+classifyFindings
+Розділяє findings на introduced та preExisting
+
+renderFindings
+Форматує та рендерить звіт про findings
 
 ## Поведінка
 
-parseOxlint: аналізує JSON-вихід `oxlint --format=json` та повертає список findings з інформацією про файл, рядок, правило та повідомлення.
-parseEslint: аналізує JSON-вихід `eslint --format=json` та повертає список findings з інформацією про файл, рядок, правило та повідомлення.
-classifyFindings: класифікує findings як introduced або pre-existing на основі доданих рядків, використовуючи Map.
-renderFindings: генерує текстовий звіт з розділенням findings на introduced та pre-existing, використовуючи формат `🆕 introduced` та `🗄 pre-existing`.
+parseOxlint
+Парсить текст у вивід oxlint
+
+parseEslint
+Парсить текст у вивід eslint
+
+classifyFindings
+Розділяє findings на introduced та preExisting
+
+renderFindings
+Форматує та рендерить звіт про findings
 
 ## Публічний API
 
-- parseOxlint — Перетворює JSON з результатів інструменту Oxlint на внутрішній об'єкт.
-- parseEslint — Перетворює JSON з результатів інструменту ESLint на внутрішній об'єкт.
-- classifyFindings — Розподіляє знайдені проблеми на нові (introduced) та існуючі (pre-existing).
-- renderFindings — Створює звіт, об'єднуючи нові та існуючі проблеми.
+parseOxlint — перетворює JSON у дані або повертає null при невдалій обробці.
+parseEslint — перетворює JSON у дані або повертає null при невдалій обробці.
+classifyFindings — групує знайдені проблеми на категорії доданих/існуючих.
+renderFindings — формує звіт, який включає виправлені проблеми та застарілі проблеми.
 
 ## Гарантії поведінки
 
-- Функція `parseOxlint` повертає JSON-об'єкт, що містить список діагностик, або `null` у разі помилки парсингу.
-- Функція `parseEslint` повертає масив об'єктів, що містять повідомлення про помилки, або `null` у разі помилки парсингу.
-- Функція `classifyFindings` повертає масив об'єктів, що представляють класифіковані результати, або `null` у разі помилки класифікації.
-- Функція `renderFindings` повертає рядок, що містить представлення результатів, або `null` у разі помилки рендерингу.
-- У разі невдачі будь-якої з функцій, повертається `false`.
-- Функції не кидають винятків.
-- Шляхи файлів, що передаються вхідним функціям, є абсолютними.
-- Результати функцій не кешуються.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.