@nitra/cursor 12.6.1 → 12.8.0

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

@@ -1,12 +1,21 @@
 /** @see ./docs/docgen-files-batch.md */
-import { readFileSync, readdirSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { classifyOmlxError, preflightLocalModel } from '../../../lib/llm.mjs'
 import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
 import { crc32, stampDoc, readDocQuality, readDocModel, QUALITY_THRESHOLD } from './docgen-crc.mjs'
-import { resolveRoot, scanForDocFiles } from './docgen-scan.mjs'
+import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from './docgen-scan.mjs'
 
 /**
  * Парсить `--limit N` / `--from N` / прапори режимів для дозапуску великого прогону.
@@ -153,7 +162,9 @@ const OKF_RESOURCE_RE = /^resource:[ \t]+(.+)$/mu
  * @returns {void}
  */
 function generateDirIndex(docsAbsDir, root) {
-  const allMd = readdirSync(docsAbsDir).filter(f => f.endsWith('.md')).sort()
+  const allMd = readdirSync(docsAbsDir)
+    .filter(f => f.endsWith('.md'))
+    .sort()
 
   // Якщо index.md вже є дока для source-файлу (має docgen.source → index.*) — не чіпаємо
   if (allMd.includes('index.md')) {
@@ -215,6 +226,46 @@ function reportStats(stats) {
   }
 }
 
+/**
+ * Видаляє сирітські доки (source-файл не існує) і оновлює/прибирає index.md.
+ * Якщо після видалення в docs/-директорії лишились тільки index.md або нічого — очищує її.
+ * @param {string} root абсолютний корінь
+ * @returns {number} кількість видалених doc-файлів
+ */
+export function purgeOrphanedDocs(root) {
+  const orphans = scanOrphanedDocs(root)
+  if (orphans.length === 0) return 0
+  let deleted = 0
+  const docsDirs = new Set()
+  for (const docRel of orphans) {
+    try {
+      unlinkSync(join(root, docRel))
+      docsDirs.add(dirname(join(root, docRel)))
+      deleted++
+    } catch {
+      // race condition або вже видалено — ігноруємо
+    }
+  }
+  for (const docsAbsDir of docsDirs) {
+    if (!existsSync(docsAbsDir)) continue
+    const remaining = readdirSync(docsAbsDir)
+    const docFiles = remaining.filter(f => f.endsWith('.md') && f !== 'index.md')
+    if (docFiles.length === 0) {
+      // Лише index.md або порожня директорія — прибираємо повністю
+      const indexPath = join(docsAbsDir, 'index.md')
+      if (existsSync(indexPath)) unlinkSync(indexPath)
+      try {
+        rmdirSync(docsAbsDir)
+      } catch {
+        /* не порожня — пропускаємо */
+      }
+    } else {
+      generateDirIndex(docsAbsDir, root)
+    }
+  }
+  return deleted
+}
+
 /**
  * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
  * @param {string[]} argv аргументи після назви субкоманди
@@ -224,11 +275,19 @@ export async function runDocFilesGenCli(argv) {
   const root = resolveRoot(argv)
   const { from, limit, overwrite } = parseGenArgs(argv)
 
+  // Видаляємо orphan-доки до генерації (незалежно від наявності stale)
+  const deleted = purgeOrphanedDocs(root)
+  if (deleted > 0) {
+    console.log(`🗑 doc-files: видалено ${deleted} сирітських доки(ів)`)
+  }
+
   const all = scanForDocFiles(root)
   const targets = selectTargets(root, all, { overwrite }).slice(from, from + limit)
 
   if (targets.length === 0) {
-    console.log('✓ doc-files: усі файлові доки свіжі й не-degraded. Нічого генерувати.')
+    if (deleted === 0) {
+      console.log('✓ doc-files: усі файлові доки свіжі й не-degraded. Нічого генерувати.')
+    }
     return 0
   }
 

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

@@ -133,7 +133,10 @@ export function splitProtected(md) {
       break
     }
   }
-  const body = lines.slice(start + 1, end).join('\n').trim()
+  const body = lines
+    .slice(start + 1, end)
+    .join('\n')
+    .trim()
   const without = [...lines.slice(0, start), ...lines.slice(end)].join('\n')
   return { body: body || null, without }
 }
@@ -395,7 +398,10 @@ export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? resolveModel('mi
  * @param {{ model?: string, threshold?: number, existingMd?: string|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції)
  * @returns {{ md: string, ms: number, llmMs: number, llmCalls: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації (ms — увесь файл; llmMs/llmCalls — лише LLM; решта ms — оркестрація)
  */
-export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD, existingMd = null } = {}) {
+export function generateDoc(
+  file,
+  { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD, existingMd = null } = {}
+) {
   const src = readFileSync(file, 'utf8')
   // Pre-send guard: весь src вшивається у промпт як є (екстракт фактів його НЕ
   // замінює). Для гігантів (vendored/генерат) це переповнює контекст → інстант-skip
@@ -403,7 +409,9 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
   const estTokens = Math.round(Buffer.byteLength(src, 'utf8') / 4)
   const budget = srcTokenBudget()
   if (estTokens > budget) {
-    throw new Error(`docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`)
+    throw new Error(
+      `docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`
+    )
   }
   const facts = extractFacts(src, file)
   const t0 = Date.now()

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

@@ -1,13 +1,13 @@
 /** @see ./docs/docgen-scan.md */
 import { join, dirname, basename, extname, relative, resolve, sep, isAbsolute, posix } from 'node:path'
-import { existsSync, readdirSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { execFileSync } from 'node:child_process'
 import { once } from 'node:events'
 import { env } from 'node:process'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { isDocgenIgnored } from './docgen-ignore.mjs'
-import { QUALITY_THRESHOLD, readDocQuality, staleness } from './docgen-crc.mjs'
+import { QUALITY_THRESHOLD, parseDocFrontmatter, readDocQuality, staleness } from './docgen-crc.mjs'
 
 /** Кодові розширення, для яких генеруємо документацію. */
 const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py', '.rs'])
@@ -78,6 +78,70 @@ export function describeFile(root, sourcePath) {
   return { sourcePath, docPath, stale, reason }
 }
 
+/**
+ * Знаходить "сирітські" доки: `docs/<stem>.md` із `resource:` + `docgen.crc` у frontmatter,
+ * у яких відповідний source-файл (resource:) вже не існує. Перевіряє лише файли,
+ * згенеровані `fix-doc-files` (наявність `docgen.crc` у frontmatter). Directory Index
+ * (resource із `/` на кінці) та ручні доки без `resource:` або без CRC — ігноруються.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {string[]} posix-шляхи сирітських doc-файлів від кореня
+ */
+export function scanOrphanedDocs(root) {
+  const orphans = []
+
+  /** @param {string} docsAbsDir абсолютний шлях docs/-директорії */
+  function scanDocsDir(docsAbsDir) {
+    let entries
+    try {
+      entries = readdirSync(docsAbsDir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+      const fullPath = join(docsAbsDir, entry.name)
+      let content
+      try {
+        content = readFileSync(fullPath, 'utf8')
+      } catch {
+        continue
+      }
+      const { data } = parseDocFrontmatter(content)
+      // Пропускаємо: Directory Index (resource з `/`), ручні доки (немає resource або CRC)
+      if (!data?.source || data.source.endsWith('/') || !data.crc) continue
+      if (!existsSync(join(root, data.source))) {
+        orphans.push(relative(root, fullPath).split(sep).join('/'))
+      }
+    }
+  }
+
+  /** Обходить дерево, шукаючи docs/-директорії для orphan-перевірки.
+   *  docs/ — входимо завжди (батьківська пройшла ignore-перевірку);
+   *  інші — перевіряємо через isDocgenIgnored. */
+  function walk(dir) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const fullPath = join(dir, entry.name)
+      if (entry.name === 'docs') {
+        scanDocsDir(fullPath)
+      } else {
+        const relPath = relative(root, fullPath).split(sep).join('/')
+        if (isDocgenIgnored(relPath, 'dir')) continue
+        walk(fullPath)
+      }
+    }
+  }
+
+  walk(root)
+  return orphans
+}
+
 /**
  * Підмножина шляхів, які git вважає ігнорованими (`.gitignore` + global excludes).
  * Один батч-виклик `git check-ignore --stdin`. Tracked-файли git не репортить як
@@ -96,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()
@@ -137,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
 }
 
@@ -307,20 +379,36 @@ export async function runDocFilesCheckCli(argv) {
   }
 
   const stale = sources.map(src => describeFile(root, src)).filter(f => f.stale)
-  if (stale.length === 0) return 0
+  // В git-режимі (Stop-гейт) додатково шукаємо сирітські доки без source-файлу
+  const orphans = gitMode ? scanOrphanedDocs(root) : []
 
-  // Великий прогін: Stop-гейт не блокує, лише попереджає (захист від нескінченного блоку).
+  if (stale.length === 0 && orphans.length === 0) return 0
+
+  // Великий прогін stale: Stop-гейт не блокує, але orphan-check продовжуємо
   if (gitMode && stale.length > gateMax) {
     console.error(
       `⚠ doc-files: застарілих док ${stale.length} (> ${gateMax}) — гейт не блокує. Запусти масовий прогін:\n  npx @nitra/cursor fix-doc-files`
     )
-    return 0
+    if (orphans.length === 0) return 0
+    const oList = orphans.map(f => `  - ${f}`).join('\n')
+    console.error(
+      `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${oList}\n→ очисти: npx @nitra/cursor fix-doc-files`
+    )
+    return 2
   }
 
-  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
-  console.error(
-    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: /doc-files`
-  )
+  if (stale.length > 0) {
+    const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+    console.error(
+      `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: /doc-files`
+    )
+  }
+  if (orphans.length > 0) {
+    const oList = orphans.map(f => `  - ${f}`).join('\n')
+    console.error(
+      `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${oList}\n→ очисти: npx @nitra/cursor fix-doc-files`
+    )
+  }
   return 2
 }
 

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,31 +3,31 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: 18c96a58
-  score: 95
+  crc: 6316eecb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-runDocFilesGenCli
-Запускає генерацію документації для застарілих або відсутніх файлів.
+## Огляд
 
-runDocFilesStampCli
-Перештампує frontmatter джерело та CRC у наявних документах без виклику LLM.
+Модуль керує життєвим циклом документації. Він вибирає цілі для оновлення за допомогою `selectTargets`, очищає від неіснуючих джерел за допомогою `purgeOrphanedDocs`, запускає генерацію файлів через `runDocFilesGenCli` та `runDocFilesStampCli`, а також виконує пакетну генерацію за допомогою `runGenerationBatch`. Усі операції виконуються з механізмом перехоплення помилок, що запобігає виникненню винятків назовні.
 
 ## Поведінка
 
-runDocFilesGenCli
-Запускає генерацію документації для застарілих/відсутніх док.
-
-runDocFilesStampCli
-Перештампує frontmatter source+crc у наявних доках без виклику LLM.
+selectTargets відфільтровує документи для генерації, вибираючи застарілі або ті, які мають низьку якість і не були спробовані раніше.
+purgeOrphanedDocs видаляє документи, для яких не існує відповідного джерела, і оновлює індекси директорій.
+runDocFilesGenCli запускає генерацію документації для застарілих або низькоякісних файлів, після попереднього очищення сирітських документів.
+runGenerationBatch виконує послідовну генерацію документації для заданого набору цілей, керуючи процесом через механізм виходу з ладу.
+runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих документів, додаючи CRC та зберігаючи дані про якість.
 
 ## Публічний API
 
-- runDocFilesGenCli — згенерувати документацію для застарілих/відсутніх док.
-- runDocFilesStampCli — детерміновано (пере)штампувати frontmatter `source`+`crc` у наявних доках без виклику LLM. Для міграції док, які ще не мають CRC. Поля якості (`score`/`issues`) зберігаються з наявного frontmatter.
+selectTargets — Визначає цілі для генерації документації: застарілі або деградовані документи, або всі документи при використанні прапора перезапису.
+purgeOrphanedDocs — Видаляє документи, для яких відсутній відповідний вихідний файл, та оновлює файл індексу.
+runDocFilesGenCli — Генерує документацію для застарілих або відсутніх документів.
+runGenerationBatch — Виконує повний цикл генерації: перевіряє стан локального бекенду, послідовно генерує документи з обробкою збоїв, та створює фінальний звіт.
+runDocFilesStampCli — Додає або оновлює метадані джерела та контрольної суми до існуючих документів без використання великих мовних моделей.
 
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.