@nitra/cursor 12.8.2 → 12.8.4

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/gha-workflow.mjs

@@ -1,7 +1,7 @@
 /**
  * Допоміжні функції для аналізу GitHub Actions workflow (`.yml`) після структурного розбору YAML.
  *
- * Використовується в check-ga, check-js, check-text, check-style-lint, check-npm-module замість
+ * Використовується в check-ga, check-js, check-text, check-style, check-npm-module замість
  * пошуку підрядків у сирому тексті там, де важливі лише значення `uses:` та `run:` кроків.
  *
  * Для `run:` також виявляється shell-продовження рядка через `\\` перед переносом (антипатерн у ga.mdc).

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