@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,207 @@
+# utils_imports.mjs — перевірка кордону `utils/`-каталогів
+
+## Огляд
+
+Модуль `npm/rules/js-lint/js/utils_imports.mjs` реалізує одну з перевірок правила `js-lint.mdc`: жоден файл усередині будь-якого каталогу з ім'ям `utils/` не має імпортувати щось за межами цього самого каталогу через відносні шляхи з префіксом `..`.
+
+Філософія перевірки:
+
+- Каталог `utils/` за конвенцією тримає **generic helpers** — функції без бізнес-логіки, без знання про домен, без залежностей від конфігів конкретного проєкту.
+- Якщо файлу треба сусідній модуль (наприклад, `lib/foo.mjs` чи cross-rule helper) — він мусить переїхати у `lib/`, а не отримувати доступ через `../lib/foo.mjs`.
+- Дозволені імпорт-джерела: `./X`, `./sub/X` (свій каталог чи глибше), bare-package (`oxc-parser`, `@scope/pkg`), Node-builtin (`node:fs`, `fs`).
+- Заборонено будь-який `..`-шлях (`../X`, `../../X`, ...).
+
+Перевірка проходить по всьому monorepo: знаходить package-roots, у кожному рекурсивно шукає каталоги `utils/`, з кожного збирає не-тестові джерела (без `tests/` і `__fixtures__/`), парсить їх через `oxc-parser`, витягає всі імпорти (статичні, динамічні, `require(...)`) і логує fail-репорт для кожного імпорту з `..`-префіксом.
+
+Файл є точкою входу check-runner-а (CI-чи-локальний прогон): експортує одну async-функцію `check()`, яка повертає exit-code.
+
+## Експорти / API
+
+| Експорт | Тип                     | Призначення                                                                                           |
+| ------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `check` | `() => Promise<number>` | named export; запускає перевірку від `process.cwd()` і повертає `0` (OK) або `1` (знайдено порушення) |
+
+Усе інше — приватні helpers модуля без `export`.
+
+## Функції
+
+### `isIgnored(dir, ignorePaths)`
+
+Перевіряє, чи каталог входить у список ignore (точний збіг або префіксне співпадіння).
+
+- **Сигнатура:** `function isIgnored(dir: string, ignorePaths: string[]): boolean`
+- **Параметри:**
+  - `dir` — абсолютний posix-шлях каталогу.
+  - `ignorePaths` — масив абсолютних posix-шляхів, отриманих з `.n-cursor.json` через `loadCursorIgnorePaths`.
+- **Повертає:** `true`, якщо `dir` дорівнює якомусь елементу `ignorePaths` або починається з нього + `/`; інакше `false`.
+- **Side effects:** немає.
+
+### `findUtilsDirs(root, ignorePosix)`
+
+Рекурсивно шукає всі каталоги з ім'ям `utils` під `root`.
+
+- **Сигнатура:** `async function findUtilsDirs(root: string, ignorePosix: string[]): Promise<string[]>`
+- **Параметри:**
+  - `root` — абсолютний шлях кореня обходу (зазвичай корінь package).
+  - `ignorePosix` — список абсолютних posix-шляхів, які пропускати.
+- **Повертає:** масив абсолютних шляхів знайдених `utils/`-каталогів. Порядок — результат DFS у тому ж порядку, в якому повертає `readdir`.
+- **Алгоритм:**
+  - Вкладена рекурсивна функція `walk(dir)` читає `readdir(dir, { withFileTypes: true })`.
+  - Помилка `readdir` (наприклад, нема прав чи каталог зник) проглинається через `try/catch` і дає ранній `return`.
+  - Для кожного запису-каталогу:
+    - якщо ім'я входить у `SKIP_DIR_NAMES` (`node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`, `__fixtures__`) — скіп;
+    - повний шлях конвертується у posix і перевіряється через `isIgnored` — скіп якщо так;
+    - якщо ім'я — рівно `utils`, додається у `found` і **не** заходить глибше (вкладені `utils/utils/` не очікуються; навіть якщо є — внутрішній `utils/` усе одно під самим `utils/` і його файли все одно пройдуть як файли зовнішнього `utils/`);
+    - інакше — рекурсивно `walk(full)`.
+- **Side effects:** filesystem-чтення.
+
+### `collectUtilsSources(utilsDir)`
+
+Збирає всі не-тестові source-файли під `utilsDir`.
+
+- **Сигнатура:** `async function collectUtilsSources(utilsDir: string): Promise<string[]>`
+- **Параметри:** `utilsDir` — абсолютний шлях каталогу `utils/`.
+- **Повертає:** масив абсолютних шляхів файлів-джерел.
+- **Фільтри:**
+  - Каталоги `tests/`, `__fixtures__/` і будь-що з `SKIP_DIR_NAMES` — пропускаються (тести легально мають імпорти `../X` до свого модуля).
+  - Файли мають матчити `JS_SOURCE_RE` (`.mjs`, `.mts`, `.cjs`, `.cts`, `.js`, `.ts`, `.jsx`, `.tsx`).
+  - Файли, що матчать `TEST_FILE_RE` (`*.test.*`), — виключаються.
+- **Алгоритм:** аналогічний DFS через вкладену `walk(dir)` з тим самим проглинанням помилок `readdir`.
+- **Side effects:** filesystem-чтення.
+
+### `extractImportSources(source, filePath)`
+
+Витягає всі рядкові імпорт-source з тексту файлу.
+
+- **Сигнатура:** `function extractImportSources(source: string, filePath: string): string[]`
+- **Параметри:**
+  - `source` — текст файлу (UTF-8).
+  - `filePath` — шлях до файлу, потрібен для визначення мови парсингу через `langFromPath`.
+- **Повертає:** масив рядків — значення source кожного імпорту в тому вигляді, в якому вони записані в коді (`'./foo'`, `'../bar'`, `'oxc-parser'`, ...).
+- **Що збирає:**
+  - **Статичні імпорти** — з `parsed.module.staticImports[*].moduleRequest.value` (oxc-parser API).
+  - **Динамічні імпорти** (`import('...')`) — через `dynamicImportModule(node)` під час обходу AST.
+  - **CommonJS `require('...')`** — через `requireCallModule(node)`.
+- **Обробка помилок парсингу:** `try/catch` на `parseSync` повертає порожній масив і **не** падає, бо синтаксична помилка — окремий концерн іншої перевірки; ця має запуститись чисто і не блокувати решту.
+- **Side effects:** немає (виклик `parseSync` — CPU-only).
+
+### `check()` (named export)
+
+Точка входу. Виконує всю перевірку від поточного робочого каталогу.
+
+- **Сигнатура:** `export async function check(): Promise<number>`
+- **Параметри:** немає; використовує `process.cwd()` як корінь monorepo.
+- **Повертає:** `0` — порушень немає; `1` — є хоча б одне (реальний exit-code обчислює `reporter.getExitCode()`).
+- **Покроковий алгоритм:**
+  1. Створити `reporter` через `createCheckReporter()`.
+  2. `root = process.cwd()`.
+  3. Завантажити `ignorePaths` з `.n-cursor.json` (`loadCursorIgnorePaths`) і перевести у posix-варіант (`ignorePosix`).
+  4. Отримати relative-paths package-roots monorepo через `getMonorepoPackageRootDirs(root)`.
+  5. Для кожного package-root знайти всі `utils/`-каталоги (`findUtilsDirs`) і покласти у `Set` (`utilsDirSet`) для де-дуплікації.
+  6. Якщо `utils/`-каталогів немає взагалі — `reporter.pass(...)` з повідомленням про пропуск і повернути exit-code.
+  7. Інакше пройти кожен `utils/`-каталог:
+     - зібрати джерела (`collectUtilsSources`);
+     - для кожного файлу прочитати контент, витягти імпорти (`extractImportSources`);
+     - кожен import з префіксом `..` — `reporter.fail(...)` з relative-шляхом файлу та порушеним import-source, інкремент `violations`;
+     - `checkedFiles` рахує всі перевірені файли.
+  8. Якщо `violations === 0` — `reporter.pass(...)` зі статистикою (кількість utils-каталогів і файлів).
+  9. Повернути `reporter.getExitCode()`.
+- **Side effects:**
+  - filesystem-чтення (рекурсивне сканування + `readFile`);
+  - запис у `reporter` (виводить рядки у stdout/stderr, залежно від реалізації);
+  - читає `process.cwd()`.
+
+## Залежності
+
+### Node-builtin
+
+- `node:fs/promises` — `readdir`, `readFile`.
+- `node:path` — `join`, `relative`, `sep`.
+
+### npm-пакет
+
+- `oxc-parser` — `parseSync` для парсингу JS/TS у AST з достовірною підтримкою сучасних синтаксисів (zero-config).
+
+### Внутрішні модулі проєкту
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера; має методи `pass`, `fail`, `getExitCode`. Уніфікований API для всіх check-функцій.
+- `../../../scripts/lib/load-cursor-config.mjs` → `loadCursorIgnorePaths` — читає `.n-cursor.json` (чи аналог) і повертає масив абсолютних шляхів, які треба пропустити.
+- `../../../scripts/lib/workspaces.mjs` → `getMonorepoPackageRootDirs` — повертає relative-paths коренів пакетів у monorepo (включно з `.`-коренем, якщо це теж пакет).
+- `../../../scripts/utils/ast-scan-utils.mjs`:
+  - `langFromPath(filePath)` — мапить розширення файлу у `lang`-параметр для `oxc-parser`.
+  - `walkAstWithAncestors(program, ancestors, visitor)` — обхід AST з трекінгом предків.
+  - `dynamicImportModule(node)` — повертає рядок source для `import('...')`, або `null`.
+  - `requireCallModule(node)` — повертає рядок source для `require('...')`, або `null`.
+
+### Константи модуля
+
+| Ім'я                 | Значення                                                                               | Призначення                                                          |
+| -------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `JS_SOURCE_RE`       | `/\.(?:[cm]?[jt]sx?)$/u`                                                               | матчить `.mjs`, `.mts`, `.cjs`, `.cts`, `.js`, `.ts`, `.jsx`, `.tsx` |
+| `TEST_FILE_RE`       | `/\.test\.[cm]?[jt]sx?$/u`                                                             | матчить `*.test.{js,ts,...}` для виключення тестів                   |
+| `PARENT_RELATIVE_RE` | `/^\.\.(?:\/                                                                           | $)/u`                                                                | матчить `..` як цілий сегмент (`..` або `../*`); відсіює false-positive типу `..foo` |
+| `SKIP_DIR_NAMES`     | `Set(['node_modules', '.git', 'dist', 'coverage', '.turbo', '.next', '__fixtures__'])` | каталоги, які скіпаємо при обходах                                   |
+
+## Потік виконання / Використання
+
+### Інтеграція в перевірочний рантайм
+
+Модуль викликається check-runner-ом правила `js-lint.mdc` (зазвичай із `npm/rules/js-lint/js/`). Runner імпортує named export `check` і чекає на її resolved-значення як на process exit-code. Сам файл **не** має top-level executable коду — лише визначення; це дозволяє безпечно імпортувати його у тестах.
+
+Типовий виклик (псевдокод):
+
+```mjs
+import { check } from './utils_imports.mjs'
+const exitCode = await check()
+process.exit(exitCode)
+```
+
+### Сценарій "усе чисто"
+
+1. Runner запускається з кореня monorepo.
+2. `check()` знаходить `utils/` каталоги в усіх package-roots.
+3. Для кожного non-test source файлу витягає імпорти.
+4. Жоден імпорт не починається з `..`.
+5. `reporter.pass('utils-каталогів: N, перевірено M файлів — domain-bound імпортів немає (js-lint.mdc)')`.
+6. `getExitCode() → 0`.
+
+### Сценарій "є порушення"
+
+1. Знайдено файл `packages/foo/utils/helper.mjs`.
+2. У ньому є `import bar from '../lib/bar.mjs'`.
+3. `PARENT_RELATIVE_RE` матчить `../lib/bar.mjs`.
+4. `reporter.fail('packages/foo/utils/helper.mjs: заборонений імпорт \'../lib/bar.mjs\' — utils/-файли мають бути generic (js-lint.mdc)')`.
+5. `violations` інкрементується.
+6. По завершенню `getExitCode() → 1`.
+
+### Сценарій "немає utils/"
+
+1. У жодному package немає каталогу `utils/`.
+2. `utilsDirSet.size === 0`.
+3. `reporter.pass('utils-каталогів немає — перевірку пропущено (js-lint.mdc)')`.
+4. `getExitCode() → 0`.
+
+### Сценарій "файл із синтаксичною помилкою"
+
+1. `parseSync` кидає виключення.
+2. `extractImportSources` ловить його у `try/catch` і повертає `[]`.
+3. Цей файл не дає порушень. Проблему синтаксису ловить інша перевірка.
+
+### Сценарій "ignore-шлях"
+
+1. У `.n-cursor.json` зазначено абсолютний шлях, що покриває певний `utils/`-каталог.
+2. `findUtilsDirs` через `isIgnored` пропускає його ще на стадії обходу — той `utils/` навіть не потрапляє у `utilsDirSet`.
+
+### Особливості/edge cases
+
+- **Тести**: каталог `tests/` усередині `utils/` ігнорується повністю; також ігноруються файли `*.test.{js,ts,...}` будь-де всередині `utils/`. Це свідомо: тести легально імпортують свій модуль через `../X`.
+- **`__fixtures__/`**: ігнорується і в `findUtilsDirs`, і в `collectUtilsSources` — фікстури можуть бути будь-якими.
+- **Bare-imports** (`oxc-parser`, `node:fs`): не відсіюються спеціально, бо просто не матчать `PARENT_RELATIVE_RE`.
+- **Same-dir імпорти** (`./X`): дозволені автоматично з тієї ж причини.
+- **POSIX-шляхи для ignore**: під Windows `sep` — `\\`, тому шляхи нормалізуються у `/`-формат перед порівнянням з ignore-конфігом.
+- **De-duplication** через `Set`: якщо monorepo-структура повертає однаковий `utils/`-шлях двічі (наприклад, `.`-root і назва вкладеного пакета перетинаються), він обробиться лише раз.
+- **Помилки `readdir`** глушаться — недоступний каталог просто пропускається без падіння всієї перевірки.
+
+### Залежність від конвенцій правила `js-lint.mdc`
+
+Файл є технічною реалізацією одного з пунктів правила `js-lint.mdc`. Усі повідомлення `reporter.pass/fail` посилаються на `(js-lint.mdc)`, щоб користувач знав, де читати про сам принцип розділу `utils/` ↔ `lib/`.

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

@@ -0,0 +1,154 @@
+# fix.mjs — точка входу правила `js-lint-ci`
+
+## Огляд
+
+Файл `npm/rules/js-lint-ci/fix.mjs` є **точкою входу** (entry-point) для правила з ідентифікатором `js-lint-ci` у системі `@nitra/cursor`. Він реалізує **подвійну роль**, типову для всіх стандартних правил каталогу `npm/rules/*`:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку викликає зовнішній CLI-оркестратор (`npx @nitra/cursor fix js-lint-ci` або агрегатор `npx @nitra/cursor fix` для усіх правил).
+2. **Standalone mode** — якщо файл запущено напряму через `bun rules/js-lint-ci/fix.mjs`, виконується повний еквівалент CLI-команди `npx @nitra/cursor fix js-lint-ci` (з завантаженням конфігу, whitelist, summary та exit-кодом для CI).
+
+Сам файл не містить жодної доменно-специфічної логіки правила — вся механіка делегована у спільну бібліотечну функцію `runStandardRule`, яка реалізує стандартний конвеєр стандартного правила:
+
+```
+applies → JS-concerns → policy → mdc-refs
+```
+
+Тобто: спершу перевіряється, чи правило застосовне до файлу (`applies`), потім виконуються специфічні для JS перевірки (`JS-concerns`), далі — політика (`policy`) та робота з посиланнями `.mdc` (`mdc-refs`).
+
+## Експорти / API
+
+| Експорт | Тип                                  | Призначення                                                                                                                      |
+| ------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function (ctx?) => Promise<number>` | Library-точка входу правила. Запускає стандартний конвеєр правила у каталозі правила, повертає exit-код (0 — OK, 1 — порушення). |
+
+Інших іменованих чи default-експортів файл не містить.
+
+### Сигнатура `run`
+
+```js
+export function run(ctx)
+```
+
+#### Параметри
+
+- `ctx` (необов’язковий) — об’єкт контексту прогону типу `RuleContext` (визначення в модулі `../../scripts/lib/run-standard-rule.mjs`). Через цей контекст передаються спільні для одного запуску артефакти, такі як кеш обходу файлової системи (`walkCache`) тощо. Якщо контекст відсутній, `runStandardRule` створює власний.
+
+#### Повертає
+
+- `Promise<number>` — асинхронно резолвиться у **exit-код**:
+  - `0` — порушень немає, правило пройшло успішно;
+  - `1` — виявлено порушення (правило завершилось зі статусом FAIL).
+
+#### Side effects
+
+Сам по собі `run` не має прямих побічних ефектів, але через делегування у `runStandardRule` ініціює:
+
+- читання конфігураційних файлів правила (зокрема `meta.json`, файлів `applies/*`, `policy/*`, `mdc-refs/*` тощо — згідно конвенції стандартного правила);
+- обхід файлів проєкту відповідно до `applies`-патернів;
+- виконання JS-перевірок (наприклад, запуск ESLint у відповідному режимі) та політики;
+- запис до stdout/stderr діагностики, summary та результатів;
+- може кешувати/читати з `walkCache` всередині `ctx`.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`.
+- **Параметри:**
+  - `ctx` — опційний контекст прогону (див. вище).
+- **Повертає:** `Promise<number>` — exit-код прогону правила (0/1).
+- **Реалізація:** єдиний виклик `runStandardRule(import.meta.dirname, ctx)`. Перший аргумент `import.meta.dirname` — абсолютний шлях до каталогу, у якому розташований цей файл (`.../npm/rules/js-lint-ci/`). Таким чином `runStandardRule` дізнається, **яке саме правило** виконувати: всі його артефакти (`meta.json`, `applies`, `policy`, `mdc-refs` тощо) лежать поряд з `fix.mjs`.
+- **Side effects:** делеговані у `runStandardRule` (див. секцію _Експорти / API_ вище).
+
+### Standalone-блок (top-level `if`)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- Це не функція, а **умовний top-level statement**, що виконується лише коли модуль завантажено як головний (а не як імпортований модуль).
+- **Умова:** `isRunAsCli(import.meta.url)` — повертає `true`, якщо поточний модуль є точкою входу процесу (тобто запущено `bun rules/js-lint-ci/fix.mjs`, а не `import` з іншого файлу).
+- **Дія:** виконує `await runRuleCli(import.meta.dirname)` — повний CLI-сценарій (config-loading, whitelist, summary), а потім завершує процес `process.exit(<exit-code>)` з тим самим кодом, що повернув `runRuleCli` (0 або 1) — це критично для CI/IDE, які орієнтуються на код виходу.
+- **Side effects:** завершення процесу (`process.exit`), вся I/O `runRuleCli`. Виклики `process.exit` тут спеціально дозволені директивою:
+  ```js
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  ```
+
+## Залежності
+
+### Внутрішні (модулі того ж пакета)
+
+- `../../scripts/lib/run-rule-cli.mjs` — імпортуються:
+  - `isRunAsCli(metaUrl)` — детектор того, що поточний ESM-модуль запущено як CLI-entry;
+  - `runRuleCli(dirname)` — full standalone CLI-runner правила, що дзеркалить поведінку `npx @nitra/cursor fix <id>` (config-loading + whitelist + summary).
+- `../../scripts/lib/run-standard-rule.mjs` — імпортується:
+  - `runStandardRule(dirname, ctx?)` — стандартний бібліотечний конвеєр правила (`applies → JS-concerns → policy → mdc-refs`).
+
+### Зовнішні (поза репозиторієм)
+
+- Стандартні Node/Bun-глобали: `process` (для `process.exit`), `import.meta.dirname`, `import.meta.url`.
+- Прямих залежностей від npm-пакетів у самому файлі немає (вони — транзитивні через `run-rule-cli.mjs` / `run-standard-rule.mjs`).
+
+### Типи (через JSDoc)
+
+- `import('../../scripts/lib/run-standard-rule.mjs').RuleContext` — імпорт типу для параметра `ctx`.
+
+## Потік виконання / Використання
+
+### Сценарій 1. Library mode (виклик з оркестратора)
+
+Виконується, коли інший модуль імпортує цей файл та викликає `run(ctx)`:
+
+```js
+import { run } from '@nitra/cursor/rules/js-lint-ci/fix.mjs'
+
+const exitCode = await run(ctx)
+if (exitCode !== 0) {
+  // правило виявило порушення
+}
+```
+
+Послідовність:
+
+1. Оркестратор передає (опційно) спільний `ctx` (наприклад, з `walkCache`).
+2. `run` викликає `runStandardRule(import.meta.dirname, ctx)`.
+3. `runStandardRule` зчитує конфіг правила з каталогу `npm/rules/js-lint-ci/` і послідовно проганяє ланцюжок:
+   - `applies` — визначає список файлів, до яких застосовне правило;
+   - `JS-concerns` — JS-специфічні перевірки;
+   - `policy` — політика правила;
+   - `mdc-refs` — звірення з посиланнями `.mdc`.
+4. Повертається `Promise<number>` з exit-кодом.
+
+У цьому сценарії `process.exit` **не** викликається — exit-код повертається у викликача, який сам вирішує, що з ним робити (наприклад, агрегує з кодами інших правил).
+
+### Сценарій 2. Standalone mode (прямий запуск)
+
+Виконується командою:
+
+```sh
+bun npm/rules/js-lint-ci/fix.mjs
+```
+
+Послідовність:
+
+1. ESM-модуль завантажується як головний, `import.meta.url` дорівнює URL процесу.
+2. Виконується top-level `if (isRunAsCli(import.meta.url))` — умова істинна.
+3. Запускається `await runRuleCli(import.meta.dirname)` — повний CLI-сценарій (config, whitelist, summary), еквівалентний `npx @nitra/cursor fix js-lint-ci`.
+4. `process.exit(<code>)` завершує процес з отриманим exit-кодом (0/1) — для коректної інтеграції з CI та IDE.
+
+> Експортована функція `run` у цьому сценарії **не** викликається напряму — `runRuleCli` сам інкапсулює всю CLI-логіку, включно з потрібними викликами `runStandardRule` всередині.
+
+### Чому існують обидві ролі
+
+- **Library `run`** потрібна, щоб агрегатор (`npx @nitra/cursor fix` без id або фоновий runner) міг прогнати багато правил у спільному контексті — з кешуванням обходу ФС, єдиним підсумком тощо, без породження окремого процесу на кожне правило.
+- **Standalone-блок** потрібен, щоб правило було самодостатнім: розробник може запустити його в IDE «як файл» і отримати повноцінний CLI-сценарій з коректним exit-кодом. Це особливо зручно для дебагу окремого правила без переходу через головний CLI пакета.
+
+Файл свідомо тримається **мінімальним**: він є лише адаптером (entry-point), уся доменна логіка — у бібліотечних функціях `runStandardRule` та `runRuleCli`. Це уніфікує всі правила з каталогу `npm/rules/*` — їхні `fix.mjs` мають однакову структуру і відрізняються лише шляхом каталогу, у якому лежать (через `import.meta.dirname`).

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

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