@nitra/cursor 12.7.0 → 12.8.0

package/rules/doc-files/js/docgen-judge-measure.mjs

@@ -64,8 +64,16 @@ function judgeCached(src, doc) {
   const hit = cacheGet(key)
   if (hit) return { ...hit, cached: true }
   const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
-  const raw = callLlm([{ role: 'system', content: SYSTEM }, { role: 'user', content: user }], JUDGE_MODEL, { timeoutMs: JUDGE_TIMEOUT, temperature: 0 })
-  const a = raw.indexOf('{'), b = raw.lastIndexOf('}')
+  const raw = callLlm(
+    [
+      { role: 'system', content: SYSTEM },
+      { role: 'user', content: user }
+    ],
+    JUDGE_MODEL,
+    { timeoutMs: JUDGE_TIMEOUT, temperature: 0 }
+  )
+  const a = raw.indexOf('{'),
+    b = raw.lastIndexOf('}')
   if (a === -1 || b === -1) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
   const v = JSON.parse(raw.slice(a, b + 1))
   cacheSet(key, v)
@@ -81,17 +89,34 @@ function main() {
     console.error('Usage: node docgen-judge-measure.mjs <file1> <file2> ...')
     process.exit(2)
   }
-  console.error(`[measure] gen=${GEN_MODEL} judge=${JUDGE_MODEL} threshold=${THRESHOLD} files=${files.length} cache=${CACHE_DIR}`)
+  console.error(
+    `[measure] gen=${GEN_MODEL} judge=${JUDGE_MODEL} threshold=${THRESHOLD} files=${files.length} cache=${CACHE_DIR}`
+  )
 
   const rows = []
   for (const [i, file] of files.entries()) {
     const tag = `(${i + 1}/${files.length}) ${file}`
     let src
-    try { src = readFileSync(file, 'utf8') } catch (error) { console.error(`[skip] ${tag}: read ${error.message}`); continue }
+    try {
+      src = readFileSync(file, 'utf8')
+    } catch (error) {
+      console.error(`[skip] ${tag}: read ${error.message}`)
+      continue
+    }
 
     let gen
-    try { gen = genCached(file, src) } catch (error) { console.error(`[gen-err] ${tag}: ${error.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: error.message.slice(0, 200) }); continue }
-    if (gen.score === null) { console.error(`[unsupported] ${tag}`); rows.push({ file, score: null, unsupported: true }); continue }
+    try {
+      gen = genCached(file, src)
+    } catch (error) {
+      console.error(`[gen-err] ${tag}: ${error.message.slice(0, 120)}`)
+      rows.push({ file, error: 'gen', detail: error.message.slice(0, 200) })
+      continue
+    }
+    if (gen.score === null) {
+      console.error(`[unsupported] ${tag}`)
+      rows.push({ file, score: null, unsupported: true })
+      continue
+    }
 
     const passed = gen.score >= THRESHOLD
     const row = { file, score: gen.score, degraded: gen.degraded, passed, genCached: gen.cached }
@@ -100,9 +125,18 @@ function main() {
     if (passed) {
       try {
         const v = judgeCached(src, gen.md)
-        row.verdict = v.verdict; row.confidence = v.confidence; row.reason = v.reason; row.offending = v.offending; row.judgeCached = v.cached
-        console.error(`  [judge${v.cached ? '*' : ''}] ${v.verdict} (${v.confidence}) — ${(v.reason || '').slice(0, 90)}`)
-      } catch (error) { row.judgeError = error.message.slice(0, 200); console.error(`  [judge-err] ${error.message.slice(0, 120)}`) }
+        row.verdict = v.verdict
+        row.confidence = v.confidence
+        row.reason = v.reason
+        row.offending = v.offending
+        row.judgeCached = v.cached
+        console.error(
+          `  [judge${v.cached ? '*' : ''}] ${v.verdict} (${v.confidence}) — ${(v.reason || '').slice(0, 90)}`
+        )
+      } catch (error) {
+        row.judgeError = error.message.slice(0, 200)
+        console.error(`  [judge-err] ${error.message.slice(0, 120)}`)
+      }
     }
     rows.push(row)
   }
@@ -119,17 +153,26 @@ function main() {
   const report = {
     config: { genModel: GEN_MODEL, judgeModel: JUDGE_MODEL, threshold: THRESHOLD },
     counts: {
-      files: files.length, generated: scored.length,
+      files: files.length,
+      generated: scored.length,
       unsupported: rows.filter(r => r.unsupported).length,
       genErrors: rows.filter(r => r.error === 'gen').length,
       passedDetScorer: scored.filter(r => r.passed).length,
-      judged: M, judgeErrors: rows.filter(r => r.judgeError).length
+      judged: M,
+      judgeErrors: rows.filter(r => r.judgeError).length
     },
-    falsePositiveRate: { // серед PASSED+judged
-      accurate: byVerdict.accurate, generic: byVerdict.generic, inaccurate: byVerdict.inaccurate,
-      badPct: pct(bad), inaccuratePct: pct(byVerdict.inaccurate), genericPct: pct(byVerdict.generic)
+    falsePositiveRate: {
+      // серед PASSED+judged
+      accurate: byVerdict.accurate,
+      generic: byVerdict.generic,
+      inaccurate: byVerdict.inaccurate,
+      badPct: pct(bad),
+      inaccuratePct: pct(byVerdict.inaccurate),
+      genericPct: pct(byVerdict.generic)
     },
-    offenders: passedRows.filter(r => r.verdict !== 'accurate').map(r => ({ file: r.file, score: r.score, verdict: r.verdict, confidence: r.confidence, reason: r.reason })),
+    offenders: passedRows
+      .filter(r => r.verdict !== 'accurate')
+      .map(r => ({ file: r.file, score: r.score, verdict: r.verdict, confidence: r.confidence, reason: r.reason })),
     rows
   }
 
@@ -138,10 +181,16 @@ function main() {
   writeFileSync(out, JSON.stringify(report, null, 2))
 
   console.log('\n===== Q4 MEASUREMENT =====')
-  console.log(`generated: ${report.counts.generated}/${files.length}  (unsupported=${report.counts.unsupported}, gen-errors=${report.counts.genErrors})`)
+  console.log(
+    `generated: ${report.counts.generated}/${files.length}  (unsupported=${report.counts.unsupported}, gen-errors=${report.counts.genErrors})`
+  )
   console.log(`passed det-scorer (score≥${THRESHOLD}): ${report.counts.passedDetScorer}   judged: ${M}`)
-  console.log(`among PASSED+judged → accurate=${byVerdict.accurate} generic=${byVerdict.generic} inaccurate=${byVerdict.inaccurate}`)
-  console.log(`>>> det-scorer FALSE-POSITIVE rate: ${pct(bad)}%  (inaccurate=${pct(byVerdict.inaccurate)}%, generic=${pct(byVerdict.generic)}%)`)
+  console.log(
+    `among PASSED+judged → accurate=${byVerdict.accurate} generic=${byVerdict.generic} inaccurate=${byVerdict.inaccurate}`
+  )
+  console.log(
+    `>>> det-scorer FALSE-POSITIVE rate: ${pct(bad)}%  (inaccurate=${pct(byVerdict.inaccurate)}%, generic=${pct(byVerdict.generic)}%)`
+  )
   console.log(`decision guide: <~5% → don't build gate; >~15% → build (inaccurate-only)`)
   console.log(`report: ${out}`)
 }

package/rules/doc-files/js/docgen-judge.mjs

@@ -58,7 +58,14 @@ export function parseDocVerdict(rawText) {
  */
 export function judgeDoc(src, doc, { model = JUDGE_MODEL, timeoutMs = 120_000 } = {}) {
   const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12_000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
-  const raw = callLlm([{ role: 'system', content: JUDGE_SYSTEM }, { role: 'user', content: user }], model, { timeoutMs, temperature: 0 })
+  const raw = callLlm(
+    [
+      { role: 'system', content: JUDGE_SYSTEM },
+      { role: 'user', content: user }
+    ],
+    model,
+    { timeoutMs, temperature: 0 }
+  )
   return parseDocVerdict(raw)
 }
 

package/rules/doc-files/js/docgen-scan.mjs

@@ -160,7 +160,12 @@ function gitIgnoredPaths(root, relPaths) {
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'ignore'] // git пише «not a git repository» у stderr — глушимо
     })
-    return new Set(out.split('\n').map(s => s.trim()).filter(Boolean))
+    return new Set(
+      out
+        .split('\n')
+        .map(s => s.trim())
+        .filter(Boolean)
+    )
   } catch {
     // exit 1 (жоден не ігнорується) і 128 (не git-репо) → execFileSync кидає; обидва = «не фільтруємо».
     return new Set()
@@ -201,7 +206,10 @@ export function scanForDocFiles(root) {
   }
 
   walk(root)
-  const ignored = gitIgnoredPaths(root, results.map(r => r.sourcePath))
+  const ignored = gitIgnoredPaths(
+    root,
+    results.map(r => r.sourcePath)
+  )
   return ignored.size ? results.filter(r => !ignored.has(r.sourcePath)) : results
 }
 

package/rules/doc-files/js/docs/docgen-crc.md

@@ -3,28 +3,39 @@ type: JS Module
 title: docgen-crc.mjs
 resource: npm/rules/doc-files/js/docgen-crc.mjs
 docgen:
-  crc: cca0a79f
+  crc: 0c277bb7
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.
+## Огляд
+
+Модуль забезпечує роботу з метаданими та оцінкою якості документів. Він дозволяє парсити метадані з Markdown-файлів за допомогою `parseDocFrontmatter`, створювати та заповнювати блоки метаданих за допомогою `buildDocFrontmatter`. Документи можуть бути промарковані за допомогою `stampDoc`. Якість документа оцінюється за допомогою `readDocQuality`, а його актуальність визначається функцією `staleness`, яка використовує `crc32` для перевірки хеш-суми. Модель документа зчитується через `readDocModel`.
 
 ## Поведінка
 
-1. Контрольна сума обчислюється з байтів джерела і записується у машинний frontmatter доки разом зі шляхом джерела; розбіжність суми з поточним джерелом (або відсутність доки) означає застарілість.
-2. Якщо генерація не дотягнула до порогу якості, frontmatter додатково несе оцінку (`score`) і коди проблем (`issues`); коди нормалізуються до YAML-безпечних (без пробілів, обмежена кількість), а старі доки без цих полів лишаються валідними.
-3. Поріг degraded — `70`, override через `N_CURSOR_DOC_FILES_THRESHOLD`.
-4. Перештампування знімає наявний frontmatter і ставить свіжий, не торкаючись тіла документа; якість при цьому передається явно — без неї поля якості зникають.
+QUALITY_THRESHOLD визначає поріг якості, нижче якого дока вважається неякісним.
+crc32 обчислює CRC32 вмісту в hex-форматі.
+parseDocFrontmatter парсить YAML-блок у вмісті md-файлу, виділяючи метадані та тіло.
+buildDocFrontmatter створює OKF-сумісний YAML-блок для доки, включаючи метадані.
+stampDoc замінює або додає свіжий YAML-блок у тіло md-доку, використовуючи дані джерела та оцінку.
+readDocCrc зчитує CRC32 з YAML-блоку md-доки за заданим абсолютним шляхом.
+readDocQuality зчитує оцінку якості (score, issues, retried, judgeModel) з YAML-блоку md-доки за абсолютним шляхом.
+readDocModel зчитує повний ID моделі-генератора з YAML-блоку md-доки за абсолютним шляхом.
+staleness визначає, чи є дока застарілою, порівнюючи CRC джерела з CRC у доці за абсолютними шляхами.
 
 ## Публічний API
 
-- `crc32` — контрольна сума вмісту в hex.
-- `staleness` — стан доки відносно джерела: `missing` / `crc-mismatch` / свіжа.
-- `parseDocFrontmatter` / `buildDocFrontmatter` / `stampDoc` — читання і (пере)штампування машинного блока.
-- `readDocCrc` / `readDocQuality` — точкове читання суми та якості з доки.
-- `QUALITY_THRESHOLD` — чинний поріг degraded.
+QUALITY_THRESHOLD — Визначає рівень якості документа: дока з низьким показником вважається неякісним.
+crc32 — Генерує 32-бітний контрольний сума вмісту у шістнадцятковому форматі.
+parseDocFrontmatter — Витягує метадані з початку документа. Якщо метаданих немає, повертає порожні дані.
+buildDocFrontmatter — Створює блок метаданих, сумісний з OKF, включаючи дані про генерацію документа (CRC, модель, якість).
+stampDoc — Додає метадані до документа, що фіксують його стан.
+readDocCrc — Зчитує контрольний сума з метаданих документа.
+readDocQuality — Зчитує рівень якості, збережений у метаданих документа.
+readDocModel — Зчитує назву моделі, використаної для генерації документа.
+staleness — Визначає, чи є документ актуальним, порівнюючи його з джерелом.
 
 ## Гарантії поведінки
 
-- Сума не залежить від git-стану: rebase, гілки й незакомічені зміни на неї не впливають.
-- Frontmatter — єдиний машинний виняток із правила «чистий Markdown»; тіло доки модуль не редагує.
-- Відсутні поля якості читаються як «не оцінено» (`score: null`), а не як нуль.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/doc-files/js/docs/docgen-extract.md

@@ -3,31 +3,33 @@ type: JS Module
 title: docgen-extract.mjs
 resource: npm/rules/doc-files/js/docgen-extract.mjs
 docgen:
-  crc: a0680e77
+  crc: 369662fe
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Витягує структурований факт-лист з вмісту файлів, аналізуючи їх залежно від мови. Для Rust витягує модульний опис, публічні експорти, локальні символи та класифікує імпорти й поведінкові маркери. Для JavaScript/TypeScript/MJS витягує опис, експортовані елементи з JSDoc, класифікує імпорти та визначає поведінкові маркери. При аналізі ігноруються директорії: .github, .git, node_modules, base/, ua/, .firebase. Звертається до мережі та кешує дані протягом одного прогону.
+## Огляд
+
+Модуль витягує структурований факт-лист з вмісту файлів, звертаючись до мережі. Функція `extractFacts` аналізує вміст файлів, визначаючи публічні експорти, локальні символи та поведінкові маркери для Rust та JavaScript/TypeScript файлів. При цьому ігноруються системні та залежності, включаючи каталоги `.github`, `.git`, `node_modules`, `base/`, `ua/` та `.firebase`. Результати аналізу кешуються протягом одного прогону.
 
 ## Поведінка
 
 1. Витягує факт-лист з вмісту файлу.
 2. Визначає мову файлу за розширенням.
 3. Якщо мова — Rust, виконує аналіз Rust-коду:
-    а. Витягує модульний опис з `//!`.
-    б. Визначає публічні експорти (структури, функції, енуми) на основі `pub` префікса або експозиційних атрибутів.
+    а. Витягує модульний заголовок (`//!`).
+    б. Визначає публічні експорти (структури, функції, класи), виходячи з префіксів `pub` та атрибутів експозиції.
     в. Визначає локальні (приватні) символи, які не є публічними.
-    г. Класифікує імпорти (`std`, зовнішні, внутрішні).
-    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі специфічних Rust-конструкцій.
+    г. Класифікує імпорти (`use`) як стандартні, зовнішні чи внутрішні.
+    д. Визначає поведінкові маркери (наприклад, чи є код лише для читання, чи обробляє помилки).
 4. Якщо мова — JavaScript/TypeScript/MJS, виконує аналіз JS-коду:
-    а. Витягує загальний опис файлу з верхнього блоку коментарів.
-    б. Витягує експортовані функції та класи разом із їхніми JSDoc-описами.
-    в. Класифікує імпорти на стандартні бібліотеки, NPM-пакети та внутрішні модулі.
-    г. Визначає локальні (неекспортовані) функції та класи.
-    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі евристик.
-5. При аналізі JS-коду, свідомо ігнорує шляхи: .github, .git, node_modules, base/, ua/, .firebase.
-6. Повертає структуру фактів, що містить метадані про файл.
+    а. Витягує заголовок файлу.
+    б. Визначає публічні експорти з їхнім JSDoc.
+    в. Класифікує імпорти як стандартні, npm або внутрішні.
+    г. Визначає локальні символи (службові функції).
+    д. Визначає поведінкові маркери (наприклад, чи є код лише для читання, чи звертається до мережі).
+5. Усі аналізи свідомо ігнорують шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.
+6. Повертає структуру фактів, що містить інформацію про файл.
 
 ## Публічний API
 

package/rules/doc-files/js/docs/docgen-files-batch.md

@@ -3,30 +3,30 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: f68c0832
+  crc: 6316eecb
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль керує життєвим циклом документації. Він вибирає цільові документи для оновлення, видаляє непов'язані документи та виконує пакетну генерацію. Модуль забезпечує стійкість роботи, перехоплюючи помилки та не кидаючи винятків назовні. Він також детерміновано оновлює метадані існуючих документів.
+Модуль керує життєвим циклом документації. Він вибирає цілі для оновлення за допомогою `selectTargets`, очищає від неіснуючих джерел за допомогою `purgeOrphanedDocs`, запускає генерацію файлів через `runDocFilesGenCli` та `runDocFilesStampCli`, а також виконує пакетну генерацію за допомогою `runGenerationBatch`. Усі операції виконуються з механізмом перехоплення помилок, що запобігає виникненню винятків назовні.
 
 ## Поведінка
 
-selectTargets фільтрує знайдені файли, вибираючи ті, що застарілі або мають низьку якість і не були спробовані раніше.
-purgeOrphanedDocs видаляє доки, для яких не існує відповідного джерела, і оновлює індекси директорій.
-runDocFilesGenCli ініціює генерацію документації, видаляючи сирітських доків, вибираючи цілі та запускаючи пакетну генерацію.
-runGenerationBatch виконує послідовний прогін цільових файлів, генеруючи документацію та керуючи цим процесом через механізм захисту від збоїв.
-runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих доків, додаючи CRC та зберігаючи якість, без виклику LLM.
+selectTargets відфільтровує документи для генерації, вибираючи застарілі або ті, які мають низьку якість і не були спробовані раніше.
+purgeOrphanedDocs видаляє документи, для яких не існує відповідного джерела, і оновлює індекси директорій.
+runDocFilesGenCli запускає генерацію документації для застарілих або низькоякісних файлів, після попереднього очищення сирітських документів.
+runGenerationBatch виконує послідовну генерацію документації для заданого набору цілей, керуючи процесом через механізм виходу з ладу.
+runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих документів, додаючи CRC та зберігаючи дані про якість.
 
 ## Публічний API
 
-selectTargets — Визначає цілі для генерації: застарілі або погіршені документи, які ще не пройшли перевірку CRC, або всі документи при використанні прапора перезапису.
-purgeOrphanedDocs — Видаляє документи, для яких відсутній вихідний файл, та оновлює/очищає файл `index.md` у відповідній директорії.
+selectTargets — Визначає цілі для генерації документації: застарілі або деградовані документи, або всі документи при використанні прапора перезапису.
+purgeOrphanedDocs — Видаляє документи, для яких відсутній відповідний вихідний файл, та оновлює файл індексу.
 runDocFilesGenCli — Генерує документацію для застарілих або відсутніх документів.
-runGenerationBatch — Виконує послідовну генерацію документів: перевіряє локальний бекенд, обробляє цілі генерації з механізмом захисту від збоїв, і надає фінальний звіт.
-runDocFilesStampCli — Додає або оновлює метадані `source` та `crc` до існуючих документів без залучення великих мовних моделей, використовуючи наявні дані про модель та якість.
+runGenerationBatch — Виконує повний цикл генерації: перевіряє стан локального бекенду, послідовно генерує документи з обробкою збоїв, та створює фінальний звіт.
+runDocFilesStampCli — Додає або оновлює метадані джерела та контрольної суми до існуючих документів без використання великих мовних моделей.
 
 ## Гарантії поведінки
 

package/rules/doc-files/js/docs/docgen-gen.md

@@ -3,42 +3,31 @@ type: JS Module
 title: docgen-gen.mjs
 resource: npm/rules/doc-files/js/docgen-gen.mjs
 docgen:
-  crc: 7674d2b2
+  crc: 059d7d6e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Огляд
-Публічні функції виконують операції з текстом та оцінками. Вони включають виділення коду, вставлення інформації та генерацію документів на основі визначених параметрів.
+## Огляд
 
-## Поведінка
-
-splitProtected
-Вибирає та видаляє код-фенс-обгортку з секції
-
-insertProtected
-Вставляє захищений блок Призначення після заголовка Огляд
+Модуль забезпечує повний цикл роботи з документами: відокремлює захищений блок за допомогою `splitProtected`, вставляє його у визначене місце за допомогою `insertProtected`, генерує повний Markdown-документ через `generateDoc` (з використанням `DEFAULT_LOCAL_MODEL`), а також оцінює якість документа за допомогою `scoreDoc`. Кешування застосовується протягом прогону. (abie.mdc)
 
-scoreDoc
-Перевіряє вихід проти фактів і повертає оцінку та список проблем
-
-DEFAULT_LOCAL_MODEL
-Повертає дефолтну модель для роботи
+## Поведінка
 
-generateDoc
-Генерує документ з детермінованою оцінкою та метаданими
+splitProtected відокремлює захищений блок Призначення від основного документа.
+insertProtected вставляє захищений блок Призначення у фіксовану позицію після заголовка документа.
+scoreDoc оцінює якість згенерованого документа за заданими критеріями.
+DEFAULT_LOCAL_MODEL визначає модель, яка використовується для генерації документа.
+generateDoc генерує повний Markdown-документ з опису файлу, застосовуючи оцінку та можливий ретрай.
 
 ## Публічний API
 
-splitProtected — Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## ` і `###` не обриває блок. (abie.mdc)
-insertProtected — Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція). (abie.mdc)
-scoreDoc — Stage 2.5 — Детермінований скоринг (0 токенів): перевіряє вихід проти фактів. (abie.mdc)
-DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel → omlx напряму. Останній fallback гарантує локальний виклик без змін середовища (через pi CLI той самий локальний виклик виміряно повільніший на ~46%). (abie.mdc)
-generateDoc — Головний API: файл → md-дока з det-оцінкою. (abie.mdc)
+splitProtected — Розділяє захищений розділ `## Призначення` (Варіант B), використовуючи наступний заголовок рівня H2 або H3 як межу.
+insertProtected — Розміщує захищений блок `## Призначення` безпосередньо після основного заголовка (H1).
+scoreDoc — Виконує детерміновану оцінку (Stage 2.5), порівнюючи вихідні дані з фактичною інформацією.
+DEFAULT_LOCAL_MODEL — Визначає модель для генерації документа, використовуючи мінімальну локальну модель. Якщо модель не задана, процес зупиняється з помилкою.
+generateDoc — Основна функція, яка перетворює вхідний файл у Markdown-документ з оцінкою достовірності.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

package/rules/doc-files/js/docs/docgen-judge-measure.md

@@ -3,26 +3,28 @@ type: JS Module
 title: docgen-judge-measure.mjs
 resource: npm/rules/doc-files/js/docgen-judge-measure.mjs
 docgen:
-  crc: e6e19732
+  crc: 86b3120f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Файл зчитує список файлів для аналізу, спираючись на конфігурацію `report.json`. Для кожного файлу генерується технічна документація за допомогою локальної моделі. Після генерації документація оцінюється хмарною моделлю. Результати оцінки кешуються у межах прогону, а потім збираються у звіт. Звіт зберігається у `report.json` та виводиться у консоль.
+## Огляд
+
+Модуль обробляє файли, витягуючи їхній зміст для генерації документації. Він порівнює цю документацію з оцінками сильної модільної системи. Під час роботи відбувається кешування у межах прогону. Модуль збирає метрики якості згенерованої документації та зберігає фінальний звіт у `report.json`, який спирається на конфігурації, визначені в `report.json`.
 
 ## Поведінка
 
-1. Зчитує список файлів для аналізу з командного рядка.
+1. Зчитує список файлів для аналізу з аргументів командного рядка.
 2. Для кожного файлу зчитує його вміст.
-3. Генерує документацію для файлу, використовуючи локальну модель. Результат кешується за хешем вмісту джерела.
-4. Якщо генерація документації неможлива або не пройшла встановлений поріг якості, фіксує це як помилку або непідтримуваний файл.
-5. Якщо документація пройшла поріг якості, вона передається для оцінки.
-6. Оцінює згенеровану документацію за допомогою потужної хмарної моделі. Результат оцінки кешується за хешем вмісту джерела та документації.
-7. Якщо оцінка неможлива, фіксує помилку оцінки.
-8. Збирає результати для всіх файлів.
-9. Обчислює звіт, включаючи загальну кількість файлів, кількість успішно згенерованих та оцінених, а також відсоток хибнопозитивних результатів (false-positive rate).
-10. Зберігає повний звіт у файл `report.json` у каталозі кешу.
-11. Виводить консольний звіт з ключовими показниками.
+3. Генерує документацію для файлу, використовуючи кеш за вмістом джерела.
+4. Якщо документація згенерована, перевіряє її якість за встановленим порогом.
+5. Якщо якість документації відповідає порогу, передає вміст джерела та згенеровану документацію для оцінки сильною моделлю.
+6. Оцінювач повертає вердикт (точний, загальний, неточний) з обґрунтуванням.
+7. Зберігає результати для кожного файлу.
+8. Агрегує результати: підраховує загальну кількість файлів, успішно згенерованих, пройшли перевірку, а також розподіл вердиктів серед тих, що пройшли перевірку.
+9. Формує звіт, який включає конфігурацію, підрахунки та відсотки помилкових спрацьовувань.
+10. Зберігає фінальний звіт у файл `report.json` у каталозі кешу.
+11. Виводить консольний звіт про результати вимірювання.
 
 ## Гарантії поведінки
 

package/rules/doc-files/js/docs/index.md

@@ -6,20 +6,20 @@ resource: npm/rules/doc-files/js/
 
 # npm/rules/doc-files/js
 
-| Файл | Тип |
-|---|---|
-| [docgen-crc.mjs](docgen-crc.md) | JS Module |
+| Файл                                                    | Тип       |
+| ------------------------------------------------------- | --------- |
+| [docgen-crc.mjs](docgen-crc.md)                         | JS Module |
 | [docgen-extract-anchors.mjs](docgen-extract-anchors.md) | JS Module |
-| [docgen-extract.mjs](docgen-extract.md) | JS Module |
-| [docgen-files-batch.mjs](docgen-files-batch.md) | JS Module |
-| [docgen-gen.mjs](docgen-gen.md) | JS Module |
-| [docgen-ignore.mjs](docgen-ignore.md) | JS Module |
-| [docgen-judge-measure.mjs](docgen-judge-measure.md) | JS Module |
-| [docgen-judge.mjs](docgen-judge.md) | JS Module |
-| [docgen-prompts.mjs](docgen-prompts.md) | JS Module |
-| [docgen-scan.mjs](docgen-scan.md) | JS Module |
-| [lint.mjs](lint.md) | JS Module |
-| [run-lint.mjs](run-lint.md) | JS Module |
-| [units-js.mjs](units-js.md) | JS Module |
-| [units-rs.mjs](units-rs.md) | JS Module |
-| [units.mjs](units.md) | JS Module |
+| [docgen-extract.mjs](docgen-extract.md)                 | JS Module |
+| [docgen-files-batch.mjs](docgen-files-batch.md)         | JS Module |
+| [docgen-gen.mjs](docgen-gen.md)                         | JS Module |
+| [docgen-ignore.mjs](docgen-ignore.md)                   | JS Module |
+| [docgen-judge-measure.mjs](docgen-judge-measure.md)     | JS Module |
+| [docgen-judge.mjs](docgen-judge.md)                     | JS Module |
+| [docgen-prompts.mjs](docgen-prompts.md)                 | JS Module |
+| [docgen-scan.mjs](docgen-scan.md)                       | JS Module |
+| [lint.mjs](lint.md)                                     | JS Module |
+| [run-lint.mjs](run-lint.md)                             | JS Module |
+| [units-js.mjs](units-js.md)                             | JS Module |
+| [units-rs.mjs](units-rs.md)                             | JS Module |
+| [units.mjs](units.md)                                   | JS Module |

package/rules/docker/docs/fix.md

@@ -14,14 +14,14 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних до політики до mdc-refs.
-    *   Повертає результат.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних до політики до mdc-refs.
+   - Повертає результат.
 
 2. Виконання у режимі CLI.
-    *   Викликається через оркестрацію CLI.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Виконує завантаження конфігурації, перевірку дозволених елементів та підбиття підсумку.
+   - Викликається через оркестрацію CLI.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Виконує завантаження конфігурації, перевірку дозволених елементів та підбиття підсумку.
 
 ## Публічний API
 

package/rules/docker/docs/index.md

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

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

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

package/rules/docker/lib/docs/docker-hadolint.md

@@ -22,8 +22,8 @@ lintDockerfileWithHadolint
 
 ## Публічний API
 
-* posixRel — Генерує абсолютний шлях від кореня з використанням лише слешів, забезпечуючи стабільність незалежно від операційної системи.
-* lintDockerfileWithHadolint — Запускає інструмент hadolint для аналізу Dockerfile. Якщо інструмент не знайдено у системних шляхах, він намагається встановити його. У разі невдачі встановлення або відключення автоматичного встановлення, повертає помилку, надаючи користувачеві підказку для ручного запуску (детальніше про інструмент можна знайти на https://github.com/hadolint/hadolint/releases).
+- posixRel — Генерує абсолютний шлях від кореня з використанням лише слешів, забезпечуючи стабільність незалежно від операційної системи.
+- lintDockerfileWithHadolint — Запускає інструмент hadolint для аналізу Dockerfile. Якщо інструмент не знайдено у системних шляхах, він намагається встановити його. У разі невдачі встановлення або відключення автоматичного встановлення, повертає помилку, надаючи користувачеві підказку для ручного запуску (детальніше про інструмент можна знайти на https://github.com/hadolint/hadolint/releases).
 
 ## Гарантії поведінки
 

package/rules/docker/lib/docs/index.md

@@ -6,9 +6,9 @@ resource: npm/rules/docker/lib/
 
 # npm/rules/docker/lib
 
-| Файл | Тип |
-|---|---|
-| [docker-hadolint.mjs](docker-hadolint.md) | JS Module |
-| [docker-mirror.mjs](docker-mirror.md) | JS Module |
+| Файл                                              | Тип       |
+| ------------------------------------------------- | --------- |
+| [docker-hadolint.mjs](docker-hadolint.md)         | JS Module |
+| [docker-mirror.mjs](docker-mirror.md)             | JS Module |
 | [docker-native-addon.mjs](docker-native-addon.md) | JS Module |
-| [docker-nginx-user.mjs](docker-nginx-user.md) | JS Module |
+| [docker-nginx-user.mjs](docker-nginx-user.md)     | JS Module |

package/rules/efes/docs/fix.md

@@ -14,16 +14,16 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 
 2. Запуск у режимі CLI.
-    *   Виконується при запуску через CLI.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Повертає код виходу.
+   - Виконується при запуску через CLI.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Повертає код виходу.
 
 ## Публічний API
 

package/rules/efes/docs/index.md

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

package/rules/feedback/docs/fix.md

@@ -12,11 +12,11 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 
 ## Публічний API