---
type: JS Module
title: main.mjs
resource: npm/rules/doc-files/docgen-scan/main.mjs
docgen:
  crc: 23cec34d
  model: omlx/gemma-4-e4b-it-OptiQ-4bit
  score: 100
  issues: judge:inaccurate:0.99
---

## Огляд

Модуль визначає, які файли є джерелами та обчислює відповідні шляхи для їхньої документації. Він сканує систему на наявність ізольованих або застарілих документів і надає засоби для ініціалізації сканування та перевірки якості існуючих документів.

## Поведінка

isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів.
docPathForSource обчислює очікуваний шлях до markdown-документа для заданого кодового джерельного шляху, розміщуючи його у теці `docs` поруч із джерелом.
isDocCandidate визначає, чи повинен файл підлягати документуванню, перевіряючи його тип, статус тесту, статус ігнорування та чи не є він частиною системних документації.
describeFile описує кодовий файл, надаючи шлях джерела та шлях до відповідного документа, а також статус його застарілості за CRC. Якщо док-файл існує, але без `docgen:`-CRC у frontmatter (рукописна дока), файл позначається `foreign: true` і НЕ вважається застарілим — людський зміст рахується чинною документацією і мовчки не перезаписується (перезапис лише explicit `--overwrite` у batch-CLI).
scanOrphanedDocs знаходить markdown-документи, які мають метадані про джерело, але відповідний код-файл більше не існує.
scanForDocFiles обходить дерево від кореня і повертає список всіх кодових файлів, для яких може бути згенерована документація, з інформацією про їхній статус застарілості, виключаючи ті, що ігноруються через Git.
resolveRoot визначає абсолютний кореневий каталог для сканування, беручи його з аргументів або використовуючи поточний робочий каталог.
runDocFilesScanCli сканує вказане дерево та виводить у форматі JSON список усіх кодових файлів з їхнім статусом застарілості.
runDocFilesCheckCli виконує перевірку на застарілість документації: може перевіряти один файл із stdin, групу змінених файлів через `git diff`, або звітувати про неякісні документи, блокуючи процес при знаходженні застарілого коду.

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

isSourceFile — визначає, чи є файл кодовим джерелом, що підлягає документуванню.
docPathForSource — розраховує шлях до відповідного Markdown-документа, розміщуючи його в теці `docs/` поруч із кодом.
isDocCandidate — вирішує, чи повинен файл підлягати документуванню: перевіряє розширення, виключення тестів, ігнорованих файлів та системних кореневих доків.
describeFile — створює опис одного кодового файлу, включаючи його розташування, шлях доки, статус застарілості за CRC та ознаку `foreign` (рукописна дока без docgen-frontmatter — не ціль генерації).
scanOrphanedDocs — шукає Markdown-документи, у яких вказано неіснуючий кодовий файл через `resource:` та `docgen.crc` у метаданих.
scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, повертаючи їх разом із статусом застарілості, фільтруючи за допомогою `git check-ignore`.
resolveRoot — визначає корінь проекту для сканування, використовуючи аргумент `--root` або поточний робочий каталог.
runDocFilesScanCli — сканує дерево та виводить у форматі JSON список усіх кодових файлів зі статусом застарілості.
runDocFilesCheckCli — виконує перевірку на застарілість доків для хуків та CLI-інструментів.

Режими роботи:
--hook — перевіряє один файл, отриманий із вхідних даних, у контексті хука після використання інструменту.
--git — порівнює з поточним станом Git, блокуючи процес, якщо знайдено застарілі доки, перевищуючи встановлений поріг.
--degraded — виводить інформаційний звіт про доки, які не відповідають встановленому порогу.
<paths...> — обробляє перелічені користувачем шляхи як джерела для документування.

Вихідний код (Exit 2) — вказує на знаходження застарілих доків (блокування хука); вихідний код (Exit 0) — вказує на відсутність проблем або успішне проходження понад встановлений поріг.

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

- Read-only: не виконує операцій запису (ФС/БД).
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
