@nitra/cursor 5.3.2 → 5.3.4

package/skills/doc-aggregate/js/docgen-scan.mjs

@@ -1,6 +1,5 @@
 /** @see ./docs/docgen-scan.md */
-// eslint-disable-next-line unicorn/import-style
-import path from 'node:path'
+import { join, relative, dirname, extname, sep, isAbsolute, resolve } from 'node:path'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
@@ -18,7 +17,7 @@ const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
  * @returns {boolean} true — корінь system-wide docs
  */
 function isSystemWideDocsRoot(root) {
-  return existsSync(path.join(root, 'docs', 'adr')) || existsSync(path.join(root, 'docs', 'explanation'))
+  return existsSync(join(root, 'docs', 'adr')) || existsSync(join(root, 'docs', 'explanation'))
 }
 
 /**
@@ -29,7 +28,7 @@ function isSystemWideDocsRoot(root) {
 export function isSourceFile(fileName) {
   if (fileName.endsWith('.d.ts')) return false
   if (TEST_FILE_RE.test(fileName)) return false
-  return SOURCE_EXTENSIONS.has(path.extname(fileName))
+  return SOURCE_EXTENSIONS.has(extname(fileName))
 }
 
 /**
@@ -49,14 +48,14 @@ export function scanSourceFiles(root) {
       return
     }
     for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name)
-      const relPath = path.relative(root, fullPath)
+      const fullPath = join(dir, entry.name)
+      const relPath = relative(root, fullPath)
       if (entry.isDirectory()) {
         if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
       } else if (entry.isFile() && isSourceFile(entry.name)) {
-        if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
-        const sourcePath = relPath.split(path.sep).join('/')
+        if (isSystemWideDocsRoot(root) && dirname(relPath) === '.') continue
+        const sourcePath = relPath.split(sep).join('/')
         if (isDocgenIgnored(sourcePath)) continue
         results.push(sourcePath)
       }
@@ -74,10 +73,10 @@ export function scanSourceFiles(root) {
  * @returns {string} slug: `npm/rules/adr` → `npm-rules-adr`, корінь → `root`
  */
 export function slugForModule(root, moduleRoot) {
-  const rel = path.relative(root, moduleRoot)
+  const rel = relative(root, moduleRoot)
   if (rel === '') return 'root'
   return rel
-    .split(path.sep)
+    .split(sep)
     .join('-')
     .replaceAll(/[^\w-]+/gu, '-')
 }
@@ -99,8 +98,8 @@ export function findModuleRoots(root) {
       return
     }
     for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name)
-      const relPath = path.relative(root, fullPath)
+      const fullPath = join(dir, entry.name)
+      const relPath = relative(root, fullPath)
       if (entry.isDirectory()) {
         if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
@@ -123,8 +122,8 @@ export function findModuleRoots(root) {
 export function nearestModuleRoot(filePath, moduleRoots) {
   let best = null
   for (const moduleRoot of moduleRoots) {
-    const rel = path.relative(moduleRoot, filePath)
-    if (rel.startsWith('..') || path.isAbsolute(rel)) continue
+    const rel = relative(moduleRoot, filePath)
+    if (rel.startsWith('..') || isAbsolute(rel)) continue
     if (best === null || moduleRoot.length > best.length) best = moduleRoot
   }
   return best
@@ -141,7 +140,7 @@ export function scanForModules(root) {
   const moduleRoots = findModuleRoots(root)
   const byRoot = new Map()
   for (const sourcePath of files) {
-    const moduleRoot = nearestModuleRoot(path.join(root, sourcePath), moduleRoots)
+    const moduleRoot = nearestModuleRoot(join(root, sourcePath), moduleRoots)
     if (moduleRoot === null) continue
     if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
     byRoot.get(moduleRoot).push(sourcePath)
@@ -151,10 +150,10 @@ export function scanForModules(root) {
   for (const moduleRoot of moduleRoots) {
     const members = byRoot.get(moduleRoot)
     if (!members || members.length === 0) continue
-    const docPath = path.join(moduleRoot, 'docs', 'ARCHITECTURE.md')
+    const docPath = join(moduleRoot, 'docs', 'ARCHITECTURE.md')
     results.push({
       moduleRoot,
-      relRoot: path.relative(root, moduleRoot) || '.',
+      relRoot: relative(root, moduleRoot) || '.',
       slug: slugForModule(root, moduleRoot),
       docPath,
       members: members.toSorted(),
@@ -171,7 +170,7 @@ export function scanForModules(root) {
  */
 export function resolveRoot(argv) {
   const i = argv.indexOf('--root')
-  return i !== -1 && argv[i + 1] ? path.resolve(argv[i + 1]) : process.cwd()
+  return i !== -1 && argv[i + 1] ? resolve(argv[i + 1]) : process.cwd()
 }
 
 /**

package/skills/doc-files/.changes/260612-0002.md

@@ -0,0 +1,5 @@
+---
+bump: minor
+section: Added
+---
+doc-files: підтримка Rust (.rs) — SOURCE_EXTENSIONS, target/-ignore, extractFactsRust, units-rs

package/skills/doc-files/.changes/260612-0006.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Fixed
+---
+мовно-нейтральний текст returnsFalsyOnFail (false/null/Err); units-rs: тести + docs

package/skills/doc-files/.changes/260612-0008.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Added
+---
+Rust .rs: тести units-rs, doc units-rs.md, мовно-нейтральний текст гарантії returnsFalsyOnFail

package/skills/doc-files/.changes/260612-0012.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Added
+---
+Rust (.rs): тести extractFactsRust у docgen-extract.test.mjs — exports, tauri::command, struct/enum, markers, header, desc

package/skills/doc-files/js/docgen-extract.mjs

@@ -211,6 +211,141 @@ function extractMarkers(src) {
   }
 }
 
+// ── Rust-екстрактор ──────────────────────────────────────────────────────────
+
+// Модульний //! doc-коментар (inner doc)
+const RS_MODULE_DOC_RE = /^(?:[ \t]*\/\/![ \t]?(.*)\n)*/m
+
+// pub fn / pub struct / pub enum / pub trait (та fn із exposure-атрибутом)
+const RS_PUB_ITEM_RE = /^[ \t]*(pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/gm
+
+// Exposure-атрибути (#[tauri::command] тощо)
+const RS_EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/gm
+
+// /// line-doc перед елементом
+const RS_LINE_DOC_RE = /(?:[ \t]*\/\/\/[ \t]?.*\n)*/
+
+// use crate::module::{A, B}  або  use std::..;
+const RS_USE_RE = /^[ \t]*use\s+([\w:]+(?:::\{[^}]+\})?(?:::\*)?(?:::\w+)?)\s*;/gm
+
+// Файловий запис: fs::write / File::create / remove_file / create_dir / write_all
+const RS_WRITE_RE = /fs::write|File::create|remove_file|create_dir|BufWriter::new|OpenOptions[^;]*\.write\s*\(\s*true/
+
+// Обробка помилок (але не просто `?`)
+const RS_CATCH_RE = /\.unwrap_or(?:_else|_default)?|if\s+let\s+Err\s*\(|match\s+\S+.*\{\s*[\s\S]*?Err\s*\(|\.map_err\s*\(|\.ok\s*\(\)/
+
+// Функції, що повертають Result або Option
+const RS_RESULT_RE = /->\s*(?:Result|Option)\s*</
+
+// Мережа
+const RS_NETWORK_RE = /reqwest|hyper::|TcpStream|UdpSocket|tokio::net/
+
+// Кешування
+const RS_CACHE_RE = /\bcache\b|\bCache\b|lazy_static!|OnceCell|OnceLock|DashMap/i
+
+/**
+ * Видобуває `///` doc-рядки перед рядком `lineIdx` (назад через `#[...]` та пусті рядки).
+ * @param {string[]} lines рядки файлу
+ * @param {number} lineIdx індекс рядка декларації
+ * @returns {string} опис або ''
+ */
+function rsDocBefore(lines, lineIdx) {
+  const doc = []
+  for (let i = lineIdx - 1; i >= 0; i--) {
+    const t = lines[i].trim()
+    if (t.startsWith('///')) doc.unshift(t.slice(3).trim())
+    else if (t.startsWith('#[') || t.startsWith('#![') || t === '') { /* skip */ }
+    else break
+  }
+  return doc.join(' ').trim()
+}
+
+/**
+ * Витягує факт-лист для `.rs` файлу.
+ * @param {string} src вміст файлу
+ * @param {string} relPath відносний шлях
+ * @returns {object} факт-лист без `unsupported`
+ */
+function extractFactsRust(src, relPath) {
+  // header — //! module-level doc
+  const headerLines = []
+  for (const line of src.split('\n')) {
+    const t = line.trim()
+    if (t.startsWith('//!')) headerLines.push(t.slice(3).trim())
+    else if (t === '' || t.startsWith('//')) continue
+    else break
+  }
+  const header = headerLines.join(' ').trim()
+
+  // Exposure-атрибути: рядки, після яких fn стає фактично pub
+  const srcLines = src.split('\n')
+  const exposedLineSet = new Set()
+  for (const m of src.matchAll(RS_EXPOSURE_ATTR_RE)) {
+    // Знаходимо, який рядок містить цей атрибут
+    let pos = 0
+    for (let li = 0; li < srcLines.length; li++) {
+      if (pos + srcLines[li].length >= m.index) {
+        // Шукаємо наступний не-атрибутний рядок з fn
+        for (let nli = li + 1; nli < Math.min(li + 5, srcLines.length); nli++) {
+          const t = srcLines[nli].trim()
+          if (t.startsWith('#[') || t === '') continue
+          if (/^(?:pub\s+)?(?:async\s+)?(?:unsafe\s+)?fn\s+/.test(t)) exposedLineSet.add(nli)
+          break
+        }
+        break
+      }
+      pos += srcLines[li].length + 1
+    }
+  }
+
+  // exports — pub items + exposure-exposed fns
+  const exports = []
+  let lineOffset = 0
+  for (let li = 0; li < srcLines.length; li++) {
+    const line = srcLines[li]
+    const m = line.match(/^[ \t]*(pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/)
+    if (m) {
+      const isPub = Boolean(m[1]) || exposedLineSet.has(li)
+      if (isPub) {
+        const desc = rsDocBefore(srcLines, li)
+        exports.push({ name: m[3], kind: m[2], desc })
+      }
+    }
+    lineOffset += line.length + 1
+  }
+
+  // localSymbols — приватні fn (не pub і не exposed) — не документуємо як публічний API
+  const localSymbols = []
+  for (let li = 0; li < srcLines.length; li++) {
+    const line = srcLines[li]
+    const m = line.match(/^[ \t]*(?:async\s+)?(?:unsafe\s+)?fn\s+(\w+)/)
+    if (m && !exports.some(e => e.name === m[1])) localSymbols.push(m[1])
+  }
+
+  // imports — use-рядки, класифіковані на std / external / internal
+  const stdlib = new Set()
+  const external = new Set()
+  for (const m of src.matchAll(RS_USE_RE)) {
+    const path = m[1]
+    const root = path.split('::')[0]
+    if (root === 'std' || root === 'core' || root === 'alloc') stdlib.add(path)
+    else external.add(path)
+  }
+  const imports = { stdlib: [...stdlib], external: [...external], internal: [] }
+
+  // markers
+  const markers = {
+    readOnly: !RS_WRITE_RE.test(src),
+    catchesErrors: RS_CATCH_RE.test(src),
+    returnsFalsyOnFail: RS_RESULT_RE.test(src),
+    network: RS_NETWORK_RE.test(src),
+    caches: RS_CACHE_RE.test(src),
+    skips: []
+  }
+
+  return { relPath, lang: 'rs', header, exports, imports, internalSymbols: [], localSymbols, markers }
+}
+
 /**
  * Головний екстрактор: код файлу → факт-лист.
  * @param {string} src вміст файлу
@@ -219,6 +354,7 @@ function extractMarkers(src) {
  */
 export function extractFacts(src, relPath) {
   const lang = relPath.split('.').pop()
+  if (lang === 'rs') return extractFactsRust(src, relPath)
   if (!['js', 'mjs', 'ts'].includes(lang)) {
     return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
   }

package/skills/doc-files/js/docgen-prompts.mjs

@@ -32,7 +32,7 @@ function factsSummary(facts) {
   if (m.skips?.length) lines.push(`Свідомо пропускає шляхи: ${m.skips.join(', ')}`)
   lines.push(`Read-only: ${m.readOnly ? 'так' : 'ні'}`)
   if (m.catchesErrors) lines.push('Перехоплює помилки (fail-safe), не кидає винятків назовні')
-  if (m.returnsFalsyOnFail) lines.push('За невдачі повертає false/null замість винятку')
+  if (m.returnsFalsyOnFail) lines.push('За невдачі повертає значення помилки (false/null/Err) замість винятку чи паніки')
   lines.push(m.caches ? 'Кешування: так, у межах прогону' : 'Кешування: НЕМАЄ — не згадуй кеш у гарантіях')
   if (m.network) lines.push('Звертається до мережі')
   else lines.push('Робота з мережею: немає')
@@ -195,7 +195,7 @@ export function guaranteesFromMarkers(facts) {
   const lines = []
   if (m.readOnly) lines.push('- Read-only: файл не виконує операцій запису у файлову систему.')
   if (m.catchesErrors) lines.push('- Перехоплює помилки і не пропускає винятків назовні (fail-safe).')
-  if (m.returnsFalsyOnFail) lines.push('- За невдалої перевірки повертає `false`/`null` замість винятку.')
+  if (m.returnsFalsyOnFail) lines.push('- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.')
   if (m.caches) lines.push('- Кешує результати в межах одного прогону.')
   if (m.skips?.length) {
     lines.push(`- Свідомо пропускає шляхи: ${m.skips.map(s => '`' + s + '`').join(', ')}.`)

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

@@ -1,6 +1,5 @@
 /** @see ./docs/docgen-scan.md */
-// eslint-disable-next-line unicorn/import-style
-import path from 'node:path'
+import { join, dirname, basename, extname, relative, resolve, sep, isAbsolute, posix } from 'node:path'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { execFileSync } from 'node:child_process'
 import { once } from 'node:events'
@@ -27,7 +26,7 @@ const DEFAULT_GATE_MAX = Number(env.N_CURSOR_DOC_FILES_GATE_MAX ?? 50) || 50
  * @returns {boolean} true — корінь system-wide docs
  */
 function isSystemWideDocsRoot(root) {
-  return existsSync(path.join(root, 'docs', 'adr')) || existsSync(path.join(root, 'docs', 'explanation'))
+  return existsSync(join(root, 'docs', 'adr')) || existsSync(join(root, 'docs', 'explanation'))
 }
 
 /**
@@ -38,7 +37,7 @@ function isSystemWideDocsRoot(root) {
 export function isSourceFile(fileName) {
   if (fileName.endsWith('.d.ts')) return false
   if (TEST_FILE_RE.test(fileName)) return false
-  return SOURCE_EXTENSIONS.has(path.extname(fileName))
+  return SOURCE_EXTENSIONS.has(extname(fileName))
 }
 
 /**
@@ -48,9 +47,9 @@ export function isSourceFile(fileName) {
  * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
  */
 export function docPathForSource(sourcePath) {
-  const dir = path.dirname(sourcePath)
-  const stem = path.basename(sourcePath, path.extname(sourcePath))
-  return path.join(dir, 'docs', `${stem}.md`)
+  const dir = dirname(sourcePath)
+  const stem = basename(sourcePath, extname(sourcePath))
+  return join(dir, 'docs', `${stem}.md`)
 }
 
 /**
@@ -61,9 +60,9 @@ export function docPathForSource(sourcePath) {
  * @returns {boolean} true — кандидат на доку
  */
 export function isDocCandidate(root, relPath) {
-  const fileName = path.posix.basename(relPath)
+  const fileName = posix.basename(relPath)
   if (!isSourceFile(fileName)) return false
-  if (isSystemWideDocsRoot(root) && path.posix.dirname(relPath) === '.') return false
+  if (isSystemWideDocsRoot(root) && posix.dirname(relPath) === '.') return false
   return !isDocgenIgnored(relPath)
 }
 
@@ -75,7 +74,7 @@ export function isDocCandidate(root, relPath) {
  */
 export function describeFile(root, sourcePath) {
   const docPath = docPathForSource(sourcePath)
-  const { stale, reason } = staleness(path.join(root, sourcePath), path.join(root, docPath))
+  const { stale, reason } = staleness(join(root, sourcePath), join(root, docPath))
   return { sourcePath, docPath, stale, reason }
 }
 
@@ -97,14 +96,14 @@ export function scanForDocFiles(root) {
       return
     }
     for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name)
-      const relPath = path.relative(root, fullPath)
+      const fullPath = join(dir, entry.name)
+      const relPath = relative(root, fullPath)
       if (entry.isDirectory()) {
         if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
       } else if (entry.isFile() && isSourceFile(entry.name)) {
-        if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
-        const sourcePath = relPath.split(path.sep).join('/')
+        if (isSystemWideDocsRoot(root) && dirname(relPath) === '.') continue
+        const sourcePath = relPath.split(sep).join('/')
         if (isDocgenIgnored(sourcePath)) continue
         results.push(describeFile(root, sourcePath))
       }
@@ -122,7 +121,7 @@ export function scanForDocFiles(root) {
  */
 export function resolveRoot(argv) {
   const i = argv.indexOf('--root')
-  return i !== -1 && argv[i + 1] ? path.resolve(argv[i + 1]) : process.cwd()
+  return i !== -1 && argv[i + 1] ? resolve(argv[i + 1]) : process.cwd()
 }
 
 /**
@@ -190,7 +189,7 @@ function gitChangedSources(root) {
   return out
     .split('\n')
     .map(s => s.trim())
-    .filter(rel => rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)))
+    .filter(rel => rel && isDocCandidate(root, rel) && existsSync(join(root, rel)))
 }
 
 /**
@@ -200,9 +199,9 @@ function gitChangedSources(root) {
  * @returns {string|null} posix-шлях від кореня
  */
 function toRelSource(root, candidate) {
-  const rel = path.relative(root, path.resolve(root, candidate))
-  if (rel.startsWith('..') || path.isAbsolute(rel)) return null
-  return rel.split(path.sep).join('/')
+  const rel = relative(root, resolve(root, candidate))
+  if (rel.startsWith('..') || isAbsolute(rel)) return null
+  return rel.split(sep).join('/')
 }
 
 /**
@@ -216,7 +215,7 @@ function runDegradedReport(root) {
   const degraded = []
   for (const f of scanForDocFiles(root)) {
     if (f.stale) continue
-    const { score, issues } = readDocQuality(path.join(root, f.docPath))
+    const { score, issues } = readDocQuality(join(root, f.docPath))
     if (score !== null && score < QUALITY_THRESHOLD) degraded.push({ ...f, score, issues })
   }
   if (degraded.length === 0) {
@@ -262,14 +261,14 @@ export async function runDocFilesCheckCli(argv) {
   if (hookMode) {
     const fp = extractHookFilePath(await readStdin())
     const rel = fp ? toRelSource(root, fp) : null
-    sources = rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)) ? [rel] : []
+    sources = rel && isDocCandidate(root, rel) && existsSync(join(root, rel)) ? [rel] : []
   } else if (gitMode) {
     sources = gitChangedSources(root)
   } else {
     sources = argv
       .filter(a => !a.startsWith('--') && a !== argv[maxIdx + 1])
       .map(a => toRelSource(root, a))
-      .filter(rel => rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)))
+      .filter(rel => rel && isDocCandidate(root, rel) && existsSync(join(root, rel)))
   }
 
   const stale = sources.map(src => describeFile(root, src)).filter(f => f.stale)

package/skills/doc-files/js/docs/docgen-extract-anchors.md

@@ -1,27 +1,45 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-extract-anchors.mjs
-  crc: e80e0827
+  crc: 49749e9c
+  score: 80
 ---
 
-# docgen-extract-anchors
+# docgen-extract-anchors.mjs
 
 ## Огляд
 
-Детермінований витяг «анкорів» — конкретних фрагментів коду, які модель зобов'язана згадати в документації, щоб не зісковзнути на generic-фрази. Анкори підставляються у промпти окремим блоком обов'язкового включення, а їх покриття перевіряється скорером.
+Витягує анкори з вихідного коду файлу.
+
+Витягує анкори з вихідного коду файлу.
+
+Формує плоский список анкор-токенів для перевірки покриття.
+
+Форматує анкори у компактний текст для system-промпта.
 
 ## Поведінка
 
-1. З тексту джерела збираються п'ять категорій анкорів: усі URL; експортовані константи-рядки з непорожнім значенням; маркери повідомлень про помилки виду `(rule.mdc)`; посилання на json-конфіги проєкту; code-block-приклади з провідного коментаря файлу (де автор зазвичай показує контракт).
-2. Кожна категорія дедуплікується зі збереженням порядку появи.
-3. Для промпта анкори форматуються в компактний текстовий блок з інструкціями, де саме їх згадати; якщо анкорів немає взагалі — блок не додається, щоб не вводити модель в оману «обов'язковими» полями.
+X
+Витягує анкори з вихідного коду файлу
+
+extractAnchors
+Витягує анкори з вихідного коду файлу
+
+anchorTokens
+Формує плоский список анкор-токенів для перевірки покриття
+
+anchorsToPrompt
+Форматує анкори у компактний текст для system-промпта
 
 ## Публічний API
 
-- `extractAnchors` — текст джерела → категоризовані анкори.
-- `anchorsToPrompt` — анкори → текстовий блок для system-промпта або порожній рядок.
+X — витягує анкори з вихідного коду файлу.
+extractAnchors — витягує анкори з вихідного коду файлу.
+anchorTokens — плоский список анкор-токенів, які мають з'явитися в документі.
+anchorsToPrompt — форматує анкори у компактний текст для system-промпта.
 
 ## Гарантії поведінки
 
-- Повністю детермінований і read-only; жодних LLM-викликів і мережі.
-- Працює по сирому тексту без AST: дешево і свідомо толерує надлишок (зайвий анкор — менша проблема, ніж пропущений).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -1,29 +1,39 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-extract.mjs
-  crc: 26bb2901
+  crc: 1592076b
+  score: 100
 ---
 
-# docgen-extract
+# docgen-extract.mjs
 
 ## Огляд
 
-Детермінований екстрактор фактів про кодовий файл (нуль токенів): з тексту джерела збирається факт-лист, на якому конвеєр будує промпти, маркери поведінки й список заборонених до згадки внутрішніх імен.
+Файл витягує факти про конфігурацію та структуру проекту. Визначає мову та заголовок файлу. Витягує публічні експорти та імпорти з різних джерел. Витягує внутрішні та локальні символи. Документація перевіряє наявність операцій запису, обробки помилок, повернення хибних значень при невдачах, мережевих викликів, механізмів кешування та пропуск певних шляхів.
 
 ## Поведінка
 
-1. Провідний блок-коментар файлу (до першого коду) стає «наміром файлу»; з документувальних коментарів перед кожним експортом витягуються опис, параметри та опис повернення, відкидаючи беззмістовні заглушки.
-2. Збираються всі експортовані оголошення з безпосередньо передуючими їм коментарями.
-3. Імпорти класифікуються на stdlib / npm / внутрішні; імена символів, імпортованих із внутрішніх модулів, складають список internalSymbols — модель не має згадувати їх у доці, а скорер штрафує за витік.
-4. Маркери поведінки визначаються евристиками по тексту: read-only (немає запису у файлову систему), перехоплення помилок, повернення false/null при невдачі, звертання до мережі, кешування, свідомі пропуски шляхів.
-5. Для розширень поза js/mjs/ts повертається позначка unsupported — конвеєр переходить на one-shot-шлях.
+1. Витягується факт про файл.
+2. Визначається мова файлу.
+3. Витягується заголовок файлу.
+4. Витягуються публічні експорти.
+5. Витягуються імпорти, класифіковані за джерелом.
+6. Витягуються внутрішні символи, імпортовані з внутрішніх модулів.
+7. Витягуються локальні символи, неекспортовані функції.
+8. Визначаються евристичні маркери.
+    * readOnly: перевірка на наявність операцій запису.
+    * catchesErrors: перевірка на наявність обробки помилок.
+    * returnsFalsyOnFail: перевірка на повернення хибних значень при невдачах.
+    * network: перевірка на наявність мережевих викликів.
+    * caches: перевірка на наявність механізмів кешування.
+    * skips: пропуск шляхів .github, .git, node_modules, base/, ua/, .firebase.
 
 ## Публічний API
 
-- `extractFacts` — головна точка: текст джерела + шлях → факт-лист `{header, exports, imports, internalSymbols, markers}` або `{unsupported: true}`.
+extractFacts — код файлу перетворює на список фактів
 
 ## Гарантії поведінки
 
-- Повністю детермінований: однаковий вхід → однаковий факт-лист; жодних LLM-викликів і мережі.
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Евристики свідомо толерують надлишок (зайвий маркер — менша проблема, ніж пропущений).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.

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

@@ -1,25 +1,35 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-files-batch.mjs
-  crc: 20a14675
+  crc: 5c9b8d72
+  score: 95
 ---
 
-# docgen-files-batch
+# docgen-files-batch.mjs
 
 ## Огляд
 
-CLI-оркестратор масової генерації файлових док (`doc-files gen` / `doc-files stamp`): черга, вибір цілей, preflight локального сервера, запис док зі свіжою контрольною сумою і degraded-маркером. Уся важка робота живе тут, а не в контексті агента.
+runDocFilesGenCli
+Запускає генерацію документації для застарілих або відсутніх файлів.
+
+runDocFilesStampCli
+Перештампує frontmatter джерело та CRC у наявних документах без виклику LLM.
 
 ## Поведінка
 
-1. Дерево проєкту сканується, цілі обираються за режимом: за замовчуванням — застарілі доки; `--overwrite` — усі; `--retry-degraded` — свіжі за сумою, але з оцінкою нижче порогу. Зріз великого прогону — `--from N --limit M`.
-2. Перед генерацією — preflight локального сервера: «сервер лежить», «модель не влазить у пам'ять зайнятої машини» чи «потрібен API-ключ» зупиняють прогін одним зрозумілим повідомленням замість лавини помилок по файлах.
-3. Кожна ціль генерується локальним конвеєром; дока пишеться поряд із джерелом у `docs/` зі свіжою сумою. Якщо оцінка нижча за поріг — у frontmatter додаються оцінка й коди проблем, файл рахується як degraded.
-4. Підсумок: кількість успішних, degraded і помилкових файлів; за наявності degraded — підказка про `--retry-degraded`. Помилка хоча б одного файлу → exit-код `1`.
-5. `stamp` детерміновано перештамповує frontmatter у наявних доках без LLM (міграція док без суми), зберігаючи наявні поля якості.
+runDocFilesGenCli
+Запускає генерацію документації для застарілих/відсутніх док.
+
+runDocFilesStampCli
+Перештампує frontmatter source+crc у наявних доках без виклику LLM.
+
+## Публічний API
+
+- runDocFilesGenCli — згенерувати документацію для застарілих/відсутніх док.
+- runDocFilesStampCli — детерміновано (пере)штампувати frontmatter `source`+`crc` у наявних доках без виклику LLM. Для міграції док, які ще не мають CRC. Поля якості (`score`/`issues`) зберігаються з наявного frontmatter.
 
 ## Гарантії поведінки
 
-- Жодних хмарних викликів: збій локальної генерації стає помилкою чи degraded-маркером, а не ескалацією.
-- Доки пишуться атомарно по файлу: успішні цілі не відкочуються через подальші збої.
-- Прогін ніколи не комітить — рішення про фіксацію приймає користувач.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.