---
docgen:
  source: npm/rules/doc-files/js/docgen-scan.mjs
  crc: dcc90d44
  score: 100
---

# docgen-scan.mjs

## Огляд

isSourceFile перевіряє, чи є файл кодовим джерелом.
docPathForSource обчислює шлях md-документа для кодового файлу.
isDocCandidate перевіряє, чи підлягає файл документуванню.
describeFile описує кодовий файл, включаючи шлях доки та стан застарілості.
scanForDocFiles рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
resolveRoot парсить аргументи, щоб визначити абсолютний корінь.
runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
runDocFilesCheckCli детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.

## Поведінка

isSourceFile Обчислює, чи є файл кодовим джерелом.
docPathForSource Обчислює шлях md-документа для кодового файлу.
isDocCandidate Перевіряє, чи підлягає файл документуванню.
describeFile Описує кодовий файл, включаючи шлях доки та стан застарілості.
scanForDocFiles Рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
resolveRoot Парсить аргументи, щоб визначити абсолютний корінь.
runDocFilesScanCli Сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
runDocFilesCheckCli Детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.

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

isSourceFile — перевіряє, чи є файл коду для документування.
docPathForSource — обчислює шлях до документа для кодового файлу, розміщуючи його в теці `docs/` поруч із джерелом. Якщо шлях відносний, документ також відносний; якщо абсолютний, документ залишається абсолютним.
isDocCandidate — визначає, чи підлягає кодовий файл документуванню: має правильне розширення, не є тестом, не знаходиться в ігнорованому списку, і не є кореневим системним документуванням.
describeFile — надає опис кодового файлу: шлях до джерела, шлях до документа та стан застарілості за CRC.
scanForDocFiles — рекурсивно переглядає дерево від заданого кореня і повертає кодові файли разом зі станом застарілості.
resolveRoot — парсить аргумент `--root <dir>` з командного рядка; за замовчуванням використовує поточну робочу директорію.
runDocFilesScanCli — сканує дерево і виводить JSON-масив усіх кодових файлів із зазначенням їхнього стану застарілості.
runDocFilesCheckCli — виконує перевірку застарілості для хуків та командного рядка через інструмент `doc-files check`.
Режими — це способи виконання:
--hook — бере шлях до файлу з вводу JSON і перевіряє один файл.
--git — перевіряє різницю в Git (`git diff --name-only HEAD`) з урахуванням порогу `--max` (за замовчуванням 50); якщо застарілості більше, не блокує (виходить з кодом 0 з попередженням).
--degraded — генерує інформаційний звіт про документи, які мають оцінку нижче встановленого порогу (виходить з кодом 0).
<paths…> — використовується для визначення явних шляхів до джерел.
Exit 2 — повертається, якщо знайдено застарілі дані; повертається 0, якщо дані свіжі або пройдено перевищення порогу.

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

- Read-only: файл не виконує операцій запису у файлову систему.
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
- Не звертається до мережі.
