@nitra/cursor 5.1.0 → 5.2.0

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

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

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

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

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

@@ -1,48 +0,0 @@
-# docgen-scan.mjs
-
-## Огляд
-
-`docgen scanner` обходить проєкт, щоб створити JSON-список кодових файлів, розташованих у теці `docs/` поряд із джерелом. Цей список використовується іншими скілами для генерації документації. Інструмент забезпечує детермінований обхід проєкту та відстежує наявність файлів, не використовуючи мережеві ресурси чи LLM.
-
-## Поведінка
-
-- `isSourceFile`: Перевіряє, чи файл є джерелом коду, враховуючи розширення та тестові файли.
-- `docPathForSource`: Генерує шлях до файлу документації для заданого джерела, враховуючи відносні шляхи.
-- `scanForDocgen`: Рекурсивно обходить дерево проєкту, визначаючи кодові файли, які потрібно документувати, та їх відповідні шляхи до документації.
-- `slugForModule`: Генерує унікальний slug для модуля на основі його відносного шляху.
-- `findModuleRoots`: Знаходить абсолютні шляхи коренів модулів проєкту.
-- `nearestModuleRoot`: Знаходить найближчий модуль-предок для заданого файлу.
-- `scanForModules`: Лістить модулі проєкту, визначаючи їхні члени (sourcePath-и) та шляхи до документації.
-- `resolveRoot`: Визначає абсолютний корінь проєкту на основі аргументів командного рядка.
-- `runDocgenScanCli`: Запускає сканування docgen як CLI, виводить JSON-масив у stdout та повертає код виходу.
-- `runDocgenModulesCli`: Запускає сканування модулів docgen як CLI, виводить JSON-масив у stdout та повертає код виходу.
-
-## Публічний API
-
-- isSourceFile — Визначає, чи є файл кодовим джерелом для створення документації.
-- docPathForSource — Генерує шлях до md-файлу, пов'язаний з кодовим файлом.
-- scanForDocgen — Рекурсивно обстежує структуру проєкту, виявляючи файли для документування.
-- slugForModule — Створює унікальний ідентифікатор (slug) для модуля на основі його шляху.
-- findModuleRoots — Знаходить корені модулів, визначаючи директорії з файлом `package.json`.
-- nearestModuleRoot — Визначає найближчий модуль-предок для заданого файлу.
-- scanForModules — Створює список логічних модулів проєкту, включаючи файли та інформацію про них.
-- resolveRoot — Встановлює базову директорію для сканування, використовуючи аргумент командного рядка або поточну директорію.
-- runDocgenScanCli — Запускає сканування для виявлення файлів документації та виводить результат у форматі JSON.
-- runDocgenModulesCli — Запускає сканування модулів та виводить результат у форматі JSON.
-
-## Гарантії поведінки
-
-- `isSourceFile` повертає `true`, якщо вказаний шлях до файлу є джерелом коду.
-- `isSourceFile` повертає `false` в іншому випадку.
-- `docPathForSource` повертає шлях до відповідної папки `docs/` для вказаного джерела.
-- `scanForDocgen` повертає JSON-список шляхів до кодових файлів, які потрібно обробити.
-- `scanForDocgen` встановлює прапор `exists` у випадку, якщо файл або папка вже існують.
-- `slugForModule` повертає унікальний URL-шлях для модуля.
-- `findModuleRoots` повертає список кореневих модулів проєкту.
-- `nearestModuleRoot` повертає найближчий кореневий модуль до вказаного шляху.
-- `scanForModules` повертає список модулів проєкту.
-- `resolveRoot` повертає кореневу папку проєкту.
-- `runDocgenScanCli` запускає процес сканування для `docgen`.
-- `runDocgenModulesCli` запускає процес сканування для модулів.
-- У разі невдачі повертається `false` та `null`.
--