@nitra/cursor 3.26.0 → 3.28.0

package/skills/docgen/js/docgen-gen.mjs

@@ -1,31 +1,37 @@
-/**
- * docgen-конвеєр (входна точка): код файлу → .md-документація.
- *
- * Інверсія керування: веде цей JS, а локальна модель — лише сервіс перефразування.
- *   Stage 0  extractFacts        — факти з коду (0 токенів)
- *   Stage 1  sectionInstructions — точкові промпти на кожну секцію (спільний KV-cached префікс)
- *   Stage 3  assemble            — фіксовані заголовки/порядок + зрізання fence
- * Режим `--oneshot` — база для порівняння (один промпт на весь документ).
- */
+/** @see ./docs/docgen-gen.md */
 import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import { request } from 'node:http'
+import { env } from 'node:process'
+import Anthropic from '@anthropic-ai/sdk'
 import { extractFacts } from './docgen-extract.mjs'
-import { sectionMessages, oneShotMessages } from './docgen-prompts.mjs'
+import { sectionMessages, oneShotMessages, STYLE, oneShotPromptText } from './docgen-prompts.mjs'
+
+const QUALITY_THRESHOLD = 70
 
 /** Один виклик чату до ollama зі streaming (токени стримуються → socket активний, жодного timeout). */
 async function ollamaChat(messages, { model, numPredict = 600 }) {
   const body = JSON.stringify({
-    model, messages, stream: true, think: false,
+    model,
+    messages,
+    stream: true,
+    think: false,
     options: { num_ctx: 8192, temperature: 0.2, num_predict: numPredict },
     keep_alive: '15m'
   })
   return new Promise((resolve, reject) => {
     const req = request(
-      { hostname: 'localhost', port: 11434, path: '/api/chat', method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } },
-      (res) => {
-        let text = '', genTok = 0, buf = ''
+      {
+        hostname: 'localhost',
+        port: 11434,
+        path: '/api/chat',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }
+      },
+      res => {
+        let text = '',
+          genTok = 0,
+          buf = ''
         res.on('data', chunk => {
           buf += chunk.toString()
           const lines = buf.split('\n')
@@ -36,7 +42,9 @@ async function ollamaChat(messages, { model, numPredict = 600 }) {
               const j = JSON.parse(line)
               text += j.message?.content ?? ''
               if (j.done) genTok = j.eval_count ?? 0
-            } catch { /* partial line */ }
+            } catch {
+              /* partial line */
+            }
           }
         })
         res.on('end', () => resolve({ text, genTok }))
@@ -53,7 +61,10 @@ async function ollamaChat(messages, { model, numPredict = 600 }) {
 function stripSection(text) {
   let t = text.trim()
   if (t.startsWith('```')) {
-    t = t.replace(/^```[a-z]*\n?/, '').replace(/\n?```\s*$/, '').trim()
+    t = t
+      .replace(/^```[a-z]*\n?/, '')
+      .replace(/\n?```\s*$/, '')
+      .trim()
   }
   t = t.replace(/^#{1,6}\s+.*\n+/, '') // зрізати випадковий заголовок
   return t.trim()
@@ -70,6 +81,131 @@ function stripSignatures(text) {
   return t
 }
 
+/** Розбиває md на секції за ## заголовками → { огляд, поведінка, api, гарантіїповедінки, … } */
+function parseSections(md) {
+  const result = {}
+  let cur = null
+  for (const line of md.split('\n')) {
+    const m = line.match(/^##\s+(.+)/)
+    if (m) {
+      cur = m[1].toLowerCase().replace(/[^а-яіїєґa-z0-9]/gi, '')
+      result[cur] = ''
+    } else if (cur) result[cur] += line + '\n'
+  }
+  return result
+}
+
+/**
+ * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
+ * @returns {{ score: number, issues: string[] }}
+ */
+function scoreDoc(md, facts) {
+  const s = parseSections(md)
+  let score = 100
+  const issues = []
+
+  if (!s['огляд']) {
+    score -= 25
+    issues.push('no-overview')
+  }
+
+  const behavior = s['поведінка'] ?? ''
+  if (behavior.length < 60) {
+    score -= 20
+    issues.push('short-behavior')
+  }
+
+  const guarantees = s['гарантіїповедінки'] ?? ''
+  // Будь-яка згадка "кеш" у Гарантіях коли файл не кешує — галюцинація
+  // Негація: "не кешує", "не має кешування", "без кешування", "немає кешу"
+  const cacheHit = /кеш/i.test(guarantees) && !/(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i.test(guarantees)
+  if (!facts.markers?.caches && cacheHit) {
+    score -= 20
+    issues.push('cache-hallucination')
+  }
+
+  // Перевіряємо лише бектік-обгорнуті імена (`sym`) — уникаємо substring false positives
+  const hasName = (text, sym) => text.includes('`' + sym + '`')
+  for (const sym of facts.internalSymbols ?? []) {
+    const inDoc = hasName(guarantees, sym) || hasName(s['огляд'] ?? '', sym) || hasName(s['поведінка'] ?? '', sym)
+    if (inDoc) {
+      score -= 10
+      issues.push(`internal-name:${sym}`)
+    }
+  }
+
+  return { score: Math.max(0, score), issues }
+}
+
+const SCORE_RUBRIC = `Оціни якість документації для JavaScript-модуля за 4 критеріями (1-3 кожен):
+
+- огляд: 3=описує роль модуля в системі (ЩО і НАВІЩО); 2=частково розмитий; 1=відсутній або перераховує функції
+- поведінка: 3=бізнес-терміни, без деталей реалізації; 2=деякі impl-деталі; 1=переважно реалізація або відсутня
+- гарантії: 3=лише реальні інваріанти підтверджені кодом, без галюцинацій; 2=частково правильні; 1=вигадані або відсутні
+- стиль: 3=без сигнатур/internal-імен, правильна markdown-структура; 2=дрібні порушення; 1=сигнатури/internal-імена/відсутні заголовки
+
+Відповідай ТІЛЬКИ JSON без пояснень:
+{"огляд":N,"поведінка":N,"гарантії":N,"стиль":N,"issues":["коротко про кожен мінус 1-5 слів"]}`
+
+/**
+ * Stage 2.5 cloud: Claude Haiku оцінює якість доку проти коду + фактів.
+ * Використовує найдешевшу хмарну модель — haiku — для мінімальної вартості судді.
+ * @returns {{ score: number, scores: object, issues: string[], tok: number }}
+ */
+async function cloudScoreDoc(md, facts, src, model = 'claude-haiku-4-5-20251001') {
+  const client = new Anthropic()
+  const factsTxt = [
+    facts.exports?.length ? `Публічні функції: ${facts.exports.map(e => e.name).join(', ')}` : '',
+    facts.internalSymbols?.length ? `Внутрішні (не публічні): ${facts.internalSymbols.join(', ')}` : '',
+    facts.markers?.caches ? 'Кешування: є' : 'Кешування: немає',
+    facts.markers?.network ? 'Мережа: є' : 'Мережа: немає',
+    facts.markers?.readOnly ? 'Read-only (не змінює файли/стан)' : ''
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  const msg = await client.messages.create({
+    model,
+    max_tokens: 256,
+    system: SCORE_RUBRIC,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: `ФАКТИ:\n${factsTxt}`, cache_control: { type: 'ephemeral' } },
+          { type: 'text', text: `КОД:\n\`\`\`\n${src.slice(0, 4000)}\n\`\`\``, cache_control: { type: 'ephemeral' } },
+          { type: 'text', text: `ДОКУМЕНТАЦІЯ:\n${md}` }
+        ]
+      }
+    ]
+  })
+  const tok = (msg.usage?.input_tokens ?? 0) + (msg.usage?.output_tokens ?? 0)
+  try {
+    const j = JSON.parse(msg.content[0]?.text ?? '{}')
+    const total = (((j.огляд ?? 0) + (j.поведінка ?? 0) + (j.гарантії ?? 0) + (j.стиль ?? 0)) / 12) * 100
+    return { score: Math.round(total), scores: j, issues: j.issues ?? [], tok }
+  } catch {
+    return { score: 50, scores: {}, issues: ['parse-error'], tok }
+  }
+}
+
+/** Tier 2: хмарний fallback через Claude коли local-score < QUALITY_THRESHOLD. */
+async function claudeOneShot(facts, src, model = 'claude-sonnet-4-6') {
+  const client = new Anthropic()
+  const prompt = oneShotPromptText(facts, src)
+  const msg = await client.messages.create({
+    model,
+    max_tokens: 1500,
+    system: STYLE,
+    messages: [{ role: 'user', content: prompt }]
+  })
+  const text = msg.content[0]?.text ?? ''
+  const genTok = msg.usage?.output_tokens ?? 0
+  let md = stripSignatures(stripSection(text))
+  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
+  return { md: md + '\n', genTok }
+}
+
 /** Stage 3: фіксовані заголовки у фіксованому порядку. */
 function assemble(stem, sections) {
   const order = [
@@ -106,28 +242,120 @@ async function generateOneShot(facts, src, model) {
   return { md: md + '\n', genTok }
 }
 
-/** Головний API: файл → { md, genTok, ms }. */
-export async function generateDoc(file, { model = 'gemma3:4b', mode = 'orchestrated' } = {}) {
+/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без локального проходу). */
+const DEFAULT_SYM_THRESHOLD = 4
+/** Максимальний час локальної генерації на один файл перед ескалацією у Tier 2. */
+const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
+
+/** Повертає promise, що відхиляється через `ms` мс з повідомленням про timeout. */
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error(`local timeout after ${ms / 1000}s`)), ms))
+  ])
+}
+
+/**
+ * Головний API: файл → { md, genTok, ms, score, issues, tier }.
+ *
+ * Routing (sym-threshold):
+ *   sym < symThreshold  → Tier 1 local (timeout: LOCAL_TIMEOUT_MS) + det-scorer
+ *                       → timeout або det-score < threshold → Tier 2
+ *   sym >= symThreshold → Pre-routing одразу Tier 2
+ *
+ * @param {string}  cloudModel    — модель для Tier 2 генерації (Sonnet за замовч.)
+ */
+export async function generateDoc(
+  file,
+  {
+    model = 'gemma3:4b',
+    mode = 'orchestrated',
+    cloudModel = 'claude-sonnet-4-6',
+    threshold = QUALITY_THRESHOLD,
+    symThreshold = DEFAULT_SYM_THRESHOLD
+  } = {}
+) {
   const src = readFileSync(file, 'utf8')
   const facts = extractFacts(src, file)
   const t0 = Date.now()
-  const r = facts.unsupported
-    ? await generateOneShot(facts, src, model) // fallback для не-JS
-    : mode === 'oneshot'
-      ? await generateOneShot(facts, src, model)
-      : await generateOrchestrated(facts, src, model)
-  return { ...r, ms: Date.now() - t0 }
+
+  // Pre-routing: складні файли (sym ≥ symThreshold) → одразу Tier 2, не витрачаємо local-час
+  const complexity = facts.internalSymbols?.length ?? 0
+  if (complexity >= symThreshold && env.ANTHROPIC_API_KEY) {
+    const r2 = await claudeOneShot(facts, src, cloudModel)
+    return {
+      ...r2,
+      ms: Date.now() - t0,
+      score: null,
+      issues: [`pre-routed:sym=${complexity}`],
+      tier: 2,
+      model: cloudModel
+    }
+  }
+
+  // Tier 1: локальна генерація з timeout 5 хв — при перевищенні одразу Tier 2
+  let r
+  try {
+    const localPromise =
+      facts.unsupported || mode === 'oneshot'
+        ? generateOneShot(facts, src, model)
+        : generateOrchestrated(facts, src, model)
+    r = await withTimeout(localPromise, LOCAL_TIMEOUT_MS)
+  } catch (e) {
+    if (env.ANTHROPIC_API_KEY) {
+      const r2 = await claudeOneShot(facts, src, cloudModel)
+      return {
+        ...r2,
+        ms: Date.now() - t0,
+        score: null,
+        issues: [`local-timeout: ${e.message}`],
+        tier: 2,
+        model: cloudModel
+      }
+    }
+    throw e
+  }
+
+  // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
+  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+
+  if (detScore < threshold && env.ANTHROPIC_API_KEY) {
+    const r2 = await claudeOneShot(facts, src, cloudModel)
+    return { ...r2, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 2, model: cloudModel }
+  }
+
+  return { ...r, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 1, model }
 }
 
-// CLI: node docgen-gen.mjs <file> [--oneshot] [--model <m>]
+// CLI: node docgen-gen.mjs <file> [--oneshot] [--model <m>] [--sym-threshold N] [--tier-only]
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 if (isRunAsCli(import.meta.url)) {
   const args = process.argv.slice(2)
   const file = args.find(a => !a.startsWith('--'))
   const mode = args.includes('--oneshot') ? 'oneshot' : 'orchestrated'
-  const mi = args.indexOf('--model'); const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
-  if (!file) { console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--model <m>]'); process.exit(1) }
-  const r = await generateDoc(file, { model, mode })
-  process.stderr.write(`[${mode}] ${r.ms}ms / ${r.genTok} tok\n`)
+  const tierOnly = args.includes('--tier-only')
+  const mi = args.indexOf('--model')
+  const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
+  const si = args.indexOf('--sym-threshold')
+  const symThreshold = si >= 0 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
+  if (!file) {
+    console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--model <m>] [--sym-threshold N] [--tier-only]')
+    process.exit(1)
+  }
+  if (tierOnly) {
+    const src = readFileSync(file, 'utf8')
+    const facts = extractFacts(src, file)
+    const sym = facts.internalSymbols?.length ?? 0
+    const icon = sym >= symThreshold ? '☁️ ' : '💻'
+    const label =
+      sym >= symThreshold
+        ? `Tier 2 cloud   (sym=${sym} ≥ ${symThreshold}, pre-routed)`
+        : `Tier 1 local   (sym=${sym} < ${symThreshold})`
+    process.stdout.write(`${icon} ${label}  |  ${file}\n`)
+    process.exit(0)
+  }
+  const r = await generateDoc(file, { model, mode, symThreshold })
+  const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
+  process.stderr.write(`[tier${r.tier} ${mode}] ${r.ms}ms / ${r.genTok} tok / score=${r.score}${issuesTxt}\n`)
   process.stdout.write(r.md)
 }

package/skills/docgen/js/docgen-ignore.mjs

@@ -1,9 +1,4 @@
-/**
- * Глоби, які `docgen` завжди ігнорує.
- *
- * Це окремий snippet-модуль: список правиться тут, scanner лише читає його
- * через predicate. Патерни пишуться в posix-формі відносно кореня проєкту.
- */
+/** @see ./docs/docgen-ignore.md */
 import picomatch from 'picomatch'
 
 /** Базовий список glob-ів для `docgen` ignore. */
@@ -20,7 +15,9 @@ export const DOCGEN_IGNORE_GLOBS = Object.freeze([
   '.worktrees/**',
   '**/benchmarks/**',
   '**/demo/**',
-  '**/docs/**'
+  '**/docs/**',
+  'npm/reports/**',
+  'npm/bin/**'
 ])
 
 const IGNORE_MATCHERS = DOCGEN_IGNORE_GLOBS.map(glob => picomatch(glob, { dot: true }))

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

@@ -1,12 +1,6 @@
-/**
- * Stage 1 docgen-конвеєра: факт-лист + код → точкові промпти на кожну секцію.
- *
- * v2 — СЕКЦІЙНО-МІНІМАЛЬНИЙ контекст: код іде ЛИШЕ у `Поведінку`. `Огляд` бере тільки
- * header, `API` — лише список експортів, `Гарантії` — лише markers. Так інгест коду
- * оплачується один раз (а не на кожну секцію), і оркестрація перестає програвати в часі.
- */
+/** @see ./docs/docgen-prompts.md */
 
-const STYLE = [
+export const STYLE = [
   'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
   'Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.',
   'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
@@ -28,7 +22,10 @@ function factsSummary(facts) {
   return lines.join('\n')
 }
 
-const msgs = (system, user) => [{ role: 'system', content: system }, { role: 'user', content: user }]
+const msgs = (system, user) => [
+  { role: 'system', content: system },
+  { role: 'user', content: user }
+]
 
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
@@ -42,33 +39,45 @@ export function sectionMessages(facts, src) {
 
   // Огляд — лише факти (без коду)
   out.push({
-    key: 'overview', numPredict: 220,
-    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
-      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій.')
+    key: 'overview',
+    numPredict: 220,
+    messages: msgs(
+      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій.'
+    )
   })
 
   // Поведінка — ЄДИНА секція, якій потрібен код
   out.push({
-    key: 'behavior', numPredict: 500,
-    messages: msgs(`${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
-      `Напиши вміст секції «Поведінка»: ${multi ? 'для кожної публічної функції — один короткий пункт «що вона робить»' : 'нумерований алгоритм у бізнес-термінах'}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${facts.internalSymbols?.length ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.` : ''} Без заголовка.`)
+    key: 'behavior',
+    numPredict: 500,
+    messages: msgs(
+      `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      `Напиши вміст секції «Поведінка»: ${multi ? 'для кожної публічної функції — один короткий пункт «що вона робить»' : 'нумерований алгоритм у бізнес-термінах'}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${facts.internalSymbols?.length ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.` : ''} Без заголовка.`
+    )
   })
 
   // API — лише список експортів (без коду)
   if (multi || facts.exports?.some(e => e.desc)) {
     const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
     out.push({
-      key: 'api', numPredict: 320,
-      messages: msgs(STYLE,
-        `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка.`)
+      key: 'api',
+      numPredict: 320,
+      messages: msgs(
+        STYLE,
+        `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка.`
+      )
     })
   }
 
   // Гарантії — лише markers (без коду)
   out.push({
-    key: 'guarantees', numPredict: 300,
-    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
-      'Напиши вміст секції «Гарантії поведінки» як маркери-інваріанти СУВОРО на основі ВІДОМИХ ФАКТІВ (read-only, fail-safe, пропуски). Згадуй кеш ЛИШЕ якщо у фактах прямо є «Кешує». Без сигнатур у дужках і без імен внутрішніх структур/Map-ів/кешів. Не вигадуй гарантій, яких немає у фактах. Без заголовка.')
+    key: 'guarantees',
+    numPredict: 300,
+    messages: msgs(
+      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Гарантії поведінки» як маркери-інваріанти СУВОРО на основі ВІДОМИХ ФАКТІВ (read-only, fail-safe, пропуски). Згадуй кеш ЛИШЕ якщо у фактах прямо є «Кешує». Без сигнатур у дужках і без імен внутрішніх структур/Map-ів/кешів. Не вигадуй гарантій, яких немає у фактах. Без заголовка.'
+    )
   })
 
   return out
@@ -77,6 +86,14 @@ export function sectionMessages(facts, src) {
 /** One-shot messages (база для порівняння). */
 export function oneShotMessages(facts, src) {
   const multi = (facts.exports?.length || 0) > 1
-  return msgs(STYLE,
-    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``)
+  return msgs(
+    STYLE,
+    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
+  )
+}
+
+/** Лише текст user-промпту для one-shot (для хмарного fallback через Anthropic SDK). */
+export function oneShotPromptText(facts, src) {
+  const multi = (facts.exports?.length || 0) > 1
+  return `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
 }

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

@@ -1,11 +1,4 @@
-/**
- * docgen scanner — детермінований обхід проєкту для скілу `docgen`.
- *
- * Друкує JSON-список кодових файлів із відносними `sourcePath`/`docPath`
- * (тека `docs/` поряд із джерелом). Рішення про overwrite/skip приймає скіл —
- * scanner лише лістить і ставить прапор `exists`. LLM/мережі тут немає: уся
- * генерація доки — у субагентах скілу.
- */
+/** @see ./docs/docgen-scan.md */
 // eslint-disable-next-line unicorn/import-style
 import path from 'node:path'
 import { existsSync, readdirSync, statSync } from 'node:fs'

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

@@ -0,0 +1,28 @@
+# docgen-extract.mjs
+
+## Огляд
+
+Файл `extractFacts` витягує інформацію про поведінку коду, формуючи об'єкт "факт-лист". Цей факт-лист використовується Stage 1 docgen-конвеєра для створення точкових промптів. Функція є ключовою частиною детермінованого процесу генерації документації, виключаючи використання великих мовних моделей.
+
+## Поведінка
+
+1.  **Обробка даних:** Система аналізує код, витягуючи інформацію про експортовані функції, імпорти та їхні описи.
+2.  **Ідентифікація відхилень:** Система визначає, чи використовується код для виконання операцій, які можуть призвести до помилок, наприклад, запис у файли, створення директорій, видалення файлів, обробка мережевих запитів або використання try/catch блоків.
+3.  **Виявлення пропущених шляхів:** Система виявляє, чи використовується код для обробки певних шляхів файлів, таких як `.github`, `.git`, `node_modules` або `base/`, `ua/`, `.firebase`.
+4.  **Визначення кешування:** Система визначає, чи використовується код для кешування даних, наприклад, за допомогою Map або Cache.
+5.  **Визначення відсутності обробки помилок:** Система визначає, чи використовується код для обробки помилок, наприклад, за допомогою try/catch блоків.
+6.  **Визначення мережевих операцій:** Система визначає, чи використовується код для виконання мережевих операцій, наприклад, за допомогою fetch або axios.
+7.  **Вихідні дані:** Система надає вихідні дані у вигляді об'єкта, що містить витягнуту інформацію про код, а також виявлені відхилення та пропущені шляхи.
+
+## Публічний API
+
+extractFacts — Витягує факти з коду файлу, представляючи їх у вигляді списку.
+
+## Гарантії поведінки
+
+- Екстрагує з коду список фактів.
+- Повертає об'єкт з витягнутими фактами.
+- Не викликає винятків при невдачі.
+- Кешує результати для одного прогону.
+- Не використовує мережу.
+- Не обробляє файли/каталоги .github, .git, node_modules, base/, ua/, .firebase.

package/skills/docgen/js/docs/docgen-gen.md

@@ -0,0 +1,41 @@
+# docgen-gen.mjs
+
+## Огляд
+
+Цей файл генерує документацію на основі коду, використовуючи конвеєр обробки. Він автоматично створює Markdown-файли, що містять опис коду, використовуючи декілька етапів, включаючи вилучення фактів та створення текстових описів. Ця функція є ключовою частиною системи документування, забезпечуючи автоматизований та послідовний процес створення документації.
+
+## Поведінка
+
+1.  Модуль визначає основну функцію `generateDoc`, яка приймає код джерела та налаштовує параметри для генерації документації.
+2.  Вхідний код обробляється для вилучення ключових фактів про функціональність модуля, включаючи назви функцій та їх призначення.
+3.  Вилучені факти використовуються для оцінки якості документації, зокрема, перевіряється, чи опис відповідає реальній поведінці модуля.
+4.  Оцінка якості здійснюється за допомогою декількох критеріїв: опис має бути чітким та описовим, а поведінка – узгодженою з кодом.
+5.  Якщо оцінка якості низька, використовується хмарний сервіс Claude для перевірки документації та надання рекомендацій щодо покращення.
+6.  У випадку, коли оцінка якості висока, генерується документ, який містить огляд модуля, його поведінку, API та гарантії поведінки.
+7.  Документація форматується у Markdown, з використанням фіксованого набору заголовків та розділів.
+8.  Під час генерації документації враховуються можливі пропуски в інформації про шляхи, що може вплинути на оцінку якості.
+9.  Використовується хмарний сервіс Claude для оцінки якості документації та надання рекомендацій щодо покращення.
+10. Генерується документ, який містить огляд модуля, його поведінку, API та гарантії поведінки.
+
+## Публічний API
+
+- generateDoc — Генерує документацію з файлу, включаючи метадані, токени, оцінки, проблеми та рівень.
+- Routing (sym-threshold) — Розподіляє обробку на основі значення символу, визначаючи рівень (Tier) та тип рефері (Haiku або без хмарного рефері).
+  - sym < BORDERLINE_SYM_LOW — Tier 1 без хмарного рефері.
+  - sym ∈ [BORDERLINE_SYM_LOW, symThreshold) — Tier 1 з хмарним рефері (Haiku).
+  - sym >= symThreshold — Відразу Tier 2.
+  - scoreCloud=true — Автоматично запускає хмарний рефері для всіх Tier 1.
+
+## Гарантії поведінки
+
+- Конвеєр завжди генерує .md-документацію на основі вхідного коду.
+- Конвеєр використовує інверсію керування, де JS-код визначає весь процес.
+- Stage 0 (extractFacts) не впливає на вихідну документацію.
+- Stage 1 (sectionInstructions) генерує точкові промпти для кожної секції коду.
+- Stage 2 (stripSignatures) завжди видаляє інформацію про сигнатури.
+- Stage 2.5 (scoreDoc) оцінює документацію за фактами.
+- Stage 3 (assemble) збирає документацію з фіксованими заголовками та порядком.
+- При низькому балі скорингу (claudeOneShot) використовується хмарний сервіс для перефразування.
+- При сим-значенні нижче BORDERLINE_SYM_LOW, документація генерується локально без використання хмарного рефері.
+- При сим-значенні між BORDERLINE_SYM_LOW та DEFAULT_SYM_THRESHOLD, документація генерується локально та оцінюється за допомогою cloudScoreDoc (Haiku).
+- При сим-значенні, що перевищує DEFAULT_SYM_THRESHOLD, документація генерується безпосередньо, без локальної оцінки

package/skills/docgen/js/docs/docgen-ignore.md

@@ -0,0 +1,24 @@
+# docgen-ignore.mjs
+
+## Огляд
+
+Цей файл містить список глобальних файлів, які `docgen` ігнорує під час генерації документації. Він використовується для визначення, які файли не потрібно аналізувати, забезпечуючи ефективність процесу генерації та запобігаючи включенню нерелевантної інформації. Цей список є основою для predicate, який scanner використовує для визначення, чи потрібно читати певний файл.
+
+## Поведінка
+
+DOCGEN_IGNORE_GLOBS: визначає список глобів, які `docgen` ігнорує.
+isDocgenIgnored: перевіряє, чи шлях має бути пропущений `docgen`, використовуючи глоби.
+
+## Публічний API
+
+- DOCGEN_IGNORE_GLOBS — Список glob-ів, які ігнорує `docgen`.
+- isDocgenIgnored — Перевіряє, чи потрібно пропустити шлях під час генерації документації.
+
+## Гарантії поведінки
+
+- `DOCGEN_IGNORE_GLOBS` завжди ігнорує певний набір шляхів.
+- `isDocgenIgnored` повертає `true` якщо шлях ігнорується.
+- Шляхи `.git` та `node_modules` завжди ігноруються.
+- Файл є read-only.
+- У разі невдачі повертає `false` або `null`.
+- Результат прогону кешується для подальшого використання.

package/skills/docgen/js/docs/docgen-prompts.md

@@ -0,0 +1,24 @@
+# docgen-prompts.mjs
+
+## Огляд
+
+Цей файл містить опис коду для конвеєра docgen. Він визначає точкові промпти для кожної секції коду, що генерується. Це дозволяє ефективно генерувати документацію на основі коду.
+
+## Поведінка
+
+Напиши вміст секції «Поведінка»: для кожної публічної функції — один короткий пункт «що вона робить». Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex. Без заголовка.
+
+## Публічний API
+
+- STYLE — Підготовка документації на першому етапі генерації: створення факт-листа та коду, а потім генерація точкових промптів для кожної секції.
+- v2 — Мінімальний контекст секції: код розміщується лише в `Поведінку`. `Огляд` містить лише заголовок, `API` – список експортів, `Гарантії` – маркери. Це дозволяє один раз обробити інсульт коду, а не секцію за секцією.
+- sectionMessages — Набори повідомлень для кожної секції з мінімальним контекстом. Код розміщується лише в `Поведінку`, решта – на факт-листи.
+- oneShotMessages — База повідомлень для порівняння.
+- oneShotPromptText — Текст user-промпту для one-shot (для резервного копіювання в хмарі через Anthropic SDK).
+
+## Гарантії поведінки
+
+- `docgen-конвеєр` кешує результати генерації промптів для кожної секції.
+- `Огляд` містить лише заголовок секції.
+- `API` містить лише список експортів секції.
+- `Гарантії` містять лише маркери.