@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,176 @@
+# 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)
+```
+
+Команда `npx @nitra/cursor check` запускає цей скрипт у пайплайні разом із Rego-полісом `npm/policy/js_bun_redis/package_json/`, який перевіряє відсутність заборонених redis-пакетів у `dependencies`/`devDependencies`/`peerDependencies` будь-якого `package.json` у репозиторії. Цей файл доповнює полісі рівнем скану реальних імпортів у коді, бо самих лише обмежень у `package.json` недостатньо: пакет може бути транзитивно встановлений або підвантажений з підшляху.
+
+Особливості та граничні випадки:
+
+- Шляхи нормалізуються до прямих слешів (`/`) перед тим як прогнатись через предикати, щоб логіка `isRedisScanSourceFile` / `shouldSkipFileForRedisScan` працювала однаково на Linux/macOS і Windows.
+- Сортування результатів `findAllSourcePathsForRedisScan` забезпечує стабільний детермінований порядок виводу повідомлень про порушення, що корисно для CI-діффів.
+- Якщо у файлі знайдено кілька порушень — кожне репортується окремим повідомленням, але сумарний `violations` повертається з усієї пробіжки.
+- `check()` свідомо не кидає винятків самостійно: усі помилки оформлюються як `fail(...)` для коректного коду виходу через `reporter.getExitCode()`. Винятки від `readFile`/`walkDir` будуть проксі через `await` і призведуть до rejected promise (це залишається на відповідальності оркестратора).
+
+## Rebuild Test
+
+Якщо за цією документацією треба відновити модуль, він повинен:
+
+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()`.

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

@@ -0,0 +1,223 @@
+# redis-imports.mjs
+
+## Огляд
+
+Модуль `redis-imports.mjs` — це сканер вихідного коду, який знаходить **заборонені** імпорти Redis-клієнтів (`ioredis`, `node-redis`, кореневий пакет `redis` та супутні підпакети сімейства `@redis/*`) у JavaScript/TypeScript-файлах. Метою сканера є **виявлення місць, які треба замінити на Bun native Redis** — стандартизований API `import { redis } from 'bun'` (див. `https://bun.com/docs/runtime/redis`).
+
+Семантичне розпізнавання імпортів виконується через AST-парсер **`oxc-parser`** (а не regex по тілу файлу), тож сканер коректно відрізняє рядкові літерали, коментарі та реальні `import`/`require`. Підтримуються три форми входу модулів:
+
+1. **Статичні ES-імпорти** — через `result.module.staticImports`.
+2. **CommonJS `require('...')`** — через обхід AST і утиліту `requireCallModule`.
+3. **Динамічні `import('...')`** — через обхід AST і утиліту `dynamicImportModule`.
+
+Це дає змогу єдиним проходом покривати і ESM-код, і CommonJS, і змішані сценарії з динамічним підвантаженням у межах одного файлу.
+
+Сканер є **частиною правила** `js-bun-redis.mdc` у системі правил `n-cursor` (директорія `npm/rules/js-bun-redis/`) і використовується чек-скриптами правила для пошуку порушень у пакетах монорепо.
+
+Сканер **не вимагає**, щоб файл був синтаксично коректним: якщо `oxc-parser` повертає помилку або `result.errors` непорожній, функція повертає порожній масив порушень. Тобто спершу треба полагодити синтаксис, а вже потім перезапускати перевірку — інакше сканер просто «нічого не знайде».
+
+## Експорти / API
+
+Модуль експортує **три** іменовані функції:
+
+| Експорт                                         | Тип        | Призначення                                                                                 |
+| ----------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------- |
+| `findRedisImportsInText(content, virtualPath?)` | `function` | Повертає масив знайдених заборонених імпортів Redis у переданому коді.                      |
+| `isRedisScanSourceFile(relativePath)`           | `function` | Предикат: чи треба сканувати файл за розширенням (`.js/.mjs/.cjs/.jsx/.ts/.mts/.cts/.tsx`). |
+| `shouldSkipFileForRedisScan(relativePosix)`     | `function` | Предикат: чи слід пропустити файл (декларації типів `.d.ts`).                               |
+
+Default export відсутній.
+
+## Функції
+
+### `isForbiddenRedisModule(mod)` (внутрішня)
+
+**Сигнатура:** `function isForbiddenRedisModule(mod: string): boolean`
+
+**Параметри:**
+
+- `mod` — рядкове значення специфікатора модуля з конструкцій `import '...'`, `require('...')` або `import('...')`.
+
+**Повертає:** `true`, якщо `mod`:
+
+- входить у множину точних збігів `FORBIDDEN_MODULE_NAMES`: `'ioredis'`, `'node-redis'`, `'redis'`, `'@redis/client'`, `'@redis/json'`, `'@redis/search'`, `'@redis/time-series'`, `'@redis/bloom'`;
+- **або** починається з префіксу `'ioredis/'`, `'redis/'`, `'@redis/'` — для підшляхів (`ioredis/built/utils`, `redis/dist/...`, `@redis/<sub>`).
+
+Інакше повертає `false`. Префіксний підхід **навмисно** ловить підшляхи Redis-пакетів, але **не зачіпає** сторонні пакети-сусіди типу `redis-mock` (бо вони не починаються з `redis/`, а саме з `redis-`).
+
+**Side effects:** немає (чиста функція).
+
+**Видимість:** локальна для модуля; не експортується.
+
+### `findRedisImportsInText(content, virtualPath = 'scan.ts')`
+
+**Сигнатура:**
+
+```js
+export function findRedisImportsInText(
+  content: string,
+  virtualPath?: string
+): { line: number, snippet: string, module: string }[]
+```
+
+**Параметри:**
+
+- `content` — повний текст вихідного файлу як рядок.
+- `virtualPath` _(необовʼязковий, дефолт `'scan.ts'`)_ — шлях, який передається в парсер і використовується для визначення мови через `langFromPath(...)`. Може бути «віртуальним», тобто не існувати на ФС — потрібен лише для вибору режиму парсингу (наприклад, `.ts` vs `.tsx`). Якщо передати порожній рядок чи `undefined`, всередині буде підставлено `'scan.ts'`.
+
+**Повертає:** масив обʼєктів-порушень, де кожен елемент має поля:
+
+- `line: number` — 1-based номер рядка, де починається `import`/`require`/`import(...)` (через `offsetToLine(content, start)`);
+- `snippet: string` — нормалізований фрагмент коду цього вузла (через `normalizeSnippet(content.slice(start, end))`);
+- `module: string` — фактичний специфікатор модуля (`'ioredis'`, `'redis/dist/...'`, `'@redis/json'` тощо).
+
+Якщо файл синтаксично некоректний (`parseSync` кинув виключення) або `result.errors` непорожній — повертає `[]`.
+
+**Side effects:** немає (чиста функція; не звертається до ФС, не пише в stdout).
+
+**Алгоритм:**
+
+1. Обирає `lang` для парсера через `langFromPath(pathForLang)`.
+2. Викликає `parseSync(pathForLang, content, { lang, sourceType: 'module' })` у `try/catch`.
+3. Якщо парсинг кинув / повернув помилки — `return []`.
+4. Проходить **статичні імпорти** через `result.module?.staticImports ?? []`; для кожного, де `imp.moduleRequest?.value` — рядок і `isForbiddenRedisModule(...)` істинне, додає запис у вихідний масив.
+5. Проходить AST програми через `walkAstWithAncestors(result.program, [], node => {...})`:
+   - якщо `requireCallModule(node)` повертає рядок із забороненим модулем — додає запис і **повертається** (`return`), щоб не дублювати спробу як динамічний `import` для того самого вузла;
+   - інакше пробує `dynamicImportModule(node)` і так само додає запис при збігу.
+6. Повертає накопичений масив `out`.
+
+### `isRedisScanSourceFile(relativePath)`
+
+**Сигнатура:** `export function isRedisScanSourceFile(relativePath: string): boolean`
+
+**Параметри:**
+
+- `relativePath` — відносний шлях до файлу.
+
+**Повертає:** `true`, якщо шлях підпадає під регулярний вираз `SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u`, тобто має одне з розширень `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`. Інакше — `false`.
+
+**Side effects:** немає.
+
+### `shouldSkipFileForRedisScan(relativePosix)`
+
+**Сигнатура:** `export function shouldSkipFileForRedisScan(relativePosix: string): boolean`
+
+**Параметри:**
+
+- `relativePosix` — шлях з POSIX-роздільниками (`/`).
+
+**Повертає:** `true`, якщо файл закінчується на `.d.ts` — декларації типів TypeScript не виконуваний код, у них не може бути «реальних» імпортів-споживачів Redis, тому їх сканувати не варто. Для решти файлів — `false`.
+
+**Side effects:** немає.
+
+## Залежності
+
+### Зовнішні (npm)
+
+- **`oxc-parser`** — використовується через іменований імпорт `parseSync` для отримання AST програми та переліку статичних імпортів модуля.
+
+### Внутрішні (репозиторій)
+
+Імпорт із `'../../../scripts/utils/ast-scan-utils.mjs'` — спільні утиліти AST-сканера для всіх правил у `npm/rules/*/lib/`:
+
+- `dynamicImportModule(node)` — якщо вузол AST є динамічним `import('mod')`, повертає рядок `'mod'`, інакше `null`/`undefined`.
+- `langFromPath(path)` — обчислює `lang` для `oxc-parser` за розширенням шляху.
+- `normalizeSnippet(src)` — нормалізує сирий зріз коду (приведення пробілів/обрізання) для зручного звіту.
+- `offsetToLine(content, offset)` — конвертує абсолютний offset символа у 1-based номер рядка.
+- `requireCallModule(node)` — якщо вузол є викликом `require('mod')`, повертає рядок `'mod'`, інакше `null`/`undefined`.
+- `walkAstWithAncestors(program, ancestors, visitor)` — обхід AST програми з накопиченням предків.
+
+### Константи модуля
+
+- `SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u` — регекс розширень JS/TS-сімʼї.
+- `FORBIDDEN_MODULE_NAMES` — `Set<string>` із вісьмома точними іменами заборонених модулів.
+
+## Потік виконання / Використання
+
+### Типовий сценарій
+
+1. Обхідник пакета монорепо отримує список файлів через `readdir/walk`.
+2. Для кожного файлу:
+   - перевіряє `shouldSkipFileForRedisScan(relativePosix)` → якщо `true`, файл пропускається (наприклад, `*.d.ts`);
+   - перевіряє `isRedisScanSourceFile(relativePosix)` → якщо `false`, файл пропускається (нерелевантне розширення);
+   - інакше читає вміст файлу та викликає `findRedisImportsInText(content, virtualPath)`.
+3. Отриманий масив порушень агрегується у звіт правила `js-bun-redis`.
+
+### Приклад
+
+```js
+import { readFileSync } from 'node:fs'
+import { findRedisImportsInText, isRedisScanSourceFile, shouldSkipFileForRedisScan } from './redis-imports.mjs'
+
+const file = 'pkg/src/cache.ts'
+if (!shouldSkipFileForRedisScan(file) && isRedisScanSourceFile(file)) {
+  const content = readFileSync(file, 'utf8')
+  const violations = findRedisImportsInText(content, file)
+  for (const v of violations) {
+    console.log(`${file}:${v.line} forbidden import of ${v.module} -> ${v.snippet}`)
+  }
+}
+```
+
+### Що саме розпізнається як порушення
+
+Усі наступні форми у `cache.ts` будуть знайдені:
+
+```ts
+import Redis from 'ioredis' // ESM static, точна назва
+import { createClient } from 'redis' // ESM static, кореневий node-redis
+import json from '@redis/json' // ESM static, підпакет @redis/*
+import utils from 'ioredis/built/utils' // ESM static, підшлях ioredis/
+const Redis2 = require('ioredis') // CommonJS require
+const lib = await import('node-redis') // динамічний ESM import
+```
+
+А ось такі **не** будуть позначені (бо це сторонні пакети):
+
+```ts
+import { mock } from 'redis-mock' // not ioredis/redis/@redis
+import x from 'my-redis-helpers' // довільний сторонній пакет
+```
+
+### Поведінка на помилках
+
+- Якщо `parseSync` кинув виняток — порожній результат `[]`.
+- Якщо `result.errors?.length` істинний — порожній результат `[]`.
+- Користувач має спершу полагодити синтаксис файлу, тільки тоді повторно запускати перевірку.
+
+### Інтеграція з правилом
+
+Модуль є **бібліотечним** шаром (`lib/`) правила `js-bun-redis`. Чек-скрипт правила (типово `npm/rules/js-bun-redis/check-*.mjs`) імпортує ці три функції, обходить файли пакета і формує звіт. Заміна — на Bun native Redis (`import { redis } from 'bun'`).
+
+## Rebuild Test
+
+Контрольний перелік, за яким можна **відтворити** функціонал модуля «з нуля»:
+
+1. Створити файл `redis-imports.mjs`, що імпортує `parseSync` з `oxc-parser`.
+2. Імпортувати з `'../../../scripts/utils/ast-scan-utils.mjs'` шість утиліт: `dynamicImportModule`, `langFromPath`, `normalizeSnippet`, `offsetToLine`, `requireCallModule`, `walkAstWithAncestors`.
+3. Оголосити константу `SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u`.
+4. Оголосити константу `FORBIDDEN_MODULE_NAMES` як `Set` із елементами: `'ioredis'`, `'node-redis'`, `'redis'`, `'@redis/client'`, `'@redis/json'`, `'@redis/search'`, `'@redis/time-series'`, `'@redis/bloom'`.
+5. Реалізувати приватну функцію `isForbiddenRedisModule(mod)`: повертає `true`, якщо `FORBIDDEN_MODULE_NAMES.has(mod)` **або** `mod.startsWith('ioredis/')` **або** `mod.startsWith('redis/')` **або** `mod.startsWith('@redis/')`.
+6. Експортувати функцію `findRedisImportsInText(content, virtualPath = 'scan.ts')`:
+   1. `pathForLang = virtualPath || 'scan.ts'`;
+   2. `lang = langFromPath(pathForLang)`;
+   3. у `try { parseSync(pathForLang, content, { lang, sourceType: 'module' }) } catch { return [] }`;
+   4. якщо `result.errors?.length` — `return []`;
+   5. ініціалізувати `out = []`;
+   6. пройти `result.module?.staticImports ?? []` — для кожного, де `imp.moduleRequest?.value` рядок і `isForbiddenRedisModule(...)` істинне, пушити `{ line: offsetToLine(content, imp.start), snippet: normalizeSnippet(content.slice(imp.start, imp.end)), module: mod }`;
+   7. викликати `walkAstWithAncestors(result.program, [], node => {...})`:
+      - спершу спробувати `requireCallModule(node)`; на збігу пушити запис і `return`;
+      - потім `dynamicImportModule(node)`; на збігу пушити запис;
+   8. повернути `out`.
+7. Експортувати функцію `isRedisScanSourceFile(relativePath)`: `return SOURCE_FILE_RE.test(relativePath)`.
+8. Експортувати функцію `shouldSkipFileForRedisScan(relativePosix)`: `return relativePosix.endsWith('.d.ts')`.
+
+Контрольні очікування:
+
+- Виклик `findRedisImportsInText("import x from 'ioredis'", 'a.ts')` повертає масив із одного елемента, де `module === 'ioredis'`, `line === 1`.
+- Виклик `findRedisImportsInText("import x from 'redis-mock'", 'a.ts')` повертає `[]`.
+- Виклик `findRedisImportsInText("const r = require('@redis/json')", 'a.js')` повертає масив із одного елемента, де `module === '@redis/json'`.
+- Виклик `findRedisImportsInText("await import('redis/dist/x')", 'a.mjs')` повертає масив із одного елемента, де `module === 'redis/dist/x'`.
+- Виклик `findRedisImportsInText("import 'ioredis'; syntax error here {{", 'a.ts')` повертає `[]` (через помилку парсингу/`errors`).
+- `isRedisScanSourceFile('foo.ts')` → `true`; `isRedisScanSourceFile('foo.md')` → `false`.
+- `shouldSkipFileForRedisScan('types/foo.d.ts')` → `true`; `shouldSkipFileForRedisScan('src/foo.ts')` → `false`.

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

@@ -0,0 +1,117 @@
+# fix.mjs — точка входу правила `js-lint`
+
+## Огляд
+
+Файл `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 (залежить від конкретної реалізації стандартного пайплайна).
+
+### 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` (є порушення).
+
+### Сценарій 2: виклик як бібліотеки (library mode)
+
+```js
+import { run } from './npm/rules/js-lint/fix.mjs'
+
+const ctx = { walkCache: /* спільний кеш */, /* ... */ }
+const exitCode = await run(ctx)
+if (exitCode !== 0) {
+  // обробка порушень: повторний прогін, escalation у CI тощо
+}
+```
+
+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. Викликач сам вирішує, що робити з кодом (агрегувати з іншими правилами, ескалувати, друкувати тощо). Завершення процесу — на боці викликача.
+
+### Інтеграція в загальну архітектуру правил
+
+- Кожне правило в каталозі `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` будь-якого правила залишається маленьким (одиниці рядків коду) і легко піддається ревʼю/документації.