---
type: JS Module
title: main.mjs
resource: npm/rules/doc-files/docgen-files-batch/main.mjs
docgen:
  crc: 6237a73f
  model: omlx/gemma-4-e4b-it-OptiQ-4bit
  score: 100
  issues: judge:inaccurate:0.99
  judgeModel: openai-codex/gpt-5.4-mini
---

## Огляд

Цей модуль керує повним циклом генерації документації. Він використовує функцію `selectTargets` для вибору цільових файлів та `purgeOrphanedDocs` для видалення посилань на відсутні файли. Для ініціалізації процесу застосовується `runDocFilesGenCli`, а пакетна генерація контролюється через `runGenerationBatch`. Після генерації метадані файлів оновлюються за допомогою `runDocFilesStampCli`, що додає хеш відповідного вихідного файлу. Усі операції виконуються з механізмом fail-safe, що перехоплює помилки та не кидає винятків назовні.

## Поведінка

Поведінка
selectTargets вибирає файли для генерації документації, які є застарілими або мають низьку якість, виключаючи ті, що вже мають потік (tier) `cloud-avg`. Рукописні доки (docPath існує без docgen-frontmatter, `foreign`) без `--overwrite` цілями не стають.
purgeOrphanedDocs видаляє вказівники на файли документації, для яких не існує відповідного вихідного файлу, і оновлює індекси директорій.
runDocFilesGenCli керує процесом генерації документації, видаляючи сирітських доків, визначаючи цілі та запускаючи пакетну генерацію; про пропущені рукописні (foreign) доки попереджає у stderr — тихого перезапису людського змісту немає, перезапис лише explicit `--overwrite`.
runGenerationBatch виконує генерацію документації для визначеного набору файлів, керуючи логікою циркут-брейкера при системних збоях; опційний `deadlineAt` (м'який дедлайн fix-pipeline) зупиняє батч перед стартом наступного файлу штатно — зроблене лишається на диску зі свіжими CRC, решту підбирає наступний прогін (перший файл стартує завжди).
generateDirIndex (пере)генерує `index.md` директорії docs/ як OKF Directory Index без H1 у тілі — top-level заголовком лишається frontmatter `title:`, тож MD025/single-title чистий; чужий `index.md` (дока source-файлу чи людський зміст без OKF-типу) не перезаписується.
runDocFilesStampCli оновлює метадані (frontmatter) наявних файлів документації, додаючи хеш вихідного файлу, без повторного запуску генерації.

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

selectTargets — Визначає цілі для генерації документації: `default` — застарілі або погіршені доки, які ще не пройшли перерахунок CRC; `--overwrite` — всі доки. Погіршена дока отримує лише один повторний ретрай на версію джерела; після невдалого ретраю вона позначається як `retried: true` і більше не змінюється до оновлення джерела.
purgeOrphanedDocs — Видаляє доки, які втратили зв'язок із джерелом, та оновлює індекс.md. Якщо в каталозі docs залишається лише index.md або нічого, він очищається.
runDocFilesGenCli — Генерує документацію для доків, які є застарілими або відсутніми.
runGenerationBatch — Основний процес генерації: перевіряє локальний бекенд, послідовно генерує документацію для визначених цілей, застосовуючи захист від ланцюгових збоїв і м'який дедлайн (`deadlineAt`); також використовується для лінтінгу змінених файлів.
generateDirIndex — (Пере)генерує Directory Index (`index.md`) у docs/-директорії; детекція власного індексу — за frontmatter `type: Directory Index`, чужі index.md недоторкані.
runDocFilesStampCli — Автоматично додає або виправляє метадані (source + crc) у існуючих доках без залучення LLM. Цей процес використовується для міграції доків без CRC, зберігаючи при цьому інформацію про модель та якість з метаданих.

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

- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
