@nitra/cursor 3.25.1 → 3.27.0

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

@@ -0,0 +1,158 @@
+/**
+ * Stage 0 docgen-конвеєра: детермінована екстракція «факт-листа» з коду (0 токенів LLM).
+ *
+ * Ідея: винести з-під локальної моделі все, що вона псує (імена експортів, stdlib-vs-internal,
+ * крайові деталі поведінки), і віддати їй лише перефразування вже відомих фактів. Тут — суто
+ * парсинг JS/MJS регулярками: жодних мереж, LLM чи запису.
+ *
+ * Повертає об'єкт-факт-лист, який Stage 1 (docgen-prompts) перетворює на точкові промпти.
+ */
+
+const BUILTIN_MODULES = new Set([
+  'fs', 'path', 'crypto', 'os', 'util', 'stream', 'events', 'http', 'https',
+  'url', 'child_process', 'process', 'assert', 'buffer', 'zlib', 'readline'
+])
+
+/** Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками. */
+function cleanJsDoc(raw) {
+  return raw
+    .replace(/^\s*\/\*\*?/, '')
+    .replace(/\*\/\s*$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/** Опис (без @-тегів) + параметри з @param як «name — опис». */
+function parseJsDoc(raw) {
+  const text = cleanJsDoc(raw)
+  const lines = text.split('\n')
+  const descLines = []
+  const params = []
+  let ret = ''
+  for (const l of lines) {
+    const pm = l.match(/^@param\s+(?:\{[^}]*\}\s+)?\[?([A-Za-z0-9_.]+)\]?\s*(.*)$/)
+    const rm = l.match(/^@returns?\s+(?:\{[^}]*\}\s+)?(.*)$/)
+    if (pm) {
+      const desc = pm[2].trim()
+      // «опис.» — JSDoc-заглушка без сенсу; не тягнемо її як факт
+      params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
+      continue
+    }
+    if (rm) { ret = rm[1].trim(); continue }
+    if (l.startsWith('@')) continue
+    descLines.push(l)
+  }
+  return { desc: descLines.join('\n').trim(), params, ret }
+}
+
+/** Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом. */
+function extractFileHeader(src) {
+  const m = src.match(/^\s*\/\*\*([\s\S]*?)\*\//)
+  if (!m) return ''
+  // має бути на самому початку (до import/код)
+  if (src.slice(0, m.index).trim() !== '') return ''
+  return parseJsDoc(m[0]).desc
+}
+
+/**
+ * Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
+ * `(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
+ * найближчий блок — без жадібного «перестрибування» через імпорти/код.
+ */
+function precedingJsDoc(prefix) {
+  const m = prefix.match(/\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/)
+  return m ? m[0] : null
+}
+
+/** Експорти + JSDoc, що безпосередньо передує кожному. */
+function extractExports(src) {
+  const out = []
+  const re = /export\s+(?:async\s+)?(function|const|class)\s+([A-Za-z0-9_]+)/g
+  let m
+  while ((m = re.exec(src))) {
+    const [, kind, name] = m
+    const jsdocRaw = precedingJsDoc(src.slice(0, m.index))
+    out.push({ name, kind, ...(jsdocRaw ? parseJsDoc(jsdocRaw) : { desc: '', params: [], ret: '' }) })
+  }
+  return out
+}
+
+/** Імпорти, класифіковані на stdlib / npm / internal. */
+function extractImports(src) {
+  const stdlib = new Set(), npm = new Set(), internal = new Set()
+  const re = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
+  let m
+  while ((m = re.exec(src))) {
+    const s = m[1]
+    if (s.startsWith('node:') || BUILTIN_MODULES.has(s.split('/')[0])) stdlib.add(s.replace(/^node:/, ''))
+    else if (s.startsWith('.') || s.startsWith('/')) internal.add(s)
+    else npm.add(s)
+  }
+  return { stdlib: [...stdlib], npm: [...npm], internal: [...internal] }
+}
+
+/** Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати. */
+function extractInternalSymbols(src) {
+  const out = new Set()
+  const re = /import\s+(?:([A-Za-z0-9_$]+)\s*,?\s*)?(?:\{([^}]+)\})?\s+from\s+['"](\.[^'"]+)['"]/g
+  let m
+  while ((m = re.exec(src))) {
+    if (m[1]) out.add(m[1].trim())
+    if (m[2]) for (const n of m[2].split(',')) {
+      const name = n.replace(/\s+as\s+.*/, '').trim()
+      if (name) out.add(name)
+    }
+  }
+  return [...out]
+}
+
+/** Поведінкові маркери — евристики регулярками. */
+function extractMarkers(src) {
+  // помітні «пропуски»: dir/segment-літерали у фільтрах
+  const skips = new Set()
+  for (const lit of ['.github', '.git', 'node_modules', 'base/', 'ua/', '.firebase']) {
+    if (src.includes(`'${lit}`) || src.includes(`"${lit}`) || src.includes(`/${lit}`)) skips.add(lit)
+  }
+  return {
+    readOnly: !/\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/.test(src),
+    catchesErrors: /catch\s*\(/.test(src) || /\btry\s*\{/.test(src),
+    returnsFalsyOnFail: /return\s+(false|null|''|"")/.test(src),
+    network: /\bfetch\(|https?\.|axios|got\(/.test(src),
+    caches: /new Map\(\)|Cache|cache/.test(src),
+    skips: [...skips]
+  }
+}
+
+/**
+ * Головний екстрактор: код файлу → факт-лист.
+ * @param {string} src вміст файлу
+ * @param {string} relPath шлях (для контексту/мови екстрактора)
+ * @returns {{relPath:string, lang:string, header:string, exports:Array, imports:object, markers:object}}
+ */
+export function extractFacts(src, relPath) {
+  const lang = relPath.split('.').pop()
+  if (!['js', 'mjs', 'ts'].includes(lang)) {
+    return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
+  }
+  return {
+    relPath,
+    lang,
+    header: extractFileHeader(src),
+    exports: extractExports(src),
+    imports: extractImports(src),
+    internalSymbols: extractInternalSymbols(src),
+    markers: extractMarkers(src)
+  }
+}
+
+// CLI для інспекції: node docgen-extract.mjs <file>
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { readFileSync } from 'node:fs'
+if (isRunAsCli(import.meta.url)) {
+  const file = process.argv[2]
+  if (!file) { console.error('Usage: node docgen-extract.mjs <file>'); process.exit(1) }
+  const facts = extractFacts(readFileSync(file, 'utf8'), file)
+  console.log(JSON.stringify(facts, null, 2))
+}

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

@@ -0,0 +1,334 @@
+/**
+ * docgen-конвеєр (входна точка): код файлу → .md-документація.
+ *
+ * Інверсія керування: веде цей JS, а локальна модель — лише сервіс перефразування.
+ *   Stage 0  extractFacts        — факти з коду (0 токенів)
+ *   Stage 1  sectionInstructions — точкові промпти на кожну секцію (спільний KV-cached префікс)
+ *   Stage 2  stripSignatures     — детермінований зріз сигнатур (0 токенів)
+ *   Stage 2.5 scoreDoc           — детермінований скоринг проти фактів (0 токенів)
+ *   Stage 3  assemble            — фіксовані заголовки/порядок + зрізання fence
+ *   Tier 2   claudeOneShot       — хмарний fallback якщо score < QUALITY_THRESHOLD
+ *
+ * Hybrid routing (sym-threshold):
+ *   sym < BORDERLINE_SYM_LOW          → Tier 1 local (без хмарного рефері)
+ *   sym ∈ [BORDERLINE_SYM_LOW, sym<4) → Tier 1 + cloudScoreDoc (Haiku) → при низькому балі → Tier 2
+ *   sym >= DEFAULT_SYM_THRESHOLD      → одразу Tier 2 (pre-routing, без local)
+ */
+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, 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,
+    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 = ''
+        res.on('data', chunk => {
+          buf += chunk.toString()
+          const lines = buf.split('\n')
+          buf = lines.pop()
+          for (const line of lines) {
+            if (!line.trim()) continue
+            try {
+              const j = JSON.parse(line)
+              text += j.message?.content ?? ''
+              if (j.done) genTok = j.eval_count ?? 0
+            } catch { /* partial line */ }
+          }
+        })
+        res.on('end', () => resolve({ text, genTok }))
+        res.on('error', reject)
+      }
+    )
+    req.on('error', reject)
+    req.write(body)
+    req.end()
+  })
+}
+
+/** Прибирає ```-обгортку й випадковий провідний `##`-заголовок із секції. */
+function stripSection(text) {
+  let t = text.trim()
+  if (t.startsWith('```')) {
+    t = t.replace(/^```[a-z]*\n?/, '').replace(/\n?```\s*$/, '').trim()
+  }
+  t = t.replace(/^#{1,6}\s+.*\n+/, '') // зрізати випадковий заголовок
+  return t.trim()
+}
+
+/**
+ * Stage 2 (детермінований лінт, 0 токенів): зрізає сигнатури `name(args)` → `name`.
+ * Два проходи — щоб зняти вкладені виклики на кшталт `check(cwd = process.cwd())`.
+ * Не чіпає дужки без ідентифікатора перед ними (напр. `(abie.mdc)`, «(наприклад)»).
+ */
+function stripSignatures(text) {
+  let t = text
+  for (let i = 0; i < 2; i++) t = t.replace(/([`\w$.]+)\([^()]*\)/g, '$1')
+  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 = [
+    ['overview', '## Огляд'],
+    ['behavior', '## Поведінка'],
+    ['api', '## Публічний API'],
+    ['guarantees', '## Гарантії поведінки']
+  ]
+  const parts = [`# ${stem}`]
+  for (const [key, title] of order) {
+    const body = sections[key]
+    if (body && body.trim()) parts.push(`${title}\n\n${body.trim()}`)
+  }
+  return parts.join('\n\n') + '\n'
+}
+
+/** Оркестрований режим: секційно-мінімальний контекст — код інгестується лише в `behavior`. */
+async function generateOrchestrated(facts, src, model) {
+  const sections = {}
+  let genTok = 0
+  for (const s of sectionMessages(facts, src)) {
+    const { text, genTok: g } = await ollamaChat(s.messages, { model, numPredict: s.numPredict })
+    sections[s.key] = stripSignatures(stripSection(text))
+    genTok += g
+  }
+  return { md: assemble(basename(facts.relPath), sections), genTok }
+}
+
+/** One-shot режим: один промпт на весь документ. */
+async function generateOneShot(facts, src, model) {
+  const { text, genTok } = await ollamaChat(oneShotMessages(facts, src), { model, numPredict: 1500 })
+  let md = stripSignatures(stripSection(text)) // Stage-2 лінт і для one-shot
+  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
+  return { md: md + '\n', genTok }
+}
+
+/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без локального проходу). */
+const DEFAULT_SYM_THRESHOLD = 4
+/** Файли з sym ≥ цього значення отримують хмарного рефері (Haiku) після локального проходу. */
+const BORDERLINE_SYM_LOW = 2
+
+/**
+ * Головний API: файл → { md, genTok, ms, score, issues, tier }.
+ *
+ * Routing (sym-threshold):
+ *   sym < BORDERLINE_SYM_LOW                   → Tier 1 (без хмарного рефері)
+ *   sym ∈ [BORDERLINE_SYM_LOW, symThreshold)   → Tier 1 + cloudScoreDoc (Haiku) як рефері
+ *   sym >= symThreshold                         → Pre-routing одразу Tier 2
+ *   scoreCloud=true                             → примусово запускає cloudScoreDoc для всіх Tier 1
+ *
+ * @param {string}  scoreModel    — модель для хмарного рефері (Haiku за замовч.)
+ * @param {string}  cloudModel    — модель для Tier 2 генерації (Sonnet за замовч.)
+ * @param {boolean} scoreCloud    — якщо true, cloudScoreDoc запускається для всіх Tier 1 файлів
+ */
+export async function generateDoc(file, {
+  model = 'gemma3:4b',
+  mode = 'orchestrated',
+  scoreModel = 'claude-haiku-4-5-20251001',
+  cloudModel = 'claude-sonnet-4-6',
+  threshold = QUALITY_THRESHOLD,
+  scoreCloud = false,
+  symThreshold = DEFAULT_SYM_THRESHOLD
+} = {}) {
+  const src = readFileSync(file, 'utf8')
+  const facts = extractFacts(src, file)
+  const t0 = Date.now()
+
+  // 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 }
+  }
+
+  let r = facts.unsupported
+    ? await generateOneShot(facts, src, model)
+    : mode === 'oneshot'
+      ? await generateOneShot(facts, src, model)
+      : await generateOrchestrated(facts, src, model)
+
+  // Stage 2.5a: детермінований скоринг (0 токенів)
+  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+
+  // Stage 2.5b: cloudScoreDoc (Haiku) як рефері для borderline-файлів або при scoreCloud=true
+  const isBorderline = complexity >= BORDERLINE_SYM_LOW && complexity < symThreshold
+  if ((isBorderline || scoreCloud) && env.ANTHROPIC_API_KEY) {
+    const cs = await cloudScoreDoc(r.md, facts, src, scoreModel)
+    if (cs.score < threshold) {
+      const r2 = await claudeOneShot(facts, src, cloudModel)
+      return { ...r2, ms: Date.now() - t0, score: cs.score, cloudScores: cs.scores,
+               issues: cs.issues, detScore, detIssues, tier: 2 }
+    }
+    return { ...r, ms: Date.now() - t0, score: cs.score, cloudScores: cs.scores,
+             issues: cs.issues, detScore, detIssues, tier: 1 }
+  }
+
+  // Детермінований fallback (без хмарного рефері)
+  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 }
+  }
+
+  return { ...r, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 1 }
+}
+
+// CLI: node docgen-gen.mjs <file> [--oneshot] [--score-cloud] [--model <m>] [--score-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 scoreCloud = args.includes('--score-cloud')
+  const tierOnly = args.includes('--tier-only')
+  const mi = args.indexOf('--model'); const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
+  const smi = args.indexOf('--score-model'); const scoreModel = smi >= 0 ? args[smi + 1] : 'claude-haiku-4-5-20251001'
+  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] [--score-cloud] [--model <m>] [--score-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
+    let label, icon
+    if (sym >= symThreshold) {
+      icon = '☁️ '; label = `Tier 2 cloud   (sym=${sym} ≥ ${symThreshold}, pre-routed)`
+    } else if (sym >= BORDERLINE_SYM_LOW) {
+      icon = '🔀'; label = `Tier 1+judge   (sym=${sym} ∈ [${BORDERLINE_SYM_LOW},${symThreshold}), Haiku рефері)`
+    } else {
+      icon = '💻'; label = `Tier 1 local   (sym=${sym} < ${BORDERLINE_SYM_LOW})`
+    }
+    process.stdout.write(`${icon} ${label}  |  ${file}\n`)
+    process.exit(0)
+  }
+  const r = await generateDoc(file, { model, mode, scoreCloud, scoreModel, symThreshold })
+  const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
+  const cloudTxt = r.cloudScores ? ` cloud-scores=${JSON.stringify(r.cloudScores)}` : ''
+  process.stderr.write(`[tier${r.tier} ${mode}] ${r.ms}ms / ${r.genTok} tok / score=${r.score}${issuesTxt}${cloudTxt}\n`)
+  process.stdout.write(r.md)
+}

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

@@ -20,7 +20,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

@@ -0,0 +1,88 @@
+/**
+ * Stage 1 docgen-конвеєра: факт-лист + код → точкові промпти на кожну секцію.
+ *
+ * v2 — СЕКЦІЙНО-МІНІМАЛЬНИЙ контекст: код іде ЛИШЕ у `Поведінку`. `Огляд` бере тільки
+ * header, `API` — лише список експортів, `Гарантії` — лише markers. Так інгест коду
+ * оплачується один раз (а не на кожну секцію), і оркестрація перестає програвати в часі.
+ */
+
+export const STYLE = [
+  'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
+  'Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.',
+  'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
+].join(' ')
+
+/** Короткий людиночитний витяг фактів (без коду). */
+function factsSummary(facts) {
+  const m = facts.markers || {}
+  const lines = []
+  if (facts.header) lines.push(`Намір файлу: ${facts.header.replace(/\n/g, ' ')}`)
+  if (facts.exports?.length) lines.push(`Публічні функції: ${facts.exports.map(e => e.name).join(', ')}`)
+  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 замість винятку')
+  lines.push(m.caches ? 'Кешування: так, у межах прогону' : 'Кешування: НЕМАЄ — не згадуй кеш у гарантіях')
+  if (m.network) lines.push('Звертається до мережі')
+  else lines.push('Робота з мережею: немає')
+  return lines.join('\n')
+}
+
+const msgs = (system, user) => [{ role: 'system', content: system }, { role: 'user', content: user }]
+
+/**
+ * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
+ * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>}
+ */
+export function sectionMessages(facts, src) {
+  const factsTxt = factsSummary(facts)
+  const multi = (facts.exports?.length || 0) > 1
+  const out = []
+
+  // Огляд — лише факти (без коду)
+  out.push({
+    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(', ')}.` : ''} Без заголовка.`)
+  })
+
+  // 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Без заголовка.`)
+    })
+  }
+
+  // Гарантії — лише markers (без коду)
+  out.push({
+    key: 'guarantees', numPredict: 300,
+    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Гарантії поведінки» як маркери-інваріанти СУВОРО на основі ВІДОМИХ ФАКТІВ (read-only, fail-safe, пропуски). Згадуй кеш ЛИШЕ якщо у фактах прямо є «Кешує». Без сигнатур у дужках і без імен внутрішніх структур/Map-ів/кешів. Не вигадуй гарантій, яких немає у фактах. Без заголовка.')
+  })
+
+  return out
+}
+
+/** 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\`\`\``)
+}
+
+/** Лише текст 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/fix/SKILL.md

@@ -8,42 +8,16 @@ description: >-
 
 ## Scope
 
-Цей скіл відповідає **лише за структуру** проєкту: щоб `.cursor/rules/` + `npx @nitra/cursor fix` були задоволені (наявність конфігів, залежностей, скриптів, GitHub workflows, відсутність заборонених файлів). **Лінт-порушення у самому коді** (ESLint, oxlint, jscpd, cspell, knip, sonarjs, stylelint тощо) — **поза скоупом**; їх діагностує й виправляє **`/n-lint`** (`bun run lint`). Не запускай `bun run lint` із цього скілу і не намагайся виправляти його порушення тут — це задача `/n-lint`. Якщо `npx @nitra/cursor fix` чистий, а `bun run lint` лишився червоним — запусти `/n-lint` окремо.
+Цей скіл відповідає **лише за структуру** проєкту: щоб `.cursor/rules/` + `npx @nitra/cursor fix` були задоволені (наявність конфігів, залежностей, скриптів, GitHub workflows, відсутність заборонених файлів). **Лінт-порушення у самому коді** (ESLint, oxlint, jscpd, cspell, knip, sonarjs, stylelint тощо) — **поза скоупом**; їх діагностує й виправляє **`/n-lint`** (`bun run lint`).
 
 ## Workflow
 
-1. **Діагностика** — запусти перевірку через retry-обгортку `n_cursor_npx` (визначена у worktree-preflight, крок 0.1: переживає транзитну CDN-гонку щойно опублікованої версії, а реальний `❌` від `fix` віддає одразу). Прапорець `--json` дає **структурований** результат у stdout, щоб не парсити термінальний текст. За замовчуванням — лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `n_cursor_npx fix bun ga --json`:
-
-```bash
-n_cursor_npx fix --json
-```
-
-2. **Аналіз** — розбери JSON `{ total, failed, rules: [{ ruleId, ok, output }] }`. Працюй **лише** з елементами `ok:false`; їх `output` містить готові `❌`-повідомлення правила (не парси stdout вручну, не визначай правила з тексту). Якщо `failed === 0` — нічого виправляти.
-
-3. **Виправлення** — для кожного `❌` відкрий відповідне правило з `.cursor/rules/` і виправ:
-   - Створи відсутні конфігураційні файли (`.cspell.json`, `.oxfmtrc.json`, `eslint.config.js`, тощо)
-   - Додай відсутні залежності до `package.json`
-   - Створи або оновити `.vscode/settings.json` та `extensions.json`
-   - Створи відсутні GitHub Actions workflows у `.github/workflows/`
-   - Видали заборонені файли та залежності (`package-lock.json`, `yarn.lock`, prettier, тощо)
-   - Оновити скрипти в `package.json`
-
-4. **Встановлення** — якщо були змінені залежності:
-
 ```bash
-bun i
+n_cursor_npx fix
 ```
 
-5. **Форматування** — відформатуй змінені файли:
+Exit 0 = чисто, 1 = є unresolved (перевір вивід — буде список правил що не закрились після 3 ітерацій).
 
-```bash
-oxfmt .
-```
-
-6. **Верифікація** — перевір що все виправлено (та сама retry-обгортка `n_cursor_npx`); чекаєш `failed === 0`:
-
-```bash
-n_cursor_npx fix --json
-```
+Якщо змінились залежності — `bun i`. Якщо змінились JS/TS файли — `oxfmt .`.
 
-7. **Результат** — `failed` має стати `0` (усі правила `ok:true`). Якщо лишились `ok:false` — повтори кроки 3-6. Лінт-помилки від `bun run lint` тут **не виправляй** — вони на скіл `/n-lint`.
+Для конкретних правил: `n_cursor_npx fix bun ga`.