---
type: JS Module
title: main.mjs
resource: npm/rules/doc-files/docgen-wave-batch/main.mjs
docgen:
  crc: 670e3912
  model: openai-codex/gpt-5.5
  tier: cloud-avg
  score: 100
  issues: judge-refine:kept-original,judge:inaccurate:0.98
  judgeModel: openai-codex/gpt-5.4-mini
---

## Огляд

`runWaveBatch` керує хвильовою LLM-генерацією документації для підготовлених файлів. Працює як batch-конвеєр із локальними fail-safe гілками для частини збоїв, щоб окремі очікувані проблеми не зупиняли весь процес; інші помилки можуть поширюватися назовні.

## Поведінка

1. runWaveBatch приймає підготовлені файли, для яких потрібна LLM-документація, і запускає хвильовий batch-конвеєр замість послідовної генерації.

2. Для кожного файла визначається робочий стан: джерело для промптів, режим документації та потреба в додатковому покритті API-описів.

3. Перша хвиля генерує поведінковий опис для всіх файлів і, за потреби, чернетку для непокритих API-частин. Якщо обов’язкова генерація для файла не вдалася, файл позначається як невдалий або пропущений залежно від характеру помилки.

4. Друга хвиля генерує огляд лише для повних документів. Режим із авторським коментарем не створює окремий огляд через LLM.

5. Після базових хвиль документ збирається у поточному вигляді та оцінюється детермінованими правилами якості.

6. Для повних документів запускається хвиля критики огляду та, лише за визначеної потреби, критики API-прогалин. Критика використовується як фільтр для подальшого покращення, а не як фінальний текст.

7. Наступна хвиля переписує тільки ті секції, де критика дала змістовне зауваження. Якщо переписування не вдалося або повернуло порожній результат, файл зберігає попередню чернетку й не вважається зламаним.

8. Документ повторно збирається та переоцінюється після можливого покращення секцій.

9. Для повних документів, які не досягли порога якості, виконується обмежена друга спроба лише для базових генеративних хвиль. Повторна критика та повторне переписування свідомо не виконуються; кращий варіант приймається тільки якщо він покращує оцінку.

10. За увімкненого суддівського етапу перевіряються лише документи, які вже пройшли детермінований поріг. Невдалий вердикт не перезапускає виправлення, а позначає результат як degraded.

11. Наприкінці успішні документи записуються на диск із діагностикою розміру та статусу, а лічильники результатів оновлюються для підсумкового звіту.

12. Помилки окремих обов’язкових хвиль ізолюються на рівні файла, але системні помилки batch-виклику можуть поширюватися назовні, щоб викликач міг класифікувати збій усього прогону.

## Публічний API

- runWaveBatch — Точка входу фази 2: хвильовий batch-конвеєр для `'comment+behavior'`/`'full'`
елементів `docgen-files-batch` (`prepareBatchItem`-виходи, `mode !== 'comment-only'`
і `!facts.unsupported`) — `docgen-files-batch` продовжує сам обробляти
`'comment-only'` (0 LLM) і `unsupported` (незмінний one-shot batch-шлях).

## Сценарії використання

- `npm/rules/doc-files/docgen-wave-batch/tests/docgen-wave-batch.test.mjs` (runWaveBatch — щасливий шлях (full mode); runWaveBatch — помилка обов’язкового виклику валить лише свій файл) — behavior → overview → фінальний запис доки з хорошим score; N файлів — один submitBatchImpl-виклик на хвилю, не по одному на файл; behavior для одного файлу падає — інший файл усе одно записується; permanent-помилка (prompt too long) → skip, не err; критик дає непорожнє зауваження → refine замінює overview у фінальному md; ще 6

## Гарантії поведінки

- Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.