@nitra/cursor 5.1.0 → 5.2.1

package/skills/docgen/js/docgen-batch-omlx.mjs

@@ -1,82 +0,0 @@
-/**
- * Тимчасовий A/B-batch: docgen Tier 1 через omlx (gemma-4-e2b 4bit на MLX)
- * замість pi/ollama. Перезаписує всі docs/<stem>.md для файлів з sym<4,
- * НЕ ескалює в cloud. Призначення — порівняння якості omlx vs попередньої версії.
- *
- * Запуск: node npm/skills/docgen/js/docgen-batch-omlx.mjs [--limit N] [--from N]
- *   --limit N — обробити перші N файлів зі списку sym<4
- *   --from N  — почати з індексу N (для дозапуску)
- */
-import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execSync } from 'node:child_process'
-import { env } from 'node:process'
-import { generateDoc } from './docgen-gen.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-
-const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
-
-const args = process.argv.slice(2)
-const limitIdx = args.indexOf('--limit')
-const limit = limitIdx !== -1 ? Number(args[limitIdx + 1]) : Infinity
-const fromIdx = args.indexOf('--from')
-const from = fromIdx !== -1 ? Number(args[fromIdx + 1]) : 0
-
-env.N_CURSOR_DOCGEN_BACKEND = 'omlx'
-
-const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
-const all = JSON.parse(scanOut)
-
-const local = []
-for (const f of all) {
-  try {
-    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
-    const facts = extractFacts(src, join(ROOT, f.sourcePath))
-    const sym = (facts.internalSymbols ?? []).length
-    if (sym < 4) local.push({ ...f, sym })
-  } catch {
-    /* пропускаємо нечитані */
-  }
-}
-
-const slice = local.slice(from, from + limit)
-console.log(`📋 Файлів sym<4 у проєкті: ${local.length}; обробляємо: ${slice.length} (from=${from}, limit=${limit === Infinity ? 'усе' : limit})`)
-console.log(`🤖 Бекенд: omlx → ${env.N_CURSOR_DOCGEN_OMLX_URL ?? 'http://127.0.0.1:8000/v1/chat/completions'}`)
-
-const stats = { ok: 0, err: 0, totalMs: 0, scores: [], errors: [] }
-
-for (let i = 0; i < slice.length; i++) {
-  const f = slice[i]
-  const t0 = Date.now()
-  const pct = Math.round(((i + 1) / slice.length) * 100)
-  process.stdout.write(`  [${i + 1}/${slice.length} ${pct}%] sym=${f.sym} ${f.sourcePath} ... `)
-  try {
-    const result = await generateDoc(join(ROOT, f.sourcePath), {
-      symThreshold: 999, // не уходити в cloud за sym
-      cloudModel: null // повністю вимкнути cloud-fallback навіть при low det-score
-    })
-    const docAbs = join(ROOT, f.docPath)
-    mkdirSync(dirname(docAbs), { recursive: true })
-    writeFileSync(docAbs, result.md)
-    const ms = Date.now() - t0
-    stats.ok++
-    stats.totalMs += ms
-    stats.scores.push(result.score ?? 0)
-    process.stdout.write(`✓ ${Math.round(ms / 1000)}s score=${result.score ?? '?'} tier=${result.tier}\n`)
-  } catch (error) {
-    stats.err++
-    stats.errors.push({ path: f.sourcePath, msg: error.message })
-    process.stdout.write(`✗ ${error.message}\n`)
-  }
-}
-
-const avgScore = stats.scores.length ? Math.round(stats.scores.reduce((a, b) => a + b, 0) / stats.scores.length) : 0
-console.log(`\n${'─'.repeat(60)}`)
-console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
-console.log(`  Сумарний час: ${Math.round(stats.totalMs / 1000)}s; середній на файл: ${stats.ok ? Math.round(stats.totalMs / stats.ok / 1000) : 0}s`)
-console.log(`  Середній det-score: ${avgScore}`)
-if (stats.errors.length) {
-  console.log('Помилки:')
-  for (const e of stats.errors) console.log(`  - ${e.path}: ${e.msg}`)
-}

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

@@ -1,95 +0,0 @@
-/**
- * Batch docgen для відсутніх файлів проєкту.
- * sym < 4 → gemma3:4b orchestrated (local)
- * sym ≥ 4 → Claude Sonnet (cloud, via generateDoc pre-routing)
- */
-import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { generateDoc } from './docgen-gen.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-import { execSync } from 'node:child_process'
-
-const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
-
-// 1. Отримати список відсутніх файлів
-const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
-const allFiles = JSON.parse(scanOut)
-const missing = allFiles.filter(x => !x.exists)
-
-console.log(`\n📋 Файлів для генерації: ${missing.length}`)
-
-// 2. Розкласти по тирах
-const cloud = [],
-  local = []
-for (const f of missing) {
-  try {
-    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
-    const facts = extractFacts(src, join(ROOT, f.sourcePath))
-    const sym = (facts.internalSymbols ?? []).length
-    if (sym >= 4) cloud.push({ ...f, sym })
-    else local.push({ ...f, sym })
-  } catch {
-    local.push({ ...f, sym: 0 })
-  }
-}
-
-console.log(`  Local (sym<4): ${local.length}`)
-console.log(`  Cloud (sym≥4): ${cloud.length}`)
-
-const stats = { ok: 0, err: 0, localOk: 0, cloudOk: 0, errors: [] }
-
-// 3. Cloud файли (sym≥4) — generateDoc auto-routes до Claude
-console.log('\n☁️  Cloud tier...')
-for (const f of cloud) {
-  const t0 = Date.now()
-  try {
-    const result = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 4 })
-    const docAbs = join(ROOT, f.docPath)
-    mkdirSync(dirname(docAbs), { recursive: true })
-    writeFileSync(docAbs, result.md)
-    stats.ok++
-    stats.cloudOk++
-    console.log(`  ✓ ${f.sourcePath} (sym=${f.sym}, ${Math.round((Date.now() - t0) / 1000)}s)`)
-  } catch (error) {
-    stats.err++
-    stats.errors.push(f.sourcePath)
-    console.error(`  ✗ ${f.sourcePath}: ${error.message}`)
-  }
-}
-
-// 4. Local файли (sym<4) — gemma3:4b orchestrated
-console.log('\n💻 Local tier...')
-let done = 0
-for (const f of local) {
-  done++
-  const t0 = Date.now()
-  const pct = Math.round((done / local.length) * 100)
-  process.stdout.write(`  [${done}/${local.length} ${pct}%] ${f.sourcePath} ... `)
-  try {
-    const result = await generateDoc(join(ROOT, f.sourcePath), {
-      mode: 'orchestrated',
-      symThreshold: 999 // force local
-    })
-    const docAbs = join(ROOT, f.docPath)
-    mkdirSync(dirname(docAbs), { recursive: true })
-    writeFileSync(docAbs, result.md)
-    stats.ok++
-    stats.localOk++
-    process.stdout.write(`✓ ${Math.round((Date.now() - t0) / 1000)}s score=${result.score ?? '?'}\n`)
-  } catch (error) {
-    stats.err++
-    stats.errors.push(f.sourcePath)
-    process.stdout.write(`✗ ${error.message}\n`)
-  }
-}
-
-// 5. Підсумок
-console.log(`\n${'─'.repeat(50)}`)
-console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
-console.log(`  💻 Local (gemma3:4b): ${stats.localOk} файлів`)
-console.log(`  ☁️  Cloud (Claude/pi): ${stats.cloudOk} файлів`)
-if (stats.errors.length > 0) {
-  console.log('Помилки:')
-  for (const e of stats.errors) console.log(`  - ${e}`)
-}

package/skills/docgen/js/docgen-compare-pi-vs-direct.mjs

@@ -1,95 +0,0 @@
-/**
- * A/B: docgen Tier 1 через pi cli (з omlx-провайдером у ~/.pi/agent/models.json)
- * vs прямий callOmlxMessages (`N_CURSOR_DOCGEN_BACKEND=omlx`).
- *
- * Однаковий 8-сет файлів, однаковий оркестратор (E1+E2+E3+E4), різний backend.
- * Пише в /tmp/docgen-compare/{pi,direct}/<idx>-<stem>.md і збирає метрики.
- *
- * Запуск: node npm/skills/docgen/js/docgen-compare-pi-vs-direct.mjs [--from N] [--limit N]
- */
-import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs'
-import { join, resolve, basename } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execSync } from 'node:child_process'
-import { env } from 'node:process'
-import { generateDoc } from './docgen-gen.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-
-const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
-const TMP = '/tmp/docgen-compare'
-
-const args = process.argv.slice(2)
-const limitIdx = args.indexOf('--limit')
-const limit = limitIdx !== -1 ? Number(args[limitIdx + 1]) : 8
-const fromIdx = args.indexOf('--from')
-const from = fromIdx !== -1 ? Number(args[fromIdx + 1]) : 1
-
-const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
-const all = JSON.parse(scanOut)
-
-const local = []
-for (const f of all) {
-  try {
-    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
-    const facts = extractFacts(src, join(ROOT, f.sourcePath))
-    const sym = (facts.internalSymbols ?? []).length
-    if (sym < 4) local.push({ ...f, sym })
-  } catch {}
-}
-const slice = local.slice(from, from + limit)
-
-mkdirSync(join(TMP, 'pi'), { recursive: true })
-mkdirSync(join(TMP, 'direct'), { recursive: true })
-
-async function runBackendAsync(kind) {
-  if (kind === 'direct') env.N_CURSOR_DOCGEN_BACKEND = 'omlx'
-  else delete env.N_CURSOR_DOCGEN_BACKEND
-  const out = { ok: 0, err: 0, totalMs: 0, scores: [], lengths: [], errors: [], times: [] }
-  console.log(`\n══════ Backend: ${kind} ══════`)
-  for (let i = 0; i < slice.length; i++) {
-    const f = slice[i]
-    const t0 = Date.now()
-    const stem = basename(f.sourcePath).replace(/\.[^.]+$/, '')
-    const destFile = join(TMP, kind, `${String(i + 1).padStart(2, '0')}-${stem}.md`)
-    process.stdout.write(`  [${i + 1}/${slice.length}] sym=${f.sym} ${f.sourcePath} ... `)
-    try {
-      const r = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 999, cloudModel: null })
-      writeFileSync(destFile, r.md)
-      const ms = Date.now() - t0
-      out.ok++
-      out.totalMs += ms
-      out.times.push(ms)
-      out.scores.push(r.score ?? 0)
-      out.lengths.push(r.md.length)
-      process.stdout.write(`✓ ${Math.round(ms / 1000)}s score=${r.score ?? '?'} chars=${r.md.length}\n`)
-    } catch (error) {
-      out.err++
-      out.errors.push({ path: f.sourcePath, msg: error.message })
-      process.stdout.write(`✗ ${error.message}\n`)
-    }
-  }
-  return out
-}
-
-const direct = await runBackendAsync('direct')
-const pi = await runBackendAsync('pi')
-
-function avg(a) { return a.length ? Math.round(a.reduce((x, y) => x + y, 0) / a.length) : 0 }
-function median(a) {
-  if (!a.length) return 0
-  const s = a.toSorted((x, y) => x - y)
-  return s[Math.floor(s.length / 2)]
-}
-
-const report = {
-  files: slice.map(f => f.sourcePath),
-  direct: { ok: direct.ok, err: direct.err, avgMs: avg(direct.times), medianMs: median(direct.times), avgScore: avg(direct.scores), avgChars: avg(direct.lengths), totalSec: Math.round(direct.totalMs / 1000) },
-  pi: { ok: pi.ok, err: pi.err, avgMs: avg(pi.times), medianMs: median(pi.times), avgScore: avg(pi.scores), avgChars: avg(pi.lengths), totalSec: Math.round(pi.totalMs / 1000) }
-}
-writeFileSync(join(TMP, 'report.json'), JSON.stringify(report, null, 2))
-
-console.log(`\n${'─'.repeat(60)}\nA/B SUMMARY (${slice.length} файлів, той самий оркестратор)\n${'─'.repeat(60)}`)
-console.log(`Backend        | ok | err | avg s | median s | avg score | avg chars | total s`)
-console.log(`direct (curl)  | ${direct.ok}  | ${direct.err}   | ${Math.round(report.direct.avgMs / 1000)}    | ${Math.round(report.direct.medianMs / 1000)}        | ${report.direct.avgScore}        | ${report.direct.avgChars}      | ${report.direct.totalSec}`)
-console.log(`pi cli         | ${pi.ok}  | ${pi.err}   | ${Math.round(report.pi.avgMs / 1000)}    | ${Math.round(report.pi.medianMs / 1000)}        | ${report.pi.avgScore}        | ${report.pi.avgChars}      | ${report.pi.totalSec}`)
-console.log(`\nФайли: ${TMP}/{direct,pi}/<idx>-<stem>.md\nReport: ${TMP}/report.json`)

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

@@ -1,306 +0,0 @@
-/** @see ./docs/docgen-gen.md */
-import { readFileSync } from 'node:fs'
-import { basename } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { env } from 'node:process'
-import { resolveModel } from '../../../lib/models.mjs'
-import { callOmlx } from '../../../lib/omlx.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-import { extractAnchors } from './docgen-extract-anchors.mjs'
-import { oneShotMessages, sectionMessages, criticMessages, refineMessages, guaranteesFromMarkers } from './docgen-prompts.mjs'
-
-const QUALITY_THRESHOLD = 70
-
-/** Прибирає ```-обгортку й випадковий провідний `##`-заголовок із секції. */
-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.replaceAll(/([`\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().replaceAll(/[^а-яіїєґ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 }
-}
-
-/**
- * omlx-бекенд: справжні OpenAI-сумісні messages (system+user збереженi).
- * Вмикається `N_CURSOR_DOCGEN_BACKEND=omlx`. Делегує у спільний `callOmlx`
- * (npm/lib/omlx.mjs) з docgen-специфічними env-дефолтами URL/моделі.
- */
-function callOmlxMessages(messages, model, timeoutMs, temperature = 0.2) {
-  return callOmlx(messages, model, {
-    url: env.N_CURSOR_DOCGEN_OMLX_URL,
-    timeoutMs,
-    temperature,
-    fallbackModel: env.N_CURSOR_DOCGEN_OMLX_MODEL
-  })
-}
-
-/**
- * Універсальний виклик LLM за повним messages-масивом.
- * - omlx: шле messages напряму (system збережено)
- * - pi: конкатенує message.content (pi приймає лише plain prompt)
- */
-function callLlm(messages, model, timeoutMs, temperature = 0.2) {
-  if (env.N_CURSOR_DOCGEN_BACKEND === 'omlx') return callOmlxMessages(messages, model, timeoutMs, temperature)
-  const prompt = messages.map(m => m.content).join('\n\n')
-  const modelArgs = model ? ['--model', model] : []
-  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
-    encoding: 'utf8',
-    timeout: timeoutMs
-  })
-  if (r.error) throw new Error(`pi error: ${r.error.message}`)
-  if (r.status !== 0) throw new Error(`pi exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
-  return r.stdout?.trim() ?? ''
-}
-
-/**
- * E2 — один цикл critique→refine на секцію.
- * Повертає або уточнену чорнетку, або оригінал якщо критик повідомив NONE.
- */
-function critiqueRefineSection(sectionKey, draft, facts, anchors, model, timeoutMs) {
-  const critique = callLlm(criticMessages(sectionKey, draft, facts, anchors), model, timeoutMs).trim()
-  if (!critique || /^\s*NONE\s*$/i.test(critique) || critique.length < 12) return draft
-  const refined = callLlm(refineMessages(sectionKey, draft, critique, facts, anchors), model, timeoutMs).trim()
-  return stripSignatures(stripSection(refined)) || draft
-}
-
-/**
- * Чи треба refine для секції API: тільки якщо є >1 експорту і всі desc-и порожні
- * (саме там модель схильна писати «застосовує логіку до файлу»).
- */
-function apiNeedsRefine(facts) {
-  const exps = facts.exports ?? []
-  if (exps.length <= 1) return false
-  return exps.every(e => !e.desc)
-}
-
-/** One-shot: один виклик LLM на весь документ. */
-function piOneShot(facts, src, model, timeoutMs = 120_000) {
-  const text = callLlm(oneShotMessages(facts, src), model, timeoutMs)
-  let md = stripSignatures(stripSection(text))
-  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  return { md: md + '\n', genTok: 0 }
-}
-
-/** 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'
-}
-
-/**
- * Orchestrated: N окремих pi-викликів, по одному на секцію.
- * Код потрапляє лише в `behavior`; решта секцій — на мінімальному факт-листі.
- */
-function piOrchestrated(facts, src, model, timeoutMs, { anchors = null, temperature = 0.2 } = {}) {
-  const sections = {}
-  const anc = anchors ?? extractAnchors(src)
-  // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
-  sections.guarantees = guaranteesFromMarkers(facts)
-  for (const s of sectionMessages(facts, src, anc)) {
-    if (s.key === 'guarantees') continue // вже згенеровано детерміновано
-    let draft = stripSignatures(stripSection(callLlm(s.messages, model, timeoutMs, temperature)))
-    // E2 + E3: critique→refine лише для секцій, де gemma-4 зриває на generic
-    if (s.key === 'overview' || (s.key === 'api' && apiNeedsRefine(facts))) {
-      draft = critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
-    }
-    sections[s.key] = draft
-  }
-  return { md: assemble(basename(facts.relPath), sections), genTok: 0 }
-}
-
-
-
-/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без Tier 1 проходу). */
-const DEFAULT_SYM_THRESHOLD = 4
-/** Максимальний час Tier 1 генерації на один файл перед ескалацією у Tier 2. */
-const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
-/** Дефолтна Tier 1 модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min'). */
-const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? resolveModel('min')
-/** Дефолтна Tier 2 модель: N_CURSOR_DOCGEN_CLOUD_MODEL → resolveModel('avg'). */
-const DEFAULT_CLOUD_MODEL = env.N_CURSOR_DOCGEN_CLOUD_MODEL ?? resolveModel('avg')
-
-/**
- * Головний API: файл → { md, genTok, ms, score, issues, tier }.
- *
- * Routing (sym-threshold):
- *   sym < symThreshold  → Tier 1 pi(resolveModel('min'), timeout=5хв) + det-scorer
- *                       → timeout або det-score < threshold → Tier 2
- *   sym >= symThreshold → Pre-routing одразу Tier 2
- */
-export async function generateDoc(
-  file,
-  {
-    model = DEFAULT_LOCAL_MODEL,
-    cloudModel = DEFAULT_CLOUD_MODEL,
-    threshold = QUALITY_THRESHOLD,
-    symThreshold = DEFAULT_SYM_THRESHOLD
-  } = {}
-) {
-  const src = readFileSync(file, 'utf8')
-  const facts = extractFacts(src, file)
-  const t0 = Date.now()
-
-  // Pre-routing: складні файли (sym ≥ symThreshold) → одразу Tier 2
-  const complexity = facts.internalSymbols?.length ?? 0
-  if (complexity >= symThreshold && cloudModel) {
-    const r2 = piOneShot(facts, src, cloudModel)
-    return { ...r2, ms: Date.now() - t0, score: null, issues: [`pre-routed:sym=${complexity}`], tier: 2, model: cloudModel }
-  }
-
-  // Tier 1: pi orchestrated (секція за секцією), timeout на секцію = LOCAL_TIMEOUT_MS
-  // facts.unsupported → one-shot (структура файлу нестандартна)
-  let r
-  const anchors = facts.unsupported ? null : extractAnchors(src)
-  try {
-    r = facts.unsupported
-      ? piOneShot(facts, src, model, LOCAL_TIMEOUT_MS)
-      : piOrchestrated(facts, src, model, LOCAL_TIMEOUT_MS, { anchors })
-  } catch (error) {
-    if (cloudModel) {
-      const r2 = piOneShot(facts, src, cloudModel)
-      return { ...r2, ms: Date.now() - t0, score: null, issues: [`tier1-error: ${error.message}`], tier: 2, model: cloudModel }
-    }
-    throw error
-  }
-
-  // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
-  let { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
-
-  // E4: best-of-N. Якщо score нижчий за threshold і немає cloud-fallback — спроба
-  // ще раз з вищою температурою, керуємо через env (повторні прогони коштовні).
-  if (detScore < threshold && !cloudModel && !facts.unsupported && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
-    try {
-      const r2 = piOrchestrated(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5 })
-      const s2 = scoreDoc(r2.md, facts)
-      if (s2.score > detScore) {
-        r = r2
-        detScore = s2.score
-        detIssues = [...s2.issues, 'best-of-2:retry-won']
-      } else {
-        detIssues = [...detIssues, 'best-of-2:retry-lost']
-      }
-    } catch (error) {
-      detIssues = [...detIssues, `best-of-2:retry-error: ${error.message}`]
-    }
-  }
-
-  if (detScore < threshold && cloudModel) {
-    const r2 = piOneShot(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> [--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 tierOnly = args.includes('--tier-only')
-  const mi = args.indexOf('--model')
-  const model = mi !== -1 ? args[mi + 1] : DEFAULT_LOCAL_MODEL
-  const si = args.indexOf('--sym-threshold')
-  const symThreshold = si !== -1 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
-  if (!file) {
-    console.error('Usage: node docgen-gen.mjs <file> [--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, symThreshold })
-  const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
-  process.stderr.write(`[tier${r.tier} pi-orchestrated] ${r.ms}ms / score=${r.score}${issuesTxt}\n`)
-  process.stdout.write(r.md)
-}

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

@@ -1,28 +0,0 @@
-# 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

@@ -1,41 +0,0 @@
-# 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, документація генерується безпосередньо, без локальної оцінки