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