@nitra/cursor 12.8.3 → 12.8.4

package/scripts/lib/docs/index.md

@@ -6,40 +6,40 @@ resource: npm/scripts/lib/
 
 # npm/scripts/lib
 
-| Файл                                                                        | Тип       |
-| --------------------------------------------------------------------------- | --------- |
-| [assert-project-root.mjs](assert-project-root.md)                           | JS Module |
-| [changed-files.mjs](changed-files.md)                                       | JS Module |
-| [check-mdc-template-refs.mjs](check-mdc-template-refs.md)                   | JS Module |
-| [check-reporter.mjs](check-reporter.md)                                     | JS Module |
-| [diff-added-lines.mjs](diff-added-lines.md)                                 | JS Module |
+| Файл | Тип |
+|---|---|
+| [assert-project-root.mjs](assert-project-root.md) | JS Module |
+| [changed-files.mjs](changed-files.md) | JS Module |
+| [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
+| [check-reporter.mjs](check-reporter.md) | JS Module |
+| [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
 | [discover-check-rules-from-cursor.mjs](discover-check-rules-from-cursor.md) | JS Module |
-| [discover-checkable-rules.mjs](discover-checkable-rules.md)                 | JS Module |
-| [ensure-tool.mjs](ensure-tool.md)                                           | JS Module |
-| [generated-markdown.mjs](generated-markdown.md)                             | JS Module |
-| [gha-workflow.mjs](gha-workflow.md)                                         | JS Module |
-| [inline-template-links.mjs](inline-template-links.md)                       | JS Module |
-| [list-project-rules-mdc.mjs](list-project-rules-mdc.md)                     | JS Module |
-| [list-rule-ids.mjs](list-rule-ids.md)                                       | JS Module |
-| [load-cursor-config.mjs](load-cursor-config.md)                             | JS Module |
-| [mirror-parity.mjs](mirror-parity.md)                                       | JS Module |
-| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md)               | JS Module |
-| [resolve-target-files.mjs](resolve-target-files.md)                         | JS Module |
-| [root-notice.mjs](root-notice.md)                                           | JS Module |
-| [rule-meta-helpers.mjs](rule-meta-helpers.md)                               | JS Module |
-| [rule-meta.mjs](rule-meta.md)                                               | JS Module |
-| [rule-predicates.mjs](rule-predicates.md)                                   | JS Module |
-| [run-conftest-batch.mjs](run-conftest-batch.md)                             | JS Module |
-| [run-lint-step.mjs](run-lint-step.md)                                       | JS Module |
-| [run-lint.mjs](run-lint.md)                                                 | JS Module |
-| [run-rule-cli.mjs](run-rule-cli.md)                                         | JS Module |
-| [run-rule.mjs](run-rule.md)                                                 | JS Module |
-| [run-standard-lint.mjs](run-standard-lint.md)                               | JS Module |
-| [run-standard-rule.mjs](run-standard-rule.md)                               | JS Module |
-| [skill-meta.mjs](skill-meta.md)                                             | JS Module |
-| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md)                   | JS Module |
-| [template.mjs](template.md)                                                 | JS Module |
-| [timing-summary.mjs](timing-summary.md)                                     | JS Module |
-| [workspaces.mjs](workspaces.md)                                             | JS Module |
-| [worktree-notice.mjs](worktree-notice.md)                                   | JS Module |
-| [worktree.mjs](worktree.md)                                                 | JS Module |
+| [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
+| [ensure-tool.mjs](ensure-tool.md) | JS Module |
+| [generated-markdown.mjs](generated-markdown.md) | JS Module |
+| [gha-workflow.mjs](gha-workflow.md) | JS Module |
+| [inline-template-links.mjs](inline-template-links.md) | JS Module |
+| [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
+| [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
+| [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
+| [mirror-parity.mjs](mirror-parity.md) | JS Module |
+| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
+| [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
+| [root-notice.mjs](root-notice.md) | JS Module |
+| [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
+| [rule-meta.mjs](rule-meta.md) | JS Module |
+| [rule-predicates.mjs](rule-predicates.md) | JS Module |
+| [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
+| [run-lint-step.mjs](run-lint-step.md) | JS Module |
+| [run-lint.mjs](run-lint.md) | JS Module |
+| [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
+| [run-rule.mjs](run-rule.md) | JS Module |
+| [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
+| [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
+| [skill-meta.mjs](skill-meta.md) | JS Module |
+| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
+| [template.mjs](template.md) | JS Module |
+| [timing-summary.mjs](timing-summary.md) | JS Module |
+| [workspaces.mjs](workspaces.md) | JS Module |
+| [worktree-notice.mjs](worktree-notice.md) | JS Module |
+| [worktree.mjs](worktree.md) | JS Module |

package/scripts/lib/docs/mirror-parity.md

@@ -3,171 +3,32 @@ type: JS Module
 title: mirror-parity.mjs
 resource: npm/scripts/lib/mirror-parity.mjs
 docgen:
-  crc: 15dc336a
+  crc: d2140a00
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `mirror-parity.mjs` забезпечує перевірку парності (parity) між «дзеркальними» файлами правил Cursor у `.cursor/rules/n-<id>.mdc` та їх канонічними джерелами у `npm/rules/<id>/<id>.mdc`. Ідея така: репозиторій містить два представлення одного й того ж правила:
+## Огляд
 
-- канонічне джерело правила лежить у `npm/rules/<id>/<id>.mdc` (з можливими посиланнями на шаблони у тій самій теці);
-- дзеркало лежить у `.cursor/rules/n-<id>.mdc` і повинно бути результатом застосування трансформу `inlineTemplateLinks` до канону (тобто посилання на шаблони мають бути вставлені «інлайном»).
+Модуль забезпечує паралельність (parity) дзеркал правил. Він порівнює вміст дзеркала `.cursor/rules/n-<id>.mdc` з канонічним вмістом `npm/rules/<id>/<id>.mdc`, який містить вбудовані шаблони (inlined-шаблони). Це гарантує, що локальні копії правил відповідають централізованим, трансформованим версіям, виявляючи дрейф, що виникає при зміні канонічного `.mdc` без регенерації дзеркала.
 
-Коли канонічний `.mdc` змінюють і забувають регенерувати дзеркало, виникає «дрейф» (drift). Цей модуль:
+## Поведінка
 
-- перелічує керовані дзеркала (ті, для яких знайдено канон);
-- обчислює очікуваний вміст дзеркала через ту саму трансформацію, що і синхронізатор;
-- виявляє ідентифікатори дрейфних правил (де `actual ≠ expected`).
+listManagedMirrors
+Визначає список керованих дзеркал правил, які мають канонічне джерело у `npm/rules`.
 
-Модуль використовується одночасно і як гард у тестах (очікувано `drift === []`), і для разової регенерації дзеркал. Контекст беклогу — адаптація flow #10.
+expectedMirrorContent
+Формує очікуваний вміст дзеркала, застосовуючи трансформацію до канонічного вмісту.
 
-## Експорти / API
+findMirrorDrift
+Виявляє і повертає список ідентифікаторів дзеркал, вміст яких відрізняється від очікуваного канонічного.
 
-Модуль експортує три іменовані функції:
+## Публічний API
 
-- `listManagedMirrors(repoRoot)` — синхронна; повертає опис керованих дзеркал.
-- `expectedMirrorContent(canonicalPath)` — асинхронна (повертає `Promise<string>`); обчислює очікуваний вміст дзеркала.
-- `findMirrorDrift(repoRoot)` — асинхронна; повертає масив id правил із дрейфом, відсортований за зростанням.
+listManagedMirrors — перераховує дзеркала, які мають визначене основне джерело, і ігнорує зовнішні.
+expectedMirrorContent — визначає, яким має бути вміст дзеркала, використовуючи основне джерело з вбудованими шаблонами.
+findMirrorDrift — виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
 
-Жодних дефолтних експортів, побічних ефектів на рівні модуля немає (лише імпорти стандартних модулів і одного локального).
+## Гарантії поведінки
 
-## Функції
-
-### `listManagedMirrors(repoRoot)`
-
-Сигнатура: `function listManagedMirrors(repoRoot: string): { id: string, mirrorPath: string, canonicalPath: string }[]`
-
-Параметри:
-
-- `repoRoot` — абсолютний шлях до кореня репозиторію (директорія, у якій лежать `.cursor/` та `npm/`).
-
-Повертає масив об'єктів-описів дзеркал, де:
-
-- `id` — ідентифікатор правила без префіксу `n-` і без розширення `.mdc` (наприклад, для файлу `n-bun.mdc` → `bun`);
-- `mirrorPath` — абсолютний шлях до файлу дзеркала всередині `.cursor/rules/`;
-- `canonicalPath` — абсолютний шлях до канонічного `.mdc` всередині `npm/rules/<id>/`.
-
-Алгоритм:
-
-1. Будує шлях до `.cursor/rules`.
-2. Якщо такої директорії не існує (`existsSync` false) — повертає порожній масив (раннє повернення, безпечне для свіжих репо).
-3. Зчитує перелік файлів директорії синхронно (`readdirSync`).
-4. Фільтрує файли: повинні починатися з префіксу `'n-'` (константа `MIRROR_PREFIX`) і завершуватися розширенням `'.mdc'` (константа `MDC_EXT`).
-5. Мапить кожен файл у об'єкт із обчисленими шляхами: `id` отримується вирізанням префіксу і розширення (`f.slice(MIRROR_PREFIX.length, -MDC_EXT.length)`).
-6. Залишає лише ті записи, для яких реально існує канонічне джерело `canonicalPath` (друга фільтрація через `existsSync`). Це дозволяє пропускати «зовнішні» дзеркала, які не мають канону в монорепо.
-
-Side effects: лише читання директорії з диску (синхронні `existsSync`, `readdirSync`). Жодних записів, мережевих викликів, мутацій глобального стану.
-
-Помилки: якщо файлова система кине помилку під час `readdirSync` (наприклад, права доступу) — вона прокинеться вгору; для типового сценарію відсутності директорії `.cursor/rules` функція не падає (гард через `existsSync`).
-
-### `expectedMirrorContent(canonicalPath)`
-
-Сигнатура: `function expectedMirrorContent(canonicalPath: string): Promise<string>`
-
-Параметри:
-
-- `canonicalPath` — абсолютний шлях до канонічного `.mdc`-файлу (`npm/rules/<id>/<id>.mdc`).
-
-Повертає `Promise<string>` — очікуваний (нормалізований) текст дзеркала після інлайнінгу шаблонів. Хоча сама функція не використовує `async`/`await`, її результат типізовано як `Promise`, оскільки делегує виклик до `inlineTemplateLinks`, яка є асинхронною (її результат може бути thenable). Це означає, що споживач має `await`-нути повернене значення.
-
-Алгоритм:
-
-1. Синхронно зчитує вміст канонічного файлу як UTF-8 (`readFileSync(canonicalPath, 'utf8')`).
-2. Викликає `inlineTemplateLinks(content, dirname(canonicalPath))`, передаючи прочитаний текст та теку канону як base для розв'язання шляхів до шаблонів.
-3. Повертає результат трансформації.
-
-Side effects: одне читання з диску. Подальша поведінка щодо шаблонів інкапсульована в `inlineTemplateLinks` (див. її документацію). Контракт: цей же самий трансформ застосовує синк, тому очікуваний вміст детермінований по канону.
-
-Помилки: якщо файл за `canonicalPath` не існує або недоступний — `readFileSync` кине помилку. Викличні сторони мають гарантувати існування (`listManagedMirrors` уже фільтрує неіснуючі канони).
-
-### `findMirrorDrift(repoRoot)`
-
-Сигнатура: `async function findMirrorDrift(repoRoot: string): Promise<string[]>`
-
-Параметри:
-
-- `repoRoot` — абсолютний шлях до кореня репозиторію.
-
-Повертає `Promise<string[]>` — відсортований за зростанням масив `id` правил, де дзеркало розійшлося з очікуваним вмістом.
-
-Алгоритм:
-
-1. Заводить порожній масив `drift`.
-2. Послідовно (через `for...of`) обходить усі керовані дзеркала, отримані з `listManagedMirrors(repoRoot)`.
-3. Для кожного дзеркала `m`:
-   - `await`-ить очікуваний вміст через `expectedMirrorContent(m.canonicalPath)`;
-   - синхронно зчитує фактичний вміст файлу дзеркала `readFileSync(m.mirrorPath, 'utf8')`;
-   - якщо стрічки не дорівнюють — додає `m.id` до `drift`.
-4. Повертає `drift.sort()` (лексикографічне сортування).
-
-Side effects: тільки читання з диску. Не записує жодних файлів, не пише в лог.
-
-Зауваження щодо порівняння: рівність стрічок є точною (строге `!==` по UTF-8 тексту). Будь-яка різниця в пробілах, символах кінця рядка чи порядку інлайнених шаблонів буде розцінена як дрейф.
-
-## Залежності
-
-Стандартна бібліотека Node.js:
-
-- `node:fs` — `existsSync`, `readdirSync`, `readFileSync`. Усі виклики синхронні. Імпорт зроблено через `node:`-префікс для явної прив'язки до built-in модуля.
-- `node:path` — `dirname`, `join`. Використовуються для безпечного складання абсолютних шляхів і отримання батьківської теки канону.
-
-Локальні модулі:
-
-- `./inline-template-links.mjs` — імпорт іменованої функції `inlineTemplateLinks(content, baseDir)`. Це той самий трансформ, що його використовує синк дзеркал; саме завдяки спільному використанню досягається консистентність між «гардом дрейфу» і «генератором дзеркал».
-
-Зовнішніх npm-залежностей немає.
-
-Константи на рівні модуля:
-
-- `MIRROR_PREFIX = 'n-'` — префікс імені файлів дзеркал.
-- `MDC_EXT = '.mdc'` — розширення файлів правил Cursor.
-
-## Потік виконання / Використання
-
-Типові сценарії використання модуля:
-
-1. Тест-гард парності (CI). Споживач передає корінь репо й перевіряє, що дрейф порожній:
-
-   ```js
-   import { findMirrorDrift } from './mirror-parity.mjs'
-
-   const drift = await findMirrorDrift(repoRoot)
-   if (drift.length) {
-     throw new Error(`Mirror drift detected for: ${drift.join(', ')}`)
-   }
-   ```
-
-2. Разова регенерація дзеркал. Споживач отримує список керованих дзеркал і для кожного перезаписує файл дзеркала очікуваним вмістом:
-
-   ```js
-   import { writeFileSync } from 'node:fs'
-   import { listManagedMirrors, expectedMirrorContent } from './mirror-parity.mjs'
-
-   for (const m of listManagedMirrors(repoRoot)) {
-     const expected = await expectedMirrorContent(m.canonicalPath)
-     writeFileSync(m.mirrorPath, expected)
-   }
-   ```
-
-   (Сам модуль `mirror-parity.mjs` записів не виконує — це задача викличного скрипта.)
-
-Внутрішній потік виконання `findMirrorDrift`:
-
-1. Виклик `listManagedMirrors(repoRoot)`:
-   - перевірка існування `.cursor/rules`;
-   - читання списку файлів;
-   - фільтрація за префіксом `n-` і розширенням `.mdc`;
-   - обчислення `id`, `mirrorPath`, `canonicalPath`;
-   - відкидання дзеркал без канону.
-2. Послідовний обхід отриманих описів:
-   - читання канону → `inlineTemplateLinks` → очікуваний текст;
-   - читання дзеркала → порівняння;
-   - накопичення id з дрейфом.
-3. Сортування результату та повернення.
-
-Контрактна гарантія: якщо синк використовує ту ж саму функцію `inlineTemplateLinks` для генерації дзеркал, то регенерація закриває будь-який дрейф, виявлений `findMirrorDrift`. Якщо дрейф виявлено — він завжди вказує на людську помилку (зміна канону без регенерації) або на розбіжність версій трансформу.
-
-Обмеження:
-
-- Обхід послідовний (без `Promise.all`) — простіший контракт по помилках, але повільніший на великих наборах правил. Зважаючи на типову кількість правил у `.cursor/rules`, це не критично.
-- Усі читання файлів синхронні, попри асинхронну сигнатуру `findMirrorDrift` — асинхронність зумовлена тільки інтерфейсом `inlineTemplateLinks`.
-- Префікс `n-` зашитий константою — додавання інших префіксів дзеркал вимагатиме зміни модуля.
-- Зовнішні дзеркала (без канону в `npm/rules/<id>/`) автоматично пропускаються; модуль не повідомляє про них окремо.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/rule-meta.md

@@ -3,36 +3,33 @@ type: JS Module
 title: rule-meta.mjs
 resource: npm/scripts/lib/rule-meta.mjs
 docgen:
-  crc: fa5ca866
+  crc: 36aea8cb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл парсує метадані правил npm/rules/<id>/meta.json для автоматичного виявлення проблемних місць у коді. Він визначає, коли правило має бути активним, використовуючи різні специфікації, такі як завжди-ввімкнене правило, правило, яке активується після виявлення залежностей, або правило, яке активується на основі glob-шаблонів чи незводимих предикатів. Це дозволяє системі динамічно визначати та застосовувати правила, не потребуючи явного налаштування.
+## Огляд
+
+Парсер інтерпретує метадані правил, що знаходяться у `npm/rules/<id>/meta.json`. Він реалізує data-driven логіку для визначення умов активації кожного детектора. Специфікації активації (`auto`) нормалізуються на основі вмісту `meta.json`, підтримуючи чотири типи: константа `RULE_ALWAYS` ("завжди"), залежності від інших правил, шаблони за допомогою `glob`, або незводимі предикати. Парсер не виконує операцій запису у файлову систему чи бази даних і забезпечує безпечну роботу, перехоплюючи помилки.
 
 ## Поведінка
 
-`RULE_ALWAYS`: визначає літерал для активації правила "завжди".
-`parseRuleAutoSpec`: нормалізує значення `meta.json.auto` у дискриміновану форму.
-`parseRuleLintPhase`: нормалізує значення `meta.json.lint` у фазу lint.
-`readRuleMetaRaw`: читає та парсить `meta.json` одного правила, повертаючи об’єкт або `null`.
+RULE_ALWAYS — константа, що позначає безумовну активацію правила.
+parseRuleAutoSpec — Нормалізує значення поля `auto` з метаданих правила у дискриміновану специфікацію активації.
+parseRuleLintSpec — Нормалізує значення поля `lint` з метаданих правила у специфікацію області застосування детектора.
+readRuleMetaRaw — Читає та парсить вміст `main.json` з каталогу правила, повертаючи його як об'єкт або `null` у разі помилки чи відсутності файлу.
 
 ## Публічний API
 
-- RULE_ALWAYS — Активує правило.
-- parseRuleAutoSpec — Перетворює значення `meta.json.auto` на конкретну опцію.
-- parseRuleLintPhase — Перетворює значення `meta.json.lint` на фазу lint.
-- readRuleMetaRaw — Зчитує та аналізує файл `meta.json` правила.
+RULE_ALWAYS — константа, що вказує на безумовну активацію.
+parseRuleAutoSpec — перетворює налаштування автоматичного визначення правил з `meta.json` у структурований формат.
+parseRuleLintSpec — перетворює налаштування лінтування з `meta.json` у визначення області дії детектора.
+"per-file" — визначає, що детектор працює з окремими зміненими файлами (порівняння змін з оригіналом).
+"full" — вказує на повний, нероздільний аналіз між усіма файлами (активується лише при використанні прапорця `--full` або в CI).
+readRuleMetaRaw — зчитує та обробляє метадані одного правила з файлу `meta.json`.
 
 ## Гарантії поведінки
 
-- `RULE_ALWAYS` повертає `true` якщо правило активне.
-- `parseRuleAutoSpec` повертає `true` якщо специфікація правила успішно розібрана.
-- `parseRuleAutoSpec` повертає `false` якщо специфікація правила не може бути розібрана.
-- `parseRuleLintPhase` повертає `true` якщо правило успішно розібрано на етапі linting.
-- `parseRuleLintPhase` повертає `false` якщо правило не може бути розібрано на етапі linting.
-- `readRuleMetaRaw` повертає `true` якщо метадані правила успішно прочитані.
-- `readRuleMetaRaw` повертає `false` якщо метадані правила не можуть бути прочитані.
-- У разі невдачі, функція повертає `false` або `null`.
-- Функції не кидають винятків.
-- Немає кешування.
-- Немає гарантій щодо стану файлів або каталогів.
-- Поля `worktree` правила не використовуються.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/docs/run-rule.md

@@ -3,27 +3,27 @@ type: JS Module
 title: run-rule.mjs
 resource: npm/scripts/lib/run-rule.mjs
 docgen:
-  crc: 27060842
-  score: 95
+  crc: 7d0585e1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-Файл слугує оркестратором правила. Він координує виконання перевірок, включаючи перевірку гейту, JS-концернів та policy-концернів.
+## Огляд
+
+Файл оркеструє виконання одного правила під CLI `fix`. Він послідовно застосовує гейт `applies` з `js/applies.mjs` для визначення придатності правила. Якщо гейт повертає `false`, правило не застосовується. Далі виконуються JS-концерни та Policy-концерни в алфавітному порядку. Резолвер `resolveTargetFiles` ділить кеш між концернами. Кожен concern створює власний репортер, а їхні exit-коди OR-уються в єдиний контракт, що забезпечує 0/1 результат для правила. Оркестратор спирається на конфігурації `target.json` та `.n-cursor.json`.
 
 ## Поведінка
 
-runTemplateSubsetConcern
-Перевіряє відповідність фактичного файлу канонічному шаблону.
+runTemplateSubsetConcern виконує перевірку концерну, де канон визначається сніпетом у `target.json`, звіряючи його з актуальними файлами-таргетами.
 
-runRule
-Оркеструє виконання правила, включаючи перевірку гейту, JS-концернів та policy-концернів.
+runRule оркеструє виконання одного правила, послідовно застосовуючи applies-гейт, виконуючи JS-концерни та запускаючи policy-концерни, а також перевіряючи відсутність markdown-посилань.
 
 ## Публічний API
 
-- runTemplateSubsetConcern — Snippet-driven перевірка концерну (`target.json:"check":"template"`): звіряє канон з фактичним файлом за допомогою глибокого підмножинного перевірки. Усі канонічні поля/елементи обов'язкові, зайві дозволені. Масиви співпадають за наявністю (незалежно від порядку). Зміна сніпета негайно впливає на примусовість.
-- runRule — Запускає одне правило: applies-гейт → JS-концерни → policy-концерни.
+runTemplateSubsetConcern — Порівнює фактичний файл із канонічним шаблоном (з `target.json`) для перевірки, чи всі обов'язкові елементи присутні, дозволяючи додаткові.
+runRule — Виконує окреме правило, яке проходить через перевірки застосовності, JavaScript-концерни та політики.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

package/scripts/lib/docs/skill-meta.md

@@ -3,33 +3,31 @@ type: JS Module
 title: skill-meta.mjs
 resource: npm/scripts/lib/skill-meta.mjs
 docgen:
-  crc: 0c638d18
+  crc: c0918db5
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл парсить метадані скілу з файлу `meta.json` та надає інформацію про його конфігурацію. Він служить єдиним джерелом правди про скіл, замінюючи старий `auto.md`, і використовується для визначення, чи потрібно запускати скіл в окремому worktree, чи з кореня репозиторію. Це забезпечує узгодженість даних про скіли та полегшує їх використання в інших частинах системи.
+## Огляд
+
+Спільний парсер метаданих скіла, що зчитує дані з `npm/skills/<id>/meta.json`. Він є єдиним джерелом правди для конфігурації скілів, визначаючи умови автоактивації (через поле `auto`, де `SKILL_ALWAYS` означає "завжди"), чи виконувати скіл в окремому git-worktree (`worktree`), та чи вимагає скіл запуску з кореня репозиторію (`requireRoot`). Модуль надає механізми для парсингу цих метаданих, перевірки вимог до кореня та читання сирих даних. Він працює в режимі fail-safe, перехоплюючи помилки та повертаючи порожнє значення замість винятків.
 
 ## Поведінка
 
-SKILL_ALWAYS: визначає літерал для безумовної автоактивації.
-parseSkillAutoSpec: перетворює значення `auto` з `meta.json` у об’єкт `SkillAutoSpec`.
-skillRequiresRoot: визначає, чи вимагає скіл запуску з кореня репо.
-readSkillMetaRaw: читає та парсить `meta.json` одного скіла, повертаючи розпарсений об’єкт або `null`.
+SKILL_ALWAYS — надає літерал для безумовної автоактивації скіла.
+parseSkillAutoSpec — перетворює значення поля `auto` з метаданих скіла у специфікацію автоактивації.
+skillRequiresRoot — визначає, чи вимагає скіл запуску з кореня репозиторію, виходячи з метаданих.
+readSkillMetaRaw — читає та парсить файл `main.json` у каталозі скіла, повертаючи його вміст або `null` у разі помилки.
 
 ## Публічний API
 
-- SKILL_ALWAYS — Активує скіл завжди.
-- parseSkillAutoSpec — Перетворює специфікацію авто-скілу з JSON.
-- skillRequiresRoot — Перевіряє, чи потрібен скілу доступ до кореневої директорії.
-- readSkillMetaRaw — Зчитує та аналізує метадані скілу з файлу JSON.
+SKILL_ALWAYS — маркер, що вказує на безумовну активацію
+parseSkillAutoSpec — витягує налаштування автоматичного запуску з `meta.json`
+skillRequiresRoot — визначає, чи потрібен запуск скіла з кореня репозиторію
+readSkillMetaRaw — зчитує та обробляє метадані окремого скіла з `meta.json`
 
 ## Гарантії поведінки
 
-- Повертає `false` якщо не вдається розібрати `meta.json`.
-- Повертає `null` якщо не вдається визначити `auto.spec`.
-- `auto.spec` завжди є масивом id правил, якщо `auto.spec` визначено.
-- `worktree` має значення `true` лише для скілів, які потребують окремого git-worktree.
-- `requireRoot` має значення `true` лише для скілів, які мутують в CWD без worktree-ізоляції.
-- Якщо `worktree` має значення `true`, поле `requireRoot` не використовується.
-- Не використовує кеш.
-- Не кидає винятків.
-- Гарантує, що `meta.json` є єдиним джерелом правди для скілу.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/docs/timing-summary.md

@@ -3,24 +3,24 @@ type: JS Module
 title: timing-summary.mjs
 resource: npm/scripts/lib/timing-summary.mjs
 docgen:
-  crc: ee74c1cd
+  crc: 47660e16
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Формує таблицю-резюме часу виконання для оркестратора `fix` або `lint`. Таблиця використовується після прогону всіх правил перевірки (`runFixCommand` у `bin/n-cursor.js`) або після прогону скриптів лінтингу (`runLintCli` у `scripts/lib/run-lint-cli.mjs`), які визначаються у `package.json`. Звіт містить деталі часу виконання для кожного елемента у форматі `<ціла>.<десята>s`, а маркер `❌` на рядку вказує на невдачу (`ok === false`).
+Формує рядок, що відображає тривалість у форматі `<ціла>.<десята>s`, забезпечуючи стабільну одиницю вимірювання для всіх інтервалів. Генерує звіт про час виконання для orchestrator `fix` / `lint`, який включає деталі кожного вимірювання та загальний час. Звіт містить маркер `❌` на рядку, якщо відповідний вимірник не пройшов успішно. Дані для звітів отримуються з `package.json` та використовуються у точках виклику `runFixCommand` у `bin/n-cursor.js` та `runLintCli` у `scripts/lib/run-lint-cli.mjs`. Функція є чистою, не виконує I/O, і повертає готовий рядок з фінальним `\n`, друк якого здійснюється на стороні виклику.
 
 ## Поведінка
 
-formatDurationMs перетворює тривалість у мілісекундах у рядок формату `<ціла>.<десята>s`.
-formatTimingSummary генерує багаторядковий текст таблиці-резюме часу виконання на основі наданого заголовка та списку записів про час.
+formatDurationMs форматує тривалість у мілісекундах як рядок у форматі `<ціла>.<десята>s`.
+formatTimingSummary генерує багаторядковий текстовий звіт про час виконання, включаючи деталі кожного запису та загальний час.
 
 ## Публічний API
 
-⏱ formatDurationMs: Перетворює мілісекунди на формат `<sec>.<десята>s`, використовуючи округлення вниз.
-⏱ formatTimingSummary: Генерує багаторядковий вивід у форматі таблиці-резюме для стандартного виводу.
+⏱ formatDurationMs: Перетворює мілісекунди у формат `<sec>.<десята>s`, використовуючи округлення вниз.
+⏱ formatTimingSummary: Генерує багаторядковий вивід таблиці-резюме часу виконання.
 
 ## Гарантії поведінки
 

package/scripts/lib/mirror-parity.mjs

@@ -30,7 +30,7 @@ export function listManagedMirrors(repoRoot) {
       return {
         id,
         mirrorPath: join(rulesDir, f),
-        canonicalPath: join(repoRoot, 'npm/rules', id, `${id}${MDC_EXT}`)
+        canonicalPath: join(repoRoot, 'npm/rules', id, `main${MDC_EXT}`)
       }
     })
     .filter(m => existsSync(m.canonicalPath))

package/scripts/lib/rule-meta.mjs

@@ -70,7 +70,7 @@ export function parseRuleLintSpec(value) {
  * @returns {Record<string, unknown> | null} обʼєкт або `null` (немає файлу / невалідний JSON / не-обʼєкт)
  */
 export function readRuleMetaRaw(ruleDir) {
-  const metaPath = join(ruleDir, 'meta.json')
+  const metaPath = join(ruleDir, 'main.json')
   if (!existsSync(metaPath)) return null
   try {
     const parsed = JSON.parse(readFileSync(metaPath, 'utf8'))

package/scripts/lib/run-rule.mjs

@@ -81,7 +81,7 @@ export async function runTemplateSubsetConcern(concernAbsDir, target, files, rul
   for (const file of files) {
     const rel = relative(process.cwd(), file) || file
     const actual = await parseByExt(file)
-    const opts = { targetPath: rel, source: `${ruleId}.mdc` }
+    const opts = { targetPath: rel, source: 'main.mdc' }
     const violations = [
       ...(typeof data.snippet === 'string'
         ? checkTextSubset(actual, data.snippet, opts)
@@ -118,7 +118,7 @@ async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache)
     if (target.files.required && target.files.single) {
       const msg =
         target.missingMessage ??
-        `${target.files.single} не існує — створи згідно ${ruleId}.mdc (${ruleId}.${concernName})`
+        `${target.files.single} не існує — створи згідно main.mdc (${ruleId}.${concernName})`
       reporter.fail(msg)
     }
     return reporter.getExitCode()
@@ -182,11 +182,11 @@ export async function runRule(rule, bundledRulesDir, walkCache) {
   }
 
   const ruleDir = join(bundledRulesDir, rule.id)
-  const missing = await findMissingMdcRefs(ruleDir, rule.id)
+  const missing = await findMissingMdcRefs(ruleDir)
   if (missing.length > 0) {
     const reporter = createCheckReporter()
     for (const rel of missing) {
-      reporter.fail(`${rule.id}.mdc: відсутнє markdown-посилання на template-файл ${rel}`)
+      reporter.fail(`main.mdc: відсутнє markdown-посилання на template-файл ${rel}`)
     }
     if (reporter.getExitCode() !== 0) totalCode = 1
   }

package/scripts/lib/skill-meta.mjs

@@ -56,7 +56,7 @@ export function skillRequiresRoot(meta) {
  * @returns {Record<string, unknown> | null} розпарсений обʼєкт або `null` (немає файлу / невалідний JSON / не-обʼєкт)
  */
 export function readSkillMetaRaw(skillDir) {
-  const metaPath = join(skillDir, 'meta.json')
+  const metaPath = join(skillDir, 'main.json')
   if (!existsSync(metaPath)) return null
   try {
     const parsed = JSON.parse(readFileSync(metaPath, 'utf8'))

package/scripts/utils/docs/index.md

@@ -6,18 +6,18 @@ resource: npm/scripts/utils/
 
 # npm/scripts/utils
 
-| Файл                                                        | Тип       |
-| ----------------------------------------------------------- | --------- |
-| [ast-scan-utils.mjs](ast-scan-utils.md)                     | JS Module |
+| Файл | Тип |
+|---|---|
+| [ast-scan-utils.mjs](ast-scan-utils.md) | JS Module |
 | [ensure-gitignore-entries.mjs](ensure-gitignore-entries.md) | JS Module |
-| [find-package-json-paths.mjs](find-package-json-paths.md)   | JS Module |
-| [lock-cache-dir.mjs](lock-cache-dir.md)                     | JS Module |
-| [pass.mjs](pass.md)                                         | JS Module |
-| [resolve-cargo-manifest.mjs](resolve-cargo-manifest.md)     | JS Module |
-| [resolve-cmd.mjs](resolve-cmd.md)                           | JS Module |
-| [resolve-js-root.mjs](resolve-js-root.md)                   | JS Module |
-| [test-helpers.mjs](test-helpers.md)                         | JS Module |
-| [walk-cache.mjs](walk-cache.md)                             | JS Module |
-| [walkDir.mjs](walkDir.md)                                   | JS Module |
-| [with-lock.mjs](with-lock.md)                               | JS Module |
-| [worktree-fingerprint.mjs](worktree-fingerprint.md)         | JS Module |
+| [find-package-json-paths.mjs](find-package-json-paths.md) | JS Module |
+| [lock-cache-dir.mjs](lock-cache-dir.md) | JS Module |
+| [pass.mjs](pass.md) | JS Module |
+| [resolve-cargo-manifest.mjs](resolve-cargo-manifest.md) | JS Module |
+| [resolve-cmd.mjs](resolve-cmd.md) | JS Module |
+| [resolve-js-root.mjs](resolve-js-root.md) | JS Module |
+| [test-helpers.mjs](test-helpers.md) | JS Module |
+| [walk-cache.mjs](walk-cache.md) | JS Module |
+| [walkDir.mjs](walkDir.md) | JS Module |
+| [with-lock.mjs](with-lock.md) | JS Module |
+| [worktree-fingerprint.mjs](worktree-fingerprint.md) | JS Module |

package/scripts/utils/docs/resolve-js-root.md

@@ -3,27 +3,26 @@ type: JS Module
 title: resolve-js-root.mjs
 resource: npm/scripts/utils/resolve-js-root.mjs
 docgen:
-  crc: 2c2b9f11
+  crc: 99e5a8a4
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл визначає кореневий JavaScript-файл проєкту, необхідний для запуску інструментів аналізу коду. Він використовується як у великих проєктах з декількома workspace-ами, так і в окремих пакетах, забезпечуючи єдине місце для визначення кореневого розташування. Це спрощує інтеграцію з інструментами coverage та тестування.
+## Огляд
+
+Визначає корінь JS-коду для проєктів, використовуючи `package.json` та `.n-cursor.json` як конфігураційні файли. Функція `resolveJsRoot` знаходить перший workspace (з підтримкою glob-патернів типу `cf/*`) для workspace-проєктів або корінь поточної директорії для single-package. Функція `resolveAllJsRoots` знаходить усі відповідні шляхи. Код свідомо ігнорує шляхи `.git` та `node_modules`. Ця утиліта є спільною для coverage-провайдера JS та test-концерну stryker_config (DRY).
 
 ## Поведінка
 
-resolveJsRoot: повертає абсолютний шлях до першого JS-кореня проєкту.
-resolveAllJsRoots: повертає масив абсолютних шляхів до всіх JS-коренів проєкту, враховуючи glob-патерни з `workspaces` у кореневому `package.json`. Якщо JS-коренів немає, повертає абсолютний шлях до кореневого каталогу.
+resolveJsRoot повертає абсолютний шлях до першого JS-кореня проєкту, якщо він існує, або null, якщо кореневий package.json відсутній.
+resolveAllJsRoots повертає масив абсолютних шляхів до всіх JS-коренів проєкту, враховуючи визначення `workspaces` у кореневому package.json, ігноруючи каталоги `.git` та `node_modules`.
 
 ## Публічний API
 
-- resolveJsRoot — Знаходить кореневий JS-файл проєкту.
-- resolveAllJsRoots — Знаходить всі кореневі JS-файли проєкту. Включає всі workspace-файли та їхні `package.json`, використовуючи glob-патерни. Для single-package повертає поточну директорію.
+resolveJsRoot — знаходить кореневий каталог JavaScript-проєкту.
+resolveAllJsRoots — повертає шляхи до коренів усіх JavaScript-проєктів у робочому просторі.
 
 ## Гарантії поведінки
 
-- Повертає `true`, якщо кореневий JS-файл знайдено.
-- Повертає `false`, якщо кореневий JS-файл не знайдено.
-- Повертає `null`, якщо не вдалося визначити кореневий JS-файл.
-- Не обробляє помилки, а повертає `false` або `null`.
-- Ігнорує директорії `.git` та `node_modules`.
-- Не використовує кешування.
-- Не здійснює мережевих запитів.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.