@nitra/cursor 12.8.3 → 12.8.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [12.8.4] - 2026-06-22
+
+### Changed
+
+- ♻️ refactor(npm): Перехід з `style-lint` на `style` у правил та конфігах
+
 ## [12.8.3] - 2026-06-22
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.8.3",
+  "version": "12.8.4",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/js/docs/index.md

@@ -6,7 +6,7 @@ resource: npm/rules/js/
 
 # npm/rules/js
 
-| Файл                | Тип       |
-| ------------------- | --------- |
-| [fix.mjs](fix.md)   | JS Module |
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |
 | [main.mjs](main.md) | JS Module |

package/rules/js/docs/main.md

@@ -3,26 +3,26 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/js/main.mjs
 docgen:
-  crc: 4f68b557
+  crc: 00294e8e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль надає інструменти для аналізу кодової бази. Функція `run` ініціює повну перевірку проєкту. Функція `filterJsFiles` відбирає файли з розширенням JavaScript. Функція `lint` запускає лінтинг для виявлення порушень у коді.
+Дозволяє запускати повний аналіз проєкту за допомогою `run`, виконувати лінтинг за допомогою `lint` або фільтрувати файли з розширенням JavaScript за допомогою `filterJsFiles`.
 
 ## Поведінка
 
 run виконує стандартну перевірку проєкту.
 filterJsFiles відбирає з наданого списку лише файли, що мають розширення, характерне для JavaScript.
-lint запускає лінтинг для вказаних файлів або всього проєкту, залежно від аргументів, і класифікує знайдені порушення.
+lint запускає перевірку проєкту: або повний аналіз усіх файлів, або класифікований аналіз лише змінених файлів.
 
 ## Публічний API
 
-run — головна точка входу для виконання правил, що включає перевірку логіки (JS-завдання → політика → посилання MDC) та запуск лінтера.
-filterJsFiles — відбирає лише файли, що відповідають формату JavaScript.
-lint — виконує аналіз коду за допомогою oxlint та eslint, з можливістю автоматичного виправлення або лише виявлення проблем.
+run — виконує повний цикл перевірки: аналіз конфігурації, перевірку логіки та посилання на метадані.
+filterJsFiles — відбирає лише файли з розширенням JavaScript.
+lint — запускає інструменти для форматування та стилізації коду (oxlint, eslint, jscpd, knip).
 
 ## Гарантії поведінки
 

package/rules/js/js/docs/check.md

@@ -3,34 +3,29 @@ type: JS Module
 title: check.mjs
 resource: npm/rules/js/js/check.mjs
 docgen:
-  crc: f61768f2
+  crc: 7ad4aa59
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 90
 ---
 
 ## Огляд
 
-Модуль виконує перевірку конфігураційних файлів проєкту, забезпечуючи їхню відповідність встановленим стандартам. Він читає та аналізує конфігураційні файли, включаючи `package.json`, `.oxlintrc.json`, `knip.json`, `knip-canonical.json` та `.eslintrc.json`. Перевірка ґрунтується на логіці, визначеній у (js.mdc) та (text.mdc). Функціонал реалізований у режимі лише читання, що означає відсутність змін у файловій системі чи базах даних. При виявленні проблем, система перехоплює помилки, працюючи у режимі fail-safe. Свідомо ігноруються шляхи `.github` та `.git`.
+Модуль перевіряє відповідність структури та конфігураційних файлів проєкту встановленим стандартам. Він валідує файли, такі як `package.json`, `.oxlintrc.json`, `.eslintrc.json` та файли робочих процесів GitHub, відповідно до вимог (js.mdc). Перевірка свідомо ігнорує шляхи `.github` та `.git`. Модуль забезпечує перехоплення помилок (fail-safe) під час виконання перевірок.
 
 ## Поведінка
 
-1. Викликає `check` для початку перевірки.
-2. Перевіряє наявність та відповідність конфігурації ESLint.
-3. Перевіряє конфігурацію `package.json` для всіх робочих просторів:
-   а. Перевіряє, чи має `package.json` `"type": "module"`.
-   б. Перевіряє, чи містить `package.json` `engines.node` з версією не менше 24.
-   в. Перевіряє, чи містить `package.json` `engines.bun` з версією не менше 1.3.
-4. Перевіряє конфігураційний файл `.oxlintrc.json` на відповідність канонічному шаблону.
-5. Перевіряє файли робочих процесів у `.github/workflows/`:
-   а. Перевіряє наявність `lint-js.yml`.
-   б. Перевіряє, чи не дублює `lint.yml` кроки лінтінгу JS.
-6. Перевіряє наявність файлу `knip.json` у корені проєкту. Якщо він відсутній, копіює канонічний шаблон.
-7. Перевіряє наявність застарілих конфігурацій ESLint (`.eslintrc`, `.eslintrc.js`, `.eslintrc.json`, `.eslintrc.yml`) та повідомляє про їхнє існування.
-8. Повертає код виходу, що відображає загальний статус перевірки.
+1. Викликати `check` для запуску перевірок конфігурації проєкту.
+2. Перевірити наявність конфігурацій ESLint (flat config) та валідувати їх вміст відповідно до вимог (js.mdc).
+3. Перевірити `package.json` у корені та у всіх пакетах workspace на відповідність вимогам: наявність `"type": "module"` та мінімальні версії `engines.node` (>=24) та `engines.bun` (>=1.3) (js.mdc).
+4. Перевірити конфігураційний файл `.oxlintrc.json` на відповідність канонічному шаблону (js.mdc).
+5. Перевірити файли робочих процесів (`.github/workflows/lint-js.yml` та `.github/workflows/lint.yml`) на відповідність політикам лінтингу (js.mdc).
+6. Перевірити наявність конфігурацій Knip (`knip.json`). Якщо відсутній, створити його, скопіювавши канонічний шаблон (js.mdc).
+7. Перевірити наявність застарілих конфігурацій ESLint (наприклад, `.eslintrc.*`) та повідомити про їхнє використання.
+8. Ігнорувати перевірки у каталогах `.github` та `.git`.
 
 ## Публічний API
 
-check — забезпечує відповідність проєкту вимогам, описаним у js.mdc.
+check — перевіряє відповідність проєкту стандартам js.mdc
 
 ## Гарантії поведінки
 

package/rules/js/js/docs/index.md

@@ -6,9 +6,9 @@ resource: npm/rules/js/js/
 
 # npm/rules/js/js
 
-| Файл                                  | Тип       |
-| ------------------------------------- | --------- |
-| [check.mjs](check.md)                 | JS Module |
+| Файл | Тип |
+|---|---|
+| [check.mjs](check.md) | JS Module |
 | [lint-findings.mjs](lint-findings.md) | JS Module |
-| [tooling.mjs](tooling.md)             | JS Module |
+| [tooling.mjs](tooling.md) | JS Module |
 | [utils_imports.mjs](utils_imports.md) | JS Module |

package/rules/js/js/docs/tooling.md

@@ -3,26 +3,26 @@ type: JS Module
 title: tooling.mjs
 resource: npm/rules/js/js/tooling.mjs
 docgen:
-  crc: 7ead48ee
+  crc: 101a5230
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 95
 ---
 
 ## Огляд
 
-Визначає шляхи до канонічних конфігураційних файлів для oxlint та knip за допомогою OXLINT_CANONICAL_JSON_PATH та KNIP_CANONICAL_JSON_PATH. Дозволяє перевіряти відповідність конфігураційного файлу .oxlintrc.json до канонічного файлу oxlint-canonical.json за допомогою verifyOxlintRcAgainstCanonical.
+Модуль визначає шляхи до канонічних JSON-файлів для інструментів oxlint та knip через функції OXLINT_CANONICAL_JSON_PATH та KNIP_CANONICAL_JSON_PATH. Він також надає функцію verifyOxlintRcAgainstCanonical для валідації конфігурацій, перевіряючи, чи відповідає `.oxlintrc.json` правилам, визначеним у oxlint-canonical.json.
 
 ## Поведінка
 
-OXLINT_CANONICAL_JSON_PATH — Вказує шлях до канонічного JSON-файлу oxlint у цьому пакеті.
-KNIP_CANONICAL_JSON_PATH — Вказує шлях до канонічного JSON-файлу knip у цьому пакеті.
-verifyOxlintRcAgainstCanonical — Перевіряє конфігураційний файл `.oxlintrc.json` на відповідність канонічному файлу oxlint-canonical.json, виявляючи відхилення у правилах та інших полях.
+OXLINT_CANONICAL_JSON_PATH — Вказує на шлях до канонічного JSON-файлу для oxlint у цьому пакеті.
+KNIP_CANONICAL_JSON_PATH — Вказує на шлях до канонічного JSON-файлу для knip у цьому пакеті.
+verifyOxlintRcAgainstCanonical — Перевіряє конфігурацію `.oxlintrc.json` на відповідність канонічному файлу oxlint-canonical.json, виявляючи відхилення у правилах та інших полях.
 
 ## Публічний API
 
-OXLINT_CANONICAL_JSON_PATH — Вказує розташування стандартного конфігураційного файлу oxlint для валідації.
-KNIP_CANONICAL_JSON_PATH — Вказує розташування стандартного конфігураційного файлу knip, який копіюється у кореневий каталог проєкту, якщо його там немає.
-verifyOxlintRcAgainstCanonical — Порівнює конфігураційний файл `.oxlintrc.json` з канонічним файлом пакета, вимагаючи збігу всіх полів, крім додаткових ключів у секції `rules`.
+OXLINT_CANONICAL_JSON_PATH — вказує на файл з еталонними налаштуваннями oxlint у пакеті.
+KNIP_CANONICAL_JSON_PATH — вказує на файл з еталонними налаштуваннями knip, який копіюється у корінь проєкту, якщо його там немає.
+verifyOxlintRcAgainstCanonical — порівнює конфігураційний файл `.oxlintrc.json` з еталоном, перевіряючи, чи всі правила з еталону присутні, а інші поля збігаються з `oxlint-canonical.json`.
 
 ## Гарантії поведінки
 

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

@@ -3,210 +3,31 @@ type: JS Module
 title: utils_imports.mjs
 resource: npm/rules/js/js/utils_imports.mjs
 docgen:
-  crc: 7eaeaf96
+  crc: 3fc9bf1b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `npm/rules/js/js/utils_imports.mjs` реалізує одну з перевірок правила `js.mdc`: жоден файл усередині будь-якого каталогу з ім'ям `utils/` не має імпортувати щось за межами цього самого каталогу через відносні шляхи з префіксом `..`.
+## Огляд
 
-Філософія перевірки:
+Модуль сканує файли у монорепозиторії. Він зчитує вміст JavaScript/TypeScript файлів та витягує всі рядкові імпорти. На основі конфігурації `.n-cursor.json` він перевіряє, чи не містять імпорти заборонених відносних шляхів, реєструючи відповідний статус у логіці (js.mdc). Публічна функція `check` виконує цю перевірку, свідомо пропускаючи шляхи `.git` та `node_modules`.
 
-- Каталог `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-репорт для кожного імпорту з `..`-префіксом.
+1. Визначає корінь проекту.
+2. Зчитує список шляхів, які слід ігнорувати, на основі конфігурації .n-cursor.json.
+3. Визначає кореневі каталоги пакетів у монорепозиторії.
+4. Для кожного кореневого каталогу пакета рекурсивно шукає каталоги з назвою `utils`, ігноруючи типові артефакти (наприклад, node_modules, .git, dist).
+5. Якщо знайдено каталоги `utils`, для кожного з них рекурсивно збирає всі файли з розширеннями `.js`, `.jsx`, `.ts`, `.tsx`, які не є тестовими.
+6. Для кожного зібраного файлу зчитує його вміст.
+7. Витягує з вмісту файлу всі рядкові імпорти (статичні, динамічні та виклики `require`).
+8. Для кожного витягнутого імпорту перевіряє, чи відповідає він шаблону забороненого відносного шляху, що вказує на імпорт з іншого каталогу, який не є загальним.
+9. Якщо заборонений імпорт знайдено, реєструє помилку, посилаючись на файл та заборонений імпорт (js.mdc).
+10. Якщо жодних порушень не знайдено, реєструє успіх (js.mdc).
+11. Повертає код виходу, що відображає статус перевірки.
 
-Файл є точкою входу 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.mdc` (зазвичай із `npm/rules/js/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.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.mdc)')`.
-5. `violations` інкрементується.
-6. По завершенню `getExitCode() → 1`.
-
-### Сценарій "немає utils/"
-
-1. У жодному package немає каталогу `utils/`.
-2. `utilsDirSet.size === 0`.
-3. `reporter.pass('utils-каталогів немає — перевірку пропущено (js.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.mdc`
-
-Файл є технічною реалізацією одного з пунктів правила `js.mdc`. Усі повідомлення `reporter.pass/fail` посилаються на `(js.mdc)`, щоб користувач знав, де читати про сам принцип розділу `utils/` ↔ `lib/`.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/rules/npm-module/js/docs/index.md

@@ -6,9 +6,9 @@ resource: npm/rules/npm-module/js/
 
 # npm/rules/npm-module/js
 
-| Файл                                            | Тип       |
-| ----------------------------------------------- | --------- |
+| Файл | Тип |
+|---|---|
 | [header_doc_pointer.mjs](header_doc_pointer.md) | JS Module |
-| [package_structure.mjs](package_structure.md)   | JS Module |
-| [rule_meta.mjs](rule_meta.md)                   | JS Module |
-| [skill_meta.mjs](skill_meta.md)                 | JS Module |
+| [package_structure.mjs](package_structure.md) | JS Module |
+| [rule_meta.mjs](rule_meta.md) | JS Module |
+| [skill_meta.mjs](skill_meta.md) | JS Module |

package/rules/npm-module/js/docs/rule_meta.md

@@ -3,31 +3,31 @@ type: JS Module
 title: rule_meta.mjs
 resource: npm/rules/npm-module/js/rule_meta.mjs
 docgen:
-  crc: 938ccd0a
+  crc: 84394694
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль перевіряє конфігурацію правил, розташованих у каталозі `npm/rules`. Він забезпечує наявність обов'язкового файлу `scripts.mdc` для кожного правила. Крім того, він валідує структуру метаданих у `meta.json`, перевіряючи відповідність полів, таких як `auto` та `lint`, визначеним контрактам. У процесі перевірки використовуються маркери повідомлень (scripts.mdc).
+Модуль перевіряє конфігурації правил, розташованих у каталозі `npm/rules`. Він гарантує, що кожен підкаталог правила містить необхідні файли, включаючи маркери повідомлень (`scripts.mdc`), та коректно структурований конфігураційний файл, що базується на `main.json` та `meta.json`. Перевірка включає валідацію визначених предикатів та експортованих функцій відповідно до очікуваного контракту.
 
 ## Поведінка
 
-1. Викликати `check` для початку валідації.
-2. Перевірити наявність каталогу `npm/rules` у корені репозиторію. Якщо каталог відсутній, валідація завершується успішно.
-3. Для кожного підкаталогу у `npm/rules` (який представляє правило):
-   а. Перевірити наявність файлу `auto.md`. Якщо він присутній, реєструється помилка, оскільки метадані тепер знаходяться у `meta.json`.
-   б. Перевірити наявність файлу `<id>.mdc` у каталозі правила. Якщо він відсутній, реєструється помилка, оскільки це обов'язковий файл (scripts.mdc).
-   в. Зчитати вміст `meta.json` правила. Якщо файл відсутній або невалідний, реєструється помилка, і перевірка цього правила припиняється.
-   г. Перевірити поле `auto` у `meta.json`. Якщо поле `auto` присутнє, воно повинно бути валідним (відповідати одному з визначених форматів, або бути відсутнім). Якщо поле `auto` містить невідомий предикат, реєструється помилка.
-   ґ. Перевірити поле `lint` у `meta.json`. Якщо поле `lint` присутнє, воно повинно бути валідним (відповідати "per-file" або "full"). Також перевіряється, чи експортує файл `main.mjs` у каталозі правила функцію `lint` відповідно до зазначеного значення `lint`.
-   і. Якщо всі перевірки для правила пройшли успішно, реєструється повідомлення про валідність `meta.json`.
-4. Після обробки всіх правил, повертається код виходу, що відображає загальний статус валідації.
+1. Перевіряє наявність каталогу `npm/rules` у корені репозиторію. Якщо каталог відсутній, завершує роботу, повідомляючи про відсутність правил для валідації.
+2. Ітерує по всім підкаталогах у `npm/rules`, ігноруючи приховані каталоги.
+3. Для кожного каталогу виконує перевірку правила:
+    а. Перевіряє відсутність файлу `auto.md`. Якщо знайдено, повідомляє про залишковий файл.
+    б. Перевіряє наявність файлу `main.mdc`. Якщо відсутній, повідомляє про відсутність обов'язкового файлу (scripts.mdc).
+    в. Зчитує вміст `main.json` каталогу правила. Якщо файл відсутній або невалідний, повідомляє про це та пропускає подальшу валідацію цього правила.
+    г. Перевіряє поле `auto` у `main.json`. Якщо поле присутнє, валідує його структуру та перевіряє, чи всі використані предикати визначені.
+    ґ. Перевіряє поле `lint` у `main.json`. Якщо поле присутнє, валідує його структуру та перевіряє, чи експортує файл `main.mjs` відповідну функцію `lint`.
+    і. Якщо всі перевірки для правила пройдені успішно, повідомляє про валідність `main.json`.
+4. Після обробки всіх правил повертає код виходу, що відображає загальний статус валідації.
 
 ## Публічний API
 
-check — перевіряє відповідність усіх файлів `npm/rules/<id>/meta.json` встановленим критеріям.
+check — перевіряє відповідність усіх `npm/rules/<id>/meta.json` вимогам.
 
 ## Гарантії поведінки
 

package/rules/npm-module/js/docs/skill_meta.md

@@ -3,24 +3,34 @@ type: JS Module
 title: skill_meta.mjs
 resource: npm/rules/npm-module/js/skill_meta.mjs
 docgen:
-  crc: a069397b
+  crc: d02dd00d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Перевірка стану конфігурації. Файл перевіряє відповідність між полями worktree та requireRoot. Перевірка спирається на конфіги meta.json.
+## Огляд
+
+Перевіряє структуру та конфігурацію скілів у каталозі `npm/skills`, використовуючи правила, визначені в `meta.json`. Валідує, що кожен скіл не містить файлу `auto.md`. Перевіряє валідність полів `worktree`, `auto` та `requireRoot` у `main.json` кожного скіла.
 
 ## Поведінка
 
-1. Перевірка поля worktree
-2. Перевірка поля auto
-3. Перевірка поля requireRoot
-4. Перевірка суперечності between worktree та requireRoot
+1. Перевіряє наявність каталогу `npm/skills` у поточному робочому каталозі. Якщо каталог відсутній, операція завершується успішно.
+2. Ітерує по всіх підкаталогах у `npm/skills`.
+3. Для кожного підкаталогу виконується перевірка метаданих скіла:
+    а. Перевіряється наявність файлу `auto.md` у каталозі скіла. Якщо він присутній, це вважається порушенням.
+    б. Зчитується вміст `main.json` скіла. Якщо файл відсутній або невалідний, перевірка для цього скіла припиняється.
+    в. Виконується перевірка полів `main.json` скіла:
+        i. `worktree` має бути булевим значенням.
+        ii. Якщо поле `auto` визначене, його вміст має бути розпізнаним як "завжди" або непорожній масив правил.
+        iii. `requireRoot` має бути булевим значенням, якщо визначений.
+        iv. Якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, це вважається порушенням.
+    г. Якщо всі поля `main.json` валідні, це вважається успішним результатом для скіла.
+4. Після перевірки всіх скілів повертається код виходу, що відображає загальний статус (0 — успіх, 1 — порушення).
 
 ## Публічний API
 
-check — Валідує всі `npm/skills/<id>/meta.json`.
+check — перевіряє відповідність усіх файлів `meta.json` у каталозі `npm/skills/<id>/` заданим критеріям.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/js/rule_meta.mjs

@@ -17,11 +17,11 @@ function checkAutoField(id, raw, reporter) {
   if (raw.auto === undefined) return true
   const spec = parseRuleAutoSpec(raw.auto)
   if (spec === null) {
-    reporter.fail(`rules/${id}: meta.json.auto нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})`)
+    reporter.fail(`rules/${id}: main.json.auto нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})`)
     return false
   }
   if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
-    reporter.fail(`rules/${id}: невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
+    reporter.fail(`rules/${id}: main.json — невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
     return false
   }
   return true
@@ -38,7 +38,7 @@ function checkAutoField(id, raw, reporter) {
 function checkLintField(id, ruleDir, raw, reporter) {
   if (raw.lint === undefined) return true
   if (parseRuleLintSpec(raw.lint) === null) {
-    reporter.fail(`rules/${id}: meta.json.lint нерозпізнане (очікується "per-file"|"full")`)
+    reporter.fail(`rules/${id}: main.json.lint нерозпізнане (очікується "per-file"|"full")`)
     return false
   }
   const mainPath = join(ruleDir, 'main.mjs')
@@ -63,19 +63,19 @@ function checkRule(id, ruleDir, reporter) {
   let ruleOk = true
 
   if (existsSync(join(ruleDir, 'auto.md'))) {
-    reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+    reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у main.json)`)
     ruleOk = false
   }
 
-  // Канон (scripts.mdc): {rule}.mdc — ОБОВ'ЯЗКОВИЙ у кожному npm/rules/<id>/.
-  if (!existsSync(join(ruleDir, `${id}.mdc`))) {
-    reporter.fail(`rules/${id}: відсутній ${id}.mdc — обов'язковий (scripts.mdc)`)
+  // Канон (scripts.mdc): main.mdc — ОБОВ'ЯЗКОВИЙ у кожному npm/rules/<id>/.
+  if (!existsSync(join(ruleDir, 'main.mdc'))) {
+    reporter.fail(`rules/${id}: відсутній main.mdc — обов'язковий (scripts.mdc)`)
     ruleOk = false
   }
 
   const raw = readRuleMetaRaw(ruleDir)
   if (!raw) {
-    reporter.fail(`rules/${id}: відсутній або невалідний meta.json`)
+    reporter.fail(`rules/${id}: відсутній або невалідний main.json`)
     return
   }
 
@@ -83,7 +83,7 @@ function checkRule(id, ruleDir, reporter) {
   if (!checkLintField(id, ruleDir, raw, reporter)) ruleOk = false
 
   if (ruleOk) {
-    reporter.pass(`rules/${id}: meta.json валідний`)
+    reporter.pass(`rules/${id}: main.json валідний`)
   }
 }