@nitra/cursor 3.21.1 → 3.23.0

package/rules/vue/lib/docs/vue-forbidden-imports.md

@@ -0,0 +1,261 @@
+# vue-forbidden-imports.mjs
+
+## Огляд
+
+Модуль `vue-forbidden-imports.mjs` — це бібліотека статичного аналізу `import`-декларацій, призначена для виявлення двох категорій порушень у вихідному коді Vue-проєкту:
+
+1. **Явні (runtime) імпорти з модуля `vue`** у будь-яких файлах, що сканує правило. За конвенцією `vue.mdc` у проєкті працює `unplugin-auto-import`, тому імпорти `ref`, `computed`, `watch` тощо мають бути неявними. Дозволено лише: side-effect форму (`import 'vue'`), повністю type-only імпорти (`import type { ... } from 'vue'`) та змішані форми, де **всі** іменовані записи мають флаг `isType` (наприклад, `import { type A, type B } from 'vue'`).
+2. **Імпорти Node-нативних модулів усередині `.vue` SFC** — `node:fs`, `node:timers/promises`, а також bare-форми вбудованих модулів (`fs`, `path`, `crypto`, `fs/promises` тощо). Vue Single-File Components виконуються в браузерному середовищі, де Node API недоступне, тому такі імпорти зривають збірку чи призводять до runtime-помилок.
+
+Аналіз виконується через **oxc-parser** (`parseSync`) — ESTree-сумісний AST-парсер, що повертає об'єкт із полем `module.staticImports`. Це усуває потребу в крихких регулярних виразах для розпізнавання структури імпортів і коректно обробляє TypeScript-синтаксис (включно з type-only записами через флаг `entries[].isType`).
+
+Для `.vue` файлів виконується попередній етап: регулярним виразом витягуються вмісти всіх тегів `<script>` / `<script setup>` (template ігнорується), і вже цей конкатенований код подається парсеру з віртуальним ім'ям `*.ts`, щоб увімкнути TypeScript-режим.
+
+Модуль чисто функціональний: жодних звернень до файлової системи, мережі чи глобального стану — усі функції приймають уже прочитаний контент і повертають структуровані дані про порушення.
+
+## Експорти / API
+
+Усі експорти — іменовані (named exports), default export відсутній.
+
+| Експорт                                                      | Тип      | Призначення                                                                          |
+| ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------ |
+| `extractVueScriptBlocks(sfc)`                                | function | Витягує конкатенований код усіх `<script>` блоків з `.vue` SFC.                      |
+| `contentForVueImportScan(content, filePath)`                 | function | Повертає текст для сканування: для `.vue` — лише script-блоки, інакше — увесь вміст. |
+| `findForbiddenVueImportsInText(content, virtualPath?)`       | function | Знаходить заборонені static-імпорти з `vue` у вже підготовленому тексті.             |
+| `shouldSkipFileForVueImportScan(relativePosix)`              | function | Чи пропустити файл під час обходу пакета (генерація, `.d.ts`).                       |
+| `isVueImportScanSourceFile(relativePath)`                    | function | Чи розширення файлу підходить для сканування.                                        |
+| `findForbiddenVueImportsInSourceFile(content, relativePath)` | function | Об'єднує підготовку контенту та парсинг для одного файлу.                            |
+| `isNodeBuiltinSpecifier(spec)`                               | function | Чи специфікатор імпорту відповідає Node-нативному модулю.                            |
+| `findForbiddenNodeImportsInText(content, virtualPath?)`      | function | Знаходить заборонені Node-імпорти у тексті.                                          |
+| `findForbiddenNodeImportsInVueFile(content, relativePath)`   | function | Знаходить заборонені Node-імпорти лише у `.vue` файлах (template ігнорується).       |
+
+Внутрішні (не експортовані) допоміжні функції: `langFromPath`, `offsetToLine`, `normalizeSnippet`, `isAllowedVueStaticImport`, `virtualPathForParse`.
+
+Внутрішні (не експортовані) константи:
+
+- `NODE_BUILTIN_MODULES` — `Set<string>` з повного списку `builtinModules` Node.js на момент запуску (наприклад, `fs`, `path`, `crypto`, ...).
+- `VUE_EXT_RE` — регекс `/\.vue$/u` для перевірки розширення `.vue`.
+- `SOURCE_FILE_RE` — регекс `/\.(vue|[cm]?[jt]sx?)$/`, що покриває `.vue`, `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`.
+
+## Функції
+
+### `langFromPath(filePath)` — внутрішня
+
+- **Сигнатура:** `(filePath: string) => 'js' | 'jsx' | 'ts' | 'tsx'`
+- **Параметри:**
+  - `filePath` — віртуальний або реальний шлях; розпізнавання йде за суфіксом у lowercase.
+- **Повертає:** значення опції `lang` для `parseSync`. Розширення `.ts`, `.mts`, `.cts` → `'ts'`; `.tsx` → `'tsx'`; `.jsx` → `'jsx'`; решта (включно з `.js`, `.mjs`, `.cjs`, відсутність розширення) → `'js'`.
+- **Side effects:** немає.
+
+### `offsetToLine(content, offset)` — внутрішня
+
+- **Сигнатура:** `(content: string, offset: number) => number`
+- **Параметри:**
+  - `content` — повний текст файлу.
+  - `offset` — байтове зміщення (точніше — індекс кодової одиниці UTF-16) початку фрагмента.
+- **Повертає:** 1-based номер рядка для зміщення. Алгоритм лінійно проходить діапазон `[0, min(offset, content.length))` і збільшує лічильник для кожного `\n` (code point `10`).
+- **Side effects:** немає.
+
+### `normalizeSnippet(s)` — внутрішня
+
+- **Сигнатура:** `(s: string) => string`
+- **Параметри:**
+  - `s` — довільний фрагмент коду.
+- **Повертає:** однорядковий рядок: усі послідовності whitespace замінено одним пробілом, обрізано початкові/кінцеві пробіли, обмежено перші 160 символів.
+- **Side effects:** немає.
+
+### `isAllowedVueStaticImport(imp)` — внутрішня
+
+- **Сигнатура:** `(imp: { moduleRequest: { value: string }, entries: { isType: boolean }[] }) => boolean`
+- **Параметри:**
+  - `imp` — один запис із масиву `module.staticImports`, отриманого від `parseSync`.
+- **Повертає:** `true`, якщо:
+  - `entries.length === 0` (це `import 'vue'` — side-effect форма), **або**
+  - усі `entries` мають `isType === true` (повністю type-only або змішана форма з `import { type X } from 'vue'`).
+- **Side effects:** немає.
+
+### `extractVueScriptBlocks(sfc)` — експортована
+
+- **Сигнатура:** `(sfc: string) => string`
+- **Параметри:**
+  - `sfc` — повний вміст `.vue` файлу.
+- **Повертає:** конкатенацію (роздільник `\n\n`) тіл усіх знайдених `<script>` блоків. Регекс `/<script\b[^>]*>([\s\S]*?)<\/script>/gi` дозволяє атрибути після `<script` (наприклад, `setup`, `lang="ts"`, `generic="T"`) і не чіпає шаблон `<template>` чи стилі `<style>`.
+- **Side effects:** немає.
+
+### `contentForVueImportScan(content, filePath)` — експортована
+
+- **Сигнатура:** `(content: string, filePath: string) => string`
+- **Параметри:**
+  - `content` — сирий вміст файлу.
+  - `filePath` — шлях, потрібний лише для перевірки суфікса `.vue`.
+- **Повертає:** для `.vue` — результат `extractVueScriptBlocks(content)`; інакше — `content` без змін.
+- **Side effects:** немає.
+
+### `virtualPathForParse(relativePath)` — внутрішня
+
+- **Сигнатура:** `(relativePath: string) => string`
+- **Параметри:**
+  - `relativePath` — шлях файлу в пакеті/репо.
+- **Повертає:** якщо суфікс `.vue` — той самий шлях із заміною `.vue` на `.ts` (для `langFromPath` → `'ts'`); інакше — шлях без змін.
+- **Side effects:** немає.
+
+### `findForbiddenVueImportsInText(content, virtualPath?)` — експортована
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string }[]`
+- **Параметри:**
+  - `content` — вже підготовлений текст для парсингу (для `.vue` — лише `<script>` блоки).
+  - `virtualPath` — необов'язковий шлях для вибору `lang`. Значення за замовчуванням — `'scan.ts'` (TypeScript-режим). Якщо передано порожнє/falsy значення — використовується той самий fallback `'scan.ts'`.
+- **Повертає:** масив об'єктів `{ line, snippet }`, де:
+  - `line` — 1-based номер рядка, де починається `import`,
+  - `snippet` — стиснений однорядковий фрагмент тексту `content.slice(imp.start, imp.end)` (≤ 160 символів).
+- **Поведінка:**
+  - У разі будь-якої exception з `parseSync` (`try/catch`) повертає `[]`.
+  - Якщо `result.errors?.length > 0` — повертає `[]` (тобто за наявності синтаксичних помилок порушення не репортяться; коментар у файлі прямо радить «спочатку виправ синтаксис»).
+  - Інакше проходить `result.module.staticImports` і додає в результат запис, якщо `moduleRequest.value === 'vue'` **і** `!isAllowedVueStaticImport(imp)`.
+- **Side effects:** немає (читання Node-builtins трапилось лише на старті модуля).
+
+### `shouldSkipFileForVueImportScan(relativePosix)` — експортована
+
+- **Сигнатура:** `(relativePosix: string) => boolean`
+- **Параметри:**
+  - `relativePosix` — шлях файлу з posix-слешами (форвард-слеш як роздільник).
+- **Повертає:** `true`, якщо:
+  - basename дорівнює `auto-imports.d.ts` або `components.d.ts` (типові згенеровані файли від `unplugin-auto-import` / `unplugin-vue-components`), **або**
+  - шлях закінчується на `.d.ts` (будь-який type-declaration файл).
+- **Side effects:** немає.
+
+### `isVueImportScanSourceFile(relativePath)` — експортована
+
+- **Сигнатура:** `(relativePath: string) => boolean`
+- **Параметри:**
+  - `relativePath` — відносний шлях.
+- **Повертає:** `true`, якщо суфікс файлу відповідає `SOURCE_FILE_RE` (тобто `.vue`, `.js`, `.cjs`, `.mjs`, `.jsx`, `.ts`, `.cts`, `.mts`, `.tsx`).
+- **Side effects:** немає.
+
+### `findForbiddenVueImportsInSourceFile(content, relativePath)` — експортована
+
+- **Сигнатура:** `(content: string, relativePath: string) => { line: number, snippet: string }[]`
+- **Параметри:**
+  - `content` — сирий вміст файлу.
+  - `relativePath` — шлях відносно кореня пакета чи репо.
+- **Повертає:** результат `findForbiddenVueImportsInText(scan, virtualPath)`, де:
+  - `scan = contentForVueImportScan(content, relativePath)` — для `.vue` витягнуті `<script>` блоки, для решти — `content`;
+  - `virtualPath = virtualPathForParse(relativePath)` — для `.vue` замінено суфікс на `.ts`, для решти — без змін.
+- **Side effects:** немає.
+
+### `isNodeBuiltinSpecifier(spec)` — експортована
+
+- **Сигнатура:** `(spec: string) => boolean`
+- **Параметри:**
+  - `spec` — значення `moduleRequest.value` (текст специфікатора імпорту).
+- **Повертає:** `true`, якщо специфікатор — Node-нативний модуль. Послідовність перевірок:
+  1. Якщо `spec` не рядок або порожній → `false`.
+  2. Префікс `node:` → `true` (покриває `node:fs`, `node:timers/promises`, `node:test` тощо).
+  3. Точне співпадіння в `NODE_BUILTIN_MODULES` → `true` (наприклад, `fs`, `path`, `crypto`).
+  4. Якщо є слеш на позиції > 0 — перевірити «head» (`spec.slice(0, slashIdx)`); якщо head у `NODE_BUILTIN_MODULES` → `true` (покриває підшляхи на кшталт `fs/promises`, `stream/web`, `timers/promises`).
+  5. Інакше → `false`.
+- **Side effects:** немає.
+
+### `findForbiddenNodeImportsInText(content, virtualPath?)` — експортована
+
+- **Сигнатура:** `(content: string, virtualPath?: string) => { line: number, snippet: string, specifier: string }[]`
+- **Параметри:**
+  - `content` — підготовлений текст (для `.vue` — `<script>` блоки).
+  - `virtualPath` — шлях для вибору `lang`. Default — `'scan.ts'`; при falsy використовується той самий fallback.
+- **Повертає:** масив `{ line, snippet, specifier }`. Структура `line` / `snippet` ідентична `findForbiddenVueImportsInText`; поле `specifier` — це сирий рядок з `imp.moduleRequest.value` (наприклад, `'node:fs'` або `'fs/promises'`).
+- **Поведінка:**
+  - Парсинг через `parseSync(pathForLang, content, { lang, sourceType: 'module' })` всередині `try/catch` — будь-яка exception → `[]`.
+  - Якщо `result.errors?.length > 0` → `[]`.
+  - Для кожного `imp` із `result.module.staticImports` перевіряється `isNodeBuiltinSpecifier(spec)`; при `true` додається запис у результат.
+  - Зверніть увагу: правило репортить **усі** Node-імпорти у Vue-контексті, у тому числі type-only (`import type { Stats } from 'fs'`) — коментар у вихідному коді пояснює, що type-only імпорти Node-модулів у SFC заплутують і доцільніше тримати такий код у server-side утилітах.
+- **Side effects:** немає.
+
+### `findForbiddenNodeImportsInVueFile(content, relativePath)` — експортована
+
+- **Сигнатура:** `(content: string, relativePath: string) => { line: number, snippet: string, specifier: string }[]`
+- **Параметри:**
+  - `content` — сирий вміст файлу.
+  - `relativePath` — шлях відносно кореня пакета чи репо.
+- **Повертає:**
+  - Якщо суфікс не `.vue` → `[]` (правило стосується лише SFC; композаблі та утиліти на Node-side можуть жити у `.ts`/`.js`).
+  - Інакше: `findForbiddenNodeImportsInText(extractVueScriptBlocks(content), virtualPathForParse(relativePath))`.
+- **Side effects:** немає.
+
+## Залежності
+
+### Зовнішні модулі
+
+- **`node:module` (Node.js builtin)** — імпортується `builtinModules` для формування `NODE_BUILTIN_MODULES`. Список фіксується на момент запуску модуля (одноразово).
+- **`oxc-parser`** — `parseSync(filename, source, options)`. Очікувані опції:
+  - `lang: 'js' | 'jsx' | 'ts' | 'tsx'` — обирається `langFromPath`;
+  - `sourceType: 'module'` — фіксовано як ES-module.
+  - Результат використовується через:
+    - `result.errors` — масив синтаксичних помилок; за наявності повертається `[]`;
+    - `result.module.staticImports` — масив записів виду `{ moduleRequest: { value }, entries: [{ isType }], start, end }`.
+
+### Внутрішні залежності між функціями цього файлу
+
+- `findForbiddenVueImportsInSourceFile` → `contentForVueImportScan`, `virtualPathForParse`, `findForbiddenVueImportsInText`.
+- `findForbiddenVueImportsInText` → `langFromPath`, `offsetToLine`, `normalizeSnippet`, `isAllowedVueStaticImport`.
+- `findForbiddenNodeImportsInVueFile` → `extractVueScriptBlocks`, `virtualPathForParse`, `findForbiddenNodeImportsInText`.
+- `findForbiddenNodeImportsInText` → `langFromPath`, `offsetToLine`, `normalizeSnippet`, `isNodeBuiltinSpecifier`.
+- `contentForVueImportScan` → `extractVueScriptBlocks`.
+- `isNodeBuiltinSpecifier` → `NODE_BUILTIN_MODULES`.
+
+### Зовнішні споживачі (за конвенцією)
+
+Файл лежить у `npm/rules/vue/lib/` і призначений для використання з `check-*.mjs` сценаріїв правила `n-vue`-родини. Сценарії-перевірки самі обходять пакети, читають файли з диска, фільтрують їх через `shouldSkipFileForVueImportScan` та `isVueImportScanSourceFile`, і викликають `findForbiddenVueImportsInSourceFile` / `findForbiddenNodeImportsInVueFile`.
+
+## Потік виконання / Використання
+
+### Типовий потік для сканера-перевірки
+
+1. Сценарій-перевірка обходить файли в пакеті, отримуючи `(relativePath, absolutePath)`.
+2. Фільтрація:
+   - `if (shouldSkipFileForVueImportScan(relativePosix)) continue;` — пропустити `.d.ts` і згенеровані файли.
+   - `if (!isVueImportScanSourceFile(relativePath)) continue;` — пропустити не-source файли (скажімо, `.json`, `.md`).
+3. Прочитати `content = fs.readFileSync(absolutePath, 'utf8')`.
+4. Знайти порушення:
+   - `const vueViolations = findForbiddenVueImportsInSourceFile(content, relativePath);`
+   - `const nodeViolations = findForbiddenNodeImportsInVueFile(content, relativePath);`
+5. Якщо масиви непорожні — зрепортити користувачу: `relativePath:${line}` + `snippet` (+ `specifier` для Node-порушень).
+
+### Точкове використання
+
+- **Тільки сирий код (без файлів):** виклик `findForbiddenVueImportsInText(code, 'scan.ts')` або `findForbiddenNodeImportsInText(code, 'scan.ts')` напряму — корисно для unit-тестів модуля.
+- **Лише витяг `<script>` блоків:** `extractVueScriptBlocks(sfc)` повертає конкатенований код; зручно для інших сканерів, що працюють лише з JS/TS-частиною SFC.
+
+### Контракти й тонкі моменти
+
+- **Помилки парсингу = «не репортимо».** Якщо `parseSync` кинув exception **або** повернув `result.errors.length > 0`, обидві `find*InText` функції повертають `[]`. Це навмисний дизайн: правило не намагається лагодити синтаксис — спочатку файл має бути коректним, тоді сканер дасть осмислений вихід.
+- **Default `virtualPath = 'scan.ts'`.** Без передачі `virtualPath` режим парсингу — TypeScript. Це безпечно і для чистого JS (TS-парсер приймає JS-синтаксис), і дозволяє type-only синтаксис.
+- **Type-only синтаксис у `vue` дозволено.** `import type { Ref } from 'vue'` і `import { type Ref } from 'vue'` пройдуть перевірку через `entries[].isType === true`. Це не суперечить ідеї auto-import: типи завжди потрібно імпортувати явно.
+- **Type-only синтаксис у Node-імпортах НЕ дозволено.** Для `.vue` навіть `import type { Stats } from 'fs'` буде в результаті — модуль не розглядає `isType` для Node-перевірки.
+- **`offsetToLine` рахує `\n` посимвольно.** Складність `O(offset)`. На великих файлах із багатьма імпортами це сумарно `O(N·M)`, але на практиці прийнятно (файли SFC рідко > 10k рядків).
+- **`normalizeSnippet` обмежує 160 символів** і стискає whitespace — формат повідомлення про порушення стабільний, незалежно від форматування у коді.
+
+## Rebuild Test
+
+За цією документацією має бути можливо відновити функціональний еквівалент модуля. Контрольні точки відтворення:
+
+- **Експорти:** `extractVueScriptBlocks`, `contentForVueImportScan`, `findForbiddenVueImportsInText`, `shouldSkipFileForVueImportScan`, `isVueImportScanSourceFile`, `findForbiddenVueImportsInSourceFile`, `isNodeBuiltinSpecifier`, `findForbiddenNodeImportsInText`, `findForbiddenNodeImportsInVueFile` — усі named, default відсутній.
+- **Регулярні вирази:**
+  - `<script>` екстрактор: `/<script\b[^>]*>([\s\S]*?)<\/script>/gi`.
+  - `.vue` суфікс: `/\.vue$/u`.
+  - Source files: `/\.(vue|[cm]?[jt]sx?)$/`.
+- **Skip-файли:** basename `auto-imports.d.ts` / `components.d.ts` або суфікс `.d.ts`.
+- **`langFromPath` мапінг:** `.tsx`→`tsx`; `.ts|.mts|.cts`→`ts`; `.jsx`→`jsx`; default→`js` (через lowercase порівняння суфіксів).
+- **Vue allow-list:** порожній `entries` (side-effect `import 'vue'`) або `entries.every(e => e.isType)`.
+- **Node-builtin перевірка:**
+  1. Не рядок або порожній → `false`.
+  2. `startsWith('node:')` → `true`.
+  3. У `Set(builtinModules)` → `true`.
+  4. Якщо є слеш (індекс > 0) і head у Set → `true`.
+  5. Інакше → `false`.
+- **Парсер:** `parseSync(virtualPath, content, { lang, sourceType: 'module' })`; обробка `try/catch` + перевірка `result.errors?.length`.
+- **Результат-формат:** Vue-порушення — `{ line, snippet }`; Node-порушення — `{ line, snippet, specifier }`.
+- **Default `virtualPath`:** `'scan.ts'` (включно з fallback при falsy значенні).
+- **`findForbiddenNodeImportsInVueFile` гарантія:** для не-`.vue` повертає `[]` навіть якщо файл містить Node-імпорти.
+- **`virtualPathForParse`:** `.vue` → той самий шлях з суфіксом `.ts`; інакше — без змін.
+- **Snippet:** `replaceAll(/\s+/g, ' ').trim().slice(0, 160)`.
+- **`offsetToLine`:** 1-based, лічить `\n` (code point 10) у діапазоні `[0, min(offset, length))`.

package/rules/worktree/docs/fix.md

@@ -0,0 +1,161 @@
+# fix.mjs — точка входу правила `worktree` (fix)
+
+## Огляд
+
+Файл `npm/rules/worktree/fix.mjs` — це **точка входу правила `worktree`** для пакета `@nitra/cursor`. Він реалізує **дві ролі одночасно** (dual role):
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку CLI-оркестратор `@nitra/cursor` (або інший runner) викликає через `import { run } from '.../fix.mjs'` для запуску правила в межах батч-прогону всіх правил.
+2. **Standalone mode** — якщо файл запускається напряму через `bun npm/rules/worktree/fix.mjs`, він самостійно ініціалізує CLI-обгортку (config-loading, whitelist, summary) і завершує процес `exit-code`-ом, придатним для CI/IDE.
+
+Сам файл **не містить власної логіки перевірки** — він лише делегує виконання стандартному раннеру `runStandardRule`, який послідовно виконує підкроки правила в наступному порядку:
+
+- **applies** — детектор, чи застосовне правило до конкретного файлу/директорії;
+- **JS-concerns** — JS-перевірки (зокрема `check-*.mjs` у директорії правила);
+- **policy** — політики/декларативні перевірки;
+- **mdc-refs** — перевірка посилань у відповідному `.mdc`-документі правила.
+
+Каталог `worktree/` стосується доменного правила про **git worktree** (див. `.cursor/rules/n-worktree.mdc`) — конвенцій ізольованих робочих дерев у `.worktrees/<branch>/` та інвентарних описів. Сам `fix.mjs` не реалізує цих перевірок безпосередньо — він лише диспетчеризує їх через стандартний пайплайн.
+
+## Експорти / API
+
+| Експорт | Тип                                             | Призначення                                                                                                                                                         |
+| ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function (ctx?: RuleContext): Promise<number>` | Library-entry. Запускає стандартний пайплайн правила для директорії, в якій знаходиться `fix.mjs`. Повертає **exit-code**: `0` — порушень немає, `1` — є порушення. |
+
+Файл також містить **side-effect блок** (виконується тільки при прямому запуску як CLI), який не є експортом, але є частиною контракту:
+
+- При `isRunAsCli(import.meta.url) === true` модуль викликає `runRuleCli(import.meta.dirname)` і завершує процес `process.exit(<code>)`.
+
+## Функції
+
+### `run(ctx)`
+
+**Сигнатура:**
+
+```js
+export function run(ctx)
+```
+
+**Параметри:**
+
+| Параметр | Тип                                                         | Обов'язковий | Опис                                                                                                                                                                                                                                                             |
+| -------- | ----------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx`    | `RuleContext` (з `../../scripts/lib/run-standard-rule.mjs`) | Ні           | Контекст прогону правила. Передається оркестратором із `@nitra/cursor` і містить, зокрема, спільні структури на кшталт `walkCache` (кеш обходу файлової системи між кількома правилами в одному прогоні). Якщо не передано — раннер створить дефолтний контекст. |
+
+**Повертає:** `Promise<number>` — exit-code:
+
+- `0` — правило виконалося без порушень;
+- `1` — знайдено порушення (інтерпретація залежить від `runStandardRule`).
+
+**Side effects:**
+
+- Сама `run` не пише в `stdout` напряму та не змінює FS — усі побічні ефекти інкапсульовані в `runStandardRule` (форматований вивід summary, потенційне читання `.mdc`/`check-*.mjs`-файлів сусідньої директорії, обхід проєктних файлів через `walkCache`).
+- `run` **не** викликає `process.exit` — це відповідальність standalone-блоку нижче.
+
+**Поведінкова ідіома:**
+
+`run` — це тонкий **прокладочний шар**: він фіксує **директорію** правила (`import.meta.dirname`), бо саме за нею раннер визначає `id` правила (ім'я каталогу `worktree`), знаходить сусідні файли (`policy.mjs`, `applies.mjs`, `check-*.mjs`, `<id>.mdc`) та збирає пайплайн.
+
+### Standalone-блок (top-level)
+
+Анонімний side-effect блок, що виконується лише при прямому запуску:
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+**Поведінка:**
+
+- `isRunAsCli(import.meta.url)` повертає `true`, якщо модуль є **головним** entry-point процесу (а не імпортований). Це типова заміна паттерну `require.main === module` для ESM.
+- `runRuleCli(import.meta.dirname)` — повна CLI-обгортка над `run`: завантажує проєктний config, застосовує whitelist (наприклад, виключення з `.cursorignore`/конфігу), друкує summary після виконання та повертає підсумковий exit-code.
+- `process.exit(code)` — закриває процес з кодом, придатним для CI/IDE. Лінт-винятки `n/no-process-exit` та `unicorn/no-process-exit` свідомо вимкнені коментарем, бо standalone entry-point має лагідно виходити з конкретним кодом, інакше CI не отримає сигналу про fail.
+
+## Залежності
+
+Внутрішні залежності (відносні до `npm/scripts/lib/`):
+
+| Імпорт            | З файлу                                   | Призначення                                                                                                                        |
+| ----------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Перевіряє, чи поточний модуль є головним процесом (заміна `require.main === module` для ESM).                                      |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Standalone-обгортка: config-loading + whitelist + summary + exit-code. Еквівалент `npx @nitra/cursor fix <id>` для одного правила. |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний пайплайн правила: applies → JS-concerns → policy → mdc-refs. Приймає директорію правила та опційний `RuleContext`.     |
+
+Зовнішні залежності та глобальні API:
+
+- `import.meta.dirname` — ESM-аналог `__dirname`; використовується для передачі шляху до каталогу правила раннерам.
+- `import.meta.url` — використовується `isRunAsCli` для визначення головного модуля.
+- `process.exit(code)` — Node.js/Bun runtime API для встановлення exit-code.
+
+Файл **не залежить** напряму від конкретних `check-*.mjs`, `policy.mjs`, `<id>.mdc` сусідньої директорії — їх відкриває та інтерпретує `runStandardRule`.
+
+## Потік виконання / Використання
+
+### Сценарій A — Library mode (виклик з оркестратора)
+
+```js
+import { run } from '@nitra/cursor/rules/worktree/fix.mjs'
+
+const ctx = { walkCache: new Map(/* ... */) }
+const exitCode = await run(ctx)
+// exitCode === 0 — OK, 1 — порушення
+```
+
+Послідовність:
+
+1. Оркестратор (`@nitra/cursor fix` без аргументів або з переліком правил) проходить по списку правил і для кожного робить `import('.../fix.mjs')`.
+2. Викликає `run(sharedCtx)`, де `sharedCtx.walkCache` спільний для всіх правил у прогоні (економить FS-обходи).
+3. `run` делегує в `runStandardRule(import.meta.dirname, ctx)`.
+4. `runStandardRule` послідовно виконує під-кроки правила `worktree`: `applies` → JS-перевірки → `policy` → `mdc-refs`.
+5. Повертається `number` (0/1), оркестратор агрегує результати всіх правил у фінальний summary.
+
+Жодних `process.exit` у цьому сценарії — control flow залишається в оркестратора.
+
+### Сценарій B — Standalone mode (прямий запуск)
+
+```bash
+bun npm/rules/worktree/fix.mjs
+# або (еквівалент)
+npx @nitra/cursor fix worktree
+```
+
+Послідовність:
+
+1. Bun завантажує файл; `import.meta.url` вказує на сам файл як головний entry-point.
+2. `isRunAsCli(import.meta.url)` повертає `true`.
+3. Виконується `await runRuleCli(import.meta.dirname)`:
+   - читає проєктний config (`.cursor`/`package.json`);
+   - застосовує whitelist (включення/виключення файлів);
+   - формує `RuleContext` та викликає `run(ctx)` (опосередковано, через стандартний пайплайн);
+   - друкує summary в stdout (кількість порушень, перелік фейлів тощо).
+4. `process.exit(<exitCode>)` — процес закривається з кодом для CI/IDE.
+
+### Чому така архітектура (dual role)
+
+- Library mode дає **спільний батч**: один обхід FS, одна summary, паралельний прогін правил.
+- Standalone mode зручний для **локальної налагодки** одного правила і для **IDE-інтеграцій** (Cursor запускає окремий `fix.mjs` й отримує exit-code).
+- Логіка не дублюється — `runRuleCli` всередині все одно використовує той самий `runStandardRule`.
+
+### Конвенція директорії правила
+
+Для коректної роботи цього `fix.mjs` у сусідній директорії `npm/rules/worktree/` мають бути (опційно — будь-які з):
+
+- `worktree.mdc` (або `<id>.mdc`) — людинозрозумілий опис правила;
+- `applies.mjs` — детектор застосовності;
+- `policy.mjs` — декларативні політики;
+- `check-*.mjs` — JS-перевірки (детальна логіка);
+- `meta.json` — метадані (у т.ч. `worktree: true` для skill-ів).
+
+Сам `fix.mjs` нічого з цього не імпортує напряму — все шукає `runStandardRule` за `import.meta.dirname`.
+
+## Rebuild Test
+
+Перевірка, що файл можна відновити з цієї документації:
+
+1. **Імпорти:** два named-імпорти — `isRunAsCli`, `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`; `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
+2. **Export `run(ctx)`:** JSDoc з `@param ctx` (опційний, тип `RuleContext` із `run-standard-rule.mjs`) та `@returns {Promise<number>}` (0 — OK, 1 — порушення); тіло — `return runStandardRule(import.meta.dirname, ctx)`.
+3. **Top-level `if`:** `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }`.
+4. **Eslint-disable коментар:** перед `process.exit` — `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE`.
+5. **Коментарі:** перед `if`-блоком — пояснення про standalone-режим та еквівалентність `npx @nitra/cursor fix <id>`; над `run` — JSDoc про послідовність applies → JS-concerns → policy → mdc-refs та library mode.
+6. **Стиль:** ESM, без `;` у кінці рядків, single quotes, без default-експортів.

package/schemas/rule-meta.json

@@ -6,7 +6,11 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "lint": { "type": "string", "enum": ["quick", "ci"], "description": "Фаза lint-кроку: quick (по змінених, у lint і lint-ci) або ci (лише lint-ci)." },
+    "lint": {
+      "type": "string",
+      "enum": ["quick", "ci"],
+      "description": "Фаза lint-кроку: quick (по змінених, у lint і lint-ci) або ci (лише lint-ci)."
+    },
     "auto": {
       "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",
       "oneOf": [

package/scripts/auto-rules.mjs

@@ -71,9 +71,7 @@ export function discoverRuleAutoActivation(rulesDir = RULES_DIR) {
 const RULE_AUTO_ACTIVATION = discoverRuleAutoActivation()
 
 /** Стабільний алфавітний порядок (замість хардкод-масиву). */
-export const AUTO_RULE_ORDER = Object.freeze(
-  Object.keys(RULE_AUTO_ACTIVATION).toSorted((a, b) => a.localeCompare(b))
-)
+export const AUTO_RULE_ORDER = Object.freeze(Object.keys(RULE_AUTO_ACTIVATION).toSorted((a, b) => a.localeCompare(b)))
 
 /** Граф залежностей із meta (Type C) — замість хардкод-константи. */
 export const AUTO_RULE_DEPENDENCIES = Object.freeze(
@@ -360,7 +358,12 @@ async function specMatches(spec, ctx) {
  * @param {string[]} [params.disableRules] список `disable-rules` з конфігу
  * @returns {Promise<{ rules: string[] }>} список id у стабільному порядку (за `AUTO_RULE_ORDER`)
  */
-export async function detectAutoRules({ root, availableRules, packageJsonParsed, disableRules = DEFAULT_DISABLED_LIST }) {
+export async function detectAutoRules({
+  root,
+  availableRules,
+  packageJsonParsed,
+  disableRules = DEFAULT_DISABLED_LIST
+}) {
   const facts = await collectAutoRuleFacts(root)
   const paths = await collectRepoPaths(root)
   const normalizedRules = new Set(availableRules.map(r => r.trim().toLowerCase()))