@nitra/cursor 3.21.1 → 3.23.0

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/js/lint-findings.mjs

@@ -0,0 +1,110 @@
+/**
+ * Нормалізація й класифікація lint-findings (oxlint + eslint) на introduced
+ * (рядок у diff від HEAD) vs pre-existing (борг файлу) — беклог #6, варіант A.
+ *
+ * Формати: oxlint `--format=json` → `{ diagnostics:[{ filename, code, labels:[{span:{line}}] }] }`;
+ * eslint `--format=json` → `[{ filePath, messages:[{ ruleId, line, message }] }]`. Шляхи абсолютні.
+ */
+import { isAbsolute, relative } from 'node:path'
+
+import { isIntroducedLine } from '../../../scripts/lib/diff-added-lines.mjs'
+
+/**
+ * @param {string} jsonText вивід `oxlint --format=json`
+ * @returns {{ file: string, line: number, rule: string, message: string, tool: string }[] | null} findings,
+ *   або `null` якщо json непарсабельний (краш/обрізаний вивід інструмента — НЕ «чисто»)
+ */
+export function parseOxlint(jsonText) {
+  let data
+  try {
+    data = JSON.parse(jsonText)
+  } catch {
+    return null
+  }
+  const diags = Array.isArray(data?.diagnostics) ? data.diagnostics : []
+  return diags
+    .filter(d => d?.filename)
+    .map(d => ({
+      file: d.filename,
+      line: d.labels?.[0]?.span?.line ?? 0,
+      rule: d.code ?? '',
+      message: d.message ?? '',
+      tool: 'oxlint'
+    }))
+}
+
+/**
+ * @param {string} jsonText вивід `eslint --format=json`
+ * @returns {{ file: string, line: number, rule: string, message: string, tool: string }[] | null} findings,
+ *   або `null` якщо json непарсабельний (краш/обрізаний вивід інструмента — НЕ «чисто»)
+ */
+export function parseEslint(jsonText) {
+  let data
+  try {
+    data = JSON.parse(jsonText)
+  } catch {
+    return null
+  }
+  const results = Array.isArray(data) ? data : []
+  const out = []
+  for (const r of results) {
+    for (const m of r?.messages ?? []) {
+      out.push({
+        file: r.filePath,
+        line: m.line ?? 0,
+        rule: m.ruleId ?? '(syntax)',
+        message: m.message ?? '',
+        tool: 'eslint'
+      })
+    }
+  }
+  return out.filter(f => f.file)
+}
+
+/**
+ * Розділяє findings на introduced / pre-existing за доданими рядками.
+ * @param {{ file: string, line: number }[]} findings нормалізовані findings
+ * @param {Map<string, Set<number> | string>} addedLines з `addedLinesByFile`
+ * @param {string} [cwd] корінь (для нормалізації абсолютних шляхів у relative)
+ * @returns {{ introduced: object[], preExisting: object[] }} класифікація
+ */
+export function classifyFindings(findings, addedLines, cwd = process.cwd()) {
+  const introduced = []
+  const preExisting = []
+  for (const f of findings) {
+    const rel = isAbsolute(f.file) ? relative(cwd, f.file) : f.file
+    if (isIntroducedLine(addedLines, rel, f.line)) introduced.push(f)
+    else preExisting.push(f)
+  }
+  return { introduced, preExisting }
+}
+
+/**
+ * Рядок одного finding: `<rel>:<line>  <rule>  <message>`.
+ * @param {{ file: string, line: number, rule: string, message: string }} f finding
+ * @param {string} cwd корінь
+ * @returns {string} рядок
+ */
+function formatFinding(f, cwd) {
+  const rel = isAbsolute(f.file) ? relative(cwd, f.file) : f.file
+  return `     ${rel}:${f.line}  ${f.rule}  ${f.message}`
+}
+
+/**
+ * Згрупований звіт: 🆕 introduced (виправ) + 🗄 pre-existing (борг файлу).
+ * @param {{ introduced: object[], preExisting: object[] }} classified результат `classifyFindings`
+ * @param {string} [cwd] корінь
+ * @returns {string} текст звіту
+ */
+export function renderFindings({ introduced, preExisting }, cwd = process.cwd()) {
+  const lines = []
+  if (introduced.length > 0) {
+    lines.push(`  🆕 introduced (${introduced.length}) — внесено цією зміною, виправ:`)
+    for (const f of introduced) lines.push(formatFinding(f, cwd))
+  }
+  if (preExisting.length > 0) {
+    lines.push(`  🗄 pre-existing (${preExisting.length}) — борг файлу, не з цієї зміни:`)
+    for (const f of preExisting) lines.push(formatFinding(f, cwd))
+  }
+  return lines.join('\n')
+}

package/rules/js-lint/js/lint.mjs

@@ -2,12 +2,17 @@
  * Quick-крок lint правила js-lint: oxlint + eslint (з автофіксом).
  *
  * Викликається lint-оркестратором (`n-cursor lint` / `lint-ci`):
- *  - `files` = масив змінених файлів (quick) → лінтимо лише js-подібні з них;
- *  - `files` = undefined (ci) → лінтимо весь проєкт.
+ *  - `files` = масив змінених файлів (quick) → лінтимо лише js-подібні з них і
+ *    КЛАСИФІКУЄМО лишені findings на introduced (рядок у diff від HEAD) vs
+ *    pre-existing (борг файлу) — беклог #6, варіант A (видимість; блокування без змін);
+ *  - `files` = undefined (ci) → лінтимо весь проєкт (стрімінг, без класифікації).
  * Крос-файлові jscpd/knip — окреме правило js-lint-ci (фаза ci).
  */
 import { spawnSync } from 'node:child_process'
 
+import { addedLinesByFile } from '../../../scripts/lib/diff-added-lines.mjs'
+import { classifyFindings, parseEslint, parseOxlint, renderFindings } from './lint-findings.mjs'
+
 const JS_EXT_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx|vue)$/u
 
 /**
@@ -20,15 +25,88 @@ export function filterJsFiles(files) {
 }
 
 /**
- * @param {string[]} args аргументи інструмента (бінар через bunx)
+ * Запуск інструмента (через bunx) зі стрімінгом у термінал.
+ * @param {string[]} args аргументи
  * @param {string} cwd корінь
  * @returns {number} exit code
  */
-function run(args, cwd) {
+function runInherit(args, cwd) {
   const r = spawnSync('bunx', args, { cwd, stdio: 'inherit' })
   return typeof r.status === 'number' ? r.status : 1
 }
 
+/**
+ * Авто-фікс-пас: застосовує `--fix`, stdout приглушено (findings перерендеримо
+ * класифіковано), stderr — назовні (краші інструмента видимі).
+ * @param {string[]} args аргументи
+ * @param {string} cwd корінь
+ * @returns {number} exit code
+ */
+function runFix(args, cwd) {
+  const r = spawnSync('bunx', args, { cwd, stdio: ['ignore', 'ignore', 'inherit'] })
+  return typeof r.status === 'number' ? r.status : 1
+}
+
+/** Запас буфера для json-виводу лінтерів (великі changeset-и > дефолтного ~1MB). */
+const JSON_MAX_BUFFER = 64 * 1024 * 1024
+
+/**
+ * Репорт-пас: `--format=json`. Повертає exit-код і stdout (щоб відрізнити
+ * «чисто/є-порушення» від краху інструмента).
+ * @param {string[]} args аргументи
+ * @param {string} cwd корінь
+ * @returns {{ status: number, stdout: string }} результат
+ */
+function runJson(args, cwd) {
+  const r = spawnSync('bunx', args, { cwd, encoding: 'utf8', maxBuffer: JSON_MAX_BUFFER })
+  return { status: typeof r.status === 'number' ? r.status : 1, stdout: r.stdout ?? '' }
+}
+
+/**
+ * Full-режим (ci): лінт усього проєкту зі стрімінгом і fail-fast (без класифікації).
+ * @param {string} cwd корінь
+ * @returns {number} exit code
+ */
+function lintFullProject(cwd) {
+  const ox = runInherit(['oxlint', '--fix'], cwd)
+  if (ox !== 0) return ox
+  return runInherit(['eslint', '--fix', '.'], cwd)
+}
+
+/**
+ * Quick-режим: авто-фікс змінених файлів, тоді класифікація лишених findings
+ * на introduced / pre-existing (беклог #6/A). Блокування на будь-якому finding.
+ * @param {string[]} js js-подібні змінені файли
+ * @param {string} cwd корінь
+ * @returns {number} exit code (0 — чисто; 1 — лишились findings)
+ */
+function lintChangedClassified(js, cwd) {
+  // Фікс-пас обох інструментів (послідовно; обидва — щоб репорт показав повну картину).
+  runFix(['oxlint', '--fix', ...js], cwd)
+  runFix(['eslint', '--fix', ...js], cwd)
+
+  // Репорт-пас по ФІНАЛЬНОМУ (пост-фікс) файлу — рядки findings і diff узгоджені.
+  const oxRes = runJson(['oxlint', '--format=json', ...js], cwd)
+  const esRes = runJson(['eslint', '--format=json', ...js], cwd)
+  const ox = parseOxlint(oxRes.stdout)
+  const es = parseEslint(esRes.stdout)
+
+  // Краш інструмента (ненульовий exit + непарсабельний json) НЕ можна тихо пропустити
+  // як «чисто» — це регресія проти старого fail-fast. Фейлимо явно.
+  if ((ox === null && oxRes.status !== 0) || (es === null && esRes.status !== 0)) {
+    process.stderr.write('❌ js-lint: інструмент завершився з помилкою (не lint-порушення) — json не розпарсено\n')
+    return 1
+  }
+
+  const findings = [...(ox ?? []), ...(es ?? [])]
+  if (findings.length === 0) return 0
+
+  const classified = classifyFindings(findings, addedLinesByFile(js, cwd), cwd)
+  const header = `❌ js-lint: ${findings.length} порушень (introduced ${classified.introduced.length}, pre-existing ${classified.preExisting.length})`
+  process.stdout.write(`${header}\n${renderFindings(classified, cwd)}\n`)
+  return 1
+}
+
 /**
  * Запускає oxlint+eslint з автофіксом.
  * @param {string[] | undefined} files quick: лише ці файли; undefined: весь проєкт
@@ -36,17 +114,10 @@ function run(args, cwd) {
  * @returns {Promise<number>} 0 — OK, ≠0 — порушення
  */
 export function lint(files, cwd = process.cwd()) {
-  let oxArgs = ['oxlint', '--fix']
-  let esArgs = ['eslint', '--fix']
   if (files === undefined) {
-    esArgs.push('.')
-  } else {
-    const js = filterJsFiles(files)
-    if (js.length === 0) return Promise.resolve(0)
-    oxArgs = ['oxlint', '--fix', ...js]
-    esArgs = ['eslint', '--fix', ...js]
+    return Promise.resolve(lintFullProject(cwd))
   }
-  const ox = run(oxArgs, cwd)
-  if (ox !== 0) return Promise.resolve(ox)
-  return Promise.resolve(run(esArgs, cwd))
+  const js = filterJsFiles(files)
+  if (js.length === 0) return Promise.resolve(0)
+  return Promise.resolve(lintChangedClassified(js, cwd))
 }

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`).